What a block is — the rules of this tree

A block is one block of knowledge. Every block declares its intent at birth: recipe if it defines how to act, truth if it claims how things are. Three sets of rules keep this tree good: what a block must be, how to write one, and how the tree changes shape.

What a block must be

• The title and summary must let a reader decide whether to open it, without opening it.
• If something must be done, it is written in the block itself. Links never carry obligations, only invitations.
• A block says how things work right now. No history, no "we used to." Old truth is deleted, not narrated.
• Say only what a reader can't learn at the moment of acting. If the system corrects a mistake the instant it's made, the block doesn't need to pre-teach it.
• Every block earns its place. A block nobody has needed is a candidate for deletion.

How to write

• Plain words. If a teenager couldn't follow it, rewrite it.
• Short sentences. One idea per paragraph.
• Every word costs the reader. Say it once, then stop.
• Use markdown: code for commands, routes and flags; lists for lists; bold for the few words that carry the weight.
• Don't use a technical term without teaching it, and don't teach what the reader already has.
• Knowledge addresses the reader as “you.” Whoever holds the credential is the reader. Only an identity block addresses a role.
• A link's reason is a condition, not a topic. Write it only if …. A reason that opens with when describes what is on the other side and reads as an invitation; only if states the test, and a reader who fails it walks past.
• Two kinds of reason are deliberately not conditional, and are not bugs to fix: the entry link into a role's own identity block, which must never gate against the role that needs it, and a last-resort link, which is already its own condition.

Where a rule belongs — four places, weakest to strongest; put each rule in the weakest place that actually holds it:

• A link's reason — advice; the reader may not follow it. For genuinely optional continuation only.
• The block body — guaranteed read by whoever fetched the block. For anything mandatory to act on that block.
• The reply at the moment of acting — guaranteed seen at exactly the right time. For corrections the system can make when a mistake happens.
• A platform door that refuses — cannot be skipped. For rules about form. A door can never judge meaning; only a person or their AI can.

One authored home per fact. The schema says what is possible, this tree says why and when, and the CLI renders the platform's words rather than carrying its own. A fact written in two authored places drifts.

How this tree changes shape

• Grow an existing block before creating a new one. A new block is born only when no existing title could honestly hold the content.
• Split a block when its title and summary can no longer sell everything inside — when a reader would open it for one thing and get mostly another.
• Merge two blocks when they are always read together — the link between them stopped earning its keep.
• Move content into a surviving block; never delete-and-recreate. Deleting a block kills every link into it and every address anyone was handed. Retitling is always safe — addresses survive it.
• After any reshuffle, re-read every touched link's reason. A reason that no longer tells the truth is a bug.
• A link's reason can be changed in place: PATCH the edge with its verb, its target and the new wording. The verb and the two ends are the edge's address rather than fields, so changing a verb still means deleting the edge and creating it again — and a failure between the two loses the edge and every address handed through it, so write the new edge immediately, then read it back off the tree before you move on.
• Read a block again immediately before you write it, and apply your change to that text. More than one session writes this tree, and a whole-block write built from a stale read erases whatever landed in between. The write door refuses that: send expectedUpdatedAt, the updatedAt your content read returned, and a block that moved since is refused with 409 and nothing written, so you re-read and re-apply. A caller that sends no version gets no refusal, so for that caller the rule in words remains the discipline: replace the exact sentence you are changing and refuse to write when it is not there exactly once, since that is what protects the other session.
• A list of branches in a block's body is not a mirror of its edges. List only what every reader should see, and leave worker machinery to its edges — an edge hides itself from an audience that cannot see its far end, but the words of a list are shown to everyone alike. Completing such a list into a full index publishes the names of private branches.
• Every new block ships reachable from the root, or named in the sweep that hunts orphans. A block nobody can walk to is a block nobody reads.
• No change without its check. Every edit ships with the thing that proves it — a contract case for a mechanical claim, a probe question for a knowledge claim. A change to the platform is held to the same rule, and it is not finished until whoever asked for it has used the thing that proves it.
• A rebuild is not verified until a reader of each kind has actually read the result — the owner and a caller without a credential both.

These rules apply to this block too.