The wiki model

A Wikai wiki is just a folder of Markdown files on your disk. A few conventions make the whole thing work.

On-disk layout

wikis/<wiki>/
├── raw/         your original sources (books, PDFs, notes) — untouched
├── ingested/    rebuildable intermediates from ingestion
├── pages/       the Markdown pages Wikai maintains (by type)
├── work/        research / work documents (active/ and done/)
├── index.md     a catalog of pages, by type
└── log.md       an append-only record of every operation

Your raw/ sources are kept as-is; the wiki Wikai builds lives in pages/.

Pages and frontmatter

Every page is Markdown with a small YAML header. The required fields are title, type, summary, created, and updated. Common page types include source-summary (one per ingested source), entity (a person, place, or organisation), concept, book-chapter, and note.

Useful optional fields include tags, aliases (alternate names used to resolve cross-references), related, and origin (human, agent, or internet-search).

Links

Pages link to each other with ordinary Markdown links to wiki-relative paths, e.g. [Julius Caesar](pages/entities/julius-caesar.md). External links use a full URL. Wikai tracks these links so it can show what connects to what.

Block references and embeds

You can point at a single block — a paragraph, heading, list item, or quote — not just a whole page. Every block on an editable page carries a durable id, written as a trailing ^id token in the Markdown and hidden in every rendered view:

The stall speed rises with bank angle. ^a4a45a

Link to it by appending the id to the page path — or use just #^a4a45a to point at a block on the same page:

[as the handbook notes](pages/chapters/stalls.md#^a4a45a)

Following that link scrolls to the block and flashes it. Use image syntax instead and the block is embedded — its content renders inline where you put it, attributed back to the page it came from:

![](pages/chapters/stalls.md#^a4a45a)

The ids survive editing. Reword a paragraph, reorder it, split it, merge it — in the app or via an agent — and anything pointing at it still resolves. That’s what makes a citation to a specific sentence worth making.

Who can edit what

Each page carries an agent_edit policy: allow (the agent edits directly), review (the agent’s edits queue for your approval), or deny (only you edit it). Verbatim pages — like ingested book chapters — default to deny, so the source text stays faithful.

The index

Wikai keeps a smart index of your pages and their links (titles, types, tags, inbound/outbound links). It’s what makes search and cross-linking fast, and it updates within seconds as your files change.

Last updated 2026-07-12.