What Sheaf is
Sheaf turns a repository of markup into a documentation site, an API reference and a machine-readable surface for agents. You keep writing files and committing them. Everything else — building, publishing, search, the agent surface — follows from the commit.
The whole product rests on three nouns. Learn these and the rest of this documentation reads itself.
Your markup, your images, one sheaf.json. The repository is the source of truth; the
platform keeps no other copy of your text.
One revision, built whole: pages, static files, the API reference, the search index and the agent files. Addressed by content hash and never edited afterwards.
One pointer per site says which artifact is live. Publish moves it forward, rollback moves it back. Both take seconds and neither rebuilds anything.
The path of one edit
A push to the connected repository raises a signed event. An unsigned event is rejected before its body is read.
The commit id becomes a revision. The same commit id always yields the same revision, so a build can be repeated later and produce the same result.
Configuration is validated, every page is compiled, the navigation is assembled, the API reference is generated, the agent files are written and the search index is built. An error in any file stops the build — the live site is untouched and you get file, line and column.
The result is written to storage under its content hash, with a manifest listing pages and their hashes, the API specifications, the configuration schema version, the platform version and the build time. The build log is kept, including for successful builds.
Publishing switches the pointer to the new artifact in one atomic step. There is no moment in which the site serves a mixture of two artifacts.
Nothing is edited in place, so there is no half-published state to recover from. The worst outcome of a bad commit is that the previous artifact keeps serving readers.
Two readers, one artifact
A person and an agent read the same revision, each in the shape that suits them. The agent surface is not a scraped copy of the site — it comes out of the same artifact and switches with it.
| Reader | Gets | Where to read next |
|---|---|---|
| A person in a browser | Rendered pages, navigation, table of contents, search, an interactive sandbox on API operations | Writing content |
| An agent | The same pages as markdown, summary files, an agent card, a skills index and an MCP server with three tools | Agent surface |
What lives where
Two places hold settings, and the line between them is the lifecycle of the setting.
Lives in sheaf.json, in your repository |
Lives in the control panel |
|---|---|
| Navigation, theme, colours, mounted API specifications, sandbox hosts, agent surface options | Domains, access keys, members and roles, audience rules, usage limits, alert receivers |
| Changes together with the text and rolls back together with it | Changes together with infrastructure and access, and must not roll back with a page |
Properties of a single page — its title, description and audiences — live in the front matter of that page, for the same reason: they change with the text.
What Sheaf deliberately does not do
The markup is a closed subset of MDX: expressions, imports, event handlers, raw HTML and any tag outside the component registry are rejected at build time with file, line and column. Delivery never compiles or executes tenant content while answering a request. This is the primary security measure of the platform, not a style preference.
- No editing of a live site. Content changes only through a commit.
- No money in the core. Usage is counted in units of account; turning units into an invoice is the job of whoever consumes the usage contract.
- No guessed answers. When search finds nothing above the relevance threshold, it says so instead of returning the closest paragraphs.
Connect a repository and publish a first site.
Every key of sheaf.json, with defaults.