docs+ffi: fill rsr-template placeholders left from template instantiation (#59)

The repo was scaffolded from rsr-template-repo but several files still
carried unfilled `{{project}}`, `{{PROJECT}}`, `{{BUILD_CMD}}`,
`{{TEST_CMD}}`, `{{LANG_STACK}}`, `{{MUST_INVARIANTS}}`, `{{PACKAGE_NAME}}`,
`{{DEPS}}`, and `{{BUILD_OUTPUT_PATH}}` placeholders. The repo's own
`.machine_readable/agent_instructions/methodology.a2ml` lists `{{PROJECT}}`
and `rsr-template-repo` in its `reject-if-contains` policy, so these were
also active policy violations.

Substitutions:

* `ABI-FFI-README.md`, `ffi/zig/build.zig`, `ffi/zig/test/integration_test.zig`
  — `{{project}}` → `valence_shell` (matches the symbol prefix already
  exported from `ffi/zig/src/main.zig`); `{{PROJECT}}` → `ValenceShell`
  (PascalCase Idris module path). Directory-tree root label fixed to the
  actual hyphenated repo name.

* `alkahest-shell-transmuter/*` — same substitutions but scoped to
  `alkahest` / `Alkahest` since that subtree is its own subproject.

* `QUICKSTART-DEV.adoc` — populated tech stack, build/test commands
  (cross-referenced against the top-level `Justfile` recipes), and
  inlined the key MUST invariants from `.machine_readable/MUST.contractile`
  rather than leaving a placeholder.

* `QUICKSTART-MAINTAINER.adoc` — populated runtime deps (glibc, optional
  Lean/Erlang runtimes), build output paths (`vsh` binary +
  `libvalence_shell.{so,a}` + generated header), and substituted
  `{{PACKAGE_NAME}}` → `valence-shell` throughout install/config paths.

Also:

* Removed `tests/fuzz/placeholder.txt`, a scorecard placeholder inherited
  from rsr-template-repo. Real fuzz infra lives at
  `impl/rust-cli/fuzz/fuzz_targets/` (cargo-fuzz) and `.clusterfuzzlite/`,
  so the placeholder served only to misrepresent fuzz coverage.
* Updated `TEST-NEEDS.md` FAKE-FUZZ ALERT section accordingly.
* Stripped the leading `{{~ Aditionally delete this line ... ~}}` template
  comment from both `ABI-FFI-README.md` files.

The only remaining `{{...}}` strings in the repo are: the legitimate
inline-prose reference to forbidden placeholders inside QUICKSTART-DEV's
invariants list, the `reject-if-contains` policy entry in `methodology.a2ml`
itself, and just-recipe variable references in `impl/ocaml/Justfile` (which
are runtime variables, not template placeholders).

Author: hyperpolymath

ABI-FFI-README.md

@@ -1,6 +1,4 @@
-{{~ Aditionally delete this line and fill out the template below ~}}
-
-# {{PROJECT}} ABI/FFI Documentation
+# ValenceShell ABI/FFI Documentation
 
 ## Overview
 
@@ -26,7 +24,7 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design:
                   ▼
 ┌─────────────────────────────────────────────┐
 │  C Headers (auto-generated)                 │
-│  generated/abi/{{project}}.h                │
+│  generated/abi/valence_shell.h                │
 └─────────────────┬───────────────────────────┘
                   │
                   │ imported by
@@ -39,7 +37,7 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design:
 │  - Memory-safe by default                   │
 └─────────────────┬───────────────────────────┘
                   │
-                  │ compiled to lib{{project}}.so/.a
+                  │ compiled to libvalence_shell.so/.a
                   ▼
 ┌─────────────────────────────────────────────┐
 │  Any Language via C ABI                     │
@@ -50,7 +48,7 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design:
 ## Directory Structure
 
 ```
-{{project}}/
+valence-shell/
 ├── src/
 │   ├── abi/                    # ABI definitions (Idris2)
 │   │   ├── Types.idr           # Core type definitions with proofs
@@ -67,11 +65,11 @@ This library follows the **Hyperpolymath RSR Standard** for ABI and FFI design:
 │       ├── test/
 │       │   └── integration_test.zig
 │       └── include/
-│           └── {{project}}.h   # C header (optional, can be generated)
+│           └── valence_shell.h   # C header (optional, can be generated)
 │
 ├── generated/                  # Auto-generated files
 │   └── abi/
-│       └── {{project}}.h       # Generated from Idris2 ABI
+│       └── valence_shell.h       # Generated from Idris2 ABI
 │
 └── bindings/                   # Language-specific wrappers (optional)
     ├── rust/
@@ -199,7 +197,7 @@ zig build test                    # Run tests
 
 ```bash
 cd src/abi
-idris2 --cg c-header Types.idr -o ../../generated/abi/{{project}}.h
+idris2 --cg c-header Types.idr -o ../../generated/abi/valence_shell.h
 ```
 
 ### Cross-Compile
@@ -222,32 +220,32 @@ zig build -Dtarget=x86_64-windows
 ### From C
 
 ```c
-#include "{{project}}.h"
+#include "valence_shell.h"
 
 int main() {
-    void* handle = {{project}}_init();
+    void* handle = valence_shell_init();
     if (!handle) return 1;
 
-    int result = {{project}}_process(handle, 42);
+    int result = valence_shell_process(handle, 42);
     if (result != 0) {
-        const char* err = {{project}}_last_error();
+        const char* err = valence_shell_last_error();
         fprintf(stderr, "Error: %s\n", err);
     }
 
-    {{project}}_free(handle);
+    valence_shell_free(handle);
     return 0;
 }
 ```
 
 Compile with:
 ```bash
-gcc -o example example.c -l{{project}} -L./zig-out/lib
+gcc -o example example.c -lvalence_shell -L./zig-out/lib
 ```
 
 ### From Idris2
 
 ```idris
-import {{PROJECT}}.ABI.Foreign
+import ValenceShell.ABI.Foreign
 
 main : IO ()
 main = do
@@ -264,44 +262,44 @@ main = do
 ### From Rust
 
 ```rust
-#[link(name = "{{project}}")]
+#[link(name = "valence_shell")]
 extern "C" {
-    fn {{project}}_init() -> *mut std::ffi::c_void;
-    fn {{project}}_free(handle: *mut std::ffi::c_void);
-    fn {{project}}_process(handle: *mut std::ffi::c_void, input: u32) -> i32;
+    fn valence_shell_init() -> *mut std::ffi::c_void;
+    fn valence_shell_free(handle: *mut std::ffi::c_void);
+    fn valence_shell_process(handle: *mut std::ffi::c_void, input: u32) -> i32;
 }
 
 fn main() {
     unsafe {
-        let handle = {{project}}_init();
+        let handle = valence_shell_init();
         assert!(!handle.is_null());
 
-        let result = {{project}}_process(handle, 42);
+        let result = valence_shell_process(handle, 42);
         assert_eq!(result, 0);
 
-        {{project}}_free(handle);
+        valence_shell_free(handle);
     }
 }
 ```
 
 ### From Julia
 
 ```julia
-const lib{{project}} = "lib{{project}}"
+const libvalence_shell = "libvalence_shell"
 
 function init()
-    handle = ccall((:{{project}}_init, lib{{project}}), Ptr{Cvoid}, ())
+    handle = ccall((:valence_shell_init, libvalence_shell), Ptr{Cvoid}, ())
     handle == C_NULL && error("Failed to initialize")
     handle
 end
 
 function process(handle, input)
-    result = ccall((:{{project}}_process, lib{{project}}), Cint, (Ptr{Cvoid}, UInt32), handle, input)
+    result = ccall((:valence_shell_process, libvalence_shell), Cint, (Ptr{Cvoid}, UInt32), handle, input)
     result
 end
 
 function cleanup(handle)
-    ccall((:{{project}}_free, lib{{project}}), Cvoid, (Ptr{Cvoid},), handle)
+    ccall((:valence_shell_free, libvalence_shell), Cvoid, (Ptr{Cvoid},), handle)
 end
 
 # Usage
@@ -355,7 +353,7 @@ When modifying the ABI/FFI:
 
 2. **Generate C header**
    ```bash
-   idris2 --cg c-header src/abi/Types.idr -o generated/abi/{{project}}.h
+   idris2 --cg c-header src/abi/Types.idr -o generated/abi/valence_shell.h
    ```
 
 3. **Update FFI implementation** (`ffi/zig/src/main.zig`)

QUICKSTART-DEV.adoc

@@ -1,13 +1,16 @@
 // SPDX-License-Identifier: MPL-2.0
-// Template: QUICKSTART-DEV.adoc — clone → build → test → PR
-// Replace valence-shell, {{BUILD_CMD}}, {{TEST_CMD}}, {{LANG_STACK}} with actuals
 = valence-shell — Quick Start for Developers
 :toc:
 :toclevels: 2
 
 == Tech Stack
 
-{{LANG_STACK}}
+* **Rust** — CLI implementation (`impl/rust-cli/`), Cargo crate `vsh`
+* **Idris2** — ABI definitions with formal proofs (`src/abi/`, `proofs/idris2/`)
+* **Zig** — C-compatible FFI layer (`ffi/zig/`, exports `valence_shell_*`)
+* **Coq / Lean4 / Agda / Isabelle / Mizar** — 6-system polyglot proofs (`proofs/`)
+* **Elixir** — NIF daemon + MCP server (`impl/elixir/`)
+* **OCaml** — Lean-extraction FFI wrapper (`impl/ocaml/`)
 
 == Set Up Development Environment
 
@@ -38,14 +41,23 @@ just setup-dev
 
 [source,bash]
 ----
-{{BUILD_CMD}}
+just build-everything    # Build proofs + FFI + CLI + Elixir + MCP
+# or one layer at a time:
+just build-coq           # Coq proofs
+just build-lean4         # Lean4 proofs
+just build-cli           # Rust CLI (vsh)
+just build-ffi           # Zig + OCaml FFI
 ----
 
 == Test
 
 [source,bash]
 ----
-{{TEST_CMD}}
+just verify-all          # Verify all proof systems
+just test-cli            # Cargo test for impl/rust-cli/
+just test-ffi-zig        # Zig FFI integration tests
+just test-ffi-ocaml      # OCaml FFI tests
+just test-elixir         # Elixir NIF tests
 ----
 
 == Project Structure
@@ -91,7 +103,13 @@ just panic-scan     # No new security issues
 Read `.machine_readable/MUST.contractile` before making changes.
 Key invariants that must never be violated:
 
-{{MUST_INVARIANTS}}
+* No hardcoded absolute paths (`/home/*`, `/mnt/*`); use env vars, XDG dirs, or relative references
+* No new TypeScript / Python / Go files; no npm/bun/yarn/pnpm dependencies (Deno only)
+* No `believe_me` or `assert_total` (Idris2); no new `Admitted.` (Coq); no `sorry` (Lean); no `unsafeCoerce` (Haskell); no `Obj.magic` (OCaml)
+* No `unsafe {}` blocks without an inline safety comment (Rust)
+* No template placeholders (`{{...}}`, `<...>`) in shipped files — see `.machine_readable/agent_instructions/methodology.a2ml`
+* All commits MUST be GPG-signed
+* Full machine-checked list lives at `.machine_readable/MUST.contractile`; K9 validators in `contractiles/k9/` enforce it on every PR
 
 == LLM/AI Agent Development
 

QUICKSTART-MAINTAINER.adoc

@@ -1,6 +1,4 @@
 // SPDX-License-Identifier: MPL-2.0
-// Template: QUICKSTART-MAINTAINER.adoc — packaging, deploying, and maintaining
-// Replace valence-shell, {{PACKAGE_NAME}}, {{DEPS}} with actuals
 = valence-shell — Quick Start for Platform Maintainers
 :toc:
 :toclevels: 2
@@ -12,7 +10,15 @@ distribution on your platform.
 
 == Runtime Dependencies
 
-{{DEPS}}
+* `glibc` >= 2.34 (or `musl` >= 1.2 for static builds)
+* Optional: `libleanshared.so` (Lean 4 runtime; required only when the Lean-extraction FFI feature is enabled — see `impl/rust-cli/docs/LEAN_EXTRACTION_BUILD_GUIDE.md`)
+* Optional: Erlang/OTP >= 26 (required only for the Elixir NIF daemon + MCP server features)
+
+Build-time dependencies (not required at runtime):
+
+* Rust >= 1.75 (CLI build)
+* Zig >= 0.13 (FFI library build)
+* Coq 8.18, Lean 4, Agda 2.6, Isabelle 2024, Mizar (proof verification; not required for release packaging if proofs are pre-verified in CI)
 
 == Build from Source
 
@@ -23,7 +29,11 @@ cd valence-shell
 just build-release
 ----
 
-Output: `{{BUILD_OUTPUT_PATH}}`
+Output:
+
+* `impl/rust-cli/target/release/vsh` — the `vsh` CLI binary
+* `ffi/zig/zig-out/lib/libvalence_shell.{so,a}` — shared and static FFI libraries
+* `ffi/zig/zig-out/include/valence_shell.h` — generated C header
 
 == Packaging
 
@@ -65,10 +75,10 @@ Files installed:
 | `$PREFIX/bin/`
 | Executables
 
-| `$PREFIX/share/{{PACKAGE_NAME}}/`
+| `$PREFIX/share/valence-shell/`
 | Data files, assets
 
-| `$PREFIX/share/doc/{{PACKAGE_NAME}}/`
+| `$PREFIX/share/doc/valence-shell/`
 | Documentation
 
 | `$PREFIX/share/applications/`
@@ -80,9 +90,9 @@ Files installed:
 
 == Configuration
 
-Default config location: `$XDG_CONFIG_HOME/{{PACKAGE_NAME}}/config.toml`
+Default config location: `$XDG_CONFIG_HOME/valence-shell/config.toml`
 
-Fallback: `$HOME/.config/{{PACKAGE_NAME}}/config.toml`
+Fallback: `$HOME/.config/valence-shell/config.toml`
 
 == Health Checks
 
@@ -102,7 +112,7 @@ just build-release
 just install --prefix=/usr/local
 ----
 
-Or via OPSM: `opsm update {{PACKAGE_NAME}}`
+Or via OPSM: `opsm update valence-shell`
 
 == Security Notes
 
@@ -117,8 +127,8 @@ For deploying multiple instances (e.g., different users or tenants):
 
 [source,bash]
 ----
-just install --prefix=/opt/{{PACKAGE_NAME}}-instance1 --config=/etc/{{PACKAGE_NAME}}/instance1.toml
-just install --prefix=/opt/{{PACKAGE_NAME}}-instance2 --config=/etc/{{PACKAGE_NAME}}/instance2.toml
+just install --prefix=/opt/valence-shell-instance1 --config=/etc/valence-shell/instance1.toml
+just install --prefix=/opt/valence-shell-instance2 --config=/etc/valence-shell/instance2.toml
 ----
 
 Each instance has isolated config, data, and logs.

TEST-NEEDS.md

@@ -70,8 +70,8 @@
 - Elixir tests: ✅ **+6** (NIF-specific behavior)
 - **Total test coverage increase: ~60 new tests/benchmarks**
 
-## FAKE-FUZZ ALERT
+## Fuzz coverage
 
-- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing
-- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file
-- Priority: P2 — creates false impression of fuzz coverage
+- Real fuzz harnesses live at `impl/rust-cli/fuzz/fuzz_targets/` (cargo-fuzz) and `.clusterfuzzlite/` (ClusterFuzzLite CI integration).
+- The legacy `tests/fuzz/placeholder.txt` scorecard-placeholder was removed on 2026-06-01; the real harnesses now satisfy the fuzz-coverage scorecard signal.
+- Missing fuzz targets per #43 (quotes, redirection, here_docs, command_sub, process_sub) tracked separately.