# Workspace, projects, goals, tasks

The fixed part (Soots, teams, projects) and the flexible part (goals, tasks, schedules); change what a team does by changing its goals.

A workspace run on Soot needs two different things. The first changes rarely: who does the work (Soots, teams), which project they work on, which server they run on. The second changes every week: which metric to push this week, which tasks to do. If you mix the two, changing direction means a person has to edit a Soot's system prompt or the workspace's ontology. Soot keeps them apart: the fixed part is config, and the soft part is data (goals, tasks) that the host feeds into the next run by itself. A person changes what a team does by changing a goal.

## Model

```text
FIXED (config in deployment.json, changes rarely, via settings action)
  Workspace ─ Project (workspace.projects[]) ─ Team (group)  ─ ontology.json: entities, relations, processes between teams ─ Soot
            server that hosts the Soots and teams

SOFT (data in the workspace store, changes any time)
  Project direction     level=direction   one active goal per project
   └ Cycle goal         level=cycle       metric + guardrails, about 6 weeks
      └ Team goal       level=team        proposed by the team, linked to a cycle goal
         └ Task         task.goal         tied to a goal, or left empty = operations
            └ Recurring task   task with repeat   this is the "schedule"
               └ Outcome   outcome          unit of finished work, recorded with its cost
```

Three main ideas:

- Few levels. A goal is measured by a number, not by how many tasks are done. Tasks serve the goal.
- Alignment, not decomposition. A person (or Lead) sets the project goal. Each team's coordinator proposes the team's own goal and says which cycle goal it links to.
- Soot does not know what a goal measures. `metric.ref` is a free-form string that a pack or skill interprets (for example `company-loop:first_payers`).

## Concepts

### A project is a label, not a server

`workspace.projects[]` is `{id, name, logo?}`; `id` is an immutable slug. One server hosts many teams, one project groups many teams, and one team can work for many projects (an empty `groups.<id>.projects[]` means all projects). A Soot's project is derived in this order: the single project that its teams declare, the host's `project` label, the workspace folder name. Tasks, goals and outcomes all carry this label, so reports and Nest filter by project without splitting the infrastructure. The contract is in contracts/projects.md.

### Goals

| Level | Set by | Meaning |
|---|---|---|
| `direction` (long term) | Person | One per project: the main metric and the sentence "what winning looks like". Changes very rarely |
| `cycle` (short term) | Person, proposed by Lead | One cycle, 6 weeks by default. Requires at least one guardrail |
| `team` | Proposed by the coordinator | An input metric the team can push itself; `parent` is a cycle goal of the same project |

An empty `project` means the whole workspace. Statuses: `draft`, `active`, `done`, `dropped`. Each goal has a `metric` (starting point, target, which direction is good), `guardrails` and check-ins (`value`, `confidence` 0..10, `note`). A guardrail is a metric that must not get worse: any metric you target can be gamed, and agents do it more easily than people. The current value is not stored in the goal; it is the last check-in, written by whoever owns the metric and reads it.

`workspace.goals` sets limits (how many active goals per project and per team, so a team does not carry ten priorities), who approves team goals (`approve_team_goals`: a person or Lead), who can activate recurring tasks that can wake a model (`approve_waking_repeats`), and the `cadence` list. See `soot schema deployment`. The contract is in contracts/goals.md.

### Tasks

A task is the record that people and Soots share: status (`todo`, `doing`, `blocked`, `review`, `done`, `canceled`), assignee (Soot, team, person), parent and child tasks, due date, comments, and an append-only log. Creating a task (`create`) does not start it: `start` is an explicit run, and only a Soot or a person marks it `done`. Sending a task (`send`, next section) creates and starts it in one step. Two fields tie a task to the workspace:

- `goal`: the goal the task serves. Empty means an operations task (answering customers, fixing bugs, measuring numbers, holding guardrails). Nest warns when too many open tasks have no goal.
- `project`: the task's project. If empty, the run takes the goal's project, or the team's only project.

### Sending a task: a task is a message

`send` writes a task together with a letter and starts it at once, without spending a model turn on forwarding. It exists as the `send` op of the `task` tool (in runs that the workspace started: Nest, schedules, events, tasks; not in widgets, SDK, live chat, evals or dry runs), at `POST /v1/workspace/tasks` with `deliver: true`, and as `soot tasks send --to team:<id> "title"`.

- `to: team:<id>`: the host picks who runs it, the team's coordinator. `to: soot:<id>` is only for use inside the same team; a Soot in another team must send to the team (`mail_address_team`). A task never reaches Lead (`mail_for_lead`). A task for a member runs as that member, inside the team, with the budget of the team and of the member ([agents.md](https://trysoot.com/docs/agents/index.md)).
- A task from a person (Nest, CLI, Lead) is only stopped by the loop guard. A task from a Soot or another runtime also passes two limits: beyond `mail.daily_per_sender` (default 20) tasks a day from one team to one team, the task stays `todo` with `mail_rate_limited`; a team with `inbox: "hold"` makes the task wait for a person to start it (`inbox_hold`). A task created during a run that serves another task carries `hops + 1`; beyond `mail.max_hops` (default 4) it is recorded without running, with the `mail_loop` tag. A team with no coordinator yet: `team_needs_coordinator`, and it runs by itself once there is one.
- `budget_tokens` is a token ceiling for the receiving run, on top of the receiving Soot's own ceiling. When the ceiling or the team budget runs out, `reply` is `blocked` with the reason.
- When the run ends, the host sends a `reply` back to the sender: status (`done`, `failed`, `blocked`, `needs_person`), a summary of at most `mail.reply_bytes` (4 KiB), result files, token count. A person reads it in the task log (`mail_reply`); Lead gets a host note in the thread without spending a turn; a Soot that sent with `wait: true` gets exactly one next turn with the `reply` as input.
- `request_id` makes a resend the same task; the same id with different content is rejected. `dry_run` returns where the task would go and who would run it, and writes nothing.
- A team on another server (group `remote`) can be sent to like a local team: the task here is a mirror, the other team runs it, and the status and `reply` come back on the polling beat. If the other server is off, the task waits with `delivery: pending` and never runs here in its place; after 30 minutes it gets the `mail_undelivered` tag. Contract: contracts/team-mail.md.

- A forwarded task (team A sends part of it to team B with `wait: true`) is answered from the end of the chain: only the turn that B's answer wakes replies to A's letter. While waiting, whoever waits at the head of the chain (a customer through intake, the Soot that sent) is told once per cause: the task waits for an approver anywhere in the chain (including on another server), the task is past its `due`, and the task has been open longer than `mail.progress_after_seconds` (default 300 seconds; told again at 4, 16, 64... times that mark). A task that is canceled or marked done by a person before its run replies still replies to the sender (`task_canceled`, or `done` with a note), so nobody waits forever.

Config: `mail {max_hops, daily_per_sender, reply_bytes, progress_after_seconds}` at the root of the deployment and `groups.<id>.inbox` (`auto` or `hold`). `project` on `send` is the task's project label.

A customer's report to a team goes through intake (`intakes.<id>`, contracts/intake.md), not through a contract line: a contract line reaches no tool, and the Soot that receives reports can stand alone, outside any team with a contract. A task from intake is still a letter as above, with the same limits.

### Granting a contract line when needed

When the workspace has an ontology (one entity or one relation), a team A Soot that reads a table or writes to team B's queue without the ontology having that relation or column is refused with a code (`contract_not_consumed`, `queue_not_requested`, `contract_field_unknown`). The error comes back with how to ask: call `report_blocker` with `grant {kind: "contract", team, item, level: "read"|"write", fields}` and stop. If the workspace has no ontology yet, the permission error stays as it was and there is no hint to ask. The host checks the request before letting the run stop: the team must be on this runtime, the table must be in team B's pack, and the relation must not be granted yet. A team on another runtime is refused with `contract_grant_remote_unsupported`, with the runtime's name.

- Every waiting run on the same line (same asking team, owner team, table, columns, read or write) merges into **one** Cần bạn card `contract-grant:<id>`. The id is a hash of the line, so asking again only adds a run to the old card.
- A person approves with `POST /v1/settings/contract-grants/{id}` `{decision: "grant"}` or `soot teams grant <id>`. The host edits `ontology.json` in one settings revision (action `contract.grant`). If team B has not declared the entity yet, it is added (for all tenants, never with a principal column), or its columns are widened if it exists. Team A gets a `read` relation, or `request` if it is a write. Another team that reads all columns of the widened entity keeps exactly its old columns. `dry_run: true` (`--dry-run`) returns the diff (before/after) for each team and writes nothing.
- Only once the runtime runs the new ontology (after the restart caused by activating the setting) are the waiting runs told to retry. The decision is stored in `contract-grants.json` in the data directory, so it survives a restart.
- Decline (`{decision: "decline", reason}`, `soot teams decline <id> --reason ...`): every waiting run gets the reason and continues with what it can still do. A line rejected by validation (for example `contract_principal_column`) returns `422` with that code; the ontology stays as it was, and the waiting runs are told and continue, so no run hangs.
- Each request has one decision: sending the same decision again is a replay (`replay`), sending a different one gets `409 contract_grant_decided`. An id with no waiting run gets `404 contract_grant_not_found`. Only a person can do this; a scoped token is blocked.

The Grant card in Nest's thread is phase P5b, not built yet.

### Watching processes

A process in the ontology (a move's `within`, `deadline`) is watched by the host, with no model: every 5 minutes, for an entity whose table this runtime holds, an instance that sits in a non-terminal state past its deadline gets **one** task letter sent to `team:<the team that holds the next move>` (process name, instance id, state, how long, next task), one per instance per state. A state with `gates` with `person` becomes a Cần bạn card instead of a letter. At most 10 letters per team per day; the rest is only a line in Cần bạn. A runtime with no processes does nothing. `GET /v1/processes` (operator only) gives the number of instances per state and the stuck instances. Contract: contracts/process-watch.md.

### Recurring tasks are schedules

A schedule is no longer a separate config entry. It is a task with `repeat`, which has:

- Timing: `every`, `cron` or `at`, plus `timezone`.
- Status: `draft` (awaiting approval), `active`, `paused`.
- How it runs, one of two: a model turn with `text`, or a chain of tools (`tool`, `then`) that wakes the model only when `wake_when` sees something. A tool chain is cheap: a schedule that asks "is any article due" every 10 minutes costs almost no tokens, and the model is called only when there is an article.
- Assignee: `team:<id>` runs as the team's coordinator; `soot:<id>` runs as that Soot. If the team has no coordinator yet, or the schedule lands on Lead, the schedule is held (`held`: `needs_coordinator`, `lead_not_scheduled`) and shows up in the list, without breaking config loading. Lead does not run team schedules.

Each run is a turn of the task, not a new task (hundreds of runs a day would flood the task table):

| Run | How it is recorded |
|---|---|
| Quiet: the tool finished, nothing to wake, or it was skipped | Only the `repeat.stats` counters increase |
| Tool only | One job that is done, cleaned up after the retention period (`events.job_retention_days`, 14 days by default) |
| Wakes the model, or fails | One child task: `parent` is the recurring task, `goal` is inherited, title `<title> · dd/mm HH:MM`. An error before the run starts leaves the child task `blocked` with the reason |

When the budget runs out, the schedule does not run its tools. A run that can wake the model (it has `wake_when`, has `then`, or is a pure model turn) has its budget checked before the tools run: if the Soot that would be woken has used up its `daily_tokens` for the day, or the team has used up its contract budget for the day, the run is skipped (`skip_reason.kind` is `budget_exhausted`, `key` is `soot_daily` or `team_daily`, `budget_stop` has the same value). The tools do not run (so nothing is "taken" and then left), there is no child task and no separate Cần bạn card; the budget card of the Soot or team is the only one. A tool-only schedule, which never wakes the model, is not blocked. On a new day, or when a person raises the budget, the next run goes through normally and work that was stopped continues by itself. Failed child tasks of the same recurring task show only one `task_waiting` card (the newest child task); a child task blocked by budget has no card of its own.

The `token_budget_exhausted` and `team_budget_exhausted` cards advise "Wait" when what was stopped is only a schedule that will run again (next time). If what was stopped includes important work (a task a person sent or started, a Lead task on a person's behalf, due within 24 hours, or tied to a goal), the card advises "Raise the budget", names that work in `why` and puts the list in `payload.important` (`task`, `title`, `reason`). The runtime never raises a budget by itself: spending money stays a person's decision.

`repeat.stats` is computed on read: next run, last run, number of runs, wakes and errors in the last 7 days, last status (`ok`, `failed`, `skipped`, `held`), error, skip reason (a missing credential is not an error), most recent wake, and 7-day cost. The cost is summed from the traces of the most recent run's conversation and does not guess a price for turns that have none yet, so the number is lower than the real cost when a Soot is very busy. If a Soot's or team's token budget cuts a model turn, `budget_stop` says so: that schedule did not finish its work, so it must not be shown as healthy. An unfinished model turn of an old schedule is replaced by the new turn (superseded), and the needs-a-person card of the old turn no longer counts as waiting. Running a recurring task immediately (`soot tasks start <id>`) runs the exact scheduled run, including the tool chain and jobs, not an ordinary model turn.

`origin` says who created the recurring task:

| `origin` | Where from |
|---|---|
| `host` | A person or a Soot, through HTTP, CLI or Nest |
| `source:<id>` | A source declared the schedule in its repo |
| `template:<team>` | Team template (`group.create`); deleting the team deletes them |
| `cadence:<id>` | Kept by the host from the team goal (see below) |
| `nest` | Lead's first morning briefing, read-only |

Tasks that are not `host` are read-only, except `state` and `goal`; their content follows the place that created them. The old `schedules` field in `deployment.json` is now only a migration input: the runtime reads it, warns, and mirrors each entry as a recurring task (`soot migrate schedules` removes the field once every id has a task). The old paths (`schedule.save`, `GET /v1/settings/ schedules`, `soot schedules`) answer clearly that they are removed, and do nothing silently.

Permission to create follows money, because a recurring task that wakes a model is regular spending:

| Creator | Result |
|---|---|
| Person | Active (unless a draft is requested) |
| Lead or coordinator, tool-only | Active (a coordinator only for its own team) |
| A task that can wake a model | Draft. When Lead creates it, it activates itself if `approve_waking_repeats = lead_within_budget` and the last run's cost is within the team budget |
| Another Soot | Always a draft |

### Outcomes

A pack declares what counts as one unit of finished work (`pack.json` `outcomes`: `id`, `label`, `unit`, void window `void_window`). A Soot records it with the `outcome` tool (or `soot outcomes record`). The host copies the project label into the record, adds the cost of the attached job, and allows voiding within the window. Reports give `gross`, `voided`, `net` and cost per Soot and project. The contract is in contracts/outcomes.md.

Outcomes and goals connect through numbers, not through a foreign key. An outcome is what was done and what it cost; a goal's metric is what changed. A pack (such as company-loop) reads its own numbers, then the team writes the check-in. Core does not add outcomes into a goal by itself.

## Main flows

### From goal to task

```text
Cycle start  person + Lead: set a cycle goal for each project
             Each team's coordinator: propose a team goal (draft), linked to a cycle goal
             a person approves (or Lead, if approve_team_goals = lead) → active
             team goal active → host keeps the cadence recurring tasks for that team
During cycle coordinator + members: create tasks tied to a goal, run, record outcomes, check in
When it changes  a person edits a goal → host pauses the related recurring tasks and notifies;
             the next run sees the new goal
```

Teams propose; goals are not handed down. A team goal in `draft` creates no cadence tasks until someone approves it, so the host puts a `goal_drafts` card into Cần bạn ("Needs you") for each project that still has a draft goal. The card disappears when the last draft is approved or dropped.

A cadence is a template `{id, title, cron, timezone, text}` in `workspace.goals.cadence`. For each team that has an active team goal, the host keeps one recurring task per template (a start-of-week commitment cadence, an end-of-week check-in, if a person configured it that way), assigned to `team:<id>`. The task runs while the goal runs, is paused afterwards, and stays as it is if a person paused it by hand.

### Who can do what

The `goal` tool checks permissions inside the host, not through the prompt:

| Actor | Allowed |
|---|---|
| Person (HTTP, CLI, Nest) | Everything: create (can be `active` right away), edit, approve, check in |
| Lead | `list`, `get`, `propose`, `update`, `checkin`. `approve` only team goals, and only when `approve_team_goals` is `lead`. Direction and cycle belong to people |
| A team's coordinator | `propose` a draft for its own team, `update` its own draft, `checkin` the team's goals |
| Another Soot | `list`, `get` |

For tasks: Lead can `start` any task; a coordinator can `start` a task assigned to its own team or to a member, still within the team's budget. Any Soot can `send` to a team, including a team on another server, within the limits above. Nothing picks up work and runs it by itself: a task runs only when a person or coordinator starts it, or when it is a recurring task that has come due. `workspace.goals.save` (limits, approval mode, cadence) is a person's setting; Lead can only propose, and the proposal waits in Cần bạn.

### What a Soot loads when it runs

The host builds a small context block (about 2 KiB) and puts it into the run as a system message placed after the transcript, starting with `[Workspace: host context, current as of this message]`. It is not in the system prompt, so a change to the work does not break the cached prefix of the prompt.

The block contains: the project direction, the active cycle goal with its last check-in and guardrails, the team's active goal, a few open tasks (each with its goal), the rule "no goal means operations", a summary (from the ontology) of what the team provides, decides and escalates to a person, and the team's brief. A run for one task adds a line "serves: <goal>". When over the size limit, the block drops tasks first, then the reason, then the brief; goals and guardrails are never cut. The block ends with a `## Tables` section: the tables the run's data tool reaches (`level: table — description`, at most 20), since what earlier work kept in a table is in no file or transcript; the lines name no row counts, so inserting rows does not change the block.

The block has no clock or counter, so it stays byte-identical until a goal, task or the ontology changes, and it is resent only when the transcript does not already end with exactly that block. A first run, a new schedule cycle and a delegated member always get the block. Public chat, SDK clients, evals and dry runs do not. A workspace with no goals has no block.

After a person edits a goal, the next run of every related Soot already sees the new goal. There is no need to edit the soul or mission, and no restart. A goal grants no extra permission: `decides`/`escalates` (in `ontology.json`), token budgets (`groups.<team>.limits.daily_tokens`) and money matters stay as they were.

### When a goal changes

Changing `status`, the target or the end date is a significant change. The host pauses every recurring task tied to a goal that is `done` or `dropped` (writing the reason on the task, reversible), creates a `goal_changed` card in Cần bạn naming the goal and its open tasks, and the context block on the next turn reflects the new goal.

### The first morning briefing

On first run, `AdoptFirstRun` picks the model that just answered for real as Lead's model and creates the morning briefing as a `nest` recurring task, read-only, run by Lead. `workspace create` and `workspace adopt` write teams from templates, together with their `template:<team>` recurring tasks.

## Workspace ontology

One file, `ontology.json`, beside `deployment.json` (found by convention like `soots/<id>/soot.json`). It gathers everything that sits between teams: the entities a team holds, which team reads or asks to write which entity, the processes that move an entity through its states, and the text that lets a Soot understand (what the workspace is, what each team takes, terms). A team carries no relations of its own: how a team works inside is the team's memory, mission and adapter. Without the file the workspace runs as before. Schema: `soot schema ontology`. Version `ontology/v1`; unknown keys are rejected.

```jsonc
{
  "version": "ontology/v1",
  "about": "what the workspace is and does",                  // 2 KiB at most
  "terms": [ { "term": "chapter", "aliases": ["chương"], "means": "…", "owner": "<team>" } ],
  "teams": { "<team>": {
      "does": "what the team takes", "not": "what it does not take", "ask": "how to write a request", // 600 bytes each
      "owns": ["concepts the team owns"],                    // 20 items at most, 80 bytes each
      "decides": { "self": ["…"], "with_person": ["…"] },    // what the team decides alone / with a person
      "escalates": [ { "when": "text for the person", "on": "queue_waiting", "after": "24h" } ],
      "emits": ["outcome_id"] } },
  "entities": { "<id>": {
      "description": "…", "owner": "<team>",                 // the team that holds the table
      "store": { "pack": "<pack>", "table": "<table>" },     // a team on another runtime may omit it
      "fields": ["columns other teams may see"],             // empty: every declared column (no principal)
      "tenant": "all", "queue": false,                       // queue: other teams may ask to write
      "state": "stage", "states": ["new", "done"], "terminal": ["done"] } },
  "relations": [ { "team": "<team>", "entity": "<id>", "can": ["read", "request"],
                   "fields": ["narrow what is read"], "why": "…", "optional": false } ],
  "processes": { "<id>": {
      "description": "…", "entity": "<id>", "deadline": "72h",
      "starts": [ { "via": "chat|app|admin|schedule", "team": "<team>" } ],
      "moves": [ { "from": "new", "to": "done", "by": "<team>", "within": "2h" } ],
      "gates": [ { "at": "new", "with": "person", "why": "…" } ] } }
}
```

An **entity** lives in a pack table; its columns come from the table definition and are not declared again. `queue: true` is an append-only queue: another team with a `request` relation may write to it, and the `fields` columns are the ones it may set. A **relation** is the only thing here that grants access: `read` lets a team read the entity (at most the relation's `fields`, within the columns the entity shows), `request` lets it write to the queue. Every old rule stays: error codes, column projection, tenant closed by the host, the `contract_read` log, teams on another runtime, granting when needed. Names with a project suffix (`posts@lohi`) still work. A **process** is the state moves of one entity, each move owned by one team (there are no steps inside a team); it is currently only checked at load and viewed through the `workspace` tool, with no watcher for deadlines (`within`, `deadline`) or person gates (`gates`) yet.

Checked at load: `owner`, a relation's `team` and a move's `by` must be groups in `groups`; the table and pack of `store` must exist when the pack is installed; `fields` and `state` must be columns; `states` contains `terminal`; a move's states and a gate's state must be in `states`; the process's entity must exist; a deadline must be a duration; limits are as before (2 KiB `about`, 600 bytes per text, 300 terms, 128 entities, 512 relations, 64 processes, 256 KiB for the whole file, no control characters). Text for a team that was removed (a `teams` key, a term's `owner`) is ignored rather than breaking the config; an entity, relation or move that points to a team that no longer exists is an error.

**Moving from the old way.** `groups.<team>.contract` and `workspace.ontology` are removed, and loading reports `retired_field` with "moved to ontology.json"; there is no automatic migration command. The mapping: `provides.tables` becomes `entities`; `provides.queues` becomes `entities` with `queue: true`; `provides.events` becomes `teams.<team>.emits`; `consumes` becomes a `read` relation; `requests` becomes a `request` relation; `decides` and `escalates` go to `teams.<team>`; `budget.daily_tokens` goes to `groups.<team>.limits.daily_tokens`.

**Who edits.** A person, in the file or with the `ontology.save` action (replacing `workspace.ontology.save`). Lead only proposes; a proposal waits in Cần bạn. Granting when needed writes relations into the same file. Nest still edits a team's "contract" part; the host writes it back to `ontology.json`. `GET /v1/ontology` (and the `ontology` key of `GET /v1/workspace`) returns the loaded file, for the operator only (a scoped token and a member key cannot read it). A peer reads a team's contract through `GET /v1/teams/{id}/contract`, still in the `team-contract/v1` form but now derived from the ontology.

**Three layers of tools.** Work mail is a default skill of every Soot: the `task` tool's `send` op, with how to send it properly (take the address from the tool, one letter per task, write enough that the receiver does not have to ask back, do not resend just to ask about progress). A Soot that is in a team also has the `team` tool. If that team belongs to a workspace (the deployment has a `workspace` block, or there is an ontology), the Soot also has the `workspace` tool. Lead is in no team but still has `workspace`. Both tools are read-only and exist only in runs inside the owner's space, not for guests, widgets, SDK or public chat.

| `team` tool, op | Returns |
|---|---|
| `members` | The members of the Soot's team, the coordinator first: `address` (`soot:<id>`, the address to send a letter to a teammate), `name`, `does` (the Soot's description), `coordinator`; plus `you` |
| `about` | `address`, `name`, `description`, `projects`, `coordinator`, `inbox`, and `provides` / `consumes` / `decides` / `escalates` derived from the ontology |

To give work to the whole team, send to `team:<id>` and the coordinator picks who does it. A member of another team cannot be sent to directly; go through that team's `team:<id>`.

The `workspace` tool:

| op | Returns |
|---|---|
| `teams` | Every team, by id: `address` (`team:<id>`), `name`, `server` (`here` or the name of the `remote` team's server), `description`, `projects`, `does`, `not`, `ask`, `owns`, `provides` (entities the team holds); the Soot's own team has `yours: true` |
| `team` + `id` | One team, plus `decides` and `escalates` |
| `terms` + `query` | Up to 20 terms matching the name, an alias or the meaning, ignoring case and accents; with `owner: "team:<id>"`. Without `query` it lists them all, paged with `limit`/`offset` |
| `about` | `about` and the workspace's projects |
| `entities` (+ `id`) | Entities: owner, description, queue, lifecycle; one entity adds the teams that have a relation to it |
| `processes` (+ `id`) | Processes: entity, deadline, the moves (which team owns each), where it starts, person gates |

Each call returns at most 16 KiB and reports `more: true` (with `next_offset`) when cut. The ontology is not in the system prompt or the goal block: a Soot pulls it when needed, so it costs no tokens on every turn. When a send address is wrong, the refusal lists the teams, each with `does` (or `description` if none), then points to `workspace op teams` for the full view (only when there is a workspace).

**Text grants nothing.** `about`, `terms`, `does`, `not`, `ask`, `owns` are text for understanding only: writing "team A takes every task" does not make team A take anything. Who may send work to which team, budgets and inboxes are still checked by the host from `groups`. Only a relation lets a team read or ask to write another team's data, and only through the existing data tools.

Diagnostic codes (pointer into `ontology.json`):

| Code | When |
|---|---|
| `ontology_team_unknown` | a `teams` key or a term's `owner` is not a group: only at save (`ontology.save`); at load it is ignored. An entity owner, a relation's team, a move's `by` that is not a group: an error at load too |
| `ontology_term_duplicate` | terms or aliases that collide (ignoring case and accents) |
| `ontology_too_large` | over a limit (see above) |
| `ontology_invalid` | control characters or direction-change characters, empty entries, or an entity, relation or process that breaks a rule |

## Nest

| Screen | What it does | Code |
|---|---|---|
| Mục tiêu và việc ("Goals and tasks", `nest://goals`) | Goal tree per project, task table filtered by goal or "operations", create, edit, approve and drop goals, approve draft recurring tasks, ask Lead to draft goals when there are none | `desktop/src/modules/goals/` |
| Việc › Lặp lại ("Tasks › Recurring") | View, pause, edit and run now a recurring task, with `repeat.stats` | `desktop/src/modules/tasks/` |
| Công ty ("Workspace") | Projects, teams, what each team provides, who depends on whom; the project layer only shows when there is more than one project | `desktop/src/modules/team/team-workspace.tsx` |
| Kết quả ("Outcomes") | Outcome report per project, CSV export | `desktop/src/modules/outcomes/` |
| Cần bạn ("Needs you") | `goal_drafts`, `goal_changed`, failed schedules, Lead's proposals | `desktop/src/modules/needs/` |

Nest talks to many servers; the goals screen merges the servers that support it and says which ones have not been updated. Nest keeps no goals of its own.

## Who owns what

| Party | Owns |
|---|---|
| Core | Tasks, recurring tasks, permission checks, outcome reports, the project list `GET /v1/projects` and the hooks features plug into |
| Workspace feature (`internal/feature/workspace`) | The goal model, check-ins, drafts, the `goal` tool, the context block, cadence, the `goal_drafts` and `goal_changed` cards, the goal routes, the `workspace.goals` config; declares projects as the projects of `GET /v1/projects` |
| Pack | The meaning of `metric.ref` and `guardrails[].ref`, outcome ids, the skills that compute the numbers (company-loop keeps `metrics` and bets) |
| Config (people) | Projects, teams, limits, approval mode, cadence |
| Lead | Proposes goals and config; does not approve direction/cycle |
| Coordinator | Proposes team goals, picks and starts tasks within the team, checks in |
| Nest | Shows and sends commands; decides nothing itself |

Deliberately not done: core does not understand specific metrics (left to packs to extend, see [extensions.md](https://trysoot.com/docs/extensions/index.md)); goals do not grant permissions; there is no queue that picks up work by itself; prices, limits and entitlements are project data and do not live in goals.

## Not there yet

- Automatic end-of-cycle scoring: the `score` field (0..1) exists, but a person or team fills it in.
- Core reading real metrics by itself: the current value comes from check-ins.
- A "week's wins" digest generated by core: the weekly rhythm is only a `cadence` template that a person configures.
- Team–project–part constraints from company-loop's `parts` table: core only checks that the team exists, the parent goal and the limits.
