AkurAI-Notes / .plan/README.md

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

# AkurAI-Notes — Plan

Notes app for the AkurAI suite. Privacy-first, pure-Rust, semantic-search
note-taking — like Oblivion, but self-hosted on `*.olibuijr.com`, single-binary,
logged in via AkurAI IDP. Built on the AkurAI-Framework runtime and released
through its exact bootstrap + release-engine conventions.

## Constraints (from Ólafur, all locked)

| # | Constraint |
|---|------------|
| 1 | **Pure Rust, zero runtime deps in the shipped binary.** The Framework's own crates (`akurai-http`, `akurai-json`, `akurai-storage`, `akurai-vector`, `akurai-collections`, `akurai-router`, `akurai-markdown`, `akurai-template`) are path-dependency includes from `~/Projects/AkurAI-Framework/crates/`. No external crates. Same rule as AkurAI-Framework `AGENTS.md` principle #1. |
| 2 | **Frontend is the Framework's no-build native-ESM stack.** SSR templates (`{{ x }}` / `{% if %}` / `{% for %}` / `{% include %}`), `signals.js` / `islands.js` / `spa.js` reactivity, CSS custom-property design system, dark-first AkurAI theme (`--bg #060912`, `--accent #5b8cff → #7af0d0`). No bundler, no React, no TypeScript. |
| 3 | **Login via AkurAI IDP** (`https://auth.olibuijr.com`, port 3500 on `akurai-mail`). Standard authorization-code OIDC flow, session cookie `notes_session=…`. Allowlist: `olibuijr@olibuijr.com`. |
| 4 | **Semantic search via on-device embeddings.** Use a small CPU embedding model behind an OpenAI-compatible `/v1/embeddings` endpoint on `127.0.0.1`; `akurai-vector::embed` already speaks that protocol over plain HTTP. Embeddings persisted as f32 little-endian bytes via `akurai-vector::encode`; similarity = `akurai_vector::cosine`; top-k via `akurai_vector::rank`. |
| 5 | **HTTPS MCP server** available at `https://akurai-notes.olibuijr.com/mcp` — same binary, forked HTTP listener on a second port whose only route is `POST /mcp` doing JSON-RPC 2.0 over HTTP (Streamable-HTTP transport; the CRM `crm-mcp` crate is the 1:1 reference). |
| 6 | **`deploy.sh`** is the deep version of the AkurAI-Framework release engine (gate → lockstep bump → dual changelog cut → commit + tag → push → `akurai-ec2` live publish), NOT the stripped CRM variant. Full text in `E07-deploy-versioning-changelog.md`. |
| 7 | **Versioning starts at `0.0.1`** in both `VERSION` and `Cargo.toml` `[workspace.package] version`. Every release is `./deploy.sh patch` → `0.0.2`, `0.0.3`, … Pre-1.0, minor versions may break (matches Framework convention). |
| 8 | **Keep-a-Changelog `CHANGELOG.md`** with `## [Unreleased]` always on top; `deploy.sh` cuts it into `## [X.Y.Z] - <date>` on release. |
| 9 | **Reference repos cloned into `.references/`** for UX inspiration only — never imported into the build. Initial set: `elie222/oblivion` + the top-4 open-source note apps (see `E04-notes-core-and-storage.md`). |
| 10 | **Icons via GPT-5.5** through `codex exec` — same pattern used by other AkurAI apps (see `E02-landing-page.md`). |
| 11 | **Registered on `AkurAI-Platform`** as a new app in the "Knowledge" category (`platform suite` entry in `~/Projects/AkurAI-Platform/backend/page.json`). |

## Topology

| Setting | Value |
|---------|-------|
| Repo | `github.com/olibuijr/AkurAI-Notes` (private, `gh repo create`) |
| Local checkout | `/home/olafurbui/Projects/AkurAI-Notes` |
| Public URL | `https://akurai-notes.olibuijr.com` |
| MCP URL | `https://akurai-notes.olibuijr.com/mcp` |
| Runtime host | `akurai-mail` (AWS EC2, `mail.olibuijr.com`, `3.94.46.219`) |
| App port | `127.0.0.1:8099` |
| MCP port | `127.0.0.1:8100` (optional fork; or same process, route `/mcp` on 8099) |
| Embeddings | `127.0.0.1:8081` — separate systemd unit `akurai-notes-embed.service` running `llama-server` (or similar) with `Qwen3-Embedding-0.6B` or `bge-small-en` GGUF |
| systemd unit | `akurai-notes.service` |
| Binary | static musl `target/x86_64-unknown-linux-musl/release/akurai-notes` |
| Runtime env | `/etc/akurai-notes/notes.env` |
| Runtime data | `/var/lib/akurai-notes` (B+tree `notes.db`, WAL) |
| IDP issuer | `https://auth.olibuijr.com` |
| IDP client_id | (created via IDP admin API — see `E03-idp-sso-login.md`) |
| Redirect URI | `https://akurai-notes.olibuijr.com/auth/callback` |
| TLS | Let's Encrypt via `akurai-ec2 tls akurai-notes.olibuijr.com` |
| DNS | managed at 1984.is — add `akurai-notes` A record → `3.94.46.219` |

## Stack (one screen)

```
                ┌─────────────────────────────────────────┐
                │            user's browser               │
                │  native-ESM SPA on AkurAI-Framework    │
                │  (signals.js / islands.js / spa.js)      │
                └───────────────────┬─────────────────────┘
                                    │  HTTPS (nginx term.)
                ┌───────────────────▼─────────────────────┐
                │  akurai-notes  (static musl binary)     │
                │  ├─ akurai-http server     :8099         │
                │  ├─ notes-cli  (serve / mcp / seed / -V) │
                │  ├─ notes-api   (REST + SSR + auth)      │
                │  ├─ notes-core  (notes/notebooks/tags)  │
                │  └─ notes-mcp  (POST /mcp JSON-RPC)     │
                └────┬──────────────────────┬──────────────┘
                     │ plain HTTP             │ plain HTTP
                     ▼                        ▼
        ┌──────────────────────┐   ┌─────────────────────────┐
        │  akurai-idp  :3500   │   │ akurai-notes-embed :8081│
        │  OIDC + /userinfo    │   │ OpenAI-compat /v1/       │
        │                      │   │   embeddings (CPU GGUF)  │
        └──────────────────────┘   └─────────────────────────┘

  Local crates path-include from ../../AkurAI-Framework/crates/* — NOT vendored.
  The Notes repo only contains: site/, crates/{notes-core,notes-api,notes-cli,
  notes-mcp}/, deploy.sh, VERSION, CHANGELOG.md, AGENTS.md, .references/.
```

## Epics

| # | Epic | Status |
|---|------|--------|
| E01 | [Scaffold + Framework bootstrap + repo](epics/E01-scaffold-and-framework-bootstrap.md) | planned |
| E02 | [Landing page + GPT-5.5 icons](epics/E02-landing-page.md) | planned |
| E03 | [AkurAI IDP SSO login](epics/E03-idp-sso-login.md) | planned |
| E04 | [notes-core + storage + collections schema](epics/E04-notes-core-and-storage.md) | planned |
| E05 | [On-device embeddings + semantic search](epics/E05-embeddings-and-semantic-search.md) | planned |
| E06 | [HTTPS MCP server at /mcp](epics/E06-mcp-server-https.md) | planned |
| E07 | [deploy.sh release engine + versioning + changelog](epics/E07-deploy-versioning-changelog.md) | planned |
| E08 | [Register on AkurAI-Platform + verify live](epics/E08-register-on-platform.md) | planned |

## Hand-off

This plan is written for **DeepSeek v4 Flash** as the implementer. Every epic
lists exact reference files to read and one concrete seed to emit. Read
[CODE-PATTERNS.md](CODE-PATTERNS.md) and [HANDOFF.md](HANDOFF.md) first.
Do not start coding on an epic without reading the listed reference paths —
they contain the canonical idiom for that subsystem.