Repository navigation
feat(docs): the /dox page, a port of gmt's Dox (#309) - #344
Conversation
The empty Dox page at /worktree/dox/: a full-bleed shell under the site header with the strip and its local/live badge, and the hub with gmt's crystal (in spring, per D5) and the prompt line. On /dox Footer.astro renders neither Starlight's footer nor the chat launcher. @astrojs/sitemap is configured explicitly with a filter that keeps /dox out of the sitemap, and the dist audit learns the page: noindex, one island, its title, the header, named controls, no sitemap or llms.txt entry, and no other page loading Dox code. The shell carries Starlight's not-content opt-out, so the hive's own code chip styles win over .sl-markdown-content code. The page's h1 is visually hidden rather than display:none, so it stays in the accessibility tree. Gate 1: pnpm check, pnpm typecheck, pnpm --filter docs typecheck, pnpm build, pnpm docs:build, worker:bundle-check, pnpm docs:audit-dist, pnpm test (3826 passed), pnpm docs:test (795 passed), test-marker grep: all exit 0. Gate 2 (reviewer subagent): PASS WITH NOTES, after one loopback on the prompt chip colour, which a headless-Chrome pass caught (ice instead of spring ink). The same pass measured no scroll at 1440x900, 1024x600 and 390x844, with the hub centred and the h1 hidden as on gmt's live page.
/dox now chats: useDocsChat's messages render as hive turns (crystal node,
Dox/You label, zigzag cards), with gmt's hub-to-transcript view transition,
a crystal that spins while the newest turn waits ("Searching docs…") and
lands on the first text, and reduced motion respected. The composer is
pinned with the accuracy note under it on wide screens and behind an info
button on a phone; the strip gains "New chat". The transcript scroller is a
named, focusable region only while it overflows, with a jump-to-latest
button. Warnings take the amber signal look and keep their roles; the stall
warning reads "Dox stopped responding…" as gmt's does. A fenced code block
gets a language label and a Copy control and is a focusable named region.
Answers get gmt's reading surface (gmt-ask.css sections 1-2, cyan to
spring): Starlight's starlight.reset layer is declared after Tailwind's
utilities, so its `* { margin: 0 }` beat MarkdownContent's mb-2 and the
prose ran together. Links are spring ink over a spring border (3:1 or more
in both themes), not gmt's teal, which measures 1.65:1 on a light card.
Gate 1: pnpm check, pnpm typecheck, pnpm --filter docs typecheck,
pnpm build, pnpm docs:build, worker:bundle-check, pnpm docs:audit-dist,
pnpm test (3826 passed), pnpm docs:test (819 passed), test-marker grep:
all exit 0. theme-contrast: every hive pair passes in both themes.
Gate 2 (reviewer subagent): PASS WITH NOTES after one loopback. That
loopback added tests for the IME guard and Try again focus (which exposed
focus left on a disabled Send after a retry, now fixed), and the reading
surface the caller's headless-Chrome pass found missing. Measured on a
seeded transcript at 1440x900: p and ul 12px apart, li 4px, inline code
rgb(74,222,128) dark and rgb(10,86,38) light, no page scroll.
The starters move into gmt's examples rail: an "Examples" heading with its
count, groups by area with an area icon, and cards that name their question
and the page that answers it. A card sends through the composer's own
guarded send (one shared path in DoxChat); when the send is refused, focus
stays on the card. On desktop the rail has a resizer that clamps, takes
arrow keys (16px, 64px with Shift), Home and End, resets on double-click and
remembers its width. On a phone, as on gmt, the list sits open under the
composer before the first question and folds behind an "Examples · 3" bar
once a conversation starts (from the start on a phone 44rem tall or less).
Escape folds the sheet and focuses the bar, but steps aside while a native
popover or Starlight's search dialog is open.
The areas ("Issues", "Environment files", "Cleanup") and their icons are a
placeholder pending the plan's open question on examples; the chip shows
the starter's route.
Chunk sizes (#304), gzip -9, after this phase: DoxPage island entry
5,784 B (17,596 raw); the hive stylesheet 4,766 B (24,600 raw).
Gate 1: pnpm check, pnpm typecheck, pnpm --filter docs typecheck,
pnpm build, pnpm docs:build, worker:bundle-check, pnpm docs:audit-dist,
pnpm test (3826 passed), pnpm docs:test (852 passed), test-marker grep:
all exit 0.
Gate 2 (reviewer subagent): PASS WITH NOTES after one loopback, which
made the card test assert the exact request rather than containment and
kept Escape from folding the sheet under Starlight's search. The caller's
headless-Chrome pass at 1440x900 and 390x844, empty and mid-conversation,
showed the rail, the open phone list and the folded bar, with no page
scroll.
/dox is now the only chat surface. The launcher bubble, the drawer, the Alt+Shift+C shortcut and the code behind them are gone. Every page links to Dox instead: - the header's right group opens with a "Chat with Dox" crystal link, ahead of the theme toggle, GitHub and Discord, with aria-current on /dox; - the mobile menu's footer carries the same link before the social icons; - the landing's "Ask Dox" is a link to /worktree/dox/ carrying the crystal. The crystal mark's rules move site-wide into custom.css. The Dox link stays out of the landing header's entrance animation while that question is open. The audit drops the launcher and shortcut rules and gains the header link (one per page and on the 404, its order, aria-current on /dox alone), the mobile-menu link, and the landing CTA. theme-contrast drops the drawer's pairs and measures the Dox link on the header glass and the phone menu, its current-page bar, and the CTA. Tests that covered live behaviour through the drawer moved to DoxChat. useLocalStorage and three chat tokens that only the drawer used are deleted. docs/README.md, context/verify.md and context/stack.md describe the new links. Gate 1: pnpm check, pnpm typecheck, pnpm --filter docs typecheck, pnpm build, pnpm docs:build, worker:bundle-check, pnpm docs:audit-dist, pnpm test (3826 passed), pnpm docs:test (785 passed; the drawer's tests went with it), test-marker grep: all exit 0. The Done-when grep for data-chat-launcher|data-chat-open|docs-chat:open|Alt+Shift+C|ChatDrawer in docs prints nothing. Gate 2 (reviewer subagent): PASS WITH NOTES after one loopback. The loopback fixed comments that still named deleted modules, pinned "a refused message stays in the box" (a lone zero-width space), removed the newly dead code and a docs line that claimed an audit rule nobody wrote. The caller's headless-Chrome pass showed the header crystal first in the group (with its bar on /dox), the CTA beside "Get started", and the mobile menu's links in the order Dox, GitHub, Discord.
The Worker no longer sends the whole docs with every question on
/api/chat. build-context.mjs now writes a corpus of 210 heading sections
from the 28 pages, a prebuilt MiniSearch 7.2.0 index, SKILL.md's sections
as vocabulary, and the counts into docs-context.ts (no SYSTEM_PROMPT).
The handler then:
- retrieves from the last question, biased toward the section of the page
the reader came from (forwardedProps.pageContext, optional and additive);
- keeps gmt's caps (10 chunks, 24,000 characters, the first kept);
- builds the prompt with a standing order, the retrieved text as data and
a route list equal to the kept chunks' pages, plus never-linkable
vocabulary.
A dox-retrieval CUSTOM event carries the trace after RUN_STARTED and again
before RUN_FINISHED, with timings. /dox renders it collapsed in the answer
card ("Searched N chunks → M matched") and shows "Dox // 28 pages ·
210 sections indexed" on the hub, both styled as gmt's. The client and the
Worker share one page-context pattern, so the client never sends a context
the Worker refuses. A corpus that cannot be searched returns a retryable
500 and calls no model.
POST / stays frozen for the live v3.0.0 client: its prompt is written as
LEGACY_PROMPT, compared byte for byte (same sha256, 353,802 chars) with
the SYSTEM_PROMPT HEAD generated.
Plan answers: Q12, a CUSTOM chunk yielded from the route's wrapper reaches
onCustomEvent (toolCallId undefined); Q14, relevance floor 10.
Sizes: docs-context.ts 360,721 B -> 1,046,164 B (index 227.5 KB, legacy
prompt ~354 KB); Worker Total Upload 3,930.56 KiB / gzip 761.07 KiB
(was about 3,222 / 577 KiB).
Gate 1: pnpm check, pnpm typecheck, pnpm --filter docs typecheck,
pnpm build, pnpm docs:build, worker:bundle-check, pnpm docs:audit-dist,
pnpm test (3826 passed), pnpm docs:test (935 passed), test-marker grep:
all exit 0.
Gate 2 (reviewer subagent): PASS WITH NOTES after one loopback, which:
- shared the page-context pattern between client and Worker (an encoded
path would have failed every question on that visit);
- removed a duplicated, stale half of docs/worker/README.md and brought
its flow and route table up to date;
- pinned the referrer bias at the handler (mutation-checked).
Before review, the caller had restored POST / to byte-identical and had
the trace and status line styled.
/api/chat now walks D9's five brains before any answer text streams: two
Workers AI models (Gemma 4 26B, GLM 4.7 Flash) and then three Gemini, and
only those that are configured. Each attempt writes a dox-progress CUSTOM
line ("Asking …", "… is busy — trying the next model…"), which /dox shows
in the waiting turn and which restarts its idle clock. Then:
- A brain silent past its start time (15 s Gemini, 20 s Workers AI) is
skipped.
- A Gemini 429 marks the brain spent; Workers AI's daily allocation (3036,
4006) retires both Workers AI brains; 400/404 are unavailable; 503/529
and other 429s are busy.
- When every brain is out, a dox-refusal (429 plus resetsAt) and a
non-retryable allowance_spent end the run.
The trace's second write names the answering brain.
Workers AI goes through @tanstack/ai-cloudflare with explicit modelOptions
(max_tokens 2048, chat_template_kwargs.enable_thinking false), because the
adapter sends neither on its own (plan Q13, R3). Its OpenAI client's
retries are switched off, and the walk rewrites its RUN_FINISHED onto the
request's runId. wrangler.toml gains `[ai] binding = "AI"` (remote in
dev). forwardedProps.brain is added; #306's forwardedProps.model is still
accepted. POST / is untouched.
Sizes: Worker Total Upload 5,396.58 KiB / gzip 986.20 KiB (was 3,930.56 /
761.07), almost all of it the openai client; the Workers limit is 64 MiB
uncompressed.
Gate 1: pnpm check, pnpm typecheck, pnpm --filter docs typecheck,
pnpm build, pnpm docs:build, worker:bundle-check, pnpm docs:audit-dist,
pnpm test (3826 passed), pnpm docs:test (1042 passed), test-marker grep:
all exit 0.
Gate 2 (reviewer subagent): PASS WITH NOTES after one loopback, which:
- wired D9's start times to the walk by test (a 90 s default had passed
everything);
- fixed the Workers AI runId mismatch;
- added allowance_spent and upstream_slow to ChatWarning's table;
- corrected the bundle attribution.
Afterwards, a handler-level test pins the runId wiring (fails with it
removed).
The Worker keeps D10's daily ledger in an optional DOX_USAGE KV store: - Each brain's count and state are keyed by its provider's day (Pacific for Gemini, UTC for Workers AI); each visitor is keyed by a hash of the client address, which never reaches KV or the logs. TTLs run to the next midnight plus 300 s, never under KV's 60 s minimum. - The ledger is read before the brain choice, so brains marked out are skipped, and a visitor's sixth question of the UTC day is refused (429, resetsAt at UTC midnight) before any brain is asked. - Once a brain accepts, the request is recorded and a dox-usage CUSTOM event goes out before the answer. - Ledger failures are best-effort: warn-level structured lines carrying the request's ids, and the chat still answers. GET /api/brains returns the counts with `cache-control: private, no-store` and its own rate-limit bucket; CORS allows GET. Without the binding, every brain is usable and the counts are empty. POST / is untouched. Still open: the DOX_USAGE namespace ids (plan §9 Q3, the maintainer's step). wrangler.toml carries no placeholder ids; docs/worker/README.md gives the two `wrangler kv namespace create` commands and the block to add. Plan Q15: KV's minimum expirationTtl is 60 s. Gate 1: pnpm check, pnpm typecheck, pnpm --filter docs typecheck, pnpm build, pnpm docs:build, worker:bundle-check (5,405.93 KiB / gzip 988.63 KiB), pnpm docs:audit-dist, pnpm test (3826 passed), pnpm docs:test (1106 passed), test-marker grep: all exit 0. Gate 2 (reviewer subagent): PASS WITH NOTES, no loopback. Its cheap notes were fixed and re-checked: structured warn logs, a test for the separate /api/brains bucket, `remote = true` for dev in the README's binding block, an honest name for the TTL-floor test, one shared provider type, and a handler-level test that the ids reach the ledger's log lines (fails with them removed).
wrangler.toml binds DOX_USAGE to the maintainer's namespaces (plan §9 Q3): worktree-dox-usage as id, worktree-dox-usage_preview as preview_id, remote in dev. They are not titled DOX_USAGE: a namespace with that title already exists on the account, most likely gmt's Dox ledger, which writes the same keys, so sharing it would merge both sites' counts and visitor caps. The worker README's binding section now describes the live binding, and its commands go through pnpm (wrangler is the docs package's dev dependency) with --config worker/wrangler.toml: without it, wrangler run from docs/ offers to add the binding to the docs site's wrangler.jsonc, which it did once (that edit was reverted, not committed). Gate 1: every verify.md command exit 0; tests 3,826 (root) + 1,106 (docs); wrangler deploy --dry-run lists env.DOX_USAGE (6622db5e…) as a KV namespace; upload 5,405.93 KiB / 988.63 KiB gzip. Gate 2: reviewer PASS WITH NOTES, no blocking items; its notes on stack.md's layout row, the permission name (Workers KV Storage Write, per Cloudflare's KV docs) and stating gmt's ownership as an inference are applied here.
#309 phase 8) Ports gmt's control bar onto Base UI (D4, D13). The brain badge ("Gemma 4 26B · You 5 left · Dox 140 today") opens a Menu radio group: Automatic, then one group per provider headed by its reset time in the reader's zone, each brain with "N left" or out. The reset chip opens a Popover with the resets, gmt's ten formats each showing its @northguild/gmt call linked to gmt's reference (§9 Q11 left open), and a Combobox zone search. The strip carries the header clock. Out of budget, the ⟨ · ⟩ banner shows ("Dox has used its free allowance for today. Back <time>." or the visitor's) and the composer rests ("Dox is resting until the quota resets…"). The badge reads GET /api/brains, then each dox-usage event; a refusal or pre-stream error re-reads it once. An unreachable /api/brains hides the badge and the chip and leaves the chat usable. The pick rides as forwardedProps.brain; Automatic sends none. Zone, locale and every time resolve after mount: the island is client:load, and nothing time-based is in its server render. Formats' expected output is gmt's reference pages' own worked examples. theme-contrast.mjs gains the hive pairs, including those Phases 1-3 left unmeasured; all pass. The format radio and the focused zone-search edge use the ink tier (spring measured 2.79:1 and 2.71:1 in the light theme). Payload (#304), /dox island entry plus imports, gzip -9: 206,911 B before (726,460 raw), 280,445 B after (953,683 raw); the dox stylesheet 25,627 B raw before, 33,719 B raw / 5,925 B gzip after. Phase 3's 5,784 B counted the entry alone. Gate 1: every verify.md command exit 0 (pnpm check, both typechecks, pnpm build, docs:build, worker:bundle-check, docs:audit-dist, pnpm test 3,826, pnpm docs:test 1,256, test-marker grep). Gate 2: the reviewer returned FAIL (a README sentence saying the menu was not on the page yet; gmt's zone-search magnifier cut silently); one loopback fixed both, matched gmt's display face on the popover's headings and pinned the single re-read after a refusal (mutation-checked); re-review PASS. A browser pass against gmt's live page at 1440 and 390 px, dark and light, with a stand-in /api/brains: badge, menu, popover, both banners and the phone wrap match; one Escape with the phone sheet and the menu open closes only the menu. The magnifier draws in CanvasText under forced colours.
There was a problem hiding this comment.
code-reviewer: minor issues
This replaces the chat drawer with a full-page /dox route: a hive transcript and composer, an examples rail with a resizer, a brain badge and reset clock fed by GET /api/brains, and audit and contrast rules for the new page and its entry links. The client code is careful and well tested, and I found nothing that should block the merge; the four findings are an accessible-name defect, two checks that can pass without testing what they claim, and a small persistence quirk. The Worker side (brains.ts, usage.ts, brains-payload.ts, chat-handler.ts, retrieval), dox.astro, custom.css/dox-hive.css, Header.astro and MobileMenuFooter.astro were left out for size, so the routing, ledger and server-side refusal logic were not reviewed.
Reviewed ed770ea for baldurpan · claude-opus-5-5 · 83 files · left out: docs/src/chat/hooks/useDocsChat.test.tsx (over the review's size budget), docs/src/chat/lib/chat-starters.test.ts (over the review's size budget), docs/src/chat/lib/chat-starters.ts (over the review's size budget), docs/src/chat/lib/chat-types.ts (over the review's size budget), docs/src/chat/lib/day-clock.test.ts (over the review's size budget), docs/src/chat/lib/day-clock.ts (over the review's size budget), docs/src/chat/lib/page-context.test.ts (over the review's size budget), docs/src/chat/lib/page-context.ts (over the review's size budget), 52 more · $0.88
… click (#309) - The brain badge's accessible name no longer runs its parts together ("Gemma 4 26BYou 3 leftDox 140 today"): literal spaces between the name and the counts and around the hidden dot, as ExamplesBar does. - The audit requires a mobile menu on every page with a sidebar (the 28 but the landing) and matches `mobile-preferences` as a class token, so a probe that stops matching the build fails instead of skipping the Dox-link rule on every page. - The rail resizer stores a width only after the pointer moved: a plain click no longer pins the CSS default, in px, for later visits.
There was a problem hiding this comment.
code-reviewer follow-up: needs changes
Since the last review, this push fixes three of my earlier comments. The brain badge's accessible name gets literal spaces, with a test that would have failed before. The mobile-menu audit now requires a menu on the 27 sidebar pages and matches the class as a token, with tests and docs. The rail handle stores a width only after a real move. The new early return in onPointerMove introduces a small drag bug, and the remaining-vs-state question in DoxChat.tsx is still open.
Earlier comments
- Fixed; yours to resolve: Risk: The brain badge's accessible name runs its parts together
- Still open: Risk: Out-of-budget and the pool count read only
remaining, not a brain'sstate - Fixed; yours to resolve: Risk: The mobile-menu rule passes silently if the menu's markup doesn't match the probe
- Fixed; yours to resolve: Suggestion: A plain click on the handle stores a width
Reviewed 0a9cdac (changes since ed770ea) for baldurpan · claude-opus-5-5 · 7 files · $0.56
0a9cdac skipped every pointermove at the drag's starting x, so a drag that came back there left the rail at the last other width and stored it. Only a move before any other is skipped now.
There was a problem hiding this comment.
code-reviewer follow-up: looks good
Since the last review, RailResizer skips a pointer move at the drag's starting x only while nothing has moved yet. A drag that returns to where it began is now followed and stored. A new test covers that path, and it would fail against the previous guard (which stored 590). Both earlier comments are settled, and I have nothing new to raise.
Earlier comments
- Answered; yours to resolve: Risk: Out-of-budget and the pool count read only
remaining, not a brain'sstate - Fixed; yours to resolve: Bug: A drag that comes back to its starting x is ignored, leaving the rail at the last other width
Reviewed 3bda975 (changes since 0a9cdac) for baldurpan · claude-opus-5-5 · 2 files · $0.11
|
/craig-review |
There was a problem hiding this comment.
code-reviewer: needs changes
This PR replaces the docs chat drawer with a full-page /dox route. It adds the hive UI, an examples rail, retrieval traces, Worker brain failover, a usage ledger with GET /api/brains, and a control bar, and it updates the dist audit and contrast checks to match. The client code and tests I could see are careful and well covered. One real defect: once the budget reads as spent, the composer stays disabled until a page reload, even after the advertised reset time. All of the Worker side (chat-handler.ts, brains.ts, usage.ts, retrieval, validation), plus chat-types.ts, the time/ helpers, dox.astro and the CSS, were left out for size, so the routing, ledger and refusal logic were not reviewed.
Reviewed 3bda975 for craig-o-curtis · claude-opus-5-5 · 54 files · left out: docs/src/chat/hooks/useDocsChat.test.tsx, docs/src/chat/lib/chat-constants.ts, docs/src/chat/lib/chat-history.test.ts, docs/src/chat/lib/chat-starters.test.ts, docs/src/chat/lib/chat-starters.ts, 58 more · $0.84
A spent budget disables the composer, so no question could be asked and no dox-usage event arrive: the page stayed resting past the time its own banner gave until the reader reloaded. useBrains now reads /api/brains again just past the soonest reset, every 30 s after it while the answer still names a reset that has passed (a Worker clock behind, a failed read), and at once when a tab that slept through one is shown again. The DoxChat test that read as checking `state` is renamed for what it checks: the counts the Worker sends for brains it has marked out, which are 0 by `remainingFor`.
There was a problem hiding this comment.
code-reviewer follow-up: minor issues
Since the last review, use-brains.ts reads GET /api/brains again once the soonest reset passes, so a spent budget that disables the composer can lift without a reload. A new soonestResetMs in quota-resets.ts supplies that reset, and the hook polls every 30 s while the counts still name a passed reset, and reads again when a tab is shown after one. The scheduling and cleanup are sound and the tests cover the main paths. The one concern is that the retry is driven entirely by the reader's clock, so a machine whose clock runs ahead keeps polling (and spending KV reads) for as long as it is ahead. brains.fixture.ts (for the new UTC_MIDNIGHT export) was not shown; I assumed it exports that constant as the tests expect.
Reviewed 89a34d7 (changes since 3bda975) for baldurpan · claude-opus-5-5 · 7 files · $0.39
89a34d7 read /api/brains every 30 s while the counts named a reset the reader's clock had passed. A clock hours ahead of the Worker's, or a route that keeps failing, made that a poll of about a dozen KV reads every 30 s for as long as it lasted. The wait now doubles from 30 s to a 5 min ceiling, counted per reset across reads that say the same thing (each is a new object, which re-ran the effect and reset the count).
There was a problem hiding this comment.
code-reviewer follow-up: looks good
Since 89a34d7 the reset re-read backs off when the reset has already passed: 30 s, then doubling, capped at 5 min. The retry count lives in a ref keyed on the reset instant, so it survives the effect re-running on each new info object. It is counted when a read fires, so the double scheduling after a read that lands new counts cannot skip a step. The new tests cover the sequence, the ceiling with a route that keeps failing, and refreshDelay as a pure function; the Worker README now describes the same behaviour. I found nothing new to raise, and the earlier comment is resolved.
Earlier comments
- Fixed; yours to resolve: Risk: A reader's clock that runs ahead turns the reset re-read into an unbounded 30 s poll
Reviewed 3a8ce83 (changes since 89a34d7) for baldurpan · claude-opus-5-5 · 3 files · $0.18
Brings in the /dox page (#344). Seven paths conflicted: - docs/astro.config.mjs: both sides registered @astrojs/sitemap; one call now takes main's `filter` (keeps /dox/ out) and this branch's `serialize` (lastmod from the footer). - docs/package.json: main's exact pin of @astrojs/sitemap. - pnpm-lock.yaml: main's, regenerated from the merged manifests. - docs/scripts/audit-dist.mjs: both doc-comment paragraphs. - docs/scripts/audit-dist.test.mjs: this branch's lastmod-aware sitemap fixture and main's Dox fixtures; the chat-launcher fixtures and tests go, as on main; main's three-character fixture hashes lengthened for this branch's `_astro/` hash rule. - context/stack.md, context/verify.md: both sides' edits.
Summary
Adds
/doxto the docs site: a full-page port of gmt's Dox, replacing the chat drawer. Plan, discussion and finished ledger are in #309.Phases landed
/doxroute, shell and the Dox mark (30d7583)/dox(62bc177)/api/brains, with theDOX_USAGEKV binding (aac56da, 9b679b5)Release note
None owed. The change touches only
docs/**,context/**and the lockfile;context/release.mdgives those paths no note. The docs site deploys with the next stable release, so this is not live on merge.Owner checks filed at close
Nobody has run these; none is a defect and none gates the merge: #339 (compare with gmt's live Dox), #340 (Cloudflare account, plan, deploy token), #341 (quota shared with gmt?), #342 (mark, header, copy, reset-clock links), #343 (manual end-to-end, keyboard, reduced-motion passes). #303's screen-reader pass now also covers
/dox.Closes #309