Page Types: Why a Working Knowledge Base Needs Six Kinds of Pages

Knowledge base structure notes

Whether a knowledge base is usable rarely depends on how beautifully the content is written. It depends on whether, three seconds after opening any page, you know what that page is for.

In the last note I wrote about how to decide whether a piece of material should be kept or thrown out. Once the triage is done, only the parts that can still support real work survive. But keeping the material is not the same as having a usable knowledge base — you have just turned a pile of messy directories into a pile of respectable messy directories. The real question is the next one: what kind of pages should these materials become.

I have been burned by this many times. In the same wiki, one page is an abstract principle, another is the current status of some project, another is a check I ran last week, and another is really just a list of commands. Each page is fine on its own; mixed together they start fighting each other — the reader has no idea what to expect before clicking, and the writer has no idea which rules to follow on the next update.

So now I make every page answer one question first: what type is it. If I can't answer, I don't write it yet. If the answer is vague, I split it.

From material to page

The previous note was about the material layer — what gets to enter the knowledge base and what stays in the working directory. Once that triage is done, you are left with maybe a few dozen items "worth turning into pages": a judgement that has stabilized, a choice that changed the behavior of the system, the current state of a project still in flight, a check whose evidence has been verified, a compressed history of how something evolved, a command sheet that gets looked up over and over.

Classifying material asks "what is this content"; classifying pages asks "what role does this need to play". They are not the same. An audit report as raw evidence may be excluded, but its conclusion needs to be rewritten and kept as an Audit page. A decision buried in a chat log will not enter the knowledge base, but the decision itself needs to become a Decision page. Between material and page, there is a second classification.

If you skip this second classification, the whole knowledge base collapses into a "document grab bag" — has everything, looks like nothing. That is why I now force myself to use only six page types, and refuse to add a seventh.

The six page types, with concrete examples

The order is not most-important to least-important. It is most-stable to most-volatile. The more stable a page, the closer it sits to knowledge; the more volatile, the closer it sits to a tool.

Concept page: a settled idea or rule

A Concept page is "how I see this thing". No specific project, no specific time, ideally no specific person. A good Concept page should still hold up two years later when a new person picks it up and reads it unchanged.

Examples: the rules for picking a canonical source, the Knowledge Model itself, Page Types (the page behind this very essay). Once written, this kind of page barely moves. If it does move, you owe a Decision page explaining why.

Decision page: a choice that changed the behavior of the system

A Decision page answers only four things: what problem was on the table, what alternatives existed, why this one was picked, and whether it turned out to be right. It is not meeting minutes, not a design doc — it is a memo to a future self who will want to know why the past self made this call.

Examples: why every launch action now starts with a dry-run-first pass, why the main-control write responsibility was migrated to a separate sidecar channel, why a more general-looking solution was abandoned. A Decision page is written once and not edited; at most a "follow-up observations" paragraph is appended to the end.

Project page: a bounded workflow plus current state

The Project page is the only one of the six allowed to move often. Its whole reason for existing is so that any new window, new AI, or new day can open it and immediately know "where this project stands right now". So it must have an owner, a current stage, a next action, and a last-updated timestamp — missing any one of those and it doesn't count as a valid Project page.

Examples: the current state of some OpenClaw Studio RC, the toggle state of a particular Jiyanran voice console version, the progress of Suwan's aesthetic sample library. The Project page is the most dangerous category in the wiki — it goes stale the fastest, and it is the easiest to mistakenly cite as if it were a Concept page. That is why this category needs to be tied tightly to freshness markers, covered further down.

Audit page: a check with an evidence trail

An Audit page says "at time X, I used method Y to check Z; the conclusion was this; the evidence is there". It differs from a Decision page — a Decision is about what to choose, an Audit is about what was done and what was seen. An Audit page naturally carries a timestamp, an evidence trail, and a reproducible method.

Examples: an end-to-end audit of some Stage pipeline, an inventory of built-in disk assets, a cross-account configuration consistency check. The interesting thing about an Audit page is that even when it expires you can't delete it — it is history, and its value is precisely "this was actually done at the time". But it shouldn't mislead a new reader into thinking "this is still how things are now", which is why its freshness marker defaults to stale almost by design.

Timeline page: a compressed chronicle

A Timeline page is for the kind of question that goes "I want to understand how this thing turned into what it is today". It doesn't capture detail; it captures turning points only — on some date a critical choice was made, in some week the whole architecture switched from A to B, after some version a component was deprecated.

Examples: the evolution timeline of a project across one quarter, the history of an ecosystem moving from single-machine to multi-account, the hardware evolution of a personal AI workstation from last year to this year. A Timeline page isn't updated densely; it gets a new line only when a "system-level change" happens — the same way I handle the CHANGE timeline.

Reference page: a compact lookup of commands, paths, and boundaries

A Reference page is a tool, not knowledge. Its point is not to be read but to be looked up. It should be as short, as flat, and as copy-pasteable as possible — tables over paragraphs, lists over sentences.

Examples: the Gate matrix (which kind of operation goes through which approval channel), the port allocation table, the Feishu routing table for each account, a list of frequently used debug commands. A Reference page has one peculiar property: it usually carries no authorial stance and is purely a snapshot of facts. So its way of going stale is purely mechanical — the fact changes, the page is stale; the fact holds, the page stays right.

Three writing rules

Once the six types are clean, writing each page only requires three rules. The rules look dumb, but every one of them comes from a real crash.

Rule one: if a page mixes "concept + state + ops", split it

This is the biggest killer I have seen. A README page where the first three paragraphs are design philosophy (Concept), the next five paragraphs are current progress (Project), and the bottom is a copy-pasted startup command block (Reference). It looks "comprehensive" at the moment of writing; three months later no one wants to open it.

The reason is not that it is badly written; it is that it can't be maintained. Design philosophy moves once every six months, current progress may change every week, the startup command may change at the next reinstall. Once three completely different cadences are stuffed into one page, the only outcome is that whoever updates it only dares touch the most volatile bit, and the rest of the page becomes increasingly fake.

Once you split, things immediately change: the Concept page barely moves, the Project page only edits its status line, the Reference page is refreshed only when the underlying fact changes. Each page has its own cadence, and each page stops lying.

Rule two: if a page can be replaced by "a link to a better canonical source", replace it

I used to like writing "summary pages" — taking several pages of content, fusing them together into one digest, telling myself this was reader-friendly. I later realized summary pages are the most dangerous artifact in a knowledge base. They don't get updated; the moment the underlying page updates, the summary starts lying — and new readers lean toward the summary precisely because it is easier to read.

My rule now is simple: if a page can be rewritten as a one-line "see page X", don't write the page — put down the link. The link won't go stale faster than the target page; a summary page will.

There is only one exception — when the page is genuinely making a combined judgement, stringing several scattered Concepts into a new conclusion. In that case it is itself a new Concept page, not a summary page. The difference is that it carries its own judgement, not just a rewording of someone else's.

Rule three: if a page is just an "execution log", keep only the summary

AI projects are especially prone to spawning "execution-log pages" — every command from one experiment pasted line by line, every step from one debug session recorded end to end, every output from one deployment kept verbatim. At the time it feels safest to keep "the full record"; six months later, those pages are unreadable and no one opens them.

My current habit is to keep the raw execution log in the evidence directory, and keep only the summary in the knowledge base — what was run, what conclusion was reached, which anomalies were recorded in which raw log. The summary may be only 200 characters, but it can be read, cited, and maintained. The raw log can be searched and traced back to, but it doesn't need to live in the knowledge base pretending to be a page of knowledge.

How types and freshness markers work together

Once types are clean, the biggest payoff isn't faster retrieval — it is that the cadence of expiration checks can vary by type. The previous note introduced the three-state freshness marker: verified, stale, needs review. The problem is that one-size-fits-all doesn't work — different categories of page go stale at different speeds.

The cadence I roughly use now:

• Concept page: review once every six to twelve months. It is stable by nature; checking it too often is just waste.
• Decision page: as a rule not reviewed at all — only picked up again when a signal appears saying "this decision may no longer be right". It is a historical fact, not a current state.
• Project page: review every two weeks to a month; if no one touches it past that cadence, it slides automatically to stale.
• Audit page: stale by default. It is a one-shot piece of check evidence; it was never meant to stay verified forever.
• Timeline page: a line is appended whenever a "system-level change" happens; no dedicated review cycle.
• Reference page: refreshed whenever the underlying fact changes. If the fact holds, it stays verified.

With this split, "reviewing the knowledge base" stops being one giant mobilization and becomes several small loops at different cadences — sweep Concepts twice a year, sweep Projects monthly, let Reference pages follow the facts. The pressure is spread across different points in time.

More importantly: when a reader opens a page, they can judge how trustworthy it is using two signals together — type and freshness. A verified Concept page and a verified Project page mean different things — the first is "I have thought this through", the second is "this still held up as of last week". Read the two signals together and you get something more accurate than either signal alone.

Common page-rot patterns

After the positive rules, the inverse: the three typical page-rot patterns I have either committed myself or watched in other people's wikis. A knowledge base goes rotten almost always down one of these three paths.

Pattern one: mixed-type pages that no one wants to touch

The most common form is a README — needs to cover design, current state, and startup commands all at once. It starts as a shortcut; eventually no one dares touch it: editing the design part might break the state description, editing the state part might contradict the design, editing the command part might paste in something wrong. The page becomes "the most authoritative and the most inaccurate" page in the whole wiki.

The fix is not to edit it; it is to split it — into a Concept, a Project, and a Reference page, each maintained at its own cadence. What remains of the README is a single line of links pointing to them.

Pattern two: stale without marker, every page looks equally trustworthy

Without freshness markers, every page in the wiki looks like it has the same weight — a Project page untouched for eighteen months and a Concept page verified yesterday look identical in the search results. The reader can't tell them apart, an AI assistant doing RAG retrieval can't tell them apart, and the result is "the old beats the new" — old pages tend to be longer and more structured, so they get matched more readily.

The fix is to make the freshness marker a required field, not an optional one — a page with no freshness signal does not get to enter the formal retrieval results. Even "needs review" is fine; at least the reader knows to be cautious about the page.

Pattern three: duplicate summaries that dilute the canonical source

One project ends up with a "design doc", a "project overview", a "FAQ", a "Wiki summary", and an "Onboarding guide" all at the same time; 70% of their content overlaps and only the emphasis and writing style differ. Each time an underlying fact changes, maybe one or two of the five get synced — the other three keep telling stories based on the old fact.

The fix is to commit to one canonical source and rewrite everything else as "see page X" plus a narrow page-specific supplement. This is the hardest rule, because "writing a new one" always feels more satisfying than "pointing at an old one" — but the fastest-rotting parts of a knowledge base are exactly those repeatedly summarized "pretty new versions".