@event4u/agent-config 1.39.0 → 1.41.0

package/docs/setup/mcp-client-config.md

@@ -1,8 +1,17 @@
-# MCP Client Config — Remote agent-config
+# MCP Client Config — Self-hosted agent-config Worker
 
-Connect any MCP-capable client to the hosted `agent-config-mcp` Worker
-at `https://agent-config-mcp.event4u.workers.dev`. Read-only,
-identity-stable per release, no auth.
+Connect any MCP-capable client to your own `agent-config-mcp` Cloudflare
+Worker. Read-only, identity-stable per release. Optional Bearer-token
+auth — see [§ Bearer auth](#bearer-auth) below.
+
+> **No public endpoint.** This package ships the Worker source under
+> `workers/mcp/`, but does **not** operate a shared hosted MCP server.
+> Deploy your own per [`mcp-cloud-setup.md`](mcp-cloud-setup.md) — your
+> URL will be `https://agent-config-mcp.<your-account>.workers.dev`
+> (or a custom domain you wire up in Step 7).
+>
+> In every snippet below, **replace `https://your-worker.workers.dev`
+> with your actual deployment URL**.
 
 For URL shapes (latest vs. pinned `/v<X.Y.Z>`) see
 [`mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md). For operator
@@ -26,14 +35,29 @@ look for MCP server config inside `.agent-settings.yml`.
 | MCP client config (this page) | client-specific path per section above | the MCP client at startup | which MCP servers to talk to (name + URL / command) |
 | `.agent-settings.yml` | consumer project root (`<repo>/.agent-settings.yml`) | the agent at runtime (Claude / Cursor / …) | per-developer preferences: `name`, `ide`, `cost_profile`, `personal.autonomy`, `pipelines.skill_improvement`, `caveman.speak_scope`, … |
 
-The hosted MCP is **stateless** and **project-agnostic** — it serves
-the same skill / rule / command catalog to every client. Personalization
+The Worker is **stateless** and **project-agnostic** — it serves the
+same skill / rule / command catalog to every client. Personalization
 happens agent-side after the MCP delivers its content blob; the Worker
 itself does not read `.agent-settings.yml`.
 
 First-time setup of `.agent-settings.yml` runs through `/onboard`;
 template drift is handled by `/sync-agent-settings`.
 
+## Bearer auth
+
+If you set the `MCP-Token` secret on your Worker (via
+`task mcp:cloud:secret-put`), every POST request must carry the header
+`Authorization: Bearer <token>`. The `GET /` liveness probe stays
+unauthenticated.
+
+Add the header to each client below by appending the per-client header
+snippet shown in its section. Treat the token like any other secret —
+keep it out of repo files and shared dotfiles; prefer an env var
+(`MCP_TOKEN`) sourced from a password manager or shell init.
+
+If your Worker has **no** `MCP-Token` secret set, skip the header
+snippets — every POST is accepted as-is.
+
 ## Claude Desktop
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
@@ -44,7 +68,24 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
   "mcpServers": {
     "agent-config": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+      "args": ["-y", "mcp-remote", "https://your-worker.workers.dev"]
+    }
+  }
+}
+```
+
+With Bearer auth, add `--header`:
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-remote", "https://your-worker.workers.dev",
+        "--header", "Authorization: Bearer ${MCP_TOKEN}"
+      ],
+      "env": { "MCP_TOKEN": "paste-token-here" }
     }
   }
 }
@@ -60,7 +101,14 @@ Connector** with the URL directly — no `mcp-remote` wrapper needed.
 Native HTTP transport — one command:
 
 ```bash
-claude mcp add --transport http agent-config https://agent-config-mcp.event4u.workers.dev
+claude mcp add --transport http agent-config https://your-worker.workers.dev
+```
+
+With Bearer auth:
+
+```bash
+
+
 ```
 
 Verify:
@@ -78,12 +126,14 @@ claude mcp list
 {
   "mcpServers": {
     "agent-config": {
-      "url": "https://agent-config-mcp.event4u.workers.dev"
+      "url": "https://your-worker.workers.dev",
+      "headers": { "Authorization": "Bearer paste-token-here" }
     }
   }
 }
 ```
 
+(Omit the `headers` block if your Worker has no `MCP-Token` secret.)
 Reload Cursor (`Cmd+Shift+P → Reload Window`).
 
 ## Zed
@@ -96,12 +146,17 @@ Reload Cursor (`Cmd+Shift+P → Reload Window`).
     "agent-config": {
       "source": "custom",
       "command": "npx",
-      "args": ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+      "args": [
+        "-y", "mcp-remote", "https://your-worker.workers.dev",
+        "--header", "Authorization: Bearer ${MCP_TOKEN}"
+      ],
+      "env": { "MCP_TOKEN": "paste-token-here" }
     }
   }
 }
 ```
 
+Drop the `--header` / `env` pair when the Worker has no token set.
 Zed has no native remote-MCP transport yet, so the `mcp-remote`
 bridge is required.
 
@@ -113,19 +168,28 @@ bridge is required.
 mcpServers:
   - name: agent-config
     command: npx
-    args: ["-y", "mcp-remote", "https://agent-config-mcp.event4u.workers.dev"]
+    args:
+      - "-y"
+      - mcp-remote
+      - https://your-worker.workers.dev
+      - --header
+      - "Authorization: Bearer ${MCP_TOKEN}"
+    env:
+      MCP_TOKEN: paste-token-here
 ```
 
+Drop the `--header` / `env` keys when the Worker has no token set.
+
 ## Verify
 
 After reload, every client should:
 
 1. List `agent-config` under connectors / tools with a release-key
    matching the live deploy. Probe the endpoint to see the current
-   release:
+   release (the `GET /` liveness probe is always unauthenticated):
 
    ```bash
-   curl https://agent-config-mcp.event4u.workers.dev
+   curl https://your-worker.workers.dev
    # → { "ok": true, "release_key": "v…", "signature": "…", … }
    ```
 
@@ -134,6 +198,23 @@ After reload, every client should:
 3. Expose rule + guideline + context resources under `rule://…`,
    `guideline://…`, `context://…`.
 
+With Bearer auth, a wrong/missing token returns HTTP 401 with body
+`{"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"Unauthorized"}}` —
+quick way to confirm enforcement:
+
+```bash
+curl -X POST -H "content-type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' \
+  https://your-worker.workers.dev
+# → 401 Unauthorized
+
+curl -X POST -H "content-type: application/json" \
+  -H "Authorization: Bearer $MCP_TOKEN" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}' \
+  https://your-worker.workers.dev
+# → 200 { "jsonrpc":"2.0","id":1,"result":{} }
+```
+
 If the client shows the connector but no prompts / resources,
 re-probe the URL — a 5xx from the Worker indicates the deploy is
 mid-roll, retry after a minute.

package/docs/setup/mcp-cloud-setup.md

@@ -15,6 +15,7 @@ machine.
 ```sh
 task mcp:cloud:login        # one-time, opens browser
 task mcp:cloud:setup        # check → r2-create → r2-verify → whoami
+task mcp:cloud:secret-put   # optional but recommended — sets MCP-Token (Bearer auth)
 # Copy account id from output → GitHub Secrets (see § GitHub Secrets)
 # Create scoped API token (see § API Token) → GitHub Secrets
 # Done. First `release: published` triggers the deploy.
@@ -114,7 +115,36 @@ Green smoke step → `latest.txt` repoints → release is live on
 `*.workers.dev`. A red smoke step leaves `latest.txt` on the previous
 release.
 
-## Step 7 — DNS (optional, Phase 5.2)
+## Step 7 — Bearer auth (recommended)
+
+Without auth, anyone who knows your `*.workers.dev` URL can read the
+catalog. The Worker checks for an `MCP-Token` secret and, when set,
+gates every POST behind `Authorization: Bearer <token>`. The `GET /`
+liveness probe stays open so health checks keep working.
+
+Generate a token (any high-entropy random string — `openssl rand -hex 32`
+or your password manager) and set it on the Worker:
+
+```sh
+task mcp:cloud:secret-put
+# wrangler prompts for the value interactively (stdin) — never passed
+# via argv, never written to shell history.
+```
+
+This wraps `npx wrangler secret put MCP-Token --name agent-config-mcp`.
+The secret is encrypted in Cloudflare and injected as `env["MCP-Token"]`
+at request time; the source repo never sees the value.
+
+Once set, every MCP client config needs the header — per-client
+snippets (Claude Desktop, Claude Code, Cursor, Zed, Continue) live in
+[`mcp-client-config.md`](mcp-client-config.md) § Bearer auth.
+
+Rotate by re-running `task mcp:cloud:secret-put` with a fresh value;
+the new secret takes effect on the next request (no redeploy needed).
+To remove auth entirely, run
+`npx wrangler secret delete MCP-Token --name agent-config-mcp`.
+
+## Step 8 — DNS (optional, Phase 5.2)
 
 Custom domain `mcp.<your-domain>` setup lives in
 [`docs/setup/mcp-cloud-endpoints.md`](mcp-cloud-endpoints.md) § DNS
@@ -141,6 +171,7 @@ setup. Until cutover, the Worker serves on the free
 | `task mcp:cloud:r2-create` | Create R2 bucket (idempotent) |
 | `task mcp:cloud:r2-verify` | Verify R2 bucket exists |
 | `task mcp:cloud:setup` | Full chain — check → r2 → whoami |
+| `task mcp:cloud:secret-put` | Set the `MCP-Token` Bearer-auth secret (interactive) |
 | `task mcp:cloud:dev` | Local `wrangler dev` on :8787 |
 | `task mcp:cloud:deploy-dispatch TAG=v…` | Manual workflow trigger |
 

package/docs/setup/per-ide/aider.md

@@ -0,0 +1,48 @@
+# Aider Setup
+
+Aider reads `AGENTS.md` (and the legacy `CONVENTIONS.md` if present)
+from the repo root for project conventions.
+
+## Prerequisites
+
+- Aider installed: <https://aider.chat>.
+- Node.js ≥ 18 (for the install entrypoints).
+
+## Install
+
+```bash
+npx @event4u/create-agent-config init --tools=aider
+```
+
+Populates:
+
+- `AGENTS.md`             — agent self-orientation (Aider auto-loads)
+- `.agent-settings.yml`   — per-project knobs
+
+Aider's chat will read `AGENTS.md` on every session start. Add it to
+the chat explicitly if Aider doesn't pick it up:
+
+```bash
+aider AGENTS.md
+```
+
+## Verification
+
+```bash
+test -f AGENTS.md
+```
+
+In Aider: type `/tokens` — `AGENTS.md` should appear in the loaded
+files list.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `AGENTS.md` not auto-loaded | `aider --read AGENTS.md` or `/read AGENTS.md`. |
+| Conventions ignored | Aider reads `CONVENTIONS.md` legacy too — check `--auto-commits` flag. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/claude-code.md

@@ -0,0 +1,108 @@
+# Claude Code Setup
+
+Claude Code is the canonical agent surface for `event4u/agent-config`. It
+reads from `.claude/skills/`, `.claude/commands/`, `CLAUDE.md`,
+`.claude/hooks/`, and project-level MCP servers. Everything in this repo
+projects to those paths during install.
+
+## Prerequisites
+
+- Claude Code installed (CLI or VS Code extension): <https://claude.com/code>.
+- Node.js ≥ 18 (for the `npx` entrypoints).
+- Git working tree (the package is repository-aware).
+
+## Project install (recommended)
+
+```bash
+# Inside an existing repo:
+npx @event4u/create-agent-config init --tools=claude-code
+
+# Or with the curl entrypoint:
+curl -sSL https://raw.githubusercontent.com/event4u-app/agent-config/main/setup.sh \
+  | bash -s -- --tools=claude-code
+```
+
+Either form populates:
+
+- `.claude/skills/`         — symlinks into `.agent-src/skills/`
+- `.claude/commands/`       — symlinks into `.agent-src/commands/`
+- `CLAUDE.md`               — agent root pointer (auto-loaded by Claude Code)
+- `.agent-settings.yml`     — your per-project knobs (kept out of git)
+
+## Global install (cross-project skills)
+
+```bash
+npx @event4u/agent-config global --tools=claude-code
+```
+
+Seeds `~/.claude/skills/` with the curated top-N skills from
+[`templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml).
+Available across every project on the machine; project-level files
+always take precedence.
+
+Uninstall:
+
+```bash
+npx @event4u/agent-config global --uninstall
+```
+
+## Plugin marketplace (Claude Code 2026+)
+
+Claude Code 2026 supports plugin marketplaces via
+`.claude-plugin/marketplace.json`. The package ships one — once
+listed at the Anthropic marketplace (Phase 7 / S34) you can also:
+
+```bash
+claude plugin install event4u/agent-config
+```
+
+Today the npm/curl entrypoints above are the supported install path.
+
+## CLAUDE.md
+
+Auto-loaded by Claude Code from the repo root. The package's `CLAUDE.md`
+points to `AGENTS.md` (single source of truth for all agent surfaces);
+edit `AGENTS.md`, never `CLAUDE.md`.
+
+## Hooks
+
+Claude Code reads `.claude/hooks/` for pre/post tool hooks. The package
+ships a memory-extraction hook (Phase 7 of `road-to-mcp-full-coverage`).
+Local overrides go in `agents/overrides/.claude/hooks/`.
+
+## Skills you'll use most
+
+- `/work "<prompt>"` — refine → plan → implement → verify → report loop.
+- `/commit` — Conventional-Commit splitter with confirmation gate.
+- `/create-pr` — opens a structured PR from the current branch.
+- `/review-changes` — five-judge self-review before requesting human review.
+- `/agent-handoff` — produces a fresh-chat continuation summary.
+
+Full list: `ls .claude/skills/`.
+
+## Verification
+
+```bash
+ls -la .claude/skills/        # should symlink into .agent-src/skills/
+ls -la CLAUDE.md              # exists, points to AGENTS.md
+test -f .agent-settings.yml   # per-project settings rendered
+```
+
+In Claude Code itself: type `/` — the slash menu should list `work`,
+`commit`, `create-pr`, etc.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `/` menu empty | `ls .claude/skills/` — re-run installer if empty. |
+| Skills look stale after `git pull` | `task sync && task generate-tools`. |
+| Hook never fires | `claude --debug` and inspect hook output. |
+| Memory MCP missing | See `road-to-mcp-full-coverage` — Phase 3 ships read-only tools. |
+
+## Cross-references
+
+- [`docs/installation.md`](../../installation.md) — install matrix index.
+- [`docs/setup/per-ide/claude-desktop.md`](claude-desktop.md) — Desktop +
+  Cowork share the same `~/.claude/skills/` path; install once, both surfaces benefit.
+- [`AGENTS.md`](../../../AGENTS.md) — package self-orientation.

package/docs/setup/per-ide/claude-desktop.md

@@ -0,0 +1,173 @@
+# Claude Desktop — agent-config setup
+
+The fastest path to running our skills, rules, and (optionally) the MCP
+server inside Claude Desktop. macOS / Windows / Linux. ~5 minutes.
+
+> **TL;DR** — install the package globally with `--global` so the
+> kernel rules and the curated top-N skills land in `~/.claude/`,
+> then restart Claude Desktop. The slash-command menu picks them up
+> automatically.
+
+## Prerequisites
+
+- Claude Desktop installed (free or paid plan — same install path).
+- Node ≥ 18 *or* a clone of the `event4u/agent-config` repo
+  (either route can run `--global`).
+- 5 minutes.
+
+## Step 1 — global install
+
+Pick whichever entrypoint matches your environment. Both seed the same
+files under `~/.claude/`.
+
+```bash
+# Node — no clone needed.
+npx @event4u/create-agent-config --global --tools=claude-code
+
+# Or via curl (no Node).
+curl -fsSL https://raw.githubusercontent.com/event4u/agent-config/main/setup.sh \
+  | bash -s -- --global --tools=claude-code
+
+# Or from a local clone.
+bash scripts/install --global --tools=claude-code
+```
+
+> `--tools=claude-code` covers both Claude Code **and** Claude
+> Desktop — the two surfaces share `~/.claude/`. Pass
+> `--tools=claude-code,cursor,windsurf` if you want Cursor / Windsurf
+> globally seeded in the same run.
+
+After the install you'll have:
+
+```
+~/.claude/
+├── rules/event4u/      # 9 kernel rules (Iron-Law set)
+└── skills/event4u/     # 15 curated top-N skills
+```
+
+Curation lives in
+[`templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml).
+Edit and re-run `--global` to grow or shrink the set.
+
+## Step 2 — verify
+
+1. Restart Claude Desktop (full quit, not just window close).
+2. Open a new conversation.
+3. Type `/` — the curated skills (`/work`, `/commit`, `/create-pr`,
+   `/quality-fix`, `/review-changes`, `/agent-handoff`,
+   `/project-analyze`, …) appear in the slash-command menu.
+4. Open Settings → Connectors. The kernel rules count appears under
+   "rules loaded".
+
+If the menu is empty:
+
+- Check `ls ~/.claude/skills/event4u/` — should list 15 directories.
+- Quit Claude Desktop (`Cmd+Q` on macOS, **not** just close the
+  window — the menubar process keeps the old skills cached).
+- Re-open and try `/` again.
+
+## Step 3 — optional MCP server
+
+Claude Desktop also speaks MCP. Wiring up your own self-hosted
+`agent-config-mcp` Cloudflare Worker exposes the **full** skill / rule /
+command catalog (~480 items) on demand, on top of the 15 you installed
+in Step 1.
+
+Deploy the Worker first per [`../mcp-cloud-setup.md`](../mcp-cloud-setup.md) — your
+URL will be `https://agent-config-mcp.<your-account>.workers.dev`
+(or a custom domain you wire up in Step 7). Replace
+`https://your-worker.workers.dev` below with that URL.
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows /
+Linux is `~/.config/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://your-worker.workers.dev"]
+    }
+  }
+}
+```
+
+If you set the `MCP-Token` secret on the Worker (recommended — see
+[`../mcp-cloud-setup.md`](../mcp-cloud-setup.md) § Bearer auth), add the header:
+
+```json
+{
+  "mcpServers": {
+    "agent-config": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-remote", "https://your-worker.workers.dev",
+        "--header", "Authorization: Bearer ${MCP_TOKEN}"
+      ],
+      "env": { "MCP_TOKEN": "paste-token-here" }
+    }
+  }
+}
+```
+
+A pre-wired template ships at
+[`templates/claude_desktop_config.json.template`](../../../templates/claude_desktop_config.json.template) —
+copy, swap the placeholder URL for your deploy, and uncomment the MCP
+block.
+
+Restart Claude Desktop. The 🔌 icon shows the connector under
+**Settings → Connectors**. Full transport details (mcp-remote vs.
+native HTTP) and per-client Bearer-auth snippets live in
+[`../mcp-client-config.md`](../mcp-client-config.md).
+
+## Claude Desktop ↔ Claude Code config sharing
+
+Both surfaces read **the same `~/.claude/` directory**. Anything you
+install for one is automatically available in the other:
+
+| File / dir                       | Shared by Desktop & Code? |
+| -------------------------------- | ------------------------- |
+| `~/.claude/CLAUDE.md`            | yes — global system prompt |
+| `~/.claude/rules/event4u/`       | yes — installed by `--global` |
+| `~/.claude/skills/event4u/`      | yes — installed by `--global` |
+| `~/.claude/commands/`            | yes — slash commands      |
+| `~/.claude/hooks/`               | yes — lifecycle hooks     |
+| `claude_desktop_config.json`     | Desktop only (MCP)        |
+| `~/.claude.json` (CLI config)    | Code only                 |
+
+Translation: run `--global` once, both clients pick the files up.
+Cross-link to [`claude-code.md`](claude-code.md) for the CLI-side
+view.
+
+## Claude Cowork
+
+Claude Cowork (paid plans only — Pro / Max / Team) **shares the
+Desktop config**. Once Step 1 + Step 3 are done in Desktop:
+
+- Skills and rules under `~/.claude/` are picked up automatically.
+- MCP servers under `claude_desktop_config.json` are available
+  inside Cowork sessions without a separate install.
+- Cowork-specific limit (per Anthropic docs): MCP tools that write to
+  the local filesystem are sandboxed — read-only tools (the entire
+  `agent-config-mcp` Worker surface) work fine.
+
+If a feature works in Desktop but not in Cowork, check that you're on
+a paid plan — Cowork is gated, Desktop's free tier has the full
+client-side feature set.
+
+## Uninstall
+
+```bash
+bash scripts/install --global --uninstall --tools=claude-code
+```
+
+Removes only `~/.claude/{rules,skills}/event4u/`. Anything you added
+under sibling paths (custom rules, your own slash commands) stays.
+
+## See also
+
+- Project-local install — [`../../installation.md`](../../installation.md)
+- Global install reference — [`../../installation.md#global-user-level-install---global`](../../installation.md#global-user-level-install---global)
+- MCP client transports — [`../mcp-client-config.md`](../mcp-client-config.md)
+- Curation manifest — [`../../../templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml)

package/docs/setup/per-ide/cline.md

@@ -0,0 +1,43 @@
+# Cline Setup
+
+Cline (formerly Claude Dev) reads `.clinerules` (single-file aggregate)
+and `AGENTS.md`.
+
+## Prerequisites
+
+- Cline VS Code extension: <https://github.com/cline/cline>.
+- Node.js ≥ 18.
+
+## Install
+
+```bash
+npx @event4u/create-agent-config init --tools=cline
+```
+
+Populates:
+
+- `.clinerules`           — single-file aggregate (rules)
+- `AGENTS.md`             — agent self-orientation
+- `.agent-settings.yml`   — per-project knobs
+
+## Verification
+
+```bash
+test -f .clinerules
+test -f AGENTS.md
+```
+
+In VS Code: open the Cline panel — it should pick up the rules
+automatically. Run `/help` in the chat to verify rule loading.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Rules not picked up | Reload VS Code window after `task generate-tools`. |
+| `.clinerules` missing | Re-run `npx @event4u/create-agent-config init --tools=cline`. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/setup/per-ide/codex.md

@@ -0,0 +1,46 @@
+# OpenAI Codex CLI Setup
+
+OpenAI's Codex CLI (the `codex` command) reads `AGENTS.md` from the
+repo root for project context.
+
+## Prerequisites
+
+- Codex CLI installed: <https://github.com/openai/codex>.
+- Node.js ≥ 18 (for the install entrypoints).
+
+## Install
+
+```bash
+npx @event4u/create-agent-config init --tools=codex
+```
+
+Populates:
+
+- `AGENTS.md`             — agent self-orientation (Codex auto-loads)
+- `.agent-settings.yml`   — per-project knobs
+
+Codex CLI reads `AGENTS.md` automatically when invoked from the repo
+root. No additional configuration needed.
+
+## Verification
+
+```bash
+test -f AGENTS.md
+codex --help            # confirm CLI installed
+```
+
+In a Codex CLI session, the loaded `AGENTS.md` content informs every
+turn — verify by asking *"what is this repo?"* and confirming the
+answer matches `AGENTS.md`'s emergency-triage block.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Codex ignores `AGENTS.md` | Run from repo root, not a subdirectory. |
+| Out-of-date context | `codex` re-reads on each session start — quit and restart. |
+
+## Cross-references
+
+- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
+- [`docs/installation.md`](../../installation.md) — install matrix index.