---
title: Concepts
description: The ideas every RoutineOS routine is built from, and how they connect.
sidebar:
  order: 1
---

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](/concepts/routines) | What a routine is, its four types, and its lifecycle |
| [The definition](/concepts/definition) | How `definition.json` declares record types, identity, filters and views |
| [Settings](/concepts/settings) | Typed values people tune, and how filters use them |
| [Stages](/concepts/stages) | Lifecycle stages, run phases, and the workflow stages packs declare |
| [The store and the write contract](/concepts/store-and-write-contract) | How every run write is planned and checked |
| [People-owned and producer-owned data](/concepts/ownership) | The one-writer-per-document rule |
| [Gates and approvals](/concepts/gates-and-approvals) | How nothing leaves without a person's yes |
| [Notifications](/concepts/notifications) | How a routine gets a person's attention |
| [Learning](/concepts/learning) | How routines improve from what people do |
| [Records](/concepts/records) | Entities: ids, status, display values, links |
| [Sightings](/concepts/sightings) | The per-run history on every record |
| [Merges](/concepts/merges) | Merge policy and hand merges |
| [Views](/concepts/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](/reference/glossary).