docs: sweep for v3.11.0 and correct stale guidance #270

Merged

claude-bot merged 1 commit from docs/v3.11-sweep into main

2026-07-27 23:19:57 +00:00

claude-bot commented

2026-07-27 23:14:21 +00:00

Contributor

Documentation sweep after v3.11.0. Docs-only — no code changes.

The Session Reference Shelf shipped and was documented nowhere: before this, webapp/CLAUDE.md was the only file that mentioned it, and only in the migration-head line.

Added

File	What
`docs/API.md`	A Session Shelf section covering all 12 endpoints — board CRUD, pin/unpin, copy-from, promote, cold-open, reveal, revealed, revoke — plus TOC entry
`docs/INTEGRATIONS.md`	A "What the Bot Posts" table. The bot's event vocabulary had never been documented anywhere
`docs/ROADMAP-COMPLETED.md`	A Live-Play Tooling section for the GM Workbench (v3.10) and the shelf (v3.11) — neither had an entry
`README.md`	The four v3.11 capabilities in "What It Does"
`webapp/CLAUDE.md`	Migrations 71–74, the three shelf models, the shelf router

The API section calls out the authorization split explicitly — everything is GM-only except GET /sessions/{id}/revealed, which is the players' surface and open to any campaign member — and documents the non-obvious semantics: null means "leave unchanged" so scene/player_text clear with an empty string; the player-safe default is an allowlist that refuses rather than guesses; reveals are frozen and outlive their card.

Corrected — three stale claims, each verified against the code first

"The frontend currently has no automated test suite." There are 30 test files and 427 tests gating CI. Replaced with how to actually run them, plus the mocking pattern page tests use.
The bot dispatch dict is _handlers (a local inside on_bot_notify), not _HANDLERS.
"Add a Celery task that calls POST <bot_url>/notify" describes the pre-v3.4 fire-and-forget path. Events go on the durable Redis stream via publish_bot_event; /notify is an optional fast path. This one mattered most — following the old instructions would produce a new event that silently drops whenever the bot is down, so the corrected version says so explicitly.

Also documents make check-versions alongside the pre-commit hooks.

Verification

Rather than trusting what I wrote, I diffed the docs against the code:

Endpoints: extracted all routes from routers/shelf.py (handling multi-line decorators) and from the new API section — 12 in code, 12 documented, zero drift in either direction.
Bot events: extracted the _handlers keys and the doc table — all 11 user-facing events documented; only test omitted, deliberately, as it's the admin connectivity ping rather than a real event.
Links: every internal .md link in the touched files resolves, and the new #session-shelf anchor has a matching heading.

Milestones (done separately, no diff here)

Renumbered into release order so numbering matches build order — Live Scene Push was "Phase 2.5" but numbered v4.4.0, after Phase 3:

v4.0.0 Foundry Phase 1 → v4.1.0 Phase 2 → v4.2.0 Phase 2.5 Live Scene Push (was v4.4.0) → v4.3.0 Phase 3 → v4.4.0 Notification Controls (was v4.2.0)

v3.12.0 was retired and its two issues moved to Backlog, with the rationale and the milestone's framing preserved on #237.

🤖 Generated with Claude Code

Documentation sweep after v3.11.0. Docs-only — no code changes. The Session Reference Shelf shipped and was documented **nowhere**: before this, `webapp/CLAUDE.md` was the only file that mentioned it, and only in the migration-head line. ## Added | File | What | |---|---| | `docs/API.md` | A **Session Shelf** section covering all 12 endpoints — board CRUD, pin/unpin, copy-from, promote, cold-open, reveal, revealed, revoke — plus TOC entry | | `docs/INTEGRATIONS.md` | A **"What the Bot Posts"** table. The bot's event vocabulary had never been documented anywhere | | `docs/ROADMAP-COMPLETED.md` | A **Live-Play Tooling** section for the GM Workbench (v3.10) and the shelf (v3.11) — neither had an entry | | `README.md` | The four v3.11 capabilities in "What It Does" | | `webapp/CLAUDE.md` | Migrations 71–74, the three shelf models, the shelf router | The API section calls out the authorization split explicitly — everything is GM-only **except** `GET /sessions/{id}/revealed`, which is the players' surface and open to any campaign member — and documents the non-obvious semantics: `null` means "leave unchanged" so `scene`/`player_text` clear with an empty string; the player-safe default is an allowlist that refuses rather than guesses; reveals are frozen and outlive their card. ## Corrected — three stale claims, each verified against the code first 1. **"The frontend currently has no automated test suite."** There are **30 test files and 427 tests** gating CI. Replaced with how to actually run them, plus the mocking pattern page tests use. 2. **The bot dispatch dict is `_handlers`** (a local inside `on_bot_notify`), not `_HANDLERS`. 3. **"Add a Celery task that calls `POST <bot_url>/notify`"** describes the pre-v3.4 fire-and-forget path. Events go on the durable Redis stream via `publish_bot_event`; `/notify` is an optional fast path. This one mattered most — following the old instructions would produce a new event that **silently drops whenever the bot is down**, so the corrected version says so explicitly. Also documents `make check-versions` alongside the pre-commit hooks. ## Verification Rather than trusting what I wrote, I diffed the docs against the code: - **Endpoints:** extracted all routes from `routers/shelf.py` (handling multi-line decorators) and from the new API section — **12 in code, 12 documented, zero drift in either direction**. - **Bot events:** extracted the `_handlers` keys and the doc table — all 11 user-facing events documented; only `test` omitted, deliberately, as it's the admin connectivity ping rather than a real event. - **Links:** every internal `.md` link in the touched files resolves, and the new `#session-shelf` anchor has a matching heading. ## Milestones (done separately, no diff here) Renumbered into release order so numbering matches build order — Live Scene Push was "Phase 2.5" but numbered v4.4.0, after Phase 3: - v4.0.0 Foundry Phase 1 → v4.1.0 Phase 2 → **v4.2.0 Phase 2.5 Live Scene Push** (was v4.4.0) → v4.3.0 Phase 3 → **v4.4.0 Notification Controls** (was v4.2.0) v3.12.0 was retired and its two issues moved to Backlog, with the rationale and the milestone's framing preserved on #237. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

claude-bot added 1 commit

2026-07-27 23:14:21 +00:00

docs: sweep for v3.11.0 and correct stale guidance

CI / Docker image build (pull_request) Successful in 12s

Details

CI / Bot/backend version sync (pull_request) Successful in 22s

Details

CI / Backend lint (ruff) (pull_request) Successful in 56s

Details

CI / Frontend tests, audit, and build (pull_request) Successful in 1m53s

Details

CI / Bot tests and audit (pull_request) Successful in 2m3s

Details

CI / Backend migration, tests, and audit (pull_request) Successful in 5m17s

Details

a370a355f5

The Session Reference Shelf shipped and was documented nowhere: before this,
`webapp/CLAUDE.md` was the only file that mentioned it, and only in the
migration-head line.

Added:

- docs/API.md — a Session Shelf section covering all 12 endpoints (board CRUD,
  pin/unpin, copy-from, promote, cold-open, reveal, revealed, revoke), with the
  authorization split called out: GM-only except GET .../revealed, which is the
  players' surface and open to any member. Verified against the router — 12 in
  code, 12 documented, no drift either direction.
- docs/INTEGRATIONS.md — a "What the Bot Posts" table. The bot's event
  vocabulary had never been documented at all; a self-hoster had no way to know
  what appears in their channel. Notes that shelf_reveal carries only the
  player-safe layer.
- docs/ROADMAP-COMPLETED.md — a Live-Play Tooling section for the Workbench
  (v3.10) and the shelf (v3.11), neither of which had an entry.
- README.md — the four v3.11 capabilities in "What It Does".
- webapp/CLAUDE.md — migrations 71-74 (the chain stopped at f0a1b2c3d4e5, still
  marked "(head)" four revisions later), the three shelf models, and the shelf
  router.

Corrected, all three verified against the code first:

- "The frontend currently has no automated test suite" — there are 30 test files
  and 427 tests gating CI. Replaced with how to actually run them.
- The bot dispatch dict is `_handlers` inside on_bot_notify, not `_HANDLERS`.
- "Add a Celery task that calls POST <bot_url>/notify" describes the pre-v3.4
  fire-and-forget path. Events go on the durable Redis stream via
  publish_bot_event; /notify is an optional fast path, and that path alone is
  lossy. Left a warning saying so, since following the old steps would build a
  new event that silently drops when the bot is down.

Also documents `make check-versions` alongside the pre-commit hooks.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

claude-bot merged commit b9fe7f8ac8 into main

2026-07-27 23:19:57 +00:00

claude-bot deleted branch docs/v3.11-sweep

2026-07-27 23:19:57 +00:00

claude-bot referenced this pull request from a commit

2026-07-27 23:19:59 +00:00

Merge PR #270: docs sweep for v3.11.0 and stale-guidance corrections