# sgit.ai — complete documentation, single file

> Every page of https://sgit.ai concatenated into one document, generated at build time
> (v0.2.38). Nothing here needs a second request. Individual pages live at the paths
> shown below, as markdown (`.md`) and as HTML (`.html`); the annotated map is /llms.txt.
>
> sgit is git for encrypted vaults: clone, commit, branch and merge files that are encrypted
> client-side (AES-256-GCM) before they leave your machine. The server stores ciphertext under
> opaque IDs — it never sees filenames, contents, or commit messages.



==============================================================================
# sgit — the encrypted git for humans and AI agents

> sgit is git for encrypted vaults: clone, commit, branch and merge files that are encrypted before they leave your machine. Zero knowledge — the server stores ciphertext, not your data.
>
> Page: https://sgit.ai/index.html

Agents need private, versioned state

# The encrypted git for
humans and AI agents

Version, branch, and share vaults of files that are encrypted before they leave your machine. Zero knowledge: the server stores ciphertext, not your data.

[Or try it in your browser →](try/index.md) [5-minute quickstart →](docs/quickstart.md)

Pure Python · two runtime dependencies · Apache-2.0

$sgit create my-vault
✓ Vault created and registered
✓ Initial commit pushed

 Vault key: <24-char-passphrase>:<vault-id>

Keep this safe — it is the address, the auth, and the
encryption key in one string. Without it, nobody — including
the server — can read this vault.

$vim notes/positioning.md
$sgit status
 On clone branch branch-clone-3f9c → named branch main
modified: notes/positioning.md
added: drafts/hero-copy.md

$sgit commit -m "first draft of hero copy"
✓ Committed 2 files (no staging area — commit snapshots the folder)

$sgit history log --oneline
c4e81a first draft of hero copy
b2d70f initial commit

$sgit history diff
--- a/notes/positioning.md
+++ b/notes/positioning.md
- sgit is a CLI for encrypted sync
+ sgit is git for encrypted vaults

$sgit push
✓ Pushed 2 objects (delta push — only changed, only ciphertext)

# on another machine (or another agent)
$sgit clone <vault-key>
✓ Cloned and decrypted 12 files

$sgit pull
✓ Up to date

# one call: encrypt, commit, push, machine-readable result —
# no working-directory scan, no full clone needed
$sgit write notes/finding.md --file result.md \
 --message "agent A: analysis" --push --json
 {
"status": "pushed",
"path": "notes/finding.md",
"blob_id": "obj-cas-imm-9c2e41ab77d0"
 }

The vault key is the address, the auth, and the encryption key — one high-entropy string. Keep it safe.

## Git workflows. Encrypted vaults. Zero knowledge.

sgit is git for encrypted vaults: clone, commit, branch, diff and merge folders of files that are encrypted with AES-256-GCM before they leave your machine.

**Git-like version control**commit, branch, merge, diff, log, stash, revert your encrypted files

**Client-side encryption**AES-256-GCM before upload; keys derived from your vault key, never sent to the server

**Real three-way merge**conflict files plus a base/ours/theirs `resolve --show` view

**The two-branch model**a private clone branch per machine or agent; shared named branches for collaboration

**Sparse & thin clones**structure now, content on demand — for agents on a time budget

**Browser interop**open the same vault in SG/Vault on the web — CLI and browser speak one wire format

## What the server sees

### Your machine

- filenames & folder structure
- file contents
- commit messages
- branch names
- the vault key & derived keys

*[diagram]*

### The server

- obj-cas-imm-3f9c41ab77d0
- ref-pid-muw-8e02cc194b3a
- ciphertext blobs (AES-256-GCM)
- object sizes · timestamps
- the vault id

That's the whole list — and we publish the threat model, including what the server *can* see (sizes, timing, vault ID). [Read the security model →](security/index.md)

## Built for agents

Agents need shared state. Shared state needs versioning — and privacy. sgit is the encrypted, versioned workspace for humans and AI agents.

Persistent memory

### A vault is just a folder

An agent clones it, reads and writes files normally, commits, pushes. The next session pulls and continues. State survives the context window.

Multi-agent, human-merged

### A branch per agent

Each agent gets its own private clone branch; work meets on named branches; a human reviews the merge — in the terminal or in the SG/Vault browser.

Agent-grade plumbing

### Machine-readable everything

`sgit write` for surgical single-call commits, `--json` on every read path, `cat --id` with zero network calls, sparse clones for fast cold starts.

[Read the agent guide →](docs/agents.md) · [Install the skills →](skills/index.md) · [llms.txt](llms.txt)

## What people use it for

[Use case### Private memory for AI agentsDurable, versioned state between sessions — encrypted end to end.Read →](use-cases/index.md#ai-agents)

[Use case### Multi-agent collaborationAgents on their own branches, humans reviewing the merge.Read →](use-cases/index.md#multi-agent)

[Use case### Human ↔ agent workspacesYou in the SG/Vault browser, the agent in the CLI — same vault.Read →](use-cases/index.md#human-ai)

[Use case### Encrypted folders with historyA shared folder the hosting provider cannot read, with rollback.Read →](use-cases/index.md#encrypted-backup)

[Use case### Signed & encrypted exchangePKI: sign, verify, encrypt and decrypt files for named recipients.Read →](use-cases/index.md#secure-file-exchange)

## In production — and honest about it

sgit is in beta, powering production workflows daily. No superlatives — just the evidence, and a page that tells you when *not* to use it.

**~4,000** tests**mutation testing** in CI**integration tests** against a real server**2** runtime dependencies**Apache-2.0** [**security model** published](security/index.md) [**when NOT** to use sgit](docs/limitations.md) [**why** does this exist?](why/index.md)

## One vault, three doors

Think of it as

**sgit** — git, for encrypted vaults

Open source CLI. Free. Apache-2.0. `pip install sgit-ai`

Think of it as

**SG/Vault** — the web app for your vaults

Browse, edit and review the same vaults in the browser — an independent implementation of the same wire format.

[Platform docs →](vault/index.md) · [sgraph.ai](https://sgraph.ai)

Think of it as

**SG/Send** — the transfer API underneath

The zero-knowledge storage service both clients speak to — the same server the integration tests run against.

[Platform docs →](vault/index.md) · [sgraph.ai](https://sgraph.ai)

Encrypted vaults. **Git workflows.** Zero knowledge.

[5-minute quickstart →](docs/quickstart.md) [Star on GitHub →](https://github.com/SGit-AI/SGit-AI__CLI)



==============================================================================
# The vault catalogue — sgit.ai

> An index of published vaults rendered live from a vault that indexes vaults, including itself. Each entry: a deliberately published read key, shape, evidence status, copy-or-reference semantics, and write-key status (known-and-escrowed or lost — a frozen vault can never be corrected). Submitting a vault costs a read key and one line; the rest is derived.
>
> Page: https://sgit.ai/catalogue/index.html

[Home](../index.md) / Catalogue

# The vault catalogue

An index of published vaults, rendered live from a vault that indexes vaults — including itself. Every entry carries a deliberately published read key, an honest evidence status, and its write-key status, because a vault whose write key is lost can never be corrected and a reader deserves to know.

**The design constraint, stated openly:** the bottleneck is one person with a backlog of vaults, so an entry costs **a read key and one line** — everything else (listing, sizes, commit count, whether an app is present) is derived by an agent opening the vault with the key it was just given. The two to-do queues are published in the catalogue itself: a named gap gets filled, an unnamed one does not. This page renders vault `kc67yhgw` directly — a push to it updates this page with no site deploy. The human companion is [the published-vaults gallery](../demos/vaults/index.md): one page per vault, with the vault running live in it.

opening the catalogue…

Fetching the encrypted index…

### Vault debug [how this works →](../case-studies/live-vault-docs.md)

not open yet

what you are looking at

 Every row above is an encrypted object pulled from the SG/Send API and decrypted locally — click one to see what it actually contains. Objects whose id contains **-imm-** are content-addressed and therefore immutable, so they are cached permanently; the mutable **ref** is the one mutable object, so it is checked at most once per freshness window (120s) rather than once per page — inside the window, reading the docs makes no requests at all, and **check for new commit** forces one whenever you want it.

The **tree** objects are the reason a first visit reads more than one file: filenames are encrypted inside them, so building the navigation means reading every directory. That index is a pure function of the commit id, so it is memoised — after the first visit, an unchanged commit reads no tree objects at all. Nothing here is stored on sgit.ai.

[How this page works →](../case-studies/live-vault-docs.md) Architecture diagrams, the object model, the cache tiers, and how a page like this one reads a vault it holds only the read key to.



==============================================================================
# Comparisons, as tests you can re-run — sgit.ai

> What a task costs with vaults and without, published by a participant and built to be challenged: every entry states the steps, the date, the result and how to re-run it. Includes a privilege vocabulary, and one comparison vaults lose.
>
> Page: https://sgit.ai/compare/index.html

[Home](../index.md) / Comparisons

# Comparisons, as tests you can re-run

What a task costs with vaults, and without them. This page is not unbiased — it is published by a participant, and nobody should read it as neutral. It is built to be **challengeable** instead: every entry states the exact steps attempted, the date, what happened, and how to run it yourself.

**Why not "unbiased".** A comparison published by one of the parties is not a neutral instrument, and claiming otherwise would be the least credible thing on this site. The achievable and stronger property is reproducibility: **an assertion that is wrong gets screenshotted; an experiment that is wrong gets corrected.** If an entry here is out of date or simply mistaken, the fix is a re-run, and the correction improves the page rather than discrediting it. [Tell us](mailto:) or open an issue on [GitHub](https://github.com/SGit-AI/SGit-AI__CLI).

## The asymmetry, stated up front

Our rows can be **executed**. A script opens a published vault, tries the operation and records what happened — it runs on demand and fails loudly when reality moves. Rows about anybody else's product cannot work that way: there is no API for "how many steps does this take in a desktop app", and automating someone's product against their terms is not something we will do. Those rows are **checked by hand, by a person, on a stated date**.

So the two kinds of row carry different badges, and you should trust them differently:

| Badge | Means | Ages |
|---|---|---|
| **machine-verified** | An automated check against the live service, in `admin/build/compare_tests.py`. The evidence below each claim is its actual output | Re-run any time; the date is the last run |
| **hand-checked** | A person performed the steps on the date shown and wrote down what happened | Decays. Past the expiry it renders as **unverified**, not as fact |

Loading verification status…

## The entry format

Every entry answers the same eight things. Anything that cannot be filled in honestly does not get published.

| Field | Why it is there |
|---|---|
| **Task** | Stated concretely enough that somebody can attempt it |
| **Steps** | Countable and disputable on facts. The number is a *summary*; the transcript below it is the evidence, because step counts are gamed by where you start counting |
| **Prerequisites** | Accounts, subscriptions, installs. This is where cost actually lands |
| **Privileges granted** | What the counterparty can now reach. The column that usually decides the answer — see the vocabulary below |
| **Where it runs** | Your machine, or theirs |
| **Survives the vendor** | Whether the artefact still works if the service stops |
| **Verified** | The date, and whether by machine or by hand |
| **Re-run it** | The command or the steps, so the claim is auditable rather than trusted |

## The privilege vocabulary

"Share it with them" hides the entire question. These seven properties make two grants comparable, and each is a fact rather than a judgement. This vocabulary is the part of this page most likely to be wrong at first — it is offered to be argued with.

| Property | Values | What it answers |
|---|---|---|
| **scope** | file · folder · vault · account · all-vaults | How much does the grant reach? |
| **operations** | read · write · delete · administer | What can be done with it? |
| **bearer** | person · program-on-their-machine · vendor-server · any-holder | Who actually holds it? "any-holder" means the grant is a string: whoever has it, has it |
| **mediation** | server-enforced · key-enforced | Who says no? A server can refuse and can log. A key cannot refuse — possession *is* access |
| **duration** | session · until-withdrawn · forever | When does it lapse on its own? |
| **withdrawal** | effective · future-only · none | Can you take it back — and does taking it back reach what they already have? |
| **observability** | per-reader-log · aggregate · none | Can you see who read what? |

Written compactly, a published read key is: `scope:vault · ops:read · bearer:any-holder · mediation:key · duration:forever · withdrawal:future-only · observability:none`. Three of those seven are **worse** than a mainstream sharing link, and saying so is the point of having a vocabulary.

**One shape the vocabulary above could not express, until a vault demonstrated it.** An app can be granted the *use* of a credential without being given the credential: the [Risk Mandate vault](../demos/vaults/risk-mandate/index.md) seals its OpenRouter key under the vault key, and the host makes the call on the app's behalf. So `ops` and `bearer` come apart — `ops:llm-chat` is granted while `bearer` of the key is not, and a read-key holder auditing the vault (as we did) finds ciphertext where the secret would be. Most sharing models cannot say this, because handing over the capability and handing over the credential are the same act.

## The entries

Three to start with, chosen to be different: one small and verifiable in seconds, one we lose, one that is the actual differentiator. More arrive as they are tested — not as they are thought of.

### 1 · Print a markdown file that somebody sent you

Small, universally understood, checkable in under a minute — the kind of entry that earns the credibility the larger claims spend.

|  | A markdown file in a vault | A markdown file on your disk |
|---|---|---|
| **Steps** | **2** — open the file in the vault UI (it renders), press **Print** | **3–5**, depending on what you already have: many editors render markdown but print the *source*; the common workarounds are convert-to-HTML, paste into a browser, or install something |
| **Prerequisites** | A browser | An editor that both renders *and* prints, or a converter, or an online tool |
| **Privileges granted** | None beyond the key you already hold | None — *unless* you use an online converter, which is `scope:file · ops:read · bearer:vendor-server · withdrawal:none`. Uploading a document to a stranger to reformat it is a privilege grant that does not feel like one |
| **Where it runs** | Your browser; the print component renders locally | Your machine, or a stranger's |
| **Verified** | **hand-checked, 2026-08-16** — the vault UI exposes a **Print** control on an open markdown file, backed by `SgPrint.printMarkdown`; confirmed present and reachable in a browser driven with a published read key |
| **Re-run it** | Open `https://dev.vault.sgraph.ai/#sgit_rk1_0a0f34839d737eef0f8f66e5236990b1f397af064763e3f71dca2717015f9d15:3d04e6b9ca98`, go to the vault browser, click `README.md`, look for **Print**. For the other column, take any `.md` file and try to produce a formatted page with whatever you already have installed — count what it takes |

**What would change this entry:** an editor that renders and prints markdown in one action, which several are close to. If you know one, that column's step count should drop and this entry should say so.

### 2 · Take access back after you have shared something we lose this one

A comparison where our column always wins is discounted on sight, so here is one where the mainstream answer is straightforwardly better.

|  | A vault, shared by read key | A hosted document, shared by link |
|---|---|---|
| **Steps to withdraw** | **Rotate the key and re-publish.** Future commits are protected | **1–2** — remove the share; the next request is refused |
| **Does it reach what they already have?** | **No.** Anything already fetched stays readable forever, with no way to reach it | **Largely yes** — unless they exported or screenshotted, the server stops serving it |
| **privileges** | `withdrawal:future-only · mediation:key · observability:none` | `withdrawal:effective · mediation:server-enforced · observability:per-reader-log` |
| **Why** | Possession of a key *is* access, so there is no server in the loop to refuse a later request. The objects are content-addressed and immutable — the same id returns the same bytes forever, which is exactly what makes an already-taken copy permanent |
| **Verified** | **machine-verified** — the immutability that causes this is checked automatically (`objects-immutable` below). The hosted-side behaviour is **hand-checked, 2026-08-16**, and is the ordinary documented behaviour of mainstream sharing |
| **Re-run it** | `python3 admin/build/compare_tests.py` — the immutability check fetches one object twice and compares bytes |

**The honest summary:** if the ability to revoke access after the fact matters more to you than the host being unable to read your content, a server-mediated platform is the better tool and you should use one. Vaults trade revocation for the host knowing nothing. That is a real trade, not a free win.

### 3 · Let a program record data for you without letting it change your records

The differentiator. Note that the step counts are similar — it is the privileges column that separates these, which is why it is the column to lead with.

|  | A vault app | An assistant with folder access |
|---|---|---|
| **Steps** | Declare the grant in `app.json` and open the vault | Grant access to the folder, then run it |
| **Privileges granted** | `scope:folder(adherence/) · ops:write,mkdir · mediation:key+host` — read broadly, but write to **one folder**. The app cannot alter the records it reports on | Typically `scope:folder · ops:read,write · bearer:vendor-server` for the whole shared folder — the granularity available is the folder you shared |
| **Where it runs** | Your browser, in a sandboxed frame with an opaque origin | Usually the vendor's infrastructure, with your files sent to it |
| **Survives the vendor** | The data is files with a documented layout; the reader is replaceable (we wrote a ~170-line one to prove it) | The conversation and any generated artefacts live where the vendor put them |
| **Verified** | **machine-verified** — `scoped-write-declared` below reads the live vault's `app.json` and asserts the write scope is exactly `["adherence/"]`. The comparison column is **hand-checked, 2026-08-16** and describes the general shape of folder-level sharing, which varies by product — corrections welcome, per-product rows to follow |
| **Re-run it** | Open the [Supplement Stack vault](../demos/vaults/supplement-stack/index.md) and read its `app.json`, or run `python3 admin/build/compare_tests.py` |

**The caveat that keeps this honest:** read granularity is coarser than write granularity here. A read key opens the *whole vault*, not one file. Finer read boundaries mean separate vaults with separate keys, decided in advance — granularity costs structure. If you need per-file read control without pre-planning the shape, this is not yet the tool.

## The checks behind the machine-verified rows

These run against the live service using only published read keys, and each states what would make it fail — a test that cannot fail is not evidence.

Loading results…

## What is deliberately not here

| Not here | Why |
|---|---|
| Anything we plan to ship | A comparison page is exactly where planned capability must not sit beside shipped capability. One unshipped row and a reader re-reads every other row as marketing |
| Ease-of-use scores | A judgement published by a participant is the thing this page cannot defend. Steps, prerequisites and privileges are facts |
| A deployment-features comparison | It would be the most linked and the fastest to rot, and our own story has a caveat worth resolving first: a vault's files are portable, but the polished viewer is currently one hosted implementation |
| A maturity model | Those score an organisation's practice over time. This scores a task against a tool stack on a date — a different instrument |



==============================================================================
# Published vaults — sgit.ai

> Every vault whose read key sgit.ai has deliberately published: what each does, the features it uses, and the vault running live in the page. A read key is the complete credential — no account, no write capability.
>
> Page: https://sgit.ai/demos/vaults/index.html

[Home](../../index.md) / Vaults

# Published vaults

Every vault whose read key this site has deliberately published — with, for each one, a page describing what it does, the features it uses, what the shape is good for, and the vault itself running live inside the page. The keys below are the complete credential: no account, no token, and no write capability anywhere in them.

**Publishing one of your own?** [**The method is written down**](publishing.md) — the seven steps behind every row below, the tools that do each one, and the mistakes that produced each rule. Written to be followed by another site's agent.

**Intake, since it nearly went wrong.** A credential submitted for publication here was once a **vault key** described as a read key — a legacy `passphrase:vault_id` form with no prefix to give it away. It was caught, only the derived read key was published, and nothing leaked; but the catch depended on somebody looking. Every submission now runs through `admin/build/check_credential.py` first, which refuses a write credential by **prefix** (`sgit_vk1_`, which new vaults emit) or, for anything older, by **shape** — a read key is 64 hex characters, and anything else before the colon is a passphrase. Prefixes are the better answer; the shape check covers the years of keys created before them.

**The two rules, applied to every row.** Read keys yes, vault keys never — a read key is a capability we hand out on purpose, and it cannot become write access. And every vault is audited before its key appears here, because content travels with the key forever; findings are published on the vault’s page, not filed away.

| Vault | Id | Shape | Contents | Published read key |  |
|---|---|---|---|---|---|
| [Field Notes](field-notes/index.md) | `4bshby5n` | application (vault app) | 4 files · 11 KB · 2 commits · app entry `index.html` | `sgit_rk1_2848993a68c02a33ea5582902c391901191e53680d35b36c0e76185d4107ad81:4bshby5n` | [open live ↗](https://dev.vault.sgraph.ai/#sgit_rk1_2848993a68c02a33ea5582902c391901191e53680d35b36c0e76185d4107ad81%3A4bshby5n) |
| [Strategy Maps](strategy-maps/index.md) | `ookq4mn4` | structured analysis (two apps, one vault) | 33 files · 830 KB · 3 commits · app entries `index.html` and `sgit-maps.html` | `sgit_rk1_451c4c1e28fbb24a7f350bb3f107b2c103d69ed363167029ef9c9000ff76c07b:ookq4mn4` | [open live ↗](https://dev.vault.sgraph.ai/#sgit_rk1_451c4c1e28fbb24a7f350bb3f107b2c103d69ed363167029ef9c9000ff76c07b%3Aookq4mn4) |
| [Deploy Docs](deploy-docs/index.md) | `fyofmkvr` | record-keeping (live markdown) | 17 files · 25 KB · 2 commits · markdown, no app | `sgit_rk1_8d01421290efc3fa03205eced0534335a06ae209d627555b3dde136b878e3de1:fyofmkvr` | [open live ↗](https://dev.vault.sgraph.ai/#sgit_rk1_8d01421290efc3fa03205eced0534335a06ae209d627555b3dde136b878e3de1%3Afyofmkvr) |
| [The Vault Catalogue](catalogue/index.md) | `kc67yhgw` | record-keeping (an index of vaults) | 9 files · 11 KB · 2 commits · markdown, no app | `sgit_rk1_fd71e4bde7232498e43a5da869b1501260d9d403031b20af87b5bc801bdf6280:kc67yhgw` | [open live ↗](https://dev.vault.sgraph.ai/#sgit_rk1_fd71e4bde7232498e43a5da869b1501260d9d403031b20af87b5bc801bdf6280%3Akc67yhgw) |
| [Algarve · May 2026](algarve-may-2026/index.md) | `3d04e6b9ca98` | gallery (photo story) | 71 files · 29 MB · 36 commits · app entry `index.html` | `sgit_rk1_0a0f34839d737eef0f8f66e5236990b1f397af064763e3f71dca2717015f9d15:3d04e6b9ca98` | [open live ↗](https://dev.vault.sgraph.ai/#sgit_rk1_0a0f34839d737eef0f8f66e5236990b1f397af064763e3f71dca2717015f9d15%3A3d04e6b9ca98) |
| [Supplement Stack](supplement-stack/index.md) | `r7zes477` | record-keeping (patient-held health record) | 23 files · 2.3 MB · 5 commits · app entry `index.html` | `sgit_rk1_047186b559528058c66d1792b7345639b1238cb95c166d1d5f5b65c59813c2ee:r7zes477` | [open live ↗](https://dev.vault.sgraph.ai/#sgit_rk1_047186b559528058c66d1792b7345639b1238cb95c166d1d5f5b65c59813c2ee%3Ar7zes477) |
| [Risk Mandate](risk-mandate/index.md) | `4zf6pf2z` | application (a software project in a vault) | 124 files · 1.9 MB · 98 commits · 8 app entries | `sgit_rk1_a702fba803faac4369eb5d5a320b4dfa017af62bd2425fb298aac4b99e95c0ae:4zf6pf2z` | [open live ↗](https://dev.vault.sgraph.ai/#sgit_rk1_a702fba803faac4369eb5d5a320b4dfa017af62bd2425fb298aac4b99e95c0ae%3A4zf6pf2z) |
| [Agentic Browser Isolation](agentic-browser-isolation/index.md) | `0610gsp9` | structured analysis (a living risk graph) | 104 files · 2.4 MB · 4 commits · 17 app entries | `sgit_rk1_92cad4cea8f58c55f59b686c71c935225a1ba7c41ecb6922a8aa570467604f6e:0610gsp9` | [open live ↗](https://dev.vault.sgraph.ai/#sgit_rk1_92cad4cea8f58c55f59b686c71c935225a1ba7c41ecb6922a8aa570467604f6e%3A0610gsp9) |
| [Risk Graph Explorer](risk-graph-explorer/index.md) | `3simlnqe` | application (public by design) | 33 files · 428 KB · 7 commits · 1 app entry | `sgit_rk1_1c1b95f5903e35850a9bc0541ffa09c6b5d4017cbf18817d2ad6f894127e5638:3simlnqe` | [open live ↗](https://dev.vault.sgraph.ai/#sgit_rk1_1c1b95f5903e35850a9bc0541ffa09c6b5d4017cbf18817d2ad6f894127e5638%3A3simlnqe) |
| [Regulation Graph](regulation-graph/index.md) | `73heuprz` | reference data (regulation as an evidence graph) | 207 files · 14.9 MB · 2 commits · 11 app views | `sgit_rk1_c004daae386e8d17fa648884acc527018bd4ea1116ad673fb2f1b068011695c9:73heuprz` | [open live ↗](https://dev.vault.sgraph.ai/#sgit_rk1_c004daae386e8d17fa648884acc527018bd4ea1116ad673fb2f1b068011695c9%3A73heuprz) |

The machine-first version of this list is [the catalogue](../../catalogue/index.md) — an index of vaults that is itself a vault, updated by an sgit push with no site deploy. New entries start there: a read key and one line, the rest derived. The walkthrough of how a vault gets published at all — creation, audit, deliberate key publication, embed — is on [the embed demo page](../vault-app-embed.md).



==============================================================================
# Publishing a vault: the method — sgit.ai

> The seven steps behind every vault published here, written for another agent to follow: classify the credential before it touches anything, derive rather than refuse, audit with the read key, derive the facts, capture evidence by driving the real product, write the page, and record what outlives it — plus the mistakes that produced each rule.
>
> Page: https://sgit.ai/demos/vaults/publishing.html

[Home](../../index.md) / [Vaults](index.md) / Publishing a vault

# Publishing a vault: the method

Every vault in this section went through the same seven steps. This page is that method written down so another site — or another agent — can follow it. It is deliberately specific: the commands are real, the tools are in this repo, and the rules are the ones learned by nearly getting them wrong.

**Who this is for.** An agent maintaining a site that publishes vaults. Read the [markdown twin](publishing.md) if you are one. The tooling referenced lives in `admin/build/` of the sgit.ai repository and is small enough to copy rather than depend on.

## The two rules everything else serves

| Rule | Why it is absolute |
|---|---|
| **Read keys yes, vault keys never** | A read key is a capability handed out on purpose and cannot become write access. A vault key is read *and* write; publishing one hands the vault to anybody |
| **Audit before the key, not after** | Revocation is not retroactive. Anyone who fetches the objects keeps them, so an audit that happens after publication has not happened |

## 1 · Classify the credential before it touches anything

Do this first, before the credential is pasted into a page, a script or a commit. Credentials arrive mislabelled — it has happened three times here, each time a vault key described as a read key.

```
python3 admin/build/check_credential.py '<credential>'
# exit 0 → read-only, safe to publish
# exit 1 → write credential (or unrecognised) — stop
```

It classifies two ways, because the problem has two eras: by **prefix** for vaults new enough to emit one, and by **shape** for everything older — a read key is 64 hex characters, and anything else before the colon is a passphrase, which means write.

## 2 · If it is a vault key, derive rather than refuse

A vault key does not block publication; it changes what you publish. Store it where the repository cannot commit it, then derive:

```
# the gitignored tier — the release tripwire then scans every tracked file for it
printf '%s' "$VAULT_KEY" > .sg_vault/local/demo-keys/<name>-vault-key

python3 - <<'PY'
from sgit_ai.crypto.Vault__Crypto import Vault__Crypto
c = Vault__Crypto()
pw, vault_id = c.parse_vault_key(open('.sg_vault/local/demo-keys/<name>-vault-key').read().strip())
print(c.derive_keys(pw, vault_id)['read_key'])     # publish only this
PY
```

The derivation is one-way: a published read key cannot be turned back into the vault key. Never print the write key; never let the vault key reach a tracked file.

## 3 · Audit with the read key, across every file

Open the vault with the *read* key — the credential your readers will have — and scan every text file. Look for: the vault's own key (this has really happened, and forced a republish), API keys, tokens and `delete_auth` values, private-key blocks, personal data, and operational bookkeeping under `.vault/`.

**Ruling hits out is the work.** Scanners produce false positives and that is normal: a phone-number pattern matching `0123456789` inside a minified library; an `sk-test-…` string that turns out to be a fixture in a test asserting a leaked key *is* caught. Read every hit. Publish the interesting ones — a finding explained is worth more than a clean sheet asserted.

## 4 · Derive the facts rather than describing them

```
python3 admin/build/catalogue_derive.py <vault_id> <read_key>
```

File count, size, commit depth, HEAD, top-level layout, file types, app entry points and browser-renderability — all from the read key, no token and no clone. A human supplies only what a human knows: what it is for, and whether it is production or a sketch.

## 5 · Capture evidence by driving the real product

Screenshots should be of the actual vault, produced by a script that opens it with the published read key and performs the navigation being described. Mock-ups age into lies; a capture script re-runs.

```
node admin/build/capture_shots.mjs --vault <slug>
```

Each shot declares a surface (the app, or the vault browser), the steps, and the crop. Steps can click in the app frame, drive shadow-DOM controls, type into the debug REPL, expand folders or switch views. Store the images beside the page — `demos/vaults/<slug>/images/` — so a vault's folder is self-contained.

## 6 · Write the page: describe, then show, then admit

| Section | What goes in it |
|---|---|
| Lead + why this one | What the vault is, and the one thing it demonstrates that others do not |
| The credential, in the open | The read key, a CLI command, and a link that opens it in the official UI. Say plainly that it grants read and only read |
| Live embed | Both surfaces, opened over the embed protocol so the key never enters a URL or the frame's storage |
| Walkthrough rows | Alternating prose and screenshot, one row per non-obvious thing. This is where a reader learns what a live embed cannot tell them |
| What it demonstrates | A feature table naming the mechanism, not the marketing |
| **The audit, honestly** | What was scanned, what was found, and what it means. Findings included |
| Derived facts | Step 4's output, with the tool named so it can be re-run |

## 7 · Record the things that outlive the page

Per entry: the **shape** (the workflow it resembles, not its domain), the **evidence status** (production, demonstration, or sketch), whether it is a copy or a live reference, and the **write-key status** — escrowed or lost. A vault whose write key is lost is frozen: readable forever, never correctable. Say so where a reader will see it.

## What we got wrong, so you do not have to

| Mistake | The rule that came out of it |
|---|---|
| A vault published its own write credential inside its content | **Republish, don't retrofit.** A sanitised copy into a fresh vault also sheds the history you cannot publish |
| A vault key submitted as a read key, three times | Classification is a check, not a habit — step 1 |
| A test reported a refusal that was really a truncated clone | Re-run before recording. A result you cannot reproduce is not evidence |
| Our own tripwire banned the string we needed in order to teach people to recognise it | Make the rule *precise*, not stricter: fire on the prefix plus a credential character, so documentation can name it |
| A read key was published in front of a vault carrying an LLM config | Check, do not assume: we attempted to unseal it with the published read key, and AES-GCM refused. State the result either way |

The best statement of the vault-side rules is not ours: the [Risk Graph Explorer](risk-graph-explorer/index.md) carries a `PUBLIC.md` whose three build-enforced rules — nothing private committed, no write token, **no metered capability** — are the version to copy if you are building a vault intended for publication.

## The tools, in one list

| Tool | Does |
|---|---|
| `admin/build/check_credential.py` | Classifies a credential; exit code says publish or stop |
| `admin/build/catalogue_derive.py` | Read key → the facts, read-only and no token |
| `admin/build/capture_shots.mjs` | Drives the live vault and crops evidence screenshots |
| `admin/build/validate.js` | The release gate, including the key-leak tripwire |
| `admin/build/compare_tests.py` | Executes the claims that can be executed, with dates |



==============================================================================
# Field Notes — a published vault

> The minimum viable published vault: six studies with generative SVG art as a self-contained vault app, read over the sg.vfs bridge, opened by a single published read key.
>
> Page: https://sgit.ai/demos/vaults/field-notes/index.html

[Home](../../../index.md) / [Vaults](../../../index.md) / Field Notes

# Field Notes

Six small studies — a note and a generative SVG drawing each — served as a self-contained vault app.

**Open it yourself — the key is the whole credential.**
 Read key: `sgit_rk1_2848993a68c02a33ea5582902c391901191e53680d35b36c0e76185d4107ad81:4bshby5n`
 In the official UI: [open it read-only in a new tab](https://dev.vault.sgraph.ai/#sgit_rk1_2848993a68c02a33ea5582902c391901191e53680d35b36c0e76185d4107ad81%3A4bshby5n) · From the CLI: `sgit clone sgit_rk1_2848993a68c02a33ea5582902c391901191e53680d35b36c0e76185d4107ad81:4bshby5n`
Published deliberately. It grants read, and only read — a write attempt is refused by the server’s write gate (the **R1 W0** badge you will see in the chrome).

## See it live, here

## What this vault demonstrates

| Feature | How this vault uses it |
|---|---|
| Vault app (`app.json`) | one self-contained `index.html`, auto-opened; CSS and JS inlined per the authoring contract |
| `sg.vfs` bridge | the app reads `content.json` over the bridge at runtime — the status line in the app proves it |
| Generative SVG | the six drawings are code, not images — no binary assets to fetch |
| Published read key | the first vault created specifically to be published; the complete walkthrough is on [the embed demo page](../../vault-app-embed.md) |

## What this shape is for

The minimum viable published vault: content plus a small app, one key, no server that can read any of it. Use this shape for anything you would put on a small static site — except the host serves only ciphertext, and unpublishing is deleting one credential from a page rather than tearing down a site.

## Derived facts

4 files · 11 KB · 2 commits · app entry `index.html` · derived from the read key alone by `admin/build/catalogue_derive.py` — the same derivation that populates [the catalogue](../../../catalogue/index.md), where this vault also has an entry.



==============================================================================
# Strategy Maps — a published vault

> The SG/Send strategy in seven Wardley maps plus the sgit positioning analysis — two app entry points in one encrypted vault, published after the audit that made a republish necessary.
>
> Page: https://sgit.ai/demos/vaults/strategy-maps/index.html

[Home](../../../index.md) / [Vaults](../../../index.md) / Strategy Maps

# Strategy Maps

The SG/Send strategy in seven Wardley maps, plus the sgit positioning analysis as a second app in the same encrypted store.

**Open it yourself — the key is the whole credential.**
 Read key: `sgit_rk1_451c4c1e28fbb24a7f350bb3f107b2c103d69ed363167029ef9c9000ff76c07b:ookq4mn4`
 In the official UI: [open it read-only in a new tab](https://dev.vault.sgraph.ai/#sgit_rk1_451c4c1e28fbb24a7f350bb3f107b2c103d69ed363167029ef9c9000ff76c07b%3Aookq4mn4) · From the CLI: `sgit clone sgit_rk1_451c4c1e28fbb24a7f350bb3f107b2c103d69ed363167029ef9c9000ff76c07b:ookq4mn4`
Published deliberately. It grants read, and only read — a write attempt is refused by the server’s write gate (the **R1 W0** badge you will see in the chrome).

## See it live, here

## What this vault demonstrates

| Feature | How this vault uses it |
|---|---|
| Two app entry points | `index.html` (the strategy essay, eight Wardley map PNGs) and `sgit-maps.html` (six inline-SVG maps) — one encrypted store, two front doors |
| Vault-path images | the essay’s PNGs travel as ciphertext and are swapped in as `blob:` URLs after decryption |
| Republish pattern | this vault is a sanitised republish: the original could not publish its key because a write credential was inside its content — [the audit is public](../../strategy-maps.md) |
| Cross-app links | the two apps link to each other and the links survive embedding |

## What this shape is for

Published analysis with real assets: strategy documents, briefs, decks. The two-entry-point trick means one vault can carry a family of related documents that share content, history and a single published key.

## Derived facts

33 files · 830 KB · 3 commits · app entries `index.html` and `sgit-maps.html` · derived from the read key alone by `admin/build/catalogue_derive.py` — the same derivation that populates [the catalogue](../../../catalogue/index.md), where this vault also has an entry.



==============================================================================
# Deploy Docs — a published vault

> The living deployment documentation for sgit.ai: markdown written by two Claude Code sessions, rendered live in the visitor’s browser, updated by an sgit push with no site deploy.
>
> Page: https://sgit.ai/demos/vaults/deploy-docs/index.html

[Home](../../../index.md) / [Vaults](../../../index.md) / Deploy Docs

# Deploy Docs

The living deployment documentation for sgit.ai itself — written by two Claude Code sessions, rendered live on the /deploy page.

**Open it yourself — the key is the whole credential.**
 Read key: `sgit_rk1_8d01421290efc3fa03205eced0534335a06ae209d627555b3dde136b878e3de1:fyofmkvr`
 In the official UI: [open it read-only in a new tab](https://dev.vault.sgraph.ai/#sgit_rk1_8d01421290efc3fa03205eced0534335a06ae209d627555b3dde136b878e3de1%3Afyofmkvr) · From the CLI: `sgit clone sgit_rk1_8d01421290efc3fa03205eced0534335a06ae209d627555b3dde136b878e3de1:fyofmkvr`
Published deliberately. It grants read, and only read — a write attempt is refused by the server’s write gate (the **R1 W0** badge you will see in the chrome).

## See it live, here

## What this vault demonstrates

| Feature | How this vault uses it |
|---|---|
| Live markdown rendering | [the /deploy page](../../../deploy/index.md) decrypts and renders this vault in the visitor’s browser — a push here updates that page with no site deploy |
| Freshness window | the mutable HEAD pointer is checked at most once per 120 s; everything else is content-addressed and cached forever |
| Two writers | written by two Claude Code sessions collaborating through the vault — the commit history shows the handoffs |
| Debug panel | the page’s vault panel shows every encrypted object arriving and what it decrypts to |

## What this shape is for

Documentation that updates without a deploy pipeline, from any writer who holds the vault key, to any reader who holds the read key. The natural shape for runbooks, guides and anything agents co-author.

## Derived facts

17 files · 25 KB · 2 commits · markdown, no app · derived from the read key alone by `admin/build/catalogue_derive.py` — the same derivation that populates [the catalogue](../../../catalogue/index.md), where this vault also has an entry.



==============================================================================
# The Vault Catalogue — a published vault

> The index of published vaults, itself a vault, listed in itself — a submission queue where an entry costs a read key and one line, with published to-do lists and first-class write-key status.
>
> Page: https://sgit.ai/demos/vaults/catalogue/index.html

[Home](../../../index.md) / [Vaults](../../../index.md) / The Vault Catalogue

# The Vault Catalogue

The index of published vaults — itself a vault, published with a read key, and listed in itself.

**Open it yourself — the key is the whole credential.**
 Read key: `sgit_rk1_fd71e4bde7232498e43a5da869b1501260d9d403031b20af87b5bc801bdf6280:kc67yhgw`
 In the official UI: [open it read-only in a new tab](https://dev.vault.sgraph.ai/#sgit_rk1_fd71e4bde7232498e43a5da869b1501260d9d403031b20af87b5bc801bdf6280%3Akc67yhgw) · From the CLI: `sgit clone sgit_rk1_fd71e4bde7232498e43a5da869b1501260d9d403031b20af87b5bc801bdf6280:kc67yhgw`
Published deliberately. It grants read, and only read — a write attempt is refused by the server’s write gate (the **R1 W0** badge you will see in the chrome).

## See it live, here

## What this vault demonstrates

| Feature | How this vault uses it |
|---|---|
| Recursion, usefully | an index of published vaults that is itself a published vault, listed in itself — [rendered live at /catalogue/](../../../catalogue/index.md) |
| Submission queue | an entry costs a read key and one line; everything else is derived by an agent opening the vault |
| Published to-do lists | `todo/awaiting-read-key.md` and `todo/awaiting-processing.md` are public, because a named gap gets filled |
| First-class write-key status | every entry records whether the write key is escrowed or lost, because a frozen vault can never be corrected |

## What this shape is for

Machine-and-human-readable registries that update by pushing to a vault rather than deploying a site. The schema here is deliberately the first instance of what a vault hub would need.

## Derived facts

9 files · 11 KB · 2 commits · markdown, no app · derived from the read key alone by `admin/build/catalogue_derive.py` — the same derivation that populates [the catalogue](../../../catalogue/index.md), where this vault also has an entry.



==============================================================================
# Supplement Stack — a published vault

> A patient-held health record as a vault: a real supplement regimen, label photographs every extracted value is traceable to, deterministic totals against UK RNIs and EFSA upper limits, and an adherence log the app may write to and nothing else. Shared with a professional by handing over a read key.
>
> Page: https://sgit.ai/demos/vaults/supplement-stack/index.html

[Home](../../../index.md) / [Vaults](../index.md) / Supplement Stack

# Supplement Stack

A patient-held health record as a vault: a real supplement regimen, a photograph of every label the numbers were read from, deterministic totals against UK reference values — and an app permitted to write to exactly one folder and nothing else.

**The idea it is built on, in one line.** Every label describes one product; **nothing describes the sum**. The missing artefact is the total per nutrient across everything a person is taking — so the model extracts (fuzzy, and traceable to a label photo), the code adds up (deterministic, and reproducible), and the output is a briefing for somebody qualified. **Never a verdict.** This is a record-keeping tool, not medical advice, and no compliance finding of any kind exists for this pattern.

**Open it yourself — the key is the whole credential.**
 Read key: `sgit_rk1_047186b559528058c66d1792b7345639b1238cb95c166d1d5f5b65c59813c2ee:r7zes477`
 In the official UI: [open it read-only in a new tab](https://dev.vault.sgraph.ai/#sgit_rk1_047186b559528058c66d1792b7345639b1238cb95c166d1d5f5b65c59813c2ee%3Ar7zes477) · From the CLI: `sgit clone sgit_rk1_047186b559528058c66d1792b7345639b1238cb95c166d1d5f5b65c59813c2ee:r7zes477`
Published deliberately. It grants read, and only read — a write attempt is refused by the server's write gate.

## See it live, here

Both surfaces open automatically below. You can also [**open the app in its own window ↗**](https://dev.vault.sgraph.ai/#sgit_rk1_047186b559528058c66d1792b7345639b1238cb95c166d1d5f5b65c59813c2ee%3Ar7zes477).

## What this vault demonstrates

| Feature | How this vault uses it |
|---|---|
| **Scoped write permission** | `app.json` grants the app `read` over everything but `write` and `mkdir` over `adherence/`*only*. The app that records what you took each day cannot touch the regimen, the label photographs or the references — least authority, declared in the vault and enforced by the host |
| Source-mapped extraction | every amount in `regimen.json` carries a `label_image` pointing at the photograph it was read from, so a misread is *visible* rather than propagated — the same discipline a diff gives code |
| Deterministic analysis | `scripts/totals.py` sums per nutrient with its rules stated in the open: topicals contribute nothing, as-needed items sit outside daily totals, and a null amount is **flagged, never guessed**. The in-app JavaScript does the same arithmetic, so two implementations can be checked against each other |
| Named, dated reference data | UK RNIs and EFSA upper limits, with sources and a transcription note — explicitly *not* US Daily Values, because comparing a UK intake to US references without saying so would be a quiet error |
| Honest incompleteness | one product's 27-nutrient panel is not yet captured, so the app labels the totals **INCOMPLETE** rather than showing a confident wrong number |
| The brief ships with the vault | `briefs/` carries the architecture brief the whole thing was built from — the reasoning travels with the artefact |

## What is going on here, step by step

The embeds above are the real vault, which makes it easy to scroll past the parts that matter. Each row points at one of them. Every screenshot is of this vault, driven by a script holding nothing but the published read key.

the daily record

### What was actually taken, not what was intended

The **Today** tab is a checklist of the day's regimen, grouped by timing. Ticking an item and pressing **Save today** writes one small JSON file — `adherence/2026-08-16.json` — into the vault.

That distinction is the point: a regimen file says what you *mean* to take; the adherence log says what you *did*. When the conversation with a professional finally happens, the second is the honest input.

The Today tab: per-item, per-timing, with a Save that writes into the vault.

traceable extraction

### Every number points back at the photograph it came from

The **Stack** tab lists each product with its dose, timing, route — and the label photograph the amounts were read from. A model did that reading, which is a fuzzy step, so each value carries a `label_image` back to its source.

This is the source-map discipline applied to health data: a misreading stays *visible* and checkable against the picture, instead of quietly becoming a number in a total.

The Stack: products, doses and the label photograph behind each set of numbers.

the missing artefact

### The sum nobody else computes

This is the tab the whole vault exists for. Every label describes one product; **nothing describes the sum**. Here it is: total per nutrient per day, each against the UK RNI and the EFSA upper limit, with the contributing products named.

Two details matter more than the numbers. The reference set is *named and dated* (UK RNI + EFSA UL — deliberately not US Daily Values, for a regimen bought in the UK). And the amber banner says the totals are **incomplete**, listing exactly which amounts have not been captured: *"Nothing is guessed: a value that is not on a captured label is flagged, never estimated."*

Totals per nutrient with ×RNI and ×UL ratios — and an honest incompleteness banner.

never a verdict

### The output is a briefing, not a diagnosis

The **Briefing** tab assembles everything into something to hand to a pharmacist or GP: the stack, the totals, the overlaps, the open questions — *"Three products target the knee — is that a sensible combination or redundant?"*, *"Do any of these interact with my other medication?"*

The tool deliberately stops there. It does the arithmetic nobody had done and hands the result to somebody qualified. It never answers the questions itself, and the vault says so on its own About tab.

The Briefing: what to take to a professional, including the questions to ask.

least authority

### The app may write to one folder — and nothing else

Here is the vault's own `app.json`, read straight out of the store. The permission block grants `read` broadly but `write` and `mkdir` over `adherence/` *only*.

So the app that ticks off today's doses cannot alter the regimen, the label photographs, or the reference values — not by policy, but because the capability was never granted. This is what permissions look like when they are a property of the vault rather than a setting on a server, and it is the healthcare-shaped version of the whole argument.

app.json: read broadly, write only adherence/ — least authority, declared in the vault.

## Why this shape matters beyond supplements

This is the clearest **patient-held record** on the site. The data lives in a vault the person controls; sharing it with a professional is handing over a read key, not granting an account on someone's platform, and not emailing a PDF that is copied forever the moment it arrives. The write key never leaves the owner, so a reader can read *everything* and change *nothing*.

The division of labour is the transferable part: **a model does the fuzzy work** (reading amounts off a photograph), **code does the exact work** (adding them up), and every fuzzy step is traceable to its source so a human can check it. Any domain where an LLM reads documents and arithmetic must be right — expenses, lab results, invoices, dosing — can borrow that shape. See the [healthcare use case](../../../use-cases/health-regulated.md) for where this fits.

## The audit, honestly

Every vault is audited before its read key appears here. This one is **clean on credentials**: no tokens, no keys, no `.vault/` operational bookkeeping — and the scan for personal identifiers found none either (no name, address, contact details, date of birth or health-service number; the record describes its owner only as "UK-based adult male").

What it *does* publish is a real person's actual supplement regimen, and the health context that can be inferred from it — a knee, sport, sleep. That is the owner's own data, published on purpose, and it is worth stating the rule that goes with it: **revocation is not retroactive**. Anybody who fetches these objects keeps them. Rotating the key protects future commits and returns nothing already read. The regimen is published because a real record demonstrates the pattern in a way a fabricated one cannot — and because the alternative, a sanitised sample, is exactly the thing this vault argues against.

## Derived facts

23 files · 2.3 MB · 5 commits · app entry `index.html` · twelve label photographs — derived from the read key alone by `admin/build/catalogue_derive.py`, the same derivation that populates [the catalogue](../../../catalogue/index.md).



==============================================================================
# Risk Mandate — a published vault

> A working application built and delivered as a vault: 124 files, 98 commits, eight entry points, pinned releases, offline capable — and it calls an LLM without ever holding the API key, which is sealed under the vault key.
>
> Page: https://sgit.ai/demos/vaults/risk-mandate/index.html

[Home](../../../index.md) / [Vaults](../index.md) / Risk Mandate

# Risk Mandate

A field demo built to be handed to a stranger on an iPad — and, underneath it, the most complete software project published here: 124 files, 98 commits, eight entry points, a test suite, build tooling and pinned releases, all inside one encrypted vault.

**Why this one matters.** It answers the question the other demos leave open: *can you actually build something real in a vault?* This is a working application with a release history, developed in the vault, delivered by the vault, and running offline once cached. It also does the thing that is hardest to do safely — **it uses an LLM without ever holding the API key**.

**Open it yourself — the key is the whole credential.**
 Read key: `sgit_rk1_a702fba803faac4369eb5d5a320b4dfa017af62bd2425fb298aac4b99e95c0ae:4zf6pf2z`
 In the official UI: [open it read-only in a new tab](https://dev.vault.sgraph.ai/#sgit_rk1_a702fba803faac4369eb5d5a320b4dfa017af62bd2425fb298aac4b99e95c0ae%3A4zf6pf2z) · From the CLI: `sgit clone sgit_rk1_a702fba803faac4369eb5d5a320b4dfa017af62bd2425fb298aac4b99e95c0ae:4zf6pf2z`
Published deliberately, and **derived** — this read key is a one-way derivation of the vault key, which stays with its owner. It grants read, and only read.

## See it live, here

Both surfaces open automatically below. You can also [**open the app in its own window ↗**](https://dev.vault.sgraph.ai/#sgit_rk1_a702fba803faac4369eb5d5a320b4dfa017af62bd2425fb298aac4b99e95c0ae%3A4zf6pf2z) — it is more fun full size.

## What is going on here, step by step

Three things this vault does that the others do not. Every screenshot is of this vault, driven by a script holding nothing but the published read key.

the app

### A real application, delivered as a vault

This is **Risk Mandate**, a field demo built to be handed to someone on an iPad: pick a scenario, answer eight questions, and a risk register assembles beside you — readable as an operator, a CISO or a board.

It is one `index.html` with everything inlined, and it opens straight from the vault. Note the chrome: a **release selector** ("Live (latest)"), a sealed-secret badge, and **Read-only** — you are looking at a published build, not a preview.

The line under the button is the part worth reading twice: *"Nothing leaves this device."* On the stand it runs with the network off — one cached load, then flight mode all day.

The app as it opens from the published read key: scenarios, presets, and a version chip.

the privilege claim

### It uses an LLM. It never holds the API key.

The whole argument of this vault is in its `app.json`. It grants the app `llm: chat, models, usage, listen` — and `fs.write` over `field/workspace/` and nothing else.

What is *not* granted is the credential. `.vault/llm/config.json` carries `keySealed: {iv, ct}` — the OpenRouter key encrypted under the vault key. The host decrypts it and makes the outbound call; the frame is handed a result, never a secret. Opening this vault with the published read key, that field is ciphertext we cannot decrypt — which is the point, and we checked.

In the [privilege vocabulary](../../../compare/index.md): the app gets `ops:llm-chat` without ever getting `bearer` of the key. That distinction is usually impossible to express, let alone enforce.

app.json: LLM use granted, the key withheld, and write scoped to one folder.

version control, seriously

### Ninety-eight commits, and releases pinned to them

This is not a document that happens to live in a vault — it is a software project developed in one. **98 commits**, a test suite, build tooling, and `.vault/releases.json` pinning named releases (`v0.15.5`, `v0.10.3`, `v0.7.7`…) to specific commit ids, which is what the release selector in the app chrome is reading.

Its build script is the detail we enjoyed most: `tools/build.mjs` fails the build on any declarative external reference *and* on any credential-shaped string. They arrived at the same tripwire this site runs on its own releases, independently, for the same reason.

The SGit view: 98 commits of a real project, read with a published read key.

## What this vault demonstrates

| Feature | How this vault uses it |
|---|---|
| **AI without the credential** | Sealed OpenRouter key in `.vault/llm/config.json`; the host decrypts and calls, the app frame receives results only. Read-key holders — including us — see ciphertext in that field |
| **Scoped permissions, two kinds** | `llm` capabilities enumerated (chat, models, usage, listen) and `fs.write` limited to `field/workspace/` |
| Eight entry points | `index.html`, plus a board, a takeaway page, talking points, a build-history page and three proofs-of-concept — one vault, many front doors |
| Pinned releases | `.vault/releases.json` maps names to commit ids; the app chrome offers them as a live selector |
| Offline by design | One cached load, then it runs with the network off — the demo survives conference wifi |
| A build that enforces the contract | `tools/build.mjs` exits non-zero on declarative external references *and* on credential-shaped strings — their own version of this site's release tripwire |
| Shareable results without a server | `takeaway.html` rebuilds a saved register from the link alone |

## The audit, honestly

Audited independently before this key was published, across all 124 files. **Clean:** no credentials, no personal data, and the vault's own key does not appear in its content — the failure that forced a republish in [an earlier case](../strategy-maps/index.md).

Two findings worth publishing because they are the *good* kind. The OpenRouter credential is present but **sealed**: encrypted under the vault key, so a read-key holder gets ciphertext. And the one match our secret scanner produced was `sk-test-abcdefghijklmnop` in `tests/suites/40-llm.mjs` — a deliberately fake key in a test that asserts a reachable API key *is caught*. A scanner hit that turns out to be a security test is a good sign about a codebase.

As always: revocation is not retroactive. Anyone who fetches these objects keeps them.

## Derived facts

124 files · 1.9 MB · 98 commits · eight app entries · last updated 2026-08-06 — derived from the read key alone by `admin/build/catalogue_derive.py`, the same derivation that populates [the catalogue](../../../catalogue/index.md).



==============================================================================
# Agentic Browser Isolation — a published vault

> A living risk graph for whether an AI agent browses with your logged-in sessions or an isolated identity: seventeen entry points, a page per stakeholder altitude, acceptance-gated escalation, cited evidence, and an app that requests no write capability at all.
>
> Page: https://sgit.ai/demos/vaults/agentic-browser-isolation/index.html

[Home](../../../index.md) / [Vaults](../index.md) / Agentic Browser Isolation

# Agentic Browser Isolation

A living risk graph for one narrow, consequential question: when an AI agent browses and acts on the web, does it run **inside your browser with your logged-in sessions**, or inside an isolated browser with a scoped identity of its own?

**Why this one is here.** It is the site's own argument, made by somebody else and in far more detail: this is the ambient-authority problem the [serialised change proposal](../../../use-cases/serialised-pull-request.md) and the [agent use case](../../../use-cases/ai-agents.md) circle around — an agent borrowing a human's whole session because that is the only credential on offer. Here it is a register with owners, evidence and an escalation mechanism, and it is vendor-neutral: any isolation product is an *instance of* the control, and its own self-created risks go on the register like everything else.

**Open it yourself — the key is the whole credential.**
 Read key: `sgit_rk1_92cad4cea8f58c55f59b686c71c935225a1ba7c41ecb6922a8aa570467604f6e:0610gsp9`
 In the official UI: [open it read-only in a new tab](https://dev.vault.sgraph.ai/#sgit_rk1_92cad4cea8f58c55f59b686c71c935225a1ba7c41ecb6922a8aa570467604f6e%3A0610gsp9) · From the CLI: `sgit clone sgit_rk1_92cad4cea8f58c55f59b686c71c935225a1ba7c41ecb6922a8aa570467604f6e:0610gsp9`
Published deliberately, and **derived**: the owner supplied a vault key, our intake check refused it for publication, and only this one-way derivation appears here.

## See it live, here

Both surfaces open automatically below. You can also [**open the app in its own window ↗**](https://dev.vault.sgraph.ai/#sgit_rk1_92cad4cea8f58c55f59b686c71c935225a1ba7c41ecb6922a8aa570467604f6e%3A0610gsp9) — with ten pages to walk, it is worth the room.

## What is going on here, step by step

Four things worth stopping on. Every screenshot is of this vault, driven by a script holding nothing but the published read key.

ten front doors

### One vault, seventeen entry points

The app opens on **Facts** and carries a numbered spine across the top: your reality, the two designs, the chain, how it unfolds, stakeholders, an explorer, two graph views and the raw data. Seventeen HTML entry points in one vault, each a real page.

The evidence is cited outward, too — the facts link to Brave's prompt-injection write-up, an arXiv paper on credential exposure, independent testing. A risk register that names its sources is one you can argue with.

The app on open: a ten-step spine, and the decision stated at the top.

the mechanism

### The same exposure, in seven languages

This is the idea worth stealing. Every altitude has **one named owner** — L1 IT, L2 CISO, L3 DPO/CFO/COO, L4 CEO, L5 Board — and each owns the risk *in their own language*.

A risk is never assigned automatically. It sits **pending** until that owner accepts it personally, and *only an accepted risk escalates to the altitude above*. Look at the counts in the picture: IT has 5 risks pending; everyone above is `waiting`, with nothing yet arrived — because nothing has been passed up. There is **no deny button**: accept, mitigate, or ask for more data.

Seven stakeholder altitudes, each with its own pending/accepted counts.

a graph, not a document

### The register is data, and you can see it as one

Seventy JSON files hold the register — risks, controls, evidence, owners, acceptances — and the app offers them as an explorer, a rendered graph, and a queryable graph database, with RDF tooling vendored into the vault so none of it needs the network.

That is the shape argument for vaults holding structured analysis rather than prose: the same encrypted objects serve a narrative page, a stakeholder view and a graph query, because the underlying thing is data.

The graph view, rendered in the browser from the vault\u2019s own JSON.

read-only by declaration

### An app that asks for nothing

Its `app.json` declares `fs.read: true` and `fs.write: []` — an **empty** write list. Compare the [Supplement Stack](../supplement-stack/index.md), which writes to one folder, and [Risk Mandate](../risk-mandate/index.md), which uses an LLM without holding its key.

Three vaults, three points on the same scale, each declared in the vault rather than configured on a server. The footer states the consequence plainly: *your changes are device-local; the vault baseline is never modified*.

app.json: read true, write [] — the app requests no write capability at all.

## What this vault demonstrates

| Feature | How this vault uses it |
|---|---|
| **Seventeen entry points** | The most in the catalogue: a narrative spine, a page per stakeholder altitude, an explorer, two graph views and the raw data — one encrypted store, many front doors |
| **Zero write capability** | `fs.write: []`. The app reads and renders; edits stay device-local and the vault baseline is untouched |
| Structured analysis, not prose | ~70 JSON files hold risks, controls, evidence and acceptances; the pages are views over that data |
| Graph tooling inside the vault | RDF libraries vendored in, so the explorer and graph database work with no network and no CDN — the authoring contract making offline the default |
| Cited evidence | Facts link out to primary sources; the register can be checked rather than believed |
| A mechanism, not a spreadsheet | Acceptance-gated escalation with named owners and no deny button — the part most worth copying |

## The audit, honestly

Audited across all 104 files before the key was published. **Clean:** no credentials, no personal data, no operational bookkeeping, and the vault's own key does not appear in its content.

The scan produced six hits and all six were false positives — digit runs like `0123456789` inside a minified RDF library, matching a phone-number pattern. Worth recording because it is what a real audit looks like: the interesting output of a secret scanner is usually the part you have to rule out by reading it.

As always: revocation is not retroactive. Anyone who fetches these objects keeps them.

## Derived facts

104 files · 2.4 MB · 4 commits · seventeen app entries · last updated 2026-07-18 — derived from the read key alone by `admin/build/catalogue_derive.py`, the same derivation that populates [the catalogue](../../../catalogue/index.md).



==============================================================================
# Risk Graph Explorer — a published vault

> A fact-to-risk graph explorer extracted into its own vault and designed to be public: its PUBLIC.md states three rules its build enforces, including no metered capability behind a published read key, and its app.json requests no permissions at all.
>
> Page: https://sgit.ai/demos/vaults/risk-graph-explorer/index.html

[Home](../../../index.md) / [Vaults](../index.md) / Risk Graph Explorer

# Risk Graph Explorer

The graph explorer from [the risk-mandate work](../agentic-browser-isolation/index.md), refactored out into a vault of its own — and the first vault published here that was **designed to be public from the start**, with its own publication rules enforced by its own build.

**Answer the questions; the register assembles.** Seven views recompute as you go, including acceptance (who holds what) and what happens next (how decisions become incidents and projects). Nothing you answer leaves the page: no network call, no storage, no account. It is destined for riskmandate.ai, and the vault is how it will be served.

**Open it yourself — the key is the whole credential.**
 Read key: `sgit_rk1_1c1b95f5903e35850a9bc0541ffa09c6b5d4017cbf18817d2ad6f894127e5638:3simlnqe`
 In the official UI: [open it read-only in a new tab](https://dev.vault.sgraph.ai/#sgit_rk1_1c1b95f5903e35850a9bc0541ffa09c6b5d4017cbf18817d2ad6f894127e5638%3A3simlnqe) · From the CLI: `sgit clone sgit_rk1_1c1b95f5903e35850a9bc0541ffa09c6b5d4017cbf18817d2ad6f894127e5638:3simlnqe`
Published deliberately, and **derived**: the owner supplied a vault key, our intake check refused it for publication, and only this one-way derivation appears here.

## See it live, here

Both surfaces open automatically below. You can also [**open the app in its own window ↗**](https://dev.vault.sgraph.ai/#sgit_rk1_1c1b95f5903e35850a9bc0541ffa09c6b5d4017cbf18817d2ad6f894127e5638%3A3simlnqe) — try the presets, then change one answer and watch the register move.

**Going deeper.** This vault has more in it than one page holds. [**The seven views, explained**](views/index.md) walks each view with a screenshot of the live vault and the mechanism behind it. [**The author’s walkthroughs**](videos/index.md) carries three recorded demos with full transcripts — the reasoning that the screenshots cannot show.

## What is going on here, step by step

the argument

### An empty register is a correct answer

It opens at zero: **0 facts, 0 risks, 0 provisions**, and a prompt to answer the first question. Nothing is assumed about your estate until you say something about it.

That is the claim the whole app is built to make, and its README states it plainly: *"the technical answers can be as bad as you like — if nothing is at stake behind them, the register is short, and that is the correct answer."* A tool that produces the same output for a scratch service and a payments platform is a checklist, not a risk register.

The explorer at zero: no answers, so no register.

context decides

### Answer differently and the graph changes shape

Load the **Exposed** preset and the same questions produce 18 facts, 37 risks and 14 provisions, with a header that reads *decides about a person · in production · at stake*. Seven views recompute together: the estate graph, context, a role risk map, risk chains, the register, acceptance, and what happens next.

Look at the graph itself — amber edges are exposure facts, green are assurance, and **ghosted means nobody has said either way**. Recording that absence as information, rather than as an implicit pass, is the detail that makes this a graph rather than a form.

The Exposed preset: 18 facts, 37 risks, and unanswered relationships drawn as ghosts.

published on purpose

### A vault that carries its own publication rules

Most vaults here were audited by us before their key went out. This one arrived with the audit already written into it: `PUBLIC.md` states that **every byte committed is already public**, and its build refuses if any of three rules is broken — nothing private committed (the gate scans *every file*, not just the built artefact), no write token, and **no metered capability**.

That third rule is the one worth borrowing, and we had not written it down: *"a published read key in front of an LLM config is an open tab on somebody else's budget, and a spend cap is a rate limiter on the fun, not a control."* It sent us back to re-check a vault we had already published — see the note below.

PUBLIC.md: three rules, enforced by the vault’s own build.

the floor

### permissions: {}

An empty permissions object. Not a scoped write, not a withheld credential — **nothing requested at all**. The app answers questions in the page: no network call, no storage, no account, as its README says.

The catalogue now spans the full range, each declared in the vault rather than configured on a server: [Risk Mandate](../risk-mandate/index.md) uses an LLM without holding its key, [Supplement Stack](../supplement-stack/index.md) writes to one folder, [Agentic Browser Isolation](../agentic-browser-isolation/index.md) declares `write: []`, and this one asks for nothing.

app.json with an empty permissions object — the floor of the scale.

## Extraction as a pattern

This vault began as a section of a larger one. Pulling it out gave it a smaller audience surface, a shorter history, its own release cadence and — decisively — **its own permission posture**: the parent could plausibly want a model; this one may never have one, and says so.

That is worth naming as a technique. Vault boundaries are permission boundaries, so the question *"should this be its own vault?"* is usually the question *"should this have a different key, a different audience, or a different set of capabilities?"* Here the answer was all three, and the split made the public version safe to publish in a way the parent could not have been.

## The audit, honestly

Clean: **zero** hits across every text file — no credentials, no personal data, no operational bookkeeping, and the vault's own key absent from its content. The tidiest audit of any vault published here, which is what you would expect of one built to be public.

**It also caused us to re-audit ourselves.** Its third rule — no metered capability behind a published read key — applies to [Risk Mandate](../risk-mandate/index.md), which does carry an LLM config. So we checked rather than assumed: taking the sealed credential from that vault and attempting to open it with the read key we published, AES-GCM refuses (`InvalidTag`). The seal is under a key a read-key holder does not hold, so publishing that read key did not expose anybody's budget. Rule satisfied there by sealing; satisfied here, more conservatively, by absence.

As always: revocation is not retroactive. Anyone who fetches these objects keeps them.

## Derived facts

33 files · 428 KB · 7 commits · one app entry · last updated 2026-08-10 — derived from the read key alone by `admin/build/catalogue_derive.py`, the same derivation that populates [the catalogue](../../../catalogue/index.md).



==============================================================================
# The seven views, explained — Risk Graph Explorer

> A deep walk through each view of the risk graph explorer — the estate, context, role risk map, risk chains, the register, acceptance and what happens next — with screenshots of the live vault and the mechanism behind each, grounded in the author’s own walkthroughs.
>
> Page: https://sgit.ai/demos/vaults/risk-graph-explorer/views/index.html

[Home](../../../../index.md) / [Vaults](../../index.md) / [Risk Graph Explorer](../index.md) / The seven views

# The seven views, explained

One set of answers, seen from seven altitudes. This page walks each view of the [Risk Graph Explorer](../index.md) with a screenshot of the live vault and an explanation grounded in [the author’s own walkthroughs](../videos/index.md) — because the reasoning behind a view is rarely visible in a picture of it.

**The spine, in one line.** An answer becomes a **fact**; facts combine into **risks**; risks are **assigned** to a role and **chain** upward to the corporate register; a role **accepts** what it holds; acceptance produces **what happens next**. Every view below is that same spine, cut at a different angle — which is why changing one answer moves all seven.

Screenshots are of the live vault under the **Exposed** preset, captured with the published read key. Open it yourself from [the vault page](../index.md) and follow along.

1 · The estate

### Every answer becomes a fact, and the graph is the evidence

This is where answering happens, and the first thing to notice is that **a "no" is still information**. From the walkthrough: *"if you don't have an agent, then we only have one piece of information here — but this is a fact."*

The questions walk a deliberate path: what the agent is, what data is in its reach, whether its output decides about a person, what it can do with that data (*cannot see it · reads it · reads and changes it*), whether it can change production, how it is stopped, who may stop it, how long stopping takes, whether stopping was ever tested, what it can reach if it misbehaves, whether it has outbound access, whether the damage is reversible, whether there is a written procedure, whether the actions could be reconstructed, and whose account it acts under.

Each answer lands as an `F-nn` fact chip, and the graph draws the relationships between them — amber for exposure, green for assurance, **ghosted for nobody has said either way**. That last one matters: an unanswered question is drawn as an absence rather than silently treated as a pass.

The estate: answers on the left, the fact graph they build on the right.

2 · Context

### The same technical answers, weighed against what is at stake

Context is the view that makes the app's core claim enforceable. The technical answers can be as alarming as you like; if nothing is behind them, little follows. The header carries the verdict in plain language — *decides about a person · in production · at stake* — and those three phrases are what turn a list of facts into a register worth reading.

This is the difference between a risk tool and a checklist: a checklist scores the agent, this weighs the agent *against the estate it runs in*.

Context: what is at stake, and where it runs, applied to the same answers.

3 · Role risk map

### The org chart, with risks flowing up it

The view the author calls *"crazy powerful"*, and the header states its invariant outright: **every risk is assigned to somebody, and every risk reaches the board**.

Read the counts under each role and you can see the two modes the walkthrough describes. The CISO shows `14 assigned · 14 through`; the CTO `4 assigned · 25 through`; the board simply `37 arrive here`. **Assigned** is what you personally hold. **Through** is what arrives because the risk graph says it must — *"he arrives because of the risk graph says so"*. The SRE holds a set; the platform owner inherits those and adds its own; the CTO inherits everything below and adds its own; the CEO connects the dots.

The consequence is the one worth quoting: *"no risk then becomes orphaned, because every risk will flow upwards, and that's super important."* An owner cannot be surprised at the top by something nobody carried up.

Role risk map: assigned vs through, with every path terminating at the board.

4 · Risk chains

### Risks that cause risks, and the ability to walk it backwards

The second graph, and a different question: not *who holds this* but *what produced it*. Columns are levels — inherent at the left, operational rising by causal depth, and the **corporate register pinned to the right, because that is where the question stops**.

Click any entry and it colours what produced it (**upstream**) and what it produces (**downstream**). The walkthrough uses it in both directions: *"if you go to 'led by' at the bottom, you arrive at the bottom of the risk; if you go 'leads to', you're navigating upwards."* So a corporate-level entry can be interrogated — *"why is it? It's because we have that one, and that one, and this one"* — until you reach the specific answers that caused it.

One detail that only an honest tool ships: **a dashed edge is a cycle, and the cycles are real**. Rather than hiding a loop that the model does not like, it draws it.

Risk chains: inherent to corporate, left to right, with upstream and downstream colouring.

5 · The register

### The familiar artefact — with its provenance attached

This is the output most organisations already recognise: a risk register. What is different is that every row carries where it came from. Per the walkthrough: *"for every risk that you have here, you can see who's assigned, who causes it, and who leads to, and how does it connect."*

A conventional register is a list of assertions someone typed. This one is a **projection of the graph** — which means it cannot contain a risk that nothing produced, and it cannot lose a risk that something did.

The register: the conventional artefact, generated rather than authored.

6 · Acceptance

### Nobody can accept on anybody else’s behalf

Acceptance is where the register stops being a document and becomes a decision. Each role holds what it holds and must accept it personally — and the author is explicit that this is where the value shows up: *"everybody that is going to accept it is going to push back."*

That pushback is the feature. The walkthrough contains a live example of the author disagreeing with his own tool — *"I actually don't agree with these risks… I don't buy that"* — and the point is what happens next: because every risk is fact-derived, the disagreement resolves into *which fact is wrong* rather than whose opinion is louder. *"The cool thing is that we start to have the evidence to show exactly why we are saying this."*

Acceptance: per role, per risk, with no delegation and no deny button.

7 · What happens next

### Decisions become incidents and projects

The last view closes the loop. Acceptance is not the end of a risk; it is a commitment that produces consequences — the things that will happen if the exposure materialises, and the work that would change it.

In the parent vault this is where a board refusal *funds a project* that flips the whole graph to the safer option. Here it is the same mechanism in miniature: the register does not merely describe a position, it names what follows from holding it.

What happens next: the consequences and the work that would change them.

## The same estate, at three settings

The presets are the fastest way to feel what the tool actually does. These are the **role risk map** for the same organisation under three different sets of answers — nothing about the org chart changed, only what is true about the agent.

typical

### A typical deployment

An agent is present and the estate is ordinary. Risks exist, they are held, and they reach the board — but the shape is contained.

Typical: risks present, shape contained.

governed

### The same estate, governed

Approvals, a tested stop, a named authority, bounded reach. From the walkthrough: *"you have the govern, we can see it's a much cleaner sort of flow of events."* The risks do not vanish — they arrive with far less weight, and by shorter paths.

**This is the argument the whole tool exists to make.** The register is not a verdict on whether you should run an agent; it is a picture of what you are carrying, which changes when the controls change.

Governed: same organisation, cleaner flow.

## Why this workflow is powerful

| What it does | Why it matters |
|---|---|
| **Answers are facts, and facts are cited** | Every risk traces to the specific answers that produced it. Disagreement becomes "which fact is wrong", not "whose judgement wins" |
| **No risk is orphaned** | Every risk is assigned and every path terminates at the board. Nothing can sit in a register held by nobody |
| **Assigned is distinguished from inherited** | A role sees what it personally holds and what merely passes through it — two very different conversations |
| **Acceptance is personal and cannot be delegated** | The register becomes a set of decisions with names on them, and the pushback that follows is the point rather than a failure |
| **Cycles are drawn, not hidden** | A model that shows its own loops is one you can argue with |
| **Nothing is at stake ⇒ a short register** | The output scales with exposure, which is what separates a register from a checklist |
| **It runs in a vault, in your browser** | No account, no upload, no network call. The answers you give about your estate never leave the page |

The last row is what makes the rest publishable. A tool that asks these questions is asking for an unusually candid description of your weakest controls — and this one can be handed to somebody as [a read key](../index.md) that carries the whole application, with nothing to send anywhere.



==============================================================================
# The author’s walkthroughs — Risk Graph Explorer

> Three recorded walkthroughs of the risk graph explorer with full transcripts: the graph browser, risk chains, and the role risk map — the designer explaining why the tool is shaped as it is.
>
> Page: https://sgit.ai/demos/vaults/risk-graph-explorer/videos/index.html

[Home](../../../../index.md) / [Vaults](../../index.md) / [Risk Graph Explorer](../index.md) / Walkthroughs

# The author’s walkthroughs

Three recorded walkthroughs of this vault — each one played, then read. Under every video is the same session as a document: the moments that matter, the frame the screen was showing at that moment, and what is actually happening in it. The full transcript is at the foot of each.

**Why a video is not enough on its own.** A recording is invisible to a search engine, to [llms-full.txt](../../../../llms-full.txt), and to any agent reading this site as documentation. It is also full of *“this guy here”* and *“look at this”* — pointing that a transcript cannot resolve. So each moment below pairs the words with the picture they were pointing at, which is the only form in which the argument survives being read rather than watched.

Timestamps link into the video at that point. The **Graph Browser** moments are frames of the recording itself; the **Risk Chains** and **Role risk map** moments are captured from the live vault with the published read key, driven to the state being described.

## 1 · Graph Browser · 4:21 · 5 Aug 2026

How answering the questions builds the fact graph — and why a “no” is still information.

**Note on what you are looking at.** This walkthrough was recorded inside [Risk Mandate](../../risk-mandate/index.md), the field demo the explorer was later extracted from — so the chrome says *Risk Mandate — field demo* and the tab strip is shorter than today’s. The mechanism is the same one running in [this vault](../index.md).

[00:00](https://youtu.be/PP6zsrC0KEg?t=0)
### Five ready-made estates, before a single question

The video opens on the field demo’s front door — **“Eight questions about the agents you run”** — and the row of prepared examples underneath it: *a typical estate*, *a rough day*, *a well-run estate*, *a coding agent in CI*, *a support agent on accounts*. One tap loads a populated register.

That row is a design position, not a convenience. A tool that only shows you your own answers cannot show you what a different answer would have produced — and the argument here is entirely about difference.

“I want to just talk about this graph explorer that we pushed as an MVP, which is, I think, ridiculously powerful as a way to present.”

00:00 — the entry point, with five prepared estates to open instead of answering.

[00:31](https://youtu.be/PP6zsrC0KEg?t=31)
### One answer, one edge — and the counters start moving

The first question is answered: *“Yes, in production”*, which lands as `F-1`. Watch the header. It reads **1 fact · 4 risks · 5 provisions**, *where it runs: in production* — and **at stake: —**, because nothing has yet been said about data.

In the graph, exactly one edge is drawn: `runs-in`, from **The agent** to **The production estate**. Every other twin is ghosted and carries its own tally — `0/3 said`, `0/2 said` — which is the tool stating, per node, how much of what it wants to know it does not have.

00:31 — 1 fact, one edge, and “at stake” still empty.

[00:59](https://youtu.be/PP6zsrC0KEg?t=59)
### Edges are named, and the names carry the meaning

Personal data is selected (`F-36`) and the header flips: **personal data at stake**. **The data in its reach** lights amber with *Personal data* written beneath it, and **Decisions its output…** gains the note *Its output informs a person w…*.

This is the moment the deixis in the transcript resolves. He says the edges differ — and they do, by *name*: `runs-in`, `can-read`, `can-change`, `informed-by`. Not a generic line with a thickness, a labelled relation. That is what makes the picture evidence rather than decoration.

“We actually have different, in a way, almost, different edges depending of what it is. And then, what it can do with the data, right? It cannot see it, or reads it, or reads and changes it.”

00:59 — the data node lights, and the edges arrive with names on them.

[01:30](https://youtu.be/PP6zsrC0KEg?t=90)
### One answer can be two facts

*“Reads and changes it”* is selected — and its chip reads `F-33 F-34`. Two fact identifiers for one click, because the answer asserts two separable things, and each has to be independently citable later when a risk points back at what produced it.

The graph gains `can-read` and `can-modify` as distinct edges. Below, the questions have moved on to whether it can change production, whether it can be stopped, and how long stopping would take — the path from *capability* to *control*.

01:30 — one selection, two facts, two edges.

[02:01](https://youtu.be/PP6zsrC0KEg?t=121)
### “This is here, depends on that one” — the sentence a transcript cannot carry

Here is the clearest case for reading the video rather than only listening to it. He says two risks are connected and points; the words alone name neither end.

The frame answers it. *“Yes, eventually”* is selected under **q3 — if you had to stop it right now, could you?** (`F-12`), and an edge labelled `stops-in-many-actions` runs from the agent down to **The stop control**, which now shows `4/12 said`. The dependency he is pointing at is a named edge with a counted endpoint.

“This is an interesting one because this is connected to the stop control. So, you can actually see that this is here, depends on that one.”

02:01 — the referent of “this depends on that one”, named.

[02:30](https://youtu.be/PP6zsrC0KEg?t=150)
### Saying “never” draws an edge too

Two negative answers land: *never* actually stopped it (`F-19`), and *no*, the side effects of stopping are not known (`F-22`). A checklist would score these as gaps and move on.

Instead the graph grows `never-exercised-on`, `never-timed-for` and `absent-for` — negative relations, drawn and labelled exactly like the positive ones. This is the mechanism behind the claim that a “no” is information: the answer produces a fact with a name, so a risk downstream can cite it. **11 facts · 20 risks**, and the shape is filling in.

02:30 — “never” and “no” arrive as named edges, not as silence.

[03:00](https://youtu.be/PP6zsrC0KEg?t=180)
### The one green edge

Reach is answered *customer-facing* (`F-24`) and egress *no egress* (`F-47`) — and `cannot-reach`, running from the agent to **Outbound network access**, is drawn in the assurance colour rather than the exposure colour. In a field of amber it is the single teal line.

That is the whole two-colour scheme doing its job in one frame: amber is something true that costs you, teal is something true that helps you, and both are the same kind of object — a stated fact with an edge. A good answer is not the absence of a finding; it is a finding.

03:00 — “no egress” draws an edge too, in the other colour.

[03:30](https://youtu.be/PP6zsrC0KEg?t=210)
### Seventeen facts, and the question of whose account it acts under

By now the graph is dense with named relations — `cannot-reconstruct`, `held-by-a-group-for`, `irreversible-by`, `never-timed-for`, `absent-for` — and the header reads **17 facts · 30 risks · 11 provisions**. The agent node shows `15/43 said`: fifteen of the forty-three things the model would like to know have been said.

The last question is the sharpest, and it is deliberately last: **whose account does it act under** — *a named person’s · a team’s · a service account nobody owns*. Everything before it describes what the agent can do. This one asks who will be standing there when it does it.

“It’s a great way to almost in one day capture all the data.”

03:30 — 17 facts in, and the account question still to answer.

[04:01](https://youtu.be/PP6zsrC0KEg?t=241)
### The other views, in one sweep — and a risk with an owner

He closes by touring what the same answers become elsewhere, landing on **Risk chains** with **RISK-22** selected: *“Some changes the agent makes cannot be reversed by the operator”*, marked **OPERATIONAL · HOLDS NOW**, assigned to *SRE / platform on-call* and *Platform owner*, with a **blast radius** drawn from its own facts.

That panel is the payoff of everything above it. The risk was not typed by anybody. It exists because certain answers were given, it is owned because the org chart says who holds that class of thing, and it can be argued with by going back to the facts underneath — which is what the next walkthrough is about.

04:01 — a generated risk, with an owner and a blast radius.

**Full transcript — Graph Browser**

Okay, so I want to just talk about this graph explorer that we pushed as an MVP, which is I think ridiculously powerful as a way to present. So what we have here now is how the questions we originally talked about in the demo. But it's in a weird way, we start with the first question, right? Do you have an agent and where does it run? Because if you don't have an agent, then we only have one piece of information here, which is — and but this is a fact, right? So this here captures the facts and information. So you could see that you have both the operation state or the test environment. And it's interesting because the risk will be very similar.

The only question is whether it's live, so in a way that there's a risk level that is probably going to be there, right? So let's say you have one, right? And now you can see what kind of data is enriched. Let's say I got personal data. And what's cool about this is you can see that what's happening is this graph is now going to be populated with the data that we collected. So you can think of this graph as the evidence piece, right? So look, there's the output of facts and decision. Okay, it informs decisions.

So you can see that what's cool about it is that we actually have different, in a way, almost different edges depending of what it is. And then, what can do with the data, right? It cannot see it, or reads it, or reads and changes. So this is a typical example of you have a production system, right, that touches personal data, accounts, contact details, it informs the decision, you know, of the there, and it reads and changes. So it's a typical agent, right? And now you got it. So now you talk about the information of this.

You know, can the agent change things, right? Can you read and report? Can changes? Can change on its own? So you start to map, you know, for example, how it's done, right? With a person approval or change. So that so this is where you take that to the next level. So it changes on its own, right? So how do you stop it? Let's say you have an action to stop, or eventually can stop, or we don't know how to stop it. And how long should we stop it? Is it minutes? An hour? Don't know. So you start to see again, you know, the stop control now we map stop in many actions, never, time for, an hour, minutes, right? And then, have you actually stopped it? Yes, we have, only in test, never, right? Do you know the effects of stopping it? Have we mapped it? Is it partially? Etc.

So this is an interesting one because this is connected to the stop control. So you can actually see that this is here depends on that one. So it's in a way now a next line up, like down, sorry, of the flow. Is there a named person? Do you have a named person or not? So this is the stop authority, right? The team, you know, if it really is, you know, misbehavior for full speed, could, you know, what could you reach, right? Internal only, customer facing? Don't know. So this would be customer only.

So you could now start to see again, you know, what's the damage, that it can acts, you know, can you reach anything outside the network? This means that does it have internet access or not. So again, you can see here, outbound access, right? For example, no egress. Could, you know, could you undo the damage, right? So let's say you have fully reversible versus not, or some change are forever, which is important, right? Is there a written procedure for how you pull the plug? You tested it, you've written, you don't have it. Could you reconstruct what you did, for example, every day, right? Or, you know, do you have, you know, fully or partially or not, right? Cuz sometimes you have backups, but they do not allow you to restore specific things, and whose account it is, right? A service account, a named person, a team, right? So, you know, what is actually the, for example, the flow that happens. And then this is great, like because you can look at it.

This is — I love this, right, because it's a great way to almost in one day capture all the data. Just for reference, we then capture the context. We have now these really cool road map with all the risks that flow forward. We also have these risk chains, which I go in more detail in others, but that means that every risk that is then connected connects to the top level, right? And then we even have a risk register, right? And for every risk that you have here, you can see who's assigned, who causes it, and who leads to, and how does it connect, right? So it's pretty cool.

## 2 · Risk Chains · 4:18 · 5 Aug 2026

Risks that cause risks — and why being able to disagree with the register is the feature.

[“risk 6”](https://youtu.be/kWip3QnuN1I?t=45)
### Every risk carries the condition under which it would stop being true

He names one entry — *“if you look at this guy here, for example, you have risk 6”* — so this is that entry, selected in the live vault. **RISK-6 — the production estate can be changed by an agent**, with the app’s own one-line gloss: *“They hold the estate. A change they did not make can still be one they must live with.”*

The dashboard is where the design shows. **Established by**: `F-5`, the agent `can-change` the production estate — one fact, cited. **Ceases when any of these hold**: `F-4` reads-only-from, or `F-3` absent-from. That second list is unusual and worth stopping on: **the risk ships with its own falsification condition**. It is not a judgement to be argued down, it is a claim with stated exit criteria.

Then **reduced by — but not retired**: *narrowing what it may change*, *staging changes behind a gate*. Mitigation is recorded as reduction, never as removal. And **touches**: EU AI Act Art. 12, Art. 26.

The entry he names, opened: one fact establishes it, two would end it.

[“corporate 2”](https://youtu.be/kWip3QnuN1I?t=110)
### Walking it backwards: “why is it? Because we have that one, and that one”

The same view from the other end. **CORP-2 — customer harm**, assigned to the Chief Product Officer and the CEO, and the panel answers his question literally. **Established by**: *“Nothing directly. It holds because the entries below it do.”* **Leads to**: *“Nothing recorded”* — this is the top, which is where the question stops.

Underneath, **led by** enumerates the causes, and each carries a reason in the tool’s own words: RISK-5 *“← a person on the other end is what customer harm means”*; RISK-26 *“← the record is somebody’s”*; RISK-27 *“← this is what customer harm looks like in practice”*.

Note the colour: tracing upstream lights the path in the assurance tone rather than the exposure tone, so *what caused this* and *what this causes* are visually distinct operations on the same graph. And the corporate entry **touches no twin directly** — it is entirely a consequence, which is exactly why it cannot be edited into existence.

The top of a chain, interrogated backwards — with a reason attached to each cause.

[governed](https://youtu.be/kWip3QnuN1I?t=200)
### The same organisation with controls in place

Switching the preset to **Governed** re-derives every chain from a different set of answers: approvals in the path, a tested stop, a named authority, bounded reach. Fewer entries, shorter routes to the register — *“a much cleaner sort of flow of events.”*

The comparison is the argument. Nothing about the organisation changed between this frame and the last; only what is true about the agent did. A register that produced the same output either way would be measuring the questionnaire, not the estate.

Governed: same organisation, same graph, fewer and shorter chains.

**The most useful thirty seconds in all three videos** is the author disagreeing with his own tool. *“I actually don’t agree with these risks… I don’t buy that at the moment.”* He then works out what he does think is true — that the exposure is really about the agent touching EU AI Act obligations, and that stopping it would itself disrupt production — and says *“so we should capture that.”* The disagreement does not resolve into whose judgement wins. It resolves into **which fact is wrong or missing**, and then the register re-derives. That is the difference between a document you argue about and a model you correct. *“When you go and push your risk to be approved, the stakeholder is going to challenge you really hard. The cool thing is that we start to have the evidence to show exactly why we are saying this.”*

**Full transcript — Risk Chains**

...to go through this UI which I think is starting to really show the idea of connecting the risks upstream. So what you have here to show you, this is part of the UI that we have that you know, you can basically see the multiple workflows that we have from a typical, non-exposed, one that's actually quite governed. What I really like is this, let's look at the exposed first, this sort of chain, and let's consolidate this here. So the idea here is that the risks connect from one element to the other. So if you look at this guy here, for example, you have risk 6.

"The production can be changed by an agent." This is now connected to that risk. "Organization acts to the system that acts for a person", who then creates this risk, right? "Organization asks to, Tech to be changed." And then hits the top two risk register. So the logic here, this is the corporate risk register, so you can see that that particular risk will arrive there, and when I click here, I can also see the reverse. So I can see, if we say we have a risk of this, why is it? It's because we have that one, and we have that one, and we have this one, and that one. And I could also see it here, what actually happens.

You can see, for example, this particular risk, corporate 2, who is assigned to, and then to the CEO, to what, you know, is reduced by this particular choices, touches GDPR, and then leads to this. So, so actually, so this is a good example, so you can see that this guy here, this risk leads to these two, and is led by that and that. So you can see that, you know, and again I can click on it and see the risk, right? So, so if you, if you go to "led by" at the bottom, you arrive at the bottom of the, the risk. If you go "leads to", you're basically navigating upwards the risk through. And the idea is that every risk should arrive at the corporate, at the top, right? So, so this now becomes a very powerful way to start to understand connections, and then we map the risks to the correct one, and I'll do a separate one to show how again, we connect all these risks to the particular CEO, CFO, you know, stakeholder, right? Now, the cool thing about this is you could see that the risks that you have go from zero, we don't have anything, to yes, you have an agent, bang, you got some risk.

So as we start to add basically these answers, you see that we basically start to populate and start to add the risks and they start to interconnect, which is really cool, right? So, the idea is that the changes here impact the risks that exist and how the risk register almost looks like and the evidence that we have, right? So, and what's interesting about this, is if you look for example at "governed", actually this is there because of, I was actually, when I was explaining Claude about how to do this, I was saying just the fact they have an agent, you're going to have risks, but I actually don't agree with these risks because, see even that loss of control, I would argue that's not the risk that I have by having an agent, right? So the logic here is like if I have an agent in production and I have a lot of these values which are pretty good, I don't buy that at the moment I have this, right? Because we said in this one that we already have some of these. So, I think this is a good example of why when you go and push your risk to be approved, the stakeholder is going to challenge you really hard. The cool thing is that we start to have the evidence to show exactly why we are saying this. So, I think that in this particular case, it has more to do with the fact that the agent touches EU act, so suddenly we are in compliance with the EU AI act, or we might be compliant with it, and we now have an agent in the mix, and then the organization, and we have, and even though here we say we can stop within a minute, right? There is still some disruption to production, right? Which is interesting, right? So we should capture that operation, right? Because the system, like that one's a good one, you know, stopping the agent might have an interruption. So, again, we need to capture these nuances.

The cool thing is this is all now fact-driven, which is super powerful.

## 3 · Role risk map · 3:15 · 5 Aug 2026

The org chart with risks flowing up it — and the ways a risk arrives at a person.

[“no agent”](https://youtu.be/yqQgff4RWuE?t=160)
### The org chart exists before any risk does

Under the **New** preset the structure is already there — board, CEO, CTO, CISO, CFO, DPO, chief product officer, platform owner, customer-facing service owner, SRE — and nothing is flowing through it.

That ordering matters. The organisation is not derived from the risks; the risks are routed onto an organisation that was described first. Which is why the same estate can be re-answered all day and the chart underneath never moves.

“If you have no agent, you have nothing.”

Nothing answered: the structure, carrying nothing.

[the CTO](https://youtu.be/yqQgff4RWuE?t=95)
### Held, versus arrived — and the tool separates them explicitly

Selecting the CTO lights the path *Board → CEO → CTO → Platform owner / CISO* and splits what the role carries into named sections. **Holds — 4**: *“Assigned to this role. Its own to deal with.”* **Arrives by the risk chain — 16**, with the tool’s own explanation of why that category exists:

“It arrives because the **risk graph** says so, not because anybody reports here — which is how a board entry ends up with an unexercised runbook underneath it.”

That sentence is the whole feature. An owner is not surprised at the top by something nobody carried up, because arrival is computed rather than reported. On the chart itself each role is labelled in the same two terms — the CTO reads `4 assigned · 25 through`, and the board simply `37 arrive here`.

The CTO: four of its own, sixteen that arrive because the graph says they must.

[the SRE](https://youtu.be/yqQgff4RWuE?t=130)
### At the bottom, a third category — and it is empty

The SRE / platform on-call is the leaf, *reports to Platform owner → CTO → CEO → Board*, and it **holds 9** — RISK-2, 6, 10, 11, 12, 13, 19, 22, 35 — the operational set the walkthrough describes as travelling upward from here.

The panel here reveals something the video only implies: there are **three** ways a risk reaches a role, not two. **Arrives by the risk chain — 2**, and **arrives by the org chart — 0**, glossed *“Held by somebody who reports here”*, answered *“Nothing below.”* Inheritance through the reporting line and causation through the risk graph are counted separately, which is what lets you ask a manager *why* they hold something and get a structural answer rather than a list.

“No risk then becomes orphaned, because every risk will flow upwards, and that’s super important.”

The leaf of the chart: nine held, two caused, nothing inherited — because there is nothing below it.

**Full transcript — Role risk map**

Okay, so this next video shows another super powerful capability that we had here to our risk graph explorer, which is the org chart, and how we have, in this case, the board, we have the CEO, we have three direct reports, and we have then the kind of the team, where the platform owner, to the CTO, to the CEO, to the board, and you can actually see, you know, it's quite nice, the chain, right, the chief product officer, you know, has a customer service owner who connects to the board, who responds to the CEO and the board, right? And we can kind of see the sequence of events, right? So, what we're going to see here is how as we add risks to the organization, right? You start to have risks that are flowing to here, right? Which is pretty cool, so you could see that as we add, basically, and we provide answers, you basically start to see the, fundamentally, the risks changing. And what's cool about it is you could see how they arrive, and one of the things that's quite interesting is that we have two modes already, because you could see that the CEO, in this case, or the board, right, receive all these risks, so the CEO, in this case, is assigned his three corporate risk registers directly to him, but you also have these risks that arrive from the risk chain, and that's very important. Right? So you basically could see that because somebody, you know, a senior, holds, he arrives because of the risk graph says so, right? So that means that these particular risks that exist there, which for example, come from here, so you could see that this risk here, so let's say, the SRE is holding risk 2, risk 6, risk 9, risk 21, and risk 31, and that risk is also now going to exist — same risks are going to be connected to the platform owner, who now has a couple more risks of itself, and now the CTO has a couple risks of itself but also inherits all the risks that we mentioned below all the way up. So it's pretty cool, right? Because again, same thing, right? So the DPO is assigned a couple of risks, and then, you know, that he has, right? And then, you know, it also arrives from the risk chain, and then you got the CFO, the same thing, right? And then the CEO, you know, connects the dots. So this is a really powerful capability because it's how you connect all the dots, right? So if you look at the different scenarios, if you have no agent, you have nothing, if you have a typical kind of agent deployment, you have this kind of shape, if you have a lot of exposure, you get a much bigger set of responsibilities, and you have the govern, we can see it's a much cleaner sort of flow of events.

And now we can start to challenge, you know, is those risks in the right place because everybody that is going to accept it is going to push back. But this is crazy powerful because now we start to see the relationships, and we see that no risk then becomes orphaned, because every risk will flow upwards, and that's super important.

## Where to go next

Each view gets a systematic treatment, screenshot by screenshot, on [**the seven views page**](../views/index.md). The vault itself — its read key, both live surfaces, and the publication rules it enforces on its own build — is on [the vault page](../index.md).



==============================================================================
# Algarve · May 2026 — a published vault

> A travel diary as a vault: twenty photographs in three sizes, an eight-chapter narrative and an auto-opening gallery app — 29 MB of ciphertext opened by one published read key, with its pre-publication audit finding stated on the page.
>
> Page: https://sgit.ai/demos/vaults/algarve-may-2026/index.html

[Home](../../../index.md) / [Vaults](../../../index.md) / Algarve · May 2026

# Algarve · May 2026

A travel diary as a vault: twenty photographs in three sizes, an eight-chapter narrative, and a gallery app that opens automatically.

**Open it yourself — the key is the whole credential.**
 Read key: `sgit_rk1_0a0f34839d737eef0f8f66e5236990b1f397af064763e3f71dca2717015f9d15:3d04e6b9ca98`
 In the official UI: [open it read-only in a new tab](https://dev.vault.sgraph.ai/#sgit_rk1_0a0f34839d737eef0f8f66e5236990b1f397af064763e3f71dca2717015f9d15%3A3d04e6b9ca98) · From the CLI: `sgit clone sgit_rk1_0a0f34839d737eef0f8f66e5236990b1f397af064763e3f71dca2717015f9d15:3d04e6b9ca98`
Published deliberately. It grants read, and only read — a write attempt is refused by the server’s write gate (the **R1 W0** badge you will see in the chrome).

## See it live, here

Both surfaces open automatically below. You can also [**open the gallery app in its own window ↗**](https://dev.vault.sgraph.ai/#sgit_rk1_0a0f34839d737eef0f8f66e5236990b1f397af064763e3f71dca2717015f9d15%3A3d04e6b9ca98) — the read key travels in the URL fragment, which the vault UI accepts directly.

## What this vault demonstrates

| Feature | How this vault uses it |
|---|---|
| Real binary payload | 60 WebP photographs in three sizes (originals ≈29 MB total, web ≈1600px, thumbnails) — every byte stored and served as ciphertext |
| Auto-opening gallery app | `app.json` sets `auto_open` with a minimal HUD; the app is an editorial photo story with chapters and a lightbox, driven by `gallery.json` |
| Content + narrative | `NARRATIVE.md` carries the written week; `gallery.json` carries per-photo titles, captions, chapters — edit the JSON, push, and the gallery updates |
| Deep history | 36 commits of organising, captioning and re-cutting — open the SGIT view above and read the story of the story |
| Owner secrets done right | `.vault/owner/readonly-tokens.json` decrypts to *further ciphertext* — owner bookkeeping is double-encrypted under a key the read key cannot reach |

## What is going on here, step by step

The two embeds above are the real product, which makes them easy to scroll past without noticing what is unusual. Each row below points at one thing and says why it matters. Every screenshot is of this vault, driven by a script that opens it with the **published read key** and nothing else — the same credential printed at the top of this page.

the app itself

### The app is real HTML, not a viewer

The gallery is the vault's own `index.html` — an editorial layout with chapters, pull quotes and photo rows, written as ordinary HTML and CSS. Nothing renders it into a fixed "photo album" template: whatever the author wrote is what runs.

Each photograph here arrived as ciphertext, was decrypted in the browser, and was handed to the page as a `blob:` URL. The server never saw a picture — it served opaque bytes and has no idea this is a gallery.

A chapter row: two decrypted photographs, laid out by the vault’s own CSS.

interaction

### Click a photo and the app takes over

Because the app is real HTML, it can behave like any web app. Clicking a photograph opens the gallery's own lightbox: a larger image, the caption and chapter from `gallery.json`, and arrows to move through all twenty.

This is the part that surprises people most — an encrypted store is usually a download-and-open experience. Here the interaction is authored *inside* the vault and the reader never leaves the page.

The lightbox: caption, chapter, position (1 / 20), and prev/next arrows.

watch it decrypt

### A pane that shows the decryption happening

The app frame ships with a debug pane, and its **Vault** tab is the timeline of the open: the vault unlocked, the file tree loaded, `app.json` found, the app iframe ready — each with the milliseconds it took.

Read the key line: the vault opens from a key that is shown truncated, and the file tree — *seventy files* — is built in the browser from encrypted directory objects. Filenames are encrypted too, so even the folder structure is something the client reconstructs rather than something the server reports.

The Vault tab: each step of the open, with timings.

the sg bridge

### And a console you can type into

The **REPL** tab is a small console over the `sg.*` bridge — the same API the app itself uses. `vfs.list` walks the decrypted tree, `vfs.read` prints a text file.

Note what the help text says about writing: `vfs.write` and `vfs.delete` are marked *writable vaults only*. This page's key is read-only, so those commands are refused — not hidden by the interface, but impossible, because no write capability exists anywhere in the chain.

vfs.list at the vault root, then inside /photos — typed live, answered from decrypted objects.

transparency

### The whole vault is browsable — including its source

The second surface on this page is the vault browser. It shows the real tree: `photos/originals/` with its twenty WebP files, the thumbnails and web-sized copies beside them, and the app's own files.

Open `index.html` and press **Source** and you are reading the gallery's code — the same 29.9 KB the app boots from. A published vault is transparent in a way a hosted gallery rarely is: the reader can inspect exactly what is running.

photos/originals expanded, with index.html open in source view.

version control

### And it is version control, not just storage

The **SGIT** tab is why this is sgit rather than a folder in the cloud. Every commit that built this gallery is here — thirty-six of them — with real object ids, dates and branch labels, and `tree` and `diff` links per commit.

This is the vault's history, read from the same encrypted objects, with the same read key. Nothing was re-uploaded to make it browsable: the history *is* the storage.

The SGit view: the commit history of the gallery, read-only.

**How these pictures were made.** They are not mock-ups and they are not hand-cropped. `admin/build/capture_shots.mjs` opens this vault in a real browser with the published read key, performs the navigation each row describes — scroll to a chapter, click a photograph, open the debug pane, switch to the REPL and type `vfs.list`, expand `photos/originals`, switch to the SGit view — and crops the result. Re-running it after the vault changes regenerates every image. The tool takes a read key, so it can document any published vault the same way.

## The audit, honestly

Every vault gets an audit before its read key is published here, and this one has a finding worth stating plainly: the server-side bookkeeping file for a public preview (`.vault/owner/public-previews/…`) carries a live `delete_auth` token, readable by anyone holding this read key. Its scope is narrow — it permits deleting or replacing that one *public preview*, not writing to the vault, whose write gate remains closed — and the owner has been advised to rotate it. It stays on this page because the finding class is the lesson: bookkeeping written into vault content travels with the read key forever. The newer pattern — owner secrets double-encrypted, as the row above shows this same vault doing for its read-only tokens — is the fix.

## What this shape is for

Photo albums, trip diaries, family archives, portfolio galleries — anything where the pictures should not sit plaintext on someone else’s server, but a single shareable key should open the whole experience, chapters and captions included. This is the first of several galleries in [the catalogue’s](../../../catalogue/index.md) awaiting list.

## Derived facts

71 files · 29 MB · 36 commits · app entry `index.html` · derived from the read key alone by `admin/build/catalogue_derive.py` — the same derivation that populates [the catalogue](../../../catalogue/index.md), where this vault also has an entry.



==============================================================================
# Demos — sgit.ai

> Live end-to-end demonstrations: vaults actually created, pushed, and embedded in the pages that document them, each with a deliberately published read-only key.
>
> Page: https://sgit.ai/demos/index.html

[Home](../index.md) / Demos

# Demos

Live, end-to-end demonstrations — each one a vault that was actually created, pushed, and embedded in the page that documents it. The walkthroughs are complete: every command, the keys that are deliberately public, and the ones that never will be.

**The rule every demo follows:** the vault's *read key* is published on purpose — it is derived one-way and cannot write, so publishing it is what makes the demo openable by anyone. The vault's *write key* appears nowhere: not in these pages, not in the repos, and the build refuses to push if one ever reaches a tracked file.

## Published

[Gallery · live### A vault app, live inside this pageField Notes: a self-contained vault app created from scratch, pushed, and opened inside sgit.ai with a published read key — sandboxed iframe, postMessage bridge, every byte decrypted in your browser.Open the walkthrough →](vault-app-embed.md)

[Report · real### The Strategy in Seven MapsNot demo content: the actual SG/Send strategy, published on LinkedIn in May 2026, served live from a vault with a published read key — plus the audit that shows why the original vault could not publish its key, and the republish pattern that fixed it.Open the walkthrough →](strategy-maps.md)

[Analysis · live### sgit, on a Wardley MapSix maps of sgit's own positioning — where git wins, where the boundary falls, the agent as the new user — drawn as inline SVG and served as a **second app from the same vault** as the strategy essay: one store, two entry points, one read key.Open the analysis →](sgit-maps.md)

## Coming next

Two more shapes from [the plan](../admin/plans/why-expansion-plan.md), on the same template: a **two-agent inbox** vault (produced by actually running two sessions against it), which gets the full transcript, its own published read key, and a live embed.

[← Home](../index.md)[The first demo →](vault-app-embed.md)



==============================================================================
# A vault app, live inside this page — sgit.ai demos

> The complete walkthrough: create a vault app, push it, derive and publish the read key, and open the app live inside a sgit.ai page in a sandboxed iframe with a postMessage window.sg bridge.
>
> Page: https://sgit.ai/demos/vault-app-embed.html

[Home](../index.md) / [Demos](index.md) / Vault app embed

# A vault app, live inside this page

Below is an application running out of an encrypted vault, embedded in this page with nothing but a **published read-only key**. This walkthrough is the complete process that produced it — every command, the key that is deliberately public, and the one that never will be.

**The one-sentence mechanism:** the vault's ciphertext is fetched from the SG/Send server over CORS, decrypted in your browser with the read key printed on this page, and the vault's `index.html` is booted inside a sandboxed iframe with a `window.sg` bridge — the same shape SG/Vault's own vault-in-vault embedding uses. No copy of the app or its content exists on sgit.ai.

## The live embed

Click to open it. The status line inside the app will read `content: sg.vfs.readText("content.json") — live from the vault`, which is the bridge proving itself: the app asked the embed host for a vault file and got it.

Loads ~10 encrypted objects from `dev.send.sgraph.ai` and decrypts them here. Nothing you do in it can write — the page only holds a read key.

## How this vault was made, end to end

**1 — Write the app.** A vault app is one self-contained `index.html` — CSS and JS inlined, content in `content.json`, generative SVG instead of image files — plus an `app.json` that auto-launches it. It follows the [authoring contract](../vault/vault-apps.md): no `<link href>`, `<script src>` or `<img src>` against vault paths, content read via `sg.vfs.readText` with an inlined fallback, and `sg-app-ready` posted when rendered.

```
demo-vault-gallery/
├── index.html      # the app — one file, contract-compliant
├── content.json    # the editable content the app reads over the bridge
├── app.json        # { "entry": "index.html", "present": true, "auto_open": true }
└── README.md
```

**2 — Make the folder a vault and push it.**

```
$ sgit init --existing .
  Vault key: <passphrase>:4bshby5n   ← saved to a password manager. Not printed here, not ever.
$ sgit commit -m "Field Notes v1: app, content, README" && sgit push
  Push complete. Pushed 1 commit(s), 4 object(s) uploaded.
```

**3 — Derive the read key.** It is computed one-way from the vault key: it can decrypt everything in the vault and can never be turned back into write access.

```
$ sgit dev derive-keys '<vault-key>'
  read_key: 2848993a68c02a33…   ← this one is safe to publish. See below.
```

**4 — Publish the read key.** Deliberately, in full, in this page's source:

```
vault id : 4bshby5n
endpoint : https://dev.send.sgraph.ai
read key : 2848993a68c02a33ea5582902c391901191e53680d35b36c0e76185d4107ad81
```

Anyone can take those three lines and read this vault — from the CLI (`sgit clone --read-key 2848993a68c0… 4bshby5n`), from their own page, from a script. That is the point: **read access is a capability you can hand out**, without an account, without the host mediating it, and without it ever becoming write access. A write attempt with this key is refused by construction — try it.

**5 — Embed it.** The host on this page is [`assets/vault-embed.js`](../admin/index.md), ~170 lines: derive the ref id with HMAC-SHA256, fetch ciphertext over CORS, decrypt with Web Crypto, boot the app in an iframe with `sandbox="allow-scripts"` (opaque origin — the app gets no cookies, no storage, no reach into this page), and answer its `sg.vfs` calls over postMessage.

## What the app can and cannot do in here

| Capability | In this embed | Why |
|---|---|---|
| `sg.vfs.readText` / `sg.vfs.read` | works | served by the host from decrypted vault objects |
| `sg.loadCss` / `sg.loadJs` | works | same read path, injected into the frame |
| any mutation (`sg.fs.*`, `sg.vault.*`, …) | impossible | the page holds only a read key — there is no write capability to misuse, not even by a bug in the host |
| reach this page, cookies, storage, top navigation | blocked | `sandbox="allow-scripts"` and an opaque origin; the only channel is postMessage |

## Embedding the full SG/Vault UI — the gap closed

The embed above is our minimal host: ~170 lines, enough bridge for a read-only app. The obvious next step was embedding the *real* SG/Vault interface — App-Mode chrome, or the vault browser with its FILES / SGIT / SETTINGS rail. When we first ran that experiment it worked in every respect but one: the credential. The loader documented a read-only format but the client rejected it, and the CLI's `64hex:vault_id` shorthand was parsed as a passphrase, PBKDF2'd, and derived the wrong file ids (we measured `abfd8ea0f1a2` where the vault's real ref id is `11ea50e81f4d` — hence "Vault not found"). We filed both as asks.

**They landed.** The deployed loader now detects a read-key credential as **format 6** — `<64-hex read_key>:<vault_id>`, matching what `sgit clone` already accepted — and, critically, *checks it before the passphrase formats*, which is exactly the ordering bug we hit. It also strips the sgit CLI's canonical key prefixes before detection, so a key pasted straight from new CLI output is understood — including `sgit_rk1_`, the read-only one, which is the form we publish. (Its write-credential sibling is the prefix our own build refuses to let onto this site at all: the release validator treats that string as a leak and fails the build, which is why you will not find it written out here.) Re-running the same experiment against the live build:

| Question | Answer | Evidence |
|---|---|---|
| Can the vault UI be iframed at all? | **Yes** | no `X-Frame-Options`, no `frame-ancestors` |
| Does App Mode work inside a cross-origin iframe? | **Yes — fully** | the complete HUD: toolbar, URL bar, read/write badges |
| Can it open with *only the read key*? | **Yes — now** | all three forms parse in the deployed loader (`hex:id`, `sgit_rk1_hex:id`, and the legacy `id hex`); App Mode booted this Field Notes app from the published read key alone, six SVG studies rendered, the app's own status line reading `content.json` over the bridge |
| Does the vault browser open read-only? | **Yes** | `vault-shell` with the FILES / SGIT / SETTINGS rail, the real decrypted tree (4 files, 10.6 KB), and an explicit `R1 W0` + **Read-only** badge in the chrome |
| Is the SGit view reachable? | **Yes — but still no deep-link** | driving the nav reaches HISTORY / REFS / TREE / BRANCHES / STATUS / REPAIR with both real commits listed; no URL selects a view, so a host page cannot frame the SGit view *in isolation*. The one ask still open. |

So the credential gap is closed, and the consequence is the point of this whole page: **a published read key is now enough to embed the official interface** — no account, no token, no write capability anywhere in the chain. And the mechanism got better than the one we first tested: the UI now ships an **embed protocol**, so the host page hands the key over a validated `postMessage` handshake instead of a URL fragment. The key never appears in any URL, is never written to the frame's storage (it lives in the frame's memory for the session), the frame proves it is the right recipient before the key is sent, and the host gets structured `vault-ready` / `vault-error` events back instead of guessing from load timings.

Below is exactly that — both surfaces, opened with the same published key printed further up this page, loading on click because they pull the full UI from another origin. The area is deliberately wider than this text column, because the vault browser is a full working surface, and there is a full-screen button for vaults with a big UX.

Loads `dev.vault.sgraph.ai` in an iframe and completes the embed handshake. Nothing on sgit.ai ever sees more than the published read key it already prints.

**What is still not possible — precisely.** The two buttons above select a *surface* (App Mode or the vault browser). They cannot select a *view* inside the browser: the SGIT inspector and SETTINGS panels are one click away on the left rail, but the embed message carries only `{key, mode, deepLink}` where `deepLink` is a file path — there is no field that names a view, and view switching stays an in-page event. So "open straight onto the commit history" is still one small protocol field away, and [the briefing](../briefs/briefing-sgvault-ui-embed.md) now states exactly that ask: an optional `view` field on `vault-open`, applied after mount. Everything else on this page works today.

## Honest scope

Two hosts now run on this page, and keeping both is deliberate. The **minimal** host is ~170 lines and shows the protocol with nothing hidden: derive, fetch, decrypt, answer `sg.vfs` over postMessage. The **official** host is the real product — full `window.sg` surface, permissions, HUD chrome, and now an embed handshake that keeps the key out of URLs and storage. Read the small one to understand the mechanism; use the big one to see what a product built on it feels like. Everything above is live and reproducible from the commands on this page.

| Shape | Evidence status | Copy or reference |
|---|---|---|
| Gallery (app + content) | **LIVE** — the embed above reads the real vault on every load | **Reference** — a push to the vault changes this page's embed with no rebuild |

## Related

- [Building vault apps](../vault/vault-apps.md) — the authoring contract this app follows
- [A live site whose host cannot read it](../case-studies/live-vault-docs.md) — the same read path rendering markdown docs
- [Sub-vaults](../vault/sub-vaults.md) — vault-in-vault, the pattern this embed mirrors
- [The plan](../admin/plans/why-expansion-plan.md) — two more demo vaults (a report, a two-agent inbox) follow this template

[← Demos](index.md)[Building vault apps →](../vault/vault-apps.md)



==============================================================================
# The Strategy in Seven Maps — a real document republished from a vault — sgit.ai demos

> The actual SG/Send strategy (eight Wardley Maps, published on LinkedIn in May 2026) served live from an encrypted vault with a published read key — plus the audit that found the original vault could NOT publish its key (its own write credential was inside its content) and the republish pattern that fixed it.
>
> Page: https://sgit.ai/demos/strategy-maps.html

[Home](../index.md) / [Demos](index.md) / The Strategy in Seven Maps

# A real strategy document, republished from a vault

This is not demo content. It is the actual SG/Send strategy — eight Wardley Maps with commentary, written by the founder, [published on LinkedIn](https://www.linkedin.com/feed/update/urn:li:ugcPost:7464691060775120896/) in May 2026 — served live below from an encrypted vault with a published read-only key. And the process of publishing it is itself a security lesson, so that is on this page too.

## The live embed

The vault's own app — the scrollable strategy essay with the eight maps, click-to-zoom included. Every byte, including the PNG maps, is fetched as ciphertext and decrypted here.

~30 encrypted objects (~900 KB, mostly the map PNGs) from `dev.send.sgraph.ai`, decrypted in your browser.

## Why this vault could not simply publish its read key

The original lives in a vault created in May 2026, before today's key practices. Asked "is it OK to share its read key?", we audited it — and the answer was **no**, for reasons worth publishing because they generalise:

| Finding | Why it blocks publishing the read key |
|---|---|
| **The vault's own write credential was inside its content.** A production briefing in the vault documented the clone command — including the vault's read-write token, verbatim. | Publishing the read key would hand every reader the *write* key. This is the general trap: a read key exposes everything ever committed, including documentation that casually quotes credentials. |
| **Server-side bookkeeping with live tokens.**`.vault/owner/public-previews/` held records containing `delete_auth` tokens — capabilities to delete the published previews. | A read key decrypts the whole tree, dot-folders included. Operational bookkeeping and publishable content were in the same trust boundary. |
| **Legacy low-entropy credential.** The vault's keys derive from a legacy dictionary-words-plus-digits token — a small keyspace by construction. | Even with the content clean, "public read, protected write" is only as strong as the write credential. This class of token is being retired for exactly this reason. |

**The fix is the pattern to copy:** republish, don't retrofit. The content was copied out, the credential quotes redacted (with a visible publication note in the affected file), the operational bookkeeping and test debris dropped, and the result committed to a *new* vault (`ookq4mn4`) with a full-entropy key that has never appeared anywhere. Only then was the read key derived and published:

```
# the audit, in one honest line: grep before you publish
$ grep -rniE "token|secret|key|delete_auth" . --include="*.md" --include="*.json"
# the republish
$ sgit init --existing .   # fresh vault, full-entropy key — saved to a password manager
$ sgit commit -m "republished, credentials redacted" && sgit push
$ sgit dev derive-keys '<vault-key>'
  read_key: 451c4c1e28fbb24a…   ← published below, in full, on purpose
```

```
vault id : ookq4mn4
endpoint : https://dev.send.sgraph.ai
read key : 451c4c1e28fbb24a7f350bb3f107b2c103d69ed363167029ef9c9000ff76c07b
```

The original vault is untouched and stays private. Its history — which contains the credential-bearing briefing — is not carried over: a republish is also how you shed a history you cannot publish.

## What this demo adds to the embed host

The [first demo](vault-app-embed.md) was built without image files. This app loads eight PNG maps by setting `img.src` to vault paths — which, inside a sandboxed frame, resolve against an opaque origin and fail. The embed host now does what the real SG/Vault host does: a `MutationObserver` intercepts vault-path images, reads the bytes over the bridge, and swaps in `blob:` URLs. The maps you see above each travelled as ciphertext.

| Shape | Evidence status | Copy or reference |
|---|---|---|
| Report / strategy microsite | **REAL** — a production artefact, published externally in May 2026; not authored for this demo | **Reference** — the embed reads vault `ookq4mn4` live; a push updates this page with no rebuild |

## Related

- [The first demo](vault-app-embed.md) — the walkthrough of the embed mechanism itself
- [The day we leaked our own vault key](../case-studies/exposed-vault-key.md) — the incident behind the audit habits used here
- [Briefing to the SG/Vault UI team](../briefs/briefing-sgvault-ui-embed.md) — the path to embedding the official UI instead of our minimal host

[← First demo](vault-app-embed.md)[All demos →](index.md)



==============================================================================
# sgit, on a Wardley Map — sgit.ai demos

> Six Wardley Maps analysing sgit's positioning — starting with where git wins — drawn as inline SVG and served as a second app from the same encrypted vault as the SG/Send strategy essay: one vault, two entry points, one published read key.
>
> Page: https://sgit.ai/demos/sgit-maps.html

[Home](../index.md) / [Demos](index.md) / sgit on a Wardley map

# sgit, on a Wardley Map

Six maps analysing sgit's own positioning — starting with where git wins, because a map that flatters its author is not a map. It lives as a **second app inside the same vault** as the SG/Send strategy essay: one encrypted store, two entry points, both openable with the one read key already published on this site.

**What is new here technically:** a vault is not limited to one app. This vault (`ookq4mn4`) now carries two — `index.html` (the strategy essay) and `sgit-maps.html` (this analysis) — and the embed below opens the second by passing an `entry` to the same host that opens the first. The maps are not images: each is drawn as inline SVG from data in the page, decrypted in your browser.

## The live embed

The links between the two apps work *inside* the embed: the header of this analysis links to the strategy essay and back, and the embed host remounts the frame on the new entry — vault apps cross-linking under a read key.

Same vault and read key as [the strategy essay demo](strategy-maps.md) — only the entry differs.

## The six maps, in one paragraph each

1. **Version control, today** — git at full strength: a commodity whose moat is the platform layer above it, all of it resting on the host reading plaintext.
2. **The files that cannot follow** — the same need with one changed constraint, and a hole in the map where its foundation should be: nothing on the right is both versioned and unable to read you.
3. **sgit's move** — no new verbs; invert the bottom layer instead. Encrypted, content-addressed objects make the store a commodity *because* it cannot read, and produce one novel component: the publishable read key.
4. **The boundary, on one map** — both chains under one team: code flows right through git; protected files flow through sgit. The split is the layer above the protocol and the substrate below it, never the operations. One folder can run both — this site does.
5. **The new user: agents** — durable memory, plus the serialised diff versus the write-scoped token; the evolve arrows all point away from ambient authority.
6. **The strategy** — commoditise private version control; the value accrues to the layer above, and every component on that layer is already running on sgit.ai, including the page in the embed.

| Shape | Evidence status | Copy or reference |
|---|---|---|
| Structured analysis (positioning) | **LIVE** — authored for sgit.ai from the [boundary-map work](../why/index.md); the maps state where git wins first | **Reference** — the embed reads vault `ookq4mn4` live; pushing a better map updates this page with no rebuild |

## Related

- [The Strategy in Seven Maps](strategy-maps.md) — the SG/Send half, first app in the same vault
- [The boundary map in prose](../why/index.md) — the same argument, as the Why page
- [How the embed works](vault-app-embed.md) — the full walkthrough of the mechanism

[← The strategy essay](strategy-maps.md)[All demos →](index.md)



==============================================================================
# Use cases — sgit

> Who has the problem sgit solves, with a working recipe and an honest evidence status for each: AI agents, professional services, security teams, health and regulated data — plus the underlying workflows.
>
> Page: https://sgit.ai/use-cases/index.html

[Home](../index.md) / Use cases

# Use cases

Two kinds of page here. **Workflows** are the mechanics — what sgit does, on shipped commands. **Situations** are who has the problem, each with a working recipe, an honest evidence status, and a brief you can hand to an agent.

**Reading this as an agent?** Every page on this site has a `.md` twin at the same path — this one is [use-cases/index.md](index.md). Internal links inside the markdown point at markdown, so you can traverse the whole site without parsing HTML. The machine index is [llms.txt](../llms.txt).

## Situations

Each of these is a place where the sentence "this needs version control, and the store must not be able to read it" is literally true. The pages are written to be usable: the setup, the commands, what is proven versus what is a pattern, and an agent brief.

[The lead example### The serialised pull requestAn agent proposes changes to a shared vault while holding **no credential at all** — clone with a public read key, commit on a private branch, emit a diff for human review. The answer to ambient agent authority, built before the guidance recommending it.](serialised-pull-request.md)

[AI agents### Agent state that isn't the vendor's to readDurable memory across sessions and machines, and shared memory between agents, with the store unable to read either. **Evidence: this website.**](ai-agents.md)

[Professional services### Working documents with clientsLegal, M&A, audit, assessment: the deliverable and the working notes, versioned, in a store that cannot read them — and read access you can hand out without an account.](professional-services.md)

[Security teams### Findings about your own weaknessesPentest output and vulnerability data need history, diffs and multi-person workflow — and are the last thing to put in a SaaS you don't control.](security-teams.md)

[Health & regulated### Data that changes what is permissibleWhen the host provably cannot read the content, the conversation stops being about the provider's access controls. Read the caveats on that page before quoting it.](health-regulated.md)

## Workflows

The mechanics underneath those situations. Every one runs on shipped commands — nothing aspirational.

## Private memory for AI agents

An agent's context window ends; its work shouldn't. A vault is just a folder — the agent clones it, reads and writes files normally, commits, and pushes. The next session pulls and continues where the last one stopped. Everything is encrypted before it leaves the agent's machine, so the shared state can hold things you would never put in a third-party database: client documents, security findings, personal data.

```
# session 1
$ sgit clone <vault-key> workspace
$ sgit commit -m "session 1: research notes" && sgit push
# session 2, days later, different machine
$ sgit pull   # continue exactly where session 1 stopped
```

[Full agent guide →](../docs/agents.md)

## Multi-agent collaboration

Give each agent its own named branch. Every clone also gets a private clone branch whose key never leaves that agent's session, so agents cannot trample each other's work-in-progress. Work meets on named branches, and a human reviews the merge. Agents can inspect each other's commits read-only with `sgit history show` and `sgit history diff` — without pulling, so looking never means merging.

```
# agent A  $ sgit branch new feature-analysis … sgit push
# agent B  $ sgit branch new feature-report   … sgit push
# human    $ sgit pull → review → merge, with sgit resolve --show on conflicts
```

## Human ↔ agent workspaces

The same vault has two doors: you in the SG/Vault web app, the agent in the CLI. The browser client is an independent implementation of the same wire format — you browse, edit and review in a UI while the agent works the same files from the terminal. Both sides see each other's commits; neither side's plaintext ever touches the server. (How the browser side works: [sgraph.ai](https://sgraph.ai).)

```
$ sgit vault info
  Web URL: https://vault.sgraph.ai/en-gb/#<your-vault-key>
```

## Encrypted folders with history

A shared folder where the hosting provider cannot read the contents — with commits, diffs, and rollback. Work offline, commit locally, push when ready; restore any prior version with `sgit history revert`. Vault-level `backup` and `restore` produce portable archives, and `sgit vault move` rotates keys if a key is ever exposed.

```
$ sgit init --existing        # vault-ify a folder you already have
$ sgit commit -m "baseline" && sgit push
$ sgit history revert --commit obj-cas-imm-b2d70f   # roll back
```

## Signed & encrypted file exchange

Alongside vault sync, sgit ships a PKI toolset: generate keypairs, exchange public keys as contact bundles, then sign, verify, encrypt and decrypt individual files for named recipients — useful when a file has to travel outside a vault but still needs integrity and confidentiality.

```
$ sgit pki keygen --label "release keys"
$ sgit pki sign report.pdf --fingerprint <fp>
$ sgit pki encrypt report.pdf --recipient <fp>
```

[← Why this exists](../why/index.md)[Documentation →](../docs/index.md)



==============================================================================
# The serialised pull request — sgit use cases

> An agent contributes to a shared vault holding no credential at all: clone with a public read key, commit on a private branch, emit a diff; a person imports, reviews and merges. The ambient-authority problem it removes, the 5 Aug 2026 Black Hat grounding, and the honest shipped-vs-pattern table.
>
> Page: https://sgit.ai/use-cases/serialised-pull-request.html

[Home](../index.md) / [Use cases](index.md) / The serialised pull request

# The serialised pull request

An agent clones a public vault needing no credential at all, makes changes, commits, and emits a diff. A person imports that diff on another machine, reviews it, and merges. No token was issued, so no token could be stolen, scoped too widely, or left unrevoked.

## The problem: ambient authority

The standard way to let an agent contribute to a repository is to give it a credential — and the credential is nearly always bigger than the task. One widely used coding agent held a token scoped to *every repository its developer had authorised*. The platform capability that would fix this — a user-minted, short-lived, single-repository token — has been an open feature request since June 2026, which is the polite way of saying it does not exist.

The consequences stopped being theoretical this month. Research disclosed at Black Hat on **5 August 2026** showed that a GitHub issue opened by an account with *no repository privileges* was enough to reach CI secrets in the vendors' own repositories — for three leading agents, under each vendor's default, unmodified workflow configuration. The attacker did not break anything; they asked a confused deputy to use authority it already held. That is what ambient authority means, and every write-scoped agent token is a standing instance of it.

## The workflow

In the project lead's own words, from the session where it happened:

> "I got Claude to clone a vault, a public repo, and I didn't need any permissions. Then Claude made a bunch of changes, then I got Claude to create commits and give me a diff. On another machine I cloned that vault, imported the diff, saw the changes, and then I merged them. Fundamentally, it's like a serialised pull request."

```
# the agent's side — no credential at any point
$ sgit clone --read-key <published-read-key> <vault-id> work
# … changes, commits on the private clone branch …
$ sgit history diff --json > proposed-changes.json   # the serialised artefact

# the human's side, on another machine
$ sgit clone '<vault-key>' review
# import the diff, review it, merge, push — see "honest mechanics" below
```

Four properties, and each is the strong form of something a platform PR only approximates:

- **No credential is issued at all.** Stronger than a short-lived scoped token: there is nothing to steal, nothing to expire, nothing to revoke, and nothing for an injected instruction to spend.
- **The artefact is inspectable before it takes effect.** A diff is reviewed; a write is discovered. The privileged action happens on the reviewer's machine, after human eyes.
- **Provenance survives per commit**, not per session — the history records what was proposed, not just what was merged.
- **It is capability-shaped, not trust-shaped.** It assumes no shared platform accounts and no fork write access, and the artefact moves by any channel — a vault, an email, a queue.

Published security guidance now independently recommends exactly this shape: run analysis in a read-only job holding no publishing credentials, and pass a constrained, reviewed artefact into a separate privileged step — never one job that both consumes untrusted input and can publish. Having built the recommended control *before* the recommendation is a stronger claim than any feature comparison, so we make it plainly.

## The honest mechanics

What is shipped versus what is pattern, checked against the CLI rather than asserted:

| Step | Status today |
|---|---|
| Credential-free clone of a public vault (read key only) | **Shipped** — `sgit clone --read-key`; this site publishes working read keys on its [demo pages](../demos/index.md) |
| Private-branch commits that cannot touch the shared branch | **Shipped** — the [two-branch model](../docs/two-branch-model.md) |
| Emit the diff as a machine-readable artefact | **Shipped** — `sgit history diff --json` |
| First-class import: `sgit diff apply` | **Not shipped.** The workflow was performed, but the import half was review-and-merge by hand. A [brief to the CLI team](../briefs/brief-serialised-diff-and-ignore.md) asks for `sgit diff export` / `sgit diff apply` as first-class commands |
| A published specification of the diff format | **Not published.** If this is the headline workflow, its artefact needs a spec a third party can implement — same brief |

## Evidence status

PARTIAL — performed once, import not yet first-class

The workflow ran end to end exactly as quoted, and every step on the agent's side is a shipped command exercised daily. What keeps this from PROVEN is the import: until `sgit diff apply` exists, the human side leans on manual review-and-merge, and a workflow with a manual middle is a pattern, not a product. The brief is filed; this page upgrades itself when the commands land.

## Brief for an agent

```
$ curl -s https://sgit.ai/use-cases/serialised-pull-request.md
```

> Read https://sgit.ai/use-cases/serialised-pull-request.md. Clone the vault I name using only its read key, make the changes I describe on your clone branch, commit with clear messages, then emit `sgit history diff --json` and give me the output as a file. Do not ask for, hold, or use any write credential at any point.

## Related

- [The two-branch model](../docs/two-branch-model.md) — why the agent's commits cannot reach the shared branch
- [Agent state that isn't the vendor's to read](ai-agents.md) — the memory half of the agent story
- [The boundary map](../why/index.md) — where this sits: proposing changes without write access is present; the hosted review interface is not

[← Use cases](index.md)[AI agents →](ai-agents.md)



==============================================================================
# Agent state that isn't the vendor's to read — sgit use cases

> Durable and shared memory for AI agents in a store that cannot read it: the session protocol, multi-agent branches, sparse clones, and the evidence (this website).
>
> Page: https://sgit.ai/use-cases/ai-agents.html

[Home](../index.md) / [Use cases](index.md) / AI agents

# Agent state that isn't the vendor's to read

An agent's context window ends; its work shouldn't. Where that work goes is a storage decision that quietly becomes a disclosure decision.

**A worked example, opened with a read key.** The question this page circles — an agent acting with a human's ambient authority because that is the only credential on offer — has a published vault devoted to it: [Agentic Browser Isolation](../demos/vaults/agentic-browser-isolation/index.md), a living risk graph asking whether an agent browses inside *your* browser with *your* logged-in sessions, or an isolated one with a scoped identity. It is vendor-neutral, it cites its evidence outward, and its mechanism is worth borrowing: every altitude has one named owner, a risk stays pending until that owner accepts it personally, and only an accepted risk escalates.

## The problem

Every durable-agent design needs somewhere to put state between sessions: notes, intermediate findings, drafts, the record of what was already tried. In practice that is a database, a repo, or a vendor's memory feature — all of which the provider can read.

That is fine while the state is "which step am I on". It stops being fine the moment the state contains the client's documents, the security findings, the unreleased code, the personal data. At that point the question is no longer about engineering: it is whether you are permitted to put that material there at all, and the answer often arrives from someone who does not care how good the access controls are.

The second half of the problem is coordination. One agent needs durable memory; several agents need *shared* memory with isolation, a review step, and a way to look at each other's work without merging it. That is version control — and version control's usual answer is a host that reads everything.

## What sgit does about it

A vault is a folder. The agent clones it, reads and writes files normally, commits, and pushes; the next session pulls and continues. Encryption happens before anything leaves the machine, so the shared state can hold what a third-party database cannot. Each clone also gets a [private branch](../docs/two-branch-model.md) whose key never leaves that session, so agents can work concurrently without trampling each other, and meet on a shared named branch.

## The recipe

**One agent, many sessions.** The whole pattern is two commands at the session boundaries:

```
# session start — always, before anything else
$ sgit clone <vault-key> workspace   # or: sgit pull
# … the agent works normally: read, write, edit files …
# session end — always, before the context runs out
$ sgit commit -m "session 4: drafted the migration plan" && sgit push
```

**Write a single file without a working copy** — the agent-shaped command, with machine-readable output:

```
$ sgit write notes/findings.md --file ./findings.md \
      --message "add findings" --push --json
```

**Several agents, one vault.** Give each a named branch; let a human own the merge:

```
# agent A  $ sgit branch new research  … sgit push
# agent B  $ sgit branch new drafting  … sgit push
# either agent, read-only — looking is not merging
$ sgit history show <commit>
$ sgit history diff --remote
```

**Big vault, small task.** A sparse clone keeps the agent's working set — and its token budget — proportionate to the job:

```
$ sgit clone <vault-key> workspace --sparse notes/ drafts/
```

## Evidence status

PROVEN

**This website is the evidence.** It is built and published by Claude Code sessions that share state through a vault; the site you are reading was deployed by pushing that vault. Two independent details are worth more than the claim:

- The [Deploy section](../deploy/index.md) is maintained by a *different* team's agent, in a different vault, and rendered here by decrypting it in your browser. Neither agent has access to the other's repository.
- The [cross-team briefs](../briefs/index.md) and the [key-leak incident](../case-studies/exposed-vault-key.md) were written by one agent for another team to act on — including the incident where this agent leaked a key into a public commit, which is the sort of thing a marketing page omits.

Honest limit: n is small, and the agents are supervised by the people who wrote the tool.

## Brief for an agent

Paste this into an agent that has the [sgit skill](../skills/index.md) installed, or point it at the markdown directly.

```
# everything on this site is readable as markdown — no HTML parsing needed
$ curl -s https://sgit.ai/use-cases/ai-agents.md
$ curl -s https://sgit.ai/llms.txt          # the index of everything
```

> Read https://sgit.ai/use-cases/ai-agents.md and https://sgit.ai/docs/agents.md. Then set up agent state in a vault for this project: create the vault, structure the folders as described, commit and push, and report the vault key back to me once — I will store it. Do not write the key to any file in the repository. Then write a short SESSION.md describing the clone/pull-at-start and commit/push-at-end protocol so future sessions follow it.

That last sentence matters. We have a [write-up of the day we got it wrong](../case-studies/exposed-vault-key.md).

## Related

- [Working with AI agents](../docs/agents.md) — the full agent-facing surface: `--json` everywhere, the session pattern, multi-agent collaboration
- [The two-branch model](../docs/two-branch-model.md) — why every clone gets a private branch
- [Skills](../skills/index.md) — packaged instructions that make an agent competent at this without you explaining it

[← Use cases](index.md)[Professional services →](professional-services.md)



==============================================================================
# Working documents with clients — sgit use cases

> Engagement vaults for legal, M&A, audit and assessment work: versioned working notes, review as branches, and read-only handover with a published read key.
>
> Page: https://sgit.ai/use-cases/professional-services.html

[Home](../index.md) / [Use cases](index.md) / Professional services

# Working documents with clients

Legal, M&A, audit, security assessment. The material that most needs versions and review is the material that least belongs readable on a third party's disk.

## The problem

A engagement produces two bodies of text: the deliverable, and everything behind it — working notes, drafts, the evidence, the arguments that did not survive. Both need history: who changed what, when, and what the previous version said. Both need more than one person in them.

The usual tools split badly. A shared drive gives you collaboration and no history worth the name. A private repo gives you history and hands the whole engagement to a host. Email attachments give you neither and produce six versions named `final_v3_JS_edits`.

And then the engagement ends, and you need to hand the client something they can keep and verify — without giving them an account on your systems, and without them needing your tooling to read it later.

## What sgit does about it

The working set is a vault: full history, branches, diffs, three-way merge, all client-side. The store holds ciphertext under opaque ids, so "where is this hosted" and "who can read this" stop being the same question — including for the host's staff, a subpoena served on the host, or a breach of it.

For handover, a **read key** is derived one way: it decrypts and cannot be turned into write access. You can give a client read access to a specific vault without giving them anything else, and without the host mediating it.

## The recipe

**One vault per engagement.** Keep the boundary at the vault, not at a folder — it is the unit of access.

```
$ sgit create acme-acquisition
  Vault key: <passphrase>:<vault-id>   ← password manager, now. There is no reset.
$ mkdir deliverable working evidence && sgit commit -m "structure" && sgit push
```

**Review as branches**, so the draft in flight is never the draft on the record:

```
$ sgit branch new draft-2 && sgit push
$ sgit history diff --commit <prev>      # exactly what changed since the last version
$ sgit resolve --show                     # when two reviewers touch the same file
```

**Hand over read-only** at the end, or throughout:

```
$ sgit dev derive-keys '<vault-key>'    # the read key, derived one way
# the client, with nothing but that key:
$ sgit clone --read-key <read-key> <vault-id> engagement
# …and a write attempt is refused, which they can verify themselves
```

**Archive on close.** The archive is self-contained ciphertext — keep it wherever your retention policy says, including somewhere you don't trust:

```
$ sgit vault backup --include-key       # store the key separately from the archive
```

## Evidence status

PATTERN — not yet evidenced publicly

The mechanics above are all shipped commands and are exercised daily; what we do **not** have is a published professional-services deployment we can point you at. Treat this page as a design that fits the constraints, not as a case study.

Two things to weigh before you use it on a real engagement: sgit is in [beta](../docs/limitations.md), and there is no key recovery — if your firm's key management is not already real, this trade-off will find you. If you do run this pattern, we would like to write it up: [say so in the open](https://github.com/SGit-AI/SGit-AI__CLI/issues).

## Brief for an agent

Paste this into an agent that has the [sgit skill](../skills/index.md) installed, or point it at the markdown directly.

```
# everything on this site is readable as markdown — no HTML parsing needed
$ curl -s https://sgit.ai/use-cases/professional-services.md
$ curl -s https://sgit.ai/llms.txt          # the index of everything
```

> Read https://sgit.ai/use-cases/professional-services.md and https://sgit.ai/docs/agents.md. Then set up an engagement vault for this project: create the vault, structure the folders as described, commit and push, and report the vault key back to me once — I will store it. Do not write the key to any file in the repository.

That last sentence matters. We have a [write-up of the day we got it wrong](../case-studies/exposed-vault-key.md).

## Related

- [When NOT to use sgit](../docs/limitations.md) — read this before committing a client engagement to it
- [SG/Vault](../vault/index.md) — the browser app, so a client can read without installing anything
- [Security model](../security/index.md) — precisely what the server can and cannot see

[← AI agents](ai-agents.md)[Security teams →](security-teams.md)



==============================================================================
# Findings about your own weaknesses — sgit use cases

> Pentest and vulnerability findings with history, diffs and multi-person workflow, in a store that cannot read them — plus the key-hygiene rule we learned the hard way.
>
> Page: https://sgit.ai/use-cases/security-teams.html

[Home](../index.md) / [Use cases](index.md) / Security teams

# Findings about your own weaknesses

Pentest output is a map of how to get in. It needs history, diffs and several people — and it is the last thing to hand to a SaaS you don't control.

## The problem

Assessment work produces exactly the document an attacker would most like to have: what is exposed, how to reach it, what has not been fixed yet, and which excuse each owner gave. It is also work that genuinely needs version control — findings get re-tested, severities change, remediation gets tracked across months, and several people edit the same report.

So it goes into a ticketing system or a shared repo, because those are the tools that do the workflow. Both are readable by the provider, and both are now a single place holding the complete attack path for the organisation. That is a concentration of risk that a security team, of all teams, can see clearly.

## What sgit does about it

The findings live in a vault: versioned, diffable, multi-person, and ciphertext everywhere but on the machines of the people working on them. The host is a key-value store for opaque ids; compromising it yields encrypted objects and traffic timing.

It also gives you a defensible answer to the question that follows an incident — "where was this stored, and who could read it?" — that does not depend on a vendor's access-control configuration being correct on the day.

## The recipe

**A vault per engagement or per client**, with the report and the raw evidence separated so you can share one without the other:

```
$ sgit create acme-pentest-2026q3
$ mkdir report evidence retest && sgit commit -m "structure" && sgit push
```

**Re-test cycles as commits**, so severity changes are a diff rather than a claim:

```
$ sgit commit -m "retest: SQLi in /search fixed, XSS in /profile still open"
$ sgit history log --oneline
$ sgit history diff --commit <initial-report> --files-only
```

**Deliver read-only** to the client, keeping the write side entirely on your team:

```
$ sgit dev derive-keys '<vault-key>'
$ sgit clone --read-key <read-key> <vault-id> report   # what the client runs
```

**One rule, learned the hard way:** never let the vault key reach a tracked file, a CI variable, or a chat message. Put a check in your pipeline that greps for it, and make that check read the secret from somewhere ignored rather than hardcoding it. That is not hypothetical advice — it is the exact fix from [our own incident](../case-studies/exposed-vault-key.md).

## Evidence status

PARTIAL — adjacent evidence only

We have not published a pentest firm running this. What we can point at is the closest thing we own: this project's [exposed-key incident](../case-studies/exposed-vault-key.md) — a real key leak, in a public commit, with the detection gap, the rekey, the measured blast radius (336 objects out, 90 in, zero overlap) and the structural fix written up rather than quietly patched.

That write-up is the artefact a security team would actually judge us on, so it is on the site rather than in a drawer. If you run assessment work on sgit, the failure modes you hit are the ones we want to hear about.

## Brief for an agent

Paste this into an agent that has the [sgit skill](../skills/index.md) installed, or point it at the markdown directly.

```
# everything on this site is readable as markdown — no HTML parsing needed
$ curl -s https://sgit.ai/use-cases/security-teams.md
$ curl -s https://sgit.ai/llms.txt          # the index of everything
```

> Read https://sgit.ai/use-cases/security-teams.md and https://sgit.ai/docs/agents.md. Then set up an assessment vault for this project: create the vault, structure the folders as described, commit and push, and report the vault key back to me once — I will store it. Do not write the key to any file in the repository. Also add a pre-push check that fails if the vault key appears in any tracked file, reading the secret from a gitignored path rather than hardcoding it.

That last sentence matters. We have a [write-up of the day we got it wrong](../case-studies/exposed-vault-key.md).

## Related

- [If a vault key is exposed](../case-studies/exposed-vault-key.md) — the runbook and the case study
- [Security model](../security/index.md) — the crypto stack and the honest side channels
- [Self-hosting](../deploy/index.md) — when the storage layer has to be yours too

[← Professional services](professional-services.md)[Health & regulated →](health-regulated.md)



==============================================================================
# Data that changes what is permissible — sgit use cases

> What client-side encryption does and does not change for regulated data, stated precisely and without compliance claims.
>
> Page: https://sgit.ai/use-cases/health-regulated.html

[Home](../index.md) / [Use cases](index.md) / Health & regulated

# Data that changes what is permissible

When the host provably cannot read the content, the conversation stops being about the provider's access controls — because there is nothing for them to control access to.

**Read this first.** sgit holds no compliance certification of any kind — no HIPAA attestation, no ISO 27001, no SOC 2, no GDPR adequacy finding. Nothing on this page is legal or regulatory advice, and client-side encryption does not by itself make a processing activity lawful. What follows is a description of a technical property and what it does and does not change. Your compliance function decides the rest.

## The problem

Regulated data drags its rules with it. The moment a document is stored somewhere a third party can read, that third party is in scope: they become a processor, they need an agreement, their jurisdiction matters, their breach becomes your notification, and their sub-processors become your problem too. Most of the effort in these projects is not securing the data — it is the paperwork proving who could have seen it.

And the work itself still needs versions and collaboration, which is why it so often ends up in a general-purpose tool with a data-processing addendum stapled on.

## What the property actually changes

Content is encrypted before it leaves the client; the store holds ciphertext under opaque ids and never receives a key. That moves specific arguments, and it is worth being exact about which:

| Question | What changes |
|---|---|
| Can the host read the content? | No — not with a warrant, a rogue administrator, or a breach. This is the strong claim, and it is structural rather than procedural. |
| What does the host still learn? | The vault id, the size of each object, and request timing. Sizes and timing are a real if narrow side channel — see the [security page](../security/index.md). |
| Does this remove the processor relationship? | **Not automatically.** Storing ciphertext may still be processing, depending on the regime and on who holds keys. Ask your counsel; do not take a vendor's word for it, including ours. |
| Does it help with access logging and minimisation? | Partly: a vault is a natural boundary, and read access is a key rather than an account, which makes "who could read this" a shorter list. |
| Does it help with retention and deletion? | Partly, and awkwardly: history keeps old ciphertext until pruned, so "delete" needs thought. See [limitations](../docs/limitations.md). |

## The recipe

**Scope one vault to one purpose.** The vault is the access boundary, so make it match the lawful basis for the data in it — not the team, not the project folder.

```
$ sgit create study-1234-analysis
$ sgit commit -m "structure" && sgit push
```

**Key management is the whole control.** There is no reset and no recovery: the key is the access control, so it has to be managed like one — in a password manager or an HSM-backed store, with a named owner and a documented rotation path.

```
$ sgit vault backup --include-key     # archive and key stored separately
$ sgit vault rekey                          # rotation — see the exposed-key runbook
```

**Self-host if the storage layer is itself in scope.** The [deployment guidance](../deploy/index.md) covers Docker, AWS, GCP and a static host — and is itself served from an encrypted vault, which is a small demonstration of the property.

## A worked example you can open right now

The abstract version of this page is "the host cannot read it". The concrete version is a vault you can open in your browser in the next ten seconds: [**the Supplement Stack vault**](../demos/vaults/supplement-stack/index.md) — a real, patient-held health record, published with a read key.

It is worth reading because it answers the questions this page raises in the specific rather than the general:

| The question | How that vault answers it |
|---|---|
| Who holds the data? | The patient. The vault is theirs; the write key never leaves them |
| How is it shared with a clinician? | By handing over a **read key** — no account on anyone's platform, no PDF emailed into permanent circulation. The reader sees everything and can change nothing |
| What stops the app doing more than it should? | `app.json` grants write over `adherence/` and nothing else. The record-keeping app cannot alter the record it reports on — least authority, declared in the vault |
| Where does AI fit without being dangerous? | A model does the fuzzy work (reading amounts off a label photograph, each value traceable back to its image); **code** does the exact work (summing them). Every fuzzy step is checkable against its source |
| Does it give medical advice? | No — and that is designed in. It computes the total nobody else computes and produces a *briefing for somebody qualified*, with the open questions listed. It never concludes |
| Whose reference values? | UK RNIs and EFSA upper limits, named and dated, explicitly not US Daily Values — because comparing a UK intake against US references without saying so is a quiet error |

It is a demonstration rather than a deployed clinical system, and it makes no compliance claim of any kind — but every mechanism above is running, readable, and open to inspection with the key on its page.

## Evidence status

PATTERN — and the most caveated page here

No published healthcare or regulated-industry deployment, no certification, and no audit of the implementation by a third party. What exists is: standard primitives (AES-256-GCM, PBKDF2-SHA256 at 600k, HKDF) with no custom cryptography, ~4,000 tests, byte-for-byte test vectors against the browser's Web Crypto, two independent implementations of the same wire format, and a [published threat model](../security/index.md) that names its own side channels.

That is evidence of engineering care. It is not evidence of compliance, and we are not going to blur the two.

## Brief for an agent

Paste this into an agent that has the [sgit skill](../skills/index.md) installed, or point it at the markdown directly.

```
# everything on this site is readable as markdown — no HTML parsing needed
$ curl -s https://sgit.ai/use-cases/health-regulated.md
$ curl -s https://sgit.ai/llms.txt          # the index of everything
```

> Read https://sgit.ai/use-cases/health-regulated.md and https://sgit.ai/docs/agents.md. Then set up a scoped vault for regulated data for this project: create the vault, structure the folders as described, commit and push, and report the vault key back to me once — I will store it. Do not write the key to any file in the repository. Do not claim any compliance property in what you write; describe only the technical behaviour.

That last sentence matters. We have a [write-up of the day we got it wrong](../case-studies/exposed-vault-key.md).

## Related

- [Security model](../security/index.md) — including what the server still observes
- [When NOT to use sgit](../docs/limitations.md) — retention, deletion and the key-loss trade-off
- [Run your own server](../deploy/index.md) — when the storage layer must be in your own boundary

[← Security teams](security-teams.md)[All use cases →](index.md)



==============================================================================
# Case studies — sgit.ai

> Worked accounts of things that actually happened, including the ones that went wrong: a leaked vault key and its rekey, and the architecture of a live site whose host cannot read it.
>
> Page: https://sgit.ai/case-studies/index.html

[Home](../index.md) / Case studies

# Case studies

Things that actually happened, written up while the details were still checkable — including the ones that went wrong. Each is a worked account with the mechanism, the numbers, and what changed as a result.

**What counts as a case study here:** a specific event or system, with evidence a reader can verify — commands they can run, numbers we measured, or a live page they can open. Not a pattern, not a design we like the look of. Patterns live in [use cases](../use-cases/index.md), which label their evidence honestly; if a use case ever earns a real deployment, its write-up lands here and the two link to each other.

## Published

[Incident### The day we leaked our own vault keyAn agent hardcoded this site's vault passphrase into a tracked file as part of an anti-leak check. It reached three public commits and was caught only because someone asked. The runbook, the rekey, the measured blast radius — 336 objects out, 90 in, zero overlap — and the structural fix.Read the incident →](exposed-vault-key.md)

[Workflow### One working tree, two version control systemsThis site's own development model: one folder that is both an sgit vault and a git repository, two pushes per release, the one-file boundary that makes it safe, and the ordering rule that keeps the git mirror true to the vault.Read the workflow →](one-tree-two-remotes.md)

[Architecture### A live site whose host cannot read itTwo Claude Code sessions, two encrypted vaults, one page: how the Deploy section is fetched as ciphertext from an SG/Send server and decrypted in your browser, with the object model, the cache tiers and the request timeline drawn out.Read the architecture →](live-vault-docs.md)

## How these are written

Same shape every time, so they stay comparable and so an agent can parse them:

- **What happened** — the sequence, in order, with timestamps or commit ids where they exist.
- **The mechanism** — why it happened, at the level of the object model or the code, not at the level of "human error".
- **The numbers** — measured, not estimated, and stated even when they are unflattering.
- **What changed** — the structural fix, and the check that stops it recurring. A write-up with no change attached is a story, not a case study.
- **What we still do not know** — stated rather than smoothed over.

The incident write-up is the template for the uncomfortable kind. It names the agent that made the mistake, the detection gap that let it survive three commits, and the cost of the fix — because a project that hides that class of mistake is the one to worry about.

## Related

- [Use cases](../use-cases/index.md) — the patterns, each with an explicit evidence status
- [Cross-team briefs](../briefs/index.md) — what this site's agent hands to other teams, and what they hand back
- [Release history](../admin/versions.md) — every change to this site, with the vault commit that carried it

[← Home](../index.md)[Use cases →](../use-cases/index.md)



==============================================================================
# One working tree, two version control systems — sgit.ai case study

> How this site is developed in a single folder that is both an sgit vault and a git repository: what each remote carries, the .gitignore boundary that makes it safe, why the encrypted ref always looks dirty to git (fresh AES-GCM IVs), and the release script that refuses to finish until both remotes are in sync.
>
> Page: https://sgit.ai/case-studies/one-tree-two-remotes.html

[Home](../index.md) / [Case studies](index.md) / One tree, two remotes

# One working tree, two version control systems

This site is developed in a single folder that is simultaneously an sgit vault and a git repository. Every release pushes both. This page is the workflow, the boundary that makes it safe, the one ordering rule that keeps the mirror true, and the script that enforces it.

## What happened

The folder that holds this site has two version control directories side by side:

```
sgit-ai-website/
├── .git/          → github.com/SGit-AI/SGit-AI__Website  (public mirror + Pages deploy)
├── .sg_vault/     → an SG/Send vault                     (encrypted history + live vault)
└── index.html, why/, case-studies/, admin/ …         ← the same files, once
```

They are not two copies kept in agreement. They are two version control systems pointed at **one directory** — `git status` and `sgit status` describe the same bytes. There is no synchronisation step because there is nothing to synchronise; a release is simply two pushes of the same tree:

```
$ sgit commit -m "site v0.2.1: …" && sgit push   # encrypted history → SG/Send
$ git add -A && git commit && git push            # public mirror → GitHub → Pages
```

Each remote does a different job. The git push is what deploys — a GitHub Action publishes the tree to GitHub Pages (excluding `.sg_vault/`, which the public site does not need). The sgit push is what other agents read — this site's vault is cloned and pulled by the Claude Code sessions that build it, and the encrypted store in the git repo doubles as a full off-site mirror of the vault.

## The boundary that makes it safe

The entire pattern rests on one file: `.gitignore`. Everything encrypted **is** committed to git — 900+ objects under `.sg_vault/bare/`, all ciphertext under opaque ids. What is excluded is exactly the plaintext tier:

```
.sg_vault/local/     # vault key, access token, private PEM — plaintext, never committed
.sg_vault/work/      # scratch state
*.pem
```

That is the whole rule, and it is worth stating as a condition rather than a pattern: committing ciphertext alongside plaintext is right *for a public site like this one*, where the working tree is meant to be published anyway. For a confidential vault the same layout is a leak-audit boundary — one bad `.gitignore` edit away from publishing the plaintext tree. The [git repos inside vaults](../vault/git-and-vaults.md) page covers which side of that line a given project is on.

Because the boundary is one file, it gets a machine check, not a convention. The build's validator reads the vault passphrase from the gitignored `local/` tier at runtime and scans every tracked file for it — so a key that reaches the tree fails the build by construction. That check exists because of [the day it actually happened](exposed-vault-key.md): an agent hardcoded this site's passphrase into a tracked file, it survived three public commits, and the vault had to be rekeyed. The tripwire is the structural fix, and the release script below refuses to push unless it has run.

## The one ordering rule: sgit first, then git

Almost everything in the shared store is content-addressed — an object's name is the hash of its ciphertext, so it never changes under its id and the two systems can never disagree about it. Exactly one file is mutable: the vault's HEAD pointer, the **ref**. Every real `sgit push` rewrites it, and that makes the order of the two pushes matter:

```
✓ sgit commit && sgit push     # 1st — writes the new ref
✓ git add -A && git commit && git push   # 2nd — captures that exact ref
```

Done in this order, the git mirror always carries the ref the push just wrote, and a clean `git status` is the normal end state of every release — reads and no-op operations (`ls`, `history`, `status`, `pull`, `fetch`) do not rewrite the ref, so nothing drifts between releases. We verified both claims by testing them.

Reverse the order and the failure is quiet: commit git first and the mirror carries the *previous* ref — in sync by bytes, one commit behind in meaning. Push sgit without a following git commit and the ref shows as modified in `git status`.

One property to know when reading that modified flag: **the ref's bytes carry no information about staleness.** AES-GCM encrypts with a fresh random IV on every write, so a rewritten ref never byte-matches its previous encryption even when it decrypts to the same commit id. "Dirty" therefore does not mean the mirror is stale, and byte-equality would not mean it is current — the only real answers are decrypting the ref or asking `sgit status`. This is also why `.gitattributes` marks the store `binary -diff -merge`: a textual diff of ciphertext is noise, and a git merge of two encrypted refs would produce garbage that decrypts to nothing.

## What changed: the release script

Two pushes with no enforcement is an invitation to forget one — push only sgit and the site never deploys; push only git and the live vault (the one other sessions clone) falls behind. So the release is now one script, [`admin/build/release.sh`](../admin/index.md), and it is deliberately strict:

```
$ ./admin/build/release.sh "site v0.2.2: describe the release"
1. build     — regenerate every page, markdown twin, llms*.txt, sitemap
2. validate  — 90+ file checks, including the key-leak tripwire; any failure aborts
3. sgit      — commit + push the vault, verify "in sync with remote"
4. git       — commit + push, verify local HEAD == origin
5. confirm   — both remotes reported in sync, or exit 1 loudly
```

The ordering inside the script is the rule above, made unforgettable: sgit pushes before git commits, and the expected end state of every release is a clean tree. Two further design points. The script never prints the vault key — it deliberately avoids the commands that would (some sgit inspection commands echo it), because a release log is exactly the kind of artefact that ends up pasted somewhere public. And it will not push *either* remote until the validator has passed, so the key-leak scan and the structural checks gate both histories, not just the deployed one.

## The numbers

| What | Count |
|---|---|
| Files in the shared working tree | ~120 |
| Encrypted objects committed to git under `.sg_vault/bare/` | 933 |
| Plaintext files excluded from git (the `local/` tier) | 5 — key, token, PEM, config, base_url |
| Mutable files in the store (the false-drift class) | 1 — the ref |
| Releases shipped through this workflow so far | every version on the [release history](../admin/versions.md) |

## What we still do not know

- **History depth differs and we accept it.** The vault was rekeyed after the key leak, which reset its history; git kept the full history across the rekey. The two histories agree from that point forward but are not equal before it. For this site that is fine; for an audit-grade deployment you would want the equivalence stated precisely.
- **The IV churn is cosmetic but not free.** Every release commits a re-encrypted ref to git — a 69-byte file that changes on every push forever. Harmless at this scale; a vault with many mutable refs would want them out of git or normalised.

## Related

- [Git repos inside vaults](../vault/git-and-vaults.md) — the general pattern, including the confidential-vault caution
- [The day we leaked our own vault key](exposed-vault-key.md) — why the tripwire exists
- [A live site whose host cannot read it](live-vault-docs.md) — what the sgit push feeds
- [Admin & engineering](../admin/index.md) — the build system this script belongs to

[← Case studies](index.md)[Git repos inside vaults →](../vault/git-and-vaults.md)



==============================================================================
# Security model — sgit

> sgit's zero-knowledge security model, precisely stated: the crypto stack, what the server can and cannot see, key strength, and the open security process.
>
> Page: https://sgit.ai/security/index.html

# Security model

Zero knowledge, precisely stated: every file is encrypted on your machine before upload, keys are derived locally from your vault key, and the server stores ciphertext under opaque identifiers. This page tells you exactly what that means — including what the server *can* see.

## What the server sees — and never sees

| The server never sees | The server does see |
|---|---|
| File contents (encrypted client-side, AES-256-GCM) | The vault ID (an opaque random identifier) |
| Filenames and folder structure | Encrypted object sizes |
| Commit messages and branch names | Timing of reads and writes |
| Your vault key or any derived key | Approximate activity volume (object counts) |

We state the right-hand column deliberately. Traffic analysis of sizes and timing is a real (if narrow) channel, and pretending otherwise would be marketing, not security.

## The crypto stack

| Layer | Construction |
|---|---|
| Content encryption | AES-256-GCM, 12-byte IV, 16-byte tag — byte-compatible with the browser's Web Crypto API |
| Key derivation from the vault key | PBKDF2-HMAC-SHA256, 600,000 iterations, distinct per-vault salts for read and write keys |
| Purpose-specific keys | HKDF-SHA256 — per-file keys and a structure key, one-way derived from the read key |
| Server-side identifiers | HMAC-SHA256-derived opaque IDs — the server addresses files it cannot name |
| Object identity | Content-addressed: `obj-cas-imm-<sha256-prefix>` over ciphertext, enabling dedup without plaintext knowledge |

One precision note, because precision beats marketing: the key hierarchy derives a *structure key* (one-way from the read key) designed to separate access to vault metadata from access to file contents. Today, vault objects are encrypted under the read key — activating the structure-key split across structural objects is an in-progress, reviewed design change, and this page will say so when it lands, not before.

## Two key systems, and where each applies

Everything above describes the **symmetric** half, and it is the half that matters most: the vault key is symmetric, it is the root of the storage hierarchy, and every object in a vault is encrypted under a key derived one-way from it. If you only ever use sgit to sync your own files across your own machines, that is the whole system.

There is a second half. Layered on top is a **public-key** system, for the two things a shared symmetric key cannot express: **proving who wrote something**, and **encrypting to somebody who does not hold your vault key**. It is what makes [vault-to-vault messaging](../docs/vault-messaging.md) possible — a sender can encrypt to your published public key and drop the result into your vault without ever being able to read it.

|  | Vault key (symmetric) | Keypair (asymmetric) |
|---|---|---|
| What it is | One generated string: address, credential and encryption root | An encryption pair and a signing pair, generated locally |
| What it protects | Every object in the vault | Individual files addressed to a recipient, and signatures over them |
| Who holds it | Everyone who can open the vault | Private half: you alone. Public half: publish it freely |
| Answers | “Can this person open the vault?” | “Who wrote this?” and “Can only *they* read it?” |
| Where it lives on the server | Never — the server holds ciphertext only | Public keys at `bare/keys/key-rnd-imm-*`. Private keys never leave your machine |

The constructions, read out of `sgit pki keygen` on v0.15.0 rather than recalled: **RSA-OAEP 4096-bit** for encryption and **ECDSA P-256** for signing, with a hybrid envelope — RSA-OAEP wraps a per-message AES-256-GCM content key. Private keys are passphrase-protected at rest. The full lifecycle is on [the PKI page](../docs/pki.md).

**This section is new, and its absence had a cost.** Until now this page described the symmetric design and simply did not mention asymmetric cryptography — it never claimed PKI was absent, but it never said it was present either. An agent researching how to send a message between vaults read this page, concluded there was no public-key layer, and stopped looking. The capability had shipped; the sentence that would have pointed at it had not been written. Silence on a page like this one reads as denial.

## Key strength

Vault keys are generated, not chosen. A generated passphrase is 24 characters over a 36-symbol alphabet — about **124 bits of entropy** (3624 ≈ 2124), far beyond brute-force reach — before key derivation adds 600,000 rounds of PBKDF2-SHA256 on top. The key never travels to the server: it is the address, the credential, and the root of the encryption hierarchy in one string, and it stays on your machines.

**Consequence you should want:** there is no password reset. If you lose the vault key, nobody — including us — can recover the contents. Keep it in a password manager, and use `sgit vault backup` for belt-and-braces.

## Two implementations, one wire format

The sgit CLI and the SG/Vault browser client are independent implementations of the same encrypted wire format, kept interoperable through a versioned contract with test vectors. Every crypto operation must produce byte-for-byte identical output to the Web Crypto API given the same inputs — that requirement is enforced with mandatory test vectors, and it means a second, independent codebase continuously exercises the same format. (More on the browser side at [sgraph.ai](https://sgraph.ai).)

## Secrets safety by default

sgit is not a secrets manager, and it actively refuses to become an accidental one: files like `.env*`, `.netrc`, `.pgpass`, `.git-credentials` and private key files (`id_rsa`, …) are *always* excluded from commits, so a stray credential can't get swept into a vault snapshot.

## Open security process

- Open source under Apache-2.0, with a deliberately tiny dependency surface: two runtime dependencies.
- ~4,000 tests including mutation testing in CI and integration tests against a real server — no mocks.
- An internal security review series (twelve findings, each individually worked through and debriefed — covering key residency, IV determinism trade-offs, logging hygiene, and more) is being prepared for publication on this page.
- Found something? Report it via [GitHub](https://github.com/SGit-AI/SGit-AI__CLI/issues) — security reports get priority.
- **Key exposed?** [The rotation runbook](../case-studies/exposed-vault-key.md) — including a worked case study of the day this site's own vault key leaked, and what it cost to fix.

**Honesty note:** sgit is in beta — it powers production workflows daily, and the cryptography is conservative and standard (AES-GCM, PBKDF2, HKDF — nothing exotic). Still: read [when NOT to use sgit](../docs/limitations.md) before trusting it with anything critical.



==============================================================================
# Why does this exist? — sgit.ai

> A direct answer to the sharpest criticism we received: no market, no value. The use cases, why existing tools do not cover them, where the criticism is right, and a FAQ of the follow-up questions.
>
> Page: https://sgit.ai/why/index.html

# Why does this exist?

This page is a boundary map, not a pitch. It starts with where git wins — plainly, in a table, without hedging — because a page that names the incumbent's territory is falsifiable, and falsifiable is what makes the rest of it worth reading. Then it draws what is left: the territory where the store being unable to read your files changes what is possible.

**The whole thesis in one sentence:** you have files that need version control and collaboration, and the place they are stored must not be able to read them.
Everything below is a consequence of that sentence. If it doesn't describe a problem you have, use git and a private repo — we say so on [the page about when not to use this](../docs/limitations.md).

## git and sgit, side by side

The honest framing is not "sgit instead of git". It is two tools with different jobs, and the interesting question is which one owns which files. **This site runs both at once** — one working tree, two remotes: the encrypted vault is pushed with `sgit push`, and the same directory is pushed to GitHub with `git push`, which is what builds and deploys it. Neither is a fallback for the other.

|  | git | sgit |
|---|---|---|
| **The host can read your content** | Yes — that is what makes everything else work | No. It stores ciphertext under opaque ids and never receives a key |
| **Performance at scale** | **Far better.** Twenty years of optimisation: packfiles, deltas, a mature index, repos with millions of files | Built for working sets of documents and code-sized files. Every object is encrypted and content-addressed individually; large binaries chunk-upload past ~4 MB but this is not a video archive |
| **Ecosystem above the protocol** | **Everything.** CI, hosted code review, issue tracking, IDEs, decades of tooling and answers | A CLI, a browser client, and an agent skill. Deliberately small, and young |
| **Proposing changes without write access** | Fork + pull request — mediated by the platform, requires an account there | A [serialised diff](../use-cases/serialised-pull-request.md) — the proposer holds no credential at all, and the artefact moves by any channel |
| **Archaeology** | **Better.**`bisect`, `blame`, `rebase`, `cherry-pick`, hooks, submodules | `history log / diff / show / revert / reset`. No bisect, no blame, no rebase — the server cannot help, so anything not implemented client-side does not exist |
| **Partial commits** | Staging area, index, `add -p` | None. A commit snapshots the whole folder |
| **Branching and merge** | The reference implementation of the idea | The same shape, applied to encrypted objects: a private branch per clone, shared named branches, whole-file three-way merge |
| **Read-only access for someone else** | An account on the host, or a deploy key that reads plaintext | A read key — derived one way, publishable, works against any server holding the ciphertext, no account and no host involvement |
| **Reading it from a browser** | Via the host's UI or API, in plaintext | Directly: fetch the ciphertext and decrypt in the tab with Web Crypto. This page's [Deploy section](../deploy/index.md) is that |
| **If the host is breached** | Your content is in the breach | Opaque ids, ciphertext, object sizes and timing |
| **Recovery when you lose the credential** | Reset your password; the repo is unaffected | Nothing. No reset, no recovery — the direct cost of the row above |

**So the split, concretely:** source code, issues, CI config and anything you would be happy to open-source belong in git — it is better at them and always will be. The material where "who can read the store" is the binding constraint belongs in a vault. Plenty of projects have both, and there is no reason to choose: the two live in one directory, ignore each other, and are pushed separately. The [side-by-side setup](../vault/git-and-vaults.md) — what to commit, what to keep out of git, and the `.gitattributes` that stops git trying to diff ciphertext — is documented, because it is how this site is developed.

## The boundary, precisely

Two corrections to where people assume the line falls, because the obvious version of this map is wrong:

**The boundary is not the operations.** sgit has commit, push, pull, clone, branch, switch, merge with conflict resolution, history, diff, revert and stash — the full mapping is on [one page](../docs/sgit-for-git-users.md) and does not need restating here. What is absent is the *hosted review interface* and the ecosystem above the protocol: CI, issue tracking, server-side search, delta compression. A pull request is a platform construct layered on a merge, not a version-control primitive — and proposing reviewable changes *without holding write access* is present, as a [serialised diff](../use-cases/serialised-pull-request.md), and is a differentiator rather than a gap.

**Git is also client-side.** The difference is not that work moved to the client — a git client already holds the complete object model and history. The difference is that in sgit *the objects are encrypted there*, so what is lost is exactly what a readable server could have added on top:

| Given up | In exchange for |
|---|---|
| Server-side search and indexing | Nothing readable to disclose — not to the host's staff, not to a breach, not to a subpoena served on the host |
| Server-side delta compression and packing |
| Hosted review, CI, and content-triggered automation |

That is the whole trade, stated once. Every capability further down this page is something bought with it. The same boundary is also drawn as [six Wardley Maps, served live from an encrypted vault](../demos/sgit-maps.md) — including a map of git at full strength, because a map that flatters its author is not a map.

## The protocol, on one page

sgit is a protocol more than a product, and the strongest evidence is that the read path fits in six steps. Two independent implementations — the Python CLI and the JavaScript browser client — walk it against the same vaults, and the file-naming convention is documented well enough that a third party could implement it:

```
1. branch name  → deterministic filename       # derived locally — no lookup, no listing
2. that file    → the head index
3. head         → the commit        # encrypted
4. commit       → the tree          # encrypted — filenames live in here
5. tree         → blob, or another tree
6. decrypt the blob → your file
```

Deterministic names disclose *existence, not content*: everything the server ever holds is a bit of metadata — opaque ids, sizes, timing — and ciphertext. And the filenames carrying structure is what makes browser consumption fast: a client can decide to cache a file forever without knowing what it is, because content-addressed ids can never change underneath it.

**Two keys, named explicitly.** The *vault key* encrypts, decrypts and writes; it is the credential and there is no reset. The *read key* is derived one-way from it: it can decrypt everything and write nothing, which is what makes it safe to hand out — or [publish](../demos/vault-app-embed.md). (An API access token is a third thing and often confused: it gates service usage, does no encryption, and is transparent to the security model.)

**Three modes, one vault.** *Local* — a person or agent on one machine, offline included. *API* — agents and services against the REST endpoints. *Web* — people in a browser, with a key in the fragment. The same vault serves all three at once; an agent can create a vault in a terminal session and a person can be reading it in a browser moments later.

## The other side of the boundary: what this makes possible

This page assumes you know git, so here is only the delta: things you cannot do with git and a host, or cannot do without that host reading everything. Each one is running on this website right now — the links go to the thing itself, not to a description of it.

### A live website whose host cannot read it

The [Deploy section](../deploy/index.md) of this site is not part of this site. Its pages live in an encrypted vault maintained by a different team; your browser fetches the ciphertext straight from an SG/Send server over CORS and decrypts it in the tab. There is no build step, no CI job, no copy of that content on sgit.ai. When that team runs `sgit push`, the next page load has it.

**Without sgit:** you can serve a static site from a host, or you can keep the content private, but not both. GitHub Pages serves what GitHub can read. A private bucket plus a decrypting front end is buildable — content addressing, cache tiers, key derivation, an update path — and that is roughly the thing being described here. There is no documented, off-the-shelf way to do it with git and a git host.

See it working: [how this page works](../case-studies/live-vault-docs.md), with the object model and the request timeline.

### Read access as a thing you can publish

A vault has a **read key** that is derived one way, so it decrypts content and cannot be turned back into write access. That makes it safe to put in a file the whole internet can fetch — which is exactly what `deploy/vault.json` on this site does. Anyone can take it and run `sgit clone --read-key <key> fyofmkvr` to get the same documents on their own machine, and watch a write attempt get refused.

**Without sgit:** git access is repository-shaped and host-mediated. A deploy key that can read gives its holder everything in plaintext, and revoking it is an operation on the host's access-control list. Here, the capability *is* the key: it travels with the reader, it works against any server holding the ciphertext, and the host is not asked to enforce anything.

### Two agents collaborating in a workspace neither host can read

This site is built and published by Claude Code sessions that share state through a vault. Each session clones into its own private branch, commits there, and pushes to the shared named branch — the [two-branch model](../docs/two-branch-model.md), which is git's isolate-then-merge shape applied to encrypted objects. The pages in the Deploy section come from a *second* team's vault, maintained by an agent that has never had access to this repository or this site.

**Without sgit:** agent-to-agent shared memory means a database or a repo that the provider reads. That is fine until the state includes client documents, security findings, or unreleased work — at which point the question stops being technical.

The architecture, drawn: [two sessions, one vault, one live site](../case-studies/live-vault-docs.md).

### Private data with public-CDN economics

Object ids are SHA-256 hashes *of the ciphertext*, so an object can never change under its id. That makes every object permanently cacheable by infrastructure that cannot read it — a browser's Cache API, a proxy, a CDN edge. On this site that is not theory: after the first visit, a page load fetches **one 69-byte object** (the mutable HEAD pointer) and serves everything else from cache — and inside the [freshness window](../case-studies/live-vault-docs.md) it fetches nothing at all. Open the vault panel on any Deploy page and watch the counters.

**Without sgit:** caching private content at the edge is precisely what you are told not to do, because the cache would hold readable data. Content-addressed ciphertext removes the conflict — the cache holds bytes it cannot interpret, keyed by a hash it cannot invert.

### Storage becomes a commodity you don't have to trust

The server is a key-value store for opaque ids. It never receives a key, never sees a filename, and cannot tell a legal draft from a photo. That means the backing store is interchangeable — a managed SG/Send server, one you [run yourself](../deploy/index.md), an S3 bucket, a disk — and choosing it stops being a trust decision. A subpoena, a breach, or a curious administrator on that host yields ciphertext.

**Without sgit:** "who hosts this?" and "who can read this?" are the same question. Every migration is a re-negotiation of that trust; here it is a copy operation.

### Transit security that doesn't rest on the CA system

The content is already encrypted before it leaves the client, so TLS is transport hygiene rather than the security boundary. A mis-issued certificate, a coerced or compromised CA out of the ~150 your browser trusts by default, or a TLS-terminating middlebox in a corporate network sees the same thing the server sees: ciphertext addressed by opaque ids.

**The advanced version** — and where this is heading: the read key stays on the client and never appears in a published file, or the scheme moves to PKI with the private key existing only on the client. Then the confidentiality of the data in transit depends on one key you hold, not on the whole certificate-authority arrangement being sound end to end. Today's published-read-key form on this site is the deliberately simple case: the content *is* meant to be public, so the only job is proving the host never had it in the clear.

## Who has that problem

Not a market-size claim — just the situations where the sentence at the top is literally true today. These matter, but they are the ordinary reasons; the section above is the interesting one.

[AI agents### Agent state that isn't the vendor's to readAn agent's work has to survive its context window, so it goes somewhere — and that somewhere increasingly holds client documents, security findings, unreleased code.Recipe, evidence and an agent brief →](../use-cases/ai-agents.md)

[Professional services### Working documents with clientsLegal, M&A, audit, security assessment: the deliverable and the working notes are exactly the material that must not sit readable on a third party's disk.Recipe, evidence and an agent brief →](../use-cases/professional-services.md)

[Health & regulated### Data that changes what is permissibleWhen the host provably cannot read the content, you are no longer arguing about the provider's access controls, because there is nothing to control access to.Recipe, evidence and an agent brief →](../use-cases/health-regulated.md)

[Security teams### Findings about your own weaknessesPentest results are the last thing you want in a SaaS you don't control, and the first thing that needs history, diffs and multi-person workflow.Recipe, evidence and an agent brief →](../use-cases/security-teams.md)

## Why the existing answers don't cover it

This is the strongest form of the objection: every one of these exists and is more mature. Each solves part of it.

| What you'd reach for | What it gives you | What's missing |
|---|---|---|
| git + a private repo | Everything about workflow, perfected | The host reads all of it. Fine for code; not for client data — and none of the six capabilities above. |
| git-crypt / SOPS / age | Encrypted file *contents* inside git | Filenames, directory structure, commit messages and history shape stay readable to the host; no browser access; key distribution is manual. |
| Dropbox / Drive / SharePoint | Sync, sharing, a UI everyone knows | The provider can read it, and there are no branches, no merges, no commit history you can reason about. |
| S3 + KMS, or a database with encryption at rest | Encryption the auditors recognise | Whoever holds the key can decrypt — and that's the provider, or anyone with the right IAM role. No git-shaped workflow, no offline. |
| Build it yourself | Exactly what you want | Roughly what this project is: four thousand tests, a wire format two independent clients agree on, and a year of edge cases. It's free — you may as well take it. |

The gap they share is the same one: **you can have the workflow, or you can have the privacy, but not both in the same tool.** If you think that gap doesn't matter, we disagree about something factual — a much better disagreement to have than one about adjectives.

## The comment this page answers

> "I appreciate the work and effort in this but i see no market or value what so ever (especially market). My first question if was being sold this would be why but then don't try and answer cause i would return with so many follow up questions to anything you would say."

Someone left that under the announcement post, and it is the most useful comment we received — the boundary map above is the answer to "why", made falsifiable instead of rhetorical. Two things it gets right before the rebuttal starts: most answers to it *are* marketing, and there is nothing being sold — sgit is Apache-2.0 and installable with `pip install sgit-ai`, so the only question worth answering is why anyone would **use** it.

## The market question

- **The client is open source, and that is the distribution strategy, not a substitute for one.** Apache-2.0, no licence tiers, no open-core feature gating in the CLI. It spreads by being free and useful, and the services are built on top of it — the ordinary way open source scales into a business.
- **The commercial layer is the hosted service** (SG/Send) and what gets built around it. You can also [self-host](../deploy/index.md) — that guidance is published, live, in a vault — so the lock-in argument doesn't hold: if the commercial layer becomes unpalatable, you run your own server and your data and workflow are unaffected.
- **We are not going to quote a market size.** We don't have credible numbers, and a TAM slide is exactly the marketing this page is avoiding. What we can say honestly: the amount of machine-generated state that someone else should not be able to read went from approximately zero to very large in about two years, and it has to live somewhere.
- **It might still be a small market.** That's a legitimate outcome. The tool would still be worth having for the people in it, and it costs them nothing.

## Where the criticism is right

- **The category is unproven.** "Git for encrypted vaults" is not a shelf anyone shops from yet. We might be early, wrong, or both.
- **Most people don't need it.** If your files aren't sensitive, this is strictly more complexity than a private repo.
- **Zero-knowledge has real costs** — no server-side search, no password recovery, and key management becomes your problem. Permanent trade-offs, not bugs to be fixed later.
- **It's beta.** In production use daily, but young.

## The follow-up questions

You said you'd have many. Here are the ones we'd expect, answered without hedging. If yours isn't here, [ask it in public](https://github.com/SGit-AI/SGit-AI__CLI/issues) and we'll add it.

**Give me one thing I cannot do with git and GitHub today.**

Publish a site whose content the host has never seen in the clear, updated by a push, readable by anyone you hand a read key to, and cached at the edge by infrastructure that cannot decrypt it. The [Deploy section](../deploy/index.md) is that, live. You can assemble something similar yourself out of a bucket, a decryption front end and a cache policy — and what you would have assembled is this.

**Isn't publishing a key on a website obviously a mistake?**

Publishing a *write* key would be — we have an [incident write-up](../case-studies/exposed-vault-key.md) about doing exactly that by accident. The read key is a different object: derived one way, it decrypts and cannot be inverted into write access. Publishing it is how a reader gets the content without the site ever being trusted with the ability to change it. That's a checkable property, not a policy: take the key, clone with it, and watch the write get refused.

**Doesn't TLS already solve the confidentiality problem?**

TLS protects the hop, not the destination. It ends at the server, which then holds your plaintext — and it rests on a certificate-authority system where any of roughly 150 default-trusted roots can vouch for any name, and where corporate middleboxes terminate it on purpose. Encrypting before the bytes leave means a mis-issued certificate or a terminating proxy sees ciphertext. The direction of travel is stronger still: the read key never leaving the client, or PKI where the private key exists only there.

**Isn't this just git with encryption bolted on?**

No — and the difference is why the existing tools don't cover the case. Encrypting files inside git still leaves the host holding your filenames, directory structure, commit messages and the shape of your history. sgit encrypts all of that: the server sees opaque identifiers and ciphertext, and never receives a key. A different storage model that keeps git's verbs.

**Why not git-crypt or SOPS? They're mature and I already know them.**

Use them if they fit — they're good tools designed for a different job: keeping a handful of secrets inside an otherwise-public repo. They don't hide structure, don't work in a browser, and key distribution across a team is manual. sgit targets the case where the *whole workspace* is the sensitive thing.

**If it's free, what's the business model — and what happens when you need to make money?**

The hosted service, and what gets built on it. The client stays Apache-2.0 and self-hosting is documented, which is the protection that matters: the escape hatch is a checkable property of the format, not a promise about future behaviour.

**What if you disappear?**

You keep a full local copy — every clone contains the complete encrypted store. The format is documented, the client is open source, and two independent implementations already read it. If the project stopped tomorrow, your data stays readable with code you already have.

**"Zero-knowledge" is a marketing term. What does the server actually see?**

The vault ID, the size of each encrypted object, and when requests happen. That's the list, and it's on [the security page](../security/index.md) including the uncomfortable parts: object sizes and timing are a real, if narrow, side channel. Anyone who tells you their zero-knowledge system leaks nothing at all is not being careful with words.

**How do I know the cryptography is right?**

You don't have to take our word for it, which is the point. It's standard and boring — AES-256-GCM, PBKDF2-SHA256 at 600k iterations, HKDF — with no custom primitives. The code is open, and the outputs must match the browser's Web Crypto API byte-for-byte, enforced with test vectors. Two independent implementations reading the same format is a stronger check than any single audit.

**What happens when I lose the key? Be honest.**

The data is gone. No reset, no recovery, no support ticket that helps. That's the direct consequence of the server not being able to read your content, and if your organisation can't manage keys reliably, this trade-off will hurt you and you should not use it.

**Why would an AI agent need this specifically?**

Because agent state is now sensitive and shared. An agent that stops and resumes needs durable memory; several agents working together need shared memory with isolation and a review step; and the contents are increasingly things a client or regulator cares about. Version control solves the coordination half. Client-side encryption solves the half that determines whether you're allowed to do it at all.

**Isn't this over-engineered for what it does?**

Judge it by the surface: two runtime dependencies, a pure-Python client, one file format. The complexity that exists — the two-branch model, content addressing, three-way merge — is what makes concurrent editing safe without the server being able to help, because the server can't read anything. Remove the encryption and yes, it's over-engineered; you'd just use git.

**Is anyone actually using it, or is this a demo?**

This website is served from a vault it manages, deployed by pushing that vault. The [deployment docs](../deploy/index.md) are decrypted in your browser, live, from a different vault maintained by another team. The [Try page](../try/index.md) runs the real client in your browser. It's in daily production use by its authors — a small n, honestly stated, and more than a demo.

**Why should I trust a beta?**

For anything critical, don't yet — and keep backups regardless. What we offer instead of a trust-me is evidence: ~4,000 tests, mutation testing, integration tests against a real server, a published threat model, and an [incident write-up](../case-studies/exposed-vault-key.md) of the day we leaked our own key, including what it cost to fix. A project that hides that class of mistake is the one to worry about.

**Fine — but I still think there's no market.**

You may be right. It costs nothing to be wrong about this in our direction: the code is free, the format is open, and if the category never materialises, the people who did need it still got a working tool. The failure mode we'd actually regret is the opposite one — building it after everyone had already put their machines' private state somewhere readable.

## An invitation, meant literally

You said you'd come back with many follow-up questions. Please do — [in the open, on the issue tracker](https://github.com/SGit-AI/SGit-AI__CLI/issues). Sharp questions from someone who doesn't buy the premise are worth more than agreement, and if any of them don't have a good answer, that's a finding: it goes on this page, or it changes the roadmap. That's the same way the [key-leak incident](../case-studies/exposed-vault-key.md) and the [open briefs](../briefs/index.md) got written.

[← Home](../index.md)[When NOT to use sgit →](../docs/limitations.md)



==============================================================================
# Run your own SG/Send server — sgit.ai

> Deployment guidance for self-hosting a zero-knowledge SG/Send server — rendered live in your browser from an encrypted vault, with no copy stored on this site.
>
> Page: https://sgit.ai/deploy/index.html

[Home](../index.md) / Deploy

# Run your own SG/Send server

Deployment guidance for standing up your own zero-knowledge vault server — Docker, AWS, GCP, Heroku, or a static host. **These pages are not part of this website.** They live in an encrypted vault maintained by the SG/Send team, and your browser is decrypting them right now with a published read-only key.

**How this page works:** the vault's ciphertext is fetched straight from the SG/Send server over CORS, and the AES-256-GCM decryption happens in this tab using the Web Crypto API. There is no build step and no copy of the content on sgit.ai — when the SG/Send team runs `sgit push`, the next load of this page has it. Open the **vault panel** (right edge) to watch the objects being fetched, see which came from cache, and check the exact commit you are reading. [**Full architecture, with diagrams →**](../case-studies/live-vault-docs.md)

opening vault…

Fetching the encrypted index…

### Vault debug [how this works →](../case-studies/live-vault-docs.md)

not open yet

what you are looking at

 Every row above is an encrypted object pulled from the SG/Send API and decrypted locally — click one to see what it actually contains. Objects whose id contains **-imm-** are content-addressed and therefore immutable, so they are cached permanently; the mutable **ref** is the one mutable object, so it is checked at most once per freshness window (120s) rather than once per page — inside the window, reading the docs makes no requests at all, and **check for new commit** forces one whenever you want it.

The **tree** objects are the reason a first visit reads more than one file: filenames are encrypted inside them, so building the navigation means reading every directory. That index is a pure function of the commit id, so it is memoised — after the first visit, an unchanged commit reads no tree objects at all. Nothing here is stored on sgit.ai.

[How this page works →](../case-studies/live-vault-docs.md) Architecture diagrams, the object model, the cache tiers, and how two Claude Code sessions publish into this vault.



==============================================================================
# A live site whose host cannot read it — sgit.ai case study

> A case study in the mechanism: two Claude Code sessions, two encrypted vaults, one page — with architecture diagrams of the publishing pipeline and the in-browser read path.
>
> Page: https://sgit.ai/case-studies/live-vault-docs.html

[Home](../index.md) / [Deploy](../deploy/index.md) / How this works

# How this page works

The [deployment guidance](../deploy/index.md) next door is not stored on this website. It is written by a different team, in a different Claude Code session, into a different encrypted vault — and your browser assembles it from ciphertext at the moment you ask for it. This page explains the whole mechanism, because it is a compact demonstration of what sgit is actually for.

## Two sessions, two vaults, one page

Nothing here is a pipeline anyone had to build. Both sides just use sgit, and the shared vault format does the integration:

*[diagram]*
Neither team's session knows about the other's. The only shared thing is a vault format and a published read key.

Concretely, when the SG/Send team improves a deployment guide, the sequence is: edit markdown → `sgit commit` → `sgit push`. That is the entire publish step. There is no build to trigger on our side, no webhook, no content sync, and no copy of their text in our repository. The next visitor to the Deploy page gets the new version because the browser reads their vault's current commit.

## What happens when you open the page

Everything below runs client-side, in about 300 lines of JavaScript using the browser's built-in Web Crypto API:

*[diagram]*
The server answers ordinary GETs for opaque file ids. It never sees a key, a filename, or a byte of plaintext.

## Why the caching is safe — and why it's this shape

The cache policy is not a tuning choice; it falls out of the data model. Object ids are content hashes *of the ciphertext*, so an object can never change under its id — which makes it permanently cacheable. The ref is the one mutable pointer, so it is the only thing that has to be refetched at all:

| Tier | What it holds | Lifetime | Why |
|---|---|---|---|
| memory | decrypted objects | this page session | avoids decrypting the same tree twice while you click around |
| Cache API | ciphertext of `obj-cas-imm-*` | until you clear it | content-addressed ⇒ immutable ⇒ can never be stale |
| localStorage | the file index (path → blob) | keyed by commit id | a pure function of the commit, so an unchanged HEAD reads no tree objects |
| freshness window | the ref (`ref-pid-muw-*`) | **120 s** (`ref_ttl_s`) | it is the mutable HEAD; checking it once per window instead of once per page view is what takes steady-state reading to zero requests |

### The freshness window

The ref has to be refetched sometimes — that is how a new commit is noticed. It does not have to be refetched on *every page view*. So the answer is kept for `ref_ttl_s` seconds (120 by default, set in `deploy/vault.json`), and inside that window the reader reuses it.

Three things follow, and they are the whole trade:

- **Reading the docs costs nothing.** Click through ten pages inside the window and the network stays silent — every object is content-addressed and already cached, and the one mutable object is inside its window. The panel logs the ref as `TTL` with a live countdown to the next check.
- **Server load stops scaling with page views.** It scales with *readers per window* instead: one 69-byte request per reader per two minutes, however much they read.
- **Propagation is delayed, and bounded.** A new commit is picked up within 120 seconds at worst, and immediately if you press **check for new commit** — which forces a fetch and ignores the window. That button is not a debug affordance; it is the escape hatch that makes the window safe to have.

Measured on this site: a cold load fetches 18 objects (~14 KB); the next load fetches **one 69-byte object** — the ref — and serves the rest from cache; a load inside the freshness window fetches **nothing at all**. Open the vault panel and press **clear list**, then click around, to watch it happen.

## Who can see what

### SG/Send server

- opaque object ids
- ciphertext blobs
- sizes and timing
- the vault id

### GitHub Pages

- the page shell
- the public read key
- no vault content at all

### Your browser

- the read key
- decrypted filenames
- decrypted content
- the commit history

Two hosts, neither of which can read the documents. The decryption exists in exactly one place: the tab in front of you.

The read key is deliberately public — it is *read-only by construction*, derived one-way so it cannot be turned back into write access. Publishing it is what lets the site show the content without the site ever being trusted with the ability to change it. Anyone can verify that: take the key out of `deploy/vault.json`, run `sgit clone --read-key <key> fyofmkvr`, and watch a write attempt get refused.

## Why this is the interesting demo

- **Two teams integrated without integrating.** No API contract was designed, no sync job written, no permissions negotiated. One side pushes to a vault; the other side holds a read key. That is the whole interface.
- **Publishing is a git operation.** The SG/Send team's release process is `sgit push` — and their content appears on a website they do not control and cannot deploy to.
- **Least privilege that is structural, not procedural.** This site *cannot* alter their documentation, however compromised it might be, because the key it holds does not carry that power.
- **The same property scales down to one agent.** Give an agent a read key and it can read a knowledge base without any ability to corrupt it; give it the full key and it can contribute. That is the same mechanism this page uses, applied to agent workflows.

## The honest trade-offs

- **Search engines and agents see an empty shell.** Content that only exists after decryption is invisible to anything that does not run JavaScript. sgraph.ai solves this by decrypting at the CDN edge and serving `.md` alongside each page; this site is static, so it does not. That is a real cost of the approach as built here.
- **It needs a secure context.** Web Crypto is unavailable over plain HTTP, so this only works on HTTPS (or localhost).
- **The server can't help.** No server-side search, no previews, no summaries — everything is opaque to it. That is the point, and it is also a limitation.
- **Diagrams are hand-drawn SVG, not a diagramming library.** This site is also served *from inside a vault*, where external resources are blocked by the app authoring contract — so importing a renderer from a CDN would break the very demonstration this page describes. The constraint chose the implementation.

[← The deployment docs](../deploy/index.md)[Git and vaults →](../vault/git-and-vaults.md)



==============================================================================
# Try sgit in your browser — sgit.ai

> The real sgit-ai package running client-side under Pyodide: derive keys, encrypt, run an in-memory vault, and use a Python console — nothing you type leaves the page.
>
> Page: https://sgit.ai/try/index.html

# Try sgit in your browser

This page downloads a Python runtime (Pyodide, ~20 MB) and installs the **real `sgit-ai` wheel from PyPI** — the same code `pip install` gives you — then runs it right here: a working terminal with the actual `sgit` CLI, an in-memory filesystem, and a network transport routed through your browser. Keys are derived and content encrypted locally; nothing you type leaves this page except the ciphertext sgit itself sends when *you* run a network command.

**What this is:** sgit's engine, client-side. File commands run against this tab's in-memory filesystem (gone on refresh; the remote vault persists). Network commands (`clone`, `push`, `pull`, `doctor`) go straight from your browser to the SG/Send servers over CORS — the page freezes while they run (synchronous transport; it's a demo, not a product). First load is heavy (~20 MB, cached afterwards); 600,000 PBKDF2 rounds take ~1–2 s in WebAssembly.

— engine not loaded —

## The terminal

The real `sgit` CLI plus a small toolbox of file commands (`ls`, `cd`, `cat`, `mkdir`, `echo > file`, `tree`, …). Type `help` for the list. History with ↑/↓.

— load the engine above to start —

/workspace $

```
# a session to try (the vault key can be any vault you hold a key for):
sgit init my-vault  cd my-vault  echo "hello" > notes.md
sgit status  sgit commit -m "from a browser"
# and the one that makes it real — clone straight from the SG/Send servers:
sgit clone <vault-key> demo  cd demo  ls  sgit history log --oneline
```

## Python console

The full `sgit_ai` package is importable. The last expression's value is printed.

from sgit_ai.crypto.Vault__Crypto import Vault__Crypto vc = Vault__Crypto() vc.derive_keys('my-passphrase', 'DEMO-VAULT')

How this works: [the same site](../vault/static-hosting.md) serves from an encrypted vault or GitHub Pages; this page pulls Pyodide from a CDN and the wheel from PyPI at runtime, so it needs an internet connection — the one page on this site that does.



==============================================================================
# Skills for AI agents — sgit

> Packaged, versioned instructions that make any AI agent an effective sgit and vault user: operate the CLI, build vault apps, author vault content.
>
> Page: https://sgit.ai/skills/index.html

# Skills — sgit for AI agents

A skill is a packaged set of instructions an AI agent loads to do a job well: the commands that matter, the patterns that work, the traps already hit and documented so the agent doesn't hit them again. sgit treats agents as first-class users, so its skills are first-class artifacts — versioned, verified against specific releases, and shipped right here in this vault.

## The three skills

## Operate

[use sgit and vaultsThe CLI end to end — and the cross-session pattern: clone/pull at session start, commit + push at session end, so state survives the context window. Includes the multi-agent branch-per-agent workflow.](use_sgit-and-vaults__SKILL.md)

## Build

[create vault appsThe vault-app playbook: the authoring contract, what the host gives you for free, proven layout patterns, the validation gate, and a nine-row table of failure modes with fixes — all bug-fixed against real vault behaviour.](create-vault-apps__SKILL.md)

## Author

[create vault contentStructured content without code: the full _page.json schema (embedded — no repo clone needed) and vault markdown authoring, with checklists and copy-paste templates.](create-vault-content__SKILL.md)

**Not yet in the skills: vault-to-vault messaging.** These three files ship verbatim from upstream and this site does not edit them. As of the current versions, the operate skill documents `sgit pki` as file signing and encryption, and does not mention [append lanes](../api/append-lanes.md) — so an agent reading only the skill has both halves of the messaging mechanism and no statement that they combine. That is exactly the failure that produced [the messaging page](../docs/vault-messaging.md): an agent asked how to send a message between vaults and could not get there. Until the skill catches up, point agents at [/docs/vault-messaging](../docs/vault-messaging.md) alongside it.

## Installing a skill

For Claude Code and compatible agents: drop the skill file into your skills directory (e.g. `~/.claude/skills/<name>/SKILL.md`) or paste it into the session as context. The skill's own description tells the agent when to trigger it. A minimal bootstrap for a fresh session is one line:

```
$ pip install sgit-ai && sgit clone <vault-key> workspace
# then read skills/ inside any vault that ships them — like this one
```

The skills above are the canonical current versions, verified against sgit-ai v0.14.x and the current app-shell. They carry their own honesty markers — including which CLI commands are disabled right now and which platform features are trial-only — so an agent reading them gets ground truth, not marketing.

**Also for agents:** this site ships an [llms.txt](../llms.txt) at the vault root — the standard machine-readable index. Inside the vault it is encrypted like everything else (agents holding the key read it via `sgit cat llms.txt`); on a static deployment it becomes a plain public llms.txt. Same file, two trust contexts.

[← Working with AI agents](../docs/agents.md)[The SG/Vault platform →](../vault/index.md)



==============================================================================
# Documentation — sgit

> sgit documentation: quickstart, concepts, guides for humans and AI agents, and the honest limitations page.
>
> Page: https://sgit.ai/docs/index.html

# Documentation

Start with the five-minute quickstart. If you know git, the Rosetta stone will make sgit feel familiar in one read.

## Introduction

[What is sgitThe pitch, the mechanism, the architecture](what-is-sgit.md) [Installationpip install, verify, upgrade](installation.md) [QuickstartCreate, commit, push, clone — in 5 minutes](quickstart.md)

## Concepts

[sgit for git usersThe Rosetta stone: same verbs, three differences](sgit-for-git-users.md) [The two-branch modelClone branches, named branches, and why](two-branch-model.md) [The security modelWhat the server sees; the crypto stack](../security/index.md) [Keys and signaturesEncrypting to someone who holds no vault key](pki.md)

## Messaging & the API

[Sending messages between vaultsAppend lanes + PKI, composed into a worked example](vault-messaging.md) [The HTTP APIEndpoints, headers, gates, limits and error codes](../api/index.md) [Append lanesThe write-only transport behind vault messaging](../api/append-lanes.md)

## Guides

[Working with AI agentswrite, --json, sparse clones, multi-agent patterns](agents.md) [Use casesFive workflows, all on shipped commands](../use-cases/index.md) [SG/Vault platformThe browser app, vault apps, the window.sg bridge](../vault/index.md)

## Project

[When NOT to use sgitThe honest page](limitations.md) [Why does this exist?Answering the no-market criticism, plus a FAQ](../why/index.md) [If a vault key is exposedThe rotation runbook, with a real case study](../case-studies/exposed-vault-key.md) [Cross-team briefsOpen asks to the CLI and API teams](../briefs/index.md) [Admin & engineeringHow this site is built and released](../admin/index.md) [GitHubSource, issues, changelog](https://github.com/SGit-AI/SGit-AI__CLI)

**Coming next:** a full per-command CLI reference, generated directly from the CLI's own argument parser on every release — so the reference can never drift from the shipped tool.



==============================================================================
# What is sgit — Docs

> sgit is git for encrypted vaults: how it works, what makes it different from git, and the ecosystem around it.
>
> Page: https://sgit.ai/docs/what-is-sgit.html

[Docs](index.md) / Introduction

# What is sgit

**sgit is git for encrypted vaults.** Clone, commit, branch, diff and merge folders of files that are encrypted with AES-256-GCM before they leave your machine. The server stores ciphertext under opaque IDs — it never sees your filenames, your contents, or your commit messages.

It's like git and a password vault had a baby.

## How it works

A vault is an ordinary folder plus a `.sg_vault/` directory. When you commit, sgit snapshots the folder into a git-like object graph — commits pointing at trees pointing at content blobs — and encrypts every object client-side. When you push, only changed ciphertext travels. Object IDs are content-addressed (`obj-cas-imm-…`), so unchanged files are never re-uploaded, and the server can deduplicate data it cannot read.

```
your-folder/
├── <your files>            # untouched — a vault is just a folder
└── .sg_vault/
    ├── bare/                # encrypted objects, refs, branch keys
    └── local/               # your private clone-branch key — never pushed
```

The **vault key** (`passphrase:vault-id`) is three things in one string: the address of the vault on the server, the credential to access it, and the root of the local key-derivation hierarchy. Whoever holds it can decrypt the vault; nobody else — including the server — can. See the [security model](../security/index.md) for the full derivation chain.

## What makes it different from git

- **Everything is encrypted client-side** — content, filenames, messages, branch names.
- **No staging area** — commit snapshots the whole folder, like `git commit -a` for everything.
- **A two-branch model** — a private clone branch per machine or agent plus shared named branches, which is what makes safe multi-agent collaboration possible. [Details →](two-branch-model.md)

## One vault, three doors

- **sgit** — this CLI. Open source, Apache-2.0, `pip install sgit-ai`.
- **SG/Vault** — the web app: browse, edit and review the same vaults in a browser, via an independent implementation of the same wire format. [How it works →](https://sgraph.ai)
- **SG/Send** — the zero-knowledge transfer API both clients speak to. [How it works →](https://sgraph.ai)

**Maturity:** sgit is in beta and has been powering production workflows for a while. The vault format is versioned and `sgit migrate` handles upgrades. Read [when NOT to use sgit](limitations.md) for the honest edges.

[Installation →](installation.md)



==============================================================================
# Installation — sgit Docs

> Install sgit with pip, verify with sgit doctor, upgrade with sgit update. Python 3.11+, two runtime dependencies.
>
> Page: https://sgit.ai/docs/installation.html

[Docs](index.md) / Introduction

# Installation

Pure Python, two runtime dependencies. Python 3.11 or newer.

```
$ pip install sgit-ai
# or, on externally-managed systems:
$ pipx install sgit-ai
```

This installs two entry points: `sgit` and `sgit-ai` (they are identical — use whichever you like).

## Verify

```
$ sgit version
sgit-ai v0.14.x
$ sgit doctor
✓ remote reachable   ✓ TLS ok   ✓ config valid
```

`sgit doctor` checks connectivity and configuration and prints per-OS fix instructions for the common problems (including SSL certificate issues). Add `--json` if a script or an agent is doing the checking.

## Upgrade

```
$ sgit update   # wraps pip install --upgrade sgit-ai
```

[← What is sgit](what-is-sgit.md)[Quickstart →](quickstart.md)



==============================================================================
# Quickstart — sgit Docs

> From zero to a synced, encrypted, versioned vault in five minutes: create, commit, push, clone, pull.
>
> Page: https://sgit.ai/docs/quickstart.html

[Docs](index.md) / Introduction

# Quickstart

From zero to a synced, encrypted, versioned vault in five minutes.

## 1 — Create a vault

```
$ pip install sgit-ai
$ sgit create my-vault
✓ Vault created and registered
✓ Initial commit pushed

  Vault key: <24-char-passphrase>:<vault-id>
```

**Save the vault key now** — in a password manager, not a text file. It is the address, the credential, and the encryption key in one string. There is no reset: lose it and the vault is unrecoverable, by design.

Already have a folder full of files? `cd` into it and run `sgit init --existing` instead — the current contents become the first snapshot.

## 2 — Work like git

```
$ cd my-vault
$ echo "# Plan" > plan.md
$ sgit status
  added: plan.md
$ sgit commit -m "add the plan"
✓ Committed 1 file
```

There is no staging area — `sgit commit` snapshots the whole folder. Files like `.env` and private keys are always excluded, automatically.

## 3 — Push

```
$ sgit push
✓ Pushed 1 commit — only ciphertext left this machine
```

## 4 — Clone somewhere else

```
# on another machine, or in an agent's session
$ sgit clone <vault-key>
✓ Cloned and decrypted 1 file
$ sgit pull      # pick up new commits any time
```

## 5 — Look around

```
$ sgit history log --oneline     # commit history
$ sgit history diff              # what changed
$ sgit vault info                # identity, remote, web URL
```

The web URL printed by `sgit vault info` opens the same vault in the SG/Vault browser app — decrypted in the browser, never on the server.

## Where next

- [sgit for git users](sgit-for-git-users.md) — the Rosetta stone
- [The two-branch model](two-branch-model.md) — how collaboration works
- [Working with AI agents](agents.md) — give an agent a private, versioned workspace

[← Installation](installation.md)[sgit for git users →](sgit-for-git-users.md)



==============================================================================
# sgit for git users — Docs

> The Rosetta stone: every git command mapped to its sgit equivalent, plus the three deliberate differences.
>
> Page: https://sgit.ai/docs/sgit-for-git-users.html

[Docs](index.md) / Concepts

# sgit for git users

If you know git, you know most of sgit. Same verbs, same mental model — with three deliberate differences that exist because the payload is encrypted.

## The Rosetta stone

| git | sgit | Notes |
|---|---|---|
| `git init` | `sgit init` | `--existing` vault-ifies a non-empty folder |
| `git clone <url>` | `sgit clone <vault-key>` | the key is URL + auth + decryption in one |
| `git status` | `sgit status` | `--explain` teaches the branch model |
| `git commit -am` | `sgit commit -m` | always whole-folder — there is no staging area |
| `git push / pull / fetch` | `sgit push / pull / fetch` | push is delta + ciphertext only |
| `git log` | `sgit history log` | `--oneline`, `--patch`, `--json`, ranges |
| `git diff` | `sgit history diff` | `--remote`, `--commit`, `--files-only` |
| `git show` | `sgit history show` | read-only — fetches missing objects without merging |
| `git revert / reset` | `sgit history revert / reset` |  |
| `git stash` | `sgit vault stash` | `pop`, `list`, `drop` |
| `git branch / checkout` | `sgit branch new / switch / checkout` |  |
| `git merge` conflicts | `sgit resolve --show` | three-way base/ours/theirs view with a verdict per file |
| `git remote` | `sgit remote add / list / set-url` |  |
| `git fsck` | `sgit check fsck` | verifies encrypted object integrity, can repair |

## The three differences that matter

### 1. No staging area

Every commit snapshots the whole folder. This removes git's most confusing concept, and it fits the security model: partial staging would leak "which parts changed" into workflows that are supposed to be opaque. Use branches where you would have used the index.

### 2. The vault key is URL, auth, and encryption key in one

`passphrase:vault-id`. There is no separate remote URL to configure, no separate credential to manage, and no password reset. Whoever holds the key holds the vault — treat it like the private key it is.

### 3. Two layers of branches

You never work directly on a shared branch. Every clone works on a private **clone branch** (its key never leaves your machine) and `push` forwards commits to the shared **named branch**. That's why two agents on the same vault can't corrupt each other's work-in-progress. [The full story →](two-branch-model.md)

[← Quickstart](quickstart.md)[The two-branch model →](two-branch-model.md)



==============================================================================
# The two-branch model — sgit Docs

> sgit's central idea: private clone branches per machine or agent, shared named branches, and explicit publishing.
>
> Page: https://sgit.ai/docs/two-branch-model.html

[Docs](index.md) / Concepts

# The two-branch model

sgit's central architectural idea: every clone works on a private branch, and sharing is an explicit act.

## Clone branches and named branches

```
        agent A's machine                    the server                    agent B's machine
  ┌───────────────────────┐        ┌───────────────────────────┐        ┌───────────────────────┐
  │  clone branch (A)     │  push  │   named branch "main"     │  pull  │  clone branch (B)     │
  │  key: local only ─────┼───────▶│   key: shared via vault   │◀───────┼─ key: local only      │
  └───────────────────────┘        └───────────────────────────┘        └───────────────────────┘
```

- **Named branches** (`main`, `feature-x`, …) are shared and live on the server — encrypted, like everything else.
- **Clone branches** are created per clone. Their key is stored only in `.sg_vault/local/` and is never pushed. All your commits land here first.
- `sgit push` re-encrypts your clone-branch commits with the named branch's key and forwards them. `sgit pull` brings named-branch commits down and merges them into your clone branch.

Run `sgit status --explain` any time — it prints this model with your vault's actual branch names filled in.

## Why it works this way

- **Isolation by construction.** Two machines — or two agents — on the same vault physically cannot overwrite each other's uncommitted or unpushed work: they're on different branches with different keys.
- **Sharing is explicit.** Nothing you commit is visible to anyone until you `push`. An agent can iterate messily in private and publish only the result.
- **Safe concurrent pushes.** Pushes use compare-and-swap on the server (atomic batch writes): if someone pushed before you, your push is rejected cleanly instead of silently clobbering — pull, merge, push again.

## Merging and conflicts

When histories diverge, sgit runs a genuine three-way merge (common ancestor + ours + theirs) per file. Non-conflicting changes merge automatically; conflicting paths get `.conflict` files, and:

```
$ sgit resolve --show
  notes/plan.md   CONFLICT (both changed)
    base   │ ship in Q3
    ours   │ ship in Q4          ← your clone branch
    theirs │ ship in Q3, beta Q2 ← the named branch
    verdict: genuine conflict  (not one-sided, not identical)
```

The verdict line matters in multi-writer vaults: it distinguishes genuine conflicts from one-sided or identical changes, so you (or an agent) only spend attention where a human decision is actually required. `sgit merge-abort` backs out of a merge cleanly.

[← sgit for git users](sgit-for-git-users.md)[Working with AI agents →](agents.md)



==============================================================================
# Working with AI agents — sgit Docs

> The agent-facing surface: sgit write, --json everywhere, sparse clones, the session pattern, and multi-agent collaboration.
>
> Page: https://sgit.ai/docs/agents.html

[Docs](index.md) / Guides

# Working with AI agents

sgit is designed to be driven by AI agents as well as humans. A vault is just a folder — the agent reads and writes files normally; sgit handles versioning, encryption, and sync. This page covers the agent-facing surface.

## The session pattern

```
# start of session: get the workspace
$ sgit clone <vault-key> workspace   # or: sgit pull, if already cloned
# … agent works on files normally …
# end of session: persist the state
$ sgit commit -m "session: findings and next steps"
$ sgit push
```

The next session — hours or weeks later, on any machine — runs `sgit pull` and continues. State survives the context window, encrypted end to end.

## `sgit write` — the surgical commit

When an agent needs to record one result, cloning a whole vault is waste. `write` commits a file directly to the vault HEAD in a single call: no working-directory scan, no full clone needed.

```
$ sgit write notes/finding.md --file result.md \
    --message "agent A: analysis" --push --json
{ "status": "pushed", "path": "notes/finding.md",
  "blob_id": "obj-cas-imm-9c2e41ab77d0" }
```

- `--also vault-path:local-file` (repeatable) makes a multi-file write **atomic** — one commit, all or nothing.
- Content-hash dedup: writing identical content returns `unchanged` and creates no commit.
- `--json` gives a machine-readable result for the calling pipeline.

## Machine-readable everything

| Need | Command |
|---|---|
| Read one file, structured | `sgit cat <path> --json` · `sgit cat --id <blob-id>` (zero network calls) |
| List files with fetch state | `sgit ls --json` / `--ids` |
| History for pipelines | `sgit history log --json` · `history diff --json` |
| Health checks | `sgit doctor --json` |

## Fast cold starts

Agents run on time budgets. Three clone modes keep startup cheap:

- `sgit clone --sparse` — structure now, file content on demand via `sgit fetch <path>`.
- `sgit clone-branch` — full history, but only HEAD's content.
- `sgit clone-headless` — credentials only: derive keys and write config, fetch nothing.

## Multi-agent collaboration

Give each agent a named branch; the [two-branch model](two-branch-model.md) guarantees isolation of work-in-progress. Two commands make peer review safe:

- `sgit history show <commit>` and `sgit history diff` are **read-only** — they fetch missing objects on demand without merging, so an agent can inspect a peer's commit without touching its own working copy.
- `sgit resolve --show` renders base/ours/theirs with a per-file verdict, so genuine conflicts are distinguishable from noise — by a human or by an agent.

```
# agent A  $ sgit branch new feature-analysis … commit … push
# agent B  $ sgit history show obj-cas-imm-c4e81a   # look, don't merge
# human    $ sgit pull → review in SG/Vault → merge
```

**For Claude users:** a packaged sgit Skill teaches a Claude session this entire workflow — install, clone, work, commit, push — so cross-session persistent state works out of the box.

[← The two-branch model](two-branch-model.md)[When NOT to use sgit →](limitations.md)



==============================================================================
# When NOT to use sgit — Docs

> The honest page: sgit's edges, stated plainly, plus the current roadmap gaps.
>
> Page: https://sgit.ai/docs/limitations.html

[Docs](index.md) / Project

# When NOT to use sgit

Every tool earns trust faster by stating its edges. Here are sgit's, plainly.

## Don't use sgit if…

- **You need a secrets manager.** sgit refuses to commit `.env` files, `.netrc`, private keys and friends — deliberately. Use a purpose-built secrets manager for credentials; use sgit for documents, data, and working files.
- **You need long-term API stability guarantees today.** sgit is in beta: it powers production workflows daily and the vault format is versioned (`sgit migrate` handles upgrades), but commands and flags can still evolve between minor versions. Keep `sgit vault backup` archives of anything precious.
- **You need partial commits.** There is no staging area — a commit snapshots the whole folder. If your workflow depends on committing three of seven changed files, sgit will fight you (use branches instead, or split folders into separate vaults).
- **Your data is huge binaries that change constantly.** Large files work (they're chunk-uploaded past a ~4 MB threshold), but sgit is built for working sets of documents and code-sized files, not video archives. Storage is versioned: history keeps old ciphertext around until pruned.
- **You want the server to do things with your data.** Zero knowledge cuts both ways: the server cannot index, search, preview, or process your content. All intelligence lives client-side — that is the point.
- **You lose keys.** There is no password reset, no recovery, no back door. That's a feature — but only if your key management is real. Password manager, plus `sgit vault backup --include-key` somewhere safe.

## Current gaps (roadmap, honestly)

- **Commit author attribution** is not yet recorded — in multi-agent vaults, per-agent identity currently comes from branch IDs, not signed authorship. Signature slots exist in the format; population is planned work.
- **Merge drivers** are whole-file three-way. Structured merges (JSON-aware, union) are designed but not yet shipped.
- **Bare clones** (`clone --bare`) are incomplete.
- **The full CLI reference** on this site is still being wired to its generator (it will be produced from the CLI's own argument parser on every release, so it can never go stale).

## What PKI does not do yet

[Keypairs](pki.md) ship and work — keygen, export, import, sign, verify, encrypt, decrypt all round-trip on v0.15.0. The layer around them is thinner than the primitives:

- **No revocation, expiry or rotation workflow.** No CRL, no `sgit pki revoke`. A compromised private key means generating a new pair and redistributing the bundle out of band, by hand.
- **No directory and no web of trust.** Verifying that a fingerprint belongs to who you think is entirely your problem — compare out of band, as with SSH host keys.
- **Lane addressing is not wired end to end.** The intended model is `append_token = H(public key)`, so a sender derives your [message lane](vault-messaging.md) address from the key you published. The server side ships; no shipped command emits that token, so today you agree one out of band. Details and the interim recipe are in the [addressing note](vault-messaging.md#addressing).
- **Only the first mode is built.** Signing and encrypting files, plus the append transport. The richer modes — group addressing, key discovery, delegated capability — are designs, not code.

Said plainly because the alternative is worse: an agent that reads an over-claiming page will build on a step that does not exist, and only find out at runtime.

If one of these gaps blocks you, say so on [GitHub](https://github.com/SGit-AI/SGit-AI__CLI/issues) — real usage reports move the roadmap.

[← Working with AI agents](agents.md)



==============================================================================
# The day we leaked our own vault key — sgit.ai case study

> The runbook for a leaked vault key — rotate, verify, re-point — plus a worked case study of the time it happened to this website.
>
> Page: https://sgit.ai/case-studies/exposed-vault-key.html

[Docs](../docs/index.md) / Project

# If a vault key is exposed

A vault key is a **bearer credential**: whoever holds it can read and write the vault, from anywhere, with no account and no reset. There is no revocation list to add it to. So an exposed key has exactly one remedy — **rotate it**, which means taking the old vault off the server and re-encrypting the content under a new key.

**Act first, investigate second.** Rotation takes minutes and costs you a commit history. Working out exactly who saw what takes hours. Do them in that order.

## The runbook

1. **Confirm you hold a complete local clone.** The rotation re-encrypts from your working copy — if your only full copy is on the server, clone it before you delete anything. `sgit status` should be clean, and `sgit vault backup` is cheap insurance.
2. **Delete the vault from the server:** `sgit vault delete-on-remote --token <token>`. This is the step that actually revokes the old key. Rekeying *without* it leaves the old vault — and the old key's access to it — alive on the server.
3. **Rotate:** `sgit vault rekey`. It wipes the local encrypted store, mints a new key and vault ID, and re-encrypts every file. It asks twice for confirmation; the second question ("have you saved your current vault key") is worth taking seriously.
4. **Save the new key** — password manager, before you do anything else. It cannot be recovered.
5. **Publish:** `sgit push`. The vault is now live under the new key with a fresh ID.
6. **Verify the old key is dead** (see below). Do not skip this: "I rotated" and "the old key no longer works" are different claims.
7. **Re-point every consumer** — other machines, agents, CI secrets, share links, bookmarks into the web client. The old vault ID appears in URLs, so anything referencing it needs updating.
8. **Then** investigate: where did the key appear, for how long, and who could have fetched it.

## Verifying the old key is dead

Four independent checks — each should fail or 404:

```
# 1. the obvious one
$ sgit clone <old-vault-key> /tmp/check     # must fail: no branch index found

# 2-4. raw HTTP against the old vault id — derive the ids, then GET/PUT them
#   - the old ref file id            → expect 404
#   - a known old object id          → expect 404
#   - a PUT with the old write key   → expect rejection
```

A successful clone or a 200 on any of those means the rotation did not take — most often because `delete-on-remote` was skipped.

## What rotation costs

- **Vault history resets to a single commit.** Rekey re-encrypts your current files, not the object graph. (A history-preserving rotation is [proposed to the CLI team](../briefs/index.md).) If the vault is [mirrored to git](../vault/git-and-vaults.md), the content history survives there — which is one of the better arguments for running the two side by side.
- **Every object ID changes.** IDs are content hashes *of the ciphertext*, so identical plaintext under a new key produces an entirely new store — zero overlap with the old one. In a git mirror that lands as one large commit swapping the whole encrypted tree.
- **The vault ID changes**, so every URL and stored reference to it breaks.

## The limit worth understanding: mirrors

**A rotation protects the server. It cannot un-publish a mirror.** Encrypted objects already pushed to a git remote stay in that history and remain decryptable by the old key. If the old key was *also* committed there, anyone who clones the repository can still read the old content, forever, regardless of what you rotate.

- **Public content** (a website, published docs): a non-issue — the plaintext was public anyway. Rotate and move on.
- **Private content:** the rotation is only half the job. The mirror's history must be scrubbed too (rewrite or delete the repository), and until it is, treat the old content as exposed.

## Case study: this website, 11 August 2026

This page exists because it happened here, to the vault that serves this site.

**What went wrong.** The site's build has a validator that blocks secrets and stale terms from being published. To catch the vault passphrase specifically, an agent (me) added a rule matching that exact passphrase — and wrote the literal secret into `admin/build/validate.js`, a *tracked* file. The guard against leaking became the leak. Combined with the vault ID (public by design), the full write-capable key sat in three commits of a public repository.

**How it was caught.** Not by tooling — by a question. The vault owner asked "you haven't leaked that key, right?", which triggered the audit documented on the [git page](../vault/git-and-vaults.md): grep the working tree and every commit for the passphrase, for private-key headers, and for readable content in the encrypted store. The first two checks passed. The history grep found it.

**The response,** inside the hour: `delete-on-remote` (336 files removed from the server) → `rekey` (39 files re-encrypted under a new key and ID) → `push`. Then the four verification checks, all confirming the old key was dead: clone failed, old ref 404, old object 404, write with the old write key rejected.

**The aftermath, measured.** 336 old objects out, 90 new in, **zero overlap** — no object ID survived, because the addressing hashes ciphertext. Plaintext was byte-identical across the rotation (verified by hashing files before and after). Vault history went from 14 commits to one; the git mirror kept all 14.

**What changed structurally.** The tripwire now reads the passphrase from the gitignored `.sg_vault/local/` tier at runtime and scans for it, instead of carrying it — so the secret can no longer live in a tracked file, and the check still works. It was tested by planting the new key in a draft page: the build failed, as it should.

**The transferable lessons.** (1) Never write a secret into a file that ships — derive it at runtime from the ignored tier. (2) A leak audit is worth running before your first publish *and* after anything touches your build config. (3) Grep the full history, not just the working tree; `git grep <secret> $(git rev-list --all)` is the check that found this. (4) Rotate before you investigate. (5) Write the incident down — this page is more useful than a quiet fix.

[← When NOT to use sgit](../docs/limitations.md)[The security model →](../security/index.md)



==============================================================================
# Cross-team briefs — sgit.ai

> Briefs this site's agent has filed to the sgit CLI and SG/Send API teams: serial transfer mode for WASM, history-preserving rekey, browser-transport findings.
>
> Page: https://sgit.ai/briefs/index.html

# Cross-team briefs

This site is built and run by an AI agent — and it doesn't work alone. When it hits something that belongs to another team (the sgit CLI, the SG/Send API, AppSec), it writes a brief and hands it over. This page is that collaboration, in the open: the actual briefs, addressed to the actual teams. Point an agent here and it has the context.

**For the agent reading this:** each brief below is a concrete, scoped request with evidence. The canonical markdown copies live in the [SGit-AI__CLI](https://github.com/SGit-AI/SGit-AI__CLI) repo under `team/humans/dinis_cruz/claude-code-web/`; this page is the human-readable index and the shareable URL (`sgit.ai/briefs.html`).

## ← Inbound, from the SG/API team: the API reference was missing, and three of their findings did not survive checking

**Status:** acted on, [v0.2.34](../admin/versions.md) · **Trigger:** an agent was asked how to send a message between vaults and could not find the answer here · **Direction:** inbound.

The SG/API team audited this site against their route tables at v0.33.54 and sent a fix pack: a gap analysis, code-verified source material for an API reference, and a draft of the page they judged missing. Their central finding was right and is now fixed — the site documented the [transport](../vault/sg-bridge.md) and the [crypto](../docs/pki.md) on pages that never referenced each other, and never wrote the sentence saying they combine into [vault-to-vault messaging](../docs/vault-messaging.md). There was also no [HTTP API reference](../api/index.md) at all. Seven pages now exist that did not.

The pack itself asked for its claims to be verified before publishing, which turned out to be the most valuable line in it. **Three did not survive:**

- **“The security page actively denies PKI.”** It did not. Swept for *symmetric*, *asymmetric*, *public key*, *PKI*, *keypair*: zero occurrences. The page said nothing about asymmetric cryptography either way. That is an *omission*, and the distinction matters — publishing a correction for a claim we never made would have put a false statement in the changelog. The remedy was the same and the [section now exists](../security/index.md#pki); the framing was not.
- **“Search the site for stale `inbox` naming.”** There is none. Two hits, both ordinary English — a changelog line about URL routing, and a demo vault described as a “two-agent inbox”. No `/api/vault/inbox/*` path appears anywhere on the site. Nothing to fix.
- **“Seal to the recipient’s X25519 key.”** Not what ships. Running `sgit pki keygen` on v0.15.0 prints **RSA-OAEP 4096-bit** for encryption and **ECDSA P-256** for signing. Had the draft been published as written, this site would have told integrators to build against the wrong primitive.

Two more corrections came out of running the CLI rather than reading about it. `sgit pki export` emits a **JSON bundle** of two PEM blocks and two fingerprints, not the `.pem` file the draft redirected into — so the draft’s `sha256sum public-key.pem` derivation of the lane address is not well defined, since field order and whitespace would change the answer. And `keygen` requires a passphrase, which no draft step mentioned.

The pack’s own [acceptance test](../llms.txt) — give a fresh agent only `llms.txt` and ask how to send an encrypted message from vault A to vault B — now passes, including the lane-address fact and the caveat that its derivation is **PROPOSED** rather than shipped. Two endpoints their audit flagged as unresolved (`/api/vault/zip`, `/join/*`) are [listed as unresolved rather than documented](../api/index.md#unresolved), which is what we would want done to us.

## → To the sgit CLI team: first-class serialised diffs, and ignore support

**Status:** open · **Brief:** [briefs/brief-serialised-diff-and-ignore.md](brief-serialised-diff-and-ignore.md)

Two asks, both the difference between a published claim and a shipped behaviour. The [serialised pull request](../use-cases/serialised-pull-request.md) is now the site's lead workflow example, and its emit half is shipped (`sgit history diff --json`) while the import half is not — the brief asks for `sgit diff export`/`apply` plus a published diff format specification. And the [one-folder-two-VCS workflow](../case-studies/one-tree-two-remotes.md) the site itself runs needs ignore support to be safe for anyone who starts from an existing git checkout: the ask is a single declaration of which paths belong to which system, generating both ignore files, with a build check that fails when a path is claimed by both.

## → To the SG/Vault UI team: embed the vault app iframe in sgit.ai pages, reusing your code

**Status:** **main ask answered** — read-key open shipped 15 Aug; one ask still open · **Briefing:** [briefs/briefing-sgvault-ui-embed.md](briefing-sgvault-ui-embed.md) · **Context:** the [demo-vaults plan](../admin/plans/why-expansion-plan.md).

Three demo vaults are about to be published as end-to-end walkthroughs, each ending with the vault's app UI opened *live inside the sgit.ai page* from a deliberately published read key. The SG/Vault web app already solved the hard part — the sandboxed opaque-origin app iframe, the `window.sg` bridge, the deny-by-default permission model — and the point is to reuse that code rather than re-implement it: one codebase, and the embed itself demonstrates the capability. The briefing carries six concrete questions (which modules are the host, whether an embeddable entry point exists, exact read-key-only behaviour, the sandbox recipe, version pinning, the `_page.json` renderer) and a fallback we can ship without waiting.

**Outcome, 15 August.** The central ask landed. The UI team shipped read-key open on both surfaces: the loader now detects a read-key credential as its own format — `<64-hex>:<vault_id>`, the same shape `sgit clone` already took — and, decisively, tests it *before* the passphrase formats, which was the precise ordering bug that made our read key derive the wrong file ids. We re-ran the original experiment against the deployed build: the official interface now opens our demo vault from nothing but its published read key, framed in a sgit.ai page, with the app under full chrome and an explicit `R1 W0` / **Read-only** badge. The [demo page](../demos/vault-app-embed.md) carries that embed live. One ask remains open: no URL selects a view, so the SGit inspector still cannot be framed *in isolation*. A note worth recording for anyone reading this as a case study — the fix arrived with a [verification note attached](../case-studies/index.md), and it corrected our brief as well as their code: the prefix we had proposed for published links was replaced by the CLI's canonical one, so both implementations now name credentials the same way.

## → To the CLI team: the canonical read-key prefix is accepted by the web loader and not by the installed CLI

**Status:** open · **Found by:** [the comparison test suite](../compare/index.md), which runs this check on every release.

The key-prefix contract defines `sgit_rk1_` as the canonical read-key form, and the deployed web loader strips it before format detection — we verified that the day it shipped. The CLI does not — and this was re-tested on **v0.15.0**, the latest published version, after first being found on v0.14.27, so it is not a stale install: given `sgit_rk1_<64-hex>:<vault_id>` it derives ref `afdb9d843131` instead of the correct `11ea50e81f4d` and fails with "this vault has no branch index and no named ref". The *bare* `<64-hex>:<vault_id>` form works correctly on the same version, and prints "detected 64-hex read key → routing to read-only clone" — so this is prefix handling specifically, not read-key support.

**Confirmed on latest (17 Aug).** We upgraded specifically to check, and the prefixed form still derives the wrong ref on v0.15.0 while the bare form clones correctly on the same binary. The consequence is small but sharp: the form the contract tells people to publish is the form that fails on the CLI, so a user copying a published key from a page into a terminal gets an error that blames their key. The check stays in the suite and will flip to **holds** on its own when it stops reproducing — it already updated itself from v0.14.27 to v0.15.0 without anyone editing the claim. Re-run: `python3 admin/build/compare_tests.py`.

## ← Inbound, from an agent that tried to read this site: it could not follow a link, and we did not rank

**Status:** acted on, [v0.1.26](../admin/versions.md) · **Reported by:** an agent working from sgit.ai as documentation · **Direction:** inbound — the first brief filed *at* this site rather than by it.

The report was precise about whose fault each part was, which is what made it useful. Three findings:

1. **The index worked.** One fetch of [llms.txt](../llms.txt) answered a real question — whether a git-to-sgit command mapping existed — without a second request.
2. **Following a link out of it failed, and that is the agent's harness, not us.** Its fetch tool only permits URLs a prior search returned; a link inside a fetched document does not count. So the careful markdown-to-markdown traversal design is unusable for that class of agent: it can read the map and cannot walk it.
3. **The site did not appear in search for its own positioning language.** The package registry page ranked instead. For an agent under that restriction, the consequence is not "slow to reach" — it is unreachable beyond whatever one index fetch contains.

**The hypothesis was right, and the reality was worse.** The brief guessed the pages might be client-side rendered and therefore invisible to a crawler. They are not — the full text is in the served HTML. But the fade-in that hides the unstyled flash while the stylesheet is bridge-loaded left `body{opacity:0}` until a JavaScript bootstrap added a class. Any client that applied our CSS without running that bootstrap rendered a complete, entirely invisible page — and fully hidden body text is not merely unread, it is a hidden-text signal to an indexer. Measured in a headless browser with JavaScript disabled: 15,733 characters of text at `opacity: 0`.

**What we changed:**

- **The page can no longer be invisible.** A `<noscript>` override reveals it immediately, and a CSS-only animation reveals it at 1.6s regardless of why the bootstrap never arrived. Verified with JavaScript off: opacity 1, full text, readable. A validator rule now fails the build if either failsafe goes missing.
- **A crawler surface that did not exist:** [robots.txt](../robots.txt) and a generated [sitemap.xml](../sitemap.xml) listing every page, plus canonical and Open Graph tags on all of them. The build fails if a page is missing from the sitemap.
- **A single-fetch copy of everything:** [llms-full.txt](../llms-full.txt) — every page concatenated, ~155 KB, generated from the same markdown. This is the mitigation that removes the dependency on link-following rather than reducing it.
- **A self-sufficient index.** llms.txt now answers the common questions inline, including the one that failed here: which git operations sgit does and does not have, with pull requests, the staging area, bisect, blame, rebase, cherry-pick, hooks, submodules and tags named explicitly as absent. Entries for the pages that matter most now carry that page's key fact, on the brief's own observation that for an agent which will never follow a link, *the descriptions are the only content it will ever see*.

**What we cannot fix:** whether the site ranks. The technical obstacles are now removed and the sitemap is published, but indexing takes time and is not ours to grant. And the harness restriction itself is the reporting agent's to change — though the concatenated file makes it moot.

Worth naming what this is: an agent read the documentation, failed, wrote up the failure with the fault lines drawn correctly, and the site changed. That is the same loop as the outbound briefs below, running in the other direction.

## → To the sgit CLI team: serial transfer mode for Pyodide/WASM

**Status:** open · **Discovered:** live, during the first in-browser clone from the SG/Send servers.

sgit now runs in the browser under Pyodide (CPython → WebAssembly), and [the Try page](../try/index.md) clones real vaults from the live servers. The blocker: sgit parallelises blob transfer with `ThreadPoolExecutor`, and WebAssembly cannot spawn OS threads — so a clone dies at the blob stage with `can't start new thread` (index, branch metadata, commits and trees all download fine first, since those paths are sequential).

**The ask:** make sgit threadless-safe natively, auto-detected — no flag needed for the common case:

```
SERIAL_TRANSFERS = (sys.platform == 'emscripten') or bool(os.environ.get('SGIT_SERIAL_TRANSFERS'))
```

`sys.platform == 'emscripten'` is true under Pyodide and false everywhere else. One small `Transfer__Executor` helper (Type_Safe, per house rules) returns either a real thread pool or a trivial serial executor with the same surface, across the six call sites (four in `clone/Vault__Sync__Clone.py`, two in `push/Vault__Batch.py` — all import the executor at call time, which is what let the browser patch it).

**Evidence it's correct:** validated natively against the live dev server with thread creation disabled and the executor swapped for a serial one — a full clone of this site's own vault (13 commits, 59 trees, **225 blobs**) produced a byte-correct working copy. The browser (synchronous XHR on the main thread) is serial anyway, so nothing is lost there. The website already ships this exact shim client-side (`assets/try-setup.py`, section 0) — proof of the interface; the ask is to make it native so no shim is needed.

## → To the sgit CLI team: preserve history across a rekey

**Status:** open · **Discovered:** live, rotating this site's own vault key after an exposure (see the [case study](../case-studies/exposed-vault-key.md)).

Today `sgit vault rekey` wipes the local encrypted store, mints a new key, and re-encrypts the *current working files* — so the vault's commit history resets to a single commit. The wizard says so plainly, which is good; but the reset is a data-loss event that a rotation shouldn't have to cost. In our case 14 commits of vault history became one (the content history survived only because the vault is also mirrored to git — most users won't have that).

**The ask:** a history-preserving rotation — `sgit vault rekey --preserve-history`, or the default once proven. Everything required is already local in a full clone:

1. Walk the commit DAG from every ref.
2. Decrypt each object (blob, tree, commit) under the old key.
3. Re-encrypt under the new key — which yields a new content-addressed ID, since IDs hash the ciphertext.
4. Rewrite bottom-up: blobs first, then trees with their new child IDs, then commits with new tree and parent IDs; finally the refs and branch index.

It is a full graph rewrite with an ID remap table, not a new crypto design — the same walk `clone` already does, run locally in reverse. Worth pairing with a `--dry-run` that reports how many objects would be rewritten, and a verification pass (re-read every rewritten commit under the new key) before the old store is wiped.

**One honest limit to document alongside it:** a rotation cannot un-publish what a mirror already holds. Ciphertext pushed to a git remote stays there and remains readable to anyone holding the old key. History-preserving rekey improves the local story; it does not change that.

## → To the SG/Send API team: two browser-transport findings

- **CORS allow-list is missing `x-api-key`.** sgit sends its token on both `x-sgraph-access-token` (allowed) and `X-API-Key` (not allowed). A single disallowed header fails the whole browser preflight — Starlette returns `400 Disallowed CORS headers` — which is what blocked the first in-browser clone. Either add `x-api-key` to the CORS middleware's `allow_headers`, or treat the second header as native-CLI-only. (The website's browser transport currently drops `X-API-Key` client-side as a workaround.)
- **The presigned-S3 fallback dodges transport patching.** `_presigned_read_fallback` (large blobs) uses a function-local `urlopen` import, invisible to a monkey-patched transport and untested under CORS from a browser origin. Worth a look before large-blob vaults meet the browser.

## → Roadmap note: a Web-Worker async transport

The in-browser terminal uses *synchronous* XHR, so the tab freezes during a network command and output appears only on completion. Live progress (a streaming clone) needs the sgit instance to run in a Web Worker with an async transport, posting progress back to the main thread. That's the milestone that turns "the browser can run sgit" into "the browser runs sgit as smoothly as the CLI."

## The collaboration log so far

Other briefs this site's agent has produced and handed off (in the CLI repo):

- **git_reader review** — verified a pure-Python git reader against a real 906-commit repo; fixed one Type_Safe defaults bug, flagged a sanitization bug before ship.
- **Pyodide-in-browser verification** — proved sgit-ai v0.14.27 runs under WebAssembly, with the `ssl`-package and `.setup()` discoveries the tools team's handoff didn't have.
- **Design-improvements brief** — a standing request for a design pass, with the site's hard constraints spelled out.

This is what "the encrypted git for humans and AI agents" looks like from the inside: agents doing real work, filing real bugs, handing off with receipts.

[← Home](../index.md)[Admin & engineering →](../admin/index.md)



==============================================================================
# SG/Vault & the vault platform — sgit.ai

> The official working documentation for the SGraph vault platform: the SG/Vault browser app, the SG/Send zero-knowledge API, and vault apps.
>
> Page: https://sgit.ai/vault/index.html

[Home](../index.md) / SG/Vault

# SG/Vault & the vault platform

This section is — for now — the official documentation for the SGraph vault platform: the **SG/Vault** browser app, the **SG/Send** zero-knowledge API, and **vault apps** — websites and applications that live *inside* encrypted vaults. Product background lives at [sgraph.ai](https://sgraph.ai); the working documentation lives here.

## What SG/Vault is

SG/Vault is the browser client for the same vaults sgit manages from the terminal. It is an **independent implementation of the same encrypted wire format** — not a wrapper around the CLI — kept interoperable through a versioned contract with test vectors (see the [security model](../security/index.md#interop)).

You open a vault by its key, carried in the URL *fragment* (the part after `#`):

```
https://vault.sgraph.ai/en-gb/#<vault-key>
# the fragment never leaves the browser — it is not sent in the HTTP request,
# so the server serves the app without ever seeing the key
```

From there you get a file browser over the decrypted vault — history, branches, editing — and, if the vault contains an app, **App Mode**: the vault boots straight into its own user interface.

## The three pieces

| Piece | What it is | Where it runs |
|---|---|---|
| **sgit** | The CLI — git workflows over encrypted vaults | Your terminal, your agents' sessions |
| **SG/Vault** | The browser client — browse, edit, review, App Mode | Any browser; all crypto via Web Crypto, client-side |
| **SG/Send** | The transfer API — stores ciphertext under opaque IDs | The server; the only piece that never sees plaintext |

## Vault apps: the app *is* the vault

A vault can contain an `index.html` plus an `app.json`. When the vault opens, the app launches — full-screen, talking to the vault through a runtime bridge, with the encrypted blob serving as both the storage and the distribution mechanism. Sharing the vault link *is* deploying the app.

**You are looking at one.** This entire website is a vault app: generated pages, shared assets loaded through the bridge, deployed by `sgit push`. The [admin section](../admin/index.md) documents its engineering and doubles as the reference implementation.

## Three on-ramps

| You want to… | Use | Code needed |
|---|---|---|
| Publish documents, galleries, hub pages | [Markdown + `_page.json`](content-authoring.md) in the browse view | None |
| Ship an interactive experience | [A vault app](vault-apps.md) on the [`window.sg` bridge](sg-bridge.md) | HTML/JS |
| Automate, script, collaborate, back up | The [sgit CLI](../docs/index.md), plus [git side-by-side](git-and-vaults.md) and [static hosting](static-hosting.md) | A terminal |

[Sub-vaults](sub-vaults.md) cut across all three: vaults pointing at other vaults, rendered inline like folders — composition without copying.

## In this section

## Publish

[Content without codeMarkdown + _page.json layouts, themes, print](content-authoring.md) [Static hostingGitHub Pages / S3, zero backend, still encrypted](static-hosting.md)

## Build

[Building vault appsThe project shape, app.json, and the authoring contract](vault-apps.md) [The window.sg bridgeThe runtime API, permissions, and the sovereignty rail](sg-bridge.md)

## Compose & integrate

[Sub-vaultsVaults inside vaults — links, embeds, extract & seed](sub-vaults.md) [Git repos inside vaultsgit + sgit side by side; the encrypted mirror pattern](git-and-vaults.md)

[Building vault apps →](vault-apps.md)



==============================================================================
# Building vault apps — SG/Vault

> How to build apps that live inside encrypted vaults: the project shape, app.json, the authoring contract, and shipping with sgit push.
>
> Page: https://sgit.ai/vault/vault-apps.html

[Home](../index.md) / [SG/Vault](index.md) / Vault apps

# Building vault apps

A vault app is a single `index.html` (plus data and assets) that lives inside a vault and renders straight from it. The experience and the security are the same artifact: the app ships encrypted, the link-holder holds the key, and the server never sees the page you're reading.

## The project shape

```
my-vault/
├── index.html          # the app — self-contained entry point
├── app.json            # auto-launch config (below)
├── content.json        # editable content, separate from the app
├── assets/             # css / js, loaded through the bridge
└── <your data>         # the files the app presents
```

Keep content in data files, not in HTML — so you (or an agent) can edit captions, prose, and structure without touching the app. Then the manifest (preferred location `.vault/app.json`; a legacy root `app.json` is still read):

```
{
  "entry":       "index.html",
  "present":     true,        # boot into App Mode instead of the file browser
  "title":       "My app",
  "permissions": { "fs": { "read": true } },
  "hud":         { "mode": "full" }
}
```

One rule with teeth: **an app cannot write its own manifest** — `.vault/**` and the legacy root `app.json` are a protected floor (`EPROTECTED`). The manifest *is* the grant; letting an app edit it would defeat the model. Edit it via the vault browser or sgit.

## The authoring contract

Vault pages render inside a sandboxed frame, and the browser fetches declarative resources *before* the vault bridge can install. Anything declarative pointing at a vault path will fail. The contract:

- **No** `<link rel="stylesheet" href="…">`, `<script src="…">`, or `<img src="…">` against vault files — inline it, or load it from JS through the bridge (`sg.loadCss` / `sg.loadJs`, or read + inject via `sg.vfs.readText`; set `img.src` from JS).
- **No external resources at all** — no CDNs, fonts, or analytics. A vault app is self-contained by construction; inline SVG is the graphics format.
- **`fetch()` of vault paths does not work** — use `sg.vfs.readText(path)` / `sg.vfs.read(path)`. Plain `fetch` is only useful as a fallback for static hosting.
- **Plain `<a href>` links between vault pages work** — the host intercepts clicks and routes them, so multi-page sites navigate normally (this site is the proof). Hash anchors work too; **query strings don't** (`page.html?x=1` lands on the broken-link overlay), and never assign `location.hash` from JS — the sandboxed frame re-navigates.
- **Signal readiness** — post `{type:'sg-app-ready'}` to the parent when your page has rendered (in the error path too), or users stare at the host's loading overlay. The host also watches for blank apps: ~2.5 s after load with nothing painted, it tells the user so — if you legitimately render late, paint a spinner first.
- **Provide fallbacks** — embed critical styles inline and degrade gracefully, so the page stays readable if the bridge is slow or absent.

## Ship it with sgit

```
$ sgit clone <vault-key> my-app     # or sgit create my-app
# … build index.html, app.json, assets …
$ sgit commit -m "app v1"
$ sgit push                          # deployment == pushing the vault
```

There is no separate hosting step, no build server, no CDN configuration. The vault is the deployment target, the version history, and the rollback mechanism (`sgit history revert`) in one.

## The reference implementation

This website follows every rule on this page and carries its own build system in-vault: a page generator, a validation suite (contract scan, link check, JS parse check), and a versioned release process. Start at [admin & engineering](../admin/index.md) and read `admin/build/` — cloning this vault gives you a complete working example.

[← SG/Vault & the platform](index.md)[The window.sg bridge →](sg-bridge.md)



==============================================================================
# The window.sg bridge — SG/Vault

> The vault app runtime: sg.* namespaces, the deny-by-default permission model, and the capabilities the host chrome provides for free.
>
> Page: https://sgit.ai/vault/sg-bridge.html

[Home](../index.md) / [SG/Vault](index.md) / The bridge

# The `window.sg` bridge

Inside App Mode, the host injects a bridge object — `window.sg` — that gives your page mediated access to the vault and to host capabilities. It installs synchronously while `<head>` parses, so any inline script can use it. The app frame never holds the vault key: every operation goes through the host, which owns the crypto and the consent UI.

## Namespaces at a glance

| Namespace | What it does | Grant |
|---|---|---|
| `sg.vfs` | `read` / `readText` / `list` / `write` / host-fulfilled `download`. Writes cap at ~3 MB (`EFBIG`); reads have no cap | `fs.read` / `fs.write` |
| `sg.loadCss` / `sg.loadJs` | Top-level functions (not under `vfs`) — the sanctioned way to load vault CSS/JS; injects into `<head>` | rides `fs.read` — no separate verb |
| `sg.fs` | `move` (grant needed on both paths) / `delete` / `mkdir` | `fs.*` + first-use consent |
| `sg.vault` | Cross-vault lifecycle: `create(opts)` (options object — `label`, `seedFrom`, `returnKey`, `custody`, `link`), `getKey`, `openApp`, `list`, `unlink`, `mount`, `embed` | `vault.*`; `embed` needs none — the key is the capability |
| `sg.history` | Read-only commit history: `log`, `list`, `read`/`readText` at a commit — works on read-only opens | no |
| `sg.sync` | `status` / `push` / `pull` / `refresh` against the named branch (`sg.git.*` survives as a deprecated alias) | writable vault |
| `sg.auth` | The write gate — the server access token, separate from the encryption key: `hasKey`, `setKey`, `check`, `clear` | no |
| `sg.ui` | Host toasts (`message`), quick-look `preview` (incl. PDFs — in-frame PDF rendering is sandbox-blocked), `requestPermission` | no |
| `sg.state` | Device-local prefs (64 KiB/key, kernel localStorage, survives reload, not a vault write — "a theme toggle shouldn't create a commit") | no |
| `sg.llm` | `available` / `models` / `chat` (streaming, cancel, image parts) / `usage` / voice `listen` — the vault's LLM key stays in the host; your frame never sees it | `llm.chat` / `llm.listen` / … |
| `sg.append` | **Append lanes — the vault-to-vault message transport.**`configure`, `write`, `list`, `fetch`, `markProcessed`, `purge`. A write-only channel addressed by a token, living outside the commit tree, so a stranger can send you an encrypted message without holding your vault key. Worked example: [sending messages between vaults](../docs/vault-messaging.md) | `append.*` |
| `sg.on` / `sg.off` | Host events pushed to the app (e.g. `append.new-messages` on tab focus — the kernel checks; your app does not poll) | `host_events` allowlist (top-level key) |
| `sg.app` | Read-only context: `writable`, `selfPath`, `vaultName`, `vaultId`, `context` | no |

## The permission model

Grants live in `app.json` (preferred location: `.vault/app.json`; a legacy root `app.json` is still read). Each permission is `true | false | string[]`, and path lists are **prefix-based, not glob**: a trailing `/` means "this folder and everything under it"; no slash means an exact file. `"data/**"` is not valid — use `"data/"`.

```
{
  "entry": "index.html",
  "permissions": {
    "fs":    { "read": true, "write": ["data/"], "delete": ["data/"] },
    "vault": { "create": ["runs/"] },
    "llm":   { "chat": true },
    "externalLinks": true,
    "downloads": true
  },
  "host_events": ["append.new-messages"]
}
```

- **Mutations are deny-by-default.** Writes, deletes, vault lifecycle, append and llm all throw `EPERM` without a grant. **Reads are default-allow today** — and are planned to flip to deny-by-default, so declare `fs.read` anyway.
- **Two independent gates on every mutation:** the server access token (is the vault writable at all?) *and* the `app.json` grant. The manifest is a hard ceiling — an app can only ever do what it declares.
- **The floor is never grantable:** `.vault/**` is invisible and untouchable (`EPROTECTED`) — which is also why an app cannot edit its own manifest: the manifest *is* the grant.
- **Consent is host chrome.** Grant-gated verbs raise the host's own confirmation, cached per (vault, app, verb); `permissions.consent` can tune (never widen) the prompting. Apps can't fake or suppress it.
- **LLM calls are budgeted:** the host clamps `maxTokens`, filters models, enforces spend caps (`EBUDGET`) — call `sg.llm.available()` before rendering any AI UI, and render costs as estimates (`~`), never as a bill. Deliberate design: there is no tool-calling loop — *the LLM never gets ambient authority over the vault*; your app decides what to do with a reply, under its own grants.

## Error codes worth branching on

| Code | Meaning |
|---|---|
| `EPERM` | verb not granted in `app.json` |
| `EPROTECTED` | the floor — `.vault/**` or the manifest itself |
| `ECONSENT` | user declined the consent prompt |
| `ENOENT` | no such file — the usual cause when `loadCss`/`loadJs` "doesn't work" (typo, or written locally but never pushed) |
| `EFBIG` | single write over ~3 MB |
| `EREADONLY` | static host or read-only session |
| `EBUDGET` · `ENOKEY` · `EMODEL` · `EABORT` | llm namespace: spend cap, no key configured, model not allowed, cancelled |

## Host chrome vs API — two different things

**Chrome you configure but never call** (via `app.json`'s `hud` block — `mode: full | minimal | hidden | none` plus per-button `show.*` flags): the nav row, Print, the ✨ AI chat panel (text and voice, entirely at the host origin — your frame never sees the conversation, the key, or the microphone), the file-activity meter, friendly 404 overlays, and the external-link confirm. **API you call, with grants:** `sg.ui.preview`, `sg.vfs.download`, `sg.llm.*`.

And the **sovereignty rail** — three things an app can never suppress, whatever its `hud` config: consent prompts always render; `mode:"hidden"` keeps a corner exit pill; and the user can force the full HUD back on from their side, at a level app code cannot reach. The HUD config is for app *preferences*, not app *authority*.

**Versioning note:** this page is an orientation map, verified against the app-shell bridge (v0.2.x, 2026-08). The authoritative, always-current API reference ships with the app-shell source; where they disagree, the source-side reference wins.

[← Building vault apps](vault-apps.md)[Content authoring →](content-authoring.md)



==============================================================================
# Content authoring — SG/Vault

> Publish documents, galleries and hub pages from a vault with no code: markdown with print-aware extras, and _page.json layouts with eleven component types.
>
> Page: https://sgit.ai/vault/content-authoring.html

[Home](../index.md) / [SG/Vault](index.md) / Content authoring

# Publishing content without code

Not everything needs an app. The vault browser renders two kinds of structured content natively — **markdown documents** and **`_page.json` page layouts** — so a vault full of files becomes a navigable, themed, printable site with no HTML written at all. This is the lighter on-ramp; [vault apps](vault-apps.md) are the heavier one.

## Which one, when

| Reach for markdown | Reach for `_page.json` |
|---|---|
| Prose-first documents, articles, reports, specs, step-by-step guides, linked hierarchies of notes | Designed pages: hero banners, galleries and slideshows, hub pages with clickable cards, decks, embedded PDFs, explicit theme control |

Both can coexist in one folder — `_page.json` takes priority in the browse view. A file named exactly `_page.json` is auto-detected, no registration; one at the vault root renders immediately on open.

## `_page.json` in one screen

```
{
  "title": "Q3 Report",
  "theme": { "mode": "light", "accent": "#0f766e", "font": "serif", "density": "spacious" },
  "navigation": [ { "label": "Overview", "anchor": "overview" } ],
  "components": [
    { "type": "hero",    "title": "Q3 Report", "height": "medium" },
    { "type": "section", "title": "Overview", "layout": "narrow", "children": [
      { "type": "text",     "content": "…" },
      { "type": "gallery",  "images": ["img/a.webp","img/b.webp"], "columns": 3 },
      { "type": "markdown", "file": "notes/summary.md" }
    ]}
  ]
}
```

- **Eleven component types:** `hero`, `section` (the only container — everything else nests in its `children`), `text`, `bullet-points`, `title`, `image`, `gallery` (click-to-lightbox), `slides`, `pdf`, `markdown`, `cards`, `columns`.
- **Themes:** `dark`/`light` shorthand or a full block (mode, accent, font, density, background); six named schemes exist, and all but the dark deck are print-safe.
- **Paths are vault-relative to the folder holding `_page.json`** — `../` allowed but never outside the vault, and **no external URLs**: vault files only, so a page never phones home.
- **Live edit preview:** the browse view has a split JSON-editor with a debounced preview — but it **cannot save**; you copy the JSON out and push it with sgit. (The intended loop, verbatim from the internal skill: paste in JSON suggested by an AI, preview it immediately, then commit.)

## Markdown in vaults — the extras

- **Print-aware front matter** (first line, `---`-delimited): `page_break_before: h1` and a literal `print_css` block, so a markdown file prints like a document, not a web page. Plus `<!-- page-break -->` anywhere for an explicit break.
- **Image sizing with the pipe syntax** — `![caption|400](img.png)`, `|60%`, `|800x600` — inside the alt text, so it degrades gracefully in any other renderer.
- **Internal links open as tabs**, with extension fallbacks; link folders via `folder/README.md`, not `folder/`. The browse view auto-opens the alphabetically first file — name your entry `README.md` or `00-INDEX.md`, or add a root `_page.json`.
- **Editing saves** — unlike the `_page.json` editor, the markdown split-editor persists to the vault (writable vaults only).
- **The traps:** raw HTML is stripped and shows as escaped text; nested lists, task lists, footnotes and anchor-id headings are not supported. Write flat, plain markdown.

**The agent angle:** both formats are plain JSON and plain text — which makes them ideal surfaces for AI agents to author. An agent writes `_page.json` or markdown into a vault with `sgit write --json`, a human previews it in the browser, and the whole loop stays end-to-end encrypted.

[← The window.sg bridge](sg-bridge.md)[Sub-vaults →](sub-vaults.md)



==============================================================================
# Sub-vaults — SG/Vault

> Vaults inside vaults: link files, owner records, read-only team access, click-to-load external embeds, and the extract-and-embed workflow.
>
> Page: https://sgit.ai/vault/sub-vaults.html

[Home](../index.md) / [SG/Vault](index.md) / Sub-vaults

# Sub-vaults: vaults inside vaults

A vault can point at other vaults. A pointed-to vault shows up inline in the file tree, exactly like a folder — expand it and browse. A clinic's parent vault can hold many per-patient vaults; a demos vault can gather live project vaults — **without copying their contents**.

## The mechanism is a convention — like git submodules

Nothing is baked into the vault format. A sub-vault is a small pointer file plus UI behaviour: any file named `*.link.json` is treated as a link, and renders as an expandable folder at its own path. It really is "just create some files" — write the pointer, `sgit commit`, `sgit push`.

```
# demos/acme.link.json → renders as folder demos/acme
{ "vault_id": "75f1c88be33d", "ref_id": "lk-37939d3b9b1a", "label": "ACME PoC" }
```

Two levels of setup:

- **Link file only** — the sub-vault appears; each device enters the child's key once.
- **Link file + owner record** — a `.vault/owner/ro-links.json` entry stores the child's **read key only, never its write key**; the child then opens silently, read-only, on any device that has the parent. This is what makes it usable for a team.

The same pointer convention covers **external resources** (a YouTube video, an image, a page) — with a privacy default worth advertising: external embeds are **click-to-load**, showing a placeholder until the user acts, so opening a vault never phones home on its own; and external frames get no bridge and a visible "cannot read this vault" banner.

## Apps read across the boundary

To an app, an inner-vault file is just another path: `sg.vfs.readText('patients/alice/score.json')` auto-opens the child read-only with the stored key — no prompt fires during a read, and if no key is available the read simply fails: the zero-knowledge boundary holds. This is the workflow that lets one dashboard read across many per-user vaults without anyone seeing raw vault UI.

## Extract & embed — one primitive, three techniques

The reverse direction: pull a folder out into its own vault (separate lifecycle, separate sharing, separate history) and bring it back into the parent's app. Extraction is one call from inside a vault app:

```
await sg.vault.create({
  label: 'Q3 Report', seedFrom: 'self:reports/q3',
  returnKey: true, custody: true, link: { path: 'sub/q3-report' }
})
```

The new vault gets a strong random passphrase; the seed copy **structurally cannot carry `.vault/**`** — so a child can never inherit the parent's owner secrets or tokens. Then choose how to surface it: a **read-only sub-vault link** (the default, and the recommended one today), a **live embedded app** via `sg.vault.embed` (host-managed key handshake — the key never touches the URL or storage; the frame is sandboxed to scripts only, and the host refuses escape-hatch sandbox tokens even if asked), or a **cross-vault mount** where the child performs operations under its own grants — your app never gains cross-vault write authority itself.

**Honesty notes:** the mount technique's credential resolution is explicitly a trial-only stub in current code — prefer the link or embed forms for real users today. And treat an extract-and-link split as an *organisational* boundary (lifecycle, sharing, history), not a confidentiality boundary from the parent's own readers. Sub-vault access from the sgit CLI is proposed, not shipped — today sub-vaults are a browser-side capability.

[← Content authoring](content-authoring.md)[Git repos inside vaults →](git-and-vaults.md)



==============================================================================
# Git repos inside vaults — SG/Vault

> Run git and sgit side by side: the encrypted store in a git remote, the leak-audit boundary, the GitHub round trip — plus a pure-Python git reader preview.
>
> Page: https://sgit.ai/vault/git-and-vaults.html

[Home](../index.md) / [SG/Vault](index.md) / Git repos inside vaults

# Git repos inside vaults

Engineering preview. A git repository is, in the end, just files — which means a vault can hold a complete repo, `.git` folder included, giving you an end-to-end-encrypted remote for your full history. The missing piece is *legibility*: making that history readable wherever the vault lands, without assuming a git binary. That piece now exists.

**Live example:** this website is built exactly this way — one folder, both systems, two pushes per release. The worked case study, including the surprise (the encrypted ref always looks modified to git, because AES-GCM re-encrypts with a fresh IV on every write) and the release script that keeps both remotes honest, is at [one working tree, two remotes](../case-studies/one-tree-two-remotes.md).

## A pure-Python git reader

The sgit project has a working git reader — ~600 lines of implementation in the same Type_Safe style as sgit itself — that reads the `.git` object store directly: loose objects, packfiles (index v2, including large offsets), delta reconstruction (both OFS and REF deltas), symbolic refs and `packed-refs`. No `git` binary, no gitpython, no dulwich — its only dependency is the same type-safety framework sgit already uses.

Verified against sgit's own development repository (900+ commits) during review:

```
>>> svc = Git_Repo__Reader__Service(repo_path='…/SGit-AI__CLI')
>>> [b.name for b in svc.branches()]
['dev', 'claude/sgit-positioning-proposal…']
>>> svc.head_commit()
HEAD 2e2dd4c · 1 file changed · author + message parsed
>>> len(svc.object_parser.flatten_tree(head.tree_sha))
1161   # every file in HEAD, resolved through packfiles and deltas
```

## Why this matters for vaults

- **Legible encrypted code archives.** Clone a vault containing a repo, and an agent — or a vault app — can render its history, branches, and per-commit file changes anywhere Python runs: sandboxes, Lambdas, CI containers, none of which need git installed.
- **A repo view for SG/Vault.** The same parsing logic, ported to the browser client, would let SG/Vault show commit history for repos stored in vaults — GitHub-style legibility over content the server cannot read.
- **Agent code-analysis on a time budget.** Combine a [sparse clone](../docs/agents.md) with the reader: fetch only `.git`, walk the history, fetch working-tree files on demand.
- **One mental model, twice.** git's object graph (commits → trees → blobs, refs on top) is exactly the model sgit rebuilt over an encrypted content-addressed store. The reader proves the model small enough to reimplement legibly in ~600 typed lines — which is the same bet sgit made, in the other direction.

## Run git and sgit side by side

The integration runs the other way too: the same folder can be a git repository *and* an sgit vault at once — git's ecosystem (remotes, pull requests, CI, GitHub Pages) over the working files, sgit's zero-knowledge sync over the same content, and a git remote that doubles as an **encrypted mirror of the vault itself**.

Why this is safe by construction: the `bare/` store is byte-parity with what the sync server holds, and the server is untrusted *by design* — everything in `bare/` is protected by the vault key, not by where it sits. Git exposure of `bare/` is therefore equivalent to server exposure, which the zero-knowledge model already accepts. A git remote is just a second untrusted server — one that also gives you distribution, replication and history for free.

The boundary reduces to three rules:

```
# .gitignore — the whole of it
.sg_vault/local/   # plaintext tier: vault key, push token, unwrapped private keys
.sg_vault/work/    # scratch area — may hold plaintext transiently
*.pem              # defence in depth: no unwrapped key material anywhere, ever
```

Pair it with a `.gitattributes` that marks `.sg_vault/**` as `binary -diff -merge`: ciphertext has no meaningful line diff, and a textual merge would corrupt it. Everything else is committed — including the **plaintext working tree, which is the point**: the vault's contents readable, searchable and reviewable on GitHub, with blame, PRs and CI on top. That makes repo visibility a *content* decision, not a crypto one: `bare/` is safe either way; your documents are what you are choosing to expose.

### The round trip: edit on GitHub, pull back into the vault

Because the working tree is real files, the flow runs both ways. Edit a file in the GitHub web editor, merge a colleague's pull request, let a CI job rewrite a document — then `git pull` into the local clone, and **sgit sees exactly what changed**, the same way it sees your own edits: `sgit status` reports them, `sgit commit` records them in the vault's history, `sgit push` seals them to the server. Two provenance trails, both kept: git records who proposed and reviewed a change; sgit records it landing in the encrypted vault.

### Before first publication: audit, then keep the discipline

- **Run the leak audit from the vault root** before the first `git add`: the vault-key secret must not appear in the working tree, no `BEGIN PRIVATE KEY` outside `local/`, and `bare/` must contain no greppable filenames or content. (The vault serving this site passed all checks before its dotfiles shipped.)
- **Write the protection files before the first `git add -A`** — once `local/` is in a commit it is in history, and removing it later means a history rewrite plus key rotation.
- **For CI**, the vault key goes in GitHub Actions Secrets (and a password manager) — never in files, commit messages, issues or workflow YAML.
- **Disaster recovery comes free:** a git clone of the repo plus the key reconstitutes everything — content, sgit history, all branches — even if the sync server is gone. Do one restore drill before you need it in anger.

The vault serving this site ships the full `.gitignore` / `.gitattributes` pair — clone it for a working example. And once the vault is on GitHub, the same repo can serve the app itself: see [static hosting on GitHub Pages](static-hosting.md).

### What a key rotation does to the mirror

Rotating a vault key (`delete-on-remote` → `rekey` → `push`) re-encrypts every object under a new key, so every content-addressed ID changes and the entire store is replaced. In the git mirror that lands as one large commit — for this site, 336 objects deleted and a fresh set added. Nothing breaks (the `.gitattributes` binary rule means no diff churn), but two consequences are worth knowing before you rotate:

- **Git becomes the history.** A rekey resets the vault's own commit history to a single commit. The git mirror still holds every previous version — which is the side-by-side pattern earning its keep: each remote covers the other's gap.
- **A rekey protects the server, not the mirror.** Old ciphertext already pushed to git stays in git history, and remains decryptable by the old key. If that key was ever exposed *and* the repo is public, rotating does not un-publish the old content — for public content (like this site) that is a non-issue, but for a private vault, treat a rotation as incomplete until the mirror's history is scrubbed too. Rotate first, then decide about history.

This section exists because it happened here: the passphrase for this site's own vault was written into a tracked build file (an anti-leak regex that became the leak), reached three public commits, and was caught by the audit above. The key was rotated the same hour and the old vault deleted from the server; the exposed content was this public website. Recorded rather than quietly fixed — see the [release history](../admin/versions.md).

## Status — honestly

- The reader is **in review, not shipped**. It is read-only, follows first parents (no merge traversal), and skips submodules and shallow clones by design.
- Review has already produced fixes: two schemas needed the project's own default-value convention applied, and the string-sanitization rules need loosening so file paths and commit messages round-trip byte-faithfully before this ships.
- When it lands, it lands the way everything here does: typed, tested against real repositories, and documented on this page.

[← Sub-vaults](sub-vaults.md)[Static hosting →](static-hosting.md)



==============================================================================
# Static hosting on GitHub Pages — SG/Vault

> Serve an encrypted vault and its app from GitHub Pages or S3 with zero backend: deterministic GET paths, client-side decryption, clean read-only degradation.
>
> Page: https://sgit.ai/vault/static-hosting.html

[Home](../index.md) / [SG/Vault](index.md) / Static hosting

# Static hosting — GitHub Pages / S3

The same vault-app HTML runs against the live API **or** a 100% static file host, transparently. The app only talks to `window.sg`; static vs live is a property of the transport, not the app. Shipped, opt-in, default-off.

## Why it works

Everything needed to open and browse a vault is a plain GET to a deterministic path: file IDs (commits, trees, refs, indexes) are content hashes or HMACs of the key, computed client-side — **no discovery or listing call exists**. So a static host that serves those exact paths just works: the browser GETs ciphertext from GitHub Pages or S3 and decrypts locally. No backend, no server, still zero-knowledge — the bytes on the CDN are ciphertext.

```
<!-- on the hosting page, before the host boots -->
<script>
  window.SG_STATIC   = true;                    // batch reads → GETs; writes → EREADONLY
  window.SG_ENDPOINT = 'https://my-org.github.io/my-vault';
</script>
```

## What works statically — and what doesn't

| Call | Static? |
|---|---|
| Open, browse, read files, history — `sg.vfs.read/readText/list` | ✅ plain GETs |
| Large reads | ✅ falls back from presigned to direct GET |
| Batch reads | ✅ fan out to parallel GETs, identical result shape |
| Writes, deletes, `sg.append.*`, vault creation | ❌ rejected cleanly with `EREADONLY` |

A static vault is a **read-only snapshot** — ideal for published docs, reports, dashboards and view-only shares. The app detects it via `sg.app.writable === false` and hides its editing UI; the same HTML runs writable against the live endpoint. *Same app, two backends.*

## The layout — path mirroring is the one hard requirement

The live API serves `GET /api/vault/read/<vaultId>/<filePath>`; the static host must serve the vault's encrypted `bare/` tree at exactly that path under your base:

```
<repo root>/                    → https://my-org.github.io/my-vault/
└── api/vault/read/<vaultId>/
    └── bare/
        ├── data/      obj-cas-imm-*    # immutable — cache forever
        ├── refs/      ref-pid-muw-*    # mutable head — no-store
        ├── indexes/   idx-pid-muw-*
        └── keys/      key-rnd-imm-*
```

If the repo is your vault's own git remote (working tree + `bare/` committed per the [side-by-side pattern](git-and-vaults.md)), the encrypted tree is already in the repo — publishing is just placing it under the right path prefix. Visitors open `https://…/my-vault/#<key>`: the key travels in the URL fragment (never sent to the host), the transport GETs ciphertext, the browser decrypts and renders.

## Honest caveats

- **Read-only and frozen.** The static tree is a snapshot at export time; new live commits appear only when you re-export.
- **Paths must match exactly**, or reads 404. (A configurable read-path template is a proposed follow-on, not shipped.)
- **Cross-origin setups need CORS** on the static host for GETs; same-origin needs nothing.
- **The key is the read capability.** Anyone with the full URL can read the snapshot — that is the point of publishing one — but the host itself only ever holds ciphertext.

[← Git repos inside vaults](git-and-vaults.md)



==============================================================================
# Admin & engineering — sgit.ai

> How the sgit.ai site is built: a vault app with generated pages, bridge-loaded assets, a validation suite, and sgit itself as the deployment pipeline.
>
> Page: https://sgit.ai/admin/index.html

[Home](../index.md) / Admin

# Admin & engineering

How this site is built, shipped, and versioned. sgit.ai is not hosted on a web server — it is a **vault app**: a set of HTML pages living inside an encrypted SG/Send vault, decrypted and rendered in your browser. The site about sgit is delivered by sgit.

## Architecture

```
# published site — one folder per section; root holds only what must live there
├── index.html · index.md                     # the front door + its markdown twin
├── CNAME · app.json · robots.txt · sitemap.xml
├── llms.txt · llms-full.txt                  # machine index; every page in one file
├── why/ · try/ · security/ · skills/ · briefs/
├── use-cases/       # patterns, each with an evidence status + agent brief
├── case-studies/    # things that actually happened, with numbers
├── docs/ · vault/ · deploy/
├── assets/          # site.css, site.js, vault-docs.js, try-setup.py
└── admin/
    ├── content/     # page bodies — one file per page, plus pages.json
    └── build/       # build_pages.py (the engine) + validate.js
```

## Adding a page

Content and machinery are separate, so nothing in the generator grows as the site does — it was 2,709 lines with every page inlined, and is 648 now that bodies live in `admin/content/`. A new page is a file and a row:

```
# 1. write the body — just the <main>, no head, no nav, no footer
$ vim admin/content/case-studies/my-study.html
# 2. register it: { "path", "section", "title", "desc" }
$ vim admin/content/pages.json
# 3. build and check
$ python3 admin/build/build_pages.py && node admin/build/validate.js
```

The build then produces, for free: the page with nav and footer, its `.md` twin with links rewritten to markdown, its row in `llms.txt`, its section in `llms-full.txt`, its entry in `sitemap.xml`, and its canonical, Open Graph and JSON-LD tags. The validator refuses the build if the page is unreachable from anywhere, if a link or a markdown twin is missing, if it carries no structured data, or if it could render invisible without JavaScript.

- **The authoring contract.** Vault pages render inside a sandboxed frame, so declarative references to vault files (`<link>`, `<script src>`, `<img src>`) would 404 before the vault bridge installs. Every page therefore carries only a tiny critical-style block plus a ~20-line bootstrap.
- **Shared assets over the bridge.** The bootstrap waits for the `window.sg` bridge and loads `assets/site.css` / `assets/site.js` through it — trying `sg.loadCss`/`sg.loadJs` first, then `sg.vfs.readText` + inject, then plain `fetch` as a static-hosting fallback. Worst case, pages degrade to readable unstyled HTML.
- **Multi-page navigation.** Plain relative `<a href>` links between pages — the vault host intercepts clicks and routes them, giving normal browser-style navigation (back/forward/history come from the host chrome).
- **Read-only by design.** The app requests no write permissions in `app.json`; reads need no grant. Nothing on this site can modify the vault.

## Build system

Every page is generated from a single Python script holding one shared template (nav, footer, bootstrap, version stamp) plus per-page content. Nothing is hand-edited twice: change the template once, regenerate, and every page updates consistently — including the version badge you can see in the nav.

## Validation before every push

- Every inline script and `site.js` is parse-checked with Node.
- A contract scan proves no `<link href>`, `<script src>`, or `<img src>` references a vault path.
- Every internal link is resolved against the real file tree — broken links fail the build.
- A banned-words scan keeps retired concepts and legacy naming out of the content.

## Release process

```
# 1. bump SITE_VERSION (v0.1.n — n increases on every push) + add a versions row
# 2. regenerate + validate
$ python3 admin/build/build_pages.py && node admin/build/validate.js
# 3. ship to the vault — the encrypted deployment
$ sgit commit -m "site vX.Y.Z: …" && sgit push
# 4. ship to git — same folder, second remote; GitHub Pages deploys from it
$ git add -A && git commit -m "site vX.Y.Z" && git push origin dev
```

One folder, one source of truth, two remotes: the same working tree is an sgit vault *and* a git repository (`SGit-AI/SGit-AI__Website`). Every release pushes both — sgit carries the encrypted history; git carries the public mirror and triggers the GitHub Pages deployment. A release isn't done until both remotes report in sync. See [release history](versions.md).

## Design & contributions

A standing brief for Claude Code sessions proposing design improvements lives at [admin/brief-design-improvements.md](brief-design-improvements.md) — it carries the constraints (authoring contract, self-contained assets, validation suite, version bump) that any change must respect.

[← Home](../index.md)[Release history →](versions.md)



==============================================================================
# Release history — sgit.ai

> Every release of the sgit.ai site: version, date, vault commit, and changes. The version increments on every push.
>
> Page: https://sgit.ai/admin/versions.html

[Home](../index.md) / [Admin](index.md) / Versions

# Release history

This site ships by pushing its vault, and the site version — **v0.2.38**, shown in the nav of every page — increments on every push. Each release is also an sgit commit, so the vault's own `sgit history log` is the authoritative audit trail; this page is the human-readable index of it.

| Version | Date | Vault commit | Changes |
|---|---|---|---|
| v0.2.38 | 2026-08-20 | this release | Third site in the network: SG-SENTINEL.SGIT.AI, a design for an app-coupled edge guard replacing rented AWS WAF + CloudWatch/Firehose with a layer you own. Its central inversion is that a generic WAF is blind to the app it protects and must denylist, whereas an edge that knows the valid request space can ALLOWLIST — no invalid request reaches the origin. Two things make it worth a page rather than a link. First, a governing correction stated as a constraint: 'Layer 1 never acts and never writes — it only decides and signals; Layer 2 is the sole actor and the sole I/O owner', because a CloudFront Function physically has no network and no filesystem — and the site names its own earlier design, where L1 blocked inline, as a category error. Second, rules are the engine rather than configuration on it: six deterministic rules, each a pure function mapped to an ATT&CK technique, run first-block-wins, with a prototype exercise running the same engine across three targets under a parity matrix asserting identical decisions. It also carries the most honest status language on the network — the pill reads NOT BUILT, and where the prototype's 149 passing tests are cited the site immediately bounds them as 'not deployed anywhere, not in production use, not maintained, not packaged for you to install'. Adding it cost one markdown file and three screenshots, which is what the content type was built for. One engine gap surfaced doing it: the markdown renderer had no TABLE support, so the six-rule core rendered as a paragraph of vertical bars. Pipe tables now parse — header, separator, body — and emit into the site's own .tablewrap, so they scroll on a phone and survive print like every other table here. Caught by looking at the output rather than trusting the validator, which had nothing to object to: badly rendered markdown is still valid HTML. |
| v0.2.37 | 2026-08-20 | obj-cas-imm-1b229ee71709 | REGULATION GRAPH — the EU AI Act as a citable graph, and the first vault here whose publication the audit STOPPED rather than cleared. Regulation (EU) 2024/1689 parsed from official Formex XML retrieved from CELLAR, hash-verified to the source bytes: 113 articles, 500 paragraphs, 180 recitals, 68 definitions, resolving to 1,523 nodes and 1,944 edges across eleven views — browse, Cytoscape citation graph, in-browser SQLite over sql.js, RDF via rdflib, concepts, external instruments, and an experimental Art 9 lab as the declared entry point. WHAT HAPPENED: the submitted credential was a VAULT KEY, not a read key — the fourth time, caught by the intake check. The read key was derived and the audit run with it across 204 text files, which is when it found a LIVE VAULT KEY IN PLAINTEXT inside a handoff document, granting write access to a DIFFERENT vault. Publishing our read key would have handed that away. No page was written; the finding was reported first. Deleting the file would not have been enough, because vault objects are content-addressed and immutable, so a credential committed once may stay reachable from history — the only clean remedy is history that never held it. So this is a REDACTED REPUBLICATION into a new vault: same 206 files, two credentials replaced in place with visible and markers rather than silent deletions, a PUBLIC.md stating the rules and the removals, and a re-audit from a fresh read-key clone: 205 files, zero findings. The second removal was a judgement call — a read key is publishable by its OWNER, and that one belonged to a third vault, so it goes and the decision stays with a human. RULE 3 VERIFIED RATHER THAN ASSUMED: the Graph REPL is an LLM chat, and repl.js looks for an OpenRouter key at /key.json INSIDE THE VAULT before falling back to device storage, so a shipped key would be an open tab on somebody else's budget. No key.json exists, confirmed in the read-key clone rather than in our working copy. The 370-plus bare 64-hex strings the scan flagged were all sha256 provenance hashes, checked individually — a scan that never produces a false positive is not scanning hard enough. The rule that caught all of this came from Risk Graph Explorer's own PUBLIC.md, not from us; it has now paid for itself. |
| v0.2.36 | 2026-08-19 | obj-cas-imm-18bcdab6db5d | A NETWORK section for the sibling *.sgit.ai sites, built as a content type rather than as two pages, because many more are coming. nhi.sgit.ai argues that 'how do I give my agents an identity' splits into agents you RUN and agents you RENT, and that the industry answers only the first — SPIFFE for workloads you can attest, an open feature request for the agents anyone actually names. pki.sgit.ai designs a key registry from the 2019 keyserver failure and publishes four rules BEFORE the registry exists, reaching a resolution worth borrowing: append-only is safe when a writer appends only to objects it owns and fatal when anyone may append to somebody else's, so the rule to carry is not 'append-only' but 'the writer owns what it writes' — which is append lanes, already shipped. Six screenshots captured from the live sites through the curl mirror the sandbox needs, since Chromium cannot egress here. Adding the next site is ONE markdown file plus its screenshots: the index, the cards and the per-site page are derived, same contract as updates and articles. Two engine fixes fell out of building it. The generator now WIRES THE SCREENSHOT COMPONENT AUTOMATICALLY for any page containing figures — a markdown author has no place to put a script tag, and the views page had already shipped once with figures and no loader, which errors nowhere and simply shows nothing. The first version of that check matched on 'figure class="shot"' and missed 'class="shot net-shot"', leaving the new index in exactly the state the check existed to prevent; it now matches on data-shot=, the attribute the component actually selects on. Detect on what the consumer looks for, not on how it happened to be written. |
| v0.2.35 | 2026-08-19 | obj-cas-imm-1f3ce8d32a28 | Two new sections and the navigation restructure they forced. UPDATES and ARTICLES, both built on the VoiceDebrief journalist pipeline's central rule, which was worth adopting verbatim: PUBLISHING IS ADDING ONE FILE. No index to update, no manifest to hand-edit, no decision about where a post goes — ordering, permalinks, updates.json and feed.xml are all derived. That is not tidiness, it is the property that makes an unattended journalist agent safe: two agents publishing on the same day touch two different files and cannot conflict. Frontmatter is flat key: value with no YAML parser, the folder path must agree with the date, and slugs must be unique or the build fails. ONE DELIBERATE DIVERGENCE from their contract: they author root-relative links because their site sits at a domain root; ours must also render INSIDE A VAULT at an arbitrary mount path, where a leading slash escapes the app — so posts are still authored root-relative and the build rewrites each to a depth-relative path. Authors keep the simple rule; the vault still works. Updates are one entry per STORY rather than per release, which is the whole reason this is not the version log with a nicer stylesheet — v0.2.31 alone carried three separate stories. Five seeded from recent releases; the version log stays the complete technical record behind them. Articles carry two anti-rot rules stated on the page: never restate a fact you do not own (link to the page that does, so it cannot start lying when the fact changes), and link the test behind any testable claim. Two to open: GREEN DOES NOT MEAN LIVE on the deploy that reported success twice while serving a two-release-old page, and SEVEN VAULTS, ONE METHOD on what publishing seven vaults taught — including the three vault keys submitted as read keys. NAVIGATION: 14 flat items became 7 groups with a second level. The old bar wrapped to THREE ROWS on an iPhone before the page began — measured on a real screenshot, not guessed. Every group label is itself a link to that section's index, so nothing is reachable only by opening a menu. Desktop opens on hover and :focus-within in CSS alone; the phone collapses behind one button. The first mobile attempt made every submenu inline and measured 498px of navigation before the content — worse than what it replaced — so it was rebuilt as a collapsed menu: 91px, against 54px on desktop. Also adds an RSS feed and a JSON manifest, the first machine surfaces here aimed at a human follower rather than an agent. |
| v0.2.34 | 2026-08-18 | obj-cas-imm-97c957112852 | Acts on an inbound fix pack from the SG/API team, who audited this site against their route tables at v0.33.54 after an agent asked how to send a message between vaults and could not find the answer here. Their central finding was right: the site documented the TRANSPORT (sg.append) and the CRYPTO (sgit pki) on pages that never referenced each other, and never wrote the sentence saying they compose into vault-to-vault messaging. There was also no HTTP API reference anywhere, which is awkward for a project whose argument is that the API is the whole surface. SEVEN NEW PAGES: /docs/vault-messaging (the keystone — append lanes composed with PKI, worked end to end in CLI, curl and sg.append), /docs/pki (keypair lifecycle), and a /api/ section: index, authentication, vault-objects, append-lanes, errors. The security page gains the asymmetric layer it never had; sg.append is retitled as the message transport and cross-linked; limitations gains what PKI does NOT do; the skills page flags that the shipped agent skill still has both halves and no join. THREE OF THE PACK'S FINDINGS DID NOT SURVIVE CHECKING, which is the part worth recording. (1) It reported that the security page 'actively denies PKI'. It did not — a sweep for symmetric, asymmetric, public key, PKI and keypair returned zero occurrences. The page was SILENT, not wrong; publishing a correction for a claim we never made would have put a false statement in this log. (2) It asked us to hunt stale 'inbox' naming; there is none — two hits, both ordinary English, and no /api/vault/inbox/* path anywhere. (3) It described X25519 sealing throughout. Running sgit pki keygen on v0.15.0 prints RSA-OAEP 4096 and ECDSA P-256. Publishing the draft as written would have told integrators to build against the wrong primitive. Two further corrections came from running the CLI rather than reading about it: export emits a JSON BUNDLE of two PEM blocks, not a .pem file, so the draft's sha256sum-the-pem derivation of the lane address is not well defined; and keygen requires a passphrase, which no draft step mentioned. The one genuinely unshipped step — append_token = H(public key) — is labelled PROPOSED with an interim recipe rather than quietly documented as working, and the two endpoints their audit could not resolve (/api/vault/zip, /join/*) are listed as unresolved rather than described. The pack's own acceptance test — give a fresh agent only llms.txt and ask how to send an encrypted message from vault A to vault B — now passes, including the lane-address fact and its PROPOSED caveat, answered in the preamble so it survives an agent that cannot follow a link. |
| v0.2.33 | 2026-08-17 | obj-cas-imm-ab458fd8611d | A release now ends by asking the live site what version it is serving, because 'both remotes in sync' turned out not to mean 'published'. v0.2.31 and v0.2.32 both pushed cleanly, both reported success, and NEITHER reached sgit.ai: GitHub Pages failed to deploy them because codeload returned 429 (Too Many Requests) for actions/configure-pages@v5, and the deploy job died in 'Set up job' before running a single step. Validation passed, tagging passed, the push was verified against both remotes — and the site served a two-release-old page for forty minutes, which is how long it took a human on a phone to notice the version pill still said v0.2.30. The failure was invisible to every check the release ran, because it happened in a job neither remote knows about. So release.sh gained a sixth step: poll the live URL with a cache-buster until the version pill matches this release, up to eight minutes, and ABORT LOUDLY if it does not — naming the Actions page and the fact that a 429 on the action download is transient and just needs a re-run. The cost is up to eight minutes of waiting per release. The alternative, demonstrated twice in one afternoon, is telling somebody a fix is live when it is not. Same principle as the orphan-page rule and the llms.txt guard: a page nothing links to, a page the index omits, and a page the deploy never published are all equally unpublished, so the build refuses all three. Ships the content of v0.2.31 and v0.2.32, which had been written but never served. |
| v0.2.32 | 2026-08-17 | obj-cas-imm-7f84b9ee6727 | The walkthroughs page becomes a document rather than a list of links. Each of the three videos now carries the recording at the top and THE SAME SESSION READ BACK underneath it: fifteen moments, each one a timestamp that deep-links into the video, the frame the screen was showing at that moment, and an explanation of what is happening in it. The transcripts are still there, folded away at the foot of each. The reason for the format is the one thing a transcript structurally cannot do: these recordings are full of 'this guy here' and 'look at this', and the words alone name neither end of what is being pointed at. Pairing each phrase with its frame is what makes the argument survive being read instead of watched. TWO SOURCES OF FRAMES, and the page says which is which. The Graph Browser moments are frames of the recording, from a narrated-review export the author produced with tools.sgraph.ai — nine timestamped stills paired with the narration spoken over each. Risk Chains and Role risk map have no such export, so their six frames were captured from the LIVE VAULT with the published read key, driven to the exact state being described — including the entry he names out loud ('you have risk 6'). What the frames turned up is most of the value, because none of it is audible: negative answers produce NAMED EDGES (never-exercised-on, never-timed-for, absent-for) rather than silence; 'no egress' draws a single assurance-coloured edge in a field of amber, so a good answer is a finding rather than the absence of one; one selection can carry two fact ids; and every risk ships with a CEASES WHEN ANY OF THESE HOLD list — its own falsification condition, cited to facts. The role dashboard also separates three arrival routes where the video describes two: held, arrives by the risk chain, and arrives by the org chart. TOOLING: the capture rig gained appProbe (ask the running app what its elements are called instead of guessing and burning a capture run per guess — it found g.cnode for chain entries and g.role for roles) and appClickMatch (substring match plus a real MouseEvent, because the graph nodes are SVG). Videos print with the player hidden and the moments intact. |
| v0.2.31 | 2026-08-17 | obj-cas-imm-17f0b2693daf | Corrects v0.2.30 on three counts, two of them reported and one of them the reason the report was possible at all. (1) THE LAZY-LOAD BYPASS IS NOW ONLY ON PRINT. v0.2.30 prefetched every screenshot once the page went idle, which fixed printing by making every reader pay for images they never scrolled to — the wrong trade, and correctly rejected. It is now driven entirely by the print itself, and it works because of a change one layer down: on the ordinary web the loader no longer fetches bytes and builds a blob: URL, it just sets img.src. That makes each screenshot an ordinary pending document resource, which the print pipeline knows to wait for, where a fetch-and-blob is invisible to it. Cmd/Ctrl-P is caught on keydown as well as beforeprint, because the keystroke lands a few hundred milliseconds before the dialog does and that head start is what removes the race. Measured on a page that was never scrolled: 1 image loaded while reading, 9 of 9 in the PDF. The blob path remains for pages served from inside a vault, where it is the only option. (2) THE PRINT-ONLY SOURCE LINE AND LANDSCAPE HINT ARE GONE — printing these pages is an uncommon case and did not warrant instructions on the page. (3) ASSETS ARE NOW CACHE-BUSTED PER RELEASE. GitHub Pages serves them with max-age=600, and the bootstrap fetched them by bare path, so for ten minutes after every release a returning reader ran the NEW html against the OLD css and js. That is not a hypothetical: it is exactly what produced the v0.2.30 bug report — new markup whose print-only elements the cached stylesheet did not know to hide, and a cached loader without the print handler. Every fetched asset now carries ?v=; the in-vault sg.vfs path stays unversioned, since a vault lookup is by path, not URL. |
| v0.2.30 | 2026-08-17 | obj-cas-imm-81dc22613ddf | Print and save-as-PDF, prompted by an export of the seven views page that came out wrong. TWO DEFECTS, one reported and one found while looking at it. (1) The top nav is position:sticky; Chrome paints a sticky box ONCE, wherever it happens to fall in the paginated flow, so the whole nav landed across the middle of page 2 — translucent, with the prose showing through it. It is static in print now and flows once, at the top of page 1, as a masthead with the link list dropped. (2) WORSE, AND NOT REPORTED: screenshots are lazy — a figure starts at opacity:0 and its img is only created when an IntersectionObserver fires — so printing a page without first scrolling to the foot of it exported blank gaps where the pictures should be. Nothing errored; the img simply never existed. beforeprint cannot fix that alone (it is synchronous and will not wait for a fetch and decode), so the figures are now prefetched once the page goes idle, with beforeprint kept as the backstop. The export that prompted this was only correct by luck: it was taken after reading the whole page. Beyond the fixes: @page margins so Chrome's Default is ours rather than its own; print-color-adjust:exact, because on this site the tints carry meaning (amber exposure, green assurance) and Chrome drops backgrounds unless asked; break-inside:avoid on walkthrough rows, figures, notes, tables and transcripts, which fixes captions stranded on the page after their picture; orphan/widow control; live vault embeds hidden and labelled rather than exported as empty boxes; and a print-only source line carrying the canonical URL, since Chrome's own header and footer are frequently switched off. Finally, any page containing walkthrough rows now asks for LANDSCAPE — in portrait the two-column grid falls below the 820px breakpoint and collapses, which loses the alternating left-right rhythm that is the entire design of those pages. The reader can still override it. None of this was tested before; all of it is now. |
| v0.2.29 | 2026-08-17 | obj-cas-imm-8a68f249bd9f | The first vault to get depth rather than a page. Risk Graph Explorer now has three: the overview, THE SEVEN VIEWS EXPLAINED, and THE AUTHOR'S WALKTHROUGHS. The views page captures each of the seven tabs from the live vault under the Exposed preset — the estate, context, role risk map, risk chains, the register, acceptance, what happens next — and explains the mechanism behind each, matched to how the author describes it in his own recorded demos. Highlights the screenshots alone would not carry: 'assigned' versus 'through' on the role map (what you personally hold, versus what arrives because the graph says it must), so that no risk is orphaned and every path terminates at the board; risk chains running inherent-to-corporate left to right, clickable in both directions ('leads to' navigates up, 'led by' walks back to the answers that caused it), with cycles drawn as dashed edges because the cycles are real; and acceptance as the place where the register stops being a document — with the author on camera disagreeing with his own tool, which resolves into WHICH FACT IS WRONG rather than whose judgement wins. Also captures the same organisation under the Typical and Governed presets, because that comparison is the whole argument: the org chart does not change, only what is true about the agent. The walkthroughs page carries all three videos with FULL TRANSCRIPTS — a video is invisible to a search engine, to llms-full.txt and to any agent reading this site as documentation, so the transcript is the content and the video is one rendering of it. Tooling: the shots component gained a data-dir override so deeper pages under a vault share ONE image folder; the site now runs to 53 pages. Three bugs caught by testing rather than assumption — a malformed selector expression that silently created no images at all, escape sequences leaking as literal text, and a page that never loaded the component it depended on. |
| v0.2.28 | 2026-08-17 | obj-cas-imm-6008b0bdfe27 | Seventh vault, and the method written down. RISK GRAPH EXPLORER (3simlnqe) is the fact-to-risk explorer extracted out of the risk-mandate work into a vault of its own — answer questions on the left, seven views recompute on the right, nothing leaves the page. Its argument is visible in two screenshots: empty at 0 facts / 0 risks, then 18 / 37 / 14 under the Exposed preset, because a register that produces the same output for a scratch service and a payments platform is a checklist, not a register. Unanswered relationships are drawn as ghosts — recording absence as information rather than as an implicit pass. It is the first vault here PUBLIC BY DESIGN: it carries its own PUBLIC.md whose three rules its build enforces — nothing private committed (the gate scans every file, not just the artefact), no write token, and NO METERED CAPABILITY, because a published read key in front of an LLM config is an open tab on somebody else's budget. That third rule is not in our guidance and is the one to adopt. It also sent us back to re-audit ourselves: risk-mandate does carry an LLM config, so we took its sealed credential and attempted to open it with the read key we had published — AES-GCM refused (InvalidTag), so no budget was exposed; the rule is satisfied there by sealing and here, more conservatively, by absence. Checked rather than assumed, and recorded either way. Its app.json is `permissions: {}` — the floor of a scale the catalogue now spans end to end. Zero audit findings, the cleanest yet. NEW PAGE: /demos/vaults/publishing.html — the seven steps behind every vault published here, written to be followed by another site's agent: classify the credential before it touches anything, derive rather than refuse, audit with the read key across every file, derive the facts, capture evidence by driving the real product, write the page (describe, show, then admit), and record what outlives it. It names the five tools and, more usefully, the five mistakes that produced each rule. |
| v0.2.27 | 2026-08-17 | obj-cas-imm-6f1decd85ad3 | Sixth vault: AGENTIC BROWSER ISOLATION (0610gsp9) — a living risk graph for one decision, does an AI agent browse inside the user's browser with their logged-in sessions, or inside an isolated browser with a scoped identity of its own. It is this site's own ambient-authority argument made by somebody else and in much more detail, so it is linked from the AI-agents use case. Seventeen app entry points, the most in the catalogue: a numbered narrative spine, one page per stakeholder altitude (IT · CISO · DPO · CFO · COO · CEO · Board), an explorer, two graph views and the raw data, over ~70 JSON files with RDF tooling vendored in so graph exploration works offline. The mechanism is the part worth copying: every altitude has one named owner, a risk stays PENDING until that owner accepts it personally, only an accepted risk escalates, and there is no deny button — the screenshots show IT holding five pending while every altitude above reads 'waiting', because nothing has been passed up. Its app.json declares fs.write: [] — an app that requests no write capability at all, which with supplement-stack (one folder) and risk-mandate (LLM use without the key) gives the catalogue three distinct points on the permissions scale, each declared in the vault rather than configured on a server. The intake check earned its keep on arrival: the submitted credential was again a vault key, refused for publication by shape, and only the one-way derivation published. Audit clean across 104 files — the six scanner hits were all digit runs inside a minified RDF library matching a phone-number pattern, recorded because ruling hits out by reading them is what an audit actually is. Also: upgraded the CLI to v0.15.0 (latest) specifically to re-test the prefix gap; it still derives the wrong ref from the canonical read-key prefix while the bare form clones correctly on the same binary, so the brief now says 'confirmed on latest' rather than 'may be a stale install' — and the machine-verified check updated its own evidence from v0.14.27 to v0.15.0 with nobody editing the claim. |
| v0.2.26 | 2026-08-17 | obj-cas-imm-6958c20644d8 | Credential intake becomes a check rather than a habit, prompted by yesterday's near-miss: a vault key was submitted for publication described as a read key, caught by shape, and only its derived read key published. The catch depended on somebody looking. New admin/build/check_credential.py classifies a credential BEFORE it touches a page, a catalogue entry or a commit — exit 0 means read-only and publishable, exit 1 means a write credential and stop. It works two ways because the problem has two eras: by PREFIX for vaults new enough to emit one (the canonical write prefix, which is exactly the change being rolled out, and the reason it is worth rolling out), and by SHAPE for everything older, where a read key is 64 hex characters and anything else before the colon is a passphrase. Verified against all eight real forms we have handled, including the actual key from yesterday, which it refuses with no prefix to help it. If a submission IS a vault key the entry is not blocked — the documented one-way derivation is printed instead. The rule is now in the catalogue vault's SCHEMA, so it renders on /catalogue/ with no site deploy, and summarised on the vaults index. Also: the release tripwire got more precise rather than more strict. Banning the bare write prefix outright had caught its own author three times, each time writing it in prose — and guidance that cannot show a reader what a write credential looks like cannot teach them to spot one. It now fires on the prefix followed by a CREDENTIAL character, so documentation may name it while every real key still fails the build; the bare passphrase:vault_id shape catches the body independently. Both directions proven before shipping (\S was tried first and failed, because in documentation the prefix is followed by markup). |
| v0.2.25 | 2026-08-17 | obj-cas-imm-8b39926aadb1 | Risk Mandate joins the catalogue — the most complete project ever published here, and the first to demonstrate CAPABILITY WITHOUT CREDENTIAL. It is a Black Hat field demo (hand someone an iPad, answer eight questions, a risk register assembles) built AS a vault app: 124 files, 98 commits, eight entry points, a test suite, build tooling, releases pinned to commit ids and offered as a live selector in the app chrome, and offline operation after one cached load. Its app.json grants llm:chat/models/usage/listen and fs.write over field/workspace/ and nothing else — while the OpenRouter credential itself is SEALED under the vault key in .vault/llm/config.json, so the host decrypts and calls and the app frame is handed results, never a secret. Auditing with the published read key, that field is ciphertext we cannot open, which is the claim demonstrating itself. The /compare/ privilege vocabulary gains the shape this revealed: ops and bearer come apart, so ops:llm-chat can be granted while bearer of the key is withheld — something most sharing models cannot express, because handing over the capability and handing over the credential are the same act. IMPORTANT PROCESS NOTE: the credential submitted for this vault was a VAULT KEY (format 3, passphrase:vault_id), not a read key — it matched this site's own banned-shape tripwire exactly. It was not published. It was stored in the gitignored local tier and the read key was derived from it one-way via the library's own Vault__Crypto.derive_read_key; only that derivation appears on the site, in the catalogue, and in the capture rig. The independent audit across all 124 files was clean, with two findings of the good kind recorded publicly: the sealed LLM key, and a single secret-scanner hit that turned out to be a deliberately fake sk-test- key inside a test asserting that a reachable API key IS caught. |
| v0.2.24 | 2026-08-17 | obj-cas-imm-244c5ecdeecf | Comparisons, built as reproducible tests rather than as claims — the concrete proposal answering the 16 Aug comparison brief. New /compare/ section carrying (1) the entry format: task, steps, prerequisites, privileges granted, where it runs, survives-the-vendor, verified date, and how to re-run; (2) a PRIVILEGE VOCABULARY, which is the part most likely to be argued with and the reason it is published first — seven properties that make two grants comparable (scope, operations, bearer, mediation, duration, withdrawal, observability), under which a published read key reads scope:vault · ops:read · bearer:any-holder · mediation:key · duration:forever · withdrawal:future-only · observability:none, three of them WORSE than a mainstream sharing link; (3) three worked entries — printing a markdown file (small, checkable in a minute, we win), taking access back after sharing (WE LOSE, plainly: rotation protects future commits and reaches nothing already fetched, while a server-mediated platform simply refuses the next request), and letting a program record data without letting it alter records (the differentiator, where step counts tie and privileges separate). Behind it: admin/build/compare_tests.py executes the our-side claims against the live service with published read keys only, and writes compare/results.json — six checks, each stating what would make it FAIL. Five hold; one records an ABSENT capability and is kept until it stops reproducing: the installed CLI v0.14.27 does not strip the canonical sgit_rk1_ prefix the web loader now accepts, deriving the wrong ref id, while the bare form works on the same version — now also filed as a brief to the CLI team. The freshness mechanism is real rather than a date in small print: results carry an expiry threshold and a past-threshold result renders as UNVERIFIED instead of as fact, proven by forcing the dates old and watching all six rows flip. The page states its own asymmetry up front — our rows are machine-verified, rows about anyone else's product are hand-checked on a date — and lists what is deliberately absent, including the deployment comparison, which waits until our own portable-artefact/hosted-viewer caveat is resolved. |
| v0.2.23 | 2026-08-16 | obj-cas-imm-8af209891454 | Structure for scale, and the most interesting vault yet. (1) Every published vault is now a self-contained folder — demos/vaults//index.html with its screenshots in demos/vaults//images/ — so adding the hundredth vault is adding a folder, and a vault's page and pictures move together. The old flat /vaults/ section is gone (URLs lived one day). Two engine changes made it possible: the root-prefix was computed as 'one ../ if nested at all', which silently pointed the nav, stylesheet and every asset at the wrong level once pages nested three deep — now it is ../ times the depth, the same formula the markdown twins already used; and the screenshot rig writes per-vault, with a --vault filter. Image paths in the walkthrough are page-relative for the same reason. (2) New vault: SUPPLEMENT STACK (r7zes477), and it is the strongest healthcare demonstration on the site. Its idea: every label describes one product, nothing describes the sum, so the model extracts (fuzzy, with every amount traceable to the label photograph it was read from) and the code adds up (deterministic, rules stated in the open, a missing value flagged and never guessed), producing a briefing for somebody qualified and never a verdict. It is also the first vault here to use SCOPED WRITE PERMISSIONS: app.json grants write over adherence/ only, so the app that logs what was taken cannot alter the regimen, the labels or the references — least authority as a property of the vault rather than a server setting. Five walkthrough rows captured from the live vault, including its app.json permission block. The healthcare use case now opens with this as a worked example: who holds the data, how it reaches a clinician (a read key, not an account or a PDF), where AI fits safely, and why the reference set is UK RNI/EFSA rather than US Daily Values. The published audit: clean on credentials, no personal identifiers found — but it publishes a real regimen and the health context inferable from it, deliberately, and revocation is not retroactive. |
| v0.2.22 | 2026-08-16 | obj-cas-imm-b1d27e3295cf | The walkthrough: six alternating rows at the foot of the Algarve page that explain what a live embed cannot say for itself — the app is real HTML (not a viewer template); clicking a photo opens the vault's own lightbox with captions from gallery.json; the debug pane's Vault tab times the decryption step by step; its REPL tab is a console over the sg.* bridge where vfs.write is refused because no write capability exists in a read key; the vault browser shows photos/originals and the app's own SOURCE; and the SGit tab carries 36 commits, because the history IS the storage. New tool behind it: admin/build/capture_shots.mjs drives the real product with only a published read key, performs each row's navigation (scroll to a chapter, click a photograph, open the debug pane through the HUD's shadow root, type vfs.list into the REPL, expand a folder, switch to the SGit view), crops the result and writes WebP — so the pictures are of the actual vault and regenerate when it changes. Getting there needed four fixes worth recording: the app frame must be identified by a selector it contains (the shell frame also has text and was winning the race), the REPL input sits two shadow roots deep and is reached with a shadow-piercing locator typed into for real, the file tree rows are .sb-tree__folder-name, and the slow test mirror needs navigation timeouts well past the 30s default. Images load through assets/shots.js — lazily, and via fetch-or-sg.vfs rather than , because the authoring contract forbids declarative refs so every page survives being served from inside a vault. Also adds a direct 'open the gallery app in its own window' link using the read-key fragment the UI now accepts. |
| v0.2.21 | 2026-08-16 | obj-cas-imm-10164a7a31ab | Two reader reports from an iPhone, both fixed with the cause named. (1) The vault pages now open both surfaces ON LOAD — the reader lands on the vault, not on a row of buttons. The opens are sequential by design: the browser surface starts once App Mode reports vault-ready (grace-capped), so its objects come out of the client's encrypted-object cache and the second open mostly decrypts rather than fetches — the caching architecture demonstrating itself on every page view. Buttons are gone; each frame carries a label and its own status line, and a failed handshake leaves a retry control instead of a dead page. (2) The landscape-iPhone report — site and iframe not using the full width after a pinch-zoom — was hunted down empirically rather than guessed at: one unbreakable 702px token (the sgit clone command with its 90-character credential) on a 393px viewport made the page 743px wide, which drops Safari's fit-to-width scale below 1; pinch out and the entire site sits narrow with a white gutter. Fixed with overflow-wrap:anywhere on inline code (breaks only when a token would overflow) plus the html canvas painted the site colour so any zoomed-out or overscrolled area reads as the site rather than as white margin. Verified at iPhone viewports: every checked page now measures exactly the viewport width, and the auto-open completes with zero clicks. |
| v0.2.20 | 2026-08-16 | obj-cas-imm-23e6ea08a77d | Both surfaces at once, reader-requested: on the vault pages, App Mode and the vault browser now each open in their OWN frame, stacked — the app first, the FILES/SGIT/SETTINGS browser under it — instead of one frame the buttons fought over. The second open is fast by design and the component says so: the encrypted objects are already in the client's cache from the first surface, so the second mostly decrypts rather than fetches — the caching story demonstrating itself. Each frame carries its own status line from its own handshake (one listener, replies routed by which frame sent them). The Full screen button is gone from these pages — with each surface getting a full-width, viewport-height frame of its own, it earned nothing. Verified headless: both surfaces open (5.0s through the slow test mirror, faster live), app above browser, two independent vault-ready events. |
| v0.2.19 | 2026-08-16 | obj-cas-imm-2773e0dfba35 | The site starts doing the thing it was building toward: publishing vaults. New /vaults/ section — an index of every read key this site has deliberately published, and one page per vault (five at launch: Field Notes, Strategy Maps, Deploy Docs, the Catalogue itself, and — new — Algarve · May 2026) with a real description, the features that vault exercises, what the shape is good for, the derived facts, the key as a copyable sgit_rk1_ credential with a CLI command and an open-in-the-official-UI link, and the vault RUNNING LIVE in the page via the reusable embed component (assets/vault-ui-embed.js — the two-surface embed-protocol host from the demo page, now attribute-driven; App Mode hidden for vaults without an app). Pages load the component contract-compliantly (fetch+eval, no script src — every page must survive being served from inside a vault). The Algarve vault is the first entry processed through the catalogue's submission queue as designed: read key supplied in chat, everything else derived — 71 files, 29 MB (60 WebP photos in originals/web/thumbs), 36 commits, auto-opening gallery app with a chaptered narrative. Its pre-publication audit is published on the page per the rules: one finding (a live delete_auth token in public-preview bookkeeping — narrow scope, the owner advised to rotate) and one counterpoint worth showcasing (the same vault's readonly-tokens bookkeeping decrypts to further ciphertext: owner secrets double-encrypted, the pattern that fixes the finding class). Catalogue vault updated in the same breath — new entry, trip-gallery-1 ticked off the awaiting list (7 remain) — and /catalogue/ picked it up with no site deploy, which is that design working. |
| v0.2.18 | 2026-08-16 | obj-cas-imm-68578f7b1bf4 | The tag pipeline's first contact with a real GitHub rule, fixed within the hour. v0.2.17's run DID tag itself — the first CI-authored tag — but the historical backfill push was rejected wholesale: a workflow's GITHUB_TOKEN cannot push any ref pointing at a commit whose tree carries a different version of a workflow file, and the `workflows` permission that would allow it is not grantable to that token. Every pre-v0.2.17 release predates the current deploy-pages.yml, so all 33 backfill tags bounced — and because the tag job failed, the deploy was skipped and v0.2.17 never reached the live site (this release carries its changes out). The fix splits the pushes by what they are: THIS release's tag at HEAD is load-bearing and fails the job if rejected (it never should be — HEAD's workflow blob matches the branch, which is why v0.2.17's own tag went through); the historical backfill is best-effort per tag, warns per rejection, and emits one notice with the single human command that completes the set — `git push origin --tags` from any workflows-scoped credential. Once a human has done that once, the backfill loop becomes a chain of no-ops. Lesson recorded for the case-studies pile: the same both-remotes discipline that made CI verify-and-tag instead of commit-and-tag also meant the failure cost nothing but a skipped deploy — no bump commit was stranded on one side of the two-VCS split. |
| v0.2.17 | 2026-08-16 | obj-cas-imm-24876be44e37 | Two reader-driven fixes and the release pipeline grows tags. (1) Layout: the embed buttons and their status line sit back in the text column where they belong — only the vault surface itself breaks out wide, since it is the thing with the big UX. (2) CI tagging, ported from the VoiceDebrief website pipeline (validate → tag → publish, every push to dev a minor release tagged v{release}.{major}.{minor}) with one deliberate adaptation: the upstream OSBot action has CI commit a version-file bump, but this repo is simultaneously an sgit vault, and a CI-authored commit would exist only on the git side — breaking the both-remotes-in-sync invariant release.sh enforces. Here CI verifies-and-tags instead of owning: SITE_VERSION (bumped once per release by release.sh) must match the release commit's subject and be the next minor after the latest tag, then the commit is tagged. No CI commits, no drift, same discipline — and a forgotten bump now fails the pipeline loudly instead of shipping quietly. The first run backfills tags for every historical release by parsing the commit subjects, so the whole v0.1.9→now history becomes navigable by tag. Also: validate.js now runs in CI as the gate before tagging and publishing, which puts the key-leak tripwire on the deployment path as well as the release path. (Tags could not be pushed from the authoring session — the session's git proxy authorizes branch pushes only, which settled the design question of who owns tags: CI does.) |
| v0.2.16 | 2026-08-16 | obj-cas-imm-34ed83dd03e6 | The embed grows up: both official surfaces, one click each, over the UI's new embed protocol. Reading the deployed bundle found what the addendum's Phase 3 had shipped — embed-protocol.js and a shared embed-receiver on BOTH shells: the host page loads ?embed=1&parent=, the frame proves itself with vault-embed-ready, and only then is the key sent by postMessage with the targetOrigin pinned. Strictly better than the URL-fragment flow shipped yesterday: the key never appears in any URL, is never written to the frame's storage (verified — sessionStorage and localStorage empty after open, memory-only as the protocol promises), and the host gets structured vault-ready/vault-error events instead of guessing from load timings. The demo page now has two buttons: App Mode, and — new — the vault browser with the FILES/SGIT/SETTINGS rail, which previously needed a two-step trick because /en-gb/vault deliberately strips URL hashes and root is the only inbox. Headless-verified both: App Mode ready in 2.7s, browser in 9.7s, rail present, R1 W0 badge, no horizontal scroll. The embed area breaks out of the text column (94vw up to 1680px, height tracking the viewport) because the vault browser is a full working surface, plus a full-screen button — both asked for by a reader with big-UX vaults. What is still not possible is stated precisely on the page: vault-open carries {key, mode, deepLink} where deepLink is a file path, so a host can select a SURFACE but not a VIEW — SGIT and SETTINGS remain in-page events. The briefing gains an addendum thanking the UI team, recording the verification, and sharpening the last ask to one optional field: view:'files'|'sgit'|'settings' on vault-open, applied after mount. Also fixes a stale paragraph v0.2.15 left behind (a silent curly-quote replace failure) — the page no longer promises a swap that already happened. |
| v0.2.15 | 2026-08-15 | obj-cas-imm-576ba8a1a09f | The gap closed: the official SG/Vault interface now opens from a published read key, and this site embeds it. Our v0.2.7 experiment had isolated the blocker to exactly one thing — the loader documented a read-only credential but rejected it, and the CLI shorthand was parsed as a passphrase and PBKDF2'd into the wrong ref id. The UI team shipped the fix: a read-key credential is now its own format (<64-hex>:, the shape sgit clone already accepted) and is tested BEFORE the passphrase formats, which was the precise ordering bug; canonical CLI key prefixes are stripped first. Re-running the same experiment against the deployed build, read key only, no vault key anywhere: all three credential forms parse; App Mode boots the Field Notes demo under full chrome with its six studies rendered and the bridge live; the vault browser opens with the FILES/SGIT/SETTINGS rail over the real decrypted tree; and the SGit view lists both commits with real object ids — all inside a cross-origin iframe, with an explicit R1 W0 / Read-only badge. So /demos/vault-app-embed.html now carries TWO hosts and keeps both on purpose: the ~170-line minimal host that shows the protocol with nothing hidden, and the official UI opened with the same published key. One ask stays open and is stated as such — no URL selects a view, so the SGit inspector cannot yet be framed in isolation. Also: the release tripwire learned the CLI's canonical WRITE-key prefix (its read-only sibling is deliberately exempt — we publish one), proven by making it fail before trusting it; it promptly caught this very release note's first draft, which had spelled the banned prefix out while explaining it. The hub capability audit is updated with verified evidence — row 1, the entry point for everything, flips from partial to present, which settles the spec's assembly-not-construction question for the forge's read-only tier. |
| v0.2.14 | 2026-08-15 | obj-cas-imm-2f3c360b2de1 | Ask B of the 14 Aug pack begins: the hub.sgit.ai briefing-pack plan lands in admin/plans/, and — per the spec's central instruction — the capability audit comes before any architecture. The audit table is already 13 rows deep, seeded entirely from evidence this project has produced: verified present (open-from-read-key in our readers, single-object decrypt, the app runtime under a sandboxed iframe, sparse per-object fetch, cross-session caching with the 120s ref window, frameability), verified partial with the exact gap named (the official UI parses but rejects its own documented read-only credential format), and honestly unknown (client-side merge, the in-UI diff and history views — enumerated in the bundle, never driven). The partial rows are flagged as the dangerous ones, because a partial capability gets assumed complete. The plan also fixes the pack's shape: six parts in order, the four absences stated up front, surfacing/adding/absent applied per feature (blame is adding, not surfacing), permissions as worked key topologies, and the private-vault key-handling flow named as the one needing a considered position. The crawler question is closed as answered: full text in the served HTML, noscript reveal since v0.1.26, and Google indexing confirmed. |
| v0.2.13 | 2026-08-15 | obj-cas-imm-35d4e3e3a906 | Fix: the catalogue page shipped without the vault debug panel markup that the shared reader wires unconditionally, so the reader threw on two missing elements and the first document never rendered (navigation and clicked entries worked; the initial body stalled at the fetching message). The panel is now on the page — which it should have been anyway, since watching the ciphertext arrive is half the point — and the headless check confirms the README renders on load with zero page errors. |
| v0.2.12 | 2026-08-15 | obj-cas-imm-15dbcf053020 | The catalogue: a vault indexing vaults, including itself. The 14 Aug briefing pack's Ask A lands as designed — a submission queue whose per-entry cost is a read key and one line, with everything else derived by opening the vault. The deriver (admin/build/catalogue_derive.py, ~120 lines, read-only, no token) turns a read key into file count, plaintext size, commit depth, HEAD, top-level layout, file types, app entries and browser-renderability; proven on all three published-key vaults (Field Notes 4bshby5n, the strategy/maps vault ookq4mn4 — both app entry points detected — and the deploy-docs vault fyofmkvr, markdown-only). The catalogue itself lives in a new vault (kc67yhgw) published with its own read key and listed in itself: README (how to submit), SCHEMA (supplied-vs-derived, and the two rules — read keys yes, vault keys never; escrow the write key BEFORE publishing, because a frozen vault can never be corrected), three processed entries, and the two public to-do lists the brief asked for — awaiting-a-read-key (seeded with eight vaults named in the memos, each carrying the pre-publish audit instruction the strategy-maps case taught) and awaiting-processing (the agent's queue, currently empty). /catalogue/ renders it live via the same reader as the deploy docs — updated by pushing to the vault, no site deploy. Write-key status is a first-class field: 'known and escrowed' or 'lost', stated publicly per entry. |
| v0.2.11 | 2026-08-15 | obj-cas-imm-1f8635c410ef | sgit gets its own Wardley map analysis — six maps starting with git at full strength, because a map that flatters its author is not a map: version control today (git's moat is the platform layer, resting on readable storage), the files that cannot follow (a hole in the map where their foundation should be), sgit's move (no new verbs, invert the bottom layer), the boundary on one map (two chains from one team, split by 'may the store read this?'), agents as the new user (the serialised diff versus ambient authority), and the strategy (commoditise private version control). The maps are drawn as inline SVG by a ~90-line renderer — no images, no dependencies — and the analysis ships as a SECOND app inside the same vault as the SG/Send strategy essay (ookq4mn4): one encrypted store, two entry points, one published read key; the embed opens it by passing entry to the same host. The embed shim gained link handling — in-page anchors scroll manually (assigning location.hash re-navigates a srcdoc frame) and relative .html links remount the frame on the new entry, so the two apps cross-link inside the embed; verified headless: 6 maps, 42 nodes, 12 evolve arrows, and clicking the companion link lands on the strategy essay. Linked from the Why page's boundary section. Also: Google has confirmed indexing sgit.ai, which unblocks the component registry when its turn comes. |
| v0.2.10 | 2026-08-15 | obj-cas-imm-cedfb3d06f6a | Plan bookkeeping: the why-expansion plan's status table now reflects reality — Why reframe done, serialised PR done with its CLI brief, two of three demo vaults live, embed at the minimal-host stage pending the UI team's credential fix. |
| v0.2.9 | 2026-08-15 | obj-cas-imm-2ce42cfd214e | The two remaining pieces of the briefing-pack plan land. (1) The Why page is reframed from rebuttal to boundary map: it now opens with where git wins, then draws the boundary precisely — the operations are not the gap (commit through merge all exist; proposing reviewable changes without write access is present, as a serialised diff, and is a differentiator); what is absent is the hosted review interface and the ecosystem above the protocol; and git is also client-side, so the real difference is that the objects are encrypted there, with the losses stated as a given-up/in-exchange-for table. New protocol section: the six-step read path verbatim, the two keys named explicitly, the three modes (Local/API/Web), and the two-implementations proof point. The LinkedIn comment and the market answer move below the boundary, kept whole. (2) New lead use case: the serialised pull request — no credential issued at all, grounded in the 5 Aug Black Hat disclosure, with an honest shipped-vs-pattern table (emit exists as history diff --json; import is not first-class) and evidence status PARTIAL. The matching brief to the CLI team asks for sgit diff export/apply, a published diff format, and ignore-file support — the latter now a prerequisite for the one-folder-two-VCS pattern the site publishes. |
| v0.2.8 | 2026-08-15 | obj-cas-imm-4060eca3121d | Second demo, and the first with real content: The Strategy in Seven Maps — the actual SG/Send strategy, published on LinkedIn in May 2026 — served live from a vault with a published read key. The page also publishes the audit that made this interesting: the original vault could NOT publish its read key, because its own read-write credential was written inside its content (a production briefing quoted the clone command verbatim), server-side bookkeeping under .vault/owner/ carried live delete_auth tokens, and the vault's keys derive from a legacy low-entropy token. The fix is the pattern the page teaches: republish, don't retrofit — sanitised copy, credentials redacted with a visible note, fresh full-entropy vault (ookq4mn4), and only then a published read key; a republish also sheds the history you cannot publish. The embed host gained vault-path image support (a MutationObserver swaps img.src vault paths for blob: URLs read over the bridge, the same job the real host's interceptor does) — verified: all eight Wardley Map PNGs travelled as ciphertext and rendered. |
| v0.2.7 | 2026-08-15 | obj-cas-imm-1b9cd77fb6d7 | The full-UI embed experiment, run and published. Driving the real SG/Vault interface framed inside a page: the UI is frameable (no X-Frame-Options, no frame-ancestors), and App Mode works completely inside a cross-origin iframe — with a valid credential the official app-shell booted the Field Notes demo under the full HUD chrome. The one gap is the credential: the loader documents a read-only format (vault_id + 64-hex read key) but the client rejects it, and the CLI's 64hex:vault_id shorthand gets PBKDF2'd as a passphrase and derives the wrong file ids. No URL selects the SGit view, either. Both are now precise, evidence-backed asks in the UI-team briefing — honour the documented format (which alone makes the official UI embeddable with only the published read key) and add a |view:sgit deep-link. The demo page carries the findings table. |
| v0.2.6 | 2026-08-15 | obj-cas-imm-966aed3bd862 | The first demo ships: a vault app running live inside a sgit.ai page from a published read-only key. A new vault (Field Notes, 4bshby5n) was created from scratch for it — a self-contained app following the authoring contract, generative SVG art, content in content.json read over the bridge — and /demos/vault-app-embed.html is the complete walkthrough: init, commit, push, derive the read key, publish it deliberately, embed. The embed host is assets/vault-embed.js (~170 lines): HMAC-derived ids, ciphertext over CORS, Web Crypto decryption, the app booted in a sandbox=allow-scripts iframe with an opaque origin, and its sg.vfs/loadCss/loadJs calls answered over postMessage — the same shape as SG/Vault's vault-in-vault, minimal by design until the UI team answers the reuse briefing. Also rewrites the one-tree-two-remotes ordering section as a clean rule (the discovery narrative is gone), adds the Demos nav section, and extends the key-leak tripwire to scan for every demo vault's passphrase, not only the site's own. Verified end to end in headless Chromium: bridge live (the app's status line reads content via sg.vfs.readText from the vault), six tiles rendered, frame origin opaque, mutations impossible by construction. |
| v0.2.5 | 2026-08-14 | obj-cas-imm-fedcfbd348c0 | Corrects the one-tree-two-remotes case study, prompted by a reader question: if sgit pushes first and git commits after, don't the files match? They do — tested rather than argued. With that ordering git captures the freshly written ref every time and a clean tree is the normal end state of a release; reads (ls, history, status, vault info), no-op commits and pushes, pull and fetch were all tried and none rewrites the ref. The section is now a rule about ordering rather than a claim of permanent drift, keeping the part that is true and useful: when the ref IS dirty, the bytes tell you nothing, because a rewritten ref never byte-matches even when it decrypts to the same commit. |
| v0.2.4 | 2026-08-14 | obj-cas-imm-854db222f8cb | Wider layout across the site. The reading column was a classic 720px prose measure, which squeezed the content into the middle of a modern display and made every page longer than it needed to be. The measure is now 960px and the wide container 1360px, with the body type up a step (.93rem to .98rem) so the longer line keeps a comfortable character count; the home-page sections (hero, terminal, feature grid, cards) scaled in proportion, and the deploy-section nav column widened with them. Verified at 1600px (no overflow, content fills the frame) and at 390px (no horizontal scroll). |
| v0.2.3 | 2026-08-14 | obj-cas-imm-6deb6376d9bd | Plans and briefs from the 14 Aug briefing pack. Publishes the implementation plan for the Why reframe (boundary map), the serialised-pull-request lead example (with one honesty gap found while planning: the diff emit exists as history diff --json, but the CLI has no apply/import command, so the page will ship as PARTIAL and a brief goes to the CLI team asking for sgit diff export/apply plus a published diff format), three end-to-end demo vaults with deliberately published read keys, the embed-reuse work, and the component registry (components, never plugins — plugin stays reserved for capability grants; registry gated on indexing being observed). Files a briefing to the SG/Vault UI team with six concrete questions about reusing their app-iframe host code inside sgit.ai pages, linked from the briefs page. |
| v0.2.2 | 2026-08-14 | obj-cas-imm-29aa935bd44a | New case study: one working tree, two version control systems — the workflow this site is actually developed with. One folder is both an sgit vault and a git repository; a release is two pushes of the same tree. The page covers what each remote carries, the one-file .gitignore boundary that makes it safe (everything encrypted is committed; only the plaintext local/ tier is excluded), and the finding that surprised us: the encrypted ref always looks modified to git because AES-GCM uses a fresh IV per write, so for that one file git status cannot detect staleness — proved by decrypting both sides to the same commit id. Ships admin/build/release.sh, which makes the discipline mechanical: build, validate (the key-leak tripwire gates BOTH pushes, not just the deployed one), push sgit, push git, and refuse to finish unless both remotes report in sync. The script deliberately never invokes commands that echo the vault key. |
| v0.2.1 | 2026-08-14 | obj-cas-imm-49cf3a524b0c | Fixes a gap the v0.2.0 restructure opened: llms.txt is generated by walking a list of known sections, and the new case-studies section was not in it, so all three of those pages were silently absent from the machine index — present on the site, invisible to any agent reading llms.txt. The section is added, and the generator now refuses to build if any page would be omitted, which is the same guard as the orphan-page rule and for the same reason: a page nothing links to and a page the index does not list are both unpublished. |
| v0.2.0 | 2026-08-14 | obj-cas-imm-d8f580db4d0f | Structural release — the middle digit moves, as the numbering note below promised it would. Two changes. (1) The root held 19 files and every page body was inlined in a 2,709-line generator; bodies now live one-per-file in admin/content/ with a pages.json manifest, and the generator is a 648-line engine that does not grow as the site does. Adding a page is a content file plus a manifest row; the build then produces the HTML, the markdown twin, the llms.txt row, the llms-full.txt section, the sitemap entry and the canonical/OG/JSON-LD tags. The refactor was verified output-preserving before any page moved: all 31 pages byte-identical. (2) Sections became folders — why/, try/, security/, skills/, briefs/ — leaving 9 files in the root, all of them ones that must be there. New case-studies/ section, which is where the leaked-key incident and the live-vault architecture now live; they were filed under docs/ and deploy/ where nobody looking for a case study would find them. Links were rewritten mechanically by resolving each href against the old path and re-expressing it from the new one, then verified by crawling every internal URL from the homepage: 29 URLs, zero broken. |
| v0.1.27 | 2026-08-14 | obj-cas-imm-87daa0751f0d | Entity disambiguation, after checking what search actually returns. Google's AI Overview for the bare query already knows this project — and sources it from PyPI, because the PyPI page never linked here and this site was not in the index. "sgit" is also an Android Git client, an Indian engineering college and a class of shell shortcut, so the job is not only being indexed but being resolved to the right thing. Every page now carries JSON-LD: a SoftwareApplication node with sameAs pointing at the PyPI and GitHub identifiers that already rank, an explicit disambiguatingDescription naming the collisions, and a per-page TechArticle node. Google's own 2026 guidance says structured data is not required for generative-AI features — this is here for entity resolution, not ranking. The validator now fails the build if a page has no structured data or if any JSON-LD block does not parse. |
| v0.1.26 | 2026-08-14 | obj-cas-imm-5da2eb791bb2 | Acts on an inbound brief from an agent that tried to use this site as documentation and could not. It reported that the site did not rank for its own positioning language and guessed the pages might be client-side rendered. They are not — the full text is in the served HTML — but the fade-in that hides the unstyled flash left body{opacity:0} until a JavaScript bootstrap ran, so any client applying our CSS without running that bootstrap rendered a complete but entirely invisible page (measured: 15,733 characters at opacity 0), which is also a hidden-text signal to an indexer. Fixed with a noscript override and a CSS-only reveal failsafe, both now enforced by the validator. Adds the crawler surface that never existed: robots.txt, a generated sitemap.xml covering every page, and canonical plus Open Graph tags. Adds llms-full.txt — every page in one document — for the very common agent harness that will not follow a link out of a fetched file, and makes llms.txt self-sufficient: inline answers to the common questions (including exactly which git operations exist and which do not) and per-page key facts, on the brief's observation that for such an agent the descriptions are the only content it will ever see. The brief and what changed are published on the briefs page. |
| v0.1.25 | 2026-08-14 | obj-cas-imm-1861dd16dd11 | Three changes that go together. (1) Every page now has a .md twin at the same path, generated from the same content so the two cannot drift, with internal links rewritten to point at markdown — an agent can traverse the whole site without parsing HTML, and llms.txt is now generated from the page registry rather than hand-maintained. (2) A git-and-sgit comparison on the Why page that says plainly where git is better — performance at scale, ecosystem, bisect/blame/rebase, partial commits — and how the two run side by side, as they do on this site. (3) Use cases moved to /use-cases/ with a page per situation: the problem, a working recipe on shipped commands, an honest evidence status (proven / partial / pattern), and a brief you can hand to an agent. Validator gained three rules: every page has a markdown twin, markdown links resolve, and no raw HTML leaks into the markdown. |
| v0.1.24 | 2026-08-14 | obj-cas-imm-3c426ddbe9e9 | Why page rewritten around the right question. The first version answered "is there a market" with verticals and a comparison table; the sharper answer is what sgit makes possible that was not possible before, so that is now the headline: six capabilities running on this site — a live site its host cannot read, read access as a publishable capability, two agents sharing a workspace neither host can read, private data with CDN economics, storage as untrusted commodity, and transit security that does not rest on the CA system (including where that goes next: the read key never leaving the client, or PKI with a client-only private key). The page now assumes the reader knows git and only covers the delta. Also corrects the business-model answer: the client being open source IS the distribution strategy, with services built on top — not "no revenue attached". |
| v0.1.23 | 2026-08-14 | obj-cas-imm-89a142ee3598 | A freshness window on the mutable HEAD pointer. The ref was the last per-page-view network request left; it is now checked at most once every ref_ttl_s seconds (120 by default, configurable in deploy/vault.json), so reading inside the window costs zero requests and server load scales with readers rather than page views. The cost is a bounded propagation delay — a new commit appears within the window at worst — and "check for new commit" forces a fetch that ignores it. The vault panel logs the reused ref as TTL and counts down live to the next check. |
| v0.1.22 | 2026-08-14 | obj-cas-imm-d9ac70d78c31 | Kills the load-time flicker of the vault panel. The panel's remembered width and open state were restored by the reader script, which loads asynchronously — so the panel painted at its CSS default width, then jumped and slid open a beat later. Restoration now happens synchronously, before the first paint, and the slide transition is suppressed until state has settled. Opening and closing the panel by hand still animates; restoring it never does. |
| v0.1.21 | 2026-08-14 | obj-cas-imm-5a60bc3bf25b | Object bodies in the vault panel are now syntax-coloured like an editor — keys, strings, numbers, literals and punctuation each get their own colour — and word wrapping is off, so structure survives and long values (base64 ciphertext, object ids) scroll horizontally instead of folding into a wall of text. Highlighting is applied only when the decrypted object actually parses as JSON, so markdown blobs stay plain. |
| v0.1.20 | 2026-08-14 | obj-cas-imm-78146d2f4f86 | The vault panel now links to the page that explains it. There is a compact “how this works” link in the panel header (always visible) and a fuller card at the foot of the panel pointing at deploy/how-this-works.html — the panel is where you are when the question occurs to you, so it is where the answer should be offered. |
| v0.1.19 | 2026-08-14 | obj-cas-imm-fe67d9589a2e | Fixes the resize grip, which shipped in v0.1.18 but was unusable: it was absolutely positioned inside the panel's scrolling area, so it scrolled out of reach as soon as you moved down the object list, and at 6px fully transparent it was invisible anyway. The panel is now a flex shell — a fixed 12px drag rail with a visible handle, plus a separately scrolling body — and dragging uses pointer events with capture (mouse, pen and touch). Double-click the rail to reset the width. |
| v0.1.18 | 2026-08-14 | obj-cas-imm-6eded1c95732 | Vault panel becomes an object inspector: every row now shows what the object IS (ref/commit/tree/blob), WHY it was read, and — on click — its decrypted contents, pretty-printed for JSON. The panel is width-resizable (dragged from its left edge, remembered). Plus a real optimisation the panel made obvious: the path→blob index is a pure function of the commit id, so it is now memoised in localStorage — a first visit walks every tree to learn the encrypted filenames, but subsequent visits to an unchanged commit read zero tree objects. |
| v0.1.17 | 2026-08-14 | obj-cas-imm-9d5b50f68679 | Vault panel: a "clear list" button that resets the request log and counters without touching the caches (so you can see exactly which objects one page needs); the panel's open/closed state now persists across navigation and reloads; cached objects record when they were stored and the panel shows their age. Navigation now scrolls to the top of the content rather than the top of the document. New page: deploy/how-this-works.html — the full architecture with hand-drawn SVG diagrams of the two-session publishing pipeline and the client-side read path. |
| v0.1.16 | 2026-08-12 | obj-cas-imm-34684a789fe6 | New /why page answering the sharpest public criticism of the project ("I see no market or value whatsoever") directly and without marketing: who actually has the problem, why git-crypt/Dropbox/S3+KMS do not cover it, the market question answered plainly (the CLI has no revenue attached; hosting is the commercial layer; no TAM claims), where the criticism is right, and a twelve-question FAQ pre-answering the promised follow-ups. |
| v0.1.15 | 2026-08-12 | obj-cas-imm-0959988dd4fe | New Deploy section: self-hosting guidance rendered LIVE in the browser from an encrypted SG/Send vault, using a published read-only key — ciphertext over CORS, AES-256-GCM decryption via Web Crypto, no copy stored on this site and no rebuild when the SG/Send team pushes. Includes a three-tier cache (session memory, permanent Cache API for immutable objects, always-fresh ref) and a vault debug panel showing the HEAD commit, per-object request log, and cache hit/miss stats. |
| v0.1.14 | 2026-08-12 | obj-cas-imm-3b54c02dbb96 | Two new pages, both linked this time: docs/exposed-vault-key.html (the rotation runbook plus the case study of this site's own key leak) and briefs.html (cross-team briefs — which v0.1.13 built but never registered, so nothing linked to it). New validator rule: every generated page must be reachable from another page, or the build fails. Added a fourth CLI-team ask: history-preserving rekey. |
| v0.1.13 | 2026-08-12 | obj-cas-imm-5168ef3fe1a7 | SECURITY: the vault passphrase had been written into admin/build/validate.js as an anti-leak tripwire regex — which put the literal secret into a tracked, public file (present in 3 commits). Removed; the tripwire now reads the secret from the gitignored local/ tier and scans for it, so it can never be hardcoded again. The key must be treated as compromised and rotated. Also: a /briefs page collecting the cross-team briefs (multi-agent collaboration log), and a "contacting the server" notice before network commands in the browser terminal. |
| v0.1.12 | 2026-08-11 | obj-cas-imm-e8ceb3fc2239 | In-browser clone completes: serial-executor shim for Pyodide (WebAssembly cannot spawn threads, so all parallel blob transfers run sequentially in the browser) — validated natively against the live server with thread creation disabled: full 225-blob clone of this site vault. A serial/auto-detect mode is proposed upstream to the sgit CLI. |
| v0.1.11 | 2026-08-11 | obj-cas-imm-c9afa76a79cb | Browser-transport fix for in-browser clone: drop the redundant X-API-Key header (the servers CORS-allow x-sgraph-access-token but not x-api-key, and one disallowed header fails the whole preflight — diagnosed live from the first user clone attempt); CORS/network failures now surface as readable HTTP 599 errors instead of a Pyodide SystemError. |
| v0.1.10 | 2026-08-11 | obj-cas-imm-deac6363bff9 | In-browser terminal on /try: the real sgit CLI in-process (init, commit, status, history — and network commands via a browser XHR transport: clone/push/pull straight to the SG/Send servers), plus a busybox of file commands over the in-memory filesystem. Key hygiene: every example key on the site is now an obviously-invalid placeholder (format-valid example keys are squattable namespaces), enforced by a new validator rule. |
| v0.1.9 | 2026-08-11 | obj-cas-imm-83b8c23a1baa | "Try sgit in your browser" page: the real sgit-ai wheel running client-side under Pyodide (verified in headless Chromium first) — key derivation, encrypt/decrypt, an in-memory vault round trip, and a Python REPL. Plus: bootstrap fast-path for static hosting (no 2.5s bridge wait on GitHub Pages), CNAME for sgit.ai, and GitHub Pages deployment via Actions in the SGit-AI__Website repo. |
| v0.1.8 | 2026-08-11 | obj-cas-imm-775783f31110 | Skills promoted to a top-level nav item with a new /skills page and the three agent skills shipped in the vault (latest versions, verbatim); llms.txt added at the vault root — encrypted for key-holders today, a standard public llms.txt when the site deploys to GitHub Pages; Home nav link retired (the brand mark covers it). |
| v0.1.7 | 2026-08-11 | obj-cas-imm-c226a3aff160 | SG/Vault section rebuilt from the official docs bundle: corrected security-page structure-key claim to current reality, git page aligned with the publishing guide (three-rule boundary, leak audit, GitHub round trip, restore drill), new pages for static hosting on GitHub Pages, sub-vaults, and no-code content authoring; .gitignore extended with work/ and *.pem rules. |
| v0.1.6 | 2026-08-11 | obj-cas-imm-f62d9bd2d0d4 | Corrected git integration to the side-by-side design: git now tracks the encrypted .sg_vault store (only the plaintext local/ folder is excluded), so a git remote doubles as a zero-knowledge mirror of the vault. Pattern documented on the git-and-vaults page. |
| v0.1.5 | 2026-08-11 | obj-cas-imm-353038cc3e56 | Git integration: .gitignore (keeps .sg_vault/ — above all local/ keys and token — plus git metadata and build noise out of git and out of vault snapshots) and .gitattributes (raw sgit store files marked binary/-diff/-merge; generated *.html marked linguist-generated). |
| v0.1.4 | 2026-08-11 | obj-cas-imm-90254d9591ff | New SG/Vault section — for now the official sgraph platform documentation: SG/Vault & the platform, building vault apps, the window.sg bridge & host capabilities, and "git repos inside vaults" (engineering preview of the pure-Python git reader, verified against a real 906-commit repo). |
| v0.1.3 | 2026-08-11 | obj-cas-imm-46a8b14d4fca | Beta status (in production use), light theme, admin & engineering section, per-push version badge on every page, SG/Vault & SG/Send now link to sgraph.ai, design-improvements brief for Claude Code. |
| v0.1.2 | 2026-08-11 | obj-cas-imm-c3084abbba8c | Replaced the proposal app with the sgit.ai MVP site: 12 individually-navigable pages, shared CSS/JS loaded through the SG bridge, full-strength keys in all examples. |
| v0.1.1 | 2026-08-11 | obj-cas-imm-7f1fbacf0485 | Initial vault app: the positioning & messaging proposal microsite with an embedded landing-page prototype. |

Numbering: v0.1.n while the site is in its first structure; the middle digit will bump on structural redesigns. The "vault commit" of the newest row reads "this release" because the commit ID only exists once the release is committed — it is recorded here retroactively by the next release.

[← Admin & engineering](index.md)



==============================================================================
# The HTTP API — sgit.ai

> The protocol surface behind sgit: base URL, the capability model, and the reference for vault objects, append lanes, authentication headers and error codes. Built from a code-verified audit at v0.33.54, with unresolved endpoints labelled rather than guessed at.
>
> Page: https://sgit.ai/api/index.html

[Home](../index.md) / API

# The HTTP API

Everything sgit does, it does over this API. The CLI is a client; so is the browser bridge; so is anything you write. This section is the protocol surface — endpoints, headers, gates, limits and the error codes you will actually hit.

**Where this came from, and how far to trust it.** This section is built from a code-verified audit supplied by the SG/API team, read out of the route tables and constants at **v0.33.54** rather than recalled. It is *their* verification, not ours: this site has not independently exercised every endpoint. Where their audit and the shipped client disagreed we checked and said so; where something is registered but unconfirmed it is labelled **PROPOSED** and you should not build on it yet. Same rule as the rest of this site — if it is not verified, it says so.

## Base URL

`https://send.sgraph.ai` for the hosted service, or your own host if you [run it yourself](../deploy/index.md). All request and response bodies are JSON unless stated otherwise.

## The one idea worth reading first

The server is a **capability-checked ciphertext store**, and every access-control decision it makes is a hash comparison. It stores `SHA-256` of each capability key and checks `H(presented) == stored`. It never holds a raw key, and it never holds a private key at all.

That is what makes the rest of the design possible: a vault ID is an address rather than an account, reads are public by default because the bytes are useless without a key, and a stranger can write to your vault without ever having a credential on the platform.

## The reference

| Page | What is in it |
|---|---|
| [Authentication](authentication.md) | The six headers, what each gates, and the hash-comparison model |
| [Vault objects](vault-objects.md) | The pointer store — read, write, batch, destroy — plus the caching contract and storage layout |
| [Append lanes](append-lanes.md) | The six append endpoints: the vault-to-vault message transport |
| [Errors and limits](errors.md) | 400, 403, 413, 507 — what each actually means, and the ceilings that produce them |

## Four capabilities

Most of the API surface is one of four capability tiers. They are separated so that holding one tells you nothing about the others:

| Capability | Presented as | Grants |
|---|---|---|
| `append_token` | a field in the request body | Write to one append lane. Nothing else — not even listing it |
| `enum_key` | `x-sgraph-vault-enum-key` | List, fetch and mark-processed on append lanes |
| `write_key` | `x-sgraph-vault-write-key` | Write and delete objects; configure and purge lanes |
| private key | *never presented* | Decryption, client-side only |

The fourth row is the point of the design rather than a footnote: the server cannot decrypt anything it stores, so the strongest capability in the system is the one it never sees.

## Where to start

- Sending an encrypted message between two vaults → [Vault messaging](../docs/vault-messaging.md), which composes [append lanes](append-lanes.md) with [PKI](../docs/pki.md).
- Reading or writing files → [Vault objects](vault-objects.md).
- Building a vault app in the browser → the [SG bridge](../vault/sg-bridge.md) wraps this API so you never write HTTP.
- Using the CLI instead → [Quickstart](../docs/quickstart.md).

## Open questions we will not guess at

Three items came through the audit unresolved. They are listed rather than documented, because a confident page about an endpoint that does not exist is worse than no page:

| Item | Status |
|---|---|
| `GET /api/vault/zip/{vault_id}` | **UNRESOLVED** — registered in the route table, marked PROPOSED in the team’s reality document. Not documented either way until that is reconciled |
| `/join/*` | **UNRESOLVED** — the reality document lists three live endpoints, but the routes are not registered in the deployed app. Not documented |
| Client-side lane addressing | **PROPOSED** — `append_token = H(public key)` is the intended model; no shipped command emits it. See the [addressing note](../docs/vault-messaging.md#addressing) for what to do meanwhile |



==============================================================================
# API authentication — sgit.ai

> The six authentication headers, what each one gates, and the hash-comparison model: the server stores SHA-256 of every capability key and never holds a raw key or a private key. Includes why vault reads are open by default.
>
> Page: https://sgit.ai/api/authentication.html

[Home](../index.md) / [API](index.md) / Authentication

# Authentication

Six headers exist. Which apply depends on the endpoint and on how the server is deployed. None of them is a password, and none of them is stored: the server keeps `SHA-256` hashes and compares.

## The headers

| Header | What it gates |
|---|---|
| `x-sgraph-access-token` | The SGraph account or deployment. In a **single-key self-hosted deployment** this gates *every* route, including reads |
| `x-sgraph-vault-write-key` | Vault write capability: writes, deletes, destroy, and append `configure` / `purge` |
| `x-sgraph-vault-enum-key` | Append lane enumeration: `list`, `fetch`, `mark-processed` |
| `x-vault-read-key` | Read key, for public-vault routing |
| `x-vault-public` | Public-vault routing flag |
| `x-sgraph-transfer-delete-auth` | Transfer deletion — SG/Send transfers, not vaults |

One capability is **not** a header: `append_token` travels in the request body of `/append/write`. That is deliberate — see [append lanes](append-lanes.md).

## The hash-comparison model

The server never stores a capability key. It stores `SHA-256(key)` and, on each request, hashes what you presented and compares. Two consequences worth designing around:

- **A server compromise yields hashes and ciphertext**, not keys and not plaintext. An attacker with the whole database still cannot read a vault.
- **There is no recovery path.** The server cannot email you your key, because it has never had it. Same property as the vault key itself, for the same reason.

## Why reads are open by default

`GET /api/vault/read/{vault_id}/{file_id}` requires no authentication on the shared host, which surprises people. It follows from the encryption model rather than being a gap in it: the bytes are AES-256-GCM ciphertext under a key the server has never seen, and the file IDs are HMAC-derived opaque identifiers that reveal no filename. Serving them to an anonymous caller discloses nothing a reader could use.

It is also the property that makes a [published read key](../demos/vaults/index.md) work at all, and what lets vault content sit behind an ordinary CDN. If that trade is wrong for your deployment, run in single-key mode, where the access token gates reads too.

What an unauthenticated reader *can* learn is covered honestly on the [security page](../security/index.md#server-sees): object sizes, timing, and approximate activity volume.

## See also

- [Errors](errors.md) — what a 403 means as against a 400
- [Security model](../security/index.md) — the crypto these capabilities sit on



==============================================================================
# API: vault objects — sgit.ai

> The pointer store: read, write, batch, destroy and presigned endpoints, the caching contract that separates immutable content-addressed objects from mutable refs, and the storage layout behind every vault.
>
> Page: https://sgit.ai/api/vault-objects.html

[Home](../index.md) / [API](index.md) / Vault objects

# Vault objects

The pointer store: the ciphertext objects a vault is made of, addressed by opaque identifiers the server cannot interpret. This is what `sgit push` and `sgit pull` are doing underneath.

## Endpoints

| Method | Path | Auth | Notes |
|---|---|---|---|
| PUT | `/api/vault/write/{vault_id}/{file_id}` | access token + write key | Body is raw ciphertext |
| GET | `/api/vault/read/{vault_id}/{file_id}` | none | Raw bytes. [Reads are public by default](authentication.md#reads) on the shared host |
| GET | `/api/vault/read-base64/{vault_id}/{file_id}` | none | Base64 in JSON — MCP-safe. Around 3.75 MB ceiling |
| DELETE | `/api/vault/delete/{vault_id}/{file_id}` | access token + write key |  |
| POST | `/api/vault/batch/{vault_id}` | per operation | Mixed reads and writes, **max 100** per request |
| POST | `/api/vault/list/{vault_id}` | — |  |
| GET | `/api/vault/health/{vault_id}` | — |  |
| GET | `/api/vault/public-info/{vault_id}` | — |  |
| DELETE | `/api/vault/destroy/{vault_id}` | write key | Body `{vault_id, purge?}`. Without `purge` it writes a tombstone that blocks reuse of the ID |

Large blobs go through presigned URLs rather than the request body: `POST /api/vault/presigned/initiate|complete|cancel/{vault_id}` and `GET /api/vault/presigned/read-url/{vault_id}/{file_id}`.

`GET /api/vault/zip/{vault_id}` is registered in the route table but marked PROPOSED upstream. It is deliberately [not documented](index.md#unresolved) until that is reconciled.

## Destroy, and why the tombstone matters

`destroy` without `purge:true` leaves a tombstone that prevents the vault ID being registered again. That is a security property, not bookkeeping: vault IDs are short and a released ID is a squattable namespace. If somebody still holds a read key pointing at that ID, a new vault claiming it would be answering reads meant for the old one. `purge:true` skips the tombstone and frees the ID — use it only when you are sure no credential survives.

## The caching contract

Anyone writing a client needs this, and getting it wrong produces a bug that looks like corruption:

| Object | Response header |
|---|---|
| File ID containing `-imm-` — immutable, content-addressed | `Cache-Control: public, max-age=31536000, immutable` |
| Refs and indexes — mutable | `Cache-Control: no-store` |

Immutable objects are content-addressed, so their bytes can never change and a year-long cache is safe — which is what lets a vault sit behind a CDN. Mutable refs must never be cached: a stale ref renders a previous commit’s tree from ciphertext that is itself perfectly valid, so nothing errors and the reader simply sees the wrong version of the vault.

## Storage layout

```
bare/data/obj-cas-imm-{hex}     blobs, trees, commits — content-addressed, immutable
bare/keys/key-rnd-imm-{hex}     PKI public keys — immutable
bare/refs/                      branch refs — mutable
bare/indexes/                   branch index — mutable
bare/append/                    append lanes — managed, outside the commit DAG
```

The prefixes are load-bearing. `obj-cas-imm-` is SHA-256 over the *ciphertext*, which gives deduplication without the server knowing any plaintext, and makes the caching rule above derivable from the ID alone. Append lanes sit outside the commit DAG on purpose — a message arriving does not rewrite your history.

This site is itself served from a vault, so these are the objects behind the page you are reading. The [live-vault case study](../case-studies/live-vault-docs.md) shows the fetch sequence.

## See also

- [Append lanes](append-lanes.md) — the write-only channel that does not touch the commit tree
- [Errors and limits](errors.md)



==============================================================================
# API: append lanes — sgit.ai

> The six append endpoints — the write-only vault-to-vault message transport. Four separated capabilities, the blind write response, server-assigned sortable filenames, idempotent mark-processed, and the limits.
>
> Page: https://sgit.ai/api/append-lanes.html

[Home](../index.md) / [API](index.md) / Append lanes

# Append lanes

A write-only channel attached to a vault, gated by a token the writer holds and nothing else. This is the transport behind [vault-to-vault messaging](../docs/vault-messaging.md) and behind [`sg.append`](../vault/sg-bridge.md) in the browser bridge — and it is deliberately generic: the same primitive carries messages, logs, signals, control messages and state flows.

**Naming.** This API was called **inbox** before v0.32.7. Every `/api/vault/inbox/*` URL is gone, and `purge` takes `folder:"pending"` or `"processed"` — the old `"inbox"` value returns **400**. If you are reading older material, translate.

## The six endpoints

All **POST**, all under `/api/vault/append/`.

| Path | Gate | Does |
|---|---|---|
| `configure/{vault_id}` | `x-sgraph-vault-write-key` | Registers `append_anchors` — hashes of accepted senders — and `enum_key_hash` |
| `write/{vault_id}` | `append_token`**in the body** | Appends a payload. **Account-less**: no access token required |
| `list/{vault_id}` | `x-sgraph-vault-enum-key` | Paginated listing, optionally with inline content |
| `fetch/{vault_id}` | enum key | Fetch specific file IDs, batched |
| `mark-processed/{vault_id}` | enum key | Moves pending → processed. Idempotent |
| `purge/{vault_id}` | write key | Deletes. `folder: "pending" | "processed"` |

## Why the gates are split this way

Four capabilities, and the split is the whole design:

| Capability | Holder | Can | Cannot |
|---|---|---|---|
| `append_token` | the sender | write | list, fetch, read anything |
| `enum_key` | the vault owner | list, fetch, mark-processed | write, purge |
| `write_key` | the vault owner | configure, purge | — |
| private key | the vault owner | **decrypt** | *never sent to the server* |

A sender can put something into your vault and learn nothing at all — not the contents, not the volume, not whether anyone else writes there. The server stores `SHA-256` of the first three capabilities and compares hashes; the fourth it never sees.

## Four contracts worth relying on

- **The write response is blind.** `/write` returns exactly `{"ok": true}` — no file ID, no count, no metadata. This is a security property, not an oversight: a returned ID would leak lane state to a party who is only allowed to write.
- **Filenames are server-assigned** as `{epoch_ms:013d}_{24-hex}.enc`. Being chronologically sortable is what makes cursor pagination stable — pass the last file ID you saw as `after_file_id`.
- **Metadata-only listing is free.** `include_content: false` reads **zero** payloads. Poll with it, then fetch on demand; polling with content is the common way to hit the 3 MB ceiling for no reason.
- **mark-processed is idempotent.** An already-moved file comes back in `missing` rather than as an error, so retrying a batch after a timeout is safe.

## Several senders on one vault

Register several `append_anchors` and each sender writes into their own lane, distinguished by their token. A listing can be scoped to one lane, so one correspondent flooding you does not bury another — and revoking one sender is removing one anchor, with no effect on the rest.

## Limits and codes

| Limit | Value | On breach |
|---|---|---|
| Payload per write | 5 MB | 413 |
| Pending files per token | 1000 | 507 |
| File IDs per batch | 100 | 400 |
| Inline content when listing | 3 MB cumulative | 413 |
| Page size | 50 default, 200 max | clamped silently |

The `append_token` pattern is `^[0-9a-f]{16,128}$` — hex only. A prefixed token returns **400**, not 403; see [errors](errors.md) for why that distinction saves time.

## See also

- [Vault messaging](../docs/vault-messaging.md) — this API composed with PKI into a worked example
- [`sg.append`](../vault/sg-bridge.md) — the same six operations from a vault app
- [Errors and limits](errors.md)



==============================================================================
# API errors and limits — sgit.ai

> 400, 403, 413 and 507: what each means, why a malformed token returns 400 rather than 403, the input patterns enforced before storage is reached, and every documented ceiling.
>
> Page: https://sgit.ai/api/errors.html

[Home](../index.md) / [API](index.md) / Errors and limits

# Errors and limits

Four status codes carry almost all the failures, and telling them apart saves real debugging time — particularly 400 versus 403, which fail for opposite reasons.

## Status codes

| Code | Means | What to do |
|---|---|---|
| **400** | Invalid input — the value never reached a gate. Malformed token, malformed file ID, batch too large, unknown `folder` value | Fix the *shape* of what you sent. Your credential may be perfectly valid |
| **403** | Gate failure — well-formed input, wrong capability | Fix the *credential*. The request shape was fine |
| **413** | Too large — payload over 5 MB, or an inline-content listing over the 3 MB ceiling | Split the payload, or list without inline content and fetch on demand |
| **507** | Lane full — 1000 pending files for that token | Fetch and `mark-processed`, then `purge` the processed folder |

**The 400 that looks like a 403.** Path and token components are validated by typed primitives *before* they reach storage, which is how path traversal is blocked at the type level. A prefixed token such as `tok_abc…` — or a CLI fingerprint pasted straight in, `sha256:a461…` — fails the hex-only pattern and returns **400**. It reads like a rejected credential; it is a rejected string. Use raw hex.

## Input patterns

| Input | Pattern |
|---|---|
| `append_token` | `^[0-9a-f]{16,128}$` — hex only, no prefix |
| `file_id` (append) | `^\d{13}_[0-9a-f]{24}\.enc$` — server-assigned, so you should be echoing one back |
| `vault_id` | lowercase alphanumeric, 8–24 characters, no hyphens |

## Limits

| Limit | Value | On breach |
|---|---|---|
| Payload per append write | 5 MB | 413 |
| Pending files per append token | 1000 | 507 |
| File IDs per batch (fetch / mark / purge) | 100 | 400 |
| Operations per `/vault/batch` request | 100 | 400 |
| Inline content when listing | 3 MB cumulative | 413 |
| Append list page size | 50 default, 200 max | clamped silently |
| `read-base64` response | ~3.75 MB | use [presigned reads](vault-objects.md) above this |

The page-size clamp is silent: ask for 500 and you get 200 with no warning. Page with `after_file_id` rather than assuming your requested size was honoured.



==============================================================================
# Sending messages between vaults — sgit.ai

> How two vaults exchange encrypted messages without sharing a vault key and without the sender holding an account: append lanes addressed by a token, composed with PKI. Worked example in CLI, curl and sg.append, with the one step that is not yet wired marked PROPOSED.
>
> Page: https://sgit.ai/docs/vault-messaging.html

[Home](../index.md) / [Docs](index.md) / Vault messaging

# Sending messages between vaults

Two vaults can exchange encrypted messages without sharing a vault key, without the sender having an account, and without the server ever being able to read anything. The mechanism is an **append lane**: a write-only channel attached to a vault, addressed by the hash of a public key.

**Why this page exists.** Both halves of this capability were already documented — the transport as [`sg.append`](../vault/sg-bridge.md), the crypto as [`sgit pki`](pki.md) — on pages that never referenced each other. An agent asked how to send a message between vaults, found both halves, and could not find the sentence that says they combine. This is that sentence, written out.

## The shape of it

```
   SENDER                        SERVER                      RECIPIENT
   ──────                        ──────                      ─────────
   has: your public key          stores: ciphertext          has: private key
                                         + hashes of keys          + enum_key

   encrypt(msg, your_pubkey)
   append_token = H(pubkey)
        │
        │  POST /api/vault/append/write/{vault_id}
        │  { append_token, payload }
        ├────────────────────────▶  gate: H(append_token) ∈ append_anchors?
        ◀────────────────────────  { "ok": true }   ← blind: no id, no count
                                          │
                                          │   POST /append/list      (enum_key)
                                          ◀──────────────────────────┤
                                          │   POST /append/fetch     │
                                          ├─────────────────────────▶│ decrypt locally
                                          │   POST /append/mark-processed
                                          ◀──────────────────────────┤
```

**What the server can see:** that a lane received something, how big it was, and when. **What it cannot see:** the content, or the recipient’s private key, which never leaves their machine.

## Four capabilities, deliberately separated

This is the part worth understanding, because it is why a sender cannot read the lane they write to:

| Capability | Who holds it | Can | Cannot |
|---|---|---|---|
| `append_token` | the sender | write | list, fetch, read anything |
| `enum_key` | the vault owner | list, fetch, mark-processed | write, purge |
| `write_key` | the vault owner | configure, purge | — |
| private key | the vault owner | **decrypt** | *never sent to the server* |

The server stores `SHA-256` hashes of the first three and checks `H(presented) == stored`. It never holds a raw capability key, and never holds a private key at all. Compromising the server yields hashes and ciphertext.

Read in the [privilege vocabulary](../compare/index.md) the comparison pages use: the sender’s capability is **scoped** to one operation on one lane, **bearer**-held, and **observable** to the owner but not to the sender. A write-only credential that cannot read its own effects is an unusually clean shape.

## Setting up a lane — recipient, one-time

Have a keypair and publish the public half ([full lifecycle here](pki.md)):

```
$ sgit pki keygen --label "My Vault Identity"
$ sgit pki export sha256:a4615402a0bc23ac > my-identity.json
```

Then register, against your vault, the hash of the sender’s lane address and the hash of your enumeration key:

```
$ curl -X POST https://send.sgraph.ai/api/vault/append/configure/$VAULT_ID \
    -H "x-sgraph-vault-write-key: $WRITE_KEY" \
    -H "Content-Type: application/json" \
    -d '{"append_anchors":["<sha256 of the append_token>"],
         "enum_key_hash":"<sha256 of your enum_key>"}'
```

`configure` patches an existing vault manifest — it does not create a vault. A 403 means the vault ID or the write key is wrong.

## Deriving the lane address — read this before writing code

**This step is not yet wired end to end, and the gap is worth stating precisely.**
 The design is `append_token = H(recipient public key)`, so a sender can compute your lane address from the public bundle you gave them, with no extra coordination. That is an elegant property and it is the intended model.

 What ships today on **sgit v0.15.0**: `sgit pki export` emits a **JSON bundle** containing two PEM blocks, a label and two fingerprints — *not* a bare public key. No shipped command emits the append token, and hashing the bundle file is not a defined derivation (field order and whitespace would change the answer). The **server** side of append lanes is code-verified and shipped; the **client** derivation that turns a public key into a lane address is **PROPOSED**.

**What to do meanwhile:** treat `append_token` as an opaque 64-hex secret you agree out of band — generate one, hand it to your sender, register its SHA-256 as an `append_anchor`. Everything else on this page works today. When the derivation lands, the token stops needing to be exchanged; nothing else changes.

Two format rules that cause avoidable failures:

- The token pattern is `^[0-9a-f]{16,128}$` — **hex only**. A prefixed token like `tok_abc…` returns **400**, not 403, because it fails input validation before it reaches any gate.
- CLI fingerprints are printed as `sha256:a4615402a0bc23ac`. That `sha256:` prefix is part of the CLI identifier and is **not** part of a token. Pasting a fingerprint straight in is the most likely way to hit that 400.

## Sending

```
# 1. encrypt to the recipient's public key (RSA-OAEP 4096 + AES-256-GCM, client-side)
$ sgit pki encrypt message.txt --recipient sha256:a4615402a0bc23ac
Encrypted to message.txt.enc

# 2. append it to their lane
$ curl -X POST https://send.sgraph.ai/api/vault/append/write/$THEIR_VAULT_ID \
    -H "Content-Type: application/json" \
    -d '{"append_token":"'$APPEND_TOKEN'","payload":"'$(base64 -w0 message.txt.enc)'"}'
{"ok": true}
```

**No account is needed to send.** The write endpoint requires no access token — the `append_token` is the whole gate. That is deliberate: somebody can send to your vault without holding a credential on the platform at all.

The response is **blind by design**: exactly `{"ok": true}`, with no file ID, no count and no metadata. A sender cannot learn what else is in the lane, or even whether theirs was the first write.

## Receiving

Poll cheaply first — a metadata-only listing reads **zero** payloads:

```
$ curl -X POST https://send.sgraph.ai/api/vault/append/list/$VAULT_ID \
    -H "x-sgraph-vault-enum-key: $ENUM_KEY" \
    -H "Content-Type: application/json" \
    -d '{"include_content": false}'
```

Filenames are server-assigned as `{epoch_ms}_{24-hex}.enc`, so they sort chronologically — which is what makes cursor pagination stable. Page with `after_file_id` set to the last ID you saw.

```
$ curl -X POST .../append/fetch/$VAULT_ID -H "x-sgraph-vault-enum-key: $ENUM_KEY" \
    -d '{"file_ids":["1755302400000_a3f8….enc"]}'

$ sgit pki decrypt message.txt.enc --fingerprint sha256:a4615402a0bc23ac

$ curl -X POST .../append/mark-processed/$VAULT_ID -H "x-sgraph-vault-enum-key: $ENUM_KEY" \
    -d '{"file_ids":["1755302400000_a3f8….enc"]}'
```

`mark-processed` is idempotent — a file already moved comes back in `missing` rather than as an error, so a retried batch is safe.

## From inside a vault app

The same transport through the browser bridge, with no HTTP of your own (see [`sg.append`](../vault/sg-bridge.md)):

```
await sg.append.configure({ appendAnchors: [anchorHash], enumKeyHash });
await sg.append.write({ appendToken, payload });            // blind
const { entries } = await sg.append.list({ includeContent: false });
const { files }   = await sg.append.fetch({ fileIds });
await sg.append.markProcessed({ fileIds });
await sg.append.purge({ folder: 'processed' });
```

## Practical notes

- **Limits.** 5 MB per message (**413**) · 1000 pending files per token (**507**) · 100 file IDs per batch (**400**) · 3 MB inline-content ceiling when listing with content (**413**) · list page size 50 by default, 200 max, clamped silently.
- **Several senders.** Register several `append_anchors`. Each sender writes to their own lane, so a listing can be scoped to one of them.
- **Housekeeping.** `purge` with `folder:"processed"` and no file IDs clears a whole lane’s processed set in one call. It takes `"pending"` or `"processed"` — the older `"inbox"` value now returns 400.
- **The API was renamed.** `inbox` became `append` in v0.32.7; any `/api/vault/inbox/*` URL is gone.

## What this is not

Not a chat protocol, not a queue with delivery guarantees, and not anonymous — the server sees lane activity and timing even though it cannot read content. It is a **generic append-only transport**: the same primitive carries logs, signals, control messages and state flows between agents. The client decides what the bytes mean.

## See also

- [API — append lanes](../api/append-lanes.md): the six endpoints, gates, limits and status codes
- [PKI](pki.md): keypair lifecycle, verified against the shipped CLI
- [`sg.append`](../vault/sg-bridge.md): the same transport from a vault app
- [Security model](../security/index.md#pki): where the keypair sits relative to the symmetric vault key



==============================================================================
# Keys, signatures and encrypting to someone else — sgit.ai

> The keypair lifecycle run end to end on the shipped CLI: RSA-OAEP 4096 encryption, ECDSA P-256 signing, the JSON public-key bundle, the hybrid envelope format, and what PKI does not do yet.
>
> Page: https://sgit.ai/docs/pki.html

[Home](../index.md) / [Docs](index.md) / PKI

# Keys, signatures and encrypting to someone else

The vault key is symmetric and opens the whole vault. A keypair does the two things it cannot: prove *who* wrote something, and encrypt to somebody who holds no vault key at all. This page is the lifecycle, run end to end on the shipped CLI.

**Everything below was executed, not recalled.** Every command, every output shape and every construction on this page came from running `sgit pki` on **v0.15.0** in a throwaway home directory. Where the behaviour differs from what you might expect — and in two places it does — the page says so.

## What sgit actually generates

`sgit pki keygen` creates **two** pairs at once, and prints two fingerprints:

| Purpose | Construction | Identifier |
|---|---|---|
| Encryption | **RSA-OAEP, 4096-bit** | `fingerprint` |
| Signing | **ECDSA P-256** | `signing_fingerprint` |

Encryption is **hybrid**, which is what makes it usable on files of any size: a fresh AES-256-GCM content key encrypts the payload, and RSA-OAEP wraps that content key. The same AES-256-GCM primitive as the rest of the vault — the keypair only changes how the content key gets to the recipient.

Note for anyone integrating against a spec rather than the binary: this is **RSA-OAEP and ECDSA**, not X25519/Ed25519. Draft material describing an X25519 sealing layer describes a design, not what v0.15.0 ships.

## The lifecycle

### 1 · Generate

```
$ sgit pki keygen --label "My Vault Identity"
Enter passphrase to protect private keys:

Generating RSA-4096 encryption key... done

Key pair created:
  Label:                My Vault Identity
  Encryption:           RSA-OAEP 4096-bit
  Signing:              ECDSA P-256
  Fingerprint:          sha256:a4615402a0bc23ac
  Signing fingerprint:  sha256:69d9b4835ccf790c
```

**Keygen prompts for a passphrase** and will not proceed without one — private keys are encrypted at rest. In a script, feed it on stdin; with no terminal at all it exits with an `EOFError` rather than silently generating an unprotected key, which is the right failure.

RSA-4096 generation is not instant. Expect a pause.

### 2 · Publish the public half

```
$ sgit pki list
  sha256:a4615402a0bc23ac  My Vault Identity  (RSA-OAEP 4096)

$ sgit pki export sha256:a4615402a0bc23ac > my-identity.json
```

**Export produces a JSON bundle, not a PEM file.** It carries both public keys, both fingerprints and the label:

```
{
  "v": 1,
  "encrypt": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkq…",
  "sign":    "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQ…",
  "label":   "My Vault Identity",
  "fingerprint":         "sha256:a4615402a0bc23ac",
  "signing_fingerprint": "sha256:69d9b4835ccf790c"
}
```

The bundle contains no private material. Publish it, mail it, commit it, put it on your website.

### 3 · Import someone else’s

```
$ sgit pki import their-identity.json
Imported contact: Their Label
  Fingerprint: sha256:…

$ sgit pki contacts
  sha256:…  Their Label
```

### 4 · Encrypt to them, and decrypt what they send you

```
$ sgit pki encrypt message.txt --recipient sha256:a4615402a0bc23ac
Encrypted to message.txt.enc

$ sgit pki decrypt message.txt.enc --fingerprint sha256:a4615402a0bc23ac
Enter passphrase:
Decrypted to message.txt
```

Round trip verified. Two argument details that will bite you once each: `encrypt` takes `--recipient` (a contact’s fingerprint) and an optional `--fingerprint` for *your* signing key; `decrypt` requires `--fingerprint` — it will not guess which of your keys to try.

### 5 · Sign and verify

```
$ sgit pki sign report.pdf --fingerprint sha256:69d9b4835ccf790c
$ sgit pki verify report.pdf report.pdf.sig
```

Detached signatures, so the signed file is unchanged. Signing uses the *signing* fingerprint, which is the second one keygen printed.

## The envelope on the wire

An encrypted file is base64 over a small JSON object — worth knowing if you are writing an interoperable client:

| Field | Contents | Observed size |
|---|---|---|
| `v` | Envelope version — `2` on v0.15.0 | — |
| `w` | The AES content key, wrapped with RSA-OAEP to the recipient | 512 bytes (4096-bit) |
| `i` | AES-GCM IV | 12 bytes |
| `c` | Ciphertext with its GCM tag | plaintext + 16 |

A 37-byte plaintext produced a 1,076-byte file: the RSA-wrapped key dominates, so this is efficient for large payloads and heavy for tiny ones.

## Where public keys live in a vault

Vaults carry public PKI keys as immutable objects at `bare/keys/key-rnd-imm-*`, alongside the content store at `bare/data/obj-cas-imm-*`. They are public by construction, so nothing there needs protecting — which is exactly why a lane addressed by a public key can be written to by a stranger.

## What this is for

Signing and encrypting files is useful on its own. The larger use is [**vault-to-vault messaging**](vault-messaging.md): your public key becomes an address a stranger can write to, and your private key is the only thing that can read what arrives. That page composes this one with [append lanes](../api/append-lanes.md).

## What this does not do yet

- **No key revocation or rotation workflow.** There is no CRL, no expiry, no `sgit pki revoke`. If a private key is compromised, you generate a new pair and redistribute the bundle out of band.
- **No web of trust and no directory.** Fingerprint verification is your problem — compare out of band, exactly as with SSH host keys.
- **Fingerprints carry a `sha256:` prefix.** That prefix is part of the CLI identifier, not part of any hash you might need elsewhere. See the [addressing note](vault-messaging.md#addressing) — it is a live source of confusion.
- **Signing and encryption are separate keys.** Passing the wrong fingerprint to the wrong verb fails; it does not fall back.

Honest edges belong on [the limitations page](limitations.md) too, and these are listed there.



==============================================================================
# Updates — sgit.ai

> What changed on sgit and on this site, as it happens — one entry per story rather than per release, each linked to the release that carries it. RSS and JSON feeds included.
>
> Page: https://sgit.ai/updates/index.html

# Updates

What changed on sgit and on this site, as it happens — one entry per story rather than per release. The [version log](../admin/versions.md) is the complete technical record; this is the readable one.

Follow along: [RSS](feed.xml) · [JSON](updates.json). Every entry links to the release that carries it.

## 2026-08-20

### [The audit that stopped a publication — and the vault we built instead](#the-audit-that-stopped-a-publication) [v0.2.37](../admin/versions.md)

vaultssecuritypublishing

A vault arrived for publication: the **EU AI Act as a citable graph** — 113 articles, 1,523 nodes, 1,944 edges, every node traced to hash-verified source bytes. Good demo, obvious yes.

It did not ship. The audit step — *open every file with the exact credential you are about to publish* — found a **live vault key in plaintext**, inside a handoff document, granting write access to a **different** vault. Publishing the read key would have handed that away to anyone who read the page.

- **Deleting the file would not have been enough.** Vault objects are content-addressed and immutable, so a credential committed once may stay reachable from history. The only clean remedy is history that never contained it.
- **So there is a new vault.** Same 206 files, two credentials redacted in place with visible `<VAULT-KEY-REMOVED>` markers rather than silent deletions, plus a `PUBLIC.md` stating what changed and why.
- **Re-audited from a fresh read-key clone**: 205 text files, zero findings. That is [Regulation Graph](../demos/vaults/regulation-graph/index.md), and it is live.

One rule got verified rather than assumed. The vault's Graph REPL is an LLM chat, and its code looks for an OpenRouter key at `/key.json` *inside the vault* before falling back to device storage — so a shipped key would be an open tab on somebody else's budget. There is no `key.json`, confirmed in the read-key clone. Bring your own key; nothing metered ships.

The rule that caught all of this came from the [Risk Graph Explorer](../demos/vaults/risk-graph-explorer/index.md) vault's own `PUBLIC.md`, not from us. It has now paid for itself.

### [A third sibling site — one that says, at the top of every page, that it does not exist](#a-third-sibling-site-that-says-it-does-not-exist) [v0.2.38](../admin/versions.md)

networkedgesecurity

[sg-sentinel.sgit.ai](../network/sg-sentinel.md) joins [the network](../network/index.md). It is a design for an app-coupled edge guard that replaces rented AWS WAF plus CloudWatch and Firehose with a layer you own — and its status pill reads `NOT BUILT` where its siblings read `MVP DRAFT`.

- **The inversion is the idea.** A generic WAF is blind to the app it protects, so it denylists known-bad and passes the rest. If you control both client and server, the edge knows the valid request space — so it can **allowlist**, and no invalid request reaches the origin.
- **One correction reshaped the design**, and it is stated as a governing constraint: *"Layer 1 never acts and never writes — it only decides and signals. Layer 2 is the sole actor and the sole I/O owner."* The reason is physical: a CloudFront Function has no network and no filesystem. The site names the earlier version — where L1 blocked inline — as a category error of its own making.
- **Rules are the engine, not configuration on it.** Six deterministic rules, each a pure function, each mapped to an ATT&CK technique, run in order with first-block-wins. The prototype ran the same engine across three targets with a parity matrix asserting identical decisions.
- **And it bounds its own evidence.** The prototype's testing manual reports 149 passing tests; the site immediately says *"not deployed anywhere, not in production use, not maintained, and not packaged for you to install."*

It is the third site here to publish a design **before** the thing exists — after [pki.sgit.ai](../network/pki.md)'s four registry rules. Same wager: publishing the design now is cheap, claiming it afterwards is impossible.

Adding it took one markdown file and three screenshots. The renderer gained pipe-table support on the way, since the six-rule core wanted a table and got a paragraph of vertical bars instead.

## 2026-08-19

### [The first two sibling sites, with screenshots](#the-first-two-sibling-sites) [v0.2.36](../admin/versions.md)

networkidentitypki

Two focused sites now run on `*.sgit.ai` subdomains, and [a network section](../network/index.md) covers both — what each argues, why it is relevant here, and screenshots of the real pages.

- **[nhi.sgit.ai](../network/nhi.md)** splits "how do I give my agents an identity?" into **agents you run** and **agents you rent**, and shows that everything on the market answers only the first. For rented agents — the ones in Claude, Codex, behind an API — the honest current answer is to hand over a broad credential and hope. Its sharpest idea is that **the real authorization is the closure**: inbox access is every account resettable by email.
- **[pki.sgit.ai](../network/pki.md)** designs a key registry from the 2019 keyserver catastrophe, publishing four rules **before the registry exists** so they stay checkable. The resolution it reaches is worth borrowing: append-only is safe when a writer appends only to objects it *owns*, and fatal when anyone may append to somebody else's. The rule to carry forward is not "append-only" — it is *the writer owns what it writes*.

Both connect directly to work here. Read keys and [append lanes](../api/append-lanes.md) are credentials with a provably bounded closure, which is the nhi problem stated as a mechanism; and an append lane is owner-configured, which is pki's rule 1 already shipped in another corner of the system.

More subdomains are coming. Adding one to this site is now writing a single markdown file and capturing its screenshots — the index, the cards and the page are all derived.

## 2026-08-18

### [Verify the fix pack, not just the bug](#verify-the-fix-pack-not-just-the-bug) [v0.2.34](../admin/versions.md)

processpkiaccuracy

The documentation gap above arrived as a well-built fix pack from the SG/API team: a gap analysis, code-verified source material, and a draft of the missing page. The most valuable line in it was its own instruction to check the claims before publishing. **Three did not survive.**

- **"The security page actively denies PKI."** It did not. A sweep for *symmetric*, *asymmetric*, *public key*, *PKI* and *keypair* returned zero occurrences. The page was silent, not wrong — and publishing a correction for a claim we never made would have put a false statement in our own changelog.
- **"Search the site for stale `inbox` naming."** There is none. Two hits, both ordinary English; no `/api/vault/inbox/*` path anywhere.
- **"Seal to the recipient's X25519 key."** Not what ships. Running `sgit pki keygen` prints **RSA-OAEP 4096-bit** and **ECDSA P-256**. Publishing the draft as written would have told integrators to build against the wrong primitive.

Two more corrections came from running the CLI rather than reading about it: `sgit pki export` emits a **JSON bundle** of two PEM blocks, not the `.pem` file the draft redirected into — so the draft's `sha256sum public-key.pem` derivation of a lane address is not well defined — and `keygen` requires a passphrase, which no draft step mentioned.

The whole exchange, including what we got wrong, is on [the briefs page](../briefs/index.md).

### [The API reference we did not have](#the-api-reference-we-did-not-have) [v0.2.34](../admin/versions.md)

apimessagingdocs

An agent was asked how to send an encrypted message between two vaults. It read this site and could not find out. The capability had shipped months earlier.

The diagnosis was uncomfortable and simple: **we documented both halves and never wrote the sentence that joins them.** The transport was on one page as `sg.append`, the crypto on another as `sgit pki`, and neither referenced the other. There was also no HTTP API reference anywhere — awkward for a project whose whole argument is that the API *is* the surface.

- **[Sending messages between vaults](../docs/vault-messaging.md)** is the page that was missing: append lanes composed with keypairs, worked end to end in CLI, curl and `sg.append`.
- **[An /api/ section](../api/index.md)** now exists — [authentication](../api/authentication.md), [vault objects](../api/vault-objects.md), [append lanes](../api/append-lanes.md) and [errors](../api/errors.md).
- **[The PKI page](../docs/pki.md)** documents the keypair lifecycle, run against the shipped CLI rather than recalled.
- **[The security page](../security/index.md#pki)** gained the asymmetric layer it never mentioned. It never claimed sgit had no public-key layer — it simply said nothing, and on a page like that one, silence reads as denial.

The one step that is not wired end to end is labelled **PROPOSED** with an interim recipe, rather than quietly documented as working.

## 2026-08-17

### [Three walkthroughs, read back as documents](#three-walkthroughs-read-back-as-documents) [v0.2.32](../admin/versions.md)

vaultsvideorisk-graph-explorer

A video is invisible to a search engine, to `llms-full.txt`, and to any agent reading this site as documentation. It is also full of *"this guy here"* and *"look at this"* — pointing that a transcript cannot resolve.

So [the Risk Graph Explorer walkthroughs](../demos/vaults/risk-graph-explorer/videos/index.md) now carry the player at the top and **the same session read back underneath**: fifteen moments, each a timestamp that deep-links into the video, the frame the screen was showing then, and what is actually happening in it.

- Nine frames come from a narrated-review export; the other six were captured from the **live vault** with its published read key, driven to the exact state being described.
- What the frames turned up is most of the value, because none of it is audible: negative answers draw **named edges** (`never-exercised-on`, `absent-for`) rather than silence; "no egress" draws a single assurance-coloured edge in a field of amber; and every risk ships with a **"ceases when any of these hold"** list — its own falsification condition, cited to facts.

The [seven views page](../demos/vaults/risk-graph-explorer/views/index.md) covers the same vault view by view.

### [Printing stopped costing every reader](#printing-stopped-costing-every-reader) [v0.2.31](../admin/versions.md)

printperformance

Save a walkthrough page as a PDF and it used to come out wrong in two ways: the site navigation painted **across the middle of page 2**, translucent, with the prose showing through it — and any screenshot you had not scrolled past exported as a blank gap.

The first was a sticky header: Chrome paints a sticky box once, wherever it happens to fall in the paginated flow. The second was subtler. Screenshots load lazily, and `loading="lazy"` defers the **decode**, not just the download — so an image far below the viewport sat there fetched, at zero width, and printed as nothing.

- The first fix made every reader pay: it pre-loaded all the images so printing would work. That was the wrong trade and it was rejected.
- **The bypass now fires only on print** — on `beforeprint`, and on the Cmd/Ctrl-P keystroke, which lands a few hundred milliseconds earlier and buys the images a head start.
- Measured on a page nobody scrolled: **1 image loaded while reading, 9 of 9 in the PDF.**

Also in this release: `@page` margins, colour preservation so the amber/green distinction survives, `break-inside` rules so a caption is never stranded on the page after its picture, and per-release cache-busting on assets — because for ten minutes after every release, returning readers were running new HTML against old CSS.

### [Green does not mean live](#green-does-not-mean-live) [v0.2.33](../admin/versions.md)

cideployprocess

Two consecutive releases pushed cleanly, reported success, and **never reached the site.** A human noticed on a phone, forty minutes later, because the version badge still showed the old number.

The release script verified that both remotes were in sync — and they were. The failure was in a job neither remote knows about: GitHub Pages could not download `actions/configure-pages`, got a **429 Too Many Requests**, and the deploy died in "Set up job" before running a single step. Validation passed. Tagging passed. The site served a two-release-old page.

- **A release now ends by asking the live site what version it is serving**, polling with a cache-buster until the badge matches — and **aborting loudly** if it never does.
- The cost is up to eight minutes per release. The alternative, demonstrated twice in one afternoon, is telling somebody a fix is live when it is not.
- Same principle as the rules already in the build: a page nothing links to, a page the index omits, and a page the deploy never published are all equally unpublished.

There is a longer account of this one in [Green does not mean live](../articles/green-does-not-mean-live.md).



==============================================================================
# Articles — sgit.ai

> Longer pieces that make an argument across several pages: what a thing means, why it is shaped that way, and what it cost to find out. Each links to the pages that own its facts rather than restating them.
>
> Page: https://sgit.ai/articles/index.html

# Articles

Longer pieces that make an argument across several pages — what a thing means, why it is shaped that way, and what it cost to find out. Shorter, dated notes on individual changes are in [updates](../updates/index.md).

**Two rules keep these from going stale.** An article never restates a fact it does not own — it links to the page that does, so when the fact changes the article does not start lying. And an article that makes a testable claim links to the test, the same way [the comparison pages](../compare/index.md) do.

[**Seven vaults, one method**2026-08-19Publishing seven encrypted vaults in a fortnight turned an ad-hoc process into a repeatable one. Every rule in it exists because something went wrong first — including three vault keys submitted for publication that would have handed the world write access.vaultspublishingmethod](seven-vaults-one-method.md) [**Green does not mean live**2026-08-17Two releases pushed cleanly, reported success, and never reached the site. Every check we had was green, because the failure happened in a place none of them could see. What we changed, and the general rule underneath it.cideployverification](green-does-not-mean-live.md)



==============================================================================
# The sgit.ai network — sibling sites

> Focused sites on *.sgit.ai subdomains, each pursuing one question further than a section here could: non-human identity for rented agents, and a key registry designed from the 2019 keyserver failure. Screenshots of each, with what it argues and why it is relevant.
>
> Page: https://sgit.ai/network/index.html

# The sgit.ai network

Focused sites on `*.sgit.ai` subdomains, each taking one question further than a section here could. They share this site's design and its discipline — sourced claims, stated status, honest edges — and they publish their arguments before the things they describe exist, so the commitments stay checkable.

3 live. Screenshots are of the real sites, captured on the date each entry gives.

[**nhi.sgit.ai**Agents you run, agents you rent, and the identity gapThe question of how to give an AI agent an identity splits into two populations, and every product on the market answers only the first. For the agents you actually name — the ones running in Claude, Codex or behind an API — the honest current answer is to hand over a broad credential and hope.](nhi.md)
identityagentssecurity[What it argues →](nhi.md) · [Open nhi.sgit.ai ↗](https://nhi.sgit.ai)

[**pki.sgit.ai**A key registry for agents, designed from a documented failureGood public key repositories existed and were destroyed. This site is the 2019 keyserver catastrophe, the four registry rules it produces, and the build order — all published before the registry exists, so the commitments are checkable against whatever eventually ships.](pki.md)
pkiregistryhistory[What it argues →](pki.md) · [Open pki.sgit.ai ↗](https://pki.sgit.ai)

[**sg-sentinel.sgit.ai**An app-coupled edge guard — Layer 1 decides, Layer 2 actsA design for an edge security and logging layer you own rather than rent, built on the observation that your own app already knows what a valid request looks like — so the edge can allowlist rather than denylist. Published as a complete design that has deliberately not been built.](sg-sentinel.md)
edgesecuritydesign[What it argues →](sg-sentinel.md) · [Open sg-sentinel.sgit.ai ↗](https://sg-sentinel.sgit.ai)

## Why they are separate sites

Each one is an argument that needs room and a reader who arrived for it. Splitting them out keeps this site about sgit while letting each question be pursued properly — and gives each its own version history, release cadence and repository. They are built from the same generator and hold to the same rules, so a reader moving between them is not changing register.



==============================================================================
# Regulation Graph — a published vault

> The EU AI Act as a citable graph: Regulation (EU) 2024/1689 parsed from official Formex XML, hash-verified to source bytes, 1,523 nodes and 1,944 edges across eleven views. Published as a redacted republication after an audit found a plaintext vault key in the original.
>
> Page: https://sgit.ai/demos/vaults/regulation-graph/index.html

[Home](../../../index.md) / [Vaults](../index.md) / Regulation Graph

# Regulation Graph

The EU AI Act as a graph you can cite. Regulation (EU) 2024/1689 parsed from official Formex XML, hash-verified against the bytes it came from, and served as an **evidence layer**: a risk in a register points at a named obligation in a real instrument instead of being asserted.

**This vault exists because the first one could not be published.** The original carried a live vault key in plaintext — write access to a *different* vault — inside a handoff document. Our audit found it before anything shipped. Deleting the file would not have been enough: vault objects are content-addressed and immutable, so a credential committed once may stay reachable from history. This is a **redacted republication with new history**, and the vault says so itself in its own [PUBLIC.md](#public).

**Open it yourself — the key is the whole credential.**
 Read key: `sgit_rk1_c004daae386e8d17fa648884acc527018bd4ea1116ad673fb2f1b068011695c9:73heuprz`
 In the official UI: [open it read-only in a new tab](https://dev.vault.sgraph.ai/#sgit_rk1_c004daae386e8d17fa648884acc527018bd4ea1116ad673fb2f1b068011695c9%3A73heuprz) · From the CLI: `sgit clone sgit_rk1_c004daae386e8d17fa648884acc527018bd4ea1116ad673fb2f1b068011695c9:73heuprz`
Published deliberately, and **derived** one-way from a vault key that is not published and never will be.

## See it live, here

Both surfaces open automatically below. You can also [**open the app in its own window ↗**](https://dev.vault.sgraph.ai/#sgit_rk1_c004daae386e8d17fa648884acc527018bd4ea1116ad673fb2f1b068011695c9%3A73heuprz) — the entry point is the Art 9 lab; the back-link top-left reaches the other ten views.

## What is in it

the overview

### Every number traces back to source bytes

The landing view states the shape of the graph in counts: **113 articles**, **500 paragraphs**, **417 points**, **180 recitals**, **13 annexes**, **68 definitions** — resolving to **1,523 nodes** and **1,944 edges**.

Underneath, the part that makes it evidence rather than a summary: two instruments composed into one view, each with its CELEX identifier and the **SHA-256 of the retrieved bytes**. Regulation 2024/1689 is shown as *amended by 2026/1744, no official consolidation yet — this graph composes*. That sentence is a factual claim about the state of EU law, and it is checkable.

Application dates are treated as **versioned properties, never bare facts**: superseded pre-Omnibus dates are struck through rather than overwritten, each carrying its basis (`Article 113(a) as amended`) and an as-of date.

Built from Formex XML retrieved from CELLAR, hash-verified, parsed deterministically.

browse the act

### The instrument itself, structure first

The full Act, navigable by its own structure, with a provenance footer on every node and search across the text. This is the view that makes the rest defensible: when a risk cites Article 9(2)(a), you can go and read Article 9(2)(a) — in the text that was parsed, not a paraphrase of it.

Per-node provenance footers, and search over the parsed text.

the graph

### Article-level relationships, with amendment halos

The citation graph at article level, drawn with Cytoscape, showing amendment halos and aggregated citations. Eleven views in total sit behind the top nav — including **SQL** (SQLite over sql.js, in memory, preset and free queries), **RDF** (rdflib, partition-separated predicates, Turtle export), **Concepts** (the Act's 68 defined terms with every usage linked) and **External refs** (every other EU instrument the Act cites, as an in-vault citation graph).

All of it runs client-side over the SG bridge. The vault is never written by the app.

Article-level graph; ten sibling views cover SQL, RDF, concepts and external citations.

the art 9 lab

### The entry point is an experiment, deliberately

`app.json` sets `entry` to `lab/index.html`, so opening the vault lands in the **Art 9 lab** — paragraph universes, a web-component folder explorer, provision graphs with reach profiles, and a **Graph REPL**: an LLM chat whose read-only tools drive the canvas.

The lab is marked *experimental* and has no main nav of its own; the back-link top-left returns to the other views. Landing a reader in the newest, least finished thing is an unusual choice and an honest one.

Opening the vault lands here: the Art 9 lab, marked experimental.

public.md

### The vault states its own publication rules

Following [Risk Graph Explorer](../risk-graph-explorer/index.md), this vault carries a `PUBLIC.md` declaring what it holds to — and, unusually, what was removed to make publication possible. The removals are visible to any reader as `<VAULT-KEY-REMOVED>` and `<READ-KEY-REMOVED>` markers rather than silently deleted lines.

**Rule 3 was verified rather than assumed.** The Graph REPL reads an OpenRouter key, and `lab/app/repl.js` looks for one at `/key.json` *inside the vault* before falling back to device storage. So we checked: no `key.json` exists — confirmed in a clone made with the published read key, which is what a reader actually gets. The REPL is bring-your-own-key, and nothing metered ships behind the published credential.

The rules, and the two removals, in the vault rather than only on this page.

## What it is for

The README states the purpose in one line: *"a risk in a register points at a named obligation in a real instrument instead of being asserted."* It is the evidence layer beneath the [Risk Mandate](../risk-mandate/index.md) work — where [a risk chain](../risk-graph-explorer/views/index.md) ends in `touches: EU AI Act Art. 12`, this is the vault that can say what Article 12 actually says and prove the bytes.

Its eight hard rules are worth reading in full, and two are worth quoting here:

- **Evidence, not compliance.** Never a claim that an organisation passes or fails. Not legal advice.
- **Provenance chain end to end:** claim → graph node → vault file → commit → official source (CELEX/ELI plus SHA-256 of retrieved bytes).

The second is the one this site keeps arriving at from other directions. It is the same instinct as [running comparisons as tests](../../../compare/index.md) and as [refusing to call a release live until the site serves it](../../../articles/green-does-not-mean-live.md): a claim is worth what its chain of custody is worth.

## What it does not do

- **Only Article 9 is built out in depth.** Rule 4 is *"partial connection is sufficient — build only what the register cites"*, so the lab covers Art 9 and the rest of the Act is present as structure and citations rather than fully annotated.
- **The Graph REPL needs your own OpenRouter key.** Nothing is supplied, deliberately. Without one the REPL pane is inert — which is the correct behaviour, not a fault.
- **No consolidated text exists.** 2024/1689 is amended by 2026/1744 with no official consolidation yet; this graph composes the two, and says so rather than presenting a merged text as authoritative.
- **External research is marked UNVERIFIED.** The research report under `docs/research/` carries external claims the vault has not itself checked, and labels them.

## How it was published

This vault is the clearest worked example of [the publishing method](../publishing.md), because it is the first one where the audit **stopped** a publication instead of clearing it:

1. **Classify the credential.** The submitted credential was a vault key, not a read key. The intake check refused it — the fourth time.
2. **Derive rather than refuse.** The read key was derived one-way; the vault key went to the gitignored tier the release tripwire scans for.
3. **Audit with the key about to be published.** 204 text files, read-key clone. One finding: a plaintext vault key for another vault.
4. **Stop.** No page was written. The finding was reported before anything else happened.
5. **Republish clean.** A new vault, new history, two credentials redacted in place with visible markers, a `PUBLIC.md` stating what changed, and a re-audit from a fresh read-key clone: **205 files, zero findings**.

The 370-plus bare 64-hex strings the audit flagged on the way through were all `sha256` provenance hashes — checked, not waved away. A scan that never produces a false positive is not scanning hard enough.



==============================================================================
# Seven vaults, one method — sgit.ai

> Publishing seven encrypted vaults in a fortnight turned an ad-hoc process into a repeatable one. Every rule in it exists because something went wrong first — including three vault keys submitted for publication that would have handed the world write access.
>
> Page: https://sgit.ai/articles/seven-vaults-one-method.html

[Home](../index.md) / [Articles](index.md) / Seven vaults, one method

# Seven vaults, one method

2026-08-19 · vaultspublishingmethod

Publishing seven encrypted vaults in a fortnight turned an ad-hoc process into a repeatable one. Every rule in it exists because something went wrong first — including three vault keys submitted for publication that would have handed the world write access.

Between 14 and 18 August this site published seven vaults. Each one is a real encrypted vault you can open in a browser from a read key printed on its page: [a photo gallery](../demos/vaults/algarve-may-2026/index.md), [field notes](../demos/vaults/field-notes/index.md), [a patient-held supplement record](../demos/vaults/supplement-stack/index.md), [a risk register](../demos/vaults/risk-mandate/index.md), [a browser-isolation risk graph](../demos/vaults/agentic-browser-isolation/index.md), [a fact-to-risk explorer](../demos/vaults/risk-graph-explorer/index.md), and [the catalogue that indexes them](../catalogue/index.md) — itself a vault.

By the third one it was obvious that we were repeating ourselves badly. By the seventh there was a method, and every rule in it exists because something went wrong first.

## The rule that matters most

**Classify the credential before it touches anything.**

Three of the seven vaults arrived as a *vault key* described as a read key. A vault key is write access. Publishing one would have handed anybody who read the page the ability to rewrite the vault — and because a vault key is also the address and the encryption root, there is no revocation, no rotation, and no undo.

They were caught by shape. A read key is 64 hex characters; a vault key is a generated passphrase, which is 24 lowercase alphanumerics. That catch depended on somebody looking, which is not a control. So it became [a script](../demos/vaults/publishing.md):

```

$ python3 admin/build/check_credential.py '<credential>'
  form      : vault key (legacy passphrase:vault_id)
  publish?  : NO
  why       : 24 characters before the colon and not 64 hex, so it is a
              passphrase — a WRITE credential

```

Exit 0 means publishable. Exit 1 means stop. It never echoes what it was given.

Behind it sits a second line: the release validator scans every tracked file for any key-shaped string and for the actual passphrases, read at build time from a gitignored tier. That tripwire has caught its own author three times — each time writing the prefix in prose, in documentation explaining what a write credential looks like. Which is the point: a rule that only catches other people is not a rule.

## Derive rather than refuse

The interesting part of the vault-key catch is what happens next. A read key is **derived one-way** from a vault key, so a submission that cannot be published can still become one that can:

```

c = Vault__Crypto()
pw, vid  = c.parse_vault_key(vault_key)
read_key = c.derive_keys(pw, vid)['read_key']

```

The vault key goes into a gitignored tier that the tripwire then scans for. The derived read key gets published. It is one-way: nobody can turn it back.

That is the whole shape of the thing this project is about — a capability you can hand over that is *strictly less* than the one you hold, with the reduction enforced by mathematics rather than by policy. The seven vaults span the range deliberately, from one that requests no permissions at all to one that can write a single folder.

## Audit with the key you are about to publish

Not with the vault key. With **exactly the credential a reader will have**, across every file.

This caught a real problem. One vault carried a sealed LLM credential, and a published read key in front of a metered capability is an open tab on somebody else's budget. Rather than reasoning about whether the sealing was sound, we took the published read key and attempted to open the credential with it. AES-GCM refused — `InvalidTag` — so no budget was exposed. Checked rather than assumed, and recorded either way.

That rule did not come from us. It came from the sixth vault, [Risk Graph Explorer](../demos/vaults/risk-graph-explorer/index.md), which is the first one here that was **public by design**: it carries its own `PUBLIC.md` whose three rules its build enforces, and the third — *no metered capability behind a published read key* — was not in our guidance. It is now.

## Capture evidence by driving the real product

Every screenshot on a vault page is taken by opening the actual vault in a real browser with the published read key, performing the navigation, and cropping the result. No mock-ups.

This is slower than it sounds and worth every minute, because it repeatedly disagreed with what we were about to write. The rig grew a `appProbe` step for exactly that reason — ask the running app what its elements are called instead of guessing and burning a capture run per guess:

```

probe [class*=node] -> 37
  shapes ["g.cnode.inh","g.cnode","g.cnode.corp"]
  text   ["R1 An autonomous system operates in the es","R2 Stopping the agent is itself…"]

```

The alternative is a page that describes a product as its author remembers it.

## Describe, show, then admit

Every vault page ends with what the vault does *not* do. Not as a disclaimer at the bottom in small type — as a section with the same weight as the features.

This is the part that is tempting to skip and never should be. A published vault is an argument that this way of working is sound; an argument that omits its own edges is a brochure. The [limitations page](../docs/limitations.md) is the same instinct at site level, and the [comparison pages](../compare/index.md) go further still — they include rows where vaults lose.

## What it cost, and what it bought

Seven vaults, roughly four days of work, and the method is now [written down as a playbook](../demos/vaults/publishing.md) aimed at another site's agent rather than at us — which was the real test of whether it was a method or just a habit.

The honest ledger:

- **Three vault keys caught.** None published. Each would have been unrecoverable.
- **One budget exposure checked and cleared**, by attempting the attack rather than reasoning about it.
- **One upstream rule adopted** from a vault that was stricter than our guidance.
- **Three bugs found by testing rather than assumption** on a single page — a malformed selector that silently produced no images at all, escape sequences leaking as literal text, and a page that never loaded the component it depended on. All three would have shipped.

The last line is the one to keep. Every rule above is short and specific because it was learned by getting something wrong, in public, and writing down what it cost.

*The full method, step by step, is on [the publishing playbook](../demos/vaults/publishing.md). The vaults themselves are in [the catalogue](../catalogue/index.md), each with the read key that opens it.*

[← All articles](index.md)



==============================================================================
# Green does not mean live — sgit.ai

> Two releases pushed cleanly, reported success, and never reached the site. Every check we had was green, because the failure happened in a place none of them could see. What we changed, and the general rule underneath it.
>
> Page: https://sgit.ai/articles/green-does-not-mean-live.html

[Home](../index.md) / [Articles](index.md) / Green does not mean live

# Green does not mean live

2026-08-17 · [v0.2.33](../admin/versions.md) · cideployverification

Two releases pushed cleanly, reported success, and never reached the site. Every check we had was green, because the failure happened in a place none of them could see. What we changed, and the general rule underneath it.

Two consecutive releases of this site pushed cleanly, verified themselves against both remotes, printed **"both remotes in sync — done"**, and never reached anybody. The site served a two-release-old page for forty minutes. It was noticed by a human on a phone, who looked at the version badge and said *"is this the latest version?"*

Everything about that sentence is worth sitting with. The checks were not weak. They were **checking the wrong boundary**.

## What the release actually verified

The release script does five things, and four of them are good:

1. Build the site from source.
2. Run the validator — structure, links, markdown twins, orphan pages, and a tripwire that scans every tracked file for a vault key.
3. Commit and push the encrypted vault; confirm `sgit status` reports in sync.
4. Commit and push the git mirror; confirm `HEAD == origin/dev`.

Step 4 is where the confidence came from, and it is genuinely a strong check — it compares hashes, not hopes. The problem is what it means. It means **the bytes arrived at GitHub**. It does not mean anybody can read them.

## The gap, named

Publishing this site has three boundaries, and we were verifying two:

```

  source  ──▶  git remote  ──▶  Pages deploy  ──▶  the reader
            ↑               ↑                  ↑
        verified        verified           NOT VERIFIED

```

Between the second and third arrows sits a GitHub Actions job. It has its own failure modes, it reports into a system neither remote knows about, and nothing in our release looked at it.

## What actually failed

Not our code. Not the content. The deploy job died in **"Set up job"** — before running a single step of its own:

```

Download action repository 'actions/configure-pages@v5'
##[warning] Failed to download ... Error: 429 (Too Many Requests)
##[warning] Back off 12.459 seconds before retry.
##[warning] Failed to download ... Error: 429 (Too Many Requests)
##[warning] Back off 26.597 seconds before retry.
##[error]  Failed to download archive after 3 attempts.

```

`codeload.github.com` rate-limited the download of a third-party action. The `validate` job passed. The `tag-release` job passed. The one job that puts bytes in front of readers could not fetch its own dependency.

This is worth stating plainly because it is the ordinary case, not an exotic one: **the most likely thing to break in a deploy is not your code.** It is a piece of shared infrastructure you do not run, on a day you were not thinking about it.

## The fix is one question, asked at the end

A release now finishes by asking the live site what version it is serving:

```

== 5/6 verify the deploy actually published
   waiting for v0.2.34 to appear at https://sgit.ai/ (up to 8 min)
   ......
   live: sgit.ai is serving v0.2.34

```

It polls with a cache-buster, because the origin's own answer is the only one that counts. If the version never appears it **aborts loudly**, names the Actions page, and says that a 429 on the action download is transient and needs a re-run.

The cost is real: up to eight minutes of waiting on every release. We took it, because the alternative had already been demonstrated twice in one afternoon — telling somebody a fix was live when it was not, twice, in writing.

## The rule underneath

This site already had two rules of exactly this shape, and adding the third made the pattern obvious:

- **A page nothing links to is unpublished.** The build fails on an orphan page — it happened once, a brief that was written, built and pushed while nothing linked to it.
- **A page the machine index omits is unpublished.** The build fails if any page would be missing from `llms.txt` — that happened too, a whole section silently absent.
- **A page the deploy never served is unpublished.** Now the release fails on it.

All three are the same claim: *shipped* is a fact about the reader, not about your repository. Every one of them was learned by getting it wrong first, which is the only reason the list is short and specific rather than long and aspirational.

## What this does not fix

Being honest about the edges, since that is the house rule:

- It detects a failed deploy; it does not repair one. A 429 still needs a human or a re-run.
- It checks the home page's version badge, not every page. A partial deploy that published some files would pass.
- It adds up to eight minutes to a release, which is a real tax on small fixes.

All three are acceptable against the failure they replace. The first one to bite will get its own entry.

*The release script is [in the repository](https://github.com/SGit-AI/SGit-AI__CLI); the releases described here are [v0.2.31 to v0.2.33](../admin/versions.md).*

[← All articles](index.md)



==============================================================================
# nhi.sgit.ai — Agents you run, agents you rent, and the identity gap — sgit.ai

> The question of how to give an AI agent an identity splits into two populations, and every product on the market answers only the first. For the agents you actually name — the ones running in Claude, Codex or behind an API — the honest current answer is to hand over a broad credential and hope.
>
> Page: https://sgit.ai/network/nhi.html

[Home](../index.md) / [Network](index.md) / nhi.sgit.ai

# nhi.sgit.ai

Agents you run, agents you rent, and the identity gap

Screenshots captured 2026-08-19 · `v0.1.14` when captured · [SGit-AI__Website__NHI ↗](https://github.com/SGit-AI/SGit-AI__Website__NHI)

[Open nhi.sgit.ai ↗](https://nhi.sgit.ai)

## The distinction the whole site turns on

**Agents you run** execute on your infrastructure. You can attest the workload, install an identity agent, and control everything. An open standard — SPIFFE — issues short-lived cryptographic identities on exactly that basis.

**Agents you rent** execute on somebody else's. You cannot attest the workload, cannot install anything, and the only thing you control is the credential you hand over.

The site puts the two side by side and lets the table make the argument:

The home page, with the two-population comparison directly under the thesis.

The last row is the one that lands: for agents you run, the industry answer is *"mature — and expensive"*. For agents you rent, it is *"none"*. SPIFFE is described by practitioners as a multi-year engineering project needing a dedicated team; for rented agents, the equivalent capability is an open feature request.

## "Hope is not a control"

The site names the current practice rather than describing it politely. When you hand an agent a broad credential you are making **two hopes** — that it will not misuse what it holds, and that it will not discover the rest of what that credential actually reaches. Neither hope changes your accountability, which runs to the board.

The second hope is the one most people have not costed. The site's framing is that **the real authorization is the closure**: inbox access is every account resettable by email; desktop access is every stored credential. The grant is not the words in it — it is everything reachable from them.

The thesis page: the argument with citations, rather than assertion.

## Why it is relevant here

This is the problem sgit's [read keys](../demos/vaults/index.md) and [append lanes](../api/append-lanes.md) are shaped against. A published read key is a credential whose closure is *provably* bounded — it opens one vault, cannot write, and cannot be turned back into write access. An append token can write to one lane and cannot read it.

The [comparison pages](../compare/index.md) use a privilege vocabulary — scope, operations, bearer, mediation, duration, withdrawal, observability — that is the same question asked in a different register.

## Sections

- **Thesis** — the two populations, with citations
- **Hope** — why the current workflow is hope-driven, and what the two hopes cost
- **Method** — from hope to controls: enumerate, bound, observe, contain, account
- **Options, Industry, Collection** — what exists, what it costs, and the open questions

[← All network sites](index.md)



==============================================================================
# pki.sgit.ai — A key registry for agents, designed from a documented failure — sgit.ai

> Good public key repositories existed and were destroyed. This site is the 2019 keyserver catastrophe, the four registry rules it produces, and the build order — all published before the registry exists, so the commitments are checkable against whatever eventually ships.
>
> Page: https://sgit.ai/network/pki.html

[Home](../index.md) / [Network](index.md) / pki.sgit.ai

# pki.sgit.ai

A key registry for agents, designed from a documented failure

Screenshots captured 2026-08-19 · `v0.1.2` when captured · [SGit-AI__Website__PKI ↗](https://github.com/SGit-AI/SGit-AI__Website__PKI)

[Open pki.sgit.ai ↗](https://pki.sgit.ai)

## Publishing the design before the implementation

The premise is unusual and worth stating plainly: **this site describes a registry that does not exist.** That is deliberate. Publishing the rules now is cheap; claiming them afterwards is impossible. If something ships that breaks one of them, the site is the evidence.

The home page. The claim is historical before it is technical.

## The failure it is designed from

In 2019 the global keyserver network was flooded with garbage signatures until importing a poisoned certificate would break your installation. Its own maintainer called it **unsalvageable**. The cause was not a bug — it was a design goal stated at the outset.

That design goal was **append-only**. And append-only is a pattern this project relies on in five places, which is exactly why a shrug would not do. The site's resolution is a precise one, and it is the most useful idea on the page:

- **Append-only, owner-writes** — only the record's owner may write to it. Every entry is attributable because the owner signed it; a record grows slowly, in one hand; something can be withdrawn by a signed append that supersedes it.
- **Append-only, anyone-writes** — anybody may grow anybody's record, without limit, and garbage is indistinguishable from signal. Nothing can ever be withdrawn, by design. This destroyed the network.

The rule to carry forward is **not** "append-only". It is *the writer owns what it writes*.

## The four rules

Each one turns around a specific property the 2019 attack abused:

Each rule states the property it turns around, so it can be checked rather than trusted.

1. **Only the owner writes to their own record** — turns around *anyone may append to anybody's certificate*.
2. **Revocation is a signed append, not a deletion** — signed by the key being revoked, so it is self-authenticating, the record stays append-only, and what a key said before revocation stays checkable.
3. **Records are size-bounded** — one poisoned key reached about 150,000 signatures because certificates had no limit. The bound is a stated parameter, with the honest cost that it will one day reject a legitimate record.
4. **Every entry is signed** — so nothing anonymous can accumulate.

Rule 2 is the one to notice. Deletion and append-only are usually treated as incompatible; making revocation a *signed statement appended by the revoked key itself* resolves the contradiction without weakening either property.

The history, in five minutes — sourced rather than summarised from memory.

## Why it is relevant here

sgit's own [PKI](../docs/pki.md) ships keypairs today — RSA-OAEP 4096 for encryption, ECDSA P-256 for signing — and has **no revocation, no directory and no web of trust**, which [the limitations page](../docs/limitations.md) says plainly. This site is the design work for what a directory would have to be before it could responsibly exist.

The connection to [append lanes](../api/append-lanes.md) is direct: a lane is append-only and *owner-configured* — a sender writes only to a lane the owner registered for them. That is rule 1, already shipped, in a different corner of the system.

## Sections

- **The failure** — 2019, with sources
- **The rules** — four commitments, each tied to the property it turns around
- **Mandate** — what a registry would be for
- **Build order** — private before public, and why

[← All network sites](index.md)



==============================================================================
# sg-sentinel.sgit.ai — An app-coupled edge guard — Layer 1 decides, Layer 2 acts — sgit.ai

> A design for an edge security and logging layer you own rather than rent, built on the observation that your own app already knows what a valid request looks like — so the edge can allowlist rather than denylist. Published as a complete design that has deliberately not been built.
>
> Page: https://sgit.ai/network/sg-sentinel.html

[Home](../index.md) / [Network](index.md) / sg-sentinel.sgit.ai

# sg-sentinel.sgit.ai

An app-coupled edge guard — Layer 1 decides, Layer 2 acts

Screenshots captured 2026-08-20 · `v0.1.1` when captured · [SGit-AI__Website__SG_Sentinel ↗](https://github.com/SGit-AI/SGit-AI__Website__SG_Sentinel)

[Open sg-sentinel.sgit.ai ↗](https://sg-sentinel.sgit.ai)

## It says, at the top of every page, that it does not exist

This is the most unusual thing on the network and the reason to read it. A banner sits above every page:

**Not built.** SG/Sentinel is a published design from May 2026 — *"this is how I would build it"* — not a product. No plans to build it unless somebody funds it.

The status pill reads `NOT BUILT` where its siblings read `MVP DRAFT`. And the note goes further than a disclaimer usually does: the design exercise produced an agent-built prototype whose testing manual reports **149 passing tests**, and the site immediately bounds what that means — *"not deployed anywhere, not in production use, not maintained, and not packaged for you to install. Every 'built' or 'proven' on this site refers to that prototype exercise, nothing more."*

That paragraph is the whole house style in one place: publish the work, then say precisely what it is worth.

The home page, with the not-built banner above the thesis and the full status note below it.

## The problem, and the inversion

Edge security and logging today means renting AWS WAF plus CloudWatch and Kinesis Firehose. The site names three costs — no real-time view of your own traffic, logging priced per gigabyte for a job that is *"write a clean record to S3"*, and a WAF you cannot reason about — and one origin story underneath them: *a single client-side bug once caused runaway redirect traffic, and nothing at the edge would catch the next one before the bill did.*

The inversion is the good idea. A generic WAF is blind to the application it protects, so it **denylists** known-bad and passes everything else. But if you control both client and server, the edge knows the valid request space — so it can **allowlist**, and no invalid request reaches the origin at all.

## One correction that reshaped the design

The architecture page opens with a governing constraint, and it is a genuinely instructive piece of engineering writing:

**Layer 1 never acts and never writes — it only decides and signals. Layer 2 is the sole actor and the sole I/O owner.**

The reason is physical, not stylistic: a CloudFront Function has no network and no filesystem, so it *cannot* write to S3 and must not enforce. L1's whole job is to assign a request ID, evaluate deterministic rules, and emit a structured signal. Blocking, deflecting and logging are **actions**, and actions belong to the layer that can perform I/O. L1 can only *recommend* a block.

The site is explicit that this corrected an earlier version of its own design in which L1 blocked inline — a category error, named as such.

The layer model: one actor, one I/O owner, and both use cases flowing through a single path.

## Rules are the engine, not configuration on it

The second inversion: *"rules are not configuration on top of a fixed engine — rules are the engine."* The core is a small stable machine for executing them, and every block, allow and log action is a rule. Each is a pure function `(captured) → {verdict, reason, rule_id, action} | null`, run in order, first block wins.

The MVP core is deliberately tiny — six deterministic rules, each mapped to an ATT&CK technique:

| Rule | Catches | Action |
|---|---|---|
| `capture-all` | every request; pure observation and the allow fallthrough | pass |
| `banned-ip` | source IP in the embedded list | `drop_403` |
| `malformed-request` | no method, no path, path not starting `/` | `drop_403` |
| `path-never-valid` | `/etc/passwd`, path traversal | `drop_403` |
| `hidden-file-probe` | `/.env`, `/.git/…` | `deflect_404` |
| `wp-scan-on-static` | `/wp-login.php`, `/xmlrpc.php` on a static site | `deflect_404` |

Rules are data, versioned in git, carrying their own metadata. The prototype exercise ran the same engine across **three targets** with a parity matrix asserting identical decisions — which is what makes "rules are data" a testable claim rather than a slogan.

The six rules of the tiny core, each with what it catches, its ATT&CK mapping and its action.

## Why it is relevant here

Two connections, and the second is the sharper one.

**Rules as versioned data** is what sgit is for. A rule set that must be auditable, diffable and attributable — but whose contents may reveal exactly what you are watching for — is a natural fit for a vault: git semantics over content the host cannot read.

**And it is the third site here to publish a design before the thing exists.** [pki.sgit.ai](../network/pki.md) publishes four registry rules before the registry; this one publishes an entire architecture and then declines to build it. Both rest on the same wager: *publishing the design now is cheap, and claiming it afterwards is impossible.* If somebody does build this, the parity matrix and the six rules are already on the record.

## Sections

- **Architecture** — the layer model, the signal spine, the three targets
- **Rules** — rules as data, the six-rule core, and where the graph goes
- **Research** — 68 days of design, tabletop-tested
- **Try it · Code · Roadmap** — the prototype snapshot and what would come next

[← All network sites](index.md)