The Stimpunks Knowledge Garden

A shared, self-maintaining home for our research library and our organizational knowledge — and an answer to a question we take seriously: what happens to everything we know when the person holding it is unavailable?

Written for whoever maintains this next — including future us.

We run on mutual aid and we are staffed by Disabled, Autistic, and otherwise Neurodivergent people. Capacity here is real, finite, and variable. A knowledge base that only works when one person is at full strength isn’t a knowledge base — it’s a hostage situation. So we built one that keeps itself current, backs itself up, audits itself, and can be read by anyone on the team without asking permission from a bottleneck.

This page covers the motivation, the architecture, and the implementation. Skip to whatever you came for.

Why we built it

Bus factor 1 is a design failure

Bus factor is the number of people who would have to become unavailable before knowledge is lost. A bus factor of 1 means it all lives in one head, on one laptop, in one person’s browser tabs.

The name is grim and the mechanism is mundane. Almost nobody gets hit by a bus. People burn out. People have flares. People take leave, grieve, move on, or need six weeks where reading a PDF is not going to happen. That is normal human variation, not a failure of character — and a system that treats it as an exception is badly designed.

We say this about buildings, classrooms, and workplaces all the time: if it only works for people operating at peak capacity, it doesn’t work. The same standard has to apply to our own infrastructure. No single point of failure for our collective knowledge.

Access is infrastructure, and so is memory

We treat access as infrastructure — never charity, never optional. Institutional memory is the same kind of thing. When knowledge is trapped, the cost lands on whoever has the least slack: the new volunteer who can’t find the citation, the person covering while someone is out, the future us who has forgotten why we made a decision.

Interdependence means building so that any one of us can be absent. That’s not a contingency plan bolted on at the end. It’s the design brief.

The scatter problem

Our knowledge was spread across a research folder, Raindrop bookmarks, Readwise highlights, Notion pages, the WordPress site and its glossary, a commonplace book in Ulysses, and assorted Drive folders. Nothing was lost, exactly. Everything was unfindable by anyone but the person who filed it.

Retrieval failure is a real failure. A citation you can’t find is a citation you don’t have.

Provenance, because we cite and we get cited

We quote generously and link back to sources — that’s house style, and it’s how the Autistic web works. Our work also gets cited by researchers and writers. That only holds up if the originals stay original.

So the system’s central rule is about provenance, not tidiness: the source files are never altered. Not renamed, not reformatted, not “cleaned up.” Every derived thing — every summary, index, and category — lives somewhere else and points back.

What it is: five corpora

Two indexed layers, three corpora that sit outside the index and are only ever read, and a staging tray.

raw/            Original, unaltered source files — the library. Never edited.
wiki/           An auto-written index over raw/ — regenerated, never hand-edited.
wiki/concepts/  One page per idea, cross-linking every corpus at once.
notes/          Live working notes (Ulysses external folder).
highlights/     A Readwise highlights export.
site/           Websites mirrored as Markdown, in git. One folder per domain —
                ours, plus two of Helen Edgar's with her permission.
inbox/          Drop zone for files awaiting ingest. Transient, always ends up empty.

The index sections are roughly what you’d expect from us: Autism & Neurodiversity (175 items), Education & Learning (66), Neurodivergent Insights infographics (56), then Mental Health, Disability & Accessibility, Social & Political Theory, Technology & AI, Nonprofit & Governance, Media & Graphics, Race, Gender & Justice, Parenting & Low Demand, Environment & Ecology, and Philosophy.

Alongside the generated sections, the wiki holds authored pages that survive regeneration: distilled workflow guides, one clean summary per working session, and extracted key claims from the creators and publications we follow.

Putting the website in the folder was the fix for an obvious hole. We had been syncing WordPress metadata — url, slug, title, modified — and never the writing, so nothing on disk could quote our own published words. Our own search tool had to reach out to the live web to answer questions about the garden it is named for. Now the whole site is local Markdown, which also means the website has a version history: a sync diff shows exactly what changed and when. Get your work into git, including your own website.

The rule of thumb is one line long: raw source material goes in raw/; distilled understanding goes in wiki/.

The concept layer: indexing ideas, not files

An index built from filenames can tell you what you own. It cannot tell you what you understand.

Ask the file index what we hold on monotropism and it offers the three files with the word in the name. The real answer was scattered across the website, the highlights, and a decade of notes. So there is now a second index, keyed on ideas rather than documents: one page per concept, gathering everything the garden holds on it from every corpus at once.

The vocabulary is one we already publish. We were a step away from inventing a taxonomy when it turned out we had published one years ago. Our glossary is 448 terms deep, so the concepts are keyed to it — the words we already maintain in public, not a private scheme a machine dreamed up. Re-sync the site mirror and the concept list follows.

Each page is deliberately half written by hand and half generated, and the halves have different rules. A synthesis block survives every rebuild untouched — that is where what we think lives. Below it, a link block is thrown away and rebuilt from scratch every run, so the links can never dangle. What we think persists; what points where is always re-derived.

Two problems were worth solving properly:

• Counting mentions is useless. 335 of our site pages “mention” monotropism, nearly all of it navigation furniture — tag lists, tables of contents, cross-link blocks. Matching now weighs a title far above a heading, and a heading far above a passing mention. A term carried everywhere by our own page branding keeps its page, but links only what is genuinely about it.
• Our own library was unreadable to us. Most of raw/ is PDFs, so a paper filed as 40614_2022_Article_338.pdf was invisible to every search we could run. Text is now extracted and cached, and that paper turns out to be a scoping review of applied behaviour analysis. Images, video, and cloud-document pointers stay filename-only — and the pages say so plainly instead of implying full coverage.

A health check reports concepts we define in public but hold nothing on, synthesis whose evidence has shifted underneath it, assets no concept touches, and broken links.

Then it told us things we did not want to hear, which is the useful part. We were standing on sources we had never filed. Deficit ideology is load-bearing across our site, and the library held exactly one asset that so much as cites Paul Gorski. Damian Milton was referenced inside 79 of our files — the double empathy problem is threaded through everything we write — and we had filed nothing he wrote. An unfiled source is not an unread one: those arguments came from reading the work directly. But a citation you cannot open from your own shelf is a weaker thing than one you can — no exact quotation, no page number, nothing to search inside, and nothing to hand a colleague without going back out to the web and hoping it is still there. Our monotropism shelf ran 216 published pages against 11 highlighted sources, which says more about what we archive than about what we read.

We publish more than we have filed — and now something says so out loud instead of leaving it comfortable. Four of those gaps were filled within two days of the layer existing, which is the first time our own tooling has sent us shopping. Having the paper on the shelf rather than a link to it changes what you can do with it: quote it exactly, cite a page number, search inside it, and still have it when the URL rots. That is the whole argument for keeping a copy of what you already read.

The sixth collection: the bookmarks we could not search

Five corpora, and a search that could not see the largest pile of all.

We keep 10,739 bookmarks in Raindrop. What the search had indexed was the bookmark record — title, URL, tags, collection — and no page text whatsoever. So a sweep of the whole garden for what we hold on curiosity came back empty, while the bookmark library held Susan Engel’s work on children’s need to know. The library was never silent. We had simply never given the search anything to read.

Fetching the pages fixed it, and the fix is honest about its own edges. 4,159 pages are now fetched, indexed, and quotable — roughly 137 million characters, a sixth collection alongside the wiki, the site, the highlights, the notes, and the library. That brings the whole index to 19,222 documents.

The other 6,580 are recorded refusals, not silent gaps. Every one carries its reason:

We refused the login walls on purpose. Indexing four thousand pages of sign in to continue would drop chrome into every result we ever run — a search that is technically complete and practically useless.

The bot-blocks are somebody else’s decision, and worth naming as such. A paper we can legally read stays out of our own index because a publisher’s edge server does not want a script reading it. That is a fact about academic publishing, not a defect on our end, and we would rather it sit visible in a table than get quietly rounded off.

So a search that finds nothing here is not evidence that the bookmarks are silent. Check the coverage before concluding anything — the same discipline the concept layer follows about images and cloud documents. Partial coverage stated plainly beats full coverage implied.

The rules that make it work

Five rules do most of the load-bearing. They’re written down in the repository so that every session — human or AI — starts from the same constraints.

1. raw/ is read-only, forever. Never edit, rename, move, delete, reformat, or reorganize. Only ever add. If something in there looks wrong, say so — don’t fix it. That’s what makes it provenance instead of just storage.
2. wiki/ is generated, never hand-edited. To change the index, change the generator and rebuild. Hand-edits get silently overwritten, which is worse than being refused. The one exception is a concept page’s synthesis block, which is designed to survive.
3. notes/ is personal and hands-off by default. It’s someone’s live writing, not an archive. Read it for context; write there only when asked (drafts land in an inbox subfolder, which is the sanctioned front door). One tool holds a narrow, deliberate exception. The reflection audit edits the writer’s existing prose before it gets published — and only mechanically: repo-relative links become absolute, and first-person singular becomes “we” where the work was collective. It never rewrites a sentence. An exception this specific is safer written down than left to judgment.
4. site/ is a mirror, not the source. The website is the source of truth. Never edit the copy expecting the change to reach the web, and never hand-patch a conversion glitch — fix the page, or fix the converter, and re-sync.
5. The staging tray is not a store. Files in inbox/ are awaiting processing. The permanent copy always ends up in raw/. An empty tray is the healthy state.

Underneath all five is a single distinction: only raw/ and wiki/ are indexed. The notes, the highlights, and the site mirror are read and cross-linked, and never filed as assets. Reading a corpus is not the same as owning it.

raw/ is also intentionally flat — no subfolders, no filing taxonomy to maintain and re-litigate. All the organizing happens in the index, where it’s cheap to change your mind. Retitling something is a one-line change to a config file and a rebuild. Nobody has to move a single original.

How it’s built

Deliberately boring technology where it counts: a folder of files, a Python script, Markdown, and git. The sources are plain files — no database, no server, no proprietary format — so anything here can be read with a text editor in ten years. There is now a search index sitting on top (SQLite plus small models that run on this machine, no vendor and no network), because a library you cannot search is only half a library. But it is a cache: delete it and one command rebuilds it from the files. Nothing we would be afraid to lose lives in a binary.

The index generator

A single script walks raw/, groups files into topic sections, and writes a README.md plus one page per section. Every entry links to a real file using a relative path, so the index and the library travel together. The same command refreshes the concept layer.

Categorization starts with keyword rules over filenames, then gets corrected by a small overrides file that maps individual files to a better title and category. That overrides file is where the system actually gets smarter over time — a lot of academic PDFs arrive named after their DOI or a content hash, and each one that gets properly titled is a permanent improvement.

Rebuild is one command, and it’s safe to run any time:

python3 wiki/_generate.py

Skills: the small tools that maintain it

The maintenance work is split into twenty-eight narrow, named tools — most of them a plain-language instruction file plus a deterministic Python helper. Narrow on purpose: a tool that does one thing can be trusted, and its failures are legible.

garden-spider is worth pausing on, because it encodes something we care about. An AI asked a question about our work will happily answer from its training data, fluently and plausibly, whether or not we ever said the thing. That tool is a hard constraint against that: search the garden first, cite the local file or link beside each claim, and name the gap when there isn’t one. We would rather have a documented hole than a confident invention.

The reflection log is worth pausing on too, for the opposite reason. The changelog records what shipped. It is public, and it is the half of a week that is easy to be proud of. The reflection records what the week cost — where the capacity went, what was hard, what got abandoned. Both run on the same weekly rhythm, and neither is a productivity tracker: no streak, no score, no penalty for an empty day. An organization staffed by Disabled and Neurodivergent people that only ever writes down its output is keeping half a record — and it is the half that makes the other half look free.

The safety model: propose, don’t just do

The audit tool sorts every proposed change into one of three buckets, and the bucket determines who decides.

• Auto-apply — low-risk and obviously correct. Rebuild the index, fix a broken link, correct a stale count. Applied immediately, logged to a change ledger.
• Needs sign-off — edits to the tools themselves, structural rewrites, resolving a contradiction. Written to a dated review file as a checkbox list and not applied until a human ticks the box and re-runs.
• More context required — genuinely ambiguous. Written out as questions, for a human to answer.

A hard rule protects the tool definitions and the top level of the index from unapproved edits. The point isn’t that automation is dangerous. It’s that the difference between a system that improves itself and one that quietly drifts is whether a human holds the risky decisions.

What runs automatically

Three scheduled routines, on a weekly rhythm.

The weekly loop:

  Mon 9:01 AM — data ingestion
  ────────────────────────────────────────────────────────────
  sessions  ─┐
  ecosystem ─┼─▶ rebuild index ─▶ log run ─▶ commit + push ─▶ mirror to team Drive
  curated   ─┘

  Mon 12:01 PM — system audit
  ────────────────────────────────────────────────────────────
  scan + read ─▶ sort by risk ─▶ apply safe fixes, queue the rest ─▶ commit + push

Two properties make this survivable rather than stressful.

Every step is idempotent. Re-running never double-ingests, because each sync owns its own cursor. You can always just run it again.

The commit, push, and mirror steps are non-fatal. A network hiccup gets logged and the next run catches up. Nothing waits on a human to notice, and nothing breaks because a laptop was closed. No urgency cues, no streak to maintain, no dashboard turning red — those are hostile design in a system meant to hold knowledge for people with variable capacity.

An automated snapshot is a safety net, not an author. The nightly backup used to commit whatever was on disk, and one evening it fired mid-edit and signed real work with a cron job’s name. It now stages the notes and nothing else — that folder is the only part of the system with no second copy, so it’s the only thing a blind, unattended job should touch. Everything else is either reproducible or hand-written, and belongs in a commit whose message says what it did and why.

Backup and sharing: three channels

Each channel does the thing it’s actually good at. This follows the 3-2-1 approach in our backup guide.

• Git, in a private repository — version control and offsite backup for the text layer: the index, the concept pages, the tools, the scripts, the notes, the highlights, the website mirror, the logs. Small, diffs cleanly, full history. Answers “why did we change this?” years later.
• A one-way mirror to the team Drive — a read-only copy of the index, the library, the highlights, the notes, and the website mirror, for everyone on the team. It only ever pushes outward. It never pulls, and it never touches the working folder.
• Time Machine — the continuous local net covering everything hourly, including the large binaries git can’t take.

The library itself isn’t in git: it’s over a gigabyte of binaries and includes individual files past the platform’s size limit. Git holds the text and the machinery; the mirror and Time Machine hold the bulk.

Why not just sync the whole folder to the cloud? Because a live sync client pointed at a working directory corrupts the git metadata, races the tools’ writes, and chokes on the library’s size. So sharing works by pushing copies out — a version-controlled text layer and a one-way mirror — never by syncing the live folder. The read-only mirror also means a teammate browsing the library cannot accidentally break it. There is nothing there to break.

What this is not

It is not a plan to replace people with software. AI writes the index here, and never the sources — that boundary is the whole architecture. Judgment, curation, and everything published in our voice stay with humans.

The concept layer stretches that boundary, and we should say so plainly rather than let it slide. Its synthesis blocks are machine-written prose, not just links. So they are treated as leads, never as evidence: a concept page is never a citation, and its synthesis is never quoted at all. To cite something, the tool has to open the human-authored source and cite that. A confident-sounding concept page written from a machine’s memory is worse than an empty one.

We are wary of techno-solutionism and technoableism, and we’re not going to pretend a folder structure fixed anything structural. This doesn’t create capacity. It stops us from wasting the capacity we have on finding things we already had, and it means one person’s bad month is no longer an outage.

It is also not a productivity system. Nothing here counts your output or asks you to keep a streak.

Honest limits

Documenting the gaps is part of the job.

• The operator’s bus factor is still low. The library and index are readable by everyone; the machinery is understood in depth by one person. This page is part of fixing that, and it isn’t fixed yet.
• The generated index will be wrong sometimes. Keyword categorization mis-files things, and a file that arrives named after its DOI keeps that name until somebody opens it and retitles it by hand. That backlog is currently clear — 257 files carry a real title instead of a hash, and nothing in the index is still labelled with a raw filename. But it is clear the way a swept floor is clear: every ingest reopens it. Search reaches inside those files either way; the shelf label is only ever as good as the last person who looked. The immutable-originals rule is what keeps the errors cheap: a bad category is a config edit, never a damaged file.
• The search index goes stale, quietly. It reflects the last time it was rebuilt, not what is on disk — and the working notes change every day. Part of it cannot be refreshed on a schedule at all: a handful of library documents come from cloud documents that need an authenticated connection to fetch, so no unattended job can keep those current. Nothing is lost when it drifts — anything missing from the index is still sitting in the library, and the plain-text search that worked before it existed still works. But a search that quietly answers from last week is worse than one that admits it doesn’t know.
• We publish more than we hold. The concept layer’s own health check says so, in specifics, and the list is longer than the four gaps we’ve closed. Concepts we define in public and own nothing on are a real limit, not a rounding error.
• The bookmark library is 39% searchable, and that is close to the ceiling. 4,159 of 10,739 bookmarks have fetchable page text in the index. Most of the rest are social posts behind login walls we skipped deliberately, and papers behind publisher bot-blocks we cannot get past. Every refusal is recorded with its reason, so the gap is legible — but legible is not closed, and a question whose answer lives inside a blocked journal will not be found by searching here.
• Most concept pages have no synthesis yet. Six of 358 are written. The rest are link collections — useful, but not understanding. Writing them is slow by design, because each one has to be grounded in material actually read.
• A check nobody has watched fire is not a check. Our staleness detector reported all-clear twice while two pages asserted we didn’t own books that were sitting in the library. The first time the threshold was wrong; the second time regenerating the wiki reset the baseline the alarm measured against, so it was structurally incapable of firing. A third arrived since: the contrast checker on our printable sheets reported screen 0/0 · print 0/391 and called it a pass. Zero failures out of zero elements measured is not a clean page — it is a page nobody looked at. All three are fixed, and all three were found by walking into the guardrail on purpose. Read the count, not the verdict.
• The originals aren’t versioned. They’re mirrored and backed up, not diffed. Because they never change, that tradeoff is acceptable — but it does rest on the never-changing part holding.
• Time Machine needs verifying, not assuming. A backup you haven’t confirmed completing is a hope.
• Two corpora started as one person’s. The notes and highlights began as personal archives. The notes now ride along to the team mirror, which makes them shared in practice and puts the burden on the writer: if a note shouldn’t reach the team, it doesn’t belong in the folder. That’s a people question, not a technical one.

Credit where it’s due

The raw-plus-wiki split is not ours. It comes from Andrej Karpathy’s llm-wiki — an idea file published to be copy-pasted into your own agent, arguing for a persistent wiki that an LLM builds and maintains over a collection of source documents, instead of re-deriving an answer from scratch on every question. We read it before we built any of this. The architecture on this page is that pattern with our constraints bolted on.

What we added is the access argument. Karpathy’s case for immutable sources is about knowledge compounding rather than being rediscovered. Ours is about that too, and about provenance because we get cited, and about bus factor as a design failure in an organization staffed by Disabled and Neurodivergent people whose capacity is real, finite, and variable. Same folder structure, different reason for the rule.

Going back to it later named two things ours was missing: links between wiki pages, and pages about concepts rather than about documents. Both now exist, keyed to our glossary. Credit for the idea. The mistakes are ours.

We also used concepts and prompts from Austin Marchese’s “How to Build A Self-Improving System with Claude – YouTube“, which builds upon Karpathy’s llm-wiki.

Steal this

You don’t need our stack. We took the core of it from someone else, and the load-bearing ideas are portable and mostly free. If you would rather have something you can actually run, we made a template: Start Your Own Knowledge Garden — five steps that degrade gracefully, the first needing no software at all, plus a walk-through of git written for someone who has never opened a terminal. The principles below are the reasoning; that page is the on-ramp.

1. Separate source from index. Originals in one place, never edited. Everything derived somewhere else, pointing back. This one decision buys most of the resilience.
2. Keep the source folder flat. Do the organizing in the index, where changing your mind is cheap.
3. Make the index regenerable. If it can be rebuilt from the sources, it can never be the thing you’re afraid to lose — and hand-edits stop being a hazard.
4. Index ideas, not just files. A filename index tells you what you own. A second index keyed on concepts starts telling you what you understand — and, less comfortably, what you’re missing.
5. Use a vocabulary you already maintain. Before inventing a taxonomy, check whether you’ve published one. Ours was sitting in the glossary the whole time.
6. Use plain files and plain text. Markdown and folders outlive every app you’ll use to read them. Prefer Markdown and boring formats — and put your own published work in git too, so it has a history.
7. Version the text, mirror the bulk. Git for what diffs, a one-way copy for what doesn’t.
8. Automate the boring, gate the risky. Let the machine rebuild indexes and fix links. Make it ask before it edits itself. Scope an unattended job to what it can’t destroy.
9. Watch every safeguard fire before you trust it. Ours reported all-clear three times while asserting things that were false — twice about books we owned, once on a page it had measured zero elements of. A check nobody has seen behave correctly is not a safeguard — it’s a hope. Read the count, not the verdict.
10. Write the rules down where the work happens. A file at the root of the project that says “never edit these, always regenerate those” is the cheapest reliability tool there is.
11. Design for absence. Assume the person who built it is unavailable. Then read your own documentation as if you were new.

The measure of this system isn’t how clever it is. It’s whether someone who didn’t build it can find what they need on a day when nobody is around to ask.

Related

• Start Your Own Knowledge Garden — the on-ramp, if you want to build one of these yourself, plus the template repository
• The Stimpunks Knowledge System as Curriculum — what this has to do with learning: knowledge gardens, and teaching revision control
• Escaping Rentier Technofeudalism with Deliberately Boring Technology and Generative AI — what rentier technofeudal SaaS actually means, and why the boring parts of this page are the point
• llm-wiki — Andrej Karpathy’s idea file, where the raw-plus-wiki pattern comes from
• qmd — Tobias Lütke’s local search engine for markdown, which is what makes the library searchable here. On-device, no vendor, no network.
• Backup and Passwords — the 3-2-1 rule and our backup stack
• Using GitHub with Ulysses via Gitfox — how the notes layer gets version-controlled
• Markdown — the format everything here is written in
• Reading Experience: Design & Technical Notes — a companion set of maintainer’s notes
• House Style Guide — the voice the drafting tools follow
• Our Library and Research — the public-facing side of the collection
• Glossary — 448 terms, and the vocabulary the concept layer is keyed to