docs: bespoke iseriser documentation — meta-framework identity, Idris2 ABI types, Zig FFI engine

Replace all template placeholders with iseriser-specific content:
- README.adoc: full architecture, generated artifacts table, 28-repo family, use cases
- ROADMAP.adoc: Phase 0-6 (scaffold through ecosystem integration, including self-hosting)
- TOPOLOGY.md: architectural topology with data flow and module structure
- Idris2 ABI: LanguageModel, TypeSystemFeature, CompilationTarget, IserTemplate,
  GeneratedArtifact types with formal proofs of generation completeness
- Layout.idr: LanguageModelData, TemplateData, GenerationContext struct layouts
- Foreign.idr: iseriser_* FFI declarations for generation pipeline
- Zig FFI: GenerationContext, language model loading, template expansion, repo generation
- Integration tests: full coverage of lifecycle, language model, templates, generation
- Machine-readable: STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM, PLAYBOOK, ANCHOR, AI.a2ml
- 0-AI-MANIFEST.a2ml: bespoke with iseriser repo structure and invariants

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
-# Defines what AI agents can and cannot do in this repository.
+# AGENTIC.a2ml — AI agent constraints and capabilities for iseriser
+# Iseriser is the meta-framework that generates new -iser projects.
 
 [metadata]
 version = "0.1.0"
-last-updated = "{{CURRENT_DATE}}"
+last-updated = "2026-03-21"
 
 [agent-permissions]
 can-edit-source = true
@@ -22,6 +22,8 @@ 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 hardcode per-language logic in templates — always derive from LanguageModel
+# - Never generate repos outside the canonical ~/Documents/hyperpolymath-repos/ location
 
 [maintenance-integrity]
 fail-closed = true

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -5,34 +5,47 @@
 (ecosystem
   (version "0.1.0")
   (name "iseriser")
-  (type "tool")
-  (purpose "Meta-framework that generates new -iser projects")
+  (type "meta-framework")
+  (purpose "Generates new -iser projects from language descriptions — the factory that makes all other -isers")
 
   (position-in-ecosystem
     (family "-iser acceleration frameworks")
-    (meta-framework "iseriser")
-    (relationship "sibling")
+    (role "meta-framework — generates all sibling -isers")
+    (generates-count 28)
+    (relationship "parent-generator")
     (top-3 ("typedqliser" "chapeliser" "verisimiser")))
 
   (related-projects
-    (project "iseriser"
-      (relationship "meta-framework")
-      (description "Generates new -iser project scaffolding"))
     (project "typedqliser"
-      (relationship "sibling-priority-1")
+      (relationship "generated-sibling-priority-1")
       (description "Formal type safety for any query language"))
     (project "chapeliser"
-      (relationship "sibling-priority-2")
+      (relationship "generated-sibling-priority-2")
       (description "Chapel distributed computing acceleration"))
     (project "verisimiser"
-      (relationship "sibling-priority-3")
+      (relationship "generated-sibling-priority-3")
       (description "VeriSimDB octad database augmentation"))
+    (project "julianiser"
+      (relationship "generated-sibling")
+      (description "Julia scientific computing acceleration"))
+    (project "futharkiser"
+      (relationship "generated-sibling")
+      (description "Futhark GPU computing acceleration"))
+    (project "idrisiser"
+      (relationship "generated-sibling")
+      (description "Idris2 formal verification acceleration"))
     (project "squeakwell"
-      (relationship "sibling")
+      (relationship "generated-sibling")
       (description "Database recovery via constraint propagation"))
     (project "proven"
       (relationship "dependency")
-      (description "Shared Idris2 verified library"))
+      (description "Shared Idris2 verified library for ABI proofs"))
     (project "typell"
       (relationship "dependency")
-      (description "Type theory engine"))))
+      (description "Type theory engine used in language model analysis"))
+    (project "rsr-template-repo"
+      (relationship "dependency")
+      (description "Source templates for generated RSR governance files"))
+    (project "nextgen-languages"
+      (relationship "upstream")
+      (description "Language ecosystem that iseriser scaffolds -isers for"))))

.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"
+    (adr "001-meta-framework"
       (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 "Need a factory to generate consistent -iser repos for each new language")
+      (decision "Iseriser takes a language description and scaffolds a complete -iser repo")
+      (consequences "Adding a new language to the ecosystem takes minutes not days; all -isers share identical structure"))
 
-    (adr "002-abi-ffi-standard"
+    (adr "002-language-model"
       (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 a structured representation of a target language's interop surface")
+      (decision "LanguageModel captures name, type system features, compilation target, primitives, calling convention")
+      (consequences "Template engine can make decisions based on language features (e.g., deeper ABI proofs for dependent types)"))
+
+    (adr "003-abi-ffi-standard"
+      (status "accepted")
+      (context "Need verified interop between Rust CLI, generation engine, and generated output")
+      (decision "Idris2 ABI for formal proofs of generation correctness, Zig FFI for C-ABI bridge")
       (consequences "Compile-time correctness guarantees; zero runtime overhead from proofs"))
 
-    (adr "003-rsr-template"
+    (adr "004-template-engine"
       (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")))
+      (context "Need a flexible template system for generating diverse file types")
+      (decision "Handlebars templates with language-model variables")
+      (consequences "Templates are readable and maintainable; language-specific logic via conditionals"))
+
+    (adr "005-self-hosting"
+      (status "proposed")
+      (context "Iseriser should be able to generate itself to prove completeness")
+      (decision "Phase 4 roadmap: iseriser generates iseriser, diff converges to zero")
+      (consequences "Ultimate validation that the template set is complete and correct")))
 
   (development-practices
     (language "Rust" (purpose "CLI and orchestration"))
-    (language "Idris2" (purpose "ABI formal proofs"))
-    (language "Zig" (purpose "FFI C-ABI bridge"))
+    (language "Idris2" (purpose "ABI formal proofs — LanguageModel, TypeSystemFeature, GeneratedArtifact types"))
+    (language "Zig" (purpose "FFI C-ABI generation engine"))
     (build-tool "cargo")
+    (template-engine "Handlebars (handlebars crate)")
     (ci "GitHub Actions (17 workflows)"))
 
   (design-rationale
-    (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"))))
+    (principle "Language-model-driven"
+      (explanation "All generation decisions flow from the language model — no hardcoded per-language logic in templates"))
+    (principle "Formally verified generation"
+      (explanation "Idris2 dependent types prove that templates expand to well-typed output and ABI layouts are consistent"))
+    (principle "Complete repo generation"
+      (explanation "Generated -isers include source, tests, CI/CD, documentation, and RSR governance — ready to cargo build from day one"))
+    (principle "Self-hosting as proof"
+      (explanation "If iseriser can generate itself, the template set is provably complete"))))

.machine_readable/6a2/NEUROSYM.a2ml

@@ -1,23 +1,27 @@
 # 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 iseriser
 # 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
+# Custom symbolic rules for iseriser:
+# - Verify generated Idris2 files have no unresolved {{placeholders}}
+# - Verify generated Zig files compile against declared ABI
+# - Verify generated Cargo.toml has correct dependencies for target language
 # - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+# - { name = "no-unresolved-templates", pattern = "\\{\\{[A-Z_]+\\}\\}", severity = "error" }
 
 [neural-config]
-# Neural pattern detection settings
+# Neural pattern detection settings for generated code quality
 # confidence-threshold = 0.85
 # model = "hypatia-v2"

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -1,35 +1,47 @@
 # 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
-# Runbooks, incident response, deployment procedures.
+# PLAYBOOK.a2ml — Operational playbook for iseriser
+# Runbooks, generation procedures, batch operations.
 
 [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 = "binary"  # iseriser ships as a Rust CLI binary
+# target = "binary"  # Primary: cargo install; secondary: container
+
+[generation-runbook]
+# How to generate a new -iser:
+# 1. Create iseriser.toml with target language description
+# 2. Run `iseriser validate -m iseriser.toml` to check the manifest
+# 3. Run `iseriser generate -m iseriser.toml -o ../new-language-iser/`
+# 4. cd into generated repo, run `cargo build` to verify
+# 5. Run `cargo test` to verify generated tests pass
+# 6. Customise codegen stubs for domain-specific logic
+
+[batch-regeneration]
+# To regenerate all 28 -iser repos from updated templates:
+# 1. Update templates in iseriser
+# 2. Run `iseriser batch-generate --manifest-dir manifests/ --output-dir ../`
+# 3. Review diffs in each generated repo
+# 4. Commit and push each repo
 
 [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
 # 4. Run `just security` to audit for vulnerabilities
 
 [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`
-# 6. Run `just container-push` if applicable
+# 3. Tag and push
+# 4. Publish to crates.io: `cargo publish`
 
 [maintenance-operations]
 # Baseline audit:
 #   just maint-audit
 # Hard release gate:
 #   just maint-hard-pass
-# Permission audit:
-#   just perms-audit

.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 "iseriser")
-    (description "Meta-framework that generates new -iser projects")
-    (status "scaffold")
-    (priority "—")
+    (description "Meta-framework that generates new -iser projects from language descriptions")
+    (status "codebase-in-progress")
+    (priority "critical — tooling foundation for all 28 -iser repos")
     (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 12)
+    (milestone "Architecture defined, CLI scaffolded, bespoke Idris2 ABI and Zig FFI written, TOPOLOGY and ROADMAP complete"))
 
   (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 LanguageDescription parser in manifest/mod.rs")
+    (step 2 "Build Handlebars template set for all generated artifact types")
+    (step 3 "Wire template engine to language model in codegen/mod.rs")
+    (step 4 "Write Idris2 ABI proofs for template expansion correctness")
+    (step 5 "End-to-end test: iseriser generates chapeliser, passes cargo test")
+    (step 6 "Self-hosting: iseriser generates iseriser")
+    (step 7 "Batch mode: regenerate all 28 -iser repos from updated templates"))
 
   (blockers-and-issues
     (none "Project is in scaffold phase — no blockers yet"))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Implement LanguageDescription struct and TOML parsing")
+    (action "Create Handlebars template files for Cargo.toml, main.rs, lib.rs")
+    (action "First end-to-end generation test")))

.machine_readable/ai/AI.a2ml

@@ -1,14 +1,23 @@
 
-# AI Assistant Instructions
+# AI Assistant Instructions for Iseriser
 
 ## Repository Focus
-- `rsr-template-repo` is treated as a Rhodium Standard Repository; obey the Rhodium policies and keep `.machine_readable/` authoritative.
+- **Iseriser** is the meta-framework that generates new -iser projects from language descriptions.
+- It is the most important -iser from a tooling perspective: it is the factory that makes all other -isers.
 - 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.
 
+## Key Architecture
+- **Manifest** (`iseriser.toml`): describes target language (name, type system features, compilation target, primitives)
+- **Language Model**: internal representation parsed from manifest
+- **Idris2 ABI** (`src/interface/abi/`): Types.idr (LanguageModel, TypeSystemFeature, etc.), Layout.idr (generation struct layouts), Foreign.idr (generation engine FFI)
+- **Zig FFI** (`src/interface/ffi/`): C-ABI generation engine (libiseriser)
+- **Template Engine**: Handlebars-based, expands language model into complete -iser repos
+- **Rust CLI** (`src/main.rs`): orchestrates init, validate, generate, build, run
+
 ## 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.
+1. Inspect `.machine_readable/6a2/STATE.a2ml` for blockers and next actions.
+2. Respect any constraints listed inside `.machine_readable/6a2/AGENTIC.a2ml`.
 3. After finishing edits, update STATE with your outcomes and commit with a concise, imperative message.
 
 ## Delivery Promises