1How knowledge gets shaped, tagged, linked, and accreted in a personal knowledge base. This is the *why*; the mechanical conventions of whatever tool holds the space live alongside it. The same content is tested as Gherkin scenarios in [scenarios.md](scenarios.md).
 2
 3The constraints apply equally to the person whose space this is and to any agent working in it. "What's worth recording, and how" doesn't change based on who's doing the recording.
 4
 5# The shape of knowledge
 6
 7## Knowledge accretes
 8
 9The right question after any session isn't "did I capture what I learned?" It's "is this space a better version of itself than it was an hour ago?" The first framing produces transcripts. The second produces compounding structure. A 2,000-word debug log that doesn't move any durable insight into the larger graph hasn't actually contributed to the space. It's just exhaust.
10
11This is the foundational principle. The rest follows.
12
13## Notes are atomic and concept-oriented
14
15One page, one concept. The page title names the concept and lets other pages link to it unambiguously. "Database backup management" is a workflow. "Using `pg_dump --format=custom` for restorable backups" is a concept. Pages built around concepts gain weight as they accumulate links and edits. Pages built around projects, sessions, or sources tend to fragment.
16
17Atomicity is a leaning. When a section of a page could plausibly be a link target on its own — when another page might want to point specifically at it — that section is usually worth extracting.
18
19## Working knowledge stays in todos; durable knowledge gets extracted
20
21Todos are the working layer. Their bodies hold the narrative of a piece of work as it unfolds — debug logs, dead ends, decisions, etc. This is good and stays good.
22
23When something durable emerges from that work — a fact, a technique, a lesson, a hard-won bit of architectural insight — it becomes a *separate* concept-oriented page, and the work log links to it from where the discovery happened. The work log narrates while the concept page accretes. The todo points at the concept page rather than copying its content.
24
25## Density lives in the link graph
26
27Wikilinks in body text are how the space becomes more than the sum of its pages. Mentions of concepts that have (or could have) their own pages get wikilinked inline, even when the link feels obvious. Surprising connections surface where notes about different domains share a link target. Without inline links, the graph stays thin and queries can't see the relationships.
28
29Dashboards and structure notes are scaffolding around the link graph. They earn their keep, but the real connective tissue is body-text wikilinks.
30
31# Hierarchy, tags, and links
32
33## What each is for
34
35The path tells you *where you're working from*. Areas-of-life are intentional blinders — working on personal things, the work hierarchy shouldn't crowd in. Hierarchy works as blinders. It fails as a taxonomy for the contents of the universe.
36
37Tags tell you *what kind of thing a page is*, in a small number of well-defined ways. They drive queries.
38
39Links tell you *what a page relates to*. They're the dense, associative web Luhmann was after.
40
41Hierarchy is coarse and exclusive (a page lives in one place). Tags are coarse and inclusive (a page can have several). Links are fine-grained and unbounded. Note-taking goes sideways when these tools get mismatched. Hierarchy used for relationships, tags used for what a page only mentions — those are the common failure modes.
42
43## The four tag axes
44
45Every tag in this space fits one of four categories. If a candidate tag doesn't fit any of them, it doesn't get added.
46
47**Type.** The note's kind, in a sense that drives queries. Examples: `project`, `task`, `journal`. New type tags appear only when a new kind of note needs its own dashboard or filter. Foundational and sparse.
48
49**Topic-as-object.** A page is tagged with a topic only when the topic is its primary subject. Mere mentions don't qualify. Would removing the topic gut the page? If yes, tag it. If no — it's just a mention or tangent — wikilink it instead. Examples: `postgres`, `rust`, `homelab`, `birding`. More than any other rule, this keeps the tag space useful.
50
51**Sensitivity.** Gates display, sharing, or attention. `nsfw` is a typical example. New sensitivity tags appear only when there's a category of content that genuinely needs gating.
52
53**Faceted sub-aspect of a topic.** A slash-tag refining a topic, used only when there's a cluster of pages sharing the facet. Example: `homelab/networking` is fine when several pages address the homelab's networking specifically. A "facet" that would only apply to one page isn't really a facet. Let the page title carry the specifics, and use the topic tag on its own.
54
55## New tags need a cluster
56
57A new tag asserts that several pages will share it. Single-occurrence tags are a smell. Most turn out to be typos, near-duplicates of an existing tag, or premature inventions. The default move when reaching for a tag is to use an existing one even if it fits imperfectly. When no existing tag fits and only one page would carry the new tag, the answer is usually a wikilink instead.
58
59Near-duplicate tags get reconciled when noticed. Pick one, update the others, move on.
60
61## Tags don't echo the hierarchy
62
63Don't tag with what the path already says. A page at `projects/orchard/X` is already in the orchard context. Adding `#orchard` adds nothing. The topic-as-object test still applies on its own terms: does the *content* centrally describe orchard? Most pages under a project directory cover a specific feature within it (sync, search, export) rather than the project as a whole. Those don't get the project's name as a tag.
64
65The project's own index page might earn the topic tag, if there's ever a query for "all pages centrally about this project regardless of location." Usually the path makes that query unnecessary.
66
67# Working the space
68
69## Look before you write
70
71Before creating a new page, find out whether something close enough already exists. Full-text search first. It surfaces excerpts and catches cases where the right page exists under an unexpected title. Structured queries second, for things like "all pages tagged X" or "all open tasks in project Y" or "what's the current list of tags across the space that I can select from?" Inventing a new page should follow at least one negative result.
72
73The same thinking applies to listing things. When a section enumerates items in the space, a structured query is preferred over a static list. Static lists go stale silently. Queries don't.
74
75## Hub notes
76
77A page that links to its constituent specs and todos, with prose around them, is a structure note. A project's index page and its docs page are typical examples. Structure notes earn their keep. A 600-line page covering five concepts because nobody felt like splitting it is just an unsplit page, regardless of label. A structure note is *short* and *links out*. When the prose around the links dominates the page, extract it. Replace it with a wikilink from the hub to the new concept page.