0-AI-MANIFEST.a2ml

# STOP - CRITICAL READING REQUIRED

**THIS FILE MUST BE READ FIRST BY ALL AI AGENTS**

## WHAT IS THIS?

This is the AI manifest for **QuandleDB**. It declares:
- Canonical file locations (where things MUST be, and nowhere else)
- Critical invariants (rules that must NEVER be violated)
- Repository structure and organization

## CANONICAL LOCATIONS (UNIVERSAL RULE)

### Machine-Readable Metadata: `.machine_readable/` ONLY

These 6 SCM files MUST exist in `.machine_readable/` directory ONLY:
1. **STATE.scm** - Project state, progress, blockers
2. **META.scm** - Architecture decisions, governance
3. **ECOSYSTEM.scm** - Position in ecosystem, relationships
4. **AGENTIC.scm** - AI agent interaction patterns
5. **NEUROSYM.scm** - Neurosymbolic integration config
6. **PLAYBOOK.scm** - Operational runbook

**CRITICAL:** If ANY of these files exist in the root directory, this is an ERROR.

### Bot Directives: `.bot_directives/` ONLY

Bot-specific instructions for:
- rhodibot - Git operations
- echidnabot - Code quality
- sustainabot - Dependency updates
- glambot - Documentation
- seambot - Integration
- finishbot - Task completion

### Agent Instructions

- `.claude/CLAUDE.md` - Claude-specific patterns (if exists)
- `0-AI-MANIFEST.a2ml` - THIS FILE (universal entry point)

## CORE INVARIANTS

1. **No SCM duplication** - Root must NOT contain STATE.scm, META.scm, etc.
2. **Single source of truth** - `.machine_readable/` is authoritative
3. **No stale metadata** - If root SCMs exist, they are OUT OF DATE
4. **License consistency** - All code MPL-2.0 unless platform requires MPL-2.0
5. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"

## REPOSITORY STRUCTURE

```
quandledb/
├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
├── README.adoc                 # Project overview
├── ROADMAP.adoc                # Future plans
├── server/                     # Julia HTTP server
│   ├── Project.toml            # Julia dependencies (Skein.jl path dep)
│   └── serve.jl                # HTTP API server
├── frontend/                   # ReScript TEA web interface
│   ├── rescript.json            # ReScript config
│   ├── deno.json                # Deno tasks + imports
│   └── src/                     # ReScript source files
├── public/                     # Static assets (HTML, CSS)
│   ├── index.html
│   └── style.css
├── .machine_readable/          # SCM files (6 files)
│   ├── STATE.scm
│   ├── META.scm
│   ├── ECOSYSTEM.scm
│   ├── AGENTIC.scm
│   ├── NEUROSYM.scm
│   └── PLAYBOOK.scm
├── .bot_directives/            # Bot instructions
├── .claude/CLAUDE.md           # Claude-specific instructions
└── contractiles/               # Contractiles (k9, dust, lust, must, trust)
```

## KEY RELATIONSHIPS

- **Skein.jl** is the computational/backend engine of the KRL stack (Julia library + embedded SQLite store)
- **QuandleDB** is the database application — the invariant/equivalence + semantic-identity face (quandle fingerprints, equivalence/identity; read-only HTTP API + AffineScript UI) wrapping Skein.jl; hosts the server-side KRL parser (`server/krl/`)
- **KRL** (Knot Resolution Language) is the stack's resolution DSL — *not merely* a query language; the four ops (construct/transform/resolve/retrieve) run against the QuandleDB+Skein substrate

## SESSION STARTUP CHECKLIST

Read THIS file (0-AI-MANIFEST.a2ml) first
Understand canonical locations (.machine_readable/, .bot_directives/)
Know the invariants (no SCM duplication, etc.)
Read `.machine_readable/STATE.scm` for current status

## META

- **Format Version:** 1.0.0
- **Created:** 2026-02-13
- **Maintained By:** Jonathan D.A. Jewell (hyperpolymath)
- **License:** MPL-2.0
- **Protocol:** https://github.com/hyperpolymath/0-ai-gatekeeper-protocol