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)
│   ├── books/<book>/        a book's index page and its chapters
│   ├── notes/daily/<YYYY>/<MM>/   daily notes
│   └── comments/<path>.md   comments on the page at pages/<path>.md
├── research/    work documents (active/ and done/)
├── chats/       your chat transcripts
├── 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/. A page’s comments live on a companion page at the same path under pages/comments/, so a chapter’s margin is one file beside the chapter, never a change to the chapter itself.

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), person, entity (a place, an organisation, anything else with a name), concept, book-index and book-chapter, note, and comments (a page’s margin — see Comments and highlights).

A page’s type is its own, not its folder’s. A concept filed under pages/notes/ stays a concept. A new page inherits the type of wherever you created it, and you can change it afterwards from the page’s metadata panel — the breadcrumb then tells you what the page is rather than just calling it a page.

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.

Moving and renaming

A wiki you keep for years is a wiki you keep rearranging, so moving a page is a first-class operation rather than something you do behind Wikai’s back. Drag a page to a different folder, or give it a better filename, and every link pointing at it is rewritten in the same step — including block references and image embeds. Images the page owns move with it, instead of being left behind as orphans.

Agents do this through the same operation, so a rearrangement started in chat leaves the graph just as intact.

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.

Long pages are indexed in sections, not just by their opening. A page is findable by any part of it, and a search result shows you the passage that actually matched rather than the first paragraph. Put a phrase in quotation marks to search for it literally; without quotes, the words are matched independently.

Last updated 2026-10-07.