docs: bridge README to the TypeScript rebuild; banner the Python-era docs

The README had zero mentions of the TypeScript implementation -- on the branch proposing to make it the main line, a reader (including PR #989's reviewers) would find only the Python product. A bridge section near the top now says what the rebuild is, its status (under independent review; do not put irreplaceable secrets in it yet), and where the migration guide, the vault/identity spec, and the cutover plan live. Deliberately a bridge, not a rewrite: everything below it still accurately describes the Python version, which is what install.sh installs today. Advertising the TS implementation as the product before its review lands would be docs describing an aspirational state -- the exact failure mode this branch has been stamping out. The 14 Python-era planning docs most likely to mislead (tui_v2/v3, index0/atlas, semantic) carry a one-line legacy banner so a reader can tell a historical record from a living document. The full TS-first rewrite -- README, landing page, docs triage, CI scoping, dependabot config -- is specced as a merge-day checklist under the cutover item in TODO.md, so main never advertises a stale product in either direction. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Tkj4rzKBA3uhfgk7kqjsb8
2026-10-27 07:52:03 +00:00 · 2026-08-18 14:07:53 -04:00
1 parent 0482bc3dfd
commit eb67dac576
@@ -8,6 +8,37 @@

 ---

+## 🚧 The TypeScript rebuild (this branch)
+
+SeedPass has been rebuilt from the ground up in **TypeScript** — a browser-safe
+core (`js/packages/core`), a CLI (`js/packages/cli`, installed as
+`seedpass-js`), and an interactive TUI mirroring the classic menus. It reads
+and writes the **same vaults, backups, and Nostr snapshots** as the Python
+implementation documented below: `scripts/cross_impl_check.py` (38 checks, in
+CI) has each implementation open the other's vaults, derive identical secrets,
+and restore the other's backups on every change.
+
+**Status: feature-complete for daily use, under independent security review
+([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)) — do not put
+irreplaceable secrets in it until that review lands.** After the review, the
+TypeScript implementation becomes the main line and Python retires to
+`legacy/` as the reference implementation.
+
+Where to look:
+
+- [`docs/typescript_migration_guide.md`](docs/typescript_migration_guide.md) —
+  using `seedpass-js` against an existing vault (short version: point it at
+  `~/.seedpass` and it works; there is no migration step)
+- [`docs/seedpass_vault_identity_spec.md`](docs/seedpass_vault_identity_spec.md) —
+  the shared vault & identity format both implementations conform to
+- [`docs/typescript_cutover_plan.md`](docs/typescript_cutover_plan.md) — the
+  gates for the cutover and their current state
+
+Everything below this line documents the **Python implementation** — still
+what `install.sh` installs today, and accurate until the cutover.
+
+---
+
 **⚠️ Disclaimer**

 This software was not developed by an experienced security expert and should be used with caution. There may be bugs and missing features. Each vault chunk is limited to 50 KB and SeedPass periodically publishes a new snapshot to keep accumulated deltas small. The security of the program's memory management and logs has not been evaluated and may leak sensitive information. Loss or exposure of the parent seed places all derived passwords, accounts, and other artifacts at risk.
@@ -222,7 +222,31 @@ before and after each was confirmed. Ordered by severity.
 - [ ] Fold the CLI bundle's `.sha256` into the `release-integrity` signing
      workflow (the remaining item of cutover gate 6).
 - [ ] Merge to `main` and move the Python implementation to `legacy/`. Blocked
-      by the independent review above.
+      by the independent review above. **Merge-day checklist** (do these in
+      the same window, so main never advertises a stale product):
+  - [ ] **README rewrite, TS-first.** Install = the `seedpass-js` bundle;
+        features/architecture describe the TypeScript implementation; the
+        Python content moves to `legacy/README.md` with a pointer. The 🚧
+        bridge section added 2026-08-18 comes out (it exists precisely
+        because the rewrite would have been premature before review).
+  - [ ] **Landing page (`landing/`).** Install command switches off the
+        Python `install.sh` (or install.sh itself learns to install the TS
+        bundle); features/architecture copy updated; main/beta branch toggle
+        reconsidered (post-cleanup there is one line of development); drop
+        the `_pgbackup`/`_pginfo` Pinegrow artifacts. Verify where the live
+        site deploys from before assuming edits take effect.
+  - [ ] **Docs triage.** Python-era planning docs (the 14 bannered
+        2026-08-18: tui_v2/v3, index0/atlas, semantic) move under
+        `docs/legacy/` or keep their banners; living docs (vault/identity
+        spec, migration guide, security model, cutover plan) stay top-level;
+        `docs/README.md`/index updated to say which is which.
+  - [ ] **Branch/repo hygiene.** Fast-forward or delete `beta` (it is fully
+        contained in the merged history); revisit `dependabot.yml` (its pip
+        entries target the retiring Python deps); CHANGELOG entry for the
+        cutover.
+  - [ ] **CI.** `python-ci`/`tests`/`briefcase` workflows follow the Python
+        code to `legacy/` (or are scoped down); `ts-parity` and
+        `release-integrity` become the primary gates.

 ### Unbuilt milestones

@@ -1,5 +1,7 @@
 # Atlas, Search, and Graph Integration Plan (2026-03-05)

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: In Progress  
 Branch target: `beta`  
 Depends on:
@@ -1,5 +1,7 @@
 # Index0 Atlas Execution Plan (2026-03-05)

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: In Progress  
 Branch target: `beta`  
 Scope: Core index payload, Nostr sync, hierarchy navigation, future KB and agent workflows
@@ -1,5 +1,7 @@
 # Index0 Phase 0 Implementation Spec (2026-03-05)

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: In Progress  
 Branch target: `beta`  
 Depends on: `docs/index0_atlas_execution_plan_2026-03-05.md`
@@ -1,5 +1,7 @@
 # Semantic Vector Index Integration Plan

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: In Progress (updated 2026-03-02)  
 Branch target: `beta`  
 Scope: Legacy TUI + Textual TUI v2 + CLI + API
@@ -1,5 +1,7 @@
 # TUI v2 Cutover Decision Memo

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Date: March 2, 2026  
 Branch: `beta`  
 Decision owner: SeedPass maintainers
@@ -1,5 +1,7 @@
 # TUI v2 Integration Execution Plan (2026-03-02)

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: Proposed and ready to execute  
 Branch target: `beta`  
 Owner: TUI v2 parity track
@@ -1,5 +1,7 @@
 # TUI v2 Large-Vault Validation

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: Added on `beta` (March 1, 2026).

 This document defines a deterministic, CI-like validation pass for TUI v2 behavior at large vault sizes.
@@ -1,5 +1,7 @@
 # TUI v2 Legacy Parity Matrix

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: In progress (2026-03-02)  
 Branch: `beta`

@@ -1,5 +1,7 @@
 # TUI v2 Mockup Gap Audit (2026-03-02)

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: Active  
 Scope: visual and interaction parity between `UI_mockups/PNG/*.png` and current Textual TUI v2 runtime

@@ -1,5 +1,7 @@
 # TUI v2 Parity Backlog

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: Active tracking on `beta` (updated 2026-03-01).

 This document captures parity learnings and the remaining implementation queue
@@ -1,5 +1,7 @@
 # TUI v2 Parity Checklist

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: Parity-complete on `beta` (updated 2026-03-02).

 This checklist tracks readiness to switch default interactive mode from legacy TUI to `seedpass tui2`.
@@ -1,5 +1,7 @@
 # TUI v2 Plan (Legacy Reference)

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 > **NOTICE:** This document is now for logic reference only. 
 > TUI v2 development has been paused in favor of the **TUI v3 Scratch Rebuild** to solve monolithic file issues and layout crowding.
 > Please see **[TUI v3 Plan](tui_v3_plan.md)** for the current roadmap.
@@ -1,5 +1,7 @@
 # TUI v2 UI Refresh Plan (Mockup-Aligned)

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Status: Active (2026-03-02)  
 Branch target: `beta`  
 Primary references: `UI_mockups/PNG/*.png`, `UI_mockups/SeedPass_UI-Board.pdf`
@@ -1,5 +1,7 @@
 # TUI v3 Modular Architecture & Parity Plan

+> **Legacy (Python implementation).** This document describes the Python version, which retires to `legacy/` after the TypeScript cutover ([PR #989](https://github.com/PR0M3TH3AN/SeedPass/pull/989)). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.
+
 Last updated: 2026-03-06  
 Branch target: `beta`  
 Status: Active (Default UI / parity hardening in progress)