From 1911d5eddca1a22eaef176ecaee7b2e5bdbacd1d Mon Sep 17 00:00:00 2001
From: QSchlegel <quirin.schlegel@icloud.com>
Date: Sun, 23 Aug 2026 16:22:32 +0200
Subject: [PATCH] docs(vault): a how-to for shielded sign-off, linked from both
 vaults
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The construction was shipped without anywhere that explains it. The vault
pages show a trust graph and a disclosure path to someone who has not been
told what either means.

The guide covers the three things that actually change how you use it: why
the logical and trust relations must stay apart (hashes cannot cycle, so
the moment you want tamper-evidence you must decide which references carry
weight), why one root is not enough (proving anything reveals the root,
and the root tells the recipient how your organisation is grouped), and
exactly what a disclosure gives away — including the part that is easy to
miss, that it leaks the COUNT of documents under the disclosed hub and the
count of hubs.

It also says plainly what is not a button yet. `disclose` and
`verifyDisclosure` exist with tests covering relabelling, reordering,
tampering and cross-vault splicing, but grep confirms they are imported
only by the test file: nothing in the product exports a disclosure
artefact. The vault view SHOWS what one would reveal, which is the part
that changes how you organise a vault, and the guide is explicit that
handing the artefact to a counterparty is the next step rather than a
shipped one. Promising otherwise in a guide about proofs would be a
strange place to start being loose.

Linked from the wallet's own vault and from the public demo, because a
guide nobody can find from the thing it explains is not documentation.

1161 tests pass; tsc clean; next build exit 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../pages/wallet/documents/vault.tsx          |   8 +-
 .../blog/how-to-use-shielded-sign-off.md      | 146 ++++++++++++++++++
 src/pages/vault.tsx                           |  11 ++
 3 files changed, 164 insertions(+), 1 deletion(-)
 create mode 100644 src/content/blog/how-to-use-shielded-sign-off.md

diff --git a/src/components/pages/wallet/documents/vault.tsx b/src/components/pages/wallet/documents/vault.tsx
index ffb0b571..6113528a 100644
--- a/src/components/pages/wallet/documents/vault.tsx
+++ b/src/components/pages/wallet/documents/vault.tsx
@@ -1,6 +1,6 @@
 import Link from "next/link";
 import { useRouter } from "next/router";
-import { FileSignature, Shield } from "lucide-react";
+import { BookOpen, FileSignature, Shield } from "lucide-react";
 
 import VaultBrowser from "@/components/pages/vault/browser";
 import WalletDetailSkeleton from "@/components/pages/wallet/wallet-detail-skeleton";
@@ -33,6 +33,12 @@ export default function PageWalletVault() {
   return (
     <main className="mx-auto flex w-full max-w-7xl flex-1 flex-col gap-4 p-3 sm:p-4 md:gap-6 lg:gap-8 lg:p-8">
       <PageHeader pageTitle="Vault" backUrl={`/wallets/${walletId}/documents`}>
+        <Button asChild size="sm" variant="outline">
+          <Link href="/blog/how-to-use-shielded-sign-off">
+            <BookOpen className="mr-2 h-4 w-4" />
+            How it works
+          </Link>
+        </Button>
         <Button asChild size="sm" variant="outline">
           <Link href={`/wallets/${walletId}/documents`}>
             <FileSignature className="mr-2 h-4 w-4" />
diff --git a/src/content/blog/how-to-use-shielded-sign-off.md b/src/content/blog/how-to-use-shielded-sign-off.md
new file mode 100644
index 00000000..05962f21
--- /dev/null
+++ b/src/content/blog/how-to-use-shielded-sign-off.md
@@ -0,0 +1,146 @@
+---
+title: "How to use shielded sign-off"
+description: "Prove one document belongs to your governance spine without revealing the rest of it. How the trust graph works, how to set your vault up, and what a disclosure actually gives away."
+date: "2026-08-23"
+tags:
+  ["shielded sign-off", "document sign-off", "cardano multisig", "governance"]
+author: "Mesh"
+---
+
+A counterparty asks you to prove your treasury has a spending policy, and that a
+particular signer is authorised under it. You can send them the policy. What you
+cannot easily do is send them _only_ that — not the other policies, not the names
+of your other workstreams, not the shape of your internal governance.
+
+Shielded sign-off is the answer to that. It is a way of hashing a set of linked
+documents so that a single one can be proved to belong, on its own, while
+everything beside it stays sealed.
+
+This is a guide to the idea and to what the product does today. Where something
+is not yet a button, this says so.
+
+## Two kinds of link, and why they must stay apart
+
+Documents reference each other. In a normal wiki those references form loops
+freely — a charter mentions a policy, the policy mentions the charter — and
+that is fine, because nothing depends on it.
+
+Hashes cannot loop. If document A's hash covers B, and B's hash covers A,
+neither can be computed. So the moment you want tamper-evidence, you have to
+decide which references carry weight.
+
+Shielded sign-off keeps two separate relations:
+
+- **The logical relation.** Ordinary references between documents. They carry a
+  name and nothing else, they may point anywhere including backwards, and they
+  are deliberately absent from every hash. Cycles here are normal.
+- **The trust relation.** A document's hash covers the hashes of everything it
+  trusts, transitively. These must form a directed acyclic graph, and the build
+  fails loudly — naming the exact chain — if they do not.
+
+That separation is the whole trick. You keep the messy, human web of
+cross-references, and you get a clean commitment underneath it.
+
+## Proxy hubs: why one root is not enough
+
+The naive structure is one root that commits to every document. It works, and it
+leaks: to prove any single document belongs, you reveal the root, and the root
+tells the recipient how many documents you have and how they are grouped.
+
+So the spine has a middle layer:
+
+```
+blinded root
+├── Governance      ← a hub
+│   ├── Spending Limits
+│   └── Signer Set
+├── Legal           ← a different hub
+│   └── Shareholder Agreement
+└── Operations
+    └── Incident Response
+```
+
+Each hub is a proxy for one angle of your organisation. Disclosing the
+Governance hub proves a governance document belongs, without naming Legal or
+Operations at all — the root commits to the hubs' **hashes**, never their
+titles.
+
+Every document also carries its own salt, so a short document cannot be
+brute-forced from a guessed title. In your wallet's vault those salts are
+derived from a per-wallet secret, which means a guessed title tells an outsider
+nothing.
+
+## Setting up your vault
+
+Your vault is not a separate thing you create. It is built from the documents
+you already have.
+
+1. **Go to Documents → Vault** in your wallet. If it is empty, it says so and
+   offers you the demo.
+2. **Create documents and give them a type.** The type is what becomes the
+   proxy hub — "Governance", "Legal", "Operations", whatever fits. Documents
+   with no type land under _Uncategorised_, which works but discloses less
+   usefully.
+3. **Write or upload.** Either edit a draft in the browser and publish it, or
+   upload a file. Uploading hashes the file locally and sends only the digest —
+   the bytes never leave your machine unless you explicitly turn on server
+   storage for that document.
+4. **Sign off.** Approvals bind the exact content hash, so a new version resets
+   approvals to zero. That is deliberate: your signers agreed to those bytes,
+   not to the title.
+
+The vault view then shows the spine: hubs on the left, the document you selected
+in the middle, and on the right the path a proof of it would reveal — together
+with the documents it would keep sealed, present only as hashes.
+
+There is a public demo of exactly this at [/vault](/vault), built from Mesh
+Multisig's own feature notes. It is real content with real hashes, and it is
+useful for seeing the mechanism before you have documents of your own.
+
+## What a disclosure gives away
+
+This is the part worth understanding before you rely on it.
+
+A disclosure of one document reveals:
+
+- that document's content and salt,
+- the hub it hangs under, and that hub's content,
+- the **hashes** of that hub's other children,
+- the **hashes** of the other hubs.
+
+A recipient re-hashes upward and checks the result against the signed root. If
+anything was altered, moved, or invented, the recomputation fails.
+
+What they learn that you may not have intended: **how many** documents sit under
+that hub, and **how many** hubs exist. Not their names, not their contents —
+counts. If those counts are themselves sensitive, split your hubs differently.
+
+What they do not learn: any other document's title or content, or anything about
+hubs you did not disclose.
+
+## What is not a button yet
+
+The construction is implemented and tested — building the trust graph, producing
+a disclosure, and verifying one against a root all exist as library code with
+tests covering relabelling, reordering, tampering and cross-vault splicing.
+
+**Exporting a disclosure from the UI is not wired up yet.** Today the vault view
+_shows_ you what a disclosure of the selected document would reveal and withhold,
+which is the part that changes how you organise your vault. Producing the
+artefact you hand to a counterparty is the next step, not a shipped one.
+
+Document sign-off itself is fully shipped: versions, content hashes,
+threshold approvals bound to those hashes, a frozen signer snapshot per round,
+and an offline-verifiable proof package you can export today.
+
+## Why the structure is worth adopting now
+
+Even before disclosure export lands, the vault changes something concrete: it
+makes the relationship between your documents explicit and tamper-evident. A
+signature over the root binds the whole structure beneath it, so "this was our
+governance spine on that date" becomes a checkable claim rather than an
+assertion.
+
+And the organising work — giving documents types, deciding which grouping you
+would be comfortable disclosing — is the part that takes judgement. The
+cryptography is already written.
diff --git a/src/pages/vault.tsx b/src/pages/vault.tsx
index a04523cc..1b247ba6 100644
--- a/src/pages/vault.tsx
+++ b/src/pages/vault.tsx
@@ -29,6 +29,17 @@ export default function Page({
           never their titles. Selecting a note shows the path a proof of it
           would reveal, and the siblings it would keep sealed.
         </p>
+        <p className="my-4 max-w-3xl text-sm text-neutral-500 dark:text-neutral-300 lg:text-base">
+          New to this?{" "}
+          <a
+            href="/blog/how-to-use-shielded-sign-off"
+            className="underline underline-offset-2"
+          >
+            How to use shielded sign-off
+          </a>{" "}
+          explains the two kinds of link, why one hub is not enough, and exactly
+          what a disclosure gives away.
+        </p>
         <p className="max-w-3xl font-mono text-xs text-neutral-500 dark:text-neutral-400">
           root {view.rootHash.slice(0, 32)}… · {view.hubs.length} hubs ·{" "}
           {view.notes.length} notes