docs: HTML and PDF set plus optional CORS

WhatToChange: recommended-changes/2026-09-21-docs-and-cors/ What-to-Change.md What-to-Change-To.md How-to-implement-the-changes.md What was actually done: - Markdown, HTML, and PDF for standards, architecture, API, and the operator guide. - README points at scripts/build-docs.sh. - VERAE_MCP_CORS=1 enables CORS and JSON responses on the Streamable HTTP app. What was not done: - (none)
2026-09-21 14:13:07 -04:00 · 2026-09-21 14:13:07 -04:00 · 840755c84a
commit 840755c84a
parent 60bcefbca2
24 changed files with 989 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -50,6 +50,15 @@ Global stamp (central VeraeTime). Token lives at `~/.verae/auth.properties` (mod

 Do not send file bytes to `stamp`. Local receipts persist at `~/.verae/mcp-timestamp-local.json` (`VERAE_LEDGER_PATH`).

+Printed and HTML copies of the operator guide, architecture, tool API, and standards:
+
+```sh
+bash scripts/build-docs.sh
+open docs/html/index.html
+```
+
+Sources: `docs/operator-guide.md`, `docs/architecture.md`, `docs/api.md`, `docs/standards.md`.
+
 ## Contributing

 Questions: this research workspace. PRs welcome. Protocol questions belong at https://github.com/modelcontextprotocol. Timestamp ledger questions belong with `verae-timestamp` / `locald`.
--- a/docs/api.md
+++ b/docs/api.md
@ -0,0 +1,63 @@
+# Tool API
+
+Server name: `verae-timestamping`.
+
+## stamp
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `sha256` | required | 64 hex characters |
+| `scope` | `local` | `local`, `shared`, or `global` |
+| `cube_id` | empty | Stored on the local receipt. Sent only as a local field on the global receipt object; the VeraeTime POST body is the digest |
+| `org_id` | empty | Local idempotency key. Ignored by the global client |
+
+Returns `{ "receipts": [ Receipt ] }`.
+
+Receipt fields: `receipt_id`, `hash`, `scope`, `cube_id`, `org_id`, `created_at`, `merkle`, `restamp_of`.
+
+## verify
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `receipt_id` | required | Local id or VeraeTime certificate / job id |
+| `want_scope` | empty | `global` forces VeraeTime. A weaker scope fails closed when the stored scope ranks lower |
+
+Returns `{ "valid": bool, "error": string or null, "receipt": Receipt or null }`.
+
+Scope rank: local < shared < global.
+
+## hash_report
+
+| Argument | Default | Meaning |
+| --- | --- | --- |
+| `sha256` | required | Digest to list |
+| `org_id` | empty | Filter when set |
+| `want_scope` | empty | Drop receipts below this rank |
+
+Returns `{ "receipts": [ ... ] }` from the local file. Global-only certificates are not listed.
+
+## Environment
+
+| Name | Default |
+| --- | --- |
+| `VERAE_GLOBAL_URL` | `https://api.veraetime.net` |
+| `VERAE_GLOBAL_TOKEN` | empty (then auth.properties) |
+| `VERAE_AUTH_PROPERTIES` | `~/.verae/auth.properties` |
+| `VERAE_LEDGER_PATH` | `~/.verae/mcp-timestamp-local.json` |
+| `VERAE_MCP_TRANSPORT` | `stdio` |
+| `VERAE_MCP_HOST` | `127.0.0.1` |
+| `VERAE_MCP_PORT` | `8000` |
+| `VERAE_MCP_CORS` | unset. `1` adds CORS for the sample page |
+
+## Client config (stdio)
+
+```json
+{
+  "mcpServers": {
+    "verae-timestamping": {
+      "command": "uv",
+      "args": ["run", "--directory", "/Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server", "verae-mcp-timestamping-server"]
+    }
+  }
+}
+```
--- a/docs/architecture.md
+++ b/docs/architecture.md
@ -0,0 +1,26 @@
+# Architecture
+
+## Flow
+
+1. An MCP client calls `stamp`, `verify`, or `hash_report`.
+2. `RoutingLedger` sends `scope=global` to `GlobalLedger` and every other scope to `FileLedger`.
+3. `FileLedger` keeps an idempotent JSON list. The same digest, org, and scope returns the existing receipt.
+4. `GlobalClient` posts the digest to VeraeTime and, when the body has no certificate yet, polls `/api/status/{jobId}`.
+5. `verify` with `want_scope=global` posts `{ "certificate": "<id>" }` to `/api/verify`. Otherwise it checks the local file first, then VeraeTime.
+
+## Modules
+
+| Module | Role |
+| --- | --- |
+| `server.py` | MCP tools and process entry |
+| `ledger.py` | Receipt model, memory ledger, file ledger, router |
+| `global_client.py` | VeraeTime HTTPS client; blocking I/O runs in a worker thread |
+| `nats_ledger.py` | Optional leaf `locald` client |
+
+## Idempotency
+
+Local stamps are idempotent per digest + org + scope. Global stamps send `restamp: false` and `wait: true`. VeraeTime may return the same certificate for the same digest. This server does not cache global receipts in the local file.
+
+## What this process is not
+
+It does not replace `verae-timestamp` / `locald`. It does not write JetStream. It does not store document bytes. Memory ledger exists for tests and for `mcp dev` when a caller injects it. `main()` always builds `RoutingLedger`.
--- a/docs/html/api.html
+++ b/docs/html/api.html
@ -0,0 +1,258 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+  <title>api</title>
+  <style>
+    /* Default styles provided by pandoc.
+    ** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
+    */
+    code{white-space: pre-wrap;}
+    span.smallcaps{font-variant: small-caps;}
+    div.columns{display: flex; gap: min(4vw, 1.5em);}
+    div.column{flex: auto; overflow-x: auto;}
+    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+    /* The extra [class] is a hack that increases specificity enough to
+       override a similar rule in reveal.js */
+    ul.task-list[class]{list-style: none;}
+    ul.task-list li input[type="checkbox"] {
+      font-size: inherit;
+      width: 0.8em;
+      margin: 0 0.8em 0.2em -1.6em;
+      vertical-align: middle;
+    }
+    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
+    /* CSS for syntax highlighting */
+    html { -webkit-text-size-adjust: 100%; }
+    pre > code.sourceCode { white-space: pre; position: relative; }
+    pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
+    pre > code.sourceCode > span:empty { height: 1.2em; }
+    .sourceCode { overflow: visible; }
+    code.sourceCode > span { color: inherit; text-decoration: inherit; }
+    div.sourceCode { margin: 1em 0; }
+    pre.sourceCode { margin: 0; }
+    @media screen {
+    div.sourceCode { overflow: auto; }
+    }
+    @media print {
+    pre > code.sourceCode { white-space: pre-wrap; }
+    pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
+    }
+    pre.numberSource code
+      { counter-reset: source-line 0; }
+    pre.numberSource code > span
+      { position: relative; left: -4em; counter-increment: source-line; }
+    pre.numberSource code > span > a:first-child::before
+      { content: counter(source-line);
+        position: relative; left: -1em; text-align: right; vertical-align: baseline;
+        border: none; display: inline-block;
+        -webkit-touch-callout: none; -webkit-user-select: none;
+        -khtml-user-select: none; -moz-user-select: none;
+        -ms-user-select: none; user-select: none;
+        padding: 0 4px; width: 4em;
+        color: #aaaaaa;
+      }
+    pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa;  padding-left: 4px; }
+    div.sourceCode
+      {   }
+    @media screen {
+    pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
+    }
+    code span.al { color: #ff0000; font-weight: bold; } /* Alert */
+    code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
+    code span.at { color: #7d9029; } /* Attribute */
+    code span.bn { color: #40a070; } /* BaseN */
+    code span.bu { color: #008000; } /* BuiltIn */
+    code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
+    code span.ch { color: #4070a0; } /* Char */
+    code span.cn { color: #880000; } /* Constant */
+    code span.co { color: #60a0b0; font-style: italic; } /* Comment */
+    code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
+    code span.do { color: #ba2121; font-style: italic; } /* Documentation */
+    code span.dt { color: #902000; } /* DataType */
+    code span.dv { color: #40a070; } /* DecVal */
+    code span.er { color: #ff0000; font-weight: bold; } /* Error */
+    code span.ex { } /* Extension */
+    code span.fl { color: #40a070; } /* Float */
+    code span.fu { color: #06287e; } /* Function */
+    code span.im { color: #008000; font-weight: bold; } /* Import */
+    code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
+    code span.kw { color: #007020; font-weight: bold; } /* Keyword */
+    code span.op { color: #666666; } /* Operator */
+    code span.ot { color: #007020; } /* Other */
+    code span.pp { color: #bc7a00; } /* Preprocessor */
+    code span.sc { color: #4070a0; } /* SpecialChar */
+    code span.ss { color: #bb6688; } /* SpecialString */
+    code span.st { color: #4070a0; } /* String */
+    code span.va { color: #19177c; } /* Variable */
+    code span.vs { color: #4070a0; } /* VerbatimString */
+    code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
+  </style>
+  <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+<header id="title-block-header">
+<h1 class="title">api</h1>
+</header>
+<h1 id="tool-api">Tool API</h1>
+<p>Server name: <code>verae-timestamping</code>.</p>
+<h2 id="stamp">stamp</h2>
+<table>
+<colgroup>
+<col style="width: 33%" />
+<col style="width: 33%" />
+<col style="width: 33%" />
+</colgroup>
+<thead>
+<tr>
+<th>Argument</th>
+<th>Default</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>sha256</code></td>
+<td>required</td>
+<td>64 hex characters</td>
+</tr>
+<tr>
+<td><code>scope</code></td>
+<td><code>local</code></td>
+<td><code>local</code>, <code>shared</code>, or <code>global</code></td>
+</tr>
+<tr>
+<td><code>cube_id</code></td>
+<td>empty</td>
+<td>Stored on the local receipt. Sent only as a local field on the
+global receipt object; the VeraeTime POST body is the digest</td>
+</tr>
+<tr>
+<td><code>org_id</code></td>
+<td>empty</td>
+<td>Local idempotency key. Ignored by the global client</td>
+</tr>
+</tbody>
+</table>
+<p>Returns <code>{ "receipts": [ Receipt ] }</code>.</p>
+<p>Receipt fields: <code>receipt_id</code>, <code>hash</code>,
+<code>scope</code>, <code>cube_id</code>, <code>org_id</code>,
+<code>created_at</code>, <code>merkle</code>,
+<code>restamp_of</code>.</p>
+<h2 id="verify">verify</h2>
+<table>
+<colgroup>
+<col style="width: 33%" />
+<col style="width: 33%" />
+<col style="width: 33%" />
+</colgroup>
+<thead>
+<tr>
+<th>Argument</th>
+<th>Default</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>receipt_id</code></td>
+<td>required</td>
+<td>Local id or VeraeTime certificate / job id</td>
+</tr>
+<tr>
+<td><code>want_scope</code></td>
+<td>empty</td>
+<td><code>global</code> forces VeraeTime. A weaker scope fails closed
+when the stored scope ranks lower</td>
+</tr>
+</tbody>
+</table>
+<p>Returns
+<code>{ "valid": bool, "error": string or null, "receipt": Receipt or null }</code>.</p>
+<p>Scope rank: local &lt; shared &lt; global.</p>
+<h2 id="hash_report">hash_report</h2>
+<table>
+<thead>
+<tr>
+<th>Argument</th>
+<th>Default</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>sha256</code></td>
+<td>required</td>
+<td>Digest to list</td>
+</tr>
+<tr>
+<td><code>org_id</code></td>
+<td>empty</td>
+<td>Filter when set</td>
+</tr>
+<tr>
+<td><code>want_scope</code></td>
+<td>empty</td>
+<td>Drop receipts below this rank</td>
+</tr>
+</tbody>
+</table>
+<p>Returns <code>{ "receipts": [ ... ] }</code> from the local file.
+Global-only certificates are not listed.</p>
+<h2 id="environment">Environment</h2>
+<table>
+<thead>
+<tr>
+<th>Name</th>
+<th>Default</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>VERAE_GLOBAL_URL</code></td>
+<td><code>https://api.veraetime.net</code></td>
+</tr>
+<tr>
+<td><code>VERAE_GLOBAL_TOKEN</code></td>
+<td>empty (then auth.properties)</td>
+</tr>
+<tr>
+<td><code>VERAE_AUTH_PROPERTIES</code></td>
+<td><code>~/.verae/auth.properties</code></td>
+</tr>
+<tr>
+<td><code>VERAE_LEDGER_PATH</code></td>
+<td><code>~/.verae/mcp-timestamp-local.json</code></td>
+</tr>
+<tr>
+<td><code>VERAE_MCP_TRANSPORT</code></td>
+<td><code>stdio</code></td>
+</tr>
+<tr>
+<td><code>VERAE_MCP_HOST</code></td>
+<td><code>127.0.0.1</code></td>
+</tr>
+<tr>
+<td><code>VERAE_MCP_PORT</code></td>
+<td><code>8000</code></td>
+</tr>
+<tr>
+<td><code>VERAE_MCP_CORS</code></td>
+<td>unset. <code>1</code> adds CORS for the sample page</td>
+</tr>
+</tbody>
+</table>
+<h2 id="client-config-stdio">Client config (stdio)</h2>
+<div class="sourceCode" id="cb1"><pre
+class="sourceCode json"><code class="sourceCode json"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">{</span></span>
+<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a>  <span class="dt">&quot;mcpServers&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
+<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a>    <span class="dt">&quot;verae-timestamping&quot;</span><span class="fu">:</span> <span class="fu">{</span></span>
+<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a>      <span class="dt">&quot;command&quot;</span><span class="fu">:</span> <span class="st">&quot;uv&quot;</span><span class="fu">,</span></span>
+<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>      <span class="dt">&quot;args&quot;</span><span class="fu">:</span> <span class="ot">[</span><span class="st">&quot;run&quot;</span><span class="ot">,</span> <span class="st">&quot;--directory&quot;</span><span class="ot">,</span> <span class="st">&quot;/Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server&quot;</span><span class="ot">,</span> <span class="st">&quot;verae-mcp-timestamping-server&quot;</span><span class="ot">]</span></span>
+<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a>    <span class="fu">}</span></span>
+<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a>  <span class="fu">}</span></span>
+<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a><span class="fu">}</span></span></code></pre></div>
+</body>
+</html>
--- a/docs/html/architecture.html
+++ b/docs/html/architecture.html
@ -0,0 +1,95 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+  <title>architecture</title>
+  <style>
+    /* Default styles provided by pandoc.
+    ** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
+    */
+    code{white-space: pre-wrap;}
+    span.smallcaps{font-variant: small-caps;}
+    div.columns{display: flex; gap: min(4vw, 1.5em);}
+    div.column{flex: auto; overflow-x: auto;}
+    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+    /* The extra [class] is a hack that increases specificity enough to
+       override a similar rule in reveal.js */
+    ul.task-list[class]{list-style: none;}
+    ul.task-list li input[type="checkbox"] {
+      font-size: inherit;
+      width: 0.8em;
+      margin: 0 0.8em 0.2em -1.6em;
+      vertical-align: middle;
+    }
+    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
+  </style>
+  <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+<header id="title-block-header">
+<h1 class="title">architecture</h1>
+</header>
+<h1 id="architecture">Architecture</h1>
+<h2 id="flow">Flow</h2>
+<ol type="1">
+<li>An MCP client calls <code>stamp</code>, <code>verify</code>, or
+<code>hash_report</code>.</li>
+<li><code>RoutingLedger</code> sends <code>scope=global</code> to
+<code>GlobalLedger</code> and every other scope to
+<code>FileLedger</code>.</li>
+<li><code>FileLedger</code> keeps an idempotent JSON list. The same
+digest, org, and scope returns the existing receipt.</li>
+<li><code>GlobalClient</code> posts the digest to VeraeTime and, when
+the body has no certificate yet, polls
+<code>/api/status/{jobId}</code>.</li>
+<li><code>verify</code> with <code>want_scope=global</code> posts
+<code>{ "certificate": "&lt;id&gt;" }</code> to
+<code>/api/verify</code>. Otherwise it checks the local file first, then
+VeraeTime.</li>
+</ol>
+<h2 id="modules">Modules</h2>
+<table>
+<colgroup>
+<col style="width: 50%" />
+<col style="width: 50%" />
+</colgroup>
+<thead>
+<tr>
+<th>Module</th>
+<th>Role</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>server.py</code></td>
+<td>MCP tools and process entry</td>
+</tr>
+<tr>
+<td><code>ledger.py</code></td>
+<td>Receipt model, memory ledger, file ledger, router</td>
+</tr>
+<tr>
+<td><code>global_client.py</code></td>
+<td>VeraeTime HTTPS client; blocking I/O runs in a worker thread</td>
+</tr>
+<tr>
+<td><code>nats_ledger.py</code></td>
+<td>Optional leaf <code>locald</code> client</td>
+</tr>
+</tbody>
+</table>
+<h2 id="idempotency">Idempotency</h2>
+<p>Local stamps are idempotent per digest + org + scope. Global stamps
+send <code>restamp: false</code> and <code>wait: true</code>. VeraeTime
+may return the same certificate for the same digest. This server does
+not cache global receipts in the local file.</p>
+<h2 id="what-this-process-is-not">What this process is not</h2>
+<p>It does not replace <code>verae-timestamp</code> /
+<code>locald</code>. It does not write JetStream. It does not store
+document bytes. Memory ledger exists for tests and for
+<code>mcp dev</code> when a caller injects it. <code>main()</code>
+always builds <code>RoutingLedger</code>.</p>
+</body>
+</html>
--- a/docs/html/index.html
+++ b/docs/html/index.html
@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Verae MCP timestamping server</title>
+<link rel="stylesheet" href="style.css">
+</head>
+<body>
+<h1>Verae MCP timestamping server</h1>
+<p>Hash-only stamps for assistants that speak the Model Context Protocol.</p>
+<ul>
+<li><a href="operator-guide.html">Operator guide</a> (<a href="../pdf/operator-guide.pdf">PDF</a>)</li>
+<li><a href="architecture.html">Architecture</a> (<a href="../pdf/architecture.pdf">PDF</a>)</li>
+<li><a href="api.html">Tool API</a> (<a href="../pdf/api.pdf">PDF</a>)</li>
+<li><a href="standards.html">Standards</a> (<a href="../pdf/standards.pdf">PDF</a>)</li>
+<li><a href="../../site/index.html">Sample page</a></li>
+</ul>
+</body>
+</html>
--- a/docs/html/operator-guide.html
+++ b/docs/html/operator-guide.html
@ -0,0 +1,128 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+  <title>operator-guide</title>
+  <style>
+    /* Default styles provided by pandoc.
+    ** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
+    */
+    code{white-space: pre-wrap;}
+    span.smallcaps{font-variant: small-caps;}
+    div.columns{display: flex; gap: min(4vw, 1.5em);}
+    div.column{flex: auto; overflow-x: auto;}
+    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+    /* The extra [class] is a hack that increases specificity enough to
+       override a similar rule in reveal.js */
+    ul.task-list[class]{list-style: none;}
+    ul.task-list li input[type="checkbox"] {
+      font-size: inherit;
+      width: 0.8em;
+      margin: 0 0.8em 0.2em -1.6em;
+      vertical-align: middle;
+    }
+    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
+    /* CSS for syntax highlighting */
+    html { -webkit-text-size-adjust: 100%; }
+    pre > code.sourceCode { white-space: pre; position: relative; }
+    pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
+    pre > code.sourceCode > span:empty { height: 1.2em; }
+    .sourceCode { overflow: visible; }
+    code.sourceCode > span { color: inherit; text-decoration: inherit; }
+    div.sourceCode { margin: 1em 0; }
+    pre.sourceCode { margin: 0; }
+    @media screen {
+    div.sourceCode { overflow: auto; }
+    }
+    @media print {
+    pre > code.sourceCode { white-space: pre-wrap; }
+    pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
+    }
+    pre.numberSource code
+      { counter-reset: source-line 0; }
+    pre.numberSource code > span
+      { position: relative; left: -4em; counter-increment: source-line; }
+    pre.numberSource code > span > a:first-child::before
+      { content: counter(source-line);
+        position: relative; left: -1em; text-align: right; vertical-align: baseline;
+        border: none; display: inline-block;
+        -webkit-touch-callout: none; -webkit-user-select: none;
+        -khtml-user-select: none; -moz-user-select: none;
+        -ms-user-select: none; user-select: none;
+        padding: 0 4px; width: 4em;
+        color: #aaaaaa;
+      }
+    pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa;  padding-left: 4px; }
+    div.sourceCode
+      {   }
+    @media screen {
+    pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
+    }
+    code span.al { color: #ff0000; font-weight: bold; } /* Alert */
+    code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
+    code span.at { color: #7d9029; } /* Attribute */
+    code span.bn { color: #40a070; } /* BaseN */
+    code span.bu { color: #008000; } /* BuiltIn */
+    code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
+    code span.ch { color: #4070a0; } /* Char */
+    code span.cn { color: #880000; } /* Constant */
+    code span.co { color: #60a0b0; font-style: italic; } /* Comment */
+    code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
+    code span.do { color: #ba2121; font-style: italic; } /* Documentation */
+    code span.dt { color: #902000; } /* DataType */
+    code span.dv { color: #40a070; } /* DecVal */
+    code span.er { color: #ff0000; font-weight: bold; } /* Error */
+    code span.ex { } /* Extension */
+    code span.fl { color: #40a070; } /* Float */
+    code span.fu { color: #06287e; } /* Function */
+    code span.im { color: #008000; font-weight: bold; } /* Import */
+    code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
+    code span.kw { color: #007020; font-weight: bold; } /* Keyword */
+    code span.op { color: #666666; } /* Operator */
+    code span.ot { color: #007020; } /* Other */
+    code span.pp { color: #bc7a00; } /* Preprocessor */
+    code span.sc { color: #4070a0; } /* SpecialChar */
+    code span.ss { color: #bb6688; } /* SpecialString */
+    code span.st { color: #4070a0; } /* String */
+    code span.va { color: #19177c; } /* Variable */
+    code span.vs { color: #4070a0; } /* VerbatimString */
+    code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
+  </style>
+  <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+<header id="title-block-header">
+<h1 class="title">operator-guide</h1>
+</header>
+<h1 id="operator-guide">Operator guide</h1>
+<h2 id="install">Install</h2>
+<div class="sourceCode" id="cb1"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="bu">cd</span> /Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server</span>
+<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> sync <span class="at">--group</span> dev</span></code></pre></div>
+<h2 id="run-stdio">Run stdio</h2>
+<div class="sourceCode" id="cb2"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> run verae-mcp-timestamping-server</span></code></pre></div>
+<h2 id="run-streamable-http">Run Streamable HTTP</h2>
+<div class="sourceCode" id="cb3"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="va">VERAE_MCP_TRANSPORT</span><span class="op">=</span>streamable-http <span class="ex">uv</span> run verae-mcp-timestamping-server</span></code></pre></div>
+<p>The listener is <code>http://127.0.0.1:8000/mcp</code>.</p>
+<p>For the sample page on another origin:</p>
+<div class="sourceCode" id="cb4"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="va">VERAE_MCP_CORS</span><span class="op">=</span>1 <span class="va">VERAE_MCP_TRANSPORT</span><span class="op">=</span>streamable-http <span class="ex">uv</span> run verae-mcp-timestamping-server</span></code></pre></div>
+<p>A page served from the public internet still cannot call
+<code>127.0.0.1</code> from current browsers. Open
+<code>site/index.html</code> on the same machine, or put TLS and an
+access control in front of a non-loopback bind you choose yourself.</p>
+<h2 id="global-token">Global token</h2>
+<div class="sourceCode" id="cb5"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="co"># POST https://api.veraetime.net/auth/login and store access_token=</span></span>
+<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="co"># in ~/.verae/auth.properties (mode 600), or:</span></span>
+<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="bu">export</span> <span class="va">VERAE_GLOBAL_TOKEN</span><span class="op">=</span>...</span></code></pre></div>
+<h2 id="tests">Tests</h2>
+<div class="sourceCode" id="cb6"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> run pytest</span></code></pre></div>
+<p>Stamp traces (live VeraeTime) are a separate script. They write
+<code>debug-trace/&lt;YYYY-MM-DDTHHMMSSZ&gt;-&lt;slug&gt;/</code>:</p>
+<div class="sourceCode" id="cb7"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="ex">uv</span> run python scripts/transaction_log_test.py</span></code></pre></div>
+<h2 id="build-these-documents">Build these documents</h2>
+<div class="sourceCode" id="cb8"><pre class="sourceCode sh"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> scripts/build-docs.sh</span></code></pre></div>
+<p>HTML lands in <code>docs/html/</code>. PDF lands in
+<code>docs/pdf/</code>.</p>
+</body>
+</html>
--- a/docs/html/standards.html
+++ b/docs/html/standards.html
@ -0,0 +1,141 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+  <title>standards</title>
+  <style>
+    /* Default styles provided by pandoc.
+    ** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
+    */
+    code{white-space: pre-wrap;}
+    span.smallcaps{font-variant: small-caps;}
+    div.columns{display: flex; gap: min(4vw, 1.5em);}
+    div.column{flex: auto; overflow-x: auto;}
+    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+    /* The extra [class] is a hack that increases specificity enough to
+       override a similar rule in reveal.js */
+    ul.task-list[class]{list-style: none;}
+    ul.task-list li input[type="checkbox"] {
+      font-size: inherit;
+      width: 0.8em;
+      margin: 0 0.8em 0.2em -1.6em;
+      vertical-align: middle;
+    }
+    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
+  </style>
+  <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+<header id="title-block-header">
+<h1 class="title">standards</h1>
+</header>
+<h1 id="standards">Standards</h1>
+<p>Rules for the Verae MCP timestamping server.</p>
+<h2 id="protocol">Protocol</h2>
+<p>This process is an MCP server (Model Context Protocol). Clients are
+assistants and inspectors that speak MCP. It is not a REST product API
+and not a browser session by itself.</p>
+<h2 id="hash-only">Hash only</h2>
+<ul>
+<li>Callers send a SHA-256 digest: 64 lowercase hex characters. A
+<code>sha256:</code> prefix is stripped.</li>
+<li>The server does not read files, does not accept document bytes, and
+does not hash content.</li>
+<li>Empty input has the well-known digest
+<code>e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855</code>.
+Callers may stamp that digest. The server does not invent it from a
+missing file.</li>
+</ul>
+<h2 id="scopes">Scopes</h2>
+<table>
+<colgroup>
+<col style="width: 50%" />
+<col style="width: 50%" />
+</colgroup>
+<thead>
+<tr>
+<th>Scope</th>
+<th>Where the receipt lives</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>local</code></td>
+<td>JSON file, default
+<code>~/.verae/mcp-timestamp-local.json</code></td>
+</tr>
+<tr>
+<td><code>shared</code></td>
+<td>Same file. There is no separate shared store in this process</td>
+</tr>
+<tr>
+<td><code>global</code></td>
+<td><code>POST https://api.veraetime.net/api/timestamp</code> with
+<code>wait=true</code></td>
+</tr>
+</tbody>
+</table>
+<p><code>want_scope=global</code> on <code>verify</code> asks VeraeTime.
+A local receipt cannot satisfy <code>global</code>.</p>
+<h2 id="global-history">Global history</h2>
+<p><code>hash_report</code> reads the local file only. VeraeTime is not
+queried for a digest history. A global stamp can verify by certificate
+id and still be absent from <code>hash_report</code>. An empty list
+means “not in the local file,” not “VeraeTime has no record.”</p>
+<h2 id="credentials">Credentials</h2>
+<ul>
+<li>Token: <code>VERAE_GLOBAL_TOKEN</code>, else
+<code>access_token</code> / <code>id_token</code> /
+<code>auth_token</code> in <code>~/.verae/auth.properties</code>
+(<code>VERAE_AUTH_PROPERTIES</code> overrides the path).</li>
+<li>Do not commit tokens. <code>.env</code> is gitignored.</li>
+<li>The local receipt file is mode <code>0600</code> after each
+save.</li>
+</ul>
+<h2 id="nats">NATS</h2>
+<p><code>NatsLedger</code> is optional and is not the default. It uses
+core NATS request/reply:</p>
+<ul>
+<li><code>verae.ts.request</code></li>
+<li><code>verae.ts.verify</code></li>
+<li><code>verae.hash.report</code></li>
+</ul>
+<p>Job-complete and receipt notifications stay ephemeral core NATS
+(<code>verae.ts.completed</code>, <code>verae.ts.receipt</code>). This
+server does not put those events on JetStream.</p>
+<h2 id="transports">Transports</h2>
+<table>
+<colgroup>
+<col style="width: 50%" />
+<col style="width: 50%" />
+</colgroup>
+<thead>
+<tr>
+<th><code>VERAE_MCP_TRANSPORT</code></th>
+<th>Bind</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>unset or <code>stdio</code></td>
+<td>Parent process stdin/stdout</td>
+</tr>
+<tr>
+<td><code>streamable-http</code></td>
+<td><code>VERAE_MCP_HOST</code> (default <code>127.0.0.1</code>) and
+<code>VERAE_MCP_PORT</code> (default <code>8000</code>), path
+<code>/mcp</code></td>
+</tr>
+</tbody>
+</table>
+<p>Leave the HTTP bind on loopback unless a reverse proxy terminates TLS
+and authentication in front of it. Do not publish the VeraeTime bearer
+token on an open internet listener.</p>
+<h2 id="errors">Errors</h2>
+<p>Invalid digests and unknown scopes raise <code>ToolError</code> with
+the <code>ValueError</code> text. HTTP failures from VeraeTime surface
+as <code>global timestamp HTTP &lt;status&gt;</code>.</p>
+</body>
+</html>
--- a/docs/html/style.css
+++ b/docs/html/style.css
@ -0,0 +1 @@
+body{font-family:Georgia,serif;max-width:42rem;margin:2rem auto;padding:0 1rem;line-height:1.45}code,pre{font-family:ui-monospace,monospace}table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:0.3rem 0.5rem}
--- a/docs/operator-guide.md
+++ b/docs/operator-guide.md
@ -0,0 +1,58 @@
+# Operator guide
+
+## Install
+
+```sh
+cd /Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server
+uv sync --group dev
+```
+
+## Run stdio
+
+```sh
+uv run verae-mcp-timestamping-server
+```
+
+## Run Streamable HTTP
+
+```sh
+VERAE_MCP_TRANSPORT=streamable-http uv run verae-mcp-timestamping-server
+```
+
+The listener is `http://127.0.0.1:8000/mcp`.
+
+For the sample page on another origin:
+
+```sh
+VERAE_MCP_CORS=1 VERAE_MCP_TRANSPORT=streamable-http uv run verae-mcp-timestamping-server
+```
+
+A page served from the public internet still cannot call `127.0.0.1` from current browsers. Open `site/index.html` on the same machine, or put TLS and an access control in front of a non-loopback bind you choose yourself.
+
+## Global token
+
+```sh
+# POST https://api.veraetime.net/auth/login and store access_token=
+# in ~/.verae/auth.properties (mode 600), or:
+export VERAE_GLOBAL_TOKEN=...
+```
+
+## Tests
+
+```sh
+uv run pytest
+```
+
+Stamp traces (live VeraeTime) are a separate script. They write `debug-trace/<YYYY-MM-DDTHHMMSSZ>-<slug>/`:
+
+```sh
+uv run python scripts/transaction_log_test.py
+```
+
+## Build these documents
+
+```sh
+bash scripts/build-docs.sh
+```
+
+HTML lands in `docs/html/`. PDF lands in `docs/pdf/`.
--- a/docs/pdf/api.pdf
+++ b/docs/pdf/api.pdf
--- a/docs/pdf/architecture.pdf
+++ b/docs/pdf/architecture.pdf
--- a/docs/pdf/operator-guide.pdf
+++ b/docs/pdf/operator-guide.pdf
--- a/docs/pdf/standards.pdf
+++ b/docs/pdf/standards.pdf
--- a/docs/standards.md
+++ b/docs/standards.md
@ -0,0 +1,56 @@
+# Standards
+
+Rules for the Verae MCP timestamping server.
+
+## Protocol
+
+This process is an MCP server (Model Context Protocol). Clients are assistants and inspectors that speak MCP. It is not a REST product API and not a browser session by itself.
+
+## Hash only
+
+- Callers send a SHA-256 digest: 64 lowercase hex characters. A `sha256:` prefix is stripped.
+- The server does not read files, does not accept document bytes, and does not hash content.
+- Empty input has the well-known digest `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`. Callers may stamp that digest. The server does not invent it from a missing file.
+
+## Scopes
+
+| Scope | Where the receipt lives |
+| --- | --- |
+| `local` | JSON file, default `~/.verae/mcp-timestamp-local.json` |
+| `shared` | Same file. There is no separate shared store in this process |
+| `global` | `POST https://api.veraetime.net/api/timestamp` with `wait=true` |
+
+`want_scope=global` on `verify` asks VeraeTime. A local receipt cannot satisfy `global`.
+
+## Global history
+
+`hash_report` reads the local file only. VeraeTime is not queried for a digest history. A global stamp can verify by certificate id and still be absent from `hash_report`. An empty list means "not in the local file," not "VeraeTime has no record."
+
+## Credentials
+
+- Token: `VERAE_GLOBAL_TOKEN`, else `access_token` / `id_token` / `auth_token` in `~/.verae/auth.properties` (`VERAE_AUTH_PROPERTIES` overrides the path).
+- Do not commit tokens. `.env` is gitignored.
+- The local receipt file is mode `0600` after each save.
+
+## NATS
+
+`NatsLedger` is optional and is not the default. It uses core NATS request/reply:
+
+- `verae.ts.request`
+- `verae.ts.verify`
+- `verae.hash.report`
+
+Job-complete and receipt notifications stay ephemeral core NATS (`verae.ts.completed`, `verae.ts.receipt`). This server does not put those events on JetStream.
+
+## Transports
+
+| `VERAE_MCP_TRANSPORT` | Bind |
+| --- | --- |
+| unset or `stdio` | Parent process stdin/stdout |
+| `streamable-http` | `VERAE_MCP_HOST` (default `127.0.0.1`) and `VERAE_MCP_PORT` (default `8000`), path `/mcp` |
+
+Leave the HTTP bind on loopback unless a reverse proxy terminates TLS and authentication in front of it. Do not publish the VeraeTime bearer token on an open internet listener.
+
+## Errors
+
+Invalid digests and unknown scopes raise `ToolError` with the `ValueError` text. HTTP failures from VeraeTime surface as `global timestamp HTTP <status>`.
--- a/recommended-changes/2026-09-21-docs-and-cors/Done-and-not-done.md
+++ b/recommended-changes/2026-09-21-docs-and-cors/Done-and-not-done.md
@ -0,0 +1,11 @@
+# Done and not done
+
+WhatToChange: recommended-changes/2026-09-21-docs-and-cors/
+
+What was actually done:
+- Markdown, HTML, and PDF for standards, architecture, API, and the operator guide.
+- README points at scripts/build-docs.sh.
+- VERAE_MCP_CORS=1 enables CORS on the Streamable HTTP app.
+
+What was not done:
+- (none)
--- a/recommended-changes/2026-09-21-docs-and-cors/How-to-implement-the-changes.md
+++ b/recommended-changes/2026-09-21-docs-and-cors/How-to-implement-the-changes.md
@ -0,0 +1,8 @@
+# How to implement the changes:
+
+Against the pin in git-versions.md (dirty tree).
+
+1. Add `docs/standards.md`, `docs/architecture.md`, `docs/api.md`, `docs/operator-guide.md`.
+2. Add `scripts/build-docs.sh` (pandoc HTML and PDF).
+3. Link the build from `README.md`.
+4. When `VERAE_MCP_CORS=1`, run uvicorn on `streamable_http_app()` with `CORSMiddleware`.
--- a/recommended-changes/2026-09-21-docs-and-cors/README.md
+++ b/recommended-changes/2026-09-21-docs-and-cors/README.md
@ -0,0 +1,25 @@
+# Recommended changes: docs and CORS
+
+Second review, 2026-09-21. Pins are in git-versions.md.
+
+## Install
+
+```sh
+cd /Users/marchon/research/modelcontextprotocol/verae-mcp-timestamping-server
+uv sync --group dev
+```
+
+## Usage
+
+```sh
+less recommended-changes/2026-09-21-docs-and-cors/What-to-Change.md
+bash scripts/build-docs.sh
+```
+
+## Contributing
+
+Questions: this research workspace. PRs welcome.
+
+## License
+
+UNLICENSED © George Lambert
--- a/recommended-changes/2026-09-21-docs-and-cors/What-to-Change-To.md
+++ b/recommended-changes/2026-09-21-docs-and-cors/What-to-Change-To.md
@ -0,0 +1,6 @@
+# What to Change To:
+
+| Component | Target behavior | Acceptance criteria | Constraints |
+| --- | --- | --- | --- |
+| `docs/*.md` plus HTML and PDF | Operator guide, architecture, tool API, and standards | `bash scripts/build-docs.sh` writes four HTML files and four PDFs, each PDF larger than 10 KB | Facts match the code. Do not document JetStream for job-complete |
+| `VERAE_MCP_CORS=1` | Starlette CORS allows the sample page to see the session header | Default `mcp.run` path unchanged when the variable is unset | Bind stays `127.0.0.1` unless the operator sets `VERAE_MCP_HOST` |
--- a/recommended-changes/2026-09-21-docs-and-cors/What-to-Change.md
+++ b/recommended-changes/2026-09-21-docs-and-cors/What-to-Change.md
@ -0,0 +1,13 @@
+# What to Change:
+
+Reviewed after `60bcefb`. Pytest 14 passed. The server behavior from the first pack is in place. Operators still had only a short README.
+
+## What is working
+
+- Hash-only tools, file ledger mode 0600, global HTTP off the event loop.
+- `debug-trace/` remains the live stamp record and stays in git.
+
+| Component | Problem | Evidence | Severity | Type |
+| --- | --- | --- | --- | --- |
+| README only | No architecture, tool reference, or standards a reader can print | `docs/` did not exist before this pack | high | doc drift |
+| Streamable HTTP | Browser sample on another origin cannot read `mcp-session-id` | `server.py` called `mcp.run` with no CORS middleware | medium | missing gate |
--- a/Show more
+++ b/Show more
				`@ -0,0 +1 @@`
				`body{font-family:Georgia,serif;max-width:42rem;margin:2rem auto;padding:0 1rem;line-height:1.45}code,pre{font-family:ui-monospace,monospace}table{border-collapse:collapse}td,th{border:1px solid #ccc;padding:0.3rem 0.5rem}`