Claude
e1c2ba96e2
- Q4 → Obsidian vault is the Notizen/ folder in Nextcloud (multi-device sync). Nexa reads via WebDAV using the existing NC_APP_PASSWORD — no filesystem mount. Ignore list pinned: .copilot/, .copilot-index/, .smart-env/, .caldav-sync/, assets/ (routed to Phase-3.2 visual queue), Templates/, BMO/, Excalidraw/. Index target: Notizen/**/*.md. - Q5 → canonical name is Karakeep; legacy Zoraxy alias hoarder.nuclide.systems kept for compatibility. - Q13 → Octoprint container is intentionally powered down most of the time. Phase-5 monitoring must skip names matching octoprint*. Reflected in docs/10 monitoring table and CLAUDE.md. - Q14 → Homepage Zoraxy widget config error; cosmetic, dropped from open questions and from docs/12 optimization list. - Q18 → SAIA does proxy embeddings but rate limit is 10 msg/min, unusable for ingest. TEI stays in Phase 3.1. - docs/12: stale items removed (Octoprint, Zoraxy widget, generic Immich vector idea); added new ones derived from the Obsidian discovery (plugin embedding collision, notify_push upgrade path, assets/ size note). - docs/04 integration matrix updated to describe Obsidian-via-Nextcloud read path explicitly. - docs/09 step-4 credentials list collapses NC Tasks / Calendar / WebDAV onto a single app password.
49 lines
4.1 KiB
Markdown
49 lines
4.1 KiB
Markdown
# 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 (legacy alias `hoarder.nuclide.systems`), Vaultwarden `:11001`, Pocket-ID `:1411`, Immich, Audiobookshelf, Paperless-ngx, Traccar, Prowlarr, plus MCP containers (`crawl4ai-mcp`, `markitdown-mcp`, `papersearch-mcp`).
|
|
- **Octoprint (LXC 106)** is *intentionally* powered down most of the time. Phase-5 monitoring must skip names matching `octoprint*` rather than alert on its Exited state.
|
|
- **Obsidian vault lives inside Nextcloud** at `nc.nuclide.systems/Notizen/` (multi-device sync via Nextcloud client). Nexa accesses it via WebDAV — read-only, no filesystem mount. Ignore list: `.copilot/`, `.copilot-index/`, `.smart-env/`, `.caldav-sync/`, `assets/` (visual queue, Phase 3.2), `Templates/`, `BMO/`, `Excalidraw/`. Index target: `Notizen/**/*.md`.
|
|
- **Decided for Nexa** (don't re-litigate without user input):
|
|
- Vector store: **reuse `qdrant_scientific`** with collections suffixed by modality (`nexa_knowledge_text`, `nexa_knowledge_visual`).
|
|
- Embeddings staged: **Phase 3.1** TEI + `BAAI/bge-m3` (text-only, 1024-dim). **Phase 3.2** swap to `infinity` and add `jinaai/jina-clip-v2` (768-dim, joint text+image space). All forward-compat fields (`modality`, `media_uri`, `graph_iri`, `nexa:pendingVisualIndex`) exist from 3.1 — adding the visual collection is additive.
|
|
- Graph store: **Ontotext GraphDB** (SPARQL/RDF), Phase 3.4. RDF schema in docs/08 already includes `nexa:modality` / `nexa:mediaUri` / `nexa:vectorCollection` / `nexa:pendingVisualIndex`.
|
|
- 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
|