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 # CLI Reference
Project Journal includes a command-line interface under `journal.cli.main`. Project Journal includes a command-line interface under `journal.cli.main`.
## Basic Usage ## Basic Usage
```bash ```bash
python -m journal.cli.main --help python -m journal.cli.main --help
``` ```
## Vault Commands ## Vault Commands
Load encrypted vaults: Load encrypted vaults:
```bash ```bash
python -m journal.cli.main vault load python -m journal.cli.main vault load
``` ```
Save vaults: Save vaults:
```bash ```bash
python -m journal.cli.main vault save python -m journal.cli.main vault save
``` ```
Notes: Notes:
- Vault commands prompt for password. - Vault commands prompt for password.
- Vault files are monthly and encrypted. - Vault files are monthly and encrypted.
## Search Commands ## Search Commands
Search by text: Search by text:
```bash ```bash
python -m journal.cli.main search "shutdown" python -m journal.cli.main search "shutdown"
``` ```
Search with filters: Search with filters:
```bash ```bash
python -m journal.cli.main search "trigger" --tag co-parent --type !TRIGGER --start-date 2026-02-01 --end-date 2026-02-21 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: Search by section:
```bash ```bash
python -m journal.cli.main search "anxiety" --section "Mental / Emotional Snapshot" python -m journal.cli.main search "anxiety" --section "Mental / Emotional Snapshot"
``` ```
Search checkbox states: Search checkbox states:
```bash ```bash
python -m journal.cli.main search --checked Masking python -m journal.cli.main search --checked Masking
python -m journal.cli.main search --unchecked Shutdown python -m journal.cli.main search --unchecked Shutdown
``` ```
## Server Commands ## Server Commands
Start server: Start server:
```bash ```bash
python -m journal.cli.main server start python -m journal.cli.main server start
``` ```
Stop server: Stop server:
```bash ```bash
python -m journal.cli.main server stop python -m journal.cli.main server stop
``` ```
## AI Chat Command ## AI Chat Command
```bash ```bash
python -m journal.cli.main chat "Summarize my last week patterns." python -m journal.cli.main chat "Summarize my last week patterns."
``` ```
## Devices Command ## Devices Command
List microphones: List microphones:
```bash ```bash
python -m journal.cli.main devices list python -m journal.cli.main devices list
``` ```
## Common Errors ## Common Errors
- `No decrypted journal entries found`: run `vault load` first. - `No decrypted journal entries found`: run `vault load` first.
- Date parsing errors: use `YYYY-MM-DD` for date filters. - Date parsing errors: use `YYYY-MM-DD` for date filters.
- No microphone listed: check device permissions and drivers. - No microphone listed: check device permissions and drivers.

105
Development-Workflow.md → WIKI_DEVELOPMENT_WORKFLOW.md

@ -1,52 +1,53 @@
# Development Workflow # Development Workflow
This page defines a lightweight workflow for a small team using phased migration and acceptance gates. This page defines a lightweight workflow for a small team using phased migration and acceptance gates.
## Recommended Board Columns ## Recommended Board Columns
- Backlog - Backlog
- Ready - Ready
- In Progress - In Progress
- Review/Test - Review/Test
- Done - Done
- Blocked - Blocked
## Card Template ## Card Template
Each work item should include: Each work item should include:
- Title - Title
- Owner - Owner
- Scope (single feature or defect) - Scope (single feature or defect)
- Acceptance IDs (if applicable) - Acceptance IDs (if applicable)
- Evidence required (test output, logs, screenshots, file refs) - Evidence required (test output, logs, screenshots, file refs)
- Done condition - Done condition
Example: Example:
- Title: `Phase 1 persistence: fragment repository` - Title: `Phase 1 persistence: fragment repository`
- Acceptance IDs: `DOM-001`, `API-001` (and phase note) - Acceptance IDs: `DOM-001`, `API-001` (and phase note)
- Evidence: smoke tests + sidecar roundtrip output - Evidence: smoke tests + sidecar roundtrip output
## Branching Guidance ## Branching Guidance
- Keep branches small and focused. - Keep branches small and focused.
- One branch per card when possible. - One branch per card when possible.
- Avoid mixing migration phases in one branch. - Avoid mixing migration phases in one branch.
## Review Rules ## Review Rules
- No `Pass` status without evidence. - No `Pass` status without evidence.
- Any intentional behavior divergence must be documented. - Any intentional behavior divergence must be documented.
- Keep security-sensitive changes reviewable and explicit. - Keep security-sensitive changes reviewable and explicit.
## Release Gate Mindset ## Release Gate Mindset
- Passing local build is not enough. - Passing local build is not enough.
- Use acceptance criteria as the source of truth for phase completion. - Use acceptance criteria as the source of truth for phase completion.
- Do not move frontend cutover work ahead of required parity gates. - Do not move frontend cutover work ahead of required parity gates.
## Documentation Expectations ## Documentation Expectations
- Update wiki pages when commands, dependencies, or behavior change. - Update wiki pages when commands, dependencies, or behavior change.
- Keep setup and troubleshooting pages current with real host issues encountered. - 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 # Project Journal Wiki
Welcome to the Project Journal documentation hub. 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. Project Journal is an offline-first journaling system with encrypted monthly vaults, desktop + CLI workflows, and optional local AI support.
## Wiki Pages ## Wiki Pages
Use these pages as your Gitea wiki starter set: Use these pages as your Gitea wiki starter set:
- `Home` (this page) - `Home` (this page)
- `Setup and Installation` (`WIKI_SETUP.md`) - `Setup and Installation` (`WIKI_SETUP.md`)
- `CLI Reference` (`WIKI_CLI.md`) - `CLI Reference` (`WIKI_CLI.md`)
- `Vaults and Data Handling` (`WIKI_VAULTS.md`) - `Vaults and Data Handling` (`WIKI_VAULTS.md`)
- `Troubleshooting` (`WIKI_TROUBLESHOOTING.md`) - `C# Migration Status` (`WIKI_CSHARP_MIGRATION.md`)
- `Development Workflow` (`WIKI_DEVELOPMENT_WORKFLOW.md`) - `Troubleshooting` (`WIKI_TROUBLESHOOTING.md`)
- `Development Workflow` (`WIKI_DEVELOPMENT_WORKFLOW.md`)
## Quick Start (Python Baseline)
## Quick Start (Python Baseline)
### Windows (CPU default)
### Windows (CPU default)
```powershell
cd Project_Journal ```powershell
py -3.14 -m venv .venv cd Project_Journal
.\.venv\Scripts\Activate.ps1 py -3.14 -m venv .venv
python -m pip install --upgrade pip .\.venv\Scripts\Activate.ps1
python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt python -m pip install --upgrade pip
python .\journal\run_desktop.py 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)
### Linux (CPU default)
```bash
cd Project_Journal ```bash
python3.14 -m venv .venv cd Project_Journal
source .venv/bin/activate python3.14 -m venv .venv
python -m pip install --upgrade pip source .venv/bin/activate
python -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt python -m pip install --upgrade pip
python ./journal/run_desktop.py 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
## Current Direction
- Python backend remains the active baseline.
- C# backend migration is in progress - Python backend remains the active baseline.
- Security posture target is HIPAA-capable architecture and safeguards (not a legal compliance certification claim). - 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
## Core References
- Project readme: `README.md`
- Python CLI: `journal/cli/main.py` - Project readme: `README.md`
- Python storage and vault logic: `journal/core/storage.py` - Python CLI: `journal/cli/main.py`
- C# backend readme: `journal-master/journal/README.md` - Python storage and vault logic: `journal/core/storage.py`
- C# minimal machine setup: `journal-master/journal/MINIMAL_MACHINE_SETUP.md` - C# backend readme: `journal-master/journal/README.md`
- C# minimal machine setup: `journal-master/journal/MINIMAL_MACHINE_SETUP.md`
## Safety Notice
## Safety Notice
Project Journal is a software tool and not a replacement for licensed mental health care, emergency services, or crisis intervention.
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) # C# Backend Parity Acceptance Criteria (Python Twin)
## Goal ## 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. 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 ## Parity Rule
Behavior parity is required. Internal implementation can differ. Behavior parity is required. Internal implementation can differ.
## Source of Truth (Current Python) ## Source of Truth (Current Python)
- `journal/core/storage.py` - `journal/core/storage.py`
- `journal/core/encryption.py` - `journal/core/encryption.py`
- `journal/core/parser.py` - `journal/core/parser.py`
- `journal/core/models.py` - `journal/core/models.py`
- `journal/core/database.py` - `journal/core/database.py`
- `journal/cli/main.py` - `journal/cli/main.py`
- `journal/ai/analysis.py` - `journal/ai/analysis.py`
- `journal/ai/chat.py` - `journal/ai/chat.py`
- `journal/core/speech.py` - `journal/core/speech.py`
## Definition of Done (Release Gate) ## Definition of Done (Release Gate)
1. All `P0` criteria below are marked `Pass`. 1. All `P0` criteria below are marked `Pass`.
2. Existing Python-created vault files load successfully in C# backend. 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. 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. 4. No plaintext journal data remains after graceful shutdown flow.
## Shared Fixture Corpus (Required) ## Shared Fixture Corpus (Required)
1. `fixtures/vaults/` 1. `fixtures/vaults/`
- Multiple months (`YYYY-MM.vault`) generated by Python app. - Multiple months (`YYYY-MM.vault`) generated by Python app.
- Includes at least one wrong-password test case. - Includes at least one wrong-password test case.
2. `fixtures/entries/` 2. `fixtures/entries/`
- Daily, deep, recovery, fragment-heavy entries. - Daily, deep, recovery, fragment-heavy entries.
- Includes multiline fragments, tags, checkboxes, unusual spacing. - Includes multiline fragments, tags, checkboxes, unusual spacing.
3. `fixtures/search/` 3. `fixtures/search/`
- Queries for text, section, tag, type, checked, unchecked, date ranges. - Queries for text, section, tag, type, checked, unchecked, date ranges.
4. `fixtures/ai/` 4. `fixtures/ai/`
- Stubbed LLM/embedding responses for deterministic comparison. - Stubbed LLM/embedding responses for deterministic comparison.
## Acceptance Matrix ## Acceptance Matrix
Use status values: `Not Started`, `In Progress`, `Blocked`, `Pass`, `Fail`. Use status values: `Not Started`, `In Progress`, `Blocked`, `Pass`, `Fail`.
| ID | Priority | Feature | Acceptance Criteria | Status | Owner | Evidence | | 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-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 | | | | 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-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-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-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 | | | | 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-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 | | | | 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-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-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-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-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-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-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-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 | | | | 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 | | | | 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-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 | | | | 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-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 | | | | 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-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 | | | | 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-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 | | | | 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-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-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 | | | | 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 | | | | 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 | | | | 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 | | 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) ## Mandatory Gate Tests (P0)
1. `Vault Compatibility` 1. `Vault Compatibility`
- Given existing Python vault fixtures, C# load succeeds with correct password. - Given existing Python vault fixtures, C# load succeeds with correct password.
- Wrong password consistently fails without partial corruption. - Wrong password consistently fails without partial corruption.
2. `Parser + Merge` 2. `Parser + Merge`
- Given fixture entries, C# parser output matches Python parser output for sections/fragments/checkboxes. - Given fixture entries, C# parser output matches Python parser output for sections/fragments/checkboxes.
- Saving edited entry preserves merge semantics. - Saving edited entry preserves merge semantics.
3. `Search` 3. `Search`
- For shared corpus, C# and Python return the same entry set for all P0 search filters. - For shared corpus, C# and Python return the same entry set for all P0 search filters.
4. `Transport` 4. `Transport`
- Sidecar commands for core actions produce stable JSON success/error envelopes. - Sidecar commands for core actions produce stable JSON success/error envelopes.
5. `Cleanup` 5. `Cleanup`
- After graceful shutdown sequence, decrypted workspace is empty. - After graceful shutdown sequence, decrypted workspace is empty.
## Migration Phases (Recommended) ## Migration Phases (Recommended)
1. `Phase 1: Fragment Vertical Slice` 1. `Phase 1: Fragment Vertical Slice`
- Complete `DOM-001`, `API-001`, persistence beyond in-memory. - Complete `DOM-001`, `API-001`, persistence beyond in-memory.
2. `Phase 2: Entry/Parser/Merge Twin` 2. `Phase 2: Entry/Parser/Merge Twin`
- Complete `DOM-002`, `PAR-*`, `MRG-*`. - Complete `DOM-002`, `PAR-*`, `MRG-*`.
3. `Phase 3: Vault/Crypto Twin` 3. `Phase 3: Vault/Crypto Twin`
- Complete `VLT-*`, `DAT-001`. - Complete `VLT-*`, `DAT-001`.
4. `Phase 4: Search + CLI Twin` 4. `Phase 4: Search + CLI Twin`
- Complete `SCH-*`, `CLI-*`, `CFG-001`. - Complete `SCH-*`, `CLI-*`, `CFG-001`.
5. `Phase 5: AI/Speech` 5. `Phase 5: AI/Speech`
- Complete `AI-*`, `SPC-001`. - Complete `AI-*`, `SPC-001`.
6. `Phase 6: Frontend Cutover` 6. `Phase 6: Frontend Cutover`
- Tauri frontend switches to C# backend only after all P0 criteria pass. - Tauri frontend switches to C# backend only after all P0 criteria pass.
## Rules for Change Requests ## Rules for Change Requests
1. Any intentional divergence from Python behavior requires: 1. Any intentional divergence from Python behavior requires:
- Written rationale. - Written rationale.
- New acceptance criterion replacing old one. - New acceptance criterion replacing old one.
- Migration note describing user-visible impact. - Migration note describing user-visible impact.
2. No removal of a `P0` criterion without both maintainers approving in writing. 2. No removal of a `P0` criterion without both maintainers approving in writing.
## Status Snapshot (2026-02-22, Phase 1.2 Progress) ## Status Snapshot (2026-02-22, Phase 1.2 Progress)
This section is a proposed status/evidence snapshot based on current code in: This section is a proposed status/evidence snapshot based on current code in:
- Python source: `Project_Journal/` - Python source: `Project_Journal/`
- C# migration: `Project_Journal/journal-master/journal/` - C# migration: `Project_Journal/journal-master/journal/`
It does not change release gates or acceptance definitions. It does not change release gates or acceptance definitions.
### Phase Summary ### Phase Summary
| Phase | Current State | Evidence | | 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 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 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 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 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 5: AI/Speech | Not Started | No C# AI/speech parity services yet. |
| Phase 6: Frontend Cutover | Not Started | P0 parity not yet achieved. | | Phase 6: Frontend Cutover | Not Started | P0 parity not yet achieved. |
### Proposed Acceptance Status Updates ### Proposed Acceptance Status Updates
| ID | Proposed Status | Evidence | Notes | | 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-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. | | 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-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-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-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#. | | 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-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#. | | 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-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-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-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-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-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-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-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#. | | 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#. | | 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-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#. | | 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-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. | | 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-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. | | 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-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. | | 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-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-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#. | | 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#. | | 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. | | 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. | | OBS-001 | In Progress | `journal-master/journal/Journal.Core/Entry.cs` | Actionable error envelope exists; structured logging/secret-scrub policy pending. |
### Snapshot Risks/Blockers ### Snapshot Risks/Blockers
1. Required fixture corpus (`fixtures/vaults`, `fixtures/entries`, `fixtures/search`, `fixtures/ai`) is still missing. 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. 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. 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 # Setup and Installation
This page covers local setup for the Python baseline and optional C# migration workspace. This page covers local setup for the Python baseline and optional C# migration workspace.
## Prerequisites ## Prerequisites
- Python `3.14` - Python `3.14`
- `pip` and virtual environment support - `pip` and virtual environment support
- Windows or Linux - Windows or Linux
- Optional: GPU drivers/toolkit if using `requirements_gpu.txt` - Optional: GPU drivers/toolkit if using `requirements_gpu.txt`
## Dependency Profiles ## Dependency Profiles
- `requirements_base.txt`: shared runtime dependencies - `requirements_base.txt`: shared runtime dependencies
- `requirements_cpu_only.txt`: base + CPU AI stack - `requirements_cpu_only.txt`: base + CPU AI stack
- `requirements_gpu.txt`: base + GPU AI stack - `requirements_gpu.txt`: base + GPU AI stack
- `requirements_nlp_optional.txt`: optional spaCy backend - `requirements_nlp_optional.txt`: optional spaCy backend
## Windows Setup (CPU default) ## Windows Setup (CPU default)
```powershell ```powershell
cd Project_Journal cd Project_Journal
py -3.14 -m venv .venv py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1 .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip 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 -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt
``` ```
Run desktop app: Run desktop app:
```powershell ```powershell
python .\journal\run_desktop.py python .\journal\run_desktop.py
``` ```
## Linux Setup (CPU default) ## Linux Setup (CPU default)
```bash ```bash
cd Project_Journal cd Project_Journal
python3.14 -m venv .venv python3.14 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
python -m pip install --upgrade pip 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 -m pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements_cpu_only.txt
``` ```
Run desktop app: Run desktop app:
```bash ```bash
python ./journal/run_desktop.py python ./journal/run_desktop.py
``` ```
## Linux GPU Setup (optional) ## Linux GPU Setup (optional)
```bash ```bash
cd Project_Journal cd Project_Journal
python3.14 -m venv .venv python3.14 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
python -m pip install --upgrade pip python -m pip install --upgrade pip
python -m pip install -r requirements_gpu.txt python -m pip install -r requirements_gpu.txt
``` ```
## Optional NLP Backend (spaCy) ## Optional NLP Backend (spaCy)
```bash ```bash
python -m pip install -r requirements_nlp_optional.txt python -m pip install -r requirements_nlp_optional.txt
python -m spacy download en_core_web_sm python -m spacy download en_core_web_sm
``` ```
NLP backend modes: NLP backend modes:
- `auto` (default): spaCy if available, fallback otherwise - `auto` (default): spaCy if available, fallback otherwise
- `spacy`: require spaCy and fail if unavailable - `spacy`: require spaCy and fail if unavailable
- `fallback`: always use fallback NLP heuristics - `fallback`: always use fallback NLP heuristics
Examples: Examples:
```powershell ```powershell
$env:JOURNAL_NLP_BACKEND = "fallback" $env:JOURNAL_NLP_BACKEND = "fallback"
python .\journal\run_desktop.py python .\journal\run_desktop.py
``` ```
```bash ```bash
export JOURNAL_NLP_BACKEND=spacy export JOURNAL_NLP_BACKEND=spacy
python ./journal/run_desktop.py python ./journal/run_desktop.py
``` ```
## C# Migration Workspace Setup (optional) ## C# Migration Workspace Setup (optional)
Location: `journal-master/journal/` Location: `journal-master/journal/`
Use: Use:
- `journal-master/journal/README.md` - `journal-master/journal/README.md`
- `journal-master/journal/MINIMAL_MACHINE_SETUP.md` - `journal-master/journal/MINIMAL_MACHINE_SETUP.md`
Quick check: Quick check:
```powershell ```powershell
cd journal-master/journal cd journal-master/journal
./scripts/dotnet-min.ps1 restore Journal.Sidecar/Journal.Sidecar.csproj ./scripts/dotnet-min.ps1 restore Journal.Sidecar/Journal.Sidecar.csproj
./scripts/dotnet-min.ps1 build 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 ./scripts/dotnet-min.ps1 run --project Journal.SmokeTests/Journal.SmokeTests.csproj
``` ```

196
Troubleshooting.md → WIKI_TROUBLESHOOTING.md

@ -1,98 +1,98 @@
# Troubleshooting # Troubleshooting
## Python Environment ## Python Environment
### Wrong Python version ### Wrong Python version
Symptom: Symptom:
- Dependency install fails or runtime errors appear unexpectedly. - Dependency install fails or runtime errors appear unexpectedly.
Fix: Fix:
- Use Python `3.14` for this baseline. - Use Python `3.14` for this baseline.
- Recreate virtual environment and reinstall dependencies. - Recreate virtual environment and reinstall dependencies.
### spaCy backend issues ### spaCy backend issues
Symptom: Symptom:
- spaCy import/model errors. - spaCy import/model errors.
Fix: Fix:
- Use fallback backend: - Use fallback backend:
```powershell ```powershell
$env:JOURNAL_NLP_BACKEND = "fallback" $env:JOURNAL_NLP_BACKEND = "fallback"
python .\journal\run_desktop.py python .\journal\run_desktop.py
``` ```
### Desktop UI fallback on Windows ### Desktop UI fallback on Windows
Symptom: Symptom:
- Embedded desktop shell unavailable. - Embedded desktop shell unavailable.
Fix: Fix:
- Current setup may open in browser mode automatically; this is expected in some Python 3.14 environments. - Current setup may open in browser mode automatically; this is expected in some Python 3.14 environments.
## Vault Issues ## Vault Issues
### Wrong password on load ### Wrong password on load
Symptom: Symptom:
- Vault load fails for existing files. - Vault load fails for existing files.
Fix: Fix:
- Re-run with the correct vault password. - Re-run with the correct vault password.
- Confirm vault files are intact in `journal/vault/`. - Confirm vault files are intact in `journal/vault/`.
### Decrypted data still present ### Decrypted data still present
Symptom: Symptom:
- Files remain in `journal/data/` after abnormal termination. - Files remain in `journal/data/` after abnormal termination.
Fix: Fix:
- Use graceful shutdown path where possible. - Use graceful shutdown path where possible.
- Manually clear decrypted workspace if needed. - Manually clear decrypted workspace if needed.
## C# Migration Workspace ## C# Migration Workspace
### NuGet or TLS errors ### NuGet or TLS errors
Symptom: Symptom:
- `dotnet restore` fails with TLS/Schannel errors. - `dotnet restore` fails with TLS/Schannel errors.
Fix: Fix:
- Run commands via `./scripts/dotnet-min.ps1` - Run commands via `./scripts/dotnet-min.ps1`
- Confirm NuGet endpoint: - Confirm NuGet endpoint:
```powershell ```powershell
curl.exe -I https://api.nuget.org/v3/index.json curl.exe -I https://api.nuget.org/v3/index.json
``` ```
- Follow host repair guidance in `journal-master/journal/MINIMAL_MACHINE_SETUP.md` if needed. - Follow host repair guidance in `journal-master/journal/MINIMAL_MACHINE_SETUP.md` if needed.
### Sidecar build/test checks ### Sidecar build/test checks
```powershell ```powershell
cd journal-master/journal cd journal-master/journal
./scripts/dotnet-min.ps1 restore Journal.Sidecar/Journal.Sidecar.csproj ./scripts/dotnet-min.ps1 restore Journal.Sidecar/Journal.Sidecar.csproj
./scripts/dotnet-min.ps1 build 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 ./scripts/dotnet-min.ps1 run --project Journal.SmokeTests/Journal.SmokeTests.csproj
``` ```
## Quick Diagnostics Checklist ## Quick Diagnostics Checklist
- `python -m journal.cli.main --help` - `python -m journal.cli.main --help`
- `python -m journal.cli.main vault load` - `python -m journal.cli.main vault load`
- `python -m journal.cli.main search "test"` - `python -m journal.cli.main search "test"`
- `./scripts/dotnet-min.ps1 --info` - `./scripts/dotnet-min.ps1 --info`

102
Vaults-and-Data-Handling.md → WIKI_VAULTS.md

@ -1,51 +1,51 @@
# Vaults and Data Handling # Vaults and Data Handling
This page summarizes how Project Journal handles encrypted vault storage and decrypted working data. This page summarizes how Project Journal handles encrypted vault storage and decrypted working data.
## Storage Model ## Storage Model
- Encrypted vault files live in `journal/vault/` - Encrypted vault files live in `journal/vault/`
- Decrypted working files live in `journal/data/` - Decrypted working files live in `journal/data/`
- Vault format is monthly: `YYYY-MM.vault` - Vault format is monthly: `YYYY-MM.vault`
## Encryption ## Encryption
- AES-256-GCM for vault payload encryption - AES-256-GCM for vault payload encryption
- PBKDF2-HMAC-SHA256 key derivation - PBKDF2-HMAC-SHA256 key derivation
- Encrypted payload layout: `salt + nonce + tag + ciphertext` - Encrypted payload layout: `salt + nonce + tag + ciphertext`
## Vault Workflow ## Vault Workflow
### Load ### Load
When loading vaults: When loading vaults:
1. Decrypted data workspace is cleared 1. Decrypted data workspace is cleared
2. All monthly vaults are decrypted/extracted 2. All monthly vaults are decrypted/extracted
3. Journal files are available for active editing/search 3. Journal files are available for active editing/search
### Save ### Save
Two save patterns exist: Two save patterns exist:
- Current-month optimized save (faster in-session saves) - Current-month optimized save (faster in-session saves)
- Full vault rebuild from decrypted markdown files (comprehensive) - Full vault rebuild from decrypted markdown files (comprehensive)
## Security Notes ## Security Notes
- Decrypted files are intended to be temporary working data. - Decrypted files are intended to be temporary working data.
- Graceful shutdown path clears decrypted workspace. - Graceful shutdown path clears decrypted workspace.
- Keep backups of encrypted vault files, not decrypted data. - Keep backups of encrypted vault files, not decrypted data.
## Operational Recommendations ## Operational Recommendations
- Always run controlled shutdown to trigger cleanup. - Always run controlled shutdown to trigger cleanup.
- Use strong vault passwords. - Use strong vault passwords.
- Store vault backups on trusted storage. - Store vault backups on trusted storage.
- Test restore procedures periodically. - Test restore procedures periodically.
## Related Source Files ## Related Source Files
- `journal/core/storage.py` - `journal/core/storage.py`
- `journal/core/encryption.py` - `journal/core/encryption.py`
- `journal/core/config.py` - `journal/core/config.py`