docs: replace template placeholders with bespoke Nim metaprogramming content

All files now contain nimiser-specific documentation and type definitions
rather than generic {{PROJECT}} placeholders:

- README.adoc: Nim template/macro/generic pipeline, pragma-driven C export
- ROADMAP.adoc: Phase 0-6 with Nim-specific milestones
- TOPOLOGY.md: Module dependency graph and data flow
- Idris2 ABI: NimTemplate, NimMacro, CompileTimeAST, CBackend, NimObject,
  NimGeneric types with Nim calling conventions and layout proofs
- Layout.idr: Nim object layout rules ({.packed.}, {.exportc.}, {.align.})
- Foreign.idr: nimiser_compile, nimiser_gen_template, nimiser_gen_macro,
  nimiser_dump_ast, nimiser_nim_available FFI declarations
- Zig FFI: All nimiser_* function implementations with Nim-specific types
- Integration tests: Template/macro generation, Nim compiler detection
- Machine-readable 6a2: Bespoke STATE, META, ECOSYSTEM, AGENTIC, NEUROSYM,
  PLAYBOOK with Nim metaprogramming context
- 0-AI-MANIFEST.a2ml: Nimiser-specific 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
+# AGENTIC.a2ml — AI agent constraints and capabilities for nimiser
 # 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 expose Nim GC internals through the C ABI
+# - Never generate Nim code with {.importc.} unless importing from user's existing C code
+# - Never use Nim's `cast` or `unsafeAddr` in generated code
+
+[nimiser-specific]
+# Nim codegen rules:
+# - All exported procs MUST have {.exportc, cdecl.} pragmas
+# - All exported types MUST have {.exportc.} pragma
+# - Use --gc:arc or --gc:orc for deterministic memory management
+# - Never generate code using Nim's default GC (refc) for library output
+# - Generated headers must be self-contained (no Nim runtime dependencies)
 
 [maintenance-integrity]
 fail-closed = true

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -6,13 +6,14 @@
   (version "0.1.0")
   (name "nimiser")
   (type "tool")
-  (purpose "Generate high-performance C libraries via Nim metaprogramming")
+  (purpose "Generate high-performance C libraries via Nim metaprogramming (templates, macros, generics -> optimised C)")
 
   (position-in-ecosystem
     (family "-iser acceleration frameworks")
     (meta-framework "iseriser")
     (relationship "sibling")
-    (top-3 ("typedqliser" "chapeliser" "verisimiser")))
+    (top-3 ("typedqliser" "chapeliser" "verisimiser"))
+    (unique-value "Nim's compile-time metaprogramming produces zero-overhead C libraries from high-level descriptions — templates for generic abstractions, macros for AST transforms, generics for type specialisation"))
 
   (related-projects
     (project "iseriser"
@@ -35,4 +36,7 @@
       (description "Shared Idris2 verified library"))
     (project "typell"
       (relationship "dependency")
-      (description "Type theory engine"))))
+      (description "Type theory engine"))
+    (project "nim-lang"
+      (relationship "upstream-dependency")
+      (description "Andreas Rumpf's Nim compiler — the target language whose metaprogramming nimiser exploits"))))

.machine_readable/6a2/META.a2ml

@@ -4,38 +4,55 @@
 
 (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 "Need to make Nim's powerful metaprogramming accessible without requiring users to learn Nim")
+      (decision "Use manifest-driven code generation: user describes library interface in nimiser.toml, tool generates Nim templates/macros/generics that compile to optimised C")
+      (consequences "Users write zero Nim code; all complexity in nimiser's codegen pipeline"))
 
     (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, Nim-generated C library, and Zig FFI bridge")
+      (decision "Idris2 ABI for formal proofs (NimTemplate, NimMacro, CompileTimeAST, CBackend types), Zig FFI for C-ABI bridge (nimiser_* functions)")
+      (consequences "Compile-time correctness guarantees for the Nim-to-C ABI; zero runtime overhead from proofs"))
 
-    (adr "003-rsr-template"
+    (adr "003-nim-metaprogramming-pipeline"
+      (status "accepted")
+      (context "Nim offers three compile-time metaprogramming mechanisms: templates, macros, and generics")
+      (decision "Generate all three: templates for zero-cost abstractions, macros for AST-level transforms (loop unrolling, pragma injection), generics for monomorphised specialisation")
+      (consequences "Maximum optimisation through compile-time code specialisation; output C code is as fast as hand-written"))
+
+    (adr "004-nim-c-backend"
+      (status "accepted")
+      (context "Nim can compile to C, C++, Objective-C, or JavaScript")
+      (decision "Primary target is C backend (nim c --app:lib), with C++ and JS as secondary backends selectable via manifest")
+      (consequences "Generated libraries are portable C with clean headers; no Nim runtime dependency in the output"))
+
+    (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"))
-    (build-tool "cargo")
+    (language "Rust" (purpose "CLI orchestration, manifest parsing, codegen pipeline"))
+    (language "Nim" (purpose "Generated target — templates, macros, generics compiled to C"))
+    (language "Idris2" (purpose "ABI formal proofs for Nim type/layout/calling-convention correctness"))
+    (language "Zig" (purpose "FFI C-ABI bridge between Rust CLI and Nim-generated libraries"))
+    (build-tool "cargo" (purpose "Rust CLI"))
+    (build-tool "nim c" (purpose "Nim -> C compilation of generated code"))
+    (build-tool "zig build" (purpose "Zig FFI layer"))
     (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 "Nim templates for zero-cost abstractions"
+      (explanation "Templates expand inline at compile time with no function-call overhead; ideal for buffer management, type adapters, and calling convention wrappers"))
+    (principle "Nim macros for AST-level optimisation"
+      (explanation "Macros rewrite the Nim AST before compilation, enabling loop unrolling, dead code elimination, and automatic {.exportc.} pragma injection"))
+    (principle "Nim generics for type specialisation"
+      (explanation "Generics are monomorphised at compile time, producing specialised code for each concrete type without runtime dispatch"))
+    (principle "Formally verified C ABI"
+      (explanation "Idris2 dependent types prove that generated Nim {.exportc.} structs match C struct layout expectations across platforms"))))

.machine_readable/6a2/NEUROSYM.a2ml

@@ -1,21 +1,24 @@
 # 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 nimiser
 # 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 nimiser:
 # - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+# - { name = "no-nim-cast", pattern = "cast\\[", severity = "warning", context = "generated Nim code" }
+# - { name = "exportc-required", pattern = "proc.*\\*.*=", severity = "info", context = "exported procs must have {.exportc.}" }
+# - { name = "no-refc-gc", pattern = "--gc:refc", severity = "critical", context = "library output must use arc/orc" }
 
 [neural-config]
 # Neural pattern detection settings

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -1,25 +1,34 @@
 # 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 nimiser
 # 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 = "ci-triggered"
+target = "binary"  # Rust CLI binary + generated Nim C libraries
+
+[nim-compilation]
+# The nimiser pipeline:
+# 1. Rust CLI parses nimiser.toml manifest
+# 2. Codegen emits Nim source (templates, macros, generics)
+# 3. Nim compiler (nim c --app:lib --gc:arc) produces C library
+# 4. Zig FFI bridge links to the C library
+# 5. Output: .a/.so + .h ready for consumption
 
 [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
+# 5. If Nim compilation fails: check `nim --version`, verify PATH
 
 [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
@@ -33,3 +42,5 @@ last-updated = "{{CURRENT_DATE}}"
 #   just maint-hard-pass
 # Permission audit:
 #   just perms-audit
+# Nim compiler check:
+#   nim --version

.machine_readable/6a2/STATE.a2ml

@@ -5,31 +5,33 @@
 (state
   (metadata
     (version "0.1.0")
-    (last-updated "2026-03-20")
+    (last-updated "2026-03-21")
     (author "Jonathan D.A. Jewell"))
 
   (project-context
     (name "nimiser")
-    (description "Generate high-performance C libraries via Nim metaprogramming")
+    (description "Generate high-performance C libraries via Nim metaprogramming (templates, macros, generics)")
     (status "scaffold")
     (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-complete")
+    (completion-percentage 10)
+    (milestone "Architecture defined, CLI scaffolded, Idris2 ABI types bespoke (NimTemplate, NimMacro, CompileTimeAST, CBackend), Zig FFI bridge stubbed with nimiser_* functions, RSR template 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 Nim template generation: parse nimiser.toml -> emit Nim template source with {.exportc.} pragmas")
+    (step 2 "Implement Nim macro generation: AST-level transforms for loop unrolling and specialisation")
+    (step 3 "Implement Nim generic generation: monomorphised type-safe wrappers")
+    (step 4 "Invoke Nim compiler: nim c --app:lib to produce .a/.so + .h from generated source")
+    (step 5 "Wire Zig FFI bridge to call Nim-generated C library functions")
+    (step 6 "End-to-end integration test: nimiser.toml -> Nim -> C library -> Zig -> consumer"))
 
   (blockers-and-issues
-    (none "Project is in scaffold phase — no blockers yet"))
+    (none "Project is in scaffold phase — Idris2 ABI and Zig FFI stubs complete, codegen implementation pending"))
 
   (critical-next-actions
-    (action "Implement codegen for primary use case")
-    (action "Write first working example end-to-end")))
+    (action "Implement src/codegen/mod.rs to emit Nim template/macro/generic source code")
+    (action "Write first nimiser.toml example that generates a working C buffer library")
+    (action "Add Nim compiler detection and invocation in the Zig FFI layer")))

0-AI-MANIFEST.a2ml

@@ -1,14 +1,21 @@
-# ⚠️ STOP - CRITICAL READING REQUIRED
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+
+# STOP - CRITICAL READING REQUIRED
 
 **THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**
 
 ## WHAT IS THIS?
 
-This is the AI manifest for **[YOUR-REPO-NAME]**. It declares:
+This is the AI manifest for **nimiser**. It declares:
 - Canonical file locations (where things MUST be, and nowhere else)
 - Critical invariants (rules that must NEVER be violated)
 - Repository structure and organization
 
+Nimiser generates **high-performance C libraries** from high-level interface
+descriptions using Nim's compile-time metaprogramming system (templates,
+macros, generics). The user writes zero Nim code.
+
 ## CANONICAL LOCATIONS (UNIVERSAL RULE)
 
 ### Machine-Readable Metadata: `.machine_readable/` ONLY
@@ -80,42 +87,44 @@ Policy enforcement contracts (k9, dust, lust, must, trust).
 6. **Container images** - MUST use Chainguard base (`cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`)
 7. **Container runtime** - Podman, never Docker. Files are `Containerfile`, never `Dockerfile`
 8. **Container orchestration** - `selur-compose`, never `docker-compose`
+9. **Nim-specific** - Generated Nim code uses `{.exportc.}` for C ABI; never expose Nim GC internals
 
 ## REPOSITORY STRUCTURE
 
 This repo follows the **Dual-Track** architecture:
 
 ```
-[YOUR-REPO-NAME]/
+nimiser/
 ├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
-├── README.adoc                 # High-level orientation (Rich Human)
-├── ROADMAP.adoc                # Future direction
+├── README.adoc                 # Nim metaprogramming pipeline overview
+├── ROADMAP.adoc                # Phase 0-6 with Nim-specific milestones
+├── TOPOLOGY.md                 # Module dependency graph
 ├── CONTRIBUTING.adoc           # Human contribution guide
-├── GOVERNANCE.adoc             # Decision-making model
 ├── Justfile                    # Task runner
+├── Cargo.toml                  # Rust CLI build
 ├── Containerfile               # OCI build
-├── LICENSE                     # Primary license
+├── LICENSE                     # PMPL-1.0-or-later
 ├── src/                        # Source code
+│   ├── main.rs                 # CLI entry point
+│   ├── lib.rs                  # Library API
+│   ├── manifest/               # nimiser.toml parser
+│   ├── codegen/                # Nim template/macro/generic generation
+│   ├── abi/                    # Rust-side ABI types
 │   └── interface/              # Verified Interface Seams
-│       ├── abi/                # Idris2 ABI (The Spec)
-│       ├── ffi/                # Zig FFI (The Bridge)
-│       └── generated/          # C Headers (The Result)
+│       ├── abi/                # Idris2 ABI (NimTemplate, NimMacro, CompileTimeAST, CBackend)
+│       ├── ffi/                # Zig FFI (nimiser_* C functions)
+│       └── generated/          # C Headers (auto-generated)
 ├── container/                  # Stapeln container ecosystem
-├── docs/                       # Technical depths
-│   ├── attribution/            # Citations, owners, maintainers (adoc)
-│   ├── architecture/           # Topology, diagrams
-│   ├── theory/                 # Domain theory
-│   └── practice/               # Manuals
-├── docs/legal/                  # Legal exhibits and full texts
+├── docs/                       # Technical documentation
 └── .machine_readable/          # ALL machine-readable metadata
 ```
 
 ## SESSION STARTUP CHECKLIST
 
-✅ Read THIS file (0-AI-MANIFEST.a2ml) first
-✅ Understand canonical location: `.machine_readable/`
-✅ State understanding of canonical locations
+Read THIS file (0-AI-MANIFEST.a2ml) first
+Understand canonical location: `.machine_readable/`
+State understanding of canonical locations
 
 ## ATTESTATION PROOF
 
-**"I have read the AI manifest. All machine-readable content (state files, anchors, policies, bot directives, contractiles, AI guides) is located in `.machine_readable/` ONLY, and community metadata is in `.github/`. I will not create duplicate files in the root directory."**
+**"I have read the AI manifest for nimiser. All machine-readable content (state files, anchors, policies, bot directives, contractiles, AI guides) is located in `.machine_readable/` ONLY, and community metadata is in `.github/`. I will not create duplicate files in the root directory."**