@event4u/agent-config 5.4.1 → 5.6.0

package/docs/contracts/benchmark-report-schema.md

@@ -82,25 +82,27 @@ verdict:
 Headers in order:
 
 1. `# Benchmark Report — <corpus_id> · <generated_at>`
-2. `## Headline` — three-line summary (selection · cost · quality).
+2. `## Headline` — three-line summary (selection · tokens · quality).
 3. `## Selection accuracy` — table per prompt with hit/miss + expected/got.
-4. `## Cost capture` — per-tier table + total; "unavailable" block if no
-   session jsonl was found.
+4. `## Token usage` — per-tier message counts + token totals; "unavailable"
+   block if no session jsonl was found. The monetary (USD) comparison is
+   **intentionally not rendered** — per-call API pricing misleads
+   subscription users; tokens are the currency-neutral metric that matters.
 5. `## Quality probe` — per-prompt assertion pass/fail; `not_collected`
    block when no agent-output path was passed.
-6. `## Notes` — pointer to `pricing.yaml`, `corpus path`, and the
-   versioned filename for citation.
+6. `## Notes` — `corpus path` and the versioned filename for citation.
 
 ## Invariants
 
-- **No silent drops.** Missing cost source → emit `source: unavailable`
-  and `total_cost_usd: 0.0` with a marker; never omit the section.
+- **No silent drops.** Missing token source → emit `source: unavailable`
+  with a marker; never omit the section.
 - **Quality stub honesty.** When agent outputs are not provided, set
   `quality.source: not_collected` and `verdict.overall: partial`. Score
   stays `0.0`; never inflate by assuming pass.
-- **Pricing dated.** Every cost row reads `sourced_on` from
-  `internal/bench/pricing.yaml`. Stale price (> 90 days) → warning line in the
-  Markdown footer.
+- **Tokens, not money.** The rendered report shows token counts only. The
+  JSON still carries the `cost` block (`total_cost_usd`, per-tier `cost_usd`)
+  for back-compat with downstream consumers, but no USD figure is rendered in
+  the Markdown headline, sections, or footer.
 
 ## Cross-references
 

package/docs/contracts/command-clusters.md

@@ -49,7 +49,11 @@ column 1 of this table.
 | `sync-gitignore` | — | `fix` | new sub-command 2026-05-11 — cluster head retains the existing append-only sync as its default flow; `:fix` adds `--cleanup-legacy` semantics, scrubbing pre-`/agents/` runtime patterns wherever they appear in the consumer's `.gitignore` (inside or outside the managed block) and re-syncing the canonical entries. |
 | `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/reference/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |
 | `post-as` | — | `me` · `ghostwriter` | new cluster 2026-05-15 — consumer-facing write entry points. `:me` reads `.agent-user.md.voice_sample` and drafts in the maintainer's own voice (no disclosure footer — the user is the author); `:ghostwriter` is a thin alias for `/ghostwriter:write` with the mandatory disclosure footer. Both share the procedural [`write-engine`](write-engine.md) contract — style source and footer are the only axes of variation. |
-| `video` | — | `from-script` · `scene` · `storyboard` · `stitch` | new cluster 2026-05-17 — AI video generation pipeline. Cluster head orchestrates the full flow; `:scene` runs a single scene end-to-end (script → blueprint → still → motion → clip); `:storyboard` expands a script into per-scene blueprints + reference stills with character-lock JSON; `:from-script` walks a multi-scene script through storyboard + per-scene generation; `:stitch` concatenates scene clips with `ffmpeg` against a scene manifest. Provider-agnostic via the adapter contract under `scripts/ai-video/lib/adapter-contract.md`; cost-gated with mandatory `AIV_DRYRUN=true` default and explicit confirmation before live provider calls. |
+| `video` | — | `from-script` · `from-song` · `scene` · `storyboard` · `stitch` | new cluster 2026-05-17 — AI video generation pipeline. Cluster head orchestrates the full flow; `:scene` runs a single scene end-to-end (script → blueprint → still → motion → clip); `:storyboard` expands a script into per-scene blueprints + reference stills with character-lock JSON; `:from-script` walks a multi-scene script through storyboard + per-scene generation; `:from-song` builds a music-video from a song + reference images — derived/briefed timed script (via the `song-to-script` skill + `probe-audio.sh` hybrid segmentation), optional character-lock, then stitch with the song muxed as the master track and a mandatory AI-generation disclosure; `:stitch` concatenates scene clips with `ffmpeg` against a scene manifest. Provider-agnostic via the adapter contract under `scripts/ai-video/lib/adapter-contract.md`; cost-gated with mandatory `AIV_DRYRUN=true` default and explicit confirmation before live provider calls. |
+| `knowledge` | — | `ingest` · `list` · `forget` · `cross-repo` | local-knowledge namespace (employee-product Phase 7); `:cross-repo` added 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 4) — read-only targeted retrieval over opted-in `linked_projects` siblings (ADR-032 Option A), per [`cross-repo-retrieval`](cross-repo-retrieval.md). The pre-existing `ingest`/`list`/`forget` sub-commands are recorded in the registry here for the first time. |
+| `skills` | — | `discover` | new cluster 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 3) — local, explained skill-recommendation surface over the catalog + role shortlists + optional local analytics, per [`skill-discovery`](skill-discovery.md). Every result carries a non-empty `why`; no network, honours the analytics opt-out. |
+| `skill` | — | `preview` | new cluster 2026-05-30 (`road-to-leaner-core-and-discovery` Phase 5) — non-destructive skill/command preview: surfaces the declared steps + files/commands a skill would touch before it runs, per [`skill-dry-run`](skill-dry-run.md). Singular `skill` (one target) vs plural `skills` (the catalog) by design. |
+| `image` | — | `analyse` · `create` · `verify` | new cluster 2026-05-31 (`road-to-character-image-fidelity` Phase 4) — character-image fidelity surface mirroring `/video:*`. `:analyse` extracts a per-feature spec from an image and diffs it against a Canon Spec down to the smallest mole (OCR for lettered tattoos, per-section severity scores, canon-breaking hard gate); `:create` assembles a max-fidelity anchors-first generation prompt from the Canon Spec, governance- + provider-gated, `AIV_DRYRUN=true` default; `:verify` runs the analyser in loop mode against a candidate and reports the gate verdict + remaining diff with plateau/oscillation/budget stop conditions. Skills: [`image-analyser`](../../skills/image-analyser/SKILL.md) + [`image-creator`](../../skills/image-creator/SKILL.md); schema/rubric/loop in [`canon-spec.md`](../../skills/image-analyser/canon-spec.md). |
 
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
 collapses 26 atomics → 11 sub-command clusters. Sub-commands use

package/docs/contracts/cross-repo-retrieval.md

@@ -0,0 +1,64 @@
+---
+stability: experimental
+---
+
+# Cross-Repo Retrieval Contract
+
+> **Status** · v0 / design · 2026-05-30. Phase 4 of `road-to-leaner-core-and-discovery`.
+> Extends [ADR-032](../decisions/ADR-032-linked-projects-scope.md) **Option A** (passive,
+> read-only, opt-in-per-sibling, no bulk inclusion). Does **not** advance to Option B (auto-scan)
+> or Option C (implicit inclusion).
+
+## Problem
+
+The ADR-032 detector finds IDE-attached sibling repos but today only produces a passive *awareness
+note* — the agent knows a sibling exists but cannot pull context from it. This contract makes opted-in
+siblings a **read-only, targeted retrieval source**: the agent can fetch a shared type, an API contract
+the frontend consumes, or a config the sibling owns, **without bulk-including** its files.
+
+## Scope guards (Option A, non-negotiable)
+
+```
+READ-ONLY. OPT-IN-PER-SIBLING. TARGETED QUERY, NEVER A FULL-TREE SWEEP.
+```
+
+- **Read-only.** No writes to any sibling. Out-of-root writes still pass the host permission gate;
+  this surface never writes.
+- **Opt-in only.** Only siblings with `include: true` in `agents/settings/.agent-settings.local.yml`
+  → `linked_projects[]` are read. A sibling not opted in is never touched.
+- **Targeted query only.** Every retrieval is a bounded path-glob + content grep — never a blind walk.
+  A `large`-flagged sibling (per the detector) **requires a path scope** and rejects an unscoped query.
+- **Bounded.** ≤ `max_chunks` results per query (default 8). One concept per query.
+
+## Retrieval envelope
+
+Each match is returned as:
+
+```json
+{ "source_repo": "<sibling dir name>", "path": "<rel path in sibling>",
+  "chunk": "<≤ 2 KB redacted excerpt>", "freshness": "<git last-commit date or mtime>",
+  "match_reason": "<why this matched: path-glob or content term>" }
+```
+
+`chunk` passes the same redaction floor as `knowledge_ingest.py` — secrets and PII are scrubbed before
+any cross-repo text is surfaced. Cross-repo text never leaks a secret.
+
+## Memory integration — tagged + discounted
+
+Cross-repo matches projected into `memory_retrieve` carry `source: cross-repo` and are scored **below**
+local curated knowledge — the same 0.85× discount the `knowledge:` namespace already applies — so
+cross-repo context never outranks the project's own truth.
+
+## Surfaces
+
+- CLI: `agent-config linked-projects:list` — prints opted-in siblings (`path · detected_via · large`).
+  Closes the ADR-032 follow-up "expose the detector as a CLI subcommand for consumer reach."
+- CLI / agent: `/knowledge:cross-repo <query>` — renders matches as `source_repo · path · freshness · why`.
+  Honours opt-out (a sibling not `include: true` is never read); inert with a clear message when no
+  siblings are opted in.
+
+## Implementation
+
+`scripts/cross_repo_retrieve.py` (≤ 300 LOC). Pure-local, read-only, no network. Reuses the chunking +
+redaction floor from `knowledge_ingest.py`. Coverage: `tests/test_cross_repo_retrieve.py` against
+fixture sibling repos under `tests/fixtures/cross-repo/`.

package/docs/contracts/rule-router.md

@@ -123,6 +123,45 @@ The host agent reads `dist/router.json` once per session. Per turn:
 No runtime profile resolution — the profile is fixed at session
 start, the router lookup is keyword/phrase/path/intent matching only.
 
+## Kill-switch — thin-projection rollback (lean-initial-context Phase 2.3)
+
+Phase 3 of the lean-initial-context migration makes the per-tool projector
+emit the kernel full-bodied and every non-kernel rule as a one-line
+router-resolved pointer. That is the suite's biggest behavioural change, so
+it ships behind a **single documented flip** that restores today's
+full-eager projection:
+
+```yaml
+# .agent-settings.yml
+lean_projection:
+  # thin     = kernel full-bodied + non-kernel rules as router pointers (Phase 3)
+  # eager-all = every rule body inlined into every projection (today's behaviour)
+  mode: eager-all   # DEFAULT until Phase 3.1 ships + its benchmark gate is green
+```
+
+Revert procedure (one flip, no code change): set `lean_projection.mode:
+eager-all`, run `task generate-tools` (regenerates `.claude/`, `.cursor/`,
+`.clinerules/`, `.windsurfrules`) + `task sync` (`.agent-src/`, `.augment/`).
+The thin projector (Phase 3.1) MUST honour this key; with it absent or
+`eager-all` the projector behaves exactly as today. Default stays
+`eager-all` so the migration is opt-in and reversible by one line.
+
+### Staleness guard — `src → dist`
+
+A projection or router that drifts from source silently re-introduces the
+eager bytes (or a missing pointer target). Three CI gates enforce
+`src == dist`, all already wired into `task ci`:
+
+- `task check-router` (`compile_router.py --check`) — `dist/router.json`
+  must equal a fresh compile from frontmatter `triggers:`/`routes_to:`.
+- `task check-artefact-checksums` — every artefact's committed checksum
+  must match its current source bytes.
+- `task lint-projection-fidelity` — the per-tool projections must match
+  what the projector would emit from source.
+
+The thin projector inherits all three: a thin projection whose recorded
+source hash ≠ current source fails CI before it can ship a stale pointer.
+
 ## Linter contract (Phase 3.3)
 
 `scripts/skill_linter.py` extension enforces:

package/docs/contracts/skill-discovery.md

@@ -0,0 +1,80 @@
+---
+stability: experimental
+---
+
+# Skill Discovery Contract
+
+> **Status** · v0 / design · 2026-05-30. Phase 3 of `road-to-leaner-core-and-discovery`.
+> **Local-only.** Mirrors [`local-analytics.md`](local-analytics.md): no network egress, no POST,
+> no remote Worker. The recommender reads local files only and honours the analytics opt-out.
+
+## Problem
+
+The package ships 220 skills. Both council members named "218-skill paralysis" as the dominant
+discoverability risk. This contract defines a **recommendation surface** that turns existing signals
+into a short, *explained* shortlist — and explicitly **reuses** signals already on disk. It adds **no**
+new always-loaded layer (that would fail the Phase-1 leaner-core premise).
+
+## Input signals (all local, all already on disk)
+
+| Signal | Source | Used for |
+|---|---|---|
+| Skill catalog | `.agent-src/skills/*/SKILL.md` frontmatter (`name`, `description`, `domain`) | candidate universe + `domain` category |
+| Role shortlist | `agents/roles/<role>/skills.yml` (priority-ordered `id` + `why`) | `most-useful-for-role` |
+| Local analytics | `~/.event4u/agent-config/workspace/analytics/events.jsonl` (`event`, `data.role`, `data.task`, optional `data.skill`) | `recently-adopted`, `popular-in-role` |
+
+The role `skills.yml` is the strongest signal and is always present; analytics is optional and
+degrades gracefully (below).
+
+## Four recommendation classes
+
+| Class | Ranking basis | `why` shape |
+|---|---|---|
+| `most-useful-for-role` | role `skills.yml` priority order | the shortlist's own `why:` line |
+| `related-to-current-task` | skills sharing the `domain` of the role's shortlist skills, not already shortlisted | `same domain (<domain>) as your role's core skills` |
+| `recently-adopted` | analytics events in the last 14 days carrying a skill id (`data.skill`), most-recent first | `used <N>d ago in this workspace` |
+| `popular-in-role` | analytics skill-events filtered by `data.role`, by frequency | `launched <N>× by the <role> role locally` |
+
+## Explanation requirement — non-negotiable
+
+```
+EVERY RECOMMENDATION CARRIES A NON-EMPTY `why`. NEVER AN UNEXPLAINED SCORE.
+```
+
+Both council members flagged "opaque / self-referential recommendations without real usage signal" as
+the main risk. A result with no `why` is a contract violation. The `why` names the *signal* (role match,
+domain adjacency, recent-adoption, role-popularity) — never a bare number.
+
+## Graceful degradation — analytics absent or opted out
+
+Analytics is optional. When the JSONL file is missing, empty, or the opt-out is set
+(`AGENT_CONFIG_NO_LOCAL_ANALYTICS` env or `analytics.local: off` config — same checks as
+`local-analytics.md`), the two analytics-backed classes do not fabricate signal:
+
+- `recently-adopted` and `popular-in-role` fall back to **role-shortlist order** with an honest `why`
+  (`from your role shortlist — no local usage signal yet`).
+- `most-useful-for-role` and `related-to-current-task` are unaffected (catalog + role only).
+
+The recommender therefore always returns a useful, explained list — even on a fresh machine with no
+analytics history. Today's analytics schema logs `data.task` (not skill ids); the skill-level classes
+read the forward-compatible `data.skill` field and degrade to the role-shortlist fallback until it is
+populated. No class ever returns an empty `why`.
+
+## Local-only / no-network floor
+
+The recommender opens local files only. It performs no network I/O, writes nothing, and never emits a
+prompt or response body. It is read-only over the catalog, the role file, and (if present) the analytics
+log. This mirrors `local-analytics.md` and does not lift the 3.1.0 Hard-Floor.
+
+## Surfaces
+
+- CLI / agent: `/skills:discover [role]` → Markdown table (`skill · class · why · first command`).
+  Defaults to the active role experience when one is set; otherwise prompts for a role.
+- GUI: a right-rail "Suggested skills" strip on the Workspace tab, reusing the `/api/v1/workspace/*`
+  bridge (no new infra). Deferrable behind the CLI surface if the employee-roadmap right-rail blocker
+  is still open.
+
+## Implementation
+
+`scripts/skill_discovery.py` (≤ 300 LOC). Pure-local, no POST. Honours the analytics opt-out env + config.
+Coverage: `tests/test_skill_discovery.py` against a fixture catalog + fixture analytics JSONL.

package/docs/contracts/skill-dry-run.md

@@ -0,0 +1,47 @@
+---
+stability: experimental
+---
+
+# Skill Dry-Run / Preview Contract
+
+> **Status** · v0 / design · 2026-05-30. Phase 5 of `road-to-leaner-core-and-discovery`.
+> The council's missing-item catch: with 220 skills, non-dev personas need a non-destructive way
+> to see what a skill/command will do **before** running it.
+
+## What "preview" means
+
+A preview reads a skill's **declared intent** — its frontmatter and `## Steps` body — and renders a
+plain-language "this skill will…" summary. It surfaces:
+
+- the skill's **declared steps** (the `## Steps` section headings);
+- its **execution type** (`manual` / `assisted` / `automated`, default `manual`) and **handler**
+  (`none` / `shell` / `php` / `node` / `internal`);
+- its declared **`allowed_tools`**;
+- any **file or command targets** named in the body (backtick paths, `python3 scripts/…` invocations).
+
+## Explicit non-goals
+
+```
+PREVIEW IS NOT A SANDBOX. IT DOES NOT EXECUTE A FENCED COPY OF THE SKILL.
+IT IS NOT A GUARANTEE OF SIDE-EFFECT-FREENESS FOR SKILLS WITH AN `execution` BLOCK.
+```
+
+Preview reads declared intent — it does not run the skill, does not dry-run its commands, and cannot
+prove a skill is harmless. It tells you what the skill *says* it will touch, so you can decide whether
+to run it. For `execution: manual` skills (the default), it states plainly: **instructional only — no
+automatic execution** (per [`runtime-safety`](../../.agent-src/rules/runtime-safety.md): `manual` is
+instructional, `assisted` must propose before executing).
+
+## Surface
+
+- CLI / agent: `/skill:preview <name>` — plain-language summary by default; `--technical` shows the raw
+  frontmatter + step list.
+- Script: `scripts/skill_preview.py <name> [--technical] [--format text|json]`.
+
+Plain-language mode reuses the plain-explain tone (employee-roadmap Phase 6). A malformed or missing
+SKILL.md degrades to a **structured error**, never a crash.
+
+## Implementation
+
+`scripts/skill_preview.py` (≤ 250 LOC). Read-only over `.agent-src/skills/<name>/SKILL.md`. No network,
+no execution. Coverage: `tests/test_skill_preview.py`.

package/docs/contracts/value-dashboard-spec.md

@@ -267,9 +267,13 @@ copies it verbatim into the dashboard.
   Saves output tokens — when the corpus rewards it.
 - **Ohne Paket / Mit Paket** — "without the package" /
   "with the package" — the two arms of the A/B comparison.
-- **€-per-1k-requests** — token cost at the reference scale
-  (1,000 requests of the average shape, priced at the current
-  Sonnet rates in `internal/bench/pricing.yaml`).
+- **Δ Tokens** — input-token difference per request vs. the baseline.
+  The rendered dashboard reports cost in **tokens only** — no € figure.
+  A €/USD comparison would assume per-call API pricing, which the many
+  users on subscriptions do not pay; tokens are the currency-neutral
+  metric. The `eur_delta` fields remain in the JSON for back-compat but
+  are not rendered. (Historical € figures elsewhere in this spec are
+  dated examples, kept as record.)
 
 ## Honest baseline appendix
 

package/docs/contracts/value-report-schema.md

@@ -80,10 +80,15 @@ totals:
   cumulative_pct: <signed float>         # net % of baseline
   net_verdict: net-saving | net-cost | break-even   # by sign of cumulative_pct
 notes:
-  - "Token→€ conversion priced at <model_tier> rates from <pricing source>."
+  - "Cost is reported in tokens only — no € figure (API pricing misleads subscription users)."
   - "<other invariants surfaced as plain prose>"
 ```
 
+> **Rendering note.** The `eur_delta` / `cumulative_eur_delta` /
+> `pricing_sourced_on` fields stay in the JSON for back-compat, but the
+> rendered dashboard (`docs/value.md`) shows **tokens only** — no € column,
+> no €-per-1k figure, no NETTO € line. See `scripts/render_value_md.py`.
+
 ## Invariants
 
 - **No silent drops.** Missing input → emit the rung with

package/docs/decisions/ADR-032-linked-projects-scope.md

@@ -99,9 +99,13 @@ telemetry.
 
 ## Open follow-ups
 
-- **Consumer detector reachability:** the detector lives in `scripts/_lib/`;
-  exposing it as an `agent-config` CLI subcommand for consumer installs is a
-  follow-up. Import-reachable in this repo / co-located maintainer setups today.
+- **Consumer detector reachability:** ✅ **Closed (2026-05-30, `road-to-leaner-core-and-discovery`
+  Phase 4).** The detector is now exposed as `agent-config linked-projects:list`
+  (`scripts/linked_projects_list.py`, registered in `src/cli/registry.ts` + `scripts/_dispatch.bash`),
+  wrapping `scripts/_lib/linked_projects.detect_linked_projects` + the `.agent-settings.local.yml`
+  opt-in cascade. Cross-repo *retrieval* over the opted-in siblings ships alongside it
+  (`/knowledge:cross-repo`, `scripts/cross_repo_retrieve.py`) per
+  [`cross-repo-retrieval`](../contracts/cross-repo-retrieval.md).
 - **Multi-agent verification:** only Claude Code was empirically validated.
   Cursor / Augment / Copilot are unverified — the guide's manual snippet covers
   them until an interactive per-IDE test is run.

package/docs/getting-started.md

@@ -129,7 +129,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 78 rules. No configuration needed.
+This is enforced automatically by 79 rules. No configuration needed.
 
 ---
 
@@ -169,7 +169,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 135 active commands](../.agent-src/commands/)
+→ [Browse all 145 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guides/cross-repo-linked-projects.md

@@ -77,6 +77,13 @@ If it reports the name, cross-repo access works. An out-of-root edit will prompt
 for confirmation, then succeed — that is expected (the agent's permission gate
 still applies).
 
+## Next: pull context from a sibling
+
+Detection makes the agent *aware* of a sibling. To have it **read** targeted
+context from one — a shared type, an API contract, a config — without copying
+the sibling's files in, see [Cross-repo retrieval](cross-repo-retrieval.md)
+(`agent-config linked-projects:list` + `/knowledge:cross-repo`).
+
 ## Tell us what works
 
 Auto-detection is verified for Claude Code only. If you use Cursor, Augment, or

package/docs/guides/cross-repo-retrieval.md

@@ -0,0 +1,61 @@
+# Cross-repo retrieval — pull sibling context without copying files
+
+Once the agent knows about a sibling repo ([detection guide](cross-repo-linked-projects.md)),
+cross-repo retrieval lets it **read targeted context** from that sibling — a shared type, an
+API contract the frontend consumes, a config the sibling owns — without bulk-including the
+sibling's files. It is the read layer on top of detection.
+
+It stays inside [ADR-032](../decisions/ADR-032-linked-projects-scope.md) Option A: read-only,
+opt-in per sibling, targeted query only. No full-tree sweep, no implicit inclusion, no writes.
+
+## 1. See which siblings are reachable
+
+```
+agent-config linked-projects:list
+```
+
+Prints the opted-in siblings as `path · detected via · large`. Add `--all` to see detected
+siblings you have not decided on yet. A sibling only becomes reachable once you set
+`include: true` for it in `agents/settings/.agent-settings.local.yml` (see the detection guide).
+
+## 2. Retrieve targeted context
+
+```
+/knowledge:cross-repo "OrderApiContract"
+```
+
+Under the hood:
+
+```bash
+python3 scripts/cross_repo_retrieve.py "OrderApiContract" [--path-scope 'src/*.ts'] [--max-chunks 8]
+```
+
+You get a bounded table — `source_repo · path · freshness · why` — drawn only from opted-in
+siblings. Each chunk is redacted (secrets and PII are scrubbed before anything is shown), so
+no credential ever crosses a repo boundary.
+
+## 3. Scope large siblings
+
+A sibling flagged `large` by the detector **requires** a `--path-scope` glob:
+
+```
+/knowledge:cross-repo "config" --path-scope 'packages/shared/**'
+```
+
+Without a scope, a large sibling is skipped with a note — this keeps retrieval cheap and
+targeted instead of walking a huge tree.
+
+## How it ranks in memory
+
+When a skill retrieves memory with the `cross-repo` type, matches are tagged `source: cross-repo`
+and scored **below** the project's own curated knowledge — so cross-repo context informs the
+answer but never outranks your own repo's truth.
+
+## Notes
+
+- **Read-only.** The surface never writes to a sibling. Out-of-root writes still pass the host
+  permission gate; cross-repo retrieval writes nothing.
+- **Opt-in only.** A sibling that is not `include: true` is never read.
+- **Targeted only.** Path-glob + content grep, never a blind full walk.
+- Contract: [`cross-repo-retrieval`](../contracts/cross-repo-retrieval.md). Detection story:
+  [`cross-repo-linked-projects`](cross-repo-linked-projects.md).

package/docs/guides/skill-discovery.md

@@ -0,0 +1,71 @@
+# Skill discovery — a 3-minute walkthrough
+
+The package ships 220 skills. You do not need to know them. `/skills:discover`
+turns the catalog into a short, **explained** shortlist for your role — every
+row tells you *why* it is suggested, so you never adopt a skill on faith.
+
+It is local-only: it reads the skill catalog, your role's shortlist, and (if
+present) your local-analytics log. No network, no writes.
+
+## 1. Run it for your role
+
+```
+/skills:discover sales
+```
+
+Or, with a role experience already active, just `/skills:discover` — it picks
+up `roles.active_role` from `.agent-settings.yml`.
+
+Under the hood the command runs:
+
+```bash
+python3 scripts/skill_discovery.py --role sales
+```
+
+## 2. Read the `why` column
+
+The output is a table. The third column is the point — it names the **signal**
+behind each suggestion, never a bare score:
+
+```
+| skill                  | class                   | why                                                       | first command            |
+|------------------------|-------------------------|-----------------------------------------------------------|---------------------------|
+| refine-prompt          | most-useful-for-role    | Tightens fuzzy buyer briefs before drafting               | Skill › refine-prompt     |
+| voice-and-tone-design  | most-useful-for-role    | Locks the deal voice across customer + procurement        | Skill › voice-and-tone-design |
+| competitive-positioning| most-useful-for-role    | Surfaces the ours-vs-theirs delta when a competitor named | Skill › competitive-positioning |
+| activation-design      | related-to-current-task | same domain (product) as your sales core skills           | Skill › activation-design |
+| customer-research      | recently-adopted        | from your role shortlist — no local usage signal yet      | Skill › customer-research |
+| funnel-analysis        | popular-in-role         | from your role shortlist — no local usage signal yet      | Skill › funnel-analysis   |
+```
+
+The four classes:
+
+- **most-useful-for-role** — your role's curated priority shortlist.
+- **related-to-current-task** — same-domain peers you have not shortlisted yet.
+- **recently-adopted** — what you actually used recently (from local analytics);
+  on a fresh machine with no usage history it honestly says *"no local usage
+  signal yet"* and falls back to your shortlist instead of inventing a number.
+- **popular-in-role** — what your role launches most locally (same fallback).
+
+## 3. Adopt one
+
+Pick a row, read its `why`, and start with the `first command`. Unsure what a
+skill will actually do before you commit? Preview it first:
+
+```
+/skill:preview competitive-positioning
+```
+
+That is the safe adoption loop: **discover → preview → run**.
+
+## Notes
+
+- **Local-only.** `/skills:discover` never touches the network and writes
+  nothing. It reads the catalog, your role file, and the optional analytics log.
+- **Analytics is optional.** Opt out with `AGENT_CONFIG_NO_LOCAL_ANALYTICS=1`
+  or `analytics.local: off` in `.agent-settings.yml`. The two usage-driven
+  classes then fall back to your role shortlist — the list is still useful, just
+  without the personalised signal.
+- **`--format json`** emits the same data machine-readably; **`--limit N`** sets
+  how many results per class (default 5).
+- Contract: [`skill-discovery`](../contracts/skill-discovery.md).

package/docs/guides/skill-preview.md

@@ -0,0 +1,71 @@
+# Skill preview — see what a skill does before you run it
+
+With 220 skills and some that run commands, you should not have to run a skill to
+find out what it touches. `/skill:preview` reads a skill's **declared intent** —
+its steps, execution type, tools, and any file/command targets — and renders a
+plain-language summary. Read-only: it never runs the skill.
+
+This is the middle of the safe adoption loop: **discover → preview → run**.
+
+## 1. Discover, then preview
+
+Find a candidate with [`/skills:discover`](skill-discovery.md), then look before you leap:
+
+```
+/skill:preview competitive-positioning
+```
+
+Under the hood:
+
+```bash
+python3 scripts/skill_preview.py competitive-positioning
+```
+
+## 2. Read the summary
+
+A **manual** skill (the default) is pure guidance — preview says so plainly:
+
+```
+# Preview — `accessibility-auditor`
+
+**Execution: instructional only.** This skill does not run anything automatically —
+it guides the agent step by step.
+
+_No tools, commands, or file targets declared — pure guidance._
+```
+
+An **assisted** skill proposes actions you approve — preview surfaces the command
+and tools it declares:
+
+```
+# Preview — `adr-create`
+
+**Execution: assisted** (handler `shell`). It will *propose* actions for you to
+approve — it never executes silently.
+
+This skill will walk these steps:
+- Pick the next ADR number
+- Write the standard template
+- Regenerate the index
+
+Declared command: `python3 scripts/adr/regenerate_index.py`
+```
+
+Add `--technical` for the raw frontmatter + numbered step list.
+
+## 3. Decide, then run
+
+Preview hands the decision back to you. If the declared steps and targets look
+right, invoke the skill. If not, skip it — you have spent zero side effects
+finding out.
+
+## What preview is not
+
+- **Not a sandbox.** It does not run the skill or a fenced copy of it.
+- **Not a safety guarantee.** It shows what the skill *declares* it will touch —
+  it cannot prove a skill with an `execution` block is side-effect-free.
+
+A malformed or missing skill yields a structured error, never a crash.
+
+Contract: [`skill-dry-run`](../contracts/skill-dry-run.md). Pairs with
+[`skill-discovery`](skill-discovery.md) as the discover → preview → run loop.