SeedPass/memory-update.md

# Memory Update (2026-03-01)

## Nostr backup failure observability
- `handle_post_to_nostr()` previously printed only a generic `❌ Sync failed…` when `sync_vault()` returned `None`, even if `nostr_client.last_error` had useful detail.
- `PasswordManager.sync_vault_async()` swallowed exceptions and returned `None` without reliably setting `nostr_client.last_error`, making root-cause diagnosis hard from CLI.

## Changes made
- Updated `sync_vault_async()` to copy exception text into `nostr_client.last_error` before returning `None`.
- Updated `handle_post_to_nostr()` to include `nostr_client.last_error` in user-visible failure output and log line when available.
- Added regression tests:
  - `test_handle_post_failure_shows_nostr_error`
  - `test_sync_vault_sets_last_error_on_exception`

## Testing note
- Could not run pytest in this environment because `pytest` is not installed (`python3 -m pytest` -> `No module named pytest`).

## Nostr namespace reset workflow
- Added Nostr Settings menu actions for profile-scoped reset operations:
  - `8. Reset Nostr sync state` clears `manifest_id`, `delta_since`, and `last_sync_ts` while preserving `nostr_account_idx`.
  - `9. Start fresh Nostr namespace (new key index)` increments `nostr_account_idx`, clears sync metadata, and reinitializes the Nostr client when available.
- This provides a first-class path for users who want to ignore legacy Nostr history and publish/retrieve only new data under current deterministic behavior.
- Added tests for both handlers and menu dispatch to prevent regressions.

## Documentation updates for Nostr reset workflow
- Added `docs/nostr_namespace_reset.md` documenting menu options `8` (reset sync state) and `9` (start fresh namespace), plus validation steps for robust publish/restore.
- Linked the new guide from `docs/nostr_setup.md`, `docs/README.md`, and root `README.md`.
- Exposed the guide in website docs navigation via `landing/docs.html` (`Nostr Namespace Reset`).

## Nostr sync failure after namespace increment
- Root-cause pattern: when profile `offline_mode` is enabled, `sync_vault_async()` exits early and previously returned `None` without a helpful message, so UI showed only `❌ Sync failed…`.
- Fixes:
  - `PasswordManager.sync_vault_async()` now sets `nostr_client.last_error` for early-return cases (`offline_mode`, missing encrypted index, and missing publish result).
  - `main.handle_post_to_nostr()` now explicitly reports offline mode when no detailed error is present.
- Regression tests added:
  - `src/tests/test_post_sync_messages.py::test_handle_post_failure_offline_mode_message`
  - `src/tests/test_background_vault_sync_paths.py::test_sync_vault_async_sets_offline_error`
- Verified with local venv:
  - `./.venv/bin/pytest -q src/tests/test_post_sync_messages.py`
  - `./.venv/bin/pytest -q src/tests/test_background_vault_sync_paths.py`

## Entry model expansion: document kind + universal date fields
- Added a new `document` entry kind across core enum, TUI, API, CLI, and agent secret resolution.
- Added universal `date_added` and `date_modified` fields for all entry kinds.
  - Creation now sets both fields.
  - Modification preserves `date_added` and updates `date_modified`.
  - Legacy entries are normalized in `_load_index()` by deriving date fields from `modified_ts`/`updated`.
- TUI now supports `Document` creation via a built-in line editor with basic commands (`p`, `a`, `i <n>`, `e <n>`, `d <n>`, `w`, `q`).
- Added document-specific display and edit flows in manager/display services.

## Sync/policy compatibility notes
- Updated deterministic merge kind matrix to include document fields (`content`, `file_type`) for equal-timestamp backfill behavior.
- Agent defaults now include `document` in non-private allow-kinds, and agent secret resolution returns document content for `document` entries.

## Tests and docs
- Added/updated tests for:
  - document entry roundtrip and CLI add command
  - universal date field presence/update semantics across all entry kinds
  - API create/modify behavior for `document`
  - large document Nostr sync roundtrip
- Added `docs/entry_types.md` and updated README/docs index and sync conflict docs.
- Verified with:
  - `./.venv/bin/pytest -q src/tests/test_cli_entry_add_commands.py src/tests/test_entry_add.py src/tests/test_entry_types_roundtrip.py src/tests/test_modify_entry_validation.py src/tests/test_api.py src/tests/test_api_new_endpoints.py src/tests/test_full_sync_roundtrip.py`
  - Result: `141 passed`.

## Document file import/export workflows
- Added document file I/O at core layer:
  - `EntryManager.import_document_file(path, ...)`
  - `EntryManager.export_document_file(index, output_path=None, overwrite=False)`
- Added TUI support:
  - `Add Entry > Document` now supports `New Document` and `Import Document File`.
  - Document entry actions now include `Export Document to File`.
- Added automation surfaces:
  - CLI: `entry import-document`, `entry export-document`
  - API: `POST /api/v1/entry/document/import`, `POST /api/v1/entry/{id}/document/export`
- Regression coverage added for core file roundtrip, CLI commands, and API endpoints.

## Agent document import/export commands
- Added dedicated agent CLI commands:
  - `seedpass agent document-import --file <path>`
  - `seedpass agent document-export <query>` (or `--entry-id`)
- Enforcement model for both commands:
  - Requires `--fingerprint` and non-interactive auth broker password resolution.
  - Denies unless policy `allow_export_import` is enabled.
  - Denies unless `document` kind is policy-allowed (`allow_kinds` / kind export check).
  - Supports scoped token enforcement with operation scopes (`import` for import, `export` for export).
  - Export honors approval gates when policy requires `export` approval.
  - Emits structured JSON responses and append-only audit events for granted/denied outcomes.
- Discovery updates:
  - Added `document_io` command hints to `agent bootstrap-context` payload.
  - Added `document_io` section to `seedpass capabilities --format json` security features.
- Added CLI tests for:
  - token-scoped agent document import success path
  - token-scoped agent document export success path
  - bootstrap context includes document command hints
- Environment note: could not run pytest in this shell because `pytest` is unavailable (`python3 -m pytest` reports module missing).

## Test environment note (2026-03-01)
- Repo `.venv` already had `pytest` and `typer`; upgraded to `pytest 9.0.2` and `typer 0.24.1`.
- New agent document I/O tests initially failed due mocked policy normalization (empty `rules` caused normalized `allow_kinds` to become empty).
- Fixed tests by adding explicit allow rule for `document` in mocked policies.
- Verification run:
  - `.venv/bin/pytest -q src/tests/test_document_file_io.py src/tests/test_cli_entry_add_commands.py src/tests/test_api_new_endpoints.py src/tests/test_entry_types_roundtrip.py src/tests/test_full_sync_roundtrip.py src/tests/test_cli_agent_mode.py`
  - Result: `150 passed`.

## Full-suite regression repair after document rollout
- Ran full suite after enabling agent document I/O and found 12 regressions (mostly stale tests).
- Fixed regressions by updating tests for:
  - new document add-menu option/mocks (`handle_add_document`),
  - expanded `EntryService.modify_entry` kwargs,
  - universal `date_added`/`date_modified` and `custom_fields` fields in entry expectations,
  - `list_entries(sort_by="updated")` relying on `modified_ts`,
  - legacy decrypt fallback monkeypatches to accept `salt` argument and revised iteration-call expectations.
- Verification: `.venv/bin/pytest -q src/tests` => `891 passed, 11 skipped`.

## Knowledge graph links integration (entry relationships)
- Added first-class graph edges to every entry via shared `links` field (list of `{target_id, relation, note}`).
- Implemented core link operations in `EntryManager`:
  - `add_link(entry_id, target_id, relation, note)`
  - `remove_link(entry_id, target_id, relation=None)`
  - `get_links(entry_id)` with resolved target label/kind.
- Added normalization/defaulting for `links` in index load path, including cache-return normalization to prevent stale in-memory schemas.
- Extended `modify_entry(..., links=...)` to allow full links replacement with validation.
- Search now matches link metadata (`relation`, `note`) and linked target labels, enabling graph-style discovery from existing index scans.
- Sync conflict equal-timestamp union now includes `links` alongside `tags` and `custom_fields` for deterministic convergence.
- Added API endpoints:
  - `GET /api/v1/entry/{id}/links`
  - `POST /api/v1/entry/{id}/links`
  - `DELETE /api/v1/entry/{id}/links`
  and `PUT /api/v1/entry/{id}` now accepts `links`.
- Added CLI graph commands:
  - `seedpass entry link-add`
  - `seedpass entry links`
  - `seedpass entry link-remove`
  plus `entry modify --links-json`.
- Documentation updated in `README.md`, `docs/entry_types.md`, and `docs/sync_conflict_contract.md`.
- Validation:
  - Focused suite: `140 passed`
  - Full suite: `895 passed, 11 skipped`.

## Website/docs refresh for graph features
- Added dedicated graph docs page: `docs/entry_graph.md`.
- Updated docs indexes/navigation:
  - `docs/README.md` now lists `entry_graph.md`.
  - `landing/docs.html` sidebar now includes `Entry Graph`.
- Updated landing page feature cards (`landing/index.html`) to highlight:
  - Entry Graph Links
  - Graph-Aware Entry Ops CLI commands
- Updated docs cross-links:
  - `docs/entry_types.md` points to `docs/entry_graph.md`.
- Updated README feature bullets to include Entry Graph Links.

## Landing graph example + help-hint refresh
- Added a visual graph snippet block to landing architecture section (`landing/index.html`) showing linked entries and graph query behavior.
- Styled graph snippet in `landing/style.css` (`.graph-snippet`) to match the terminal UI aesthetic.
- Expanded help/discovery surfaces for users and agents:
  - `seedpass capabilities` now includes a `knowledge_graph` security feature block with CLI/API graph commands and sync/search behavior.
  - Capabilities API discovery now lists `/api/v1/entry/{id}/links`.
  - Capabilities text output now explicitly mentions graph links and document workflows.
  - Capabilities `help_hints` now include graph/document command pointers.
  - `agent bootstrap-context` now includes `commands.knowledge_graph` hints.
  - Root CLI help string now mentions document I/O and entry graph links.
- Verification:
  - `.venv/bin/pytest -q src/tests/test_typer_cli.py -k "capabilities_text or capabilities_json" src/tests/test_cli_agent_mode.py -k "bootstrap_context"`
  - Result: `2 passed`.

## TUI v2 scaffold kickoff on beta
- Added `docs/tui_v2_plan.md` with phased migration plan, risk controls, and testing strategy for Textual-based TUI v2.
- Added experimental CLI command `seedpass tui2` and diagnostics mode `seedpass tui2 --check`.
- Added new runtime-check/launcher scaffold package at `src/seedpass/tui_v2/`.
- Updated discoverability/docs surfaces:
  - `docs/README.md` includes `tui_v2_plan.md`
  - `landing/docs.html` includes `TUI v2 Plan`
  - `README.md` discovery snippet includes `seedpass tui2 --check`
  - `capabilities` root commands/help hints include `tui2`
- Validation:
  - `py_compile` for updated modules
  - `pytest` capabilities tests (`2 passed`)
  - `.venv` smoke run confirms `seedpass tui2 --check` emits runtime diagnostics.
- 2026-03-01: TUI v2 phase 1 moved from placeholder to functional read-only Textual shell. `seedpass tui2` now passes a lazy `entry_service_factory` so vault/service init only happens when Textual is actually available, preventing unnecessary prompts on unavailable runtimes.
- Added focused CLI tests in `src/tests/test_typer_cli.py` for `tui2 --check`, unavailable + no fallback exit path, and legacy fallback fingerprint forwarding.
- 2026-03-01: TUI v2 phase 2 slice added in `seedpass/tui_v2/app.py`: archive/restore action (`a`), document editor mode (`e`) with save/cancel (`Ctrl+S`/`Esc`), and a persistent status line for operation feedback.
- Document editor uses `TextArea` when available and falls back to single-line input if unavailable, keeping runtime compatibility across Textual versions.
- 2026-03-01: TUI v2 gained `Ctrl+P` command palette with command parsing (`help`, `open`, `search`, `filter`, `archive/restore`, `edit-doc/save-doc/cancel-edit`, `link-add`, `link-rm`, `refresh`).
- Added a graph links panel in the right view that renders current entry links via `EntryService.get_links` and updates after palette link mutations.
- 2026-03-01: TUI v2 graph navigation expanded with relation-aware link filtering (`l` or `link-filter`) and quick neighbor traversal (`[`/`]` to change selected link, `o` or `link-open` to jump to target entry).
- Link panel now tracks selection state and displays active relation filter + selected link position to support KB-style navigation in large graphs.
- 2026-03-01: Phase 4 kickoff added `docs/tui_v2_parity_checklist.md` and linked it in docs indexes (`docs/README.md`, `landing/docs.html`) to track legacy-vs-v2 cutover readiness.
- TUI v2 large-vault UX/perf pass: entry list pagination (200/page, `p`/`n`, palette `page-next/page-prev/page <n>`) and document detail preview truncation (`content_truncated`) to avoid rendering extremely large payloads in the detail pane.
- 2026-03-01: TUI v2 error/recovery pass added unified failure recording (`_record_failure`) and retry workflow (`x` key + palette `retry`) across init/search/select/link/save/archive paths.
- Recovery hints are now included in status messages (for example, "Press 'x' to retry") and Phase 4 docs mark error/recovery flow work complete.
- 2026-03-01: Added `docs/tui_v2_cutover_decision.md` with explicit recommendation to keep legacy default for next release, required cutover gates, staged rollout, and rollback plan for switching `seedpass` default to TUI v2.
- Updated phase tracking docs to mark the cutover timing decision item complete and linked the memo in docs indexes.
- 2026-03-01: Began cutover-gate automation by extracting testable TUI v2 helpers (`parse_palette_command`, `pagination_window`, `truncate_entry_for_display`) from `tui_v2/app.py`.
- Added `src/tests/test_tui_v2_helpers.py` with coverage for palette parsing edge cases, pagination normalization, and large-vault pagination smoke sizes up to 50k rows.
- 2026-03-01: Added Textual interaction tests in `src/tests/test_tui_v2_textual_interactions.py` for pagination/search, document edit+save, link add/remove + neighbor open, and retry-after-failure.
- Introduced a test hook in `launch_tui2(..., app_hook=...)` so tests can capture and pilot the Textual app instance without starting a live terminal run.
- 2026-03-01: Added CI-like large-vault validation with explicit thresholds in `src/tests/test_tui_v2_large_vault_validation.py` (10k rows standard, 50k rows under `--stress`).
- Added docs `docs/tui_v2_large_vault_validation.md` with exact commands and budgets; parity checklist now marks large-vault CI-like validation complete.
- 2026-03-01: Added deterministic TUI v2 parity scenarios across entry kinds in `src/tests/test_tui_v2_parity_scenarios.py` (kind filters, archive/restore roundtrip, non-document edit guard).
- Completed help/docs alignment gate: updated `seedpass tui2` help text, capabilities hints for keybindings/palette (`Ctrl+P`, `p/n`, `x`), and docs discoverability commands (`seedpass tui2 --help/--check`).
- 2026-03-01: Switched default root CLI interactive routing to TUI v2 in `seedpass.cli.main` (when no subcommand), with automatic legacy fallback when Textual runtime is unavailable.
- Added explicit one-release override flag `--legacy-tui` and updated test coverage (`test_typer_cli.py`) for default TUI v2 launch, forced legacy path, and root fallback behavior.
- 2026-03-01: UX pass for TUI v2 added help overlay (`?`), quick jump input (`j`), pane focus switching (`1/2/3`) with visual focus borders, mode-tagged status line, and an activity log panel of recent actions.
- Added document dirty-state UX improvements (`Edit mode [*]` marker, no-op save guard) and updated Textual interaction/parity tests for Textual 8-compatible action-driven control paths.
- 2026-03-01: Visual polish pass for TUI v2 updated panel styling hierarchy (stronger status/pane contrast), refined left-panel summaries, improved help overlay readability, and added labeled headers for entry/detail and links sections.
- UI copy now emphasizes current selection/filter context while keeping deterministic action affordances unchanged; full TUI-focused test slice remains green.
- 2026-03-01: Reduced TUI v2 status noise by deduplicating repeated status messages before appending to status bar/activity log.
- Verified critical coverage gate against existing full coverage artifact (`artifacts/coverage/coverage.json`): all default threshold modules pass (main/core manager/core encryption/core migrations).

## 2026-03-01 Determinism test infrastructure hardening
- Added a dedicated determinism lane with `scripts/run_determinism_tests.sh` and wired `scripts/run_ci_tests.sh` to run it by default (`DETERMINISM_GATE=1`, disable with `DETERMINISM_GATE=0`).
- Added pytest marker support for determinism (`pyproject.toml`, `src/tests/conftest.py`) and a `--determinism-only` selector that skips non-determinism tests.
- Expanded deterministic regression vectors in `src/tests/test_deterministic_artifact_regression.py`:
  - pinned entropy-stream SHA-256 vectors for indexes `0,1,352,1024`
  - pinned password outputs for policy variants (default, safe specials, no specials, exclude ambiguous, restricted special charset)
- Marked existing deterministic suites so they run in the determinism lane: password helpers/policy plus seed, SSH, PGP, and Nostr determinism tests.
- Verified determinism lane now executes 23 focused tests and fails fast on derivation drift.

## 2026-03-01 Determinism gates + cross-process + size-tier sync tests
- Added `scripts/check_determinism_suite.py` and wired it into `scripts/run_determinism_tests.sh`.
- Determinism gate now enforces both a minimum test count (`DETERMINISM_MIN_TESTS`, default 25) and required determinism files, preventing accidental suite erosion.
- Added unit tests for determinism gate parser logic in `src/tests/test_check_determinism_suite.py`.
- Added cross-process determinism regression in `src/tests/test_cross_process_determinism.py`; derives artifacts in separate Python processes and asserts exact JSON identity.
- Expanded size-tier sync integrity coverage:
  - `src/tests/test_document_file_io.py` includes large document import/export and portable backup restore invariance checks (hash/equality).
  - `src/tests/test_full_sync_roundtrip.py` includes parameterized large document Nostr sync roundtrip with content hash checks.
  - `src/tests/test_nostr_snapshot.py` includes chunk hash and gzip roundtrip integrity across multiple payload size tiers.
- Current determinism lane status after updates: 43 passed, 916 skipped.

## 2026-03-01 TUI v2 agent harness + deep coverage expansion
- Added `scripts/ai_tui2_agent_test.py` as a deterministic agent-style TUI v2 harness using Textual pilot mode; emits timestamped JSON reports in `artifacts/agent_tui2_test/`.
- Added test/process documentation: `docs/agent_test_format.md` with repeatable commands for TUI v2, legacy interactive harness, CLI/CUI, API, and determinism gate runs.
- Fixed legacy harness invalid-input regression after Document type addition: in `scripts/ai_tui_agent_test.py`, Add Entry invalid choice now uses `99` instead of `9`.
- Added `src/tests/test_tui_v2_action_matrix.py` to exercise broad TUI v2 action and palette paths (including guards/failure/retry/event handlers).
- Fixed a real TUI v2 help-overlay bug in `src/seedpass/tui_v2/app.py` where `[/]` text triggered Textual markup parsing errors (`MarkupError`).
- Latest TUI v2 focused coverage run:
  - Command: test helper/interactions/parity/large-vault/action-matrix suites with `--cov=seedpass.tui_v2.app`
  - Result: 25 passed, 2 skipped
  - Coverage: 86% for `src/seedpass/tui_v2/app.py` (up from ~57%).
- Harness validation results:
  - `scripts/ai_tui2_agent_test.py --scenario extended`: passed
  - `scripts/ai_tui_agent_test.py --scenario core`: passed

## 2026-03-01 Installer + TUI v2 preflight fix (gray-screen mitigation)
- Root cause found for "blank/gray screen" reports: TUI v2 was initializing `PasswordManager` inside Textual mount via `entry_service_factory`, so password/setup prompts could occur behind the Textual screen and appear as a frozen UI.
- Updated `src/seedpass/cli/__init__.py` to pre-initialize entry service before launching Textual (`_prime_tui2_service`), then pass the ready service into `launch_tui2`.
- Added explicit fallback/error behavior:
  - default `seedpass`: preflight failures now fall back to legacy TUI with details.
  - `seedpass tui2 --no-fallback-legacy`: preflight failures now return exit code 1 with a clear error.
- Updated installer `scripts/install.sh` to run `seedpass tui2 --check` after install and warn when Textual runtime is unavailable, plus print a legacy fallback hint for users seeing blank/gray startup.
- Added regression coverage in `src/tests/test_typer_cli.py` for preflight behavior and adapted existing TUI launch tests to mock preflight service creation.

## 2026-03-01 TUI v2 parity slice: reveal + QR integration
- Added Textual TUI v2 sensitive-data actions:
  - Keybindings: `v` reveal selected secret, `g` show QR.
  - Palette commands: `reveal`, `qr`.
- Implemented reveal support for entry kinds: `password`, `seed`, `managed_account`, `totp`.
- Implemented QR rendering in-app (ASCII QR panel) for:
  - TOTP (`otpauth://` payload)
  - Seed / managed account seed (SeedQR digit payload)
- Added a dedicated `#secret-detail` panel in the right pane and reset-on-selection behavior to avoid stale secret display.
- Extended core `EntryService` API with deterministic seed retrieval methods used by TUI v2:
  - `get_seed_phrase(entry_id)`
  - `get_managed_account_seed(entry_id)`
- Added/updated tests for helper QR rendering, TUI reveal/QR workflows, and service wrappers; targeted suite passed.

## 2026-03-01 TUI v2 parity slice: SSH/PGP/Nostr + secret mode behavior
- Extended TUI v2 sensitive reveal support to additional kinds: `ssh`, `pgp`, and `nostr`.
- Added legacy-aligned confirmation semantics in TUI v2:
  - `reveal confirm` required for high-risk reveals (`seed`, `managed_account`, `ssh`, `pgp`).
  - `qr private confirm` required for Nostr private-key QR rendering.
- Added `qr` mode parsing (`qr [public|private] [confirm]`) and retained default safe behavior (`public` for Nostr).
- Integrated secret-mode behavior into TUI reveal flow:
  - when secret mode is enabled, reveal copies sensitive value to clipboard and avoids on-screen plaintext output for that reveal.
- Expanded `EntryService` API for TUI parity and safe abstraction from manager internals:
  - `get_ssh_key_pair`, `get_pgp_key`, `get_nostr_key_pair`
  - `get_secret_mode_enabled`, `get_clipboard_clear_delay`, `copy_to_clipboard`
- Added/updated tests covering confirmation-gated flows, Nostr private QR confirmation, and secret-mode clipboard behavior.

## 2026-03-01 TUI v2 visual alignment with landing page
- Updated Textual TUI v2 default styling to mirror landing-page palette tokens:
  - background: `#080a0c` / panel: `#0d1114`
  - primary text: `#97b8a6` / bright text: `#daf2e5`
  - accent borders/focus: `#58f29d`, `#2abf75`, `#274533`, `#1a3024`
- Styled Header/Footer/Input/ListView/ListItem focus/selection states to reduce default Textual blue and align with SeedPass mint-green terminal aesthetic.
- Added website-style icon semantics into TUI copy and sensitive panel titles (key/mobile/network/lock/bolt/document/users/seed mappings) to improve visual continuity between landing and app.