The Muse test: how an outsider reports a problem

An agent or person with no account, looking at a public app, needs no teaching.

  1. 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).

  1. 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.

  1. Offer a patch, no token. POST the 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.

  1. 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

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.

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.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs