AkurAI-Framework / AGENTS.md

Latest change 4ed55d17e0979479dc70291811217113b6062fa0 - docs: split AGENTS.md into domain-indexed subfiles + add breaking-changes guide by Ólafur Búi Ólafsson

# AGENTS.md — AkurAI-Framework

> The map. Read this first, then jump to the right domain file below. Every
> subsystem is a small, single-responsibility crate; every crate is many small
> files. Land in the right file via the domain indexes — don't grep blind.

## What this is

A **single-binary, pure-Rust, zero-runtime-dependency** full-stack web framework
in the spirit of PocketBase: embedded relational database, auto-generated REST
API from a declarative schema, built-in semantic search, and a from-scratch
client-first frontend toolchain. Copy one binary to a box, run it, done.

## Constitutional principles (do not violate)

1. **Zero runtime dependencies.** The shipped binary links NO external crates —
   `std` only. Internal workspace crates are fine. Dev/test/bench tooling
   (proptest, criterion, Playwright) is allowed; it never enters the binary.
2. **TLS terminates at the edge** (Caddy/nginx). The server speaks plain HTTP on
   localhost. std cannot do TLS and we will not pull a crate for it.
3. **Client-first.** The browser does rendering, routing, and state. The server
   serves the data API and does SSR only for SEO / dynamic content that needs it.
   Keep the server lean.
4. **No-build frontend.** Native ES modules + import maps + web components +
   server-rendered HTML. NO JS bundler/transpiler. Win DX/memory by subtraction.
5. **Declarative source of truth.** `backend/collections.toml` defines the data
   model; the API, validation, migrations, and embeddings all derive from it.
6. **Self-describing.** `GET /api/_meta` emits a machine-readable manifest of
   every generated route. Agents discover the whole surface in one call.
7. **TDD, always.** Failing test first, every phase. No subsystem advances
   without its test layer (unit → property → integration → e2e/visual).
8. **Performance is a gate, not a hope.** Budgets (cold start, idle memory,
   hot-reload latency, throughput) are asserted; regressions fail the release.
9. **Small scoped files.** One responsibility per file. If a file grows two
   concerns, split it and index it here.
10. **Docs are first-class.** Maintain a `/docs` documentation site in a
    Next.js/Vue-style layout (sidebar nav, sectioned guides + API reference) and
    keep it updated as the framework evolves — every new crate or feature ships
    with its docs in the same commit. See [`AGENTS_DOCS.md`](./AGENTS_DOCS.md).
11. **Data updates without a rebuild — essential.** All application data lives
    in the runtime data store (crash-safe, WAL-style durability) and editable
    context files (e.g. `backend/page.json`), never compiled into the binary.
    Changing data must NEVER require recompiling or redeploying the binary.
12. **Breaking changes are documented, never silent.** Pre-1.0, minor versions
    may break. Every breaking change gets a `### Breaking` changelog entry **and**
    a migration note in `site/content/docs/breaking-changes.md`. See
    [`AGENTS_DOCS.md`](./AGENTS_DOCS.md).

## Domain index — where everything lives

| Domain file | Covers |
|-------------|--------|
| [`AGENTS_CRATES.md`](./AGENTS_CRATES.md) | The full crate map + per-crate file lists, roles, public API, and gotchas for every workspace crate (`http`, `ws`, `router`, `json`, `sql`, `sqlexec`, `storage`, `collections`, `vector`, `toml`, `template`, `markdown`, `css`, `assets`, `cli`). |
| [`AGENTS_DATA.md`](./AGENTS_DATA.md) | The data engine: how `storage` + `sql`/`sqlexec` + `collections` + `vector` + `toml` compose; the B+tree key layout, the `coll:` / `\0`-prefix reserved keyspaces, and the embedding / `?search` lifecycle. |
| [`AGENTS_FRONTEND.md`](./AGENTS_FRONTEND.md) | No-build native-ESM frontend conventions: SSR templates, `signals.js`/`islands.js`/`spa.js`/`app.js`, the design system, and the markdown `preview` live-preview fence. |
| [`AGENTS_DEPLOY.md`](./AGENTS_DEPLOY.md) | `deploy.sh` (gate → bump → changelogs → tag → push → publish), the `ec2` publish-only mode, the `akurai-ec2` ops CLI + EC2 topology, lockstep versioning, and `install.sh` + `akurai update`. |
| [`AGENTS_TESTING.md`](./AGENTS_TESTING.md) | TDD discipline, the green gate, `CARGO_TARGET_TMPDIR` rule, the <1000-line file rule, and the worktree-agent batch recipe (`BATCHES.md`). |
| [`AGENTS_DOCS.md`](./AGENTS_DOCS.md) | Documentation conventions: the docs-with-every-feature rule (principle #10), the dual-changelog policy, and the breaking-changes policy. |

## How to work here

Work lands in **parallel worktree agents on disjoint file sets**, then an
orchestrator integrates. Read [`AGENTS_TESTING.md`](./AGENTS_TESTING.md) for the
full batch recipe, and [`BATCHES.md`](./BATCHES.md) — the live ledger of what's
shipped and what's queued. Before touching code, find the file via the domain
indexes above; before opening a PR, run the green gate
([`AGENTS_TESTING.md`](./AGENTS_TESTING.md)).

## Directory layout

```
AkurAI-Framework/
├── AGENTS.md            ← this file (the map) + AGENTS_<DOMAIN>.md domain files
├── BATCHES.md           ← live batch ledger (roadmap, what's shipped/queued)
├── CHANGELOG.md         ← developer-facing Keep-a-Changelog; deploy.sh cuts releases
├── VERSION              ← deploy.sh bumps it lockstep with Cargo workspace version
├── deploy.sh            ← gate → bump → changelog → tag → push → publish (see AGENTS_DEPLOY.md)
├── Cargo.toml           ← workspace root; `members` is the authoritative crate list
├── crates/              ← one subsystem per crate, small files (see AGENTS_CRATES.md)
├── scripts/hooks/       ← optional non-blocking pre-commit changelog nudge
└── site/                ← the framework's OWN website (the framework serves it):
                           frontend/ (native-ESM SPA + docs + components),
                           content/ (docs/*.md, changelog.md),
                           backend/ (page.json, routes.json, collections.toml).
                           Deployed to akurai-framework.olibuijr.com via deploy.sh.
```

## Roadmap

The roadmap is the live batch ledger in [`BATCHES.md`](./BATCHES.md) (build order,
what's shipped, what's queued, per batch + version). The user-facing roadmap is
`site/content/docs/roadmap.md` (orchestrator-maintained).