ruv.sgit.airUv + sgit

Articles · No. 10

Getting started with ruv.sgit: a ladder of examples, and run vaults that end sealed and published

draft brief getting started examples ruv.sgit sgit vaults seal publish abp ruflo animation

Abstract. DRAFT for Dinis to check. This is the brief for the ruv.sgit team and an article for anyone who wants to try ruv.sgit. It proposes two things. First, a new end for every run: once a run has been measured, the vault key is deleted, so the vault can no longer change, because it represents a run that has ended; then the vault is either published with its read key, handed over privately, or deleted. Second, a ladder of seven examples, from a one-file hello world to the killer workflow (an explainer animation made from a brief by a Ruflo hive) and a meta example (the run that wrote this article), each on a standard page with its brief, its output, its sealed vault and its ledger entry. The thirteen run vaults made so far were deleted by design, so the examples will be re-runs. Four runs, r15 to r18, build it; nine open questions have proposed answers.

Written by Claude (Claude Code), worker "writer" in run r14-examples, from Dinis Cruz's voice memo of 16 October 2026, this site's runner, run specs and ledger, the sgit 0.21.0 command help, and the way sgit.ai and the newsroom publish vaults. It is for Dinis to check and fine-tune; once he has, it is the brief the next runs implement.

DRAFT v0.1.0. Every command, path and page below is a proposal until Dinis signs it off. Commands marked to be confirmed are waiting for the first real run of the new ending, which another worker in this run (the "mechanic") is building now. Edit the source (site/articles/src/getting-started.md) and the implementation follows the edited version.

In short

Why examples, and for whom

ruv.sgit is a Ruflo hive (Ruflo is MIT, by rUv / ruvnet) whose shared memory and output is one sgit vault per run, with each role bounded by an Agent Behaviour Policy (ABP). The site already proves that the pieces work: thirteen runs in the ledger, 74 vault commits, 48 worker branches, no plaintext found in what the server stored (0 of 483 probed text fragments), and every fresh clone identical to what the workers delivered (13 of 13). What it does not yet have is a way in. A reader can see that runs happened; they cannot easily make one.

Dinis named who the examples are for: "not only consultants that are going to be providing these services can learn and test, but also people can try it out". So the ladder serves three readers:

ReaderWhat they need from an example
A consultant who will deliver ruv.sgitA safe place to learn each moving part, one at a time, and a known-good result to compare their own run with
Anyone trying itSomething that runs on a laptop in minutes, with nothing to sign up for, and an obvious "it worked" at the end
Us, developing itA fixed set of runs to repeat after every change to the runner, sgit or Ruflo: a regression suite that is also documentation

The third use matters as much as the first two. If example 01 still produces the same ledger shape after an upgrade, the upgrade did not break the basics.

The new end of a run: seal, then publish, hand over or delete

Today

The runner, poc/ruv-sgit/ruvsgit.py, does four things:

  1. open: a fresh Ruflo hive (one specialist per role, one task per deliverable) and a new vault on a local SG/Send vault server, with the brief committed;
  2. deliver: each worker's output committed on its own branch (w-<worker>), pushed, and merged into current;
  3. close: measure the vault (history, files, bytes, what the server stored, a plaintext probe, a fresh clone compared with the working copy) and write the ledger entry;
  4. delete: remove the vault's objects from the server store, check that a clone with the key now fails, and destroy the key and the working copy.

The runs were ephemeral by design: the point was to show that a vault can carry a run and then be gone. It worked (12 of the 12 runs with a delete check left no store paths behind, and a clone afterwards failed), and it means there is nothing left to publish.

The lifecycle from now on

opendelivera branch per workerclosemeasure, ledgerpublishread key, publichand overread key, privatedeleteobjects removedthe spec decides: "visibility"sealvault keydeletedThe last step is always the same: the vault key is deleted, so no commit can be added. The run has ended; the vault is its record.
The proposed lifecycle. The first three steps are today's runner. The decision is written in the run's spec before the run starts; every path ends by deleting the vault key.
  1. open, deliver, close: as today.
  2. Decide, from the spec. Each spec gains one field, "visibility", with three values: "public", "private" (the default) or "delete".
  3. Prepare the way in. For public, sgit publish --visibility public writes a static folder that includes the read key; it is pushed to the sgraph vault server and only the reference (server, vault id, read key, viewer URL, clone command) goes into the site. *(Decided 17 Oct: first built as a static folder under site/vaults/<run>/, then moved to the server; see the update below.)* For private, the read key is written to a 0600 file outside the repository for handing over. For delete, today's delete step runs.
  4. Seal: delete the vault key. Always the last step. The key file in ~/.ruv-sgit/runs/<run>/, the working copy (whose .sg_vault folder also holds the key) and every temporary clone are removed. The ledger records sealed_at.

Dinis put the principle plainly: "the last step of the vault is always the deletion of the vault key, because the vault should not be modified anymore, because the vault represents a run, and the run has ended". The order inside step 3 and 4 matters: publishing needs the key, so the read surface is prepared first and the key is destroyed straight after, in the same step of the runner.

Dinis's four questions, answered

QuestionProposed answer
Is the data in the vault confidential or not?A decision per run, written in the spec as "visibility" before the run starts, not after. The default is private. Client work is always private first, as the next-phase brief already decided.
Can we publish the vault?Only when its content is meant to be public: examples, the site's own runs, open work. Publishing the read key is irreversible (CLAUDE.md, rule 1): anyone who has it can read the vault for as long as a copy exists. So a public run is checked before it is sealed: no keys, no tokens, no personal data, nothing a client owns, the same audit sgit.ai's demo pages describe ("Audited before publishing").
Who accesses it?Anyone with the read key. For a public vault that is anyone who opens its page on ruv.sgit.ai; for a private one, the people the read key was handed to. Nobody can write to it, including us, because the vault key no longer exists.
How is it passed to the next round?The next run clones it read-only as an input, with the read key: from the published folder for a public vault, from the server for a private one. The new run has its own vault; the old one is never changed. That is example 04.

How a sealed vault is published (to be confirmed by the mechanic's run)

Update, 17 Oct (run r15-publish). Dinis decided the vaults live on the sgraph vault server, not in the repository. seal now pushes the run's vault (every branch, full history) to https://dev.send.sgraph.ai, checks a fresh read-only clone and the vault UI at https://dev.vault.sgraph.ai, deletes the local copy, then destroys the vault key. The site keeps only the reference, and lists the published vaults, each open in the vault UI, on the examples page. The static folders under site/vaults/ are removed; example-01-hello and r14-examples are superseded by example-01-hello-v2 and example-07-meta. The sketch below is the first version, kept as written.

The intended mechanism follows how sgit.ai publishes its demo vaults, where each page shows the read key, a link that opens the vault read-only in the official web UI, and a one-line clone command:

# inside the run's working copy, after close, before the key is deleted (to be confirmed)
sgit publish --visibility public --yes        # writes the static folder: cover.json, index.html, manifest.json, the read key file
# copied by the runner to site/vaults/<run>/

# a reader, afterwards (to be confirmed)
sgit clone <read-key>:<vault-id> --base-url https://ruv.sgit.ai/vaults/<run> --transport static my-copy

What is already known, from sgit publish --help (sgit-ai 0.21.0) and from publishing this site's POC vault on 14 October (see evidence/notes.md and the published POC vault):

The example ladder

Seven rungs. Each one adds one idea to the one before. The times are measured where a past run did the same thing, and marked estimate where none did.

01 Hello world

02 Two workers, two branches, a merge

03 A mandate

04 Memory across runs

05 The killer workflow: an explainer animation from a brief

Dinis: "the creation of those animations to explain stuff is the killer one".

06 A talk built as a timeline

07 The meta example: the run that made the examples

The example page: the standard way

Dinis asked for "a standard way", listing for each example "the original briefs, the output, and the vault". Each example gets one page, site/examples/<id>/index.html, with five parts in this order:

PartWhat it showsWhere it comes from
(a) The briefThe spec rendered: purpose, feedback, each worker's id, role, task and output path, and the visibilitybrief/spec.json in the vault, the same as poc/ruv-sgit/runs/<run>.spec.json
(b) The outputThe deliverable, rendered. An animation runs live in a frame, with play, pause and review (it follows the slide contract)The delivered files, from the site
(c) The vaultOpen it: a link to the official read-only web UI with the read key, as on sgit.ai. Clone it: the one-line command with the read key. What is inside: the file tree from manifest.json. Its history, drawn: the commits and w-* branches as a graph, reusing the history slide's drawingsite/vaults/<run>/ and the ledger entry
(d) The ledger entryCommits, files, bytes, branches with write and merge times, the plaintext probe, the clone check, sealed_at, and whether the key file is gonedata/vaults.json
(e) Try it yourselfThe exact commands, copyable: bash scripts/offline.sh setup once, then the example's run, then ./run-website-locally.sh to see itThe repository

The "history, drawn" part answers Dinis's request for runs "where we actually use the visualisation of the vaults": every example page shows its own vault, not a diagram of one.

An index page, site/examples/index.html, lists the ladder: number, name, one line, how long, and a link; the menu gets an "Examples" entry. Like every page on this site, it reads its numbers from the data files when it loads.

The plan

Four runs, in order, each after the one before is reviewed. Run numbers continue from r14; the runs proposed in the next-phase brief take the numbers after these, or run in between, as Dinis prefers.

RunPurposeWorkers
r15-sealSeal and publish in the runner, proven by example 01 (if the mechanic's work in r14 is not finished, this completes it)mechanic (ruvsgit.py: seal and publish, the visibility field, sealed_at), checker (the acceptance checks as a script), page (the first example page)
r16-ladderExamples 02 to 04three scripted example workers, one per example; page (their pages); editor
r17-explainerExamples 05 and 06researcher, animator, editor (example 05, a hive); writer, timer (example 06); page
r18-metaExample 07, the examples index and the menu entryarchivist (r14's vault published, or r14 re-run), page (the index), indexer (llms.txt, the README, the version history), editor

Acceptance checks

r15-seal

r16-ladder

r17-explainer

r18-meta

Open questions for Dinis

Each has a proposed answer. A "yes" accepts it.

  1. Where do published vaults live? Decided 17 Oct: on the sgraph vault server (dev.send.sgraph.ai), shown in its vault UI; the site keeps only the reference. First proposal: on this site, under ruv.sgit.ai/vaults/<run>/, next to their example pages, and listed in sgit.ai's catalogue with a link here, rather than moved to sgit.ai.
  2. Keep a server copy after sealing? Proposed: for public vaults, also push the sealed vault to the hosted sgit server, so the official web UI link works as it does for sgit.ai's demos; the static folder stays the copy we control. For private vaults, keep the server copy until the client has their own, then delete it.
  3. Naming. Proposed: example-01-hello to example-07-meta for the example runs; a re-run of an old run keeps its old name with -rerun (r8-explain-rerun).
  4. Model or scripted workers? Proposed: scripted for 01 to 04, so anyone can run them with no API key and get the same result each time; a model for 05 and 06, where the work needs one; 07 is whatever r14 was (Claude Code workers).
  5. Size limit for a published vault. Proposed: 5 MB per vault for the examples. The largest run so far, r10-articles, held about 6.9 MB of plaintext; examples should be small enough to clone in seconds.
  6. The seal is permanent; is that what we want for the examples? Proposed: yes. A fixed example is re-run as a new vault with a new name, never edited, so its page always points at what it says.
  7. Which past runs are re-run as examples? Proposed: r8-explain (the clearest explainer) inside example 05, and nothing else for now; the rest stay as ledger entries.
  8. A check before publishing. Proposed: the runner refuses to publish if the secret check finds anything shaped like a key or token in the delivered files, and the spec must say "visibility": "public" explicitly; no flag on the command line can override either.
  9. Licence of published example content. Proposed: the same as the site: code Apache-2.0, text CC BY 4.0 (as decided for the next phase), rUv's projects credited as MIT, by rUv / ruvnet.

What this does not claim

Where this comes from

Dinis Cruz's voice memo of 16 October 2026 (quoted where his words are used) and the run spec r14-examples.spec.json; the runner ruvsgit.py; the ledger data/vaults.json (13 runs; the totals and times above are computed from it); docs/01-sgit-cheatsheet.md and sgit publish --help / sgit clone --help (sgit-ai 0.21.0, run on 16 October); evidence/notes.md (publishing the POC vault, 14 October); sgit.ai's published vaults and Black Hat Europe 2025 demo page and the newsroom's vault page, read on 16 October; and the articles the studio, the talk player and from the talk to the service.

Changes