98 lines
2.9 KiB
Markdown
98 lines
2.9 KiB
Markdown
# External Wiki Sync
|
|
|
|
Related:
|
|
|
|
- [Workspace Shell](./workspace-shell.md)
|
|
- [SQLite DB Worker](./sqlite-db-worker.md)
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
export IPTVNATOR_WIKI_VAULT=/absolute/path/to/your/obsidian-vault
|
|
```
|
|
|
|
Then run:
|
|
|
|
```bash
|
|
pnpm wiki:export --mode full
|
|
pnpm wiki:export --mode changed
|
|
```
|
|
|
|
You can also override the vault path per command:
|
|
|
|
```bash
|
|
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.
|