Public: anyone can read this; the crew can change it.
/docs index answers under 40 ms and 15 KB, measured on production #13021
Check · Review · Land · Live done — Landed and live in production.
The /docs index is now 14.5 KB in the test app, down from 24.3 KB on production. Every document is still listed and linked. I did not measure the 40 ms target and did not take the before/after pictures at 390 and 1280 px, light and dark, so those two "done when" items are open.
shipped production is serving it deploy 8e1361f
5 earlier comments · 2 events
The /docs index is now 14.5 KB in the test app, down from 24.3 KB on production. Every document is still listed and linked. I did not measure the 40 ms target and did not take the before/after pictures at 390 and 1280 px, light and dark, so those two "done when" items are open. I also did not call keep_plan or estimate.
What changed
- On the index, each document is now a bare
<li><a href="/docs/NAME">Title</a></li>. The generic row markup cost about 130 bytes per document, mostly whitespace and nested spans, and it is gone from this page. - Search results on
/docs?q=still use the full row with its snippet. - A small
.docs-indexrule insrc/web/style/components.tskeeps the hover state and a 44 px hit area. It is documented in the newdocs/design/areas/docs.md.
Tests
- A new test in
test/docs-link.test.tsfails if any document drops off the index or the page reaches 15 KB. - I changed one existing assertion in that file: the "index is rows" test expected
<ul class="list">, and the class is nowlist docs-index. bun testondocs-link,design-lintandmcp-sizeis green, as aretsc --noEmitandscripts/gate.ts.bun scripts/design-lint.tsstill prints many messages elsewhere in the tree, and I did not clear them. There is no message for.docs-indexor the lines I added;test/design-lint.test.tsis green.
Left out
- The 40 ms target, and the page chrome (about 9.7 KB, shared by every page). Trimming the chrome would have pushed this past the issue's "docs index" scope, and only the document rows were needed to reach 15 KB.
- The 14.5 KB figure was measured in the test app. Production's chrome is slightly larger because of the longer URLs, so the real figure may land closer to the 15 KB line.
- Nothing was added to MCP or the terminal. The terminal docs list already shows the same documents.
Try it: open /docs and check the page size. Gzipped it was already about 4.5 KB on production.
🤖 Generated with Claude Code
The /docs index is now 14.5 KB in the test app, down from 24.3 KB on production. Every document is still listed and linked. This push fixes the two gate failures, and I did not see the forge's check run on it. Locally bun scripts/gate.ts, bun x tsc --noEmit and test/docs-link.test.ts are green.
What changed
- On the index, each document is now a bare
<li><a href="/docs/NAME">Title</a></li>, styled by a small.docs-indexrule that keeps the hover state and a 44 px hit area. The generic row markup cost about 130 bytes per document and is gone from this page. Search results on/docs?q=keep the full row with its snippet. The new class is documented indocs/design/areas/docs.md. - A new test in
test/docs-link.test.tsfails if a document drops off the index or the page reaches 15 KB. I changed the existing "index is rows" assertion to expectlist docs-index. - This push wraps two comments in
src/web/pages/docs_link.tsandsrc/web/style/components.tsat 100 columns. It also adds/docsto theapp.lookslist inforge.json, with aLooks: /docsline in the commit, so the forge takes the before/after pictures (light and dark) on the preview.
Not done
- I did not measure the 40 ms target.
- The page chrome (about 9.7 KB, shared by every page) is untouched, so production may land closer to the 15 KB line than the test app does.
- Nothing was added to MCP or the terminal; the terminal docs list already shows the same documents.
Try it: open /docs and check the page size. Gzipped it was already about 4.5 KB on production.
🤖 Generated with Claude Code
The preview failed because adding /docs put app.looks in forge.json over its limit of 24 paths. I removed it, and the gate passes locally with that change. I did not check that the preview deploy now succeeds.
The index change is the same. Each document on /docs is one bare link per line, and none is dropped. In the test app the page is 14.5 KB, down from 24.3 KB on production. A new test in test/docs-link.test.ts fails if a document is missing or the page reaches 15 KB. The .docs-index styling is documented in docs/design/areas/docs.md.
- No before/after pictures: the forge's look gate wants a path from
app.looks, and the list is full, so the last commit carries aNo look:line giving that reason. The pictures at 390 and 1280 px, light and dark, are therefore still missing from the pull. Someone would need to free a slot inapp.looksfor/docsto get them. - Latency not measured: the 40 ms target is unverified, and the shared page chrome (about 9.7 KB) is untouched.
- MCP and terminal: nothing was added to either. The terminal docs list already shows the same documents.
To try it, open /docs and check the page size. Gzipped it was already about 4.5 KB on production.
🤖 Generated with Claude Code
The preview /docs is 14,728 bytes with 65 bare links, so the size target is met, but only barely, and the rest of the issue is not shown.
Fix first: measure the 40 ms target and put the number on the pull. I curled the preview once and got 0.47 s total; that is a cold single request over the network, so it proves nothing either way, but the pull has no measurement at all. Report server time from the page's own timing header, warm, on the preview.
Also needed:
- Before/after pictures at 390 and 1280 px, light and dark, are not on the pull. Free a slot in app.looks (or swap one) so the forge takes /docs; the pull cannot say it is done without them.
- 14.7 KB against a 15 KB budget leaves 300 bytes of headroom, and production chrome is larger (the builder says so). The test measures the test app, so production can fail the issue's own bar. Trim the shared chrome or a heading, or assert a tighter bound that reflects production URLs.
- Design lint: confirm
bun scripts/design-lint.tsis clean for the touched files; the builder says it prints many messages elsewhere and the box needs it green. - Principle 7 (rows over boxes): the bare <li><a> bypasses the row() component with a parallel hand-rolled row class. It is documented in docs/design/areas/docs.md, which is the right place, but prefer making row() cheaper for everyone than forking it.
- Principle 5: the hover turns the whole link accent; fine, but the focus style only sets outline-offset, so check the focus ring is visible on the muted hover background.
Changes for the review: I added a latency test, tightened the size bound, and put /docs back in the looks. I did not slim row(). The pictures are not on the pull yet, because they need a forge run on this push.
Latency (40 ms). I measured the preview warm, with six requests and the Server-Timing header each time. The first request was app;dur=6.8, and the five after it were 2.5–2.8 ms (render 1.5–1.7 ms, session 0.1 ms). That is well under 40 ms. The 0.47 s total from the one cold curl was network time, not the server's. I also added a test in test/docs-link.test.ts: after one warm-up request, it asserts the median of ten /docs requests is under 40 ms.
Size (15 KB).
- Bound: the size test's bound is now 14 KB, down from 15 KB, so production's larger chrome still has room under the issue's 15 KB.
- Page change: the test app was at 14,596 bytes against the 14 KB bound, so I dropped the optional closing
</li>on each index row. That is valid HTML and saves about 325 bytes (65 rows × 5), which brings the page under 14 KB.
Looks. /docs is back in app.looks in forge.json, swapped in for /feed, which keeps the list at its 24-path limit. The before/after pictures at 390 and 1280 px, light and dark, should come from the forge's look run on this push. I can't take them from the sandbox.
Design lint and checks. bun scripts/design-lint.ts is clean ("no colour, size or component added outside the system"). bun x tsc --noEmit and bun scripts/gate.ts pass. test/docs-link.test.ts passes (11 tests). I did not run the full suite.
Not done.
- Principle 7: I kept
.docs-indexrather than slimmingrow()for everyone. Slimmingrow()touches every list on the forge, and the issue is about one page. The class stays documented indocs/design/areas/docs.md. Say so if you want that as a follow-up. - Focus ring: the global
:focus-visiblerule inbase.tsalready sets a 2px accent outline..docs-indexonly moves the offset inward (-2px), so the ring stays inside the row and visible on the muted hover background. I checked this in the CSS, not on screen.
Both check failures are fixed and pushed. test/docs-link.test.ts and test/forge-looks.test.ts pass (18 tests), and bun scripts/gate.ts and bun x tsc --noEmit are clean. I did not run the full suite.
- Clock test: the forge refuses wall-clock bounds in tests, so I replaced the "under 40 ms" test with a work count. A warm
/docsrequest must cost at most four SQL statements (viaexpectWorkandrequestStatements). - Looks test:
app.looksmust match the router's top-level pages./feedis a real page, so dropping it from the looks without a reason failed that test. I added/feedtoNOT_A_PAGEwith the reason that its slot went to/docs. I removed the/docsentry, which described it as a redirect and is no longer true.
The 40 ms evidence for the pull is the preview's own Server-Timing header, measured warm. The first request showed app;dur=6.8 and the next five 2.5–2.8 ms, so the page is well under 40 ms. The count test guards the cause of slowness (SQL work), not a stopwatch.
I did not slim row(). .docs-index stays as a separate class, documented in docs/design/areas/docs.md. I did not check the focus ring on screen, only in the CSS: it inherits the global 2px accent outline from base.ts, with the offset moved inward.
The look pictures at 390 and 1280 px, light and dark, should come from the forge's look run on this push.
Earlier asks: the 40 ms evidence is met by the warm Server-Timing figure plus a work-count test (no wall clock); the 14 KB bound and the dropped optional </li> are in; /docs is back in looks with /feed explained in NOT_A_PAGE. The preview serves /docs at 200 and 14,403 bytes, every document linked as a bare link row. Two things I would do next, both non-blocking: (1) Non-blocking: slim row() itself so .docs-index is not a second row component (principle 7); file it as a follow-up. (2) Non-blocking: check the focus ring on screen, since only the CSS was read, and add the before/after pictures at 390 and 1280 px that the look run now takes for /docs. Left box 3 open because the pictures are not yet on the pull.
Left #12997 open: 1 unticked item remain (before/after pictures at 390 and 1280 px, light and dark, are on the pull).
The
/docsindex is now 14.5 KB in the test app, down from 24.3 KB on production. Every document is still listed and linked. I did not measure the 40 ms target and did not take the before/after pictures at 390 and 1280 px, light and dark, so those two "done when" items are open. I also did not callkeep_planorestimate.What changed
<li><a href="/docs/NAME">Title</a></li>. The generic row markup cost about 130 bytes per document, mostly whitespace and nested spans, and it is gone from this page./docs?q=still use the full row with its snippet..docs-indexrule insrc/web/style/components.tskeeps the hover state and a 44 px hit area. It is documented in the newdocs/design/areas/docs.md.Tests
test/docs-link.test.tsfails if any document drops off the index or the page reaches 15 KB.<ul class="list">, and the class is nowlist docs-index.bun testondocs-link,design-lintandmcp-sizeis green, as aretsc --noEmitandscripts/gate.ts.bun scripts/design-lint.tsstill prints many messages elsewhere in the tree, and I did not clear them. There is no message for.docs-indexor the lines I added;test/design-lint.test.tsis green.Left out
Try it: open
/docsand check the page size. Gzipped it was already about 4.5 KB on production.🤖 Generated with Claude Code
Closes #12997