diff --git a/AGENTS.md b/AGENTS.md
index 2594b24..bd4b6f7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,20 +1,5 @@
 # AGENTS.md
 
-This repository doesn't contain any agent specific instructions other than its [README.md](README.md), required development documentation, and its linked resources.
+An application frontend for [porringer](https://www.github.com/synodic/porringer) that manages and downloads package managers and their dependents.
 
-## Logging
-
-Application logs are written to a deterministic path under the OS config directory:
-
-| Mode           | Path                                                 |
-|----------------|------------------------------------------------------|
-| Production     | `%LOCALAPPDATA%\Synodic\logs\synodic.log`            |
-| Dev (`--dev`)  | `%LOCALAPPDATA%\Synodic-Dev\logs\synodic-dev.log`    |
-
-Resolve the current log path programmatically:
-
-```shell
-python -c "from synodic_client.logging import log_path; print(log_path())"
-```
-
-Logs use rotating file handlers (1 MB max, 3 backups).
+Development workflow, commands, and debug CLI reference are in `docs/development.md`.
diff --git a/docs/development.md b/docs/development.md
index 0720d6c..3b125f0 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -1 +1,118 @@
 # Development Guide
+
+We use [PDM](https://pdm-project.org/en/latest/) as our build system and package manager. All commands below are `pdm <script>`.
+
+## Quick Commands
+
+| Command | Description |
+|---------|-------------|
+| `pdm dev` | Launch the app from source with `--dev` isolation. Accepts `-- --debug` for verbose file logging. |
+| `pdm test` | Run pytest with coverage (`--cov=synodic_client`). |
+| `pdm lint` | Composite: `analyze` + `format` + `type-check`. |
+| `pdm analyze` | `ruff check` — linting only. |
+| `pdm format` | `ruff format` — formatting only. |
+| `pdm type-check` | `pyrefly check` — type checking. |
+
+`post_install` runs automatically after `pdm install` and registers example project directories with porringer.
+
+## Dev Mode
+
+The `--dev` flag isolates the development instance from production:
+
+- **Config dir:** `%LOCALAPPDATA%\Synodic-Dev\` (instead of `Synodic\`)
+- **Log file:** `synodic-dev.log` (instead of `synodic.log`)
+- **Instance lock:** Separate named socket — dev and production can run side-by-side.
+- **Velopack + protocol registration:** Skipped in dev mode.
+
+## Debug CLI
+
+With the app running (`pdm dev`), inspect and control it from another terminal:
+
+```shell
+pdm run synodic-c debug state --dev              # JSON dump of app state, config, update phase, data
+pdm run synodic-c debug actions --dev            # List available actions with descriptions
+pdm run synodic-c debug action <name> --dev      # Trigger an action (e.g. check_update, show_main)
+pdm run synodic-c debug action <name> <arg> --dev  # Action with argument (e.g. add_project /path)
+```
+
+Available actions: `check_update`, `tool_update`, `refresh_data`, `show_main`, `show_settings`, `apply_update`, `list_projects`, `add_project`, `remove_project`, `project_status`, `select_project`.
+
+### Project management actions
+
+| Action | Arg | Description |
+|--------|-----|-------------|
+| `list_projects` | — | List cached directories with validation status. |
+| `add_project` | `<path>` | Add a directory to the cache (no file picker). |
+| `remove_project` | `<path>` | Remove a directory from the cache. |
+| `project_status` | `[path]` | Per-action preview status. Defaults to selected project. |
+| `select_project` | `<path>` | Switch sidebar selection to a project. |
+
+Example workflow:
+
+```shell
+pdm run synodic-c debug action list_projects --dev
+pdm run synodic-c debug action show_main --dev
+pdm run synodic-c debug action project_status --dev                # selected project
+pdm run synodic-c debug action project_status D:\example --dev     # specific project
+pdm run synodic-c debug action add_project D:\my-project --dev
+pdm run synodic-c debug action remove_project D:\my-project --dev
+```
+
+Commands route to the controller/service layer (not widgets), so they are stable across UI changes.
+
+For production instances, omit `--dev`:
+
+```shell
+pdm run synodic-c debug state
+pdm run synodic-c debug action check_update
+```
+
+## IPC Console
+
+The debug CLI communicates with the running GUI over a local named-pipe IPC channel powered by `QLocalServer` / `QLocalSocket` (PySide6).
+
+### Architecture
+
+```
+CLI process                             GUI process
+───────────                             ───────────
+synodic-c debug <cmd>
+  │
+  ▼
+SingleInstance.send_debug_command(cmd)
+  │  connects to named pipe
+  │  writes  b"debug:<cmd>"
+  │  waits for response
+  │                                     QLocalServer._on_new_connection()
+  │                                       reads "debug:<cmd>"
+  │                                       strips prefix → DebugHandler.handle(cmd)
+  │                                       returns JSON string
+  ▼
+  reads JSON response
+  pretty-prints to stdout
+```
+
+### Transport
+
+| Detail | Value |
+|--------|-------|
+| Server name | `synodic-client` (production) / `synodic-client-dev` (dev mode) |
+| Backing | Windows named pipe (`\\.\pipe\…`), Unix domain socket elsewhere |
+| Protocol | `debug:` prefix → synchronous JSON response; all other payloads treated as `synodic://` URIs (fire-and-forget) |
+
+### Wiring
+
+1. **Server start** — `SingleInstance.start_server()` opens the `QLocalServer` during GUI init in `application/qt.py`.
+2. **Handler registration** — `SingleInstance.set_debug_handler(debug_handler.handle)` connects the `DebugHandler` callback.
+3. **Client send** — Each CLI invocation calls `SingleInstance.send_debug_command(command)`, which opens a new socket, writes the prefixed message, reads the JSON response, and disconnects.
+
+Dev and production instances use separate server names so they can run side-by-side without colliding.
+
+### Key files
+
+| File | Role |
+|------|------|
+| `synodic_client/application/instance.py` | `SingleInstance` — QLocalServer/QLocalSocket transport, `send_debug_command()` static helper |
+| `synodic_client/application/debug.py` | `DebugHandler` — dispatches commands to controllers, returns JSON |
+| `synodic_client/cli/debug.py` | CLI subcommands (`state`, `actions`, `action`) that call `_send_debug()` |
+| `synodic_client/application/qt.py` | Wires `SingleInstance` + `DebugHandler` during startup |
diff --git a/pdm.lock b/pdm.lock
index af2008f..ed2d4aa 100644
--- a/pdm.lock
+++ b/pdm.lock
@@ -5,7 +5,7 @@
 groups = ["default", "build", "lint", "test"]
 strategy = ["inherit_metadata"]
 lock_version = "4.5.0"
-content_hash = "sha256:84eef30b22559e9c8bd387d005ecf59a984863bb82aa20036361ff5222931e64"
+content_hash = "sha256:95efa849546cf87e4eedb3801bccd06a9b79016f0b3750955b8d7e9196ffc0ad"
 
 [[metadata.targets]]
 requires_python = ">=3.14,<3.15"
@@ -336,7 +336,7 @@ files = [
 
 [[package]]
 name = "porringer"
-version = "0.2.1.dev81"
+version = "0.2.1.dev84"
 requires_python = ">=3.14"
 summary = ""
 groups = ["default"]
@@ -349,8 +349,8 @@ dependencies = [
     "userpath>=1.9.2",
 ]
 files = [
-    {file = "porringer-0.2.1.dev81-py3-none-any.whl", hash = "sha256:904e0b5dcb8487f5e033313317bd834fcc88c7975f2fd5f6cc491d6e263c101d"},
-    {file = "porringer-0.2.1.dev81.tar.gz", hash = "sha256:3f42c5ce318298ef4d8ab3239c740fcf29c9d8fdc79a95a8476fd6a42d8aefc0"},
+    {file = "porringer-0.2.1.dev84-py3-none-any.whl", hash = "sha256:c6cf7c0ef71b62c4c947d874eddcb268608508de2861bab37d9c618674f1a202"},
+    {file = "porringer-0.2.1.dev84.tar.gz", hash = "sha256:3318abda2d04379d2490f79338f366e553a6985701a41f847c817545f91d25f7"},
 ]
 
 [[package]]
@@ -631,29 +631,29 @@ files = [
 
 [[package]]
 name = "ruff"
-version = "0.15.5"
+version = "0.15.6"
 requires_python = ">=3.7"
 summary = "An extremely fast Python linter and code formatter, written in Rust."
 groups = ["lint"]
 files = [
-    {file = "ruff-0.15.5-py3-none-linux_armv6l.whl", hash = "sha256:4ae44c42281f42e3b06b988e442d344a5b9b72450ff3c892e30d11b29a96a57c"},
-    {file = "ruff-0.15.5-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:6edd3792d408ebcf61adabc01822da687579a1a023f297618ac27a5b51ef0080"},
-    {file = "ruff-0.15.5-py3-none-macosx_11_0_arm64.whl", hash = "sha256:89f463f7c8205a9f8dea9d658d59eff49db05f88f89cc3047fb1a02d9f344010"},
-    {file = "ruff-0.15.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ba786a8295c6574c1116704cf0b9e6563de3432ac888d8f83685654fe528fd65"},
-    {file = "ruff-0.15.5-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:fd4b801e57955fe9f02b31d20375ab3a5c4415f2e5105b79fb94cf2642c91440"},
-    {file = "ruff-0.15.5-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:391f7c73388f3d8c11b794dbbc2959a5b5afe66642c142a6effa90b45f6f5204"},
-    {file = "ruff-0.15.5-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:8dc18f30302e379fe1e998548b0f5e9f4dff907f52f73ad6da419ea9c19d66c8"},
-    {file = "ruff-0.15.5-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1cc6e7f90087e2d27f98dc34ed1b3ab7c8f0d273cc5431415454e22c0bd2a681"},
-    {file = "ruff-0.15.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c1cb7169f53c1ddb06e71a9aebd7e98fc0fea936b39afb36d8e86d36ecc2636a"},
-    {file = "ruff-0.15.5-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:9b037924500a31ee17389b5c8c4d88874cc6ea8e42f12e9c61a3d754ff72f1ca"},
-    {file = "ruff-0.15.5-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:65bb414e5b4eadd95a8c1e4804f6772bbe8995889f203a01f77ddf2d790929dd"},
-    {file = "ruff-0.15.5-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:d20aa469ae3b57033519c559e9bc9cd9e782842e39be05b50e852c7c981fa01d"},
-    {file = "ruff-0.15.5-py3-none-musllinux_1_2_i686.whl", hash = "sha256:15388dd28c9161cdb8eda68993533acc870aa4e646a0a277aa166de9ad5a8752"},
-    {file = "ruff-0.15.5-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:b30da330cbd03bed0c21420b6b953158f60c74c54c5f4c1dabbdf3a57bf355d2"},
-    {file = "ruff-0.15.5-py3-none-win32.whl", hash = "sha256:732e5ee1f98ba5b3679029989a06ca39a950cced52143a0ea82a2102cb592b74"},
-    {file = "ruff-0.15.5-py3-none-win_amd64.whl", hash = "sha256:821d41c5fa9e19117616c35eaa3f4b75046ec76c65e7ae20a333e9a8696bc7fe"},
-    {file = "ruff-0.15.5-py3-none-win_arm64.whl", hash = "sha256:b498d1c60d2fe5c10c45ec3f698901065772730b411f164ae270bb6bfcc4740b"},
-    {file = "ruff-0.15.5.tar.gz", hash = "sha256:7c3601d3b6d76dce18c5c824fc8d06f4eef33d6df0c21ec7799510cde0f159a2"},
+    {file = "ruff-0.15.6-py3-none-linux_armv6l.whl", hash = "sha256:7c98c3b16407b2cf3d0f2b80c80187384bc92c6774d85fefa913ecd941256fff"},
+    {file = "ruff-0.15.6-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:ee7dcfaad8b282a284df4aa6ddc2741b3f4a18b0555d626805555a820ea181c3"},
+    {file = "ruff-0.15.6-py3-none-macosx_11_0_arm64.whl", hash = "sha256:3bd9967851a25f038fc8b9ae88a7fbd1b609f30349231dffaa37b6804923c4bb"},
+    {file = "ruff-0.15.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:13f4594b04e42cd24a41da653886b04d2ff87adbf57497ed4f728b0e8a4866f8"},
+    {file = "ruff-0.15.6-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e2ed8aea2f3fe57886d3f00ea5b8aae5bf68d5e195f487f037a955ff9fbaac9e"},
+    {file = "ruff-0.15.6-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:70789d3e7830b848b548aae96766431c0dc01a6c78c13381f423bf7076c66d15"},
+    {file = "ruff-0.15.6-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:542aaf1de3154cea088ced5a819ce872611256ffe2498e750bbae5247a8114e9"},
+    {file = "ruff-0.15.6-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:1c22e6f02c16cfac3888aa636e9eba857254d15bbacc9906c9689fdecb1953ab"},
+    {file = "ruff-0.15.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:98893c4c0aadc8e448cfa315bd0cc343a5323d740fe5f28ef8a3f9e21b381f7e"},
+    {file = "ruff-0.15.6-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:70d263770d234912374493e8cc1e7385c5d49376e41dfa51c5c3453169dc581c"},
+    {file = "ruff-0.15.6-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:55a1ad63c5a6e54b1f21b7514dfadc0c7fb40093fa22e95143cf3f64ebdcd512"},
+    {file = "ruff-0.15.6-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8dc473ba093c5ec238bb1e7429ee676dca24643c471e11fbaa8a857925b061c0"},
+    {file = "ruff-0.15.6-py3-none-musllinux_1_2_i686.whl", hash = "sha256:85b042377c2a5561131767974617006f99f7e13c63c111b998f29fc1e58a4cfb"},
+    {file = "ruff-0.15.6-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:cef49e30bc5a86a6a92098a7fbf6e467a234d90b63305d6f3ec01225a9d092e0"},
+    {file = "ruff-0.15.6-py3-none-win32.whl", hash = "sha256:bbf67d39832404812a2d23020dda68fee7f18ce15654e96fb1d3ad21a5fe436c"},
+    {file = "ruff-0.15.6-py3-none-win_amd64.whl", hash = "sha256:aee25bc84c2f1007ecb5037dff75cef00414fdf17c23f07dc13e577883dca406"},
+    {file = "ruff-0.15.6-py3-none-win_arm64.whl", hash = "sha256:c34de3dd0b0ba203be50ae70f5910b17188556630e2178fd7d79fc030eb0d837"},
+    {file = "ruff-0.15.6.tar.gz", hash = "sha256:8394c7bb153a4e3811a4ecdacd4a8e6a4fa8097028119160dffecdcdf9b56ae4"},
 ]
 
 [[package]]
diff --git a/pyproject.toml b/pyproject.toml
index eb2fa52..cc1745f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -14,7 +14,7 @@ requires-python = ">=3.14, <3.15"
 dependencies = [
     "pyside6>=6.10.2",
     "packaging>=26.0",
-    "porringer>=0.2.1.dev81",
+    "porringer>=0.2.1.dev84",
     "qasync>=0.28.0",
     "velopack>=0.0.1444.dev49733",
     "typer>=0.24.1",
@@ -25,18 +25,9 @@ homepage = "https://github.com/synodic/synodic-client"
 repository = "https://github.com/synodic/synodic-client"
 
 [dependency-groups]
-build = [
-    "pyinstaller>=6.19.0",
-]
-lint = [
-    "ruff>=0.15.5",
-    "pyrefly>=0.56.0",
-]
-test = [
-    "pytest>=9.0.2",
-    "pytest-cov>=7.0.0",
-    "pytest-mock>=3.15.1",
-]
+build = ["pyinstaller>=6.19.0"]
+lint = ["ruff>=0.15.6", "pyrefly>=0.56.0"]
+test = ["pytest>=9.0.2", "pytest-cov>=7.0.0", "pytest-mock>=3.15.1"]
 
 [project.scripts]
 synodic-c = "synodic_client.cli:app"
@@ -53,7 +44,7 @@ line-length = 120
 preview = true
 
 [tool.ruff.lint]
-ignore = ["D206", "D300", "D415", "E111", "E114", "E117"]
+ignore = ["D206", "D300", "D415", "E111", "E114", "E117", "PLC0415", "PLR0913"]
 select = [
     "D",   # pydocstyle
     "F",   # Pyflakes
@@ -66,10 +57,6 @@ select = [
     "PT",  # flake8-pytest-style
 ]
 
-[tool.ruff.lint.per-file-ignores]
-"synodic_client/application/bootstrap.py" = ["E402"]
-"synodic_client/cli.py" = ["PLC0415"]
-
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 
@@ -92,7 +79,7 @@ allow-prereleases = true
 
 [tool.pdm.scripts]
 analyze = "ruff check"
-dev = { call = "tool.scripts.dev:main" }
+dev = "synodic-c --dev"
 format = "ruff format"
 lint = { composite = ["analyze", "format", "type-check"] }
 package = { call = "tool.scripts.package:main" }
diff --git a/synodic_client/application/bootstrap.py b/synodic_client/application/bootstrap.py
index 24bcb22..5ec146d 100644
--- a/synodic_client/application/bootstrap.py
+++ b/synodic_client/application/bootstrap.py
@@ -17,41 +17,47 @@
 import sys
 import traceback
 
-try:
-    from synodic_client.config import set_dev_mode
-    from synodic_client.logging import configure_logging
-    from synodic_client.protocol import extract_uri_from_args
-    from synodic_client.subprocess_patch import apply as _apply_subprocess_patch
-    from synodic_client.updater import initialize_velopack
-except Exception:
-    # Last-resort crash log when imports fail before logging is configured.
-    import os
 
-    _fallback = os.path.join(os.environ.get('LOCALAPPDATA', '.'), 'Synodic', 'logs', 'bootstrap-crash.log')
-    os.makedirs(os.path.dirname(_fallback), exist_ok=True)
-    with open(_fallback, 'a', encoding='utf-8') as _f:  # noqa: PTH123
-        _f.write(traceback.format_exc())
-    raise
+def bootstrap() -> None:
+    """Execute the ordered bootstrap sequence."""
+    try:
+        from synodic_client.config import set_dev_mode
+        from synodic_client.logging import configure_logging
+        from synodic_client.protocol import extract_uri_from_args
+        from synodic_client.subprocess_patch import apply as _apply_subprocess_patch
+        from synodic_client.updater import initialize_velopack
+    except Exception:
+        # Last-resort crash log when imports fail before logging is configured.
+        import os
 
-# Parse flags early so logging uses the right filename and level.
-_dev_mode = '--dev' in sys.argv[1:]
-_debug = '--debug' in sys.argv[1:]
-set_dev_mode(_dev_mode)
-_apply_subprocess_patch()
+        _fallback = os.path.join(os.environ.get('LOCALAPPDATA', '.'), 'Synodic', 'logs', 'bootstrap-crash.log')
+        os.makedirs(os.path.dirname(_fallback), exist_ok=True)
+        with open(_fallback, 'a', encoding='utf-8') as _f:
+            _f.write(traceback.format_exc())
+        raise
 
-configure_logging(debug=_debug)
+    # Parse flags early so logging uses the right filename and level.
+    dev_mode = '--dev' in sys.argv[1:]
+    debug = '--debug' in sys.argv[1:]
+    set_dev_mode(dev_mode)
+    _apply_subprocess_patch()
 
-_logger = logging.getLogger(__name__)
-_logger.info('Bootstrap started (exe=%s, argv=%s)', sys.executable, sys.argv)
+    configure_logging(debug=debug)
 
-initialize_velopack()
+    logger = logging.getLogger(__name__)
+    logger.info('Bootstrap started (exe=%s, argv=%s)', sys.executable, sys.argv)
 
-if not _dev_mode:
-    from synodic_client.application.init import run_startup_preamble
+    initialize_velopack()
 
-    run_startup_preamble(sys.executable)
+    if not dev_mode:
+        from synodic_client.application.init import run_startup_preamble
 
-# Heavy imports happen here — PySide6, porringer, etc.
-from synodic_client.application.qt import application
+        run_startup_preamble(sys.executable)
 
-application(uri=extract_uri_from_args(), dev_mode=_dev_mode, debug=_debug)
+    # Heavy imports happen here — PySide6, porringer, etc.
+    from synodic_client.application.qt import application
+
+    application(uri=extract_uri_from_args(), dev_mode=dev_mode, debug=debug)
+
+
+bootstrap()
diff --git a/synodic_client/application/data.py b/synodic_client/application/data.py
index aa7247f..fdfe662 100644
--- a/synodic_client/application/data.py
+++ b/synodic_client/application/data.py
@@ -64,6 +64,11 @@ def discovered_plugins(self) -> DiscoveredPlugins | None:
         """Shortcut to the current ``DiscoveredPlugins`` instance."""
         return self._snapshot.discovered
 
+    @property
+    def is_stale(self) -> bool:
+        """Whether the cached data needs refreshing."""
+        return self._stale
+
     def invalidate(self) -> None:
         """Mark the cached data as stale.
 
@@ -173,14 +178,27 @@ async def _fetch(self) -> Snapshot:
             if isinstance(env, PluginManager) and env.is_available():
                 managers[env.tool_name()] = env
 
+        # Step 5: collect protocol capabilities for each plugin
+        capabilities: dict[str, frozenset] = {
+            plugin.name: frozenset(discovered.capabilities(plugin.name)) for plugin in plugins
+        }
+
         # Derive the un-validated directory list for callers that only
         # need path + name (e.g. _gather_packages).
         directories = [r.directory for r in validated]
 
+        logger.info(
+            'Discovery complete: %d plugin(s), %d directory(ies), %d plugin manager(s)',
+            len(plugins),
+            len(directories),
+            len(managers),
+        )
+
         return Snapshot(
             plugins=plugins,
             directories=directories,
             validated_directories=validated,
             discovered=discovered,
             plugin_managers=managers,
+            plugin_capabilities=capabilities,
         )
diff --git a/synodic_client/application/debug.py b/synodic_client/application/debug.py
new file mode 100644
index 0000000..6624ae3
--- /dev/null
+++ b/synodic_client/application/debug.py
@@ -0,0 +1,271 @@
+"""Debug automation interface for agent and developer interaction.
+
+Provides a command handler that serialises application domain state and
+dispatches deterministic actions via the existing controller/service
+layer.  Commands arrive over the :class:`SingleInstance` IPC socket and
+responses are returned as JSON strings.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import logging
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from synodic_client.config import is_dev_mode
+
+if TYPE_CHECKING:
+    from porringer.api import API
+
+    from synodic_client.application.config_store import ConfigStore
+    from synodic_client.application.data import DataCoordinator
+    from synodic_client.application.screen.screen import MainWindow
+    from synodic_client.application.screen.settings import SettingsWindow
+    from synodic_client.application.screen.tool_update_controller import ToolUpdateOrchestrator
+    from synodic_client.application.update_controller import UpdateController
+    from synodic_client.application.update_model import UpdateModel
+    from synodic_client.client import Client
+
+logger = logging.getLogger(__name__)
+
+_ACTIONS: dict[str, str] = {
+    'check_update': 'Trigger a self-update check.',
+    'tool_update': 'Run tool/package updates for all plugins.',
+    'refresh_data': 'Mark cached data as stale (next refresh re-fetches).',
+    'show_main': 'Show and raise the main window.',
+    'show_settings': 'Show the settings window.',
+    'apply_update': 'Apply a downloaded update and restart.',
+    'list_projects': 'List cached project directories with validation status.',
+    'add_project': 'Add a directory to the project cache. Arg: <path>',
+    'remove_project': 'Remove a directory from the project cache. Arg: <path>',
+    'project_status': 'Dump per-action preview status. Arg (optional): <path>',
+    'select_project': 'Select a project in the sidebar. Arg: <path>',
+}
+
+
+@dataclasses.dataclass
+class DebugServices:
+    """Bundle of service references for the debug handler."""
+
+    client: Client
+    porringer: API
+    coordinator: DataCoordinator | None
+    config_store: ConfigStore
+    update_controller: UpdateController
+    update_model: UpdateModel
+    tool_orchestrator: ToolUpdateOrchestrator
+    main_window: MainWindow
+    settings_window: SettingsWindow
+
+
+class DebugHandler:
+    """Routes debug IPC commands to the application service layer."""
+
+    def __init__(self, services: DebugServices) -> None:
+        """Initialize the debug handler with service references."""
+        self._s = services
+
+    def handle(self, command: str) -> str:
+        """Dispatch a debug command and return a JSON response string."""
+        logger.debug('Debug command received: %s', command)
+
+        if command == 'state':
+            return self._handle_state()
+        if command == 'actions':
+            return self._handle_actions()
+        if command.startswith('action:'):
+            remainder = command[len('action:') :]
+            name, _, arg = remainder.partition(':')
+            return self._handle_action(name, arg or None)
+
+        return json.dumps({'error': f'unknown command: {command}'})
+
+    def _handle_state(self) -> str:
+        """Serialise current application domain state."""
+        config = self._s.config_store.config
+        coordinator = self._s.coordinator
+        model = self._s.update_model
+
+        snapshot = coordinator.snapshot if coordinator is not None else None
+        data_stale = coordinator.is_stale if coordinator is not None else None
+
+        state = {
+            'app': {
+                'version': str(self._s.client.version),
+                'dev_mode': is_dev_mode(),
+                'frozen': getattr(sys, 'frozen', False),
+                'platform': sys.platform,
+            },
+            'config': dataclasses.asdict(config),
+            'update': {
+                'phase': model.phase.name,
+                'version': model.version,
+                'error_message': model.error_message,
+            },
+            'data': {
+                'plugin_count': len(snapshot.plugins) if snapshot else 0,
+                'directory_count': len(snapshot.directories) if snapshot else 0,
+                'manager_count': len(snapshot.plugin_managers) if snapshot else 0,
+                'stale': data_stale,
+            },
+            'windows': {
+                'main_visible': self._s.main_window.isVisible(),
+                'settings_visible': self._s.settings_window.isVisible(),
+            },
+        }
+        return json.dumps(state, default=str)
+
+    @staticmethod
+    def _handle_actions() -> str:
+        """Return a list of available action names with descriptions."""
+        return json.dumps({'actions': _ACTIONS})
+
+    def _handle_action(self, name: str, arg: str | None = None) -> str:
+        """Dispatch a named action to the appropriate controller."""
+        if name not in _ACTIONS:
+            return json.dumps({'error': f'unknown action: {name}', 'available': list(_ACTIONS)})
+
+        # Actions that return their own JSON response
+        _project_dispatch: dict[str, Callable[[str | None], str]] = {
+            'list_projects': lambda _: self._handle_list_projects(),
+            'add_project': self._handle_add_project,
+            'remove_project': self._handle_remove_project,
+            'project_status': self._handle_project_status,
+            'select_project': self._handle_select_project,
+        }
+
+        if name in _project_dispatch:
+            return _project_dispatch[name](arg)
+
+        # Fire-and-forget actions
+        if name == 'check_update':
+            self._s.update_controller.check_now(silent=False)
+        elif name == 'tool_update':
+            self._s.tool_orchestrator.on_tool_update()
+        elif name == 'refresh_data':
+            if self._s.coordinator is not None:
+                self._s.coordinator.invalidate()
+        elif name == 'show_main':
+            self._s.main_window.show()
+            self._s.main_window.raise_()
+            self._s.main_window.activateWindow()
+        elif name == 'show_settings':
+            self._s.settings_window.show()
+        elif name == 'apply_update':
+            self._s.update_controller.request_apply()
+
+        return json.dumps({'ok': True, 'action': name})
+
+    # -- Project management actions ----------------------------------------
+
+    def _handle_list_projects(self) -> str:
+        """List all cached project directories with validation status."""
+        from synodic_client.operations.project import list_projects
+
+        projects = list_projects(self._s.porringer)
+        return json.dumps({'projects': [dataclasses.asdict(p) for p in projects]})
+
+    def _handle_add_project(self, arg: str | None) -> str:
+        """Add a directory to the porringer cache."""
+        if not arg:
+            return json.dumps({'error': 'add_project requires a path argument'})
+
+        from synodic_client.operations.project import add_project
+
+        try:
+            add_project(self._s.porringer, arg)
+        except (NotADirectoryError, ValueError) as exc:
+            return json.dumps({'error': str(exc)})
+
+        if self._s.coordinator is not None:
+            self._s.coordinator.invalidate()
+
+        projects_view = self._s.main_window._projects_view
+        if projects_view is not None:
+            projects_view.refresh()
+
+        return json.dumps({'ok': True, 'action': 'add_project', 'path': arg})
+
+    def _handle_remove_project(self, arg: str | None) -> str:
+        """Remove a directory from the porringer cache."""
+        if not arg:
+            return json.dumps({'error': 'remove_project requires a path argument'})
+
+        from synodic_client.operations.project import remove_project
+
+        remove_project(self._s.porringer, arg)
+
+        if self._s.coordinator is not None:
+            self._s.coordinator.invalidate()
+
+        projects_view = self._s.main_window._projects_view
+        if projects_view is not None:
+            projects_view.refresh()
+
+        return json.dumps({'ok': True, 'action': 'remove_project', 'path': arg})
+
+    def _handle_project_status(self, arg: str | None) -> str:
+        """Dump per-action preview status for a project."""
+        projects_view = self._s.main_window._projects_view
+        if projects_view is None:
+            return json.dumps({'error': 'projects view not initialised — run show_main first'})
+
+        if arg:
+            target = Path(arg)
+        else:
+            target = projects_view._sidebar.selected_path
+            if target is None:
+                return json.dumps({'error': 'no project selected and no path argument provided'})
+
+        widget = projects_view._widgets.get(target)
+        if widget is None:
+            available = [str(p) for p in projects_view._widgets]
+            return json.dumps({'error': f'no widget for path: {target}', 'available_paths': available})
+
+        model = widget.model
+        actions = []
+        for state in model.action_states:
+            act = state.action
+            entry: dict[str, object] = {
+                'description': act.description,
+                'kind': act.kind.name if act.kind else None,
+                'status': state.status,
+            }
+            if act.package is not None:
+                entry['package'] = act.package.name
+                if act.package.constraint:
+                    entry['constraint'] = act.package.constraint
+            if act.installer:
+                entry['installer'] = act.installer
+            actions.append(entry)
+
+        needed = sum(1 for s in model.action_states if s.status == 'Needed')
+        satisfied = sum(1 for s in model.action_states if '\u2713' in s.status)
+        pending = sum(1 for s in model.action_states if s.status == 'Pending')
+        upgradable = len(model.upgradable_keys)
+
+        return json.dumps({
+            'path': str(target),
+            'phase': model.phase.name,
+            'action_count': len(model.action_states),
+            'checked_count': model.checked_count,
+            'actions': actions,
+            'summary': {
+                'needed': needed,
+                'satisfied': satisfied,
+                'pending': pending,
+                'upgradable': upgradable,
+            },
+        })
+
+    def _handle_select_project(self, arg: str | None) -> str:
+        """Select a project in the sidebar."""
+        if not arg:
+            return json.dumps({'error': 'select_project requires a path argument'})
+
+        self._s.main_window._navigate_to_project(arg)
+        return json.dumps({'ok': True, 'action': 'select_project', 'path': arg})
diff --git a/synodic_client/application/instance.py b/synodic_client/application/instance.py
index 3149fa3..c93f9e1 100644
--- a/synodic_client/application/instance.py
+++ b/synodic_client/application/instance.py
@@ -3,9 +3,13 @@
 Ensures only one instance of Synodic Client runs at a time.  When a second
 instance is launched (e.g. by clicking a ``synodic://`` URI), it sends the
 URI to the already-running instance and exits.
+
+Debug commands (prefixed with ``debug:``) receive a JSON response on the
+same connection before it is closed.
 """
 
 import logging
+from collections.abc import Callable
 
 from PySide6.QtCore import QByteArray, QObject, Signal
 from PySide6.QtNetwork import QLocalServer, QLocalSocket
@@ -18,6 +22,13 @@
 _SERVER_NAME = 'synodic-client'
 _SERVER_NAME_DEV = 'synodic-client-dev'
 
+_DEBUG_PREFIX = 'debug:'
+
+
+def _decode(raw: bytes | bytearray | memoryview) -> str:
+    """Decode raw socket data to a UTF-8 string."""
+    return bytes(raw).decode('utf-8')
+
 
 def _server_name() -> str:
     """Return the server name, namespaced for dev mode."""
@@ -41,6 +52,16 @@ def __init__(self, parent: QObject | None = None) -> None:
         """
         super().__init__(parent)
         self._server: QLocalServer | None = None
+        self._debug_handler: Callable[[str], str] | None = None
+
+    def set_debug_handler(self, handler: Callable[[str], str]) -> None:
+        """Register a handler for ``debug:`` IPC commands.
+
+        Args:
+            handler: Callable that accepts a command string (without the
+                ``debug:`` prefix) and returns a JSON response string.
+        """
+        self._debug_handler = handler
 
     @staticmethod
     def try_send_to_existing(message: str) -> bool:
@@ -65,6 +86,34 @@ def try_send_to_existing(message: str) -> bool:
 
         return False
 
+    @staticmethod
+    def send_debug_command(command: str) -> str:
+        """Send a debug command to the running instance and return its response.
+
+        Args:
+            command: The debug command (without the ``debug:`` prefix).
+
+        Returns:
+            The JSON response string from the running instance, or an
+            error JSON string if the connection failed.
+        """
+        socket = QLocalSocket()
+        socket.connectToServer(_server_name())
+
+        if not socket.waitForConnected(SOCKET_TIMEOUT_MS):
+            return '{"error": "No running instance found"}'
+
+        socket.write(QByteArray(f'{_DEBUG_PREFIX}{command}'.encode()))
+        socket.waitForBytesWritten(SOCKET_TIMEOUT_MS)
+
+        if not socket.waitForReadyRead(SOCKET_TIMEOUT_MS):
+            socket.disconnectFromServer()
+            return '{"error": "Timed out waiting for response"}'
+
+        raw = socket.readAll().data()
+        socket.disconnectFromServer()
+        return _decode(raw)
+
     def start_server(self) -> bool:
         """Start the local socket server to listen for incoming messages.
 
@@ -98,8 +147,17 @@ def _on_new_connection(self) -> None:
 
         if socket.waitForReadyRead(SOCKET_TIMEOUT_MS):
             raw = socket.readAll().data()
-            data = raw.decode('utf-8') if isinstance(raw, (bytes, bytearray)) else str(raw)
-            if data:
+            data = _decode(raw)
+
+            if data.startswith(_DEBUG_PREFIX):
+                command = data[len(_DEBUG_PREFIX) :]
+                if self._debug_handler is not None:
+                    response = self._debug_handler(command)
+                else:
+                    response = '{"error": "debug handler not registered"}'
+                socket.write(QByteArray(response.encode('utf-8')))
+                socket.waitForBytesWritten(SOCKET_TIMEOUT_MS)
+            elif data:
                 logger.info('Received message from another instance: %s', data)
                 self.uri_received.emit(data)
             else:
diff --git a/synodic_client/application/qt.py b/synodic_client/application/qt.py
index b789415..bb7c5ac 100644
--- a/synodic_client/application/qt.py
+++ b/synodic_client/application/qt.py
@@ -2,7 +2,9 @@
 
 import asyncio
 import ctypes
+import importlib.metadata
 import logging
+import os
 import signal
 import sys
 import traceback
@@ -16,6 +18,7 @@
 from PySide6.QtWidgets import QApplication, QWidget
 
 from synodic_client.application.config_store import ConfigStore
+from synodic_client.application.debug import DebugHandler, DebugServices
 from synodic_client.application.icon import app_icon
 from synodic_client.application.init import run_startup_preamble
 from synodic_client.application.instance import SingleInstance
@@ -25,7 +28,7 @@
 from synodic_client.application.uri import parse_uri
 from synodic_client.client import Client
 from synodic_client.config import set_dev_mode
-from synodic_client.logging import configure_logging, set_debug_level
+from synodic_client.logging import configure_logging, log_path, set_debug_level
 from synodic_client.protocol import extract_uri_from_args
 from synodic_client.resolution import (
     ResolvedConfig,
@@ -60,6 +63,19 @@ def _init_services(logger: logging.Logger) -> tuple[Client, API, ResolvedConfig]
         update_config.repo_url,
         len(cached_dirs),
     )
+    logger.debug(
+        'Resolved config: update_source=%s update_channel=%s auto_update=%dm tool_update=%dm '
+        'auto_apply=%s auto_start=%s debug_logging=%s prerelease_packages=%s plugin_auto_update=%s',
+        config.update_source,
+        config.update_channel,
+        config.auto_update_interval_minutes,
+        config.tool_update_interval_minutes,
+        config.auto_apply,
+        config.auto_start,
+        config.debug_logging,
+        config.prerelease_packages,
+        config.plugin_auto_update,
+    )
 
     return client, porringer, config
 
@@ -74,22 +90,41 @@ def _process_uri(uri: str, handler: Callable[[str], None]) -> None:
             handler(manifests[0])
 
 
-def _cancel_all_tasks(loop: asyncio.AbstractEventLoop) -> None:
-    """Cancel every pending asyncio task on *loop*.
+_SHUTDOWN_TIMEOUT: float = 3.0
+
+
+async def _async_shutdown(
+    loop: asyncio.AbstractEventLoop,
+    *,
+    timeout: float = _SHUTDOWN_TIMEOUT,
+) -> None:
+    """Cancel remaining async tasks and wait for cleanup to finish.
 
-    Called synchronously from the ``aboutToQuit`` handler.  Each task
-    receives a cancellation request; when the event loop processes its
-    remaining iterations the ``CancelledError`` propagates and the
-    tasks finish cleanly.
+    Runs after the Qt event loop exits.  Tasks blocked in
+    ``run_in_executor`` threads (network / subprocess I/O) cannot be
+    interrupted, so if any are still alive after *timeout* seconds
+    the process is force-exited via ``os._exit(0)`` to avoid blocking
+    on non-daemon thread joins during interpreter shutdown.
     """
     _logger = logging.getLogger(__name__)
-    pending = [t for t in asyncio.all_tasks(loop) if not t.done()]
+    current = asyncio.current_task()
+    pending = [t for t in asyncio.all_tasks(loop) if t is not current and not t.done()]
     if not pending:
         return
+
     _logger.info('Cancelling %d pending async task(s)', len(pending))
     for task in pending:
         task.cancel()
 
+    _, still_pending = await asyncio.wait(pending, timeout=timeout)
+    if still_pending:
+        _logger.warning(
+            '%d task(s) did not finish within %.1fs — forcing exit',
+            len(still_pending),
+            timeout,
+        )
+        os._exit(0)
+
 
 def _install_exception_hook(logger: logging.Logger) -> None:
     """Redirect unhandled exceptions to the log file.
@@ -115,7 +150,7 @@ class _TopLevelShowFilter(QObject):
 
     _diag_logger = logging.getLogger('synodic_client.diag.window')
 
-    def eventFilter(self, obj: QObject, event: QEvent) -> bool:  # noqa: N802
+    def eventFilter(self, obj: QObject, event: QEvent) -> bool:
         if (
             event.type() in {QEvent.Type.Show, QEvent.Type.WindowActivate}
             and isinstance(obj, QWidget)
@@ -152,9 +187,12 @@ def _init_app() -> QApplication:
     app.setWindowIcon(app_icon())
     app.setAttribute(Qt.ApplicationAttribute.AA_CompressHighFrequencyEvents)
 
-    # [DIAG] Install a global event filter to log every top-level window show.
-    diag_filter = _TopLevelShowFilter(app)  # parented to app, prevented from GC
-    app.installEventFilter(diag_filter)
+    # Install the diagnostic event filter only when debug-level logging is
+    # active — it calls traceback.format_stack() on every top-level Show
+    # event, which is measurable overhead in normal operation.
+    if logging.getLogger('synodic_client').isEnabledFor(logging.DEBUG):
+        diag_filter = _TopLevelShowFilter(app)  # parented to app, prevented from GC
+        app.installEventFilter(diag_filter)
 
     # Allow Ctrl+C in the terminal to terminate the application.
     # Qt's event loop blocks Python's default SIGINT handling, so we
@@ -168,6 +206,40 @@ def _init_app() -> QApplication:
     return app
 
 
+def _configure_startup(
+    logger: logging.Logger,
+    *,
+    uri: str | None,
+    dev_mode: bool,
+    debug: bool,
+) -> None:
+    """Run the early startup sequence: Velopack, logging banner, URI log."""
+    logger.info('Log file: %s', log_path())
+    logger.info(
+        'Environment: Python %s | PySide6 %s | porringer %s | platform=%s | frozen=%s',
+        sys.version.split()[0],
+        importlib.metadata.version('PySide6'),
+        importlib.metadata.version('porringer'),
+        sys.platform,
+        getattr(sys, 'frozen', False),
+    )
+
+    _install_exception_hook(logger)
+
+    if not dev_mode:
+        # All three functions are idempotent — safe to call even when
+        # bootstrap.py has already executed them before heavy imports.
+        initialize_velopack()
+        run_startup_preamble(sys.executable)
+
+    if uri:
+        logger.info('Received URI: %s', uri)
+
+    if not debug and logging.getLogger('synodic_client').level > logging.DEBUG:
+        # Will be re-evaluated after config is loaded; this is just the banner.
+        pass
+
+
 def application(*, uri: str | None = None, dev_mode: bool = False, debug: bool = False) -> None:
     """Application entry point.
 
@@ -188,16 +260,8 @@ def application(*, uri: str | None = None, dev_mode: bool = False, debug: bool =
     # first-run diagnostics are captured in the log file.
     configure_logging(debug=debug)
     logger = logging.getLogger('synodic_client')
-    _install_exception_hook(logger)
 
-    if not dev_mode:
-        # All three functions are idempotent — safe to call even when
-        # bootstrap.py has already executed them before heavy imports.
-        initialize_velopack()
-        run_startup_preamble(sys.executable)
-
-    if uri:
-        logger.info('Received URI: %s', uri)
+    _configure_startup(logger, uri=uri, dev_mode=dev_mode, debug=debug)
 
     client, porringer, config = _init_services(logger)
 
@@ -237,20 +301,35 @@ def _handle_install_uri(manifest_url: str) -> None:
         window.activateWindow()
         window.start()
 
+    _debug_handler = DebugHandler(
+        DebugServices(
+            client=client,
+            porringer=porringer,
+            coordinator=_screen.window.coordinator,
+            config_store=_store,
+            update_controller=_tray.update_controller,
+            update_model=_tray.update_model,
+            tool_orchestrator=_tray.tool_orchestrator,
+            main_window=_screen.window,
+            settings_window=_tray.settings_window,
+        )
+    )
+    instance.set_debug_handler(_debug_handler.handle)
+
     instance.uri_received.connect(lambda received_uri: _process_uri(received_uri, _handle_install_uri))
 
     if uri:
         _process_uri(uri, _handle_install_uri)
 
     # --- Graceful shutdown ---
-    # aboutToQuit fires synchronously when app.quit() is called but
-    # before the event loop stops, giving us a window to cancel
-    # in-flight async tasks and stop timers.
+    # aboutToQuit fires while the Qt event loop is still running —
+    # stop timers and issue task cancellations here.  The actual await
+    # of those cancellations runs after run_forever() returns (see
+    # _async_shutdown below).
 
     def _on_about_to_quit() -> None:
-        logger.info('Application shutting down — cancelling async tasks')
+        logger.info('Application shutting down')
         _tray.shutdown()
-        _cancel_all_tasks(loop)
 
     app.aboutToQuit.connect(_on_about_to_quit)
 
@@ -258,6 +337,15 @@ def _on_about_to_quit() -> None:
     # enabling async/await usage in the GUI layer without dedicated threads.
     with loop:
         loop.run_forever()
+        # The Qt event loop has exited.  Give cancelled tasks a window
+        # to handle CancelledError, run finally blocks, and release
+        # resources.  If any tasks are stuck in executor threads,
+        # _async_shutdown force-exits after the timeout.
+        try:
+            loop.run_until_complete(_async_shutdown(loop))
+        except Exception:
+            logger.exception('Async shutdown failed — forcing exit')
+            os._exit(0)
 
 
 if __name__ == '__main__':
diff --git a/synodic_client/application/schema.py b/synodic_client/application/schema.py
index 932d56d..9c27450 100644
--- a/synodic_client/application/schema.py
+++ b/synodic_client/application/schema.py
@@ -13,6 +13,7 @@
 from porringer.schema import (
     DirectoryValidationResult,
     ManifestDirectory,
+    PluginCapability,
     PluginInfo,
 )
 
@@ -40,6 +41,9 @@ class Snapshot:
     plugin_managers: dict[str, PluginManager] = field(default_factory=dict)
     """Project-environment plugins implementing the ``PluginManager`` protocol."""
 
+    plugin_capabilities: dict[str, frozenset[PluginCapability]] = field(default_factory=dict)
+    """Protocol capabilities reported for each discovered plugin."""
+
 
 @dataclass(slots=True)
 class ToolUpdateResult:
diff --git a/synodic_client/application/screen/__init__.py b/synodic_client/application/screen/__init__.py
index bbac2ea..412a4d3 100644
--- a/synodic_client/application/screen/__init__.py
+++ b/synodic_client/application/screen/__init__.py
@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import re
 from datetime import UTC, datetime
 
 from porringer.schema import SetupAction, SetupActionResult, SkipReason
@@ -113,3 +114,15 @@ def _format_relative_time(iso_timestamp: str) -> str:
         return f'{days}d ago'
     except ValueError, TypeError:
         return ''
+
+
+def is_version_specifier(value: str) -> bool:
+    """Return whether *value* looks like a PEP 440 version specifier.
+
+    Returns ``True`` when the string contains comparison operators
+    (``>=``, ``<=``, ``!=``, ``~=``, ``==``, ``>``, ``<``) or
+    caret/tilde shorthand (``^``, ``~`` not followed by ``=``).
+    This distinguishes constraint strings like ``">=0.8.0"`` from
+    resolved version numbers like ``"0.9.1"``.
+    """
+    return bool(re.search(r'[><=!~^]', value))
diff --git a/synodic_client/application/screen/action_card.py b/synodic_client/application/screen/action_card.py
index d5911d6..66a2cfd 100644
--- a/synodic_client/application/screen/action_card.py
+++ b/synodic_client/application/screen/action_card.py
@@ -29,7 +29,12 @@
     QWidget,
 )
 
-from synodic_client.application.screen import ACTION_KIND_LABELS, format_cli_command, skip_reason_label
+from synodic_client.application.screen import (
+    ACTION_KIND_LABELS,
+    format_cli_command,
+    is_version_specifier,
+    skip_reason_label,
+)
 from synodic_client.application.screen.spinner import SpinnerCanvas
 from synodic_client.application.theme import (
     ACTION_CARD_COMMAND_STYLE,
@@ -441,13 +446,13 @@ def _stop_spinner(self) -> None:
     def set_check_result(self, result: SetupActionResult) -> None:
         """Update the card with a dry-run check result.
 
-        Handles four cases:
+        Handles these cases:
 
         * **Skipped (update available)** — amber "Update available" badge.
         * **Skipped (other)** — muted satisfied badge.
         * **Failed** — red "Failed" badge with diagnostic tooltip.
-          This covers backend failures surfaced during the dry-run
-          (e.g. missing SCM plugin, unresolvable deferred action).
+        * **Bare command** (kind=None, success=True) — keeps "Pending".
+        * **Project sync** (kind=PROJECT, success=True) — "Ready".
         * **Needed** — default blue badge.
 
         Args:
@@ -475,6 +480,15 @@ def set_check_result(self, result: SetupActionResult) -> None:
                 self._action.description if self._action else '(unknown)',
                 result.message or 'unknown error',
             )
+        elif self._action is not None and self._action.kind is None:
+            # Bare command — porringer returns success=True; keep Pending.
+            label = 'Pending'
+            self._status_label.setText(label)
+            self._status_label.setStyleSheet(ACTION_CARD_STATUS_PENDING)
+        elif self._action is not None and self._action.kind == PluginKind.PROJECT:
+            label = 'Ready'
+            self._status_label.setText(label)
+            self._status_label.setStyleSheet(ACTION_CARD_STATUS_SATISFIED)
         else:
             label = 'Needed'
             self._status_label.setText(label)
@@ -494,12 +508,27 @@ def set_check_result(self, result: SetupActionResult) -> None:
             self._command_row.show()
 
         # Version column
+        self._update_version_column(result)
+
+    def _update_version_column(self, result: SetupActionResult) -> None:
+        """Update the version label and tooltip from a dry-run result."""
         self._check_available_version = result.available_version
+        assert self._action is not None
+        constraint = (
+            str(self._action.package.constraint)
+            if self._action.package and getattr(self._action.package, 'constraint', None)
+            else ''
+        )
         if result.installed_version and result.available_version:
             self._version_label.setText(f'{result.installed_version} \u2192 {result.available_version}')
             self._version_label.setStyleSheet(ACTION_CARD_VERSION_STYLE + ' color: #d7ba7d;')
         elif result.installed_version:
             self._version_label.setText(result.installed_version)
+            if constraint:
+                self._version_label.setToolTip(f'satisfies {constraint}')
+        elif result.available_version and is_version_specifier(result.available_version):
+            self._version_label.setText(f'requires {result.available_version}')
+            self._version_label.setStyleSheet(ACTION_CARD_VERSION_STYLE + ' color: grey;')
         elif result.available_version:
             self._version_label.setText(f'\u2192 {result.available_version}')
             self._version_label.setStyleSheet(ACTION_CARD_VERSION_STYLE + ' color: grey;')
@@ -514,6 +543,10 @@ def finalize_checking(self) -> None:
             return
         if self._checking:
             self._stop_spinner()
+            logger.warning(
+                'Finalizing card with no dry-run result: %s',
+                self._action.description if self._action else '(unknown)',
+            )
             self._status_label.setText('Needed')
             self._status_label.setStyleSheet(ACTION_CARD_STATUS_NEEDED)
 
diff --git a/synodic_client/application/screen/install.py b/synodic_client/application/screen/install.py
index 0c1f432..4255a3d 100644
--- a/synodic_client/application/screen/install.py
+++ b/synodic_client/application/screen/install.py
@@ -27,6 +27,7 @@
     SubActionProgress,
     SyncStrategy,
 )
+from porringer.schema.plugin import PluginKind
 from PySide6.QtCore import Qt, QTimer, Signal
 from PySide6.QtGui import QShowEvent
 from PySide6.QtWidgets import (
@@ -537,9 +538,14 @@ def _on_manifest_parsed(self, preview: SetupResults, manifest_path: str, temp_di
 
         self._on_preview_ready(preview, manifest_path, temp_dir_path)
 
-    def _on_plugins_queried(self, mapping: dict[str, bool]) -> None:
-        """Store plugin presence data for annotating the action cards."""
+    def _on_plugins_queried(
+        self,
+        mapping: dict[str, bool],
+        capabilities: dict[str, frozenset],
+    ) -> None:
+        """Store plugin presence and capability data for annotating the action cards."""
         self._model.plugin_installed = mapping
+        self._model.plugin_capabilities = capabilities
 
     def _on_preview_ready(self, preview: SetupResults, manifest_path: str, temp_dir_path: str) -> None:
         """Handle a successful preview — populate action cards."""
@@ -621,11 +627,31 @@ def _on_action_checked(self, row: int, result: SetupActionResult) -> None:
         elif not result.success:
             label = 'Failed'
         else:
-            label = 'Needed'
+            # Bare commands (kind=None) and PROJECT actions always return
+            # success=True from porringer's dry_run_action.  Don't
+            # overwrite their initial status to "Needed".
+            action = m.action_states[row].action if 0 <= row < len(m.action_states) else None
+            if action is not None and action.kind is None:
+                label = 'Pending'
+            elif action is not None and action.kind == PluginKind.PROJECT:
+                label = 'Ready'
+            else:
+                label = 'Needed'
 
         if 0 <= row < len(m.action_states):
             m.action_states[row].status = label
 
+        logger.debug(
+            'Action checked [%d]: status=%s success=%s skipped=%s skip_reason=%s installed=%s available=%s',
+            row,
+            label,
+            result.success,
+            result.skipped,
+            result.skip_reason,
+            result.installed_version,
+            result.available_version,
+        )
+
         # Update the card widget
         if m.preview and 0 <= row < len(m.preview.actions):
             action = m.preview.actions[row]
@@ -658,9 +684,17 @@ def _on_preview_finished(self) -> None:
 
         self._card_list.finalize_all_checking()
 
+        finalized: list[str] = []
         for state in m.action_states:
             if state.status == 'Checking\u2026':
+                finalized.append(state.action.description)
                 state.status = 'Needed'
+        if finalized:
+            logger.warning(
+                'Finalized %d action(s) from Checking to Needed (no dry-run result received): %s',
+                len(finalized),
+                finalized,
+            )
 
         # Compute summary
         total = len(m.action_states)
@@ -668,19 +702,23 @@ def _on_preview_finished(self) -> None:
         upgradable = len(m.upgradable_keys)
         unavailable = sum(1 for s in m.action_states if s.status == 'Not installed')
         failed = sum(1 for s in m.action_states if s.status == 'Failed')
-        satisfied = total - needed - upgradable - unavailable - failed
+        pending = sum(1 for s in m.action_states if s.status == 'Pending')
+        ready = sum(1 for s in m.action_states if s.status == 'Ready')
+        satisfied = total - needed - upgradable - unavailable - failed - pending - ready
 
         parts: list[str] = []
-        if needed:
-            parts.append(f'{needed} needed')
-        if upgradable:
-            parts.append(f'{upgradable} upgradable')
-        if satisfied:
-            parts.append(f'{satisfied} already satisfied')
-        if unavailable:
-            parts.append(f'{unavailable} unavailable (plugin not installed)')
-        if failed:
-            parts.append(f'{failed} failed')
+        _counts: list[tuple[int, str]] = [
+            (needed, 'needed'),
+            (upgradable, 'upgradable'),
+            (satisfied, 'already satisfied'),
+            (ready, 'ready'),
+            (pending, 'pending'),
+            (unavailable, 'unavailable (plugin not installed)'),
+            (failed, 'failed'),
+        ]
+        for count, label in _counts:
+            if count:
+                parts.append(f'{count} {label}')
 
         actionable = needed + upgradable
         if actionable == 0 and unavailable == 0 and failed == 0:
@@ -692,11 +730,14 @@ def _on_preview_finished(self) -> None:
         self._set_phase(PreviewPhase.READY)
 
         logger.info(
-            'Preview complete: %d total, %d needed, %d upgradable, %d satisfied, %d unavailable, %d failed',
+            'Preview complete: %d total, %d needed, %d upgradable, %d satisfied, '
+            '%d ready, %d pending, %d unavailable, %d failed',
             total,
             needed,
             upgradable,
             satisfied,
+            ready,
+            pending,
             unavailable,
             failed,
         )
@@ -895,7 +936,7 @@ def __init__(
 
         self._init_ui()
 
-    def showEvent(self, event: QShowEvent) -> None:  # noqa: N802
+    def showEvent(self, event: QShowEvent) -> None:
         """[DIAG] Log every show event with a stack trace."""
         geo = self.geometry()
         stack = ''.join(traceback.format_stack(limit=10))
diff --git a/synodic_client/application/screen/install_workers.py b/synodic_client/application/screen/install_workers.py
index b52986b..f997891 100644
--- a/synodic_client/application/screen/install_workers.py
+++ b/synodic_client/application/screen/install_workers.py
@@ -14,13 +14,18 @@
 from porringer.api import API
 from porringer.backend.command.core.discovery import DiscoveredPlugins
 from porringer.schema import (
+    ActionCompletedEvent,
+    ActionStartedEvent,
     DownloadParameters,
+    ManifestLoadedEvent,
+    ManifestParsedEvent,
+    PluginsDiscoveredEvent,
     ProgressEvent,
-    ProgressEventKind,
     SetupAction,
     SetupActionResult,
     SetupParameters,
     SetupResults,
+    SubActionProgressEvent,
 )
 
 from synodic_client.application.screen.schema import (
@@ -79,22 +84,17 @@ async def run_install(
     manifest_result: SetupResults | None = None
 
     async for event in porringer.sync.execute_stream(params, plugins=plugins):
-        if event.kind == ProgressEventKind.MANIFEST_LOADED and event.manifest:
+        if isinstance(event, ManifestLoadedEvent):
             manifest_result = event.manifest
             actions = list(event.manifest.actions)
 
-        if event.kind == ProgressEventKind.ACTION_STARTED and event.action and cb.on_action_started is not None:
+        elif isinstance(event, ActionStartedEvent) and cb.on_action_started is not None:
             cb.on_action_started(event.action)
 
-        if (
-            event.kind == ProgressEventKind.SUB_ACTION_PROGRESS
-            and event.action
-            and event.sub_action
-            and cb.on_sub_progress is not None
-        ):
+        elif isinstance(event, SubActionProgressEvent) and cb.on_sub_progress is not None:
             cb.on_sub_progress(event.action, event.sub_action)
 
-        if event.kind == ProgressEventKind.ACTION_COMPLETED and event.result and event.action:
+        elif isinstance(event, ActionCompletedEvent):
             collected.append(event.result)
             if cb.on_progress is not None:
                 cb.on_progress(event.action, event.result)
@@ -161,30 +161,24 @@ def _dispatch_preview_event(
 
     Mutates *state* in-place (``got_parsed`` flag).
     """
-    if event.kind == ProgressEventKind.MANIFEST_PARSED and event.manifest:
+    if isinstance(event, ManifestParsedEvent):
         if cb.on_manifest_parsed is not None:
             cb.on_manifest_parsed(event.manifest, manifest_path, temp_dir_str)
         state.got_parsed = True
         return
 
-    if event.kind == ProgressEventKind.PLUGINS_DISCOVERED and cb.on_plugins_queried is not None:
-        if event.plugin_availability is not None:
-            cb.on_plugins_queried(event.plugin_availability)
-        elif event.plugin_names is not None:
-            cb.on_plugins_queried({name: True for name in event.plugin_names})
+    if isinstance(event, PluginsDiscoveredEvent) and cb.on_plugins_queried is not None:
+        availability = {entry.name: entry.available for entry in event.discovered_plugins}
+        capabilities = {entry.name: entry.capabilities for entry in event.discovered_plugins}
+        cb.on_plugins_queried(availability, capabilities)
         return
 
-    if event.kind == ProgressEventKind.MANIFEST_LOADED and event.manifest:
+    if isinstance(event, ManifestLoadedEvent):
         if cb.on_preview_ready is not None:
             cb.on_preview_ready(event.manifest, manifest_path, temp_dir_str)
         return
 
-    if (
-        event.kind == ProgressEventKind.ACTION_COMPLETED
-        and event.result
-        and event.action_index is not None
-        and cb.on_action_checked is not None
-    ):
+    if isinstance(event, ActionCompletedEvent) and event.action_index is not None and cb.on_action_checked is not None:
         cb.on_action_checked(event.action_index, event.result)
 
 
diff --git a/synodic_client/application/screen/plugin_row.py b/synodic_client/application/screen/plugin_row.py
index b8d354e..3027288 100644
--- a/synodic_client/application/screen/plugin_row.py
+++ b/synodic_client/application/screen/plugin_row.py
@@ -8,7 +8,7 @@
 from __future__ import annotations
 
 from porringer.schema import PluginInfo
-from porringer.schema.plugin import PluginKind
+from porringer.schema.plugin import PluginCapability, PluginKind
 from PySide6.QtCore import Qt, QTimer, Signal
 from PySide6.QtWidgets import (
     QFrame,
@@ -133,6 +133,7 @@ def __init__(
         plugin: PluginInfo,
         auto_update: bool = True,
         *,
+        capabilities: frozenset[PluginCapability] = frozenset(),
         show_controls: bool = False,
         has_updates: bool = False,
         parent: QWidget | None = None,
@@ -173,7 +174,12 @@ def __init__(
         status_label.setStyleSheet(
             PLUGIN_PROVIDER_STATUS_INSTALLED_STYLE if plugin.installed else PLUGIN_PROVIDER_STATUS_MISSING_STYLE
         )
-        status_label.setToolTip('Installed' if plugin.installed else 'Not installed')
+        base_tip = 'Installed' if plugin.installed else 'Not installed'
+        if capabilities:
+            cap_names = ', '.join(c.name.replace('_', ' ').title() for c in sorted(capabilities, key=lambda c: c.name))
+            status_label.setToolTip(f'{base_tip} \u00b7 {cap_names}')
+        else:
+            status_label.setToolTip(base_tip)
         self._layout.addWidget(status_label)
 
         self._layout.addStretch()
diff --git a/synodic_client/application/screen/schema.py b/synodic_client/application/screen/schema.py
index bc88cea..4459024 100644
--- a/synodic_client/application/screen/schema.py
+++ b/synodic_client/application/screen/schema.py
@@ -14,6 +14,7 @@
 from pathlib import Path
 
 from porringer.schema import (
+    PluginCapability,
     PluginInfo,
     SetupAction,
     SetupActionResult,
@@ -244,6 +245,7 @@ def __init__(self) -> None:
         self.manifest_key: str | None = None
         self.project_directory: Path | None = None
         self.plugin_installed: dict[str, bool] = {}
+        self.plugin_capabilities: dict[str, frozenset[PluginCapability]] = {}
         self.prerelease_overrides: set[str] = set()
         self.action_states: list[ActionState] = []
         self._action_state_map: dict[SetupAction, ActionState] = {}
@@ -315,8 +317,8 @@ class PreviewCallbacks:
     on_manifest_parsed: Callable[[SetupResults, str, str], None] | None = None
     """``(SetupResults, manifest_path, temp_dir)`` — after JSON load."""
 
-    on_plugins_queried: Callable[[dict[str, bool]], None] | None = None
-    """``(dict[str, bool])`` — plugin → installed mapping."""
+    on_plugins_queried: Callable[[dict[str, bool], dict[str, frozenset[PluginCapability]]], None] | None = None
+    """``(dict[str, bool], dict[str, frozenset[PluginCapability]])`` — plugin → installed + capabilities mappings."""
 
     on_preview_ready: Callable[[SetupResults, str, str], None] | None = None
     """``(SetupResults, manifest_path, temp_dir)`` — CLI commands resolved."""
diff --git a/synodic_client/application/screen/screen.py b/synodic_client/application/screen/screen.py
index 10074c8..6ef1094 100644
--- a/synodic_client/application/screen/screen.py
+++ b/synodic_client/application/screen/screen.py
@@ -11,16 +11,16 @@
 from porringer.core.plugin_schema.plugin_manager import PluginManager
 from porringer.core.plugin_schema.project_environment import ProjectEnvironment
 from porringer.schema import (
+    ActionCompletedEvent,
     ManifestDirectory,
+    ManifestParsedEvent,
     PluginInfo,
-    ProgressEventKind,
     SetupAction,
     SetupParameters,
     SkipReason,
     SyncStrategy,
 )
 from porringer.schema.plugin import PluginKind, RuntimePackageResult
-from porringer.utility.exception import PluginError
 from PySide6.QtCore import QEasingCurve, QEvent, QObject, QPropertyAnimation, Qt, QTimer, Signal
 from PySide6.QtGui import QKeyEvent, QKeySequence, QShortcut, QShowEvent
 from PySide6.QtWidgets import (
@@ -477,6 +477,11 @@ def _sort_key(rt: RuntimePackageResult) -> tuple[int, str]:
             provider = PluginProviderHeader(
                 plugin,
                 auto_val is not False,
+                capabilities=(
+                    self._coordinator.snapshot.plugin_capabilities.get(plugin.name, frozenset())
+                    if self._coordinator is not None
+                    else frozenset()
+                ),
                 show_controls=True,
                 has_updates=bool(rt_updates),
                 parent=self._container,
@@ -531,10 +536,16 @@ def _build_plugin_section(
         """
         auto_val = auto_update_map.get(plugin.name, True)
         plugin_updates = self._get_plugin_updates(plugin.name)
+        caps = (
+            self._coordinator.snapshot.plugin_capabilities.get(plugin.name, frozenset())
+            if self._coordinator is not None
+            else frozenset()
+        )
 
         provider = PluginProviderHeader(
             plugin,
             auto_val is not False,
+            capabilities=caps,
             show_controls=True,
             has_updates=bool(plugin_updates),
             parent=self._container,
@@ -946,8 +957,6 @@ async def _gather_runtime_packages(self, plugin_name: str, discovered) -> list |
                 plugin_name,
                 plugins=discovered,
             )
-        except PluginError:
-            return None
         except Exception:
             logger.debug(
                 'Per-runtime probe failed for %s',
@@ -1066,7 +1075,7 @@ async def _gather_project_requirements(
                     project_directory=path,
                 )
                 async for event in self._porringer.sync.execute_stream(params):
-                    if event.kind == ProgressEventKind.MANIFEST_PARSED and event.manifest:
+                    if isinstance(event, ManifestParsedEvent):
                         actions.extend(event.manifest.actions)
                         break
         except Exception:
@@ -1244,11 +1253,7 @@ async def _check_directory_updates(
                 project_directory=path,
             )
             async for event in self._porringer.sync.execute_stream(params):
-                if (
-                    event.kind == ProgressEventKind.ACTION_COMPLETED
-                    and event.result is not None
-                    and event.result.skip_reason == SkipReason.UPDATE_AVAILABLE
-                ):
+                if isinstance(event, ActionCompletedEvent) and event.result.skip_reason == SkipReason.UPDATE_AVAILABLE:
                     action = event.result.action
                     if action.installer and action.package:
                         pkg_name = str(action.package.name)
@@ -1435,7 +1440,7 @@ def __init__(
         # Update banner — always available, starts hidden.
         self._update_banner = UpdateBanner(self)
 
-    def showEvent(self, event: QShowEvent) -> None:  # noqa: N802
+    def showEvent(self, event: QShowEvent) -> None:
         """[DIAG] Log every show event with a stack trace."""
         geo = self.geometry()
         stack = ''.join(traceback.format_stack(limit=10))
diff --git a/synodic_client/application/screen/settings.py b/synodic_client/application/screen/settings.py
index f178942..9ceaf83 100644
--- a/synodic_client/application/screen/settings.py
+++ b/synodic_client/application/screen/settings.py
@@ -55,7 +55,7 @@ class SettingsWindow(QMainWindow):
     restart_requested = Signal()
     """Emitted when the user clicks the *Restart & Update* button."""
 
-    def showEvent(self, event: QShowEvent) -> None:  # noqa: N802
+    def showEvent(self, event: QShowEvent) -> None:
         """[DIAG] Log every show event with a stack trace."""
         geo = self.geometry()
         stack = ''.join(traceback.format_stack(limit=10))
diff --git a/synodic_client/application/screen/tool_update_controller.py b/synodic_client/application/screen/tool_update_controller.py
index ccc3588..321fea8 100644
--- a/synodic_client/application/screen/tool_update_controller.py
+++ b/synodic_client/application/screen/tool_update_controller.py
@@ -11,9 +11,9 @@
 
 import asyncio
 import logging
-from collections.abc import Callable
+from collections.abc import Callable, Coroutine
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from porringer.api import API
 from porringer.core.schema import PackageRef
@@ -96,6 +96,12 @@ def shutdown(self) -> None:
             self._tool_task = None
         logger.info('ToolUpdateOrchestrator shut down')
 
+    def _set_task(self, coro: Coroutine[Any, Any, None]) -> None:
+        """Cancel any in-flight task and start *coro* as the active task."""
+        if self._tool_task is not None and not self._tool_task.done():
+            self._tool_task.cancel()
+        self._tool_task = asyncio.create_task(coro)
+
     # -- Timer management --
 
     @staticmethod
@@ -192,7 +198,7 @@ def on_tool_update(self) -> None:
             return
 
         logger.info('Starting periodic tool update check')
-        self._tool_task = asyncio.create_task(self._do_tool_update(porringer))
+        self._set_task(self._do_tool_update(porringer))
 
     async def _do_tool_update(self, porringer: API) -> None:
         """Resolve enabled plugins off-thread, then run the tool update."""
@@ -250,11 +256,11 @@ def on_single_plugin_update(self, plugin_name: str) -> None:
 
         bare_plugin, runtime_tag = _parse_plugin_key(plugin_name)
         if runtime_tag is not None:
-            self._tool_task = asyncio.create_task(
+            self._set_task(
                 self._async_runtime_plugin_update(porringer, plugin_name, bare_plugin, runtime_tag),
             )
         else:
-            self._tool_task = asyncio.create_task(
+            self._set_task(
                 self._async_single_plugin_update(porringer, plugin_name),
             )
 
@@ -341,7 +347,7 @@ def on_single_package_update(self, plugin_name: str, package_name: str) -> None:
         tools_view = self._window.tools_view
         if tools_view is not None:
             tools_view.set_package_updating(plugin_name, package_name, True)
-        self._tool_task = asyncio.create_task(
+        self._set_task(
             self._async_single_package_update(porringer, plugin_name, package_name),
         )
 
@@ -467,7 +473,7 @@ def on_single_package_remove(self, plugin_name: str, package_name: str) -> None:
         tools_view = self._window.tools_view
         if tools_view is not None:
             tools_view.set_package_removing(plugin_name, package_name, True)
-        self._tool_task = asyncio.create_task(
+        self._set_task(
             self._async_single_package_remove(porringer, plugin_name, package_name),
         )
 
diff --git a/synodic_client/application/screen/tray.py b/synodic_client/application/screen/tray.py
index e6c24c4..5e6dd0a 100644
--- a/synodic_client/application/screen/tray.py
+++ b/synodic_client/application/screen/tray.py
@@ -50,10 +50,8 @@ def __init__(
         self._window = window
         self._store = store
 
-        self.tray_icon = app_icon()
-
         self.tray = QSystemTrayIcon()
-        self.tray.setIcon(self.tray_icon)
+        self.tray.setIcon(app_icon())
         self.tray.activated.connect(self._on_tray_activated)
 
         # At early Windows login the notification area may not be ready.
@@ -113,25 +111,25 @@ def __init__(
 
     def _build_menu(self, app: QApplication, window: MainWindow) -> None:
         """Build the tray context menu."""
-        self.menu = QMenu()
+        self._menu = QMenu()
 
-        self.open_action = QAction('Open', self.menu)
-        self.menu.addAction(self.open_action)
-        self.open_action.triggered.connect(window.show)
+        self._open_action = QAction('Open', self._menu)
+        self._menu.addAction(self._open_action)
+        self._open_action.triggered.connect(window.show)
 
-        self.menu.addSeparator()
+        self._menu.addSeparator()
 
-        self.settings_action = QAction('Settings\u2026', self.menu)
-        self.settings_action.triggered.connect(self._show_settings)
-        self.menu.addAction(self.settings_action)
+        self._settings_action = QAction('Settings\u2026', self._menu)
+        self._settings_action.triggered.connect(self._show_settings)
+        self._menu.addAction(self._settings_action)
 
-        self.menu.addSeparator()
+        self._menu.addSeparator()
 
-        self.quit_action = QAction('Quit', self.menu)
-        self.quit_action.triggered.connect(app.quit)
-        self.menu.addAction(self.quit_action)
+        self._quit_action = QAction('Quit', self._menu)
+        self._quit_action.triggered.connect(app.quit)
+        self._menu.addAction(self._quit_action)
 
-        self.tray.setContextMenu(self.menu)
+        self.tray.setContextMenu(self._menu)
 
     # Maximum number of tray-visibility retries at startup.
     _TRAY_MAX_RETRIES = 5
@@ -185,6 +183,26 @@ def _is_user_active() -> bool:
         """
         return any(w.isVisible() for w in QApplication.topLevelWidgets() if isinstance(w, QMainWindow))
 
+    @property
+    def update_controller(self) -> UpdateController:
+        """Return the self-update controller."""
+        return self._update_controller
+
+    @property
+    def update_model(self) -> UpdateModel:
+        """Return the self-update observable model."""
+        return self._update_model
+
+    @property
+    def tool_orchestrator(self) -> ToolUpdateOrchestrator:
+        """Return the tool-update orchestrator."""
+        return self._tool_orchestrator
+
+    @property
+    def settings_window(self) -> SettingsWindow:
+        """Return the settings window."""
+        return self._settings_window
+
     def shutdown(self) -> None:
         """Stop all timers and cancel in-flight tasks for a clean exit."""
         self._update_controller.shutdown()
diff --git a/synodic_client/application/update_controller.py b/synodic_client/application/update_controller.py
index 7dca2b3..0204841 100644
--- a/synodic_client/application/update_controller.py
+++ b/synodic_client/application/update_controller.py
@@ -15,9 +15,9 @@
 import asyncio
 import logging
 import sys
-from collections.abc import Callable
+from collections.abc import Callable, Coroutine
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from PySide6.QtCore import QTimer
 from PySide6.QtWidgets import QApplication
@@ -120,6 +120,12 @@ def shutdown(self) -> None:
             self._update_task = None
         logger.info('UpdateController shut down')
 
+    def _set_task(self, coro: Coroutine[Any, Any, None]) -> None:
+        """Cancel any in-flight task and start *coro* as the active task."""
+        if self._update_task is not None and not self._update_task.done():
+            self._update_task.cancel()
+        self._update_task = asyncio.create_task(coro)
+
     # ------------------------------------------------------------------
     # Config helpers
     # ------------------------------------------------------------------
@@ -284,7 +290,7 @@ def _do_check(self, *, silent: bool) -> None:
             self._model.set_restart_visible(False)
             self._model.set_status('Checking\u2026', UPDATE_STATUS_CHECKING_STYLE)
 
-        self._update_task = asyncio.create_task(self._async_check(silent=silent))
+        self._set_task(self._async_check(silent=silent))
 
     async def _async_check(self, *, silent: bool) -> None:
         """Run the update check coroutine and route results."""
@@ -336,7 +342,7 @@ def _on_check_finished(self, result: UpdateInfo | None, *, silent: bool = False)
 
         # New update available — download it
         self._model.set_status(f'v{version} available', UPDATE_STATUS_AVAILABLE_STYLE)
-        self._model.begin_download(version)
+        self._model.set_downloading(version)
         self._start_download(version, silent=silent)
 
     def _on_check_error(self, error: str, *, silent: bool = False) -> None:
@@ -350,7 +356,7 @@ def _on_check_error(self, error: str, *, silent: bool = False) -> None:
 
     def _start_download(self, version: str, *, silent: bool = False) -> None:
         """Start downloading the update in the background."""
-        self._update_task = asyncio.create_task(self._async_download(version, silent=silent))
+        self._set_task(self._async_download(version, silent=silent))
 
     async def _async_download(self, version: str, *, silent: bool = False) -> None:
         """Run the download coroutine and route results."""
@@ -382,10 +388,7 @@ def _on_download_finished(self, success: bool, version: str, *, silent: bool = F
                 logger.warning('Download failed for %s (silent)', version)
             return
 
-        # Persist the client-update timestamp (actual update downloaded)
-        ts = datetime.now(UTC).isoformat()
-        self._store.update(last_client_update=ts)
-        self._model.set_last_checked(ts)
+        self._persist_check_timestamp()
 
         self._pending_version = version
 
diff --git a/synodic_client/application/update_model.py b/synodic_client/application/update_model.py
index 48cc33f..386901a 100644
--- a/synodic_client/application/update_model.py
+++ b/synodic_client/application/update_model.py
@@ -75,7 +75,7 @@ def error_message(self) -> str:
 
     # --- Lifecycle transitions (controller writes) ---
 
-    def begin_download(self, version: str) -> None:
+    def set_downloading(self, version: str) -> None:
         """Enter the *DOWNLOADING* phase for *version*."""
         self._version = version
         self._phase = UpdatePhase.DOWNLOADING
diff --git a/synodic_client/application/workers.py b/synodic_client/application/workers.py
index 62d91ac..372f8bd 100644
--- a/synodic_client/application/workers.py
+++ b/synodic_client/application/workers.py
@@ -14,7 +14,7 @@
 from porringer.api import API
 from porringer.backend.command.core.discovery import DiscoveredPlugins
 from porringer.core.schema import PackageRef
-from porringer.schema import ProgressEventKind, SetupParameters, SkipReason, SyncStrategy
+from porringer.schema import ActionCompletedEvent, SetupParameters, SkipReason, SyncStrategy
 from porringer.schema.execution import SetupActionResult
 
 from synodic_client.application.schema import ToolUpdateResult
@@ -120,7 +120,7 @@ async def run_tool_updates(
                 params,
                 plugins=discovered_plugins,
             ):
-                if event.kind != ProgressEventKind.ACTION_COMPLETED or event.result is None:
+                if not isinstance(event, ActionCompletedEvent):
                     continue
                 action_result = event.result
                 if action_result.skipped:
@@ -187,6 +187,8 @@ async def run_runtime_package_updates(
     """
     result = ToolUpdateResult()
     packages = await porringer.package.list_by_runtime(plugin_name, plugins=discovered_plugins)
+    if packages is None:
+        return result
     for rt in packages:
         if rt.tag != runtime_tag:
             continue
diff --git a/synodic_client/cli.py b/synodic_client/cli.py
deleted file mode 100644
index be61e88..0000000
--- a/synodic_client/cli.py
+++ /dev/null
@@ -1,46 +0,0 @@
-"""CLI entry point for the Synodic Client application."""
-
-from typing import Annotated
-
-import typer
-
-from synodic_client import __version__
-
-app = typer.Typer(
-    name='synodic-c',
-    help='Synodic Client — a system tray frontend for porringer.',
-    add_completion=False,
-)
-
-
-def _version_callback(value: bool) -> None:
-    """Print the version and exit."""
-    if value:
-        typer.echo(f'synodic-client {__version__}')
-        raise typer.Exit
-
-
-@app.command()
-def main(
-    uri: Annotated[
-        str | None,
-        typer.Argument(help='A synodic:// URI to process on launch.'),
-    ] = None,
-    *,
-    version: Annotated[
-        bool | None,
-        typer.Option('--version', callback=_version_callback, is_eager=True, help='Show version and exit.'),
-    ] = None,
-    dev: Annotated[
-        bool,
-        typer.Option('--dev', help='Run in dev mode with isolated config, logs, and instance lock.'),
-    ] = False,
-    debug: Annotated[
-        bool,
-        typer.Option('--debug', help='Enable DEBUG-level file logging for this session.'),
-    ] = False,
-) -> None:
-    """Launch the Synodic Client GUI application."""
-    from synodic_client.application.qt import application
-
-    application(uri=uri, dev_mode=dev, debug=debug)
diff --git a/synodic_client/cli/__init__.py b/synodic_client/cli/__init__.py
new file mode 100644
index 0000000..40564bd
--- /dev/null
+++ b/synodic_client/cli/__init__.py
@@ -0,0 +1,74 @@
+"""CLI entry point for the Synodic Client application.
+
+Restructured as a package with resource-verb subcommands:
+
+    synodic-c                    → launch GUI
+    synodic-c project list       → list cached projects
+    synodic-c tool check         → check for tool updates
+    synodic-c config get <key>   → read a config value
+    synodic-c update check       → check for self-update
+    synodic-c debug state        → dump running instance state (IPC)
+"""
+
+from typing import Annotated
+
+import typer
+
+from synodic_client import __version__
+from synodic_client.cli.config import config_app
+from synodic_client.cli.debug import debug_app
+from synodic_client.cli.project import project_app
+from synodic_client.cli.tool import tool_app
+from synodic_client.cli.update import update_app
+
+app = typer.Typer(
+    name='synodic-c',
+    help='Synodic Client — a system tray frontend for porringer.',
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    """Print the version and exit."""
+    if value:
+        typer.echo(f'synodic-client {__version__}')
+        raise typer.Exit
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    *,
+    uri: Annotated[
+        str | None,
+        typer.Option('--uri', help='A synodic:// URI to process on launch.'),
+    ] = None,
+    version: Annotated[
+        bool | None,
+        typer.Option('--version', callback=_version_callback, is_eager=True, help='Show version and exit.'),
+    ] = None,
+    dev: Annotated[
+        bool,
+        typer.Option('--dev', help='Run in dev mode with isolated config, logs, and instance lock.'),
+    ] = False,
+    debug: Annotated[
+        bool,
+        typer.Option('--debug', help='Enable DEBUG-level file logging for this session.'),
+    ] = False,
+) -> None:
+    """Launch the Synodic Client GUI application."""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    from synodic_client.application.qt import application
+
+    application(uri=uri, dev_mode=dev, debug=debug)
+
+
+# -- Register sub-typers --------------------------------------------------
+
+app.add_typer(project_app, name='project')
+app.add_typer(tool_app, name='tool')
+app.add_typer(config_app, name='config')
+app.add_typer(update_app, name='update')
+app.add_typer(debug_app, name='debug')
diff --git a/synodic_client/cli/config.py b/synodic_client/cli/config.py
new file mode 100644
index 0000000..c44738c
--- /dev/null
+++ b/synodic_client/cli/config.py
@@ -0,0 +1,92 @@
+"""Configuration commands.
+
+synodic-c config get <key>
+synodic-c config set <key> <value>
+synodic-c config list
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from synodic_client.cli.output import render
+
+config_app = typer.Typer(
+    help='Read and write Synodic Client configuration.',
+    add_completion=False,
+)
+
+
+@config_app.command('get')
+def config_get(
+    key: Annotated[
+        str,
+        typer.Argument(help='Configuration key to read.'),
+    ],
+    *,
+    json_output: Annotated[
+        bool,
+        typer.Option('--json', help='Output as JSON.'),
+    ] = False,
+) -> None:
+    """Print the current value of a config key."""
+    import dataclasses
+
+    from synodic_client.operations.config import get_config
+
+    config = get_config()
+    fields = {f.name for f in dataclasses.fields(config)}
+    if key not in fields:
+        typer.echo(f'Unknown key: {key!r}. Valid keys: {sorted(fields)}', err=True)
+        raise typer.Exit(code=1)
+
+    value = getattr(config, key)
+    render({key: value}, as_json=json_output)
+
+
+@config_app.command('set')
+def config_set(
+    key: Annotated[
+        str,
+        typer.Argument(help='Configuration key to update.'),
+    ],
+    value: Annotated[
+        str,
+        typer.Argument(help='New value for the key.'),
+    ],
+    *,
+    json_output: Annotated[
+        bool,
+        typer.Option('--json', help='Output as JSON.'),
+    ] = False,
+) -> None:
+    """Update a single configuration key."""
+    from synodic_client.operations.config import set_config
+
+    try:
+        updated = set_config(key, value)
+    except KeyError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+    render(updated, as_json=json_output)
+
+
+@config_app.command('list')
+def config_list(
+    *,
+    json_output: Annotated[
+        bool,
+        typer.Option('--json', help='Output as JSON.'),
+    ] = False,
+) -> None:
+    """List all configuration keys and their current values."""
+    from synodic_client.operations.config import list_config_keys
+
+    keys = list_config_keys()
+    if json_output:
+        render(keys, as_json=True)
+    else:
+        for name, info in keys.items():
+            typer.echo(f'{name} = {info.current_value!r}  ({info.type_hint})')
diff --git a/synodic_client/cli/context.py b/synodic_client/cli/context.py
new file mode 100644
index 0000000..1d641d2
--- /dev/null
+++ b/synodic_client/cli/context.py
@@ -0,0 +1,29 @@
+"""Service context for standalone CLI commands.
+
+Provides lazy initialisation of porringer ``API`` and ``Client`` so that
+data commands can run without Qt.  When a running GUI instance is
+detected, IPC is preferred for GUI-control commands.
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from porringer.api import API
+
+    from synodic_client.client import Client
+    from synodic_client.schema import ResolvedConfig
+
+
+@functools.cache
+def get_services() -> tuple[Client, API, ResolvedConfig]:
+    """Return ``(Client, API, ResolvedConfig)`` for standalone CLI usage.
+
+    The result is cached so subsequent calls in the same process reuse
+    the same instances.
+    """
+    from synodic_client.operations.bootstrap import init_services
+
+    return init_services()
diff --git a/synodic_client/cli/debug.py b/synodic_client/cli/debug.py
new file mode 100644
index 0000000..5ad3c40
--- /dev/null
+++ b/synodic_client/cli/debug.py
@@ -0,0 +1,85 @@
+"""Debug IPC commands for inspecting a running GUI instance.
+
+    synodic-c debug state
+    synodic-c debug actions
+    synodic-c debug action <name> [arg]
+
+These commands send commands over the local-socket IPC channel and
+require a running Synodic Client GUI instance.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+debug_app = typer.Typer(
+    help='Inspect and control the running Synodic Client instance.',
+    add_completion=False,
+)
+
+
+def _send_debug(command: str, *, dev: bool) -> None:
+    """Send a debug command to the running instance and print the response."""
+    from synodic_client.application.instance import SingleInstance
+    from synodic_client.config import set_dev_mode
+
+    set_dev_mode(dev)
+    response = SingleInstance.send_debug_command(command)
+
+    try:
+        data = json.loads(response)
+    except json.JSONDecodeError:
+        typer.echo(response)
+        raise typer.Exit(code=1) from None
+
+    typer.echo(json.dumps(data, indent=2))
+    if 'error' in data:
+        raise typer.Exit(code=1)
+
+
+@debug_app.command('state')
+def debug_state(
+    *,
+    dev: Annotated[
+        bool,
+        typer.Option('--dev', help='Target the dev-mode instance.'),
+    ] = False,
+) -> None:
+    """Dump the running application's domain state as JSON."""
+    _send_debug('state', dev=dev)
+
+
+@debug_app.command('actions')
+def debug_actions(
+    *,
+    dev: Annotated[
+        bool,
+        typer.Option('--dev', help='Target the dev-mode instance.'),
+    ] = False,
+) -> None:
+    """List available debug actions."""
+    _send_debug('actions', dev=dev)
+
+
+@debug_app.command('action')
+def debug_action(
+    name: Annotated[
+        str,
+        typer.Argument(help='The action to trigger (e.g. check_update, show_main).'),
+    ],
+    arg: Annotated[
+        str | None,
+        typer.Argument(help='Optional argument for the action (e.g. a project path).'),
+    ] = None,
+    *,
+    dev: Annotated[
+        bool,
+        typer.Option('--dev', help='Target the dev-mode instance.'),
+    ] = False,
+) -> None:
+    """Trigger a deterministic action on the running instance."""
+    command = f'action:{name}:{arg}' if arg else f'action:{name}'
+    _send_debug(command, dev=dev)
diff --git a/synodic_client/cli/output.py b/synodic_client/cli/output.py
new file mode 100644
index 0000000..c242e86
--- /dev/null
+++ b/synodic_client/cli/output.py
@@ -0,0 +1,60 @@
+"""Shared output formatting for CLI commands.
+
+Provides human-readable table output by default and machine-readable
+JSON when ``--json`` is requested.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Any
+
+import typer
+
+
+def render(data: Any, *, as_json: bool = False) -> None:
+    """Render *data* to stdout.
+
+    Args:
+        data: A dataclass, list of dataclasses, dict, or primitive.
+        as_json: If ``True``, emit JSON; otherwise human-readable text.
+    """
+    if as_json:
+        typer.echo(json.dumps(_serialise(data), indent=2))
+    elif isinstance(data, list):
+        for item in data:
+            _print_record(item)
+    elif dataclasses.is_dataclass(data) and not isinstance(data, type):
+        _print_record(data)
+    elif isinstance(data, dict):
+        for key, value in data.items():
+            typer.echo(f'{key}: {value}')
+    else:
+        typer.echo(str(data))
+
+
+def _serialise(obj: Any) -> Any:
+    """Recursively convert dataclass instances to dicts."""
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return dataclasses.asdict(obj)
+    if isinstance(obj, list):
+        return [_serialise(item) for item in obj]
+    if isinstance(obj, dict):
+        return {k: _serialise(v) for k, v in obj.items()}
+    return obj
+
+
+def _print_record(item: Any) -> None:
+    """Print a single record (dataclass or dict) as key: value lines."""
+    if dataclasses.is_dataclass(item) and not isinstance(item, type):
+        fields = dataclasses.asdict(item)
+    elif isinstance(item, dict):
+        fields = item
+    else:
+        typer.echo(str(item))
+        return
+
+    for key, value in fields.items():
+        typer.echo(f'  {key}: {value}')
+    typer.echo()
diff --git a/synodic_client/cli/project.py b/synodic_client/cli/project.py
new file mode 100644
index 0000000..3072ad7
--- /dev/null
+++ b/synodic_client/cli/project.py
@@ -0,0 +1,77 @@
+"""Project directory commands.
+
+synodic-c project list
+synodic-c project add <path>
+synodic-c project remove <path>
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from synodic_client.cli.output import render
+
+project_app = typer.Typer(
+    help='Manage cached project directories.',
+    add_completion=False,
+)
+
+
+@project_app.command('list')
+def project_list(
+    *,
+    json_output: Annotated[
+        bool,
+        typer.Option('--json', help='Output as JSON.'),
+    ] = False,
+) -> None:
+    """List all cached project directories."""
+    from synodic_client.cli.context import get_services
+    from synodic_client.operations.project import list_projects
+
+    _, porringer, _ = get_services()
+    projects = list_projects(porringer)
+    render(projects, as_json=json_output)
+
+
+@project_app.command('add')
+def project_add(
+    path: Annotated[
+        str,
+        typer.Argument(help='Filesystem path of the directory to add.'),
+    ],
+    *,
+    json_output: Annotated[
+        bool,
+        typer.Option('--json', help='Output as JSON.'),
+    ] = False,
+) -> None:
+    """Add a directory to the porringer project cache."""
+    from synodic_client.cli.context import get_services
+    from synodic_client.operations.project import add_project
+
+    _, porringer, _ = get_services()
+    try:
+        info = add_project(porringer, path)
+    except (NotADirectoryError, ValueError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+    render(info, as_json=json_output)
+
+
+@project_app.command('remove')
+def project_remove(
+    path: Annotated[
+        str,
+        typer.Argument(help='Filesystem path of the directory to remove.'),
+    ],
+) -> None:
+    """Remove a directory from the porringer project cache."""
+    from synodic_client.cli.context import get_services
+    from synodic_client.operations.project import remove_project
+
+    _, porringer, _ = get_services()
+    remove_project(porringer, path)
+    typer.echo(f'Removed: {path}')
diff --git a/synodic_client/cli/tool.py b/synodic_client/cli/tool.py
new file mode 100644
index 0000000..4daa052
--- /dev/null
+++ b/synodic_client/cli/tool.py
@@ -0,0 +1,93 @@
+"""Tool and package management commands.
+
+synodic-c tool check
+synodic-c tool update [plugin] [--package <name>]
+synodic-c tool remove <plugin> <package>
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+
+from synodic_client.cli.output import render
+
+tool_app = typer.Typer(
+    help='Inspect and manage installed tools and packages.',
+    add_completion=False,
+)
+
+
+@tool_app.command('check')
+def tool_check(
+    *,
+    json_output: Annotated[
+        bool,
+        typer.Option('--json', help='Output as JSON.'),
+    ] = False,
+) -> None:
+    """Check for available tool/package updates."""
+    from synodic_client.cli.context import get_services
+    from synodic_client.operations.tool import check_tool_updates
+
+    _, porringer, _ = get_services()
+    directories = porringer.cache.list_directories(validate=True, check_manifest=True)
+    manifest_dirs = [d.directory for d in directories if d.has_manifest]
+    available = asyncio.run(check_tool_updates(porringer, manifest_dirs))
+    render(available, as_json=json_output)
+
+
+@tool_app.command('update')
+def tool_update(
+    plugin: Annotated[
+        str,
+        typer.Argument(help='Installer plugin name to update.'),
+    ],
+    *,
+    package: Annotated[
+        str | None,
+        typer.Option('--package', help='Update a specific package only.'),
+    ] = None,
+    runtime_tag: Annotated[
+        str | None,
+        typer.Option('--runtime', help='Scope to a runtime tag.'),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option('--json', help='Output as JSON.'),
+    ] = False,
+) -> None:
+    """Update a tool plugin or a specific package within it."""
+    from synodic_client.cli.context import get_services
+    from synodic_client.operations.tool import update_tool as _update_tool
+
+    _, porringer, _ = get_services()
+    result = asyncio.run(_update_tool(porringer, plugin, package, runtime_tag=runtime_tag))
+    render(result, as_json=json_output)
+
+
+@tool_app.command('remove')
+def tool_remove(
+    plugin: Annotated[
+        str,
+        typer.Argument(help='Installer plugin name.'),
+    ],
+    package: Annotated[
+        str,
+        typer.Argument(help='Package name to remove.'),
+    ],
+    *,
+    json_output: Annotated[
+        bool,
+        typer.Option('--json', help='Output as JSON.'),
+    ] = False,
+) -> None:
+    """Remove a single installed package."""
+    from synodic_client.cli.context import get_services
+    from synodic_client.operations.tool import remove_package as _remove_package
+
+    _, porringer, _ = get_services()
+    success = asyncio.run(_remove_package(porringer, plugin, package))
+    render({'success': success, 'plugin': plugin, 'package': package}, as_json=json_output)
diff --git a/synodic_client/cli/update.py b/synodic_client/cli/update.py
new file mode 100644
index 0000000..6e0b615
--- /dev/null
+++ b/synodic_client/cli/update.py
@@ -0,0 +1,81 @@
+"""Self-update commands.
+
+synodic-c update check
+synodic-c update download
+synodic-c update apply
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+
+from synodic_client.cli.output import render
+
+update_app = typer.Typer(
+    help='Check, download, and apply synodic-client self-updates.',
+    add_completion=False,
+)
+
+
+@update_app.command('check')
+def update_check(
+    *,
+    json_output: Annotated[
+        bool,
+        typer.Option('--json', help='Output as JSON.'),
+    ] = False,
+) -> None:
+    """Check whether a newer version of synodic-client is available."""
+    from synodic_client.cli.context import get_services
+    from synodic_client.operations.update import check_self_update
+
+    client, _, _ = get_services()
+    result = asyncio.run(check_self_update(client))
+    render(result, as_json=json_output)
+
+
+@update_app.command('download')
+def update_download(
+    *,
+    json_output: Annotated[
+        bool,
+        typer.Option('--json', help='Output as JSON.'),
+    ] = False,
+) -> None:
+    """Download a self-update."""
+    from synodic_client.cli.context import get_services
+    from synodic_client.operations.update import download_self_update
+
+    client, _, _ = get_services()
+
+    def _progress(pct: int) -> None:
+        typer.echo(f'\rDownloading… {pct}%', nl=False)
+
+    result = asyncio.run(download_self_update(client, on_progress=None if json_output else _progress))
+    if not json_output:
+        typer.echo()  # newline after progress
+    render(result, as_json=json_output)
+
+
+@update_app.command('apply')
+def update_apply(
+    *,
+    no_restart: Annotated[
+        bool,
+        typer.Option('--no-restart', help='Apply without restarting.'),
+    ] = False,
+    silent: Annotated[
+        bool,
+        typer.Option('--silent', help='Suppress the Velopack splash window.'),
+    ] = False,
+) -> None:
+    """Apply a downloaded self-update."""
+    from synodic_client.cli.context import get_services
+    from synodic_client.operations.update import apply_self_update
+
+    client, _, _ = get_services()
+    apply_self_update(client, restart=not no_restart, silent=silent)
+    typer.echo('Update applied.')
diff --git a/synodic_client/logging.py b/synodic_client/logging.py
index 9492ecd..1e21f65 100644
--- a/synodic_client/logging.py
+++ b/synodic_client/logging.py
@@ -17,8 +17,6 @@
 _BACKUP_COUNT = 3
 _FORMAT = '%(asctime)s [%(levelname)s] %(name)s: %(message)s'
 
-_debug_active: bool = False
-
 
 def log_path() -> Path:
     """Return the path to the application log file.
@@ -103,8 +101,6 @@ def set_debug_level(*, enabled: bool) -> None:
     Args:
         enabled: ``True`` for DEBUG, ``False`` for INFO.
     """
-    global _debug_active  # noqa: PLW0603
-    _debug_active = enabled
     level = logging.DEBUG if enabled else logging.INFO
 
     app_logger = logging.getLogger('synodic_client')
@@ -112,3 +108,8 @@ def set_debug_level(*, enabled: bool) -> None:
     for h in app_logger.handlers:
         if isinstance(h, EagerRotatingFileHandler):
             h.setLevel(level)
+
+    # Also toggle porringer logger so resolution-level diagnostics
+    # (is_package_installed, _apply_strategy) appear in --debug output.
+    porringer_logger = logging.getLogger('porringer')
+    porringer_logger.setLevel(level)
diff --git a/synodic_client/operations/__init__.py b/synodic_client/operations/__init__.py
new file mode 100644
index 0000000..a82ee67
--- /dev/null
+++ b/synodic_client/operations/__init__.py
@@ -0,0 +1,84 @@
+"""Operations layer — pure functions for all user-facing actions.
+
+Every module in this package provides stateless functions that take
+explicit dependencies (porringer ``API``, ``Client``, config) as
+arguments and return typed result dataclasses.  No Qt imports, no
+signal emission, no implicit state.
+
+Modules:
+    schema      — Typed result dataclasses consumed by CLI and GUI.
+    project     — Project directory CRUD and status queries.
+    tool        — Tool/package listing, update checking, and upgrades.
+    install     — Manifest preview and execution.
+    config      — Configuration introspection and mutation.
+    update      — Self-update lifecycle (check, download, apply).
+    bootstrap   — Porringer API initialisation without Qt.
+"""
+
+from synodic_client.operations.bootstrap import init_services
+from synodic_client.operations.config import get_config, list_config_keys, set_config
+from synodic_client.operations.install import execute_install, preview_manifest
+from synodic_client.operations.project import add_project, list_projects, remove_project
+from synodic_client.operations.schema import (
+    ActionInfo,
+    ConfigKeyInfo,
+    DownloadResult,
+    PackageInfo,
+    PreviewResult,
+    ProjectInfo,
+    ProjectStatus,
+    ProviderInfo,
+    StatusSummary,
+    TagInfo,
+    ToolSection,
+    UpdateCheckResult,
+    UpdateResult,
+)
+from synodic_client.operations.tool import (
+    check_tool_updates,
+    remove_package,
+    resolve_auto_update_scope,
+    update_all_tools,
+    update_tool,
+)
+from synodic_client.operations.update import apply_self_update, check_self_update, download_self_update
+
+__all__ = [
+    # bootstrap
+    'init_services',
+    # config
+    'get_config',
+    'list_config_keys',
+    'set_config',
+    # install
+    'execute_install',
+    'preview_manifest',
+    # project
+    'add_project',
+    'list_projects',
+    'remove_project',
+    # schema
+    'ActionInfo',
+    'ConfigKeyInfo',
+    'DownloadResult',
+    'PackageInfo',
+    'PreviewResult',
+    'ProjectInfo',
+    'ProjectStatus',
+    'ProviderInfo',
+    'StatusSummary',
+    'TagInfo',
+    'ToolSection',
+    'UpdateCheckResult',
+    'UpdateResult',
+    # tool
+    'check_tool_updates',
+    'remove_package',
+    'resolve_auto_update_scope',
+    'update_all_tools',
+    'update_tool',
+    # update
+    'apply_self_update',
+    'check_self_update',
+    'download_self_update',
+]
diff --git a/synodic_client/operations/bootstrap.py b/synodic_client/operations/bootstrap.py
new file mode 100644
index 0000000..9061b47
--- /dev/null
+++ b/synodic_client/operations/bootstrap.py
@@ -0,0 +1,48 @@
+"""Porringer API initialisation without Qt.
+
+Extracts the service-creation logic from ``qt.py`` so that CLI commands
+and tests can obtain a configured ``(Client, API, ResolvedConfig)``
+tuple without importing PySide6 or qasync.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from porringer.api import API
+from porringer.schema import LocalConfiguration
+
+from synodic_client.client import Client
+from synodic_client.resolution import resolve_config, resolve_update_config
+from synodic_client.schema import ResolvedConfig
+
+logger = logging.getLogger(__name__)
+
+
+def init_services() -> tuple[Client, API, ResolvedConfig]:
+    """Create and configure core services without Qt.
+
+    Returns:
+        A ``(Client, porringer API, resolved config)`` tuple ready for
+        use by CLI commands or headless operations.
+    """
+    config = resolve_config()
+    client = Client()
+
+    local_config = LocalConfiguration()
+    porringer = API(local_config)
+
+    update_config = resolve_update_config(config)
+    client.initialize_updater(update_config)
+
+    cached_dirs = porringer.cache.list_directories()
+
+    logger.info(
+        'Synodic Client v%s started (channel: %s, source: %s, cached_projects: %d)',
+        client.version,
+        update_config.channel.name,
+        update_config.repo_url,
+        len(cached_dirs),
+    )
+
+    return client, porringer, config
diff --git a/synodic_client/operations/config.py b/synodic_client/operations/config.py
new file mode 100644
index 0000000..bac5699
--- /dev/null
+++ b/synodic_client/operations/config.py
@@ -0,0 +1,67 @@
+"""Configuration operations.
+
+Pure functions for reading, writing, and introspecting configuration.
+No Qt, no signals — works with the resolution module directly.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+from synodic_client.operations.schema import ConfigKeyInfo
+from synodic_client.resolution import resolve_config, update_user_config
+from synodic_client.schema import ResolvedConfig
+
+
+def get_config() -> ResolvedConfig:
+    """Load and return the current resolved configuration.
+
+    Returns:
+        An immutable :class:`ResolvedConfig` snapshot.
+    """
+    return resolve_config()
+
+
+def set_config(key: str, value: object) -> ResolvedConfig:
+    """Update a single configuration key and return the new config.
+
+    Args:
+        key: The :class:`UserConfig` field name.
+        value: The new value.
+
+    Returns:
+        The updated :class:`ResolvedConfig`.
+
+    Raises:
+        KeyError: If *key* is not a recognised config field.
+    """
+    valid_keys = {f.name for f in dataclasses.fields(ResolvedConfig)}
+    if key not in valid_keys:
+        msg = f'Unknown config key: {key!r}. Valid keys: {sorted(valid_keys)}'
+        raise KeyError(msg)
+
+    return update_user_config(**{key: value})
+
+
+def list_config_keys(config: ResolvedConfig | None = None) -> dict[str, ConfigKeyInfo]:
+    """Return metadata for every configuration key.
+
+    Args:
+        config: Optional resolved config to read current values from.
+            If ``None``, a fresh config is loaded.
+
+    Returns:
+        A dict mapping field name → :class:`ConfigKeyInfo`.
+    """
+    if config is None:
+        config = resolve_config()
+
+    result: dict[str, ConfigKeyInfo] = {}
+    for f in dataclasses.fields(ResolvedConfig):
+        result[f.name] = ConfigKeyInfo(
+            name=f.name,
+            type_hint=str(f.type),
+            description='',
+            current_value=getattr(config, f.name),
+        )
+    return result
diff --git a/synodic_client/operations/install.py b/synodic_client/operations/install.py
new file mode 100644
index 0000000..9924da0
--- /dev/null
+++ b/synodic_client/operations/install.py
@@ -0,0 +1,150 @@
+"""Install / preview operations.
+
+Pure async functions for previewing and executing manifest installs.
+No Qt, no signals — progress is reported via optional async callbacks.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from porringer.schema import (
+    ActionCompletedEvent,
+    ActionStartedEvent,
+    ManifestLoadedEvent,
+    ManifestParsedEvent,
+    ProgressEvent,
+    SetupParameters,
+    SubActionProgressEvent,
+    SyncStrategy,
+)
+
+from synodic_client.operations.schema import ActionInfo, PreviewResult
+
+if TYPE_CHECKING:
+    from porringer.api import API
+    from porringer.backend.command.core.discovery import DiscoveredPlugins
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Preview
+# ---------------------------------------------------------------------------
+
+
+async def preview_manifest(
+    porringer: API,
+    url: str,
+    *,
+    project_directory: Path | None = None,
+    prerelease_packages: set[str] | None = None,
+    discovered: DiscoveredPlugins | None = None,
+) -> PreviewResult:
+    """Perform a dry-run preview of a manifest.
+
+    Downloads the manifest if *url* is remote, then runs
+    ``execute_stream`` with ``dry_run=True`` to resolve actions.
+
+    Args:
+        porringer: The porringer API instance.
+        url: Manifest URL or local path.
+        project_directory: Optional project directory for the preview.
+        prerelease_packages: Optional prerelease overrides.
+        discovered: Pre-discovered plugins.
+
+    Returns:
+        A :class:`PreviewResult` with the resolved actions.
+    """
+    params = SetupParameters(
+        paths=[url],
+        dry_run=True,
+        project_directory=project_directory,
+        prerelease_packages=prerelease_packages,
+    )
+
+    actions: list[ActionInfo] = []
+    project_name = ''
+    description = ''
+    manifest_key = url
+
+    async for event in porringer.sync.execute_stream(params, plugins=discovered):
+        if isinstance(event, ManifestParsedEvent):
+            meta = event.manifest.metadata
+            if meta:
+                project_name = meta.name or ''
+                description = meta.description or ''
+            manifest_key = str(event.manifest.manifest_path or url)
+
+        elif isinstance(event, ManifestLoadedEvent):
+            for act in event.manifest.actions:
+                actions.append(
+                    ActionInfo(
+                        description=act.description,
+                        kind=act.kind.name if act.kind else None,
+                        package=str(act.package.name) if act.package else None,
+                        constraint=act.package.constraint if act.package else None,
+                        installer=act.installer,
+                    )
+                )
+
+    return PreviewResult(
+        manifest_key=manifest_key,
+        project_name=project_name,
+        description=description,
+        actions=actions,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Execute install
+# ---------------------------------------------------------------------------
+
+
+async def execute_install(
+    porringer: API,
+    manifest_path: Path,
+    *,
+    project_directory: Path | None = None,
+    strategy: SyncStrategy = SyncStrategy.MINIMAL,
+    prerelease_packages: set[str] | None = None,
+    discovered: DiscoveredPlugins | None = None,
+) -> AsyncIterator[tuple[str, ProgressEvent]]:
+    """Execute setup actions and yield ``(stage, event)`` tuples.
+
+    Yields ``("action_started", event)``, ``("sub_progress", event)``,
+    ``("action_completed", event)``, etc. so callers can wire up
+    progress tracking without coupling to porringer event kinds.
+
+    Args:
+        porringer: The porringer API instance.
+        manifest_path: Path to the manifest file to execute.
+        project_directory: Optional project directory scope.
+        strategy: Sync strategy (MINIMAL or LATEST).
+        prerelease_packages: Optional prerelease overrides.
+        discovered: Pre-discovered plugins.
+
+    Yields:
+        ``(stage_name, event)`` tuples for progress tracking.
+    """
+    params = SetupParameters(
+        paths=[manifest_path],
+        project_directory=project_directory,
+        strategy=strategy,
+        prerelease_packages=prerelease_packages,
+    )
+
+    async for event in porringer.sync.execute_stream(params, plugins=discovered):
+        if isinstance(event, ManifestLoadedEvent):
+            yield ('manifest_loaded', event)
+        elif isinstance(event, ActionStartedEvent):
+            yield ('action_started', event)
+        elif isinstance(event, SubActionProgressEvent):
+            yield ('sub_progress', event)
+        elif isinstance(event, ActionCompletedEvent):
+            yield ('action_completed', event)
+        else:
+            yield ('other', event)
diff --git a/synodic_client/operations/project.py b/synodic_client/operations/project.py
new file mode 100644
index 0000000..36885fb
--- /dev/null
+++ b/synodic_client/operations/project.py
@@ -0,0 +1,87 @@
+"""Project directory operations.
+
+Pure functions for listing, adding, removing, and querying status of
+cached project directories.  No Qt, no signals — just porringer API
+calls in → typed results out.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from synodic_client.operations.schema import ProjectInfo
+
+if TYPE_CHECKING:
+    from porringer.api import API
+
+
+def list_projects(porringer: API) -> list[ProjectInfo]:
+    """List all cached project directories with validation status.
+
+    Args:
+        porringer: The porringer API instance.
+
+    Returns:
+        A list of :class:`ProjectInfo` for every cached directory.
+    """
+    results = porringer.cache.list_directories(validate=True, check_manifest=True)
+    return [
+        ProjectInfo(
+            path=str(r.directory.path),
+            name=r.directory.name or '',
+            exists=r.exists or False,
+            has_manifest=r.has_manifest or False,
+        )
+        for r in results
+    ]
+
+
+def add_project(porringer: API, path: str | Path) -> ProjectInfo:
+    """Add a directory to the porringer project cache.
+
+    Args:
+        porringer: The porringer API instance.
+        path: Filesystem path to add.
+
+    Returns:
+        A :class:`ProjectInfo` for the newly added directory.
+
+    Raises:
+        NotADirectoryError: If *path* is not an existing directory.
+        ValueError: If porringer rejects the directory (e.g. duplicate).
+    """
+    directory = Path(path)
+    if not directory.is_dir():
+        msg = f'Not a directory: {directory}'
+        raise NotADirectoryError(msg)
+
+    porringer.cache.add_directory(directory)
+
+    # Re-query to get validation status for the returned info.
+    for r in porringer.cache.list_directories(validate=True, check_manifest=True):
+        if Path(r.directory.path) == directory:
+            return ProjectInfo(
+                path=str(r.directory.path),
+                name=r.directory.name or '',
+                exists=r.exists or False,
+                has_manifest=r.has_manifest or False,
+            )
+
+    # Shouldn't happen, but satisfy the return type.
+    return ProjectInfo(
+        path=str(directory),
+        name=directory.stem,
+        exists=directory.exists(),
+        has_manifest=False,
+    )
+
+
+def remove_project(porringer: API, path: str | Path) -> None:
+    """Remove a directory from the porringer project cache.
+
+    Args:
+        porringer: The porringer API instance.
+        path: Filesystem path to remove.
+    """
+    porringer.cache.remove_directory(Path(path))
diff --git a/synodic_client/operations/schema.py b/synodic_client/operations/schema.py
new file mode 100644
index 0000000..3a97b61
--- /dev/null
+++ b/synodic_client/operations/schema.py
@@ -0,0 +1,180 @@
+"""Typed result dataclasses for the operations layer.
+
+Every operation function returns one of these dataclasses.  They are
+plain frozen (where practical) dataclasses with no Qt, no I/O, and no
+porringer imports so that CLI, GUI, and tests can all consume them
+without extra dependencies.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# ---------------------------------------------------------------------------
+# Project operations
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectInfo:
+    """Summary of a single cached project directory."""
+
+    path: str
+    """Filesystem path of the directory."""
+
+    name: str
+    """Human-readable label (usually the directory stem)."""
+
+    exists: bool
+    """Whether the directory still exists on disk."""
+
+    has_manifest: bool
+    """Whether the directory contains a recognised manifest file."""
+
+
+@dataclass(frozen=True, slots=True)
+class ActionInfo:
+    """One action from a project manifest preview."""
+
+    description: str
+    kind: str | None = None
+    status: str = ''
+    package: str | None = None
+    constraint: str | None = None
+    installer: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class StatusSummary:
+    """Aggregate counts for a project status preview."""
+
+    needed: int = 0
+    satisfied: int = 0
+    pending: int = 0
+    upgradable: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectStatus:
+    """Full status preview for a single project directory."""
+
+    path: str
+    phase: str
+    action_count: int = 0
+    checked_count: int = 0
+    actions: list[ActionInfo] = field(default_factory=list)
+    summary: StatusSummary = field(default_factory=StatusSummary)
+
+
+# ---------------------------------------------------------------------------
+# Tool / package operations
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class TagInfo:
+    """A project-scoped occurrence tag for a package."""
+
+    project_path: str
+    is_transitive: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class PackageInfo:
+    """Display-ready info about a single installed package."""
+
+    name: str
+    version: str = ''
+    has_update: bool = False
+    update_version: str | None = None
+    timestamp: str | None = None
+    tags: list[TagInfo] = field(default_factory=list)
+    is_global: bool = False
+    auto_update: bool = False
+    host_tool: str = ''
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderInfo:
+    """A single plugin provider (installer) with its packages."""
+
+    plugin_name: str
+    plugin_version: str | None = None
+    installed: bool = True
+    kind: str = ''
+    runtime_tag: str | None = None
+    packages: list[PackageInfo] = field(default_factory=list)
+    has_updates: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ToolSection:
+    """A section grouping providers by plugin kind (e.g. Tool, Package)."""
+
+    kind: str
+    providers: list[ProviderInfo] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class UpdateResult:
+    """Summary of a tool/package update run."""
+
+    plugin: str = ''
+    packages_updated: list[str] = field(default_factory=list)
+    packages_failed: list[str] = field(default_factory=list)
+    already_latest: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Install operations
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class PreviewResult:
+    """Result of a manifest preview (dry-run)."""
+
+    manifest_key: str = ''
+    project_name: str = ''
+    description: str = ''
+    actions: list[ActionInfo] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Self-update operations
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class UpdateCheckResult:
+    """Result of a self-update availability check."""
+
+    available: bool
+    current_version: str = ''
+    version: str | None = None
+    channel: str | None = None
+    error: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DownloadResult:
+    """Result of a self-update download."""
+
+    success: bool
+    version: str = ''
+    error: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Config operations
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigKeyInfo:
+    """Metadata about a single configuration key."""
+
+    name: str
+    type_hint: str = ''
+    description: str = ''
+    current_value: object = None
diff --git a/synodic_client/operations/tool.py b/synodic_client/operations/tool.py
new file mode 100644
index 0000000..4d607ed
--- /dev/null
+++ b/synodic_client/operations/tool.py
@@ -0,0 +1,388 @@
+"""Tool and package listing/update operations.
+
+Pure async functions for listing installed tools, checking for updates,
+and running updates.  Policy logic (auto-update scope, manifest-aware
+defaults) lives here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from porringer.core.schema import PackageRef
+from porringer.schema import (
+    ActionCompletedEvent,
+    SetupParameters,
+    SkipReason,
+    SyncStrategy,
+)
+
+from synodic_client.operations.schema import UpdateResult
+
+if TYPE_CHECKING:
+    from porringer.api import API
+    from porringer.backend.command.core.discovery import DiscoveredPlugins
+    from porringer.schema import ManifestDirectory
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Update-check
+# ---------------------------------------------------------------------------
+
+
+async def check_tool_updates(
+    porringer: API,
+    directories: list[ManifestDirectory],
+    discovered: DiscoveredPlugins | None = None,
+) -> dict[str, dict[str, str]]:
+    """Detect available updates across cached manifests.
+
+    Returns ``{plugin_name: {package_name: latest_version}}`` for
+    packages that have a newer version available.
+
+    Args:
+        porringer: The porringer API instance.
+        directories: Cached project directories to scan.
+        discovered: Pre-discovered plugins to avoid redundant discovery.
+    """
+    available: dict[str, dict[str, str]] = {}
+
+    async def _check_one(directory: ManifestDirectory) -> None:
+        try:
+            path = Path(directory.path)
+            filenames = porringer.sync.manifest_filenames()
+            manifest_path: Path | None = None
+            for fname in filenames:
+                candidate = path / fname
+                if candidate.exists():
+                    manifest_path = candidate
+                    break
+
+            if manifest_path is None:
+                return
+
+            params = SetupParameters(
+                paths=[str(manifest_path)],
+                dry_run=True,
+                project_directory=path,
+            )
+            async for event in porringer.sync.execute_stream(params, plugins=discovered):
+                if isinstance(event, ActionCompletedEvent) and event.result.skip_reason == SkipReason.UPDATE_AVAILABLE:
+                    action = event.result.action
+                    if action.installer and action.package:
+                        pkg_name = str(action.package.name)
+                        latest = event.result.available_version or ''
+                        available.setdefault(action.installer, {})[pkg_name] = latest
+        except Exception:
+            logger.debug('Could not detect updates for %s', directory.path, exc_info=True)
+
+    async with asyncio.TaskGroup() as tg:
+        for d in directories:
+            tg.create_task(_check_one(d))
+
+    return available
+
+
+# ---------------------------------------------------------------------------
+# Update execution
+# ---------------------------------------------------------------------------
+
+
+async def update_tool(
+    porringer: API,
+    plugin_name: str,
+    package_name: str | None = None,
+    *,
+    runtime_tag: str | None = None,
+    discovered: DiscoveredPlugins | None = None,
+) -> UpdateResult:
+    """Upgrade a single plugin or a specific package within it.
+
+    When *package_name* is ``None`` the entire plugin is updated by
+    re-syncing cached manifests for that plugin only.  When a
+    *runtime_tag* is provided, the upgrade is scoped to that runtime.
+
+    Args:
+        porringer: The porringer API instance.
+        plugin_name: The installer plugin name.
+        package_name: Optional specific package to upgrade.
+        runtime_tag: Optional runtime tag for per-runtime updates.
+        discovered: Pre-discovered plugins.
+
+    Returns:
+        An :class:`UpdateResult` summarising the operation.
+    """
+    result = UpdateResult(plugin=plugin_name)
+
+    if package_name is not None:
+        # Single-package upgrade
+        ref = PackageRef(name=package_name)
+        action_result = await porringer.package.upgrade(
+            plugin_name,
+            ref,
+            runtime_tag=runtime_tag,
+            plugins=discovered,
+        )
+        if action_result.skipped:
+            result.already_latest.append(package_name)
+        elif action_result.success:
+            result.packages_updated.append(package_name)
+        else:
+            result.packages_failed.append(package_name)
+        return result
+
+    # Full-plugin update: re-sync all cached manifests for this plugin.
+    if runtime_tag is not None:
+        return await _update_runtime_plugin(
+            porringer,
+            plugin_name,
+            runtime_tag,
+            discovered=discovered,
+        )
+
+    return await _update_plugin_via_manifests(
+        porringer,
+        plugin_name,
+        discovered=discovered,
+    )
+
+
+async def _update_plugin_via_manifests(
+    porringer: API,
+    plugin_name: str,
+    *,
+    discovered: DiscoveredPlugins | None = None,
+) -> UpdateResult:
+    """Re-sync cached manifests scoped to a single plugin."""
+    result = UpdateResult(plugin=plugin_name)
+    loop = asyncio.get_running_loop()
+    dir_results = await loop.run_in_executor(
+        None,
+        lambda: porringer.cache.list_directories(validate=True, check_manifest=True),
+    )
+
+    for dr in dir_results:
+        if not dr.has_manifest:
+            continue
+        path = Path(dr.directory.path)
+        params = SetupParameters(
+            paths=[path],
+            project_directory=path if path.is_dir() else None,
+            strategy=SyncStrategy.LATEST,
+            plugins={plugin_name},
+        )
+        try:
+            async for event in porringer.sync.execute_stream(params, plugins=discovered):
+                if not isinstance(event, ActionCompletedEvent):
+                    continue
+                ar = event.result
+                pkg_name = str(ar.action.package.name) if ar.action.package else ''
+                if ar.skipped:
+                    if ar.skip_reason in {SkipReason.ALREADY_LATEST, SkipReason.ALREADY_INSTALLED}:
+                        result.already_latest.append(pkg_name)
+                elif ar.success:
+                    result.packages_updated.append(pkg_name)
+                else:
+                    result.packages_failed.append(pkg_name)
+        except asyncio.CancelledError:
+            raise
+    return result
+
+
+async def _update_runtime_plugin(
+    porringer: API,
+    plugin_name: str,
+    runtime_tag: str,
+    *,
+    include_packages: set[str] | None = None,
+    discovered: DiscoveredPlugins | None = None,
+) -> UpdateResult:
+    """Upgrade packages for a plugin scoped to a specific runtime."""
+    result = UpdateResult(plugin=plugin_name)
+    packages = await porringer.package.list_by_runtime(plugin_name, plugins=discovered)
+    if packages is None:
+        return result
+    for rt in packages:
+        if rt.tag != runtime_tag:
+            continue
+        for pkg in rt.packages:
+            pkg_name = str(pkg.name)
+            if include_packages is not None and pkg_name not in include_packages:
+                continue
+            ref = PackageRef(name=pkg_name)
+            ar = await porringer.package.upgrade(
+                plugin_name,
+                ref,
+                runtime_tag=runtime_tag,
+                plugins=discovered,
+            )
+            if ar.skipped:
+                result.already_latest.append(pkg_name)
+            elif ar.success:
+                result.packages_updated.append(pkg_name)
+            else:
+                result.packages_failed.append(pkg_name)
+        break
+    return result
+
+
+async def remove_package(
+    porringer: API,
+    plugin_name: str,
+    package_name: str,
+    *,
+    discovered: DiscoveredPlugins | None = None,
+) -> bool:
+    """Uninstall a single package.
+
+    Args:
+        porringer: The porringer API instance.
+        plugin_name: The installer plugin name.
+        package_name: The package to remove.
+        discovered: Pre-discovered plugins.
+
+    Returns:
+        ``True`` if the removal succeeded.
+    """
+    ref = PackageRef(name=package_name)
+    action_result = await porringer.package.uninstall(plugin_name, ref, plugins=discovered)
+    return action_result.success
+
+
+async def update_all_tools(
+    porringer: API,
+    plugins: set[str] | None = None,
+    include_packages: set[str] | None = None,
+    *,
+    discovered: DiscoveredPlugins | None = None,
+) -> UpdateResult:
+    """Re-sync all cached project manifests (bulk update).
+
+    Args:
+        porringer: The porringer API instance.
+        plugins: Optional include-set of plugin names.
+        include_packages: Optional include-set of package names.
+        discovered: Pre-discovered plugins.
+
+    Returns:
+        An :class:`UpdateResult` summarising the full run.
+    """
+    result = UpdateResult(plugin='*')
+    loop = asyncio.get_running_loop()
+    dir_results = await loop.run_in_executor(
+        None,
+        lambda: porringer.cache.list_directories(validate=True, check_manifest=True),
+    )
+
+    for dr in dir_results:
+        if not dr.has_manifest:
+            continue
+        path = Path(dr.directory.path)
+        params = SetupParameters(
+            paths=[path],
+            project_directory=path if path.is_dir() else None,
+            strategy=SyncStrategy.LATEST,
+            plugins=plugins,
+            include_packages=include_packages,
+        )
+        try:
+            async for event in porringer.sync.execute_stream(params, plugins=discovered):
+                if not isinstance(event, ActionCompletedEvent):
+                    continue
+                ar = event.result
+                pkg_name = str(ar.action.package.name) if ar.action.package else ''
+                if ar.skipped:
+                    if ar.skip_reason in {SkipReason.ALREADY_LATEST, SkipReason.ALREADY_INSTALLED}:
+                        result.already_latest.append(pkg_name)
+                elif ar.success:
+                    result.packages_updated.append(pkg_name)
+                else:
+                    result.packages_failed.append(pkg_name)
+        except asyncio.CancelledError:
+            raise
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Auto-update scope policy
+# ---------------------------------------------------------------------------
+
+
+def resolve_auto_update_scope(
+    plugin_auto_update: dict[str, bool | dict[str, bool]] | None,
+    all_plugin_names: list[str],
+    manifest_packages: dict[str, set[str]] | None = None,
+) -> tuple[set[str] | None, set[str] | None]:
+    """Derive plugin and package include-lists for auto-update.
+
+    Walks ``plugin_auto_update`` to determine which plugins and packages
+    should participate in automatic updates.
+
+    Args:
+        plugin_auto_update: The per-plugin auto-update config mapping.
+        all_plugin_names: Every known (installed) plugin name.
+        manifest_packages: Mapping of ``plugin_name`` → set of package
+            names declared in cached manifests.
+
+    Returns:
+        A ``(enabled_plugins, include_packages)`` tuple.  Either element
+        may be ``None`` meaning "no filtering".
+    """
+    mapping = plugin_auto_update
+
+    disabled_plugins: set[str] = set()
+    per_package_entries: dict[str, dict[str, bool]] = {}
+
+    if mapping:
+        for name, value in mapping.items():
+            if ':' in name:
+                continue
+            if value is False:
+                disabled_plugins.add(name)
+            elif isinstance(value, dict):
+                per_package_entries[name] = value
+
+    enabled_plugins: set[str] | None = None
+    if disabled_plugins:
+        enabled_plugins = {n for n in all_plugin_names if n not in disabled_plugins}
+
+    include_packages = _build_include_packages(
+        per_package_entries,
+        manifest_packages,
+        disabled_plugins,
+    )
+
+    return enabled_plugins, include_packages
+
+
+def _build_include_packages(
+    per_package_entries: dict[str, dict[str, bool]],
+    manifest_packages: dict[str, set[str]] | None,
+    disabled_plugins: set[str],
+) -> set[str] | None:
+    """Build the set of package names eligible for auto-update."""
+    if not per_package_entries and not manifest_packages:
+        return None
+
+    pkg_set: set[str] = set()
+    if manifest_packages:
+        for plugin_name, pkgs in manifest_packages.items():
+            if plugin_name not in disabled_plugins:
+                pkg_set |= pkgs
+
+    for plugin_name, pkg_map in per_package_entries.items():
+        if plugin_name in disabled_plugins:
+            continue
+        for pkg_name, enabled in pkg_map.items():
+            if enabled:
+                pkg_set.add(pkg_name)
+            else:
+                pkg_set.discard(pkg_name)
+
+    return pkg_set or None
diff --git a/synodic_client/operations/update.py b/synodic_client/operations/update.py
new file mode 100644
index 0000000..0f89e52
--- /dev/null
+++ b/synodic_client/operations/update.py
@@ -0,0 +1,104 @@
+"""Self-update operations.
+
+Pure functions for checking, downloading, and applying synodic-client
+self-updates.  No Qt, no signals — the controller layer handles UI
+concerns.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from synodic_client.operations.schema import DownloadResult, UpdateCheckResult
+
+if TYPE_CHECKING:
+    from synodic_client.client import Client
+
+logger = logging.getLogger(__name__)
+
+
+async def check_self_update(client: Client) -> UpdateCheckResult:
+    """Check whether a newer version of synodic-client is available.
+
+    Runs the blocking Velopack check in a thread-pool executor.
+
+    Args:
+        client: The Synodic Client service facade.
+
+    Returns:
+        An :class:`UpdateCheckResult` describing availability.
+    """
+    loop = asyncio.get_running_loop()
+    try:
+        result = await loop.run_in_executor(None, client.check_for_update)
+    except asyncio.CancelledError:
+        logger.debug('check_self_update cancelled')
+        raise
+
+    if result is None:
+        return UpdateCheckResult(
+            available=False,
+            current_version=str(client.version),
+            error='Updater is not initialized.',
+        )
+
+    if result.error:
+        return UpdateCheckResult(
+            available=False,
+            current_version=str(result.current_version),
+            error=result.error,
+        )
+
+    return UpdateCheckResult(
+        available=result.available,
+        current_version=str(result.current_version),
+        version=str(result.latest_version) if result.latest_version else None,
+    )
+
+
+async def download_self_update(
+    client: Client,
+    on_progress: Callable[[int], None] | None = None,
+) -> DownloadResult:
+    """Download a self-update, reporting progress via *on_progress*.
+
+    Args:
+        client: The Synodic Client service facade.
+        on_progress: Optional callback for percentage progress (0–100).
+
+    Returns:
+        A :class:`DownloadResult` describing success/failure.
+    """
+    loop = asyncio.get_running_loop()
+
+    def _run() -> bool:
+        def _progress(percentage: int) -> None:
+            if on_progress is not None:
+                loop.call_soon_threadsafe(on_progress, percentage)
+
+        return client.download_update(_progress)
+
+    try:
+        success = await loop.run_in_executor(None, _run)
+    except asyncio.CancelledError:
+        logger.debug('download_self_update cancelled')
+        raise
+
+    version = str(client.version)
+    if success:
+        return DownloadResult(success=True, version=version)
+    return DownloadResult(success=False, version=version, error='Download failed.')
+
+
+def apply_self_update(client: Client, *, restart: bool = True, silent: bool = False) -> None:
+    """Schedule the downloaded update to apply on exit.
+
+    Args:
+        client: The Synodic Client service facade.
+        restart: Whether to restart after applying.
+        silent: Whether to suppress the Velopack splash window.
+    """
+    client.apply_update_on_exit(restart=restart, silent=silent)
diff --git a/synodic_client/protocol.py b/synodic_client/protocol.py
index 04f25e8..3405713 100644
--- a/synodic_client/protocol.py
+++ b/synodic_client/protocol.py
@@ -42,7 +42,7 @@ def register_protocol(exe_path: str) -> None:
 
             command_path = f'{key_path}\\shell\\open\\command'
             with winreg.CreateKey(winreg.HKEY_CURRENT_USER, command_path) as key:
-                winreg.SetValueEx(key, '', 0, winreg.REG_SZ, f'"{exe_path}" "%1"')
+                winreg.SetValueEx(key, '', 0, winreg.REG_SZ, f'"{exe_path}" --uri "%1"')
 
             logger.info('Registered synodic:// protocol handler -> %s', exe_path)
         except OSError:
diff --git a/synodic_client/schema.py b/synodic_client/schema.py
index 2cb1354..64fc8c6 100644
--- a/synodic_client/schema.py
+++ b/synodic_client/schema.py
@@ -184,7 +184,7 @@ class UpdateConfig:
     """Configuration for the updater."""
 
     # GitHub repository URL for Velopack to discover releases
-    repo_url: str = 'https://github.com/synodic/synodic-client'
+    repo_url: str = GITHUB_REPO_URL
 
     # Channel determines whether to use dev or stable releases
     channel: UpdateChannel = UpdateChannel.STABLE
diff --git a/synodic_client/subprocess_patch.py b/synodic_client/subprocess_patch.py
index 19f888b..6de7815 100644
--- a/synodic_client/subprocess_patch.py
+++ b/synodic_client/subprocess_patch.py
@@ -30,15 +30,14 @@
 import sys
 from typing import Any
 
-_applied = False
+_applied: list[bool] = []
 
 
 def apply() -> None:
     """Activate the subprocess-suppression patch (idempotent, Windows-only)."""
-    global _applied  # noqa: PLW0603
     if _applied or sys.platform != 'win32':
         return
-    _applied = True
+    _applied.append(True)
 
     _patch_popen()
 
diff --git a/tests/unit/operations/__init__.py b/tests/unit/operations/__init__.py
new file mode 100644
index 0000000..8e05a8a
--- /dev/null
+++ b/tests/unit/operations/__init__.py
@@ -0,0 +1 @@
+"""Operations test package."""
diff --git a/tests/unit/operations/test_config.py b/tests/unit/operations/test_config.py
new file mode 100644
index 0000000..3f614e1
--- /dev/null
+++ b/tests/unit/operations/test_config.py
@@ -0,0 +1,77 @@
+"""Tests for operations.config module."""
+
+import dataclasses
+from unittest.mock import patch
+
+import pytest
+
+from synodic_client.operations.config import get_config, list_config_keys, set_config
+from synodic_client.operations.schema import ConfigKeyInfo
+
+
+class TestGetConfig:
+    """Tests for get_config()."""
+
+    @staticmethod
+    def test_returns_resolved_config() -> None:
+        """get_config returns the result of resolve_config()."""
+        with patch('synodic_client.operations.config.resolve_config') as mock:
+            sentinel = object()
+            mock.return_value = sentinel
+            assert get_config() is sentinel
+
+
+class TestSetConfig:
+    """Tests for set_config()."""
+
+    @staticmethod
+    def test_unknown_key_raises() -> None:
+        """Raises KeyError for an invalid config key."""
+        with pytest.raises(KeyError, match='Unknown config key'):
+            set_config('nonexistent_key_xyz', 'value')
+
+    @staticmethod
+    def test_delegates_to_update_user_config() -> None:
+        """Calls update_user_config with the correct kwargs."""
+        with patch('synodic_client.operations.config.update_user_config') as mock:
+            mock_config = object()
+            mock.return_value = mock_config
+            # Use a known field from ResolvedConfig
+            from synodic_client.schema import ResolvedConfig
+
+            field_names = [f.name for f in dataclasses.fields(ResolvedConfig)]
+            if field_names:
+                key = field_names[0]
+                result = set_config(key, 'test_value')
+                mock.assert_called_once_with(**{key: 'test_value'})
+                assert result is mock_config
+
+
+class TestListConfigKeys:
+    """Tests for list_config_keys()."""
+
+    @staticmethod
+    def test_returns_all_fields() -> None:
+        """Returns a ConfigKeyInfo entry for each ResolvedConfig field."""
+        from synodic_client.schema import ResolvedConfig
+
+        with patch('synodic_client.operations.config.resolve_config') as mock:
+            mock.return_value = ResolvedConfig(
+                update_source=None,
+                update_channel='stable',
+                auto_update_interval_minutes=60,
+                tool_update_interval_minutes=60,
+                plugin_auto_update=None,
+                prerelease_packages=None,
+                auto_apply=False,
+                auto_start=False,
+                debug_logging=False,
+                last_client_update=None,
+                last_tool_updates=None,
+            )
+            # Override: use a fresh resolve to build the keys dict
+            keys = list_config_keys()
+            expected_fields = {f.name for f in dataclasses.fields(ResolvedConfig)}
+            assert set(keys.keys()) == expected_fields
+            for info in keys.values():
+                assert isinstance(info, ConfigKeyInfo)
diff --git a/tests/unit/operations/test_install.py b/tests/unit/operations/test_install.py
new file mode 100644
index 0000000..57aee24
--- /dev/null
+++ b/tests/unit/operations/test_install.py
@@ -0,0 +1,221 @@
+"""Tests for operations.install module."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from unittest.mock import MagicMock
+
+from porringer.schema import ProgressEvent, SetupParameters
+
+from synodic_client.operations.install import execute_install, preview_manifest
+from synodic_client.operations.schema import ActionInfo, PreviewResult
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_manifest_parsed_event(*, name: str = '', description: str = '', manifest_path: str = '') -> MagicMock:
+    """Build a mock ManifestParsedEvent."""
+    from porringer.schema import ManifestMetadata, ManifestParsedEvent
+
+    event = MagicMock(spec=ManifestParsedEvent)
+    event.manifest.metadata = ManifestMetadata(name=name, description=description)
+    event.manifest.manifest_path = manifest_path or None
+    return event
+
+
+def _make_manifest_loaded_event(actions: list[MagicMock] | None = None) -> MagicMock:
+    """Build a mock ManifestLoadedEvent."""
+    from porringer.schema import ManifestLoadedEvent
+
+    event = MagicMock(spec=ManifestLoadedEvent)
+    event.manifest.actions = actions or []
+    return event
+
+
+def _make_action(
+    *,
+    description: str = '',
+    kind_name: str | None = None,
+    package_name: str | None = None,
+    constraint: str | None = None,
+    installer: str | None = None,
+) -> MagicMock:
+    """Build a mock manifest action."""
+    action = MagicMock()
+    action.description = description
+    action.kind.name = kind_name
+    if kind_name is None:
+        action.kind = None
+    action.installer = installer
+    if package_name is not None:
+        action.package.name = package_name
+        action.package.constraint = constraint
+    else:
+        action.package = None
+    return action
+
+
+# ---------------------------------------------------------------------------
+# preview_manifest
+# ---------------------------------------------------------------------------
+
+
+class TestPreviewManifest:
+    """Tests for preview_manifest()."""
+
+    @staticmethod
+    def test_empty_stream() -> None:
+        """No events → empty PreviewResult."""
+        api = MagicMock()
+
+        async def _empty_stream(*_a: object, **_kw: object):
+            return
+            yield  # make it an async generator
+
+        api.sync.execute_stream = _empty_stream
+
+        result = asyncio.run(preview_manifest(api, 'https://example.com/manifest.json'))
+        assert isinstance(result, PreviewResult)
+        assert result.actions == []
+        assert not result.project_name
+
+    @staticmethod
+    def test_parses_metadata_and_actions() -> None:
+        """Extracts project name, description, and actions from events."""
+        parsed_event = _make_manifest_parsed_event(
+            name='My Project',
+            description='A test project',
+            manifest_path='/tmp/manifest.json',
+        )
+        action = _make_action(
+            description='Install requests',
+            kind_name='INSTALL',
+            package_name='requests',
+            constraint='>=2.0',
+            installer='pip',
+        )
+        loaded_event = _make_manifest_loaded_event(actions=[action])
+
+        api = MagicMock()
+
+        async def _stream(*_a: object, **_kw: object):
+            yield parsed_event
+            yield loaded_event
+
+        api.sync.execute_stream = _stream
+
+        result = asyncio.run(preview_manifest(api, 'https://example.com/manifest.json'))
+        assert result.project_name == 'My Project'
+        assert result.description == 'A test project'
+        assert result.manifest_key == '/tmp/manifest.json'
+        assert len(result.actions) == 1
+        assert result.actions[0] == ActionInfo(
+            description='Install requests',
+            kind='INSTALL',
+            package='requests',
+            constraint='>=2.0',
+            installer='pip',
+        )
+
+    @staticmethod
+    def test_passes_parameters_correctly() -> None:
+        """Verifies SetupParameters are constructed with correct args."""
+        api = MagicMock()
+        captured_params: list[SetupParameters] = []
+
+        async def _capture_stream(params: SetupParameters, **_kw: object):
+            captured_params.append(params)
+            return
+            yield
+
+        api.sync.execute_stream = _capture_stream
+
+        asyncio.run(
+            preview_manifest(
+                api,
+                'https://example.com/m.json',
+                project_directory=Path('/proj'),
+                prerelease_packages={'alpha-pkg'},
+            )
+        )
+
+        assert len(captured_params) == 1
+        p = captured_params[0]
+        assert p.paths == ['https://example.com/m.json']
+        assert p.dry_run is True
+        assert p.project_directory == Path('/proj')
+        assert p.prerelease_packages == {'alpha-pkg'}
+
+
+# ---------------------------------------------------------------------------
+# execute_install
+# ---------------------------------------------------------------------------
+
+
+class TestExecuteInstall:
+    """Tests for execute_install()."""
+
+    @staticmethod
+    def test_yields_stage_event_tuples() -> None:
+        """Yields (stage, event) tuples for different event types."""
+        from porringer.schema import (
+            ActionCompletedEvent,
+            ActionStartedEvent,
+            ManifestLoadedEvent,
+            SubActionProgressEvent,
+        )
+
+        loaded = MagicMock(spec=ManifestLoadedEvent)
+        started = MagicMock(spec=ActionStartedEvent)
+        progress = MagicMock(spec=SubActionProgressEvent)
+        completed = MagicMock(spec=ActionCompletedEvent)
+        other = MagicMock()  # no spec → falls through to 'other'
+
+        api = MagicMock()
+
+        async def _stream(*_a: object, **_kw: object):
+            yield loaded
+            yield started
+            yield progress
+            yield completed
+            yield other
+
+        api.sync.execute_stream = _stream
+
+        async def _collect() -> list[tuple[str, ProgressEvent]]:
+            results = []
+            async for stage, event in execute_install(api, Path('/m.json')):
+                results.append((stage, event))
+            return results
+
+        results = asyncio.run(_collect())
+        expected_count = 5
+        assert len(results) == expected_count
+        assert results[0] == ('manifest_loaded', loaded)
+        assert results[1] == ('action_started', started)
+        assert results[2] == ('sub_progress', progress)
+        assert results[3] == ('action_completed', completed)
+        assert results[4] == ('other', other)
+
+    @staticmethod
+    def test_empty_stream() -> None:
+        """No events → no yields."""
+        api = MagicMock()
+
+        async def _empty(*_a: object, **_kw: object):
+            return
+            yield
+
+        api.sync.execute_stream = _empty
+
+        async def _collect() -> list[tuple[str, ProgressEvent]]:
+            results = []
+            async for stage, event in execute_install(api, Path('/m.json')):
+                results.append((stage, event))
+            return results
+
+        results = asyncio.run(_collect())
+        assert results == []
diff --git a/tests/unit/operations/test_project.py b/tests/unit/operations/test_project.py
new file mode 100644
index 0000000..e7786d0
--- /dev/null
+++ b/tests/unit/operations/test_project.py
@@ -0,0 +1,85 @@
+"""Tests for operations.project module."""
+
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+from synodic_client.operations.project import add_project, list_projects, remove_project
+from synodic_client.operations.schema import ProjectInfo
+
+
+def _make_dir_result(path: str, *, exists: bool = True, has_manifest: bool = False) -> MagicMock:
+    """Create a mock DirectoryResult."""
+    result = MagicMock()
+    result.directory.path = path
+    result.directory.name = Path(path).name
+    result.exists = exists
+    result.has_manifest = has_manifest
+    return result
+
+
+class TestListProjects:
+    """Tests for list_projects()."""
+
+    @staticmethod
+    def test_empty() -> None:
+        """No cached directories returns empty list."""
+        api = MagicMock()
+        api.cache.list_directories.return_value = []
+        assert list_projects(api) == []
+
+    @staticmethod
+    def test_returns_project_info() -> None:
+        """Each directory result maps to a ProjectInfo."""
+        api = MagicMock()
+        api.cache.list_directories.return_value = [
+            _make_dir_result('/a/foo', exists=True, has_manifest=True),
+            _make_dir_result('/b/bar', exists=False, has_manifest=False),
+        ]
+        result = list_projects(api)
+        expected_count = 2
+        assert len(result) == expected_count
+        assert result[0] == ProjectInfo(path='/a/foo', name='foo', exists=True, has_manifest=True)
+        assert result[1] == ProjectInfo(path='/b/bar', name='bar', exists=False, has_manifest=False)
+
+    @staticmethod
+    def test_passes_validation_flags() -> None:
+        """list_projects passes validate=True, check_manifest=True."""
+        api = MagicMock()
+        api.cache.list_directories.return_value = []
+        list_projects(api)
+        api.cache.list_directories.assert_called_once_with(validate=True, check_manifest=True)
+
+
+class TestAddProject:
+    """Tests for add_project()."""
+
+    @staticmethod
+    def test_not_a_directory(tmp_path: Path) -> None:
+        """Raises NotADirectoryError for a missing directory."""
+        api = MagicMock()
+        with pytest.raises(NotADirectoryError, match='Not a directory'):
+            add_project(api, tmp_path / 'nonexistent')
+
+    @staticmethod
+    def test_adds_and_returns_info(tmp_path: Path) -> None:
+        """Adds the directory and returns ProjectInfo."""
+        api = MagicMock()
+        api.cache.list_directories.return_value = [
+            _make_dir_result(str(tmp_path), exists=True, has_manifest=False),
+        ]
+        info = add_project(api, tmp_path)
+        api.cache.add_directory.assert_called_once_with(tmp_path)
+        assert info.path == str(tmp_path)
+
+
+class TestRemoveProject:
+    """Tests for remove_project()."""
+
+    @staticmethod
+    def test_delegates_to_cache() -> None:
+        """remove_project calls porringer.cache.remove_directory."""
+        api = MagicMock()
+        remove_project(api, '/tmp/foo')
+        api.cache.remove_directory.assert_called_once_with(Path('/tmp/foo'))
diff --git a/tests/unit/operations/test_tool.py b/tests/unit/operations/test_tool.py
new file mode 100644
index 0000000..a18682a
--- /dev/null
+++ b/tests/unit/operations/test_tool.py
@@ -0,0 +1,231 @@
+"""Tests for operations.tool module."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+from synodic_client.operations.schema import UpdateResult
+from synodic_client.operations.tool import (
+    check_tool_updates,
+    remove_package,
+    resolve_auto_update_scope,
+    update_tool,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_action_completed(
+    *,
+    installer: str,
+    package_name: str,
+    skip_reason: object,
+    available_version: str = '',
+) -> MagicMock:
+    """Build a mock ActionCompletedEvent."""
+    event = MagicMock()
+    event.result.skip_reason = skip_reason
+    event.result.action.installer = installer
+    event.result.action.package.name = package_name
+    event.result.available_version = available_version
+    return event
+
+
+def _make_manifest_dir(path: str) -> MagicMock:
+    """Build a mock ManifestDirectory."""
+    md = MagicMock()
+    md.path = path
+    return md
+
+
+# ---------------------------------------------------------------------------
+# check_tool_updates
+# ---------------------------------------------------------------------------
+
+
+class TestCheckToolUpdates:
+    """Tests for check_tool_updates()."""
+
+    @staticmethod
+    def test_empty_directories() -> None:
+        """No directories → empty dict."""
+        api = MagicMock()
+        result = asyncio.run(check_tool_updates(api, []))
+        assert result == {}
+
+    @staticmethod
+    def test_detects_update_available(tmp_path: Path) -> None:
+        """Finds packages with UPDATE_AVAILABLE skip reason."""
+        from porringer.schema import ActionCompletedEvent, SkipReason
+
+        # Create a real manifest file so the path check succeeds
+        manifest_dir = tmp_path / 'proj'
+        manifest_dir.mkdir()
+
+        api = MagicMock()
+        api.sync.manifest_filenames.return_value = ['porringer.json']
+        (manifest_dir / 'porringer.json').write_text('{}')
+
+        event = _make_action_completed(
+            installer='pip',
+            package_name='requests',
+            skip_reason=SkipReason.UPDATE_AVAILABLE,
+            available_version='2.32.0',
+        )
+        # Make the event pass isinstance check
+        event.__class__ = ActionCompletedEvent
+
+        async def _stream(*_a: object, **_kw: object):
+            yield event
+
+        api.sync.execute_stream = _stream
+
+        md = _make_manifest_dir(str(manifest_dir))
+        result = asyncio.run(check_tool_updates(api, [md]))
+        assert result == {'pip': {'requests': '2.32.0'}}
+
+    @staticmethod
+    def test_skips_directory_without_manifest(tmp_path: Path) -> None:
+        """Directories without a manifest file are skipped silently."""
+        manifest_dir = tmp_path / 'empty'
+        manifest_dir.mkdir()
+
+        api = MagicMock()
+        api.sync.manifest_filenames.return_value = ['porringer.json']
+
+        md = _make_manifest_dir(str(manifest_dir))
+        result = asyncio.run(check_tool_updates(api, [md]))
+        assert result == {}
+
+
+# ---------------------------------------------------------------------------
+# update_tool
+# ---------------------------------------------------------------------------
+
+
+class TestUpdateTool:
+    """Tests for update_tool()."""
+
+    @staticmethod
+    def test_single_package_success() -> None:
+        """Upgrading a specific package that succeeds."""
+        api = MagicMock()
+        action_result = MagicMock()
+        action_result.skipped = False
+        action_result.success = True
+        api.package.upgrade = AsyncMock(return_value=action_result)
+
+        result = asyncio.run(update_tool(api, 'pip', 'requests'))
+        assert isinstance(result, UpdateResult)
+        assert result.packages_updated == ['requests']
+        assert result.already_latest == []
+        assert result.packages_failed == []
+
+    @staticmethod
+    def test_single_package_already_latest() -> None:
+        """Upgrading a package that is already up to date."""
+        api = MagicMock()
+        action_result = MagicMock()
+        action_result.skipped = True
+        api.package.upgrade = AsyncMock(return_value=action_result)
+
+        result = asyncio.run(update_tool(api, 'pip', 'requests'))
+        assert result.already_latest == ['requests']
+
+    @staticmethod
+    def test_single_package_failure() -> None:
+        """Upgrading a package that fails."""
+        api = MagicMock()
+        action_result = MagicMock()
+        action_result.skipped = False
+        action_result.success = False
+        api.package.upgrade = AsyncMock(return_value=action_result)
+
+        result = asyncio.run(update_tool(api, 'pip', 'requests'))
+        assert result.packages_failed == ['requests']
+
+
+# ---------------------------------------------------------------------------
+# remove_package
+# ---------------------------------------------------------------------------
+
+
+class TestRemovePackage:
+    """Tests for remove_package()."""
+
+    @staticmethod
+    def test_success() -> None:
+        """Successful removal returns True."""
+        api = MagicMock()
+        api.package.uninstall = AsyncMock(return_value=MagicMock(success=True))
+        assert asyncio.run(remove_package(api, 'pip', 'requests')) is True
+
+    @staticmethod
+    def test_failure() -> None:
+        """Failed removal returns False."""
+        api = MagicMock()
+        api.package.uninstall = AsyncMock(return_value=MagicMock(success=False))
+        assert asyncio.run(remove_package(api, 'pip', 'requests')) is False
+
+
+# ---------------------------------------------------------------------------
+# resolve_auto_update_scope
+# ---------------------------------------------------------------------------
+
+
+class TestResolveAutoUpdateScope:
+    """Tests for resolve_auto_update_scope()."""
+
+    @staticmethod
+    def test_none_config_returns_none_none() -> None:
+        """No config → (None, None) meaning all plugins, all packages."""
+        plugins, packages = resolve_auto_update_scope(None, ['pip', 'npm'])
+        assert plugins is None
+        assert packages is None
+
+    @staticmethod
+    def test_disabled_plugin_excluded() -> None:
+        """A plugin set to False is excluded from the enabled set."""
+        plugins, _ = resolve_auto_update_scope(
+            {'pip': False, 'npm': True},
+            ['pip', 'npm', 'cargo'],
+        )
+        assert plugins is not None
+        assert 'pip' not in plugins
+        assert 'npm' in plugins
+        assert 'cargo' in plugins
+
+    @staticmethod
+    def test_per_package_entries() -> None:
+        """Per-package granularity builds the include set."""
+        _, packages = resolve_auto_update_scope(
+            {'pip': {'requests': True, 'flask': False}},
+            ['pip'],
+            manifest_packages=None,
+        )
+        assert packages is not None
+        assert 'requests' in packages
+        assert 'flask' not in packages
+
+    @staticmethod
+    def test_manifest_packages_included() -> None:
+        """Manifest packages are added to the include set."""
+        _, packages = resolve_auto_update_scope(
+            {},
+            ['pip'],
+            manifest_packages={'pip': {'requests', 'flask'}},
+        )
+        assert packages is not None
+        assert 'requests' in packages
+        assert 'flask' in packages
+
+    @staticmethod
+    def test_empty_config_returns_none_none() -> None:
+        """Empty mapping → (None, None)."""
+        plugins, packages = resolve_auto_update_scope({}, ['pip'])
+        assert plugins is None
+        assert packages is None
diff --git a/tests/unit/operations/test_update.py b/tests/unit/operations/test_update.py
new file mode 100644
index 0000000..75ef61b
--- /dev/null
+++ b/tests/unit/operations/test_update.py
@@ -0,0 +1,147 @@
+"""Tests for operations.update module."""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import MagicMock
+
+from synodic_client.operations.schema import DownloadResult, UpdateCheckResult
+from synodic_client.operations.update import apply_self_update, check_self_update, download_self_update
+
+# ---------------------------------------------------------------------------
+# check_self_update
+# ---------------------------------------------------------------------------
+
+
+class TestCheckSelfUpdate:
+    """Tests for check_self_update()."""
+
+    @staticmethod
+    def test_returns_available_when_update_exists() -> None:
+        """Returns available=True with the latest version."""
+        client = MagicMock()
+        check_result = MagicMock()
+        check_result.error = None
+        check_result.available = True
+        check_result.current_version = '1.0.0'
+        check_result.latest_version = '2.0.0'
+        client.check_for_update.return_value = check_result
+
+        result = asyncio.run(check_self_update(client))
+        assert isinstance(result, UpdateCheckResult)
+        assert result.available is True
+        assert result.version == '2.0.0'
+        assert result.current_version == '1.0.0'
+
+    @staticmethod
+    def test_returns_unavailable_when_no_update() -> None:
+        """Returns available=False when already on the latest."""
+        client = MagicMock()
+        check_result = MagicMock()
+        check_result.error = None
+        check_result.available = False
+        check_result.current_version = '1.0.0'
+        check_result.latest_version = None
+        client.check_for_update.return_value = check_result
+
+        result = asyncio.run(check_self_update(client))
+        assert result.available is False
+        assert result.version is None
+
+    @staticmethod
+    def test_returns_error_when_check_fails() -> None:
+        """Returns error string when the check reports an error."""
+        client = MagicMock()
+        check_result = MagicMock()
+        check_result.error = 'Network timeout'
+        check_result.current_version = '1.0.0'
+        client.check_for_update.return_value = check_result
+
+        result = asyncio.run(check_self_update(client))
+        assert result.available is False
+        assert result.error == 'Network timeout'
+
+    @staticmethod
+    def test_returns_error_when_updater_not_initialised() -> None:
+        """Returns error when check_for_update returns None."""
+        client = MagicMock()
+        client.check_for_update.return_value = None
+        client.version = '1.0.0'
+
+        result = asyncio.run(check_self_update(client))
+        assert result.available is False
+        assert result.error is not None
+        assert 'not initialized' in result.error.lower()
+
+
+# ---------------------------------------------------------------------------
+# download_self_update
+# ---------------------------------------------------------------------------
+
+
+class TestDownloadSelfUpdate:
+    """Tests for download_self_update()."""
+
+    @staticmethod
+    def test_success() -> None:
+        """Returns success=True when download succeeds."""
+        client = MagicMock()
+        client.download_update.return_value = True
+        client.version = '2.0.0'
+
+        result = asyncio.run(download_self_update(client))
+        assert isinstance(result, DownloadResult)
+        assert result.success is True
+        assert result.version == '2.0.0'
+
+    @staticmethod
+    def test_failure() -> None:
+        """Returns success=False with error message on failure."""
+        client = MagicMock()
+        client.download_update.return_value = False
+        client.version = '1.0.0'
+
+        result = asyncio.run(download_self_update(client))
+        assert result.success is False
+        assert result.error is not None
+
+    @staticmethod
+    def test_progress_callback_invoked() -> None:
+        """The on_progress callback is wired to the download."""
+        client = MagicMock()
+        client.download_update.return_value = True
+        client.version = '2.0.0'
+
+        progress_values: list[int] = []
+
+        def _on_progress(pct: int) -> None:
+            progress_values.append(pct)
+
+        # download_self_update passes a _progress wrapper; we just verify
+        # download_update receives a callable and the overall flow works.
+        result = asyncio.run(download_self_update(client, on_progress=_on_progress))
+        assert result.success is True
+        client.download_update.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# apply_self_update
+# ---------------------------------------------------------------------------
+
+
+class TestApplySelfUpdate:
+    """Tests for apply_self_update()."""
+
+    @staticmethod
+    def test_delegates_to_client() -> None:
+        """Calls client.apply_update_on_exit with correct kwargs."""
+        client = MagicMock()
+        apply_self_update(client, restart=True, silent=False)
+        client.apply_update_on_exit.assert_called_once_with(restart=True, silent=False)
+
+    @staticmethod
+    def test_no_restart() -> None:
+        """Passes restart=False correctly."""
+        client = MagicMock()
+        apply_self_update(client, restart=False, silent=True)
+        client.apply_update_on_exit.assert_called_once_with(restart=False, silent=True)
diff --git a/tests/unit/qt/test_action_card.py b/tests/unit/qt/test_action_card.py
index a62c598..deec219 100644
--- a/tests/unit/qt/test_action_card.py
+++ b/tests/unit/qt/test_action_card.py
@@ -14,6 +14,7 @@
 from PySide6.QtCore import Qt
 from PySide6.QtWidgets import QApplication
 
+from synodic_client.application.screen import is_version_specifier
 from synodic_client.application.screen.action_card import (
     ActionCard,
     ActionCardList,
@@ -58,6 +59,7 @@ def _make_action(
     action.installer = installer
     pkg_mock = MagicMock()
     pkg_mock.name = package
+    pkg_mock.constraint = overrides.get('constraint')
     pkg_mock.configure_mock(**{'__str__': MagicMock(return_value=package)})
     action.package = pkg_mock
     action.package_description = overrides.get('package_description', description)
@@ -600,6 +602,149 @@ def test_prerelease_signal_forwarded() -> None:
         assert len(received) == 1
         assert received[0] == ('requests', True)
 
+
+# ---------------------------------------------------------------------------
+# ActionCard — PROJECT and bare-command status (Bug B fix)
+# ---------------------------------------------------------------------------
+
+
+class TestActionCardKindStatus:
+    """Tests for PROJECT and bare-command actions getting correct status."""
+
+    @staticmethod
+    def test_bare_command_shows_pending_after_check() -> None:
+        """Bare command (kind=None) keeps 'Pending' after dry-run check."""
+        card = ActionCard()
+        action = _make_action(kind=None, package='post_sync', installer=None, command=('echo', 'done'))
+        card.populate(action)
+        assert card.status_text() == 'Pending'
+
+        result = _make_result(success=True, skipped=False)
+        card.set_check_result(result)
+        assert card.status_text() == 'Pending'
+        assert ACTION_CARD_STATUS_PENDING in card._status_label.styleSheet()
+
+    @staticmethod
+    def test_project_shows_ready_after_check() -> None:
+        """PROJECT action shows 'Ready' after dry-run check."""
+        card = ActionCard()
+        action = _make_action(kind=PluginKind.PROJECT, package='myproject')
+        card.populate(action)
+
+        result = _make_result(success=True, skipped=False)
+        card.set_check_result(result)
+        assert card.status_text() == 'Ready'
+        assert ACTION_CARD_STATUS_SATISFIED in card._status_label.styleSheet()
+
+    @staticmethod
+    def test_package_still_shows_needed() -> None:
+        """A PACKAGE action with success=True still shows 'Needed'."""
+        card = ActionCard()
+        card.populate(_make_action(kind=PluginKind.PACKAGE))
+        result = _make_result(success=True, skipped=False)
+        card.set_check_result(result)
+        assert card.status_text() == 'Needed'
+
+
+# ---------------------------------------------------------------------------
+# ActionCard — version specifier display (Phase 3)
+# ---------------------------------------------------------------------------
+
+
+class TestActionCardVersionSpecifier:
+    """Tests for constraint-aware version column display."""
+
+    @staticmethod
+    def test_specifier_available_version_shows_requires() -> None:
+        """available_version with a specifier shows 'requires …'."""
+        card = ActionCard()
+        card.populate(_make_action())
+        result = _make_result(
+            success=True,
+            skipped=False,
+            available_version='>=0.8.0',
+        )
+        card.set_check_result(result)
+        assert card._version_label.text() == 'requires >=0.8.0'
+        assert 'grey' in card._version_label.styleSheet()
+
+    @staticmethod
+    def test_resolved_available_version_shows_arrow() -> None:
+        """available_version with a plain version shows '→ X.Y.Z'."""
+        card = ActionCard()
+        card.populate(_make_action())
+        result = _make_result(
+            success=True,
+            skipped=False,
+            available_version='1.2.0',
+        )
+        card.set_check_result(result)
+        assert '\u2192 1.2.0' in card._version_label.text()
+
+    @staticmethod
+    def test_satisfied_with_constraint_shows_tooltip() -> None:
+        """Satisfied action with constraint shows 'satisfies ...' tooltip."""
+        card = ActionCard()
+        action = _make_action(constraint='>=0.8.0')
+        card.populate(action)
+        result = _make_result(
+            skipped=True,
+            skip_reason=SkipReason.ALREADY_INSTALLED,
+            installed_version='0.9.1',
+        )
+        card.set_check_result(result)
+        assert card._version_label.text() == '0.9.1'
+        assert 'satisfies >=0.8.0' in card._version_label.toolTip()
+
+    @staticmethod
+    def test_satisfied_without_constraint_no_tooltip() -> None:
+        """Satisfied action without constraint has no version tooltip."""
+        card = ActionCard()
+        action = _make_action()
+        card.populate(action)
+        result = _make_result(
+            skipped=True,
+            skip_reason=SkipReason.ALREADY_INSTALLED,
+            installed_version='0.9.1',
+        )
+        card.set_check_result(result)
+        assert card._version_label.text() == '0.9.1'
+        # No constraint tooltip — only message tooltip may have been set
+        assert 'satisfies' not in (card._version_label.toolTip() or '')
+
+
+# ---------------------------------------------------------------------------
+# is_version_specifier helper
+# ---------------------------------------------------------------------------
+
+
+class TestIsVersionSpecifier:
+    """Tests for the is_version_specifier helper."""
+
+    @staticmethod
+    def test_pep440_operators() -> None:
+        """PEP 440 operators are detected."""
+        assert is_version_specifier('>=0.8.0')
+        assert is_version_specifier('==1.0.0')
+        assert is_version_specifier('~=2.0')
+        assert is_version_specifier('!=1.5.0')
+        assert is_version_specifier('>3.0')
+        assert is_version_specifier('<4.0')
+        assert is_version_specifier('<=2.0')
+
+    @staticmethod
+    def test_caret_tilde() -> None:
+        """Caret and tilde shorthand are detected."""
+        assert is_version_specifier('^1.0')
+        assert is_version_specifier('~1.0')
+
+    @staticmethod
+    def test_plain_versions_not_specifiers() -> None:
+        """Plain version strings are not specifiers."""
+        assert not is_version_specifier('1.2.3')
+        assert not is_version_specifier('0.8.0')
+        assert not is_version_specifier('2024.1')
+
     @staticmethod
     def test_card_at_out_of_range() -> None:
         """card_at returns None for out-of-range indices."""
diff --git a/tests/unit/qt/test_gather_packages.py b/tests/unit/qt/test_gather_packages.py
index 70f6def..75116a4 100644
--- a/tests/unit/qt/test_gather_packages.py
+++ b/tests/unit/qt/test_gather_packages.py
@@ -10,7 +10,6 @@
 from porringer.core.schema import Package, PackageRelation, PackageRelationKind
 from porringer.schema import ManifestDirectory
 from porringer.schema.plugin import PluginInfo, PluginKind, RuntimePackageResult
-from porringer.utility.exception import PluginError
 from PySide6.QtWidgets import QLabel, QPushButton
 
 from synodic_client.application.config_store import ConfigStore
@@ -1162,7 +1161,7 @@ def test_gather_runtime_packages_returns_none_for_non_consumer() -> None:
         """_gather_runtime_packages returns None when plugin is not a RuntimeConsumer."""
         porringer = _make_porringer()
         porringer.package.list_by_runtime = AsyncMock(
-            side_effect=PluginError('not a RuntimeConsumer'),
+            return_value=None,
         )
 
         view = ToolsView(porringer, _make_store())
diff --git a/tests/unit/qt/test_install_preview.py b/tests/unit/qt/test_install_preview.py
index 6413899..662bb3d 100644
--- a/tests/unit/qt/test_install_preview.py
+++ b/tests/unit/qt/test_install_preview.py
@@ -9,9 +9,12 @@
 
 import pytest
 from porringer.schema import (
+    ActionCompletedEvent,
+    DiscoveredPluginEntry,
     DownloadResult,
-    ProgressEvent,
-    ProgressEventKind,
+    ManifestLoadedEvent,
+    ManifestParsedEvent,
+    PluginsDiscoveredEvent,
     SetupActionResult,
     SetupResults,
     SkipReason,
@@ -142,11 +145,10 @@ def test_worker_emits_finished_on_success() -> None:
 
         action = MagicMock()
         manifest = SetupResults(actions=[action])
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=manifest)
+        manifest_event = ManifestLoadedEvent(manifest=manifest)
 
         result = MagicMock(spec=SetupActionResult)
-        completed_event = ProgressEvent(
-            kind=ProgressEventKind.ACTION_COMPLETED,
+        completed_event = ActionCompletedEvent(
             action=action,
             result=result,
             action_index=0,
@@ -186,7 +188,7 @@ def test_worker_passes_prerelease_packages() -> None:
         manifest_path = Path('/tmp/test/porringer.json')
 
         manifest = SetupResults(actions=[])
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=manifest)
+        manifest_event = ManifestLoadedEvent(manifest=manifest)
 
         captured_params: list[Any] = []
 
@@ -214,7 +216,7 @@ def test_worker_omits_prerelease_when_none() -> None:
         manifest_path = Path('/tmp/test/porringer.json')
 
         manifest = SetupResults(actions=[])
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=manifest)
+        manifest_event = ManifestLoadedEvent(manifest=manifest)
 
         captured_params: list[Any] = []
 
@@ -273,7 +275,7 @@ def test_local_manifest_skips_download(tmp_path: Path) -> None:
 
         porringer = MagicMock()
         expected = SetupResults(actions=[])
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=expected)
+        manifest_event = ManifestLoadedEvent(manifest=expected)
 
         async def mock_stream(*args: Any, **kwargs: Any) -> Any:
             yield manifest_event
@@ -349,7 +351,7 @@ async def _mock_download(params: Any, progress_callback: Any = None) -> Download
         monkeypatch.setattr(_DOWNLOAD_PATCH, _mock_download)
 
         expected = SetupResults(actions=[])
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=expected)
+        manifest_event = ManifestLoadedEvent(manifest=expected)
 
         async def mock_stream(*args: Any, **kwargs: Any) -> Any:
             yield manifest_event
@@ -387,10 +389,9 @@ def test_emits_preview_ready_and_finished(tmp_path: Path) -> None:
         preview = SetupResults(actions=[action])
 
         # Dry-run stream yields manifest loaded then one completed event
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
         result = SetupActionResult(action=action, success=True, skipped=False, skip_reason=None)
-        completed_event = ProgressEvent(
-            kind=ProgressEventKind.ACTION_COMPLETED,
+        completed_event = ActionCompletedEvent(
             action=action,
             result=result,
             action_index=0,
@@ -434,7 +435,7 @@ def test_emits_finished_for_empty_actions(tmp_path: Path) -> None:
 
         porringer = MagicMock()
         preview = SetupResults(actions=[])
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
 
         async def mock_stream(*args: Any, **kwargs: Any) -> Any:
             yield manifest_event
@@ -464,21 +465,19 @@ def test_action_checked_maps_correct_rows(tmp_path: Path) -> None:
         action_b.kind = PluginKind.PACKAGE
         preview = SetupResults(actions=[action_a, action_b])
 
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
         result_b = SetupActionResult(
             action=action_b, success=True, skipped=True, skip_reason=SkipReason.ALREADY_INSTALLED
         )
         result_a = SetupActionResult(action=action_a, success=True, skipped=False, skip_reason=None)
 
         # Stream returns in execution order (b before a), not preview order
-        event_b = ProgressEvent(
-            kind=ProgressEventKind.ACTION_COMPLETED,
+        event_b = ActionCompletedEvent(
             action=action_b,
             result=result_b,
             action_index=1,
         )
-        event_a = ProgressEvent(
-            kind=ProgressEventKind.ACTION_COMPLETED,
+        event_a = ActionCompletedEvent(
             action=action_a,
             result=result_a,
             action_index=0,
@@ -536,11 +535,13 @@ def test_emits_plugins_queried(tmp_path: Path) -> None:
         porringer = MagicMock()
 
         preview = SetupResults(actions=[])
-        plugins_event = ProgressEvent(
-            kind=ProgressEventKind.PLUGINS_DISCOVERED,
-            plugin_availability={'pip': True, 'uv': False},
+        plugins_event = PluginsDiscoveredEvent(
+            discovered_plugins=(
+                DiscoveredPluginEntry(name='pip', available=True, capabilities=frozenset(), kind=PluginKind.PACKAGE),
+                DiscoveredPluginEntry(name='uv', available=False, capabilities=frozenset(), kind=PluginKind.PACKAGE),
+            ),
         )
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
 
         async def mock_stream(*args: Any, **kwargs: Any) -> Any:
             yield plugins_event
@@ -548,20 +549,20 @@ async def mock_stream(*args: Any, **kwargs: Any) -> Any:
 
         porringer.sync.execute_stream = mock_stream
 
-        plugin_data: list[dict[str, bool]] = []
+        captured: list[tuple[dict[str, bool], dict[str, frozenset]]] = []
 
         asyncio.run(
             run_preview(
                 porringer,
                 str(manifest),
                 callbacks=PreviewCallbacks(
-                    on_plugins_queried=plugin_data.append,
+                    on_plugins_queried=lambda avail, caps: captured.append((avail, caps)),
                 ),
             ),
         )
 
-        assert len(plugin_data) == 1
-        assert plugin_data[0] == {'pip': True, 'uv': False}
+        assert len(captured) == 1
+        assert captured[0][0] == {'pip': True, 'uv': False}
 
     @staticmethod
     def test_plugins_queried_emitted_before_preview_ready(tmp_path: Path) -> None:
@@ -572,11 +573,10 @@ def test_plugins_queried_emitted_before_preview_ready(tmp_path: Path) -> None:
         porringer = MagicMock()
 
         preview = SetupResults(actions=[])
-        plugins_event = ProgressEvent(
-            kind=ProgressEventKind.PLUGINS_DISCOVERED,
-            plugin_availability={},
+        plugins_event = PluginsDiscoveredEvent(
+            discovered_plugins=(),
         )
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
 
         async def mock_stream(*args: Any, **kwargs: Any) -> Any:
             yield plugins_event
@@ -591,7 +591,7 @@ async def mock_stream(*args: Any, **kwargs: Any) -> Any:
                 porringer,
                 str(manifest),
                 callbacks=PreviewCallbacks(
-                    on_plugins_queried=lambda _: order.append('plugins'),
+                    on_plugins_queried=lambda _avail, _caps: order.append('plugins'),
                     on_preview_ready=lambda *_: order.append('preview'),
                 ),
             ),
@@ -608,11 +608,10 @@ def test_emits_manifest_parsed(tmp_path: Path) -> None:
         porringer = MagicMock()
 
         preview = SetupResults(actions=[])
-        parsed_event = ProgressEvent(
-            kind=ProgressEventKind.MANIFEST_PARSED,
+        parsed_event = ManifestParsedEvent(
             manifest=preview,
         )
-        loaded_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        loaded_event = ManifestLoadedEvent(manifest=preview)
 
         async def mock_stream(*args: Any, **kwargs: Any) -> Any:
             yield parsed_event
@@ -643,15 +642,15 @@ def test_two_phase_signal_order(tmp_path: Path) -> None:
         porringer = MagicMock()
 
         preview = SetupResults(actions=[])
-        parsed_event = ProgressEvent(
-            kind=ProgressEventKind.MANIFEST_PARSED,
+        parsed_event = ManifestParsedEvent(
             manifest=preview,
         )
-        plugins_event = ProgressEvent(
-            kind=ProgressEventKind.PLUGINS_DISCOVERED,
-            plugin_availability={'pip': True},
+        plugins_event = PluginsDiscoveredEvent(
+            discovered_plugins=(
+                DiscoveredPluginEntry(name='pip', available=True, capabilities=frozenset(), kind=PluginKind.PACKAGE),
+            ),
         )
-        loaded_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        loaded_event = ManifestLoadedEvent(manifest=preview)
 
         async def mock_stream(*args: Any, **kwargs: Any) -> Any:
             yield parsed_event
@@ -668,7 +667,7 @@ async def mock_stream(*args: Any, **kwargs: Any) -> Any:
                 str(manifest),
                 callbacks=PreviewCallbacks(
                     on_manifest_parsed=lambda *_: order.append('parsed'),
-                    on_plugins_queried=lambda _: order.append('plugins'),
+                    on_plugins_queried=lambda _avail, _caps: order.append('plugins'),
                     on_preview_ready=lambda *_: order.append('ready'),
                 ),
             ),
@@ -688,7 +687,7 @@ def test_passes_prerelease_packages(tmp_path: Path) -> None:
 
         porringer = MagicMock()
         preview = SetupResults(actions=[])
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
 
         captured_params: list[Any] = []
 
@@ -719,7 +718,7 @@ def test_defaults_prerelease_none(tmp_path: Path) -> None:
 
         porringer = MagicMock()
         preview = SetupResults(actions=[])
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
 
         captured_params: list[Any] = []
 
@@ -768,7 +767,7 @@ def test_file_path_forwards_parent_as_project_directory(tmp_path: Path) -> None:
 
         porringer = MagicMock()
         preview = SetupResults(actions=[])
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
 
         captured_params: list[Any] = []
 
@@ -797,7 +796,7 @@ def test_directory_path_forwarded_directly(tmp_path: Path) -> None:
 
         porringer = MagicMock()
         preview = SetupResults(actions=[])
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
 
         captured_params: list[Any] = []
 
@@ -841,15 +840,14 @@ def test_scm_already_installed_emits_correct_result(self, tmp_path: Path) -> Non
         action = self._make_scm_action()
         preview = SetupResults(actions=[action])
 
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
         result = SetupActionResult(
             action=action,
             success=True,
             skipped=True,
             skip_reason=SkipReason.ALREADY_INSTALLED,
         )
-        completed_event = ProgressEvent(
-            kind=ProgressEventKind.ACTION_COMPLETED,
+        completed_event = ActionCompletedEvent(
             action=action,
             result=result,
             action_index=0,
@@ -888,15 +886,14 @@ def test_scm_needed_emits_correct_result(self, tmp_path: Path) -> None:
         action = self._make_scm_action()
         preview = SetupResults(actions=[action])
 
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=preview)
+        manifest_event = ManifestLoadedEvent(manifest=preview)
         result = SetupActionResult(
             action=action,
             success=True,
             skipped=False,
             skip_reason=None,
         )
-        completed_event = ProgressEvent(
-            kind=ProgressEventKind.ACTION_COMPLETED,
+        completed_event = ActionCompletedEvent(
             action=action,
             result=result,
             action_index=0,
diff --git a/tests/unit/qt/test_log_panel.py b/tests/unit/qt/test_log_panel.py
index 813bb20..2c83a1c 100644
--- a/tests/unit/qt/test_log_panel.py
+++ b/tests/unit/qt/test_log_panel.py
@@ -7,13 +7,15 @@
 from unittest.mock import MagicMock
 
 from porringer.schema import (
-    ProgressEvent,
-    ProgressEventKind,
+    ActionCompletedEvent,
+    ActionStartedEvent,
+    ManifestLoadedEvent,
     SetupAction,
     SetupActionResult,
     SetupResults,
     SkipReason,
     SubActionProgress,
+    SubActionProgressEvent,
 )
 from porringer.schema.plugin import PluginKind
 
@@ -463,11 +465,10 @@ def test_emits_action_started() -> None:
         action = _make_action()
         manifest = SetupResults(actions=[action])
 
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=manifest)
-        started_event = ProgressEvent(kind=ProgressEventKind.ACTION_STARTED, action=action)
+        manifest_event = ManifestLoadedEvent(manifest=manifest)
+        started_event = ActionStartedEvent(action=action)
         result = _make_result(action)
-        completed_event = ProgressEvent(
-            kind=ProgressEventKind.ACTION_COMPLETED,
+        completed_event = ActionCompletedEvent(
             action=action,
             result=result,
         )
@@ -507,15 +508,13 @@ def test_emits_sub_progress() -> None:
             stream='stderr',
         )
 
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=manifest)
-        sub_event = ProgressEvent(
-            kind=ProgressEventKind.SUB_ACTION_PROGRESS,
+        manifest_event = ManifestLoadedEvent(manifest=manifest)
+        sub_event = SubActionProgressEvent(
             action=action,
             sub_action=sub,
         )
         result = _make_result(action)
-        completed_event = ProgressEvent(
-            kind=ProgressEventKind.ACTION_COMPLETED,
+        completed_event = ActionCompletedEvent(
             action=action,
             result=result,
         )
@@ -544,30 +543,26 @@ async def mock_stream(*args, **kwargs):
         assert received[0][1] is sub
 
     @staticmethod
-    def test_sub_progress_requires_action_and_sub_action() -> None:
-        """Verify SUB_ACTION_PROGRESS events without action or sub_action are ignored."""
+    def test_non_sub_progress_events_ignored_by_sub_callback() -> None:
+        """Verify non-SubActionProgressEvent events don't trigger sub_progress callback."""
         porringer = MagicMock()
         manifest_path = Path('/tmp/test/porringer.json')
 
         action = _make_action()
         manifest = SetupResults(actions=[action])
 
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=manifest)
-        # Missing action
-        bad_event_1 = ProgressEvent(kind=ProgressEventKind.SUB_ACTION_PROGRESS, action=None, sub_action=None)
-        # Missing sub_action
-        bad_event_2 = ProgressEvent(kind=ProgressEventKind.SUB_ACTION_PROGRESS, action=action, sub_action=None)
+        manifest_event = ManifestLoadedEvent(manifest=manifest)
+        # ActionStartedEvent should not trigger sub_progress callback
+        started_event = ActionStartedEvent(action=action)
         result = _make_result(action)
-        completed_event = ProgressEvent(
-            kind=ProgressEventKind.ACTION_COMPLETED,
+        completed_event = ActionCompletedEvent(
             action=action,
             result=result,
         )
 
         async def mock_stream(*args, **kwargs):
             yield manifest_event
-            yield bad_event_1
-            yield bad_event_2
+            yield started_event
             yield completed_event
 
         porringer.sync.execute_stream = mock_stream
@@ -587,26 +582,23 @@ async def mock_stream(*args, **kwargs):
         assert len(received) == 0
 
     @staticmethod
-    def test_action_started_requires_action() -> None:
-        """Verify ACTION_STARTED events without action are ignored."""
+    def test_non_started_events_ignored_by_started_callback() -> None:
+        """Verify non-ActionStartedEvent events don't trigger action_started callback."""
         porringer = MagicMock()
         manifest_path = Path('/tmp/test/porringer.json')
 
         action = _make_action()
         manifest = SetupResults(actions=[action])
 
-        manifest_event = ProgressEvent(kind=ProgressEventKind.MANIFEST_LOADED, manifest=manifest)
-        bad_event = ProgressEvent(kind=ProgressEventKind.ACTION_STARTED, action=None)
+        manifest_event = ManifestLoadedEvent(manifest=manifest)
         result = _make_result(action)
-        completed_event = ProgressEvent(
-            kind=ProgressEventKind.ACTION_COMPLETED,
+        completed_event = ActionCompletedEvent(
             action=action,
             result=result,
         )
 
         async def mock_stream(*args, **kwargs):
             yield manifest_event
-            yield bad_event
             yield completed_event
 
         porringer.sync.execute_stream = mock_stream
diff --git a/tests/unit/qt/test_logging.py b/tests/unit/qt/test_logging.py
index ba52085..cb9b067 100644
--- a/tests/unit/qt/test_logging.py
+++ b/tests/unit/qt/test_logging.py
@@ -185,7 +185,7 @@ def test_normal_build_sets_porringer_info(tmp_path: Path) -> None:
         had_frozen = hasattr(sys, 'frozen')
         old_frozen = getattr(sys, 'frozen', None)
         if had_frozen:
-            delattr(sys, 'frozen')
+            sys.__dict__.pop('frozen')
 
         try:
             with patch('synodic_client.logging.log_path', return_value=tmp_path / 'synodic.log'):
diff --git a/tests/unit/qt/test_update_controller.py b/tests/unit/qt/test_update_controller.py
index 04e39b0..9e8f38c 100644
--- a/tests/unit/qt/test_update_controller.py
+++ b/tests/unit/qt/test_update_controller.py
@@ -528,8 +528,10 @@ def test_reinit_resets_state_and_cancels_task() -> None:
             )
             ctrl._reinitialize_updater(new_config)
 
-        assert ctrl._pending_version is None  # pyrefly: ignore
-        assert ctrl._failed_version is None  # pyrefly: ignore
+        pending: str | None = ctrl._pending_version
+        failed: str | None = ctrl._failed_version
+        assert pending is None
+        assert failed is None
         fake_task.cancel.assert_called_once()
 
     @staticmethod
diff --git a/tests/unit/test_cli.py b/tests/unit/test_cli.py
index 9b5bbe2..f0dd38a 100644
--- a/tests/unit/test_cli.py
+++ b/tests/unit/test_cli.py
@@ -1,6 +1,9 @@
 """Tests for the CLI entry point."""
 
-from unittest.mock import patch
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
@@ -9,6 +12,13 @@
 from typer.testing import CliRunner
 
 from synodic_client.cli import app
+from synodic_client.operations.schema import (
+    ConfigKeyInfo,
+    DownloadResult,
+    ProjectInfo,
+    UpdateCheckResult,
+    UpdateResult,
+)
 
 runner = CliRunner()
 
@@ -28,7 +38,7 @@ def test_help() -> None:
         """Verify --help shows usage information."""
         result = runner.invoke(app, ['--help'])
         assert result.exit_code == 0
-        assert 'synodic://' in result.output.lower() or 'uri' in result.output.lower()
+        assert '--uri' in result.output
 
     @staticmethod
     def test_launches_application_without_uri() -> None:
@@ -40,10 +50,10 @@ def test_launches_application_without_uri() -> None:
 
     @staticmethod
     def test_launches_application_with_uri() -> None:
-        """Verify invoking with a URI passes it to application()."""
+        """Verify invoking with --uri passes it to application()."""
         test_uri = 'synodic://install?manifest=https://example.com/foo.json'
         with patch('synodic_client.application.qt.application') as mock_app:
-            result = runner.invoke(app, [test_uri])
+            result = runner.invoke(app, ['--uri', test_uri])
             assert result.exit_code == 0
             mock_app.assert_called_once_with(uri=test_uri, dev_mode=False, debug=False)
 
@@ -54,3 +64,274 @@ def test_launches_application_with_dev_flag() -> None:
             result = runner.invoke(app, ['--dev'])
             assert result.exit_code == 0
             mock_app.assert_called_once_with(uri=None, dev_mode=True, debug=False)
+
+
+# ---------------------------------------------------------------------------
+# Project subcommands
+# ---------------------------------------------------------------------------
+
+
+class TestProjectCli:
+    """Tests for synodic-c project sub-commands."""
+
+    @staticmethod
+    def test_project_list() -> None:
+        """Project list renders projects."""
+        projects = [
+            ProjectInfo(path='/a', name='a', exists=True, has_manifest=True),
+        ]
+        with (
+            patch('synodic_client.cli.context.get_services', return_value=(None, MagicMock(), None)),
+            patch('synodic_client.operations.project.list_projects', return_value=projects),
+        ):
+            result = runner.invoke(app, ['project', 'list'])
+            assert result.exit_code == 0
+            assert '/a' in result.output
+
+    @staticmethod
+    def test_project_list_json() -> None:
+        """Project list --json returns valid JSON."""
+        projects = [
+            ProjectInfo(path='/a', name='a', exists=True, has_manifest=False),
+        ]
+        with (
+            patch('synodic_client.cli.context.get_services', return_value=(None, MagicMock(), None)),
+            patch('synodic_client.operations.project.list_projects', return_value=projects),
+        ):
+            result = runner.invoke(app, ['project', 'list', '--json'])
+            assert result.exit_code == 0
+            data = json.loads(result.output)
+            assert isinstance(data, list)
+            assert data[0]['path'] == '/a'
+
+    @staticmethod
+    def test_project_add_not_a_directory() -> None:
+        """Project add with a bad path exits with code 1."""
+        with (
+            patch('synodic_client.cli.context.get_services', return_value=(None, MagicMock(), None)),
+            patch('synodic_client.operations.project.add_project', side_effect=NotADirectoryError('Not a directory')),
+        ):
+            result = runner.invoke(app, ['project', 'add', '/nonexistent'])
+            assert result.exit_code == 1
+
+    @staticmethod
+    def test_project_remove() -> None:
+        """Project remove delegates and prints confirmation."""
+        with (
+            patch('synodic_client.cli.context.get_services', return_value=(None, MagicMock(), None)),
+            patch('synodic_client.operations.project.remove_project') as mock_remove,
+        ):
+            result = runner.invoke(app, ['project', 'remove', '/tmp/foo'])
+            assert result.exit_code == 0
+            assert 'Removed' in result.output
+            mock_remove.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Tool subcommands
+# ---------------------------------------------------------------------------
+
+
+class TestToolCli:
+    """Tests for synodic-c tool sub-commands."""
+
+    @staticmethod
+    def test_tool_check() -> None:
+        """Tool check renders available updates."""
+        api = MagicMock()
+        api.cache.list_directories.return_value = []
+        with (
+            patch('synodic_client.cli.context.get_services', return_value=(None, api, None)),
+            patch(
+                'synodic_client.operations.tool.check_tool_updates',
+                new_callable=AsyncMock,
+                return_value={'pip': {'requests': '2.32'}},
+            ),
+        ):
+            result = runner.invoke(app, ['tool', 'check'])
+            assert result.exit_code == 0
+
+    @staticmethod
+    def test_tool_update() -> None:
+        """Tool update renders an UpdateResult."""
+        update_result = UpdateResult(plugin='pip', packages_updated=['requests'])
+        with (
+            patch('synodic_client.cli.context.get_services', return_value=(None, MagicMock(), None)),
+            patch(
+                'synodic_client.operations.tool.update_tool',
+                new_callable=AsyncMock,
+                return_value=update_result,
+            ),
+        ):
+            result = runner.invoke(app, ['tool', 'update', 'pip'])
+            assert result.exit_code == 0
+
+    @staticmethod
+    def test_tool_remove_json() -> None:
+        """Tool remove --json returns valid JSON with success."""
+        with (
+            patch('synodic_client.cli.context.get_services', return_value=(None, MagicMock(), None)),
+            patch(
+                'synodic_client.operations.tool.remove_package',
+                new_callable=AsyncMock,
+                return_value=True,
+            ),
+        ):
+            result = runner.invoke(app, ['tool', 'remove', 'pip', 'requests', '--json'])
+            assert result.exit_code == 0
+            data = json.loads(result.output)
+            assert data['success'] is True
+
+
+# ---------------------------------------------------------------------------
+# Config subcommands
+# ---------------------------------------------------------------------------
+
+
+class TestConfigCli:
+    """Tests for synodic-c config sub-commands."""
+
+    @staticmethod
+    def test_config_get_unknown_key() -> None:
+        """Config get with unknown key exits code 1."""
+        from synodic_client.schema import ResolvedConfig
+
+        mock_config = ResolvedConfig.__new__(ResolvedConfig)
+        with patch('synodic_client.operations.config.get_config', return_value=mock_config):
+            result = runner.invoke(app, ['config', 'get', 'nonexistent_key_xyz'])
+            assert result.exit_code == 1
+            assert 'Unknown key' in result.output
+
+    @staticmethod
+    def test_config_set_unknown_key() -> None:
+        """Config set with unknown key exits code 1."""
+        with patch('synodic_client.operations.config.set_config', side_effect=KeyError('Unknown config key')):
+            result = runner.invoke(app, ['config', 'set', 'bad_key', 'value'])
+            assert result.exit_code == 1
+
+    @staticmethod
+    def test_config_list() -> None:
+        """Config list renders key=value lines."""
+        keys = {
+            'theme': ConfigKeyInfo(name='theme', type_hint='str', current_value='dark'),
+        }
+        with patch('synodic_client.operations.config.list_config_keys', return_value=keys):
+            result = runner.invoke(app, ['config', 'list'])
+            assert result.exit_code == 0
+            assert 'theme' in result.output
+            assert 'dark' in result.output
+
+
+# ---------------------------------------------------------------------------
+# Update subcommands
+# ---------------------------------------------------------------------------
+
+
+class TestUpdateCli:
+    """Tests for synodic-c update sub-commands."""
+
+    @staticmethod
+    def test_update_check_json() -> None:
+        """Update check --json returns valid JSON."""
+        check_result = UpdateCheckResult(available=True, current_version='1.0', version='2.0')
+        with (
+            patch('synodic_client.cli.context.get_services', return_value=(MagicMock(), None, None)),
+            patch(
+                'synodic_client.operations.update.check_self_update',
+                new_callable=AsyncMock,
+                return_value=check_result,
+            ),
+        ):
+            result = runner.invoke(app, ['update', 'check', '--json'])
+            assert result.exit_code == 0
+            data = json.loads(result.output)
+            assert data['available'] is True
+
+    @staticmethod
+    def test_update_download() -> None:
+        """Update download renders the download result."""
+        dl_result = DownloadResult(success=True, version='2.0')
+        with (
+            patch('synodic_client.cli.context.get_services', return_value=(MagicMock(), None, None)),
+            patch(
+                'synodic_client.operations.update.download_self_update',
+                new_callable=AsyncMock,
+                return_value=dl_result,
+            ),
+        ):
+            result = runner.invoke(app, ['update', 'download'])
+            assert result.exit_code == 0
+
+    @staticmethod
+    def test_update_apply() -> None:
+        """Update apply calls apply_self_update."""
+        with (
+            patch('synodic_client.cli.context.get_services', return_value=(MagicMock(), None, None)),
+            patch('synodic_client.operations.update.apply_self_update') as mock_apply,
+        ):
+            result = runner.invoke(app, ['update', 'apply'])
+            assert result.exit_code == 0
+            assert 'applied' in result.output.lower()
+            mock_apply.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Debug subcommands
+# ---------------------------------------------------------------------------
+
+
+class TestDebugCli:
+    """Tests for synodic-c debug sub-commands."""
+
+    @staticmethod
+    def test_debug_state() -> None:
+        """Debug state prints JSON from IPC."""
+        response = json.dumps({'app': {'version': '1.0.0'}})
+        with (
+            patch('synodic_client.application.instance.SingleInstance') as mock_si,
+            patch('synodic_client.config.set_dev_mode'),
+        ):
+            mock_si.send_debug_command.return_value = response
+            result = runner.invoke(app, ['debug', 'state'])
+            assert result.exit_code == 0
+            data = json.loads(result.output)
+            assert data['app']['version'] == '1.0.0'
+
+    @staticmethod
+    def test_debug_actions() -> None:
+        """Debug actions prints the actions dict."""
+        response = json.dumps({'actions': {'check_update': 'Trigger check.'}})
+        with (
+            patch('synodic_client.application.instance.SingleInstance') as mock_si,
+            patch('synodic_client.config.set_dev_mode'),
+        ):
+            mock_si.send_debug_command.return_value = response
+            result = runner.invoke(app, ['debug', 'actions'])
+            assert result.exit_code == 0
+            data = json.loads(result.output)
+            assert 'actions' in data
+
+    @staticmethod
+    def test_debug_action_with_arg() -> None:
+        """Debug action sends action:<name>:<arg>."""
+        response = json.dumps({'ok': True})
+        with (
+            patch('synodic_client.application.instance.SingleInstance') as mock_si,
+            patch('synodic_client.config.set_dev_mode'),
+        ):
+            mock_si.send_debug_command.return_value = response
+            result = runner.invoke(app, ['debug', 'action', 'add_project', '/tmp/foo'])
+            assert result.exit_code == 0
+            mock_si.send_debug_command.assert_called_once_with('action:add_project:/tmp/foo')
+
+    @staticmethod
+    def test_debug_error_response_exits_1() -> None:
+        """An error response causes exit code 1."""
+        response = json.dumps({'error': 'not found'})
+        with (
+            patch('synodic_client.application.instance.SingleInstance') as mock_si,
+            patch('synodic_client.config.set_dev_mode'),
+        ):
+            mock_si.send_debug_command.return_value = response
+            result = runner.invoke(app, ['debug', 'state'])
+            assert result.exit_code == 1
diff --git a/tool/scripts/dev.py b/tool/scripts/dev.py
deleted file mode 100644
index 8d74c8c..0000000
--- a/tool/scripts/dev.py
+++ /dev/null
@@ -1,37 +0,0 @@
-"""Dev launch script for Synodic Client.
-
-Runs the application directly from source with ``--dev`` mode enabled,
-skipping the PyInstaller build for fast iteration.  Dev mode isolates
-configuration, logs, and the single-instance lock from the user-installed
-application.
-
-Invoked via ``pdm run dev`` or ``pdm run dev -- --uri <URI>``.
-"""
-
-from typing import Annotated
-
-import typer
-
-from synodic_client.application.qt import application
-
-app = typer.Typer(help='Launch Synodic Client from source in dev mode.')
-
-
-@app.command()
-def main(
-    *,
-    uri: Annotated[
-        str | None,
-        typer.Option(help='A synodic:// URI to pass as a command-line argument.'),
-    ] = None,
-) -> None:
-    """Launch the application from source with dev-mode isolation.
-
-    Args:
-        uri: Optional ``synodic://`` URI to pass as a command-line argument.
-    """
-    application(uri=uri, dev_mode=True)
-
-
-if __name__ == '__main__':
-    app()