Articles · No. 10
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.
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:
| Reader | What they need from an example |
|---|---|
| A consultant who will deliver ruv.sgit | A safe place to learn each moving part, one at a time, and a known-good result to compare their own run with |
| Anyone trying it | Something that runs on a laptop in minutes, with nothing to sign up for, and an obvious "it worked" at the end |
| Us, developing it | A 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 runner, poc/ruv-sgit/ruvsgit.py, does four things:
w-<worker>), pushed, and merged into current;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.
"visibility", with three values: "public", "private" (the default) or "delete".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.~/.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.
| Question | Proposed 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. |
Update, 17 Oct (run r15-publish). Dinis decided the vaults live on the sgraph vault server, not in the repository.
sealnow pushes the run's vault (every branch, full history) tohttps://dev.send.sgraph.ai, checks a fresh read-only clone and the vault UI athttps://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 undersite/vaults/are removed;example-01-helloandr14-examplesare superseded byexample-01-hello-v2andexample-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):
--visibility public puts the READ KEY in the folder; the help itself says "irreversible". bare (the default) publishes no key.--bundles also writes a head snapshot and per-commit delta zips; --api-spec writes a description of the folder.sgit clone has a static transport ("any GET host, read-only") and accepts <read-key-hex>:<vault-id>, which it detects as read-only.site/vaults/<run>/ carries the encrypted objects too (copied, or as --bundles), and that a clone from it works with no server running. Example 01 is the proof.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.
hello, role writer, task "write hello.md: one line saying which run this is and when", "visibility": "public".example-01-hello-v2, open in the vault UI from the examples page), and a ledger entry.smoke-1, did the same with one 72-byte file: 23 seconds from open to close.smoke-1 in the ledger. Being built now by the mechanic.current.left and right, each writing one file; then a third, editor, that writes summary.md naming both.w-* branches merged, and the vault's history drawn as a graph on the example page.sgit history log --json).r2-materials used, and the history slide from the talk, which draws a real run's commits.writer may write files in its lane; tester may not write files and may not reach the network. The worker actions go through Ruflo's own policy engine in enforce mode, with the ABP compiled into its rules, exactly as POC1 does through the engine's library API (no faked terminal, no weakened control)."inputs": [{"run": "example-01-hello", "read": "vaults/example-01-hello/"}]. Run B clones it read-only into inputs/, and its worker writes reply.md quoting A's file and A's head commit.Dinis: "the creation of those animations to explain stuff is the killer one".
researcher (collects the facts and numbers, each with its source, into facts.json), animator (builds the page), editor (checks it against the brief and the contract, and against the facts, and writes the review).clock.js loaded first and one timeline on requestAnimationFrame, so it can be paused, sped up, stepped and sought; ?review shows the final frame, ?once plays once and holds, ?ruvt= starts part-way; numbers read from data files, never typed in.r8-explain made two such slides in 7 minutes 15 seconds from open to close, with its two animators using about 90,500 and 118,400 tokens; r7-claim took 8 minutes 47 seconds for two.r8-explain, spec r8-explain.spec.json); the claim (r7-claim); the definition animations, equation, layers and journey (r3-define); and the studio, whose seven versions are the same idea pushed further.writer (the beats and the words), timer (the timings, checked so the beats add up), editor.talk-example.json the player plays, live slides included, and an offline build.talk-10.json and talk-5.json, the timelines of 15 October, and the articles the talk player and the talk, live.r14-examples.spec.json: the mechanic (the runner's new ending and example 01) and the writer (this article).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:
| Part | What it shows | Where it comes from |
|---|---|---|
| (a) The brief | The spec rendered: purpose, feedback, each worker's id, role, task and output path, and the visibility | brief/spec.json in the vault, the same as poc/ruv-sgit/runs/<run>.spec.json |
| (b) The output | The 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 vault | Open 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 drawing | site/vaults/<run>/ and the ledger entry |
| (d) The ledger entry | Commits, files, bytes, branches with write and merge times, the plaintext probe, the clone check, sealed_at, and whether the key file is gone | data/vaults.json |
| (e) Try it yourself | The exact commands, copyable: bash scripts/offline.sh setup once, then the example's run, then ./run-website-locally.sh to see it | The 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.
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.
| Run | Purpose | Workers |
|---|---|---|
| r15-seal | Seal 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-ladder | Examples 02 to 04 | three scripted example workers, one per example; page (their pages); editor |
| r17-explainer | Examples 05 and 06 | researcher, animator, editor (example 05, a hive); writer, timer (example 06); page |
| r18-meta | Example 07, the examples index and the menu entry | archivist (r14's vault published, or r14 re-run), page (the index), indexer (llms.txt, the README, the version history), editor |
r15-seal
scripts/offline.sh with no network.~/.ruv-sgit finds no vault key for the run.site/vaults/example-01-hello/, with the read key and no vault server running, gets back files identical to what the worker delivered.sealed_at and visibility; validate.py passes (its secret check still finds no vault key or token anywhere in site/; the published read key is the one string it allows on purpose)."visibility": "private" writes nothing under site/vaults/.r16-ladder
sgit history log --json for its vault.r17-explainer
?review, ?once and ?ruvt= work, it pauses with the player, and every number on it is read from a file with a source.validate.py).r18-meta
validate.py passes; every new page is in llms.txt.Each has a proposed answer. A "yes" accepts it.
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.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).r10-articles, held about 6.9 MB of plaintext; examples should be small enough to clone in seconds.r8-explain (the clearest explainer) inside example 05, and nothing else for now; the rest stay as ledger entries."visibility": "public" explicitly; no flag on the command line can override either.sgit publish --help and sgit.ai's demo pages; the exact form waits for example 01.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.