docs(reference): section 10 — zddc-server bootstrap config

A fresh deployment grants no access to anyone until the operator
populates the root /.zddc (admins) and per-project /<project>/.zddc
(role members). Without them the server runs but every request
returns 403 — the embedded defaults intentionally ship with empty
role members so deployments must opt-in to authorize anyone.

The new section walks operators through:

- Step 1: root /.zddc with `admins:` only.
- Step 2: per-project .zddc populating `document_controller` and
  `project_team` role members.
- Schema essentials (admins/acl/roles/title, permission bits,
  principal forms).
- The `acl: { allow: [...] }` footgun — silently dropped because
  ACLRules only reads `permissions:`.
- The startup warning to watch for and `zddc-server show-defaults`
  as the full schema reference.

Renumbered "Tools" from 10 to 11 and updated the sidebar TOC to
match. Mirrors the new sections added to the main repo's README.md
and AGENTS.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

reference.html

@@ -80,7 +80,8 @@
         <div class="ref-toc__item"><a href="#status-codes" class="ref-toc__link">7. Status codes</a></div>
         <div class="ref-toc__item"><a href="#folder-naming" class="ref-toc__link">8. Folder naming</a></div>
         <div class="ref-toc__item"><a href="#transmittal-workflow" class="ref-toc__link">9. Transmittal workflow</a></div>
-        <div class="ref-toc__item"><a href="#tools" class="ref-toc__link">10. Tools</a></div>
+        <div class="ref-toc__item"><a href="#bootstrap" class="ref-toc__link">10. zddc-server bootstrap</a></div>
+        <div class="ref-toc__item"><a href="#tools" class="ref-toc__link">11. Tools</a></div>
       </nav>
     </aside>
 
@@ -1101,9 +1102,139 @@ project/
         </ol>
       </section>
 
-      <!-- Section 10: Tools -->
+      <!-- Section 10: zddc-server bootstrap -->
+      <section id="bootstrap">
+        <h2>10. zddc-server bootstrap</h2>
+
+        <div class="highlight-box">
+          <p><strong>A fresh <code>zddc-server</code> deployment grants no access to anyone until two config files are populated.</strong> Without them the server runs but every request returns 403. The embedded defaults ship with empty role members, so deployments must opt-in to authorize anyone — there is no default "anything goes" mode (except <code>--insecure</code>, which is explicitly for deliberately-public archives).</p>
+        </div>
+
+        <p>Two files, both named <code>.zddc</code>. YAML format. Hand-edited.</p>
+
+        <h3>Step 1 — root <code>/.zddc</code></h3>
+
+        <p>At <code>&lt;ZDDC_ROOT&gt;/.zddc</code>, name at least one admin:</p>
+
+        <div class="code-block">admins:
+  - cwitt@burnsmcd.com
+</div>
+
+        <p><code>admins:</code> is honored only at the root file. Admins behave as normal users by default and elevate per-request via the <code>zddc-elevate=1</code> cookie (the header toggle visible in every tool) or implicitly when authenticating with a bearer token. This sudo-style model means an admin can't accidentally clobber files in their everyday browsing — elevation is opt-in.</p>
+
+        <p>Without this file the server refuses to start (the served tree would be publicly accessible to anonymous callers); pass <code>--insecure</code> to acknowledge a deliberately-public deployment.</p>
+
+        <h3>Step 2 — per-project <code>&lt;project&gt;/.zddc</code></h3>
+
+        <p>In each project, populate the <code>document_controller</code> and <code>project_team</code> role members:</p>
+
+        <div class="code-block">title: "Project Phoenix"
+roles:
+  document_controller:
+    members:
+      - dc1@burnsmcd.com
+  project_team:
+    members:
+      - alice@burnsmcd.com
+      - '*@acme.com'                # external counterparty (glob)
+</div>
+
+        <p>That's it. The embedded cascade does the rest:</p>
+
+        <ul style="margin: var(--spacing-md) 0; padding-left: 1.5rem; color: var(--color-text-muted); line-height: 1.65;">
+          <li><code>project_team</code> gets read across the project</li>
+          <li><code>document_controller</code> gets read+write project-wide, plus create authority on <code>archive/</code>, WORM filing rights on <code>received/</code> and <code>issued/</code>, and subtree-admin of <code>working/</code>, <code>staging/</code>, and <code>reviewing/</code></li>
+        </ul>
+
+        <p>Add a new project team member with one line; revoke by removing the line. No need to restate the cascade's grants — they're already in the embedded defaults that ship with <code>zddc-server</code>.</p>
+
+        <h3>Schema essentials</h3>
+
+        <table>
+          <thead>
+            <tr>
+              <th scope="col">Key</th>
+              <th scope="col">Where</th>
+              <th scope="col">Shape</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td><code>admins:</code></td>
+              <td>Root only</td>
+              <td>List of emails. Sudo-style; gates on <code>zddc-elevate=1</code>.</td>
+            </tr>
+            <tr>
+              <td><code>acl:</code></td>
+              <td>Anywhere; cascades</td>
+              <td><code>{ permissions: { &lt;principal&gt;: &lt;bits&gt; }, inherit: &lt;bool&gt;? }</code></td>
+            </tr>
+            <tr>
+              <td><code>roles:</code></td>
+              <td>Anywhere; members union across the cascade</td>
+              <td><code>{ &lt;name&gt;: { members: [...], reset: &lt;bool&gt;? } }</code></td>
+            </tr>
+            <tr>
+              <td><code>title:</code></td>
+              <td>Per-project only</td>
+              <td>String; surfaces on the landing-page picker.</td>
+            </tr>
+          </tbody>
+        </table>
+
+        <p><strong>Permission bits</strong> — any subset of:</p>
+
+        <ul style="margin: var(--spacing-md) 0; padding-left: 1.5rem; color: var(--color-text-muted); line-height: 1.65;">
+          <li><code>r</code> read</li>
+          <li><code>w</code> write (overwrite existing files)</li>
+          <li><code>c</code> create (new files, new directories)</li>
+          <li><code>d</code> delete</li>
+          <li><code>a</code> admin (subtree-admin at this level and below)</li>
+        </ul>
+
+        <p>An empty bits string (<code>''</code>) is an explicit deny.</p>
+
+        <p><strong>Principals</strong> — three forms:</p>
+
+        <ul style="margin: var(--spacing-md) 0; padding-left: 1.5rem; color: var(--color-text-muted); line-height: 1.65;">
+          <li>Email address — must contain <code>@</code>, e.g. <code>alice@burnsmcd.com</code></li>
+          <li>Email glob — wildcard on the local part, e.g. <code>'*@acme.com'</code> (quote it in YAML so the leading <code>*</code> doesn't confuse the parser)</li>
+          <li>Role name — anything without an <code>@</code>, e.g. <code>document_controller</code>. The role's members are looked up via <code>roles:</code> at any cascade level.</li>
+        </ul>
+
+        <h3>Common footgun</h3>
+
+        <div class="highlight-box">
+          <p><strong>This is silently dropped:</strong></p>
+          <div class="code-block" style="margin: var(--spacing-sm) 0;">acl:
+  allow:
+    - '*@burnsmcd.com'
+</div>
+          <p>The YAML parses cleanly but <code>ACLRules</code> only reads <code>permissions:</code>. The <code>allow:</code> block is discarded during unmarshal and you end up with zero grants. Correct form:</p>
+          <div class="code-block" style="margin: var(--spacing-sm) 0;">acl:
+  permissions:
+    '*@burnsmcd.com': r
+</div>
+        </div>
+
+        <h3>Verifying the bootstrap</h3>
+
+        <p><code>zddc-server</code> prints a startup warning when the root <code>.zddc</code> grants nobody anything — watch for it on first boot:</p>
+
+        <div class="code-block">level=WARN msg="root .zddc grants nobody anything (no admins,
+no acl.permissions, no role members). ZDDC will refuse every
+request until you populate it..."</div>
+
+        <p>To dump the full annotated schema (every cascade key with documentation):</p>
+
+        <div class="code-block">zddc-server show-defaults</div>
+
+        <p>That prints the embedded <code>defaults.zddc.yaml</code> with comments explaining every option (<code>worm:</code>, <code>auto_own:</code>, <code>drop_target:</code>, <code>apps:</code>, <code>convert:</code>, <code>on_plan_review:</code>, <code>records:</code>, <code>available_tools:</code>, <code>default_tool:</code>, <code>dir_tool:</code>, and more). Pipe it to a file and use it as the starting point for any deeper customization.</p>
+      </section>
+
+      <!-- Section 11: Tools -->
       <section id="tools">
-        <h2>10. Tools</h2>
+        <h2>11. Tools</h2>
         <p>Two single-file HTML applications — each is complete and self-contained. Save them locally and they work forever, without internet, without updates, without a subscription. Together they cover the full ZDDC workflow: <strong>archive</strong> for searching and exporting the formal record; <strong>browse</strong> for navigating, editing, and managing the project tree.</p>
 
         <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: var(--spacing-lg); margin-top: var(--spacing-lg);">