Home / Guidance

Working on a vault: start here

The first page to read before building, publishing or changing a vault — human or agent. It is deliberately short and made almost entirely of edges: the practices that get repeated most, and a route to the page that actually answers each question. If you are an agent and you fetch one thing, fetch /docs/guidance/llms.txt, which is this page in the form you prefer.

The one-minute version. Pick your surface first — it changes every other answer. Do not build what the platform already has: markdown, file trees and page layouts are free. Publish a read key, never a vault key. Version everything and show the version, linked to what changed. Anything rendered stays one click from the bytes it was rendered from.

Read in this order

	Read	Because
1	Three surfaces	Every “how do I show this” question has three different right answers. Picking the surface first collapses most of them
2	What not to build	The two most common asks — a markdown viewer, a file browser — are already in the platform. Most tasks end here
3	Content authoring	The syntax for `_page.json` and vault markdown, once you know you need it
4	Vault apps and the window.sg bridge	Only when a view has to compute something the host cannot know
5	Publishing: the method	Before anything becomes public. Classify the credential before it touches anything

Version everything, show the version, link what changed

This is the single most repeated piece of guidance, so it goes first among the practices. A vault is a versioned thing; an app that does not say which version it is leaves the reader unable to tell what they are looking at, and leaves a screenshot or a recording undateable.

Show the version in the app's chrome — small, in the top bar, always visible. Not in a footer, not in an About box.
Make it a link, and make the link go to that version's own details — not to a generic changelog. A reader who clicks v0.1.7 wants to know what v0.1.7 was.
Give versions a home in the vault: versions/index.json plus one file per version. It is data, so an app can render it, a script can check it, and an agent can read it without running anything.
Record the commit. A version that does not name the vault commit it was built from cannot be verified later.
Say when a version is reconstructed rather than recorded — a history assembled after the fact is still useful, but only if it is labelled.

The AIUC-1 conformance vault is the reference implementation: a Versions tab, the number in the top bar, and one JSON file per version carrying exactly this shape.

versions/index.json      { "current": "v0.18.0", "versions": [ … newest first … ] }
versions/v0.15.1.json    { "version", "date", "commit", "vault",
                           "reconstructed", "title", "summary",
                           "changes": [ … ], "basis": [ … ] }

title is a sentence, not a label — “the settings move into the right-hand column, which folds and resizes” tells a reader more than “UI improvements” ever will. changes names files. basis is for a reconstructed entry: the files that make that stage a distinct thing.

The rest of the practices, in one place

Practice	Why it exists
Read keys are publishable. Vault keys never are	A read key is derived one-way and cannot become write access. A vault key is write access, and there is no partly-public version of it. Escrow the write key before publishing, not after
Scan for other people's secrets too	A scan built for sgit credential shapes will not catch an API key sitting in a vault file. We nearly published a live OpenRouter key in a field called `openrouter_key` that matched no sgit pattern
Every credential test needs a negative control	`sgit clone` creates a directory whether or not the key is valid. The marker that discriminates is `.sg_vault/local/clone_mode.json`. We called a leak once on a directory that an all-zeros key produced identically
Anything rendered stays one click from its bytes	A reader that only shows its own interpretation asks to be trusted; one that also shows the source offers to be checked. `_page.json` has `{ } Source`; this site gives every page a `.md` twin
Deny by default in `app.json`	Declare the narrowest permission that works, and write down why each grant exists. `"permissions": {}` is a real answer and often the right one
Manifests at build time, files on click	A vault can be tens of megabytes. Do not re-derive at runtime what the build already knew, and do not fetch what nobody opened
Content exists once	If a paragraph is in the vault and again in a page about the vault, they will disagree, and the vault is the one that is right
State the gap rather than papering over it	A page that names what it is missing is more useful than one that quietly omits it. Measured, not guessed

Build briefs — written to be executed

Brief	For
Markdown and file viewers: what not to build	Documents and file browsing in a vault
Decks from a vault, on a site	Presentations published on a web page
Reading a vault from a site page	Devs coding the `*.sgit.ai` sites
Telemetry from a published vault	A public vault reporting usage back to its author
Publishing a vault: the method	Anything about to become public

The mechanism underneath the last three is reading one file out of a vault. The catalogue of what has already been built this way is the published vaults — and /demos/vaults/llms.txt is that catalogue with every read key, for an agent that wants to go and look rather than take our word for it.

Where the rest of the answer lives

This site covers vaults and sgit. It deliberately does not cover how code should be written, what a system owes its users when nobody is watching, or how to model meaning — because each of those has a site of its own, with the room to do it properly. An agent that stops at this domain will get a worse answer than one that follows the edge.

coding.sgit.ai · Agents & AI — How software actually gets written here ↗ — The rules, the compliance measurement against them, which are machine-enforced and which are explicitly not, the open tensions — and a section on writing code for agents to read. Read this before writing a vault app, not after. — “The style guide that measured itself.” — part of the sgit.ai network

nfrs.sgit.ai · Risk & governance — The requirements nobody writes down until they are violated ↗ — Resilience, budgets, project management, backups — as a reality system rather than a checklist, with a scorecard and a page naming backups as a gap. The questions a vault has to answer once somebody depends on it. — “The non-functional requirements, from the inside.” — part of the sgit.ai network

graphs.sgit.ai · Graphs & method — A grammar for semantic graphs ↗ — From five rules you can apply tomorrow to a full positioning against schemas and vector search — including the four situations in which its own argument is the wrong one. The page to read before modelling anything as data. — “A node is just a node. Meaning lives in the edges.” — part of the sgit.ai network

The full network lists every site with what it covers and the words it answers to.

Why this page is mostly links

The estate is one semantic graph that happens to be served from many domains. A vault is a node; so is a site, a page, a version, a published read key. What makes any of them useful is not the node — it is what it is connected to. That is graphs.sgit.ai's own argument, applied to the thing you are reading:

“A node is just a node. Meaning lives in the edges.”

So this page does not restate the guidance that lives elsewhere, and it should not grow into a manual. Its job is to be the node an agent can always find, with enough edges to reach the right answer in one hop. Three properties keep that working, and they are worth preserving in anything built here:

Every page is reachable and machine-readable. Each has a .md twin and appears in llms.txt; the build fails on an orphan. A page nothing links to is a page nothing can find, which is the same as unpublished.
Indexes are generated from the data they index. The vault catalogue comes from the same file the human-readable table does, so the two cannot disagree. An index maintained by hand becomes a lie on a schedule.
Scope by domain, link across. Each site says one thing properly and points at the others rather than summarising them badly. The edge is the answer; the summary would be a worse copy.

If something here is wrong, that is worth telling us — the last brief on this site was corrected by the team that read it, and the correction sits above the mistake. /docs/guidance/llms.txt · All briefs · The network