Merge pull request #15 from rubakas/refactor/option-a-phase0-packaging

Simplify packaging (uv) + architecture; fix cost-report cache cost; add credential & precompact hooks

Author: verkligheten

.github/workflows/validate.yml

@@ -13,17 +13,15 @@ jobs:
         python-version: ["3.10", "3.12"]
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
-        run: |
-          pip install -e ".[dev]"
-          export PYTHONPATH=.
+        run: uv sync
       - name: Run tests
-        run: PYTHONPATH=. python3 -m pytest tests/ -v
+        run: uv run pytest tests/ -v
       - name: Verify build
-        run: PYTHONPATH=. python3 -m agent_notes build
+        run: uv run python -m agent_notes build
       - name: Validate configs
-        run: PYTHONPATH=. python3 -m agent_notes validate
+        run: uv run python -m agent_notes validate

README.md

@@ -31,12 +31,6 @@ pipx install agent-notes
 agent-notes install
 ```
 
-Update anytime:
-
-```bash
-pipx upgrade agent-notes && agent-notes install
-```
-
 **venv + pip (if you prefer to manage your own environment):**
 
 ```bash
@@ -45,12 +39,34 @@ pip install agent-notes
 agent-notes install
 ```
 
-Update anytime:
+### Upgrade from a previous version
+
+**Update in place (normal upgrade):**
+
+With pipx:
+```bash
+pipx upgrade agent-notes && agent-notes install
+```
 
+With venv:
 ```bash
 pip install --upgrade agent-notes && agent-notes install
 ```
 
+**Clean reinstall (from an older version, fresh slate):**
+
+If you are on a significantly older version or want a fresh configuration, uninstall completely and reinstall:
+
+With pipx:
+```bash
+agent-notes uninstall && pipx uninstall agent-notes && pipx install agent-notes && agent-notes install
+```
+
+With venv:
+```bash
+agent-notes uninstall && pip uninstall agent-notes && pip install agent-notes && agent-notes install
+```
+
 ### Local build (developers)
 
 ```bash
@@ -87,6 +103,36 @@ agent-notes config provider openrouter   # prints "configured" or "no key"
 
 </details>
 
+<details>
+<summary>Uninstall</summary>
+
+To fully remove agent-notes:
+
+**pipx:**
+
+```bash
+agent-notes uninstall
+pipx uninstall agent-notes
+```
+
+Run `agent-notes uninstall` first — it removes agent files, hooks, settings.json entries, context file, and state that agent-notes installed. Then `pipx uninstall` removes the package itself. The `agent-notes uninstall` command must run while the CLI is still installed.
+
+**venv:**
+
+```bash
+agent-notes uninstall
+deactivate
+rm -rf .venv
+```
+
+Run `agent-notes uninstall` first to clean up installed components, then deactivate the environment and delete the `.venv` directory.
+
+**Note on memory and vault permissions:**
+
+If you configured agent-notes to access your memory vault (Obsidian or local), those read/write permissions are intentionally left in place after uninstalling so Claude Code and other tools can still access your notes. To remove them, edit `~/.claude/settings.json` and delete the entries under `permissions.allow` that reference your vault path (e.g. `Read(/path/to/your/vault/**)`, `Write(/path/to/your/vault/**)`, `Edit(/path/to/your/vault/**)`).
+
+</details>
+
 ---
 
 <details>
@@ -377,6 +423,8 @@ By default, `agent-notes install` re-runs the interactive wizard and prompts for
 
 The plugin build scripts (`scripts/build-claude-plugin.sh`, `scripts/build-opencode-plugin.sh`) automatically use `.venv/bin/python` when present, fall back to system `python3`, and honor a `PYTHON=` override.
 
+**Note:** `uv` is used only in the local development and release workflow (see `scripts/release`). It is not required to install or use agent-notes — end users should use `pipx` or `pip` / `venv`.
+
 ### Test structure
 
 - `tests/functional/` — Unit tests

agent_notes/cli.py

@@ -291,7 +291,7 @@ def main():
 
     # hook
     p_hook = subparsers.add_parser("hook", help="Claude Code hook integrations")
-    p_hook.add_argument("subaction", choices=["memory-bridge", "session-discover"],
+    p_hook.add_argument("subaction", choices=["memory-bridge", "precompact-memory-bridge", "session-discover", "guard-credentials"],
         help="Hook to run")
 
     # cost-report