@event4u/agent-config 2.26.0 → 3.1.0

package/docs/deploy/policy-cookbook.md

@@ -0,0 +1,130 @@
+# Policy cookbook — internal AI OS
+
+> **Status**: 🚧 **skeleton**. Phase 3 of
+> [`road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md)
+> is **not yet implemented**. This file documents the **shape** that
+> central org policy will take so operators can review the contract
+> before code lands. Every section below is normative-once-shipped.
+>
+> Open design questions live in
+> [`agents/tmp/council-question-central-policy.md`](../../agents/tmp/council-question-central-policy.md).
+
+## Audience
+
+An admin at a deploying organization who needs to set org-wide floors
+(and ceilings) that individual users cannot escape.
+
+## File location (planned)
+
+```text
+/etc/event4u/policy.yaml          # inside the container
+${POLICY_PATH:-./policy.yaml}      # bind-mounted from the host
+```
+
+The file is the source of truth. A future admin UI generates this
+file, never the other way around.
+
+## Inheritance model (planned)
+
+```text
+default → org policy → user settings
+                   ↑           ↑
+                   |           └── user-only knobs (preferred name,
+                   |               IDE, bot icon)
+                   └── shared knobs (autonomy ceiling, redaction
+                       allowlist, provider allowlist, cost cap) —
+                       org wins; user cannot escape upward.
+```
+
+## Schema sketch (planned)
+
+```yaml
+# /etc/event4u/policy.yaml — example, not yet enforced.
+version: 1
+
+autonomy:
+  ceiling: review                   # never | review | apply-low | apply-medium
+  user_can_lower: true
+
+redaction:
+  allowlist_paths: []               # paths users are allowed to disable redaction for
+  block_paths:                      # paths where redaction is mandatory
+    - "**/secrets/**"
+    - "**/credentials/**"
+
+providers:
+  allowlist:
+    - openai
+    - anthropic
+  cost_cap_usd_per_day_per_user: 25
+  cost_cap_usd_per_day_total: 500
+
+audit:
+  retention_days: 90
+  include_read_actions: false       # only state-changing requests by default
+```
+
+## Recipes (planned)
+
+### Lock autonomy at "review" for all users
+
+```yaml
+autonomy:
+  ceiling: review
+  user_can_lower: false
+```
+
+### Cap monthly spend per user
+
+```yaml
+providers:
+  cost_cap_usd_per_day_per_user: 5      # ≈ $150/mo at max
+```
+
+### Restrict providers to those with EU data residency
+
+```yaml
+providers:
+  allowlist:
+    - anthropic-eu
+    - mistral
+```
+
+### Mandate redaction for `infrastructure/`
+
+```yaml
+redaction:
+  block_paths:
+    - "infrastructure/**"
+```
+
+## Hot reload (planned)
+
+The server will watch `POLICY_PATH` and apply changes within ~2 s
+without a restart. Sessions are not invalidated; only new
+permissions checks see the new policy. A `policy_reloaded` audit
+event lands on each successful reload.
+
+## Versioning (planned)
+
+Operators are expected to check `policy.yaml` into their **own** git
+repo (separate from this project) and mount it read-only into the
+container. `version: 1` is the only currently-defined schema version;
+breaking changes will bump the version + ship a migrator.
+
+## What's not yet here
+
+- Schema is not validated by the running server.
+- Hot-reload is not wired.
+- Admin UI does not exist.
+- Audit log table does not exist.
+
+All of the above land in Phase 3. Until then, per-user
+`.agent-settings.yml` is the only enforcement surface.
+
+## Cross-references
+
+- 🚧 Reserved ADR slot: `docs/decisions/ADR-023-central-policy.md`.
+- Council question: [`agents/tmp/council-question-central-policy.md`](../../agents/tmp/council-question-central-policy.md).
+- Env contract: [`env-vars.md`](env-vars.md) (`POLICY_PATH`).
+- Quickstart: [`quickstart.md`](quickstart.md).

package/docs/deploy/quickstart.md

@@ -0,0 +1,112 @@
+# Quickstart — internal AI OS
+
+> **Status**: skeleton. Phase 6 of
+> [`road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md).
+> The artefacts referenced (Compose, env contract, healthcheck) land in
+> Phase 1; **Phases 2–5 (auth, policy, team context, connectors) are
+> not yet implemented**. Sections flagged `🚧` describe surfaces that
+> only become real after those phases ship.
+
+## Audience
+
+A platform / DevOps engineer at a 5–50-person company who wants to
+host `@event4u/agent-config` once for the team behind their existing
+reverse proxy.
+
+## Prerequisites
+
+- Docker Engine ≥ 24 with Compose v2.
+- Reverse proxy (nginx / Caddy / Traefik / ALB) terminating TLS at
+  a hostname you control.
+- One free TCP port to forward to the container (default 8787).
+- 🚧 **Phase 2+** — your company's SSO / OIDC discovery URL + client
+  credentials.
+
+## Five-minute path
+
+```bash
+# 1. Clone the deployment artefacts.
+git clone https://github.com/event4u-app/agent-config.git
+cd agent-config/packages/core/deploy
+
+# 2. Copy and edit the environment file.
+cp .env.example .env
+${EDITOR:-vi} .env
+# Required: ALLOWED_HOSTS=your.host:443
+# Required: POSTGRES_PASSWORD=<long random>
+
+# 3. Boot.
+docker compose up -d
+
+# 4. Verify.
+curl -fsS http://127.0.0.1:8787/api/v1/health | jq
+# {
+#   "status": "ok",
+#   "version": "x.y.z",
+#   "uptime_seconds": 12,
+#   "storage_mode": "filesystem",
+#   "session_backend": "memory",
+#   ...
+# }
+```
+
+## Environment contract
+
+The full table of variables, their defaults, and validation rules
+lives in [`env-vars.md`](env-vars.md). The minimum a production
+deployment must override:
+
+- `ALLOWED_HOSTS` — comma-separated host\:port allowlist for the
+  `Host` header. Non-loopback bind without this **refuses to boot**.
+- `POSTGRES_PASSWORD` — `agent-config` user's password.
+- `SESSION_SECRET` — 32-byte random; rotates user sessions when
+  changed.
+- 🚧 **Phase 2+** — `AUTH_MODE=oidc` + `OIDC_*` block.
+
+## Reverse-proxy template (Caddy)
+
+```caddyfile
+your.host {
+    reverse_proxy 127.0.0.1:8787
+}
+```
+
+The container ships plain HTTP; TLS is the proxy's job. See ADR-021
+for the rationale.
+
+## Healthcheck
+
+Every 10 s the Compose `agent-config` service hits
+`/api/v1/health` (1-rps rate limit means this lands inside the
+budget). A non-200 response for two consecutive cycles flips the
+service to `unhealthy` and the orchestrator restarts it.
+
+## What's not yet here
+
+| Capability | Phase | Status |
+|---|---|---|
+| SSO / OIDC login | 2 | 🚧 deferred (security-sensitive) |
+| Central org policy | 3 | 🚧 deferred |
+| Team context (shared rules / skills) | 4 | 🚧 deferred |
+| Linear / GitHub / Slack connectors | 5 | 🚧 deferred |
+
+Until those land, the deployed instance is a **single-tenant** AI OS
+shared via the reverse proxy. Lock the proxy down with HTTP basic
+auth or an IP allowlist for v1.
+
+## Troubleshooting
+
+- **Container exits with `BIND_HOST=0.0.0.0 requires ALLOWED_HOSTS`** —
+  add `ALLOWED_HOSTS` to `.env` and `docker compose up -d` again.
+- **`/api/v1/health` returns 503 with `storage_unavailable`** —
+  Postgres has not finished its first-boot init. Wait 15 s and retry.
+- **Wizard 404s on every route** — reverse proxy is stripping the
+  `Host` header; either preserve it (`proxy_set_header Host $host`)
+  or add the proxy hostname to `ALLOWED_HOSTS`.
+
+## Cross-references
+
+- ADR-021 — [deployment shape](../decisions/ADR-021-deployment-shape.md).
+- Env contract — [env-vars.md](env-vars.md).
+- 🚧 Policy guide — [policy-cookbook.md](policy-cookbook.md) (Phase 3).
+- 🚧 Connector setup — [connector-setup.md](connector-setup.md) (Phase 5).

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

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

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

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

package/docs/distribution/registries.md

@@ -0,0 +1,55 @@
+# 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.
+
+## 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 agent-tooling section, links to `README.md` hero anchor | ⬜ open | — |
+| 2 | `mcp.so` | <https://mcp.so/> | Submit via the directory form; same one-line shape | ⬜ open | — |
+| 3 | `mcpservers.org` | <https://mcpservers.org/> | Submit via the directory form; same one-line shape (verify URL current at submission time) | ⬜ open | — |
+
+## 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 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/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.