# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repository is

Gnexus Book is a Git-backed personal infrastructure knowledge base plus the tooling that operates on it: a FastAPI backend, an MCP server for AI agents, and a Vue UI. The repository root **is** the data store — Markdown docs (numbered directories), YAML inventory in `40-inventory/`, JSON Schemas in `schemas/`, and an audit/pending-change area in `90-maintenance/pending-changes/`.

Two consumers must keep working:

- humans reading Markdown/YAML from Git;
- AI agents calling the MCP tools, which must not bypass validation or Git safety checks.

## Platform handbook (mandatory)

Rules for the whole Gnexus ecosystem live in `~/Projects/gnexus-handbook` (https://git.gnexus.space/root/gnexus-handbook), not here. Before changing authentication, MCP/keys, UI, secrets, backups, health, deployment, or documentation policy, read the handbook README and the relevant section. Link to the handbook instead of copying its rules.

Notable for this repository:

- Commit messages follow `10-platform/git.md`; it overrides Claude Code's default attribution (no co-authorship lines).
- This file-backed prototype predates several handbook conventions (SSO, per-user MCP keys, streamable-HTTP MCP, off-host verified backups). `50-decisions/ADR-0002-postgres-storage-and-versioning.md` tracks the gaps and the planned move to PostgreSQL.

## Common commands

### Server

```bash
cd server
python3 -m venv .venv && . .venv/bin/activate   # or: uv venv --python 3.11
pip install -e ".[dev]"

# Run all tests
.venv/bin/python -m pytest -q

# Run a single test
.venv/bin/python -m pytest tests/test_api.py::test_health_endpoint -q

# Dev API (README uses 8080; the Vite proxy expects 3005)
.venv/bin/python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 3005

# MCP server (stdio by default)
.venv/bin/python -m app.mcp_server
```

MCP environment: `GNEXUS_BOOK_REPO_ROOT` (defaults to the repo root derived from `server/app/config.py`) and `GNEXUS_BOOK_MCP_TRANSPORT` (`stdio` | `sse` | `streamable-http`). Production agents use streamable HTTP at `/mcp-protocol/` with a personal `mcp_*` key:

```bash
cd server
GNEXUS_BOOK_MCP_HOST=0.0.0.0 GNEXUS_BOOK_MCP_PORT=8001 .venv/bin/python -m app.mcp_http
```

Keys are managed through `/mcp-keys` (session) and `/internal/keys` (service secret, not exposed by nginx); `mcp_tokens` stores only a SHA-256 hash and a tail hint, never plaintext.

### PostgreSQL read backend (Phase 1)

```bash
# From the repo root: local dev cluster on 127.0.0.1:5433
./scripts/dev-db.sh start

cd server
export GNEXUS_BOOK_DATABASE_URL="$(../scripts/dev-db.sh url)"
.venv/bin/alembic upgrade head
.venv/bin/python -m app.storage.cli import --replace
.venv/bin/python -m app.storage.cli parity     # exits 1 on a file/DB difference
.venv/bin/python -m app.storage.cli migrate --replace --manifest /tmp/report.json

# Rehearsed/real cutover and rollback verification
../scripts/cutover-db.sh --replace
../scripts/rollback-cutover.sh

GNEXUS_BOOK_STORAGE_BACKEND=db .venv/bin/python -m uvicorn app.main:app --port 3005

# Local stack with database storage and gnexus-auth (loads server/.env)
../scripts/dev-server.sh
../scripts/dev-mcp.sh
```

`server/.env` is gitignored and holds the local database URL, OAuth client, webhook
secret and internal key secret; systemd loads it through `EnvironmentFile`. Local SSO
details are in `30-runbooks/local-auth-testing.md`.

`GNEXUS_BOOK_STORAGE_BACKEND` defaults to `file`. Dumps go to the off-host NFS via
`scripts/backup-db.sh`; `scripts/restore-db.sh` requires `GNEXUS_BOOK_RESTORE_YES=1`.

### UI

```bash
cd ui
npm install
npm run dev     # port 3006, proxies /api -> http://127.0.0.1:3005
npm run build   # outputs dist/
```

`gnexus-ui-kit` is a local `file:../../gnexus-ui-kit` dependency (sibling of the repo root), built from `https://git.gnexus.space/root/gnexus-ui-kit`. `ui/vite.config.js` dedupes Vue, resolves Vue's ESM bundler build, and serves the kit's fonts from `node_modules/gnexus-ui-kit/dist/assets/fonts`.

### Deploy (VPS)

```bash
./scripts/install.sh   # uv + Python 3.11, nvm/Node, clone/build ui-kit, venv, UI build, systemd user units
./scripts/deploy.sh    # git pull, rebuild kit + UI, sync UI dist to /var/www/gnexus-book, restart backend, reload nginx
```

`systemd/*.service` hardcodes `/home/ubuntu/gnexus-book` paths — adjust them if the deployment user differs. Nginx (`nginx/gnexus-book.conf`) serves `ui/dist` on port 80, proxies `/api/` to the backend on 8000 and `/mcp/` to the MCP server on 8001.

## Backend architecture

`server/app/main.py` is the FastAPI composition root. Every route depends on a repository class constructed from `app/config.py:Settings`; `Settings()` defaults `repo_root` to `server/../..`, and tests pass `Settings(tmp_path)` to build isolated fake repositories.

The domain layer is split by responsibility:

- **`docs_repository.py` + `markdown.py`** — list/read/search Markdown under the repo root, skipping `.git`, `.venv`, `node_modules`, etc. The frontmatter parser is deliberately simple: only a flat `key: value` block between the first `---` fences is parsed. Nested YAML or typed values in frontmatter are not supported.
- **`inventory.py`** — reads `40-inventory/<type>.yml`; each file is a YAML list and items are looked up by `id`.
- **`relationships.py`** — builds a graph whose node ids are `<inventory-type>/<id>` and whose edges come from known cross-record fields (`host`, `hypervisor_host`, `runs_services`, `points_to`, `destination`, `related_*`, etc.). References to unknown ids are returned in `unresolved_references` rather than failing the request.
- **`freshness.py`** — checks required frontmatter fields and staleness (`last_reviewed` + `review_interval`, e.g. `90d`), and reports inventory `docs:` targets that do not exist.
- **`validation.py`** — the full-repo gate used before apply/commit: schemas parse as Draft 2020-12, every inventory file validates against its schema (`SCHEMA_BY_INVENTORY`), Markdown has required frontmatter, ids are unique per inventory file, and a regex scan detects raw secret assignments/private-key blocks. The separate inventory `docs`-link validator (`_validate_inventory_doc_links`) is intentionally disabled; freshness still reports those missing targets.
- **`pending_changes.py`** — the write path. A proposal is a JSON file in `90-maintenance/pending-changes/`; `apply()` writes a Markdown doc or patches/creates an inventory item, runs whole-repo validation, and restores the previous file content if validation fails. Only `doc` and `inventory-item` kinds can be applied; full-file inventory replacement is not implemented.
- **`git_adapter.py`** — status/diff/commit. Commit requires an explicit file list, rejects absolute/traversal/denied paths, runs validation first, stages only the named files, and creates a local commit only (never pushes).
- **`auth/`** — gnexus-auth integration: OAuth 2.0 PKCE login/callback, hashed browser sessions, user mirror, HMAC webhook handling, a pure-ASGI session guard, personal MCP key management (`mcp_keys.py`, `mcp_routes.py`), the MCP bearer guard (`mcp_guard.py`), and the actor context used by writes. Authentication is disabled unless `GNEXUS_BOOK_AUTH_CLIENT_ID`, `..._CLIENT_SECRET`, `..._BASE_URL`, and `..._REDIRECT_URI` are set; disabled mode is intentional for local development. The guard exempts `/health`, `/me`, `/auth/*`, and `/webhooks/gnexus-auth*`. The `gnexus-gauth` client library is a pinned git dependency.
- **`storage/`** — the PostgreSQL layer introduced for the migration. `models.py` defines the schema (documents/versions/blobs, inventory items/versions, changesets, users, audit), `db_repositories.py` implements the read interfaces, `pending_changes_db.py` implements draft/apply changesets transactionally, `documents.py` provides history/version/diff/restore, `validation.py` validates the database, `importer.py` copies the repository into PostgreSQL, `parity.py` compares both backends, and `cli.py` exposes `import`, `parity`, and `counts`. `factory.py` selects docs/inventory/pending repositories from `GNEXUS_BOOK_STORAGE_BACKEND`. Alembic lives in `server/alembic/`. In `db` mode all knowledge writes go through changesets; `commit_changes` is a no-op. Validation, freshness, and relationships use the selected backend.

### MCP server

`server/app/mcp_server.py` exposes the same domain functions (not HTTP) as 17 MCP tools plus `gnexus-book://*` resources. The long tool descriptions and `MCP_INSTRUCTIONS`/`AGENT_USAGE_GUIDE` strings are covered by tests in `tests/test_mcp_server.py`; update the tests when changing that guidance. `GET /mcp/info` reflects the registered tools and instructions.

The MCP guidance tells external agents never to edit repository files directly and to use propose → apply → validate → commit. That rule is for MCP clients; normal development in this checkout edits files directly, but still run validation before committing.

## Documentation and data conventions

- Every knowledge document needs frontmatter with `owner`, `status`, `last_reviewed`, `review_interval`, `confidence`, `source_of_truth`. Validation skips `README.md` and `server/**`; other Markdown (including `ui/README.md`) is checked.
- Inventory files are YAML sequences beginning with `---`. Item ids must be unique within a file. Adding a new inventory type requires both `40-inventory/<type>.yml` and an entry in `validation.SCHEMA_BY_INVENTORY`.
- Never store raw passwords, tokens, private keys, recovery codes, or session cookies. Describe where a secret lives using reference values such as `unknown`, `redacted`, `password manager`, `vault`, or `ref:...`.
- Some inventory schemas require a `docs` link. When creating such an item, create the Markdown document first (the MCP inventory-creation guidance codifies this).
- Update `last_reviewed` only after the information was actually verified.
- `60-generated/inventory-index.md` is still a placeholder; no generator exists yet.

## UI architecture

The frontend is a single Vue 3 app in `ui/src/main.js` (no router). It uses a drawer shell with pages: docs (search, history, diff, proposals), inventory (JSON/raw), changes (apply), status, MCP keys, and settings. `ui/src/i18n/` holds flat en/uk/ru dictionaries; navigation labels must be `computed` because `t()` reads the reactive locale. The auth gate calls `/api/me`; sign-in redirects through `/api/auth/login`, and gnexus-auth returns to `/auth/callback` (Vite proxies `/auth` and `/webhooks`, nginx proxies them in production). All data goes through `/api`. Avoid copying UI-kit styles locally; prefer upstream changes in the kit.

## Testing notes

Tests run from `server/` with `pythonpath = ["."]`. Most tests read the real repository, so they assert on real inventory/docs content; fixture-based tests use `Settings(tmp_path)` and copy schemas from the real repo.

Database tests use `GNEXUS_BOOK_TEST_DATABASE_URL` (default `postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book_test`) and skip when PostgreSQL is unavailable. `tests/test_db_storage.py` covers read parity, `tests/test_db_changesets.py` covers versioning/changesets/history/diff/restore, `tests/test_auth.py` covers login, sessions, `/me`, the route guard and signed webhooks with mocked gnexus-auth HTTP calls, `tests/test_mcp_keys.py` covers internal provisioning, the user key API, the MCP bearer guard, rate limits, actor selection and key revocation on user block, and `tests/test_migrations.py` applies the Alembic migration to a temporary database.

`tests/test_docs_repository.py::test_freshness_report_is_clean_for_knowledge_docs` is date-dependent: it fails once documents pass their `review_interval`. When it fails, refresh `last_reviewed` only for docs whose content was actually reviewed, or treat the failure as genuine staleness.
