@event4u/agent-config 9.8.0 → 9.9.0

package/docs/distribution/registries.md

@@ -1,126 +0,0 @@
-# External Registry Submissions
-
-Track third-party registries / directories we want this package to surface in. Submissions are **human-owner** — they require a GitHub account interacting with another org's PR review or with the GitHub UI to flip settings.
-
-> **Authority** — Phase 2 of [`road-to-product-adoption.md`](../../agents/roadmaps/road-to-product-adoption.md). The autonomous roadmap pass cannot open PRs in third-party repos; this file is the handoff.
-
-## Distribution channels — npm-primary
-
-Per [`ADR-033`](../decisions/ADR-033-distribution-identity-npm-primary.md), the package is **npm-primary, Packagist deprecated-in-place**. Both lenses of the council deliberation (strategic / operational) converged on a single-channel posture: this is the canonical record of which registries we publish to vs. which we treat as legacy.
-
-| Channel | Status | Canonical install | Notes |
-|---|---|---|---|
-| npm — `@event4u/agent-config` | **Primary** | `npm install @event4u/agent-config` or `npx @event4u/agent-config install` | The release pipeline (`scripts/release.py`) runs `npm publish` exclusively; `package.json` is the source of truth for the published version. |
-| Packagist — `event4u/agent-config` | **Deprecated-in-place** | (do not install — see ADR-033) | The 1.0.4 listing is a legacy artefact from the pre-3.x repo namespace. No `composer.json` ships from this repo. Maintainer-side claim/archive action required (see below). |
-
-### Packagist deprecation — human-owner item
-
-The Packagist `event4u/agent-config` listing pins at 1.0.4 from a repository state that no longer exists. The autonomous pipeline cannot retire that listing — it requires a maintainer login at `packagist.org/packages/event4u/agent-config`. Two paths exist; either is acceptable per ADR-033.
-
-- [ ] **Claim + abandoned-flag the package.** Log in at packagist.org, claim the `event4u/agent-config` namespace, set the package to `abandoned` with the replacement pointer `event4u/agent-config` on npm (or the npm package URL as a body note where Packagist's abandoned-replacement field expects a Composer-namespace value, fall back to a `description` field redirect).
-- [ ] **OR: leave the listing as legacy + add a description-field redirect.** If claim is blocked or out of scope, edit the listing description to add a one-line `> Deprecated — install via npm: \`@event4u/agent-config\`` so any consumer who lands there sees the correct path.
-
-This item is **owner-owned**, not autonomous; the roadmap explicitly captures it as such (`road-to-distribution-identity.md` Phase 2 Step 1). Mark the chosen path with `[x]` once executed.
-
-### Breaking-change communication
-
-Major-version bumps are policy-correct per [`CONTRIBUTING.md § Versioning policy`](../../CONTRIBUTING.md) (semver — installer-layout changes are major). The auto-generated `CHANGELOG.md § Breaking` section is the **single source of truth** for breaking changes; [`ADR-027`](../decisions/ADR-027-changelog-machine-vs-manual.md) locks the machine-generated path.
-
-Consumers who see a major-version bump should follow:
-
-1. [`CHANGELOG.md § Breaking`](../../CHANGELOG.md#breaking) — the diff between the prior and the new major. Every breaking change carries a Conventional-Commits subject prefixed `feat!:` or with a `BREAKING CHANGE:` footer.
-2. The release-line link in the GitHub release entry for the new version (links the auto-generated changelog section).
-
-No bespoke `BREAKING_CHANGES.md` is maintained — the changelog is the authoritative surface.
-
-## Submission status
-
-| # | Registry | URL | Submission shape | Status | PR link |
-|---|---|---|---|---|---|
-| 1 | `punkpeye/awesome-mcp-servers` | <https://github.com/punkpeye/awesome-mcp-servers> | One-line entry under the Developer-Tools section + Glama score badge | ❌ **PR closed unmerged 2026-06-11** (verified live 2026-07-25 via `gh pr view 6865`; this row previously read "PR open" for six weeks) | <https://github.com/punkpeye/awesome-mcp-servers/pull/6865> |
-| 2 | `mcp.so` | <https://mcp.so/> | Submit via the directory form; same one-line shape | ✅ submitted (maintainer-confirmed 2026-06) | — |
-| 3 | `mcpservers.org` | <https://mcpservers.org/> | Submit via the directory form; same one-line shape (verify URL current at submission time) | ✅ submitted (maintainer-confirmed 2026-06) | — |
-| 4 | `glama.ai` | <https://glama.ai/mcp/servers/event4u-app/agent-config> | Server page live; score badge embedded in the awesome-mcp-servers entry (PR #6865) | ✅ listed (server page + badge return HTTP 200, verified 2026-06-08) | <https://glama.ai/mcp/servers/event4u-app/agent-config> |
-
-## Submission template
-
-Use this exact text for the awesome-list entry. Adjust the link anchor per directory.
-
-```markdown
-- [event4u/agent-config](https://github.com/event4u-app/agent-config#readme) — Universal AI Agent OS. Audited skills, governance rules, commands, and templates for Claude Code, Cursor, Windsurf, Copilot. Bring your own provider.
-```
-
-## Submission body — ledger-bound, version-agnostic
-
-Reuse this block in any directory submission or PR description.
-
-It deliberately carries **no artefact counts and no version number.** The block
-this replaced described version 3.2.0 with figures like "4929 tests" and role
-experiences that no longer exist; it sat here for months while the package
-reached 9.7.0, because this file is not scanned by the artefact-count gate
-(it is now — see § Drift guard). A stale number on a public growth surface is
-precisely what this package positions against, so the shape below cannot rot:
-every figure resolves through [`docs/CLAIMS.md`](../CLAIMS.md), and anything you
-add needs a ledger entry or it does not go in.
-
-```
-event4u/agent-config — a governance and content layer for AI coding agents,
-compiled into each host's native format. Bring your own provider: no SaaS, no
-remote sync, and no background daemon (claim: no-runtime-daemon).
-
-What is different is falsifiability. Every public claim binds to evidence a
-skeptic can reproduce on a fresh checkout, and the runs where the layer changed
-nothing are published too (claim: positioning-honest-nulls). The measured wedge
-is deliberately narrow: on weak or cheap hosts the `essential` tier transplants
-scope and downstream-change discipline at a measured 1.71x corpus cost, and it
-switches itself off on hosts where the effect measured null.
-
-Start at the proof, not the catalog:
-https://event4u-app.github.io/agent-config/proof/
-```
-
-Before pasting, verify: `task check-claims` is green on `main`, and each
-`claim:` id above still resolves to a `backed` entry. Artefact counts belong in
-the README badges (`update_counts` owns them) — never hand-typed into a listing.
-
-## Drift guard
-
-`docs/distribution/registries.md` is in
-[`check_artefact_count_messaging`](../../src/scripts/check_artefact_count_messaging.ts)
-`SURFACES`, so any artefact count that appears here must match the canonical
-number or CI fails. That is the structural fix for the rot described above:
-the previous block went stale silently because nothing watched this file.
-
-## Submission checklist
-
-Before opening any submission PR:
-
-- [ ] `README.md` hero block is the current shape (no stale claims).
-- [ ] `Public install smoke (3 OS × 2 Node)` badge is green on `main` for the last 3 cron cycles.
-- [ ] `package.json` `keywords` mirror `.github/topics.yml` `topics:` list (audit per Phase 2.4).
-- [ ] `LICENSE` and `CONTRIBUTING.md` are current.
-
-## GitHub Discussions
-
-Roadmap Phase 2 Step 5 calls for opening three Discussions categories: `Show & Tell`, `Q&A`, `Ideas`. This requires repo-admin in the GitHub UI (Settings → Features → Discussions). The README hero should then link to Discussions, not Issues, for first-touch questions.
-
-- [ ] Discussions enabled at `https://github.com/event4u-app/agent-config/discussions`
-- [ ] Three categories created: `Show & Tell`, `Q&A`, `Ideas` (no more — keep the surface narrow)
-- [ ] README hero updated to link to Discussions for first-touch questions
-
-## Audit cadence
-
-Run a topic / keyword reality check **every quarter**:
-
-1. Run three search queries on GitHub: `AI agent governance`, `MCP skill registry`, `AI video pipeline`.
-2. For each, verify this repo surfaces within page 2.
-3. If not, audit `.github/topics.yml` for missing topics and `package.json` `keywords` for alignment.
-4. Update `notes:` / `equivalents:` in `.github/topics.yml` and re-run `task sync-github-topics`.
-
-## See also
-
-- [`.github/topics.yml`](../../.github/topics.yml) — source of truth for GitHub topics.
-- [`package.json`](../../package.json) — `keywords` array, must mirror topics by category.
-- [`docs/distribution/topics-equivalents-decay-policy.md`](./topics-equivalents-decay-policy.md) — when to add / retire `equivalents:` entries.
-- [`docs/distribution/mcp-submission-checklist.md`](./mcp-submission-checklist.md) — MCP-specific submission checklist.
-- [`agents/roadmaps/road-to-product-adoption.md`](../../agents/roadmaps/road-to-product-adoption.md) — parent roadmap.

package/docs/distribution/registry-submissions.md

@@ -1,85 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-26
-roadmap_ref: road-to-adoption-proof-and-ci-green.md
----
-
-# Registry Submissions — tracking sheet
-
-> Phase C Step 2 of [`road-to-adoption-proof-and-ci-green.md`](../../agents/roadmaps/road-to-adoption-proof-and-ci-green.md).
-> Post-submission tracking sheet. The submission shape, schedule, and
-> the maintainer's automation contract live in
-> [`registries.md`](registries.md); this file is the operational
-> ledger.
-
-## Why a separate tracking sheet
-
-`registries.md` defines **what** to submit (the entry template, the
-audit cadence, the GitHub Discussions setup). This file records
-**what happened** — one row per submission, with status, link, and
-maintainer notes. Splitting them keeps `registries.md` editable as
-the submission shape evolves; this file accumulates history.
-
-## Status legend
-
-| Status | Meaning |
-|---|---|
-| `pending` | Pre-submission. Entry text staged but the maintainer has not opened the PR / submitted the form yet. |
-| `submitted` | PR opened or form submitted. Awaiting upstream review. |
-| `accepted` | Upstream merged the PR or accepted the directory entry. |
-| `rejected` | Upstream declined. Maintainer notes the reason. |
-| `stalled` | ≥ 60 days in `submitted` with no upstream response. Treated as effectively `rejected` for adoption-tracking purposes. |
-
-## Tracking rows
-
-| # | Registry | Submission shape | Status | PR / form URL | Date | Maintainer notes |
-|---|---|---|---|---|---|---|
-| 1 | `punkpeye/awesome-mcp-servers` | One-line entry under agent-tooling section; PR via `scripts/mcp_registry_submit.sh` | `submitted` | <https://github.com/punkpeye/awesome-mcp-servers/pull/9607> | 2026-07-07 | PR opened via the submit script (two script bugs fixed on the way: idempotent upstream remote, `--head OWNER:branch` format). Awaiting upstream review. |
-| 2 | `mcp.so` | Directory form submission (web form, no programmatic API) | `pending` | — | — | Form URL: <https://mcp.so/>. Submission shape: same one-line entry, paste into the form's `description` field. |
-| 3 | `mcpservers.org` | Directory form submission (web form, verify URL at submission time) | `pending` | — | — | Form URL: <https://mcpservers.org/>. Submission shape: one-line entry; check the site is live before posting. |
-
-## How to update a row
-
-When a row transitions:
-
-1. **`pending` → `submitted`.** Set `Status: submitted`, `Date: YYYY-MM-DD`, `PR / form URL: <link>`. Add one-sentence maintainer note (e.g. "PR #142; reviewer assigned").
-2. **`submitted` → `accepted`.** Set `Status: accepted`. Append the merge timestamp to the maintainer notes. Cross-link the merge commit / form-confirmation in the notes.
-3. **`submitted` → `rejected`.** Set `Status: rejected`. Append the reviewer's stated reason verbatim (or paraphrase if the conversation is verbal).
-4. **`submitted` → `stalled`.** Set `Status: stalled` once the row has been in `submitted` for ≥ 60 days with no upstream movement. The agent's `task adoption:status` (Phase C Step 6) flags any `stalled` row.
-
-The dates are UTC.
-
-## Maintainer-side checklist
-
-Before flipping a row from `pending` to `submitted`:
-
-- [ ] The `README.md` hero block is current (no stale claims about deferred features).
-- [ ] `task ci:status --branch main` is green (per `ci-green-floor.md`).
-- [ ] The submission template in `registries.md` § Submission template matches the package's current positioning.
-- [ ] The PR body (or form description) cites concrete reality, not aspiration — `task adoption:status` outputs the recent green-check tally + npm install delta the maintainer can paste into the submission.
-
-If any row stays `pending` for more than four weeks, the maintainer
-re-validates the readiness checklist; positioning that was current
-in week 1 can age out by week 4.
-
-## Adoption-tracking signal
-
-Each row's status contributes to the adoption-dimension score
-tracked in
-[`road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/archive/road-to-employee-product-and-external-proof.md)
-Phase 0 § Adoption surface:
-
-- ≥ 1 row in `accepted` — adoption-dimension lifts from "scaffolded"
-  to "evidence" for the next review round.
-- ≥ 2 rows in `accepted` — registries are no longer the bottleneck;
-  next adoption-dimension lift requires recruit-session reports
-  (Phase B of this roadmap).
-- All rows in `pending` after four weeks — the bottleneck is the
-  human-owner action, not the scaffold; the scaffold is solid.
-
-## See also
-
-- [`registries.md`](registries.md) — submission template + audit cadence + Discussions setup.
-- [`scripts/mcp_registry_submit.sh`](../../src/scripts/mcp_registry_submit.sh) — automation for row 1.
-- [`mcp-submission-checklist.md`](mcp-submission-checklist.md) — MCP-specific pre-submission floor.
-- `task adoption:status` (Phase C Step 6) — one-screen adoption dashboard.

package/docs/distribution/telemetry-privacy.md

@@ -1,128 +0,0 @@
-# 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

@@ -1,174 +0,0 @@
-# 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.uncondensed/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

@@ -1,51 +0,0 @@
-# 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.