Initial AMPB scaffold

docs/architecture.md

@@ -0,0 +1,41 @@
+# Architecture
+
+> Status: draft | Updated 2026-07-05 | Applies to: AMPB contributors and integrators
+
+AMPB is a browser orchestration layer for privacy and alternate-network transports. It
+keeps the routing, transport management, and profile isolation decisions outside the
+browser engine until those contracts are stable.
+
+## Operating Model
+
+1. Normalize the requested URL.
+2. Select a transport from scheme and host rules.
+3. Inspect whether the required local transport is already running.
+4. Adopt healthy existing transports.
+5. If the selected transport is missing, show a first-use prompt before setup.
+6. Start or install managed transports only after user consent.
+7. Open the URL with the matching isolated profile.
+
+## Main Components
+
+- `ampbrowser.routing`: deterministic URL-to-transport rules.
+- `ampbrowser.transports`: local readiness checks for Tor, I2P, Reticulum, and Gemini.
+- `ampbrowser.plan`: dry-run action planner for browser launches.
+- `ampbrowser.docsgen`: generated public documentation from code-owned metadata.
+
+## Browser Strategy
+
+The first implementation should be a launcher and profile manager, not a browser-engine
+fork. Tor Browser, Mullvad Browser, Firefox profiles, Chromium profiles, terminal Gemini
+clients, and future Reticulum-native viewers can all sit behind the same route and
+transport contracts.
+
+The long-term browser can become more integrated once the orchestration surface is boring:
+profile isolation is reliable, transport adoption is predictable, and generated fixtures
+from AMPG can be opened without manual proxy setup.
+
+## Relationship To AMPG
+
+AMPG publishes protocol-specific site variants. AMPB opens those variants with the right
+transport and profile. Wownero is the shared fixture for static publishing, while
+interactive targets exercise sessions, dynamic assets, forms, and script policy.

docs/autodocs.md

@@ -0,0 +1,39 @@
+# Autodocs
+
+> Status: draft | Updated 2026-07-05 | Applies to: AMPB maintainers
+
+Public docs should stay concise and current. Code-owned behavior is documented from code,
+while manual docs explain stable concepts and operator-facing choices.
+
+## Generated Docs
+
+Run:
+
+```sh
+python3 -m ampbrowser docs generate
+```
+
+Check for drift:
+
+```sh
+python3 -m ampbrowser docs generate --check
+```
+
+Generated files live under `docs/generated/` and must not be edited by hand.
+
+## Manual Docs
+
+Manual public docs must include a status header near the top and should avoid strategy
+notes, checkpointing, timelines, private addresses, local hostnames, credentials, and
+deployment inventory.
+
+Private notes belong in `docs/private/`. That directory is ignored and should remain
+absent from commits.
+
+## Link And Header Check
+
+Run:
+
+```sh
+python3 tools/docs_check.py
+```

docs/configuration.md

@@ -0,0 +1,49 @@
+# Configuration
+
+> Status: draft | Updated 2026-07-05 | Applies to: AMPB users and package maintainers
+
+AMPB should work without a config file for common local setups. Explicit configuration is
+for changing defaults, pinning binary paths, choosing managed state directories, and
+restricting which transports are allowed.
+
+Transport setup is lazy. AMPB does not install, start, or configure a transport until the
+user opens a URL that needs it and approves the first-use prompt.
+
+## Default Behavior
+
+- Clearnet URLs use a clearnet profile.
+- `.onion` hosts use Tor through `127.0.0.1:9050` when available.
+- `.i2p` hosts use I2P through `127.0.0.1:4444` when available.
+- `gemini://` URLs use the Gemini profile.
+- Reticulum-family URLs are routed to the Reticulum adapter once configured.
+
+## Future Config Shape
+
+```toml
+[browser]
+default_engine = "system"
+state_dir = ".ampb"
+
+[transports.tor]
+enabled = true
+mode = "adopt-or-manage"
+socks_endpoint = "127.0.0.1:9050"
+
+[transports.i2p]
+enabled = true
+mode = "adopt-or-manage"
+http_proxy = "127.0.0.1:4444"
+
+[transports.reticulum]
+enabled = false
+mode = "adopt"
+
+[profiles]
+isolate_by_transport = true
+```
+
+## Public And Private Files
+
+Public docs describe behavior, configuration, and supported fixtures. Private strategy,
+deployment notes, host inventory, generated keys, and local address books belong under
+`docs/private/`, which is ignored by git.

docs/generated/route-rules.md

@@ -0,0 +1,13 @@
+# Generated Route Rules
+
+> Status: generated | Updated by `python3 -m ampbrowser docs generate` | Applies to: AMPB
+
+This file is generated from code. Do not edit it by hand.
+
+| Match | Transport | Profile | Note |
+| --- | --- | --- | --- |
+| `*.onion` | `tor` | `tor` | route through Tor SOCKS |
+| `*.i2p` | `i2p` | `i2p` | route through I2P HTTP proxy |
+| `gemini://*` | `gemini` | `gemini` | fetch and render Gemtext |
+| `rns://*, lxmf://*, nomad://*` | `reticulum` | `reticulum` | route through Reticulum adapter |
+| `http://*, https://*` | `clearnet` | `clearnet` | ordinary web profile |

docs/generated/transports.md

@@ -0,0 +1,12 @@
+# Generated Transports
+
+> Status: generated | Updated by `python3 -m ampbrowser docs generate` | Applies to: AMPB
+
+This file is generated from code. Do not edit it by hand.
+
+| Transport | Adopt Check | Managed State | Profile | Note |
+| --- | --- | --- | --- | --- |
+| `tor` | SOCKS on 127.0.0.1:9050 | `.ampb/transports/tor` | `tor` | Adopt existing Tor when healthy; otherwise prompt before managed setup. |
+| `i2p` | HTTP proxy on 127.0.0.1:4444 | `.ampb/transports/i2p` | `i2p` | Adopt existing i2pd/I2P router when healthy; otherwise prompt before managed setup. |
+| `gemini` | built-in renderer available | `.ampb/transports/gemini` | `gemini` | No daemon required for static Gemtext browsing. |
+| `reticulum` | RNS tools and configured interfaces | `.ampb/transports/reticulum` | `reticulum` | Adapter planned; physical/link-layer setup may require operator config. |

docs/test-fixtures.md

@@ -0,0 +1,25 @@
+# Test Fixtures
+
+> Status: draft | Updated 2026-07-05 | Applies to: AMPB and AMPG compatibility testing
+
+Fixtures should cover static sites, protocol-specific publishing, and interactive web
+apps without exposing private deployment notes.
+
+## Primary Fixture
+
+Wownero is the first shared fixture between AMPG and AMPB. It exercises ordinary
+clearnet pages, Tor and I2P HTML variants, Gemini output, static assets, and semantic
+HTML improvements that improve alternate renderers.
+
+## Interactive Fixtures
+
+`ai-gen-bot` and `medusa-multi-tenant-platform` are stretch fixtures for dynamic behavior:
+sessions, forms, asset policy, script policy, tenant routing, and transport-specific
+degradation.
+
+## Fixture Requirements
+
+- Every fixture has a public description of what behavior it exercises.
+- Private addresses, tunnel keys, host inventory, and credentials stay out of public docs.
+- Browser checks prefer dry-run plans before live launch.
+- Static output from AMPG should be openable by AMPB without manual proxy setup.

docs/transport-management.md

@@ -0,0 +1,34 @@
+# Transport Management
+
+> Status: draft | Updated 2026-07-05 | Applies to: AMPB transport adapters
+
+Transport management follows one rule: use what is already healthy, and manage missing
+transports only after the user opens a URL that needs them and approves setup.
+
+## Lifecycle
+
+1. Inspect known local endpoints.
+2. Adopt running transports that match the selected URL.
+3. For missing transports, show a prompt that names what will be installed or started.
+4. Resolve a configured binary and state directory only after consent.
+5. Start the daemon with AMPB-owned state.
+6. Wait for the health endpoint.
+7. Launch the browser profile only after the transport is ready.
+8. Stop only AMPB-owned daemons.
+
+## Ownership
+
+AMPB never stops a daemon it did not start. Adopted transports remain owned by the user,
+system service, or package manager that launched them.
+
+Managed transports store runtime state under `.ampb/transports/<name>` by default. Keys,
+leases, tunnels, and daemon logs in that tree are local state and must not be committed.
+
+## Current Adapters
+
+- Tor: detect SOCKS on `127.0.0.1:9050`; managed start planned.
+- I2P: detect HTTP proxy on `127.0.0.1:4444`; managed start planned.
+- Gemini: built-in route and render path; no daemon required for static browsing.
+- Reticulum: route contract exists; adapter and readiness model are planned.
+
+Generated transport metadata lives in [generated transports](generated/transports.md).