contextdevkit 1.8.0

package/docs/SQUADS/agent-forge.md

@@ -0,0 +1,65 @@
+# agent-forge — the factory squad
+
+> Public reference for the optional L4+ squad that forges portable, multi-provider
+> **Agent Packages (APF v1)** for projects *outside* the kit. The kit gains an
+> agent-that-builds-agents whose output ships independently — zero ContextDevKit
+> dependency at consume time.
+
+## When to enable
+
+Add `agent-forge` when a project's purpose includes shipping production AI
+agents (chatbots, extractors, RAG, classifiers, etc.) as standalone artefacts —
+typically `project_type: ai-product`. Stays inert otherwise.
+
+## Approval + constraints
+
+- **[ADR-0012](../../contextkit/memory/decisions/0012-agent-forge-squad-for-portable-agent-packages.md)** — 7 binding constraints (portable zero-dep output, hot path stays zero-dep, reuse `squadOf`, no phantom prerequisite, **eval-as-authority**, owned matrix freshness, mandatory tests).
+- **[ADR-0013](../../contextkit/memory/decisions/0013-agent-forge-yaml-via-optional-dynamic-import.md)** — YAML strategy: optional `yaml` dep behind a dynamic import (the `zod` precedent).
+
+## Pipeline
+
+```
+/forge-new
+  → agent-architect      (interview → blueprint)
+  → model-router         (capability-matrix × decision-rules → primary/fallback/cheap/premium + rationale)
+  → prompt-engineer      (canonical → Anthropic+OpenAI+Gemini+DeepSeek+Ollama)
+  → tool-designer        (canonical JSON Schema → 5 provider adapters)
+  → eval-designer        (golden + red-team + rubric + thresholds)
+  → governance-officer   (three pillars + fallback chain; refuses under-configured)
+  → packager             (assembles APF, stamps provenance, writes 5 prompts + 5 tool adapters)
+  → eval gate            (optional `runEval` → stamps `eval_passed_at` only on PASS)
+```
+
+## Maintenance commands (Fase 4)
+
+| Command | What it does |
+| --- | --- |
+| `/forge-list` | Every package + version + routed primary + eval-stamp status |
+| `/forge-show <agent>` | Manifest + provenance + last eval timestamp |
+| `/forge-doctor` | Integrity check; fails on missing files or `{{TOKEN}}` placeholders |
+| `/forge-policy <agent>` | Resolved cost / compliance / quality + fallback chain |
+| `/forge-budget` | Aggregate monthly target + hard cap |
+| `/forge-audit <agent>` | Audit-log tally (ok / refused / error / killed / fallbacks / cost) |
+| `/forge-eval <agent>` | Re-run golden + red-team |
+| `/forge-redteam <agent>` | Red-team only |
+| `/forge-route <agent>` | Re-run router, diff vs current manifest |
+| `/forge-fallback-test <agent>` | Chaos: primary 503 on first call |
+| `/forge-refresh-matrix` | Stamp `updated`; model adds require an ADR |
+| `/forge-killswitch <agent> <on\|off>` | Toggle quality kill switch (atomic) |
+| `/forge-deprecate <agent>` | Stamp `metadata.deprecated_at`; recommend an ADR |
+
+Read `/context-stats` for the aggregate Forge Stats section.
+
+## Where each piece lives
+
+- **Squad source** — [`templates/contextkit/squads/agent-forge/`](../../templates/contextkit/squads/agent-forge/)
+- **Status map** — [`ROADMAP.md`](../../templates/contextkit/squads/agent-forge/ROADMAP.md) (the section-by-section blueprint coverage)
+- **Best-practices bar** — [`best-practices.md`](../../templates/contextkit/squads/agent-forge/best-practices.md)
+- **APF v1 template** — [`templates/contextkit/squads/agent-forge/templates/agent-package/`](../../templates/contextkit/squads/agent-forge/templates/agent-package/) (45 files)
+- **APF format reference** — [`docs/AGENT-PACKAGE-FORMAT.md`](AGENT-PACKAGE-FORMAT.md)
+
+## Boundary
+
+This squad's *clients* are external projects, not Claude Code. Every other squad
+in the kit (devteam / qa-team / security-team / …) services the developer; this
+one services *the developer's product*.

package/docs/SQUADS/design-team.md

@@ -0,0 +1,161 @@
+# Squad — design-team
+
+The kit's "make it usable, make it beautiful, make it findable" squad. Five
+specialists, each sharp and narrow. Activated at **Level 4+**.
+
+## When to invoke each
+
+| Specialist | When to use | Refuses |
+|---|---|---|
+| **`ux-designer`** | Designing or critiquing a flow / screen / interaction. User journeys, friction maps, empty/loading/error states, IA. | Clever-over-clear, decoration that costs friction, designing only happy paths |
+| **`ui-designer`** | Layout, spacing, type scale, colour roles, components, responsive behaviour, design tokens. | One-off styles, hard-coded raw hex colours in components, inventing patterns when the system has one |
+| **`accessibility`** | WCAG 2.1 AA verification — keyboard nav, screen-reader semantics, contrast ratios, focus management, ARIA. | Adding ARIA when semantic HTML already does the job; mouse-only interactions |
+| **`seo-specialist`** *(v1.7)* | Public-facing surfaces where indexability matters — SEO (Google + Bing) and AISO (LLM answer engines). | Plain client-rendered SPAs on public routes, JS-rendered cited content, prerender hacks, missing `llms.txt` / FAQ schema |
+| **`landing-architect`** *(v1.7)* | Landing-page or marketing-site structural decisions — rendering posture, fold map, conversion levers, package picks. | Cookie-cutter "Lovable / v0 / Tailwind UI" pattern; `Inter` / Heroicons / three-tier pricing / testimonial slider as defaults |
+
+## How they pair
+
+```text
+Brief: "design a landing page for our pricing change"
+
+  /landing-page  →  landing-architect
+                       │
+                       ├──→ seo-specialist     (mandatory gate — indexability first)
+                       ├──→ ui-designer        (tokens + visual layout)
+                       ├──→ ux-designer        (user flow through the page)
+                       ├──→ accessibility      (pre-merge WCAG AA)
+                       └──→ /media-gen         (hero imagery instead of stock)
+```
+
+The **order matters**. `landing-architect` decides the rendering posture and
+fold map first; `seo-specialist` verifies indexability *before* visual work
+lands; only then do `ui-designer` and `ux-designer` shape the screen.
+
+## `landing-architect` — the structural decision-maker *(new in v1.7)*
+
+Authority: [ADR-0023](../../contextkit/memory/decisions/0023-landing-page-and-conversion-posture.md)
++ [`landing-page.md`](../../templates/contextkit/workflows/playbooks/landing-page.md) playbook.
+
+### Posture
+
+Anti-Lovable / anti-cookie-cutter is the load-bearing principle. The current
+generation of AI-generated landing pages has a uniform look (gradient hero,
+three feature cards, three-tier pricing, testimonial slider, FAQ accordion)
+that a savvy visitor recognises in 3 seconds. Recognition reads as
+"AI-built" → "low effort" → conversion cost.
+
+### The three decisions (in this order)
+
+1. **Rendering posture** — SSG (Astro recommended), SSR (Next App Router /
+   Nuxt / Remix / SvelteKit), or carve-out via project ADR. Plain Vite +
+   React for a public landing page is a refusal; propose Astro.
+2. **Fold map** — count from the playbook's table:
+   - **min 3** (hero · proof · CTA) — utility / one-feature pages
+   - **ideal 5–7** — SaaS, marketing pages
+   - **max 9** — high-ticket B2B; beyond falls off a cliff
+   - Per-fold rule: **one message · one action · one proof**.
+3. **Package picks** — framework, styling, animation, typography, icons,
+   forms, analytics, experimentation, imagery. From the dated rec table
+   in the playbook; refuse `Inter` / Heroicons / GA4 / Material UI as
+   *defaults*.
+
+### Output shape
+
+Every `/landing-page` response is structured exactly:
+
+1. Indexability decision (SSG / SSR / carve-out + framework + rationale)
+2. Fold map (each: `<fold-name> · <message> · <action> · <proof>`)
+3. Anti-Lovable map (smells refused + substitute for each)
+4. Stack (one-line rationale per category)
+5. Performance budget (LCP < 2.5 s · INP < 200 ms · CLS < 0.1 · JS < 100 kB)
+6. Next-step delegations (which agent for what input)
+
+**No code.** The plan is the deliverable.
+
+## `seo-specialist` — the indexability + discoverability gate *(new in v1.7)*
+
+Authority: [ADR-0025](../../contextkit/memory/decisions/0025-seo-and-aiso-posture.md)
++ [`seo-aiso.md`](../../templates/contextkit/workflows/playbooks/seo-aiso.md) playbook.
+
+### Two index spaces, two rule sets
+
+A public page is judged by **two crawler classes simultaneously**, and most
+projects optimise the first while ignoring the second.
+
+| Index | Crawlers | Rewards | Kills |
+|---|---|---|---|
+| **Classical SEO** | Googlebot, Bingbot, DuckDuckBot | Server-rendered HTML, semantic tags, canonical URLs, sitemap, Core Web Vitals, JSON-LD entities | Empty `<div id="root"></div>`, JS-rendered titles, missing `<meta description>`, CLS > 0.1 |
+| **AISO** (AI Search Optimization) | GPTBot, ClaudeBot, PerplexityBot, Google-Extended, OAI-SearchBot | `llms.txt`, FAQ schema, scannable Q&A headings, semantic HTML5, recency stamps, author schema | Div-soup, JS-rendered content, no FAQ schema, no `llms.txt`, robots.txt blocking AI crawlers |
+
+### Operational principles
+
+- **Audit-first.** Runs `seo-audit.mjs` + `aiso-audit.mjs` before any opinion.
+- **Refuse-on-unindexable for landing surfaces.** Plain SPA on public routes
+  is a refusal — proposes SSG / SSR.
+- **Refuse JS-tricks.** Prerender services, dynamic-rendering middleware —
+  brittle, propose-correct-rendering-mode-up-front instead.
+- **AISO is not optional for marketing sites.** `llms.txt` + FAQ schema +
+  semantic HTML5 = the 80/20.
+- **Propose, don't auto-rewrite.** Findings are the deliverable.
+- **Respect project-local ADRs** that carve out indexability (internal admin
+  tools, etc).
+
+### Audits available
+
+```bash
+# Classical SEO — 8 codes, exit 1 on critical (SPA_ENTRYPOINT)
+node contextkit/tools/scripts/seo-audit.mjs            # human-readable table
+node contextkit/tools/scripts/seo-audit.mjs --json     # machine-readable
+
+# AISO — 8 codes
+node contextkit/tools/scripts/aiso-audit.mjs           # human-readable table
+node contextkit/tools/scripts/aiso-audit.mjs --json    # machine-readable
+
+# Or the slash command runs both and summarises:
+/seo-audit
+```
+
+| SEO codes | AISO codes |
+|---|---|
+| `SPA_ENTRYPOINT` (critical), `MISSING_TITLE` (high), `MISSING_DESCRIPTION` (high), `MULTIPLE_H1` (high), `MISSING_CANONICAL` (medium), `MISSING_ALT` (medium), `MISSING_SITEMAP` (high), `MISSING_ROBOTS` (medium) | `MISSING_LLMS_TXT` (high), `MISSING_FAQ_SCHEMA` (high), `MISSING_ORG_SCHEMA` (medium), `DIV_SOUP` (medium), `JS_RENDERED_CONTENT` (high), `MISSING_AUTHOR_SCHEMA` (low), `MISSING_DATE_STAMP` (low), `BLOCKS_AI_CRAWLERS` (high) |
+
+## `ui-designer` — the system voice
+
+Owns layout, spacing, type scale, colour roles, components, responsive
+behaviour, and visual consistency via **design tokens** (`:root { --color-primary: ... }`).
+Refuses one-off styles. Pairs with the chosen styling system (Tailwind +
+tokens being the kit's recommended default).
+
+## `ux-designer` — the user-flow voice
+
+Owns user journeys, IA, interaction design, and the *unhappy paths* (empty,
+loading, error, partial, offline, first-run). Designs the flow backward
+from the job-to-be-done; resists clever-over-clear.
+
+## `accessibility` — the WCAG 2.1 AA floor
+
+Owns keyboard navigation, screen-reader semantics, contrast ratios, focus
+management, ARIA hygiene. Refuses ARIA-when-semantic-HTML-already-does-the-job.
+Mandatory before any landing-page or marketing surface merges.
+
+## Growing the squad
+
+To add a specialist (e.g. `motion-designer` for advanced interaction):
+
+1. Copy `templates/claude/agents/_TEMPLATE.md`.
+2. Fill in `name` + `description` (the routing signal — Claude picks an
+   agent by matching the description).
+3. Add posture / principles / anti-patterns / self-audit / delegate-to.
+4. Add a selfcheck assertion in `tools/selfcheck-source.mjs`.
+5. Document in this file under "When to invoke each".
+
+A vague "helps with everything" agent defeats routing. Keep it **sharp and
+narrow** — see `seo-specialist.md` and `landing-architect.md` as references.
+
+## Related
+
+- [`docs/SQUADS/agent-forge.md`](agent-forge.md) — the L6+ squad that *builds*
+  Agent Packages portable across hosts.
+- Playbook [`landing-page.md`](../../templates/contextkit/workflows/playbooks/landing-page.md)
+  + [`seo-aiso.md`](../../templates/contextkit/workflows/playbooks/seo-aiso.md).
+- [`docs/CUSTOMIZING.md`](../CUSTOMIZING.md) — adding agents to any squad.

package/docs/token-economy-plan.md

@@ -0,0 +1,135 @@
+# Token-Economy & Agility Plan
+
+> A plan to reduce token consumption **and** increase agility in ContextDevKit, by
+> moving deterministic extraction out of the AI and into zero-dep scripts.
+> Companion to [ADR-0027](../contextkit/memory/decisions/0027-token-economy-digest-layer.md)
+> and the ROADMAP section *"Token economy: the digest layer"*.
+> Authored 2026-06-03.
+
+## 1. The principle
+
+In this kit, **tokens are spent when the AI (Claude) reads files and reasons over
+them.** Every line of raw markdown the AI ingests is input tokens. The cheapest token
+is the one never read. So the lever is simple:
+
+> **Pre-digest deterministically in a script; let the AI reason over the compact
+> output.** Scripts are free (they don't consume model tokens); the AI's context is
+> the scarce resource.
+
+The kit already lives by this — ~40 of 65 commands delegate heavy work to a `.mjs`
+script. This plan finishes the job for the cluster that still makes the AI ingest
+**full raw artifacts**.
+
+## 2. Where the tokens go (the audit)
+
+A pass over `templates/claude/commands/` (65 files) + the boot hook found three cost
+shapes:
+
+| Shape | Where | Why it's expensive |
+| --- | --- | --- |
+| **Read N raw session logs** | `/distill-sessions`, `/retro`, `/tune-agents` | last ~10 logs = 1,100–1,300 lines (~13–16K tok) **before any reasoning** |
+| **Overlapping multi-file reads** | `/dev-start`, `/state`, `/ship` | each re-reads latest session + `[Unreleased]` + `CLAUDE.md` rules (+ADRs); also 3–5 sequential round-trips |
+| **ADR discovery** | many flows ("read the relevant ADR") | 26 ADRs × ~110 lines; finding the right one by reading 3–5 ≈ 10–13K tok |
+| **Boot banner** | `session-start.mjs` (every session) | injects 60 raw lines of the last session, **every session**, from turn 1 |
+
+Already efficient (no action): `/audit`, `/deep-analysis`, `/deps-audit`,
+`/contract-check`, `/dashboard`, `/stats`, `/pipeline`, `/token-report`, the forge/
+vcs/setup families — all script-backed.
+
+## 3. The fix (four pieces, one shared library)
+
+Per ADR-0027 — each piece has a concrete existing consumer (Rule 9), reuses one
+single-source extractor (Rule 4), stays zero-dep (Rule 1), and degrades to raw on any
+parse miss (Rule 2/8):
+
+1. **`lib/digest/`** — pure shared extractor (session log → compact record; ADR →
+   `{number,title,status,decision1line}`). Used by the boot hook **and** the scripts.
+2. **`session-digest.mjs`** — session logs → ~12–18 line digest (`--last N`/`--id`/
+   `--json`). Rewires `/distill-sessions`, `/retro`, `/tune-agents`.
+3. **`adr-digest.mjs`** — ~26-line ADR catalog + `--search`. Wires into `/ship`,
+   `/dev-start`, `/new-adr`, `/deep-analysis`.
+4. **`context-pack.mjs`** — one bounded "start of work" bundle. Collapses
+   `/dev-start`/`/state`/`/ship` pre-reads into one call.
+5. **Boot rewire** — 60 raw lines → ~12-line digest, with raw-truncated fallback.
+
+## 4. Estimated token savings
+
+**Assumptions (stated honestly):** ~12 input tokens per dense markdown line; figures
+are **input/ingest** tokens (reasoning + output unaffected); prompt caching already
+discounts re-reads inside a warm window, so the *realized* saving is largest on cold
+and **cross-session** reads — the digest shrinks the bytes regardless. Frequencies are
+for a single active project in a week; scale per your cadence. These are
+**order-of-magnitude estimates**, provable after the fact with `/token-report --json`.
+
+| Command / surface | Raw ingest today | With digest | Saved / run | ~Freq/wk | Weekly |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| `/distill-sessions` | ~1,200 ln ≈ 14K | ~150 ln ≈ 1.8K | **~12K** | 2 | ~24K |
+| `/retro` | ~1,300 ln ≈ 15K | ~250 ln ≈ 3K | **~12K** | 1 | ~12K |
+| `/tune-agents` | ~1,100 ln ≈ 13K | ~200 ln ≈ 2.5K | **~10K** | 1 | ~10K |
+| `/dev-start` (step 2) | ~160 ln ≈ 2K | ~55 ln ≈ 0.7K | **~1.3K** | 15 | ~20K |
+| `/state` | ~150 ln ≈ 1.8K | ~50 ln ≈ 0.6K | **~1.2K** | 10 | ~12K |
+| `/ship` pre-read + ADRs | ~350 ln ≈ 4.5K | ~80 ln ≈ 1K | **~3.5K** | 4 | ~14K |
+| ADR discovery (ad hoc) | ~330 ln ≈ 4K | ~136 ln ≈ 1.7K | **~2.3K** | 15 | ~35K |
+| **Boot banner** (per session) | 60 ln ≈ 0.7K | 12 ln ≈ 0.15K | **~0.55K** | 35 | ~19K |
+| | | | | **Total** | **~145K/wk** |
+
+**Headline: ~120–200K input tokens/week** on an active project (the range covers
+caching and cadence variance), order **~0.5–0.8M/month**. Two clear leaders:
+- **Biggest single-run wins:** the periodic L5/L6 commands (`/distill-sessions`,
+  `/retro`, `/tune-agents`) — ~10–14K each, because they ingest ~10 raw logs.
+- **Highest-frequency win:** the **boot digest** — small per session (~0.55K) but
+  paid by *every* session from turn 1.
+
+## 5. The agility dividend (beyond tokens)
+
+Token count isn't the only cost — **round-trips and determinism** matter too:
+
+- **Fewer round-trips → lower latency.** `/dev-start` step 2 is 3–4 sequential
+  `Read` calls today (each a turn). `context-pack.mjs` makes it **one** call. Same for
+  `/state` and `/ship`'s pre-read.
+- **Deterministic briefings.** Extraction is regex/structure, not an AI summary — the
+  session *starts from the same context every time*, no run-to-run drift in what the
+  AI saw. Reproducible inputs → reproducible behaviour.
+- **Leaner from turn 1.** The boot digest means *every* session begins with a tighter
+  context window, leaving more headroom before compaction kicks in.
+
+## 6. Rollout — smallest blast radius first, measure around it
+
+Sequenced so each slice ships independently, with a test (Rule 3) and a re-measure:
+
+- **Phase 0 — Baseline (measure first).** Capture `node contextkit/tools/scripts/token-report.mjs
+  --json` now, and note the `cache_read` share. You can't prove a saving you didn't
+  baseline. *(No code.)*
+- **Phase 1 — Biggest single-run wins.** Build `lib/digest/` + `session-digest.mjs` +
+  selfcheck; rewire `/distill-sessions` and `/retro`. Highest tokens-per-run, lowest
+  risk (these commands are periodic, off the hot path).
+- **Phase 2 — Highest-frequency win + start pack.** Rewire the boot hook to the shared
+  digester (with raw fallback) and ship `context-pack.mjs`; wire `/dev-start` + `/state`.
+  Touches the hot path → guarded by the fallback + an integration test that the boot
+  banner never empties.
+- **Phase 3 — ADR discovery.** Ship `adr-digest.mjs`; wire `/ship`, `/new-adr`
+  (dup-decision check), `/deep-analysis`, `/tune-agents`.
+- **Phase 4 — Re-measure & close the loop.** Re-run `/token-report`, compare actual vs
+  the §4 estimate, and file the predicted-vs-actual delta (the kit's predictions-review
+  culture). Feed any surprise into the next reducer (follow-ups in ADR-0027).
+
+## 7. Guardrails (don't regress the invariants)
+
+- **Zero-dep, zero new hook** — plain scripts + one pure shared module; boot reuses the
+  existing hot path. (Rule 1)
+- **Never break, never empty** — a digest miss falls back to the current raw-truncated
+  output; the boot banner can degrade but never blocks or shows nothing. (Rule 2/8)
+- **Single-source** — one extractor module, used by boot *and* the scripts; no second
+  copy of the parser. (Rule 4)
+- **Every slice ships with a test** — `selfcheck`/`integration-test` assertions,
+  including one that fails if the canonical session-log headings drift out of sync
+  with the parser. (Rule 3)
+- **Deterministic, not lossy** — digests extract structure; they never let the AI
+  "summarize and forget". The full artifacts stay on disk, one `Read` away.
+
+## 8. Out of scope (deferred, per Rule 9)
+
+Per-command/agent token attribution in `/token-report`; a DevPipeline board digest for
+`/pipeline`; a general "summarize any file" digester (unsafe — only the structured
+artifacts qualify); an mtime-keyed digest cache (only if extraction cost ever shows up
+in a profile).

package/install.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * ContextDevKit installer — entry point + orchestration.
+ *
+ * Bootstraps the AI-assisted development platform into ANY project (greenfield
+ * or existing, any stack). Idempotent: re-run it to change level or pull engine
+ * updates. It never clobbers your own content (CLAUDE.md, memory, config
+ * overrides); it only overwrites the kit's own engine code and slash commands.
+ *
+ * The mechanics live in focused modules under `tools/install/` (cli, fs,
+ * project, git, uninstall); this file just wires the steps together.
+ * Run `node install.mjs --help` for usage and the full flag list.
+ *
+ * Cohesion note (line budget): this file is intentionally a single linear
+ * orchestrator — the ordered install steps (settings → engine → commands →
+ * agents → memory seeds → GitHub → git hooks → config) share one `target` +
+ * `report` and must run in sequence. Splitting the sequence into more modules
+ * would scatter the one thing this file exists to express (the install order)
+ * and add indirection without reducing real complexity. The heavy lifting is
+ * already delegated to `tools/install/*`; what remains is the recipe.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+import { composeSettings } from './templates/contextkit/runtime/config/settings-compose.mjs';
+import { applyPreset, listPresets } from './templates/contextkit/runtime/config/presets.mjs';
+import { ensureDir, read, writeIfMissing, overwrite, copyTree, copyTreeIfMissing, render } from './tools/install/fs.mjs';
+import { detectStack, requireBasename, looksGreenfield } from './tools/install/project.mjs';
+import { installGitHooks, patchGitignore, patchGitattributes } from './tools/install/git.mjs';
+import { uninstall } from './tools/install/uninstall.mjs';
+import { isValidLevel } from './templates/contextkit/runtime/config/levels.mjs';
+import { parseArgs, HELP, prompt, LEVEL_LABELS } from './tools/install/cli.mjs';
+
+const KIT_ROOT = dirname(fileURLToPath(import.meta.url));
+const TPL = resolve(KIT_ROOT, 'templates');
+
+async function kitVersion() {
+  try {
+    return JSON.parse(await read(join(KIT_ROOT, 'package.json'))).version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    console.log(HELP);
+    return;
+  }
+  if (args.version) {
+    console.log(`contextdevkit ${await kitVersion()}`);
+    return;
+  }
+
+  const target = resolve(args.target || process.cwd());
+  await ensureDir(target);
+
+  if (args.uninstall) {
+    await uninstall(target, args.purge);
+    return;
+  }
+
+  const interactive = !args.yes && process.stdout.isTTY;
+  let level = Number.isInteger(args.level) ? args.level : undefined;
+  let name = args.name;
+  let mode = args.mode;
+
+  if (interactive) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    console.log('\n🌀 ContextDevKit installer\n');
+    console.log(`Target: ${target}\n`);
+    if (!name) name = await prompt(rl, 'Project name', requireBasename(target));
+    if (!mode) {
+      const auto = looksGreenfield(target) ? 'greenfield' : 'existing';
+      mode = await prompt(rl, 'Mode (greenfield/existing)', auto);
+    }
+    if (!level) {
+      console.log('\nLevels:');
+      for (const [k, v] of Object.entries(LEVEL_LABELS)) console.log(`  ${k}. ${v}`);
+      level = Number(await prompt(rl, '\nStart at level', String(mode === 'greenfield' ? 3 : 7)));
+    }
+    rl.close();
+  }
+
+  // Recommended starting level by project type: L3 for greenfield, L7 for a project
+  // that already has code (full toolkit; gates stay inert until configured). [ADR-0009]
+  const effMode = mode === 'greenfield' || mode === 'existing' ? mode : looksGreenfield(target) ? 'greenfield' : 'existing';
+  const recommended = effMode === 'greenfield' ? 3 : 7;
+
+  // Safe re-run / update: if no explicit --level, preserve the project's current
+  // level (read from config) instead of silently downgrading to the default.
+  if (!isValidLevel(level)) {
+    try {
+      const existingCfg = JSON.parse(await read(join(target, 'contextkit', 'config.json')));
+      if (Number.isInteger(existingCfg.level)) level = existingCfg.level;
+    } catch {
+      /* no config yet */
+    }
+  }
+  level = isValidLevel(level) ? level : recommended;
+  name = name || requireBasename(target);
+  mode = effMode;
+
+  const report = [];
+
+  // 1. settings.json (always — this is the wiring).
+  const settingsPath = join(target, '.claude', 'settings.json');
+  let existingSettings = null;
+  if (existsSync(settingsPath)) {
+    try {
+      existingSettings = JSON.parse(await read(settingsPath));
+    } catch {
+      report.push('⚠️  existing .claude/settings.json was malformed — recreated');
+    }
+  }
+  await overwrite(settingsPath, JSON.stringify(composeSettings(existingSettings, level), null, 2) + '\n');
+  report.push(`✓ .claude/settings.json wired for L${level}`);
+
+  if (args.rewire) {
+    console.log(report.join('\n'));
+    console.log(`\n✅ Rewired to Level ${level}. Restart Claude Code to load the new hooks.`);
+    return;
+  }
+
+  // 2. Engine: always overwrite (kit code; updates should propagate).
+  await copyTree(join(TPL, 'contextkit', 'runtime'), join(target, 'contextkit', 'runtime'));
+  await copyTree(join(TPL, 'contextkit', 'tools'), join(target, 'contextkit', 'tools'));
+  report.push('✓ engine installed (contextkit/runtime, contextkit/tools)');
+
+  // 3. Slash commands: always overwrite.
+  await copyTree(join(TPL, 'claude', 'commands'), join(target, '.claude', 'commands'));
+  report.push('✓ slash commands installed (.claude/commands)');
+
+  // 4. Agents + L4+ squads: only at L >= 4.
+  if (level >= 4) {
+    await copyTree(join(TPL, 'claude', 'agents'), join(target, '.claude', 'agents'));
+    report.push('✓ agent archetypes installed (.claude/agents)');
+    // agent-forge factory squad: engine code + matrix + APF templates (ADR-0012).
+    // Always overwrite — engine kit code, not user-editable.
+    await copyTree(join(TPL, 'contextkit', 'squads', 'agent-forge'), join(target, 'contextkit', 'squads', 'agent-forge'));
+    report.push('✓ agent-forge squad installed (contextkit/squads/agent-forge)');
+  }
+
+  // 5. Memory seeds: write only if missing. `.env.example` is seeded here so the
+  //    user's edits survive re-install (ADR-0024 — media-gen credentials template).
+  for (const rel of ['memory/SESSIONS.md', 'memory/WORKSPACE.md', 'memory/GLOSSARY.md', 'memory/roadmap.md', 'memory/decisions/_TEMPLATE.md', 'memory/decisions/0000-record-architecture-decisions.md', 'memory/business-rules/_TEMPLATE.md', 'memory/predictions/.gitkeep', 'memory/sessions/.gitkeep', 'README.md', 'instrucoes.md', 'best-practices.md', 'behaviors.md', 'behaviors-examples.md', 'CLAUDE.child.md.tpl', 'squads/README.md', 'squads/_BRIEFING.md.tpl', '.env.example']) {
+    const src = join(TPL, 'contextkit', rel);
+    if (!existsSync(src)) continue;
+    const wrote = await writeIfMissing(join(target, 'contextkit', rel), await read(src), args.force);
+    if (wrote) report.push(`✓ seeded contextkit/${rel}`);
+  }
+  // Ensure memory dirs exist even if a packager stripped the .gitkeep seed.
+  await ensureDir(join(target, 'contextkit', 'memory', 'sessions'));
+  await ensureDir(join(target, 'contextkit', 'memory', 'decisions'));
+  await ensureDir(join(target, 'contextkit', 'memory', 'business-rules'));
+  await ensureDir(join(target, 'contextkit', 'memory', 'predictions'));
+  // DevPipeline scaffolding (write-if-missing so existing tasks survive re-install).
+  const pipeCount = await copyTreeIfMissing(join(TPL, 'contextkit', 'pipeline'), join(target, 'contextkit', 'pipeline'));
+  if (pipeCount > 0) report.push(`✓ seeded contextkit/pipeline (${pipeCount} file(s))`);
+  for (const s of ['backlog', 'testing', 'conclusion']) await ensureDir(join(target, 'contextkit', 'pipeline', s));
+  // Workflow guides (L1–L6) + reusable playbooks (write-if-missing so customizations survive).
+  const wfCount = await copyTreeIfMissing(join(TPL, 'contextkit', 'workflows'), join(target, 'contextkit', 'workflows'));
+  if (wfCount > 0) report.push(`✓ seeded contextkit/workflows (${wfCount} file(s))`);
+  // Pluggable-detector seed (README + inert example) so the extension point is discoverable.
+  const detCount = await copyTreeIfMissing(join(TPL, 'contextkit', 'detectors'), join(target, 'contextkit', 'detectors'));
+  if (detCount > 0) report.push(`✓ seeded contextkit/detectors (${detCount} file(s))`);
+  // Curated-stack starters (always overwrite — pure templates, no user edits expected here;
+  // /aidevtool-from0 copies them OUT of contextkit/starters/ into the project root, not in-place).
+  await copyTree(join(TPL, 'contextkit', 'starters'), join(target, 'contextkit', 'starters'));
+  report.push('✓ curated-stack starters installed (contextkit/starters)');
+
+  // 6. config.json: create with level + first-run flag, or update level
+  //    (preserving an already-completed setup so re-installs don't re-trigger).
+  const cfgPath = join(target, 'contextkit', 'config.json');
+  const preset = args.preset && listPresets().includes(args.preset) ? args.preset : null;
+  if (args.preset && !preset) report.push(`⚠️  unknown --preset "${args.preset}" (have: ${listPresets().join(', ')}) — ignored`);
+  if (existsSync(cfgPath)) {
+    try {
+      let cfg = JSON.parse(await read(cfgPath));
+      cfg.level = level;
+      if (cfg.setup?.completed !== true) cfg.setup = { completed: false, installedAt: new Date().toISOString() };
+      if (preset) cfg = applyPreset(cfg, preset);
+      await overwrite(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+      report.push(`✓ updated contextkit/config.json level → ${level}${preset ? ` (+preset ${preset})` : ''}`);
+    } catch {
+      /* leave malformed file for the user */
+    }
+  } else {
+    let cfg = JSON.parse(await read(join(TPL, 'contextkit', 'config.json')));
+    cfg.level = level;
+    cfg.setup = { completed: false, installedAt: new Date().toISOString() };
+    if (preset) cfg = applyPreset(cfg, preset);
+    await overwrite(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+    report.push(`✓ created contextkit/config.json (level ${level}, first-run pending${preset ? `, preset ${preset}` : ''})`);
+  }
+
+  // 7. CLAUDE.md: render if missing; else drop a side file to merge.
+  //    On --update we NEVER touch CLAUDE.md (it's user-owned content).
+  const claudePath = join(target, 'CLAUDE.md');
+  if (args.update && existsSync(claudePath)) {
+    /* update: leave the user's CLAUDE.md untouched */
+  } else {
+    const claudeTpl = await read(join(TPL, 'CLAUDE.md.tpl'));
+    const claudeOut = render(claudeTpl, {
+      PROJECT_NAME: name,
+      DATE: new Date().toISOString().slice(0, 10),
+      LEVEL: String(level),
+      MODE: mode,
+      STACK_NOTES: mode === 'existing' ? await detectStack(target) : 'Greenfield — define the stack as the first architectural decision (`/new-adr`).',
+    });
+    if (!existsSync(claudePath) || args.force) {
+      await overwrite(claudePath, claudeOut);
+      report.push('✓ CLAUDE.md created');
+    } else {
+      await overwrite(join(target, 'CLAUDE.contextdevkit.md'), claudeOut);
+      report.push('⚠️  CLAUDE.md exists — wrote CLAUDE.contextdevkit.md to merge by hand');
+    }
+  }
+
+  // 8. CHANGELOG: render if missing.
+  const changelogPath = join(target, 'docs', 'CHANGELOG.md');
+  if (!existsSync(changelogPath)) {
+    const clTpl = await read(join(TPL, 'docs', 'CHANGELOG.md.tpl'));
+    await overwrite(changelogPath, render(clTpl, { PROJECT_NAME: name, DATE: new Date().toISOString().slice(0, 10) }));
+    report.push('✓ docs/CHANGELOG.md created');
+  }
+
+  // 9. .gitignore + .gitattributes + GitHub templates + git hooks.
+  if (await patchGitignore(target)) report.push('✓ .gitignore patched');
+  if (await patchGitattributes(target, TPL)) report.push('✓ .gitattributes patched (LF for engine scripts)');
+  const ghCount = await copyTreeIfMissing(join(TPL, 'github'), join(target, '.github'));
+  if (ghCount > 0) report.push(`✓ ${ghCount} GitHub template(s) added to .github/`);
+  if (level >= 3) {
+    const gitHooks = await installGitHooks(target);
+    if (gitHooks.installed) {
+      report.push('✓ git hooks installed (pre-commit, commit-msg, pre-push)');
+      if (gitHooks.backedUp.length) report.push(`  ↳ backed up your existing ${gitHooks.backedUp.join(', ')} hook(s) → *.bak`);
+    } else report.push('ℹ️  no .git found — run `git init` then re-run to install git hooks');
+  }
+  // Version-control hint: suggest connecting a remote if there isn't one.
+  if (!existsSync(join(target, '.git')) || !(await read(join(target, '.git', 'config')).catch(() => '')).includes('[remote "origin"]')) {
+    report.push('ℹ️  no git remote — run /git setup-remote to connect GitHub/GitLab/other (+ CLI)');
+  }
+
+  // ── summary ──
+  console.log('\n' + report.join('\n'));
+  if (args.update) {
+    console.log(`\n✅ ContextDevKit UPDATED to v${await kitVersion()} (Level ${level} preserved) in ${target}`);
+    console.log('   Refreshed: engine + slash commands + hook wiring. Untouched: CLAUDE.md, config,');
+    console.log('   memory (ADRs/sessions/roadmap), pipeline tasks, scoped module CLAUDE.md files.');
+    console.log('   Restart Claude Code to load the refreshed hooks.');
+    console.log('');
+    return;
+  }
+  console.log(`\n✅ ContextDevKit installed at Level ${level} into ${target}`);
+  console.log('\nNext steps:');
+  console.log('  1. Open the project in Claude Code (it reads .claude/ + CLAUDE.md).');
+  console.log('  2. Approve the hooks on first run (one-time per hook).');
+  console.log('  3. ⭐ Run  /setupcontextdevkit  — it fits the kit to THIS project');
+  console.log('     (detects stack, tunes config, fills CLAUDE.md, flags risks).');
+  console.log('     The first-run trigger will remind you automatically.');
+  console.log('  4. Then work normally. /log-session at the end.');
+  if (level < 5) console.log(`  5. Level up later:  /context-level ${Math.min(level + 1, 5)}`);
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error('\n❌ ContextDevKit install failed:', err?.stack || err);
+  process.exit(1);
+});