Add Troubleshooting

Troubleshooting.md

@@ -0,0 +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`