What these rules are
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.
When to re-read them
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 depth
Start every session with get_outline(node_id=<wiki>, max_depth=-1, limit=100, offset=0). 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.
max_depth=-1 is the whole subtree, so nobody has to guess a number deep enough. limit and offset are required on every paged read: naming them is what makes the reading deliberate rather than a first page taken for the whole.
Bodies come later, and one page at a time
Leave include_body at its default false. The skeleton of titles, ids and token counts is the whole point of reading by outline, and it stays small. Setting include_body=true pulls every descendant's full body into one response: on a sizable wiki that overflows the read cap, and the cheap overview is lost.
Read bodies only once you've narrowed: a whole page comes back cheapest as one markdown document, a single block through get_node.
Page until has_more comes back false
A paged read returns as many rows as fit one response, which may be fewer than the limit you asked for, and has_more says whether any are left. Add the rows you got to the offset and ask again until it comes back false.
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 child
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". The same verdict also names where the new text folds: the sibling it merges into, or that no sibling covers it. Without a visible verdict both disciplines stay mental-only and silently get skipped, and text parked beside a block that already carries the claim is paid for on every later read. 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.
h2 names a section, h3 and deeper usually state a claim
The top level of a page is its table of contents: every h2 is the name of a section, a noun phrase of a few words, and it answers "what is this part about". It sits beside the page's own title and is set almost as large, so a sentence there competes with the title and reads as a second heading of the page rather than an entry under it.
A claim belongs one level down. At h3 and below the heading states the idea and the body argues it, which is what lets a reader take the idea off the outline and open the body only for the argument. Deeper levels may name a section too, wherever a node groups children rather than making a point: what decides is what the node holds, not the depth it sits at.
The one thing depth never decides is placement. A node sits where the structure puts it, and the title is written to fit that place; a claim that will not shorten into a section name is a sign the block belongs under one, not a reason to move it.
This also answers whether a title should restate its body. Under a section name it should not: the body carries the section's frame, and naming the topic is all the outline needs. Under a claim it already does, because the claim is the title.
Title is the headline of the body
Titles exist so that a read of the outline alone is a map of what the wiki holds. That is the test to apply, and the rest follows from it.
When the body carries one idea, the title states that idea, and the body is where it is argued: a reader who knows the claim can decide from the outline whether they need the argument. When the body is descriptive, a biography or a story or a list, the title carries the subject plus enough scope to disambiguate.
A framing title such as "Intro", "Core principle" or "Basics" is right where the body is the frame of the page rather than a claim inside it: it says "the ground everything here stands on, read it whole", and that is a true entry on the map. What is wrong is a title that promises nothing over a body that does carry a claim: "Background", "Details", "Other" force every reader to open the body to find out whether it 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 block
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.
Name the sections first, then put the claims inside them
A page written in one pass comes out flat: every paragraph becomes a top-level block, every heading a sentence, and the outline turns into a row of h2 claims with no shape. That is the default to resist, and it is the same defect as a block packing five parallel ideas into bold-prefix paragraphs, seen from the other side.
Name the sections first and put the claims inside them. A section name is short and thematic, a noun phrase naming a subject rather than a statement about it, because the top level is read as a table of contents and a claim there competes with the page's own title.
A page whose top level reads as a table of contents can be scanned; a page whose top level is a list of statements has to be read whole to find anything.
No # headings inside markdown bodies
Every ## Section belongs in a child block, not in the body, and the write tools refuse a body that carries one. The refusal names create_nodes and lists the sections it found, so the recovery is one call away.
What the refusal protects: a heading written into a body would leave the parent looking like a single node in get_outline when it isn't, give the would-be section no id for a cross-link to reach, and record every change under it as one undivided 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 id
Important
Whenever you name a specific node to a human, rather than 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, as [the visa rules](page:N) rather than 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 or 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 humans
The markdown document a public wiki or page serves at its .md URL 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.
The unit of review
The unit of review is the page with every block on it, even when the edit touched one. A block read on its own can only be judged against itself, and most of what makes writing here bad lives between blocks: a claim a sibling already carries, a contradiction with one, titles that stop reading as a chapter list once the new one joins them.
Placement is the reason the rule is absolute rather than a preference. An author puts a block where it seemed to fit, and a wrong page or a wrong parent is invisible from every vantage except the whole page: the block itself looks fine, its body says what it means to say, and only its neighbours show that it belongs somewhere else or that the page it landed on is now about two things.
So the reviewer gets the page and its tree, never a diff and never one node, and a finding about a block nobody touched counts exactly as much as one about the new text.