@event4u/agent-config 5.10.0 → 6.0.0

package/docs/guidelines/agent-infra/roadmap-progress-mechanics.md

@@ -10,7 +10,7 @@ _Origin: migrated from `.agent-src.uncondensed/rules/roadmap-progress-sync.md` p
 # Roadmap Progress Sync
 
 > **Enforced by (defence in depth):**
-> 1. [`scripts/roadmap_progress_hook.py`](../../scripts/roadmap_progress_hook.py)
+> 1. [`scripts/roadmap_progress_hook.py`](../../src/scripts/roadmap_progress_hook.py)
 >    on Augment + Claude Code (`PostToolUse`) — auto-regen on write.
 > 2. `.git/hooks/pre-commit` (installed by `scripts/install-hooks.sh`) —
 >    blocks any commit whose staged set touches `agents/roadmaps/` or

package/docs/guidelines/agent-infra/self-improvement-pipeline.md

@@ -32,7 +32,7 @@ blocks — it does not hand a half-filled doc to the next stage.
 - **Input:** raw observation (PR link, log line, review comment).
 - **Output:** learning note at `agents/learnings/<date>-<slug>.md`
   with frontmatter `source`, `evidence[]` (≥1 link), `stage: captured`.
-- **Guardrails:** nothing is written into `.agent-src/` at this stage.
+- **Guardrails:** nothing is written into `dist/agent-src/` at this stage.
   Learnings live in the consumer repo until promoted.
 
 ### Stage 2 — Classify

package/docs/guidelines/agent-infra/verify-before-complete-demos.md

@@ -28,7 +28,7 @@ Agent: Ja, sollte jetzt durchlaufen — ich habe die fehlende
 Bedingung ergänzt und die Tests müssten grün sein.
 ```
 
-**Failure mode:** "sollte", "müssten" are red-flag hedges (§ Red
+**Failure mode:** "sollte", "müssten" are red-flag hedges (§ Red  <!-- md-language-check: ignore -->
 flags — STOP immediately). No fresh command output in this message.
 The claim rides on inference, not evidence.
 

package/docs/guidelines/augment-portability-patterns.md

@@ -40,7 +40,7 @@ Skills, rules, commands, guidelines, personas, and context docs run in
 **consumer projects**, which may not have Task installed. **Never**
 reference a `task <something>` invocation inside any artefact file
 under `.agent-src.uncondensed/{skills,rules,commands,guidelines,personas,contexts}/`
-(and therefore also not in the condensed mirror under `.agent-src/`).
+(and therefore also not in the condensed mirror under `dist/agent-src/`).
 Use direct script invocations instead.
 
 ## Consumer CLI — `./agent-config`

package/docs/guides/local-analytics.md

@@ -1,6 +1,6 @@
 # Local analytics — a 3-minute walkthrough
 
-> Phase 7 of [`road-to-employee-product-and-external-proof`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md).
+> Phase 7 of [`road-to-employee-product-and-external-proof`](../../agents/roadmaps/archive/road-to-employee-product-and-external-proof.md).
 > Contract: [`docs/contracts/local-analytics.md`](../contracts/local-analytics.md).
 
 ## What this is

package/docs/guides/local-knowledge.md

@@ -8,7 +8,7 @@ keep-beta-until: 2026-08-24
 Point the agent at a folder of local files (PDFs, Markdown, Word docs, spreadsheets). It chunks, redacts PII + secrets, and persists into the agent memory namespace — local-only, single-user, no OAuth, no remote fetch.
 
 Contract: [`local-knowledge-ingestion`](../contracts/local-knowledge-ingestion.md).
-Roadmap home: `agents/roadmaps/road-to-employee-product-and-external-proof.md` Phase 2.
+Roadmap home: `agents/roadmaps/archive/road-to-employee-product-and-external-proof.md` Phase 2.
 
 ## Prerequisites
 
@@ -123,5 +123,5 @@ Forget is atomic — no partial state. Pinned ingests are dropped the same as un
 ## See also
 
 - [`local-knowledge-ingestion`](../contracts/local-knowledge-ingestion.md) — contract (input shapes, bounds, storage, redaction).
-- [`/knowledge ingest`](../../.agent-src/commands/knowledge/ingest.md) · [`/knowledge list`](../../.agent-src/commands/knowledge/list.md) · [`/knowledge forget`](../../.agent-src/commands/knowledge/forget.md)
-- [`markitdown` skill](../../.agent-src/skills/markitdown/SKILL.md) — peer-side adapter for binary formats.
+- [`/knowledge ingest`](../../dist/agent-src/commands/knowledge/ingest.md) · [`/knowledge list`](../../dist/agent-src/commands/knowledge/list.md) · [`/knowledge forget`](../../dist/agent-src/commands/knowledge/forget.md)
+- [`markitdown` skill](../../dist/agent-src/skills/markitdown/SKILL.md) — peer-side adapter for binary formats.

package/docs/hook-payload-capture.md

@@ -166,7 +166,7 @@ If the captured shape diverges from the docs-verified extractor
 branch, that is the trigger for a code patch — open a tiny new roadmap
 under `agents/roadmaps/` for the divergence work, do **not** edit the
 archived roadmap to track new code work
-(see [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md)).
+(see [`no-roadmap-references`](../dist/agent-src/rules/no-roadmap-references.md)).
 
 ## Final verify
 
@@ -188,7 +188,7 @@ python3 -m pytest tests/hooks/ -q
 ```
 
 Per
-[`commit-policy`](../.agent-src/rules/commit-policy.md):
+[`commit-policy`](../dist/agent-src/rules/commit-policy.md):
 do **not** commit unless explicitly told to. The user owns the commit
 step.
 
@@ -213,9 +213,9 @@ before paste because the redacted output goes into a tracked file
 
 ## Sources
 
-- Capture engine: [`scripts/hooks/dispatch_hook.py`](../scripts/hooks/dispatch_hook.py) — `_maybe_capture_payload`
-- Redactor: [`scripts/redact_hook_capture.py`](../scripts/redact_hook_capture.py)
-- Per-platform install logic: [`scripts/install.py`](../scripts/install.py) — search `ensure_<platform>_bridge` / `ensure_<platform>_user_hooks`
+- Capture engine: [`scripts/hooks/dispatch_hook.py`](../src/scripts/hooks/dispatch_hook.py) — `_maybe_capture_payload`
+- Redactor: [`scripts/redact_hook_capture.py`](../src/scripts/redact_hook_capture.py)
+- Per-platform install logic: [`scripts/install.py`](../src/scripts/install.py) — search `ensure_<platform>_bridge` / `ensure_<platform>_user_hooks`
 - Platform matrix + payload schemas: [`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md)
 - Hook architecture: [`docs/contracts/hook-architecture-v1.md`](contracts/hook-architecture-v1.md)
 - Archived roadmap with per-phase paste sections: [`agents/roadmaps/archive/road-to-verified-chat-history-platforms.md`](../agents/roadmaps/archive/road-to-verified-chat-history-platforms.md)

package/docs/installation.md

@@ -448,7 +448,7 @@ copilot plugin install agent-config@event4u-agent-config
 ### Team auto-setup for plugins
 
 To auto-recommend the plugin for your team, add the marketplace to project settings.
-See [`templates/consumer-settings/`](../templates/consumer-settings/) for ready-to-use config templates per tool.
+See [`src/templates/consumer-settings/`](../templates/consumer-settings/) for ready-to-use config templates per tool.
 
 For marketplace registration (required once before `plugin install`):
 
@@ -500,8 +500,8 @@ UI. The package builds one ZIP per cloud-eligible skill.
    `cloud_safe: noop` (filesystem-bound, e.g. `chat-history`,
    `file-editor`) are bundled with a stripped no-op variant; T3-H
    skills (hard filesystem dependencies) are excluded by default.
-   See [`scripts/audit_cloud_compatibility.py`](../scripts/audit_cloud_compatibility.py)
-   for per-skill tier and [`scripts/build_cloud_bundle.py`](../scripts/build_cloud_bundle.py)
+   See [`scripts/audit_cloud_compatibility.py`](../src/scripts/audit_cloud_compatibility.py)
+   for per-skill tier and [`scripts/build_cloud_bundle.py`](../src/scripts/build_cloud_bundle.py)
    for the gating logic.
 
 2. **Upload to Claude.ai**

package/docs/mcp-registries.md

@@ -0,0 +1,94 @@
+# MCP registries & cross-tool install landscape
+
+> Reference material. Where to *discover* MCP servers, what each registry gives
+> you, and how to install one into each agent today — without our own tooling.
+>
+> Background: we evaluated building a read-only cross-agent MCP discovery helper
+> (`ADR-086`) and decided **not to** — existing tooling already covers it. This
+> doc captures the surviving value: the registry comparison and the per-agent
+> manual install path. See [`docs/mcp.md`](mcp.md) for generating *your own*
+> `mcp.json` across tools.
+
+## The three registries (verified 2026-06-11)
+
+| Dimension | Official registry | Glama | Smithery |
+|---|---|---|---|
+| Role | Vendor-neutral **catalog** (discovery spec) | Catalog **superset** + quality/safety scoring | Catalog **+ installer** |
+| Canonical shape | `server.json` | Own schema (maps to `server.json` fields) | Own schema |
+| Approx. scale | Hundreds+ (paginated, growing) | ~32k servers | Own index |
+| Writes client config? | **No** (discovery only) | **No** (discovery only) | **Yes** — `smithery install X --client <c>` |
+| API auth | **None** — public read | **None** — public read | n/a (CLI) |
+| Query endpoint | `GET registry.modelcontextprotocol.io/v0/servers?search=&limit=&cursor=` | `GET glama.ai/api/mcp/v1/servers?first=&after=` | `smithery` CLI / site |
+
+Both catalog APIs were live-checked: each returns `200` with **no API key**. The
+official registry returns `{servers:[{server:<server.json>,_meta:…}],metadata:{nextCursor,count}}`;
+Glama returns `{pageInfo:{endCursor,hasNextPage},servers:[{id,name,namespace,slug,
+description,environmentVariablesJsonSchema,repository,spdxLicense,tools,url}]}`.
+
+> Glama's quality/safety **score is a popularity/heuristic signal, not a verified
+> security property** — treat it as a hint, never a guarantee.
+
+## Installing a discovered server per agent
+
+For most agents, **Smithery already writes the config for you** (the read-write
+path — harder than discovery). Its CLI (`smithery-ai/cli`, `src/config/clients.ts`
+`VALID_CLIENTS`, verified 2026-06-11) configures 23 clients, including:
+
+`smithery install <server> --client <client>` where `<client>` ∈ **claude** (Desktop),
+**claude-code**, **cursor**, **windsurf**, **cline**, **vscode** / **vscode-insiders**
+(Copilot), plus codex, gemini-cli, zed, goose, kiro, trae, and others.
+
+That covers Claude Code, Cursor, Windsurf, Cline, and VS Code/Copilot. **Augment is
+the gap** — it is not in Smithery's client list, so install it manually (below).
+
+## Augment — manual MCP install (no tooling needed)
+
+Augment supports the **standard `mcpServers` object map** via its built-in
+**Import from JSON** (Augment Settings Panel → gear icon → Import from JSON).
+Paste, for a stdio server:
+
+```json
+{
+  "mcpServers": {
+    "<server-name>": {
+      "command": "npx",
+      "args": ["-y", "<package>"]
+    }
+  }
+}
+```
+
+…or for a remote server:
+
+```json
+{
+  "mcpServers": {
+    "<server-name>": {
+      "url": "https://example.com/mcp",
+      "type": "sse"
+    }
+  }
+}
+```
+
+Secret env vars get their own section in the Settings Panel — paste placeholders,
+fill in the real value there; never commit a real secret. Augment also offers
+**Easy MCP** (one-click) for common servers, and the JetBrains plugin manages MCP
+through its own settings UI.
+
+> Why no automated Augment writer? Augment's only file-writable surface is VS Code
+> `settings.json` under the nested key `augment.advanced.mcpServers` (an array of
+> `{name, command, args}`), which the official docs do not commit to as a stable
+> contract. Smithery's writer targets flat, dedicated config files, so it cannot
+> safely write Augment's nested/shared surface. Manual Import-from-JSON is the
+> supported path today.
+
+## Reopen criteria — automated Augment install
+
+Reconsidered (e.g. native Smithery support or our own writer) only if **all** hold:
+
+1. ≥ 3 users independently request automated Smithery → Augment install.
+2. Augment documents the `settings.json` MCP schema as a **stable** contract.
+3. The Smithery maintainers pre-approve the integration approach.
+
+Until then this stays manual by design (`ADR-086`, AI-council convergence 2026-06-11).

package/docs/mcp-server.md

@@ -28,10 +28,10 @@ shells**. It is a read-only instructional surface — see
 
 | Primitive | URIs | Source | Count (this package) |
 |---|---|---|---|
-| `prompts/list` + `prompts/get` | `skill.<name>`, `command.<name>` | `.agent-src/skills/`, `.agent-src/commands/` | 174 skills + 104 commands |
-| `resources/list` + `resources/read` | `rule://<stem>` | `.agent-src/rules/` | 60 rules |
+| `prompts/list` + `prompts/get` | `skill.<name>`, `command.<name>` | `dist/agent-src/skills/`, `dist/agent-src/commands/` | 174 skills + 104 commands |
+| `resources/list` + `resources/read` | `rule://<stem>` | `dist/agent-src/rules/` | 60 rules |
 | ↳ | `guideline://<relpath>` | `docs/guidelines/` | 69 guidelines |
-| ↳ | `context://<relpath>` | `.agent-src/contexts/` | 31 contexts |
+| ↳ | `context://<relpath>` | `dist/agent-src/contexts/` | 31 contexts |
 
 All resources are served with `mimeType: text/markdown`. Pagination is
 cursor-based (default page size: 100). Hot-reload triggers automatically on
@@ -148,7 +148,7 @@ boots cleanly:
 
 | Symptom | Fix |
 |---|---|
-| Client shows no prompts | Confirm the `cwd` points at the repo root (where `.agent-src/` lives), not at `scripts/`. |
+| Client shows no prompts | Confirm the `cwd` points at the repo root (where `dist/agent-src/` lives), not at `scripts/`. |
 | `ModuleNotFoundError: mcp` | Re-run `task mcp:setup`. The MCP runtime is isolated in `.venv-mcp/` — the project's base Python 3.9 deliberately does not see it. |
 | Stale prompts after editing | Hot-reload triggers on mtime; touch the file or reissue `resources/list`. |
 | Client refuses to start the server | Check the client's log for the full command. Most clients require **absolute** paths in `command` and `cwd`. |

package/docs/mcp.md

@@ -138,6 +138,9 @@ secret tool you already use into the process environment before you run
 
 ## Related
 
+- [`docs/mcp-registries.md`](mcp-registries.md) — where to *discover* MCP servers
+  (official registry / Glama / Smithery) and how to install one per agent, incl.
+  Augment's manual Import-from-JSON path.
 - [`.agent-src.uncondensed/skills/mcp/SKILL.md`](../.agent-src.uncondensed/skills/mcp/SKILL.md) — MCP server
   selection and usage patterns.
 - [`agents/roadmaps/archive/road-to-mcp.md`](../agents/roadmaps/archive/road-to-mcp.md) — archived roadmap that produced this feature.

package/docs/parity/ruflo.md

@@ -23,15 +23,15 @@ soak in [`bench.json`](bench.json) flips from `warmup` to `baseline_ready`
 
 | # | Ruflo pattern | Verdict | Evidence |
 |---|---|---|---|
-| 1 | **Cost-tracker plugin** — real model pricing, per-1M, separated input/output/cache | `[x] covered by` | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) + [`internal/bench/pricing.yaml`](../../bench/pricing.yaml) (Haiku/Sonnet/Opus per-1M, input/output/cache-read/cache-write split). Step-11 Phase 1. |
-| 2 | **Auto-capture from session jsonl** — reads Claude Code log, no manual tracking | `[x] covered by` | [`scripts/cost/track.mjs`](../../scripts/cost/track.mjs) reads `~/.claude/projects/*/sessions/*.jsonl` automatically. Step-11 Phase 1 Step 1. |
-| 3 | **50/75/90/100 % budget ladder with hard stop** | `[x] covered by` | [`scripts/cost/budget.mjs`](../../scripts/cost/budget.mjs) — exit codes 0/1/2/3 per tier; opt-in fail-closed via `cost.enforcement` setting. Fixtures: `tests/fixtures/cost/budget/{under-50,at-100,over-100}/`. Step-11 Phase 2. |
+| 1 | **Cost-tracker plugin** — real model pricing, per-1M, separated input/output/cache | `[x] covered by` | [`scripts/cost/track.mjs`](../../src/scripts/cost/track.mjs) + [`internal/bench/pricing.yaml`](../../bench/pricing.yaml) (Haiku/Sonnet/Opus per-1M, input/output/cache-read/cache-write split). Step-11 Phase 1. |
+| 2 | **Auto-capture from session jsonl** — reads Claude Code log, no manual tracking | `[x] covered by` | [`scripts/cost/track.mjs`](../../src/scripts/cost/track.mjs) reads `~/.claude/projects/*/sessions/*.jsonl` automatically. Step-11 Phase 1 Step 1. |
+| 3 | **50/75/90/100 % budget ladder with hard stop** | `[x] covered by` | [`scripts/cost/budget.mjs`](../../src/scripts/cost/budget.mjs) — exit codes 0/1/2/3 per tier; opt-in fail-closed via `cost.enforcement` setting. Fixtures: `tests/fixtures/cost/budget/{under-50,at-100,over-100}/`. Step-11 Phase 2. |
 | 4 | **Measured-vs-claimed disclaimer** — every percentage tagged "claimed upstream" | `[x] covered by` | One-line `**Measured-vs-claimed disclaimer:**` header block on all 9 active roadmaps in `agents/roadmaps/`. Verified 2026-05-16. Step-11 Phase 5 Step 4. |
-| 5 | **Smoke test as contract** — `bash scripts/smoke.sh` with declared baseline | `[x] covered by` | Four per-tier smoke scripts: [`scripts/smoke/kernel.sh`](../../scripts/smoke/kernel.sh), [`router.sh`](../../scripts/smoke/router.sh), [`schema.sh`](../../scripts/smoke/schema.sh), [`skills.sh`](../../scripts/smoke/skills.sh). Declared baselines in [`docs/contracts/smoke-contracts.md`](../contracts/smoke-contracts.md). CI gate: [`.github/workflows/smoke.yml`](../../.github/workflows/smoke.yml). Step-11 Phase 3. |
-| 6 | **Per-plugin ADR directory** — `docs/adrs/0001-*.md` co-located with subsystem | `[x] covered by` | Six bootstrap ADRs under [`docs/adrs/{cost,memory,router,schema,smoke,telegraph}/`](../adrs/). Coverage gate: [`scripts/audit_adr_coverage.py`](../../scripts/audit_adr_coverage.py) (`task lint-adr-coverage`). Contract: [`docs/contracts/adr-layout.md`](../contracts/adr-layout.md). Step-11 Phase 4. |
-| 7 | **Namespace contract** — `<stem>-<intent>` kebab-case, reserved-names list | `[x] covered by` | [`scripts/lint_namespace.py`](../../scripts/lint_namespace.py) enforces shape + length floors + reserved-names + skill-dir-matches-name across 430 names · 0 issues. Contract: [`docs/contracts/namespace.md`](../contracts/namespace.md). CI gate: `task lint-namespace`. Step-11 Phase 5 Step 1. |
+| 5 | **Smoke test as contract** — `bash scripts/smoke.sh` with declared baseline | `[x] covered by` | Four per-tier smoke scripts: [`scripts/smoke/kernel.sh`](../../src/scripts/smoke/kernel.sh), [`router.sh`](../../src/scripts/smoke/router.sh), [`schema.sh`](../../src/scripts/smoke/schema.sh), [`skills.sh`](../../src/scripts/smoke/skills.sh). Declared baselines in [`docs/contracts/smoke-contracts.md`](../contracts/smoke-contracts.md). CI gate: [`.github/workflows/smoke.yml`](../../.github/workflows/smoke.yml). Step-11 Phase 3. |
+| 6 | **Per-plugin ADR directory** — `docs/adrs/0001-*.md` co-located with subsystem | `[x] covered by` | Six bootstrap ADRs under [`docs/adrs/{cost,memory,router,schema,smoke,telegraph}/`](../adrs/). Coverage gate: [`scripts/audit_adr_coverage.py`](../../src/scripts/audit_adr_coverage.py) (`task lint-adr-coverage`). Contract: [`docs/contracts/adr-layout.md`](../contracts/adr-layout.md). Step-11 Phase 4. |
+| 7 | **Namespace contract** — `<stem>-<intent>` kebab-case, reserved-names list | `[x] covered by` | [`scripts/lint_namespace.py`](../../src/scripts/lint_namespace.py) enforces shape + length floors + reserved-names + skill-dir-matches-name across 430 names · 0 issues. Contract: [`docs/contracts/namespace.md`](../contracts/namespace.md). CI gate: `task lint-namespace`. Step-11 Phase 5 Step 1. |
 | 8 | **Topology choices in swarm** — `hierarchical / mesh / star / adaptive` with anti-drift defaults | `[x] covered by` | [`.agent-src.uncondensed/skills/subagent-orchestration/SKILL.md`](../../.agent-src.uncondensed/skills/subagent-orchestration/SKILL.md) `Topology hints` subsection — 7-row table mapping each mode to topology + Ruflo anti-drift default (`hierarchical, 6–8 agents, raft consensus`). Step-11 Phase 5 Step 2. |
-| 9 | **MCP-tool count + source-line refs** — every tool with `<file>:<line>` citation | `[x] covered by` | [`docs/contracts/mcp-tool-inventory.md`](../contracts/mcp-tool-inventory.md) — 20 tools (9 stdio-implemented · 11 discovery stubs) each with catalog `<file>:<line>` + handler `<file>:<line>`. Generator: [`scripts/audit_mcp_tools.py`](../../scripts/audit_mcp_tools.py). CI drift gate: `task lint-mcp-inventory`. Step-11 Phase 5 Step 3. |
+| 9 | **MCP-tool count + source-line refs** — every tool with `<file>:<line>` citation | `[x] covered by` | [`docs/contracts/mcp-tool-inventory.md`](../contracts/mcp-tool-inventory.md) — 20 tools (9 stdio-implemented · 11 discovery stubs) each with catalog `<file>:<line>` + handler `<file>:<line>`. Generator: [`scripts/audit_mcp_tools.py`](../../src/scripts/audit_mcp_tools.py). CI drift gate: `task lint-mcp-inventory`. Step-11 Phase 5 Step 3. |
 
 ## Open `[!]` rows
 

package/docs/personas.md

@@ -10,7 +10,7 @@ This page catalogs the **24 active personas** shipped with
 **advisor** personas in `personas/advisors/`. It also explains how
 `personas:` (lens axis) interacts with `/mode` (role-mode axis).
 Removed personas are deleted in-commit (no soak window) — see
-[`persona-governance § Deprecation path`](../.agent-src/rules/persona-governance.md).
+[`persona-governance § Deprecation path`](../dist/agent-src/rules/persona-governance.md).
 
 ## Catalog — Core (always-loaded, 6)
 
@@ -77,7 +77,7 @@ not cited by skills directly:
 - **Core (≤ 6)** — always-loaded cast. 5 sections (Focus · Mindset · Unique Questions · Output Expectations · Anti-Patterns), ≤ 120 lines.
 - **Specialist** — opt-in lenses. 7 sections (Core-5 + Critical Rules + Workflows). Line cap is wing-scoped: ≤ 100 (no wing / Wings 1–2), ≤ 140 (Wings 3–4) per [`persona-schema § 4`](contracts/persona-schema.md).
 
-Schema contract: [`docs/contracts/persona-schema.md`](contracts/persona-schema.md). Governance rule: [`persona-governance`](../.agent-src/rules/persona-governance.md).
+Schema contract: [`docs/contracts/persona-schema.md`](contracts/persona-schema.md). Governance rule: [`persona-governance`](../dist/agent-src/rules/persona-governance.md).
 
 ## When to invoke a persona
 
@@ -145,7 +145,7 @@ override mechanism:
 - **Body override** — full replace. Drop a same-named file under
   `agents/personas/<id>.md`; the package version is shadowed.
 
-See [`override-management`](../.agent-src/skills/override-management/SKILL.md)
+See [`override-management`](../dist/agent-src/skills/override-management/SKILL.md)
 for the mechanics.
 
 ## Anti-patterns

package/docs/profiles.md

@@ -4,11 +4,15 @@ Each block below is the first-screen for one shipped profile. The
 `profile.id` written by `agent-config setup` selects the anchor; the block names
 the audience, the first three things the agent does for that role,
 and the exact commands and skills wired into the profile YAML at
-[`.agent-src.uncondensed/profiles/<id>.yml`](../.agent-src.uncondensed/profiles/).
+[`src/agent-src/profiles/<id>.yml`](../src/agent-src/profiles/).
 
 The summary table at the top of [`README.md`](../README.md) is the
 one-page index; the prose below is the deep version.
 
+→ Each profile's **experience page** (packs · flows · what is *not* loaded ·
+examples) lives under [`docs/experiences/`](experiences/); the multi-command
+**work journeys** those profiles run are in [`docs/flows.md`](flows.md).
+
 **Switching experience.** `agent-config setup` writes `profile.id` on first run
 (it is the wizard's first question). To switch later, run
 `agent-config use --profile=<id>` (one of `developer` · `content_creator` ·
@@ -26,7 +30,7 @@ and verifies; `/work` is the free-form sibling; `/review-changes`
 dispatches five judges (bug, security, tests, quality, architecture)
 on the local diff. Stack-aware skills cover Laravel · Symfony ·
 Next.js · React · Node. **Preset default: `balanced`.**
-[Profile YAML](../.agent-src.uncondensed/profiles/developer.yml) ·
+[Profile YAML](../src/agent-src/profiles/developer.yml) ·
 [Role guide](getting-started-by-role.md#developer-the-original-audience).
 
 <a id="profile-content_creator"></a>
@@ -43,7 +47,7 @@ motion+audio prompt → provider render → stitched clip), with
 `character-consistency` locking identity tokens across scenes and
 `AIV_DRYRUN=true` as the cost-safety default.
 **Preset default: `balanced`.**
-[Profile YAML](../.agent-src.uncondensed/profiles/content_creator.yml) ·
+[Profile YAML](../src/agent-src/profiles/content_creator.yml) ·
 [Role guide](getting-started-by-role.md#creator-writer-marketer-indie-content-shop).
 
 <a id="profile-founder"></a>
@@ -55,7 +59,7 @@ into a copyable pitch; `/council` polls external AIs for a neutral
 second opinion; `rice-prioritization` ranks the backlog;
 `vision-articulation` and `fundraising-narrative` shape the
 internal-vs-external story. **Preset default: `fast`.**
-[Profile YAML](../.agent-src.uncondensed/profiles/founder.yml) ·
+[Profile YAML](../src/agent-src/profiles/founder.yml) ·
 [Role guide](getting-started-by-role.md#founder-early-stage-operator-wearing-every-hat).
 
 <a id="profile-agency"></a>
@@ -67,7 +71,7 @@ provenance. `/refine-ticket` rewrites the ticket and surfaces top-5
 risks; `estimate-ticket` sizes and splits; `decision-record` anchors
 the trade-off in an ADR before code starts. **Preset default:
 `strict`.**
-[Profile YAML](../.agent-src.uncondensed/profiles/agency.yml) ·
+[Profile YAML](../src/agent-src/profiles/agency.yml) ·
 [Role guide](getting-started-by-role.md#consultant-advisory-freelance-fractional).
 
 <a id="profile-finance"></a>
@@ -78,7 +82,7 @@ walks the WACC / terminal-value / 5-year-hold reasoning; `forecasting`
 reconciles top-down vs bottom-up; `scenario-modeling` produces the
 base / upside / downside cuts; `runway-cognition` frames the
 fundraise-vs-cut-vs-grow decision. **Preset default: `strict`.**
-[Profile YAML](../.agent-src.uncondensed/profiles/finance.yml) ·
+[Profile YAML](../src/agent-src/profiles/finance.yml) ·
 [Role guide](getting-started-by-role.md#finance--ops-cfo-controller-ops-lead-founder-finance).
 
 <a id="profile-ops"></a>
@@ -90,15 +94,15 @@ breaks, build the dashboard that catches it next time.
 the first line of code; `incident-commander` frames severity and
 post-mortem; `dashboard-design` chooses the right RED / USE / Golden
 Signal panel. **Preset default: `strict`.**
-[Profile YAML](../.agent-src.uncondensed/profiles/ops.yml) ·
+[Profile YAML](../src/agent-src/profiles/ops.yml) ·
 [Role guide](getting-started-by-role.md#finance--ops-cfo-controller-ops-lead-founder-finance).
 
 > **Universal AI Agent OS, not "for developers only".** The same
 > orchestration core also drives non-software trades. Worked-example
-> user types ship for [galabau](../.agent-src.uncondensed/user-types/galabau-field-crew.md),
-> [metalworking](../.agent-src.uncondensed/user-types/metalworking-shop.md),
-> [truck driving](../.agent-src.uncondensed/user-types/truck-driver.md) —
-> with a [scaffold](../.agent-src.uncondensed/user-types/_template/) for
+> user types ship for [galabau](../src/agent-src/user-types/galabau-field-crew.md),
+> [metalworking](../src/agent-src/user-types/metalworking-shop.md),
+> [truck driving](../src/agent-src/user-types/truck-driver.md) —
+> with a [scaffold](../src/agent-src/user-types/_template/) for
 > contributing your own.
 
 → [Public catalog](catalog.md) (all rules, skills, commands, guidelines) · [Skills only](skills-catalog.md) · [llms.txt](../llms.txt)

package/docs/quality.md

@@ -10,7 +10,7 @@ task ci
 
 This runs, in order:
 
-1. **Sync check** — `.agent-src/` matches `.agent-src.uncondensed/` (non-`.md` files)
+1. **Sync check** — `dist/agent-src/` matches `.agent-src.uncondensed/` (non-`.md` files)
 2. **Condensation hashes** — Condensed `.md` hashes match source
 3. **Reference check** — No broken cross-references between files
 4. **Portability check** — No project-specific paths in shared files
@@ -52,13 +52,13 @@ fail before the full linter.
 
 ## Condensation System
 
-Content flows from verbose (`.agent-src.uncondensed/`) to condensed (`.agent-src/`),
+Content flows from verbose (`.agent-src.uncondensed/`) to condensed (`dist/agent-src/`),
 which is then projected into `.augment/` for Augment Code.
 
 ### Rules
 
 - Source of truth is **always** `.agent-src.uncondensed/`
-- Never edit `.agent-src/` or `.augment/` directly
+- Never edit `dist/agent-src/` or `.augment/` directly
 - The `/condense` command produces token-efficient output
 - Condensation hashes track which files have been condensed
 

package/docs/setup/mcp-client-config.md

@@ -1,8 +1,14 @@
-# MCP Client Config — Self-hosted agent-config Worker
+# MCP Client Config — agent-config
 
-Connect any MCP-capable client to your own `agent-config-mcp` Cloudflare
-Worker. Read-only, identity-stable per release. Optional Bearer-token
-auth — see [§ Bearer auth](#bearer-auth) below.
+Connect any MCP-capable client to the `agent-config` read-only content
+surface. Two entry points — a **local stdio** server (`agent-config
+mcp-server`, no account, no network) and a **self-hosted Cloudflare Worker**
+(a shared HTTP endpoint). See [§ Two ways to connect](#two-ways-to-connect--pick-one)
+to choose; both are read-only and identity-stable per release.
+
+The Worker sections below assume the self-hosted path (optional Bearer-token
+auth — see [§ Bearer auth](#bearer-auth)). For the local path jump straight to
+[§ Local stdio (turnkey)](#local-stdio-turnkey--no-worker-no-account).
 
 > **No public endpoint.** This package ships the Worker source under
 > `internal/workers/mcp/`, but does **not** operate a shared hosted MCP server.
@@ -17,6 +23,26 @@ For URL shapes (latest vs. pinned `/v<X.Y.Z>`) see
 [`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md). For operator
 setup of your own deployment see [`mcp-cloud-setup.md`](mcp-cloud-setup.md).
 
+## Two ways to connect — pick one
+
+There are **two distinct entry points**, and it is easy to confuse them.
+Pick the one that matches your situation; the per-client sections below
+cover the **remote Worker**, and [§ Local stdio (turnkey)](#local-stdio-turnkey--no-worker-no-account)
+covers the local one.
+
+| | **Local stdio (turnkey)** | **Remote Worker (self-hosted)** |
+|---|---|---|
+| Command | `agent-config mcp-server` | `npx -y mcp-remote https://your-worker…` |
+| Needs | the npm package installed | your own deployed Cloudflare Worker |
+| Network / account | none — fully local & offline | a Cloudflare account + a deployed Worker |
+| Surface | read-only content (skills / commands / rules / guidelines) | same read-only content |
+| Best for | end-users configuring an agent; offline; no account; a Worker-outage fallback | a shared team endpoint reachable from anywhere |
+
+> **Don't mix them up.** The local entry runs a **command** (`agent-config
+> mcp-server`); the remote entry points at a **URL**. If you installed the
+> npm package and just want the content locally, use the local-stdio path —
+> you do **not** need a Worker.
+
 ## Transport note
 
 The Worker speaks JSON-RPC over HTTP POST. Clients that support
@@ -25,6 +51,10 @@ Clients that only support stdio (Claude Desktop, Zed) need the
 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge from
 npm — invoked via `npx`, no install required.
 
+The **local stdio** path is the opposite: it is natively stdio
+(`agent-config mcp-server`), so stdio-only clients need **no** bridge,
+and HTTP-native clients run it as a local command.
+
 ## Where settings live — `.agent-settings.yml` vs. MCP config
 
 These are **two different files** for two different layers. Don't
@@ -219,12 +249,107 @@ If the client shows the connector but no prompts / resources,
 re-probe the URL — a 5xx from the Worker indicates the deploy is
 mid-roll, retry after a minute.
 
-## Local stdio alternative
+## Local stdio (turnkey) — no Worker, no account
+
+Install the package, then point your client at the **`agent-config
+mcp-server`** command. It serves the bundled content (skills / commands as
+prompts; rules / guidelines as resources) over stdio — **read-only**, fully
+local, no network, no Cloudflare account, no repo clone. This is the local
+counterpart to the remote-Worker snippets above; the Worker templates are
+unchanged.
+
+```bash
+npm install -g @event4u/agent-config   # provides the `agent-config` binary
+```
+
+In every snippet below, `agent-config` is the globally-installed binary. If
+you prefer not to install globally, replace
+`"command": "agent-config", "args": ["mcp-server"]` with
+`"command": "npx", "args": ["-y", "@event4u/agent-config", "mcp-server"]`.
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
+`%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "agent-config",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop fully (Cmd+Q on macOS).
+
+### Claude Code
+
+Native stdio — one command (everything after `--` is the server command):
+
+```bash
+claude mcp add agent-config -- agent-config mcp-server
+claude mcp list
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (global) or `<repo>/.cursor/mcp.json` (project-local):
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "agent-config",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+Reload Cursor (`Cmd+Shift+P → Reload Window`).
+
+### Zed
+
+`~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "agent-config": {
+      "source": "custom",
+      "command": "agent-config",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+No `mcp-remote` bridge is needed — the local server is already stdio.
+
+### Verify the local server
+
+The server speaks the same wire surface; drive it directly to confirm:
+
+```bash
+printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
+  | agent-config mcp-server
+# → {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"…","serverInfo":{"name":"agent-config-mcp",…}}}
+```
 
-If you have the repo cloned and prefer running the MCP server
-locally (faster startup, no network), the stdio kernel under
-`scripts/mcp_server/` is the same wire surface. Setup:
-`task mcp:setup`, run details in [`../mcp-server.md`](../mcp-server.md).
+The readiness note (`[mcp-server] … ready — N entries, read-only`) is printed
+on **stderr**; stdout carries only JSON-RPC. `tools/list` is empty and
+`tools/call` returns a `not_implemented` envelope — the local surface is
+read-only by design (execution is deferred; see
+[`../decisions/ADR-085-mcp-stdio-end-user-distribution-shape.md`](../decisions/ADR-085-mcp-stdio-end-user-distribution-shape.md)).
+
+> **Contributor variant.** If you have the repo cloned and want the
+> execution-capable Python kernel under `scripts/mcp_server/` instead, run
+> `task mcp:setup` then `task mcp:run` — details in
+> [`../mcp-server.md`](../mcp-server.md). That path is for development, not
+> end-user packaging.
 
 ## See also
 

package/docs/setup/mcp-server-docker.md

@@ -34,13 +34,15 @@ docker run --rm -i agent-config-mcp:local
 You should see, on **stderr**:
 
 ```
-mcp-server: loaded 278 prompts (0 warnings)
-mcp-server: loaded 160 resources (0 warnings)
-mcp-server: registered 2 tools: ['chat_history_append', 'lint_skills']
-mcp-server: identity serverVersion=0.1.0 packageVersion=1.36.1 skillSetSignature=<12-hex>
+mcp-server: loaded 377 prompts (0 warnings)
+mcp-server: loaded 189 resources (0 warnings)
+mcp-server: registered 20 tools (9 implemented, 11 stubs)
+mcp-server: identity serverVersion=0.1.0 packageVersion=<semver> skillSetSignature=<12-hex>
 ```
 
-The fourth line is the F1 identity surface — see
+Prompt / resource / tool counts grow as the suite grows — the meaningful
+signal is `0 warnings`, not the exact numbers. The fourth line is the F1
+identity surface — see
 [`mcp-phase-1-scope.md § Phase 6`](../contracts/mcp-phase-1-scope.md)
 for semantics.
 
@@ -85,7 +87,7 @@ The image inherits the A0 contract verbatim — see
 - No `subprocess`, `os.system`, `requests`, `httpx`, or `urllib`
   imports anywhere on the MCP wire surface (enforced by
   `test_no_unsafe_imports_in_*` tests).
-- Tools allowlist is hardcoded in `scripts/mcp_server/tools.py`. The
+- Tools allowlist is hardcoded in `src/scripts/mcp_server/tools.py`. The
   container cannot grow new tools at runtime.
 - Image runs as a non-root user (`mcp:mcp`). Mounted host paths must
   be writable by uid/gid `999` or you'll see permission errors.
@@ -95,5 +97,5 @@ The image inherits the A0 contract verbatim — see
 ## Size
 
 The runtime stage is `python:3.11-slim` + the pinned deps + the
-`.agent-src/` content. Expect ~150-200 MB; the builder stage is
+`dist/agent-src/` content. Expect ~150-200 MB; the builder stage is
 discarded.