agentirc-cli 9.10.0__tar.gz → 9.11.0__tar.gz

agentirc_cli-9.11.0/.github/workflows/tests.yml

@@ -0,0 +1,238 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Portability lint (full tree)
+        run: bash .claude/skills/cicd/scripts/portability-lint.sh --all
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Bootstrap status check
+        id: bootstrap
+        run: |
+          if [ -f pyproject.toml ]; then
+            echo "ready=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::Pre-bootstrap (no pyproject.toml) — pytest skipped."
+          fi
+
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+        if: steps.bootstrap.outputs.ready == 'true'
+
+      - name: Install Python
+        if: steps.bootstrap.outputs.ready == 'true'
+        run: uv python install 3.12
+
+      - name: Sync deps (with dev extras)
+        if: steps.bootstrap.outputs.ready == 'true'
+        run: uv sync --extra dev
+
+      - name: Run tests
+        if: steps.bootstrap.outputs.ready == 'true'
+        env:
+          # Console scripts only land on PATH after `uv sync` activates the
+          # project venv; this guard surfaces the path issue clearly if it
+          # ever regresses.
+          UV_PROJECT_ENVIRONMENT: .venv
+        run: uv run pytest -n auto -v
+
+  version-check:
+    needs: lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Bootstrap status check
+        id: bootstrap
+        run: |
+          if [ -f pyproject.toml ]; then
+            echo "ready=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::Pre-bootstrap (no pyproject.toml) — version check skipped."
+          fi
+
+      - run: git fetch origin main
+        if: steps.bootstrap.outputs.ready == 'true'
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        if: steps.bootstrap.outputs.ready == 'true'
+        with:
+          python-version: "3.12"
+
+      - name: Check if code changed
+        id: changes
+        if: steps.bootstrap.outputs.ready == 'true'
+        run: |
+          CODE_CHANGED=$(git diff --name-only origin/main...HEAD -- 'agentirc/' 'pyproject.toml' 'tests/' | head -1)
+          if [ -z "$CODE_CHANGED" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Check version bump
+        if: steps.bootstrap.outputs.ready == 'true' && steps.changes.outputs.skip != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PR_VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if ! git cat-file -e origin/main:pyproject.toml 2>/dev/null; then
+            echo "::notice::main lacks pyproject.toml (first-time bootstrap PR) — skipping version-bump check."
+            exit 0
+          fi
+          MAIN_VERSION=$(git show origin/main:pyproject.toml | python3 -c "import sys,tomllib; print(tomllib.loads(sys.stdin.read())['project']['version'])")
+
+          if [ "$PR_VERSION" = "$MAIN_VERSION" ]; then
+            BODY="⚠️ **Version not bumped** — \`pyproject.toml\` still has \`$PR_VERSION\` (same as main). Run \`/version-bump patch\` (or minor/major) before merging.
+
+          <!-- version-check -->"
+
+            EXISTING=$(gh api repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments \
+              --jq '.[] | select(.body | contains("<!-- version-check -->")) | .id' | head -1)
+
+            if [ -n "$EXISTING" ]; then
+              gh api repos/${{ github.repository }}/issues/comments/$EXISTING -X PATCH -f body="$BODY" > /dev/null
+            else
+              gh pr comment ${{ github.event.pull_request.number }} --body "$BODY" || true
+            fi
+
+            echo "::error::Version $PR_VERSION matches main. Bump before merging."
+            exit 1
+          fi
+
+  # Guards for the agent-accessibility release (task t14). GitHub-hosted
+  # runners never have a `../culture` checkout, so the "clean venv, no
+  # culture on the machine" guarantee already holds by construction here;
+  # the explicit check below turns that ambient fact into a loud failure
+  # if it's ever violated (e.g. a self-hosted runner, or a future workflow
+  # change that checks out a sibling repo).
+  # Pre-bootstrap gating is handled per-step via `steps.bootstrap.outputs.ready`
+  # below (same pattern as `test`/`version-check`), NOT a job-level
+  # `if: hashFiles(...)`. A job-level `hashFiles()` fails to evaluate for push
+  # events that don't match the branch filter, which GitHub reports as a
+  # spurious "workflow file issue" run failure on feature-branch pushes.
+  agent-guards:
+    needs: lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Bootstrap status check
+        id: bootstrap
+        run: |
+          if [ -f pyproject.toml ]; then
+            echo "ready=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::Pre-bootstrap (no pyproject.toml) — agent guards skipped."
+          fi
+
+      - uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+        if: steps.bootstrap.outputs.ready == 'true'
+
+      - name: Install Python
+        if: steps.bootstrap.outputs.ready == 'true'
+        run: uv python install 3.12
+
+      - name: Sync deps (fresh venv, with dev extras)
+        if: steps.bootstrap.outputs.ready == 'true'
+        run: uv sync --extra dev
+
+      - name: Assert no ../culture checkout on this runner
+        if: steps.bootstrap.outputs.ready == 'true'
+        run: |
+          if [ -d ../culture ]; then
+            echo "::error::../culture checkout found next to agentirc — this job exists to guarantee agentirc's test suite (and this walkthrough) run clean, with no culture checkout on the machine. Remove the sibling checkout or move it outside the runner's workspace."
+            exit 1
+          fi
+          echo "No ../culture checkout present — clean-venv invariant holds."
+
+      - name: No 'import culture' under agentirc/ or tests/
+        if: steps.bootstrap.outputs.ready == 'true'
+        run: |
+          if git grep -nE '^(from|import) culture' -- agentirc/ tests/; then
+            echo "::error::Found a top-level 'import culture' / 'from culture import ...' under agentirc/ or tests/ — agentirc must have no import-time dependency on culture (see CLAUDE.md's 'Hard invariants')."
+            exit 1
+          fi
+          echo "No 'import culture' found under agentirc/ or tests/."
+
+      - name: No agent/backend SDKs declared in pyproject.toml
+        if: steps.bootstrap.outputs.ready == 'true'
+        run: |
+          python3 - <<'PYEOF'
+          import sys
+          import tomllib
+
+          # agentirc's dependency boundary (CLAUDE.md "Hard invariants"):
+          # no backend/agent SDKs, ever, as a real dependency. Checked
+          # against declared dependency *names* (project.dependencies +
+          # every project.optional-dependencies group), not the raw file
+          # text — pyproject.toml's own [tool.citation] notes legitimately
+          # *mention* several of these names in prose explaining why
+          # they're forbidden, which a plain grep would misfire on.
+          FORBIDDEN = {
+              "claude-agent-sdk",
+              "anthropic",
+              "agex-cli",
+              "afi-cli",
+              "github-copilot-sdk",
+              "openai",
+          }
+
+          with open("pyproject.toml", "rb") as f:
+              data = tomllib.load(f)
+
+          project = data.get("project", {})
+          deps = list(project.get("dependencies", []))
+          for group_deps in project.get("optional-dependencies", {}).values():
+              deps.extend(group_deps)
+
+          def dep_name(spec: str) -> str:
+              name = spec.split(";", 1)[0]  # drop environment markers
+              for sep in (">=", "<=", "==", "~=", "!=", ">", "<", "[", " "):
+                  name = name.split(sep, 1)[0]
+              return name.strip().lower()
+
+          hits = [d for d in deps if dep_name(d) in FORBIDDEN]
+          if hits:
+              for h in hits:
+                  print(f"::error::Forbidden agent/backend SDK dependency in pyproject.toml: {h!r}")
+              sys.exit(1)
+
+          print("No forbidden agent/backend SDK dependencies found in pyproject.toml.")
+          PYEOF
+
+      - name: Agent walkthrough smoke (by marker)
+        if: steps.bootstrap.outputs.ready == 'true'
+        env:
+          UV_PROJECT_ENVIRONMENT: .venv
+        run: uv run pytest -m walkthrough -v

{agentirc_cli-9.10.0 → agentirc_cli-9.11.0}/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [9.11.0] - 2026-07-02
+
+The agent-accessibility release. Spec:
+`docs/specs/2026-07-01-agentirc-ships-an-agent-accessibility-release-ai-a.md`;
+plan: `docs/plans/2026-07-01-…` (16 tasks, built wave-by-wave by a
+fanned-out workforce with TDD-gated merges). Everything below is additive:
+clients that worked against 9.7.0 work unchanged, and non-`message-tags`
+clients see a byte-identical wire format (locked by golden tests).
+
+### Added
+
+- **Agent CLI client verbs** — `agentirc join/send/read/watch` drive a
+  running daemon over real TCP from a shell (built on the new public
+  transport; no culture checkout, no Python). `read`/`watch` accept a bare
+  nick for DM pairs; `read --since <cursor>` resumes without count-guessing
+  and prints the next cursor; `--json` emits one object per line with
+  `msgid`. `agentirc status --json` / `version --json` for orchestrators.
+- **Public reconnecting transport** — `agentirc.agent_client.AgentClient` +
+  `IncomingMessage` (semver-tracked): auto-reconnect with exponential
+  backoff, nick re-registration, channel re-join, `messages()` spanning
+  reconnects, `send_raw()`/`raw_lines()` escape hatch.
+- **Message structure** — server stamps `msgid` (fan-out-stable) and `time`
+  (IRCv3 server-time) tags on PRIVMSG delivery and `agentirc.io/thread` on
+  thread messages, gated on the `message-tags` cap.
+- **Stable error tokens** — every rooms/threads/history error reply carries
+  a named token via the `agentirc.io/error` tag (`ERROR_TOKEN_*`,
+  `ERROR_TOKENS_VERSION = 1` in `agentirc.protocol`); prose replies are
+  byte-unchanged for non-tag clients.
+- **HISTORY SINCE** — opaque-cursor pagination (deterministic, gap- and
+  duplicate-free across retention prunes) on both backends; replay lines
+  carry `msgid`/`time` tags; `HISTORYEND` returns the next cursor.
+- **DM history** — DMs to connected recipients are stored under a canonical
+  pair key, queryable only by the two participants (`HISTORY <nick>`), same
+  retention as channels. Offline DMs stay undelivered and unstored by
+  design; `agentirc send <nick>` now exits `1` on `ERR_NOSUCHNICK`.
+- **Client-facing BACKFILL** — the overflow-recovery path extension-api.md
+  had promised since 9.5.0 is now real (`BACKFILL <channel-or-*>
+  <cursor-or-*> [limit]`, bot-cap gated, EVENT-shaped replay, `BACKFILLEND`
+  terminator, DM history never replayed); a docs-vs-implementation test
+  keeps the doc honest.
+- **VERBS discovery** — versioned, machine-parseable inventory of the verbs
+  the running server accepts (derived live from the dispatch surface),
+  negotiable caps, and the error-token vocabulary version.
+- **Server liveness** — periodic server→client PING with a dead-connection
+  reaper (`ping_interval`/`pong_timeout` in `ServerConfig`/YAML, defaults
+  60/120 s, `0` disables); activity counts as liveness, so busy clients
+  ignoring PING are never dropped.
+- **Long-message handling** — outbound relay splits over-budget messages at
+  the 512-byte line limit (codepoint-safe, order-preserving, each chunk its
+  own msgid/history entry); over-limit inbound lines get an explicit
+  `line-too-long` error naming the limit instead of the old silent
+  truncation.
+- **Docs** — `docs/agent-walkthrough.md` (end-to-end, runnable as written,
+  with a five-dimension feature-traceability table), agent-facing updates
+  to `api-stability.md` (7th public module), `extension-api.md`, `cli.md`,
+  README. Gap-verification and release-audit notes under `docs/specs/`.
+- **CI** — `agent-guards` job: fresh-venv suite + walkthrough smoke with no
+  culture checkout, culture-import grep, backend-SDK dependency check
+  (tomllib-scoped), on-disk-path lock tests.
+
 ## [9.10.0] - 2026-06-24
 
 ### Added

{agentirc_cli-9.10.0 → agentirc_cli-9.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 9.10.0
+Version: 9.11.0
 Summary: Agent-friendly IRCd: server core for AI agent meshes
 Project-URL: Homepage, https://github.com/agentculture/agentirc
 Project-URL: Issues, https://github.com/agentculture/agentirc/issues
@@ -32,6 +32,7 @@ Requires-Dist: flake8; extra == 'dev'
 Requires-Dist: isort; extra == 'dev'
 Requires-Dist: pylint; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
 Requires-Dist: pytest-xdist>=3; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -143,9 +144,31 @@ See [`docs/cli.md`](docs/cli.md) for the full verb reference and
 [`docs/deployment.md`](docs/deployment.md) for systemd, containers, and
 multi-host federation.
 
+## Agent CLI (since 9.11.0)
+
+For a shell agent that just wants to talk to a running server — no Python,
+no raw IRC — four verbs cover join/send/read/watch:
+
+```bash
+agentirc join '#general' --nick myagent-bot
+agentirc send '#general' 'hello' --nick myagent-bot
+agentirc read '#general' --since '*' --json      # resume with the printed next-cursor
+agentirc watch '#general' --json                  # stream live messages until Ctrl-C
+```
+
+`read`/`send` also accept a bare nick instead of `#channel` for direct
+messages. Messages carry a stable `msgid` and IRCv3 server-time in
+`--json` mode. [`docs/agent-walkthrough.md`](docs/agent-walkthrough.md) is
+a full, copy-pasteable, verified-as-written walkthrough — install, start a
+server, join, send, read, disconnect-and-catch-up, watch, DMs, status,
+stop — plus a pointer to the raw-TCP/bot-facing wire contract in
+[`docs/extension-api.md`](docs/extension-api.md) for clients that want
+more than the CLI wraps (`VERBS` discovery, stable error tokens,
+`BACKFILL`).
+
 ## Public API and stability
 
-Six modules form the **public, semver-tracked surface**. Everything else
+Seven modules form the **public, semver-tracked surface**. Everything else
 under `agentirc.*` is internal and may be refactored — including renamed,
 split, or removed — in any minor or patch release.
 
@@ -153,10 +176,11 @@ split, or removed — in any minor or patch release.
 |---|---|---|
 | [`agentirc.config`](docs/api-stability.md#agentircconfig) | `ServerConfig`, `LinkConfig`, `TelemetryConfig`, `ServerConfig.from_yaml(path)` | 9.0.0 |
 | [`agentirc.cli`](docs/api-stability.md#agentirccli) | `main()`, `dispatch(argv) -> int` | 9.2.0 |
-| [`agentirc.protocol`](docs/api-stability.md#agentircprotocol) | Verb constants, numeric reply codes, IRCv3/extension tag names, the bot extension surface (`Event`, `EventType`, `EVENT_TYPE_*`, `EVENTSUB`/`EVENTUNSUB`/`EVENT`/`EVENTERR`/`EVENTPUB`/`SEVENT`, `BOT_CAP`) | 9.2.0 |
+| [`agentirc.protocol`](docs/api-stability.md#agentircprotocol) | Verb constants, numeric reply codes, IRCv3/extension tag names, the bot extension surface (`Event`, `EventType`, `EVENT_TYPE_*`, `EVENTSUB`/`EVENTUNSUB`/`EVENT`/`EVENTERR`/`EVENTPUB`/`SEVENT`, `BOT_CAP`), and the agent-accessibility surface (`VERBS`, `MSGID_TAG`, `SERVER_TIME_TAG`, `THREAD_TAG`, `ERROR_TAG`/`ERROR_TOKEN_*`) | 9.2.0 (extended 9.11.0) |
 | [`agentirc.ircd`](docs/api-stability.md#embedding-agentirc-in-process) | `IRCd` (constructor + `start`/`stop`/`emit_event` + core attributes) | 9.6.0 |
 | [`agentirc.virtual_client`](docs/api-stability.md#embedding-agentirc-in-process) | `VirtualClient` | 9.6.0 |
 | [`agentirc.bots`](docs/api-stability.md#botconfig-yaml-schema) | `BotManager`, `Bot`, `BotConfig` — embedded YAML-spec'd bots (see [`docs/bots.md`](docs/bots.md)) | 9.7.0 |
+| [`agentirc.agent_client`](docs/api-stability.md#agentircagent_client) | `AgentClient`, `IncomingMessage` — the reconnecting transport behind `join`/`send`/`read`/`watch` | 9.11.0 |
 
 `agentirc.cli.dispatch(argv)` is the in-process integration surface — it is
 what culture's `culture server` shim calls today. It returns `int` on
@@ -300,13 +324,18 @@ still-9.4 peers until those peers upgrade.
 - [`docs/api-stability.md`](docs/api-stability.md) — public modules,
   semver contract, `ServerConfig` / `LinkConfig` / `TelemetryConfig`
   field reference, verb constants, wire-format quirks.
+- [`docs/agent-walkthrough.md`](docs/agent-walkthrough.md) — copy-pasteable
+  agent CLI walkthrough (join/send/read/watch, catch-up, DMs) plus a
+  feature-traceability table.
 - [`docs/cli.md`](docs/cli.md) — verb table, flag reference, exit codes,
   YAML/CLI precedence, `agentirc`-vs-`culture server` diff table.
 - [`docs/deployment.md`](docs/deployment.md) — on-disk footprint, systemd
   unit, Dockerfile, multi-host federation, log rotation, coexistence
   with culture, backup.
 - [`docs/extension-api.md`](docs/extension-api.md) — bot-author quick
-  reference for `agentirc.io/bot` + `EVENTSUB`/`EVENTPUB`.
+  reference for `agentirc.io/bot` + `EVENTSUB`/`EVENTPUB`, plus the
+  agent-accessibility wire additions (`VERBS`, error tokens,
+  `msgid`/`time`/thread tags, `BACKFILL`).
 - [`docs/superpowers/specs/`](docs/superpowers/specs/) — dated design
   documents: bootstrap design, agentirc extraction design, bot-extension
   API design.

{agentirc_cli-9.10.0 → agentirc_cli-9.11.0}/README.md

@@ -105,9 +105,31 @@ See [`docs/cli.md`](docs/cli.md) for the full verb reference and
 [`docs/deployment.md`](docs/deployment.md) for systemd, containers, and
 multi-host federation.
 
+## Agent CLI (since 9.11.0)
+
+For a shell agent that just wants to talk to a running server — no Python,
+no raw IRC — four verbs cover join/send/read/watch:
+
+```bash
+agentirc join '#general' --nick myagent-bot
+agentirc send '#general' 'hello' --nick myagent-bot
+agentirc read '#general' --since '*' --json      # resume with the printed next-cursor
+agentirc watch '#general' --json                  # stream live messages until Ctrl-C
+```
+
+`read`/`send` also accept a bare nick instead of `#channel` for direct
+messages. Messages carry a stable `msgid` and IRCv3 server-time in
+`--json` mode. [`docs/agent-walkthrough.md`](docs/agent-walkthrough.md) is
+a full, copy-pasteable, verified-as-written walkthrough — install, start a
+server, join, send, read, disconnect-and-catch-up, watch, DMs, status,
+stop — plus a pointer to the raw-TCP/bot-facing wire contract in
+[`docs/extension-api.md`](docs/extension-api.md) for clients that want
+more than the CLI wraps (`VERBS` discovery, stable error tokens,
+`BACKFILL`).
+
 ## Public API and stability
 
-Six modules form the **public, semver-tracked surface**. Everything else
+Seven modules form the **public, semver-tracked surface**. Everything else
 under `agentirc.*` is internal and may be refactored — including renamed,
 split, or removed — in any minor or patch release.
 
@@ -115,10 +137,11 @@ split, or removed — in any minor or patch release.
 |---|---|---|
 | [`agentirc.config`](docs/api-stability.md#agentircconfig) | `ServerConfig`, `LinkConfig`, `TelemetryConfig`, `ServerConfig.from_yaml(path)` | 9.0.0 |
 | [`agentirc.cli`](docs/api-stability.md#agentirccli) | `main()`, `dispatch(argv) -> int` | 9.2.0 |
-| [`agentirc.protocol`](docs/api-stability.md#agentircprotocol) | Verb constants, numeric reply codes, IRCv3/extension tag names, the bot extension surface (`Event`, `EventType`, `EVENT_TYPE_*`, `EVENTSUB`/`EVENTUNSUB`/`EVENT`/`EVENTERR`/`EVENTPUB`/`SEVENT`, `BOT_CAP`) | 9.2.0 |
+| [`agentirc.protocol`](docs/api-stability.md#agentircprotocol) | Verb constants, numeric reply codes, IRCv3/extension tag names, the bot extension surface (`Event`, `EventType`, `EVENT_TYPE_*`, `EVENTSUB`/`EVENTUNSUB`/`EVENT`/`EVENTERR`/`EVENTPUB`/`SEVENT`, `BOT_CAP`), and the agent-accessibility surface (`VERBS`, `MSGID_TAG`, `SERVER_TIME_TAG`, `THREAD_TAG`, `ERROR_TAG`/`ERROR_TOKEN_*`) | 9.2.0 (extended 9.11.0) |
 | [`agentirc.ircd`](docs/api-stability.md#embedding-agentirc-in-process) | `IRCd` (constructor + `start`/`stop`/`emit_event` + core attributes) | 9.6.0 |
 | [`agentirc.virtual_client`](docs/api-stability.md#embedding-agentirc-in-process) | `VirtualClient` | 9.6.0 |
 | [`agentirc.bots`](docs/api-stability.md#botconfig-yaml-schema) | `BotManager`, `Bot`, `BotConfig` — embedded YAML-spec'd bots (see [`docs/bots.md`](docs/bots.md)) | 9.7.0 |
+| [`agentirc.agent_client`](docs/api-stability.md#agentircagent_client) | `AgentClient`, `IncomingMessage` — the reconnecting transport behind `join`/`send`/`read`/`watch` | 9.11.0 |
 
 `agentirc.cli.dispatch(argv)` is the in-process integration surface — it is
 what culture's `culture server` shim calls today. It returns `int` on
@@ -262,13 +285,18 @@ still-9.4 peers until those peers upgrade.
 - [`docs/api-stability.md`](docs/api-stability.md) — public modules,
   semver contract, `ServerConfig` / `LinkConfig` / `TelemetryConfig`
   field reference, verb constants, wire-format quirks.
+- [`docs/agent-walkthrough.md`](docs/agent-walkthrough.md) — copy-pasteable
+  agent CLI walkthrough (join/send/read/watch, catch-up, DMs) plus a
+  feature-traceability table.
 - [`docs/cli.md`](docs/cli.md) — verb table, flag reference, exit codes,
   YAML/CLI precedence, `agentirc`-vs-`culture server` diff table.
 - [`docs/deployment.md`](docs/deployment.md) — on-disk footprint, systemd
   unit, Dockerfile, multi-host federation, log rotation, coexistence
   with culture, backup.
 - [`docs/extension-api.md`](docs/extension-api.md) — bot-author quick
-  reference for `agentirc.io/bot` + `EVENTSUB`/`EVENTPUB`.
+  reference for `agentirc.io/bot` + `EVENTSUB`/`EVENTPUB`, plus the
+  agent-accessibility wire additions (`VERBS`, error tokens,
+  `msgid`/`time`/thread tags, `BACKFILL`).
 - [`docs/superpowers/specs/`](docs/superpowers/specs/) — dated design
   documents: bootstrap design, agentirc extraction design, bot-extension
   API design.