docs(otpiser): bespoke OTP supervision tree content across all layers

Replace template placeholders and generic content with OTP-specific
documentation, types, and FFI implementations:

- README.adoc: supervision strategies, GenServer/GenStateMachine scaffolding,
  restart intensity, use cases, example manifest, quick start
- ROADMAP.adoc: Phase 0-6 with OTP-specific milestones (tree generation,
  GenServer scaffolding, advanced OTP patterns, Elixir ecosystem integration)
- TOPOLOGY.md: module map, data flow, supervision tree model, key interfaces
- Idris2 ABI: SupervisorStrategy, ChildSpec, RestartIntensity,
  GenServerCallback, ProcessTree with well-formedness proofs
- Zig FFI: tree construction (create_supervisor, create_worker, add_child),
  tree validation, OTP code emission stubs, serialisation
- Rust ABI: mirrored OTP types with strategy/restart/shutdown enums
- Manifest parser: OTP-aware validation (strategies, feature flags)
- Machine-readable 6a2: bespoke STATE, META, ECOSYSTEM for OTP domain
- 0-AI-MANIFEST: replaced [YOUR-REPO-NAME] with otpiser

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

Author: hyperpolymath

.machine_readable/6a2/AGENTIC.a2ml

@@ -6,7 +6,7 @@
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [agent-permissions]
 can-edit-source = true

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -6,12 +6,13 @@
   (version "0.1.0")
   (name "otpiser")
   (type "tool")
-  (purpose "Generate OTP supervision trees and fault-tolerance scaffolding")
+  (purpose "Generate OTP supervision trees, GenServers, GenStateMachines, and fault-tolerance scaffolding from service descriptions")
 
   (position-in-ecosystem
     (family "-iser acceleration frameworks")
     (meta-framework "iseriser")
     (relationship "sibling")
+    (domain "Fault-tolerant distributed systems (Erlang/OTP/BEAM)")
     (top-3 ("typedqliser" "chapeliser" "verisimiser")))
 
   (related-projects
@@ -23,16 +24,25 @@
       (description "Formal type safety for any query language"))
     (project "chapeliser"
       (relationship "sibling-priority-2")
-      (description "Chapel distributed computing acceleration"))
+      (description "Chapel distributed computing acceleration — otpiser can supervise Chapel workers"))
     (project "verisimiser"
       (relationship "sibling-priority-3")
-      (description "VeriSimDB octad database augmentation"))
+      (description "VeriSimDB octad database augmentation — otpiser can supervise DB connections"))
+    (project "burble"
+      (relationship "consumer")
+      (description "Voice platform — uses OTP supervision for call handling, WebRTC, and media pipelines"))
     (project "squeakwell"
       (relationship "sibling")
       (description "Database recovery via constraint propagation"))
     (project "proven"
       (relationship "dependency")
-      (description "Shared Idris2 verified library"))
+      (description "Shared Idris2 verified library — provides foundational proofs"))
     (project "typell"
       (relationship "dependency")
-      (description "Type theory engine"))))
+      (description "Type theory engine — powers type-level supervision tree analysis"))
+    (project "panll"
+      (relationship "integration")
+      (description "Panel framework — supervision tree visualisation panel"))
+    (project "boj-server"
+      (relationship "integration")
+      (description "BoJ cartridge for OTP scaffolding generation"))))

.machine_readable/6a2/META.a2ml

@@ -4,38 +4,53 @@
 
 (meta
   (version "0.1.0")
-  (last-updated "2026-03-20")
+  (last-updated "2026-03-21")
 
   (architecture-decisions
     (adr "001-iser-pattern"
       (status "accepted")
-      (context "Need to make powerful languages accessible without steep learning curves")
-      (decision "Use manifest-driven code generation: user describes WHAT, tool generates HOW")
-      (consequences "Users write zero target language code; all complexity in the -iser"))
+      (context "OTP supervision trees are powerful but hard to learn correctly")
+      (decision "Manifest-driven code generation: user describes services, otpiser generates the supervision tree")
+      (consequences "Users write zero Elixir code; all OTP complexity is handled by the -iser"))
 
     (adr "002-abi-ffi-standard"
       (status "accepted")
-      (context "Need verified interop between Rust CLI, target language, and user code")
-      (decision "Idris2 ABI for formal proofs, Zig FFI for C-ABI bridge")
-      (consequences "Compile-time correctness guarantees; zero runtime overhead from proofs"))
+      (context "Need verified interop between Rust CLI, Elixir/BEAM runtime, and NIF bridge")
+      (decision "Idris2 ABI for formal proofs of tree correctness, Zig FFI for C-ABI NIF bridge")
+      (consequences "Compile-time guarantees that supervision trees are well-formed; zero runtime overhead"))
 
-    (adr "003-rsr-template"
+    (adr "003-strategy-selection"
+      (status "accepted")
+      (context "Choosing the right supervision strategy is the hardest part of OTP design")
+      (decision "Automatic strategy selection from service dependency analysis: independent → one_for_one, coupled → one_for_all, ordered → rest_for_one")
+      (consequences "Users describe relationships; otpiser computes optimal strategies"))
+
+    (adr "004-restart-intensity"
+      (status "accepted")
+      (context "Incorrect max_restarts/max_seconds causes restart storms or premature shutdown")
+      (decision "Compute restart intensity from SLA definitions: high-availability services get aggressive budgets, best-effort services get conservative ones")
+      (consequences "Self-tuning fault tolerance without manual parameter guessing"))
+
+    (adr "005-rsr-template"
       (status "accepted")
       (context "Need consistent project structure across 29+ -iser repos")
       (decision "All repos cloned from rsr-template-repo with full CI/CD and governance")
       (consequences "17 workflows, SECURITY.md, CONTRIBUTING, bot directives from day one")))
 
   (development-practices
-    (language "Rust" (purpose "CLI and orchestration"))
-    (language "Idris2" (purpose "ABI formal proofs"))
-    (language "Zig" (purpose "FFI C-ABI bridge"))
+    (language "Rust" (purpose "CLI orchestration and manifest parsing"))
+    (language "Idris2" (purpose "ABI formal proofs for supervision tree invariants"))
+    (language "Zig" (purpose "FFI C-ABI bridge for Erlang NIF generation"))
+    (language "Elixir" (purpose "Target language — generated code"))
     (build-tool "cargo")
     (ci "GitHub Actions (17 workflows)"))
 
   (design-rationale
     (principle "Manifest-driven"
-      (explanation "User intent captured in TOML; all generation is deterministic and reproducible"))
+      (explanation "User intent captured in otpiser.toml; supervision tree generation is deterministic and reproducible"))
     (principle "Formally verified bridges"
-      (explanation "Idris2 dependent types prove interface correctness at compile time"))
+      (explanation "Idris2 dependent types prove supervision tree well-formedness at compile time"))
     (principle "Zero target language exposure"
-      (explanation "Users never write Chapel/Julia/Futhark/etc. — the -iser handles everything"))))
+      (explanation "Users never write Elixir/Erlang — otpiser generates everything including Application, Supervisor, GenServer, tests, and mix.exs"))
+    (principle "Let it crash, correctly"
+      (explanation "OTP's 'let it crash' philosophy is correct but easy to misconfigure — otpiser ensures the crash recovery strategy matches service semantics"))))

.machine_readable/6a2/NEUROSYM.a2ml

@@ -6,7 +6,7 @@
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [hypatia-config]
 scan-enabled = true

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -6,7 +6,7 @@
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [deployment]
 # method = "gitops"  # gitops | manual | ci-triggered

.machine_readable/6a2/STATE.a2ml

@@ -5,31 +5,38 @@
 (state
   (metadata
     (version "0.1.0")
-    (last-updated "2026-03-20")
+    (last-updated "2026-03-21")
     (author "Jonathan D.A. Jewell"))
 
   (project-context
     (name "otpiser")
-    (description "Generate OTP supervision trees and fault-tolerance scaffolding")
-    (status "scaffold")
+    (description "Generate OTP supervision trees, GenServers, GenStateMachines, and fault-tolerance scaffolding from service descriptions")
+    (status "scaffold-documented")
     (priority "—")
     (ecosystem "-iser family (https://github.com/hyperpolymath/iseriser)"))
 
   (current-position
-    (phase "initial-scaffold")
-    (completion-percentage 5)
-    (milestone "Architecture defined, CLI scaffolded, RSR template complete"))
+    (phase "scaffold-documented")
+    (completion-percentage 10)
+    (milestone "Architecture defined, CLI scaffolded, ABI/FFI bespoke for OTP, full documentation"))
 
   (route-to-mvp
-    (step 1 "Replace codegen stubs with target-language-specific generation")
-    (step 2 "Implement Idris2 ABI proofs for core invariants")
-    (step 3 "Build Zig FFI bridge")
-    (step 4 "Integration tests with real-world examples")
-    (step 5 "Documentation and examples"))
+    (step 1 "Implement manifest parser for OTP-specific fields (services, strategies, SLAs)")
+    (step 2 "Build dependency graph from service descriptions")
+    (step 3 "Implement strategy selection engine (one_for_one, one_for_all, rest_for_one)")
+    (step 4 "Implement restart intensity calculator from SLA definitions")
+    (step 5 "Generate Elixir Application and Supervisor modules")
+    (step 6 "Generate GenServer modules with typed callbacks")
+    (step 7 "Generate DynamicSupervisor and Registry modules")
+    (step 8 "Generate mix.exs, config, and ExUnit tests")
+    (step 9 "First working end-to-end example (payment gateway)")
+    (step 10 "Idris2 ABI proofs for tree correctness invariants")
+    (step 11 "Zig FFI NIF bridge for performance-critical paths"))
 
   (blockers-and-issues
-    (none "Project is in scaffold phase — no blockers yet"))
+    (none "Project is in documented scaffold phase — no blockers yet"))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Expand otpiser.toml manifest schema with service/supervisor/SLA sections")
+    (action "Implement supervision tree topology computation from dependency graph")
+    (action "Write first working example: single-service one_for_one supervision")))

0-AI-MANIFEST.a2ml

@@ -4,7 +4,7 @@
 
 ## WHAT IS THIS?
 
-This is the AI manifest for **[YOUR-REPO-NAME]**. It declares:
+This is the AI manifest for **otpiser**. It declares:
 - Canonical file locations (where things MUST be, and nowhere else)
 - Critical invariants (rules that must NEVER be violated)
 - Repository structure and organization
@@ -86,7 +86,7 @@ Policy enforcement contracts (k9, dust, lust, must, trust).
 This repo follows the **Dual-Track** architecture:
 
 ```
-[YOUR-REPO-NAME]/
+otpiser/
 ├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
 ├── README.adoc                 # High-level orientation (Rich Human)
 ├── ROADMAP.adoc                # Future direction

README.adoc

@@ -7,42 +7,124 @@ Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 
 == What Is This?
 
-OTPiser generates **OTP supervision trees, GenServers, and fault-tolerance
-scaffolding** from service descriptions — bringing Erlang/BEAM reliability
-to any service architecture.
+OTPiser generates **OTP supervision trees, GenServers, GenStateMachines, and
+fault-tolerance scaffolding** from service descriptions -- bringing Erlang/BEAM
+reliability to any service architecture.
 
-The "let it crash" supervision tree model is genuinely superior for
-reliability, but OTP patterns are hard to learn. OTPiser eliminates the cliff.
+The "let it crash" supervision tree model is genuinely superior for reliability,
+but OTP patterns are notoriously hard to learn correctly. Supervision strategy
+selection, restart intensity tuning, child spec ordering, and process linking
+are all sources of subtle production bugs. OTPiser eliminates the cliff.
 
 == How It Works
 
 Describe your services in `otpiser.toml`. OTPiser:
 
-1. Generates Elixir/Erlang supervision trees with correct restart strategies
-2. Creates GenServer modules for each service component
-3. Wires up health checks, circuit breakers, and backpressure
-4. Generates NIFs (via Zig FFI) for performance-critical paths
+1. Parses your service architecture into a dependency graph
+2. Generates an Elixir supervision tree with correct restart strategies
+   (`one_for_one`, `one_for_all`, `rest_for_one`)
+3. Creates GenServer modules for stateful service components
+4. Creates GenStateMachine modules for state-machine workflows
+5. Wires up `max_restarts`, `max_seconds`, and child spec ordering
+6. Generates health checks, circuit breakers, and backpressure mechanisms
+7. Emits NIFs (via Zig FFI) for performance-critical hot paths
 
-== Key Value
+== OTP Concepts Generated
 
-* **9-nines reliability patterns** without learning OTP
-* **Supervision trees generated from service descriptions**
-* **"Let it crash" philosophy** — services self-heal automatically
+=== Supervision Strategies
+
+[cols="1,3"]
+|===
+| Strategy | When OTPiser uses it
+
+| `one_for_one`
+| Independent services -- restarting one does not affect siblings
+
+| `one_for_all`
+| Tightly coupled service groups -- if one fails, restart the whole group
+
+| `rest_for_one`
+| Ordered dependency chains -- restart the failed process and everything started after it
+|===
+
+=== Generated Modules
+
+* **Application** -- top-level OTP application with `start/2` callback
+* **Root Supervisor** -- entry supervisor with configurable strategy
+* **Service Supervisors** -- per-service-group supervisors (nested trees)
+* **GenServer workers** -- stateful services with `init/1`, `handle_call/3`, `handle_cast/2`, `handle_info/2`
+* **GenStateMachine workers** -- state-machine processes with typed state transitions
+* **DynamicSupervisor** -- for services that spawn workers on demand (connection pools, consumers)
+* **Registry** -- named process registry for service discovery
+* **Task.Supervisor** -- for fire-and-forget or awaited async work
+
+=== Restart Intensity
+
+OTPiser computes safe `max_restarts` / `max_seconds` values from your service
+SLA definitions. High-availability services get aggressive restart budgets;
+best-effort services get conservative ones to avoid restart storms.
+
+== Use Cases
+
+* **Microservice resilience** -- describe your service mesh, get a battle-tested supervision tree
+* **Message queue consumers** -- GenStage/Broadway pipelines with backpressure and consumer groups
+* **Connection pool management** -- DynamicSupervisor pools with health-checked workers
+* **Distributed system orchestration** -- multi-node process groups with `:pg` and `:net_kernel`
+* **IoT device management** -- per-device GenServers under a DynamicSupervisor
+* **WebSocket/long-lived connections** -- supervised connection handlers with clean shutdown
 
 == Architecture
 
 Follows the hyperpolymath -iser pattern (same as https://github.com/hyperpolymath/chapeliser[Chapeliser]):
 
-* **Manifest** (`otpiser.toml`) — describe WHAT you want
-* **Idris2 ABI** (`src/abi/`) — formal proofs of interface correctness
-* **Zig FFI** (`ffi/zig/`) — C-ABI bridge to target language runtime
-* **Codegen** (`src/codegen/`) — generates target language wrapper code
-* **Rust CLI** — parses manifest, validates, generates, builds, runs
+* **Manifest** (`otpiser.toml`) -- describe WHAT you want
+* **Idris2 ABI** (`src/interface/abi/`) -- formal proofs of supervision tree correctness
+* **Zig FFI** (`src/interface/ffi/`) -- C-ABI bridge for NIF generation
+* **Codegen** (`src/codegen/`) -- generates Elixir modules, mix.exs, config, and tests
+* **Rust CLI** -- parses manifest, validates, generates, builds, runs
 
-User writes zero target language code. Otpiser generates everything.
+User writes zero Elixir code. OTPiser generates everything.
 
 Part of the https://github.com/hyperpolymath/iseriser[-iser family] of acceleration frameworks.
 
+== Quick Start
+
+[source,bash]
+----
+# Initialise a new otpiser manifest
+otpiser init
+
+# Edit otpiser.toml to describe your services
+# Then generate the supervision tree
+otpiser generate
+
+# Validate the manifest before generation
+otpiser validate
+
+# Build the generated Elixir project
+otpiser build
+
+# Show manifest info
+otpiser info
+----
+
+== Example Manifest
+
+[source,toml]
+----
+[workload]
+name = "payment-gateway"
+entry = "PaymentGateway.Application"
+strategy = "one_for_one"
+
+[data]
+input-type = "PaymentRequest"
+output-type = "PaymentResult"
+
+[options]
+flags = ["distributed", "health-checks"]
+----
+
 == Status
 
 **Pre-alpha.** Architecture defined, scaffolding in place, codegen pending.