# 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.