From 07f7480e5f7dd0d4b6b6262cfe3fbd1d424cc3e8 Mon Sep 17 00:00:00 2001
From: bordumb <bordumbb@gmail.com>
Date: Mon, 20 Jul 2026 16:27:43 +0100
Subject: [PATCH] =?UTF-8?q?docs:=20witness-network=20IA=20redesign=20?=
 =?UTF-8?q?=E2=80=94=20promote=20to=20a=20top-level=20area?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Moves the witness-network pages out from under mcp to their own top-level
docs area, with a shared NavSection disclosure component and the
supporting content-layer + config changes. See docs/docs-ia-redesign-plan.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Auths-Id: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
Auths-Device: did:keri:EB5cPHY0t-ejNC_rUzPS1dclTvd6kG-R9mQzjozCuGgd
Auths-Anchor-Seq: 13
---
 components/docs/DocsSidebar.tsx               | 113 +----
 components/docs/NavSection.tsx                | 153 +++++++
 components/markdoc/CodeTabs.tsx               |  28 +-
 .../anchor-your-attestation.md                |  99 -----
 .../mcp/witness-network/choose-witnesses.md   |  71 ---
 .../docs/mcp/witness-network/conformance.md   |  73 ----
 content/docs/mcp/witness-network/index.md     |  59 ---
 .../docs/mcp/witness-network/run-a-witness.md | 111 -----
 .../mcp/witness-network/verify-freshness.md   |  83 ----
 content/docs/witness-network/glossary.md      |  33 ++
 content/docs/witness-network/index.md         |  43 ++
 .../operators/deploy-for-real.md              |  58 +++
 .../witness-network/operators/get-listed.md   |  60 +++
 .../operators/keep-the-registry-synced.md     |  42 ++
 .../operators/monitor-your-node.md            |  52 +++
 .../operators/prove-conformance.md            |  53 +++
 .../witness-network/operators/run-a-node.md   |  71 +++
 .../reference/acceptance-rules.md             |  91 ++++
 .../witness-network/reference/anchor-api.md   |  78 ++++
 .../reference/witness-node-cli.md             |  64 +++
 .../users/anchor-your-attestation.md          |  62 +++
 .../users/choose-your-witnesses.md            |  47 ++
 .../witness-network/users/do-i-need-this.md   |  33 ++
 .../users/handle-a-duplicity-proof.md         |  42 ++
 .../users/verify-an-anchored-attestation.md   |  58 +++
 docs/docs-ia-redesign-plan.md                 | 406 ++++++++++++++++++
 lib/content.ts                                |  39 +-
 next-env.d.ts                                 |   2 +-
 next.config.ts                                |   8 +
 29 files changed, 1516 insertions(+), 616 deletions(-)
 create mode 100644 components/docs/NavSection.tsx
 delete mode 100644 content/docs/mcp/witness-network/anchor-your-attestation.md
 delete mode 100644 content/docs/mcp/witness-network/choose-witnesses.md
 delete mode 100644 content/docs/mcp/witness-network/conformance.md
 delete mode 100644 content/docs/mcp/witness-network/index.md
 delete mode 100644 content/docs/mcp/witness-network/run-a-witness.md
 delete mode 100644 content/docs/mcp/witness-network/verify-freshness.md
 create mode 100644 content/docs/witness-network/glossary.md
 create mode 100644 content/docs/witness-network/index.md
 create mode 100644 content/docs/witness-network/operators/deploy-for-real.md
 create mode 100644 content/docs/witness-network/operators/get-listed.md
 create mode 100644 content/docs/witness-network/operators/keep-the-registry-synced.md
 create mode 100644 content/docs/witness-network/operators/monitor-your-node.md
 create mode 100644 content/docs/witness-network/operators/prove-conformance.md
 create mode 100644 content/docs/witness-network/operators/run-a-node.md
 create mode 100644 content/docs/witness-network/reference/acceptance-rules.md
 create mode 100644 content/docs/witness-network/reference/anchor-api.md
 create mode 100644 content/docs/witness-network/reference/witness-node-cli.md
 create mode 100644 content/docs/witness-network/users/anchor-your-attestation.md
 create mode 100644 content/docs/witness-network/users/choose-your-witnesses.md
 create mode 100644 content/docs/witness-network/users/do-i-need-this.md
 create mode 100644 content/docs/witness-network/users/handle-a-duplicity-proof.md
 create mode 100644 content/docs/witness-network/users/verify-an-anchored-attestation.md
 create mode 100644 docs/docs-ia-redesign-plan.md

diff --git a/components/docs/DocsSidebar.tsx b/components/docs/DocsSidebar.tsx
index 97f2929..fcd0ab2 100644
--- a/components/docs/DocsSidebar.tsx
+++ b/components/docs/DocsSidebar.tsx
@@ -1,18 +1,17 @@
 'use client'
 
 import Link from 'next/link'
-import { useEffect, useState } from 'react'
 import { usePathname } from 'next/navigation'
-import { ChevronDown } from 'lucide-react'
-import type { NavSection, ProductNav } from '@/lib/content'
+import type { ProductNav } from '@/lib/content'
+import { NavSection } from './NavSection'
 
 /**
- * Frontmatter-derived nav with the product switch on top: auths-mcp and
- * Identity & signing are separate worlds that never intermix. The switch
- * navigates to each product's landing page; the shown product follows the URL.
+ * Frontmatter-derived nav with the area switch on top. Areas are separate
+ * worlds that never intermix; the switch navigates to each area's landing page
+ * and the shown area follows the URL.
  *
- * Sections come in two shapes: flat (always open) and collapsible — one row
- * with a chevron for large topics, auto-expanded while the reader is inside.
+ * Every section renders through the one shared {@link NavSection} disclosure —
+ * same caret, same behaviour, in every area.
  */
 
 function productForPath(nav: ProductNav[], pathname: string): ProductNav['product'] {
@@ -22,7 +21,7 @@ function productForPath(nav: ProductNav[], pathname: string): ProductNav['produc
   return 'mcp'
 }
 
-/** A product's first navigable page — where its switch tab points. */
+/** An area's first navigable page — where its switch tab points. */
 function landingHref(p: ProductNav): string {
   for (const section of p.sections) {
     const first = section.items.find((i) => i.badge !== 'soon')
@@ -31,83 +30,14 @@ function landingHref(p: ProductNav): string {
   return '#'
 }
 
-function SectionItems({ section, pathname }: { section: NavSection; pathname: string }) {
-  return (
-    <ul className="space-y-0.5">
-      {section.items.map((item) => {
-        const isActive = pathname === item.href
-        if (item.badge === 'soon') {
-          return (
-            <li key={item.href}>
-              <div className="flex cursor-default items-center justify-between px-3 py-1.5 text-sm text-ink-faint/70">
-                <span>{item.label}</span>
-                <span className="rounded-sm border border-rule px-1.5 py-0.5 font-mono text-[10px] text-ink-faint">
-                  soon
-                </span>
-              </div>
-            </li>
-          )
-        }
-        return (
-          <li key={item.href}>
-            <Link
-              href={item.href}
-              className={`flex items-center justify-between border-l-2 px-3 py-1.5 text-sm transition-colors ${
-                isActive
-                  ? 'border-seal font-semibold text-ink'
-                  : 'border-transparent text-ink-soft hover:border-rule hover:text-ink'
-              }`}
-            >
-              <span>{item.label}</span>
-              {item.badge === 'new' ? (
-                <span className="rounded-sm bg-seal/10 px-1.5 py-0.5 font-mono text-[10px] font-semibold text-seal">
-                  new
-                </span>
-              ) : null}
-            </Link>
-          </li>
-        )
-      })}
-    </ul>
-  )
-}
-
-/** A large topic folded to one row; opens on click and while a child is active. */
-function CollapsibleSection({ section, pathname }: { section: NavSection; pathname: string }) {
-  const containsActive = section.items.some((i) => i.href === pathname)
-  const [open, setOpen] = useState(containsActive)
-  useEffect(() => {
-    if (containsActive) setOpen(true)
-  }, [containsActive])
-
-  return (
-    <div>
-      <button
-        type="button"
-        onClick={() => setOpen((v) => !v)}
-        aria-expanded={open}
-        className="mb-3 flex w-full items-center justify-between px-2 font-mono text-[11px] font-semibold uppercase tracking-[0.15em] text-ink-faint transition-colors hover:text-ink"
-      >
-        <span>{section.title}</span>
-        <ChevronDown
-          size={14}
-          aria-hidden="true"
-          className={`transition-transform ${open ? '' : '-rotate-90'}`}
-        />
-      </button>
-      {open ? <SectionItems section={section} pathname={pathname} /> : null}
-    </div>
-  )
-}
-
 export function DocsSidebar({ nav }: { nav: ProductNav[] }) {
   const pathname = usePathname()
   const currentProduct = productForPath(nav, pathname)
   const active = nav.find((p) => p.product === currentProduct) ?? nav[0]
 
   return (
-    <nav className="space-y-8">
-      <div aria-label="Product" className="flex rounded-lg border border-rule bg-paper p-1">
+    <nav className="space-y-6">
+      <div aria-label="Area" className="flex flex-col gap-1 rounded-lg border border-rule bg-paper p-1">
         {nav.map((p) => {
           const selected = p.product === currentProduct
           return (
@@ -115,10 +45,8 @@ export function DocsSidebar({ nav }: { nav: ProductNav[] }) {
               key={p.product}
               href={landingHref(p)}
               aria-current={selected ? 'page' : undefined}
-              className={`flex-1 rounded-md px-2 py-1.5 text-center font-mono text-[12px] transition-colors ${
-                selected
-                  ? 'bg-paper-deep font-semibold text-ink'
-                  : 'text-ink-faint hover:text-ink'
+              className={`rounded-md px-2 py-1.5 text-center font-mono text-[12px] transition-colors ${
+                selected ? 'bg-paper-deep font-semibold text-ink' : 'text-ink-faint hover:text-ink'
               }`}
             >
               {p.label}
@@ -127,18 +55,11 @@ export function DocsSidebar({ nav }: { nav: ProductNav[] }) {
         })}
       </div>
 
-      {active.sections.map((section) =>
-        section.collapsible ? (
-          <CollapsibleSection key={section.title} section={section} pathname={pathname} />
-        ) : (
-          <div key={section.title}>
-            <h3 className="mb-3 px-2 font-mono text-[11px] font-semibold uppercase tracking-[0.15em] text-ink-faint">
-              {section.title}
-            </h3>
-            <SectionItems section={section} pathname={pathname} />
-          </div>
-        )
-      )}
+      <div className="space-y-2">
+        {active.sections.map((section) => (
+          <NavSection key={section.title} section={section} pathname={pathname} />
+        ))}
+      </div>
     </nav>
   )
 }
diff --git a/components/docs/NavSection.tsx b/components/docs/NavSection.tsx
new file mode 100644
index 0000000..5f814d0
--- /dev/null
+++ b/components/docs/NavSection.tsx
@@ -0,0 +1,153 @@
+'use client'
+
+import Link from 'next/link'
+import { useEffect, useId, useState } from 'react'
+import { ChevronDown } from 'lucide-react'
+import type { NavItem, NavSection as NavSectionData } from '@/lib/content'
+
+/**
+ * One sidebar sub-category.
+ *
+ * Two shapes, chosen by content rather than configuration:
+ *
+ * - **Many pages** → a disclosure row with the caret on the LEFT, open by
+ *   default so the nav shows its full structure on arrival. Collapsing is the
+ *   reader's opt-in, and navigating into a collapsed section re-opens it.
+ * - **Exactly one page** (Overview, Glossary) → a plain row. A caret that
+ *   reveals a single child is noise, so there is none; the row is aligned to
+ *   the disclosure labels by a spacer the width of the caret.
+ *
+ * Every section in every area goes through this component, so the sidebar
+ * cannot drift into looking different between areas.
+ */
+
+/** Reserves the caret's width so plain rows align with disclosure labels. */
+function CaretSpacer() {
+  return <span aria-hidden="true" className="w-[13px] shrink-0" />
+}
+
+const ROW_CLASS =
+  'flex w-full items-center gap-1.5 px-2 py-1 font-mono text-[11px] font-semibold uppercase tracking-[0.15em] transition-colors'
+
+function NavItemRow({ item, pathname }: { item: NavItem; pathname: string }) {
+  if (item.badge === 'soon') {
+    return (
+      <li>
+        <div className="flex cursor-default items-center justify-between py-1.5 pl-8 pr-3 text-sm text-ink-faint/70">
+          <span>{item.label}</span>
+          <span className="rounded-sm border border-rule px-1.5 py-0.5 font-mono text-[10px] text-ink-faint">
+            soon
+          </span>
+        </div>
+      </li>
+    )
+  }
+
+  const isActive = pathname === item.href
+  return (
+    <li>
+      <Link
+        href={item.href}
+        aria-current={isActive ? 'page' : undefined}
+        className={`flex items-center justify-between border-l-2 py-1.5 pl-8 pr-3 text-sm transition-colors ${
+          isActive
+            ? 'border-seal font-semibold text-ink'
+            : 'border-transparent text-ink-soft hover:border-rule hover:text-ink'
+        }`}
+      >
+        <span>{item.label}</span>
+        {item.badge === 'new' ? (
+          <span className="rounded-sm bg-seal/10 px-1.5 py-0.5 font-mono text-[10px] font-semibold text-seal">
+            new
+          </span>
+        ) : null}
+      </Link>
+    </li>
+  )
+}
+
+/**
+ * A one-page section: the section title *is* the nav entry, linking straight to
+ * its single page. No caret, no nesting.
+ */
+function PlainSection({
+  section,
+  pathname,
+}: {
+  section: NavSectionData
+  pathname: string
+}) {
+  const item = section.items[0]
+  const isActive = pathname === item.href
+
+  if (item.badge === 'soon') {
+    return (
+      <div className={`${ROW_CLASS} cursor-default text-ink-faint/70`}>
+        <CaretSpacer />
+        <span>{section.title}</span>
+      </div>
+    )
+  }
+
+  return (
+    <Link
+      href={item.href}
+      aria-current={isActive ? 'page' : undefined}
+      className={`${ROW_CLASS} ${isActive ? 'text-ink' : 'text-ink-faint hover:text-ink'}`}
+    >
+      <CaretSpacer />
+      <span>{section.title}</span>
+    </Link>
+  )
+}
+
+/**
+ * Renders one nav section.
+ *
+ * Args:
+ * * `section`: the frontmatter-derived section (title + its pages).
+ * * `pathname`: the active route, used to auto-open the containing section.
+ */
+export function NavSection({
+  section,
+  pathname,
+}: {
+  section: NavSectionData
+  pathname: string
+}) {
+  const containsActive = section.items.some((i) => i.href === pathname)
+  const [open, setOpen] = useState(true)
+  const panelId = useId()
+
+  useEffect(() => {
+    if (containsActive) setOpen(true)
+  }, [containsActive])
+
+  if (section.items.length === 0) return null
+  if (section.items.length === 1) return <PlainSection section={section} pathname={pathname} />
+
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        aria-expanded={open}
+        aria-controls={panelId}
+        className={`${ROW_CLASS} text-ink-faint hover:text-ink`}
+      >
+        <ChevronDown
+          size={13}
+          aria-hidden="true"
+          className={`shrink-0 transition-transform ${open ? '' : '-rotate-90'}`}
+        />
+        <span>{section.title}</span>
+      </button>
+      {/* Kept mounted (hidden) so `aria-controls` always resolves. */}
+      <ul id={panelId} hidden={!open} className="mt-1 space-y-0.5">
+        {section.items.map((item) => (
+          <NavItemRow key={item.href} item={item} pathname={pathname} />
+        ))}
+      </ul>
+    </div>
+  )
+}
diff --git a/components/markdoc/CodeTabs.tsx b/components/markdoc/CodeTabs.tsx
index 085b734..a7146eb 100644
--- a/components/markdoc/CodeTabs.tsx
+++ b/components/markdoc/CodeTabs.tsx
@@ -41,9 +41,31 @@ export function CodeTabs({ children }: { children: ReactNode }) {
   const tabs = Children.toArray(children).filter(
     (c): c is ReactElement<CodeTabProps> => isValidElement(c) && 'lang' in ((c.props as object) ?? {})
   )
+  const langs = tabs.map((t) => t.props.lang)
+
+  // Tabs are identified by language and sync site-wide, so a duplicated `lang`
+  // makes every tab after the first unreachable — `indexOf` always resolves to
+  // the first match, and clicking the others is a no-op. Surface the authoring
+  // mistake rather than shipping dead tabs.
+  const langSignature = langs.join('|')
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'production') return
+    const seen = new Set<string>()
+    const duplicated = new Set<string>()
+    for (const l of langSignature.split('|')) {
+      if (seen.has(l)) duplicated.add(l)
+      seen.add(l)
+    }
+    if (duplicated.size > 0) {
+      console.warn(
+        `CodeTabs: duplicate lang(s) [${[...duplicated].join(', ')}] — use one tab per language. ` +
+          'For non-language variants (deploy tools, platforms), use separate headed sections instead.'
+      )
+    }
+  }, [langSignature])
+
   if (tabs.length === 0) return null
 
-  const langs = tabs.map((t) => t.props.lang)
   // Until hydration, and whenever the chosen language is absent, show the
   // block's own first tab.
   const chosen = hydrated && lang && langs.includes(lang) ? lang : langs[0]
@@ -71,7 +93,7 @@ export function CodeTabs({ children }: { children: ReactNode }) {
           const active = i === activeIndex
           return (
             <button
-              key={tab.props.lang}
+              key={`${tab.props.lang}-${i}`}
               ref={(el) => {
                 tabRefs.current[i] = el
               }}
@@ -100,7 +122,7 @@ export function CodeTabs({ children }: { children: ReactNode }) {
       </div>
       {tabs.map((tab, i) => (
         <div
-          key={tab.props.lang}
+          key={`${tab.props.lang}-${i}`}
           role="tabpanel"
           id={`${baseId}-panel-${i}`}
           aria-labelledby={`${baseId}-tab-${i}`}
diff --git a/content/docs/mcp/witness-network/anchor-your-attestation.md b/content/docs/mcp/witness-network/anchor-your-attestation.md
deleted file mode 100644
index 3ea9c0c..0000000
--- a/content/docs/mcp/witness-network/anchor-your-attestation.md
+++ /dev/null
@@ -1,99 +0,0 @@
----
-title: "Anchor your attestation"
-description: "Add the anchor leg to export-attestation: declare a witness set, collect cosignatures to the threshold, and publish an aggregate whose rollback would be evidence."
-product: mcp
-section: "Witness network"
-order: 2
-lastReviewed: "2026-07-20"
----
-
-`export-attestation` publishes one signed aggregate of your agent's private
-spend log — `{head, count, cumulative_cents, as_of}` — at a public URL. The
-market re-verifies it and credits growth it witnessed itself. No per-call row
-ever leaves your infrastructure.
-
-Unanchored, that aggregate proves authenticity and monotonicity to whoever
-fetched it. What it cannot prove is that you didn't quietly publish an older
-version, or show a different one to someone else. **Anchoring closes exactly
-that gap** — and it is one flag on the command you already run.
-
-{% steps %}
-{% step title="Declare your witness set" %}
-A set is `N` named members and a threshold `t`. Each member is a witness's
-public name and member key — the operator hands you both (a node prints its
-member key at first boot). Pick witnesses from the
-[public directory](https://auths.dev/network), or
-[run your own](/mcp/witness-network/run-a-witness) to start.
-
-The set travels inside every anchor as a content hash, so a verifier always
-knows exactly which `t`-of-`N` was promised. How to pick members and a
-threshold: [Choose your witnesses](/mcp/witness-network/choose-witnesses).
-{% /step %}
-
-{% step title="Export with the anchor leg" %}
-```bash
-auths-mcp export-attestation \
-  --live-dir ./live \
-  --agent <agent-did> --root <root-did> \
-  --out ./public/activity.json \
-  --registry-url https://github.com/you/registry \
-  --anchor-to https://w1.example.com \
-  --anchor-to https://w2.example.net \
-  --witness "w1=<w1 member key>" \
-  --witness "w2=<w2 member key>" \
-  --witness-threshold 2
-```
-
-The gateway signs the aggregate, submits the anchor tuple to every
-`--anchor-to` endpoint, and collects cosignatures:
-
-```output
-export-attestation: anchored — 2 cosignature(s), threshold 2
-export-attestation: head a470be04c3b4f6af… count 412 cumulative 15c → ./public/activity.json
-```
-
-The finalized anchor — tuple, resolved set, cosignatures, and each witness's
-log-inclusion proof — is embedded in `activity.json` itself. The gateway
-re-verifies the finalization locally before writing, so it never publishes an
-anchor a stranger would refuse.
-{% /step %}
-
-{% step title="Publish as usual" %}
-Nothing changes downstream: host `activity.json` (and the `audit.json`
-sibling written by `--registry-url`) at your listing's attestation URL. The
-anchor rides inside the same document; verifiers that predate the network
-simply ignore it.
-{% /step %}
-{% /steps %}
-
-{% callout type="warning" title="Below threshold, the export fails" %}
-Unreachable or refusing witnesses are reported per endpoint, and if the
-collected cosignatures don't reach the declared threshold the whole export
-fails — there is no silent fallback to an unanchored publish once you asked
-for anchoring. Fix the witness (or the set) and re-run.
-{% /callout %}
-
-## What each witness checks
-
-A witness keeps one durable record per spend chain: the last anchor it
-co-signed. Against that it enforces:
-
-| Rule | On violation |
-| --- | --- |
-| Index strictly increases | Refused |
-| Cumulative total never decreases | Refused |
-| Timestamp never goes backwards | Refused |
-| Same index, **different head** | Refused **with a duplicity proof** — a signed, portable contradiction |
-| Signature verifies under your agent's current keys | Refused (the witness resolves them from your public registry) |
-
-That last row is why the witness needs no trust in you, and you none in it:
-everything it asserts, anyone can re-check.
-
-## The payoff
-
-The market's receipts worker verifies embedded anchors and derives its tier
-from them — never from anything the document claims about itself. A verified
-anchor turns your listing's observation into a `witness`-tier record, and the
-badge upgrades from market-witnessed to **quorum-anchored (t-of-N)**. One
-market's memory can be doubted; a quorum of independent operators across
-jurisdictions is a different conversation.
diff --git a/content/docs/mcp/witness-network/choose-witnesses.md b/content/docs/mcp/witness-network/choose-witnesses.md
deleted file mode 100644
index 424bb29..0000000
--- a/content/docs/mcp/witness-network/choose-witnesses.md
+++ /dev/null
@@ -1,71 +0,0 @@
----
-title: "Choose your witnesses"
-description: "A quorum is only as honest as its operators are independent: how to pick members, set a threshold, and read the guarantee ceiling you just bought."
-product: mcp
-section: "Witness network"
-order: 4
-lastReviewed: "2026-07-20"
----
-
-Your declared set is the whole strength of your anchors. The cryptography is
-identical whether you declare one witness or seven — what changes is a single
-number: **how many independent parties must collude to lie about your
-history.**
-
-## What a set is
-
-`N` named members plus a threshold `t`. Each member carries its public name,
-its member key, and its operator facts — operator, organization,
-jurisdiction, infrastructure. The set is committed by a content hash that
-travels inside every anchor, so no one can quietly swap members after the
-fact: each anchor names exactly the set it was submitted under.
-
-Structural rules, enforced at declaration: at least one member, unique names,
-unique keys, `1 ≤ t ≤ N`.
-
-## The guarantee ceiling
-
-A finalized anchor proves that `t` declared witnesses saw this exact tuple
-and found it a monotone extension. The ceiling on that guarantee is
-independence:
-
-- Three nodes run by **one** operator are one witness with three signatures.
-- `t` witnesses must collude to co-sign a rollback; `N − t + 1` must be down
-  before you can't anchor at all.
-
-So diversity is not a compliance nicety — it is the number the whole
-construction rests on. Spread members across the four axes (operator,
-organization, jurisdiction, infrastructure), and prefer witnesses whose
-operators have nothing to gain from your books looking good. **The strongest
-witness in your set is one your counterparty — or your regulator — runs.**
-
-## Picking a threshold
-
-| Shape | What it buys | What it costs |
-| --- | --- | --- |
-| 1-of-1 (yourself) | The full loop, end to end; catches your own rollback bugs | No third-party guarantee — you witnessed yourself |
-| 1-of-2 | Either witness can be down | Either witness alone can co-sign a fork |
-| 2-of-3 | One witness can be down; two must collude to lie | Three operators to recruit — the production floor |
-| 3-of-5 | Two down; three to collude | Serious quorum, serious recruiting |
-
-Raising `t` buys collusion resistance and costs liveness. Start at 1-of-1 in
-development, ship at 2-of-3 across genuinely distinct operators, and grow the
-set as counterparties who care about your books appear — they are your best
-recruits.
-
-## Where witnesses come from
-
-- **The public directory** at [auths.dev/network](https://auths.dev/network)
-  lists conformant witnesses with the facts above and their live status.
-- **Run one yourself** — [it's one container](/mcp/witness-network/run-a-witness);
-  a self-run witness is a fine first member and a bad only member.
-- **Ask your counterparty.** Anyone who passes
-  [the conformance harness](/mcp/witness-network/conformance) can witness;
-  handing a counterparty a seat in your set converts their suspicion into
-  your guarantee.
-
-## Changing the set
-
-Sets aren't forever. Future anchors can declare a new set; every past anchor
-keeps verifying against the set it named. A verifier reading your history
-sees each era under the quorum that actually signed it.
diff --git a/content/docs/mcp/witness-network/conformance.md b/content/docs/mcp/witness-network/conformance.md
deleted file mode 100644
index 09a9162..0000000
--- a/content/docs/mcp/witness-network/conformance.md
+++ /dev/null
@@ -1,73 +0,0 @@
----
-title: "Conformance & the directory"
-description: "Who may join a witness set is answered with a test suite, not a policy document: the vectors, the live drive, and how a passing node gets listed."
-product: mcp
-section: "Witness network"
-order: 6
-lastReviewed: "2026-07-20"
----
-
-Anyone can claim to run an honest witness. The network's answer to "who may
-join a declared set" is a published test suite — pass it and you're
-conformant, whoever you are, whatever you built the node from. A regulator's
-in-house implementation and the shipped container clear the same bar.
-
-## What the vectors cover
-
-Four groups, generated from the same protocol core every verifier runs:
-
-| Group | The obligation it proves |
-| --- | --- |
-| Monotone accept | A well-ordered successor is co-signed |
-| Duplicity | Same index, different head is refused **and** the emitted proof verifies offline |
-| Regression | A non-monotone index is rejected outright |
-| Freshness ladder | `fresh`, `stale`, and `unanchored` are computed exactly as verifiers will |
-
-## Run it
-
-Against the shipped core, emitting the machine-readable vectors for your own
-harness:
-
-```bash
-cargo xtask witness-conformance --emit ./vectors
-```
-
-```output
-witness-conformance: wrote vectors to ./vectors/conformance-vectors.json
-witness-conformance: 4/4 vector groups passed
-```
-
-Against a **live** node — yours, or one you're evaluating:
-
-```bash
-cargo xtask witness-conformance --url http://127.0.0.1:3333
-```
-
-```output
-witness-conformance: live endpoint http://127.0.0.1:3333 passed 4/4 transport checks
-```
-
-The live drive proves the transport obligations: health answers, malformed
-and unauthorized submissions are refused fail-closed, unknown chains read as
-absent. Full acceptance vectors additionally need the conformance identity
-provisioned in your node's registry copy — emit the vectors and drive your
-own endpoint through them.
-
-{% callout type="info" title="The vectors are the wire contract" %}
-`conformance-vectors.json` is deliberately implementation-neutral: a witness
-written from scratch that answers the vectors correctly is conformant. The
-suite is the membership criterion, so it lives in the open repo where anyone
-can hold it against us too.
-{% /callout %}
-
-## Get listed in the directory
-
-The [public directory](https://auths.dev/network) shows each witness's name,
-operator, jurisdiction, infrastructure class, and live status — the facts
-principals choose sets by. Listing has one requirement: pass the harness.
-
-Send your conformance transcript, your node's public endpoint, and your
-operator facts to
-[network@auths.dev](mailto:network@auths.dev?subject=Witness%20directory%20listing).
-Independent operators are the point of the whole construction — the
-directory exists to be filled with witnesses nobody at Auths controls.
diff --git a/content/docs/mcp/witness-network/index.md b/content/docs/mcp/witness-network/index.md
deleted file mode 100644
index e571756..0000000
--- a/content/docs/mcp/witness-network/index.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: "The witness network"
-description: "Independent witnesses co-sign every history's growth, so hiding or rewriting the recent past stops being deniable — while verification stays offline and free."
-product: mcp
-section: "Witness network"
-order: 1
-lastReviewed: "2026-07-20"
----
-
-Receipts and attestations verify offline, forever — signatures, budgets, and
-monotone growth all re-derive on any machine with no account and no server.
-The one thing an offline check cannot prove is that you are looking at the
-**latest** history.
-
-That gap has exactly two cheap attacks:
-
-| Attack | What it looks like |
-| --- | --- |
-| **Withholding** | The recent records "don't exist" — you're shown a truncated history that verifies cleanly |
-| **Equivocation** | Two verifiers are shown two different histories, each internally consistent |
-
-Forgery is already futile; these two are free. The witness network makes them
-expensive by making them **attributable**.
-
-## What the network does
-
-A seller's agent periodically anchors its published aggregate — head, count,
-cumulative — with a set of witnesses it declared in advance. Each witness
-accepts only monotone growth, co-signs what it accepts, and records the
-acceptance in its own append-only log. Present the same index with a
-different head to any of them and what comes back is not a cosignature but a
-**duplicity proof**: a self-contained, signed contradiction any stranger can
-check.
-
-Once an anchor has cosignatures from `t` of the `N` declared witnesses, it is
-**finalized**. Rolling history back now requires contradicting a quorum's
-signatures in append-only logs — a rollback is no longer a deletion, it is
-evidence.
-
-Two things never change:
-
-- **Verification stays offline and free.** A finalized anchor adds one
-  labeled fact — `fresh`, `stale`, or `unanchored` — beside the verdicts,
-  never inside them.
-- **Witnesses see aggregates only.** No per-call rows, no counterparties, no
-  tool names. The private log never leaves the seller's infrastructure.
-
-## Who does what
-
-| Role | What they do | Start here |
-| --- | --- | --- |
-| Seller / agent operator | Anchors the published aggregate with a declared witness set | [Anchor your attestation](/mcp/witness-network/anchor-your-attestation) |
-| Relying party / buyer | Checks freshness beside the verdicts; refuses forks | [Verify freshness](/mcp/witness-network/verify-freshness) |
-| Principal choosing a set | Picks independent witnesses and a threshold | [Choose your witnesses](/mcp/witness-network/choose-witnesses) |
-| Witness operator | Runs one hardened node; co-signs monotone growth | [Run a witness](/mcp/witness-network/run-a-witness) |
-| Watcher | Reads many logs, compares, publishes contradictions | The market is one — its observations are public |
-
-The live network — the public witness directory and its status — is at
-[auths.dev/network](https://auths.dev/network).
diff --git a/content/docs/mcp/witness-network/run-a-witness.md b/content/docs/mcp/witness-network/run-a-witness.md
deleted file mode 100644
index efdcd45..0000000
--- a/content/docs/mcp/witness-network/run-a-witness.md
+++ /dev/null
@@ -1,111 +0,0 @@
----
-title: "Run a witness"
-description: "One container, three roles, one durable volume: stand up a conformant witness node, hand your member key to a principal, and keep the anti-equivocation memory safe."
-product: mcp
-section: "Witness network"
-order: 5
-lastReviewed: "2026-07-20"
----
-
-A witness is one operator artifact: a hardened HTTP surface, a durable anchor
-store, an append-only log, and one signing identity. It reimplements no
-protocol — the same acceptance rule and log code every verifier runs is what
-the node serves.
-
-## Quickstart
-
-{% steps %}
-{% step title="Boot the node" %}
-```bash
-git clone https://github.com/auths-dev/auths
-cd auths/deploy/witness
-WITNESS_SEED=$(openssl rand -hex 32) docker compose up -d
-```
-
-The compose file pins a durable volume for `/data`, mounts your registry copy
-read-only, and wires a container healthcheck. Keep the seed: it **is** the
-witness identity, and it must be identical on every restart.
-
-```output
-witness-node: anchor role up as `acme-w1` (member key did:key:z6Mk…)
-witness-node: listening on 0.0.0.0:3333
-```
-
-Prefer bare metal? The binary takes the same shape:
-
-```bash
-witness-node serve --roles anchor,kel,cosign --bind 0.0.0.0:3333 \
-  --data-dir /data --registry /registry --witness-name acme-w1
-```
-{% /step %}
-
-{% step title="Hand the member key to your principal" %}
-First boot prints your **member key**. Whoever's history you witness adds it
-— with your public name and operator facts (operator, organization,
-jurisdiction, infrastructure) — to their declared set. From then on your
-cosignature counts toward their `t`-of-`N`.
-
-Being removed from a set is the principal's one-liner, not yours: sets are
-theirs to declare, signatures are yours to give.
-{% /step %}
-
-{% step title="Prove conformance" %}
-```bash
-cargo xtask witness-conformance --url http://127.0.0.1:3333
-```
-
-```output
-witness-conformance: live endpoint http://127.0.0.1:3333 passed 4/4 transport checks
-```
-
-Passing [the harness](/mcp/witness-network/conformance) is the only entry bar
-for the [public directory](https://auths.dev/network).
-{% /step %}
-{% /steps %}
-
-## The three roles
-
-| Role | What it serves | Why it exists |
-| --- | --- | --- |
-| `anchor` | Spend-anchor acceptance and reads | The witness network's core: monotone growth or a duplicity proof |
-| `kel` | Receipt witnessing for key histories | Freshness for identity events, same posture |
-| `cosign` | Transparency-log checkpoint cosigning | Countersigns log heads so log operators can't rewrite either |
-
-Default is all three — one identity, one data dir, one hardening envelope. A
-role whose requirements aren't configured refuses to start with a named
-error; a partially configured witness never serves.
-
-## The surfaces
-
-| Endpoint | Behavior |
-| --- | --- |
-| `POST /v1/anchor` | Verify the party signature against their registry, enforce monotone growth, co-sign, log, return `{cosignature, inclusion}`. A fork at an existing index returns **409 with a duplicity proof** |
-| `GET /v1/anchor/{seed}` | The latest co-signed anchor for a chain — the public withholding-detection read |
-| `GET /health` | Liveness |
-
-Hardening is built in, not bolted on: request bodies are capped small (an
-anchor is a few KiB; anything larger is hostile), concurrency is limited, and
-slow requests are timed out.
-
-## What you must keep safe
-
-{% callout type="danger" title="The data dir is the anti-equivocation memory" %}
-The anchor store under `--data-dir` is the reason a fork gets caught: it
-holds the last co-signed anchor per chain. Run it on a persistent volume,
-back it up, and never wipe it — a witness with amnesia will happily co-sign
-the rollback it exists to refuse. The same dir holds your append-only log;
-the seed must survive restarts for the same reason.
-{% /callout %}
-
-Two operational duties round it out:
-
-- **Keep the registry copy current.** The anchor role resolves each
-  submitter's current keys from the local registry copy at `--registry`; a
-  stale copy refuses legitimate anchors (fail-closed, never fail-open). The
-  node refuses to start the role if the path is missing.
-- **Expect to be watched.** Watchers read your log and your latest-anchor
-  surface and compare them across witnesses. That's the job: being the party
-  whose silence or contradiction would be visible.
-
-Helm charts and Terraform for AWS, GCP, and Azure ship beside the compose
-file in `deploy/witness/` — the same templates the first-party quorum runs.
diff --git a/content/docs/mcp/witness-network/verify-freshness.md b/content/docs/mcp/witness-network/verify-freshness.md
deleted file mode 100644
index f048bea..0000000
--- a/content/docs/mcp/witness-network/verify-freshness.md
+++ /dev/null
@@ -1,83 +0,0 @@
----
-title: "Verify freshness"
-description: "Read the freshness ladder beside the verdicts, verify an embedded anchor with one SDK call, and know what a duplicity proof obliges you to do."
-product: mcp
-section: "Witness network"
-order: 3
-lastReviewed: "2026-07-20"
----
-
-Freshness is a separate, labeled fact. It sits **beside** the authorization
-verdicts, never inside them — a perfectly authorized history can still be an
-old view, and you deserve to know which one you're looking at.
-
-## The ladder
-
-| Status | Meaning | What to do |
-| --- | --- | --- |
-| `fresh` | The history you hold extends the best finalized anchor | Nothing — this is the good state |
-| `stale` | A finalized anchor exists **ahead** of the history you were given | You're looking at an old view; fetch the current one, and ask why you were handed a stale one |
-| `unanchored` | No anchor at all | Judge by the other tiers of evidence; growth may still be market-witnessed |
-
-`stale` is not tampering — tampering fails verification outright. Stale means
-the math checked out on a view someone chose not to update.
-
-## Verify an anchored attestation
-
-One call does everything: signature under the agent's current keys, the
-delegation to the claimed root, and — when an anchor is embedded — the full
-finalization: the set's content hash, threshold, each cosignature, and each
-witness's log-inclusion proof.
-
-```js
-const sdk = require('@auths-dev/sdk')
-const check = JSON.parse(sdk.verifyActivityAttestation(doc, registryDir))
-
-check.ok      // false if ANY part fails — including a bad embedded anchor
-check.anchor  // null, or the verified quorum shape:
-// { tier: 'witness', threshold: 2, witnesses: 3, cosigners: 2,
-//   seedId: 'c6ec71d2…', witnessSetSaid: 'EHSPi3…' }
-```
-
-Two properties worth naming:
-
-- **A present-but-bad anchor fails the whole document.** There is no "the
-  signature was fine but the anchor wasn't" gray zone — an anchored document
-  either proves its quorum or proves nothing.
-- **`anchor` restates verified facts only.** The tier is derived from
-  cryptography the SDK just re-checked, never from a claim inside the
-  document. (The field ships in SDK releases after 0.1.12; older builds omit
-  it, and consumers treat absence as unanchored.)
-
-## Duplicity proofs
-
-A duplicity proof is what a witness emits instead of a cosignature when the
-same chain presents the same index with two different heads. It contains both
-signed tuples, verifies offline, and requires no trust in the witness that
-emitted it — the contradiction is in the submitter's own signatures.
-
-Treat one as disqualifying. There is no innocent reading of two histories at
-one index, and the proof is portable: attach it to a dispute, publish it,
-hand it to a counterparty. Watchers (the market among them) scan witness logs
-for exactly these collisions.
-
-## Check for withholding
-
-Every witness answers for the latest anchor it co-signed on a chain:
-
-```bash
-curl https://w1.example.com/v1/anchor/<seed-id>
-```
-
-If the newest anchor any declared witness holds is days old while the seller
-claims live activity, you are being shown a gap. Anchoring cadence is a
-promise its absence breaks visibly.
-
-## What you trust, spelled out
-
-Nothing new. Verification still runs on your machine from public inputs: the
-attestation, the seller's public registry, and the anchor riding in the
-document. The network's guarantee has a ceiling — the independence of the
-declared witnesses, which is [the chooser's problem](/mcp/witness-network/choose-witnesses)
-— but every input to that judgment (operators, jurisdictions, threshold) is
-in the anchor for you to read.
diff --git a/content/docs/witness-network/glossary.md b/content/docs/witness-network/glossary.md
new file mode 100644
index 0000000..e87f3e4
--- /dev/null
+++ b/content/docs/witness-network/glossary.md
@@ -0,0 +1,33 @@
+---
+title: "Glossary"
+description: "Every witness-network term, in one line each."
+product: witness
+section: "Glossary"
+order: 1
+lastReviewed: "2026-07-20"
+---
+
+| Term | Means |
+| --- | --- |
+| **Anchor** | One signed tuple — `{head, count, cumulative, as_of}` — submitted to witnesses. The only thing a witness ever sees. |
+| **Chain** | One agent's spend history, identified by a seed id. |
+| **Seed id** | The stable identifier of a chain, derived from the public delegation. Used to read a witness: `GET /v1/anchor/{seed}`. |
+| **Head** | The commitment to the whole private log at a point in time. Reveals nothing about its contents. |
+| **Witness** | A node that co-signs monotone growth and logs what it accepted. Sees aggregates only. |
+| **Member key** | A witness's public signing key, printed at first boot. What principals put in their declared set. |
+| **Witness set (𝒲)** | `N` named members plus a threshold `t`, committed by a content hash carried inside every anchor. |
+| **Threshold (`t`)** | How many cosignatures finalize an anchor. `t` must collude to lie; `N − t + 1` down blocks anchoring. |
+| **Finalized anchor** | An anchor carrying ≥ `t` distinct cosignatures from the declared set, each with a log-inclusion proof. |
+| **Cosignature** | A witness's signature over an anchor it accepted. |
+| **Inclusion proof** | Evidence that a witness put the anchor in its append-only log, rooted in a signed checkpoint. |
+| **Duplicity proof** | Both signed tuples for one `(chain, index)` — a portable, offline-verifiable contradiction. |
+| **Equivocation** | Showing two verifiers two different histories. What a duplicity proof catches. |
+| **Withholding** | Serving a truncated history so recent records "don't exist". What freshness catches. |
+| **Freshness** | A labeled result — `fresh`, `stale`, `unanchored` — reported beside the verdicts, never inside them. |
+| **Stale** | A finalized anchor exists ahead of the history you were given. Not tampering — tampering fails outright. |
+| **Unanchored** | No anchor reachable. Freshness unknown, which is never the same as fresh. |
+| **Watcher** | Anyone reading many witness logs and comparing them. The market is one. |
+| **Anchor store** | The node's durable record of the last anchor co-signed per chain — its anti-equivocation memory. |
+| **Roles** | `anchor` (spend anchors), `kel` (key-history receipts), `cosign` (log checkpoints). One node serves any combination. |
+| **Registry copy** | The node's local copy of parties' public identity events, used to resolve submitters' current keys. |
+| **Conformance vectors** | The published, implementation-neutral test suite that defines what a witness must do. |
diff --git a/content/docs/witness-network/index.md b/content/docs/witness-network/index.md
new file mode 100644
index 0000000..073f0f0
--- /dev/null
+++ b/content/docs/witness-network/index.md
@@ -0,0 +1,43 @@
+---
+title: "Witness network"
+description: "Independent witnesses co-sign your history's growth, so hiding or rewriting the recent past stops being deniable."
+product: witness
+section: "Overview"
+order: 1
+lastReviewed: "2026-07-20"
+---
+
+Receipts verify offline, forever. The one thing an offline check **cannot** prove
+is that you are looking at the *latest* history.
+
+Two attacks exploit that gap, and both are free:
+
+| Attack | What it looks like |
+| --- | --- |
+| **Withholding** | Recent records "don't exist" — you get a truncated history that verifies cleanly |
+| **Equivocation** | Two verifiers are shown two different histories, each internally consistent |
+
+Witnesses co-sign every step forward. Rolling history back then means
+contradicting signatures sitting in append-only logs — the rollback stops being
+a deletion and becomes evidence.
+
+## Start here
+
+{% card-group %}
+{% card title="I publish attestations" href="/witness-network/users/do-i-need-this" %}
+Anchor your aggregate so a rollback is attributable.
+{% /card %}
+{% card title="I verify attestations" href="/witness-network/users/verify-an-anchored-attestation" %}
+Check an anchor and read the freshness result.
+{% /card %}
+{% card title="I want to run a witness" href="/witness-network/operators/run-a-node" %}
+One container, five minutes.
+{% /card %}
+{% /card-group %}
+
+Two things never change:
+
+- **Verification stays offline and free.** An anchor adds one labeled fact —
+  `fresh`, `stale`, or `unanchored` — *beside* the verdicts, never inside them.
+- **Witnesses see aggregates only.** No per-call rows, no counterparties, no
+  tool names. Your private log never leaves your infrastructure.
diff --git a/content/docs/witness-network/operators/deploy-for-real.md b/content/docs/witness-network/operators/deploy-for-real.md
new file mode 100644
index 0000000..542fa07
--- /dev/null
+++ b/content/docs/witness-network/operators/deploy-for-real.md
@@ -0,0 +1,58 @@
+---
+title: "Deploy for real"
+description: "Helm, Terraform, or systemd — with a pinned image digest and a durable anchor store."
+product: witness
+section: "Operators"
+order: 2
+lastReviewed: "2026-07-20"
+---
+
+The same templates the first-party quorum runs ship in `deploy/witness/`.
+
+## Helm
+
+```bash
+helm install acme-w1 ./deploy/witness/helm \
+  --set image.digest=sha256:<digest> \
+  --set seed.existingSecret=acme-w1-seed \
+  --set anchorStore.size=10Gi
+```
+
+## Terraform
+
+```bash
+cd deploy/witness/terraform/aws
+terraform init
+terraform apply -var image_digest=sha256:<digest> -var witness_seed=$WITNESS_SEED
+```
+
+`terraform/` has `aws`, `gcp`, and `azure`. Running your quorum across providers
+is how a fleet spans distinct infrastructure and jurisdictions.
+
+## systemd
+
+```bash
+cp docs/deployment/witness/witness-node.service /etc/systemd/system/
+systemctl enable --now witness-node
+```
+
+## Non-negotiables
+
+| Rule | Why |
+| --- | --- |
+| **Pin the image by digest** | A tag is not reproducible. Verifiers can check which binary you ran. |
+| **Durable volume for `/data`** | It's the anti-equivocation memory — never `tmpfs`, never wiped. |
+| **Back up `/data` and the seed** | Losing either makes you a new witness with no memory. |
+| **One writer** | Single replica, `Recreate` strategy, `ReadWriteOnce`. Two writers can co-sign a fork. |
+
+{% callout type="warning" title="Restore is not a fresh start" %}
+If you restore `/data` from a backup that is *behind* your real position, you
+can co-sign an index you already signed differently. Restore the newest state
+you have, or rotate to a new identity.
+{% /callout %}
+
+**If it fails:** a pod that starts and immediately exits is usually a missing
+`WITNESS_SEED` secret or an unmountable data volume — check the named startup
+error before anything else.
+
+**Next:** [Keep the registry synced](/witness-network/operators/keep-the-registry-synced).
diff --git a/content/docs/witness-network/operators/get-listed.md b/content/docs/witness-network/operators/get-listed.md
new file mode 100644
index 0000000..ee20140
--- /dev/null
+++ b/content/docs/witness-network/operators/get-listed.md
@@ -0,0 +1,60 @@
+---
+title: "Get listed in the directory"
+description: "Submit your node to the public directory, and what the interim admissions process means for trust."
+product: witness
+section: "Operators"
+order: 6
+lastReviewed: "2026-07-20"
+---
+
+The [public directory](https://auths.dev/network) lists conformant witnesses with
+the facts principals pick sets by. Listing has one bar: pass the harness.
+
+## Submit
+
+```bash
+cargo xtask witness-conformance --url https://w1.acme.example > conformance.txt
+```
+
+Send to [network@auths.dev](mailto:network@auths.dev?subject=Witness%20directory%20listing):
+
+| Field | Example |
+| --- | --- |
+| Node endpoint | `https://w1.acme.example` |
+| Witness name | `acme-w1` |
+| Member key | `did:key:z6Mk…` (printed at first boot) |
+| Operator facts | operator, organization, jurisdiction, infrastructure |
+| Region | `us-west` |
+| Conformance transcript | `conformance.txt` |
+
+## How admissions work today
+
+Entries are admitted by an **attestation signed with a single admissions key**
+held by Auths. Your browser then does two checks before trusting any entry:
+
+1. The admissions attestation re-verifies under a key **pinned into the app
+   bundle at build time** — never read from the served document.
+2. The exact roster bytes hash to the id that attestation commits to, so the
+   attestation can't be reused over a swapped entry list.
+
+Only a roster that passes both can supply keys to anything else on the site.
+
+{% callout type="warning" title="This is interim governance, and it is centralized" %}
+One key decides who appears. That key can add or omit an operator — the
+directory says so on its face rather than implying neutrality it doesn't have.
+
+What it **cannot** do: forge your cosignatures, or make a bad anchor verify. The
+directory is a *discovery* surface. Every guarantee you rely on is re-checked
+from the anchor itself, so a compromised or partial directory costs you
+discoverability, never correctness.
+{% /callout %}
+
+## You don't need the directory
+
+Listing is convenience, not permission. A principal can add your name and member
+key to their declared set directly — the set is theirs to declare and your
+signature is yours to give. Nothing in the protocol consults the directory.
+
+**If your listing is refused or delayed:** the conformance transcript is the
+objective part; ask for the specific check that failed and re-drive after fixing
+it.
diff --git a/content/docs/witness-network/operators/keep-the-registry-synced.md b/content/docs/witness-network/operators/keep-the-registry-synced.md
new file mode 100644
index 0000000..f2c057f
--- /dev/null
+++ b/content/docs/witness-network/operators/keep-the-registry-synced.md
@@ -0,0 +1,42 @@
+---
+title: "Keep the registry synced"
+description: "The anchor role resolves submitters' keys from your local registry copy — a stale copy refuses legitimate anchors."
+product: witness
+section: "Operators"
+order: 3
+lastReviewed: "2026-07-20"
+---
+
+`--registry` points at your own copy of the parties' **public** identity
+registry. The anchor role reads it to resolve each submitter's current keys.
+
+```bash
+git -C /var/lib/auths-registry pull --ff-only
+```
+
+Run it on a timer:
+
+```bash
+*/5 * * * * git -C /var/lib/auths-registry pull --ff-only
+```
+
+## Why it matters
+
+A submitter who rotated keys since your last sync will fail signature
+verification, and you'll refuse an anchor that was perfectly valid. The node
+**fails closed** — it never accepts a signature it cannot check.
+
+| Symptom | Cause |
+| --- | --- |
+| A specific party's anchors are refused, others work | Stale copy — that party rotated |
+| The anchor role won't start | `--registry` path missing |
+| Everything is refused | You're pointing at the wrong registry |
+
+{% callout type="info" title="Public data only" %}
+The registry holds public identity events. Nothing secret lives here, and a
+witness never sees a per-call row, counterparty, or tool name — only the
+aggregate tuple.
+{% /callout %}
+
+**If it fails:** confirm the path is a real checkout and readable by the node
+user (compose mounts it read-only), then re-run the failing submission.
diff --git a/content/docs/witness-network/operators/monitor-your-node.md b/content/docs/witness-network/operators/monitor-your-node.md
new file mode 100644
index 0000000..9f208bd
--- /dev/null
+++ b/content/docs/witness-network/operators/monitor-your-node.md
@@ -0,0 +1,52 @@
+---
+title: "Monitor your node"
+description: "Health, the signed build proof, and the console that re-verifies both in your browser."
+product: witness
+section: "Operators"
+order: 4
+lastReviewed: "2026-07-20"
+---
+
+Two endpoints, and a console that checks them for you.
+
+```bash
+curl -s localhost:3333/health
+curl -s localhost:3333/build
+```
+
+```output
+{"status":"ok","roles":["anchor","kel","cosign"],"witness":"acme-w1"}
+{"version":"0.1.12","running_digest":"sha256:…","attestation":{…}}
+```
+
+`/build` is the node's **signed** statement of which binary it runs — checked
+against the digest you deployed.
+
+## The console
+
+Open your node in the network console at
+[auths.dev/network](https://auths.dev/network) → **node**. It reads `/health`
+and `/build` and re-verifies the signed payloads **in your browser** with the
+published WASM verifier. The node is treated as an untrusted data source;
+trust comes from the in-browser check, never the connection.
+
+## Container healthcheck
+
+The image ships its own probe — no `curl` needed inside the container:
+
+```bash
+witness-node healthcheck --url http://127.0.0.1:3333/health
+```
+
+Exit `0` is healthy. Compose already wires this on a 30s interval.
+
+## What to alert on
+
+| Signal | Meaning |
+| --- | --- |
+| `/health` non-200 | Node down — your cosignature is missing from live quorums |
+| `/build` digest ≠ deployed digest | You're running something you didn't deploy |
+| Disk pressure on `/data` | The anchor store cannot grow — anchors will start failing |
+
+**If it fails:** a node that answers `/health` but not `/build` was started
+without a build attestation — that surface is optional, not a fault.
diff --git a/content/docs/witness-network/operators/prove-conformance.md b/content/docs/witness-network/operators/prove-conformance.md
new file mode 100644
index 0000000..fe45eb2
--- /dev/null
+++ b/content/docs/witness-network/operators/prove-conformance.md
@@ -0,0 +1,53 @@
+---
+title: "Prove conformance"
+description: "Run the published test suite against your node — the only entry bar for the directory."
+product: witness
+section: "Operators"
+order: 5
+lastReviewed: "2026-07-20"
+---
+
+Drive your live node through the published suite:
+
+```bash
+cargo xtask witness-conformance --url http://127.0.0.1:3333
+```
+
+```output
+witness-conformance: live endpoint http://127.0.0.1:3333 passed 4/4 transport checks
+```
+
+Emit the machine-readable vectors to drive your own harness (or a node you built
+from scratch):
+
+```bash
+cargo xtask witness-conformance --emit ./vectors
+```
+
+```output
+witness-conformance: wrote vectors to ./vectors/conformance-vectors.json
+witness-conformance: 4/4 vector groups passed
+```
+
+## What the vectors cover
+
+| Group | The obligation it proves |
+| --- | --- |
+| Monotone accept | A well-ordered successor is co-signed |
+| Duplicity | Same index, different head is refused **and** the emitted proof verifies offline |
+| Regression | A non-monotone index is rejected outright |
+| Freshness ladder | `fresh`, `stale`, `unanchored` computed exactly as verifiers will |
+
+The live drive proves the transport obligations: health answers, malformed and
+unauthorized submissions are refused fail-closed, unknown chains read as absent.
+
+{% callout type="info" title="The vectors are the wire contract" %}
+`conformance-vectors.json` is implementation-neutral. A witness written from
+scratch that answers the vectors correctly is conformant — the suite lives in
+the open repo so anyone can hold it against us too.
+{% /callout %}
+
+**If it fails:** full acceptance vectors need the conformance identity present in
+your registry copy. Emit the vectors, provision that identity, then re-drive.
+
+**Next:** [Get listed in the directory](/witness-network/operators/get-listed).
diff --git a/content/docs/witness-network/operators/run-a-node.md b/content/docs/witness-network/operators/run-a-node.md
new file mode 100644
index 0000000..368c2d5
--- /dev/null
+++ b/content/docs/witness-network/operators/run-a-node.md
@@ -0,0 +1,71 @@
+---
+title: "Run a node in 5 minutes"
+description: "One container, three roles, one identity seed — up and answering /health."
+product: witness
+section: "Operators"
+order: 1
+lastReviewed: "2026-07-20"
+---
+
+**Before you start:** Docker, and a local copy of the parties' public identity
+registry (see [Keep the registry synced](/witness-network/operators/keep-the-registry-synced)).
+
+```bash
+git clone https://github.com/auths-dev/auths
+cd auths/deploy/witness
+
+export WITNESS_SEED=$(openssl rand -hex 32)   # this IS your identity — keep it
+export WITNESS_REGISTRY=/path/to/registry     # required; mounted read-only
+export WITNESS_NAME=acme-w1
+
+docker compose up -d
+```
+
+Confirm it's up:
+
+```bash
+curl -s localhost:3333/health
+```
+
+```output
+{"status":"ok","roles":["anchor","kel","cosign"],"witness":"acme-w1"}
+```
+
+Your **member key** is printed at first boot — that's what principals add to
+their declared set:
+
+```bash
+docker compose logs | grep 'member key'
+```
+
+```output
+witness-node: anchor role up as `acme-w1` (member key did:key:z6Mk…)
+```
+
+{% callout type="danger" title="Two things will silently break trust" %}
+- **`WITNESS_SEED` must be identical on every restart.** A changed seed is a
+  *new witness* — your cosignatures stop counting toward anyone's threshold.
+- **`/data` must be a durable volume.** It holds the last anchor you co-signed
+  per chain. A witness with amnesia will happily co-sign the rollback it exists
+  to refuse.
+{% /callout %}
+
+## Without Docker
+
+```bash
+witness-node serve --roles anchor,kel,cosign --bind 0.0.0.0:3333 \
+  --data-dir /var/lib/auths-witness \
+  --registry /var/lib/auths-registry \
+  --witness-name acme-w1
+```
+
+`WITNESS_SEED` is read from the environment. Full flags:
+[witness-node CLI](/witness-network/reference/witness-node-cli).
+
+**If it fails:**
+
+- *`set WITNESS_REGISTRY…`* — compose requires it; there is no default.
+- *a role refuses to start* — that role's required config is missing. The node
+  fails closed with a named error rather than serving a half-configured witness.
+
+**Next:** [Deploy for real](/witness-network/operators/deploy-for-real).
diff --git a/content/docs/witness-network/reference/acceptance-rules.md b/content/docs/witness-network/reference/acceptance-rules.md
new file mode 100644
index 0000000..3335521
--- /dev/null
+++ b/content/docs/witness-network/reference/acceptance-rules.md
@@ -0,0 +1,91 @@
+---
+title: "Acceptance rules & shapes"
+description: "What a witness enforces, how a set and a finalized anchor are structured, and the guarantee ceiling that follows."
+product: witness
+section: "Reference"
+order: 3
+lastReviewed: "2026-07-20"
+---
+
+## What a witness enforces
+
+A witness keeps one durable record per chain: the last anchor it co-signed.
+Against that it checks every submission.
+
+| Rule | On violation |
+| --- | --- |
+| Index strictly increases | Refused |
+| Cumulative total never decreases | Refused |
+| Timestamp never goes backwards | Refused |
+| Same index, **different head** | Refused **with a duplicity proof** |
+| Signature verifies under the party's current keys | Refused (keys resolved from the local registry copy) |
+
+The check is fail-closed: a signature the witness cannot verify is never
+accepted.
+
+## What a witness sees
+
+The anchor tuple only — `{head, count, cumulative, as_of}` plus the set
+reference and the party signature. Never a per-call row, a counterparty, or a
+tool name. The private log stays on the publisher's infrastructure.
+
+## The witness set
+
+`N` named members plus a threshold `t`. Each member carries a public name, a
+member key, and operator facts (operator, organization, jurisdiction,
+infrastructure).
+
+Structural rules, enforced at declaration:
+
+- at least one member
+- unique names, unique keys
+- `1 ≤ t ≤ N`
+
+The set is committed by a **content hash carried inside every anchor**, so
+members can't be swapped after the fact — each anchor names exactly the set it
+was submitted under.
+
+## Finalization
+
+An anchor is finalized once it carries **≥ `t` distinct cosignatures from
+members of the declared set**, each with that witness's log-inclusion proof. A
+verifier re-checks all of it offline:
+
+- every cosigner is in the declared set
+- cosignatures are distinct (one member can't count twice)
+- the count reaches `t`
+- each inclusion proof roots in that witness's signed checkpoint
+
+## The guarantee ceiling
+
+A finalized anchor proves `t` declared witnesses saw this exact tuple and found
+it a monotone extension. What bounds that:
+
+- `t` witnesses must **collude** to co-sign a rollback.
+- `N − t + 1` must be **down** before you cannot anchor at all.
+- Three nodes run by one operator are **one** witness with three signatures —
+  independence, not node count, is the real number.
+
+## The freshness ladder
+
+Computed from the best finalized anchor a verifier can reach, and reported
+*beside* the verdicts — never inside them.
+
+| Status | Condition |
+| --- | --- |
+| `fresh` | The history held extends the best finalized anchor |
+| `stale` | A finalized anchor exists ahead of the history held |
+| `unanchored` | No anchor reachable |
+
+## Duplicity proofs
+
+Self-contained: both signed tuples for one `(chain, index)`. Verifies offline
+with no trust in the emitting witness — the contradiction is in the submitter's
+own signatures. Portable by design, so a watcher can publish one and anyone can
+re-check it.
+
+## Changing sets over time
+
+Future anchors may declare a new set; past anchors keep verifying against the
+set they named. A verifier reading a history sees each era under the quorum that
+actually signed it.
diff --git a/content/docs/witness-network/reference/anchor-api.md b/content/docs/witness-network/reference/anchor-api.md
new file mode 100644
index 0000000..7fbd440
--- /dev/null
+++ b/content/docs/witness-network/reference/anchor-api.md
@@ -0,0 +1,78 @@
+---
+title: "Anchor HTTP API"
+description: "The endpoints a witness serves, their responses, and the hardening applied to all of them."
+product: witness
+section: "Reference"
+order: 2
+lastReviewed: "2026-07-20"
+---
+
+## `POST /v1/anchor`
+
+Submit one anchor. The witness verifies the party signature against its registry
+copy, enforces monotone growth, co-signs, logs, and returns the cosignature with
+its log-inclusion proof.
+
+```output
+200 OK
+{ "cosignature": { "witness": "acme-w1", "signature": "…" },
+  "inclusion":   { "checkpoint": {…}, "proof": [ … ] } }
+```
+
+A fork at an existing index returns a duplicity proof instead:
+
+```output
+409 Conflict
+{ "duplicity": { "seedId": "c6ec71d2…", "index": 412, "a": {…}, "b": {…} } }
+```
+
+| Status | Meaning |
+| --- | --- |
+| `200` | Co-signed |
+| `409` | Duplicity — same index, different head. Body is the proof. |
+| `4xx` | Refused: bad signature, non-monotone, unknown party, or malformed body |
+
+## `GET /v1/anchor/{seed}`
+
+The latest co-signed anchor for a chain — the public withholding-detection read.
+
+```bash
+curl https://w1.example.com/v1/anchor/<seed-id>
+```
+
+| Status | Meaning |
+| --- | --- |
+| `200` | The latest anchor this witness co-signed |
+| `404` | This witness has never co-signed this chain |
+
+## `GET /health`
+
+Liveness. `200` with the served roles and witness name.
+
+## `GET /build`
+
+The node's signed statement of which binary it runs (`version`,
+`running_digest`, `attestation`). Absent — `404` — when the node was started
+without a build attestation; that surface is optional.
+
+## `POST /add-checkpoint`
+
+Served by the `cosign` role: countersigns a transparency-log head after checking
+consistency.
+
+## Hardening
+
+Applied to every route, not bolted on per-handler:
+
+| Control | Behaviour |
+| --- | --- |
+| Body cap | Small — an anchor is a few KiB; larger is treated as hostile |
+| Concurrency limit | Bounded in-flight requests |
+| Timeout | Slow requests answered `408` |
+
+## Trust posture
+
+Everything a witness asserts is re-checkable by anyone: it needs no trust in the
+submitter, and the submitter needs none in it. Clients should treat a node as an
+**untrusted data source** and verify signed payloads themselves — which is what
+the network console does in-browser.
diff --git a/content/docs/witness-network/reference/witness-node-cli.md b/content/docs/witness-network/reference/witness-node-cli.md
new file mode 100644
index 0000000..9cbd409
--- /dev/null
+++ b/content/docs/witness-network/reference/witness-node-cli.md
@@ -0,0 +1,64 @@
+---
+title: "witness-node CLI"
+description: "Every flag on serve and healthcheck, and what each role requires."
+product: witness
+section: "Reference"
+order: 1
+lastReviewed: "2026-07-20"
+---
+
+## `witness-node serve`
+
+```bash
+witness-node serve --roles anchor,kel,cosign --bind 0.0.0.0:3333 \
+  --data-dir /var/lib/auths-witness \
+  --registry /var/lib/auths-registry \
+  --witness-name acme-w1
+```
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--roles <list>` | `anchor,kel,cosign` | Comma-separated roles to serve. |
+| `--bind <addr>` | `127.0.0.1:3333` | Bind address. Use `0.0.0.0:3333` in a container. |
+| `--data-dir <dir>` | *required* | Durable anchor store **and** append-only log. Must be a persistent volume. |
+| `--registry <dir>` | *required* | Local copy of the parties' public identity registry, used to resolve submitters' current keys. |
+| `--witness-name <name>` | *required* | Public name carried in cosignatures and checkpoints. |
+| `--seed <hex>` | env `WITNESS_SEED` | 64-hex Ed25519 seed. One key serves cosignatures **and** log checkpoints. |
+
+`WITNESS_SEED` is read from the environment so the value never lands in
+`ps`/shell history.
+
+## `witness-node healthcheck`
+
+```bash
+witness-node healthcheck --url http://127.0.0.1:3333/health
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--url <url>` | Health URL to probe. Exit `0` iff the response is 200. |
+
+A dependency-free HTTP/1.0 probe over a plain socket — it runs inside the
+distroless image where no HTTP tooling exists.
+
+## The roles
+
+| Role | Serves | Requires |
+| --- | --- | --- |
+| `anchor` | Spend-anchor acceptance and reads | `--data-dir`, `--registry` |
+| `kel` | Receipt witnessing for key histories | `--data-dir` |
+| `cosign` | Transparency-log checkpoint cosigning | `--data-dir` |
+
+All roles share one identity seed, one data dir, and one hardening envelope. A
+role whose requirements aren't configured **refuses to start with a named
+error** — a partially configured witness never serves.
+
+## Identity
+
+The seed *is* the witness. Changing it produces a different member key, which
+stops counting toward any principal's threshold. The member key is printed at
+first boot:
+
+```output
+witness-node: anchor role up as `acme-w1` (member key did:key:z6Mk…)
+```
diff --git a/content/docs/witness-network/users/anchor-your-attestation.md b/content/docs/witness-network/users/anchor-your-attestation.md
new file mode 100644
index 0000000..84bf8ee
--- /dev/null
+++ b/content/docs/witness-network/users/anchor-your-attestation.md
@@ -0,0 +1,62 @@
+---
+title: "Anchor your attestation"
+description: "Add the anchor leg to export-attestation: collect cosignatures to your threshold and publish an aggregate whose rollback is evidence."
+product: witness
+section: "Users"
+order: 3
+lastReviewed: "2026-07-20"
+---
+
+Three flags on the `export-attestation` you already run.
+
+**Before you start:** your witnesses' names and member keys, and their URLs.
+
+```bash
+auths-mcp export-attestation \
+  --live-dir ./live \
+  --agent <agent-did> --root <root-did> \
+  --out ./public/activity.json \
+  --anchor-to https://w1.example.com \
+  --anchor-to https://w2.example.net \
+  --witness "w1=<w1 member key>" \
+  --witness "w2=<w2 member key>" \
+  --witness-threshold 2
+```
+
+You should see:
+
+```output
+export-attestation: anchored — 2 cosignature(s), threshold 2
+export-attestation: head a470be04c3b4f6af… count 412 cumulative 15c → ./public/activity.json
+```
+
+The finalized anchor is embedded **inside** `activity.json`. Publish it exactly
+as before — verifiers that predate the network ignore the extra field.
+
+{% callout type="warning" title="Below threshold, the export fails" %}
+If cosignatures don't reach `--witness-threshold`, the whole export fails and
+nothing is written. There is no silent fallback to an unanchored publish once
+you asked for anchoring.
+{% /callout %}
+
+## The flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--anchor-to <URL>` | A witness endpoint. Repeat per witness. |
+| `--witness "<name>=<key>"` | A declared member — the name and member key the operator gave you. Repeat per member. |
+| `--witness-threshold <t>` | How many cosignatures finalize. Default `1`. |
+
+**If it fails:**
+
+- *"below threshold"* — check each witness answers `GET /health`, and that every
+  `--witness` key matches the key that node actually cosigns with.
+- *refused by a witness* — your submission wasn't a monotone extension, or that
+  witness's registry copy is stale. See
+  [acceptance rules](/witness-network/reference/acceptance-rules).
+
+## The payoff
+
+The market derives its tier from the verified anchor, never from anything the
+document claims. Your listing badge upgrades from market-witnessed to
+**quorum-anchored (t-of-N)**.
diff --git a/content/docs/witness-network/users/choose-your-witnesses.md b/content/docs/witness-network/users/choose-your-witnesses.md
new file mode 100644
index 0000000..1aa8969
--- /dev/null
+++ b/content/docs/witness-network/users/choose-your-witnesses.md
@@ -0,0 +1,47 @@
+---
+title: "Choose your witnesses"
+description: "Pick members and a threshold: what t buys, what it costs, and where to find operators."
+product: witness
+section: "Users"
+order: 2
+lastReviewed: "2026-07-20"
+---
+
+A set is `N` named members plus a threshold `t`. You need each member's **public
+name** and **member key** — the operator gives you both (a node prints its member
+key at first boot).
+
+## Pick a threshold
+
+| Shape | Buys you | Costs you |
+| --- | --- | --- |
+| 1-of-1 (yourself) | The full loop end to end; catches your own rollback bugs | No third-party guarantee — you witnessed yourself |
+| 1-of-2 | Either witness can be down | Either one alone can co-sign a fork |
+| **2-of-3** | One can be down; two must collude to lie | Three operators to recruit — **the production floor** |
+| 3-of-5 | Two down; three to collude | Serious recruiting |
+
+Raising `t` buys collusion resistance and costs liveness: `t` witnesses must
+collude to co-sign a rollback, and `N − t + 1` must be down before you can't
+anchor at all.
+
+{% callout type="warning" title="Independence is the ceiling" %}
+Three nodes run by one operator are **one** witness with three signatures. Spread
+members across operator, organization, jurisdiction, and infrastructure — the
+strongest witness in your set is one your counterparty or regulator runs.
+{% /callout %}
+
+## Find operators
+
+- **[The public directory](https://auths.dev/network)** — conformant witnesses
+  with their operator facts and live status.
+- **[Run one yourself](/witness-network/operators/run-a-node)** — a fine first
+  member, a bad only member.
+- **Ask your counterparty.** Anyone who passes
+  [conformance](/witness-network/operators/prove-conformance) can witness.
+
+## Changing the set later
+
+Future anchors can declare a new set. Every past anchor keeps verifying against
+the set it named, so a verifier sees each era under the quorum that signed it.
+
+**Next:** [Anchor your attestation](/witness-network/users/anchor-your-attestation).
diff --git a/content/docs/witness-network/users/do-i-need-this.md b/content/docs/witness-network/users/do-i-need-this.md
new file mode 100644
index 0000000..017b540
--- /dev/null
+++ b/content/docs/witness-network/users/do-i-need-this.md
@@ -0,0 +1,33 @@
+---
+title: "Do I need this?"
+description: "A yes/no decision: what anchoring adds over an unanchored attestation, and when it is worth it."
+product: witness
+section: "Users"
+order: 1
+lastReviewed: "2026-07-20"
+---
+
+**Yes — if someone reads your attestation to make a decision, and you can't
+afford them doubting it.**
+
+| | Unanchored | Anchored |
+| --- | --- | --- |
+| Signature is authentic | ✅ | ✅ |
+| Growth is monotone | ✅ | ✅ |
+| You quietly published an older version | deniable | **attributable** |
+| You showed two buyers two histories | deniable | **attributable** |
+
+Anchoring is one flag on the command you already run, and it costs verifiers
+nothing — they still check offline, for free.
+
+## Skip it
+
+- You're in development, or nothing consumes your attestation yet.
+
+## Do it
+
+- A buyer, market, or regulator reads your attestation.
+- You want the `quorum-anchored (t-of-N)` badge instead of market-witnessed.
+
+**Next:** [Choose your witnesses](/witness-network/users/choose-your-witnesses),
+then [Anchor your attestation](/witness-network/users/anchor-your-attestation).
diff --git a/content/docs/witness-network/users/handle-a-duplicity-proof.md b/content/docs/witness-network/users/handle-a-duplicity-proof.md
new file mode 100644
index 0000000..e3838e5
--- /dev/null
+++ b/content/docs/witness-network/users/handle-a-duplicity-proof.md
@@ -0,0 +1,42 @@
+---
+title: "Handle a duplicity proof"
+description: "What a duplicity proof is, how to check one, and what it obliges you to do."
+product: witness
+section: "Users"
+order: 5
+lastReviewed: "2026-07-20"
+---
+
+A **duplicity proof** is what a witness returns instead of a cosignature when a
+chain presents the same index with two different heads. It contains both signed
+tuples, so the contradiction is in the submitter's *own* signatures.
+
+You get one from a `POST /v1/anchor` that conflicts:
+
+```output
+409 Conflict
+{ "duplicity": { "seedId": "c6ec71d2…", "index": 412, "a": {…}, "b": {…} } }
+```
+
+## Check it
+
+```bash
+auths artifact verify --offline duplicity.json
+```
+
+It verifies with **no trust in the witness that emitted it** and no network — the
+proof is self-contained.
+
+{% callout type="danger" title="Treat one as disqualifying" %}
+There is no innocent reading of two histories at one index. The proof is
+portable: attach it to a dispute, publish it, hand it to a counterparty.
+{% /callout %}
+
+## Where they come from
+
+Watchers — the market among them — scan witness logs for exactly these
+collisions and publish what they find. You don't have to be the one who catches
+it.
+
+**If it doesn't verify:** a proof that fails offline verification proves nothing;
+it may be a malformed or fabricated artifact. Discard it.
diff --git a/content/docs/witness-network/users/verify-an-anchored-attestation.md b/content/docs/witness-network/users/verify-an-anchored-attestation.md
new file mode 100644
index 0000000..5e7a1d6
--- /dev/null
+++ b/content/docs/witness-network/users/verify-an-anchored-attestation.md
@@ -0,0 +1,58 @@
+---
+title: "Verify an anchored attestation"
+description: "One SDK call checks the signature, the delegation, and the whole quorum — then read the freshness result beside the verdicts."
+product: witness
+section: "Users"
+order: 4
+lastReviewed: "2026-07-20"
+---
+
+One call verifies everything, including the embedded anchor.
+
+```js
+const sdk = require('@auths-dev/sdk')
+const check = JSON.parse(sdk.verifyActivityAttestation(doc, registryDir))
+
+check.ok      // false if ANY part fails — including a bad embedded anchor
+check.anchor  // null when unanchored, else the verified quorum:
+// { tier: 'witness', threshold: 2, witnesses: 3, cosigners: 2,
+//   seedId: 'c6ec71d2…', witnessSetSaid: 'EHSPi3…' }
+```
+
+Two rules worth knowing:
+
+- **A present-but-bad anchor fails the whole document.** There is no "signature
+  was fine but the anchor wasn't" middle ground.
+- **`anchor` restates only what was just re-verified** — never a claim read out
+  of the document.
+
+## The freshness ladder
+
+Freshness sits *beside* the verdicts, never inside them. A perfectly authorized
+history can still be an old view.
+
+| Status | Meaning | What to do |
+| --- | --- | --- |
+| `fresh` | What you hold extends the best finalized anchor | Nothing — good state |
+| `stale` | A finalized anchor exists **ahead** of what you were given | Fetch the current view, and ask why you got an old one |
+| `unanchored` | No anchor at all | Judge on the other evidence tiers |
+
+`stale` is not tampering — tampering fails verification outright. Stale means the
+math checked out on a view someone chose not to update.
+
+## Check for withholding
+
+Ask any declared witness for the latest anchor it co-signed:
+
+```bash
+curl https://w1.example.com/v1/anchor/<seed-id>
+```
+
+If the newest anchor any witness holds is days old while the seller claims live
+activity, you're being shown a gap.
+
+**If it fails:** `ok: false` with `anchor: null` on a document that should be
+anchored usually means the publisher's export fell back — treat it as
+unanchored, not as broken.
+
+**Next:** [Handle a duplicity proof](/witness-network/users/handle-a-duplicity-proof).
diff --git a/docs/docs-ia-redesign-plan.md b/docs/docs-ia-redesign-plan.md
new file mode 100644
index 0000000..0169275
--- /dev/null
+++ b/docs/docs-ia-redesign-plan.md
@@ -0,0 +1,406 @@
+# Docs IA redesign — Stripe-shaped navigation
+
+**Date:** 2026-07-20 · **Status:** rev 2 — §4 shipped, rest proposed ·
+**Scope:** `auths-docs` information architecture, navigation contract, content
+layout, and a full rewrite of the witness-network section.
+
+**Already landed:** the witness-network rewrite (§4) is implemented —
+`witness` is a third area in `lib/content.ts`, the 16 new pages are in
+`content/docs/witness-network/`, the 6 old pages are gone (harvested, not
+binned), and redirects are wired. `node scripts/check-docs.mjs` is clean at 39
+pages. What remains is the *chrome*: top nav + left-caret three-level sidebar
+(§7) and the other areas' migration (§8).
+
+Grounded in the branches open right now — **not** from memory:
+
+| Repo | Branch | What it gave us |
+|---|---|---|
+| `auths-base/auths` | `witness-network` | `witness-node` CLI, `/v1/anchor` API, `deploy/witness/*`, gateway `--anchor-to`/`--witness`, node SDK `verifyActivityAttestation` |
+| `auths-base/auths-mcp` | `main` | the packaged gateway consumers install |
+| `auths-base/auths-network` | `roster-trust` | the public `/directory` + `/node` console, roster admissions model |
+
+---
+
+## 1. The two axes
+
+Stripe's docs are two independent axes; we currently have one.
+
+1. **Top nav = which world.** Today the area switcher is buried *inside*
+   `DocsSidebar`, so you must already be in a world to discover the others.
+2. **Left nav = where in this world**, three levels: category → collapsible
+   sub-category → page. Today it's two, which is why witness network (6 pages,
+   growing) has nowhere to put depth.
+
+**Top nav (4 areas):** `Get started` · `Identity & signing` · `Agent payments` ·
+`Witness network`.
+
+**Reference and Glossary are not areas.** Each product area ends its own left
+nav with its own `Reference` and `Glossary`. A reader looking up a witness CLI
+flag stays inside Witness network; they never bounce to a global reference and
+lose context.
+
+---
+
+## 2. Layout
+
+Caret sits **left** of the sub-category label, so labels stay flush and the
+expand affordance reads as a disclosure triangle:
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│  auths    Get started   Identity & signing   Agent payments   Witness network │  ← top nav
+│                                                                  [search ⌘K] │
+├───────────────────────┬──────────────────────────────────────────────────────┤
+│                       │                                                      │
+│  WITNESS NETWORK      │   Anchor your attestation                            │
+│                       │   ───────────────────────                            │
+│  Overview             │                                                      │
+│                       │   Submit your aggregate to your declared witnesses   │
+│  ▾ Users              │   and embed the finalized anchor.                    │
+│      Do I need this?  │                                                      │
+│      Choose witnesses │   auths-mcp export-attestation \                     │
+│    › Anchor your att… │     --witness west=<key> --witness east=<key> \      │
+│      Verify an anchor │     --witness-threshold 2 \                          │
+│      Duplicity proofs │     --anchor-to https://w1… --anchor-to https://w2…  │
+│                       │                                                      │
+│  ▾ Operators          │   You should see:                                    │
+│      Run a node …     │     anchored — 2 cosignature(s), threshold 2         │
+│      Deploy for real  │                                                      │
+│      …                │                                                      │
+│  ▾ Reference          │                                                      │
+│  Glossary             │                                                      │
+└───────────────────────┴──────────────────────────────────────────────────────┘
+   ▾ open (the default)   ▸ collapsed by the reader   › active page
+   `Overview` and `Glossary` are one-page sections — plain rows, no caret.
+```
+
+Rules — two shapes, chosen by content, never configured:
+
+- **Multi-page section** → a disclosure, caret on the left, **open by default**.
+  A wall of collapsed rows hides the structure the nav exists to show;
+  collapsing is the reader's opt-in, and navigating into a collapsed section
+  re-opens it.
+- **One-page section** (`Overview`, `Glossary`) → a **plain row** labeled with
+  the section title, linking straight to its page. A caret revealing a single
+  child is noise. The row is aligned to the disclosure labels by a spacer the
+  width of the caret.
+
+Never a fourth level.
+
+---
+
+## 3. The tree
+
+```mermaid
+graph LR
+  ROOT["auths docs"]
+  ROOT --> GS["Get started"]
+  ROOT --> ID["Identity & signing"]
+  ROOT --> AP["Agent payments"]
+  ROOT --> WN["Witness network"]
+
+  GS --> GS1["Overview"]
+  GS --> GS2["Install"]
+  GS --> GS3["Pick your path<br/>· Sign your commits<br/>· Pay for agent calls<br/>· Verify someone's work"]
+
+  ID --> ID1["Get started<br/>· Installation · Quickstart · Authentication"]
+  ID --> ID2["Guides<br/>· Sign commits · Prove provenance<br/>· Build agents · Team identities"]
+  ID --> ID3["Concepts<br/>· Identity model · Delegation · Key rotation"]
+  ID --> ID4["Reference<br/>· CLI · GitHub Actions"]
+  ID --> ID5["Glossary"]
+
+  AP --> AP1["Get started<br/>· Overview · Install · Quickstart"]
+  AP --> AP2["Concepts<br/>· How it works · Budgets<br/>· Custody · Receipts"]
+  AP --> AP3["Guides<br/>· Spend real money · Publish receipts"]
+  AP --> AP4["Providers<br/>· Stripe · x402"]
+  AP --> AP5["Reference<br/>· Gateway CLI"]
+  AP --> AP6["Glossary"]
+
+  WN --> WN0["Overview"]
+  WN --> WNU["Users<br/>· Do I need this?<br/>· Choose your witnesses<br/>· Anchor your attestation<br/>· Verify an anchored attestation<br/>· Read the freshness result"]
+  WN --> WNO["Operators<br/>· Run a node in 5 minutes<br/>· Deploy for real<br/>· Sync the registry<br/>· Get listed in the directory<br/>· Monitor your node<br/>· Prove conformance"]
+  WN --> WNR["Reference<br/>· witness-node CLI<br/>· Anchor HTTP API<br/>· JSON shapes"]
+  WN --> WNG["Glossary"]
+```
+
+---
+
+## 4. Witness network — full rewrite ✅ shipped
+
+Implemented as `content/docs/witness-network/`:
+
+| Section | Pages |
+| --- | --- |
+| Overview | `index.md` |
+| Users | `do-i-need-this`, `choose-your-witnesses`, `anchor-your-attestation`, `verify-an-anchored-attestation`, `handle-a-duplicity-proof` |
+| Operators | `run-a-node`, `deploy-for-real`, `keep-the-registry-synced`, `monitor-your-node`, `prove-conformance`, `get-listed` |
+| Reference | `witness-node-cli`, `anchor-api`, `acceptance-rules` |
+| Glossary | `glossary.md` |
+
+**Decision — harvest, don't bin.** Every protocol fact from the six deleted
+pages was moved into `Reference`, not discarded: the acceptance-rule table, the
+set structural rules, the guarantee-ceiling math, finalization, the freshness
+ladder definition, the endpoint table, the roles table, and the hardening
+posture all live in `reference/acceptance-rules.md` and
+`reference/anchor-api.md`. Task pages link there instead of re-explaining.
+
+**Decision — document interim admissions now.** `operators/get-listed` states
+plainly that one Auths-held admissions key decides who appears, that a browser
+re-verifies the roster against a *pinned* key plus a content hash, and — the
+part that matters — that a compromised or partial directory costs
+discoverability, never correctness, because nothing in the protocol consults it.
+
+**Why it was rewritten rather than edited.** The old six pages were organised by
+protocol concept and written in protocol vocabulary, so they answered neither
+question anyone actually arrives with: *should I use this, and how?* — or, *how
+do I run one?* Reorganising by **entity** (`Users`, `Operators`) makes every page
+a task with a command, an expected output, and a failure mode.
+
+### 4.1 Users — people who anchor and verify
+
+| Page | Answers | Built from |
+|---|---|---|
+| **Do I need this?** | A decision, not theory. Unanchored: your attestation is authentic, but rolling it back or showing two buyers different histories is deniable. Anchored: both become attributable. Ends in a yes/no. | product behaviour |
+| **Choose your witnesses** | Pick names + keys, pick a threshold. What `t` trades off: liveness vs. how many operators must collude. Where to find operators: the public directory. | `auths-network` `/directory` |
+| **Anchor your attestation** | The command, the expected output, the fail-closed rule (below threshold the export fails rather than publishing unanchored). | `--witness`, `--witness-threshold`, `--anchor-to` |
+| **Verify an anchored attestation** | One SDK call; read `anchor` — `null` means unanchored, otherwise the verified quorum `{tier, threshold, witnesses, cosigners, seedId}`. A bad anchor fails the whole document. | `verifyActivityAttestation` |
+| **Read the freshness result** | `fresh` / `stale` / `unanchored`, reported beside the verdicts, never folded in. What to do about each. | freshness ladder |
+
+Anchor page skeleton (the shape every task page takes):
+
+````md
+Submit your aggregate to your declared witnesses and embed the finalized anchor.
+
+**Before you start:** a live attestation export, and 2+ witness URLs.
+
+```bash
+auths-mcp-gateway export-attestation \
+  --live-dir ./live \
+  --root did:keri:<root> --agent did:keri:<agent> \
+  --witness west=<key> --witness east=<key> \
+  --witness-threshold 2 \
+  --anchor-to https://west.example.com \
+  --anchor-to https://east.example.com \
+  --out activity.json
+```
+
+You should see:
+
+```
+anchored: 2/2 cosignatures, threshold 2
+```
+
+**If it fails:** below-threshold is a hard failure — nothing is written. Check
+each witness answers `GET /health`, and that every `--witness` key matches the
+key that node actually cosigns with.
+````
+
+### 4.2 Operators — people who run a node
+
+| Page | Answers | Built from |
+|---|---|---|
+| **Run a node in 5 minutes** | `openssl rand -hex 32` → `WITNESS_SEED`, `WITNESS_REGISTRY`, `docker compose up`, confirm `/health`. | `deploy/witness/docker-compose.yml` |
+| **Deploy for real** | Helm / Terraform (aws, gcp, azure) / systemd unit; pin the image digest. **The data dir must be a durable volume** — the anchor store is the node's anti-equivocation memory; an amnesiac witness co-signs a fork after restart. | `deploy/witness/{helm,terraform}`, `witness-node.service` |
+| **Sync the registry** | `--registry` is a local copy of the parties' public identity registry, used to resolve current keys for party signatures. Keep it synced or valid submissions get refused. | `--registry` |
+| **Get listed in the directory** | Submit your entry (`did`, `name`, `region`); it is admitted by an attestation under the pinned admissions key. Browsers verify the roster before trusting any key in it. | `auths-network` roster |
+| **Monitor your node** | The console reads `GET /health` and `GET /build`; what each field means; what "unhealthy" looks like. | `auths-network` `/node` |
+| **Prove conformance** | `cargo xtask witness-conformance --url http://127.0.0.1:3333` and what the transport checks assert. | xtask conformance |
+
+Quickstart skeleton:
+
+````md
+One node, all three roles, on your machine.
+
+```bash
+export WITNESS_SEED=$(openssl rand -hex 32)   # keep this stable — it IS your identity
+export WITNESS_REGISTRY=/path/to/registry
+docker compose -f deploy/witness/docker-compose.yml up
+```
+
+Confirm it's up:
+
+```bash
+curl -s localhost:3333/health
+```
+
+**Keep in mind:** `WITNESS_SEED` changing = a new witness. The `/data` volume
+must be durable.
+````
+
+---
+
+## 5. Writing rules (enforced, not aspirational)
+
+1. **Show, don't tell.** Every task page leads with the command. Prose exists to
+   say what to run and how to know it worked.
+2. **No preamble.** ≤ 2 sentences before the first command or list. If a page
+   needs more context, that context is a linked concept page.
+3. **Every command has expected output.** A page that shows a command without
+   showing what success looks like is not finished.
+4. **Every page ends with a failure mode.** "If it fails: …" — the one or two
+   things that actually go wrong.
+5. **Jargon links or dies.** First use of a protocol term links to that area's
+   Glossary. If it can't be linked, rewrite the sentence without it.
+6. **Concept pages are capped** — ~200 words plus one diagram, and only where a
+   decision genuinely requires the concept.
+7. **Commands are copy-pasteable and real** — taken from the shipped CLI, with
+   placeholders in `<angle brackets>`, never invented flags.
+
+`scripts/check-docs.mjs` grows two gates: fail a page whose first command
+appears after N lines, and fail an unlinked term from the area's glossary list.
+
+---
+
+## 6. Navigation contract
+
+Nav stays **derived from frontmatter** — the nav can never disagree with disk.
+The contract grows one level.
+
+```yaml
+---
+title: Anchor your attestation
+description: Submit your aggregate to your declared witnesses and embed the anchor.
+area: witness-network        # was: product (mcp | identity)
+category: Users              # was: section
+order: 3
+lastReviewed: "2026-07-20"
+---
+```
+
+- `area` replaces `product`, validated against an area registry rather than a
+  hardcoded two-value union.
+- `category` replaces `section`.
+- `subcategory` (optional) adds the third level where a category needs it.
+
+**`lib/areas.ts`** — the one hand-maintained nav input, replacing
+`SECTION_ORDER`, `COLLAPSIBLE_SECTIONS`, and `PRODUCT_LABEL`:
+
+```ts
+export interface Area {
+  slug: string          // URL segment AND content directory name
+  label: string         // top-nav label
+  order: number         // top-nav position
+  categories: string[]  // display order; put Reference + Glossary last
+}
+```
+
+Derivation rules (build-time enforced, as today):
+
+1. Unknown `area` fails the build.
+2. A category missing from `Area.categories` still renders, last.
+3. ~~A category is collapsible iff it has subcategories or > 6 pages.~~
+   **Superseded — every section is a disclosure.** A per-area collapse rule
+   produced exactly the inconsistency it was meant to avoid (only witness
+   network had carets). `COLLAPSIBLE_SECTIONS` is deleted and one shared
+   `components/docs/NavSection.tsx` renders every section in every area
+   identically: caret left, **open by default**, re-opening if the reader
+   navigates into one they collapsed, kept mounted so `aria-controls` resolves.
+   There is no second "flat section" shape to drift.
+4. Directory name **is** the area slug **is** the URL segment — this kills the
+   current `idsigning/` vs `product: identity` vs `/idsigning/*` drift.
+
+`getPrevNext()` flattens depth-first **within an area** and stops at the
+boundary.
+
+---
+
+## 7. Component changes
+
+| Component | Change |
+|---|---|
+| `DocsTopBar` | Gains the area nav (the primary change); active area underlined; collapses to a menu under `md`; search slot. |
+| `DocsSidebar` | ✅ *Every* section now renders through the shared `NavSection` disclosure — **caret on the left**, open by default, identical in all areas. Still to do: move the area switcher up into the top bar. |
+| `NavSection` | ✅ **New, shared.** The single disclosure used by the sidebar and (via it) the mobile drawer. One component = one behaviour everywhere. |
+| `DocsMobileDrawer` | Two-pane: areas → selected area's tree. |
+| `DocsPrevNext` | Flatten within area. |
+| `app/[...slug]` | Route shape unchanged (`/[area]/…`); only derived nav differs. |
+
+Caret rows are `<button aria-expanded>` inside `<nav aria-label>`; active page
+carries `aria-current="page"`. Not raw `<details>` — expanded state must survive
+client navigation. Toggle state in `sessionStorage`, keyed by area; expanding a
+sibling doesn't collapse others.
+
+---
+
+## 8. Migration
+
+| Now | Becomes |
+|---|---|
+| `mcp/index.md`, `install.md`, `quickstart.md` | `agent-payments/` · `Get started` |
+| `mcp/concepts/*` (4) | `agent-payments/concepts/` · `Concepts` |
+| `mcp/guides/*` (2) | `agent-payments/guides/` · `Guides` |
+| `mcp/providers/*` (2) | `agent-payments/providers/` · `Providers` |
+| `mcp/witness-network/*` (6) | **deleted — rewritten** per §4 into `witness-network/{users,operators}/` |
+| `idsigning/{installation,quickstart,authentication}` | `identity/` · `Get started` |
+| `idsigning/{sign-commits,prove-provenance,build-agents,team-identities}` | `identity/guides/` · `Guides` |
+| `idsigning/concepts/*` (3) | `identity/concepts/` · `Concepts` |
+| `idsigning/reference/{cli,github-actions}` | `identity/reference/` · `Reference` (stays in-area) |
+
+New: `get-started/{index,install,pick-your-path}`, the 11 witness-network pages,
+and per-area `reference/` + `glossary/` pages.
+
+**Redirects** in `next.config.ts`:
+
+```
+/mcp/witness-network/:path*  → /witness-network/:path*
+/mcp/:path*                  → /agent-payments/:path*
+/idsigning/:path*            → /identity/:path*
+```
+
+**Do this before the docs.auths.dev cutover.** That origin still serves mkdocs,
+so URL churn is nearly free today and expensive the moment it switches.
+
+---
+
+## 9. Phasing
+
+4. **Rewrite witness network** ✅ **done** — §4. Shipped first because it was
+   the content emergency; it also proved the shape.
+1. **Contract + registry** — generalise to `lib/areas.ts`, widen frontmatter to
+   `area`/`category`/`subcategory`, nested `getNavigation()`. *Partly done:*
+   `witness` exists as a third area with `Users`/`Operators`/`Reference`/
+   `Glossary` sections; the third nesting level and the registry are still to
+   come.
+2. **Chrome** — area nav into `DocsTopBar`; left-caret three-level
+   `DocsSidebar`; mobile drawer. *Stripe-shaped with today's content.* **This is
+   the next job** — witness network already has more sections than the current
+   two-level sidebar shows well.
+3. **Move files + redirects** for `identity` and `agent-payments`, per §8.
+5. **Per-area Reference + Glossary** for the other two areas, then search.
+
+Witness network now has its Reference and Glossary; identity and agent-payments
+still need theirs.
+
+---
+
+## 10. Risks
+
+- **Two glossaries drift.** Same term defined twice in different areas.
+  *Mitigation:* one shared term source, rendered per-area filtered by tag — a
+  glossary page is a view, not a document.
+- **Users/Operators split duplicates the anchor format.** Users need to read it;
+  operators need to serve it. *Mitigation:* it lives once in
+  `Witness network → Reference`; both link there.
+- **`> 6 pages` collapse threshold is a guess.** One constant; tune it once real
+  counts land rather than restoring a hand-maintained list.
+- ~~**The rewrite deletes real content.**~~ *Resolved:* harvested into
+  `Witness network → Reference` before the old pages were removed.
+- **Witness network now out-sections the sidebar.** It has five sections and
+  two collapsible groups while the sidebar is still two-level and the area
+  switcher still lives inside it. The content is right; the chrome (§7) is now
+  the bottleneck.
+
+## 11. Open questions
+
+1. `Agent payments` (audience language) vs. `auths-mcp` (matches the package)?
+   Proposal: label `Agent payments`, slug `agent-payments`, say "auths-mcp" in
+   the blurb.
+2. Does `Get started` keep its own `Install`, or redirect into each product's?
+   Proposal: one install page covering CLI + SDKs, products link to it.
+3. ~~Do the operator docs describe interim admissions now?~~ **Answered: yes** —
+   documented in `operators/get-listed`, including that it is centralized and
+   what that does (and doesn't) put at risk.
+4. The docs checker bans `KERI`/`CESR`/`did:keri` as protocol jargon. The new
+   pages comply, but `Reference` is where such terms are legitimately needed —
+   do we want a narrow allowance for reference pages, or keep the hard ban and
+   describe key material in plain terms (current approach)?
diff --git a/lib/content.ts b/lib/content.ts
index 287b5d3..07f1d10 100644
--- a/lib/content.ts
+++ b/lib/content.ts
@@ -11,11 +11,16 @@ import * as yaml from 'js-yaml'
 
 const CONTENT_DIR = path.join(process.cwd(), 'content/docs')
 
+/** The top-level areas. Each owns its own Reference and Glossary. */
+export type ProductKey = 'mcp' | 'identity' | 'witness'
+
+const PRODUCTS: readonly ProductKey[] = ['mcp', 'identity', 'witness'] as const
+
 export interface DocFrontmatter {
   title: string
   description: string
   /** Which product world the page belongs to. */
-  product: 'mcp' | 'identity'
+  product: ProductKey
   /** The sidebar section (eyebrow) the page lives under. */
   section: string
   /** Sort order within its section. */
@@ -42,35 +47,30 @@ export interface NavItem {
 export interface NavSection {
   title: string
   items: NavItem[]
-  /** Large topics render as one collapsible row; flat sections stay open. */
-  collapsible: boolean
 }
 
 export interface ProductNav {
-  product: 'mcp' | 'identity'
+  product: ProductKey
   label: string
   sections: NavSection[]
 }
 
 /** Section display order per product — the only hand-maintained nav input. */
-const SECTION_ORDER: Record<'mcp' | 'identity', string[]> = {
-  mcp: ['Get started', 'Core ideas', 'Spend real money', 'Witness network'],
+const SECTION_ORDER: Record<ProductKey, string[]> = {
+  mcp: ['Get started', 'Core ideas', 'Spend real money'],
   identity: ['Guides', 'Concepts', 'Reference'],
+  // Organised by who you are, not by protocol concept. Reference and Glossary
+  // sit last, inside the area — looking up a flag never leaves the area.
+  witness: ['Overview', 'Users', 'Operators', 'Reference', 'Glossary'],
 }
 
-/**
- * Large topics that collapse to a single sidebar row (expanded when the
- * reader is inside them) — the second and last hand-maintained nav input.
- * Keeps a many-page topic from flooding the sidebar.
- */
-const COLLAPSIBLE_SECTIONS: Record<'mcp' | 'identity', string[]> = {
-  mcp: ['Witness network'],
-  identity: [],
-}
+// Every section is a disclosure (see components/docs/NavSection.tsx), so there
+// is no per-area collapse list to maintain — one shape, every area.
 
-const PRODUCT_LABEL: Record<'mcp' | 'identity', string> = {
+const PRODUCT_LABEL: Record<ProductKey, string> = {
   mcp: 'auths-mcp',
   identity: 'Identity & signing',
+  witness: 'Witness network',
 }
 
 const REQUIRED_FIELDS = [
@@ -108,9 +108,9 @@ function readFrontmatter(filePath: string): DocFrontmatter {
       `frontmatter contract: ${path.relative(process.cwd(), filePath)} is missing [${missing.join(', ')}]`
     )
   }
-  if (fm.product !== 'mcp' && fm.product !== 'identity') {
+  if (!PRODUCTS.includes(fm.product as ProductKey)) {
     throw new Error(
-      `frontmatter contract: ${path.relative(process.cwd(), filePath)} has product="${String(fm.product)}" (must be "mcp" or "identity")`
+      `frontmatter contract: ${path.relative(process.cwd(), filePath)} has product="${String(fm.product)}" (must be one of ${PRODUCTS.join(', ')})`
     )
   }
   return fm as unknown as DocFrontmatter
@@ -154,7 +154,7 @@ export function getDocBySlug(slug: string[]): DocEntry | null {
  */
 export function getNavigation(): ProductNav[] {
   const docs = getAllDocs()
-  return (['mcp', 'identity'] as const).map((product) => {
+  return PRODUCTS.map((product) => {
     const inProduct = docs.filter((d) => d.frontmatter.product === product)
     const sectionNames = [
       ...SECTION_ORDER[product].filter((s) => inProduct.some((d) => d.frontmatter.section === s)),
@@ -168,7 +168,6 @@ export function getNavigation(): ProductNav[] {
       label: PRODUCT_LABEL[product],
       sections: sectionNames.map((title) => ({
         title,
-        collapsible: COLLAPSIBLE_SECTIONS[product].includes(title),
         items: inProduct
           .filter((d) => d.frontmatter.section === title)
           .sort((a, b) => a.frontmatter.order - b.frontmatter.order)
diff --git a/next-env.d.ts b/next-env.d.ts
index 9edff1c..c4b7818 100644
--- a/next-env.d.ts
+++ b/next-env.d.ts
@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/next.config.ts b/next.config.ts
index a4a3083..9caa7c8 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -19,6 +19,14 @@ const nextConfig: NextConfig = {
       // Strip it from every old URL (e.g. /docs/mcp → /mcp).
       { source: '/docs', destination: '/mcp', permanent: false },
       { source: '/docs/:path*', destination: '/:path*', permanent: false },
+      // The witness network is its own area — it anchors BOTH products and has
+      // an operator audience that never touches auths-mcp.
+      { source: '/mcp/witness-network', destination: '/witness-network', permanent: false },
+      {
+        source: '/mcp/witness-network/:path*',
+        destination: '/witness-network/:path*',
+        permanent: false,
+      },
       // Pre-idsigning flat identity URLs → their new home under /idsigning.
       { source: '/quickstart', destination: '/idsigning/quickstart', permanent: false },
       { source: '/installation', destination: '/idsigning/installation', permanent: false },