Topics, artifacts, and versions

#A topic is a project

A topic has a key (its stable id, used in URLs and by agents), a kind, a title, tags, and two fields written for agents: instructions (how to work on this topic) and skills (what to load before acting). Topics live in exactly one workspace. Archiving hides a topic from the list; deleting moves it to the trash, where it can be restored.

#An artifact is a named document

Inside a topic, an artifact has a name such as status, journal, or spec, a file path, an owner, and a history of versions. The topic's kind declares which names it expects and what each is for. A name that starts with x- is yours to invent: x-meeting-notes, x-scratch. It skips the kind's contract and is never wrong.

#Every write names the version it read

A write carries the base version: the head you read before editing. If the head moved in the meantime, den refuses with a conflict instead of overwriting, and you merge and retry. The app does this for you; an agent passes base_version; the CLI sends If-Match. A first write uses * as its base.

The head is the newest committed version. Older versions stay readable forever: pick one in the version list, or pass version to read_artifact.

#Leases for long edits

A quick save needs no ceremony. For a long edit, check out the artifact: you hold a lease for two hours (eight at most), other writers see who holds it and until when, and your saves go through while you hold it. Check in releases it. A lease you forget expires on its own. Owners and admins can release someone else's lease.

#The trash keeps everything

Deleting an artifact or a topic is a soft delete. It leaves the lists, keeps every version, and comes back with Restore from the Trash page. Nothing is purged in the app.

#Documents

Some artifacts are structured: a list, a table, or dates, kept as JSON and drawn by the app. An agent writes them through find_place (which place a thing belongs in, and the smallest valid shape), change_document (the whole document, with base_version) and change_rows (one row, item or event by id). A document that would lose a row is refused until the removal is confirmed. A table leaves and arrives as CSV.

#Export

A topic exports as a folder: a topic.json manifest and one file per artifact, with every version if you ask. The folder imports into any den with the CLI, so a topic can move between workspaces or dens, and a workspace can be backed up as plain files.