obsidian-foundry-sync/CLAUDE.md

obsidian-foundry-sync: LLM Wiki

Mode: B (GitHub / Repository) Purpose: Map the architecture of the obsidian-foundry-sync tool — modules, data flows, and the design decisions behind them. Owner: Kaysser Kayyali Created: 2026-06-22

Structure

vault root (= this repo)
├── .raw/              # immutable source documents (README, code dumps, issue exports)
├── wiki/
│   ├── modules/       # one note per major module / package (server, push, batch, autosync, …)
│   ├── components/    # reusable pieces (content-hash guard, foundry block, name↔uuid resolver)
│   ├── decisions/     # Architecture Decision Records (ADRs)
│   ├── dependencies/  # external deps + services (relay, classic-level, linkedom, rest-api module)
│   └── flows/         # data flows / request paths (push, refresh, auto-sync watch loop, index)
├── _meta/
│   ├── index.md       # master catalog of all wiki pages
│   ├── log.md         # append-only operation log (newest at top)
│   ├── overview.md    # executive summary of the whole wiki
│   └── hot.md         # hot cache: ~500-word recent-context summary
├── _templates/        # one template per note type
└── CLAUDE.md          # this file

This repo is ALSO the obsidian-foundry-sync code project. The wiki layer (above) documents it; the code itself, build/test/usage, and the live-stack wiring live in README.md, src/, scripts/, docker-compose.yml, and .env.example. When doing code work, prefer those; when doing knowledge work, prefer the wiki.

Conventions

• All notes use YAML frontmatter: type, status, created, updated, tags (minimum). Module/flow/decision/dependency notes add the fields in their _templates/ file.
• Wikilinks use [[Note Name]] format: filenames are unique, no paths needed.
• .raw/ contains source documents: never modify them.
• _meta/index.md is the master catalog: update on every ingest/page creation.
• _meta/log.md is append-only: never edit past entries; new entries go at the TOP.
• _meta/hot.md is a cache, not a journal: overwrite it completely each time (keep <500 words).

Operations

• Ingest: drop a source in .raw/, say "ingest [filename]" (→ wiki-ingest).
• Query: ask any question; Claude reads _meta/index.md first, then drills in (→ wiki-query).
• Lint: say "lint the wiki" to run a health check (→ wiki-lint).
• Save: say "save this" / "file this" (→ save).
• Archive: move cold sources to .archive/ to keep .raw/ clean.

Cross-project referencing

Other Claude Code projects can point at this vault without duplicating context. In that project's CLAUDE.md, add a ## Wiki Knowledge Base block with Path: <this repo>, and the reading order: _meta/hot.md → _meta/index.md → wiki/<domain>/_index.md → individual pages.