What a block is — the rules of this tree

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, write it in the block itself. A link is an invitation, not an order.
• Never assume the reader can open another page. If they need something to act, say it here.
• A block says how things work right now. No history, no "we used to." Old truth is replaced, not narrated. The platform keeps what a note said before, for its owner only, so nothing is lost by writing the present tense.
• 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.
• A block nobody uses should be deleted.
• A block never records a secret: a key, a password, a code or link that lets someone in, an email address, or the private details of a real person. The scoring section below flags anything that looks like one, for a person to check.

A public block never embeds a block address in its words. The edges carry the connections. If a link matters, it is an edge with a reason. If it does not matter to a stranger, it does not belong in the body. If an address is written into the text and its target turns private, the reader hits a dead end with no way to tell if it's private or just gone.

Fix the thing, don't warn about it.

Sometimes our own software behaves in a way people do not expect. You can either change it, or write a warning here so the next person is ready.

Change it. A warning doesn't stop anyone from hitting the problem — it just means they heard about it first.

Only write it down when it is not ours to change, such as how another company's product behaves. Then a warning is all you can do.

If you were about to warn someone about our own software, raise it as work instead.

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.
• Write a link's reason as only if …. A reason that starts with when just describes what's on the other side, and reads as an invitation. only if states a real test — a reader who fails it walks past.
• Two kinds of link don't need this, and that's fine, not a bug. The entry link into a role's own identity block must always stay open to that role. A last-resort link is already its own condition.

Where a rule belongs. There are four places, from weakest to strongest. Put each rule in the weakest one 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.

Don't copy what already has a home.

One authored home per fact: the one place where somebody wrote it down, as against the places that only show it. Don't write it here if it already lives in the code, a command's output, or a config file.

Two copies will drift apart, and then someone has to work out which one is right.

Here's who owns what:

• The code shows how things actually work, and what's possible.
• This tree explains why we chose it that way, and when it applies.
• The CLI only displays the platform's words. It has none of its own.

If it is not clear which one should be the home, stop and ask rather than write both.

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.
• 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, target and new wording. Changing the verb itself is different — the verb and the two ends are what identify the edge, so that means deleting the edge and creating a new one. If that fails partway through, you lose the edge and everything it carried. So create the new edge first, then read it back off the tree before you move on.
• Read a note 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 would erase whatever landed in between. The write door refuses that: every note edit carries baseFingerprint, the fingerprint your content read returned. A write with none is refused with 428 and nothing written. A write whose fingerprint is no longer current is refused with 409 and nothing written, and the refusal carries the note as it stands now, so you re-apply your change to those words and send the new fingerprint. The CLI keeps your refused draft in a file and prints its path. Every refused write is still a write you built from a stale read, so the discipline stands: replace the exact sentence you are changing and refuse to write when it is not there exactly once. A block that is not a note takes expectedUpdatedAt instead, and for it a caller that sends no version gets no refusal.
• A list of branches written in a block's body is not the same thing as its edges. List only what every reader should see there, and leave the rest as edges — an edge stays hidden from someone who can't open what it points to, but everyone sees a list the same way. Turning that list into a full index ends up publishing the names of branches meant to stay private.
• Every new block must be reachable from the root, or listed in the sweep that finds orphaned blocks.
• 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.

Question: should this passage be on the page

Scores: each passage Context: the whole page Ask: Judge only the marked passage. This page is written for someone about to write or edit a page in this knowledge base, who has been told nothing else. The rest of the page is shown so you can see what the marked passage adds to it. Do not judge how well the passage is worded, only whether that person needs it on this page. Which option describes the marked passage? Passes: belongs Act at: 0.4

• belongs: it gives a rule you can follow while writing, the reason a rule is so, or steps you carry out yourself, and you would not be told this at the moment you act, e.g. 'Say "is" and "has". Not "serves as", not "boasts".', 'Split a page when its title can no longer cover everything in it.', 'Name the source, because a claim nobody can check is no use.', or steps for getting a draft checked. An instruction to you belongs even when it is about using the software ('Open the link yourself before you save.'). A few short examples beside a rule are fine, and so is one unknown term in a passage whose instruction is still clear.
• cannot_say_what_it_means: even with the whole page beside it, a newcomer could not say in their own words what the passage means or what they would do differently because of it, e.g. it rests on several terms the page never explains ('the STATUS line the run rewrote'), on shorthand ('apply the R3 carve-out before the TTL lapses'), or on something that is not on the page ('do it the way we agreed for the last migration').
• told_when_you_act: it describes what the software does or answers at the moment you act, which you would see then without this page: a refusal and the code or message it answers with ('a write that sends no version is refused with 412 and nothing is saved'); what a command, a route or a flag does ('a PUT to a page's route replaces its whole text, and a field left out is cleared'); what happens to a thing when you delete, restore or erase it ('a deleted page goes to a bin with its links kept, and restore brings it back'); or how a check works inside and when to override it ('the refusal names the word it caught, and a hyphen counts as part of the word').
• checkers_detail: it states a rule you can follow, and then carries what only someone checking that rule needs: the full list of words to catch (six or more, e.g. 'delve, pivotal, landscape, testament, crucial, showcase…'), a threshold ('a score of 0.62 or more counts as a miss'), or a worked case ('given the sentence X, the check must catch Y').
• adds_nothing: take it out and you lose no rule, no reason and no instruction, e.g. it describes the page itself ('this is the checklist behind them'), says again what the page has already said ('As said above, keep it short.'), or comments on the rules without adding one ('These rules matter more than they look.').

Expect:

• "A door refuses a further list of words outright — ones no ordinary person says out loud. … The refusal names the word it caught, so this block does not repeat the list. … A hyphen sits inside a word … A space does not, so a phrase cannot be banned. The override flag exists for the rare line that genuinely needs the refused word … That is a finding to report, not a habit to pick up." -> told_when_you_act
• "Cut these on sight: delve, pivotal, landscape, testament, crucial, showcase, robust, seamless, leverage. None of them carries information a plainer word does not. Add to the list when you catch another." -> checkers_detail
• "A run is the exception, and the only one. A block carries a fact and its number, never the run that produced it — the STATUS line the run rewrote is where a run's number lives, and the captured session is the source if anyone needs to trace it." -> cannot_say_what_it_means
• "How words go out on this tree. The block rules say what a block must be; this is the checklist behind them, and every item is checkable — you can point at the word and delete it." -> adds_nothing
• "Two passes. Neither one catches what the other catches, so run both." -> belongs
• "The edit pass. Spawn a throwaway cold session. Hand it this block and your draft, and ask for specific edits — the word, the line, the replacement. Keep the edits you agree with and drop the rest. …" -> belongs
• "The reader pass. Spawn a second throwaway cold session and hand it the draft on its own. … Ask it two questions and nothing else: What can you not explain back in your own words? What is this telling someone to do?" -> belongs
• "Say is and has. Not "serves as", not "boasts", not "acts as a"." -> belongs
• "Lists for lists. A run of things named inside one sentence, duties, cases, steps, places, impacts, is a list, and it is written as dot points, one item per line. … An argument stays a paragraph, because bullets lose the reasoning that holds it together." -> belongs
• "- Plain words. If a teenager couldn't follow it, rewrite it." -> belongs
• "- Grow an existing block before creating a new one. A new block is born only when no existing title could honestly hold the content." -> belongs
• "If you were about to warn someone about our own software, raise it as work instead." -> belongs
• "These rules apply to this block too." -> adds_nothing

Question: is anything secret recorded here

Scores: each passage Context: the whole page Ask: Judge only the marked passage. The question is whether the marked passage records something secret or private, so that a person can be told to look at it. The rest of the page is shown so you can see whether a value is a real one or only an example, what a description in words points at, and who or what the marked passage is about. Which option describes the marked passage? Passes: nothing_secret, only_looks_like_one Act at: 0.2

• nothing_secret: ordinary writing: sentences, code, commands, a public web address, a block id, a UUID, a commit hash, or a sentence that says a thing is secret without saying what it is, e.g. 'The signing key is secret and only the owner holds it.'
• only_looks_like_one: it looks secret or private but gives nothing away: a placeholder ('YOUR_API_KEY', '<token>', 'xxxx', 'sk-...' with dots for the value), the name of a variable or file that holds a secret without the value ('BILLING_API_KEY', '~/.billing_key'), advice on storing a secret, a public figure or company named in the ordinary way, a role, a first name with nothing private attached ('ask Priya to review it'), or an example address ('jo@example.com').
• a_way_in: something a stranger could use, as written, to sign in, connect, join or open something locked, with or without a label near it: a real-looking key, password, token, private key, cookie or recovery code ('ADMIN_PASSWORD=fake-Tangerine-Bicycle-42'), an invite or reset link with its code, an address with a password in it ('postgres://reports:Not-A-Real-Pw-77@db.example.internal/ledger'), or the same told in ordinary words ('the door code is the year we moved in').
• private_persons_detail: a private person who could be picked out, by name or by description, together with something of theirs that is not the public's business: health, money, home address, phone number, family or legal trouble, or simply their real email address, e.g. 'Marisol Quenby is off until March for chemotherapy', 'call Tobin Ashgrove on 0491 570 006', 'sign in as maria.okafor@mail.test'.
• private_thing_named: it gives the name or the contents of something the passage or the page itself shows is not public: an unannounced project, an internal system or machine, a private page, a customer or a deal not yet announced, e.g. 'Project Marlowe (not announced yet) moves billing onto bill-core-02.corp.internal'.

Expect:

• "Set the key before the first run: STRIPE_KEY=sk_live_FAKEfakeFAKEfake0000notreal" -> a_way_in
• "If the deploy box asks for anything, type madeup-Heron-Lamp-9 and press enter." -> a_way_in
• "The reports read from postgres://reports:Not-A-Real-Pw-77@db.example.internal:5432/ledger every night." -> a_way_in
• "New contractors join the workspace here: https://app.example.com/invite/MADEUPmadeup2468FAKE" -> a_way_in
• "The server room door code is the year we moved into this office, followed by the street number." -> a_way_in
• "If the nightly job fails, call Tobin Ashgrove on 0491 570 006. He has been off with a back operation, so try twice." -> private_persons_detail
• "The only woman on the night shift at the Dunmore depot has asked for her pay to be advanced twice this year." -> private_persons_detail
• "Project Marlowe, which has not been announced, replaces the billing page in the spring, and it runs on bill-core-02.corp.internal." -> private_thing_named
• "Run it with your own key: export BILLING_API_KEY=YOUR_API_KEY, or pass --key sk-... on the command line. The CLI also reads the file ~/.billing_key." -> only_looks_like_one
• "Never paste a key into a page. Keep it in your password manager and load it into the environment when you need it." -> only_looks_like_one
• "To see the draft, sign in as dario.whitlock@mail.test and open the review page." -> private_persons_detail
• "Write to the list at hello@example.com, or to jo@example.com if it bounces." -> only_looks_like_one
• "Linus Torvalds wrote Git in 2005. Ask Priya to review the draft, then hand it to the on-call engineer." -> only_looks_like_one
• "The fix is in commit 3f9a1c27d4e5b6a7c8d9e0f1a2b3c4d5e6f70812 and the request id is 7b1e4c9a-2d3f-4a5b-8c6d-0e1f2a3b4c5d." -> nothing_secret
• "The signing key is secret. Only the account owner holds it, and it is never shown after it is made." -> nothing_secret