0-AI-MANIFEST.a2ml

# SPDX-License-Identifier: AGPL-3.0-or-later
# SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
#
# 0-AI-MANIFEST.a2ml — Universal AI Agent Entry Point
# IDApTIK — Asymmetric co-op stealth puzzle-platformer + adaptive game engine
#
# READ THIS FILE FIRST. This is the canonical entry point for all AI agents.
#
# CRITICAL: This is the LIVE game repo. Your son depends on this.
# DO NOT experiment here. Use idaptik-rescript13-staging for testing.

[manifest]
version = "1.2"
project = "idaptik"
type = "educational-game"
license = "AGPL-3.0-or-later"
author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
repo = "https://github.com/hyperpolymath/idaptik"

[context-tiers]
# Tier 0 (always load): This file + .claude/CLAUDE.md — orientation only
# Tier 1 (load if working on code): README.adoc, EXPLAINME.adoc, deno.json, rescript.json
# Tier 2 (load on demand): .machine_readable/6a2/STATE.a2ml, docs/, idaptik-developers/
# Tier 3 (never load unless asked): tests/, generated/, CI configs
#
# DO NOT READ unless specifically asked:
#   shared/tests/    — test files (run them, don't read them)
#   vm/tests/        — VM tests
#   public/assets/   — generated assets (from raw-assets/ via AssetPack)
#   src/manifest.json — generated by AssetPack (do not edit)
#   node_modules/    — dependencies
#   lib/bs/          — ReScript compiler cache
#   *.lock           — lock files
#   *.res.mjs        — compiled ReScript output (read .res source instead)

[canonical-locations]
state-files = ".machine_readable/"
ai-instructions = "CLAUDE.md"
source = "src/"
main-game = "main-game/"
shared = "shared/"
vm = "vm/"
vm-wasm = "vm/wasm/"
dlc = "dlc/"
escape-hatch = "escape-hatch/"
containers = "containers/"
idaptik-ums = "idaptik-ums/"
idaptik-developers = "idaptik-developers/"
tools = "tools/"
locales = "locales/"

[tech-stack]
primary = "ReScript 12.2.0 + PixiJS 8.8.1"
runtime = "Deno + Vite 6.2.0"
backend = "Elixir/Phoenix (sync server, port 4030)"
escape-hatch = "Rust + ratatui TUI"
modding-studio = "Tauri 2 (idaptik-ums)"
vm = "Pure reversible VM (ReScript core + Zig WASM backend)"
dev-port = "8080"

[critical-invariants]
invariant-1 = "This is the LIVE repo — DO NOT break the game"
invariant-2 = "State files in .machine_readable/ ONLY — never in root"
invariant-3 = "License: AGPL-3.0-or-later throughout"
invariant-4 = "Author: Jonathan D.A. Jewell (hyperpolymath)"
invariant-5 = "Build with: deno task dev (NOT npm or bun)"
invariant-6 = "ReScript source in src/ — no TypeScript"
invariant-7 = "For experiments, use idaptik-rescript13-staging"
invariant-8 = "WASM binary: vm/wasm/ (Zig-compiled, 41M ops/sec, 407KB)"
invariant-9 = "Belt is BANNED — use @rescript/core exclusively"
invariant-10 = "No Js.* APIs — all migrated to Dict/Array/String/Math/Console/JSON"

[structure]
# Core game
src-app = "src/app/"              # Game application code (combat, companions, devices, enemies, ...)
src-engine = "src/engine/"        # Core game engine
src-bindings = "src/bindings/"    # PixiJS/Sound/UI/Motion FFI bindings
# Components
main-game = "main-game/"          # Main game content and PWA
shared = "shared/"                # Cross-component (224 modules, 640+ tests)
vm = "vm/"                        # Reversible VM (23 instructions, Tier 0-4)
vm-wasm = "vm/wasm/"              # Zig WASM backend
dlc = "dlc/"                      # Downloadable content / puzzle packs
escape-hatch = "escape-hatch/"    # Rust TUI (5 tabs, Podman integration)
containers = "containers/"        # Stapeln-style Containerfiles
idaptik-ums = "idaptik-ums/"      # Unified Modding Studio (Tauri 2, Idris2 ABI, Zig FFI)
idaptik-developers = "idaptik-developers/"  # Developer portal (17 ADRs, white paper)
tools = "tools/"                  # Balance analyser (Julia)
locales = "locales/"              # i18n JSON locale files (polyglot-i18n)

[architecture]
# Asymmetric co-op: Jessica (platformer) + Q (CCTV/blueprints) — NEVER same view
# Characters: Jessica (SBS operative, 6 subclasses), Q (cert tree), Moletaire (companion)
# Network topology: Star with DNS, traceroute, SSH, zone-based layout
# State: functional immutable records, localStorage persistence
paradigm = "Screen navigation with lifecycle (prepare/show/hide/pause/resume/update/resize)"

[panll-mapping]
panel-L = "Game rules, level constraints, network topology validation"
panel-N = "AI companions (Moletaire), adaptive difficulty, learning analytics"
panel-W = "Game state, player progress, network simulation results"

[session-protocol]
on-enter = [
  "Read this manifest",
  "Confirm: LIVE repo or staging?",
  "Read .machine_readable/STATE.scm for current status",
]
on-exit = [
  "Verify game still builds: deno task res:build",
  "Update .machine_readable/STATE.scm with progress",
]