Skip to main content
A Collection is not a spreadsheet. It is the operational substrate: a configured table whose records read the team’s Knowledge before anyone works them. This guide works a single record the right way, reading the collection’s criterion first, so the update reflects the team’s criteria instead of a fresh guess. The example is a pipeline collection where each record is an account. Read it as a lead, a customer, a content item, or a product signal: the shape is the same, only the configuration differs.

​
Outcome

One record advanced with the team’s criteria applied: the criterion Knowledge read first, the confirmed fields updated, and the status changed only because the underlying state changed, not because the workflow reached a step.

​
When to use it

  • You are working a record in a pipeline, an analysis, or a content collection and want to apply the team’s recorded criteria, not improvise.
  • The same real-world identity shows up in more than one collection and you want it understood as one Entity.
  • You want to keep operational state where it belongs while escalating any finite follow-up to Work.

​
Availability and prerequisites

You need the CLI installed and logged in. Over MCP or OAuth, collection, record, and entity writes require the work:write scope; reads and collection doctor are member-level.

​
Objects involved

​
Before you begin

Find the collection you mean to work, and confirm the workspace. Searches are intent-ranked and active-only by default.

​
Context preflight

The seam that makes a Collection more than a table is its criterion: the criterion_rel_slugs that resolve to the Topics the team wants read before a record is worked. Read them before you evaluate anything. Two ways to pull it, depending on whether you also want the records:
retrieve returns { records, nextCursor, criterion, criterion_missing }. If criterion_missing lists a slug that does not resolve, that is a gap: the collection points at Knowledge that does not exist yet. Close it with a Note or a Topic (see Govern agent learning) rather than working the record blind. Do not pull the whole workspace; the criterion is the scoped context this collection asked for.

​
Step-by-step workflow

1

Resolve the Collection and read its shape

Read the archetype, schema, stages, views, and criterion relations before touching a record. The stages are the only statuses a record may sit in. get is brief by default; pass --view full to read the full config (record_schema, views, distill_policy).
2

Read the criterion, then pull the relevant records

Load the team’s “how we do this” first, then the records to work.
Read criterion before you read the records. It is the difference between working with the team’s judgment and working from scratch.
3

Resolve or create the Entity

If this account also appears in another collection, tie the records to one identity. An Entity upserts idempotently on (kind, dedup_key), so re-adding the same pair updates it instead of creating a duplicate.
You should get back an <entity-id>. An Entity is not a row in a collection; it is a separate identity that records point at.
4

Resolve the Record

Find the specific record and read its current fields and status.
5

Evaluate, then update confirmed fields

Judge the record against the criterion and its current state, then write only the fields you can confirm. Link it to the entity while you are here.
6

Advance status only when the state actually changed

A status is a claim about reality. Move the record to a new stage only because the underlying thing changed, never because the workflow reached this step. A transition to a terminal stage triggers the distill_policy and the response carries a context_outcome (created · already_exists · skipped · failed) — best-effort, never blocks the write.
The status is validated against the collection’s own stages; a value outside them is rejected.
7

Delete a record, or retire the collection

Safe record delete previews impact before it touches anything: the Entity link that would be removed and the distilled Notes that are preserved (not deleted).
When the collection itself is done, archive it and (if truly permanent) purge it. Lifecycle is explicit — collection update --status cannot archive.
purge is owner/admin only and permanent; it preserves the distilled Notes the collection spawned (they survive the delete). Restore is collection restore <id> (archived → active).
Same surface over MCP: driftless_collection action:'search' \| 'retrieve' \| 'context' \| 'archive' \| 'restore', driftless_collection_record action:'update', driftless_collection_purge (owner/admin), driftless_collection_record_delete (safe, with dry_run), and driftless_entity action:'upsert'. Over REST it is GET /workspaces/:slug/collections/:id/retrieve, POST .../:id/archive|restore, DELETE .../:id?expected_version=, and the record and entity routes under the same base. See API: Collections, Records, and Entities.

​
Expected states

​
Knowledge write-back

Most of what you touch here is operational state, and it should stay that way. Escalate deliberately:
  • The record’s own values stay in the Record. That is operational state, not Knowledge.
  • Finite follow-up stays in the Record’s fields or status until it is complete. It is operational state, not a durable why.
  • A reusable observation (a pattern in how these records behave, a rule that keeps recurring) becomes a Note. Capture it, do not inline it into the record.
  • A durable why worth the whole team trusting (how this collection should be worked) may become Knowledge, but only after a person reviews it.
A single record’s outcome is not Knowledge. The recurring pattern behind many records might be, once reviewed.

​
What not to do

  • Do not invent a terminal status. Never set won, published, signed, completed, validated, deposited, or committed unless that thing actually happened. A status is a claim, and an agent writing it is making the claim.
  • Do not treat a Collection as an isolated table. Read the criterion first; that is the whole point of the substrate.
  • Do not confuse Entity and Record. A Record is a row in one collection; an Entity is an identity across collections. Deduplicate identities on the Entity, not by editing rows.
  • Do not promote a single record’s result into Knowledge. Operational outcomes live in the record; only a reviewed, durable pattern becomes a Topic.

​
Troubleshooting

  • A field write returns 400 VALIDATION_FAILED. The field is not in the collection’s record_schema, or its value is the wrong type. Read the schema with collection get and match the field keys and types.
  • A status change is rejected. The status is not one of the collection’s declared stages. A record can only sit in a stage its collection defines.
  • A duplicate entity appeared. You used a different dedup_key (or none). The upsert is idempotent on (kind, dedup_key); use the stable key consistently.
  • Something looks off across records. Audit the collection before relying on it:

​
Limits and truth states