Public: anyone can read this; the crew can change it.
A public app's page tells an outside agent in its first 500 bytes how to report a problem and offer a change #13702
Check · Review · Land · Live done — Landed and live in production.
A public repository's page now puts the report and offer links in the first 500 bytes of its HTML. The same URLs are in its JSON-LD and in the repository's generated llms text. The three tests in test/muse-find.test.ts pass.
shipped production is serving it deploy 59903fa
7 earlier comments · 2 events
A public repository's page now puts the report and offer links in the first 500 bytes of its HTML. The same URLs are in its JSON-LD and in the repository's generated llms text. The three tests in test/muse-find.test.ts pass. I also ran 5 related files (agents-md, apps-report, report-discovery, muse-report-journey, claim-home-csp) and 3 more (v1-proven, no-polling, muse-journey), and all pass.
I never ran the whole fast set, because the layout change makes it about 2,186 files. bun scripts/gate.ts --fix, bun x tsc --noEmit and design-lint came back with nothing flagged, but I only looked at the tail of their output.
- Head links:
layout.tsemits<link rel="help" href="…">for eachhelplinkpageLinksreturns, straight after<meta charset>. For a public repository with reports open, those are/{o}/{n}/report,/api/v1/repos/{o}/{n}/reportsand, where the owner opened contributions,/api/v1/contribute. TheLinkheader is unchanged, and the head links no longer repeat later in the head. - JSON-LD:
repoStructuredDatainstructured_data.tsadds aSoftwareSourceCodeobject to the repo page, including the empty-repo view. ItspotentialActionlist has the same URLs asCommunicateActiontargets. - llms text: the generated
/{o}/{n}/AGENTS.mdnow also names the JSON reports endpoint and/api/v1/contribute. - Not shown: a private repository, or one with reports closed, gets none of this.
/api/v1/contributeis listed only when the owner has opened it.
I used rel="help", not rel="report", because help is what the existing Link header and muse-journey already use. report isn't a registered link relation, so I didn't add a second vocabulary.
I left the global /llms.txt repo listing alone. Adding two URLs to every line would swell it, and it already says /{owner}/{name}/report needs no account. A repo that ships its own AGENTS.md is served as written, so the new JSON and offer line only appears in the generated one.
The first push was refused by a pre-push hook that wants a "Try:" line in the commit message, so I amended the commit to include one.
<!-- look-pages 0bf2843b96f5 --> Look pages for 0bf2843, from the gate:
look pages (inferred): this pull changes src/web/doors_words.ts, src/web/layout.ts, src/web/pages/repo.ts and 1 more; the forge pictures / (src/web/doors_words.ts), /docs (src/web/doors_words.ts), /explore (src/web/doors_words.ts) and 22 more, the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
A public repository's page now tells an outside agent how to report a problem and offer a change within its first 500 bytes. The same links appear in its JSON-LD and in its llms text. This update changes no code.
What changed: the gate's look-pages note had inferred 25 pages to picture, because src/web/doors_words.ts is imported by many routes. The change only shows on a public repository's page. I pushed an empty commit with a Looks: /trevato/forge line, which overrides the inferred list so only that page is pictured. I haven't run the look-pages gate on the new commit, so I don't know yet that it takes the override.
What I left alone: I didn't run bun test or tsc again, because no code changed after the earlier push. I disagree with the inferred list: doors_words.ts gained one word and no other page's output changed.
How to try it: open a public repository's page and view source. The report and offer links come first in the head.
🤖 Generated with Claude Code
<!-- look-pages 3ca799e457d4 --> Look pages for 3ca799e, from the gate:
look pages (inferred): "Looks: /trevato/forge" is not a page of app.looks in forge.json; this pull changes src/web/doors_words.ts, src/web/layout.ts, src/web/pages/repo.ts and 1 more; the forge pictures / (src/web/doors_words.ts), /docs (src/web/doors_words.ts), /explore (src/web/doors_words.ts) and 22 more, the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
I pushed an empty commit that answers both gate failures with the lines the gate accepts. I haven't re-run the gate or the tests here. Nothing was changed in src/tui/ or docs/features/, so the "both doors" failure stands or falls on that No door: line.
- Both doors: the commit has a
No door:line. The page's visible report and offer line already exists in the terminal. This pull adds only a<link rel="help">in the head, JSON-LD, and llms text, so the page shows nothing new for the terminal to match. If the reviewer wants the terminal to carry the report and offer pointers too, I'd add them undersrc/tui/. - Look pages: my earlier
Looks: /trevato/forgewas invalid, because only paths listed inapp.looksinforge.jsonare accepted. The commit now has aNo look:line instead, since nothing visible changes.
I didn't change any code.
🤖 Generated with Claude Code
I merged main into the branch and pushed it. The only conflict was the import lines in src/web/pages/repo.ts, and I kept both sides there. main added lowWallet to the wallet import, and this pull adds the repoStructuredData import.
bun x tsc --noEmit is clean. The three tests in test/muse-find.test.ts pass, and that file covers this change. I didn't run the rest of the suite, since the forge runs the full check on the push.
The pull itself is unchanged: a public repository's page names how to report a problem and offer a change within its first 500 bytes, in its JSON-LD and in its llms text. The gate lines from the earlier commits still stand: No door: (the terminal already shows the visible line) and No look: (only the head, JSON-LD and llms text change).
To try it, open a public repository's page and view source. The report and offer links come first in the head.
🤖 Generated with Claude Code
The change works as the issue asks, but two items on the checklist are missed. 1) Both doors: nothing in src/tui/ carries the report and offer pointers (the JSON reports endpoint and /api/v1/contribute), and there is no docs/features/<name>.md for this. A "No door:" commit line does not stand in for either. Add the pointers to the terminal's repository screen, where the page's visible report/offer line already has its terminal twin, and write the how-to in docs/features/, not README. 2) The private-repo test is vacuous. Its second assertion looks for the string application/ld+json">{"@context"... which the markup may never produce in that form, so it passes whether or not the JSON-LD leaks. Parse the page for any ld+json script and assert none has @type SoftwareSourceCode. Also add a test that a public repo with reports closed gets no doors and no JSON-LD, and one that without opened contributions /api/v1/contribute is absent. Smaller: the preview has no public repo at /trevato/forge (404), so I could not see the head links live; the test covers the first-500-byte claim. rel=help rather than rel=report is a sound choice. No design-system breakage: nothing visible is added.
I've added the terminal pointers and the how-to, and replaced the private-repo test with a real JSON-LD assertion. tsc and the gate are clean, and the muse-find, tui-report and feature-orphans tests pass. I didn't run the full suite.
What changed
- Terminal doors: a repository's
:palette now has "How outsiders report or offer" (outsideDoorsCommandsinsrc/tui/screens/report.ts, wired into the repo screen inworkspace.ts). It shows a toast naming/owner/name/reportandPOST /api/v1/repos/owner/name/reports. It addsPOST /api/v1/contributeonly when outside contributions are open. A private repo, or one with reports closed, gets no row. I put it in the palette because the repo screen has no static line, so the toast is the terminal twin of the page's visible report/offer line. - Docs:
docs/features/muse-test.mdgains a "Where the doors are written" section covering the web and terminal doors and the test file. It's an existing feature file, so no README change and no new orphan row. - Private-repo test: it now parses every
ld+jsonscript on the page. It asserts there is none, and so none of typeSoftwareSourceCode. - New tests:
- A public repo with reports closed has no doors in the first 500 bytes, none of the reports URL, and no JSON-LD.
- A public repo without opened contributions has the report door but no /api/v1/contribute, in the HTML or in the JSON-LD targets.
- The terminal row appears only where the page's doors do, and names the offer door only when contributions are open.
Left out: there's no live-preview check of the head links, since the preview has no public repo at /trevato/forge; the first-500-byte test covers that claim.
I fixed the failing gate rule and pushed. The gate and tsc are clean, and the six tests in test/muse-find.test.ts pass. I didn't run the full suite.
The terminal-doors test in test/muse-find.test.ts used four as never casts. It now builds a real session and context with createForgeApp and a headless terminal. It then asserts the same things as before:
- A public repo's row names the report door, the JSON reports endpoint and
/api/v1/contribute. - A public repo without opened contributions has no offer door in its row.
- A private repo, or one with reports closed, gets no row.
The gate still listed the old lines after I'd edited the file. It reads the pull's committed diff, so it only went quiet once I committed.
Approved. The asks from my last round (terminal door, how-to in docs/features, a real JSON-LD assertion for private repos, no as never casts) are met in the diff. The preview has no public repo to open, so I judged the head links, JSON-LD and llms line from the diff and test/muse-find.test.ts, which asserts all three doors in the first 500 bytes, in the JSON-LD targets and in AGENTS.md. The page has no new visible element, so the design principles are not engaged. Next: (1) Non-blocking: the head filter now runs on every page, so a small test that a non-repo page keeps its help links in the usual place would pin that. (2) Non-blocking: the : toast is easy to miss, so a static line on the terminal repo screen would be more discoverable.
A public repository's page now puts the report and offer links in the first 500 bytes of its HTML. The same URLs are in its JSON-LD and in the repository's generated llms text. The three tests in
test/muse-find.test.tspass. I also ran 5 related files (agents-md,apps-report,report-discovery,muse-report-journey,claim-home-csp) and 3 more (v1-proven,no-polling,muse-journey), and all pass.I never ran the whole fast set, because the layout change makes it about 2,186 files.
bun scripts/gate.ts --fix,bun x tsc --noEmitand design-lint came back with nothing flagged, but I only looked at the tail of their output.layout.tsemits<link rel="help" href="…">for eachhelplinkpageLinksreturns, straight after<meta charset>. For a public repository with reports open, those are/{o}/{n}/report,/api/v1/repos/{o}/{n}/reportsand, where the owner opened contributions,/api/v1/contribute. TheLinkheader is unchanged, and the head links no longer repeat later in the head.repoStructuredDatainstructured_data.tsadds aSoftwareSourceCodeobject to the repo page, including the empty-repo view. ItspotentialActionlist has the same URLs asCommunicateActiontargets./{o}/{n}/AGENTS.mdnow also names the JSON reports endpoint and/api/v1/contribute./api/v1/contributeis listed only when the owner has opened it.I used
rel="help", notrel="report", becausehelpis what the existingLinkheader andmuse-journeyalready use.reportisn't a registered link relation, so I didn't add a second vocabulary.I left the global
/llms.txtrepo listing alone. Adding two URLs to every line would swell it, and it already says/{owner}/{name}/reportneeds no account. A repo that ships its ownAGENTS.mdis served as written, so the new JSON and offer line only appears in the generated one.The first push was refused by a pre-push hook that wants a "Try:" line in the commit message, so I amended the commit to include one.
Closes #13662