27 lines
2.5 KiB
Markdown
27 lines
2.5 KiB
Markdown
# 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.
|