@event4u/agent-config 2.6.0 → 2.7.0

package/README.md

@@ -90,7 +90,7 @@ npx @event4u/agent-config init --tools=windsurf         # Windsurf
 npx @event4u/agent-config init --tools=cline            # Cline
 npx @event4u/agent-config init --tools=gemini-cli       # Gemini CLI
 npx @event4u/agent-config init --tools=copilot          # GitHub Copilot
-npx @event4u/agent-config init --tools=augment          # Augment Code
+npx @event4u/agent-config init --tools=augment --global # Augment Code (global-only)
 npx @event4u/agent-config init --tools=roocode          # Roo Code
 npx @event4u/agent-config init --tools=aider            # Aider
 npx @event4u/agent-config init --tools=codex            # Codex CLI
@@ -112,13 +112,16 @@ npx @event4u/agent-config init --tools=claude-code --global   # → ~/.claude/
 npx @event4u/agent-config init --tools=cursor --global        # → ~/.cursor/
 ```
 
-Per-AI scope support varies — Claude Desktop, for example, is
-global-only (no project-local discovery on macOS), while Roo Code and
-Continue.dev are project-local. The Supported Tools table below
-documents per-AI scope. Incompatible combinations (e.g.
-`--tools=roocode --global` or `--tools=claude-desktop` without
-`--global`) are rejected with a directive error; `--tools=all`
-silently filters to the scope's compatible subset.
+Per-AI scope support varies — Claude Desktop and Augment Code, for
+example, are global-only (Claude Desktop has no project-local
+discovery on macOS; Augment ships from a single user-scope tree
+(`~/.augment/`) — see [`ADR-007 § Amendment 2026-05-13 — global-only`](docs/decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only)),
+while Roo Code and Continue.dev are project-local. The Supported
+Tools table below documents per-AI scope. Incompatible combinations
+(e.g. `--tools=roocode --global`, `--tools=claude-desktop` without
+`--global`, or `--tools=augment` without `--global`) are rejected
+with a directive error; `--tools=all` silently filters to the scope's
+compatible subset.
 
 ### For individual use (optional)
 
@@ -154,10 +157,26 @@ Cloudflare account takes ~5 minutes:
 ```bash
 task mcp:cloud:login         # one-time, opens browser
 task mcp:cloud:setup         # check → r2-create → r2-verify → whoami
-task mcp:cloud:secret-put    # set MCP-Token (Bearer auth, recommended)
+task mcp:cloud:secret-put    # opt in to bearer-auth mode (recommended for private deploys)
 # Then deploy via CI — see operator guide below.
 ```
 
+The Worker ships **two MVP-1 auth modes** the operator picks at deploy
+time (per `docs/contracts/mcp-cloud-scope.md` § `Auth surface`):
+
+- **`public`** — default. No per-request auth. Edge cache plus
+  Cloudflare account-level DDoS shielding are the ingress controls.
+  Use only for OSS, read-only deploys where the URL is shared widely.
+- **`bearer-auth`** — operator opt-in. Set the `MCP-Token` Wrangler
+  secret with `task mcp:cloud:secret-put`. Every `POST /` then
+  requires `Authorization: Bearer <MCP-Token>`. `GET /` liveness
+  stays open. Use this for private deploys.
+
+HMAC and Cloudflare Access modes are declared but **deferred** in the
+contract (`hmac-deferred`, `cf-access-deferred`) — wake-up triggers
+listed there. The README intentionally names no mode the contract
+has not declared (bidirectional drift test enforces this).
+
 After deploy your Worker lives at
 `https://agent-config-mcp.<your-account>.workers.dev` (or a custom
 domain you wire in Step 7 of the operator guide). Verify:
@@ -174,11 +193,13 @@ Full operator walkthrough (account, R2, GitHub secrets, deploy) —
 [`docs/setup/mcp-cloud-setup.md`](docs/setup/mcp-cloud-setup.md).
 Experimental — A0-cloud contract lives at `docs/contracts/mcp-cloud-scope.md` (internal reference only per `STABILITY.md`).
 
-#### Lock your Worker behind a Bearer token
+#### Lock your Worker behind a Bearer token (`bearer-auth` mode)
 
-Without auth, any MCP client that knows your `*.workers.dev` URL can
-read the catalog. For private deploys, set the `MCP-Token` secret and
-the Worker will require `Authorization: Bearer <token>` on every POST:
+In `bearer-auth` mode the Worker requires `Authorization: Bearer
+<MCP-Token>` on every `POST /` and returns HTTP 401 + RFC 6750
+`WWW-Authenticate` on mismatch. The `GET /` liveness probe stays open
+so health checks keep working without the token. Switch modes by
+setting (or clearing) the `MCP-Token` secret:
 
 ```bash
 task mcp:cloud:secret-put          # wraps `npx wrangler secret put MCP-Token --name agent-config-mcp`
@@ -188,18 +209,21 @@ task mcp:cloud:secret-put          # wraps `npx wrangler secret put MCP-Token --
 Once the secret is set, every client config block needs the token in
 its headers — see [`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md) § Bearer auth for the
 per-client snippets (Claude Desktop, Claude Code, Cursor, Zed,
-Continue). The `GET /` liveness probe stays open so health checks keep
-working without the token.
-
-> **Scope — Lite, not Full.** The Worker serves the read-only governance
-> surface (skills · commands · rules · guidelines · contexts) as MCP
-> prompts and resources, plus a small set of read-only tools (`memory_lookup`,
-> `chat_history_read`, `list_*`, `read_resource_body`). It does **not**
-> execute any of the ~112 Python scripts that ship with the package
-> (linters, audits, `task ci`, work-engine hooks, …). Those require the
-> full local install per [Quickstart](#quickstart). See
+Continue). Mode contract is normative: `docs/contracts/mcp-cloud-scope.md`
+§ `Auth surface` § `bearer-auth`.
+
+> **Scope — Lite, not Full.** The Worker serves the **MCP Lite
+> scope** (`mcp_scope: lite` per `docs/contracts/mcp-cloud-scope.md`):
+> the read-only governance surface (skills · commands · rules ·
+> guidelines · contexts) as MCP prompts and resources, plus a small
+> set of read-only tools (`memory_lookup`, `chat_history_read`,
+> `list_*`, `read_resource_body`). It does **not** execute any of the
+> ~112 Python scripts that ship with the package (linters, audits,
+> `task ci`, work-engine hooks, …) — those require the **MCP Full
+> scope** (`mcp_scope: full` — local install per [Quickstart](#quickstart)).
+> The Lite vs Full boundary is normative in
 > `docs/contracts/mcp-cloud-scope.md` (internal reference only per
-> `STABILITY.md`) for the execution-safety boundary.
+> `STABILITY.md`).
 
 ### Optional: persistent agent memory
 
@@ -467,7 +491,6 @@ Every developer gets the same behavior. No per-user setup needed —
 
 | Tool | Rules | Skills | Commands | How it works |
 |---|---|---|---|---|
-| **Augment VSCode/IntelliJ** | ✅ | ✅ | ✅ | Reads `.augment/` from project |
 | **Claude Code** | ✅ | ✅ | ✅ | Reads `.claude/` (skills + commands as skills) |
 | **Cursor** | ✅ | — | ☑️ | Reads `.cursor/rules/` + commands via AGENTS.md |
 | **Cline** | ✅ | — | ☑️ | Reads `.clinerules/` + commands via AGENTS.md |
@@ -478,6 +501,7 @@ Every developer gets the same behavior. No per-user setup needed —
 | **Codex CLI** | ✅ | — | ☑️ | Auto-discovers `AGENTS.md` at project root |
 | **Continue.dev** | ✅ | — | ☑️ | Auto-discovers `.continue/rules/*.md` + AGENTS.md |
 | **Aider** | 📌 | — | — | Marker + manual `read:` in `.aider.conf.yml` |
+| **Augment VSCode/IntelliJ** | 📌 | — | — | Global-only — install with `--global` (see [ADR-007 Amendment 2026-05-13](docs/decisions/ADR-007-agent-discovery-scopes.md#amendment-2026-05-13--augment-global-only)); project writes `.augment/settings.json` marker only |
 | **Claude Desktop** | 📌 | — | — | Global-only — install with `--global` (see ADR-007) |
 
 ✅ = native support &nbsp; — = not available &nbsp; ☑️ = text reference only
@@ -485,13 +509,15 @@ Every developer gets the same behavior. No per-user setup needed —
 slash-commands) &nbsp; 📌 = informational marker only (no auto-discovery
 or manual wiring required)
 
-> **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 174 skills + 106 native commands). Cursor, Cline, Windsurf,
-> Gemini CLI, GitHub Copilot, Roo Code, Codex CLI, and Continue.dev only get
-> the **rules** natively; skills and commands are available as documentation
-> the agent can read, not as first-class features. Aider and Claude Desktop
-> ship marker-only bridges — Aider needs a one-line `read:` entry in
-> `.aider.conf.yml`; Claude Desktop is global-scope and pairs with `--global`.
+> **What this means in practice:** Claude Code gets the full project-scoped
+> package (rules + 174 skills + 106 native commands); Augment Code gets the
+> same content but only from a single global install at `~/.augment/`.
+> Cursor, Cline, Windsurf, Gemini CLI, GitHub Copilot, Roo Code, Codex CLI,
+> and Continue.dev only get the **rules** natively; skills and commands are
+> available as documentation the agent can read, not as first-class features.
+> Aider, Augment, and Claude Desktop ship marker-only bridges in projects —
+> Aider needs a one-line `read:` entry in `.aider.conf.yml`; Augment and
+> Claude Desktop are global-scope and pair with `--global`.
 
 > **Team reproducibility (ADR-008):** every tool you `init` is also recorded in
 > `agents/installed-tools.lock` — committed, machine-managed. New team members

package/config/gitignore-block.txt

@@ -36,3 +36,8 @@
 /agents/council-questions/
 /agents/council-responses/
 /agents/council-sessions/
+
+# Agent config — Tier 1 hook runtime state (context-hygiene.json,
+# onboarding-gate.json). Written by SessionStart / PostToolUse hooks
+# on Augment + Claude Code; regenerated on demand, never commit.
+/agents/state/

package/docs/architecture/augment-projection.md

@@ -0,0 +1,70 @@
+# Pipeline B — Augment projection
+
+> **Scope:** project the shipped `.agent-src/` payload into the
+> `.augment/` tree that Augment Code (CLI + IDE) reads on startup.
+
+## Input → Transform → Output
+
+```
+.agent-src/**                      ← Compressed payload (shipped in @event4u/agent-config)
+    ↓ scripts/compress.py:project_to_augment()
+.augment/**                        ← Local projection (gitignored on consumer side)
+    rules/                         ← copies (Augment historically does not load symlinked rules)
+    skills/ commands/ contexts/
+    personas/ templates/           ← symlinks into .agent-src/<dir>/
+    docs/guidelines/               ← symlink → docs/guidelines/ (only docs/ subdir exposed)
+```
+
+The default mode is **copy-rules-symlink-everything-else**. The toggle
+`augment.rules_use_symlinks: true` in `.agent-settings.yml` flips
+rules to symlinks once the host supports it. The toggle is honored by
+both [`scripts/install.sh`](../../scripts/install.sh) on the consumer
+side and `project_to_augment()` in the package's own self-projection.
+
+Cross-references inside `.agent-src/rules/*.md` use **relative paths
+from `.agent-src/rules/`** (e.g. `../contexts/execution/foo.md`).
+After projection, those paths resolve through the symlinks in
+`.augment/`. The host agent reads `.augment/`, follows the symlink to
+`.agent-src/`, and lands on the payload.
+
+## Entry points
+
+| Surface | Command |
+|---|---|
+| Project self-projection | `task sync` (`project_to_augment()` step) — [`taskfiles/content.yml:4`](../../taskfiles/content.yml) |
+| Standalone project-augment | `task project-augment` — [`taskfiles/content.yml:23`](../../taskfiles/content.yml) |
+| Consumer install | `scripts/install.sh` (delegates to `scripts/install.py`) |
+| Direct script | `python3 scripts/compress.py --project-augment` |
+
+## Invariants
+
+1. **`.augment/rules/` are real files** by default — symlinks break
+   Augment's rule loader on current versions.
+2. **Symlink targets exist** — `task sync-check` verifies every
+   `.augment/` symlink resolves into `.agent-src/`.
+3. **Single docs subtree** — only `docs/guidelines/` is exposed; the
+   `docs/contracts/` and `docs/decisions/` trees stay package-internal
+   (rules inline 2–3 line excerpts instead of linking out).
+4. **Idempotent** — re-running projection on a clean tree must
+   produce no diff. Enforced by CI.
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Rule not loading in Augment | rule was symlinked instead of copied | unset `augment.rules_use_symlinks` or re-run `task project-augment` |
+| Broken `load_context:` path | symlink target missing in `.agent-src/` | run `task sync` first (Pipeline A must succeed) |
+| `task sync-check` fails on clean tree | source edited but `.augment/` not regenerated | `task sync` |
+| Stale skill / command in `.augment/` after rename in source | projection didn't clean orphans | `task project-augment` re-runs cleanup |
+
+## Proving the pipeline
+
+- [`tests/test_compress.py`](../../tests/test_compress.py) §
+  `test_project_to_augment_rules_mode_toggle` and surrounding cases
+  — exercises both copy-mode and symlink-mode for rules; verifies
+  symlink targets for skills / commands / contexts.
+- [`scripts/smoke_path_resolution.py`](../../scripts/smoke_path_resolution.py)
+  — walks `.augment/rules/*.md` and resolves every `load_context:`
+  entry; non-zero exit means a consumer would see the same break.
+
+← [Architecture overview](../architecture.md)

package/docs/architecture/claude-bundle.md

@@ -0,0 +1,77 @@
+# Pipeline D — Claude.ai cloud bundle
+
+> **Scope:** package shipped skills into Anthropic Skills ZIP bundles
+> for upload to Claude.ai Web or the Skills API. Cloud-side surfaces
+> have no filesystem access, so the builder applies sandbox-aware
+> transformations not needed in the on-disk projections.
+
+## Input → Transform → Output
+
+```
+.agent-src/skills/<id>/SKILL.md     ← Compressed skill (+ supporting assets)
+    ↓ scripts/build_cloud_bundle.py
+dist/cloud/<skill>.zip              ← Anthropic Skills bundle (Claude.ai Web / Skills API)
+```
+
+Per-skill tier classification comes from
+[`scripts/audit_cloud_compatibility.py`](../../scripts/audit_cloud_compatibility.py):
+
+| Tier | Bundle action |
+|---|---|
+| **T1** | Bundle as-is — pure guidance, sandbox-safe |
+| **T2** | Bundle with prepended sandbox note + package-internal path-swap |
+| **T3-S** | Same as T2; optional script calls degrade gracefully on cloud |
+| **T3-H** | **Skipped** — cloud-aware variant required before bundling |
+
+Cloud-side caps enforced by the builder:
+
+- `description` ≤ 200 chars (Claude.ai Web display limit).
+- 1024-char hard cap (Anthropic Skills API spec).
+- Sandbox note explains to the agent that `.agent-src/`, `agents/`,
+  and `task …` references are descriptive — the host has no
+  filesystem access.
+
+## Entry points
+
+| Surface | Command |
+|---|---|
+| Build one skill | `task build-cloud-bundle -- SKILL=<id>` ([`taskfiles/engine.yml:184`](../../taskfiles/engine.yml)) |
+| Build all eligible | `task build-cloud-bundles-all` ([`taskfiles/engine.yml:189`](../../taskfiles/engine.yml)) |
+| CI dry-run | `task ci-cloud-bundle` ([`taskfiles/engine.yml:194`](../../taskfiles/engine.yml)) |
+| Tier audit only | `task audit-cloud` ([`taskfiles/engine.yml:199`](../../taskfiles/engine.yml)) |
+
+## Invariants
+
+1. **No T3-H bundles** — high-coupling skills are skipped, never
+   silently bundled with broken expectations.
+2. **Description budget enforced** — overlong descriptions fail
+   the build (and CI via `ci-cloud-bundle --check`).
+3. **Package-internal paths swapped** — references to `.agent-src/`,
+   `scripts/`, `agents/` are rewritten to descriptive form so the
+   cloud agent does not attempt filesystem access.
+4. **`mcp_scope: lite`** — bundles tagged `lite` may not reference
+   MCP servers that require local stdio (per
+   [`docs/contracts/mcp-cloud-scope.md`](../contracts/mcp-cloud-scope.md)).
+5. **Deterministic ZIP** — same skill input produces identical
+   archive bytes (modulo timestamps, normalized in the builder).
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `ci-cloud-bundle` fails on a skill | description > 200 chars, or T3-H detected | shorten frontmatter, or add cloud variant |
+| `frontmatter.description` reflows to the prompt unexpectedly | over the 200-char Claude.ai cap (hard 1024) | tighten the description |
+| Bundle references `.agent-src/` in body | path-swap rule missing | extend `build_cloud_bundle.py` rewrite table |
+| Skill silently dropped from `dist/cloud/` | T3-H tier (cloud-unsafe) | author a cloud-aware variant, re-classify |
+
+## Proving the pipeline
+
+- [`tests/test_build_cloud_bundle.py`](../../tests/test_build_cloud_bundle.py)
+  — covers tier filtering, sandbox-note injection, path-swap, and
+  description-cap enforcement.
+- [`tests/test_claude_desktop_bundler.py`](../../tests/test_claude_desktop_bundler.py)
+  — complementary coverage for the Claude Desktop bundle surface.
+- CI gate: `task ci-cloud-bundle` runs the builder in `--check` mode
+  on every PR.
+
+← [Architecture overview](../architecture.md)

package/docs/architecture/compression.md

@@ -0,0 +1,67 @@
+# Pipeline A — Compression
+
+> **Scope:** transform verbose authoring source into the token-efficient
+> distribution payload that ships in the npm package.
+
+## Input → Transform → Output
+
+```
+.agent-src.uncompressed/**         ← Source of truth (verbose, human-readable)
+    ↓ scripts/compress.py + scripts/compress.sh (--sync)
+.agent-src/**                      ← Compressed, hash-tracked, shipped in @event4u/agent-config
+```
+
+| Layer | Source | Output |
+|---|---|---|
+| Skills | `.agent-src.uncompressed/skills/<id>/SKILL.md` (+ assets) | `.agent-src/skills/<id>/SKILL.md` |
+| Rules | `.agent-src.uncompressed/rules/<name>.md` | `.agent-src/rules/<name>.md` |
+| Commands | `.agent-src.uncompressed/commands/**` | `.agent-src/commands/**` |
+| Personas, contexts, templates | `.agent-src.uncompressed/<dir>/**` | `.agent-src/<dir>/**` |
+
+The path rewriter ([`scripts/compress.py:157`](../../scripts/compress.py)
+`apply_path_rewriter()`) converts logical names in source frontmatter
+(`contexts/execution/foo.md`) into the relative form expected from
+`.agent-src/rules/` (`../contexts/execution/foo.md`). Hardcoding
+`.agent-src.uncompressed/` in source is a CI failure — caught by
+[`scripts/check_compressed_paths.py`](../../scripts/check_compressed_paths.py).
+
+## Entry points
+
+| Surface | Command |
+|---|---|
+| Full sync | `task sync` ([`taskfiles/content.yml:4`](../../taskfiles/content.yml)) |
+| Sync drift check | `task sync-check` ([`taskfiles/content.yml:38`](../../taskfiles/content.yml)) |
+| Hash drift check | `task sync-check-hashes` ([`taskfiles/content.yml:43`](../../taskfiles/content.yml)) |
+| Single file | `task sync-mark-done -- <path>` |
+| Direct script | `bash scripts/compress.sh --sync` |
+
+## Invariants
+
+1. **Determinism** — same input must produce identical bytes in
+   `.agent-src/`. CI enforces via `task sync-check` (no output diff
+   permitted on a clean checkout).
+2. **Hash tracking** — every compressed file's source-hash is stored
+   in `.agent-src/.compression-hashes.json`; stale hashes are caught
+   by `task sync-check-hashes`.
+3. **No source-side leakage** — `.agent-src.uncompressed/` must not
+   appear anywhere in compressed output (frontmatter, body, includes).
+4. **Frontmatter preserved** — YAML frontmatter survives compression
+   unchanged except for the path rewriter on `load_context:` entries.
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `task sync-check` fails on clean tree | source edited but not re-compressed | `task sync` |
+| `check-compressed-paths` fails | `.agent-src.uncompressed/` substring leaked into compressed output | re-author source, re-run `task sync` |
+| Hash drift on unchanged file | concurrent edits / merge artefact | `task sync-clean-hashes && task sync` |
+| Path rewriter mangles a link | logical name collision with a real relative path | declare `validator_ignore:` in rule frontmatter |
+
+## Proving the pipeline
+
+- [`tests/test_compress.py`](../../tests/test_compress.py) — end-to-end
+  compression, hash invariants, path rewriter.
+- [`tests/test_compress_paths.py`](../../tests/test_compress_paths.py)
+  — path-rewriter edge cases and forbidden-substring detection.
+
+← [Architecture overview](../architecture.md)

package/docs/architecture/multi-tool-projection.md

@@ -0,0 +1,72 @@
+# Pipeline C — Multi-tool projection
+
+> **Scope:** generate the tool-specific surface files that non-Augment
+> hosts (Claude Code, Cursor, Cline, Windsurf, Gemini CLI, Copilot CLI)
+> read from their conventional locations.
+
+## Input → Transform → Output
+
+```
+.agent-src/**                      ← Compressed payload
+    ↓ scripts/compress.py --generate-tools
+.claude/      .cursor/             ← Claude Code, Cursor (rules + skills)
+.clinerules/  .windsurfrules       ← Cline (rules dir), Windsurf (concatenated file)
+GEMINI.md                          ← Gemini CLI (symlink → AGENTS.md)
+.github/copilot-instructions.md    ← Copilot Chat + PR review (already shipped)
+```
+
+Per-tool method ([`scripts/compress.py:_filter_tool_dirs`](../../scripts/compress.py)):
+
+| Tool | Surface | Method | Coverage |
+|---|---|---|---|
+| Claude Code | `.claude/` | native plugin + symlinks | rules + skills + commands |
+| Augment VSCode/IntelliJ | `.augment/` | install.sh copies + symlinks | rules + skills + commands |
+| Copilot CLI | (plugin) | native plugin | rules + skills + commands |
+| Cursor | `.cursor/` | install.sh symlinks | rules only |
+| Cline | `.clinerules/` | install.sh symlinks | rules only |
+| Windsurf | `.windsurfrules` | install.sh concatenates | rules only |
+| Gemini CLI | `GEMINI.md` | install.sh symlink → AGENTS.md | rules only |
+
+Hosts opt in / out via `.agent-settings.yml § tools.enabled`. The
+generator filters output to enabled tools only — disabling Cursor
+removes `.cursor/` on next `task generate-tools`.
+
+## Entry points
+
+| Surface | Command |
+|---|---|
+| Regenerate all enabled | `task generate-tools` ([`taskfiles/content.yml:63`](../../taskfiles/content.yml)) |
+| Clean output | `task clean-tools` ([`taskfiles/content.yml:69`](../../taskfiles/content.yml)) |
+| Direct script | `python3 scripts/compress.py --generate-tools` |
+| Consumer install | `scripts/install.sh` (calls `--generate-tools` after `--project-augment`) |
+
+## Invariants
+
+1. **Modern formats only** — Claude / Cursor get the host's modern
+   skill / rule format; legacy XML / `.cursorrules` is not emitted.
+2. **Tool gating respected** — output for `tools.enabled = false`
+   never appears on disk.
+3. **Determinism** — same input + settings produce identical output;
+   CI enforces via `task sync-check`.
+4. **Path stability** — surface files live at the host's documented
+   location ([Cursor](https://docs.cursor.com), [Cline](https://docs.cline.bot),
+   [Windsurf](https://docs.codeium.com)).
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Cursor doesn't see rules | `.cursor/` not generated | `tools.enabled.cursor: true` then `task generate-tools` |
+| Claude Code missing a skill | skill not in `.agent-src/` yet | run Pipeline A (`task sync`) first |
+| Stale `.windsurfrules` after rule rename | concatenation cache | `task clean-tools && task generate-tools` |
+| Gemini CLI reads outdated content | `AGENTS.md` changed without re-symlink | `task generate-tools` |
+
+## Proving the pipeline
+
+- [`tests/test_modern_editor_formats.py`](../../tests/test_modern_editor_formats.py)
+  — verifies Claude / Cursor receive modern format with correct
+  frontmatter; runs only when `task generate-tools` has been executed.
+- [`tests/test_compress.py`](../../tests/test_compress.py) — covers
+  the shared compress / generate-tools entrypoint and `_filter_tool_dirs`.
+
+← [Architecture overview](../architecture.md)

package/docs/architecture.md

@@ -21,44 +21,36 @@ Stability tiers follow [`docs/contracts/STABILITY.md`](contracts/STABILITY.md):
 > The previous "observability, feedback, lifecycle" layers were removed in
 > 1.5 — they were scaffolds without production consumers.
 
-## Content pipeline
+## Content pipelines
+
+The end-to-end flow from source authoring to distributed surfaces
+is four discrete pipelines, each owned by one sub-page. Each page
+documents input → transform → output, invariants, failure modes,
+and cites the script, Taskfile target, and test file that prove
+the pipeline.
 
 ```
-.agent-src.uncompressed/          ← Source of truth (verbose, human-readable)
-    ↓ /compress command
-.agent-src/                     ← Compressed output (token-efficient, shipped in the package)
-    ↓ project_to_augment() — copies rules by default, symlinks rest
-                              (toggle: augment.rules_use_symlinks)
-.augment/                       ← Local projection for Augment Code (gitignored)
-    ↓ install.sh (Cursor, Cline, Windsurf, Augment VSCode) / plugin system
-.claude/ .cursor/ .clinerules/  ← Tool-specific symlinks/copies (auto-generated)
-.windsurfrules  GEMINI.md
-    ↓ scripts/build_cloud_bundle.py    (Phase 1 — cloud distribution)
-dist/cloud/<skill>.zip          ← Anthropic Skills bundles (Claude.ai Web / Skills API)
+.agent-src.uncompressed/   ──Pipeline A──▶  .agent-src/
+                                              │
+                                              ├──Pipeline B──▶  .augment/
+                                              │
+                                              ├──Pipeline C──▶  .claude/ · .cursor/ · .clinerules/
+                                              │                  .windsurfrules · GEMINI.md
+                                              │
+                                              └──Pipeline D──▶  dist/cloud/<skill>.zip
 ```
 
-### Installer layout
-
-In a consumer project, the installer (`scripts/install.sh`) and the
-package's own `project_to_augment()` projection produce a `.augment/`
-tree where:
-
-- `.augment/rules/` — **copies** of compressed rule files by default.
-  Augment Code historically does not load symlinked rules, so each
-  rule is a real file. Set `augment.rules_use_symlinks: true` in
-  `.agent-settings.yml` to switch them to symlinks once Augment Code
-  supports it (the toggle is honored by both `scripts/install.sh` on
-  the consumer side and `project_to_augment()` in the package).
-- `.augment/skills/`, `.augment/commands/`, `.augment/personas/`,
-  `.augment/contexts/`, `.augment/templates/` — **symlinks** into
-  `.agent-src/<subdir>/`. Reading a context follows the symlink to
-  the package payload.
-- `.augment/docs/guidelines/` — **symlink** into the package's
-  `docs/guidelines/` (consumer side: `node_modules/@event4u/agent-config/docs/guidelines/`;
-  package self-projection: `../docs/guidelines/`). This is the only
-  `docs/` subdirectory exposed in `.augment/`; `docs/contracts/` and
-  `docs/decisions/` are package-internal — rules that reference
-  contracts inline a 2–3 line excerpt instead of linking out.
+| Pipeline | Page | Output |
+|---|---|---|
+| **A.** Compression | [`architecture/compression.md`](architecture/compression.md) | `.agent-src/` |
+| **B.** Augment projection | [`architecture/augment-projection.md`](architecture/augment-projection.md) | `.augment/` |
+| **C.** Multi-tool projection | [`architecture/multi-tool-projection.md`](architecture/multi-tool-projection.md) | `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`, `GEMINI.md` |
+| **D.** Claude.ai bundle | [`architecture/claude-bundle.md`](architecture/claude-bundle.md) | `dist/cloud/<skill>.zip` |
+
+The drift check
+[`tests/test_architecture_docs_pipelines.py`](../tests/test_architecture_docs_pipelines.py)
+fails if any of the four sub-pages exists without its cited script /
+Taskfile target — or vice versa.
 
 Cross-references inside `.agent-src/rules/*.md` are written
 **relative to `.agent-src/rules/`** (e.g. `../contexts/execution/foo.md`,
@@ -118,25 +110,10 @@ green.
 
 ### Cloud-bundle pipeline
 
-`task build-cloud-bundles-all` produces one ZIP per skill at
-`dist/cloud/<skill>.zip`, ready for upload to Claude.ai Web (Settings →
-Customize → Skills) or the Anthropic Skills API. Per-skill behavior
-follows the cloud-tier classification from `scripts/audit_cloud_compatibility.py`:
-
-| Tier  | Bundle action                                                     |
-|-------|-------------------------------------------------------------------|
-| T1    | Bundle as-is — pure guidance, sandbox-safe                        |
-| T2    | Bundle with prepended sandbox note + package-internal path-swap   |
-| T3-S  | Same as T2; optional script calls degrade gracefully on cloud     |
-| T3-H  | **Skipped** — Phase 2 cloud-aware variant required before bundling |
-
-Cloud-side caps enforced by the builder: `description` ≤ 200 chars
-(Claude.ai Web) with a 1024-char hard cap (Anthropic spec). The sandbox
-note explains to the agent that `.agent-src/`, `agents/`, and `task …`
-references are descriptive — the host has no filesystem access.
-
-CI gate: `task ci-cloud-bundle` runs the builder in `--check` mode and
-fails on any source-side violation, without producing artifacts.
+See [`architecture/claude-bundle.md`](architecture/claude-bundle.md)
+for the full Pipeline D documentation — tier classification, sandbox
+note, package-internal path-swap, description budget, and the
+`task ci-cloud-bundle` dry-run gate.
 
 ## What's inside