@event4u/agent-config 3.0.0 → 3.1.1

package/docs/distribution/telemetry-privacy.md

@@ -0,0 +1,128 @@
+# Install-Funnel Telemetry — Privacy
+
+> **3-minute read.** This page explains what the `@event4u/agent-config`
+> installer collects when you opt in, what it never collects, and how to
+> opt out.
+
+## TL;DR
+
+- **Off by default.** You see one prompt during install. If you do nothing,
+  nothing is sent.
+- **Anonymous.** No IP, no machine ID, no project name, no file paths.
+- **Short retention.** Raw events live 14 days; sessions live 2 hours.
+- **One-click off.** `--no-telemetry`, the wizard "No thanks" button, or
+  unsetting `TELEMETRY_OPT_IN=1` for the next install.
+
+## 1. What we collect (only if you opt in)
+
+Per install attempt, we send one event per funnel stage with these fields:
+
+- **Funnel stage** — one of: `started`, `wizard_opt_in_seen`,
+  `wizard_opt_in_accepted`, `packs_selected`, `applied`,
+  `first_command_run`, `errored`.
+- **Entry path** — `npx`, `curl`, or `gui`.
+- **Host agent family** — coarse bucket: `vscode`, `jetbrains`, `cli`,
+  `browser`, or `unknown`. Specific tool names (Cursor, Copilot, Windsurf)
+  are collapsed into the family bucket.
+- **Operating-system family** — `linux`, `macos`, or `windows`.
+- **Node major version** — `20` or `22`.
+- **agent-config version** — the semver string of the installer release.
+- **Pack categories** — a list of broad categories from a fixed enum
+  (`finance`, `founder`, `engineering`, `content`, `consultant`, `meta`,
+  `other`). Specific pack names are never sent.
+- **Wizard used** — boolean.
+- **Duration bucket** — one of `<30s`, `30s-2m`, `2m-10m`, `>10m`. We never
+  send millisecond timings.
+- **Error class** (only on `errored`) — one of `network`, `filesystem`,
+  `config_invalid`, `dependency`, `unknown`. Never a stack, never a
+  message.
+- **Session ID** — a 128-bit random token issued by our server with a
+  2-hour time-to-live, used to stitch the funnel. It is never persisted
+  on your machine.
+
+The full wire contract is in [`telemetry-schema.md`](telemetry-schema.md).
+
+## 2. What we NEVER collect
+
+- IP address. Cloudflare drops it before our worker reads the request body;
+  our code does not log `cf-connecting-ip`.
+- Machine identifiers — no MAC, no hostname, no username, no home directory.
+- Project name, project path, repository slug, git remote URL.
+- Pack names (only the coarse `pack_categories` enum).
+- File paths of any kind.
+- Error stacks, error messages, or any freeform error text.
+- Anything you typed: prompts, ticket IDs, ad-hoc commands.
+- Sub-bucket timing (no `duration_ms`).
+
+## 3. How to opt out
+
+Three paths, any one works:
+
+1. **Wizard (browser GUI)** — click "No thanks" on the telemetry screen.
+   This is the default focus; pressing Enter without picking declines.
+2. **CLI / TUI** — answer `n` at the telemetry prompt (default `n`).
+3. **CI / `--yes` mode** — telemetry is **always off** unless you pass
+   `--telemetry-opt-in` explicitly. There is no implicit consent in
+   non-interactive runs.
+
+You can also disable telemetry for one specific install by setting
+`AGENT_CONFIG_NO_TELEMETRY=1` in the environment.
+
+## 4. Per-install scope — choice is never persisted
+
+The opt-in choice applies **only to the current install session**. We do
+not write a preference file under your project, your home directory, or
+anywhere else. If you run the installer again, you will see the prompt
+again. This is intentional — every install is an explicit consent moment.
+
+## 5. How long we keep it
+
+| What | Storage | Time to live |
+|---|---|---|
+| Session ID + stage events | Cloudflare KV | 14 days |
+| Session token only | Cloudflare KV | 2 hours |
+| Weekly aggregates (no session ID) | Cloudflare KV | 24 months |
+
+Aggregates contain only counts — number of installs per stage, per OS, per
+entry path. No identifier survives beyond 14 days.
+
+## 6. Where the source lives, who can see the data
+
+- Client SDK source — [`packages/core/installer/src/telemetry/`](../../packages/core/installer/src/telemetry/).
+- Worker source — [`packages/cloud/telemetry-worker/`](../../packages/cloud/telemetry-worker/).
+- Aggregates are visible only to the named maintainers of
+  `event4u/agent-config`. No third-party access. No advertising integration.
+  No resale.
+
+## 7. Remote kill-switch
+
+We host a public feature-flag JSON. If we ever need to disable telemetry
+across all installs — for an incident, a privacy concern, or a deprecation
+— we flip the flag to `enabled: false`. The installer reads the flag
+before opening a session; if disabled, no events are sent regardless of
+your opt-in choice. The flag defaults to `false` when unreachable.
+
+## 8. Legal basis
+
+Lawful basis under the General Data Protection Regulation is consent
+under Article 6(1)(a). You give consent by clicking "opt in" or passing
+`--telemetry-opt-in`; you withdraw consent by choosing any of the opt-out
+paths in §3. Withdrawal applies to all future installs immediately.
+
+Because session IDs are server-issued, short-lived (2 hours), and not
+combined with re-identifying quasi-identifiers, the resulting records are
+designed to fall outside the GDPR Art. 4(1) definition of personal data.
+We treat them as personal data anyway for safety.
+
+## 9. Changes to this policy
+
+Material changes ship as a new section in this file plus a bump of
+`schema_version` in the wire format. Non-material changes (typo fixes,
+clearer wording) ship as plain edits. The current version corresponds to
+`schema_version: "1"` in [`telemetry-schema.md`](telemetry-schema.md).
+
+## See also
+
+- [`telemetry-schema.md`](telemetry-schema.md) — full wire contract.
+- `agents/roadmaps/road-to-product-adoption.md § Phase 4`.
+- `non-destructive-by-default` — why worker deploy is a separate PR.

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/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.
 
 ---
 
@@ -146,7 +146,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 128 active commands](../.agent-src/commands/)
+→ [Browse all 129 active commands](../.agent-src/commands/)
 
 ---
 

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/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/installation.md

@@ -1,23 +1,27 @@
 # Installation
 
-**Principle:** Global-first install (cross-project, in `~/.claude/`,
-`~/.cursor/`, …), opt-in project export when a team wants the config
-committed to a repo. No Task, no Make, no build tools required.
-
-> **v2.1+** — the installer detects intent. Running `npx
-> @event4u/agent-config init` in `~/` or any directory without a
-> project manifest defaults to **global**. Running it inside a project
-> (`package.json` / `composer.json` / `pyproject.toml` / etc.) defaults
-> to **project**. Pass `--scope=global` or `--scope=project` to override
-> detection. See `--scope` in the CLI help for the full matrix.
-
-A global install records itself in `~/.event4u/agent-config/installed.lock`
+**Principle:** Global is the only consumer scope. `init` writes to
+user-scope paths (`~/.event4u/agent-config/`, `~/.claude/`,
+`~/.cursor/`, …); the project tree only gets `agents/overrides/`
+and `agents/.event4u-bridge.yml`. Opt-in `export` if a team wants
+a tool's config committed to a repo. No Task, no Make, no build
+tools required.
+
+> **v2.5+** — `npx @event4u/agent-config init` always installs
+> globally. The `--project` / `--scope=project` flag is no longer
+> exposed to consumers; project-scope survives only behind the
+> maintainer-only `AGENT_CONFIG_DEV_MODE=1` flag (see
+> [`docs/maintainers/dev-mode.md`](maintainers/dev-mode.md)). The
+> legacy `--global` flag is accepted as a no-op for back-compat.
+> Rationale: [ADR-020](decisions/ADR-020-global-only-consumer-scope.md).
+
+The install records itself in `~/.event4u/agent-config/installed.lock`
 (schema_version, agent_config_version, installed_at, tools[]; the legacy
 `~/.config/agent-config/installed.lock` is read as a fallback). `npx
 @event4u/agent-config update` keeps that manifest in lockstep
 with the project pin in `.agent-settings.yml`. A version-mismatched
-re-run of `init --scope=global` is refused with exit code 1 until you
-`update` or pass `--force`.
+re-run of `init` is refused with exit code 1 until you `update` or
+pass `--force`.
 
 To commit a specific tool's config into a project repo, use:
 
@@ -311,6 +315,15 @@ Under the hood:
 
 - `scripts/install.sh` — payload sync (callable directly for sync-only runs).
 - `scripts/install.py` — bridge files (callable directly for bridge-only runs).
+  Two install.py-specific flags worth knowing:
+  - `--dry-run` prints a plan summary (profile · scope · tools · target ·
+    wizard auto-launch decision) and exits 0 without writing files or
+    spawning subprocesses. Distinct from the bash wrapper's `--dry-run`,
+    which only skips bridges.
+  - `--no-ui` suppresses the post-install browser-wizard auto-launch.
+    Also honored via `AGENT_CONFIG_NO_UI=1`. CI runners (`CI=1`) and
+    non-TTY stdouts auto-suppress regardless. See
+    [`docs/wizard.md § Auto-launch`](wizard.md#auto-launch-from-npx--init).
 
 A full run creates: