Update README env vars and remove stale Python sidecar references

- Replace JOURNAL_DATABASE_DIR with JOURNAL_DATA_DIR (matches devtool.json)
- Update JOURNAL_AI_PROVIDER options to none/llamasharp (no more python-sidecar)
- Remove JOURNAL_NLP_BACKEND, JOURNAL_PYTHON_EXE, JOURNAL_AI_SIDECAR_PATH, JOURNAL_AI_TIMEOUT_MS
- Add SDT_ENV_PROFILE and SDT_LOG_LEVEL env vars
- Update architecture diagram: LlamaSharpAiService, remove PythonSidecarClient
- Update DI registrations to match current code
- Add full SDT workflow table, env profiles section
- Remove legacy Python vault parity note

Co-Authored-By: Oz <oz-agent@warp.dev>
This commit is contained in:
Jacob Schmidt 2026-03-02 20:22:58 -06:00
parent 6482382572
commit 75852eac83

View File

@ -138,9 +138,9 @@ Entry (thin command dispatcher — shared by all three hosts)
├── Vault/ IVaultStorageService → VaultStorageService → IVaultCryptoService
├── Database/ IJournalDatabaseService (SQLCipher schema/key derivation/hydration)
│ IDatabaseSessionService (encrypted connection lifecycle after auth)
├── Ai/ IAiService → PythonSidecarAiService | DisabledAiService
├── Speech/ ISpeechBridgeService → PythonSidecarSpeechService | DisabledSpeechBridgeService
├── Sidecar/ PythonSidecarClient (shared Python process I/O), SidecarCli
├── Ai/ IAiService → LlamaSharpAiService | DisabledAiService
├── Speech/ ISpeechBridgeService → DisabledSpeechBridgeService
├── Sidecar/ SidecarCli
├── Logging/ CommandLogger, LogRedactor
└── Config/ IJournalConfigService → JournalConfigService
```
@ -172,26 +172,31 @@ NuGet package versions are managed centrally in `Directory.Packages.props`. Proj
### Encryption
- **Vault**: AES-256-GCM with PBKDF2-HMAC-SHA256 key derivation (600k iterations) — wire format matches the Python implementation for cross-language parity
- **Vault**: AES-256-GCM with PBKDF2-HMAC-SHA256 key derivation (600k iterations)
- **Database**: SQLCipher with PBKDF2-derived key
- Fragments and structured data are stored in the encrypted SQLCipher database; auth is required via `vault.load_all` or `db.hydrate_workspace`
- `DatabaseSessionService` holds the encryption password in memory after first auth and closes the connection on `vault.clear_data_directory`
### Environment Variables
**Journal backend:**
| Variable | Default | Description |
|----------|---------|-------------|
| `JOURNAL_PROJECT_ROOT` | auto-detected | Override project root (vault path resolution) |
| `JOURNAL_VAULT_DIR` | `<root>/journal/vault` | Override vault directory |
| `JOURNAL_DATABASE_DIR` | `<vault>/db` | Override SQLCipher database directory |
| `JOURNAL_AI_PROVIDER` | `none` | `none` or `python-sidecar` |
| `JOURNAL_PYTHON_EXE` | `python` | Python executable for AI/speech sidecar |
| `JOURNAL_AI_SIDECAR_PATH` | auto | Path to Python AI sidecar script |
| `JOURNAL_AI_TIMEOUT_MS` | 30000 | AI sidecar timeout |
| `JOURNAL_NLP_BACKEND` | `auto` | `auto`, `spacy`, or `fallback` |
| `JOURNAL_LOG_LEVEL` | `warning` | `trace`, `debug`, `information`, `warning`, `error`, `critical` |
| `JOURNAL_PROJECT_ROOT` | auto-detected | Override project root path (vault path resolution) |
| `JOURNAL_VAULT_DIR` | `<root>/journal/vault` | Override vault directory path |
| `JOURNAL_DATA_DIR` | _(empty)_ | Override decrypted data directory path |
| `JOURNAL_AI_PROVIDER` | `none` | AI provider mode (`none`, `llamasharp`) |
| `JOURNAL_LOG_LEVEL` | `warning` | Log verbosity (`trace`, `debug`, `information`, `warning`, `error`, `critical`) |
| `JOURNAL_WEB_DIST` | auto | Override web UI dist path for WebGateway |
**SDT orchestrator:**
| Variable | Default | Description |
|----------|---------|-------------|
| `SDT_ENV_PROFILE` | `dev` | Active runtime environment profile (`dev`, `ci`, `release`) |
| `SDT_LOG_LEVEL` | `information` | CLI log verbosity (`trace` through `critical`) |
---
## Journal.WebGateway
@ -472,8 +477,8 @@ Key registrations:
- `IVaultCryptoService``VaultCryptoService` (singleton)
- `IVaultStorageService``VaultStorageService` (singleton)
- `IJournalDatabaseService``JournalDatabaseService` (singleton)
- `IAiService``PythonSidecarAiService` or `DisabledAiService` (per `JOURNAL_AI_PROVIDER`)
- `ISpeechBridgeService``PythonSidecarSpeechService` or `DisabledSpeechBridgeService`
- `IAiService``LlamaSharpAiService` or `DisabledAiService` (per `JOURNAL_AI_PROVIDER`)
- `ISpeechBridgeService``DisabledSpeechBridgeService`
- `IJournalConfigService``JournalConfigService` (singleton)
- `CommandLogger` (singleton)
- `SidecarCli` (singleton)
@ -493,9 +498,34 @@ The `Command`/`Entry` pattern uses dot-notation actions. To add a module:
## SDT DevTool
`Journal.DevTool/` contains the pre-built SDT (Stan's Dev Tools) orchestrator and its Python build/automation scripts. See [`Journal.DevTool/README.md`](Journal.DevTool/README.md) for full documentation.
`Journal.DevTool/` contains the pre-built SDT (Stan's Dev Tools) orchestrator (`sdt.exe`) and its Python build/automation scripts. Workflows are defined in `devtool.json` at the repo root. See [`Journal.DevTool/README.md`](Journal.DevTool/README.md) for full documentation.
Key scripts in `Journal.DevTool/scripts/`:
### Workflows (`devtool.json`)
| ID | Label | Group | Description |
|----|-------|-------|-------------|
| `build-dotnet` | Build .NET Projects | Build | `dotnet build` — all C# projects in solution |
| `sidecar` | Publish Sidecar | Build | Build Journal.Sidecar as self-contained exe → output/ |
| `web` | Build Web UI | Build | Build SvelteKit bundle → Journal.App/build/ |
| `webgateway` | Publish WebGateway | Build | Publish ASP.NET host with embedded web UI (depends on `web`) |
| `tauri` | Build Tauri Desktop App | Build | Build desktop exe, no installer (depends on `sidecar`) |
| `tauri-nsis` | Build Tauri + NSIS Installer | Build | Build desktop exe with NSIS installer (depends on `sidecar`) |
| `all` | Full Release Build ✦ | Build | Sidecar → Web → WebGateway → Tauri, in dependency order |
| `sync-output` | Sync Build Assets to Output | Build | Sweep repo for newest builds and copy to output/ |
| `stage-output` | Stage Output Bundle | Build | Full publish + stage journalapp.exe into output/ |
| `run-gateway-dev` | Run WebGateway Server (Dev) | Dev | Start HTTP gateway via `dotnet run` at http://localhost:5180 |
| `run-gateway-prod` | Run WebGateway Server (Output) | Dev | Start compiled gateway from output/webgateway |
| `test` | Run Smoke Tests | Test | Run all ~80 integration tests in Journal.SmokeTests |
| `gate` | Run Migration Gate | Test | Full build + smoke tests + parity check |
| `nuget-export` | Export NuGet Cache | Cache | Prime and export .nuget cache to zip for offline use |
| `nuget-import` | Import NuGet Cache | Cache | Import cache zip and validate restore |
| `npm-clean` | Clean Node Modules | System | Remove Journal.App node_modules |
### Environment Profiles
SDT supports `dev`, `ci`, and `release` profiles (configured in `devtool.json` under `envProfiles`). Select the active profile via `SDT_ENV_PROFILE` or from the TUI.
### Key Scripts (`Journal.DevTool/scripts/`)
| Script | Purpose |
|--------|---------|
@ -514,5 +544,5 @@ Key scripts in `Journal.DevTool/scripts/`:
## Notes
- Journal content and templates persist in SQLCipher (`entry_documents`) under the vault DB directory.
- The legacy Python placeholder file `_init_vault.vault` is treated as obsolete — the C# backend ignores and removes it during vault load.
- The legacy placeholder file `_init_vault.vault` is treated as obsolete — the C# backend ignores and removes it during vault load.
- On Windows + Tauri, the sidecar process is spawned with `CREATE_NO_WINDOW` to suppress the console window.