Epics 12–17: public API, Inbox capture funnel, one-verb assign, export

[Seanathon]

Capture → Curate → Archive: public API + Inbox triage + export

This branch lands 8 stories from the v2 wave (Epics 12–17), turning board-oss from a single-surface app into one with a token-authed public API, a capture funnel (Inbox + bookmarklet), one-verb assignment with tiered enrichment, and data export. Every change is additive — the no-regression constraint (NFR-BC) is enforced by a dedicated test in each story, the single-FK item.board_id is preserved throughout, and existing boards/items/assets are untouched.

Tests: npm test → 423 pass / 0 fail (was 350 on main), 76 suites.

Stories included

#	Story	What it adds
12.1	Static bearer-token auth	An encapsulated /api/v1 plugin guarded by BOARD_API_TOKEN (SHA-256 + timingSafeEqual, fail-closed) + scoped CORS
12.2	CRUD item + board API	POST/GET/PATCH/DELETE /api/v1/items, GET /api/v1/boards — reuses existing helpers, no parallel write path
13.1	Inbox board + cheap capture	A typeless Inbox seed board; capture runs cheap (no AI takeaway) — the expensive enrichment is earned on assignment
13.2	Bookmarklet	A GET /bookmarklet help page → one-click save of the current tab to your Inbox
14.1	Cheap-vs-earned tier	Formal tier contract on the enrichment pipeline (the seam 14.2 builds on)
14.2	Move/assign (the one verb)	POST /api/v1/items/assign — single-FK move then earned enrichment against the target board
14.3	Inbox suggestion chip	Read-only AI board suggestion + additive override-signal store + pure chip/picker renderer
17.1	Export	POST /skills/export → full JSON (round-trippable) or a Netscape bookmark file

One new dependency: @fastify/cors@11.2.0 (passed the supply-chain score gate).

---

How the new features work

1. The token-authed API (/api/v1)

A new versioned surface, mounted as an encapsulated Fastify plugin so its bearer guard + CORS structurally cannot leak onto the existing SPA/legacy/collections routes. Set a token to enable it:

BOARD_API_TOKEN=$(openssl rand -hex 32)        # your secret; the server stores only its SHA-256 hash
BOARD_API_CORS_ORIGINS=https://your-extension  # optional; comma-separated; default = no cross-origin

With no token configured, the /api/v1 surface fails closed (401 on everything). The plaintext token is never logged, serialized, or written to board.db.

2. Capture funnel → Inbox

• A typeless Inbox board is now seeded automatically (idempotent — existing DBs gain it on next boot, nothing else changes).
• A POST /api/v1/items with no boardId lands the item in the Inbox.
• Inbox capture is cheap: it fetches title/screenshot but does not spend an LLM call. The expensive descriptor-driven takeaway is earned when you assign the item to a typed board.

3. The one assign verb

POST /api/v1/items/assign {itemIds, boardId} is the single code path for promotion (the AI composer will reuse it too). It moves item.board_id first, then fires the earned enrichment against the target board's schema. It's idempotent (same-board re-assign is a no-op), reversible (assign back to Inbox is a safe no-op), and batch-capable.

4. AI suggestion + override signal

GET /api/v1/items/:id/suggestion returns a suggested home board (read-only; requires an LLM provider, else null → manual picker). POST /api/v1/suggestions/override records suggested-vs-chosen as a future-quality signal in a new additive table — never mutating item/board rows.

5. Export

POST /skills/export {format} serializes everything read-only: json (every board+descriptor, item, asset reference — re-ingestible via the importer) or netscape (a browser/linkding-compatible bookmark file). Binary assets are referenced by path+hash; copy your screenshots/ dir separately.

---

Manual testing: UI vs API

✅ Usable in the UI right now

• Inbox board — start the app and open the collection switcher; Inbox appears as a third board. Anything captured without a target board shows up here (cheap metadata only).
• Bookmarklet — visit http://localhost:3141/bookmarklet, paste your BOARD_API_TOKEN, and drag the "📥 Save to Board" button to your bookmarks bar. Click it on any web page → it saves that tab to your Inbox and shows a transient confirmation without navigating you away. (The token is filled in entirely in your browser; the page never sends it to the server.)

🔌 Usable via the API (curl / extension / PWA)

Run the server with a token, then (default port 3141):

TOKEN=your-token
BASE=http://localhost:3141

# auth probe
curl -s $BASE/api/v1/ping -H "Authorization: Bearer $TOKEN"            # {"ok":true}

# capture to the Inbox (no boardId)
curl -s -X POST $BASE/api/v1/items -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"url":"https://example.com"}'

# list (newest-first, filterable)
curl -s "$BASE/api/v1/items?board=inbox&limit=20" -H "Authorization: Bearer $TOKEN"

# board list for targeting
curl -s $BASE/api/v1/boards -H "Authorization: Bearer $TOKEN"

# assign (move + earned enrichment); use a real item id + target board
curl -s -X POST $BASE/api/v1/items/assign -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"itemIds":["<id>"],"boardId":"library"}'

# patch notes / favorite
curl -s -X PATCH $BASE/api/v1/items/<id> -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"notes":"hello","favorite":true}'

# AI suggestion (null unless an LLM provider is configured)
curl -s $BASE/api/v1/items/<id>/suggestion -H "Authorization: Bearer $TOKEN"

# export (no auth — the generic skills route)
curl -s -X POST $BASE/skills/export -H 'Content-Type: application/json' -d '{"format":"json"}'
curl -s -X POST $BASE/skills/export -H 'Content-Type: application/json' -d '{"format":"netscape"}'

Try the guards too: omit the header → 401; junk ?limit=abc → falls back, no 500; DELETE an unknown id → 404.

🚧 Staged (not yet wired into the SPA)

The suggestion chip / manual board-picker in the Inbox list is delivered as a tested pure renderer + the two endpoints above, but the browser event-glue (tap → POST /api/v1/items/assign, and mounting the control into the Inbox list) is staged with the flat-JSON→SQLite SPA cutover — consistent with how Epic 8 staged its DOM wiring. So suggestion/assign are exercisable via the API today, not yet via a click in the Inbox. Same for an export button (export works via the endpoint).

🧭 Not in this branch (out of scope for this loop)

13.3 (PWA share-target), 13.4 (browser extension), and Epic 15 (AI composer / saved views) — Epic 15 stays planned pending confirmation of the view-definition design. 14.2's assignItems is the single path the composer will reuse.

---

Notes for review

• Each story file in docs/bmad/stories/ is at Status: review with a full Dev Agent Record (decisions + the party-mode review findings that were fixed before commit).
• Reviews caught + fixed: a Host-header reflected-XSS on the bookmarklet page, a NaN-param 500 on the list endpoint, a confounded cheap-tier test, the missing no-auto-assign regression, and an undeclared staged-DOM boundary.