@event4u/agent-config 3.0.0 → 3.1.0

package/docs/deploy/connector-setup.md

@@ -0,0 +1,129 @@
+# Connector setup — internal AI OS
+
+> **Status**: 🚧 **skeleton**. Phase 5 of
+> [`road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md)
+> is **not yet implemented**. Phase 5 is contingent on Phase 2 (SSO)
+> and Phase 3 (central policy) shipping first.
+>
+> Open design questions live in
+> [`agents/tmp/council-question-connector-scope.md`](../../agents/tmp/council-question-connector-scope.md).
+
+## Audience
+
+An admin at a deploying organization who wants the AI OS to read
+tickets / PRs / Slack threads to ground its plans in the org's actual
+state of work.
+
+## Launch set (planned)
+
+| Connector | Read | Write | OAuth shape |
+|---|---|---|---|
+| Linear | v1 | v2 (gated) | per-org app install |
+| GitHub | v1 | v2 (gated) | GitHub App (per-org) |
+| Jira Cloud | v1 | v2 (gated) | per-user OAuth |
+| Slack | v1 | v2 (gated) | per-org app install |
+| Notion | v1 | — | per-user OAuth |
+
+**v1** = read-only · **v2** = write paths, each behind explicit org
+policy gate (see [`policy-cookbook.md`](policy-cookbook.md) →
+`connectors.write_enabled`).
+
+## OAuth contract (planned)
+
+Each connector lands one of two shapes:
+
+### Per-org app install
+
+Admin installs the app once at the org level. Every authenticated
+user inherits read access. Best for Linear / GitHub / Slack where
+the data is org-shared.
+
+### Per-user OAuth
+
+Each engineer authorizes their own account. The wizard surfaces a
+per-user "Connect Jira" / "Connect Notion" panel. Best where data is
+user-scoped or per-user permission boundaries matter.
+
+## Token storage (planned)
+
+OAuth tokens land in Postgres encrypted with the deployment's
+`SESSION_SECRET` derivative. Rotation happens automatically on
+refresh-token success. A `connector_token_rotated` audit event lands
+on each rotation.
+
+## Rate limits & cost (planned)
+
+| Connector | Cost model | Default cache TTL |
+|---|---|---|
+| Linear | Free, generous quota | 5 min for tickets, 1 min for comments |
+| GitHub | 5,000 / hr per token | 10 min for PRs, 2 min for reviews |
+| Jira Cloud | 10 / sec per app | 5 min |
+| Slack | Tier 2 (~20 / min) | 1 min for threads |
+| Notion | 3 / sec per integration | 10 min |
+
+The wizard surfaces per-connector cost in the admin panel; user-facing
+flows hide it.
+
+## Setup walkthrough (planned)
+
+### Linear
+
+```text
+1. Admin → Linear workspace settings → API → OAuth applications.
+2. Create app, set redirect URI to https://your.host/oauth/linear/callback.
+3. Copy client_id + client_secret into the AI OS admin panel.
+4. Authorize once at the org level.
+```
+
+### GitHub
+
+```text
+1. Admin → org settings → Developer settings → GitHub Apps → New.
+2. Permissions: read on Issues, Pull Requests, Contents, Metadata.
+3. Install on selected repos (or all).
+4. Copy app_id + private_key into the AI OS admin panel.
+```
+
+### Jira Cloud
+
+```text
+🚧 Per-user OAuth flow; each engineer connects on first use.
+```
+
+### Slack
+
+```text
+1. Admin → Slack app directory → Create app → from manifest.
+2. Manifest ships at packages/core/deploy/connectors/slack.manifest.yml
+   (does not yet exist).
+3. Install in workspace, copy bot token + signing secret.
+```
+
+### Notion
+
+```text
+🚧 Per-user OAuth flow.
+```
+
+## Hard-Floor caveats
+
+- OAuth token storage → **security-sensitive**, human-reviewed PR.
+- Write paths (v2) → **explicit org-policy gate** before merge.
+- Third-party data caching → cross-tenant isolation review before
+  merge (a stray cache-key collision exposes org A's data to org B).
+
+## What's not yet here
+
+- No connector code exists in the repo.
+- No OAuth callback routes are registered.
+- No admin panel for connector management.
+- No token-storage schema.
+
+All of the above land in Phase 5, contingent on Phases 2 + 3.
+
+## Cross-references
+
+- 🚧 Reserved ADR slot: `docs/decisions/ADR-025-connector-scope.md`.
+- Council question: [`agents/tmp/council-question-connector-scope.md`](../../agents/tmp/council-question-connector-scope.md).
+- Quickstart: [`quickstart.md`](quickstart.md).
+- Policy cookbook: [`policy-cookbook.md`](policy-cookbook.md).

package/docs/deploy/env-vars.md

@@ -0,0 +1,70 @@
+# Environment variable contract — `agent-config` deployment
+
+Phase 1 of [`road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md).
+Decision shape: [`ADR-021`](../decisions/ADR-021-deployment-shape.md).
+
+This file is the **single source of truth** for environment variables
+read by the deployed container. Every knob below is consumed by either
+the GUI server (TypeScript) or the embedded Python install supervisor.
+
+| Variable | Required | Default | Phase | Meaning |
+|---|---|---|---|---|
+| `BIND_HOST` | no | `127.0.0.1` | 1 | Bind address. Set to `0.0.0.0` for container deployments; non-loopback REQUIRES `ALLOWED_HOSTS`. |
+| `GUI_PORT` | no | `8787` | 1 | TCP port the wizard listens on. CLI override: `--port`. |
+| `ALLOWED_HOSTS` | when host ≠ loopback | derived | 1 | Comma-separated `host:port` allowlist for the Host-header gate. Reverse-proxy hostnames go here. |
+| `STORAGE_MODE` | no | `filesystem` | 1+ | `filesystem` (Phase 1) or `postgres` (Phase 2+). Audit log + memory backend. |
+| `SESSION_BACKEND` | no | `memory` | 1+ | `memory` (Phase 1) or `redis` (Phase 3+). Wizard session + per-user state. |
+| `AGENT_CONFIG_PROJECT_ROOT` | no | `/var/lib/agent-config/runtime` | 1 | Mountpoint the container treats as the consumer "project root". |
+| `AGENT_CONFIG_GUI_NO_OPEN` | no | `1` (in image) | 1 | Set to suppress the browser-launch attempt — required in headless containers. |
+| `AUTH_MODE` | no | `none` | 2 | `none` \| `oidc` \| `saml`. **Not yet read by the server** — placeholder for Phase 2. |
+| `OIDC_ISSUER_URL` | yes when `AUTH_MODE=oidc` | — | 2 | OIDC discovery URL. Not yet consumed. |
+| `OIDC_CLIENT_ID` | yes when `AUTH_MODE=oidc` | — | 2 | Not yet consumed. |
+| `OIDC_CLIENT_SECRET` | yes when `AUTH_MODE=oidc` | — | 2 | Not yet consumed. Read from secret manager only. |
+| `POLICY_PATH` | no | `/etc/event4u/policy.yaml` | 3 | Central org-policy YAML mount path. **Not yet read by the server** — placeholder for Phase 3. |
+| `DATABASE_URL` | yes when `STORAGE_MODE=postgres` | — | 2+ | Postgres connection string. Compose-default points at the bundled service. |
+| `REDIS_URL` | yes when `SESSION_BACKEND=redis` | — | 3+ | Redis connection string. Compose-default points at the bundled service. |
+
+## What ships honoring these vs not
+
+**Honored today (Phase 1):**
+
+- `BIND_HOST` — server respects `--host` flag and `BIND_HOST` env.
+- `GUI_PORT` / `--port` — server listens on this port.
+- `ALLOWED_HOSTS` — `Host:`-header allowlist for the GUI gate.
+- `STORAGE_MODE` / `SESSION_BACKEND` — surfaced in `/api/v1/health`
+  responses but **storage and session implementations still default
+  to filesystem and memory**. Setting them to `postgres` / `redis`
+  in Phase 1 has no effect on storage behavior (and the health
+  response will tell you so).
+- `AGENT_CONFIG_PROJECT_ROOT` — the container's runtime mount.
+- `AGENT_CONFIG_GUI_NO_OPEN` — auto-set to `1` in the shipped image
+  so the wizard does not try to `xdg-open` a browser from inside a
+  container.
+
+**Documented now, wired later:**
+
+- `AUTH_MODE` and its OIDC dependents — Phase 2.
+- `POLICY_PATH` — Phase 3.
+- `DATABASE_URL` / `REDIS_URL` — Phase 2 / Phase 3 respectively.
+
+## Security posture
+
+- **Secrets stay in env or a mounted secret manager.** Never bake
+  `OIDC_CLIENT_SECRET`, `DATABASE_URL` with a password, or
+  `POSTGRES_PASSWORD` into the image. Compose uses host-env or
+  `.env` files; production uses your secrets manager of choice.
+- **`BIND_HOST=0.0.0.0` without `ALLOWED_HOSTS`** — server refuses
+  to start. This is intentional: a non-loopback bind without a
+  Host-header allowlist is an open invitation for DNS rebinding.
+  See [`ADR-021`](../decisions/ADR-021-deployment-shape.md) § Security.
+- **`/api/v1/health`** is the only endpoint exempt from CSRF, but it
+  is rate-limited to 1 request per second per remote IP and exposes
+  no secrets.
+
+## Cross-references
+
+- Image + compose: [`packages/core/deploy/`](../../packages/core/deploy/)
+- ADR: [`ADR-021-deployment-shape.md`](../decisions/ADR-021-deployment-shape.md)
+- Operator quickstart: [`quickstart.md`](quickstart.md)
+- Policy cookbook (Phase 3 preview): [`policy-cookbook.md`](policy-cookbook.md)
+- Connector setup (Phase 5 preview): [`connector-setup.md`](connector-setup.md)

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