The Muse test: how an outsider reports a problem
An agent or person with no account, looking at a public app, needs no teaching.
- The door says it. Every HTML page of a public app carries
Link: </__forge/report>; rel="help" and a rel="alternate" to the forge's
manifest for the repository (/api/v1/here?path=/owner/app). A private app
carries neither and names nothing. On a repository that takes offers the
same headers add <…/api/v1/repos/owner/app/offers>; rel="https://forge.open-platform.sh/rel/offer",
and the manifest lists "offer a patch" (no account).
- Report a problem, no token.
- Page: follow rel=help; /__forge/report?from=/page sends you to
/owner/app/report, told which page you came from.
- HTTP: POST /api/v1/repos/{owner}/{name}/reports with
{"title", "body"?, "page"?, "agent"?} answers 202.
- MCP: call report on /mcp with {repo, title, body?, page?, agent?}.
/.well-known/mcp.json lists it in tokenFreeTools; every other tool needs a token.
- Offer a patch, no token.
POSTthe link's target with
{"title", "body"?, "patch"}, or call MCP offer; it becomes a pull a
person reads (docs/features/offer.md), under 3 offers a minute per source.
- A person decides. The report waits, marked
untrusted,from: "outside",
with its page. A person who writes the repository accepts it as an issue
(label outside, the stranger's words fenced, "Sent from: <page>") or dismisses it.
The door is open, so its limits hold: 3 reports a minute per source, 20 per
repository, 60 for the forge, 100 waiting per repository, and a request body
of at most 64 KiB (413). test/muse-journey.test.ts walks all of this
end to end and asserts the limits.
Where the doors are written
- Web: a public repository's page carries both doors in its first 500
bytes (<link rel="help"> to the report page and the JSON reports endpoint,
and /api/v1/contribute only when outside contributions are open), the same
URLs in its JSON-LD potentialAction, and in its AGENTS.md llms text. A
private repository, or one whose reports are closed, gets no doors and no
JSON-LD.
- Terminal: on a public repository's screen,
:lists "How outsiders
report or offer"; it names /owner/name/report, POST /api/v1/repos/owner/name/reports
and, when contributions are open, POST /api/v1/contribute. Private or
reports-closed repositories list nothing.
- Tests:
test/muse-find.test.ts.