feat(cli): install the framework for every project with setup --global

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

aidd_docs/memory/deployment.md

@@ -66,7 +66,7 @@ Config: `release-please-config.json`, eleven packages. Manifest: `.release-pleas
 
 ## 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
 
@@ -101,31 +107,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
@@ -201,7 +215,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/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/package.json

@@ -36,7 +36,7 @@
     "node": ">=22.12"
   },
   "packageManager": "pnpm@12.16.1",
-  "bundleBudgetKB": 722,
+  "bundleBudgetKB": 747,
   "scripts": {
     "build": "tsup && node scripts/check-bundle-size.mjs",
     "build:check-size": "node scripts/check-bundle-size.mjs",

cli/scripts/check-bundle-size.mjs

@@ -55,6 +55,8 @@ const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
 // (+5.2 KB over its 712.9 KB skills profile); 0.3% measured headroom.
 // 722 KB: 720.2 KB, Antigravity portable agents and direct-local installation
 // (+2.1 KB over its 718.1 KB hooks build); 0.3% measured headroom.
+// 747 KB: 732.4 KB, the machine-wide install of `setup --global` (+12.2 KB over the 720.2 KB
+// above); 2.0% measured headroom.
 const budgetKB = pkg.bundleBudgetKB ?? 500;
 const budgetBytes = budgetKB * 1024;
 

cli/scripts/smoke-real.sh

@@ -167,11 +167,12 @@ PROJ_U=$(mktemp -d "$TMPROOT/proj-user.XXXXXX")
 (cd "$PROJ_U" && git init -q)
 
 # `setup --scope user` exits 1 for a tool declaring no machine-wide activation
-# (`registry.ts`'s `supportsUserScopeActivation`; opencode today), before anything is
+# (`registry.ts`'s `supportsUserScopeActivation`; none today), before anything is
 # written — so the machine-scope phases carry their own tool list, never `ai_list`.
+# kilo is listed for parity but never measured: `AI_TOOLS` does not probe for it.
 user_ai_list() {
   local ids=()
-  for t in claude codex copilot cursor; do
+  for t in claude codex copilot cursor kilo opencode; do
     [[ -n "${PRESENT[$t]:-}" ]] && ids+=("$t")
   done
   (IFS=,; echo "${ids[*]}")

cli/src/contexts/distribution/application/marketplace-refresh-use-case.ts

@@ -1,5 +1,4 @@
 import { join, resolve } from "node:path";
-import { marketplaceCacheDir } from "../../../kernel/paths.js";
 import type { FileReader } from "../../../kernel/ports/file-reader.js";
 import type { Logger } from "../../../kernel/ports/logger.js";
 import {
@@ -61,7 +60,7 @@ export class MarketplaceRefreshUseCase implements MarketplaceRefresh {
   // through the result, never thrown.
   private async refreshOne(projectRoot: string, m: Marketplace): Promise<RefreshEntryResult> {
     try {
-      const cacheDir = marketplaceCacheDir(projectRoot, m.name);
+      const cacheDir = this.resolveMarketplace.cacheDirOf(m, projectRoot);
       await this.warnIfStale(m.name, cacheDir);
       this.logger?.info(`Fetching marketplace '${m.name}'...`);
       const { catalog } = await this.resolveMarketplace.execute({

cli/src/contexts/distribution/application/resolve-marketplace-use-case.ts

@@ -1,4 +1,4 @@
-import { marketplaceCacheDir } from "../../../kernel/paths.js";
+import { fetchedMarketplaceDir } from "../../../kernel/paths.js";
 import type { PluginCatalog } from "../domain/catalog.js";
 import type { Marketplace } from "../domain/marketplace.js";
 import type { PluginCatalogRepository } from "../domain/ports/plugin-catalog-repository.js";
@@ -24,11 +24,12 @@ export interface ResolveMarketplace {
 export class ResolveMarketplaceUseCase implements ResolveMarketplace {
   constructor(
     private readonly fetchMarketplaceSource: FetchMarketplaceSourceUseCase,
-    private readonly catalogRepo: PluginCatalogRepository
+    private readonly catalogRepo: PluginCatalogRepository,
+    private readonly userConfigDir?: () => string
   ) {}
 
   async execute(options: ResolveMarketplaceOptions): Promise<ResolveMarketplaceResult> {
-    const cacheDir = marketplaceCacheDir(options.projectRoot, options.marketplace.name);
+    const cacheDir = this.cacheDirOf(options.marketplace, options.projectRoot);
     const localPath = await this.fetchMarketplaceSource.execute({
       marketplace: options.marketplace,
       cacheDir,
@@ -37,4 +38,8 @@ export class ResolveMarketplaceUseCase implements ResolveMarketplace {
     const catalog = await this.catalogRepo.load(localPath);
     return { marketplace: options.marketplace, localPath, catalog };
   }
+
+  cacheDirOf(marketplace: Marketplace, projectRoot: string): string {
+    return fetchedMarketplaceDir(marketplace, projectRoot, this.userConfigDir?.());
+  }
 }

cli/src/contexts/framework/application/clean-use-case.ts

@@ -272,7 +272,8 @@ export class CleanUseCase {
           this.hostPluginRegistries.get(toolId),
           registration.hostName,
           new Set([...registrations.pluginRefs, ...machineRefs]),
-          projectRoot
+          projectRoot,
+          toolId
         );
       }
     }
@@ -604,7 +605,8 @@ export class CleanUseCase {
         reader,
         sourceRegistration.hostName,
         new Set([...registrations.pluginRefs, ...machineRefs]),
-        projectRoot
+        projectRoot,
+        toolId
       );
     } catch (error) {
       this.logger.warn(`${binary}: '${ref}' left enabled; ${String(error)}`);

cli/src/contexts/framework/application/clean/clean-user-scope-use-case.ts

@@ -327,7 +327,8 @@ export class CleanUserScopeUseCase {
           this.hostPluginRegistries.get(toolId),
           registration.hostName,
           owned,
-          projectRoot
+          projectRoot,
+          toolId
         );
         for (const ref of refsByHost.get(registration.hostName) ?? []) {
           if (hostRefs.get(ref)?.enabled !== true)
@@ -419,6 +420,15 @@ export class CleanUserScopeUseCase {
     await this.purgeWhitelistedPath("cache/built", "cache/built", (candidate) =>
       this.fs.deleteDirectory(candidate)
     );
+    // Other user marketplaces keep their registered sources. Plugin fetches belong to the
+    // machine manifest being removed, whose active dependents were checked before any purge.
+    const frameworkSource = `cache/marketplaces/${FRAMEWORK_MARKETPLACE_NAME}`;
+    for (const path of [frameworkSource, "cache/plugin-cache"]) {
+      await this.purgeWhitelistedPath(path, path, (candidate) =>
+        this.fs.deleteDirectory(candidate)
+      );
+    }
+    await this.purgeEmptyCacheShell("cache/marketplaces");
     // The self-update check cache, written into the same `cache/` directory by any online
     // command: left behind it keeps the shell below non-empty, the one occupant that made
     // "leaves nothing of aidd's on the machine" false in the ordinary case.
@@ -444,17 +454,15 @@ export class CleanUserScopeUseCase {
     await this.userManifestRepo.delete();
   }
 
-  /** `cache/built/` and `cache/update-check.json` are this whitelist's only occupants of
-   * `userConfigDir()/cache/`. The shell around them is removed only once proven empty, under the
-   * same containment as every other candidate — never assumed from having just purged its only
-   * children, since a future writer under `cache/` would make that assumption stale silently. */
-  private async purgeEmptyCacheShell(): Promise<void> {
+  /** Remove a cache directory only once proven empty, with the same containment as every
+   * whitelist candidate: another marketplace or a future cache writer may still use it. */
+  private async purgeEmptyCacheShell(path = "cache"): Promise<void> {
     const candidate = await resolveCacheCandidate(
       this.fs,
       this.logger,
       this.userConfigDir(),
-      "cache",
-      "user scope: cache"
+      path,
+      `user scope: ${path}`
     );
     if (candidate === null) return;
     let entries: string[];
@@ -466,7 +474,7 @@ export class CleanUserScopeUseCase {
     }
     if (entries.length > 0) return;
     await this.fs.deleteDirectory(candidate);
-    this.logger.info(`user scope: cache purged: ${candidate}`);
+    this.logger.info(`user scope: ${path} purged: ${candidate}`);
   }
 
   /** Never `userConfigDir()` itself, and never on a manifest's word: every fixed whitelist entry

cli/src/contexts/framework/application/doctor/doctor-registration-use-case.ts

@@ -35,6 +35,8 @@ export interface DoctorRegistrationOptions {
   manifest: Manifest;
   projectRoot: string;
   allowedIds: Set<string> | null;
+  /** A global install declares nothing in a project's settings, so it skips that check. */
+  globalInstall?: boolean;
 }
 
 /** One plugin `doctor` expects a native-activation tool's own registry to carry, and the ref to
@@ -84,7 +86,7 @@ export class DoctorRegistrationUseCase {
 
   async execute(options: DoctorRegistrationOptions): Promise<DoctorIssue[]> {
     return [
-      ...(await this.checkDeclaredMarketplaces(options)),
+      ...(options.globalInstall === true ? [] : await this.checkDeclaredMarketplaces(options)),
       ...(await this.checkNativeRegistrations(options)),
       ...(await this.checkMarketplaceSources(options)),
     ];