docs: bespoke documentation for mylangiser progressive-disclosure generator

Replace all template placeholders and generic content with mylangiser-specific
documentation covering API surface analysis, complexity scoring, disclosure
levels (@beginner/@intermediate/@expert), smart default inference, and
layered wrapper generation.

Files updated:
- README.adoc: full architecture, My-Lang specifics, use cases
- ROADMAP.adoc: Phase 0-6 from scaffold through ecosystem
- TOPOLOGY.md: module map, data flow, scoring formula, invariants
- Idris2 ABI: DisclosureLevel, ComplexityScore, APIEndpoint, LayeredWrapper,
  SmartDefault types; APISurfaceDescriptor/EndpointDescriptor/WrapperDescriptor
  layouts; analysis/scoring/generation FFI declarations
- Zig FFI: domain-specific Handle with endpoints/wrappers, scoring algorithm,
  layer generation logic, all tests updated
- 0-AI-MANIFEST.a2ml: domain concepts, repo structure, session checklist
- .machine_readable/6a2/*: STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK
- .machine_readable/anchors/ANCHOR.a2ml: semantic authority for disclosure levels
- .machine_readable/ai/AI.a2ml: domain rules and key files

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

Author: hyperpolymath

.machine_readable/6a2/AGENTIC.a2ml

@@ -1,12 +1,12 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# AGENTIC.a2ml — AI agent constraints and capabilities
+# AGENTIC.a2ml — AI agent constraints and capabilities for mylangiser
 # Defines what AI agents can and cannot do in this repository.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [agent-permissions]
 can-edit-source = true
@@ -22,6 +22,17 @@ can-create-files = true
 # - Never use banned languages (TypeScript, Python, Go, etc.)
 # - Never place state files in repository root (must be in .machine_readable/)
 # - Never use AGPL license (use PMPL-1.0-or-later)
+# - Never break disclosure-level ordering (@beginner < @intermediate < @expert)
+# - Never generate smart defaults that violate type constraints
+# - Never remove existing Idris2 proofs without replacement
+
+[domain-constraints]
+# mylangiser-specific rules:
+# - DisclosureLevel ordering is invariant: Beginner < Intermediate < Expert
+# - ComplexityScore is bounded 0-100; never exceed
+# - Layered wrappers must have monotonically non-decreasing parameter counts
+# - Smart defaults must be provably type-safe (Idris2 proof required)
+# - API surface analysis must be deterministic and reproducible
 
 [maintenance-integrity]
 fail-closed = true

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -6,13 +6,14 @@
   (version "0.1.0")
   (name "mylangiser")
   (type "tool")
-  (purpose "Generate progressive-disclosure interfaces via My-Lang")
+  (purpose "Analyse complex API surfaces and generate progressive-disclosure wrappers with @beginner/@intermediate/@expert levels via My-Lang")
 
   (position-in-ecosystem
     (family "-iser acceleration frameworks")
     (meta-framework "iseriser")
     (relationship "sibling")
-    (top-3 ("typedqliser" "chapeliser" "verisimiser")))
+    (top-3 ("typedqliser" "chapeliser" "verisimiser"))
+    (unique-value "Only -iser focused on API usability and progressive disclosure; all others target specific compute domains"))
 
   (related-projects
     (project "iseriser"
@@ -32,7 +33,10 @@
       (description "Database recovery via constraint propagation"))
     (project "proven"
       (relationship "dependency")
-      (description "Shared Idris2 verified library"))
+      (description "Shared Idris2 verified library — may share disclosure-level proofs"))
     (project "typell"
       (relationship "dependency")
-      (description "Type theory engine"))))
+      (description "Type theory engine — complexity scoring may leverage type analysis"))
+    (project "nextgen-languages"
+      (relationship "upstream")
+      (description "My-Lang language definition lives here; mylangiser consumes its spec"))))

.machine_readable/6a2/META.a2ml

@@ -4,38 +4,52 @@
 
 (meta
   (version "0.1.0")
-  (last-updated "2026-03-20")
+  (last-updated "2026-03-21")
 
   (architecture-decisions
-    (adr "001-iser-pattern"
+    (adr "001-progressive-disclosure"
       (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 "Complex APIs have steep learning curves; users must learn everything before they can do anything")
+      (decision "Generate three disclosure tiers (@beginner, @intermediate, @expert) where each is a strict superset of the previous")
+      (consequences "Users start simple, grow into power features; layer correctness verified by Idris2 proofs"))
 
-    (adr "002-abi-ffi-standard"
+    (adr "002-complexity-scoring"
       (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")
+      (context "Need an automated way to decide which endpoints belong at which disclosure level")
+      (decision "Compute a cognitive-load score (0-100) per endpoint based on parameter count, type depth, and error surface")
+      (consequences "Deterministic, reproducible tier assignment; configurable thresholds in mylangiser.toml"))
+
+    (adr "003-smart-defaults"
+      (status "accepted")
+      (context "@beginner wrappers need fewer parameters, so hidden parameters need safe values")
+      (decision "Infer defaults from type constraints (enum first variant, numeric lower bound), API docs, or user overrides")
+      (consequences "Beginner code works out of the box; defaults are provably type-safe via Idris2"))
+
+    (adr "004-abi-ffi-standard"
+      (status "accepted")
+      (context "Need verified interop between Rust CLI, Zig runtime, and generated My-Lang code")
+      (decision "Idris2 ABI for formal proofs (DisclosureLevel, ComplexityScore, LayeredWrapper), Zig FFI for C-ABI bridge")
       (consequences "Compile-time correctness guarantees; zero runtime overhead from proofs"))
 
-    (adr "003-rsr-template"
+    (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, manifest parsing, codegen pipeline"))
+    (language "Idris2" (purpose "ABI formal proofs: layer subset correctness, smart-default safety, layout verification"))
+    (language "Zig" (purpose "FFI C-ABI bridge: API analysis runtime, complexity scoring, layer generation"))
     (build-tool "cargo")
     (ci "GitHub Actions (17 workflows)"))
 
   (design-rationale
+    (principle "Progressive disclosure"
+      (explanation "Every API should teach itself — users see only what they need, and can peel back layers as they grow"))
+    (principle "Formally verified layers"
+      (explanation "Idris2 dependent types prove that @beginner is a subset of @intermediate, which is a subset of @expert"))
+    (principle "Smart defaults are type-safe"
+      (explanation "Inferred defaults are validated against type constraints; Idris2 proves they cannot violate invariants"))
     (principle "Manifest-driven"
-      (explanation "User intent captured in TOML; all generation is deterministic and reproducible"))
-    (principle "Formally verified bridges"
-      (explanation "Idris2 dependent types prove interface correctness at compile time"))
-    (principle "Zero target language exposure"
-      (explanation "Users never write Chapel/Julia/Futhark/etc. — the -iser handles everything"))))
+      (explanation "User intent captured in mylangiser.toml; all generation is deterministic and reproducible"))))

.machine_readable/6a2/NEUROSYM.a2ml

@@ -1,23 +1,30 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# NEUROSYM.a2ml — Neurosymbolic integration metadata
+# NEUROSYM.a2ml — Neurosymbolic integration metadata for mylangiser
 # Configuration for Hypatia scanning and symbolic reasoning.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [hypatia-config]
 scan-enabled = true
 scan-depth = "standard"  # quick | standard | deep
 report-format = "logtalk"
 
 [symbolic-rules]
-# Custom symbolic rules for this project
-# - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+# Mylangiser-specific symbolic rules for Hypatia:
+# - Disclosure level ordering: @beginner < @intermediate < @expert (always)
+# - Complexity score bounds: 0 <= score <= 100
+# - Layer monotonicity: beginner_params <= intermediate_params <= expert_params
+# - Smart default safety: inferred defaults must satisfy type constraints
+# - No unsafe FFI patterns (believe_me, unsafeCoerce banned)
 
 [neural-config]
-# Neural pattern detection settings
+# Neural pattern detection for API surface analysis:
+# - Detect CRUD patterns in endpoint names
+# - Detect pagination patterns in parameter lists
+# - Detect auth/retry patterns for smart default inference
 # confidence-threshold = 0.85
 # model = "hypatia-v2"

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -1,35 +1,40 @@
 # SPDX-License-Identifier: PMPL-1.0-or-later
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# PLAYBOOK.a2ml — Operational playbook
+# PLAYBOOK.a2ml — Operational playbook for mylangiser
 # Runbooks, incident response, deployment procedures.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [deployment]
-# method = "gitops"  # gitops | manual | ci-triggered
-# target = "container"  # container | binary | library | wasm
+method = "gitops"
+target = "binary"  # Rust CLI binary + Zig shared library
+
+[build-pipeline]
+# 1. cargo build --release        (Rust CLI)
+# 2. cd src/interface/ffi && zig build  (Zig FFI library)
+# 3. cargo test                   (Rust unit tests)
+# 4. cd src/interface/ffi && zig build test  (Zig unit tests)
 
 [incident-response]
-# 1. Check .machine_readable/STATE.a2ml for current status
+# 1. Check .machine_readable/6a2/STATE.a2ml for current status
 # 2. Review recent commits and CI results
-# 3. Run `just validate` to check compliance
+# 3. Run `just validate` to check RSR compliance
 # 4. Run `just security` to audit for vulnerabilities
+# 5. For layer-generation bugs: check Idris2 proofs in src/interface/abi/
 
 [release-process]
-# 1. Update version in STATE.a2ml, META.a2ml, Justfile
+# 1. Update version in STATE.a2ml, META.a2ml, Cargo.toml, Justfile
 # 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass)
-# 3. Optional local permission hardening: `just perms-snapshot && just perms-lock`
-# 4. Tag and push
-# 5. Restore local permissions if needed: `just perms-restore`
+# 3. Verify Idris2 ABI proofs compile cleanly
+# 4. Run end-to-end test: mylangiser generate on example manifest
+# 5. Tag and push
 # 6. Run `just container-push` if applicable
 
 [maintenance-operations]
-# Baseline audit:
-#   just maint-audit
-# Hard release gate:
-#   just maint-hard-pass
-# Permission audit:
-#   just perms-audit
+# Baseline audit:    just maint-audit
+# Hard release gate: just maint-hard-pass
+# Permission audit:  just perms-audit
+# ABI verification:  cd src/interface/abi && idris2 --check Types.idr Layout.idr Foreign.idr

.machine_readable/6a2/STATE.a2ml

@@ -5,31 +5,34 @@
 (state
   (metadata
     (version "0.1.0")
-    (last-updated "2026-03-20")
+    (last-updated "2026-03-21")
     (author "Jonathan D.A. Jewell"))
 
   (project-context
     (name "mylangiser")
-    (description "Generate progressive-disclosure interfaces via My-Lang")
-    (status "scaffold")
+    (description "Analyse complex API surfaces and generate progressive-disclosure wrappers with beginner/intermediate/expert levels via My-Lang")
+    (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, RSR template complete, all docs bespoke, Idris2 ABI domain types defined, Zig FFI domain stubs implemented"))
 
   (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 API surface analysis: parse mylangiser.toml, build endpoint model")
+    (step 2 "Implement complexity scoring: cognitive-load formula, threshold configuration")
+    (step 3 "Implement My-Lang layer generation: @beginner/@intermediate/@expert codegen")
+    (step 4 "Implement smart default inference from type constraints and API docs")
+    (step 5 "Write Idris2 ABI proofs for layer subset correctness")
+    (step 6 "End-to-end test: real API manifest -> three-tier wrapper output")
+    (step 7 "Documentation, examples, ecosystem integration"))
 
   (blockers-and-issues
-    (none "Project is in scaffold phase — no blockers yet"))
+    (none "Project is in scaffold-documented phase — no blockers yet"))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Implement API surface analysis (parse manifest, classify parameters)")
+    (action "Implement complexity scoring algorithm")
+    (action "First working example: simple REST API -> layered wrapper")))

.machine_readable/ai/AI.a2ml

@@ -1,16 +1,48 @@
-
-# AI Assistant Instructions
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# AI.a2ml — AI assistant instructions for mylangiser
 
 ## Repository Focus
-- `rsr-template-repo` is treated as a Rhodium Standard Repository; obey the Rhodium policies and keep `.machine_readable/` authoritative.
-- All machine-readable content lives under `.machine_readable/` — state files (a2ml), bot directives, and contractiles.
-- Prefer to keep generated files out of source control, and regenerate them with the documented commands before committing.
+
+- **mylangiser** generates progressive-disclosure interfaces from complex APIs.
+- Three disclosure levels: @beginner (smart defaults, simplified), @intermediate
+  (full params, named args), @expert (raw API, escape hatches).
+- Core pipeline: manifest -> API analysis -> complexity scoring -> Idris2 ABI
+  proofs -> My-Lang codegen -> layered wrapper.
+- All machine-readable content lives under `.machine_readable/` -- state files
+  (a2ml), bot directives, and contractiles.
+
+## Domain Rules
+
+- **Disclosure ordering is invariant**: Beginner < Intermediate < Expert.
+  Never generate a wrapper where beginner exposes more than intermediate.
+- **Complexity scores are bounded 0-100**. Never exceed.
+- **Smart defaults must be type-safe**: if you add a default, verify it
+  satisfies the parameter's type constraints.
+- **Layer monotonicity**: beginner_params <= intermediate_params <= expert_params.
 
 ## Workflow
-1. Inspect `.machine_readable/STATE.a2ml` for blockers and next actions.
-2. Respect any constraints listed inside `.machine_readable/AGENTIC.a2ml` when tooling changes are requested.
-3. After finishing edits, update STATE with your outcomes and commit with a concise, imperative message.
+
+1. Inspect `.machine_readable/6a2/STATE.a2ml` for blockers and next actions.
+2. Respect constraints in `.machine_readable/6a2/AGENTIC.a2ml`.
+3. After finishing edits, update STATE with your outcomes and commit.
+
+## Key Files
+
+- `src/interface/abi/Types.idr` -- DisclosureLevel, ComplexityScore, APIEndpoint,
+  LayeredWrapper, SmartDefault
+- `src/interface/abi/Layout.idr` -- APISurfaceDescriptor, EndpointDescriptor,
+  WrapperDescriptor memory layouts
+- `src/interface/abi/Foreign.idr` -- FFI declarations for analysis, scoring,
+  layer generation
+- `src/interface/ffi/src/main.zig` -- FFI implementation
+- `src/main.rs` -- CLI entry point
+- `src/manifest/` -- mylangiser.toml parser
+- `src/codegen/` -- My-Lang layer generation
 
 ## Delivery Promises
-- Mention in summaries whether STATE, `.machine_readable/contractiles/`, or `.machine_readable/bot_directives/` changed.
-- Keep this file in sync with the repository's status; update it if the governance changes.
+
+- Mention in summaries whether STATE, `.machine_readable/contractiles/`, or
+  `.machine_readable/bot_directives/` changed.
+- Keep this file in sync with the repository's status.