diff --git a/CLI-Reference.md b/WIKI_CLI.md similarity index 94% rename from CLI-Reference.md rename to WIKI_CLI.md index 316fd7c..a71ad2a 100644 --- a/CLI-Reference.md +++ b/WIKI_CLI.md @@ -1,89 +1,89 @@ -# CLI Reference - -Project Journal includes a command-line interface under `journal.cli.main`. - -## Basic Usage - -```bash -python -m journal.cli.main --help -``` - -## Vault Commands - -Load encrypted vaults: - -```bash -python -m journal.cli.main vault load -``` - -Save vaults: - -```bash -python -m journal.cli.main vault save -``` - -Notes: - -- Vault commands prompt for password. -- Vault files are monthly and encrypted. - -## Search Commands - -Search by text: - -```bash -python -m journal.cli.main search "shutdown" -``` - -Search with filters: - -```bash -python -m journal.cli.main search "trigger" --tag co-parent --type !TRIGGER --start-date 2026-02-01 --end-date 2026-02-21 -``` - -Search by section: - -```bash -python -m journal.cli.main search "anxiety" --section "Mental / Emotional Snapshot" -``` - -Search checkbox states: - -```bash -python -m journal.cli.main search --checked Masking -python -m journal.cli.main search --unchecked Shutdown -``` - -## Server Commands - -Start server: - -```bash -python -m journal.cli.main server start -``` - -Stop server: - -```bash -python -m journal.cli.main server stop -``` - -## AI Chat Command - -```bash -python -m journal.cli.main chat "Summarize my last week patterns." -``` - -## Devices Command - -List microphones: - -```bash -python -m journal.cli.main devices list -``` - -## Common Errors - -- `No decrypted journal entries found`: run `vault load` first. -- Date parsing errors: use `YYYY-MM-DD` for date filters. -- No microphone listed: check device permissions and drivers. +# CLI Reference + +Project Journal includes a command-line interface under `journal.cli.main`. + +## Basic Usage + +```bash +python -m journal.cli.main --help +``` + +## Vault Commands + +Load encrypted vaults: + +```bash +python -m journal.cli.main vault load +``` + +Save vaults: + +```bash +python -m journal.cli.main vault save +``` + +Notes: + +- Vault commands prompt for password. +- Vault files are monthly and encrypted. + +## Search Commands + +Search by text: + +```bash +python -m journal.cli.main search "shutdown" +``` + +Search with filters: + +```bash +python -m journal.cli.main search "trigger" --tag co-parent --type !TRIGGER --start-date 2026-02-01 --end-date 2026-02-21 +``` + +Search by section: + +```bash +python -m journal.cli.main search "anxiety" --section "Mental / Emotional Snapshot" +``` + +Search checkbox states: + +```bash +python -m journal.cli.main search --checked Masking +python -m journal.cli.main search --unchecked Shutdown +``` + +## Server Commands + +Start server: + +```bash +python -m journal.cli.main server start +``` + +Stop server: + +```bash +python -m journal.cli.main server stop +``` + +## AI Chat Command + +```bash +python -m journal.cli.main chat "Summarize my last week patterns." +``` + +## Devices Command + +List microphones: + +```bash +python -m journal.cli.main devices list +``` + +## Common Errors + +- `No decrypted journal entries found`: run `vault load` first. +- Date parsing errors: use `YYYY-MM-DD` for date filters. +- No microphone listed: check device permissions and drivers. diff --git a/Development-Workflow.md b/WIKI_DEVELOPMENT_WORKFLOW.md similarity index 95% rename from Development-Workflow.md rename to WIKI_DEVELOPMENT_WORKFLOW.md index 458e904..0a8fcb1 100644 --- a/Development-Workflow.md +++ b/WIKI_DEVELOPMENT_WORKFLOW.md @@ -1,52 +1,53 @@ -# Development Workflow - -This page defines a lightweight workflow for a small team using phased migration and acceptance gates. - -## Recommended Board Columns - -- Backlog -- Ready -- In Progress -- Review/Test -- Done -- Blocked - -## Card Template - -Each work item should include: - -- Title -- Owner -- Scope (single feature or defect) -- Acceptance IDs (if applicable) -- Evidence required (test output, logs, screenshots, file refs) -- Done condition - -Example: - -- Title: `Phase 1 persistence: fragment repository` -- Acceptance IDs: `DOM-001`, `API-001` (and phase note) -- Evidence: smoke tests + sidecar roundtrip output - -## Branching Guidance - -- Keep branches small and focused. -- One branch per card when possible. -- Avoid mixing migration phases in one branch. - -## Review Rules - -- No `Pass` status without evidence. -- Any intentional behavior divergence must be documented. -- Keep security-sensitive changes reviewable and explicit. - -## Release Gate Mindset - -- Passing local build is not enough. -- Use acceptance criteria as the source of truth for phase completion. -- Do not move frontend cutover work ahead of required parity gates. - -## Documentation Expectations - -- Update wiki pages when commands, dependencies, or behavior change. -- Keep setup and troubleshooting pages current with real host issues encountered. +# Development Workflow + +This page defines a lightweight workflow for a small team using phased migration and acceptance gates. + +## Recommended Board Columns + +- Backlog +- Ready +- In Progress +- Review/Test +- Done +- Blocked + +## Card Template + +Each work item should include: + +- Title +- Owner +- Scope (single feature or defect) +- Acceptance IDs (if applicable) +- Evidence required (test output, logs, screenshots, file refs) +- Done condition + +Example: + +- Title: `Phase 1 persistence: fragment repository` +- Acceptance IDs: `DOM-001`, `API-001` (and phase note) +- Evidence: smoke tests + sidecar roundtrip output + +## Branching Guidance + +- Keep branches small and focused. +- One branch per card when possible. +- Avoid mixing migration phases in one branch. + +## Review Rules + +- No `Pass` status without evidence. +- Any intentional behavior divergence must be documented. +- Keep security-sensitive changes reviewable and explicit. + +## Release Gate Mindset + +- Passing local build is not enough. +- Use acceptance criteria as the source of truth for phase completion. +- Do not move frontend cutover work ahead of required parity gates. + +## Documentation Expectations + +- Update wiki pages when commands, dependencies, or behavior change. +- Keep setup and troubleshooting pages current with real host issues encountered. +- For local wiki editing and push flow, use `WIKI_GIT_WORKFLOW.md`. diff --git a/WIKI_GIT_WORKFLOW.md b/WIKI_GIT_WORKFLOW.md new file mode 100644 index 0000000..f621474 --- /dev/null +++ b/WIKI_GIT_WORKFLOW.md @@ -0,0 +1,47 @@ +# Wiki Git Workflow (Gitea) + +Use this workflow to edit the project wiki locally and push changes to Gitea without using the web editor. + +Wiki remote: + +`https://gitea.innovativedevsolutions.org/stan44/Project_Journal-Python.wiki.git` + +## One-time setup + +```powershell +Set-Location E:\stansshit\Project_Journal +git clone https://gitea.innovativedevsolutions.org/stan44/Project_Journal-Python.wiki.git wiki +Set-Location .\wiki +git config user.name "Your Name" +git config user.email "you@example.com" +``` + +## Daily update flow + +```powershell +Set-Location E:\stansshit\Project_Journal\wiki +git pull --ff-only +``` + +Edit or add `*.md` pages, then: + +```powershell +Set-Location E:\stansshit\Project_Journal\wiki +git add . +git commit -m "wiki: update migration docs" +git push +``` + +## Quick check + +```powershell +Set-Location E:\stansshit\Project_Journal\wiki +git status +git log --oneline -n 5 +``` + +## Notes + +- Wiki pages are normal Markdown files in this separate wiki Git repo. +- Use short, scoped commits (one topic per commit). +- If `git push` fails due to auth, re-run with your preferred credential method (token/credential manager). diff --git a/Home.md b/WIKI_HOME.md similarity index 93% rename from Home.md rename to WIKI_HOME.md index 5ba3bbc..52eee27 100644 --- a/Home.md +++ b/WIKI_HOME.md @@ -1,58 +1,59 @@ -# Project Journal Wiki - -Welcome to the Project Journal documentation hub. - -Project Journal is an offline-first journaling system with encrypted monthly vaults, desktop + CLI workflows, and optional local AI support. - -## Wiki Pages - -Use these pages as your Gitea wiki starter set: - -- `Home` (this page) -- `Setup and Installation` (`WIKI_SETUP.md`) -- `CLI Reference` (`WIKI_CLI.md`) -- `Vaults and Data Handling` (`WIKI_VAULTS.md`) -- `Troubleshooting` (`WIKI_TROUBLESHOOTING.md`) -- `Development Workflow` (`WIKI_DEVELOPMENT_WORKFLOW.md`) - -## Quick Start (Python Baseline) - -### Windows (CPU default) - -```powershell -cd Project_Journal -py -3.14 -m venv .venv -.\.venv\Scripts\Activate.ps1 -python -m pip install --upgrade pip -python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt -python .\journal\run_desktop.py -``` - -### Linux (CPU default) - -```bash -cd Project_Journal -python3.14 -m venv .venv -source .venv/bin/activate -python -m pip install --upgrade pip -python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt -python ./journal/run_desktop.py -``` - -## Current Direction - -- Python backend remains the active baseline. -- C# backend migration is in progress -- Security posture target is HIPAA-capable architecture and safeguards (not a legal compliance certification claim). - -## Core References - -- Project readme: `README.md` -- Python CLI: `journal/cli/main.py` -- Python storage and vault logic: `journal/core/storage.py` -- C# backend readme: `journal-master/journal/README.md` -- C# minimal machine setup: `journal-master/journal/MINIMAL_MACHINE_SETUP.md` - -## Safety Notice - -Project Journal is a software tool and not a replacement for licensed mental health care, emergency services, or crisis intervention. +# Project Journal Wiki + +Welcome to the Project Journal documentation hub. + +Project Journal is an offline-first journaling system with encrypted monthly vaults, desktop + CLI workflows, and optional local AI support. + +## Wiki Pages + +Use these pages as your Gitea wiki starter set: + +- `Home` (this page) +- `Setup and Installation` (`WIKI_SETUP.md`) +- `CLI Reference` (`WIKI_CLI.md`) +- `Vaults and Data Handling` (`WIKI_VAULTS.md`) +- `C# Migration Status` (`WIKI_CSHARP_MIGRATION.md`) +- `Troubleshooting` (`WIKI_TROUBLESHOOTING.md`) +- `Development Workflow` (`WIKI_DEVELOPMENT_WORKFLOW.md`) + +## Quick Start (Python Baseline) + +### Windows (CPU default) + +```powershell +cd Project_Journal +py -3.14 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt +python .\journal\run_desktop.py +``` + +### Linux (CPU default) + +```bash +cd Project_Journal +python3.14 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt +python ./journal/run_desktop.py +``` + +## Current Direction + +- Python backend remains the active baseline. +- C# backend migration is in progress in `journal-master/journal/`. +- Security posture target is HIPAA-capable architecture and safeguards (not a legal compliance certification claim). + +## Core References + +- Project readme: `README.md` +- Python CLI: `journal/cli/main.py` +- Python storage and vault logic: `journal/core/storage.py` +- C# backend readme: `journal-master/journal/README.md` +- C# minimal machine setup: `journal-master/journal/MINIMAL_MACHINE_SETUP.md` + +## Safety Notice + +Project Journal is a software tool and not a replacement for licensed mental health care, emergency services, or crisis intervention. diff --git a/MIGRATION_ACCEPTANCE_CRITERIA.md b/WIKI_MIGRATION_ACCEPTANCE_CRITERIA.md similarity index 98% rename from MIGRATION_ACCEPTANCE_CRITERIA.md rename to WIKI_MIGRATION_ACCEPTANCE_CRITERIA.md index 1c8491e..570b398 100644 --- a/MIGRATION_ACCEPTANCE_CRITERIA.md +++ b/WIKI_MIGRATION_ACCEPTANCE_CRITERIA.md @@ -1,165 +1,165 @@ -# C# Backend Parity Acceptance Criteria (Python Twin) - -## Goal -Create a C# backend that is behaviorally equivalent to the current Python backend for core journaling workflows, with zero data-loss regressions and compatible vault handling. - -## Parity Rule -Behavior parity is required. Internal implementation can differ. - -## Source of Truth (Current Python) -- `journal/core/storage.py` -- `journal/core/encryption.py` -- `journal/core/parser.py` -- `journal/core/models.py` -- `journal/core/database.py` -- `journal/cli/main.py` -- `journal/ai/analysis.py` -- `journal/ai/chat.py` -- `journal/core/speech.py` - -## Definition of Done (Release Gate) -1. All `P0` criteria below are marked `Pass`. -2. Existing Python-created vault files load successfully in C# backend. -3. Side-by-side output comparison on shared fixture corpus shows no functional mismatch for `P0` flows. -4. No plaintext journal data remains after graceful shutdown flow. - -## Shared Fixture Corpus (Required) -1. `fixtures/vaults/` -- Multiple months (`YYYY-MM.vault`) generated by Python app. -- Includes at least one wrong-password test case. -2. `fixtures/entries/` -- Daily, deep, recovery, fragment-heavy entries. -- Includes multiline fragments, tags, checkboxes, unusual spacing. -3. `fixtures/search/` -- Queries for text, section, tag, type, checked, unchecked, date ranges. -4. `fixtures/ai/` -- Stubbed LLM/embedding responses for deterministic comparison. - -## Acceptance Matrix -Use status values: `Not Started`, `In Progress`, `Blocked`, `Pass`, `Fail`. - -| ID | Priority | Feature | Acceptance Criteria | Status | Owner | Evidence | -| ------- | -------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------- | ----- | -------- | -| DOM-001 | P0 | Fragment model parity | Fragment has `type`, `description`, `time`, `tags`; rejects empty `type`/`description`; trims values. | Pass | Stan44/Codex | `Journal.Core/Models/Fragment.cs`, `Journal.Core/Services/FragmentService.cs`, smoke test `CreateAsync trims fields` + `UpdateAsync rejects whitespace type` | -| DOM-002 | P0 | Journal entry domain parity | Entry model supports `date`, `raw_content`, `sections`, `fragments` equivalent to Python semantics. | Not Started | | | -| PAR-001 | P0 | Date extraction parity | Parser reads `**Date:**` or `Date:`; falls back to filename stem when missing. | Not Started | | | -| PAR-002 | P0 | Section parsing parity | Recognizes canonical section titles and captures section content lines. | Not Started | | | -| PAR-003 | P0 | Checkbox parsing parity | Parses markdown checkboxes (`- [ ]`, `- [x]`) and preserves checked state by checkbox text. | Not Started | | | -| PAR-004 | P0 | Fragment parsing parity | Parses `!TYPE @time #tags` plus multiline description blocks with same boundary behavior as Python regex parser. | Not Started | | | -| MRG-001 | P0 | Merge behavior parity | Saving existing entry merges non-empty section updates and appends only non-duplicate fragments by description. | Not Started | | | -| MRG-002 | P0 | Markdown reconstruction parity | Entry serialization writes canonical section order and fragment block formatting equivalent to Python `to_markdown()`. | Not Started | | | -| VLT-001 | P0 | Vault crypto format compatibility | Uses AES-256-GCM with payload layout compatible with Python (`salt + nonce + tag + ciphertext`). | Not Started | | | -| VLT-002 | P0 | KDF compatibility | Uses PBKDF2-HMAC-SHA256 with matching salt/key sizes and iteration count for Python vault compatibility. | Not Started | | | -| VLT-003 | P0 | Monthly vault naming parity | Vault filename format exactly `YYYY-MM.vault`. | Not Started | | | -| VLT-004 | P0 | Load workflow parity | `load all vaults` clears decrypted workspace first, then decrypts/extracts monthly vaults. | Not Started | | | -| VLT-005 | P0 | Wrong password behavior | Wrong password returns explicit failure and does not corrupt existing vault files. | Not Started | | | -| VLT-006 | P1 | Legacy vault handling | Legacy `_init_vault.vault` handling behavior is preserved or intentionally migrated with backward-compat note. | Not Started | | | -| VLT-007 | P0 | Current-month optimized save | Supports current-month save path equivalent to Python optimization. | Not Started | | | -| VLT-008 | P0 | Full rebuild save | Supports full monthly regroup/rebuild save flow from decrypted `.md` files. | Not Started | | | -| DAT-001 | P0 | Decrypted data cleanup | Graceful shutdown removes decrypted workspace artifacts. | Not Started | | | -| DB-001 | P1 | SQLCipher compatibility | Database key derivation and SQLCipher connection behavior are compatible with Python expectations. | Not Started | | | -| DB-002 | P1 | Schema parity | `entries`, `sections`, `fragments`, `tags`, `fragment_tags` schema exists with compatible constraints. | Not Started | | | -| SCH-001 | P0 | Search parity (content) | Search supports text query over full entry content. | Not Started | | | -| SCH-002 | P0 | Search parity (filters) | Search supports date range, section filter, tag filter, fragment type filter, checked/unchecked filters. | Not Started | | | -| CLI-001 | P0 | Vault CLI parity | CLI supports vault load/save with password prompt semantics matching Python UX. | Not Started | | | -| CLI-002 | P0 | Search CLI parity | CLI options match existing Python capabilities sufficiently for drop-in replacement. | Not Started | | | -| API-001 | P0 | Sidecar protocol stability | Stdin/stdout contract is line-delimited JSON with `{ok,data}` or `{ok:false,error}` and strict action routing. | In Progress | Stan44/Codex | `Journal.Core/Entry.cs`, smoke tests for unknown action / missing payload / missing id handling | -| API-002 | P1 | HTTP API parity | API exposes endpoints equivalent to supported sidecar actions; no template-only endpoints in parity mode. | Not Started | | | -| AI-001 | P1 | LLM summarize parity | Entry/all-entry summarize workflow callable with equivalent behavior and timeout controls. | Not Started | | | -| AI-002 | P2 | Embedding parity | Embedding endpoint integration available with equivalent request/response contract. | Not Started | | | -| AI-003 | P1 | Cloud chat parity | Cloud chat request/response flow available and configurable. | Not Started | | | -| SPC-001 | P2 | Speech parity | Engine-selectable speech flow (whisper/google/sphinx-like modes) retained or intentionally delegated. | Not Started | | | -| CFG-001 | P0 | Config parity | Equivalent configuration keys exist for paths, vault format, AI endpoints, and speech settings. | Not Started | | | -| OBS-001 | P1 | Logging/error parity | Failures return actionable messages without leaking secrets or plaintext journal data. | In Progress | Stan44/Codex | Error envelope behavior implemented in sidecar; structured logging policy pending | - -## Mandatory Gate Tests (P0) -1. `Vault Compatibility` -- Given existing Python vault fixtures, C# load succeeds with correct password. -- Wrong password consistently fails without partial corruption. -2. `Parser + Merge` -- Given fixture entries, C# parser output matches Python parser output for sections/fragments/checkboxes. -- Saving edited entry preserves merge semantics. -3. `Search` -- For shared corpus, C# and Python return the same entry set for all P0 search filters. -4. `Transport` -- Sidecar commands for core actions produce stable JSON success/error envelopes. -5. `Cleanup` -- After graceful shutdown sequence, decrypted workspace is empty. - -## Migration Phases (Recommended) -1. `Phase 1: Fragment Vertical Slice` -- Complete `DOM-001`, `API-001`, persistence beyond in-memory. -2. `Phase 2: Entry/Parser/Merge Twin` -- Complete `DOM-002`, `PAR-*`, `MRG-*`. -3. `Phase 3: Vault/Crypto Twin` -- Complete `VLT-*`, `DAT-001`. -4. `Phase 4: Search + CLI Twin` -- Complete `SCH-*`, `CLI-*`, `CFG-001`. -5. `Phase 5: AI/Speech` -- Complete `AI-*`, `SPC-001`. -6. `Phase 6: Frontend Cutover` -- Tauri frontend switches to C# backend only after all P0 criteria pass. - -## Rules for Change Requests -1. Any intentional divergence from Python behavior requires: -- Written rationale. -- New acceptance criterion replacing old one. -- Migration note describing user-visible impact. -2. No removal of a `P0` criterion without both maintainers approving in writing. - -## Status Snapshot (2026-02-22, Phase 1.2 Progress) -This section is a proposed status/evidence snapshot based on current code in: -- Python source: `Project_Journal/` -- C# migration: `Project_Journal/journal-master/journal/` - -It does not change release gates or acceptance definitions. - -### Phase Summary -| Phase | Current State | Evidence | -| ----- | ------------- | -------- | -| Phase 1: Fragment Vertical Slice | In Progress (near-complete) | Fragment model/service/sidecar + persisted repository + smoke tests: `journal-master/journal/Journal.Core/Models/Fragment.cs`, `journal-master/journal/Journal.Core/Entry.cs`, `journal-master/journal/Journal.Core/Repositories/FileFragmentRepository.cs`, `journal-master/journal/Journal.SmokeTests/Program.cs` | -| Phase 2: Entry/Parser/Merge Twin | Not Started | No C# entry/parser/merge domain yet. | -| Phase 3: Vault/Crypto Twin | Not Started | No C# vault/crypto compatibility module yet. | -| Phase 4: Search + CLI Twin | Not Started | C# search remains fragment-scoped only (not full entry parity). | -| Phase 5: AI/Speech | Not Started | No C# AI/speech parity services yet. | -| Phase 6: Frontend Cutover | Not Started | P0 parity not yet achieved. | - -### Proposed Acceptance Status Updates -| ID | Proposed Status | Evidence | Notes | -| ------- | --------------- | -------- | ----- | -| DOM-001 | Pass | `journal-master/journal/Journal.Core/Models/Fragment.cs`, `journal-master/journal/Journal.Core/Services/FragmentService.cs`, `journal-master/journal/Journal.SmokeTests/Program.cs` | Fields/validation/trim behavior implemented and smoke-tested. | -| DOM-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No C# `JournalEntry` parity domain yet. | -| PAR-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No C# parser/date extraction path yet. | -| PAR-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No section parser in C#. | -| PAR-003 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No checkbox parser in C#. | -| PAR-004 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No fragment markdown parser in C#. | -| MRG-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No entry merge behavior in C#. | -| MRG-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No markdown reconstruction pipeline in C#. | -| VLT-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No vault encryption/decryption compatibility module yet. | -| VLT-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No PBKDF2 compatibility implementation yet. | -| VLT-003 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No monthly vault naming/save implementation yet. | -| VLT-004 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No load-all-vaults workflow in C#. | -| VLT-005 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | Wrong-password behavior not implemented in C# vault flow. | -| VLT-006 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | Legacy vault handling not implemented/documented in C#. | -| VLT-007 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | Current-month optimized save path not implemented in C#. | -| VLT-008 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | Full rebuild save flow not implemented in C#. | -| DAT-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | Decrypted workspace cleanup flow not implemented in C#. | -| DB-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No SQLCipher keying/connection behavior in C#. | -| DB-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No `entries/sections/fragments/tags/fragment_tags` schema in C#. | -| SCH-001 | Not Started | `journal-master/journal/Journal.Core/Repositories/FileFragmentRepository.cs` | C# search is fragment-centric, not full-entry content search. | -| SCH-002 | Not Started | `journal-master/journal/Journal.Core/Repositories/FileFragmentRepository.cs` | Date/section/checkbox filters not implemented for full entry search. | -| CLI-001 | Not Started | `journal-master/journal/Journal.Sidecar/App.cs` | Sidecar exists; vault CLI parity not implemented. | -| CLI-002 | Not Started | `journal-master/journal/Journal.Sidecar/App.cs` | Search CLI parity not implemented. | -| API-001 | In Progress | `journal-master/journal/Journal.Core/Entry.cs`, `journal-master/journal/Journal.SmokeTests/Program.cs` | JSON envelope routing implemented and tested; fixture-driven P0 gate tests still pending. | -| API-002 | Not Started | `journal-master/journal/Journal.Api/Program.cs` | HTTP API still template endpoint, no journal parity endpoints. | -| AI-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No summarize workflow/service in C#. | -| AI-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No embeddings integration in C#. | -| AI-003 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No cloud chat flow in C#. | -| SPC-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No speech module/service in C#. | -| CFG-001 | Not Started | `journal-master/journal/Journal.Core/ServiceCollectionExtensions.cs` | C# config surface is partial and not parity-complete. | -| OBS-001 | In Progress | `journal-master/journal/Journal.Core/Entry.cs` | Actionable error envelope exists; structured logging/secret-scrub policy pending. | - -### Snapshot Risks/Blockers -1. Required fixture corpus (`fixtures/vaults`, `fixtures/entries`, `fixtures/search`, `fixtures/ai`) is still missing. -2. P0 gate test harness for side-by-side Python vs C# parity is not yet implemented. -3. Phase 1 remaining item is final API-001 hardening + fixture-backed transport stability evidence. +# C# Backend Parity Acceptance Criteria (Python Twin) + +## Goal +Create a C# backend that is behaviorally equivalent to the current Python backend for core journaling workflows, with zero data-loss regressions and compatible vault handling. + +## Parity Rule +Behavior parity is required. Internal implementation can differ. + +## Source of Truth (Current Python) +- `journal/core/storage.py` +- `journal/core/encryption.py` +- `journal/core/parser.py` +- `journal/core/models.py` +- `journal/core/database.py` +- `journal/cli/main.py` +- `journal/ai/analysis.py` +- `journal/ai/chat.py` +- `journal/core/speech.py` + +## Definition of Done (Release Gate) +1. All `P0` criteria below are marked `Pass`. +2. Existing Python-created vault files load successfully in C# backend. +3. Side-by-side output comparison on shared fixture corpus shows no functional mismatch for `P0` flows. +4. No plaintext journal data remains after graceful shutdown flow. + +## Shared Fixture Corpus (Required) +1. `fixtures/vaults/` +- Multiple months (`YYYY-MM.vault`) generated by Python app. +- Includes at least one wrong-password test case. +2. `fixtures/entries/` +- Daily, deep, recovery, fragment-heavy entries. +- Includes multiline fragments, tags, checkboxes, unusual spacing. +3. `fixtures/search/` +- Queries for text, section, tag, type, checked, unchecked, date ranges. +4. `fixtures/ai/` +- Stubbed LLM/embedding responses for deterministic comparison. + +## Acceptance Matrix +Use status values: `Not Started`, `In Progress`, `Blocked`, `Pass`, `Fail`. + +| ID | Priority | Feature | Acceptance Criteria | Status | Owner | Evidence | +| ------- | -------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------- | ----- | -------- | +| DOM-001 | P0 | Fragment model parity | Fragment has `type`, `description`, `time`, `tags`; rejects empty `type`/`description`; trims values. | Pass | Stan44/Codex | `Journal.Core/Models/Fragment.cs`, `Journal.Core/Services/FragmentService.cs`, smoke test `CreateAsync trims fields` + `UpdateAsync rejects whitespace type` | +| DOM-002 | P0 | Journal entry domain parity | Entry model supports `date`, `raw_content`, `sections`, `fragments` equivalent to Python semantics. | Not Started | | | +| PAR-001 | P0 | Date extraction parity | Parser reads `**Date:**` or `Date:`; falls back to filename stem when missing. | Not Started | | | +| PAR-002 | P0 | Section parsing parity | Recognizes canonical section titles and captures section content lines. | Not Started | | | +| PAR-003 | P0 | Checkbox parsing parity | Parses markdown checkboxes (`- [ ]`, `- [x]`) and preserves checked state by checkbox text. | Not Started | | | +| PAR-004 | P0 | Fragment parsing parity | Parses `!TYPE @time #tags` plus multiline description blocks with same boundary behavior as Python regex parser. | Not Started | | | +| MRG-001 | P0 | Merge behavior parity | Saving existing entry merges non-empty section updates and appends only non-duplicate fragments by description. | Not Started | | | +| MRG-002 | P0 | Markdown reconstruction parity | Entry serialization writes canonical section order and fragment block formatting equivalent to Python `to_markdown()`. | Not Started | | | +| VLT-001 | P0 | Vault crypto format compatibility | Uses AES-256-GCM with payload layout compatible with Python (`salt + nonce + tag + ciphertext`). | Not Started | | | +| VLT-002 | P0 | KDF compatibility | Uses PBKDF2-HMAC-SHA256 with matching salt/key sizes and iteration count for Python vault compatibility. | Not Started | | | +| VLT-003 | P0 | Monthly vault naming parity | Vault filename format exactly `YYYY-MM.vault`. | Not Started | | | +| VLT-004 | P0 | Load workflow parity | `load all vaults` clears decrypted workspace first, then decrypts/extracts monthly vaults. | Not Started | | | +| VLT-005 | P0 | Wrong password behavior | Wrong password returns explicit failure and does not corrupt existing vault files. | Not Started | | | +| VLT-006 | P1 | Legacy vault handling | Legacy `_init_vault.vault` handling behavior is preserved or intentionally migrated with backward-compat note. | Not Started | | | +| VLT-007 | P0 | Current-month optimized save | Supports current-month save path equivalent to Python optimization. | Not Started | | | +| VLT-008 | P0 | Full rebuild save | Supports full monthly regroup/rebuild save flow from decrypted `.md` files. | Not Started | | | +| DAT-001 | P0 | Decrypted data cleanup | Graceful shutdown removes decrypted workspace artifacts. | Not Started | | | +| DB-001 | P1 | SQLCipher compatibility | Database key derivation and SQLCipher connection behavior are compatible with Python expectations. | Not Started | | | +| DB-002 | P1 | Schema parity | `entries`, `sections`, `fragments`, `tags`, `fragment_tags` schema exists with compatible constraints. | Not Started | | | +| SCH-001 | P0 | Search parity (content) | Search supports text query over full entry content. | Not Started | | | +| SCH-002 | P0 | Search parity (filters) | Search supports date range, section filter, tag filter, fragment type filter, checked/unchecked filters. | Not Started | | | +| CLI-001 | P0 | Vault CLI parity | CLI supports vault load/save with password prompt semantics matching Python UX. | Not Started | | | +| CLI-002 | P0 | Search CLI parity | CLI options match existing Python capabilities sufficiently for drop-in replacement. | Not Started | | | +| API-001 | P0 | Sidecar protocol stability | Stdin/stdout contract is line-delimited JSON with `{ok,data}` or `{ok:false,error}` and strict action routing. | In Progress | Stan44/Codex | `Journal.Core/Entry.cs`, smoke tests for unknown action / missing payload / missing id handling | +| API-002 | P1 | HTTP API parity | API exposes endpoints equivalent to supported sidecar actions; no template-only endpoints in parity mode. | Not Started | | | +| AI-001 | P1 | LLM summarize parity | Entry/all-entry summarize workflow callable with equivalent behavior and timeout controls. | Not Started | | | +| AI-002 | P2 | Embedding parity | Embedding endpoint integration available with equivalent request/response contract. | Not Started | | | +| AI-003 | P1 | Cloud chat parity | Cloud chat request/response flow available and configurable. | Not Started | | | +| SPC-001 | P2 | Speech parity | Engine-selectable speech flow (whisper/google/sphinx-like modes) retained or intentionally delegated. | Not Started | | | +| CFG-001 | P0 | Config parity | Equivalent configuration keys exist for paths, vault format, AI endpoints, and speech settings. | Not Started | | | +| OBS-001 | P1 | Logging/error parity | Failures return actionable messages without leaking secrets or plaintext journal data. | In Progress | Stan44/Codex | Error envelope behavior implemented in sidecar; structured logging policy pending | + +## Mandatory Gate Tests (P0) +1. `Vault Compatibility` +- Given existing Python vault fixtures, C# load succeeds with correct password. +- Wrong password consistently fails without partial corruption. +2. `Parser + Merge` +- Given fixture entries, C# parser output matches Python parser output for sections/fragments/checkboxes. +- Saving edited entry preserves merge semantics. +3. `Search` +- For shared corpus, C# and Python return the same entry set for all P0 search filters. +4. `Transport` +- Sidecar commands for core actions produce stable JSON success/error envelopes. +5. `Cleanup` +- After graceful shutdown sequence, decrypted workspace is empty. + +## Migration Phases (Recommended) +1. `Phase 1: Fragment Vertical Slice` +- Complete `DOM-001`, `API-001`, persistence beyond in-memory. +2. `Phase 2: Entry/Parser/Merge Twin` +- Complete `DOM-002`, `PAR-*`, `MRG-*`. +3. `Phase 3: Vault/Crypto Twin` +- Complete `VLT-*`, `DAT-001`. +4. `Phase 4: Search + CLI Twin` +- Complete `SCH-*`, `CLI-*`, `CFG-001`. +5. `Phase 5: AI/Speech` +- Complete `AI-*`, `SPC-001`. +6. `Phase 6: Frontend Cutover` +- Tauri frontend switches to C# backend only after all P0 criteria pass. + +## Rules for Change Requests +1. Any intentional divergence from Python behavior requires: +- Written rationale. +- New acceptance criterion replacing old one. +- Migration note describing user-visible impact. +2. No removal of a `P0` criterion without both maintainers approving in writing. + +## Status Snapshot (2026-02-22, Phase 1.2 Progress) +This section is a proposed status/evidence snapshot based on current code in: +- Python source: `Project_Journal/` +- C# migration: `Project_Journal/journal-master/journal/` + +It does not change release gates or acceptance definitions. + +### Phase Summary +| Phase | Current State | Evidence | +| ----- | ------------- | -------- | +| Phase 1: Fragment Vertical Slice | In Progress (near-complete) | Fragment model/service/sidecar + persisted repository + smoke tests: `journal-master/journal/Journal.Core/Models/Fragment.cs`, `journal-master/journal/Journal.Core/Entry.cs`, `journal-master/journal/Journal.Core/Repositories/FileFragmentRepository.cs`, `journal-master/journal/Journal.SmokeTests/Program.cs` | +| Phase 2: Entry/Parser/Merge Twin | Not Started | No C# entry/parser/merge domain yet. | +| Phase 3: Vault/Crypto Twin | Not Started | No C# vault/crypto compatibility module yet. | +| Phase 4: Search + CLI Twin | Not Started | C# search remains fragment-scoped only (not full entry parity). | +| Phase 5: AI/Speech | Not Started | No C# AI/speech parity services yet. | +| Phase 6: Frontend Cutover | Not Started | P0 parity not yet achieved. | + +### Proposed Acceptance Status Updates +| ID | Proposed Status | Evidence | Notes | +| ------- | --------------- | -------- | ----- | +| DOM-001 | Pass | `journal-master/journal/Journal.Core/Models/Fragment.cs`, `journal-master/journal/Journal.Core/Services/FragmentService.cs`, `journal-master/journal/Journal.SmokeTests/Program.cs` | Fields/validation/trim behavior implemented and smoke-tested. | +| DOM-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No C# `JournalEntry` parity domain yet. | +| PAR-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No C# parser/date extraction path yet. | +| PAR-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No section parser in C#. | +| PAR-003 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No checkbox parser in C#. | +| PAR-004 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No fragment markdown parser in C#. | +| MRG-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No entry merge behavior in C#. | +| MRG-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No markdown reconstruction pipeline in C#. | +| VLT-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No vault encryption/decryption compatibility module yet. | +| VLT-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No PBKDF2 compatibility implementation yet. | +| VLT-003 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No monthly vault naming/save implementation yet. | +| VLT-004 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No load-all-vaults workflow in C#. | +| VLT-005 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | Wrong-password behavior not implemented in C# vault flow. | +| VLT-006 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | Legacy vault handling not implemented/documented in C#. | +| VLT-007 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | Current-month optimized save path not implemented in C#. | +| VLT-008 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | Full rebuild save flow not implemented in C#. | +| DAT-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | Decrypted workspace cleanup flow not implemented in C#. | +| DB-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No SQLCipher keying/connection behavior in C#. | +| DB-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No `entries/sections/fragments/tags/fragment_tags` schema in C#. | +| SCH-001 | Not Started | `journal-master/journal/Journal.Core/Repositories/FileFragmentRepository.cs` | C# search is fragment-centric, not full-entry content search. | +| SCH-002 | Not Started | `journal-master/journal/Journal.Core/Repositories/FileFragmentRepository.cs` | Date/section/checkbox filters not implemented for full entry search. | +| CLI-001 | Not Started | `journal-master/journal/Journal.Sidecar/App.cs` | Sidecar exists; vault CLI parity not implemented. | +| CLI-002 | Not Started | `journal-master/journal/Journal.Sidecar/App.cs` | Search CLI parity not implemented. | +| API-001 | In Progress | `journal-master/journal/Journal.Core/Entry.cs`, `journal-master/journal/Journal.SmokeTests/Program.cs` | JSON envelope routing implemented and tested; fixture-driven P0 gate tests still pending. | +| API-002 | Not Started | `journal-master/journal/Journal.Api/Program.cs` | HTTP API still template endpoint, no journal parity endpoints. | +| AI-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No summarize workflow/service in C#. | +| AI-002 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No embeddings integration in C#. | +| AI-003 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No cloud chat flow in C#. | +| SPC-001 | Not Started | `journal-master/journal/Journal.Core/Entry.cs` | No speech module/service in C#. | +| CFG-001 | Not Started | `journal-master/journal/Journal.Core/ServiceCollectionExtensions.cs` | C# config surface is partial and not parity-complete. | +| OBS-001 | In Progress | `journal-master/journal/Journal.Core/Entry.cs` | Actionable error envelope exists; structured logging/secret-scrub policy pending. | + +### Snapshot Risks/Blockers +1. Required fixture corpus (`fixtures/vaults`, `fixtures/entries`, `fixtures/search`, `fixtures/ai`) is still missing. +2. P0 gate test harness for side-by-side Python vs C# parity is not yet implemented. +3. Phase 1 remaining item is final API-001 hardening + fixture-backed transport stability evidence. diff --git a/Setup-and-Installation.md b/WIKI_SETUP.md similarity index 95% rename from Setup-and-Installation.md rename to WIKI_SETUP.md index cd50816..2e0599c 100644 --- a/Setup-and-Installation.md +++ b/WIKI_SETUP.md @@ -1,102 +1,102 @@ -# Setup and Installation - -This page covers local setup for the Python baseline and optional C# migration workspace. - -## Prerequisites - -- Python `3.14` -- `pip` and virtual environment support -- Windows or Linux -- Optional: GPU drivers/toolkit if using `requirements_gpu.txt` - -## Dependency Profiles - -- `requirements_base.txt`: shared runtime dependencies -- `requirements_cpu_only.txt`: base + CPU AI stack -- `requirements_gpu.txt`: base + GPU AI stack -- `requirements_nlp_optional.txt`: optional spaCy backend - -## Windows Setup (CPU default) - -```powershell -cd Project_Journal -py -3.14 -m venv .venv -.\.venv\Scripts\Activate.ps1 -python -m pip install --upgrade pip -python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt -``` - -Run desktop app: - -```powershell -python .\journal\run_desktop.py -``` - -## Linux Setup (CPU default) - -```bash -cd Project_Journal -python3.14 -m venv .venv -source .venv/bin/activate -python -m pip install --upgrade pip -python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt -``` - -Run desktop app: - -```bash -python ./journal/run_desktop.py -``` - -## Linux GPU Setup (optional) - -```bash -cd Project_Journal -python3.14 -m venv .venv -source .venv/bin/activate -python -m pip install --upgrade pip -python -m pip install -r requirements_gpu.txt -``` - -## Optional NLP Backend (spaCy) - -```bash -python -m pip install -r requirements_nlp_optional.txt -python -m spacy download en_core_web_sm -``` - -NLP backend modes: - -- `auto` (default): spaCy if available, fallback otherwise -- `spacy`: require spaCy and fail if unavailable -- `fallback`: always use fallback NLP heuristics - -Examples: - -```powershell -$env:JOURNAL_NLP_BACKEND = "fallback" -python .\journal\run_desktop.py -``` - -```bash -export JOURNAL_NLP_BACKEND=spacy -python ./journal/run_desktop.py -``` - -## C# Migration Workspace Setup (optional) - -Location: `journal-master/journal/` - -Use: - -- `journal-master/journal/README.md` -- `journal-master/journal/MINIMAL_MACHINE_SETUP.md` - -Quick check: - -```powershell -cd journal-master/journal -./scripts/dotnet-min.ps1 restore Journal.Sidecar/Journal.Sidecar.csproj -./scripts/dotnet-min.ps1 build Journal.Sidecar/Journal.Sidecar.csproj -./scripts/dotnet-min.ps1 run --project Journal.SmokeTests/Journal.SmokeTests.csproj -``` +# Setup and Installation + +This page covers local setup for the Python baseline and optional C# migration workspace. + +## Prerequisites + +- Python `3.14` +- `pip` and virtual environment support +- Windows or Linux +- Optional: GPU drivers/toolkit if using `requirements_gpu.txt` + +## Dependency Profiles + +- `requirements_base.txt`: shared runtime dependencies +- `requirements_cpu_only.txt`: base + CPU AI stack +- `requirements_gpu.txt`: base + GPU AI stack +- `requirements_nlp_optional.txt`: optional spaCy backend + +## Windows Setup (CPU default) + +```powershell +cd Project_Journal +py -3.14 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt +``` + +Run desktop app: + +```powershell +python .\journal\run_desktop.py +``` + +## Linux Setup (CPU default) + +```bash +cd Project_Journal +python3.14 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt +``` + +Run desktop app: + +```bash +python ./journal/run_desktop.py +``` + +## Linux GPU Setup (optional) + +```bash +cd Project_Journal +python3.14 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -r requirements_gpu.txt +``` + +## Optional NLP Backend (spaCy) + +```bash +python -m pip install -r requirements_nlp_optional.txt +python -m spacy download en_core_web_sm +``` + +NLP backend modes: + +- `auto` (default): spaCy if available, fallback otherwise +- `spacy`: require spaCy and fail if unavailable +- `fallback`: always use fallback NLP heuristics + +Examples: + +```powershell +$env:JOURNAL_NLP_BACKEND = "fallback" +python .\journal\run_desktop.py +``` + +```bash +export JOURNAL_NLP_BACKEND=spacy +python ./journal/run_desktop.py +``` + +## C# Migration Workspace Setup (optional) + +Location: `journal-master/journal/` + +Use: + +- `journal-master/journal/README.md` +- `journal-master/journal/MINIMAL_MACHINE_SETUP.md` + +Quick check: + +```powershell +cd journal-master/journal +./scripts/dotnet-min.ps1 restore Journal.Sidecar/Journal.Sidecar.csproj +./scripts/dotnet-min.ps1 build Journal.Sidecar/Journal.Sidecar.csproj +./scripts/dotnet-min.ps1 run --project Journal.SmokeTests/Journal.SmokeTests.csproj +``` diff --git a/Troubleshooting.md b/WIKI_TROUBLESHOOTING.md similarity index 95% rename from Troubleshooting.md rename to WIKI_TROUBLESHOOTING.md index 6bca95e..0ca8c5b 100644 --- a/Troubleshooting.md +++ b/WIKI_TROUBLESHOOTING.md @@ -1,98 +1,98 @@ -# Troubleshooting - -## Python Environment - -### Wrong Python version - -Symptom: - -- Dependency install fails or runtime errors appear unexpectedly. - -Fix: - -- Use Python `3.14` for this baseline. -- Recreate virtual environment and reinstall dependencies. - -### spaCy backend issues - -Symptom: - -- spaCy import/model errors. - -Fix: - -- Use fallback backend: - -```powershell -$env:JOURNAL_NLP_BACKEND = "fallback" -python .\journal\run_desktop.py -``` - -### Desktop UI fallback on Windows - -Symptom: - -- Embedded desktop shell unavailable. - -Fix: - -- Current setup may open in browser mode automatically; this is expected in some Python 3.14 environments. - -## Vault Issues - -### Wrong password on load - -Symptom: - -- Vault load fails for existing files. - -Fix: - -- Re-run with the correct vault password. -- Confirm vault files are intact in `journal/vault/`. - -### Decrypted data still present - -Symptom: - -- Files remain in `journal/data/` after abnormal termination. - -Fix: - -- Use graceful shutdown path where possible. -- Manually clear decrypted workspace if needed. - -## C# Migration Workspace - -### NuGet or TLS errors - -Symptom: - -- `dotnet restore` fails with TLS/Schannel errors. - -Fix: - -- Run commands via `./scripts/dotnet-min.ps1` -- Confirm NuGet endpoint: - -```powershell -curl.exe -I https://api.nuget.org/v3/index.json -``` - -- Follow host repair guidance in `journal-master/journal/MINIMAL_MACHINE_SETUP.md` if needed. - -### Sidecar build/test checks - -```powershell -cd journal-master/journal -./scripts/dotnet-min.ps1 restore Journal.Sidecar/Journal.Sidecar.csproj -./scripts/dotnet-min.ps1 build Journal.Sidecar/Journal.Sidecar.csproj -./scripts/dotnet-min.ps1 run --project Journal.SmokeTests/Journal.SmokeTests.csproj -``` - -## Quick Diagnostics Checklist - -- `python -m journal.cli.main --help` -- `python -m journal.cli.main vault load` -- `python -m journal.cli.main search "test"` -- `./scripts/dotnet-min.ps1 --info` +# Troubleshooting + +## Python Environment + +### Wrong Python version + +Symptom: + +- Dependency install fails or runtime errors appear unexpectedly. + +Fix: + +- Use Python `3.14` for this baseline. +- Recreate virtual environment and reinstall dependencies. + +### spaCy backend issues + +Symptom: + +- spaCy import/model errors. + +Fix: + +- Use fallback backend: + +```powershell +$env:JOURNAL_NLP_BACKEND = "fallback" +python .\journal\run_desktop.py +``` + +### Desktop UI fallback on Windows + +Symptom: + +- Embedded desktop shell unavailable. + +Fix: + +- Current setup may open in browser mode automatically; this is expected in some Python 3.14 environments. + +## Vault Issues + +### Wrong password on load + +Symptom: + +- Vault load fails for existing files. + +Fix: + +- Re-run with the correct vault password. +- Confirm vault files are intact in `journal/vault/`. + +### Decrypted data still present + +Symptom: + +- Files remain in `journal/data/` after abnormal termination. + +Fix: + +- Use graceful shutdown path where possible. +- Manually clear decrypted workspace if needed. + +## C# Migration Workspace + +### NuGet or TLS errors + +Symptom: + +- `dotnet restore` fails with TLS/Schannel errors. + +Fix: + +- Run commands via `./scripts/dotnet-min.ps1` +- Confirm NuGet endpoint: + +```powershell +curl.exe -I https://api.nuget.org/v3/index.json +``` + +- Follow host repair guidance in `journal-master/journal/MINIMAL_MACHINE_SETUP.md` if needed. + +### Sidecar build/test checks + +```powershell +cd journal-master/journal +./scripts/dotnet-min.ps1 restore Journal.Sidecar/Journal.Sidecar.csproj +./scripts/dotnet-min.ps1 build Journal.Sidecar/Journal.Sidecar.csproj +./scripts/dotnet-min.ps1 run --project Journal.SmokeTests/Journal.SmokeTests.csproj +``` + +## Quick Diagnostics Checklist + +- `python -m journal.cli.main --help` +- `python -m journal.cli.main vault load` +- `python -m journal.cli.main search "test"` +- `./scripts/dotnet-min.ps1 --info` diff --git a/Vaults-and-Data-Handling.md b/WIKI_VAULTS.md similarity index 96% rename from Vaults-and-Data-Handling.md rename to WIKI_VAULTS.md index 3b3bb44..85986f4 100644 --- a/Vaults-and-Data-Handling.md +++ b/WIKI_VAULTS.md @@ -1,51 +1,51 @@ -# Vaults and Data Handling - -This page summarizes how Project Journal handles encrypted vault storage and decrypted working data. - -## Storage Model - -- Encrypted vault files live in `journal/vault/` -- Decrypted working files live in `journal/data/` -- Vault format is monthly: `YYYY-MM.vault` - -## Encryption - -- AES-256-GCM for vault payload encryption -- PBKDF2-HMAC-SHA256 key derivation -- Encrypted payload layout: `salt + nonce + tag + ciphertext` - -## Vault Workflow - -### Load - -When loading vaults: - -1. Decrypted data workspace is cleared -2. All monthly vaults are decrypted/extracted -3. Journal files are available for active editing/search - -### Save - -Two save patterns exist: - -- Current-month optimized save (faster in-session saves) -- Full vault rebuild from decrypted markdown files (comprehensive) - -## Security Notes - -- Decrypted files are intended to be temporary working data. -- Graceful shutdown path clears decrypted workspace. -- Keep backups of encrypted vault files, not decrypted data. - -## Operational Recommendations - -- Always run controlled shutdown to trigger cleanup. -- Use strong vault passwords. -- Store vault backups on trusted storage. -- Test restore procedures periodically. - -## Related Source Files - -- `journal/core/storage.py` -- `journal/core/encryption.py` -- `journal/core/config.py` +# Vaults and Data Handling + +This page summarizes how Project Journal handles encrypted vault storage and decrypted working data. + +## Storage Model + +- Encrypted vault files live in `journal/vault/` +- Decrypted working files live in `journal/data/` +- Vault format is monthly: `YYYY-MM.vault` + +## Encryption + +- AES-256-GCM for vault payload encryption +- PBKDF2-HMAC-SHA256 key derivation +- Encrypted payload layout: `salt + nonce + tag + ciphertext` + +## Vault Workflow + +### Load + +When loading vaults: + +1. Decrypted data workspace is cleared +2. All monthly vaults are decrypted/extracted +3. Journal files are available for active editing/search + +### Save + +Two save patterns exist: + +- Current-month optimized save (faster in-session saves) +- Full vault rebuild from decrypted markdown files (comprehensive) + +## Security Notes + +- Decrypted files are intended to be temporary working data. +- Graceful shutdown path clears decrypted workspace. +- Keep backups of encrypted vault files, not decrypted data. + +## Operational Recommendations + +- Always run controlled shutdown to trigger cleanup. +- Use strong vault passwords. +- Store vault backups on trusted storage. +- Test restore procedures periodically. + +## Related Source Files + +- `journal/core/storage.py` +- `journal/core/encryption.py` +- `journal/core/config.py`