Writing and organising the brain

The brain fills itself in as goblins work, but the pages you write are the ones that change what they do. This page is the practical half: getting knowledge in, keeping it findable, and rearranging it without breaking anything.

Writing a page

A page is an address, an optional title, and markdown. The editor shows your text beside a live preview, which is rendered by the same pipeline the published page uses — so what you are looking at while you write is what the page will be.

Tags are optional and flat: docs, runbook, security. They cut across folders, which is what makes them worth having — a tag collects pages that live in different places, where a folder collects pages that live in the same one.

One thing worth knowing: saving replaces a page's tags with whatever the editor submits. The tag control exists so that a save always states them, rather than a content edit quietly clearing them.

Choosing an address

Addresses are lowercase letters, numbers and dashes, in segments separated by /. conventions/testing, people/alice, runbooks/rollback.

The address is the page's identity, so it is worth ten seconds of thought:

• Name the thing, not the moment. runbooks/rollback still makes sense next year; notes/tuesday-meeting does not.
• Group by how you will look for it, not by who wrote it. deploys/staging beats alice/deploy-notes.
• Shallow beats deep. Two levels is almost always enough. A brain is browsed by searching and by following links, not by clicking down a tree.
• It is what gets referred to. A goblin writing "see conventions/testing" in a sentence creates a link, so an address that reads naturally in prose is an address that gets cited.

Addresses can be changed later, and changing one repairs the references — see below.

Bringing what you already have

If your conventions currently live in a docs/ folder, a wiki export, or a pile of READMEs, import them rather than retyping them. Drop the files or the folder onto the import area and TaskGoblin shows you what each one would become — its address, its title, and whether something already lives there — before anything is written. Conflicts are decided per file, by you, because nobody can resolve a conflict they were not shown.

Some details that save a surprise:

• Folder structure survives. docs/people/Alice Chen.md becomes people/alice-chen; the directory layout turns into address prefixes.
• Non-markdown files are ignored, and the count of what was skipped is shown. A real docs folder with 40 markdown files beside 300 screenshots imports the 40 and tells you it left 300.
• A batch is up to 200 files and 20 MB, all or nothing. Import a big archive in a few passes.
• The import lands in the folder you are standing in. Open runbooks first and the whole batch arrives underneath it.

Going the other way, Export hands you a ZIP of the entire brain as markdown files, with the folder structure mirroring the addresses. It is there so the answer to "can we get our knowledge back out?" is a button rather than a conversation.

Rearranging without breaking things

Pages can be moved, folders renamed, and either deleted — one at a time from the row menu, or several at once by selecting them.

Moving repairs the links. When a page changes address, every [[wikilink]] pointing at it on every other page is rewritten to the new one. Without that, moving a well-cited page would quietly turn a dozen good references into broken ones. Sentences that merely mention the old address in prose are deliberately left alone — those are someone's writing, not markup, and rewriting them would be editing prose you did not ask anyone to edit.

Renaming a folder is all or nothing. If one page in it cannot move — something already occupies the destination — nothing moves. Half a rename leaves a folder existing under two names with no way to tell which pages were meant to be where. Moving a selection, by contrast, is per page: one awkward member of a hand-picked set of forty should not lose you the other thirty-nine.

Two addresses cannot move: memory, because that is where the organisation playbook is written, and anything under tasks/, because each of those pages is pointed at by the thread it belongs to. Everything else is yours to arrange.

Deleting, and getting it back

Deleting is a soft delete. The page leaves the tree, the search results and the goblins' tools straight away, and stays recoverable from Recently deleted for 72 hours — after which it is removed for good.

A bulk delete offers Undo immediately, which matters more than it sounds: deleting a folder resolves server-side, so your browser never knew which forty pages went. Recently deleted is there for the slower change of mind.

Goblins can delete pages, but they cannot restore them. That is deliberate. Restoring is a judgement about whether a deletion was right, and an agent that could undo its own deletions could undo yours.

Finding things

Search is the same ranking your goblins get — meaning as well as words, so a page can match a question it does not share any vocabulary with. That parity is on purpose: an agent citing the third-best page while the person beside it reads the first is a disagreement neither of them can resolve.

You can also filter by tag, or browse the folder tree, and any folder or page you land on has its own address you can share.

Letting a goblin tidy up

Two kinds of maintenance keep a brain healthy, and TaskGoblin separates them.

The mechanical half — keeping search indexes current, deriving links, clearing out pages past their recovery window — runs on a schedule, costs nothing, and needs no decision from you. Correctness should not depend on anyone having credit.

The other half is judgement: merging two pages that have drifted into covering the same thing, rewriting a page the code has since contradicted, retiring one that has been superseded. That is real work by a real goblin, so it ships as a loop — Tidy the brain, which runs daily at 03:00 once you enable it — and it ships paused. It is an ordinary billed run, and deciding that something you wrote should be merged or retired is not a decision to make on your behalf without asking.

If you turn it on, it is deliberately conservative: it will not delete a page merely for being old, and when two pages disagree and it cannot tell which is right, it leaves both and writes down that they disagree. Anything it does retire is restorable for 72 hours like any other deletion, and it reports what it merged, rewrote and retired when it finishes.

Where to go next

• The brain — what the brain is, and the two addresses that fill themselves in.
• Loops — the primitive "Tidy the brain" is built on, and how to enable it.
• How a run works — where the brain is read and written inside a single turn.
• Schedule loops — unattended runs on a cadence, of which brain consolidation is one.