@event4u/agent-config 9.7.0 → 9.9.0

package/docs/development.md

@@ -1,230 +0,0 @@
-# Development
-
-## Prerequisites
-
-- [Task](https://taskfile.dev/) (task runner)
-- Python 3.10+ (for linter, condensation tools)
-- Bash (for install scripts, tests)
-
-## Editing content
-
-1. **Always edit in `src/`** — never in `dist/agent-src/` or `.augment/` directly
-2. Run `task sync` to copy non-`.md` files
-3. Use the `/condense` command to condense changed `.md` files
-4. Run `task ci` to verify everything passes before pushing
-
----
-
-## Task Commands
-
-All commands use [Task](https://taskfile.dev/). The root `Taskfile.yml` orchestrates
-`ci`/`_ci-*` and includes the four task groups under `taskfiles/`
-(`ci-fast.yml`, `content.yml`, `engine.yml`, `release.yml`) with `flatten: true`,
-so every task stays in the root namespace. Run `task --list` for the full list.
-
-### CI & Verification
-
-```bash
-task ci                        # Run ALL CI checks locally (must pass before push)
-task consistency               # Verify sync + generated tool outputs are clean
-task consistency-fix           # Regenerate all derived outputs from source
-```
-
-### Sync & Condensation
-
-```bash
-task sync                      # src/ → dist/agent-src/, then project → .augment/
-task sync-changed              # List .md files changed since last condensation
-task sync-check                # Check if dist/agent-src/ is in sync (for CI)
-task sync-check-hashes         # Verify condensed .md hashes match source
-task sync-mark-done <file>     # Mark a single file as condensed
-task sync-mark-all-done        # Mark ALL files as condensed
-task sync-clean-hashes         # Remove stale hashes for deleted source files
-```
-
-### Tool Generation
-
-```bash
-task generate-tools            # Regenerate .claude/, .cursor/, .clinerules/, .windsurfrules, GEMINI.md
-task clean-tools               # Remove all generated tool directories
-```
-
-### Testing
-
-```bash
-task test                      # Run all tests (bash + Python)
-task test-install              # Install script integration tests
-task test-python               # Condensation and linter tests
-task test-linter               # Skill linter unit tests
-task test-readme-linter        # README linter unit tests
-task test-runtime              # Runtime registry + dispatcher tests
-task test-tools                # Tool registry + adapter tests
-task test-runtime-all          # All runtime and tools tests
-```
-
-#### CI test matrix
-
-GitHub Actions runs the suite on every push and PR across:
-
-| Runner | Python versions |
-|---|---|
-| `ubuntu-latest` | 3.10, 3.11, 3.12, 3.13 |
-| `macos-latest` | 3.12 |
-
-The matrix enforces the "Python 3.10+, stdlib only" guarantee from
-`CONTRIBUTING.md`. Installer integration tests (`test_install.sh`,
-`test_install_orchestrator.sh`) run on both Linux and macOS. Windows
-is not part of the matrix — consumers on Windows use WSL2 (see
-[installation guide](installation.md#windows)).
-
-### Linting
-
-```bash
-task lint-skills               # Lint all skills, rules, and commands
-task lint-skills-strict        # Lint with warnings as failures
-task lint-skills-changed       # Lint only changed files
-task lint-skills-report        # Per-file quality breakdown
-task lint-skills-regression    # Compare against main branch (detect regressions)
-task lint-skills-pairs         # Check condensation quality (source vs condensed)
-task lint-readme               # Lint README.md
-```
-
-### Quality Checks
-
-```bash
-task check-condensation         # Verify code blocks, headings, frontmatter preserved
-task check-refs                # No broken cross-references
-task check-portability         # No project-specific references in shared files
-task quality-report            # Per-artifact-type quality scores
-```
-
-### Runtime & Lifecycle
-
-```bash
-task runtime-list              # List all runtime-capable skills
-task runtime-validate          # Validate runtime registry consistency
-task runtime-e2e               # Dispatch each pilot skill (CI gate)
-task tool-list                 # List all registered tools
-task tool-validate             # Validate tool declarations
-```
-
-### Installation
-
-```bash
-task install -- --target <dir> # Run the installer orchestrator on a target
-task install-hooks             # Install git hooks (pre-commit marketplace lint, pre-push consistency gate, chat-history bridges)
-```
-
-The **pre-push hook runs `task consistency`** — the exact local mirror of the CI
-"Sync + Generate Tools Consistency" gate (sync + hashes + generate-tools +
-router + corpus + `git diff --quiet`). Any derived-output drift (counts, dist,
-generated tool trees) is blocked **before** the push instead of failing remote
-CI; the fix is `task consistency-fix`, stage, re-push. The hook auto-installs on
-`npm install` in a git clone (the `prepare` script); run `task install-hooks`
-manually if you skipped install scripts. Bypass a genuine WIP push with
-`git push --no-verify`.
-
-### Local dev install (no release)
-
-Use these tasks to run the working tree as if it were a published
-release — useful for testing changes before `task release` cuts an npm
-version.
-
-```bash
-task dev:install-global        # Refresh ~/.claude, ~/.cursor, ~/.augment, … from this working tree (--force)
-task dev:link                  # Symlink this repo as the global @event4u/agent-config (npm link)
-task dev:unlink                # Remove the global symlink
-```
-
-**Switch the global install between dev and release** — one-shot toggles
-that flip BOTH the `agent-config` bin on PATH and the user-scope content:
-
-```bash
-task install:use-dev           # global = THIS working tree (npm link + dev-build content)
-task install:use-release       # global = latest npm release (npm i -g @latest + release content)
-```
-
-Run `install:use-dev` to test the working tree as the live global install,
-then `install:use-release` to switch back to the published version. They are
-symmetric — whichever you run last is the active global `agent-config`.
-
-**Typical flow:**
-
-1. In this repo: `task dev:link` — once. The `agent-config` bin on PATH
-   now resolves into the working tree.
-2. In this repo: `task dev:install-global` — every time you want
-   user-scope content (`~/.claude/rules`, `~/.cursor/`, …) refreshed.
-3. In a consumer project that uses `@event4u/agent-config` from npm,
-   opt in to the linked dev tree:
-
-   ```bash
-   cd /path/to/consumer-project
-   npm link @event4u/agent-config
-   ```
-
-   `npx @event4u/agent-config …` and `node_modules/.bin/agent-config`
-   in that project now resolve into the dev tree. Undo with
-   `npm unlink @event4u/agent-config` (project) and `task dev:unlink`
-   (this repo).
-
-**Caveat — npx outside a linked project:** `npx @event4u/agent-config`
-in a directory without a linked `node_modules/@event4u/agent-config`
-fetches the published version from the registry. Either run `npm link
-@event4u/agent-config` in that project first, or call the global
-`agent-config` bin directly (which `task dev:link` puts on PATH).
-
----
-
-## Project Structure
-
-```
-.augment-plugin/               ← Plugin manifest (Augment CLI + Claude Code)
-.claude-plugin/                ← Plugin manifest (Claude Code)
-.github/plugin/                ← Plugin manifest (Copilot CLI)
-
-scripts/
-├── install                    ← Primary installer (orchestrator)
-├── install.sh                 ← Payload sync stage (hybrid copy + symlink)
-├── install.py                 ← Bridge files stage (.agent-settings.yml, JSONs)
-├── postinstall.sh             ← npm postinstall hook → scripts/install
-├── setup.sh                   ← One-time Composer hook setup
-├── condense.py                ← Condensation hash management
-├── check_condensation.py       ← Condensation quality checker
-├── skill_linter.py            ← Skill/rule/command linter
-├── lint_regression.py         ← Branch regression detection
-├── generate_tools.sh          ← Generate tool-specific directories
-├── check_references.py        ← Cross-reference validator
-├── ci_summary.py              ← GitHub Actions job summary (dispatcher runs)
-└── tools/
-    ├── base_adapter.py        ← Tool adapter contract
-    ├── github_adapter.py      ← GitHub API adapter
-    └── jira_adapter.py        ← Jira API adapter
-
-tests/
-├── test_install.sh            ← install.sh payload-sync integration tests
-├── test_install_orchestrator.sh ← scripts/install end-to-end tests
-├── test_skill_linter.py       ← Linter unit tests
-└── test_ci_summary.py         ← CI summary tests
-
-.github/workflows/
-├── skill-lint.yml             ← Lint + PR comment workflow
-└── consistency.yml            ← Sync + hash + tool verification
-src/templates/consumer-settings/   ← Settings templates for consumer projects
-
-src/                            ← Source of truth (human-readable, verbose)
-├── rules/                     ← Behavior rules
-├── skills/                    ← Skill definitions (SKILL.md per skill)
-├── domains/                   ← Slash command definitions (per pack)
-└── agent-src/                 ← Contexts, templates, profiles, personas, …
-
-dist/agent-src/                    ← Condensed output (token-efficient, shipped)
-├── (same structure)           ← Condensed .md + copied non-.md files
-
-.augment/                      ← Local projection for Augment Code (gitignored)
-├── rules/                     ← Real file copies (Augment cannot load symlinked rules)
-└── skills/, commands/, ...    ← Symlinks → ../dist/agent-src/<sub>
-```
-
----
-
-← [Back to README](../README.md)

package/docs/distribution/awesome-list-submission.md

@@ -1,46 +0,0 @@
-# awesome-list submission — DRAFT (not yet submitted)
-
-> Market-readiness roadmap B5. Submission copy for the community
-> "awesome-claude-code" / "awesome-claude-code-subagents" lists. **Draft only** —
-> submitting is a human act. Every line here is ledger-consistent: no unbacked
-> number, no invented third-party comparison. Lead with the wedge, not the OS.
-
-## Where to submit
-
-Candidate lists (verify each is active + read its CONTRIBUTING before opening a PR):
-
-- `awesome-claude-code` (skills / plugins / tooling)
-- `awesome-claude-code-subagents` (the wedge fits here — a single subagent)
-
-Track status in [`registry-submissions.md`](registry-submissions.md).
-
-## Entry A — the wedge (lead with this)
-
-**production-validator** — a read-only Claude Code subagent that runs the last
-gate before "done": it hunts mocks, stubs, and placeholders on the shipped
-(non-test) path and demands real-system evidence, returning a `READY` / `NOT
-READY` verdict with `file:line` citations. One `curl` into `.claude/agents/`, no
-other install, no runtime.
-
-- Link: `https://github.com/event4u-app/agent-config/tree/main/docs/wedge/production-validator`
-- One-liner (list-row form): `production-validator — the last-gate-before-done subagent: no mock/stub survives on the shipped path; install in one curl.`
-
-## Entry B — the suite (secondary)
-
-**event4u/agent-config** — a governed, no-runtime configuration layer for AI
-coding agents: audited skills, review personas, rules, and commands projected
-into 7+ hosts (Claude Code, Cursor, Windsurf, Copilot, …). Its distinguishing
-discipline: **every public claim is machine-checked** — the README binds each
-claim to resolvable evidence in a Claims-Ledger, and a generated proof page lets
-anyone reproduce the checks (`docs/proof.md`). Bring your own model.
-
-- Link: `https://github.com/event4u-app/agent-config`
-- One-liner: `agent-config — governed skills/rules/personas for AI coding agents, with machine-checked claims and a reproducible proof page. No runtime, bring your own model.`
-
-## Guardrails for whoever submits this
-
-- Do **not** add a performance number or a "better than X" comparison — the
-  suite's whole position is that claims are verifiable, so an unverifiable
-  submission line would be self-defeating.
-- Keep the wedge first: it is the low-friction door. The suite is the follow-on.
-- Re-check the target list is still maintained + follow its exact entry format.

package/docs/distribution/consumer-matrix.md

@@ -1,96 +0,0 @@
-# Consumer Matrix — pack-based release E2E
-
-> **Status:** active · **Owner:** maintainer · **Opened:** 2026-07-10
->
-> Workflow: [`.github/workflows/consumer-matrix.yml`](../../.github/workflows/consumer-matrix.yml)
-> · Runner: [`src/scripts/consumer_matrix.ts`](../../src/scripts/consumer_matrix.ts)
-> · Tripwire: [`.github/workflows/release-adjacent-health.yml`](../../.github/workflows/release-adjacent-health.yml)
-> · Source roadmap: road-to-proof-under-real-conditions (Phase 1)
-
-The consumer matrix exercises the **published tarball** the way a consumer
-does — pack → fresh global install into an isolated prefix → `init` into a
-fresh project → `doctor` → `conformance` → MCP stdio handshake →
-`hooks:doctor` → projection presence (`validate`) → uninstall — plus an
-upgrade leg (last published minor from the registry → packed tarball →
-`doctor` stays green) and pre-tag dry-runs of every release-adjacent
-workflow.
-
-## Why it exists — the tarball window
-
-Ordinary PRs run source-level matrices; release PRs run shape checks and
-(correctly) skip the source matrices per
-[`release-pr-gating`](../contracts/release-pr-gating.md). That skip is sound
-for the *diff* but blind to the *tarball*: every packaging incident below
-entered `main` on an ordinary PR and manifested only at publish time —
-exactly the window where nothing pack-based ran. The consumer matrix is the
-documented exemption from the release-PR cut surface and runs **on** release
-PRs, plus weekly against registry drift.
-
-## Counterfactual map — five historical failures → the leg that catches each
-
-Recorded per the roadmap's acceptance criterion 1. "Leg" names either a
-`consumer_matrix.ts` leg or a `consumer-matrix.yml` job.
-
-| # | Historical failure | Caught by |
-|---|---|---|
-| 1 | Published tarball missing `src/install/` while published code imported it (two minors; `ERR_MODULE_NOT_FOUND` in global installs of `doctor`/`conformance`) | `fresh-install` leg (`--version` + every subsequent CLI leg runs from the tarball) **and** `publish-dry-run` job's `prepack-check.mjs` import-completeness step |
-| 2 | `tsx` absent from the published package — hooks and TS commands failed for consumers | `fresh-install` + `hooks` legs (installed binary + `hooks:doctor` run from the isolated prefix, no repo `node_modules` to lean on) |
-| 3 | Release workflow failed on missing `go-task` in the CI environment | `publish-dry-run` job replicates the publish path pre-tag; any missing binary in a release-adjacent workflow surfaces on the release PR, not post-tag (see also the runbook note in [`release-pr-gating`](../contracts/release-pr-gating.md)) |
-| 4 | npm publish failed on `npm@latest` → npm 12 requiring Node 22 while the job ran Node 20 | `publish-dry-run` job: asserts `publish-npm.yml` pins an npm **major** (fails on `npm@latest`), then installs that exact pin on both Node 20 and 22 and runs the publish steps sans `npm publish` |
-| 5 | MCP worker deploy red across five consecutive releases, undetected (worker deps installed, root `tsx` missing) | `mcp-worker-dry-run` job (same pack + `wrangler deploy --dry-run` path, pre-tag, including the root `npm ci`) **and** the daily `release-adjacent-health` tripwire (fails loudly when any watched workflow's last completed run is non-success for > 48h) |
-
-**Rule for future failures:** a release incident with no leg in this table
-gets a new leg in the same fix PR — or a recorded reason why it is out of
-scope. The table is the audit trail.
-
-## Triggers
-
-| Trigger | What runs | Why |
-|---|---|---|
-| `pull_request` with `release/*` head | all four jobs | the pre-tag gate — release PRs are the primary trigger |
-| weekly cron (Tue 06:00 UTC) | all four jobs | registry/upstream drift between releases — the class the 48h tripwire alone cannot see pre-release |
-| `workflow_dispatch` | all four jobs | on-demand verification (e.g. after a packaging change) |
-| daily cron 06:30 UTC | `release-adjacent-health` | the > 48h durably-red detector |
-
-## Headless default-scope trap (matrix finding, 2026-07-10)
-
-Building this matrix surfaced a live consumer trap: on a fresh machine,
-headless `agent-config init --tools=… --yes` (no `--scope`) picks "project
-default for backward compatibility" and then hard-fails with
-`--scope=project is reserved for maintainers (ADR-020)` — the bare README
-invocation is red in any non-TTY context (CI, scripts), while the TTY path
-escapes into the browser wizard. `--scope=auto` honors detection and
-completes the documented global-only consumer install (`~/.claude`,
-`~/.cursor`, `~/.codeium/windsurf`, `~/.event4u` lockfile). The matrix
-therefore runs `init --scope=auto --yes` and pins that behaviour; whether
-the backward-compatibility default should flip to `auto` is a product
-decision tracked outside this contract (it changes installer behaviour, not
-the gate). Two adjacent facts the matrix also pins: standalone `doctor` is
-project-manifest-scoped (exit 2 without a project lockfile — expected on a
-global-only install; `conformance` embeds `doctor --ci` and is the health
-probe the matrix asserts), and consumer uninstall is `uninstall --global`.
-
-## Branch-protection note
-
-Marking the four jobs as **required** checks for `release/*` PRs is a
-repository setting (Settings → Branches), not something this repo's files
-can enforce. Until flipped, the jobs still run and fail visibly on the
-release PR; flipping them to required is the intended end state.
-
-## Local run (carve-out verification)
-
-```bash
-npm ci && npm run build
-npx tsx src/scripts/consumer_matrix.ts --json           # all legs
-npx tsx src/scripts/consumer_matrix.ts --skip-registry  # offline: skips the upgrade leg
-```
-
-## See also
-
-- [`release-pr-gating`](../contracts/release-pr-gating.md) — the cut surface
-  this matrix is exempt from, and why.
-- [`public-install-smoke`](public-install-smoke.md) — OS × Node entrypoint
-  matrix (installer correctness); the consumer matrix owns tarball shape +
-  runtime surface instead.
-- [`release-sizing`](../contracts/release-sizing.md) — names this matrix as
-  the floor for every release.

package/docs/distribution/launch-story-draft.md

@@ -1,58 +0,0 @@
-# Launch-story — DRAFT (not published)
-
-> Market-readiness roadmap B5. A short narrative draft for a launch post
-> (Show HN / dev.to / discussions), centered on the wedge + reproducible honesty.
-> **Draft only** — not published; the final headline is gated on the B0
-> positioning decision. Every claim must stay ledger-bound; no unbacked number,
-> no third-party performance comparison.
-
-## Angle
-
-Not "another agent framework." The hook is **reproducible honesty**: an AI-agent
-config layer where every public claim is machine-checked, and you can verify it
-yourself in one command. Open with the wedge (something the reader installs in 30
-seconds), then reveal the discipline behind it.
-
-## Draft body
-
-> Most AI-agent tooling asks you to trust a headline number. This one lets you
-> **check it.**
->
-> Start small — one file, 30 seconds:
->
-> ```bash
-> curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/production-validator.md \
->   -o .claude/agents/production-validator.md
-> ```
->
-> `@production-validator` is a read-only Claude Code subagent that runs the last
-> gate before "done": it finds the mock/stub/placeholder still sitting on your
-> shipped path and the "done" that was only ever validated against fakes.
->
-> That one subagent is a slice of a larger governed layer — skills, review
-> personas, rules, commands across 7+ hosts, no runtime. What makes it different
-> isn't the size; it's that **the marketing is under CI too.** Every claim in the
-> README binds to evidence in a ledger, a generated proof page renders those
-> bindings plus the benchmark runs where the tool changed *nothing*, and a
-> "verify it yourself" block reproduces all of it on a fresh checkout. If a claim
-> ever loses its binding, the build goes red.
->
-> Try the one file. If it earns its place, the rest is `npx @event4u/agent-config init`.
-
-## Placeholders to resolve before publishing
-
-- **H1 (decided, B0 · 2026-07-04):** *"Agent Config — every claim machine-checked,
-  including 'zero runtime'."* — adopted from the council's verifiability-as-frame
-  option. Use this headline for the post; do not substitute a provisional one.
-- Confirm the raw `curl` URL resolves on `main` at publish time.
-- Link the live proof page once a docs site (Starlight) hosts it, if built.
-
-## Guardrails
-
-- No performance claim or third-party comparison in the post.
-- The "benchmark runs where the tool changed nothing" line points at real
-  published nulls (`docs/benchmark.md`) — keep it truthful, do not dramatize.
-- Include the honest-provenance note: the skills/rules/personas are distilled
-  from real TypeScript/PHP production work; the governance is stack-agnostic but
-  domain heuristics are richest where forged — coverage elsewhere is promising,
-  not proven. (Roadmap B5.)

package/docs/distribution/mcp-submission-checklist.md

@@ -1,95 +0,0 @@
-# MCP registry submission checklist
-
-> One-shot procedure for opening a submission PR to an external MCP
-> registry. The manifest under `dist/mcp/` is the source of truth;
-> this file is what the maintainer runs through at submission time.
-
-## Before submitting
-
-1. Confirm the npm package is published with **2FA-required** for new
-   releases. A downstream user clicking the registry link must not
-   land on a hijacked release.
-2. Re-run the builder so payloads reflect the current package:
-   ```bash
-   ./scripts-run src/scripts/build_discovery_manifest --write --strict
-   ./scripts-run src/scripts/build_mcp_registry_manifest --write --strict
-   ./scripts-run src/scripts/lint_mcp_registry_manifest
-   ```
-3. Confirm `dist/mcp/registry-manifest.json` `package.version`
-   matches the latest published npm version (or the version about to
-   be released in the same change set).
-
-## Per-registry steps
-
-### `awesome-mcp-servers`
-
-- Upstream: <https://github.com/punkpeye/awesome-mcp-servers>
-- Target file: `README.md`, section **"Server Frameworks / Agents"**.
-  *Verify the section heading before each submission — upstream
-  reorganises occasionally.*
-- Payload to paste: the row in `dist/mcp/awesome-mcp-servers.row.md`.
-  ```bash
-  cat dist/mcp/awesome-mcp-servers.row.md
-  ```
-- Open the upstream PR. Title: `Add @event4u/agent-config`.
-- After opening, update `dist/mcp/registry-manifest.json`:
-  ```jsonc
-  {
-    "id": "awesome-mcp-servers",
-    "status": "pending",     // → "listed" once merged, "rejected" if closed
-    "submitted_at": "YYYY-MM-DD",
-    "pr_url": "https://github.com/punkpeye/awesome-mcp-servers/pull/NNN",
-    "last_verified": null
-  }
-  ```
-  Then commit the manifest change as a follow-up.
-
-### `mcp-cloudflare-catalogue`
-
-- Upstream: <https://github.com/cloudflare/mcp-server-cloudflare>
-- Target file: the catalogue JSON file the repository documents
-  (verify path against the upstream README before each submission).
-- Payload to paste: the JSON object in
-  `dist/mcp/mcp-cloudflare-catalogue.json`.
-  ```bash
-  cat dist/mcp/mcp-cloudflare-catalogue.json
-  ```
-- Same lifecycle update as above once the PR is open.
-
-## After the upstream PR closes
-
-The submission PR can end in three states. Each maps to a `status`
-value in the manifest. Do **not** silently drop entries.
-
-- **merged** → `status: "listed"`, set `last_verified` to today, open
-  the live listing once and confirm the link still resolves to this
-  package. Refresh `last_verified` every release.
-- **closed without merge** → `status: "rejected"`. Leave
-  `submitted_at` and `pr_url` populated so the rejection is
-  auditable. Do **not** auto-resubmit; the next attempt is a
-  judgment call by the maintainer.
-- **listing removed later** → `status: "unlisted"`. Refresh
-  `last_verified` to the date of removal so the audit trail is
-  intact.
-
-`scripts/lint_mcp_registry_manifest.py` exits non-zero if any
-registry entry uses a value outside the four-state enum.
-
-## Submitting to a new registry
-
-The schema's `id` vocabulary is closed (`awesome-mcp-servers`,
-`mcp-cloudflare-catalogue`). Adding a third registry is a
-**schema-version bump**:
-
-1. Update `docs/contracts/mcp-registry-manifest.schema.json`:
-   add the new `id` value, bump the top-level `version` const if
-   the field shape changes.
-2. Update `scripts/build_mcp_registry_manifest.py`'s
-   `REGISTRIES_SEED` with the new entry (id, label,
-   listing_format, submission_url, rendered_payload).
-3. Add a new renderer for the rendered payload (Markdown row,
-   JSON entry, or whatever the new registry expects).
-4. Add a new payload-shape check to
-   `scripts/lint_mcp_registry_manifest.py`.
-5. Land it as its own PR so the schema change is reviewed
-   independently of the submission itself.

package/docs/distribution/public-install-smoke.md

@@ -1,68 +0,0 @@
-# Public Install Smoke
-
-Cross-platform install matrix for the two consumer entrypoints.
-
-> **Authority** — Phase 1 of [`road-to-product-adoption.md`](../../agents/roadmaps/road-to-product-adoption.md). The matrix is the regression guard for Phases 3–5 of that roadmap.
-
-## What the matrix runs
-
-Workflow: [`.github/workflows/smoke-public-install.yml`](../../.github/workflows/smoke-public-install.yml).
-
-| Axis | Values | Total |
-|---|---|---|
-| OS | `ubuntu-latest` · `macos-latest` · `windows-latest` | 3 |
-| Node | `20` · `22` | 2 |
-| Install path | `setup.sh` (curl) · `agent-config init` (npx bin) · `--dry-run --yes` headless leg | 3 |
-| Total legs | | **18** |
-
-Each leg builds a local tarball from the current checkout, extracts it, then invokes the consumer entrypoint against a temp project root. The matrix proves "our installer is correct" — not "the npm registry is reachable".
-
-## Triggers
-
-| Trigger | Purpose |
-|---|---|
-| Pull request (path-filtered) | Catch regressions before merge when installer files change |
-| Push to `main` / `master` | Lock the baseline so a green main can be released without surprises |
-| Weekly cron `0 6 * * 1` (Mon 06:00 UTC) | Catch drift from upstream toolchain / registry changes even when no PR touched our installer |
-| `workflow_dispatch` | Manual run for incident triage |
-
-## What the matrix proves
-
-- `curl … setup.sh \| bash` resolves a tarball, extracts it, runs `scripts/install`, exits 0 on every OS / Node combination.
-- `npx @event4u/agent-config init` (simulated via `scripts/agent-config init` on the extracted tarball) writes `.claude/` and `.agent-settings.yml` to the target project on every OS / Node combination.
-- The headless `--dry-run --yes` leg accepts non-interactive flags, produces no file writes, exits 0.
-
-## What the matrix deliberately does NOT prove
-
-- **Provider credentials.** No OpenAI / Anthropic keys in CI; the `agent-config setup` wizard's provider validation step is exercised by unit tests in `tests/cli/` and `packages/core/installer/tests/`, not this matrix.
-- **The GUI wizard in a real browser.** The `ui:serve` boot path is covered by `vitest` (`tests/cli/uiServe.test.ts`); end-to-end wizard interactions are deferred to a follow-up roadmap.
-- **Network fetch from the public npm registry.** The matrix uses a local tarball on purpose so a flaky registry doesn't fail the smoke. Real-registry health is covered by `publish-npm.yml` after release.
-- **Tooling beyond `claude-code`.** The matrix installs a single tool target to keep wall-clock short. The full per-tool matrix lives in [`tests.yml`](../../.github/workflows/tests.yml) (`install-tests` job, sharded × 4).
-
-## Failure policy
-
-- Any leg red → **block merge** (status check required on `main`).
-- Weekly cron red → file an issue with the `regression` label and the failing leg's URL; do not auto-retry.
-- A leg that flakes twice in 14 days → freeze, audit `tests/test_one_liner_entrypoints.sh` for non-determinism, only un-freeze after a green run on three consecutive cron cycles.
-
-## Adapting the test scope
-
-The matrix invokes [`tests/test_one_liner_entrypoints.sh`](../../tests/test_one_liner_entrypoints.sh) plus the inline dry-run leg. Adding a new install path means adding a `test_*` function to that shell script — the matrix picks it up automatically.
-
-## Roadmap deviations
-
-The Phase 1 roadmap referenced two surfaces that never landed in code:
-
-| Roadmap text | Reality | Adaptation |
-|---|---|---|
-| `--no-ui` flag | CLI surface is `--yes` (non-interactive) + `--dry-run` (no writes) | Headless leg uses `--yes --dry-run` |
-| `AGENT_CONFIG_NO_UI=1` env | Not implemented; non-interactive mode is detected via stdin TTY + `--yes` | Same — `--yes` is the canonical CI-safe entry |
-
-These deviations are recorded here so a future maintainer reading the roadmap doesn't search for flags that don't exist. The intent of the roadmap step — prove the installer survives headless CI — is preserved.
-
-## See also
-
-- [`tests/test_one_liner_entrypoints.sh`](../../tests/test_one_liner_entrypoints.sh) — the smoke harness invoked per matrix leg.
-- [`scripts/install`](../../src/scripts/install) — the consumer-facing installer orchestrator.
-- [`.github/workflows/tests.yml`](../../.github/workflows/tests.yml) — the broader install integration matrix (Linux + macOS, 35 tests × 4 shards).
-- [`agents/roadmaps/road-to-product-adoption.md`](../../agents/roadmaps/road-to-product-adoption.md) — parent roadmap and acceptance criteria.