From eb67dac5764e4927d95670b055838ad4ddd7dcfb Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN Date: Tue, 18 Aug 2026 14:07:53 -0400 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01Tkj4rzKBA3uhfgk7kqjsb8 --- README.md | 31 +++++++++++++++++++ TODO.md | 26 +++++++++++++++- ...earch_graph_integration_plan_2026-03-05.md | 2 ++ .../index0_atlas_execution_plan_2026-03-05.md | 2 ++ docs/index0_phase0_spec_2026-03-05.md | 2 ++ docs/semantic_vector_index_plan.md | 2 ++ docs/tui_v2_cutover_decision.md | 2 ++ ...2_integration_execution_plan_2026-03-02.md | 2 ++ docs/tui_v2_large_vault_validation.md | 2 ++ docs/tui_v2_legacy_parity_matrix.md | 2 ++ docs/tui_v2_mockup_gap_audit_2026-03-02.md | 2 ++ docs/tui_v2_parity_backlog.md | 2 ++ docs/tui_v2_parity_checklist.md | 2 ++ docs/tui_v2_plan.md | 2 ++ docs/tui_v2_ui_refresh_plan.md | 2 ++ docs/tui_v3_plan.md | 2 ++ 16 files changed, 84 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 623532ff..1e1d42e1 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/TODO.md b/TODO.md index 08827ce2..6c47bd86 100644 --- a/TODO.md +++ b/TODO.md @@ -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 diff --git a/docs/atlas_search_graph_integration_plan_2026-03-05.md b/docs/atlas_search_graph_integration_plan_2026-03-05.md index 16a48e9a..1b77b3a4 100644 --- a/docs/atlas_search_graph_integration_plan_2026-03-05.md +++ b/docs/atlas_search_graph_integration_plan_2026-03-05.md @@ -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: diff --git a/docs/index0_atlas_execution_plan_2026-03-05.md b/docs/index0_atlas_execution_plan_2026-03-05.md index 76ce3e48..8b5548d8 100644 --- a/docs/index0_atlas_execution_plan_2026-03-05.md +++ b/docs/index0_atlas_execution_plan_2026-03-05.md @@ -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 diff --git a/docs/index0_phase0_spec_2026-03-05.md b/docs/index0_phase0_spec_2026-03-05.md index 6101df4b..6e5cc564 100644 --- a/docs/index0_phase0_spec_2026-03-05.md +++ b/docs/index0_phase0_spec_2026-03-05.md @@ -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` diff --git a/docs/semantic_vector_index_plan.md b/docs/semantic_vector_index_plan.md index c709a7d4..e9038b11 100644 --- a/docs/semantic_vector_index_plan.md +++ b/docs/semantic_vector_index_plan.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 diff --git a/docs/tui_v2_cutover_decision.md b/docs/tui_v2_cutover_decision.md index 53d21096..329c07b9 100644 --- a/docs/tui_v2_cutover_decision.md +++ b/docs/tui_v2_cutover_decision.md @@ -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 diff --git a/docs/tui_v2_integration_execution_plan_2026-03-02.md b/docs/tui_v2_integration_execution_plan_2026-03-02.md index 032c113a..f7d845f2 100644 --- a/docs/tui_v2_integration_execution_plan_2026-03-02.md +++ b/docs/tui_v2_integration_execution_plan_2026-03-02.md @@ -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 diff --git a/docs/tui_v2_large_vault_validation.md b/docs/tui_v2_large_vault_validation.md index 26730602..7359fb0d 100644 --- a/docs/tui_v2_large_vault_validation.md +++ b/docs/tui_v2_large_vault_validation.md @@ -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. diff --git a/docs/tui_v2_legacy_parity_matrix.md b/docs/tui_v2_legacy_parity_matrix.md index 2b9bb905..ca2beae6 100644 --- a/docs/tui_v2_legacy_parity_matrix.md +++ b/docs/tui_v2_legacy_parity_matrix.md @@ -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` diff --git a/docs/tui_v2_mockup_gap_audit_2026-03-02.md b/docs/tui_v2_mockup_gap_audit_2026-03-02.md index d8c39618..9bac1c54 100644 --- a/docs/tui_v2_mockup_gap_audit_2026-03-02.md +++ b/docs/tui_v2_mockup_gap_audit_2026-03-02.md @@ -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 diff --git a/docs/tui_v2_parity_backlog.md b/docs/tui_v2_parity_backlog.md index 1dbdd978..82fb41d5 100644 --- a/docs/tui_v2_parity_backlog.md +++ b/docs/tui_v2_parity_backlog.md @@ -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 diff --git a/docs/tui_v2_parity_checklist.md b/docs/tui_v2_parity_checklist.md index d981456d..2d2f74f7 100644 --- a/docs/tui_v2_parity_checklist.md +++ b/docs/tui_v2_parity_checklist.md @@ -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`. diff --git a/docs/tui_v2_plan.md b/docs/tui_v2_plan.md index af140f4a..08a3bc0c 100644 --- a/docs/tui_v2_plan.md +++ b/docs/tui_v2_plan.md @@ -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. diff --git a/docs/tui_v2_ui_refresh_plan.md b/docs/tui_v2_ui_refresh_plan.md index ce66c1d7..31cf6d5a 100644 --- a/docs/tui_v2_ui_refresh_plan.md +++ b/docs/tui_v2_ui_refresh_plan.md @@ -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` diff --git a/docs/tui_v3_plan.md b/docs/tui_v3_plan.md index c74ece12..ab6c136e 100644 --- a/docs/tui_v3_plan.md +++ b/docs/tui_v3_plan.md @@ -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)