contextdevkit 1.8.0

package/templates/claude/commands/setup/setupcontextdevkit.md

@@ -0,0 +1,121 @@
+---
+description: One-shot intelligent onboarding — inspects the project and self-configures ContextDevKit to it.
+argument-hint: [target level 1-7]
+---
+
+# 🚀 Setup ContextDevKit
+
+You are running the **self-configuring onboarding**. Goal: make this project's
+ContextDevKit setup *at least as rich as a hand-tuned one* — adapted to THIS
+project's stack, structure, and domain. Be thorough, infer aggressively, ask
+only the few questions that genuinely need a human, and **never break the
+project**. Confirm before any command that installs packages or changes the
+environment.
+
+Work through these phases in order. Use TodoWrite to track them.
+
+## Phase 1 — Inspect
+1. Run `node contextkit/tools/scripts/detect-stack.mjs` and parse the JSON report
+   (languages, package manager, frameworks, monorepo, source dirs, suggested
+   `ledger` + `highRiskPaths`, README summary, greenfield flag).
+2. Read `README*`, the existing `CLAUDE.md`, and skim the top-level structure to
+   understand what the project *is* and its domain language.
+3. If it's **greenfield** (no source yet), say so — onboarding will set up
+   conventions and defer stack specifics to the first `/new-adr`.
+
+## Phase 2 — Ask only what you can't infer
+Ask the user (batch into one short round, offer inferred defaults):
+- A one-sentence description of the project + its audience.
+- The **language for user-facing UI text** (code stays English; this is for
+  visible strings) — infer from README if obvious.
+- 1–3 **immutable rules** to enforce (propose candidates from the detected
+  stack, e.g. "never introduce <competing tech>", "all DB access via <layer>").
+- The **target level** (use `$ARGUMENTS` if provided; else recommend based on
+  the report — L2 for most, L1 for greenfield, L4/L5 if the codebase is large or
+  has clear high-risk areas).
+
+## Phase 3 — Apply configuration
+1. Tune the ledger + high-risk paths to this stack in one step (this also flips
+   the first-run flag off at the end):
+   ```
+   node contextkit/tools/scripts/setup-complete.mjs --detect
+   ```
+   Then review `contextkit/config.json` and refine `ledger.important` /
+   `l5.highRiskPaths` by hand if the heuristics missed something.
+2. Set the chosen level: `node contextkit/tools/scripts/context-level.mjs <N>`
+   (this rewires `.claude/settings.json` and installs git hooks at L≥3).
+
+## Phase 4 — Fill in CLAUDE.md
+Edit `CLAUDE.md` (or merge `CLAUDE.contextdevkit.md` if the installer left one):
+- "What this is" — the description from Phase 2.
+- "Stack" — the concrete detected stack (languages, frameworks, package manager).
+- "Immutable rules" — the rules from Phase 2; link an ADR for each big one.
+- "Language policy" — set the UI language row.
+- Keep it under ~200 lines. Push detail into ADRs.
+
+**Curated-stack rules.** When the detect report contains any `@tanstack/*`
+framework, inherit the conventions block from
+`contextkit/workflows/playbooks/tanstack.md` (the "Core conventions" section)
+into the project's `CLAUDE.md` under "Stack" or "Immutable rules". Cite the
+playbook + ADR-0017. Do **not** copy the opt-in starter — `/setupcontextdevkit`
+detects and writes rules; the starter is `/aidevtool-from0`-only.
+
+## Phase 4b — Scoped CLAUDE.md per app/module
+Run `node contextkit/tools/scripts/claude-md.mjs find`. For a multi-app/monorepo
+project, ensure **each app/module has its own CLAUDE.md** (backend, frontend,
+each package/service): `claude-md.mjs scaffold`, then **fill each** with real
+local rules (role, local stack, local conventions, boundaries) via `/claude-md`.
+Single-package project → the root CLAUDE.md is enough; skip.
+
+## Phase 5 — Glossary, business rules & squads (sub-agents)
+- Add any clear domain terms (from README/code) to `contextkit/memory/GLOSSARY.md`.
+- Capture any explicit **domain rules** you can infer as versioned files in
+  `contextkit/memory/business-rules/` (copy `_TEMPLATE.md`) — e.g. pricing, eligibility,
+  scheduling, gamification. One cohesive rule per file.
+- At **level ≥ 4** the squads install (`.claude/agents/`): **devteam**, **qa-team**,
+  **compliance-team** (LGPD), **design-team** (UI/UX), plus starter product/ops
+  agents. Review `contextkit/squads/README.md`. Enable the squads relevant to this
+  project (e.g. compliance-team if it handles Brazilian residents' personal data;
+  design-team if it has a UI) and **grow the devteam** with domain agents via
+  `/squad` (e.g. `frontend`, `backend`, `db`) from `_TEMPLATE.md`.
+
+## Phase 5b — Product roadmap (important — don't skip)
+Run `node contextkit/tools/scripts/roadmap.mjs find --json`:
+- If it lists an existing roadmap/PRD/spec file → offer to **import/normalize** it
+  into `contextkit/memory/roadmap.md` via `/roadmap from-existing`.
+- If none and the roadmap is undefined → **analyze** the codebase and **propose** a
+  roadmap, then **ask the user for their objectives** to add (P-IDs). Drive this
+  with `/roadmap from-existing`. A project without a roadmap is flying blind —
+  create it now (with the user), even a small first version.
+
+## Phase 6 — Install what's needed (confirm first)
+- If `package.json` exists but dependencies aren't installed, offer to run the
+  detected package manager's install (`pnpm install` / `npm install` / …).
+- If the user chose **Level 5** and wants strict `/context-config` validation,
+  offer to add `zod` as a dev dependency (optional — the kit runs without it).
+- Never install anything without explicit confirmation.
+
+## Phase 6b — Version control (verify the remote, decide with the user)
+Run `node contextkit/tools/scripts/git.mjs status` and act on the result:
+- **`isRepo: false`** → offer `git init`.
+- **`remoteUrl` present** → already connected; confirm it's the right one, move on.
+- **`remoteUrl: null`** → **ask**: "No remote — do you already have a repo
+  (GitHub/GitLab/other) to connect, or should we create one?" Then run
+  `/git setup-remote` (B1 connect existing / B2 create new, private by default).
+Confirm before any push/repo-creation (outward-facing).
+
+## Phase 7 — Record the baseline
+1. Create `contextkit/memory/decisions/0001-<stack-slug>.md` (use `/new-adr` style)
+   capturing the chosen stack + immutable rules as the baseline decision.
+2. Run `/log-session` to register this onboarding session.
+3. The `setup-complete.mjs` call already flipped `config.setup.completed = true`,
+   so the first-run trigger will no longer fire. Confirm it is `true`.
+
+## Phase 8 — Report
+Summarize to the user: detected stack, level set, config tuned (counts of
+important/high-risk paths), CLAUDE.md sections filled, agents created, deps
+installed, ADR + session logged. End with the natural next step.
+
+If anything is ambiguous, prefer asking one crisp question over guessing wrong.
+The point of this command is that the user goes from "kit installed" to "kit
+fully fitted to my project" in a single pass.

package/templates/claude/commands/simulate-impact.md

@@ -0,0 +1,32 @@
+---
+description: L5 pre-flight — map the blast radius of a change BEFORE editing high-risk paths.
+argument-hint: <one-sentence objective>
+---
+
+# 🔮 Simulate Impact
+
+Objective: **$ARGUMENTS**
+
+Produce a **Blast Radius Report** before any Edit/Write on high-risk paths.
+
+1. **Identify what the change touches.** List the concrete files/dirs you expect to modify. Cross-
+   reference `contextkit/config.json` → `l5.highRiskPaths` to see which are gated.
+
+2. **Map the blast radius.** For each touched area, reason about downstream effects: public
+   contracts/exports, API/route signatures, data schema, auth surface, shared types, anything that
+   other modules or external consumers depend on. If agents are installed (Level 4), delegate
+   focused sub-analyses to the relevant specialists in parallel and consolidate.
+
+3. **Write the report** to `contextkit/memory/predictions/<YYYY-MM-DD>-<slug>.md` with: objective,
+   files in scope, downstream risks, suggested order of changes, and a rollback note.
+
+4. **Authorize the edits** by recording the simulation on the ledger (this unblocks the L5 gate):
+   ```
+   node contextkit/tools/scripts/mark-simulation.mjs "$ARGUMENTS" <covered-path-or-dir/> [more ...]
+   ```
+   Use trailing slashes for directory coverage (e.g. `src/services/`).
+
+5. Summarize the report to the user and proceed with the change in the suggested order.
+
+For a genuinely trivial edit (typo/comment) on a gated path, record an explicit bypass instead:
+`node contextkit/tools/scripts/mark-simulation.mjs "BYPASS: <reason>" <path>`.

package/templates/claude/commands/squad.md

@@ -0,0 +1,44 @@
+---
+description: Show/route/grow the agent squads (devteam + qa-team) — the roster, when to use each, and how to add agents/squads.
+argument-hint: [show | route <task> | brief <agent> | new-squad <name>]
+---
+
+# 👥 Squads
+
+The sub-agents are organized into **squads** (see `contextkit/squads/README.md`):
+**devteam** (constructive — build + review) and **qa-team** (adversarial — verify
+behaviour). Agents live in `.claude/agents/` and install at **Level 4**.
+
+Act on **$ARGUMENTS**:
+
+## show (default)
+Run `node contextkit/tools/scripts/squad.mjs list` (agents + which already have a
+tier-2 briefing) and read `contextkit/squads/README.md`; summarize the squads, their
+members, and when to use each. If `.claude/agents/` isn't present, note the project
+is below Level 4 — suggest `/context-level 4` to enable the squads.
+
+## route <task>
+Pick the right squad/agent for the task and delegate (use the Agent tool to
+invoke the sub-agent). Building/designing/reviewing → **devteam** (`architect` →
+`code-reviewer`); testing/verifying → **qa-team** (via `qa-orchestrator`). For a
+full feature, prefer `/ship` (orchestrates the whole squad with checkpoints).
+
+## brief <agent>
+Scaffold the **tier-2 rich briefing**, then fill it:
+```
+node contextkit/tools/scripts/squad.mjs brief <agent>
+```
+It auto-detects the agent's squad and creates `contextkit/squads/<squad>/<agent>.md`
+from `_BRIEFING.md.tpl` (idempotent). Then **fill it** with real, specific content
+for this project — anti-patterns, end-to-end recipes, edge cases — the deep
+reference behind the lean `.claude/agents/<agent>.md`.
+
+## new-squad <name>
+Add a new squad (e.g. `design-team`, `product-team`, `ops-team`): create a
+section in `contextkit/squads/README.md` with its mandate + roster, and scaffold its
+agents from `.claude/agents/_TEMPLATE.md` (sharp `description`s). Keep the
+sovereignty rule clear (who decides on conflict).
+
+Remember the conflict rule: `code-reviewer` owns style/constitution;
+`qa-orchestrator` owns behaviour/sign-off; devteam decides until you harden the
+gates (`/context-level`).

package/templates/claude/commands/state.md

@@ -0,0 +1,21 @@
+---
+description: Quick summary of current project state (latest session + Unreleased + key rules)
+---
+
+> ⚠️ **Deprecated (1.0):** prefer **/audit** for a fuller, prioritized health
+> view. This quick state read still works for now.
+
+Summarize the current state of this project in at most 12 lines. To do so:
+
+1. Run `node contextkit/tools/scripts/context-pack.mjs` [ADR-0027] — **one** bounded
+   bundle with the latest-session digest, `[Unreleased]`, the immutable rules, the
+   open backlog, and recent ADRs. Reason over the pack instead of opening those
+   files separately; open a full file only if the pack flags something to inspect.
+
+Structure the answer in 3 blocks:
+
+- **State**: what is done, what is in progress.
+- **Natural next step**: based on `[Unreleased]` and the current phase.
+- **Do NOT touch**: the 1–2 most critical immutable rules to remember.
+
+Do not invent — only cite what is in the files. If something is empty, say "empty".

package/templates/claude/commands/token-report.md

@@ -0,0 +1,29 @@
+---
+description: Token economy & usage insight — report Claude Code token usage per session/week with budget warnings.
+argument-hint: [--all | --json]
+---
+
+# 🪙 Token Report
+
+Make token cost a **measured** dimension of the project (L6 Insight).
+
+Run:
+
+```
+node contextkit/tools/scripts/token-report.mjs
+```
+
+It reads Claude Code's local session transcripts (`~/.claude/projects/…`) and aggregates
+**input / output / cache** tokens per session and per ISO week — read-only, local,
+**aggregated counts only** (never content). Then:
+
+1. Call out the **heaviest sessions** and what likely drove them (long context, big files
+   re-read, repeated tool loops). A high cache-read share is normal — that's prompt caching.
+2. Check usage against the budget (`tokens.budgetPerSession`). If sessions trend hot,
+   suggest concrete optimizations: tighter scope per session (`/dev-start`), fewer
+   full-file re-reads, a leaner boot context, cheaper models for low-stakes steps.
+3. Set or adjust the budget: `/context-config set tokens.budgetPerSession <n>` (and
+   `tokens.warnAtPct`).
+
+Flags: `--all` (every project, not just this cwd) · `--json` (machine-readable) ·
+`--from <dir>` (read transcripts from a specific directory).

package/templates/claude/commands/tune-agents.md

@@ -0,0 +1,35 @@
+---
+description: L6 — propose outcome-driven refinements to agent briefings (writes a proposal, applies nothing). Mirrors /distill-sessions.
+---
+
+# 🎯 Tune agents (propose)
+
+Refine the squad's **agent briefings** from how they actually performed — but
+**apply nothing**. This is the review step (like `/distill-sessions` for `CLAUDE.md`);
+you apply the edits with your own OK.
+
+1. **Signals** (deterministic):
+   ```
+   node contextkit/tools/scripts/agent-tuning.mjs --json
+   ```
+   Gives the roster, tier-2 briefing coverage, and per-agent mention counts across
+   the session history (a usage proxy).
+
+2. **Outcomes** (judgment): read the recent session files + the DevPipeline
+   (`/pipeline`, the known-bugs map, ingested findings) and look, per agent, for:
+   - **false positives** it keeps raising → add a "don't flag X" note to dampen them,
+   - **blind spots** — real issues it missed that sit squarely in its lane → add an
+     anti-pattern row,
+   - **routing friction** — work that landed on the wrong agent → sharpen the
+     `description` (that's what routing keys on).
+
+3. **Draft** concrete briefing edits to `contextkit/squads/<team>/<agent>.md` (scaffold
+   a missing briefing first: `node contextkit/tools/scripts/squad.mjs brief <agent>`).
+   Prefer small, high-signal additions — briefings stay sharp, not bloated.
+
+4. **Write the proposal** to `.agent-tuning-proposal.md` (gitignored): the evidence
+   (which sessions/findings, what pattern), per-agent **before/after** edits, and any
+   agent that needs a new briefing. **Apply nothing in this command.**
+
+5. Summarize to the user and tell them to review it, then apply the edits with their
+   OK (or re-run after a batch of work). Do not edit agent briefings here.

package/templates/claude/commands/vcs/claim.md

@@ -0,0 +1,18 @@
+---
+description: Reserve path(s) for this session so parallel sessions get a cross-claim warning.
+argument-hint: <path1> [path2 ...]
+---
+
+Reserve the following path(s) for this session: **$ARGUMENTS**
+
+Run:
+
+```
+node contextkit/tools/scripts/claim.mjs $ARGUMENTS
+```
+
+This records the claim in `.claude/.workspace/<sid>.json` and regenerates
+`contextkit/memory/WORKSPACE.md`. Any OTHER active Claude session that edits inside a claimed path
+will see a cross-claim warning from the PostToolUse hook.
+
+Confirm to the user which paths are now claimed. Release them at the end with `/release`.

package/templates/claude/commands/vcs/git.md

@@ -0,0 +1,83 @@
+---
+description: Version-control command — git workflow + connect a remote (GitHub/GitLab/other) with the CLI, fully integrated.
+argument-hint: [status | setup-remote | new-branch <name> | commit | pr | sync | release]
+---
+
+# 🔧 Git / Version Control
+
+The disciplined git workflow for this project, integrated with the kit's hooks
+(`commit-msg` enforces Conventional Commits, `pre-push` blocks real conflicts)
+and commands (`/worktree-new`, `/close-version`). Always start by reading the
+facts: `node contextkit/tools/scripts/git.mjs status`.
+
+Act on **$ARGUMENTS**:
+
+## status (default)
+Run `git.mjs status` and summarize: repo/commits, branch, remote + provider,
+ahead/behind, and whether `gh`/`glab` are installed + authed. Flag what's missing
+and recommend the single next action.
+
+## setup-remote — the decision tree (detect → connect or create)
+**Always start by detecting** — read `git.mjs status` (`remoteUrl`, `isRepo`,
+`hasCommits`, `cli`). Then follow the branch that matches:
+
+**0. Not a git repo yet?** → `git init` first (and make an initial commit once
+there are files).
+
+**A. A remote ALREADY exists** (`remoteUrl` not null) → say so, show the URL +
+provider, confirm it's the intended one, and stop. Nothing to set up. (Only fix
+it if the user says it's wrong.)
+
+**B. No remote → ASK: "Do you already have a repository for this
+   (GitHub/GitLab/other) to connect, or should we create a new one?"**
+
+  - **B1 — they HAVE one to connect** → ask for the URL (or `owner/repo`) and wire
+    it: `git remote add origin <url>`, then `git fetch origin` and either
+    `git push -u origin <branch>` (local has the history) or
+    `git pull --rebase origin <default>` (remote has history) — reconcile if both
+    do, keeping BOTH sides.
+
+  - **B2 — they DON'T have one → suggest creating it.** Ask provider
+    (GitHub/GitLab/other) + visibility (**private by default**; public is hard to
+    undo — confirm explicitly). Ensure the CLI is installed + authed first (offer
+    the OS-aware install; confirm before installing):
+    - **GitHub** → `gh`: macOS `brew install gh` · Windows `winget install
+      GitHub.cli` · Linux cli.github.com. Auth: `gh auth login`.
+    - **GitLab** → `glab`: macOS `brew install glab` · Windows `winget install
+      glab` · Linux gitlab.com/gitlab-org/cli. Auth: `glab auth login`.
+    Then create + wire + push (confirm — outward-facing):
+    - GitHub: `gh repo create <name> --private --source . --remote origin --push`
+    - GitLab: `glab repo create <name> --private` then `git push -u origin <branch>`
+    - other: create in the UI, then `git remote add origin <url>` + push.
+
+Finally, recommend branch protection on the default branch (PRs + green CI before
+merge). Never push/create without the user's explicit OK.
+
+## new-branch <name>
+`git checkout -b <type>/<name>` using a Conventional type
+(feat/fix/chore/docs/refactor/test/ci/build/perf/style/revert). Never work on the
+default branch directly.
+
+## commit
+Stage intentionally and commit with Conventional Commits
+(`<type>(<scope>)?: <subject>`, ≤100 chars, no trailing period) — the `commit-msg`
+hook enforces this; `[skip-cc]` bypasses. Keep commits small and coherent.
+
+## pr
+**First, re-check sync** [ADR-0026]: `node contextkit/tools/scripts/sync-check.mjs
+prepr`. It re-confirms you are not behind the default branch (rebase first if you
+are) and detects whether an **open PR already exists for this branch** — if so,
+just push to update it instead of creating a duplicate. Then push the branch
+(`git push -u origin <branch>` — the `pre-push` hook checks for conflicts first)
+and open a PR: `gh pr create` / `glab mr create`. Summarize the change; wait for
+CI green before merge. Don't push to the default branch directly.
+
+## sync
+`git fetch` then `git pull --rebase origin <default>` to replay your work on top
+and resolve conflicts cleanly (keeping BOTH sides' changes — never clobber).
+
+## release
+Defer to `/close-version <x.y.z>` (CHANGELOG + tag); a `v*` tag triggers the
+release workflow if configured.
+
+Confirm before any push, repo creation, or install — those are outward-facing.

package/templates/claude/commands/vcs/release.md

@@ -0,0 +1,15 @@
+---
+description: Release this session's claim(s) — a specific path, or all of them.
+argument-hint: [path]
+---
+
+> ℹ️ **Paired with `/claim`** (claim → work → release). Manage both as one flow;
+> this command does the release half.
+
+Release path claims for this session.
+
+- To release a specific path: `node contextkit/tools/scripts/release.mjs $ARGUMENTS`
+- To release everything (no argument): `node contextkit/tools/scripts/release.mjs`
+
+Run the appropriate command based on whether `$ARGUMENTS` is empty, then confirm to the user what
+was released. This also regenerates `contextkit/memory/WORKSPACE.md`.

package/templates/claude/commands/vcs/worktree-new.md

@@ -0,0 +1,18 @@
+---
+description: Create a git worktree + branch for a parallel session on the same machine.
+argument-hint: <feature> [base-branch]
+---
+
+Create an isolated worktree so another Claude session can work in parallel without colliding on the
+ledger or on live file edits.
+
+Run:
+
+```
+node contextkit/tools/scripts/worktree-new.mjs $ARGUMENTS
+```
+
+This creates branch `feat/<feature>` and a sibling worktree directory `../<repo>-<feature>`. Show
+the user the output, including the `code "<path>"` command to open the new worktree in a separate
+window. Remind them: each worktree has its own `.claude/.sessions/`, so the two sessions stay fully
+isolated. When the feature is done: `git push -u origin feat/<feature>` then open a PR.

package/templates/claude/commands/watch.md

@@ -0,0 +1,47 @@
+---
+description: Watch the active session ledger — what got edited, in order. Optional --follow streams new entries.
+argument-hint: [-f | --follow]
+---
+
+# 👀 Watch the active ledger
+
+Stream what the **current session** has touched, in the order it touched them.
+Zero-dep, file-based — reads `.claude/.sessions/<active-id>.json` via the
+runtime's `readMostRecentLedger`.
+
+## Usage
+
+```
+node contextkit/tools/scripts/watch.mjs           # print all entries and exit
+node contextkit/tools/scripts/watch.mjs --follow  # stream (re-poll every 500 ms; Ctrl-C to stop)
+```
+
+Output format:
+
+```
+# session 04b759ee — 17 entries
+[14:02:11] EDIT  templates/claude/commands/dev-start.md
+[14:02:14] WRITE templates/contextkit/runtime/providers/review/_adapter.mjs
+[14:02:16] WRITE templates/contextkit/runtime/providers/review/gh.mjs
+...
+```
+
+## When to use it
+
+- **Mid-session sanity check.** "What has this session actually edited so
+  far?" without opening the ledger JSON in the editor.
+- **Long agent run.** Pair with `--follow` in a second pane to watch a
+  sub-agent's progress in real time.
+- **Drift triage.** When the Stop hook nags about unregistered work, run
+  `/watch` once to see the footprint before you decide to `/log-session`
+  or `/resume`.
+
+## What it does *not* do
+
+- It does **not** filter by ticket. Ticket-scoped view comes when ticket
+  042's per-task scratch convention lands and the `/pipeline` board gains
+  a "what touched this ticket?" surface.
+- It does **not** modify state. Pure read.
+- It does **not** invent entries. If the ledger is missing or the active
+  session cannot be resolved, the script exits non-zero with a clear
+  reason — never prints "0 entries" as a soft success.

package/templates/contextkit/.env.example

@@ -0,0 +1,36 @@
+# ContextDevKit — environment template (ADR-0024)
+#
+# This file is COPIED INTO YOUR PROJECT at contextkit/.env.example. To use
+# it: copy to contextkit/.env (or your project's root .env), fill in values.
+# Then run the kit scripts that need creds with Node's built-in env-file
+# loader (Node 20.6+):
+#
+#   node --env-file=contextkit/.env contextkit/tools/scripts/media-gen.mjs image \
+#     --prompt "editorial product hero, asymmetric grid" --out hero.png
+#
+# Or copy the variables into your project's existing dotenv setup
+# (Astro / Next / Nuxt / Vite all already read .env).
+#
+# Nothing here is required by default. The kit refuses cleanly with a
+# NO_CREDENTIALS error if you call a media-generation script without
+# the key set, and points you back at this file.
+
+# ─── Media generation (ADR-0024) ────────────────────────────────────────
+# Google AI Studio API key — used by both:
+#   nano-banana.mjs  (image — Imagen)
+#   veo.mjs          (video — Veo)
+# Get one at: https://aistudio.google.com/apikey
+# GOOGLE_AI_API_KEY=
+
+# Per-process cost cap in USD. The adapters keep a running tally and
+# refuse the next call that would push the total over this floor. Leave
+# unset = no cap (you pay for whatever you call).
+# CONTEXTDEVKIT_MEDIA_MAX_USD=5.00
+
+# ─── Future home-scoped overrides (optional) ───────────────────────────
+# These are listed for discoverability — the kit reads them from
+# process.env directly, so they can live here or in your shell.
+# CONTEXTDEVKIT_HOME=          # override ~/.contextdevkit/ (ADR-0020)
+# CONTEXTDEVKIT_DASHBOARD_PORT= # override /dashboard --watch port (default 4242)
+# CONTEXT_FLEET_FILE=          # override the fleet registry path
+# CONTEXT_GIT_TIMEOUT_MS=      # override the kit's git command timeout

package/templates/contextkit/CLAUDE.child.md.tpl

@@ -0,0 +1,38 @@
+# {{MODULE_NAME}} — local context for Claude
+
+> Scoped CLAUDE.md for `{{MODULE_PATH}}`. Claude Code loads the file **closest**
+> to the code being edited, so this carries the rules specific to this
+> module/app. It **inherits** the root [`CLAUDE.md`](../../CLAUDE.md) constitution
+> — don't repeat it here; only add what's local.
+> Scaffolded by ContextDevKit ({{DATE}}). Fill in the TODOs.
+
+## What this is
+
+<!-- One line: this module's role (backend API / web frontend / mobile app /
+     shared library / service X) and its single responsibility. -->
+_TODO: describe `{{MODULE_PATH}}` and its role in the system._
+
+## Local stack & tooling
+
+{{MODULE_STACK}}
+
+## Local conventions (what's different here)
+
+<!-- Rules that apply ONLY to this module — folder layout, where things go, the
+     patterns to follow, the traps to avoid. Examples:
+     - Routes are thin controllers; business logic lives in `services/`.
+     - Components stay presentational; state/effects go into `hooks/`.
+     - Public API of this package is the barrel `src/index.ts` — keep it stable. -->
+- _TODO: add this module's local rules._
+
+## Boundaries
+
+- **Depends on:** _TODO (which modules/packages this one consumes)._
+- **Consumed by:** _TODO (who depends on this module's public surface)._
+- Changes to the public surface are contract changes — see `/contract-check`.
+
+## Pointers
+
+- Root constitution & immutable rules: [`CLAUDE.md`](../../CLAUDE.md)
+- Architecture decisions: `contextkit/memory/decisions/`
+- Glossary (naming): `contextkit/memory/GLOSSARY.md`

package/templates/contextkit/README.md

@@ -0,0 +1,74 @@
+# contextkit/ — ContextDevKit platform
+
+This folder is the AI-assisted development platform installed by
+[ContextDevKit](https://github.com/reiTavares/ContextDevKit). It is a **bounded
+context** separate from your product code — everything here exists to make
+Claude Code sessions reliable, self-documenting, and consistent across time.
+
+## Layout
+
+| Path | What |
+| --- | --- |
+| `runtime/hooks/` | Claude Code hooks (boot context, edit ledger, drift nudge, L5 gate) |
+| `runtime/config/` | Zero-dep config loader, defaults, paths, settings composer, optional zod schema |
+| `runtime/git-hooks/` | `pre-commit` (reindex), `commit-msg` (Conventional Commits), `pre-push` (block real conflicts) |
+| `runtime/providers/review/` | PR/review CLI adapters (`gh` ships) — see ADR-0021 |
+| `runtime/providers/media/` | Media generation adapters — `nano-banana` (Imagen 3) + `veo` (Veo 3); see ADR-0024 |
+| `runtime/state/` | Canonical `state.json` substrate for tasks + pipeline runs (ADR-0015) |
+| `tools/scripts/` | 50+ helpers (reindex, dashboard, sync-check, audits, media-gen, …) |
+| `memory/decisions/` | ADRs — the immutable *why* |
+| `memory/sessions/` | One markdown file per work session — the *what* |
+| `memory/SESSIONS.md` | Auto-generated index (do not hand-edit) |
+| `memory/WORKSPACE.md` | Auto-generated active-claims index (do not hand-edit) |
+| `memory/GLOSSARY.md` | Domain term ↔ code identifier |
+| `pipeline/` | DevPipeline lanes: `backlog/ → working/ → testing/ → conclusion/` |
+| `workflows/playbooks/` | Reusable procedures (tanstack, landing-page, seo-aiso, tech-debt-sweep, …) |
+| `squads/agent-forge/` | The L6+ "agent that builds agents" (Agent Package pipeline) |
+| `config.json` | Level + ledger path lists + L5 params (edit via `/context-config`) |
+| `.env.example` | Optional credentials template (`/media-gen` Google AI Studio keys) |
+
+## The 7 levels
+
+The active level is `config.json` → `level`. See `/context-level` to inspect or
+change it. Higher levels add capability — earlier ones stay active.
+
+1. **Memory** — boot context, session log, ADRs, changelog.
+2. **Ledger** — drift detection (tracks edits, nudges you to `/log-session`).
+3. **Multi-session** — claims, worktrees, derived indices, git hooks.
+4. **Squads** — 28 specialized sub-agents organised into 7 squads (devteam,
+   qa-team, design-team with `seo-specialist` + `landing-architect`,
+   security-team, compliance-team, ops-team, agent-forge).
+5. **Proactive** — `/simulate-impact` gate on high-risk paths, tech-debt sweep,
+   distill-detect nudge, contract drift.
+6. **Autonomy & Insight** — `/ship`, `/retro`, `/context-stats`, agent-forge squad.
+7. **Ecosystem** — `/fleet` multi-repo control plane, `/tune-agents`,
+   visual tests, playbook runner.
+
+## Requirements
+
+- **Node.js ≥ 18** (the hooks/scripts — Levels 1–3 need zero npm packages).
+  **Node 20.6+** unlocks `--env-file` for the media-gen credentials flow.
+- **git** (for divergence detection and Level 3 git hooks).
+- `zod` is optional, only for strict `/context-config` validation at Level 5.
+- *Optional:* `gh` (GitHub CLI) for sync-check PR awareness;
+  `GOOGLE_AI_API_KEY` for `/media-gen`.
+
+## Updating the engine
+
+Re-run the kit installer over the project to pull engine updates without losing
+your memory or config:
+
+```bash
+npx contextdevkit@latest --target . --update
+# or, offline / from GitHub:
+npx github:reiTavares/ContextDevKit --target . --update
+```
+
+## Quick references
+
+- **Slash commands** — see `.claude/commands/README.md` for the taxonomy.
+- **Provider adapters** — `runtime/providers/{review,media}/_adapter.mjs`
+  document the contract.
+- **Playbooks** — `workflows/playbooks/` for reusable procedures.
+- **Setup credentials for `/media-gen`** — copy `.env.example` to `.env`, fill
+  in `GOOGLE_AI_API_KEY`, run with `node --env-file=contextkit/.env ...`.