Add public visual guide

docs/visual-guide.md

@@ -0,0 +1,203 @@
+# Visual Guide
+
+> Status: draft | Updated 2026-07-07 | Applies to: AMPG operators and contributors
+
+This guide shows the core AMPG flows and common deployment topologies. Diagrams use
+Mermaid so they render in GitHub Markdown and can later be reused by a public docs site.
+
+## Build Flow
+
+AMPG starts from one canonical site and renders transport-appropriate outputs. Rich web
+output can stay rich on clearnet, while constrained or privacy-oriented transports get
+safer defaults.
+
+```mermaid
+flowchart LR
+  source["Source site<br/>static HTML, Markdown, or generated output"]
+  graph["AMPG content graph"]
+  clearnet["clearnet<br/>HTML/CSS/assets"]
+  tor["Tor<br/>privacy HTML"]
+  i2p["I2P<br/>privacy HTML"]
+  gemini["Gemini<br/>Gemtext"]
+  ipfs["IPFS<br/>static tree"]
+  reticulum["Reticulum<br/>Micron"]
+  manifest["fixture manifest<br/>routes and expected transports"]
+
+  source --> graph
+  graph --> clearnet
+  graph --> tor
+  graph --> i2p
+  graph --> gemini
+  graph --> ipfs
+  graph --> reticulum
+  clearnet --> manifest
+  tor --> manifest
+  i2p --> manifest
+  gemini --> manifest
+  ipfs --> manifest
+  reticulum --> manifest
+```
+
+## Deployment Spine
+
+Live deploy work is split into narrow stages. Each stage has a dry-run form first, and
+live stages require explicit confirmation.
+
+```mermaid
+flowchart TD
+  init["init site"]
+  build["build outputs"]
+  plan["install-plan<br/>review package, state, supervisor steps"]
+  packages["deploy apply --stage packages<br/>install selected daemon packages"]
+  approve["approvals approve<br/>record reviewed artifact digests"]
+  state["deploy apply --stage state<br/>copy approved config into AMPG state"]
+  supervisor["deploy apply --stage supervisor<br/>install AMPG-named service files"]
+  start["deploy apply --stage start<br/>start AMPG-owned services"]
+  addresses["deploy apply --stage addresses<br/>capture daemon-written public addresses"]
+  health["deploy apply --stage health<br/>verify published fixtures"]
+
+  init --> build --> plan --> packages --> approve --> state --> supervisor --> start --> addresses --> health
+```
+
+## Ownership Boundaries
+
+AMPG tries to keep operator-owned services, AMPG-owned generated state, and
+daemon-written identity material distinct.
+
+```mermaid
+flowchart LR
+  operator["Operator-owned<br/>DNS, router, existing reverse proxy, adopted daemons"]
+  ampg["AMPG-owned<br/>generated outputs, reviewed artifacts, state registry"]
+  daemon["Daemon-written<br/>onion hostname, I2P destination, keys, logs"]
+  public["Public routes<br/>clearnet, Tor, I2P, Gemini, IPFS, Reticulum"]
+
+  operator -- may be adopted by policy --> ampg
+  ampg -- starts or configures managed service --> daemon
+  daemon -- writes transport identity --> ampg
+  ampg -- publishes selected outputs --> public
+```
+
+## VPS Multi-Transport
+
+A normal VPS is the cleanest full-stack topology. AMPG can adopt existing daemons or
+manage missing ones, while clearnet DNS and TLS remain operator-controlled by default.
+
+```mermaid
+flowchart TB
+  dns["DNS provider<br/>A/AAAA/CNAME records"]
+  internet["public internet"]
+  vps["VPS host"]
+  ampg["AMPG"]
+  outputs["/var/www/ampg/site outputs"]
+  nginx["nginx or Caddy<br/>clearnet ingress"]
+  tor["Tor daemon<br/>onion service"]
+  i2p["i2pd<br/>server tunnel"]
+  gemini["Gemini daemon"]
+  users["Visitors and AMPB checks"]
+
+  dns --> internet --> vps
+  vps --> ampg --> outputs
+  outputs --> nginx
+  outputs --> tor
+  outputs --> i2p
+  outputs --> gemini
+  nginx --> users
+  tor --> users
+  i2p --> users
+  gemini --> users
+```
+
+## Home Server Behind A Router
+
+Behind-router clearnet publishing may need port forwarding, IPv6, Dynamic DNS, a reverse
+tunnel, or DNS-01 certificate validation. Tor and I2P can often avoid inbound clearnet
+port forwarding.
+
+```mermaid
+flowchart LR
+  visitor["Visitor"]
+  dns["DNS or Dynamic DNS"]
+  router["Home router<br/>NAT and firewall"]
+  host["Laptop or mini server"]
+  ampg["AMPG"]
+  clearnet["clearnet web server"]
+  tor["Tor onion service"]
+  i2p["I2P server tunnel"]
+
+  visitor --> dns --> router --> clearnet
+  router --> host
+  host --> ampg
+  ampg --> clearnet
+  ampg --> tor
+  ampg --> i2p
+  visitor -. no router port forward required for many cases .-> tor
+  visitor -. no router port forward required for many cases .-> i2p
+```
+
+## Android Or Termux Server
+
+An old phone can be useful for mobile-server experiments. AMPG plans user-space daemons,
+Termux package installs, and service scripts, while battery policy, storage, and public
+reachability remain device-owned.
+
+```mermaid
+flowchart TB
+  phone["Android phone<br/>Termux"]
+  ampg["AMPG CLI"]
+  pkg["pkg install<br/>tor, i2pd, nginx"]
+  state["Termux state<br/>AMPG config, keys, logs"]
+  services["termux-services<br/>AMPG-named daemons"]
+  transports["Tor/I2P/Gemini routes"]
+  checks["health checks<br/>fixture URLs"]
+
+  phone --> ampg
+  ampg --> pkg
+  ampg --> state
+  state --> services
+  services --> transports
+  transports --> checks
+```
+
+## Single-Transport Deployments
+
+AMPG should also work when the operator wants only one selected transport. This is useful
+for I2P-only, Tor-only, Gemini-only, or Reticulum-focused deployments.
+
+```mermaid
+flowchart LR
+  source["existing site"]
+  ampg["AMPG"]
+  selected["selected transport only"]
+  daemon["adopted or managed daemon"]
+  public["published route"]
+
+  source --> ampg --> selected --> daemon --> public
+```
+
+## Browser Test Loop
+
+AMPG writes fixture manifests so a companion browser or checker can verify that each
+route uses the expected transport profile.
+
+```mermaid
+sequenceDiagram
+  participant Site as Source site
+  participant AMPG as AMPG
+  participant Manifest as Fixture manifest
+  participant AMPB as AMPB/browser checker
+  participant Transport as Selected transport
+
+  Site->>AMPG: build selected outputs
+  AMPG->>Manifest: write route expectations
+  AMPB->>Manifest: load fixtures
+  AMPB->>Transport: request fixture URL through expected profile
+  Transport-->>AMPB: return generated output
+  AMPB-->>AMPG: report pass or failure
+```
+
+## Public Docs Site Path
+
+The first public docs site should be generated from the public Markdown docs in this
+repository. A GitHub Pages build can later reuse these Mermaid diagrams with MkDocs,
+mdBook, or another static docs generator. Private strategy notes, deployment inventory,
+and host-specific material should stay under private docs and outside any Pages build.