RSR template repo - see RSR_OUTLINE.adoc in root for general background and specification

Tip	AI-Assisted Install: Just tell any AI assistant: Set up v-graphql from https://github.com/hyperpolymath/v-graphql The AI reads this repo, asks you a few questions, and handles everything. See details below.

This is your repo - don’t forget to rename me!

ABI/FFI Standards (Hyperpolymath Universal Standard)

All repos with foreign function interfaces MUST follow this standard:

• ABI (Application Binary Interface) → Idris2 (src/abi/*.idr)

  • Type definitions with dependent type proofs

  • Memory layout verification

  • Platform-specific ABIs with compile-time selection

  • Formal verification of interface correctness

• FFI (Foreign Function Interface) → Zig (ffi/zig/src/*.zig)

  • C-compatible function implementations

  • Zero-cost abstractions

  • Memory-safe by default

  • Cross-compilation support

• Generated C Headers → Auto-generated from Idris2 ABI (generated/abi/*.h)

  • Bridge between Idris2 and Zig

  • Consumed by any language via C ABI

Directory Structure:

project/
├── src/abi/          # Idris2 ABI definitions (REQUIRED)
├── ffi/zig/          # Zig FFI implementation (REQUIRED)
├── generated/abi/    # Auto-generated C headers
└── bindings/         # Language-specific wrappers (optional)

See: ABI-FFI-README.md for complete documentation

AI Gatekeeper Protocol (MANDATORY)

CRITICAL: All repos MUST include an AI manifest.

• File: 0-AI-MANIFEST.a2ml (included in this template)

• Purpose: Universal entry point for ALL AI agents (Claude, Gemini, OpenAI, etc.)

• Location: Repository root (alphabetically first)

• Customize: Update [YOUR-REPO-NAME] placeholders and repository structure section

The manifest declares:

• Canonical file locations (e.g., "machine-readable files ONLY in `.machine_readable/`")

• Critical invariants (rules that must NEVER be violated)

• Repository structure and organization

• Lifecycle hooks (on-enter, on-exit) for session logging

Benefits:

• ✅ Prevents duplicate file errors (e.g., machine-readable files in wrong locations)

• ✅ Context preserved across sessions and AI platforms

• ✅ No repeated explanations - mechanical enforcement

• ✅ Works universally (not just Claude)

See: AI Gatekeeper Protocol for details

Enforcement:

• MCP server (mcp-repo-guardian) - Hard enforcement for Claude

• FUSE wrapper (repo-guardian-fs) - Universal enforcement (coming soon)

• CI/CD validation - Continuous compliance checking

TOPOLOGY.md (Architecture Map)

Every repo should include a TOPOLOGY.md in its root — an ASCII architecture diagram combined with a completion dashboard. This gives any contributor (human or AI) an instant picture of the whole project.

• Template: TOPOLOGY.md (included in this template)

• Guide: docs/TOPOLOGY-GUIDE.adoc (includes AI prompt for generation, conventions, batch rollout)

• Sections: System Architecture (ASCII diagram), Completion Dashboard (progress bars), Key Dependencies (critical path)

See docs/TOPOLOGY-GUIDE.adoc for how to generate bespoke TOPOLOGY.md files for existing repos using an AI agent.

AI CLI standards

• FIRST: Customize 0-AI-MANIFEST.a2ml for your repo before any other work

• All machine-readable content lives in .machine_readable/ — state files (*.a2ml), anchors/, bot_directives/, contractiles/, and ai/.

• Include .machine_readable/ structure from this template in new repos.

Directory Structure Policy (Owner Override)

The owner policy for this template family is:

• Keep only essential entry-point files in root.

• Put licensing materials in licensing/ (retain root LICENSE for forge/license detection).

• Put documentation under docs/ with explicit tracks:

  • docs/theory/

  • docs/practice/

  • docs/whitepapers/academic/

  • docs/whitepapers/industry/

• Keep test fixtures/outputs under tests/.

• Keep AI-agent guidance in .machine_readable/ai/.

• Prefer Containerfile (not Dockerfile) for container builds.

Maintenance Gate (Release)

This template includes a maintenance workflow that is intended to be a release gate.

• Scripted audit: scripts/maintenance/run-maintenance.sh

• Permission lock/restore helper: scripts/maintenance/perms-state.sh

• Checklist: docs/maintenance/MAINTENANCE-CHECKLIST.md

Recommended release flow:

just maint-audit
just maint-hard-pass

Permission policy is audit-first by default. Use just perms-lock only when intentionally hardening local modes, and just perms-restore to restore your previous local permission state.

AI-Assisted Installation

You don’t need to read this README to get started. Just say this to any AI:

Set up v-graphql from https://github.com/hyperpolymath/v-graphql

The URL is the spec. The AI fetches this repo, reads docs/AI_INSTALLATION_GUIDE.adoc, and handles everything — prerequisites, build, config, verification. You answer a few questions and confirm the privacy notice. No commands, no installers, no forms.

If the AI already knows this project, shorter prompts work too. If it doesn’t, the URL gives it everything.

For developers: Fill in docs/AI_INSTALLATION_GUIDE.adoc with your project-specific install recipe. Paste the highlight box from docs/AI-INSTALL-README-SECTION.adoc into your README. Run just validate-ai-install to check completeness. finishbot verifies this pre-release.

The normal installation instructions remain below for anyone who prefers to do things manually.

Standard Dependencies (Optional)

Add your project’s standard dependencies here. Remove or customize this section for your ecosystem.