echo6-docs/CLAUDE.md

Echo6 Docs Vault — Claude Guidelines

This repo (echo6-docs, canonical on Forge) is both an Obsidian documentation vault (vault/) and its self-contained maintenance engine (engine/).

The documentation model

• Documentation library only. Do NOT create entity/concept/node pages or stubs — nothing exists just to be a graph dot.
• Tags = categories. Each doc carries 1–3 honest category tags in frontmatter. Default to ONE; add a second only if the doc is genuinely about two co-equal subjects. The tag vocabulary lives in engine/config.yaml (topic_categories).
• Inline [[wikilinks]] point ONLY to existing docs. Never link to a non-existent target (zero unresolved/red nodes). If a thing has no doc, leave it as plain text.
• No INDEX.md — tags organize, not a hub.
• Frontmatter: title, type, tags, related, updated (+ optional aliases, status). type ∈ reference|runbook|project|note|session.

The engine (engine/) — how it works

• Runs on cortex RTX A4000. Tagger = vault-tagger (Qwen2.5-7B-Instruct) via Ollama (localhost:11434); embeddings = bge-m3 via TEI (localhost:8090) for related:. Pure stdlib HTTP, no cloud.
• Daily cron at 09:00 UTC (GPU-guarded): engine/sweep.sh → lint + tag + link changed docs. Internals: engine/sweep.sh, engine/lib/agent.py, engine/lib/lint.py, engine/config.yaml.
• Symlink guard: agent.py skips symlinks (os.path.islink); sweep.sh uses find -type f to exclude them. vault/CLAUDE-baseline.md and vault/rules/ are symlinks to ~/.claude/ — the engine skips them automatically.
• Run manually: python3 engine/lib/agent.py <doc> (one doc), engine/sweep.sh (changed docs), engine/sweep.sh --all.
• Lint (engine/lib/lint.py): dead links (stay 0), untagged docs, orphans, unknown tags, gap report (terms across many docs with no own doc — Matt decides whether to create one).

Going forward

When you ADD or EDIT a doc: honest category tags, [[wikilink]] only existing docs, no invented pages. The gap report (engine/lib/lint.py) surfaces candidates for new docs; the next sweep links mentions once a doc exists.

Sync & safety

Double-synced: Obsidian LiveSync ↔ edge2 CouchDB, and echo6-docs-autocommit cron (every 6h → Forge). (Syncthing was decommissioned 2026-06-19 — service masked, local state removed; Forge is the durable backup.) Mass file ops require care — commits happen automatically. Secrets live in credentials (the one documented exception to no-secrets-in-repo); never put secrets in a graph-tracked doc.