Auwai documentation

This is the index for the Auwai documentation. The top-level README is the short entry point; this page is the map.

Diagrams

The repository includes a static documentation site generated from this tree by scripts/build_docs_site.py. It keeps the docs layout and renders every Mermaid diagram inline. Wheel zooms a diagram, drag pans, and Ctrl + wheel scrolls the page.

The site is published at https://auwai.pages.dev/. The workflow in .github/workflows/cloudflare-pages.yml builds _site/ and deploys it with Wrangler.

One-time setup:

Create a Cloudflare Pages project named auwai using direct upload:

sh npx wrangler pages project create auwai --production-branch=main

Add CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID repository secrets.

GitHub-hosted runners use a large, changing set of IP addresses. Use a separate token without client IP filtering for CI, or run the workflow on a self-hosted runner on an allowed address.

Push to main or run the workflow manually.

The build still runs when the secrets are absent; only the deploy step is skipped.

Build it locally:

python -m pip install '.[docs]'
make docs-site
python -m http.server -d _site 8000

Then open http://127.0.0.1:8000/. The all-diagrams page is at docs/diagrams.html.

Reading order

Read 00-overview to learn the model.
Read 10-architecture before changing the index or the read loop.
Use 20-workflows for a task.
Use 30-reference for exact commands and data.
Use 40-operations when running Auwai on a machine.
Read 50-development before changing the code.
Read 60-roadmap for what is committed and what is aspirational.
Read 70-benchmarks for the current method and results.

Sections

Section	Purpose
00-overview	The problem, the coverage model, and the vocabulary
10-architecture	The components and the boundaries between them
20-workflows	The full-read, delta, query, workspace, and recovery procedures
30-reference	Commands, configuration, schema, files, and chunk ids
40-operations	Install, security, watch, audit, performance, and troubleshooting
50-development	Contributing, testing, providers, release, and decisions
60-roadmap	Stages, release readiness, aspirational features, and metrics
70-benchmarks	Local replication, method, calibration, and results

Release links

Status labels

Current describes the code on main.
Planned describes a committed stage that is not complete.
Aspirational describes an idea that is not committed.

A page that mixes these labels states which part is which.

Not checked

The full-read path has unit and integration coverage. The quality of a full-window segment is not measured yet.