The rules below are the operating core for any agent writing into Wikilayer. Apply them on every edit. Style and anti-patterns sit on their own pages; this one is the structural floor.
Rules outlive the task you scanned them forbefore-read
When get_outline returns titles like "All commands through make" or "Never share .md URLs with humans", those rules apply for the rest of the session, not only to the task you fetched the outline for.
The failure mode: you skim the outline searching for some specific thing, see a rule-title in passing, register that "such a rule exists", then ten minutes later draft a plan step that violates it because the rule didn't fire when you were composing the plan.
Before any new phase of work — drafting a plan, writing code, sending a structural change — re-scan the outlines of rule-wikis (this guide, the codestyle wiki for the project at hand, any per-project CLAUDE.md you've already loaded) and read each title as a question: "does this affect what I'm about to do?"
Before writechecklist
Discipline that fires before any create_nodes or update_node call. Skipping these is how outlines drift and duplicates get added.
Read by outline, full depthbefore-read
Start every session with get_outline(wiki_id, max_depth=10). Stopping at h2 hides h3 children where real distinctions live. Without that depth you'll miss an existing block and create a duplicate. The outline is the wiki's mental map: titles alone should tell you what's where. Then search_nodes on the topic at hand to catch dupes hiding under different titles.
Leave include_markdown at its default false. The skeleton — titles, ids, token counts — is the whole point of reading by outline, and it stays small. Setting include_markdown=true pulls every descendant's full body into one response: on a sizable wiki that runs to tens of thousands of characters and overflows the tool-result limit, so the call returns truncated or spilled to a file and the cheap overview is lost. Read bodies only once you've narrowed to a specific block or small subtree, with get_node or a shallow max_depth outline on that node.
The outline paginates: at most 100 rows per call, so a full page means more remain. Page with offset until it comes back short. Never take a partial outline for the whole wiki, and never call something absent from a truncated read; confirm with search_nodes.
Re-scan parent load before adding a childbefore-write
Before any write call (create_nodes, update_node, patch_node, move_node): re-read the parent's outline AND write a one-line verdict in chat: "parent X, N children, themes [...], fits or drifts". Without a visible verdict the discipline stays mental-only and silently gets skipped. If the parent drifts, split into category siblings, move_node the existing children, then add.
Block structure
How each block sits in the tree: one claim, named correctly, no hidden subdivisions in the body.
Title is the headline of the bodybefore-write
The title is how a reader scanning the outline decides whether to open the body. When the body carries a rule, the title states that rule. When the body is descriptive — a biography, a story, a list — the title carries the subject plus enough scope to disambiguate. A title that only names the topic ("Background", "Details", "Other") wastes the outline: it forces every reader to open the body to find out whether anything inside applies to them.
Self-check after a write: read your own outline back. If you can't tell what's where from titles alone, the titles are wrong, not the depth.
One claim per blockbefore-write
One claim per block is the principle behind two narrower rules: its inline form, No bold-prefix subtopics inside one block, and its depth form, No oversized bullets that should be h3 children.
When you catch yourself adding "and also..." inside a block (a second rule, a second story, a second angle), split it into a sibling with its own title. Otherwise the second claim is invisible from the outline, reachable only by the readers who happened to open this particular body.
Write h2/h3 by defaultbefore-write
Flat h2-only outlines are an agent smell, not a style choice. If a block packs five parallel ideas as bold-prefix paragraphs or long bullets, those are h3 children waiting to happen.
No # headings inside markdown bodiesbefore-write
Every ## Section belongs in a child block, not in the body. A # inside a body invisibly hides sub-structure from get_outline: the parent looks single-node when it isn't, cross-links can't reach the would-be section, history records every change as one diff. The tree is the structure, not the markdown text.
References to nodes
How to point at other nodes in chat with humans and in markdown bodies.
Naming a node to a human means a clickable link, never a bare idbefore-read
Important
Whenever you name a specific node to a human — not merely paraphrase its topic — in a wiki body or in a chat reply, make it a clickable link. A bare title, even bolded or quoted, is not enough; the mention itself has to be clickable.
Two invariants hold in either medium: the mention is a link, and the internal id never shows in the visible text — not bare (3907(block 3907)(вики 6555)[3907](url)
The visible text depends on the medium. In a chat reply, use the node's title as the link text: a reply has no surrounding prose to weave into, and the title is how the human recognises the section. In a wiki body, weave the link into a natural noun phrase per the link anti-patterns — [the visa rules](page:N), not the bare title [Visa rules](page:N).
Every node you name individually must be a link; there is no discretion to name one and leave it as plain text. The only unlinked case is a set you refer to collectively without naming its members — a glossary, a category: link the covering node once (its nearest ancestor page or category) and leave the unnamed members out. Paste each URL verbatim from the tool response (url, or base_url + url_path).
One exception to all of the above: the human explicitly asks for an id to debug — give only that id, and no link is needed.
Never share .md URLs with humansbefore-read
The .md projection of a wiki or page (see Append .md to a URL for the stitched-markdown view) is for the agent's own re-reading. A human opening the same URL gets a wall of raw markdown with no chrome, broken anchors and lost cross-block links. When citing a node to a human, always use the HTML URL the tools return: the url field, or base_url joined with url_path.