Preface
Should notes data be handled like water into a container or like trail mix, where the content is heterogeneous?
Handbook takes the unorganised exhaust of learning (scattered LLM conversations, articles, notes, bookmarks) and organises it into a structured, searchable reference guide. The distinguishing move that separates it from NotebookLM or Notion? The guide keeps reorganising itself as you feed it, so it improves as you learn instead of decaying into another stale document.
It’s like adding another drop of water to a pond, making it a uniform, homogeneous mixture.
The problem: learning that scatters
Especially in today’s world where learning and written material is practically free, fragments of insight, in the wrong shape, become spread across too many places. No tool turned that exhaust into something structured that kept improving.
The clearest case for me was music. I taught myself to mix and master my own tracks properly, the kind of knowledge people pay thousands for in courses, and it worked: the mixes came out louder, cleaner, more professional. But the learning lived across a dozen conversations and notes. Every time I wanted to reapply a technique, I was excavating old chats to find it.
The same problem, in a different domain, had been sitting on my list for years. I wanted the fundamental UI/UX principles I had picked up over years of design work in one place I could actually reference on the job — not buried in a notebook, not lost in a document I would never reorganise. Two domains, one missing solution.
What I built
A tool that ingests raw material from wherever you learn and returns neat, referenceable categories. You keep feeding it; new information lands in the right place and merges with what is already there rather than piling up. You never file anything by hand.
The instinct came straight from mixing: adding a new source should feel like adding a drop to a homogeneous mixture — it blends in, the whole stays coherent, nothing clumps or duplicates. That metaphor turned out to be the actual product architecture, not just a way of describing it.
Because the structure is generated rather than authored, the product is domain-agnostic. The same pipeline produces a design reference, a cooking guide, and a training programme.
What’s great about building a handbook is the guide stores as markdown, making it easily exportable and interpretable by your favourite coding agent. It’s a guide for both you as the human author/reader as well as for machines!
The bet I made, and why I reversed it
The decision the whole product originally rested on: nothing is stored as a paragraph of prose. Every piece of content was a typed, sectioned atom — one of exactly four types: principle, antipattern, quote, or prose. Each type earned its own visual treatment, so the shape of the knowledge would be legible before you read a word.
Then I used it on my own music notes and it felt wrong — ordinary sentences kept getting promoted to principles. I went looking for a prompt to tune and found something worse. There were two classifiers and they were nothing alike. Pasted content went through real AI judgement; generated content, which is almost everything, went through a parser with no AI in it at all, reading a ### heading as a principle and everything else as prose. And the prompt that wrote the content had never been told to emit ###. Measured across a real guide: twenty-seven section headings, zero of the signal that made anything a principle.
So the question the product appeared to be answering — is this a principle? — was never actually being asked.
The fix was not a better prompt but rather admitting the question was wrong. "Is this a principle or ordinary prose?" has no correct answer, so the model cannot be accurate at it and the reader cannot meaningfully disagree. "Does this idea deserve a name?" has an answer you can see at a glance, and overrule by typing one. The four types are gone. Every block is a heading and a body, and the heading belongs to the reader.
Figures 4 and 5 below are the treatment I removed. Figure 6 is what replaced it.
The thing it has to be flawless at
Editing blocks, dragging them into order, undoing a mistake — a notes app like Notion does all of that, and does it better. The only thing here that is not available somewhere else is what happens when you add something: a new note dissolving into a guide that already exists, landing where it belongs and merging with whatever already said it.
So I went back and audited that one loop, and found it had been quietly half-working the whole time. Similarity matching only ever compared a new note against blocks carrying an embedding — and only pasted blocks ever got one. Every guide starts out generated, so the detection was blind to nearly all of it: paste something the guide already said and nothing noticed, unless it happened to have been said in another paste. Matching was also gated to blocks sharing a type, by then a field that meant nothing. And placement was decided from section names — filing against a table of contents rather than against contents.
All three are fixed. Every block is embedded, matching scans the whole guide, and placement is judged against what each section actually holds. The mechanism is honest now.
Whether it feels like dissolving is a different question, and I have not answered it. Merging triggers at a similarity threshold I picked rather than calibrated, it only ever considers the single closest match, and nothing yet notices when a section has quietly grown into three. That is what real use has to tell me, and it is the part of this project I would most like to be wrong about.
Design decisions that define it
- Sources in, handbook presses out. The founding pivot: the product does not curate fixed content, it ingests your raw material and generates the structure. You bring the mess; it makes the shape.
- Merge by meaning, always visible. New content is embedded and compared against what exists. Near-duplicates merge by default, related ideas sit together, genuinely new ideas start a new section — and every merge is surfaced, never silent. This is the drop of liquid into the mixture.
- Never auto-apply; always reversible. Generations preview before they apply. Undo covers every hand edit, snapshots cover everything the AI does, and a bad result can never cost you your guide. Trust was designed in from day one, not bolted on.
- The reading surface is the editing surface (just like Notion). You rewrite a block where it sits, drag it into place, name it or unname it, send it to another tab. Underneath it is all markdown — that file is the artifact you own, and the blocks are a way of reading and rearranging it rather than a second copy of it.
- Search is the primary verb. It sits centered in the top nav rather than buried in a toolbar, because a reference tool is only as good as your ability to find the one thing you need right now. Its placeholder is drawn from real terms in your own content.
Open questions I am still sitting with
These are not roadmap items. They are honest questions about the structure I have already built, looking back at it as it stands.
- How much should the model decide at all? Retiring the type vocabulary moved one judgement from the machine to the reader. The open version of the question is where else that trade applies: how much structure should be proposed rather than imposed, and what is the smallest correction that makes a wrong proposal cost nothing.
- Is tab → section → atom the right shape for everything? It fits a reference manual cleanly. Does it fit a workflow, a process, a story — or am I forcing every domain into the shape that suited the first two I built for?
- Should merging really be the default? It keeps the guide tight, but merging is lossy. Am I quietly eroding the specific phrasing that made a source worth keeping?
- How much automatic reorganisation is too much? Self-organisation is the magic, but it also means the structure can move under someone who thought they knew where things were. Does that build trust, or quietly break a user's mental model of their own guide?
- Where is the line between a threshold and a judgement? Merging fires above a similarity score. Set it high and obvious restatements pile up as duplicates; set it low and it fuses things that merely rhyme. There is no correct number, only a number that feels right to the person whose knowledge it is — which suggests it should not be my number at all, and I do not yet know what the alternative looks like.
Where I am taking it next
- Calibrate the merge. The mechanism works; the judgement is untuned. Real pastes against a real guide are the only thing that will tell me whether the threshold is close, and whether merging should be rewriting someone's words at all.
- Polish the front door. Make the component library as refined as it can be and attach a genuinely attractive landing experience. The tool should look as considered as it is.
- Make adding data frictionless. Adding a source should feel like adding a drop to a homogeneous mixture — instant, clean, self-organising, with no manual filing.
- Make search powerful. It needs to sift the whole guide and surface exactly what matters in the moment you are looking — fast, robust, and smart about meaning.
- Earn trust with other people's data. As people host their own handbooks here, I need to raise the bar on security and safety.
- Decide the economics. How much do I invest in providing the AI tokens that make the magic happen, and where is the sustainable line?