# Instructions for Claude (and other agents)

This file tells future automated runs what they need to know about this repo.

## Repo conventions

- **Documentation:** all docs live in `/docs/` and are numbered. Entry point is `docs/index.md`. When you add a doc, give it the next free `NN-` prefix and add a row to the index TOC.
- **Runtime artifacts:** live in `nexa-core/` (workflows, prompts, configs, scripts). Don't put `.md` documentation in there — link from `/docs/` instead.
- **Source-of-truth:** if a doc duplicates content from `nexa-core/config/*.md`, **delete the duplicate**. Single source of truth.

## Real infrastructure (verified from screenshots, May 2026)

- **Proxmox host** `nuc` at `192.168.1.20:8006` (PVE 9.1.9).
  - LXC 102 dns (AdGuard) — internal DNS, rewrites for `*.nuclide.systems`.
  - LXC 103 backrest — backup orchestration.
  - LXC 104 docker — main docker host at `192.168.1.40` (40 containers).
  - LXC 105 nextcloud — Nextcloud at `nc.nuclide.systems`.
  - LXC 106 octoprint — currently *Exited*; flagged in [docs/11](./docs/11-open-questions.md#q13).
  - LXC 108 zoraxy — reverse proxy at `192.168.1.4:8000`, TLS for `*.nuclide.systems`.
  - VM 100 haos — Home Assistant.
- **Already-running services on docker host** (don't redeploy):
  - Memos `:5230`, n8n `:5678`, LiteLLM `:4000` (UI LobeHub `:3210`), Qdrant (`qdrant_scientific`), ntfy `:7998`, Karakeep/Hoarder, Vaultwarden `:11001`, Pocket-ID `:1411`, Immich, Audiobookshelf, Paperless-ngx, Traccar, Prowlarr, plus MCP containers (`crawl4ai-mcp`, `markitdown-mcp`, `papersearch-mcp`).
- **Decided for Nexa** (don't re-litigate without user input):
  - Vector store: **reuse `qdrant_scientific`** with `nexa_*` collection prefix.
  - Embeddings: **TEI** (HF text-embeddings-inference), self-hosted, `bge-m3` candidate (Q15 still pending the model name).
  - Graph store: **Ontotext GraphDB** (SPARQL/RDF), Phase 3.4.
  - Chat model: SAIA via LiteLLM virtual key.

## When working on Nexa

1. **Read `docs/index.md` first** — it's the navigator.
2. **Open questions first.** Before writing code or workflow JSON, scan `docs/11-open-questions.md`. If your task touches an unanswered Q, **stop and ask** rather than picking a default. Append new blockers to that doc as `[ ] Q-NN`.
3. **Optimization findings.** When you spot infrastructure improvements, add them to `docs/12-optimization-opportunities.md` as a numbered bullet — don't just mention them in commit messages.
4. **Never inline secrets** in workflow JSON or `.env` committed to git. Use n8n credentials, LiteLLM virtual keys, or (longer term) Vaultwarden.
5. **Keep deployment minimal.** The default answer to *"do we need a new container?"* is **no** — the existing stack covers most needs.

## Branch policy

- This branch is `claude/organize-docs-deployment-7N4v2`. Push only here unless told otherwise.
- New work for an unrelated feature → new branch under `claude/<topic>`.

## Quick links

- [docs/index.md](./docs/index.md)
- [docs/09-deployment.md](./docs/09-deployment.md) — most-touched file during bring-up
- [docs/11-open-questions.md](./docs/11-open-questions.md) — read **before** assuming defaults