AkurAI-Notes / .plan/HANDOFF.md

Latest change f1d9b8cc6ff48113d891a2d95fd79b2c49f1f4ff - Initial plan and .plan directory by Claude Code

# HANDOFF.md — for DeepSeek v4 Flash

You are picking up AkurAI-Notes, a new project at
`/home/olafurbui/Projects/AkurAI-Notes`. This plan is complete and executable.
Rules:

## What Ólafur wants

A new self-hosted note app, pure-Rust, on-device embeddings, semantic search,
login via AkurAI IDP, HTTPS MCP at `https://akurai-notes.olibuijr.com/mcp`,
Framework-based UI, `deploy.sh` releases, `0.0.1` starting version, Keep-a-
Changelog maintained, icons generated by GPT-5.5 via `codex exec`.

## Rules of execution

1. **Never re-investigate what the plan already investigated.** Every file
   reference in `CODE-PATTERNS.md` is the canonical answer to "how do I do
   X in this codebase". Open it, copy the shape, swap identifiers.
2. **Never pull an external crate.** Strictly std + AkurAI-Framework path
   deps + Notes' own workspace crates. Validate before commit:
   `cargo tree --workspace --edges normal | rg -v '^\s*(├|└|│|\s)*.*(akurai-|notes-)'`
   should print nothing.
3. **One epic at a time.** Execute E01 → E08 in order; each has a seed and an
   acceptance test. Do not skip ahead. Do not combine. E03 depends on E01; E04
   depends on E01; E05 depends on E04; E06 depends on E04; E07 can be drafted
   early (it's a shellscript) but only verified at E08.
4. **Verify each epic's acceptance test before declaring it done.** Each epic
   lists what to run. Run it; print output; only move on after it passes.
5. **Mirror the framework's deploy.sh exactly**, with only the values swapped
   in `CODE-PATTERNS.md` §11. Do not write a custom release script.
6. **Icons via `codex exec`** with GPT-5.5 — the prompt shape is in E02. Save
   PNG to `site/frontend/icon-notes.png` and `favicon.svg` (also `apple-touch-icon.png`
   at higher res). Do not browse for icon assets; do not third-party-source
   them.
7. **Commit + tag releases using `./deploy.sh`.** Each work epic that lands on
   `main` is one commit; the *release* is the only thing that bumps VERSION.
   Initial bootstrap work lives on `main` untagged until `./deploy.sh patch`
   cuts `v0.0.1`.
8. **Don't `cargo add` external deps.** Don't pull `axum`, `tower-http`,
   `rusqlite`, `base64`, `serde`, `reqwest`, `tokio`. The CRM project already
   got away with a heavier dep stack (it predates the zero-deps rule); Notes
   inherits the Framework's stricter convention.
9. **SSH access is granted automatically by AGENTS.md.** To verify things on
   the EC2 host: `ssh akurai-mail '…'`. To fetch IDP admin token:
   `AKURAI_NOTES_IDP_ISSUER` needs no token for discovery; `AKURAI_ADMIN_TOKEN`
   is at `/etc/akurai-idp/idp.env` on the host.
10. **Don't amend releases.** If a release fails after tag, cut the next patch.

## Environment assumptions to assert before starting

```bash
# AkurAI-Framework crates path-include (workspace dep on ../AkurAI-Framework)
ls ~/Projects/AkurAI-Framework/crates/{http,json,storage,router,collections,vector,markdown,template,schema,i18n}

# The `akurai` CLI is on PATH for `akurai new`
which akurai && akurai --version

# gh for repo create + push (deploy.sh uses it)
gh auth status

# codex exec for GPT-5.5 icon generation
which codex && codex --version

# akurai-ec2 for live publish
which akurai-ec2 && akurai-ec2 --help | head -5

# SSH to the EC2 host (IDP + nginx live here)
ssh akurai-mail 'systemctl is-active akurai-idp nginx'
```

If any of the above fails, halt and report — the plan can't execute cleanly
without them. (In this environment all are confirmed present.)

## Sequencing (recommended batch sizes if running parallel worktree agents)

| Wave | Epics | Why batchable |
|------|-------|--------------|
| 1 | E01 | Scaffolding is single-threaded foundation |
| 2 | E02 + E04 + E07 (write only) | All file-disjoint: E02 = site/frontend/art/, E04 = crates/notes-core + site/backend, E07 = deploy.sh + VERSION + CHANGELOG.md |
| 3 | E03 + E05 | E03 = notes-api/src/auth/, E05 = notes-api/src/embed.rs + search.rs — disjoint files |
| 4 | E06 | Depends on E04 for tools.rs payload |
| 5 | E08 | Depends on E07 published binary + a DNS A record (manual step) |

## Per-epic expected time (rough, for Ólafur's planning)

- E01 — 10 min
- E02 — 8 min (icon gen via codex is the longest step; do Codex in background)
- E03 — 15 min (mostly file porting + IDP client registration)
- E04 — 10 min
- E05 — 25 min (reviewing `collections_api.rs` and writing `search.rs`)
- E06 — 15 min
- E07 — 10 min if E01 had a verbatim copy of framework deploy.sh
- E08 — 5 min + DNS propagation wait

## When in doubt

The Framework's AGENTS.md is the constitution. The CRM project is the nearest
production-grade sibling of what we're building — its file shape is what Notes
will look like at v0.0.1. When the plan says "port XYZ", port means: copy the
file, rename CRM → Notes, remove dead-code warnings from unused imports, and
do not improve the algorithm. First release gets it *working*; second release
can get it elegant.

— Ólafur Búi Ólafsson, 2026-06-27