kushi-agents 5.0.0 → 5.0.2

package/README.md

@@ -5,6 +5,11 @@
 [![license](https://img.shields.io/npm/l/kushi-agents.svg)](LICENSE)
 [![host: Clawpilot](https://img.shields.io/badge/host-Clawpilot-7c9cff)](https://gim-home.github.io/kushi/)
 [![host: VS Code](https://img.shields.io/badge/host-VS%20Code-007acc)](https://gim-home.github.io/kushi/)
+[![spec: agentskills.io](https://img.shields.io/badge/spec-agentskills.io-22c55e)](https://agentskills.io/skill-creation/best-practices)
+
+> **v5.0.1 spec-compliance pass.** Every `plugin/skills/<name>/SKILL.md` follows the [agentskills.io best practices](https://agentskills.io/skill-creation/best-practices) and [optimizing-descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) guides: ≤ 500 lines & ≤ 5000 tokens, load-on-trigger references, top-5 gotchas, checklist orchestrators, validation loops, plan-validate-execute for graph + State writers, and "USE WHEN …" descriptions. Enforced by `self-check -Deep` D30.*.
+
+> **Project lineage:** for the *why* behind each release — what built on what, what trade-offs were accepted, what external work inspired which design — see [`docs/genealogy.md`](docs/genealogy.md). Every release MUST add an entry there before tagging (enforced by `self-check` D31.genealogy).
 
 > A multi-skill GitHub Copilot agent for grounded engagement evidence — across Email, Teams, Meetings, OneNote, SharePoint, Dataverse (CRM), and Azure DevOps.
 
@@ -116,20 +121,38 @@ See [Quickstart](https://gim-home.github.io/kushi/getting-started/quickstart/) f
 
 ## Install
 
-Two install targets — pick the one that matches how you talk to Copilot, optionally combined with a profile.
+Kushi supports **two host surfaces** as first-class peers (v5.0.2+):
 
-**VS Code Chat** — `.kushi/` in your workspace:
+| Host                                  | Install path                       | Best for                                |
+|---------------------------------------|------------------------------------|-----------------------------------------|
+| **Clawpilot CLI**                     | `~/.copilot/m-skills/kushi/`       | Scheduled / overnight runs (e.g. `kushi refresh <project>` at 6 AM via automation) |
+| **VS Code Chat** ("GitHub Copilot Chat") | `~/.vscode/chat/skills/kushi/`     | Interactive use (`@kushi what's the MACC for X?`) |
+
+Both hosts read the **same** Evidence/ tree on disk, so a refresh from one is immediately visible from the other — the same user routinely lives in both. SKILL content is host-agnostic (no per-host branching, enforced by self-check `D32.multi-host`).
 
 ```bash
-npx kushi-agents                               # default profile (standard)
-npx kushi-agents --profile core                # aggregator only
+# Install to a single host
+npx kushi-agents --clawpilot                       # Clawpilot only
+npx kushi-agents --vscode                          # VS Code Chat only
+
+# Install to BOTH at once (auto-detects what's present + targets both)
+npx kushi-agents --all-hosts
+
+# Uninstall
+npx kushi-agents --uninstall                       # all detected hosts
+npx kushi-agents --uninstall --clawpilot           # Clawpilot only
+npx kushi-agents --uninstall --vscode              # VS Code Chat only
+npx kushi-agents --uninstall --all                 # both
+
+# Legacy workspace install (per-project .kushi/ in cwd)
+npx kushi-agents                                   # default = standard profile
+npx kushi-agents --profile core                    # aggregator only
 ```
 
-**Clawpilot CLI** — `~/.copilot/m-skills/kushi/`:
+The 2-host matrix is a deliberate cap — see [`plugin/instructions/multi-host-install.instructions.md`](plugin/instructions/multi-host-install.instructions.md) for the rationale + per-host layout details.
 
 ```bash
-npx kushi-agents --clawpilot
-npx kushi-agents --clawpilot --profile full
+npx kushi-agents --clawpilot --profile full        # everything
 ```
 
 To switch profiles later, re-run with `--force` (cleanly handles downgrades):

package/bin/cli.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { main } from '../src/main.mjs';
+import { runMultiHost } from '../src/multi-host.mjs';
 
 const args = process.argv.slice(2);
 
@@ -10,72 +11,99 @@ if (args.includes('--help') || args.includes('-h')) {
 
   Installs the Kushi multi-source project-evidence + Q&A agent.
 
-  Targets (pick one — default is vscode):
-    --target vscode     Install to <cwd>/.kushi/ + update .vscode/settings.json
-    --target clawpilot  Install to ~/.copilot/m-skills/kushi/ for Clawpilot CLI
-    --clawpilot         Shortcut for --target clawpilot
+  Host installs (v5.0.2+ — install into a host's user-global skill folder):
+    --clawpilot       Install to ~/.copilot/m-skills/kushi/
+    --vscode          Install to ~/.vscode/chat/skills/kushi/  (a.k.a. GitHub Copilot Chat)
+    --all-hosts       Install to BOTH hosts
+    --uninstall [--clawpilot|--vscode|--all]
+                      Cleanly remove the kushi install + skills-metadata.json entry
+                      from the chosen host(s). Default = all detected hosts.
+
+  Workspace install (legacy / default when no host flag is given):
+    --target vscode     Install to <cwd>/.kushi/ + update .vscode/settings.json   [default]
+    --target clawpilot  Alias for --clawpilot (kept for back-compat)
 
   Profile (controls what gets installed):
-    --profile core      Aggregator only (pull + consolidate + ask). The
-                        Evidence/ folder is the public contract; suitable for
-                        external rollup integrations.
-    --profile standard  Core + State/ rollup (Kushi's default opinion).  [DEFAULT]
-    --profile full      Standard + report packs (FDE weekly/customer/handoff).
+    --profile core      Aggregator only (pull + consolidate + ask).
+    --profile standard  Core + State/ rollup.                          [DEFAULT]
+    --profile full      Standard + report packs.
 
   Options:
     --force             Overwrite existing destination without asking
-    --yes, -y           Skip the project-root check (useful for scripted or
-                        agent-driven installs)
-    --no-settings       Skip .vscode/settings.json update (vscode target only)
-    --no-instructions   Skip .github/copilot-instructions.md merge (vscode target only)
+    --yes, -y           Skip the project-root check
+    --no-settings       Skip .vscode/settings.json update (vscode workspace target only)
+    --no-instructions   Skip .github/copilot-instructions.md merge   (vscode workspace target only)
 
   WorkIQ (REQUIRED — Kushi cannot pull evidence without it):
     --with-workiq           Auto-install WorkIQ via winget (Windows) / brew (macOS)
     --workiq-path <abs>     Use this explicit path to the workiq binary
-    --skip-workiq-check     Bypass the WorkIQ pre-flight check (CI / inspection only —
-                            bootstrap/refresh will block until WorkIQ is installed)
+    --skip-workiq-check     Bypass the WorkIQ pre-flight check
 
     --help, -h          Show this help
 
   After install, talk to Kushi:
-    aggregate <project>     Pull + consolidate (no State/) — all profiles
-    bootstrap <project>     First-time setup, 30d initial pull        — standard+
-    refresh <project>       Incremental refresh + rebuild State/      — standard+
-    state <project>         Re-render State/ from existing Evidence   — standard+
-    consolidate <project>   Merge per-user evidence                   — all profiles
-    status <project>        Show run-log                              — all profiles
-    ask <project> <q>       Cited Q&A over Evidence/ (auto-routes)    — all profiles
+    bootstrap <project>     First-time setup
+    refresh <project>       Incremental refresh + rebuild State/
+    state <project>         Re-render State/ from existing Evidence
+    consolidate <project>   Merge per-user evidence
+    status <project>        Show run-log
+    ask <project> <q>       Cited Q&A over Evidence/ (auto-routes)
 
   In VS Code Chat the prefix is "@Kushi". In Clawpilot just say "kushi <verb>".
 `);
   process.exit(0);
 }
 
-let target = getFlag('--target');
-if (args.includes('--clawpilot')) {
-  if (target && target !== 'clawpilot') {
-    console.error(`\n  Conflicting flags: --target ${target} and --clawpilot.\n`);
+// ── multi-host mode (v5.0.2+) ───────────────────────────────────────────────
+// Trigger when the user passes any of: --vscode, --all-hosts, --uninstall.
+// --clawpilot ALONE continues to route through the legacy main.mjs path so
+// the existing target=clawpilot flow stays byte-identical.
+const wantsVscode = args.includes('--vscode');
+const wantsAllHosts = args.includes('--all-hosts');
+const wantsUninstall = args.includes('--uninstall');
+
+if (wantsVscode || wantsAllHosts || wantsUninstall) {
+  const hosts = [];
+  if (args.includes('--clawpilot')) hosts.push('clawpilot');
+  if (wantsVscode) hosts.push('vscode');
+  const all = wantsAllHosts || args.includes('--all');
+
+  runMultiHost({
+    hosts,
+    all,
+    uninstall: wantsUninstall,
+    profile: getFlag('--profile'),
+  }).catch((err) => {
+    console.error(`\n  ${err.message}\n`);
     process.exit(1);
+  });
+} else {
+  let target = getFlag('--target');
+  if (args.includes('--clawpilot')) {
+    if (target && target !== 'clawpilot') {
+      console.error(`\n  Conflicting flags: --target ${target} and --clawpilot.\n`);
+      process.exit(1);
+    }
+    target = 'clawpilot';
   }
-  target = 'clawpilot';
-}
 
-const options = {
-  force: args.includes('--force'),
-  yes: args.includes('--yes') || args.includes('-y'),
-  noSettings: args.includes('--no-settings'),
-  noInstructions: args.includes('--no-instructions'),
-  target,
-  profile: getFlag('--profile'),
-  withWorkiq: args.includes('--with-workiq'),
-  workiqPath: getFlag('--workiq-path'),
-  skipWorkiqCheck: args.includes('--skip-workiq-check'),
-};
-
-main(options).catch((err) => {
-  console.error(`\n  ${err.message}\n`);
-  process.exit(1);
-});
+  const options = {
+    force: args.includes('--force'),
+    yes: args.includes('--yes') || args.includes('-y'),
+    noSettings: args.includes('--no-settings'),
+    noInstructions: args.includes('--no-instructions'),
+    target,
+    profile: getFlag('--profile'),
+    withWorkiq: args.includes('--with-workiq'),
+    workiqPath: getFlag('--workiq-path'),
+    skipWorkiqCheck: args.includes('--skip-workiq-check'),
+  };
+
+  main(options).catch((err) => {
+    console.error(`\n  ${err.message}\n`);
+    process.exit(1);
+  });
+}
 
 function getFlag(flag) {
   const idx = args.indexOf(flag);
@@ -85,4 +113,4 @@ function getFlag(flag) {
   const prefix = flag + '=';
   const match = args.find((a) => a.startsWith(prefix));
   return match ? match.slice(prefix.length) : undefined;
-}
+}

package/package.json

@@ -1,52 +1,52 @@
-{
-  "name": "kushi-agents",
-  "version": "5.0.0",
-  "description": "Install Kushi — multi-source project evidence agent with Comprehensive Structured Capture (CSC) into weekly-only files across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. Meetings retain a sibling verbatim/ audit folder. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
-  "type": "module",
-  "bin": {
-    "kushi-agents": "./bin/cli.mjs"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "plugin/",
-    ".github/copilot-instructions.kushi.md"
-  ],
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@mozilla/readability": "^0.6.0",
-    "jsdom": "^29.1.1",
-    "jsonc-parser": "^3.3.1"
-  },
-  "keywords": [
-    "vscode",
-    "copilot",
-    "agents",
-    "kushi",
-    "project-evidence",
-    "workiq",
-    "m365",
-    "ai",
-    "cli"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/gim-home/kushi.git"
-  },
-  "homepage": "https://gim-home.github.io/kushi/",
-  "bugs": {
-    "url": "https://github.com/gim-home/kushi/issues"
-  },
-  "license": "MIT",
-  "scripts": {
-    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs src/sanitize-workiq-input.test.mjs src/detect-vertex-repo.test.mjs src/vertex-validate.test.mjs src/emit-vertex.e2e.test.mjs src/config-root-resolve.test.mjs src/forbidden-workiq-phrasings.test.mjs",
-    "test:integration:bootstrap": "node src/bootstrap-dryrun.integration.test.mjs",
-    "smoke": "node scripts/smoke.mjs",
-    "prepublishOnly": "npm test && npm run smoke"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
+{
+  "name": "kushi-agents",
+  "version": "5.0.2",
+  "description": "Install Kushi — multi-source project evidence agent with Comprehensive Structured Capture (CSC) into weekly-only files across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. Meetings retain a sibling verbatim/ audit folder. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
+  "type": "module",
+  "bin": {
+    "kushi-agents": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "plugin/",
+    ".github/copilot-instructions.kushi.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "jsdom": "^29.1.1",
+    "jsonc-parser": "^3.3.1"
+  },
+  "keywords": [
+    "vscode",
+    "copilot",
+    "agents",
+    "kushi",
+    "project-evidence",
+    "workiq",
+    "m365",
+    "ai",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gim-home/kushi.git"
+  },
+  "homepage": "https://gim-home.github.io/kushi/",
+  "bugs": {
+    "url": "https://github.com/gim-home/kushi/issues"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs src/sanitize-workiq-input.test.mjs src/detect-vertex-repo.test.mjs src/vertex-validate.test.mjs src/emit-vertex.e2e.test.mjs src/config-root-resolve.test.mjs src/forbidden-workiq-phrasings.test.mjs src/multi-host-install.test.mjs",
+    "test:integration:bootstrap": "node src/bootstrap-dryrun.integration.test.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "prepublishOnly": "npm test && npm run smoke"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/plugin/instructions/agentskills-compliance.instructions.md

@@ -0,0 +1,144 @@
+---
+name: "agentskills-compliance"
+description: "Spec-compliance doctrine. Aligns every plugin/skills/<name>/SKILL.md with the conventions from https://agentskills.io/skill-creation/best-practices and /optimizing-descriptions. Defines size caps, load-on-trigger layout, gotchas, checklists, validation loops, plan-validate-execute, defaults-not-menus, and description-optimization rules. Enforced by self-check D30."
+applies_to: "every plugin/skills/<name>/SKILL.md"
+since: "kushi v5.0.1"
+---
+
+# agentskills-compliance — doctrine
+
+A SKILL.md is loaded **fully** into the agent's context window the moment it triggers. Every token competes with the conversation, system prompt, and other active skills. Compliance with the agentskills.io best-practices is therefore not stylistic — it is a context-budget contract.
+
+Authoritative external references:
+
+- <https://agentskills.io/skill-creation/best-practices>
+- <https://agentskills.io/skill-creation/optimizing-descriptions>
+
+## Rules (HARD)
+
+### 1. Size cap
+
+Every `plugin/skills/<name>/SKILL.md` MUST be:
+
+- ≤ **500 lines**, AND
+- ≤ **5000 tokens** (approximated by `char_count / 4`).
+
+Oversize SKILLs MUST be split per rule 2 below. Enforced by `self-check D30.skill-size`.
+
+### 2. Load-on-trigger layout
+
+`plugin/skills/<name>/SKILL.md` contains:
+
+- front-matter (`name`, `version`, `description`)
+- one-paragraph purpose
+- `## Gotchas` (top 5) — pull-* skills MUST have this
+- numbered or checklist procedure
+- `## Validation loop` (writer skills)
+- output contract
+
+Bulk content (full canonical WorkIQ prompts, full error-mode taxonomies, deep schema details, worked examples) moves to `plugin/skills/<name>/references/<topic>.md`. Standard reference filenames:
+
+| File | Contents |
+|------|----------|
+| `references/canonical-prompts.md` | Full WorkIQ prompt text (tier A/B/C, CSC, recovery) |
+| `references/error-modes.md` | Error taxonomy with retry semantics |
+| `references/taxonomy.md` | CSC schema deep details (where source-specific) |
+| `references/examples.md` | Full worked examples |
+| `references/playwright-fallback.md` | Opt-in fallback procedures |
+
+Every reference cited from SKILL.md MUST be cited with an **explicit trigger**, not a passive link. Trigger templates:
+
+```
+> Load references/canonical-prompts.md when constructing the WorkIQ query for this source.
+> Load references/error-modes.md if the API returns non-200, or WorkIQ returns "throttled".
+> Load references/playwright-fallback.md only when WorkIQ body-retrieval rate stays poor across ≥2 refreshes.
+```
+
+Enforced by `self-check D30.references-layout`.
+
+### 3. Gotchas (top 5)
+
+Every `pull-*` SKILL.md MUST surface its top 5 gotchas in a `## Gotchas` section near the top (immediately after the H1 / opening paragraph; before `## Steps` or `## Procedure`).
+
+Format: bullet list. Each bullet starts with the **concrete failure mode**, then the correction.
+
+```markdown
+## Gotchas
+
+- **Moved pages keep original wdsectionfileid** → if a section returns `page-body-unavailable` or zero `wdpartid` entries, the pages were authored elsewhere and moved. Open OneNote desktop, drag pages back into target section, retry.
+- **WorkIQ tier C requires ONE page per call** — batching multiple pages into a single ask returns empty results. Loop over pageIds, one call each.
+```
+
+Pull from `plugin/learnings/<source>.md` if present; else extract from the SKILL body itself. Enforced by `self-check D30.gotchas-section`.
+
+### 4. Checklists for orchestrators
+
+Orchestrator SKILLs (`bootstrap-project`, `refresh-project`, `build-state`, `link-entities`, `dashboard`, `tour`) MUST use GitHub checkbox syntax `- [ ]` for their step lists so progress is trackable in tooling and in conversation.
+
+```markdown
+- [ ] Step 1 — Resolve engagement root.
+- [ ] Step 2 — Resolve project alias.
+- [ ] Step 3 — Preflight per source.
+```
+
+Enforced by `self-check D30.checklist-orchestrators`.
+
+### 5. Validation loops (writer skills)
+
+Every skill that writes files to `Evidence/`, `State/`, `_graph/`, `dashboards/`, or `tours/` MUST end with a `## Validation loop` section:
+
+```markdown
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted <area>`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.
+```
+
+Enforced by `self-check D30.validation-loop`.
+
+### 6. Plan-validate-execute (link-entities + build-state)
+
+See `plan-validate-execute.instructions.md`. The skill writes a plan JSON, validates against a source of truth, then executes.
+
+### 7. Defaults not menus
+
+Pick ONE tool for each procedure step. Alternatives are escape hatches and MUST live in `references/` (e.g. `references/playwright-fallback.md`), not in the main SKILL body. The SKILL.md procedure does not enumerate alternatives.
+
+### 8. Procedures over declarations
+
+Write what the agent must DO, not what the skill IS. Imperative voice, concrete steps.
+
+### 9. Description optimization
+
+Per <https://agentskills.io/skill-creation/optimizing-descriptions> the `description:` front-matter is the sole trigger signal. It MUST describe **WHEN to use** the skill (trigger conditions), not just what it does. Convention for kushi skills:
+
+```yaml
+description: "USE WHEN <situational trigger> AND <precondition>. DO NOT USE for <near-miss>. <one-line capability summary>."
+```
+
+- BAD: `"Pulls OneNote pages and saves them as markdown."`
+- GOOD: `"USE WHEN refreshing project evidence for a known kushi project AND the project boundaries.onenote.section_ids list is non-empty. DO NOT USE for global OneNote search or non-kushi note capture."`
+
+Hard limit: 1024 characters. Enforced loosely by `self-check D30.description-optimized` (checks for the literal substring `USE WHEN` or `WHEN ` near the start of `description:`).
+
+## Migration checklist (per oversized SKILL)
+
+- [ ] Move full WorkIQ prompts → `references/canonical-prompts.md`
+- [ ] Move full error taxonomy → `references/error-modes.md`
+- [ ] Move source-specific schema details → `references/taxonomy.md`
+- [ ] Move opt-in fallbacks (Playwright, Edge profile bootstrap) → `references/playwright-fallback.md`
+- [ ] Add `## Gotchas` (top 5)
+- [ ] Add `## Validation loop` (if writer)
+- [ ] Replace inline blocks with "Load references/&lt;file&gt; when …" pointers
+- [ ] Bump skill version (minor) since structure changed
+- [ ] Re-run `self-check D30` and `npm test`
+
+## References
+
+- `instructions/plan-validate-execute.instructions.md`
+- `instructions/capture-learnings.instructions.md`
+- `instructions/issue-recovery.instructions.md`

package/plugin/instructions/multi-host-install.instructions.md

@@ -0,0 +1,125 @@
+---
+name: "multi-host-install"
+version: "1.0.0"
+description: "USE WHEN installing kushi to a user-global host (Clawpilot or VS Code Chat), uninstalling, or wondering why kushi ships to two hosts (not three or N) and how the layouts differ. DO NOT USE for workspace-local .kushi/ install — that is the legacy --target vscode flow."
+---
+
+# Multi-host install doctrine (v5.0.2+)
+
+Kushi ships as a single host-agnostic skill bundle, installed into a host's
+user-global skill folder by `npx kushi-agents`. **Exactly two hosts are
+supported.** No third host. No N-host generality.
+
+## The 2-host matrix
+
+| Host ID      | Display name                            | Skill dir                          | Metadata file                                |
+|--------------|-----------------------------------------|------------------------------------|----------------------------------------------|
+| `clawpilot`  | Clawpilot CLI                           | `~/.copilot/m-skills/kushi/`       | `~/.copilot/m-skills/skills-metadata.json`   |
+| `vscode`     | VS Code Chat ("GitHub Copilot Chat")    | `~/.vscode/chat/skills/kushi/`     | `~/.vscode/chat/skills/skills-metadata.json` |
+
+> The VS Code Chat path is the canonical user-global skill folder location
+> assumed by this doctrine. If a future VS Code Chat release ships a
+> different canonical path, update `VSCODE_CHAT_DEST_SUBPATH` in
+> `src/constants.mjs` — every other surface reads from there.
+
+## Why only these two
+
+- **Clawpilot** — primary scheduled / overnight surface (e.g. `kushi refresh <project>`
+  run from a Clawpilot automation at 6 AM).
+- **VS Code Chat** — primary interactive surface (`@kushi what's the MACC for X?`
+  asked the next morning).
+
+The same user routinely lives in both — automation in Clawpilot, follow-up
+questions in VS Code Chat. Both hosts read the **same** Evidence/ tree on disk,
+so a refresh in one is visible from the other immediately.
+
+A third host (e.g. a hypothetical web UI) would force per-host SKILL surgery
+or a content-branching shim. The 2-host matrix is the deliberate stopping
+point — it covers ≥ 99 % of the actual usage pattern and keeps cross-host
+parity trivially enforceable.
+
+## Per-host layout
+
+Both hosts get **byte-identical** content under their skill dir:
+
+```text
+<host-skill-dir>/
+├── SKILL.md                         (mirrored from agents/kushi.agent.md)
+├── agents/kushi.agent.md
+├── instructions/<name>.instructions.md
+├── prompts/<name>.prompt.md
+├── skills/<name>/SKILL.md           (+ references/, run.ps1, etc.)
+├── templates/<...>
+├── lib/<...>
+├── reference-packs/<...>
+├── config/
+│   ├── shared/                       (team-owned, safe to commit)
+│   └── user/                         (per-contributor, gitignored)
+└── kushi-install.json               (profile manifest)
+```
+
+And at the **parent** dir, `skills-metadata.json` carries the host's skill
+registry. The installer upserts a single `{"name": "kushi", ...}` entry that
+points `instructions` at the host's own `SKILL.md` (absolute path).
+
+There is **no per-host content branching**. A SKILL.md that opens with `WHEN
+running on Clawpilot, do X; WHEN running on VS Code Chat, do Y` is a defect.
+
+## Detection rules
+
+A host is **detected** when its parent dir exists on the file system:
+
+| Host       | Detection probe                       |
+|------------|---------------------------------------|
+| clawpilot  | `~/.copilot/m-skills/` exists         |
+| vscode     | `~/.vscode/chat/skills/` exists       |
+
+`bin/cli.mjs` runs detection before any install/uninstall and prints
+`Detected hosts: …` so the user sees which targets will be touched by the
+default behavior.
+
+## Install / uninstall flags
+
+| Flag                                 | Effect |
+|--------------------------------------|--------|
+| `--clawpilot`                        | Install to Clawpilot host (alone: also legacy `--target clawpilot` path) |
+| `--vscode`                           | Install to VS Code Chat host |
+| `--all-hosts`                        | Install to BOTH hosts (regardless of detection) |
+| `--uninstall`                        | Uninstall from all *detected* hosts |
+| `--uninstall --clawpilot`            | Uninstall from Clawpilot only |
+| `--uninstall --vscode`               | Uninstall from VS Code Chat only |
+| `--uninstall --all`                  | Uninstall from BOTH hosts |
+| (no flag)                            | Workspace install (legacy `.kushi/` in cwd) |
+
+## `kushi refresh <project>` is host-agnostic
+
+`refresh` is just a SKILL — the same `plugin/skills/refresh-project/SKILL.md`
+content runs under both hosts. It writes Evidence to disk at the user-
+configured engagement root (`~/Documents/Engagements/<project>/` by default),
+which lives **outside** the host skill dir. That is why a Clawpilot-driven
+refresh is immediately visible to a VS Code Chat `ask` — neither host owns
+the data.
+
+## Cross-host parity rule
+
+Every SKILL.md, prompt, instruction, template, and lib asset MUST work
+identically under both hosts. Concretely:
+
+- No `if (HOST === 'clawpilot') ...` style branching in any markdown body.
+- No host-specific paths in skill content (always use `<engagement-root>` /
+  `<project>` placeholders that resolve at runtime via the standard
+  `engagement-root-resolution.instructions.md` chain).
+- The two `SKILL.md` files (one per host) are required to be **byte-identical**
+  — enforced by `self-check` `D32.multi-host` in deep mode (temp-dir dry-run).
+
+If a future feature genuinely requires host-specific behavior (e.g. UI affordance
+only one host provides), it belongs in a host-specific *helper* outside `plugin/`
+— not inside the shared skill bundle.
+
+## See also
+
+- `host-portability.instructions.md` — older doctrine on per-host portability of
+  individual skill calls (still in force for runtime tool selection).
+- `D32.multi-host` self-check (deep) — validates installer + temp-dir layout.
+- `src/multi-host.mjs` — the installer/uninstaller implementation.
+- `src/multi-host-install.test.mjs` — node:test coverage.