wicked-garden 12.27.0

package/docs/adr/0004-code-graph-moves-to-wicked-brain.md

@@ -0,0 +1,47 @@
+# ADR 0004 — Move the code-relationship graph to wicked-brain (inverts ADR 0001's homing)
+
+- **Status:** Accepted
+- **Date:** 2026-06-10
+- **Supersedes:** the *homing* decision of [ADR 0001](0001-code-relationship-graph-engine.md) (graph lives in garden). **Keeps** ADR 0001's engine choice (codegraph) and the injected-edge concept.
+- **Context owners:** wicked-garden + wicked-brain
+- **Implements:** `docs/specs/2026-06-10-codegraph-to-brain-migration.md` (decisions D1–D6).
+
+## Context
+
+ADR 0001 adopted `@colbymchenry/codegraph` + wicked-garden-specific injected-edge extractors **inside garden**, and noted in passing that `search:blast-radius`/`lineage` were "wrongly" calling the brain (hardcoded to the wrong port) and concluded the fix was to *pull the graph into garden*.
+
+That instinct was backwards. "What breaks if I change X" / "what flows where" / "who depends on this" are **knowledge** questions about relationships — and the brain is the knowledge layer. It already shipped LSP-based code intelligence (`wicked-brain:lsp` advertised blast-radius/architecture). So the ecosystem had **two half-built code-intelligence stacks** answering overlapping questions in different repos. The decisive constraint: the graph is valuable to *every* repo, and requiring all of wicked-garden just to give a repo enhanced code/graph knowledge is unacceptable.
+
+## Decision
+
+**Move the code-relationship graph to `wicked-brain`.** Brain owns the engine integration, the unified graph, and every relationship query (blast-radius / callers / lineage). Garden becomes a **consumer**. The line is *knowing* (brain) vs *doing* (garden — deterministic refactor, gates, archetypes).
+
+Per the spec's locked decisions:
+- **D1/D2** Brain owns the graph + queries; **zero garden dependency** — brain is valuable standalone; the dependency arrow only ever points garden→brain.
+- **D3** Brain ships the generic/ecosystem extractors (bus, command→agent dispatch, capability); a **pluggable drop-in registry** (`<repo>/.codegraph-extractors/*.mjs`) lets any plugin contribute proprietary extractors (garden's archetype extractor) without brain importing the plugin.
+- **D4** codegraph = graph-of-record; LSP = live single-symbol precision (blast-radius/architecture moved off the lsp skill onto `wicked-brain:graph`).
+- **D5** Lazy staleness stamp + opt-in commit hook; **never** a watcher-driven full reindex (a known CPU-runaway hazard).
+- **D6** The graph DB stays codegraph-native (`<repo>/.codegraph/codegraph.db`); brain reads it directly via better-sqlite3.
+
+### What ADR 0001 keeps vs changes
+| | 0001 | 0004 |
+|---|---|---|
+| Engine | codegraph (adopt, runtime peer) | **unchanged** |
+| Injected-edge concept | yes | **unchanged** |
+| Home of the graph + queries | wicked-garden | **wicked-brain** |
+| blast-radius/lineage owner | garden commands | **brain `graph-*` actions + `wicked-brain:graph` skill** |
+| bus edge direction | `source=producer, target=consumer` (latent bug — blast-radius(producer) saw nothing) | **`source=consumer, target=producer`** (consumer depends on the producer's event contract; blast-radius(producer) surfaces the consumer) |
+
+## Consequences
+
+- **Any repo** gets relationship-graph knowledge by running wicked-brain — no garden required. Verified on a real repo: brain `graph-index` on wicked-garden built the static graph + 20 injected edges, and `blast-radius(scripts/_bus.py)` surfaced the `jam` consumer wired only by the `wicked.persona.contributed` event string (grep-invisible).
+- Garden's `scripts/_codegraph.py` + `scripts/codegraph/*` (the in-garden engine shim + extractors) are **superseded** by the brain implementation and are removed/aliased (this PR family).
+- `search:blast-radius` / `search:lineage` rewire to brain's `graph-*` actions (no more grep-with-extra-steps).
+- wicked-patch consumes the same codegraph-native `.codegraph/codegraph.db` brain builds (via `scripts/engineering/patch/codegraph_db.py`) — unchanged contract.
+- garden ships its proprietary **archetype** extractor as a brain drop-in (`.codegraph-extractors/archetype.mjs`), discovered by brain's registry — the D3 mechanism in action.
+
+## Implementation
+
+- wicked-brain: Phase 1a (graph core) + Phase 1b (injected edges + extractor registry) — see wicked-brain PR.
+- wicked-garden: Phase 2 — archetype drop-in, command rewire, this ADR, CLAUDE.md update.
+- Plans: `docs/plans/2026-06-10-codegraph-to-brain-phase1a-graph-core.md`, `docs/plans/2026-06-10-codegraph-to-brain-phase1b-injected-edges.md`.

package/docs/brain-chunk-format.md

@@ -0,0 +1,135 @@
+# Brain Chunk Format — Cross-CLI Reference
+
+This document defines the wicked-brain chunk format so any CLI (Claude Code, Codex, Gemini, Copilot) can write chunks that integrate into the shared knowledge graph.
+
+## Chunk File Structure
+
+Each chunk is a Markdown file with YAML frontmatter:
+
+```markdown
+---
+source: filename.py
+source_path: relative/path/to/filename.py
+source_type: py
+chunk_id: chunks/extracted/relative-path-to-filename.py/chunk-001
+content_type:
+  - text
+contains:
+  - keyword1
+  - keyword2
+  - synonym-of-keyword1
+entities:
+  systems: [named-systems]
+  people: [roles-or-people]
+confidence: 0.7
+indexed_at: "2026-04-07T12:00:00.000Z"
+---
+
+Actual content here in Markdown format.
+```
+
+## Required Frontmatter Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `source` | string | Original filename |
+| `source_type` | string | File extension without dot (py, js, md, etc.) |
+| `chunk_id` | string | Unique path within the brain directory |
+| `content_type` | list | Always `["text"]` for text files |
+| `contains` | list | 5-15 keyword tags for FTS5 search |
+| `confidence` | float | 0.7 for text extraction, 0.85 for vision |
+| `indexed_at` | string | ISO 8601 timestamp in quotes |
+
+## Optional Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `source_path` | string | Relative path from project root |
+| `entities` | dict | Named entities extracted from content |
+| `narrative_theme` | string | "So what" summary in 8 words or fewer |
+| `memory_id` | string | UUID if this chunk represents a memory |
+| `memory_type` | string | episodic, decision, procedural, preference |
+| `memory_tier` | string | working, episodic, semantic |
+| `ttl_days` | int | Auto-decay after N days (working tier) |
+
+## Brain Directory Layout
+
+```
+~/.wicked-brain/
+  brain.json                    # Brain identity and links
+  raw/                          # Original source files (symlinks)
+  chunks/
+    extracted/                  # Deterministic extraction from text
+      {safe-name}/chunk-NNN.md
+    inferred/                   # LLM-generated or working-tier
+      {safe-name}/chunk-NNN.md
+  wiki/
+    concepts/                   # Semantic-tier synthesized articles
+    topics/                     # Topic-level wiki articles
+  _meta/
+    config.json                 # Port, brain path
+    log.jsonl                   # Event log
+```
+
+## Brain API
+
+All operations go through the HTTP API at `http://localhost:4242/api`:
+
+```bash
+# Search
+curl -s -X POST http://localhost:4242/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"search","params":{"query":"authentication","limit":10}}'
+
+# Index a chunk
+curl -s -X POST http://localhost:4242/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"index","params":{"id":"chunk-path","path":"chunk-path","content":"text","brain_id":"wicked-brain"}}'
+
+# Stats
+curl -s -X POST http://localhost:4242/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"stats","params":{}}'
+
+# Health
+curl -s -X POST http://localhost:4242/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"health","params":{}}'
+```
+
+## Agent-Driven Ingestion (Any CLI)
+
+Any AI CLI can ingest files into the brain:
+
+1. **Read the file** using the CLI's native file-reading tool
+2. **Split into chunks** (Markdown: split on H1/H2; Code: one chunk per file; Other: ~800 word paragraphs)
+3. **Write chunk files** to `~/.wicked-brain/chunks/extracted/{safe-name}/chunk-NNN.md`
+4. **Index via API**: POST each chunk to the brain server
+
+### Safe Name Convention
+
+Convert file paths to safe chunk directory names:
+- Lowercase
+- Replace non-alphanumeric characters (except `.` and `-`) with hyphens
+- Collapse consecutive hyphens
+- Strip leading/trailing hyphens
+
+Example: `src/auth/login.py` -> `src-auth-login.py`
+
+### Tag Expansion
+
+When generating `contains:` tags, expand keywords with synonyms:
+- Abbreviations: JWT -> json-web-token, K8s -> kubernetes
+- Synonyms: auth -> authentication, DB -> database
+- Related concepts: JWT -> tokens, session, security
+- Cap at 15 tags per chunk
+
+## Memory Chunks
+
+Memories stored via wicked-garden are indexed as brain chunks at:
+- Working tier: `memories/working/mem-{uuid}`
+- Episodic tier: `memories/episodic/mem-{uuid}`
+- Semantic tier: `memories/semantic/mem-{uuid}`
+
+The brain's `compile` action synthesizes wiki articles from chunk clusters.
+The brain's `lint` action auto-decays chunks with expired TTL.

package/docs/compiler.md

@@ -0,0 +1,95 @@
+# The Compiler
+
+`/wicked-garden:compile` takes any repo and emits a **self-contained,
+vault-backed build gate** into `<repo>/.wicked/` — a gate that proves the
+build's claims and runs with **no wicked-garden runtime present**.
+
+The compiler is in `scripts/compiler/compile.py`. The detection pass is
+`scripts/compiler/phase0/detect.py`.
+
+## What it does
+
+The compiler reads a repo and works out how to gate it:
+
+1. **Detect the bindings** (`phase0/detect.py`) — test / lint / build
+   commands, the ecosystem, any structured `claims:` docs, and the repo's
+   risk surfaces.
+2. **Derive a contract** — a multi-claim wicked-vault contract built from
+   what it found.
+3. **Emit a harness** into `<repo>/.wicked/` (see below).
+
+## What it emits
+
+Everything lands in `<repo>/.wicked/`:
+
+| File | What it is |
+|------|------------|
+| `bindings.json` | The detected test/lint/build commands + ecosystem |
+| `contract.json` | The derived multi-claim vault contract |
+| `gate.py` | A **stdlib-only** gate — imports nothing from wicked-garden |
+| `claims_lint.py` | Emitted only when the repo has structured `claims:` docs |
+| `README.md` | How to run and wire up the emitted gate |
+
+## Runs with no wicked-garden present
+
+This is the property that makes the compiler worth having: the emitted
+`gate.py` carries **no dependency on the wicked-garden runtime**. It
+resolves the vault via `npx` and re-derives the build's claims itself —
+records the test/lint/build commands, then cross-checks. A
+claimed-but-false "tests pass" gets **REJECTED**; a missing vault **fails
+closed** rather than waving the build through.
+
+You compile once; the gate then lives in the target repo and runs on its
+own, in CI or on a developer's machine, with nothing of the garden
+installed.
+
+> **Why vault-direct, not loom?** Inside wicked-garden the produces-gate
+> re-derives through **wicked-loom** (which shells the vault). The *emitted*
+> gate deliberately does **not** — it shells **wicked-vault** directly via
+> `npx`. It has to run in a foreign repo with neither wicked-garden nor
+> wicked-loom present, so it depends only on the one public re-derivation
+> utility (the vault). This split is intentional, not drift: the garden gate
+> assumes loom is installed; the emitted gate cannot.
+
+## The on-switch rule
+
+Compile the **trigger** and the **enforcement**; never compile the
+**tool**.
+
+The vault is a runtime-resolved utility — resolved via `npx`, skippable,
+and not something the compiler bakes into the repo. The *trigger* that
+fires the gate, on the other hand, is exactly what the compiler installs.
+You don't ship a copy of the tool; you ship the on-switch and the rule it
+enforces.
+
+## Triggers
+
+Optionally, the compiler installs what actually fires the gate:
+
+- **Git pre-push hook** — idempotent, never clobbers a foreign hook, and
+  resolves the gitdir pointer so it works inside worktrees.
+- **GitHub Actions workflow** — its toolchain setup is derived from the
+  detected ecosystem.
+
+Pass `--trigger hook,ci` (or `all`) to install them.
+
+## Usage
+
+```bash
+# Detect + emit the harness into the repo's .wicked/
+/wicked-garden:compile ~/path/to/repo
+
+# Also install the triggers that fire the gate
+/wicked-garden:compile ~/path/to/repo --trigger hook,ci
+/wicked-garden:compile ~/path/to/repo --trigger all
+
+# Run the emitted gate (exit 0 = PASS)
+python3 .wicked/gate.py
+python3 .wicked/gate.py --check      # don't kick off a new run
+python3 .wicked/gate.py --dry-run    # show what would run
+```
+
+## Proven
+
+The compiler was tested on an unseen repo (memos) and self-hosted on
+wicked-garden itself.

package/docs/daemon-api.md

@@ -0,0 +1,70 @@
+# Daemon HTTP API
+
+The wicked-garden daemon exposes a local HTTP API (default port 7333) for reading garden state and issuing commands.
+
+## State endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/state` | Current garden state snapshot |
+| POST | `/council` | Run a synchronous council session |
+| GET | `/council/{session_id}` | Council session status |
+
+## Hook management
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/hooks` | Register a bus event hook |
+| GET | `/hooks` | List all registered hooks |
+| DELETE | `/hooks/{id}` | Deregister a hook by id |
+
+### POST /hooks
+
+Body:
+```json
+{
+  "event_pattern": "wicked.signals.*",
+  "command": "python3 /path/to/handler.py",
+  "description": "Handle signal events"
+}
+```
+
+Response 201:
+```json
+{"id": "uuid", "event_pattern": "wicked.signals.*", "command": "...", "created_at": "..."}
+```
+
+### DELETE /hooks/{id}
+
+Response 200: `{"ok": true, "id": "uuid"}`
+Response 404: `{"error": {"code": "NOT_FOUND", "message": "Hook not found"}}`
+
+## Council voting
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/council/vote` | Cast a vote on a council session |
+
+### POST /council/vote
+
+Body:
+```json
+{
+  "session_id": "sess-uuid",
+  "voter_id": "agent-1",
+  "vote": "approve",
+  "rationale": "Evidence is sufficient"
+}
+```
+
+Response 200: `{"ok": true, "session_id": "...", "voter_id": "..."}`
+Response 404: `{"error": {"code": "NOT_FOUND", "message": "Session not found"}}`
+
+## Error format
+
+All error responses use the nested format:
+```json
+{"error": {"code": "NOT_FOUND", "message": "Human-readable description"}}
+```
+
+Codes: `INVALID_REQUEST` (400), `NOT_FOUND` (404), `METHOD_NOT_ALLOWED` (405), `INTERNAL_ERROR` (500).

package/docs/domains.md

@@ -0,0 +1,197 @@
+# Domains
+
+Domains are **skill and agent families** — the discipline expertise wicked-garden ships. They are not an orchestrator and they do not run a workflow on their own.
+
+Work is shaped by the **9 archetypes** (triage, explore, specify, decide, ship, review, incident, build, migrate — see [Archetypes](v11/archetypes.md)). When an archetype's playbook needs domain expertise — a code review, a security scan, a requirements pass, a structural lookup — it **invokes a domain skill or agent** to get it. You can also call any domain command directly, without an archetype, when you just want that capability.
+
+Every command follows the pattern `/wicked-garden:{domain}:{command}`. Every agent declares `subagent_type: wicked-garden:{domain}:{name}` for Task-tool dispatch.
+
+There are **9 domains**: engineering, platform, product, data, jam, search, agentic, persona, smaht.
+
+> **v12 cleanup (ADR 0002).** Most domain commands are *rubric-wrappers* — a checklist the agent already applies. These were **collapsed**: the rubric moved to an on-demand `skills/{domain}/refs/{name}.md` and the command now loads it and works **inline** (no `Task` dispatch hop). Dispatch is kept only where it earns it — real parallelism (multiple lenses at once), a real external tool, or an independent gate. The dispatch-only agents that nothing reaches anymore were removed; agents still referenced by a surviving command, skill, scenario, or the specialist registry stay. Capability is preserved; only the token-burning hop is gone.
+
+---
+
+## engineering — Software Engineering
+
+Solution architect, API documentarian, and migration engineer. The workhorse for `build` and `migrate` work. The wicked-patch family (`patch-plan`/`apply`/`rename`/`add-field`/`remove`) and `new-generator` are real refactor/scaffolding tools and stay as-is; `arch`/`debug`/`docs`/`plan`/`review` collapsed to inline skill-refs. Code-quality, backend/frontend, debugging, and technical-writing work are handled inline by the engineering skill (the dedicated `senior-engineer`/`backend-engineer`/`frontend-engineer`/`debugger`/`technical-writer` agents were cut in the v12 lift eval — they produced zero measured lift over the base model; see `tests/agents/EVAL_RESULTS.md`).
+
+| Command | What It Does |
+|---------|-------------|
+| `engineering:review` | Code review from a senior engineering perspective |
+| `engineering:arch` | Architecture analysis and recommendations |
+| `engineering:debug` | Systematic debugging with root cause analysis |
+| `engineering:plan` | Review changes against the codebase and plan steps |
+| `engineering:patch-plan` | Show what a change would affect without patching |
+| `engineering:apply` | Apply patches from a saved JSON file |
+| `engineering:rename` | Rename a field/symbol across all usages |
+| `engineering:add-field` | Add a field to an entity and propagate it |
+| `engineering:remove` | Remove a field and all its usages |
+| `engineering:docs` | Generate or improve documentation |
+| `engineering:new-generator` | Create a language generator for wicked-patch |
+
+**Agents**: `solution-architect`, `api-documentarian`, `migration-engineer` — the dispatch-only `system-designer` and `devex-engineer` were removed when their commands collapsed inline; `senior-engineer`, `backend-engineer`, `frontend-engineer`, `debugger`, and `technical-writer` were cut in the v12 lift eval (zero measured lift) and now run inline via the engineering skill.
+
+## platform — DevSecOps
+
+SRE, security, compliance, incident response, and privacy engineering. Backs `ship`, `incident`, and `review` work. `security` (real gitleaks/semgrep), `toolchain`, `assert`, and `plugin-health` stay as real tools; `actions`/`audit`/`compliance`/`gh`/`health`/`incident`/`infra`/`traces` collapsed to inline skill-refs.
+
+| Command | What It Does |
+|---------|-------------|
+| `platform:security` | OWASP vulnerability assessment |
+| `platform:compliance` | SOC2/HIPAA/GDPR/PCI checks |
+| `platform:audit` | Collect audit evidence |
+| `platform:health` | System health and reliability assessment |
+| `platform:incident` | Incident response and triage |
+| `platform:infra` | Infrastructure review and IaC analysis |
+| `platform:actions` | GitHub Actions workflow generation |
+| `platform:traces` | Distributed tracing analysis |
+| `platform:toolchain` | Discover and query monitoring tools |
+| `platform:gh` | GitHub CLI power utilities |
+| `platform:assert` | Contract assertions against subprocess outputs |
+| `platform:plugin-health` | Health probes against installed plugins |
+
+**Agents**: `security-engineer`, `compliance-officer`, `privacy-expert` — the dispatch-only `infrastructure-engineer`, `devops-engineer`, `release-engineer`, `auditor`, `chaos-engineer`, and `observability-engineer` were removed when their commands collapsed inline; `sre` and `incident-responder` were cut in the v12 lift eval (zero measured lift), with incident/log work now handled inline via the platform incident command + errors/observability skills.
+
+## product — Product Management & Design
+
+Requirements, UX, customer voice, market/value strategy, accessibility, visual design review. Backs `specify` and `explore` work.
+
+| Command | What It Does |
+|---------|-------------|
+| `product:elicit` | Requirements elicitation through structured inquiry |
+| `product:acceptance` | Define acceptance criteria from requirements |
+| `product:listen` | Aggregate customer feedback from available sources |
+| `product:analyze` | Analyze feedback for themes and sentiment |
+| `product:synthesize` | Generate actionable recommendations |
+| `product:align` | Facilitate stakeholder alignment |
+| `product:strategy` | ROI, value proposition, competitive analysis |
+| `product:ux` | UX flow design and analysis |
+| `product:ux-review` | UX and design quality review |
+| `product:mockup` | Wireframe and prototype generation |
+| `product:screenshot` | Screenshot-based UI review (multimodal) |
+| `product:a11y` | WCAG 2.1 AA accessibility audit |
+
+> **Collapsed to skill (cleanup ADR 0002).** Most product commands now load their rubric inline from `skills/product/refs/<name>.md` and apply it directly — no `Task` dispatch hop. Dispatch is kept only where multiple lenses run in parallel: `product:ux-review --focus all` (flows + ui + a11y + research) and `product:strategy --focus all` (market + value).
+
+**Agents**: `requirements-analyst`, `ux-designer`, `value-strategist`, `a11y-expert`, `ui-reviewer` — the dispatch-only `ux-analyst`, `user-voice`, and `mockup-generator` were removed when their commands collapsed inline; `product-manager`, `user-researcher`, and `market-strategist` were cut in the v12 lift eval (zero measured lift). The user-researcher lens is folded into `ux-designer`; the market-strategist lens runs inline in `product:strategy` (value lens kept via `value-strategist`).
+
+### Requirements skills — which one? (router)
+
+The `product` domain ships four `requirements-*` skills (under `skills/product/`)
+that are **stages of one lifecycle**, not duplicates. Reach for them in this order:
+
+| Skill | Use it when | Hands off to |
+|-------|-------------|--------------|
+| `requirements-analysis` | Turning a vague idea/stakeholder ask into structured user stories + ACs. For complexity ≥ 3 or compliance work it defaults to **graph mode**. | `requirements-graph` (graph mode) |
+| `requirements-graph` | Laying out ACs as atomic markdown nodes with traceable frontmatter edges (filesystem-as-graph). | `requirements-navigate` |
+| `requirements-navigate` | Querying/maintaining an existing graph — coverage reports, gap-finding, `meta.md` refresh, lint. | — |
+| `requirements-migrate` | One-shot converting a monolithic requirements doc into the graph structure. | `requirements-navigate` |
+
+> Quick decision: **starting fresh →** `requirements-analysis`. **defining the graph directly →** `requirements-graph`. **already have a graph →** `requirements-navigate`. **have a legacy doc to convert →** `requirements-migrate`. For *testable* "definition of done" use `product:acceptance` (skill `acceptance-criteria`); for stakeholder *disagreement* use `product:align`.
+
+### "review" appears in three domains — which one? (router)
+
+`review` is intentionally split across three domains by *what is being reviewed*.
+They do not overlap; pick by target:
+
+| Command | Reviews | Output |
+|---------|---------|--------|
+| `engineering:review` | Source code — quality, patterns, maintainability, security/perf focus | findings list (advisory) |
+| `agentic:review` | An *agentic AI system* — framework detection, agent topology, safety/performance | remediation roadmap |
+| `archetype:review` | Any artifact/PR/commit as the v11 **review work-shape** | a HARD verdict (APPROVE / CONDITIONAL / REJECT) + remediation |
+| `product:ux-review` | UX/visual/accessibility quality of a UI | UX findings |
+
+> Quick decision: **code →** `engineering:review`. **an AI agent system →** `agentic:review`. **a UI →** `product:ux-review`. **need a binding go/no-go verdict on anything →** `archetype:review` (the only one that gates).
+
+## data — Data Engineering
+
+Data analyst, data engineer, ML engineer, and a unified data architect for OLTP + OLAP design.
+
+| Command | What It Does |
+|---------|-------------|
+| `data:analyze` | Interactive data analysis on files |
+| `data:data` | Data profiling and schema validation |
+| `data:pipeline` | Data pipeline design and review |
+| `data:ml` | ML model review and training pipeline |
+| `data:ontology` | Dataset ontology recommendations |
+
+**Agents**: `data-engineer` — `data-analyst`, `data-architect`, and `ml-engineer` were cut in the v12 lift eval (zero measured lift); their work routes to `data-engineer` or runs inline via the data analysis skill.
+
+## jam — AI Brainstorming
+
+Dynamic focus groups with AI personas plus structured multi-model council sessions using external LLM CLIs. The natural fit for `explore` work.
+
+| Command | What It Does |
+|---------|-------------|
+| `jam:brainstorm` | Full multi-perspective session with dynamic focus groups |
+| `jam:quick` | Lightweight exploration (fewer personas, one round) |
+| `jam:council` | Structured multi-model evaluation via external LLM CLIs |
+| `jam:revisit` | Revisit a past brainstorm decision |
+
+**Agents**: `brainstorm-facilitator`, `quick-facilitator`, `council`. The post-hoc viewers (`perspectives`/`thinking`/`persona`/`transcript`) were removed — niche retrieval the agent rarely reached for.
+
+## search — Code Intelligence
+
+Structural code intelligence on the **codegraph** graph (column-precise tree-sitter) plus the plugin's **injected edges** — bus producer→consumer, command→agent dispatch, agent→capability — that grep and a static call-graph can't see. Heavily used during `build`, `migrate`, and `review` to ground changes.
+
+| Command | What It Does |
+|---------|-------------|
+| `search:index` | Refresh both layers — brain (semantic) + codegraph (structural) incl. injected edges |
+| `search:blast-radius` | Dependencies and dependents of a symbol, including injected (string-keyed) links |
+| `search:lineage` | Trace data/reference flow from UI to DB (or reverse) |
+| `search:service-map` | Detect service architecture from infra files |
+| `search:hotspots` | Most-referenced symbols (find god-objects / coupling) |
+
+> For open-ended symbol and concept search, prefer `wicked-brain:search` / `wicked-brain:query`; the `search:*` commands cover the structural + injected-relationship analysis the brain doesn't. The thin index-admin wrappers (`categories`/`coverage`/`sources`/`quality`/`validate`) were removed — they duplicated `wicked-brain` tooling.
+
+## agentic — Agentic Architecture
+
+Architecture review, safety auditing, and performance analysis — for reviewing and designing AI agent systems. All four commands (`review`/`design`/`audit`/`frameworks`) collapsed to inline skill-refs (the 8-layer trust-and-safety rubric is preserved in `skills/agentic/refs/`).
+
+| Command | What It Does |
+|---------|-------------|
+| `agentic:review` | Full agentic codebase review with framework detection |
+| `agentic:design` | Interactive architecture design guide |
+| `agentic:audit` | Trust and safety audit |
+| `agentic:frameworks` | Research and compare frameworks |
+
+**Agents**: `architect`, `safety-reviewer`, `performance-analyst` — the dispatch-only `pattern-advisor` and `framework-researcher` were removed when their commands collapsed inline.
+
+## persona — On-Demand Personas
+
+Invoke any specialist persona directly. Define custom personas with personality, constraints, and preferences.
+
+| Command | What It Does |
+|---------|-------------|
+| `persona:as` | Invoke a named persona to perform a task |
+| `persona:define` | Create or update a custom persona |
+| `persona:list` | List all available personas |
+
+**Agents**: `persona-agent` (`persona:as` builds its prompt from the registry at runtime — kept). `persona:define` collapsed to an inline skill-ref; the no-op `persona:submit` stub was deleted.
+
+## smaht — Context Assembly
+
+On-demand context assembly over wicked-brain and the search index. A pull-model skill — archetypes and subagents call it when they need a briefing, rather than pushing context onto every prompt.
+
+| Command | What It Does |
+|---------|-------------|
+| `smaht:briefing` | What happened since the last session — recent events and updates |
+| `smaht:state` | Snapshot and report current session state |
+| `smaht:events-import` | Import existing domain JSON records into the event log |
+
+> `smaht:briefing` and `events-import` are real event-store tools and stay; `smaht:state` collapsed to an inline skill-ref (its dead v6 half dropped); the weak-signal `smaht:propose-skills` was deleted.
+
+---
+
+## How archetypes invoke domains
+
+An archetype playbook (`skills/archetype/refs/{archetype}.md`) doesn't hardcode a domain pipeline — it reaches for whatever expertise the work needs:
+
+- A `build` reaches for `engineering` to implement and review, `search` to ground changes, and `wicked-testing` for evidence.
+- A `review` reaches for `engineering:review`, `platform:security`, and `agentic:review` depending on the target.
+- An `explore` reaches for `jam` to diverge across perspectives.
+- A `specify` reaches for `product:elicit` and `product:acceptance`.
+- A `ship` runs its own canary→ramp→soak rollout playbook and reaches for `platform:health`.
+
+Domains are the *how*; archetypes are the *when* and *what shape*. The two compose — neither replaces the other.