Kanban — per-board seed vault

Status: Design approved in chat · 2026-11-05
Scope: Interactive Module Kanban (html/kanban.html + html/js/kanban.js / board-store.js) — save and restore per-project seeds with datetime labels; browser vault + Export/Import.
Out of scope (v1): Auto-snapshots on every edit · rewriting kanban-seed.js / bumping bible seedVersion from the UI · dedicated Seeds page · Gantt/Bugs UI changes (they keep reading live board storage)

Authority: docs/21-module-kanban.md · seed builder build_pb_kanban.py · live seed html/js/kanban-seed.js

---

1. Problem

Today Reset to seed only restores the single baked-in bible seed (TFA_KANBAN_SEED, currently seedVersion 41) for selected project(s). Older bible bumps are not archived in the pack — there is no picker of historical seeds. Users need:

1. Save a new seed from the current working board (per board).
2. Restore by picking a seed on a per-board basis (not only “latest bible”).
3. Label seeds with date/time (optional short note).
4. Persist in localStorage and support Export/Import of the vault.

---

2. Decisions locked

Topic	Lock
Approach	Extend existing toolbar (Save + Restore); no new page in v1
Save source	Snapshot of current working board only
Restore modes	Ask each time: Full replace or Soft merge
Scope of mutate	Selected project(s) only; other boards untouched
Bible seed	Always offered as Bible seed (vN) when that project exists in TFA_KANBAN_SEED; not deletable
Labels	Default local datetime; optional short note appended
Storage	localStorage vault + Export/Import JSON (sibling to board export)
Cap	No hard cap; warn in UI if a board exceeds ~50 snapshots

---

3. Data model

New key: tfa-pb-kanban-board-seeds-v1 (separate from live board tfa-pb-kanban-board-v13).

{
  "version": 1,
  "byProjectId": {
    "demo": [
      {
        "id": "seed_…",
        "createdAt": "2026-11-05T16:54:00.000Z",
        "label": "2026-11-05 10:54 — before MM cut",
        "source": "working",
        "project": { "id": "demo", "name": "Demo", "modules": [], "trash": [] }
      }
    ]
  }
}

• project is a deep clone of one project (modules, trash, name, id) — not the full multi-project state.
• Display label: format createdAt in local time; if user note present, append — {note}.
• Bible entry is not stored in the vault; it is synthesized at restore time from TFA_KANBAN_SEED.

Export/Import file: JSON of the vault (version + byProjectId). Import merges by seed id — skip duplicates by default. Invalid JSON → alert, no write.

---

4. UI / flows

Toolbar

Control	Behavior
Save board seed (new)	Active board only → modal → confirm → append vault entry
Restore seed (rename from Reset to seed)	Pick board(s) → pick seed per board → Full replace / Soft merge → ack + confirm

Save board seed

1. Current project name shown.
2. Datetime prefilled; optional note field.
3. On confirm: deep-clone currentProject() into byProjectId[projectId] (newest first).

Restore seed

1. Multi-select boards (same pattern as today’s reset; default active checked).
2. Seed list for the focused/selected board: Bible seed (vN) first (if present in bake), then user snapshots newest-first.
3. Mode: Full replace | Soft merge.
4. Ack checkbox + confirm dialog naming board(s) and mode.
5. Light housekeeping in modal: delete selected user snapshot(s); Export seeds / Import seeds.

Apply semantics

Mode	Behavior
Full replace	Same as today’s reset: replace that project with a clone of the chosen seed’s project (or bible project); clears that board’s local placement/notes/trash as in the seed
Soft merge	Same spirit as ensureSeedModules: add missing cards; refresh tasks / name / phase / blocked / order from chosen seed; keep local column, notes, comments; for cinematic-benchmark, prune modules not in the chosen seed when that seed is treated as authoritative for the board

Push one board-level undo snapshot before apply when the existing undo path supports it.

---

5. Edge cases

Case	Behavior
Empty user vault	Restore still offers Bible seed when available
Custom board (no bible project)	No Bible row; Save/Restore user snapshots only
Soft merge + local-only cards	Keep local-only cards; only add/refresh from seed
Full replace	Drop cards not in chosen seed
Gantt / Bugs	Unchanged readers of live board storage; restore updates project in place
Large vault	Warn at ~50 snapshots per board; no forced delete

---

6. Files likely touched

• html/js/kanban.js — Save / Restore modals, vault load/save, apply modes
• html/js/board-store.js — optional helpers (clone project, undo hook) if cleaner there
• html/kanban.html + build_pb_kanban.py shell — toolbar button labels
• docs/21-module-kanban.md — document Save / Restore / Export-Import seeds
• html/css/kanban.css — minimal modal list styles if needed

Bible generator build_pb_kanban.py / kanban-seed.js content unchanged by this feature (except toolbar label in the HTML shell if generated there).

---

7. Testing checklist

• Save on Demo → vault entry with datetime; Full game vault unchanged
• Restore Demo → Bible Full replace; Demo Soft merge from a named snapshot; Website untouched
• Export vault → clear vault key → Import → entries return; duplicate ids skipped
• Custom board: Save + Restore only (no Bible row)
• Delete user snapshot; Bible row not deletable
• Soft merge keeps column/notes; Full replace matches prior reset behavior

---

8. Doc follow-up

After implement: update docs/21-module-kanban.md What you can edit / Have to replace “Reset to seed” with Save board seed + Restore seed (Full replace / Soft merge) and note the vault key + Export/Import.