torbenandClaude Opus 5.5
f9056c04f7
Files changed: - .gitea/workflows/ci.yml - .gitignore - .vibe/hooks.toml - AGENTS.md - CHANGES.md - EVALS.md - INSTALL-MCP.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/architecture.md - docs/explanation/language-boundaries.md - docs/explanation/telemetry-and-evaluation.md - docs/how-to/README.md - docs/how-to/browse-with-obsidian.md - docs/how-to/capture-repository-docs.md - docs/how-to/export-guidelines.md - docs/how-to/ingest-a-source.md - docs/how-to/maintain-the-wiki.md - docs/how-to/query-the-wiki.md - docs/how-to/run-the-weekly-review.md - docs/how-to/set-up-the-mcp-server.md - docs/how-to/trace-and-score-sessions.md - docs/how-to/troubleshoot.md - docs/how-to/update-an-instance.md - docs/reference/README.md - docs/reference/commands/distribution-and-versioning.md - docs/reference/commands/instance-health.md - docs/reference/commands/raw-material-and-uploads.md - docs/reference/commands/telemetry.md - docs/reference/commands/types-instructions-and-docs.md - docs/reference/configuration.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-build/SKILL.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - instructions/setup-instance.md - instructions/upgrade-instance.md - reports/CONTRACT.md - tools/.coveragerc - tools/CONTRACT.md - tools/README.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/doctor.py - tools/chemenu/commands/eval_cmd.py - tools/chemenu/commands/git_publish.py - tools/chemenu/commands/upload_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/evals/__init__.py - tools/chemenu/evals/scorecard.py - tools/chemenu/evals/trajectory.py - tools/chemenu/telemetry/policy.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_instructions_shell.py - tools/chemenu/tests/test_pipeline_l0.py - tools/chemenu/toc.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
55 lines
2.9 KiB
Markdown
55 lines
2.9 KiB
Markdown
# Browse the wiki in Obsidian
|
|
|
|
The wiki is a folder of Markdown files joined by `[[wikilinks]]`, so any Markdown editor can read
|
|
it. Obsidian adds a graph of the links between pages, which makes it a good way to look around.
|
|
|
|
## What you prepare
|
|
|
|
Open the instance's root directory as an Obsidian vault. Obsidian keeps its own settings in
|
|
`.obsidian/`. That folder is personal state: it is never shipped with a release, and it has no
|
|
effect on the wiki.
|
|
|
|
What you get:
|
|
|
|
- the graph view of how pages connect;
|
|
- navigation by wikilink, the way the agent writes them;
|
|
- plugins such as Dataview, which can query page frontmatter, or Marp for slides.
|
|
|
|
## Reading, not writing
|
|
|
|
Browse and read freely. Change pages through the agent, though, not by editing them in Obsidian. A
|
|
page carries generated frontmatter, cross-references and footnote citations that `tools/wikitool`
|
|
keeps consistent across the whole wiki. A hand edit can quietly break them. Renaming or moving a
|
|
file in Obsidian is the clearest case: a title is the page's only identifier, so it also appears in
|
|
every wikilink and citation that points at the page. A rename goes through
|
|
`tools/wikitool rename`, which updates every reference. The full procedure is
|
|
[instructions/page-lifecycle.md](../../instructions/page-lifecycle.md).
|
|
|
|
Generated files - `kb/index.md`, `kb/log.md`, `kb/provenance.md` and every `INDEX.md` - are
|
|
rebuilt by the tool and never edited by hand.
|
|
|
|
## How pages are named
|
|
|
|
Knowing the naming rules makes the vault easier to find your way in:
|
|
|
|
- **Titles are human-readable names with spaces:** `Hybrid Search.md`, not kebab-case. A wikilink
|
|
matches the file name exactly: `[[Hybrid Search]]`.
|
|
- **Entities are singular:** `HA Integration.md`, not `HA Integrations.md`.
|
|
- **A title follows the subject's own established name, not the wiki's language.** `Act Runner`
|
|
and `GitOps Ownership Model` keep their names in a German wiki too. Translating a title is a
|
|
rename, not an edit.
|
|
- **A title works on every operating system.** It contains none of `< > : " / \ | ? *`, is not a
|
|
reserved name such as `CON` or `Index`, does not end in a dot, and does not differ from another
|
|
page's title by case alone. A file's whole path below the instance root stays at 160 characters
|
|
or fewer, so a Windows checkout works without long paths. `wikitool new` and `wikitool rename`
|
|
refuse titles that break these rules, and `wikitool lint` reports existing ones.
|
|
[kb/CONTRACT.md](../../kb/CONTRACT.md) has the full rule.
|
|
|
|
## Letting the structure grow
|
|
|
|
- Start with a few broad categories and refine as the material arrives. Don't over-organise early.
|
|
- Use tags for concerns that cut across collections.
|
|
- Review what the agent changed from time to time - `kb/log.md` lists every operation - and tell it
|
|
when something is off. It keeps to the standards in `AGENTS.md` and the contracts, but you are the
|
|
one who notices when a page misses the point.
|