Plan: the Why reframe, three end-to-end demo vaults, and the component registry

date 2026-08-14 · owner the sgit.ai site agent · source the 14 Aug briefing pack (leading brief + 9 supporting docs) canonical URL https://sgit.ai/admin/plans/why-expansion-plan.md↗

Decisions taken up front, per the project lead: reusable interface pieces are components, never plugins (plugin stays reserved for capability grants); the three demo vaults are actually created, each as a full end-to-end walkthrough; demo vault read keys are published on purpose, vault keys never; the embed mechanism reuses the SG/Vault UI code (briefing filed: /briefs/briefing-sgvault-ui-embed.md).

Status against the leading brief

Phase 1, Reframe /why/ from rebuttal to boundary map

Rewrite of the existing page, not new work. The git-vs-sgit table (already on the page) moves to the top and becomes the frame; the rebuttal to the LinkedIn comment moves underneath it. Corrections the pack is right about and the page currently gets subtly wrong:

• The boundary is not the operations. commit/push/pull/clone/branch/diff/merge all exist. What is absent is the hosted review interface and the ecosystem above the protocol (CI, issues, server-side search, delta compression). A pull request is a platform construct layered on merge.
• Git is also client-side. The difference is not that work moved to the client, a git client already holds the object model. The difference is the objects are encrypted there. Losses are what a readable server could have added; "the server can do nothing" overstates it and costs trust.
• Name the two keys and the three modes (Local / API / Web), and publish the six-step read path verbatim, it fits on a page and is the protocol argument.
• Scenario template for every situation added later: THE SITUATION / WHAT YOU TRIED / WHAT CHANGED / HOW → link. The second field is the one that makes it believable.
• One canonical location per fact: the Why links to the Rosetta page, limitations, security, never restates them.

Phase 2, The serialised pull request, honestly stated

The lead example: an agent clones a public vault with no credential at all, changes, commits, emits a diff; a person imports, reviews, merges elsewhere. Grounding to cite: the 5 Aug 2026 Black Hat disclosure (an issue from a no-privilege account reached CI secrets in three vendors' default configurations); no-credential is stronger than short-lived-scoped (which remains an open platform feature request); published security guidance independently recommends read-only-job → constrained artefact → separate privileged step.

Honesty gap found while planning: sgit history diff --json (emit) is shipped; there is no apply/import command in the current CLI (v0.15.x). The workflow was performed, but its import half is not a first-class command. Therefore:

1. The page ships with evidence status PARTIAL and shows the real mechanics (emit via history diff --json; import via review-and-merge).
2. A brief goes to the CLI team: sgit diff export / sgit diff apply as first-class commands, plus a published diff format specification: the pack itself flags that the headline claim needs one.

Phase 3, Three demo vaults, built end-to-end in public

Three shapes, chosen for maximum difference, each created from scratch so the walkthrough is complete and reproducible, not imported from existing vaults (those can follow as catalogue entries once the mechanism is proven):

Each demo page (under /demos/) is the full transcript: sgit create → structure → commit → push → derive the read key → publish the read key in the page, with the sentence explaining why that is safe and deliberate → the live embed (Phase 4) → a downloadable archive. Per-sample metadata, stated on every page: shape · evidence status · copy-or-reference semantics (archive = copy that diverges; embed = reference that stays live). Archives go in GitHub release assets, never the repo tree (3,000-entries-per-directory recommendation; ciphertext neither compresses nor deltas, so the archive is ~vault-sized and every tree copy is paid for by every clone forever).

Key hygiene, mechanical: each demo vault's key lives in the gitignored .sg_vault/local/demo-keys/ tier; the validator's tripwire extends to scan every tracked file for all passphrases found there, not only the site vault's; release.sh already refuses to push until that passes. Read keys (64-hex) are exempt by design.

Phase 4, The embed: reuse the SG/Vault UI host code

Goal: open the vault app iframe (opaque origin, window.sg bridge, deny-by-default permissions) inside a sgit.ai page from read key + vault id alone, using the same code dev.vault.sgraph.ai runs, one codebase, and the embed itself demonstrates the capability. Briefing with six concrete questions filed to the UI agent: /briefs/briefing-sgvault-ui-embed.md (modules, embeddable entry point, read-key-only behaviour, sandbox recipe, version pinning, _page.json renderer).

Fallback so Phase 3 never blocks: <iframe> straight to dev.vault.sgraph.ai/en-gb/#<read-key>:<vault-id>, whole-app embed, works today. Ship demos on the fallback if the reuse answer takes time; swap the inner-host embed in when it lands and write the integration up as a case study.

Phase 5, Component registry (gated)

Only after search indexing of the site is observed, per the brief: a registry an agent cannot fetch does not remove the agent tax. When unblocked: vault-in-vault first (small, everything depends on it); chat is two-or-three components, not one; each component gets a single canonical URL whose artefact is self-sufficient, an evidence status, and the one-line agent reference as the most prominent thing on the page. Component fetching and capability granting never share a command.

Also queued from the pack

• Case study: the site's own multi-vault build: the inbox-coordinated multi-agent, multi-vault architecture behind this site, written up properly.
• Ignore-file gap brief to the CLI team: sgit has no ignore support (documented as planned); the single-declaration two-ignore-files-generated pattern in the pack is the right ask, plus the build check that fails when a path is claimed by both systems.
• Per-path index (sg-vault-v1:file-id:path-index:{vault_id}:{path}), briefed, not built; our reader adopts it for single-request page loads when it ships.

Order and dependencies

1 (Why rewrite) → 2 (serialised PR page + CLI brief) → 3+4 together (demos on the fallback embed; upgrade embed when the UI agent answers) → registry last, behind indexing. The naming decision applies from the first word written.