feat(framework): add maintenance and scoped upgrades

.claude-plugin/marketplace.json

@@ -87,6 +87,15 @@
       "metadata": {
         "recommended": false
       }
+    },
+    {
+      "name": "aidd-maintenance",
+      "source": "./plugins/aidd-maintenance",
+      "description": "Framework maintenance: show the installed marketplace version and update available installations.",
+      "strict": true,
+      "metadata": {
+        "recommended": false
+      }
     }
   ]
 }

.github/workflows/ci.yml

@@ -258,6 +258,7 @@ jobs:
             aidd-ui,
             aidd-telemetry,
             aidd-qa,
+            aidd-maintenance,
           ]
     steps:
       - name: Check if this plugin was released

.release-please-manifest.json

@@ -9,5 +9,6 @@
   "plugins/aidd-ui": "0.2.1-alpha.0",
   "plugins/aidd-telemetry": "0.4.0",
   "plugins/aidd-qa": "1.0.0",
+  "plugins/aidd-maintenance": "0.1.0",
   "cli": "5.6.0"
 }

CONTRIBUTING.md

@@ -63,6 +63,7 @@ Fork the repository, or branch from it if you have write access.
 | `make setup` | Installs dependencies and git hooks, registers the marketplace, installs the plugins into Claude Code and Codex |
 | `make doctor` | Checks your environment |
 | `make reload` | Reloads your checkout into your tools |
+| `make check-hosts` | Tables what each installed tool really loads of the plugins |
 | `make check` | Runs the pre-commit checks |
 
 ## 3. The rules

Makefile

@@ -1,5 +1,5 @@
 .DEFAULT_GOAL := help
-.PHONY: help setup doctor check reload
+.PHONY: help setup doctor check reload check-hosts
 
 help: ## List targets
 	@grep -hE '^[a-z-]+:.*##' $(MAKEFILE_LIST) | sed 's/:.*## /\t/' | sort
@@ -15,6 +15,9 @@ doctor: ## Check the local toolchain
 check: ## Run the pre-commit checks
 	pnpm exec lefthook run pre-commit
 
-reload: ## Dev: reload all plugins into Claude, Codex, OpenCode, Copilot, and Cursor
+reload: ## Dev: reload all plugins into Claude, Codex, OpenCode, Kilo, Copilot, and Cursor via aidd setup --global
 	pnpm --dir cli build
 	scripts/dev-sync.sh
+
+check-hosts: ## Dev: table what each installed tool really loads of the plugins
+	node scripts/check-hosts.cjs

README.md

@@ -11,7 +11,7 @@ Unify **engineering teams** around **standardized workflows** and **shared best
 🧱 **IDE agnostic** · 🏗️ **Legacy systems** · 🌱 **Token-optimized** · 🇫🇷 **Made in France**
 
 <p>
-  <!--counts:start--><kbd>9 plugins</kbd> · <kbd>52 skills</kbd> · <kbd>4 agents</kbd><!--counts:end-->
+  <!--counts:start--><kbd>10 plugins</kbd> · <kbd>53 skills</kbd> · <kbd>4 agents</kbd><!--counts:end-->
 </p>
 
 [![Open Source](https://img.shields.io/badge/Open_Source-Yes-yellow?logo=open-source-initiative&logoColor=white)](https://opensource.org/)
@@ -207,6 +207,18 @@ Acceptance QA with video evidence
 </a>
 </td>
 </tr>
+<tr>
+<td width="33%" valign="top">
+<a href="plugins/aidd-maintenance/README.md">
+<img align="right" alt="preview" src="https://img.shields.io/badge/preview-0969da?style=flat-square" />
+<h3>🔄 aidd-maintenance</h3>
+1 skill · 1 hook<br />
+Framework version and updates
+</a>
+</td>
+<td width="33%"></td>
+<td width="33%"></td>
+</tr>
 </table>
 
 <!--plugins:end-->

aidd_docs/memory/architecture.md

@@ -10,13 +10,13 @@ The macro technical shape: the stack, how the pieces fit, and the decisions behi
 | --- | --- |
 | Product | markdown — skills, agents, rules, templates. No framework runtime; an LLM interprets them. |
 | Delivery | Node `>=22.12`, pnpm. `cli/` is the `aidd` binary; `kanban/` is a private package. |
-| Manifest | `.claude-plugin/marketplace.json`, the plugin manifest: 9 plugins, no version among them. Versions are release-please's, in `deployment.md`. |
+| Manifest | `.claude-plugin/marketplace.json`, the plugin manifest: 10 plugins, no version among them. Versions are release-please's, in `deployment.md`. |
 
 ## How it fits together
 
 ```mermaid
 flowchart LR
-    Manifest[".claude-plugin/marketplace.json"] -->|lists| Plugins["plugins/ · 9"]
+    Manifest[".claude-plugin/marketplace.json"] -->|lists| Plugins["plugins/ · 10"]
     Plugins -->|ships| Surfaces["skills · agents · commands · hooks · rules"]
     CLI["cli/ · aidd"] -->|reads| Manifest
     CLI -->|installs| Target["a project's AI tool dir"]
@@ -40,6 +40,6 @@ The concern-to-plugin taxonomy is canonical in [`docs/ARCHITECTURE.md`](../../do
 
 ## Gotchas
 
-- 9 plugins ship, 3 off the curated install path: `aidd-ui` is alpha, `aidd-telemetry` beta and opt-in, `aidd-qa` new and unproven outside this repository.
+- 10 plugins ship, 3 off the curated install path: `aidd-ui` is alpha, `aidd-telemetry` beta and opt-in, `aidd-qa` new and unproven outside this repository.
 - A skill never links outside itself: the tree ships both flat and as a marketplace, so no relative path survives both.
 - Bundled hooks run Node. No `node` on `PATH`, no memory refresh and no question about the task.

aidd_docs/memory/deployment.md

@@ -58,15 +58,15 @@ flowchart TD
 - The umbrella stays a draft until every asset is attached; its publication is the event n8n listens to.
 - A failed video build keeps the release a draft, so nothing is announced without its video. A failed YouTube upload does not stop Discord and Skool: they post without the video link. Their text is the video's programme, one section per theme, so the announcements say what the video shows.
 
-Config: `release-please-config.json`, eleven packages. Manifest: `.release-please-manifest.json`.
+Config: `release-please-config.json`, twelve packages. Manifest: `.release-please-manifest.json`.
 
 ## Gotchas
 
 - `build-per-tool` builds the CLI from this run's own checkout (`pnpm build`, then `node cli/dist/cli.js translate`), never a pinned published version: nothing to bump, nothing to go stale.
 
 ## Local reload
 
-`make reload` syncs all plugins and generic delegation guidance to installed hosts; details in `scripts/dev-sync.sh`.
+`make reload` installs every plugin into the installed hosts with `aidd setup --global` from this checkout, then syncs generic delegation guidance; details in `scripts/dev-sync.sh`.
 
 ## Monitoring
 

aidd_docs/memory/project-brief.md

@@ -33,7 +33,7 @@ What this project is, the problem it solves, and its domain language. The non-de
 
 | Capability | Entry |
 | --- | --- |
-| Install and refresh a tool's configuration | `aidd setup --ai <ids> --ide <ids>` |
+| Install and refresh a tool's configuration | `aidd setup --ide <ids>`; `--global` for every project on the machine |
 | Install plugins from a marketplace | `aidd plugin install`, `aidd marketplace add` |
 | Build a target-native distribution | `aidd translate <source> --to <tool> --out <dir>` |
 | Bootstrap and refresh project memory | `aidd-context:02-project-memory` |

cli/README.md

@@ -25,13 +25,19 @@ Check: `aidd --version`.
 
 | Step | Run |
 | --- | --- |
-| Bootstrap the project | `aidd setup --ai claude --ide vscode --plugins recommended --yes` |
+| Bootstrap the project | `aidd setup --ide claude,vscode --plugins recommended --yes` |
 | Add a plugin | `aidd plugin install aidd-dev` |
 | Check the state | `aidd doctor` |
 | Restore owned files | `aidd sync` |
 | Update the CLI | `aidd update` |
 
 `setup` writes the manifest, the default marketplace, the tool configs and the plugins.
+`--global` installs for the machine instead, and writes nothing under the project.
+
+| Command | Lands in |
+| --- | --- |
+| `aidd setup --ide claude` | `.claude/` and `.aidd/` in this project |
+| `aidd setup --global --ide opencode --plugins all` | `~/.config/opencode/` and `~/.config/aidd/`, nothing in this project |
 
 ## Commands
 
@@ -46,13 +52,14 @@ Every flag: `aidd --help`, then a group's own `--help`.
 | `aidd sync` | Rewrite owned files from the manifest, then re-drive native activation |
 | `aidd clean` | Remove every AIDD-managed file from the project |
 | `aidd update` | Update the CLI itself (alias `upgrade`) |
+| `aidd run opencode -- <args>` / `aidd run kilo -- <args>` | Run headless with the installed maintenance notice on stderr |
 
 ### Framework
 
 | Command | Does |
 | --- | --- |
 | `aidd framework install` | Write one tool's runtime configuration from the bundled assets |
-| `aidd framework update` | Move installed tools to this CLI's assets (all of them without `--tool`) |
+| `aidd framework update` | Update tool configs from this CLI; `--release <tag>` updates project plugins after confirmation, or global flat copies with `--scope user` |
 | `aidd framework remove` | Delete the generated configuration files of one tool |
 | `aidd framework rules` | List the rules installed across every AI tool (`--json` for a machine) |
 
@@ -101,31 +108,39 @@ Counts the tokens of Claude Code and Codex sessions, locally. Details: [FAQ](../
 
 ## Scope
 
-`setup`, `doctor`, `sync` and `clean` accept `--scope <project|user>`.
+`setup`, `doctor`, `sync` and `clean` accept `--global`, or its former spelling `--scope user`.
 
 | Scope | Acts on |
 | --- | --- |
-| `project` (default) | This project alone |
-| `user` | The machine: registers the framework source and supported tools, writes nothing under the project |
+| project (default) | This project alone |
+| `--global` | Every project on the machine; writes nothing under the project |
 
-`setup --scope user` needs:
+`setup --global` needs:
 
-- An explicit `--ai` list of supported tools (`--ai all` is refused).
-- `--plugins none`, or no `--plugins` in a scripted run.
-- No `--ide`.
+- An explicit `--ide` list of supported tools, no editor (`--ide all` is refused).
+- `--plugins all`, `recommended`, `none` or comma-separated names.
 
-| Tool | `setup --scope user` |
+| Tool | `setup --global --plugins …` |
 | --- | --- |
-| `claude`, `codex`, `copilot` | Registers the source and drives the tool's own CLI |
-| `cursor` | Records the source and tool only, no native activation |
-| `opencode`, `kilo` | Unsupported: use project scope |
+| `claude`, `copilot` | Registers the source and enables the plugins through the tool's own CLI |
+| `codex` | The same, plus the plugins' agents in `~/.codex/agents/` |
+| `opencode`, `kilo` | Copies the plugins' skills and agents into `~/.config/opencode/` or `~/.config/kilo/` |
+| `cursor` | Copies the plugins into `~/.cursor/plugins/local/`; Cursor must allow local plugin imports |
+
+Files without recorded AIDD ownership are refused even when their content matches. This includes
+copies from an older `make reload`, or files left by an interrupted install before ownership was
+saved. Move the named files aside, then rerun the original setup or reload command.
+
+Copilot needs a CLI whose `plugin marketplace list` accepts `--json` (verified with 1.0.98; 1.0.83 refuses it).
 
 Native activation needs the tool's executable on `PATH`.
 Without it, registration succeeds with a warning and activation stays unrun.
-Install it, then run `aidd sync --scope user`.
+Install it, then rerun the original `aidd setup --global` command with its `--ide` and `--plugins` selections.
 
 ```sh
-aidd setup --scope user --ai claude,codex,copilot --plugins none --yes
+aidd setup --global --ide claude,codex,copilot,cursor,kilo,opencode --plugins all --yes
+aidd sync --global    # rebuild the copied files and refresh the hosts from the framework source
+aidd clean --global --force   # remove what --global installed and purge the shared source; without --force it previews or asks
 ```
 
 ## Authentication
@@ -137,6 +152,8 @@ Needed for a private marketplace only.
 | `stored` | The token itself | `--token <value>` |
 | `external` | The provider name. The token is asked from it at fetch time | `--gh` |
 
+For Git clones, AIDD sends these tokens only to `github.com`. Configure a [Git credential helper](https://git-scm.com/docs/gitcredentials) for GitLab, Bitbucket or other hosts (documentation read 2026-11-06).
+
 The token resolves from the first hit:
 
 1. `AIDD_TOKEN`
@@ -175,7 +192,7 @@ The token resolves from the first hit:
 
 | Variable | Effect |
 | --- | --- |
-| `AIDD_TOKEN` | Token for every fetch, ahead of any stored credential |
+| `AIDD_TOKEN` | GitHub token, ahead of any stored credential |
 | `AIDD_USER_CONFIG_DIR` | Relocates the user config directory, credentials included |
 | `XDG_CONFIG_HOME` | Names the config root when `AIDD_USER_CONFIG_DIR` is unset |
 | `AIDD_SKIP_UPDATE_CHECK` | `1` skips the self-update check before a command |
@@ -201,7 +218,7 @@ Under `$AIDD_USER_CONFIG_DIR`, else `$XDG_CONFIG_HOME/aidd`, else `~/.config/aid
 | `auth.json` | The user-level credential |
 | `marketplaces.json` | The user-scope registry |
 | `references.json` | The projects claiming it |
-| `manifest.json` | What `--scope user` owns |
+| `manifest.json` | What `--global` owns |
 | `cache/built/<version>/` | One built tree per CLI version |
 
 ### Settings written per tool

cli/aidd_docs/memory/architecture.md

@@ -51,3 +51,4 @@ flowchart LR
 - Configs are inlined at build time, schemas are not: five JSON files ship beside the binary. Drop them from `files` and the CLI breaks.
 - The build empties its output directory; `AIDD_BUILD_OUT_DIR` accepts two shapes only.
 - `git` exports `GIT_*` into everything it spawns. Strip them before reading a repository.
+- User-lock recovery requires the same boot and process namespace. References read 2026-11-05: [Linux kernel identity](https://kernel.org/doc/html/v6.6/admin-guide/sysctl/kernel.html), [Darwin boot session](https://github.com/apple/darwin-xnu/blob/main/iokit/IOKit/pwr_mgt/IOPM.h). Windows recovery is not verified and refuses to reap an owner.

cli/aidd_docs/memory/cli.md

@@ -8,6 +8,7 @@ Thirty leaf commands. Read them live: `aidd --help`, then each group's. `scripts
 
 - `setup`, `doctor`, `sync`, `clean`: bring a project to a correct state, keep it there.
 - `framework install | update | remove | rules`, chosen by `--tool <id>`.
+- `framework update --release <tag>` lists project plugin/tool pairs and asks before updating their source; `--yes` accepts non-interactively, and `--allow-shared` separately approves a shared marketplace.
 - `plugin install | list | remove | search | update`.
 - `marketplace add | list | remove | refresh | check`.
 - `auth login | logout | status`.

cli/aidd_docs/memory/codebase-map.md

@@ -22,6 +22,8 @@ src/
 │   │   │   ├── install/
 │   │   │   │   └── content/
 │   │   │   ├── ownership/    # machine plugin claims and safe project detach
+│   │   │   │   ├── release/  # recoverable machine release updates
+│   │   │   │   └── tui/      # owned startup TUI configuration
 │   │   │   ├── plugin/
 │   │   │   ├── recipes/
 │   │   │   ├── restore/
@@ -91,7 +93,8 @@ src/
 │   ├── ports/    # a port two or more contexts both need
 │   └── reading/    # getting at a file's location and its content safely
 ├── presentation/    # everything that talks to a human — depends on contexts, never the reverse
-│   ├── commands/    # one file per command, wiring only
+│   ├── commands/    # command wiring
+│   │   └── run/    # headless tool launcher
 │   ├── display/    # rendering a result
 │   │   └── telemetry/    # the telemetry report, which outgrew one file beside the others
 │   └── prompts/    # asking the user; the decision stays in the context

cli/aidd_docs/memory/internal/decisions/framework-source-is-machine-scope.md

@@ -47,15 +47,16 @@ One registration of `aidd-framework` per machine, shared by every project. Read
 
 ## `setup --scope user`
 
-- Registers the shared local source; native machine-wide activation requires verified current host source/ref proof. Unsupported Copilot versions refuse it.
+- Registers the shared local source; native machine-wide activation requires verified current host source/ref proof. Copilot proves its source through `plugin marketplace list --json` (1.0.98); a version rejecting `--json` (1.0.83) refuses it.
 - Writes nothing under `projectRoot`: no content, no plugin prompt, no gitignore touch.
+- `--plugins all|recommended|<names>` picks plugins from the shared source's catalog. A tool with native activation gets them through `MarketplaceSyncSettingsOptions.enablePlugins`; a tool declaring `PluginsCapability.globalFiles` (opencode's and kilo's skills and agents, codex's agents) or installing into a user plugins directory (cursor) gets them copied there as `scope: "user"` plugins, written by `UserPluginFileUpdater`, so `sync --scope user` rebuilds them and `clean --scope user` removes them. An interactive pick is refused (`UserScopePluginModeError`).
 - Its manifest: `userManifestPath(userConfigDir())`, `userConfigDir()/manifest.json`, same schema and version as the project one.
 - `UserManifestRepositoryAdapter` reuses `Manifest.fromJSON`/`toJSON`; its `delete()` removes that one file only.
 - Each AI tool gets a manifest entry with an empty file list, so `MarketplaceSyncSettingsUseCase` has something to iterate.
 - Records no `references.json` claim: absence is the state until `clean --scope user`.
 - `doctor --scope user` runs only `DoctorRegistrationUseCase`.
-- `sync --scope user` resolves the same manifest.
+- `sync --scope user` resolves the same manifest, rebuilds its `scope: "user"` plugin files, then drives native activation.
 - `--scope <project|user>` on all three, default `project`.
 - Refuses an `--ide` tool (`UserScopeIdeToolsError`): IDE config is project-relative.
-- Refuses an AI tool without machine-wide activation (`UserScopeUnsupportedAiToolsError`; `registry.ts`'s `supportsUserScopeActivation`, false for opencode alone).
+- Refuses an AI tool without machine-wide activation (`UserScopeUnsupportedAiToolsError`; `registry.ts`'s `supportsUserScopeActivation`); every registered AI tool supports it today.
 - Both refusals fire in `SetupFlow`'s constructor; `--ai all` is unusable at this scope.

cli/aidd_docs/memory/testing.md

@@ -22,7 +22,7 @@ How this package is tested: the layers, the tools, the conventions.
 - Doubles from `tests/helpers/ports/`. Substitute at the seam; never mock functional behaviour.
 - Fixtures in `tests/fixtures/`, read-only, excluded from JSON and link checks. Mutate a copy in a temp directory.
 - `.gitattributes`'s `tests/fixtures/** text eol=lf` keeps byte-for-byte comparisons (`manifest-round-trip.unit.test.ts`) passing on Windows.
-- A temp directory: `await mkdtemp(join(tmpdir(), "aidd-<thing>-"))`, never a fixed name (a plantable symlink). The prefix is what `scripts/sweep-stale-test-dirs.cjs` reclaims.
+- A temp directory: `await mkdtemp(join(tmpdir(), "aidd-<thing>-"))`, never a fixed name (a plantable symlink). Clean up only the directory the test created.
 - A test name is a phrase of observable behaviour; nested `describe` reads as a sentence. `E2E:` is a recurring legacy prefix, not one to copy.
 - A golden snapshot is machine-independent, never derived from an absolute path: [`golden-machine-independence.md`](../../.claude/skills/test/references/golden-machine-independence.md).
 - `describe.concurrent` appears in no unit or integration file; in e2e the golden and command-matrix suites use it. An observed split, not a rule.

cli/package.json

@@ -36,7 +36,7 @@
     "node": ">=22.12"
   },
   "packageManager": "pnpm@12.16.1",
-  "bundleBudgetKB": 722,
+  "bundleBudgetKB": 826,
   "scripts": {
     "build": "tsup && node scripts/check-bundle-size.mjs",
     "build:check-size": "node scripts/check-bundle-size.mjs",
@@ -86,6 +86,8 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "commander": "^15.0.0",
+    "cross-spawn": "7.0.6",
+    "jsonc-parser": "^3.3.1",
     "simple-git": "^4.0.2",
     "smol-toml": "^1.6.1"
   },
@@ -95,6 +97,7 @@
     "@commitlint/config-conventional": "^21.2.0",
     "@stryker-mutator/core": "^10.0.0",
     "@stryker-mutator/vitest-runner": "^10.0.0",
+    "@types/cross-spawn": "6.0.6",
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^5.0.0",
     "fast-check": "^4.7.0",