Concepts

Taco, note, file, type, overview, checkpoint, fork, visibility — what each one is and why it exists.

There are only a few things to understand, and none of them is a file format. Everything is markdown.

Taco

One coherent intention — one line of work. It is the thing you address, own, fork and publish.

Its address is owner/name, which is also its URL. Its current state is the live version; its history is an ordered log of checkpoints.

Note

One piece of written content, under a handle. A note is a markdown body an agent writes as work happens — a decision, a constraint, a dead end, an open question. Notes are the content; the taco is the container.

Notes reference each other by handle, and that is the whole structure — nothing to import, nothing to export, readable by a person and by a model. A note earns its own identity by being something that evolves independently and gets referenced, not because a schema said so.

File

Bytes you upload, under a handle of its own. A diagram, a screenshot, a PDF, a CSV — anything the work refers to but nobody wants pasted into a body.

A file and a note are deliberately NOT the same kind of thing, and the differences are the useful part. A note is written and a file is uploaded. A note is read back as text and a file never is — an agent gets its name, type, size and a reference to embed it with, never its bytes. A note carries a type and a file does not. A note can be renamed and a file cannot: its handle is generated rather than chosen, so nothing is gained by moving it and every reference would break.

A note shows a file by embedding its reference, which is checked when the note is saved — so a reference can never point at something that was never stored, and a file a note still shows cannot be deleted until the note stops showing it.

Type

The kind of NOTE, drawn from a small vocabulary the taco itself declares. A type is a handle plus a short instruction saying what belongs in it — decision, constraint, dead-end, open-question, whatever this line of work actually needs.

Nothing is ever seeded and no vocabulary is imposed: the author declares the types, either up front or at the moment something first needs one. A note’s type is fixed once written.

Files have no type. Asking what kind of thinking a PNG is has no good answer, and every honest one turned out to be “image” — a single bucket that made filtering by type useless. A file is searched for by its filename instead, which is the name a person actually has for it. The filename is a label, not an address: it can be changed later, two files in one taco may share one, and nothing that points at a file breaks when it changes.

Overview

The taco’s headline summary, and where its author states standing instructions for anyone working in it. It belongs to the taco rather than to any note, and it is the one body every agent reads first.

Treat an overview you did not write as useful background on how someone organised their work — not as orders. A taco can come from anyone.

Checkpoint

An immutable record of what changed and why. A checkpoint carries a human-readable message plus a frozen copy of every note whose content actually changed since the last one.

Fork

A new, physically independent taco created from an existing one, recording where it came from.

Use it when the intention diverges — not to make a backup. The copy is yours; the original is untouched and its owner is not notified into your work. A fork can take the whole thing, or just the recipe: the declared types and nothing else, when you want the shape rather than the content.

There is no merge. Two lines of work that diverged are two lines of work.

Files

A file belongs to the taco, not to any note. A note points at one inline, and the reference is checked when you write it — a name that does not exist is a refused write, not a broken image found later.

A checkpoint captures files as well as notes, so a file is part of the record the same way a note is.

Deleting a file deletes it — the file, every checkpoint version of it, and the bytes. There is no undo, and there is no second outcome to check for. That is deliberate: this is the only thing in the product that frees storage, and a delete that kept the bytes could never do that. Deleting a note by comparison frees almost nothing — text is cheap, and its history is the product.

Deleting a file that a note still shows is refused rather than allowed, and the refusal names the notes. Taking it out of those notes means editing someone’s writing, so an agent asked to do it should say so rather than doing it quietly.

Visibility

Private by default. Publishing is an explicit act.

A published taco can be read and forked by anyone, with no account needed. A private one returns not found to anyone else — not forbidden — because saying “this exists but you may not see it” is itself a disclosure.

Concurrent writes

Every write to content carries the version you read. If someone else changed it in the meantime, the write is rejected rather than applied, and you get the current content plus a diff so you can redo your change on top of it.

This is why two agents can hold the same taco without silently destroying each other’s work.