KiraTV---App-Linux/docs/architecture/external-wiki-sync.md

External Wiki Sync

Related:

• Workspace Shell
• SQLite DB Worker

Summary

• Repo docs are canonical, even when they were originally drafted by an LLM.
• The external Obsidian wiki imports canonical repo docs read-only into _repo-context/.
• Higher-level synthesis pages stay outside _repo-context/ in the wiki's own folders.
• Sync is one-way by default: repo docs -> wiki context.

Ownership Model

Canonical repo docs include:

1. docs/architecture/**/*.md
2. top-level workflow docs such as README.md, GETTING-STARTED.md, AGENTS.md, and CLAUDE.md
3. selected module README.md files when they describe current code behavior or workflows

The external wiki can add cross-links, feature pages, decision notes, and synthesis pages, but it must not become a second source of truth for the same implementation details.

Export Scope

The repo-owned exporter writes only to _repo-context/ inside the external vault.

Current default export scope:

1. docs/architecture/**/*.md
2. README.md
3. GETTING-STARTED.md
4. AGENTS.md
5. CLAUDE.md
6. selected module README.md files

The exporter also generates:

1. _repo-context/index.md
2. _repo-context/repo-map.md
3. _repo-context/recent-changes.md
4. _repo-context/manifest.json
5. _repo-context/state.json

Running The Exporter

Set the external vault path in the shell environment:

export IPTVNATOR_WIKI_VAULT=/absolute/path/to/your/obsidian-vault

Then run:

pnpm wiki:export --mode full
pnpm wiki:export --mode changed

You can also override the vault path per command:

pnpm wiki:export --mode changed --vault /absolute/path/to/your/obsidian-vault

If the vault path is missing, the exporter skips cleanly and reports why it did not run.

Agent Workflow After Changes

After a meaningful implementation change, agents must assess whether canonical repo docs need updates.

Documentation-worthy changes include:

1. new or changed user-visible behavior
2. architecture or data-flow changes
3. non-obvious maintenance workflows
4. new setup, debugging, or operational steps
5. new subsystem contracts or boundaries

Prefer updating an existing authoritative doc before creating a new one:

1. README.md for top-level developer or user workflows
2. docs/architecture/ for architecture, ownership, and behavior contracts
3. the nearest module README.md for local usage or behavior

If docs changed and IPTVNATOR_WIKI_VAULT is configured, agents should run pnpm wiki:export --mode changed before considering the task complete.

Promotion Workflow

If a wiki page becomes stable enough to be canonical:

1. promote that content back into a repo doc
2. treat the repo doc as the source of truth
3. export again so _repo-context/ reflects the promoted canonical doc

The wiki page can then either link to the repo-backed generated page or remain as a smaller synthesis page that references the canonical doc.