Concepts

Taco, entity, file, type, name, description, 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/handle, which is also its URL. It has a display name as well — what you call it — and the two are different things on purpose: see Name. Its current state is the live version; its history is an ordered log of checkpoints.

Entity

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

Entities 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. An entity earns its own identity by being something that evolves independently and gets referenced, not because a schema said so.

An entity also has a display name — what it is called, as opposed to the handle it is addressed by. Renaming one is a real change to the work and is recorded as such: see Name.

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 an entity are deliberately NOT the same kind of thing, and the differences are the useful part. An entity is written and a file is uploaded. An entity 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. An entity carries a type and a file does not. An entity 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.

An entity shows a file by embedding its reference. A file an entity still shows cannot be deleted until the entity stops showing it — that guard is real, and it is what stops a picture disappearing out from under the writing around it.

Type

The kind of ENTITY, drawn from a small set of types the taco itself declares. A type is a handle, a short instruction saying what belongs in it, a colour and a shape — decision, constraint, dead-end, open-question, whatever this line of work actually needs. The colour and the shape are how it is drawn: a shape follows the usual diagram conventions, so a rectangle is a claim or a finding, a diamond is a decision or a branch, and a circle is a person, a company or another actor. A shape says what a kind is, never how far along it is.

Nothing is ever seeded and no types is imposed: the author declares the types, and does it in the same act as writing the content they are for — a kind and the entities filed under it are saved together, under the same note about why. A kind the taco does not have yet is stated in full: a name, a sentence, a colour and a shape. Revising one you already have changes only what you mention; the rest stays as it was.

An entity’s type is fixed once written, and a type’s meaning is not: rewording what belongs in a kind is a change like any other, so it is kept, and you can look back at what a category used to say it was for.

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.

Name

What something is called, as opposed to where it lives. A taco and an entity each have two: a handle and a display name. They are not redundant, and keeping them apart is what makes both work.

The handle is the address. It is the owner/handle in the URL, it is what a reference resolves through, and it is a slug — lowercase, no spaces. It has to be unique, because two things at one address is not an address.

The display name is for people. Capitals, spaces, punctuation, a colon in the middle — Rate Limiting: What We Settled rather than ratelimit-notes. It is unique nowhere, so two tacos may share one, which is exactly what stops it quietly becoming a second address. Search matches it, so work is findable by the words someone would actually use for it.

Changing them is not the same act. Changing a handle moves the address, so existing links stop resolving — deliberate, and the same thing renaming a repository does. Changing a display name breaks nothing at all.

Description

The taco’s headline summary — what this line of work is about, in a paragraph. It belongs to the taco rather than to any entity. It answers a different question from the display name above it: the name says what this work is CALLED, the description says what it is ABOUT. Search matches both, so it is worth writing for someone who does not already know what the taco is.

It is plain text and deliberately short. Anything longer — the reasoning, the conventions, the detail — belongs in an entity, where it can be read, revised and checkpointed on its own.

Treat a description you did not write as useful background on how someone framed 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 entity 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 takes the whole thing: the description, every entity, the files and the declared types.

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 entity. An entity 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 records your writing. A file’s bytes never change, so there is nothing about a file for a checkpoint to capture — what the record holds is which files were there.

Deleting a file deletes it — the file and its bytes, always, with no undo and no second outcome to check for. That is deliberate: freeing storage is what it is for, and a delete that kept the bytes could not do that.

Removing an entity takes its files with it, and that is usually where the space goes. The entity’s own writing is kept — it stays in the checkpoints that recorded it, which is what makes the history worth having — so removing it frees very little text. Its files are a different matter: they leave with it and their bytes come back.

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

The same refusal appears from the other direction. If you remove an entity whose file some other entity still shows, nothing is removed at all — the refusal names the entity that is still showing it, and you decide what should happen to that one first.

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.