docs(cartridge): scaffold RSR essentials for echidna-llm-mcp

Cartridge previously had only README.adoc + docs/CALL-PROTOCOL.adoc.
Add the RSR-canonical essentials that bring it to D-grade conformance
on its own (rather than relying purely on parent boj-server scaffolding):

- LICENSE              MPL-2.0 (legal fallback for PMPL-1.0-or-later, copied from parent)
- SECURITY.md          Cartridge-specific notes + pointer to parent's reporting flow
- CONTRIBUTING.md      Cartridge-specific contribution guidance + parent pointer
- EXPLAINME.adoc       README claims with evidence and caveats
- .machine_readable/6a2/{STATE,META,ECOSYSTEM,AGENTIC,NEUROSYM,PLAYBOOK,ANCHOR}.a2ml

The 6a2 set is minimal-but-valid:
- STATE.a2ml: 90% complete, recent commits captured (Zig 0.15 fix, V-lang
  sweep), no current blockers
- META.a2ml: 3 ADRs (V-lang retirement, Zig 0.15 module-first build,
  slug-based prover addressing)
- ECOSYSTEM.a2ml: 8 downstream consumers found in earlier audit, plus
  upstream relationship to echidna and hosting in boj-server. Notes the
  echidnabot-mcp exception alongside.
- AGENTIC.a2ml: agent perms + constraints (no V-lang, no npm, no
  hardcoded slugs)
- NEUROSYM.a2ml: declares cartridge is pure transport — no local models
- PLAYBOOK.a2ml: incident response for the 3 most likely failures
  (echidna down, unknown slug, Zig version mismatch)
- ANCHOR.a2ml: id, parents (boj-server + echidna), recalibration triggers

License/security/contributing files all explicitly defer to the parent
boj-server for the canonical flow — cartridge sovereignty ends at the
ABI surface; parent owns trust + threat model.

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

Author: hyperpolymath

cartridges/echidna-llm-mcp/.machine_readable/6a2/AGENTIC.a2ml

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# AGENTIC.a2ml — AI agent constraints + capabilities for echidna-llm-mcp
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-04-25"
+
+[agent-permissions]
+can-edit-source = true       # mod.js, ffi/, adapter/
+can-edit-tests = true        # ffi tests
+can-edit-docs = true         # CALL-PROTOCOL, README, EXPLAINME
+can-edit-config = true       # cartridge.json
+can-edit-protocol = false    # ABI changes need parent boj-server review
+
+[agent-constraints]
+# What agents must NOT do:
+# - Add new tools without updating CALL-PROTOCOL.adoc
+# - Hardcode prover slugs (delegate to echidna's provers.a2ml at runtime)
+# - Bypass the parent BoJ loader for production traffic
+# - Use V-lang (banned 2026-04-10) — Zig only
+# - Use npm/Bun/pnpm — Deno only
+# - Use believe_me / unsafeCoerce / Obj.magic / similar dangerous patterns
+
+[automation-hooks]
+# on-enter: Read parent boj-server STATE.a2ml + this STATE.a2ml + CALL-PROTOCOL
+# on-edit-tool: Update CALL-PROTOCOL.adoc + bump cartridge.json version
+# on-build-fail: Check Zig version >= 0.15.2; check FFI exports marked `pub`
+# on-commit: Run zig build + zig build test on FFI changes
+
+[trust-policy]
+inherits-from = "boj-server (loader, signature verification, threat model)"
+adds = "none — cartridge introduces no new privileged operations"
+
+[exceptions]
+# No carve-outs from estate-wide rules at the cartridge level.
+# The companion echidnabot-mcp is a documented exception in its own
+# AGENTIC.a2ml — sunsets to fold back into a BoJ cartridge.

cartridges/echidna-llm-mcp/.machine_readable/6a2/ANCHOR.a2ml

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# ⚓ ANCHOR: echidna-llm-mcp
+# Canonical identity + recalibration anchor for the echidna-llm-mcp BoJ
+# cartridge.
+
+id      = "org.hyperpolymath.boj-server.cartridges.echidna-llm-mcp"
+version = "0.3.0"
+clade   = "boj-cartridge"
+status  = "active"
+
+# No SSG — cartridge is a runtime component, not a static-site source.
+
+[relationships]
+parents = [
+  "org.hyperpolymath.boj-server",   # hosted in (loader)
+  "org.hyperpolymath.echidna",      # delegated to (proof engine)
+]
+
+siblings = [
+  # All other boj-server cartridges
+]
+
+[recalibration]
+# When this anchor becomes stale, walk the following:
+# 1. Verify echidna REST surface compatibility (docs/CALL-PROTOCOL.adoc vs echidna's actual endpoints)
+# 2. Check Zig version still supported (currently 0.15.2+)
+# 3. Confirm cartridge ABI compatibility with current boj-server loader
+# 4. Re-verify slug catalogue alignment (echidna's provers.a2ml unchanged enums)
+triggers = [
+  "echidna major version bump",
+  "boj-server loader ABI change",
+  "Zig stdlib API breaking change (next major)",
+]

cartridges/echidna-llm-mcp/.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# ECOSYSTEM.a2ml — Position of echidna-llm-mcp in the hyperpolymath stack
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-04-25"
+
+[ecosystem]
+name = "echidna-llm-mcp"
+type = "boj-cartridge"
+purpose = "AI-assistant gateway to echidna proof engine"
+
+[position-in-ecosystem]
+layer = "transport / shim"
+direction = "AI assistants → echidna proof engine"
+
+[upstream-dependencies]
+[[upstream-dependencies.dep]]
+name = "echidna"
+repo = "github.com:hyperpolymath/echidna.git"
+relationship = "consumer-of"
+purpose = "All proof operations are delegated to echidna's REST API"
+contract = "REST endpoints documented in docs/CALL-PROTOCOL.adoc"
+
+[[upstream-dependencies.dep]]
+name = "boj-server"
+repo = "github.com:hyperpolymath/boj-server.git"
+relationship = "hosted-in"
+purpose = "Loader, security policy, FFI primitives, threat-model"
+contract = "Cartridge ABI per boj-server/cartridges/README.adoc"
+
+[downstream-consumers]
+# Repos that invoke this cartridge (as found in 2026-04-24 estate audit):
+referenced-from = [
+  "aspasia",
+  "panll",
+  "007-lang",
+  "proven-servers",
+  "typell",
+  "nesy-solver",
+  "absolute-zero",
+  "boj-server (parent — TOPOLOGY.md)",
+]
+
+[related-projects]
+[[related-projects.project]]
+name = "echidnabot"
+relationship = "sibling-actuator"
+note = """
+Echidnabot also calls echidna for proof verification, but goes via
+echidna's REST API directly (not through this cartridge). Echidnabot
+ships a separate native MCP server (echidnabot-mcp) as a documented
+BoJ-only-MCP exception — see echidnabot/.machine_readable/6a2/AGENTIC.a2ml
+[exceptions.boj-only-mcp]. This cartridge remains the canonical
+BoJ-mediated MCP surface for echidna.
+"""
+
+[invariants]
+canonical-mcp-surface = "This cartridge is the canonical BoJ-mediated MCP surface for echidna. All MCP-shaped traffic to echidna SHOULD route through here."
+echidnabot-exception = "Echidnabot's standalone MCP bin is a temporary exception, sunsets when BoJ loader supports double-loop feedback protocol."

cartridges/echidna-llm-mcp/.machine_readable/6a2/META.a2ml

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# META.a2ml — Architecture decisions for echidna-llm-mcp
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-04-25"
+
+[project-info]
+license = "PMPL-1.0-or-later"
+license-fallback = "MPL-2.0"
+author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
+parent-repo = "hyperpolymath/boj-server"
+
+[architecture-decisions]
+
+[[architecture-decisions.decision]]
+id      = "ADR-CART-001"
+date    = "2026-04-10"
+status  = "accepted"
+title   = "V-lang adapter retired in favour of Zig"
+context = """
+V-lang was banned estate-wide on 2026-04-10. The cartridge's V-lang
+intermediate adapter was deleted; Zig is the canonical native FFI
+language going forward.
+"""
+consequences = """
+- adapter/ now contains Zig sources only
+- Build requires Zig 0.15.2+ (see ADR-CART-002)
+- Deno mod.js remains the canonical default transport for BoJ loader
+"""
+
+[[architecture-decisions.decision]]
+id      = "ADR-CART-002"
+date    = "2026-04-25"
+status  = "accepted"
+title   = "Zig 0.15 module-first build pattern"
+context = """
+Zig 0.15.2 dropped `.root_source_file` from `Build.ExecutableOptions`.
+The cartridge's adapter/build.zig was on the legacy 0.14 API. Migrated
+to the module-first pattern (createModule → addExecutable with
+.root_module). All 16 export fns in the FFI were also marked `pub`
+to satisfy 0.15's cross-module visibility check.
+"""
+consequences = """
+- Single supported Zig: 0.15.2+ (no 0.14 fallback)
+- FFI now usable both as Zig module imports (Zig consumers) and via
+  C ABI symbol table (BoJ loader)
+"""
+
+[[architecture-decisions.decision]]
+id      = "ADR-CART-003"
+date    = "2026-04-20"
+status  = "accepted"
+title   = "Slug-based prover addressing"
+context = """
+Echidna ships ~113 prover backends. Hardcoding the list in the cartridge
+would require a cartridge bump on every echidna prover addition. Decision:
+the cartridge accepts a `prover` slug string and delegates resolution to
+echidna at request time. The catalogue lives upstream in
+echidna/.machine_readable/provers.a2ml.
+"""
+consequences = """
+- Cartridge is forward-compatible with echidna prover additions
+- Invalid slugs surface as echidna-side 404, not cartridge errors
+- Discovery: callers list provers via the dedicated tool (see
+  docs/CALL-PROTOCOL.adoc)
+"""
+
+[development-practices]
+build-tool = "zig build (adapter), no build for Deno path"
+test-runner = "zig build test (FFI), Deno test suite (mod.js)"
+ci = "inherits from boj-server parent repo"
+spdx = "required on all source files"
+language-policy = "Zig 0.15.2+, Deno (no Node/npm), no V-lang"

cartridges/echidna-llm-mcp/.machine_readable/6a2/NEUROSYM.a2ml

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# NEUROSYM.a2ml — Neurosymbolic integration config for echidna-llm-mcp
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-04-25"
+
+[role]
+# This cartridge does not perform any symbolic reasoning or neural inference
+# itself. It is a transport shim. Both layers live upstream in echidna:
+# - symbolic: provers/, verification/, dispatch.rs
+# - neural: src/julia/ (GNN, premise selection, tactic ranking)
+
+is-symbolic-engine = false
+is-neural-engine = false
+exposes-neurosym = true   # via echidna's combined endpoints
+
+[exposed-tools]
+# Tools that route to neurosymbolic backends in echidna:
+[[exposed-tools.tool]]
+name = "suggest_tactics"
+neural-component = "echidna /gnn/rank (Julia GNN endpoint)"
+symbolic-component = "echidna prover dispatch"
+
+[[exposed-tools.tool]]
+name = "rank_premises"
+neural-component = "echidna /gnn/rank"
+symbolic-component = "premise filter"
+
+[hypatia-scanning]
+# Hypatia (estate-wide neurosymbolic CI/CD intelligence) scans this
+# cartridge as part of boj-server's parent scan. No cartridge-specific
+# Hypatia config needed.
+inherits-from = "boj-server"
+
+[invariants]
+no-local-models = "This cartridge ships no model weights, no inference code. All AI happens upstream in echidna."
+no-bypass = "Tool callers cannot reach echidna's neural endpoints by other means through this cartridge — only the documented suggest_tactics / rank_premises path."

cartridges/echidna-llm-mcp/.machine_readable/6a2/PLAYBOOK.a2ml

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# PLAYBOOK.a2ml — Operational runbook for echidna-llm-mcp
+
+[metadata]
+version = "1.0.0"
+last-updated = "2026-04-25"
+
+[deployment]
+# Cartridge is deployed as part of boj-server. No standalone deployment.
+loader = "boj-server"
+loader-loads-via = "Deno mod.js (default) or Zig adapter binary (optional)"
+typical-port = "delegated to BoJ loader; no cartridge-owned port"
+
+[runtime-config]
+# Configuration sources, in precedence order:
+# 1. BoJ loader env (passes through)
+# 2. cartridge.json static defaults
+# 3. Code-baked defaults (e.g. http://127.0.0.1:7700 for Zig adapter)
+[[runtime-config.var]]
+name = "BOJ_ENDPOINT"
+read-by = "Zig adapter only"
+default = "http://127.0.0.1:7700"
+purpose = "BoJ server URL the adapter forwards to"
+
+[[runtime-config.var]]
+name = "ECHIDNA_ENDPOINT"
+read-by = "Deno mod.js"
+default = "http://127.0.0.1:8081"
+purpose = "Echidna REST API endpoint"
+
+[incident-response]
+[[incident-response.scenario]]
+trigger = "All tool calls return 503 / connection refused"
+likely-cause = "Echidna REST endpoint down"
+diagnose = "curl ${ECHIDNA_ENDPOINT}/api/health"
+mitigate = "Restart echidna; cartridge has no local fallback"
+
+[[incident-response.scenario]]
+trigger = "Tool call returns 'unknown prover slug'"
+likely-cause = "Slug not in echidna's current ProverKind enum"
+diagnose = "curl ${ECHIDNA_ENDPOINT}/api/v1/provers — compare against requested slug"
+mitigate = "Use a valid slug from the returned list, or upgrade echidna"
+
+[[incident-response.scenario]]
+trigger = "Zig adapter fails to start"
+likely-cause = "Zig version < 0.15.2 OR libc not linked"
+diagnose = "zig version; check adapter/build.zig has .link_libc = true"
+mitigate = "Upgrade Zig; or fall back to Deno mod.js path"
+
+[release]
+versioning = "semver, in cartridge.json"
+release-procedure = "inherits from boj-server release flow"
+breaking-change-policy = "Tool removal or signature change requires major bump + update CALL-PROTOCOL.adoc"
+
+[backup]
+# Cartridge is stateless. No backup needed.
+stateful = false

cartridges/echidna-llm-mcp/.machine_readable/6a2/STATE.a2ml

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+#
+# STATE.a2ml — echidna-llm-mcp cartridge state
+
+[metadata]
+project = "echidna-llm-mcp"
+version = "0.3.0"
+last-updated = "2026-04-25"
+status = "active"
+
+[project-context]
+name = "echidna-llm-mcp"
+purpose = """
+BoJ cartridge exposing echidna's proof engine to AI assistants via
+JSON-RPC. 15 tools mapping 1:1 to echidna REST endpoints, addressable
+across all 113 ProverKind variants by slug.
+"""
+completion-percentage = 90
+
+[position]
+phase = "production"
+maturity = "stable"
+
+[components]
+deno-transport = { status = "shipping", path = "mod.js" }
+zig-adapter = { status = "shipping", path = "adapter/", note = "Zig 0.15.2 build fix landed afbab20 (2026-04-25)" }
+ffi = { status = "shipping", path = "ffi/echidna_llm_ffi.zig" }
+call-protocol = { status = "shipping", path = "docs/CALL-PROTOCOL.adoc" }
+
+[dependencies]
+parent-repo = "boj-server (loader, security, threat-model)"
+upstream = "echidna (REST endpoints, prover catalogue)"
+
+[blockers-and-issues]
+issues = []
+
+[critical-next-actions]
+actions = [
+  "Track echidna REST surface drift — when echidna gains new endpoints, mirror in CALL-PROTOCOL.adoc",
+  "Watch for BoJ loader signature/auth changes that might affect cartridge invocation",
+]
+
+[recent-history]
+[[recent-history.entry]]
+date = "2026-04-25"
+ref = "afbab20"
+note = "Zig 0.15.2 cartridge build fix (4 sub-issues: API drift + libc + 16 pub fns + missing init arg)"
+
+[[recent-history.entry]]
+date = "2026-04-25"
+note = "RSR scaffolding added: LICENSE, SECURITY.md, CONTRIBUTING.md, EXPLAINME.adoc, .machine_readable/6a2/"
+
+[[recent-history.entry]]
+date = "2026-04-24"
+ref = "1fef110, c5188a8"
+note = "V-lang seam sweep — removed historical V-lang references after V-lang ban"