Concepts

The ideas every RoutineOS routine is built from, and how they connect.

A RoutineOS routine is a folder of plain files plus a store. The files say what the routine is (its type, schedule, settings, prompt and record types). The store holds what it found and what people decided. A small set of rules, held in code, says who may write what.

The map

routine folder                         store (artifact database)
--------------                         -------------------------
routine.toml   type, schedule,         meta/        workspace, compiled definition
               settings, gate          settings/    people: setting values
prompt.md      the work, in words      entities/    producers: records and sightings
definition.json record types, views,   runs/        producers: one doc per run
               learning                inbox/       producers: messages for people
dashboard/     the Desk page           pending/     producers: gates waiting
app.toml       integrations, budget    decisions/   people: keep, drop, approve, reject
                                       merges/      people: hand merges
                                       views/       agent proposes, people own
                                       state/       producers: learning tallies
                                       data/users/  each viewer: private state

Reading order

Page	Read it to learn
Routines	What a routine is, its four types, and its lifecycle
The definition	How `definition.json` declares record types, identity, filters and views
Settings	Typed values people tune, and how filters use them
Stages	Lifecycle stages, run phases, and the workflow stages packs declare
The store and the write contract	How every run write is planned and checked
People-owned and producer-owned data	The one-writer-per-document rule
Gates and approvals	How nothing leaves without a person’s yes
Notifications	How a routine gets a person’s attention
Learning	How routines improve from what people do
Records	Entities: ids, status, display values, links
Sightings	The per-run history on every record
Merges	Merge policy and hand merges
Views	Saved filters and sorts over records

Vocabulary in one breath

A routine is a scheduled agent. When it writes to a Desk it is a producer, and its routine name is its producer id. It writes records (entities) of the types its definition declares. Each run adds a sighting to every record it saw and writes one run document. Settings filter records; a filtered record is kept with status dropped and a reason. Messages for people go to the Inbox; anything that would leave the routine waits behind a gate. People’s choices are decisions. The learning step reads decisions and raises proposals. See the Glossary.