Capture funnel finished + meaning-preserving archival + AI composer (Epics 13/16/15)

[Seanathon]

Capture funnel finished + Meaning-preserving archival + AI composer (views, not copies)

This branch lands 8 stories across three v2 epics, building on the Epics 12–14 spine already on main. Everything is additive — the no-regression constraint (NFR-BC) is enforced by a dedicated test per story, the single-FK item.board_id is preserved, and existing boards/items/assets are untouched.

Tests: npm test → 492 pass / 0 fail (was 423 on main), 0 regressions.

Stories included

#	Story	What it adds
13.3	PWA + Web Share Target	Installable PWA (manifest.webmanifest + service worker) and a POST /share handler so any app's share sheet one-taps a URL into the Inbox
13.4	Browser-extension review lane	A pure, token-authed API client + an MV3 popup that triages the Inbox via the AI suggested-board chip (one-tap confirm → the assign verb)
16.1	Snapshot asset (SingleFile)	A kind='snapshot' self-contained-HTML asset captured on the existing single-Chrome sidecar, so a curated link survives the page going down
16.2	Opt-in archival trigger	A default-off archive_on_promote board flag + a per-item archive action that fire the snapshot on the one assign verb
16.3	Archive footprint + backfill	GET /api/archive/footprint (snapshot disk usage) + a serial, idempotent archive:backfill CLI
15.1	View-definition model	A view table — a read-only cross-board lens (filter + optional pin/order overlay), never a copy
15.2	AI collection composer	A propose-only skill that proposes home-board assignments and/or a view; accept reuses the one assign verb + the view model
15.3	Materialize view → board	The copy-on-write escape hatch: copy a lens's items into a real board (assets reused by hash, source untouched)

One new dependency: single-file-cli@2.0.83 — added as an optionalDependency (it's AGPL-3.0; lazily import()-ed only when an archive runs, so board-oss core never loads AGPL code on a normal path). Passed the Socket score gate (supply_chain 0.81 / quality 0.99 / vuln 1.00 / maintenance 0.93).

---

How the new features work

Capture funnel (Epic 13, now complete)

• PWA / share target (13.3): the manifest declares a share_target → POST /share; the handler extracts the URL (from url, or the first URL in shared text/title) and saves it to the Inbox via the same cheap-capture create path as the API — no second capture path. The service worker is additive and passes /api, /events (SSE), /screenshots, /share straight through, so it can't buffer the live-status stream.
• Browser extension (13.4): an MV3 popup (extension/) over a pure api-client.js (no DOM) that speaks only the /api/v1/* contracts. Each recent Inbox item shows its AI suggested-board chip; tapping it promotes via POST /api/v1/items/assign. Degrades to a manual board picker when there's no suggestion. The token lives in chrome.storage.local, sent only as a Bearer header (a remote instance must be https).

Meaning-preserving archival (Epic 16)

• Snapshot (16.1): runs through the existing concurrency-1 Chrome sidecar (never a second Chromium), with a per-snapshot byte cap + timeout, hash-dedupe, and graceful degradation — a failed archival never flips a curated item to error (status-neutral).
• Opt-in (16.2): off by default. Set a board's archive_on_promote flag (additive descriptor field) or call the per-item archive action — the snapshot fires on the one assign verb, alongside the AI takeaway (which lives on the item, not a copy).
• Footprint + backfill (16.3): see how much disk archives use; backfill existing curated items serially through the one Chrome (idempotent by item id — safe to re-run/resume).

AI composer — views, not copies (Epic 15)

• View (15.1): a "composed board" is a saved lens — a row of {filter, order?, captions?} that resolves dynamically (new matches auto-appear) across boards, read-only. Items keep one canonical home board.
• Composer (15.2): describe a board and the AI proposes home-board assignments and/or a view — a reviewable proposal that persists nothing until you accept. Accept reuses the one assign verb + the view model; bounded validate-and-repair; degrades to a manual builder with no AI.
• Materialize (15.3): when you want to hand-prune, copy a view into a real board — new rows, asset files reused by hash (no duplicate bytes), source untouched. Divergence is a deliberate choice.

---

Manual testing: UI vs API/CLI

✅ Usable in the UI / browser

• Inbox + share target: load the app, then POST /share (or, on a real installed PWA, share a page) → the item lands in the Inbox.
• Browser extension: load extension/ as an unpacked MV3 extension, set your instance URL + BOARD_API_TOKEN in its options, open the popup on any tab → save + triage. (Real install + OS share-sheet are manual/mobile QA — see "Staged" below.)

🔌 Usable via the API / CLI

TOKEN=your-token; BASE=http://localhost:3141
# share-to-Inbox (no auth; same-origin handler)
curl -s -X POST $BASE/share -H 'content-type: application/x-www-form-urlencoded' --data 'url=https://example.com'
# per-item archive (opt-in archival, 16.2)
curl -s -X POST $BASE/api/v1/items/<id>/archive -H "Authorization: Bearer $TOKEN"   # 202 / 404 / 422
# archive footprint (16.3)
curl -s $BASE/api/archive/footprint                                                  # {totalBytes,count}
# serial backfill (16.3) — stop the server first (concurrency-1 is per-process)
npm run archive:backfill
# composer (15.2) — propose-only; needs an LLM provider, else returns a draft
curl -s -X POST $BASE/skills/compose-collection -H 'content-type: application/json' -d '{"description":"a board about retrieval"}'

🚧 Staged / manual QA (documented per story, not claimed green)

• PWA install + SW-vs-SSE runtime + OS share-sheet (13.3) — browser/OS-level, verified by inspection + live curl; the node suite proves additive serving + route preservation.
• SingleFile CDP wiring (16.1) — the default driver (dynamic import + backEnd:'cdp' against the existing Chrome) is inspection/manual-verified; the suite fakes the capture and proves the asset/dedupe/degradation/no-regression logic.
• Composer & view SPA mounting (15.2/15.3) — the read-model, resolver, propose/accept primitives are tested at the function level; mounting them in the SPA is staged DOM (the Epic 8 precedent).

---

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 fixed before commit).
• Reviews caught + fixed, among others: a snapshot-job nested-enqueue deadlock on the success path (16.1); a typed-error-union violation + non-atomic accept in the composer (15.2); the shared-file delete guard's key mismatch (15.3); a cleartext-token vector in the extension (13.4); plus several confounded/vacuous tests replaced with discriminating ones.
• Known follow-ups (documented, out of scope): an app-wide capture-layer SSRF denylist (pre-existing; affects every create path); deleteItemWithAssets resolves snapshots/* assets under the screenshots dir (Epic 16 didn't update the deleter); a materialized board's descriptor fields aren't editable (the fields:[] v1 choice).

[Seanathon]

Pushed two follow-up fixes to the batch's own code (from the post-batch backlog ticket):

• deleteItemWithAssets now cleans up snapshot assets — Epic 16 added snapshots/<id>.html but the deleter still resolved everything as basename-under-screenshots, orphaning archived .html on item/board delete. Now routes each asset to its dir by its stored path prefix; shared-file guard re-keyed on the full relative path. (b640655)
• archive:backfill refuses to run while the server is up — the single-Chrome/concurrency-1 guarantee is per-process; the CLI now probes the configured port and bails (override BOARD_ALLOW_CONCURRENT_CHROME=1), instead of only a doc warning. (10029b5)

Suite 497 pass / 0 fail. The app-wide SSRF denylist (the remaining substantive backlog item) is going up as its own follow-up PR since it's pre-existing and touches code already on main.