# Homefoam Wiki Architecture & Automation Rules

This vault is a shared cognitive workspace for both human and agent. It is maintained by background LLM orchestration and semantic indexing, utilizing the QMD search engine.

## 1. Vault Organization
The vault uses a hybrid hierarchy. Do not create folders with numeric prefixes if they don't already exist unless listed below.
- `00-inbox/` - Unprocessed human notes.
- `00-inbox/agent/` - Raw, timestamped agent insights (memory store).
- `01-journal/` - Daily notes and chronologies.
- `02-projects/` - Active projects.
- `03-areas/` - Life and maintenance areas.
- `04-knowledge/topics/` - Canonical topic pages.
- `04-knowledge/entities/` - Canonical entity pages (people, organizations, etc).
- `04-knowledge/synthesis/` - Cross-topic conclusions and multi-source answers.
- `04-knowledge/hypotheses/` - Speculative connections generated by the Dreaming Cycle.
- `05-sources/` - External ingested materials, packaged as `sources/<slug>-<hash>/`.
- `system/` - System records, rules (this file), claim ledgers, and run logs.

## 2. Memory & Cognitive Cycles
- **Store**: Agents must write new insights as timestamped markdown files in `00-inbox/agent/`. Do not bypass the inbox to write unstructured facts directly into canonical pages.
- **Recall/Reflect**: Use standard file reads and QMD CLI/MCP tools.
- **Distillation Cycle (Nightly 03:30)**:
  1. Process `00-inbox/` (human and agent) into formal claims.
  2. Compact and deduplicate the existing claim graph.
  3. Re-evaluate dependent claims for modified sources.
- **Dreaming Cycle (Weekly)**: Traverse the QMD graph, synthesize non-obvious connections, and write speculative notes to `04-knowledge/hypotheses/`.

## 3. Evidence & Formal Claims
- **Location**: Per-page Markdown sidecars in `system/claims/`.
- **Identity**: Globally stable, opaque IDs (e.g., `clm-a1b2c3`).
- **Locators**: Exact locators (headings, line numbers, timestamps) are required.
- **Authored Notes**: For notes the human authors directly, cite the Git path and baseline commit (e.g., `path/to/note.md@commit`). Do not duplicate human notes into `05-sources/`.
- **Status Lifecycle**: `supported`, `inferred`, `conflicted`, `superseded`, `retracted`.
- **Confidence**: `high`, `medium`, `low`.
- **Contradictions**: Preserved as `conflicted`; the agent must not silently force a winner.

## 4. Editing Rules & Automation Guardrails
- **Privacy (.wikiignore)**: Paths in `.wikiignore` are strictly excluded from remote LLM/web processing.
- **Protected Markers**:
  - `<!-- wiki:private:start -->` ... `<!-- wiki:private:end -->` : Content inside is never sent to the LLM or indexed.
  - `<!-- wiki:protected:start -->` ... `<!-- wiki:protected:end -->` : Content inside may be read/indexed, but the agent must never rewrite it.
- **Rewrite Authority**: The agent may freely rewrite semantic content in eligible Markdown notes (unless protected). It must never overwrite, move, or delete raw source binaries, assets, attachments, or editor config files.
- **Failures & Recovery**: Operational failures (network, locks) can be retried. Semantic/content conflicts during automated sync must halt the job and leave `main` untouched; never attempt to force a Git conflict resolution on knowledge content.

## 5. QMD Search
- **Corpus**: Knowledge, sources, extracted text, and claim sidecars. (Exclude `system/runs`, `system/migration`, and raw binaries).
- **Tooling**: CLI and Stdio MCP.
- **Artifacts**: QMD config is committed. SQLite indexes and model caches must remain untracked.
- **Index Refresh**: Only run after a successful batch that actually altered indexable content.