@event4u/agent-config 2.26.0 → 3.1.0

package/docs/distribution/telemetry-schema.md

@@ -0,0 +1,174 @@
+# Install-Funnel Telemetry — Wire Schema
+
+> **Status: source-only / inert.** This document specifies the install-funnel
+> telemetry contract. The client SDK ships in this repository with the remote
+> kill-switch defaulting to **off** and the production endpoint unset, so no
+> traffic is emitted from any consumer install until the maintainer deploys
+> the worker under a separate PR. See `non-destructive-by-default` — worker
+> deploy is Hard-Floor and requires explicit per-turn maintainer authorization.
+
+This is **install-funnel** telemetry. It is distinct from
+`telemetry.artifact_engagement` (agent-runtime skill/rule/command usage,
+stored locally per consumer project — see
+[`artifact-engagement-flow`](../../packages/core/.agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md)).
+The two systems do not share storage, transport, or opt-in state.
+
+## Goals
+
+Close the "we have no idea where consumers drop in the install funnel" blind
+spot named in `feedback6.txt § 10`, while staying inside three hard
+constraints:
+
+1. **Privacy-by-default** — opt-in, off by default, anonymous beyond
+   reasonable doubt, no PII, no quasi-IDs that re-identify under combination.
+2. **GDPR-fit out of the box** — lawful basis is consent under
+   Art. 6(1)(a); short retention; no cross-session linkability beyond a
+   2-hour server-issued session.
+3. **Cheap to drop** — if we kill the system we leave no orphan data.
+
+## Funnel stages (one event per stage)
+
+```text
+started
+  └→ wizard_opt_in_seen        (browser GUI only)
+  └→ wizard_opt_in_accepted    (browser GUI only)
+  └→ packs_selected
+  └→ applied
+  └→ first_command_run         (optional, ≤ 7 days after applied)
+  └→ errored                   (terminal; mutually exclusive with applied)
+```
+
+## Wire shape (one POST per stage event)
+
+`POST <worker-base-url>/install-event` with JSON body:
+
+```jsonc
+{
+  "schema_version": "1",
+  "event": "install_stage",
+  "stage": "started" | "wizard_opt_in_seen" | "wizard_opt_in_accepted"
+         | "packs_selected" | "applied" | "first_command_run" | "errored",
+  "ts": "2026-05-24T10:00:00Z",
+  "session_id": "<server-issued, 128-bit, 2h TTL; omit on first event>",
+  "entry_path": "npx" | "curl" | "gui",
+  "host_agent_family": "vscode" | "jetbrains" | "cli" | "browser" | "unknown",
+  "os": "linux" | "macos" | "windows",
+  "node_major": "20" | "22",
+  "agent_config_version": "<semver>",
+  "pack_categories": ["finance" | "founder" | "engineering" | "content"
+                    | "consultant" | "meta" | "other"],
+  "wizard_used": true | false,
+  "duration_bucket": "<30s" | "30s-2m" | "2m-10m" | ">10m",
+  "error_class": "network" | "filesystem" | "config_invalid"
+              | "dependency" | "unknown"
+}
+```
+
+### `session_id` is server-issued, not client-issued
+
+Per the AI Council Round-2 verdict, the client never generates an identifier.
+The first event in a session POSTs **without** `session_id`. The worker
+generates a random 128-bit token, writes it to KV with a 2-hour TTL, and
+returns it in the response. Subsequent stage events include the returned
+`session_id` so the worker can stitch the funnel.
+
+Sessions that exceed 2 hours appear as two unstitched events. This is
+acceptable — sessions that long are statistical outliers.
+
+### Field-by-field rationale
+
+| Field | Rationale | Re-identification risk |
+|---|---|---|
+| `session_id` | Server-controlled session stitching; 2h TTL; never persisted client-side | None (auto-expires) |
+| `entry_path` | Required to compare npx vs curl vs GUI funnels | None (3 buckets) |
+| `host_agent_family` | Required to compare IDE vs CLI completion rates | Low (4 buckets) |
+| `os` | Required to spot OS-specific install failures | Low (3 buckets) |
+| `node_major` | Required to spot Node version issues | Low (2 buckets) |
+| `agent_config_version` | Required to spot regression on a new release | Low |
+| `pack_categories` | Actionable funnel signal (which packs convert?) | Low (small fixed enum, no pack names) |
+| `wizard_used` | Wizard vs TUI completion comparison | None |
+| `duration_bucket` | Coarse timing; 4 buckets; no side-channel | None (vs `duration_ms` which leaks CI vs human) |
+| `error_class` | 5 buckets; never freeform; never a stack | None |
+
+## What we NEVER send
+
+- IP address (Cloudflare drops it before the worker reads the request body;
+  the worker code does not log or persist `cf-connecting-ip`).
+- Any machine identifier, MAC, hostname, username, home-directory path.
+- Project name, project path, repository slug, git remote URL.
+- Pack **names** (only the small fixed `pack_categories` enum is sent).
+- File paths of any kind.
+- Error stacks, error messages, or freeform `error_class` strings.
+- Anything the user typed (prompts, ticket IDs, ad-hoc commands).
+- Any timing field with sub-bucket precision (no `duration_ms`).
+
+## Retention
+
+| Tier | Storage | TTL | Notes |
+|---|---|---|---|
+| Raw stage events | Cloudflare KV | 14 days | Keyed by `event:<session_id>:<stage>` |
+| Sessions | Cloudflare KV | 2 hours | Keyed by `session:<session_id>` |
+| Weekly aggregates | Cloudflare KV | 24 months | Keyed by `funnel:weekly:<iso-week>`, no `session_id` |
+
+Aggregates contain only stage counts and bucketed dimension counts. No
+`session_id` is retained beyond 14 days.
+
+## Authentication and abuse resistance
+
+- **Per-channel HMAC signing.** Each entry path (`npx`, `curl`, `gui`) ships
+  with its own pre-shared HMAC secret embedded at build time. The installer
+  computes `HMAC-SHA256(secret, body)` and sends it in the `x-install-sig`
+  header. The worker validates the signature before parsing the body.
+  Rotation is handled by shipping a new installer release.
+- **Rate-limit per `session_id`.** The worker caps each session at 20 events
+  total. Excess events return `429`.
+- **Body size cap.** Bodies > 4 KB are rejected with `413`.
+- **Schema strictness.** Unknown fields cause `400`. Validators run before
+  KV writes.
+
+## Remote kill-switch
+
+The installer reads a Cloudflare-hosted feature-flag JSON
+(`https://<flag-host>/install-telemetry-flags.json`, cached for 1 hour,
+default `enabled=false` if unreachable) before each session. If the flag
+returns `enabled: false`, the SDK is a no-op for the entire session — no
+session is opened, no `started` event is sent, no opt-in prompt is shown.
+
+This gives the maintainer a one-line config change to disable telemetry
+across all consumers within 1 hour, independent of installer releases.
+
+## Worker contract
+
+`POST /install-event` — see fields above. Returns:
+
+- `200 { session_id }` on the first event of a session.
+- `204 No Content` on subsequent stage events.
+- `400 { error }` on schema mismatch or unknown fields.
+- `401` on missing or invalid HMAC.
+- `413` on body > 4 KB.
+- `429` on per-session rate limit.
+- `5xx` on worker error — the SDK fails open (no retry, no log).
+
+`GET /install-telemetry-flags.json` — see kill-switch above. Returns
+`{ enabled: bool, schema_version: "1" }`.
+
+## Versioning
+
+`schema_version: "1"` is the contract above. A breaking change ships
+`schema_version: "2"` alongside `/install-event/v2`. The worker maintains v1
+for ≥ 90 days after v2 ships. The installer always reports the version it
+was built with — no client-side migration.
+
+## Open questions for a follow-up PR
+
+- Should `pack_categories` include `other` or omit unknown? Currently `other`
+  is included to avoid silent loss.
+- Should `errored` events be retained longer (30 days) for incident
+  investigation? Decision deferred to first operational quarter.
+
+## See also
+
+- [`telemetry-privacy.md`](telemetry-privacy.md) — reader-facing privacy doc.
+- [AI Council Round-2 transcript](../../agents/runtime/council/responses/install-telemetry.json) — verdict + revisions.
+- `agents/roadmaps/road-to-product-adoption.md § Phase 4`.
+- `non-destructive-by-default` — worker deploy is Hard-Floor.

package/docs/distribution/topics-equivalents-decay-policy.md

@@ -0,0 +1,51 @@
+# Topics-equivalents decay policy
+
+The `equivalents:` map in [`.github/topics.yml`](../../.github/topics.yml)
+is a manually-curated paraphrase dictionary. Without a review cadence
+it rots: the README's prose evolves, the equivalents stay frozen, the
+positioning lint quietly accepts dead phrases, and a topic that *used*
+to be discoverable in the README becomes a ghost mapping.
+
+This policy locks down the review cadence so the map stays load-bearing.
+
+## Review cadence
+
+- **Every release cycle that touches the README tagline, H1, or any
+  section heading enumerated in `.github/topics.yml`** — the PR
+  author must re-run `task lint-positioning` *after* the README edit
+  and visually re-confirm that every entry under `equivalents:` still
+  matches a phrase in the current README. The lint only checks that
+  *at least one* needle hits — it cannot detect a stale entry.
+- **Six-monthly** — a dedicated `chore(visibility): refresh topics
+  equivalents` PR walks every key in `equivalents:` and either:
+  removes it (the equivalent now appears literally in the README),
+  rewrites it (the README phrase changed), or removes the parent
+  topic (no longer positioned).
+
+## Removal heuristics
+
+Drop an `equivalents:` entry when **any** of these holds:
+
+- The topic key appears verbatim (case-insensitive) in the current
+  README — the equivalents row is redundant.
+- The README phrase the equivalent was mapped to no longer exists —
+  the row is a stale alias and the lint is silently passing on a
+  ghost.
+- The topic itself is no longer in `topics:` — orphan entry.
+
+## Why not a runtime lint?
+
+The original AI-Council suggestion was to "replace the map with a
+runtime lint that warns when a tagline word appears in a topic
+equivalent but the parent README phrase has changed." That requires
+storing a hash of the matched README phrase per equivalent and
+re-validating on every lint run — extra moving parts for a low-yield
+gate. The cheaper contract is the six-monthly human review documented
+above. If the map grows past ~15 keys or rots faster than two release
+cycles, revisit and promote to a runtime check.
+
+## Tracking
+
+Maintainers log each refresh in
+[`agents/evidence/notes/visibility-sync-audit.md`](../../agents/evidence/notes/visibility-sync-audit.md)
+with a one-line entry: date, PR, keys touched.

package/docs/examples/agent-user.example.md

@@ -4,7 +4,9 @@ identity:
   name: "Mathias"
   nickname: "Matze"
 language: "de"
-role: "founder/engineer"
+role:
+  - founder
+  - engineer
 style:
   formality: "informal"
   pace: "pragmatic"

package/docs/featured-skills.md

@@ -0,0 +1,95 @@
+# Featured Skills
+
+A curated subset of the ~218 active skills. Three tiers, one per primary audience. Full catalog lives in [`.agent-src/skills/`](../.agent-src/skills/); see also [`docs/catalog.md`](catalog.md) for the complete index and [`docs/featured-commands.md`](featured-commands.md) for command-level highlights.
+
+> **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (see `road-to-product-adoption.md` Phase 1), this page is documentation, not marketing. The entries below are the candidates the corpus tests against; their description quality is what the eval validates.
+
+Each row links to the canonical artefact under `.agent-src/`. Substitutions vs. the original roadmap proposal: `pitch-narrative` → [`fundraising-narrative`](../.agent-src/skills/fundraising-narrative/SKILL.md) (closest existing skill; pitch-narrative is not yet authored).
+
+---
+
+## Featured for Founders & Consultants
+
+**Install:** `npx -y @event4u/agent-config init --pack founder-strategy`
+(Consultants: pair with `--pack product-discovery` for discovery / interview tooling.)
+
+**You reach for this when:** you switch between investor pitch, hiring decision, product spec, and unit-economics modeling in the same week — and need cross-domain skills that respect a board-defensible bar.
+
+| Artefact | What it does |
+|---|---|
+| [`/refine-prompt`](../.agent-src/skills/refine-prompt/SKILL.md) | Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans |
+| [`/work`](../.agent-src/commands/work.md) | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report |
+| [`/grill-me`](../.agent-src/commands/grill-me.md) | Interactive grill-style interview that sharpens a fuzzy plan / idea into a copyable Markdown pitch |
+| [`/optimize-prompt`](../.agent-src/commands/optimize-prompt.md) | Optimize a raw prompt for ChatGPT / Claude / Gemini via the 4-D methodology |
+| [`decision-record`](../.agent-src/skills/decision-record/SKILL.md) | Lock a trade-off — options · trade-offs · consequences — before the ADR file is written |
+| [`fundraising-narrative`](../.agent-src/skills/fundraising-narrative/SKILL.md) | Why-now / why-us / why-this framing, market-size reasoning, traction-story construction |
+| [`okr-tree-modeling`](../.agent-src/skills/okr-tree-modeling/SKILL.md) | Decompose a company objective into team OKRs; audit a draft tree for measurability and laddering |
+| [`voc-extract`](../.agent-src/skills/voc-extract/SKILL.md) | Extract Voice-of-Customer themes from existing artefacts — GH issues, PR threads, Sentry patterns |
+| [`dcf-modeling`](../.agent-src/skills/dcf-modeling/SKILL.md) | Valuation cognition for a CFO / finance-partner — DCF, WACC, terminal value, sensitivity |
+| [`runway-cognition`](../.agent-src/skills/runway-cognition/SKILL.md) | Cash runway, burn shape, fundraise triggers, layoff-vs-cut-vs-grow decisions |
+
+→ Pack details: [`packages/founder-strategy/`](../packages/founder-strategy/) · Role guide: [`docs/getting-started-by-role.md#founder`](getting-started-by-role.md#founder-early-stage-operator-wearing-every-hat)
+
+---
+
+## Featured for Content Creators
+
+**Install:** `npx -y @event4u/agent-config init --pack ai-video`
+(Writers / marketers without video: pair with `--pack gtm-marketing` for editorial / brand tooling.)
+
+**You reach for this when:** you draft blog posts, marketing emails, launch copy, release announcements, or produce AI-generated video — and need brand-voice discipline plus a cinematic-grade prompting pipeline more than code-quality enforcement.
+
+| Artefact | What it does |
+|---|---|
+| [`/video:from-script`](../.agent-src/commands/video/from-script.md) | End-to-end pipeline: script → character-locked image → motion + audio prompt → provider render → stitched clip |
+| [`/video:scene`](../.agent-src/commands/video/scene.md) | Render a single scene from an existing blueprint against the configured provider adapter |
+| [`/video:storyboard`](../.agent-src/commands/video/storyboard.md) | Expand a one-line idea into the 12-block Cinematic Scene Blueprint (provider-agnostic) |
+| [`pixar-storyteller`](../.agent-src/skills/pixar-storyteller/SKILL.md) | Turn an idea into a Pixar-style animation prompt — character sheet, scene, image, video — anchored in emotional beat, want, obstacle |
+| [`motion-choreographer`](../.agent-src/skills/motion-choreographer/SKILL.md) | Turn a locked still + blueprint into a provider-tuned motion prompt — camera, primary + secondary motion, physics, native-audio sync |
+| [`canvas-design`](../.agent-src/skills/canvas-design/SKILL.md) | Create static visual art — posters, marketing visuals, brand assets, PDF / PNG design pieces |
+| [`voice-and-tone-design`](../.agent-src/skills/voice-and-tone-design/SKILL.md) | Define and audit brand voice — voice attributes, tone-by-context matrix, consistency review |
+| [`editorial-calendar`](../.agent-src/skills/editorial-calendar/SKILL.md) | Cadence shape — evergreen vs campaign vs reactive, beat-mapping across channel stages, content-debt management |
+
+`AIV_DRYRUN=true` is the mandatory default for video pipelines — no provider call, no spend until you opt in.
+
+→ Pack details: [`packages/ai-video/`](../packages/ai-video/) · Role guide: [`docs/getting-started-by-role.md#creator`](getting-started-by-role.md#creator-writer-marketer-indie-content-shop)
+
+---
+
+## Featured for Engineering Leads
+
+**Install:** `npx -y @event4u/agent-config init --pack engineering-base`
+(Stack-specific add-ons: `--pack laravel`, `--pack nextjs`, `--pack symfony`, `--pack react`, `--pack typescript`.)
+
+**You reach for this when:** you write code daily and want testing / quality / git / CI / security guardrails baked into the agent's behavior — covering both the daily loop (`/work`, `/commit`) and the review surface (`/review-changes`, judges).
+
+| Artefact | What it does |
+|---|---|
+| [`/work`](../.agent-src/commands/work.md) | Free-form prompt end-to-end loop — refine → plan → implement → test → verify, confidence-band gated |
+| [`/implement-ticket`](../.agent-src/commands/implement-ticket.md) | Drive a Jira / Linear ticket end-to-end — same loop, ticket-anchored |
+| [`/review-changes`](../.agent-src/commands/review-changes.md) | Self-review local changes before creating a PR — dispatches to five specialized judges and consolidates verdicts |
+| [`/commit`](../.agent-src/commands/commit.md) | Stage and commit all uncommitted changes — splits into logical commits following Conventional Commits |
+| [`judge-bug-hunter`](../.agent-src/skills/judge-bug-hunter/SKILL.md) | Correctness review — null-safety, edge cases, off-by-one, races, error handling |
+| [`judge-code-quality`](../.agent-src/skills/judge-code-quality/SKILL.md) | Readability review — naming, single-responsibility, DRY, dead code, codebase-convention drift |
+| [`judge-security-auditor`](../.agent-src/skills/judge-security-auditor/SKILL.md) | Security review — authZ, injection, secrets, unsafe deserialization, SSRF, XSS, mass assignment |
+| [`judge-test-coverage`](../.agent-src/skills/judge-test-coverage/SKILL.md) | Test review — missing assertions, uncovered branches, over-mocking, regression coverage |
+| [`playwright-architect`](../.agent-src/skills/playwright-architect/SKILL.md) | Shape a Playwright suite — locator strategy, Page Object boundaries, fixture composition, flake prevention |
+| [`threat-modeling`](../.agent-src/skills/threat-modeling/SKILL.md) | Pre-implementation threat model — trust boundaries + abuse cases mapped to files, BEFORE the first line of code |
+
+→ Pack details: [`packages/engineering-base/`](../packages/engineering-base/) · Role guide: [`docs/getting-started-by-role.md#developer`](getting-started-by-role.md#developer-the-original-audience)
+
+---
+
+## Lint contract
+
+Every entry above MUST resolve in [`dist/discovery/discovery-manifest.json`](../dist/discovery/discovery-manifest.json). The check is automated:
+
+```bash
+task lint-featured-skills
+# or directly:
+python3 scripts/lint_featured_skills.py
+```
+
+CI runs this in `taskfiles/ci-fast.yml`. Stale entries (renamed / removed skill or command) fail the build. See [`scripts/lint_featured_skills.py`](../scripts/lint_featured_skills.py) for the matcher.
+
+→ Browse all ~218 active skills: [`.agent-src/skills/`](../.agent-src/skills/) · all ~129 commands: [`.agent-src/commands/`](../.agent-src/commands/)

package/docs/getting-started-by-role.md

@@ -4,6 +4,8 @@
 
 `agent-config` ships ~210 skills, ~67 rules, and ~124 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
 
+> **Quickstart for every role.** Run `npx -y @event4u/agent-config init` — the browser wizard auto-launches and walks you through role, pack, and identity. Headless install path lives at [`docs/wizard.md`](wizard.md#headless--ci--no-browser). The wizard writes `.agent-settings.yml`, `.augment/`, and `.claude/` atomically; nothing leaves your disk.
+
 > **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (step-12 Phase 1 exit), this page is documentation, not marketing. The skills listed below are the candidates the corpus tests against; their description quality is what the eval validates.
 
 ---
@@ -16,7 +18,9 @@
 - [`messaging-architecture`](../.agent-src/skills/messaging-architecture/SKILL.md) — primary message + supporting proofs + audience-by-message matrix.
 - [`editorial-calendar`](../.agent-src/skills/editorial-calendar/SKILL.md) — evergreen vs campaign vs reactive cadence across channels.
 
-### Video
+### AI Video Pipeline
+
+Cinematic-blueprint approach: the agent expands your script into a 12-block scene plan, locks a character identity, then drives the rendering provider you have chosen. Provider-agnostic and dry-run-by-default.
 
 - [`/video:from-script`](../.agent-src/commands/video/from-script.md) — end-to-end pipeline: script → character-locked image → motion+audio prompt → provider render → stitched clip.
 - [`/video:storyboard`](../.agent-src/commands/video/storyboard.md) — expand a one-line idea into the 12-block Cinematic Scene Blueprint (provider-agnostic).
@@ -26,6 +30,10 @@
 
 `AIV_DRYRUN=true` is the mandatory default — no provider call, no spend until you opt in.
 
+**Try the first win →** [`pack-ai-video/FIRST_WIN.md`](../packages/pack-ai-video/FIRST_WIN.md) — one-line idea to a provider-tuned motion prompt in ~12 minutes.
+
+> **What this is not:** the package does **not** host a video model. It orchestrates prompts against the provider you select (Veo, Kling, Sora, Runway, …). Trust level is set by the provider's adapter lifecycle tier — see [`provider-lifecycle-discipline`](../.agent-src/rules/provider-lifecycle-discipline.md). You pay the provider directly, the package never sees your API key.
+
 **Install path:** **MCP recommended.** Claude Desktop is the lowest-friction entry; no terminal required. See [`docs/mcp.md`](mcp.md). CLI install works too if you already use a code editor.
 
 ---
@@ -38,6 +46,8 @@
 - [`unit-economics-modeling`](../.agent-src/skills/unit-economics-modeling/SKILL.md) — CAC, LTV, payback, contribution margin per customer.
 - [`fundraising-narrative`](../.agent-src/skills/fundraising-narrative/SKILL.md) — why-now / why-us / why-this framing, market-size reasoning.
 
+**Try the first win →** [`pack-founder-strategy/FIRST_WIN.md`](../packages/pack-founder-strategy/FIRST_WIN.md) — investor question reshaped into a defensible memo in ~10 minutes.
+
 **Install path:** **MCP for advisory work, CLI when you touch code.** Claude Desktop covers strategy / finance / narrative; CLI is needed only when you sit in the repo with the dev team.
 
 ---
@@ -74,6 +84,10 @@
 - [`deal-qualification-meddic`](../.agent-src/skills/deal-qualification-meddic/SKILL.md) — MEDDIC slots with evidence, inversion test, disqualification heuristic.
 - [`release-comms`](../.agent-src/skills/release-comms/SKILL.md) — value-not-feature framing, audience-segmented surfaces.
 
+Use the AI Video skills (see [Creator → AI Video Pipeline](#ai-video-pipeline)) when you need a launch asset, not a documentary — 8-second hero clips, social cutdowns, or feature-announcement teasers.
+
+**Try the first win →** [`pack-gtm-sales/FIRST_WIN.md`](../packages/pack-gtm-sales/FIRST_WIN.md) — single deal to a MEDDIC scorecard with inversion test in ~7 minutes.
+
 **Install path:** **MCP recommended.** GTM artifacts are documents, decks, and Notion pages; Claude Desktop is the natural home.
 
 ---
@@ -86,6 +100,10 @@
 - [`scenario-modeling`](../.agent-src/skills/scenario-modeling/SKILL.md) — base / upside / downside, three-statement modeling, sensitivity.
 - [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) — GDPR / CCPA / HIPAA fit, cross-border transfer, breach-impact triage.
 
+Outputs are flagged for human-accountant review by default — the agent surfaces a trust banner on every forecast / scenario reply so downstream readers see the human-in-the-loop expectation. See [`finance-safety-floor`](../.agent-src/rules/finance-safety-floor.md).
+
+**Try the first win →** [`pack-finance-basic/FIRST_WIN.md`](../packages/pack-finance-basic/FIRST_WIN.md) — runway question to a base/upside/downside narrative with trust banner in ~8 minutes. People-leaders running 1:1s: [`pack-ops-people/FIRST_WIN.md`](../packages/pack-ops-people/FIRST_WIN.md) — 1:1 cadence audit to a concrete recommendation in ~6 minutes.
+
 **Install path:** **MCP recommended.** Finance / ops workflows are spreadsheet- and document-heavy; the CLI buys nothing here unless you also export models into a code repo.
 
 ---

package/docs/getting-started.md

@@ -106,7 +106,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 72 rules. No configuration needed.
+This is enforced automatically by 75 rules. No configuration needed.
 
 ---
 
@@ -150,11 +150,12 @@ Your agent now understands slash commands:
 
 ---
 
-## Crash recovery — `agents/.agent-chat-history`
+## Crash recovery — `agents/runtime/.agent-chat-history`
 
 When `chat_history.enabled: true` in `.agent-settings.yml` (on by default
 for every profile), the agent keeps a JSONL log of your conversation in
-`agents/.agent-chat-history`. The file is git-ignored and rotates at the
+`agents/runtime/.agent-chat-history`. The file is git-ignored (covered
+by the `/agents/runtime/` catch-all) and rotates at the
 size configured in the profile (`128 KB` on `minimal`, `256 KB` on
 `balanced`, `512 KB` on `full`).
 
@@ -169,7 +170,7 @@ the log size, last entries, and current fingerprint. For the rare case
 where auto-adopt misfires (corrupted file, hook misconfiguration), run
 `./agent-config chat-history:adopt` as the manual recovery lever.
 
-See [`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+See [`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md)
 and [`scripts/chat_history.py`](../scripts/chat_history.py) for the mechanics.
 
 ---

package/docs/guidelines/agent-infra/ask-when-uncertain-demos.md

@@ -106,7 +106,7 @@ Agent: Bevor ich die Roadmap übergebe:
 - Welcher Branch?
 - Soll ich PRs erwähnen?
 - Welches Modell für die Fortsetzung?
-- Soll ich agents/.agent-chat-history zitieren?
+- Soll ich agents/runtime/.agent-chat-history zitieren?
 
 Antworte als 1, 2, 3, 4.
 ```

package/docs/guidelines/agent-infra/installed-tools-manifest.md

@@ -86,14 +86,17 @@ intentionally pin an older version of the manifest.
 
 ## Scope migration
 
-Moving a tool between `project` and `global` is supported but loud:
-
-1. Run `init --tools=<id> --scope=<new> --force`. The installer detects
-   the conflict, warns, and rewrites the entry only when `--force` is
-   present.
-2. The old bridge is **not** removed automatically — clean up the
-   leftover marker yourself (`rm .windsurf/agent-config.md` etc.).
-3. `validate` afterwards confirms the new state.
+Under [ADR-020](../../decisions/ADR-020-global-only-consumer-scope.md)
+global is the only consumer scope. Consumers carrying a pre-2.5
+project-scope payload move to global with the one-shot
+`npx @event4u/agent-config migrate-to-global` subcommand — it copies
+each tool's project payload into the matching user-scope path, drops
+the bridge marker, and removes the legacy project artefacts.
+
+For maintainers running `AGENT_CONFIG_DEV_MODE=1`, project-scope
+re-installs remain available; the installer still detects scope
+conflicts and refuses to rewrite without `--force`. `validate`
+afterwards confirms the new state.
 
 Reasoning: scope is a project-wide decision; flipping it silently
 would surprise other team members who never asked for the change. The

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

@@ -112,7 +112,7 @@ When the agent autonomously creates a roadmap, it owns the placement
 in the **same response**:
 
 - **Phase plan** (checkboxes, multi-turn execution) → `agents/roadmaps/<name>.md`, `status: ready` (default), regen dashboard.
-- **Decision matrix / ADR / pattern / lookup** (no `Phase N`, durable rationale) → `agents/contexts/<name>.md`.
+- **Decision matrix / ADR / pattern / lookup** (no `Phase N`, durable rationale) → `agents/settings/contexts/<name>.md`.
 - **Completed work snapshot** → `agents/roadmaps/archive/<name>.md`.
 
 A non-trackable file in `agents/roadmaps/` is a rule violation — the
@@ -146,6 +146,15 @@ dashboard, commit if commit policy allows.
 **Required:** each turn — implement step, flip `[x]`, regen, commit (if policy allows).
 A reply that lands a verified step without flipping its checkbox is a rule violation.
 
+**Deterministic flip-guard.** The autonomous loop carries a per-step
+guard at [`roadmap-process-loop § 5b`](../../.agent-src.uncompressed/contexts/execution/roadmap-process-loop.md#5b-flip-guard--deterministic):
+after the atomic flip, the loop runs
+`git diff --name-only -- agents/roadmaps/<file>.md` and halts loudly
+when the diff is empty. The `command:` triggers on
+`roadmap-progress-sync` keep the rule loaded for the entire
+`/roadmap:process-*` run; the guard is the deterministic backstop
+that catches a forgotten flip per step rather than at run end.
+
 **In-progress marker:** when a step takes more than one reply,
 mark it `[~]` the moment work starts on it and regenerate. The
 user sees one row move from `[ ]` to `[~]` to `[x]` instead of

package/docs/guidelines/agent-infra/rule-type-governance.md

@@ -48,7 +48,7 @@ The `description` field IS the trigger. It must describe **when** the rule appli
 
 Every new rule, and every edited rule whose body changes the trigger
 or the obligation, MUST classify itself against the hardening tiers
-documented in [`rule-trigger-matrix.md`](../../agents/contexts/rule-trigger-matrix.md):
+documented in [`rule-trigger-matrix.md`](../../agents/settings/contexts/rule-trigger-matrix.md):
 
 | Tier | Meaning |
 |---|---|
@@ -64,7 +64,7 @@ Classification surface: the optional `tier:` frontmatter field
 rules; bulk-retrofit of existing rules is tracked separately.
 
 Tier 3 dispositions are recorded centrally in
-[`agents/contexts/tier-3-dispositions.md`](../../agents/contexts/tier-3-dispositions.md)
+[`agents/settings/contexts/tier-3-dispositions.md`](../../agents/settings/contexts/tier-3-dispositions.md)
 with a 6-month re-audit clock. New Tier 3 rules append to that list
 on landing.
 

package/docs/guidelines/agent-infra/tool-integration.md

@@ -54,7 +54,7 @@ tool_permissions:
 New tools require:
 1. An adapter implementation in `scripts/tools/`
 2. Registration in the tool registry
-3. Documentation in `agents/docs/tools/`
+3. Documentation in `agents/reference/docs/tools/`
 
 ## Validation rules (linter)
 

package/docs/guidelines/docs/readme-size-and-splitting.md

@@ -142,9 +142,61 @@ in the other audience must find their link within the first screen too.
 
 ---
 
+## First-screen contract
+
+The "first screen" is roughly the **first ~40 rendered lines** (one
+laptop viewport on GitHub at default zoom). Every README must place
+the following inside the first screen:
+
+1. **Project name** as `# H1`
+2. **One-sentence pitch** — what it is, who it's for
+3. **Status badges** (CI, version, license) when they exist
+4. **Primary CTA** — either the install command or an explicit deep
+   link to the install section
+5. **Audience marker** — at least a chip / sentence telling the reader
+   which audience this README is written for
+
+What does **not** belong on the first screen: feature lists longer
+than a single line, architecture diagrams, contributor notes, license
+boilerplate.
+
+The skills `readme-writing`, `readme-writing-package`, and
+`readme-reviewer` enforce this checklist verbatim. Drift here is a
+hard finding, not a stylistic preference.
+
+---
+
+## Banner / visual-identity preservation
+
+When a README already carries a banner, hero image, badge row, or
+official logo lockup, the rewrite must preserve it **byte-identical**
+unless the user explicitly asks to change it. This includes:
+
+- The `<p align="center">` / banner image block (with its surrounding
+  HTML and the source URL of the image asset)
+- The status / npm / build badge block, including the exact badge
+  order if it was deliberate
+- Any profile / role / persona grid that establishes audience routing
+
+The re-analysis gate in each writing skill captures the exact line
+range as `visual_keep:` in the evidence ledger; the rewrite must
+echo those lines without paraphrase. If the badges' **counts** are
+out of date, propose new counts via the link-delta / currency-check
+output — do not silently rewrite the badge HTML to update numbers
+without surfacing the diff.
+
+Visual changes that are allowed without explicit user opt-in:
+
+- Repointing a badge whose `href` 404s to its current location
+- Repointing a banner image whose source path moved, when the file
+  is unambiguously the same asset
+
+---
+
 ## Validation checklist
 
-- [ ] First screen answers what / why / install
+- [ ] First screen answers what / why / install (see *First-screen contract*)
+- [ ] Banner / badge block preserved byte-identical (see *Banner / visual-identity preservation*)
 - [ ] Size is below the "overloaded" threshold, or splitting is in place
 - [ ] ToC present if > 150 lines or > 6 top-level sections
 - [ ] No duplication between README and `/docs/`

package/docs/guidelines/php/api-design.md

@@ -43,7 +43,7 @@ $projects = Project::query()
 
 ## Filtering and Sorting
 
-- Use the project's **filter pipeline** pattern (see `agents/docs/query-filter.md`).
+- Use the project's **filter pipeline** pattern (see `agents/reference/docs/query-filter.md`).
 - Filter classes are dedicated, testable units — not inline query logic.
 - Sorting via `sort` query parameter.
 

package/docs/guidelines/prompt-templates.md

@@ -153,7 +153,7 @@ This package **rejects** that whitelist. CO-STAR, RISEN, CRISPE,
 ReAct, and the image-AI templates above are first-class. The
 "5 safe" framing came from a single benchmark on a single LLM
 generation — it does not generalise. See AI Council session
-`agents/council-responses/prompt-master-mini.json` (2026-05-17) for the analysis behind this rejection. <!-- council-ref-allowed: ADR decision trace -->
+`agents/runtime/council/responses/prompt-master-mini.json` (2026-05-17) for the analysis behind this rejection. <!-- council-ref-allowed: ADR decision trace -->
 
 The right gate is request-type fit, not technique-whitelist
 membership.
@@ -163,4 +163,4 @@ membership.
 - [`prompt-optimizer`](../../.agent-src.uncompressed/skills/prompt-optimizer/SKILL.md) — engine-outbound; cites this catalogue in its Develop step
 - [`refine-prompt`](../../.agent-src.uncompressed/skills/refine-prompt/SKILL.md) — engine-inbound; uses templates in `mini` mode for stack-aware shaping
 - [`prompt-engineering-patterns`](../../.agent-src.uncompressed/skills/prompt-engineering-patterns/SKILL.md) — production-LLM prompt patterns (sibling skill, not a catalogue)
-- AI Council session: `agents/council-responses/prompt-master-mini.json` (2026-05-17) <!-- council-ref-allowed: ADR decision trace -->
+- AI Council session: `agents/runtime/council/responses/prompt-master-mini.json` (2026-05-17) <!-- council-ref-allowed: ADR decision trace -->

package/docs/hook-payload-capture.md

@@ -2,7 +2,7 @@
 
 **Purpose:** walk through the live-session payload capture for one platform
 in roughly 5 minutes, so the corresponding entry in
-[`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+[`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md)
 can move from `docs-verified` to `payload-verified`.
 
 **Scope:** Cursor · Cline · Windsurf · Gemini CLI. Augment Code and Claude
@@ -158,7 +158,7 @@ then flip the `[ ] Optional upgrade — payload-verified` checkbox to
 `[x]`.
 
 Then update the matching row in
-[`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md):
+[`agents/settings/contexts/chat-history-platform-hooks.md`](../agents/settings/contexts/chat-history-platform-hooks.md):
 the `Verification` column moves from `docs-verified` to
 `payload-verified`.
 
@@ -216,6 +216,6 @@ before paste because the redacted output goes into a tracked file
 - 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`
-- Platform matrix + payload schemas: [`agents/contexts/chat-history-platform-hooks.md`](../agents/contexts/chat-history-platform-hooks.md)
+- 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)