Working on a vault, start here
The entry point for any agent about to build, publish or change a vault (v0.6.8). Short on purpose: this is a router, not a manual. Every line below is an edge to the page that actually answers the question. Human-readable twin: /docs/guidance/index.md
The five rules that get repeated most
- Pick the surface first. _page.json inside a vault, an HTML vault app inside a vault, or a page on a *.sgit.ai site. It changes every other answer, including who distrusts whom. /docs/surfaces.md
- Do not build what the platform already has. Markdown rendering, file trees and page layouts are free. Most tasks end here. /docs/briefs/markdown-and-file-viewers.md
- Publish a read key. Never a vault key. A read key is derived one-way and cannot become write access; a vault key IS write access. Escrow the write key BEFORE publishing. /demos/vaults/publishing.md
- Version everything, show the version, link what changed. The number belongs in the app chrome and must link to that version's own details, not a generic changelog. Keep versions/index.json plus one file per version, each naming the commit it was built from. /docs/guidance/index.md#versions
- Anything rendered stays one click from the bytes it was rendered from. A reader that only shows its own interpretation is asking to be trusted.
Read in this order
- Three surfaces↗, pick where the code runs before anything else.
- What not to build↗, the ladder, rung 0 upward.
- Content authoring↗, _page.json and vault markdown syntax.
- Vault apps↗ and the window.sg bridge↗, only when a view must compute.
- Publishing: the method↗, before anything becomes public.
Build briefs, written to be executed
- Markdown and file viewers: what not to build↗
- Decks from a vault, on a site↗
- Reading a vault from a *.sgit.ai site page↗
- Telemetry from a published vault↗
- Reading one file out of a vault↗, the primitive under the last three.
Reference implementations, go and look rather than take our word
- The published vaults↗, and the same catalogue with every read key↗.
- Version convention, done properly: the AIUC-1 conformance vault (2wzct4k7), a Versions tab, the number in the top bar, one JSON file per version. /demos/vaults/aiuc-1-conformance/index.md
- A file explorer with raw always available, in the same vault: "raw is the point, a catalog that asks to be trusted has to be readable in the form it was written."
- Decks read live out of a vault onto a site: /demos/vaults/aiuc-1-conformance/decks/index.md
Follow the edge. The answer is often on another domain
This site covers vaults and sgit, and deliberately stops there. An agent that stops at this domain will give a worse answer than one that follows the edge.
- https://coding.sgit.ai/↗: how code is written here, measured against its own rules, read before writing a vault app. "The style guide that measured itself"
- https://nfrs.sgit.ai/↗: resilience, budgets, backups: what a vault owes anyone who comes to depend on it. "The non-functional requirements, from the inside"
- https://graphs.sgit.ai/ ↗: the grammar of semantic graphs, read before modelling anything as data. "A node is just a node. Meaning lives in the edges" The full map of sites, with the words each answers to: /network/index.md
Why this file is mostly links
The estate is one semantic graph 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 but what it is connected to. So: every page is reachable and has a .md twin, indexes are generated from the data they index rather than maintained by hand, and each site says one thing properly and links out instead of summarising the rest badly.