This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
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:
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:
10-platform/git.md; it overrides Claude Code's default attribution (no co-authorship lines).50-decisions/ADR-0002-postgres-storage-and-versioning.md tracks the gaps and the planned move to PostgreSQL.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:
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.
# 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 GNEXUS_BOOK_STORAGE_BACKEND=db .venv/bin/python -m uvicorn app.main:app --port 3005
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.
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.
./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.
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.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.
owner, status, last_reviewed, review_interval, confidence, source_of_truth. Validation skips README.md and server/**; other Markdown (including ui/README.md) is checked.---. 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.unknown, redacted, password manager, vault, or ref:....docs link. When creating such an item, create the Markdown document first (the MCP inventory-creation guidance codifies this).last_reviewed only after the information was actually verified.60-generated/inventory-index.md is still a placeholder; no generator exists yet.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.
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.