From 40a0098f84407433564a0105a440d3f8edbb4016 Mon Sep 17 00:00:00 2001
From: stan44 <stanton.e@gmail.com>
Date: Sat, 21 Feb 2026 18:33:33 -0600
Subject: [PATCH] committed main

---
 README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..37f9d31
--- /dev/null
+++ b/README.md
@@ -0,0 +1,114 @@
+# Project_Journal
+
+A structured journaling system with encrypted monthly vaults, desktop UI, CLI tools, and optional AI-assisted analysis.
+
+## Support Matrix
+
+- Python: `3.14`
+- Platforms: Windows and Linux (first-class), macOS (best effort)
+- Default profile: CPU
+- Optional profiles: GPU, optional NLP backend
+
+## Dependency Profiles
+
+- `requirements_base.txt`: shared Journal runtime dependencies
+- `requirements_cpu_only.txt`: base + CPU AI stack
+- `requirements_gpu.txt`: base + GPU AI stack
+- `requirements_nlp_optional.txt`: optional spaCy backend (auto-fallback if unavailable)
+
+## Quickstart
+
+### 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
+```
+
+### Linux (GPU 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
+```
+
+### Windows PowerShell (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
+```
+
+On Windows + Python 3.14, `pywebview` is intentionally skipped due upstream
+`pythonnet` build compatibility. `run_desktop.py` will auto-fallback to opening
+the app in your system browser.
+
+### Optional NLP backend (spaCy)
+
+```bash
+python -m pip install -r requirements_nlp_optional.txt
+python -m spacy download en_core_web_sm
+```
+
+If spaCy is missing or unsupported, Journal now auto-falls back to built-in NLP heuristics.
+On current Python 3.14 environments, this optional install may be skipped due upstream spaCy compatibility.
+
+## Running
+
+### Desktop App
+
+```bash
+python ./journal/run_desktop.py
+```
+
+### CLI
+
+```bash
+python -m journal.cli.main --help
+python -m journal.cli.main vault load
+python -m journal.cli.main search "your query"
+```
+
+## NLP Backend Control
+
+Set `JOURNAL_NLP_BACKEND` to choose behavior:
+
+- `auto` (default): use spaCy when available, else fallback
+- `spacy`: require spaCy backend and fail clearly if unavailable
+- `fallback`: always use fallback heuristics
+
+Examples:
+
+```bash
+export JOURNAL_NLP_BACKEND=fallback
+python ./journal/run_desktop.py
+```
+
+```powershell
+$env:JOURNAL_NLP_BACKEND = "spacy"
+python .\journal\run_desktop.py
+```
+
+## Installer Script
+
+Use the Linux helper script:
+
+```bash
+./installreqs.sh
+./installreqs.sh --gpu
+./installreqs.sh --with-nlp
+```
+
+## Notes
+
+- Decrypted journal data in `journal/data` is cleared on graceful shutdown.
+- Vault save/load commands remain unchanged.