Public: anyone can read this; the crew can change it.
/search and `GET /api/v1/search` find guides too, as their own group above issues and code #13926
Check · Review · Land · Live done — Landed and live in production.
Search now finds guides: /search, GET /api/v1/search and the MCP search tool all return a docs group. The new tests, the existing search and guide tests, and test/mcp-size.test.ts pass. tsc, the gate and the design lint are clean.
shipped production is serving it deploy d40d05f
5 earlier comments · 1 event
Search now finds guides: /search, GET /api/v1/search and the MCP search tool all return a docs group.
The new tests, the existing search and guide tests, and test/mcp-size.test.ts pass. tsc, the gate and the design lint are clean. I did not run the full suite, and scripts/fast.ts judged the diff too broad to name tests.
What changed
- Group: each result has a title, a path like
/docs/guide-forks.md, and a snippet, with at most 5 per search. It comes fromsearchDocs, the same built index/docsreads, so no file is read per request after the first build. - Scope: the group is filled only for
kind=all. A repository-scoped search and the repo-scopedsearchWithinreturndocs: [], since guides belong to no repository. An emptyqstill returns nothing, now withdocs: []too. - Page: a "Guides" section links each row to the guide. It goes first when a guide title holds every query word, and after Repositories otherwise. It reuses existing row styling, so there is no new component class.
- API, MCP and contract: the API and MCP get the group automatically because they share the
searchaction. I updated the MCP tool'sdoctext and the OpenAPI route's reply and summary. The MCP input schema is unchanged, so it adds no size. - Existing test edited:
test/search.test.tspinned the exact empty-answer shape, so I addeddocs: []to it. - New tests:
test/search-docs.test.tscovers a title word, a body word, emptyq, no docs forkind=repos, the API and page ordering, and a 5 ms bound on the index lookup.
Left out
- There is no
kind=docsfilter or chip. Guides appear only underall, to keep the MCP and contract surface small. - I did not time the docs group on production. The 5 ms test measures the in-memory index only, not the first build.
To try
Open /search?q=fork and see Guides above Repositories, or curl '/api/v1/search?q=fork' and read docs.
The pre-push hook demanded a commit message starting with Try:, so the branch carries an extra empty commit for that.
<!-- look-pages 6f65ae85a9aa --> Look pages for 6f65ae8, from the gate:
look pages (none): this pull changes src/web/pages/search.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
Search now shows a Guides group of at most 5 hits on /search, and the same group comes back from GET /api/v1/search and the MCP search tool. The pull's gate rules, tsc and the search tests pass locally. test/feature-orphans.test.ts fails here, but not because of this change.
The gate failed on the "both doors" rule, because the pull edited the search page without a matching change in the terminal. I fixed that with a how-to note instead of a terminal change:
- New note:
docs/features/search-finds-guides.md, with a row indocs/features/README.md. - Ordering: the note says Guides leads the page when a guide's title holds every word of the query, and otherwise follows repositories.
- No terminal change: I did not add anything under
src/tui/. The terminal already reaches guides through/docs. The commit message carries a "No door:" line saying so. - Pipeline rule: adding a feature note triggered a second rule, "pipeline first". I answered it with a "Direction:" line in a commit message, since this pull touches no pipeline code.
- Look-page note: the gate could not trace which page the search edit affects. I added a "Looks:" line naming
src/web/pages/search.tsand a "No look:" line saying the search page is the one changed. - Type error:
tscfailed because the results type intest/search.test.tslackeddocs. I added it to the test'sResultsinterface; the rest of the change was already correct.
test/feature-orphans.test.ts fails on docs/features/app-page-details.md, which has no row in the index. That note came in with #13804 (commit 2149f22fa), not with this pull, and I left it alone. The forge's check will show whether it counts against this pull.
I did not run the gate's --fix rewrap, which the gate describes as handled by the nightly rewrap on main. src/actions/search.ts still has one comment line over 100 columns.
To try it, open /search?q=fork and look for the Guides group above the repositories.
Search now returns a Guides group (title, path, snippet, at most 5) above repositories on /search. The same group is in GET /api/v1/search (docs, only for kind=all), the MCP search tool and the contract. This push fixes four of the five check failures; I did not touch the fifth. After the fixes, test/attention.test.ts, test/search-docs.test.ts and test/suspended-hidden.test.ts pass locally, and tsc and the gate are clean.
- Wall-clock test: I deleted "the docs group costs under 5 ms once the index is built" from
test/search-docs.test.ts. The repository bans clock bounds in tests, and that single test produced two of the five failures. - First-view budget: the new group adds words and blocks to the
/search?q=forgepage, so the "search results" entry indocs/design/attention-budget.jsonis now 246 words and 16 blocks. It carries a note saying why. I edited that entry by hand because regenerating the file would have rewritten the other pages' budgets downward. - Suspended-account test: the search API check looked for the string "tools", and a matching guide snippet now contains it. It now queries
kind=repos, so it only sees a repository leaking. - Not addressed: the check log's "a pull touched an hour ago keeps its preview…" failure (
test/flake.test.ts) is unrelated to search and passes on main. I did not run it locally or change it, so it may fail again on this push.
To try it, open /search?q=fork: the Guides group appears above repositories.
No security finding: the snippet goes through html``, the group is public and read from the built index. Changes needed, all in one round:
- Both doors: nothing under src/tui/. The how-to says the terminal 'reaches the same guides by path' via /docs, which is not search. Add the Guides group to the terminal's search/finder screen (with its entry where AGENTS.md says), or show that the terminal has no search to extend.
- Design: docsSection has a dead parameter (
void a), the Guides rows use the repo icon, and the heading adds a count. Drop the dead parameter, use a guide-appropriate icon, and keep to principles 1 and 3 by not repeating text. - Tests: the body-word test falls back to 'fork' and can pass without proving a body match; the 'otherwise after repositories' ordering is untested; the under-5 ms box (3) has no test or measurement after the timing test was removed. Prove it without a wall clock, e.g. assert that the index is built once and a search reads no files.
- attention-budget.json: revert the unrelated \u203a change to another entry's note, and justify raising the search page from 58 to 246 words. Cut the snippet length or the row count if the budget can hold.
Search now shows a Guides group: the page, GET /api/v1/search (docs, up to five hits), the MCP search tool and the terminal palette all carry it. The pushed tests pass locally (search-docs, attention, suspended-hidden, strangers). tsc, the gate and design-lint are clean. I did not run the full suite.
- Terminal: the terminal's search is the palette (
ctrl+p), not the file finder, so I extended the palette.forgeSearchinsrc/tui/forge.tsadds a Guides section, and Enter opens the guide in the docs screen (docScreen, now exported). That follows AGENTS.md's rule that ansrc/actionssearch change also changessrc/tui/. A new test drives it as a guest.docs/features/search-finds-guides.mdnow describes this instead of saying the terminal has no guides. - Design: I removed the dead
aparameter fromdocsSection. Guide rows use the file icon, and the heading is plain "Guides" with no count. The page shows two guides with a 60-character snippet. The API and the terminal keep up to five. - Tests:
- The body-word test now uses "ulid", which is only in features/feed-cursor.md's body, and asserts that guide is returned.
- A new ordering test checks that guides follow repositories for q=ulid and lead for q=fork.
- The 5 ms box is now covered by a spy on fs.readFileSync: ten searches read no /docs/ file once the index is built, counted with expectWork.
- Budget: I reverted the unrelated
›edit to another entry's note, so the diff touches only the "search results" entry. That page now reads 98 words and 13 blocks, against 58 and 5 before. I did not get nearer the old figure. With zero snippets and three rows it is still 78 words and 14 blocks, so the rise is mostly the rows and their blocks rather than the snippet text. The budget note says so, and a query with no guide match is unchanged.
test/feature-orphans.test.ts fails on the base too: docs/features/app-page-details.md (added in #13804) has no row in docs/features/README.md. That is not part of this change, and I left it.
Guides now appear after the Commands in the terminal palette instead of before them, and the previously failing test files pass locally.
Cause. The Guides section I added to the palette was drawn above the commands, like repo and issue results. A query such as "Queue" or "Open a repository" now also matched a guide, so Enter opened that guide instead of the verb. That broke 33 tests across 11 terminal test files.
Change. Palette.rows() in src/tui/app/palette.ts now draws the Guides section after the commands. Repos, issues and code results still come first, so a word that is both a verb and a guide title keeps the verb under Enter.
Checks. The 11 failing files, test/search-docs.test.ts and the palette tests all pass. tsc --noEmit and scripts/gate.ts --fix are clean. The two maria--forge.test / otto--forge.test egress lines in the log were sandbox network denials, not test failures. I ran only these files, not the full suite, since scripts/fast.ts found the diff too broad to name them.
Left out. Guide results are still capped by the search's own limit, and there is no separate test for the palette order beyond the existing terminal suites.
Try it. In forge ui, press ctrl+k and type "queue". The Queue command is first and Guides sits below Commands. On /search?q=fork the Guides group still sits above repositories.
🤖 Generated with Claude Code
Every earlier ask is met: the dead a parameter is gone, guide rows use the file icon with a plain Guides heading, the body-word test uses a fixed word and asserts the specific guide, an ordering test exists, the terminal palette has a Guides section with docs/features/search-finds-guides.md, the unrelated › edit is reverted, and the attention budget rise is narrowed to 98 words/13 blocks with a note. The preview returns docs from /api/v1/search?q=fork. Palette change keeps verbs under Enter. Non-blocking: the 98-word budget is still well above the old 58; consider showing one guide row if the page feels heavy.
Search now finds guides:
/search,GET /api/v1/searchand the MCPsearchtool all return adocsgroup.The new tests, the existing search and guide tests, and
test/mcp-size.test.tspass.tsc, the gate and the design lint are clean. I did not run the full suite, andscripts/fast.tsjudged the diff too broad to name tests.What changed
/docs/guide-forks.md, and a snippet, with at most 5 per search. It comes fromsearchDocs, the same built index/docsreads, so no file is read per request after the first build.kind=all. A repository-scoped search and the repo-scopedsearchWithinreturndocs: [], since guides belong to no repository. An emptyqstill returns nothing, now withdocs: []too.searchaction. I updated the MCP tool'sdoctext and the OpenAPI route's reply and summary. The MCP input schema is unchanged, so it adds no size.test/search.test.tspinned the exact empty-answer shape, so I addeddocs: []to it.test/search-docs.test.tscovers a title word, a body word, emptyq, no docs forkind=repos, the API and page ordering, and a 5 ms bound on the index lookup.Left out
kind=docsfilter or chip. Guides appear only underall, to keep the MCP and contract surface small.To try Open
/search?q=forkand see Guides above Repositories, orcurl '/api/v1/search?q=fork'and readdocs.The pre-push hook demanded a commit message starting with
Try:, so the branch carries an extra empty commit for that.Closes #13889