stan44/Project_Journal-Csharp_backend-Python-Frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

commit

stan44 2026-02-22 02:29:36 -06:00
parent 558f932c23
commit c9dbc48fc5
8 changed files with 664 additions and 615 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
CLI-Reference.md → 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.

105
Development-Workflow.md → 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`.

47
WIKI_GIT_WORKFLOW.md Normal file

@ -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).

117
Home.md → 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.

330
MIGRATION_ACCEPTANCE_CRITERIA.md → 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.

204
Setup-and-Installation.md → 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
```

196
Troubleshooting.md → 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`

102
Vaults-and-Data-Handling.md → 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`