Fix catalog PDF links; add bring-online guide; feature zappier billing

PDFs rewrite in-document .md/.html links to sibling PDFs. Catalog start page is GETTING-STARTED (install, first-up, monitor). Billing and user platform is zappier-edge (original ~/zappier tree).
2026-09-11 14:59:13 -04:00 · 2026-09-11 14:59:13 -04:00 · 65bfa544b2
commit 65bfa544b2
parent e401635fd6
10 changed files with 149 additions and 25 deletions
--- a/README.MD
+++ b/README.MD
@ -28,8 +28,9 @@ cd ../.. && npm run gate:0

 Gates (`npm run gate:N`) continue the middleware plan in [TODO.md](TODO.md). Phases 0–8, 10, 11 already passed in the source tree; 9 and 12+ are still open. Path prefixes now use `packages/`.

+**Bring online:** https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf  
 **Live catalog (PDF default):** https://zapier.georgelambert.org/ · [Markdown indexes](https://zapier.georgelambert.org/index-md.html)  
-**Install / Docker / Proxmox / metal:** https://zapier.georgelambert.org/packages/verae-ops/README.pdf  
+**Billing / users (zappier-edge):** https://zapier.georgelambert.org/packages/zappier/docs/USER-MANUAL.pdf  
 **Sphinx:** https://zapier.georgelambert.org/sphinx/ · [LaTeX PDF](https://zapier.georgelambert.org/sphinx/verae-zapier-modules.pdf)

 ## Documentation map
--- a/docs/00-sources/provenance.md
+++ b/docs/00-sources/provenance.md
@ -4,7 +4,7 @@ This workspace composes three existing trees. Canonical work after import is her

 | Package / tree | Imported from | Role |
 |----------------|---------------|------|
-| `packages/zappier` | `/Users/marchon/zappier` | Commercial platform: custom rate card, tiers, API keys, customer portal, admin, Stripe meter, PO invoices, usage ledger. Demo `/v1/transform` and `/v1/storage` are **not** Verae. |
+| `packages/zappier` (**zappier-edge**) | Standalone git tree `/Users/marchon/zappier` (no GitHub remote; published at https://git.georgelambert.org/marchon/zappier-edge) | **Billing and user middleware:** custom rate card, tiers, API keys, customer portal, admin users, Stripe meter, PO invoices, usage ledger. Demo `/v1/transform` and `/v1/storage` are **not** Verae. |
 | `packages/verae-zapier-middleware` | `/Users/marchon/datacubes/verae-zapier-api/verae-zapier-middleware` | Verae timestamp adapter: `/zapier/v1/*`, MOCK_VERAE, NATS workers, REST Hooks. Coarse `PLAN_LIMITS` — not used on the public edge after composition. |
 | `packages/verae-zapier` | `/Users/marchon/datacubes/verae-zapier-api/verae-zapier` | Zapier Platform CLI app (JS). Today talks to middleware with `zmw_` keys; will talk to zappier `x-api-key` after PR 5. |
 | `vendor/zapier-platform` | `/Users/marchon/research/zapier-platform` (upstream `git@github.com:zapier/zapier-platform.git`) | Official CLI/core/schema/examples. Reference only; do not fork for product code. |
--- a/packages/overview/INDEX.md
+++ b/packages/overview/INDEX.md
@ -1,6 +1,8 @@
 # Documentation index

-Read **high-level first**, then **architecture**, then the rest. Live catalog (PDF by default): https://zapier.georgelambert.org/ — [Markdown indexes](https://zapier.georgelambert.org/index-md.html)
+**Bring the system online:** https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf
+
+Live catalog (PDF by default): https://zapier.georgelambert.org/ — [Markdown indexes](https://zapier.georgelambert.org/index-md.html)

 Operator console (loopback): http://127.0.0.1:3850/ · [CONSOLE.pdf](https://zapier.georgelambert.org/packages/verae-fleet/docs/CONSOLE.pdf)

--- a/packages/overview/README.md
+++ b/packages/overview/README.md
@ -3,6 +3,7 @@
 High-level description of the whole system: what it is, which **independent git repositories** implement it, how it stays up, how it behaves when the local network fails, and how it talks to the **central Verae NATS.IO 3-server cluster**. New work is added by **new address routing**, not by teaching Zapier about NATS.

 **This repo:** https://git.georgelambert.org/marchon/overview  
+**Bring online:** https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf  
 **Live catalog (PDF by default):** https://zapier.georgelambert.org/ · [Markdown indexes](https://zapier.georgelambert.org/index-md.html)  
 **Clone:** `ssh://git@git.georgelambert.org:2223/marchon/overview.git`

--- a/packages/verae-ops/GETTING-STARTED.md
+++ b/packages/verae-ops/GETTING-STARTED.md
@ -0,0 +1,95 @@
+# Bring Verae Time × Zapier online
+
+This is the **top document** for install, first-up, and monitoring. Platform-specific detail lives in the numbered ops chapters; do not start there.
+
+**Catalog:** https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf  
+**Billing / users (zappier-edge):** https://zapier.georgelambert.org/packages/zappier/docs/USER-MANUAL.pdf  
+**Operator console:** http://127.0.0.1:3850/ (loopback) · https://zapier.georgelambert.org/packages/verae-fleet/docs/CONSOLE.pdf
+
+## What you are turning on
+
+| Piece | Job | Default |
+|-------|-----|---------|
+| **zappier-edge** | Billing, API keys, customer portal, admin, Stripe | `:3000` public HTTPS |
+| **verae-middleware** | Zapier `/zapier/v1`, chain, NATS | `:3100` |
+| **NATS JetStream** | Private jobs / archive | `:4222` **not public** |
+| **worm ×3, tree-node ×3** | Off-chain files and Merkle leaves | fleet floor |
+| **fleet** | Replica floors, SSH hosts, Trace, Docs | `:3850` loopback |
+
+Zapier cloud talks **only** to zappier-edge over HTTPS.
+
+The billing and user platform is the standalone **zappier** project (`/Users/marchon/zappier`, Forgejo [zappier-edge](https://git.georgelambert.org/marchon/zappier-edge)): portal signup, TOTP, API keys, rate card, Stripe meter, PO invoices, admin users. Verae middleware does **not** replace it.
+
+## 15-minute lab (one machine)
+
+```bash
+git clone ssh://git@git.georgelambert.org:2223/marchon/master-zapier-plan-draft.git
+cd master-zapier-plan-draft
+export MONOREPO="$PWD"
+cd packages/verae-ops
+docker compose up --build
+```
+
+Check:
+
+```bash
+curl -fsS http://127.0.0.1:3000/health    # zappier-edge (billing + users)
+curl -fsS http://127.0.0.1:3100/health    # middleware
+```
+
+Open:
+
+- Customer portal: http://127.0.0.1:3000/portal — sign up, copy `x-api-key`
+- Admin: http://127.0.0.1:3000/admin
+- API docs: http://127.0.0.1:3000/docs
+
+Do **not** publish NATS `4222`.
+
+## Operator console (monitor)
+
+On the same machine (or SSH tunnel `ssh -L 3850:127.0.0.1:3850 user@host`):
+
+```bash
+cd "$MONOREPO/packages/verae-fleet"
+node src/cli.js serve
+```
+
+http://127.0.0.1:3850/ — Fleet (green/yellow/red), Trace, Docs. Tree-node **min 3**; pause does not count.
+
+```bash
+node src/cli.js status
+node src/cli.js ssh-check ns1
+```
+
+## Point Zapier at the lab
+
+1. TLS in front of `:3000` (Caddy).
+2. Zapier app env: `MIDDLEWARE_BASE_URL=https://<zappier-host>` (edge meters, then proxies to middleware).
+3. Connect with the portal API key.
+
+## Production (pick one)
+
+| Where | Read |
+|-------|------|
+| Docker | [02-docker.pdf](02-docker.pdf) |
+| Proxmox | [03-proxmox.pdf](03-proxmox.pdf) |
+| Cloud VMs | [04-virtual-servers.pdf](04-virtual-servers.pdf) |
+| Dedicated / NS1 | [05-dedicated-hardware.pdf](05-dedicated-hardware.pdf) |
+| Env vars & NATS | [06-linking-services.pdf](06-linking-services.pdf) |
+| Backup / upgrade | [07-maintenance.pdf](07-maintenance.pdf) |
+
+## Daily monitor
+
+| Check | Expect |
+|-------|--------|
+| `curl -fsS https://zappier.example.com/health` | 200 |
+| `curl -fsS https://middleware.example.com/health` | 200 |
+| NATS `http://127.0.0.1:8222/healthz` on each node | ok (localhost only) |
+| Fleet tree-node available ≥ 3 | green |
+| Portal login + key still works | 200 `/v1/status` with `x-api-key` |
+
+## If something is red
+
+1. Fleet row color: yellow = paused/degraded, red = below floor — `restart` that replica.
+2. 401/402 from Zapier → zappier-edge keys and rate card, not NATS.
+3. Archive lookup empty → bloom miss is **silence**; check worm/tree floors, not “error replies”.
--- a/packages/verae-ops/README.md
+++ b/packages/verae-ops/README.md
@ -11,6 +11,7 @@ This is the operations repo. Application code lives in the other independent git

 ## Reading order

+0. **[GETTING-STARTED.md](GETTING-STARTED.md)** — install, first-up, monitor (read this first)
 1. [01-dependencies.md](01-dependencies.md) — what must exist, who talks to whom
 2. [02-docker.md](02-docker.md) — Compose (NATS 3-node cluster + HTTPS edges)
 3. [03-proxmox.md](03-proxmox.md) — LXC / QEMU VMs
--- a/packages/zappier/README.md
+++ b/packages/zappier/README.md
@ -5,8 +5,11 @@ monthly credits, a usage ledger, Stripe metered billing, purchase-order
 invoicing, a company admin console, a self-service customer portal, and a
 Zapier integration.

+This is the **billing and user platform** (originally the standalone `zappier` git tree at `~/zappier`). Forgejo name: **zappier-edge**. It owns signup, TOTP, API keys, rate card, Stripe meter, PO invoices, admin users, and the customer portal. Verae middleware does not replace this.
+
 **Forgejo:** https://git.georgelambert.org/marchon/zappier-edge  
-**Catalog README:** https://zapier.georgelambert.org/packages/zappier/README.pdf
+**Catalog README:** https://zapier.georgelambert.org/packages/zappier/README.pdf  
+**Bring the whole system online:** https://zapier.georgelambert.org/packages/verae-ops/GETTING-STARTED.pdf

 ## Documentation (public PDFs)

--- a/scripts/build-docs-site.py
+++ b/scripts/build-docs-site.py
@ -21,14 +21,9 @@ SECTIONS = [
    (
        "Start here",
        [
-            ("packages/overview/README.md", "System overview (plain language)"),
-            ("packages/overview/INDEX.md", "Documentation index"),
-            ("packages/verae-ops/README.md", "Install & maintenance (Docker, Proxmox, VMs, metal)"),
-            ("packages/verae-fleet/docs/CONSOLE.md", "Operator console (Fleet · Trace · Docs)"),
-            ("README.md", "Workspace README"),
-            ("docs/04-activate/SETUP-ZAPIER-DEVELOPER.pdf", "Zapier developer setup (PDF)"),
-            ("docs/OPEN.md", "Still open"),
-            ("TODO.md", "Implementation TODO / gates"),
+            ("packages/verae-ops/GETTING-STARTED.md", "Bring the system online (install, first-up, monitor)"),
+            ("packages/overview/README.md", "What the system is (plain language)"),
+            ("packages/verae-fleet/docs/CONSOLE.md", "Operator console (loopback Fleet · Trace · Docs)"),
        ],
    ),
    (
@ -52,9 +47,7 @@ SECTIONS = [
    (
        "Per-module README (public PDFs)",
        [
-            ("packages/overview/README.md", "overview"),
-            ("packages/verae-ops/README.md", "verae-ops (install)"),
-            ("packages/zappier/README.md", "zappier-edge"),
+            ("packages/zappier/README.md", "zappier-edge (billing + users)"),
            ("packages/verae-zapier-middleware/README.md", "verae-middleware"),
            ("packages/verae-zapier/README.md", "verae-zapier-app"),
            ("packages/verae-activate/README.md", "verae-activate"),
@ -70,25 +63,32 @@ SECTIONS = [
        ],
    ),
    (
-        "Install / run",
+        "Billing, users, portal (zappier-edge)",
        [
-            ("packages/verae-ops/README.md", "Ops index"),
-            ("packages/verae-ops/01-dependencies.md", "Dependencies and data flow"),
+            ("packages/zappier/README.md", "zappier-edge README (the billing/user platform)"),
+            ("packages/zappier/docs/USER-MANUAL.md", "Operations & usage"),
+            ("packages/zappier/docs/USER-MANAGEMENT.md", "Admin users, pricing, customer types"),
+            ("packages/zappier/docs/CUSTOMER-PORTAL.md", "Signup, 2FA, API keys, reloads"),
+            ("packages/zappier/docs/ACCOUNTING.md", "Invoices, PO billing, reports"),
+            ("packages/zappier/docs/DEVELOPER.md", "Developer reference"),
+        ],
+    ),
+    (
+        "Install (detail)",
+        [
+            ("packages/verae-ops/GETTING-STARTED.md", "Bring online (start here)"),
            ("packages/verae-ops/02-docker.md", "Docker Compose"),
-            ("packages/verae-ops/03-proxmox.md", "Proxmox LXC / QEMU"),
-            ("packages/verae-ops/04-virtual-servers.md", "Virtual servers"),
+            ("packages/verae-ops/03-proxmox.md", "Proxmox"),
            ("packages/verae-ops/05-dedicated-hardware.md", "Dedicated hardware"),
-            ("packages/verae-ops/06-linking-services.md", "Linking dependent services"),
-            ("packages/verae-ops/07-maintenance.md", "Maintenance"),
+            ("packages/verae-ops/06-linking-services.md", "Linking services"),
        ],
    ),
    (
        "Samples",
        [
            ("packages/zappier/zapier-app/README.md", "Sample Zapier app (metered zappier API)"),
-            ("packages/verae-activate/README.md", "Activate-now Add Numbers sample"),
+            ("packages/verae-activate/README.md", "Activate-now Add Numbers"),
            ("packages/verae-zapier-simulator/README.md", "Hop-trace simulator"),
-            ("packages/verae-nats-process/README.md", "New NATS address template"),
        ],
    ),
    (
@ -174,10 +174,11 @@ def render_md(src: Path, html_dest: Path, pdf_dest: Path, title: str) -> str:
            str(html_dest),
            "--standalone",
            f"--resource-path={resource}",
-            "--highlight-style=breezedark",
+            "--syntax-highlighting=breezedark",
            f"--metadata=title={title}",
            f"--include-in-header={header}",
            f"--include-before-body={banner}",
+            f"--lua-filter={ROOT / 'scripts' / 'pdf-links.lua'}",
        ],
        capture_output=True,
        text=True,
--- a/scripts/build-readme-latex.py
+++ b/scripts/build-readme-latex.py
@ -48,6 +48,7 @@ def main() -> None:
            "--metadata=title=Verae Time × Zapier — repository READMEs",
            f"--include-in-header={hdr}",
            "--syntax-highlighting=breezedark",
+            f"--lua-filter={ROOT / 'scripts' / 'pdf-links.lua'}",
        ],
        check=True,
    )
--- a/scripts/pdf-links.lua
+++ b/scripts/pdf-links.lua
@ -0,0 +1,19 @@
+-- Rewrite in-document links so catalog PDFs point at other PDFs, not .md/.html.
+function Link(el)
+  local t = el.target or ""
+  if t:match("^https?://") and not t:match("zapier%.georgelambert%.org") then
+    return el
+  end
+  if t:match("^mailto:") or t:match("^#") then
+    return el
+  end
+  local path, frag = t:match("^(.-)(#.*)$")
+  if not path then
+    path, frag = t, ""
+  end
+  if path:match("%.md$") or path:match("%.html$") then
+    path = path:gsub("%.md$", ".pdf"):gsub("%.html$", ".pdf")
+    el.target = path .. frag
+  end
+  return el
+end