# Concepts

Start with one `work` item: **Prepare the launch checklist**. It can stand alone in a **wirkspace**, the shared place for a team's items. Give it a title and a reason. Add an owner, status, or criteria when useful. A person can see what is planned and what was done; an authorized agent can read the item and update it as work proceeds.

Other items add detail when you need it. A `record` can hold the draft checklist or evidence; it is not another task. A `context` item can explain a team goal or an initiative. A link can connect the work to either one. Items remain flat: no initiative, folder, context item, record, or link is required before that first task.

When the checklist is completed, the edit includes evidence of the result. The item keeps its earlier revisions, so readers can see what changed. A **proposal** holds a suggested change for someone with review authority to decide. The sections below explain these parts and link to the [operations](/docs/status.md) and [first-use guide](/docs/getting-started.md).

## Accounts, wirkspaces and principals

An **account** is a team or a company. It holds **wirkspaces**, where items live, and its people and their agents. Everyone in a wirkspace can read everything in it. On the wire a wirkspace is `workspace_id`; you can leave it out when your token belongs to one wirkspace.

Each token belongs to a **principal**: a person (`alice`) or an agent (`alice-agents`, agent of `alice`). A person's agents work under their own agent principal, so every change says who, or what, made it: cards show `by alice-agents (agent)`. Roles in a wirkspace are reader, editor, reviewer and administrator, each adding to the one before, and proposer, for agents only: a proposer reads and proposes, and applies nothing, completing work included. Agents are never administrators. An agent with no membership of its own acts with its person's role, capped at reviewer; an agent given a membership of its own acts only through it. Working in several wirkspaces means being a member of each.

## Items and their kinds

An item is anything worth keeping. Every item has a title and may have a body, files, and the wirkspace's **fields**: values from lists the wirkspace defines, such as `status` or `priority`. The wirkspace's administrators define fields; agents use them. Keys are stable; display names can change. [status](/docs/status.md) lists the keys and values your wirkspace uses. The launch checklist is `work`; a draft checklist saved as a `record` does not gain a work status just because it is linked.

Every item has one of five kinds. Cards print it, and you filter on the same word:

| Kind | What it is |
|---|---|
| `work` | An item with a work part: an optional `owner_id` (a member, `me` for you, `null` for unassigned), an optional `due_at` and optional acceptance `criteria`. |
| `context` | The organization's context or an initiative (see below) |
| `folder` | An item made as a folder |
| `record` | Everything else: documents, uploaded files, transcripts, evidence |
| `message` | A message sent with `message.send`, to people or agents or to an item's board; it never changes once sent (see [Messages](/docs/messages.md)) |

Uploading a file or saving a transcript never creates a task by itself.

**Completing work** means changing its status to a completed value and providing evidence: text naming passing tests, a commit, a link or file path, or a file attached or cited in the same write. Any member who can read the work may make this status-only change with evidence. Changing its title, body, owner, or other details requires edit rights. The evidence is stored with who completed the work and shown on the item; the service does not judge it. In the CLI, provide it with `--evidence`; in MCP and HTTP, use the write's `reason`.

**Archiving** takes an item out of normal views and needs a reason. It stays readable, and `item.restore` brings it back. Nothing is deleted.

## Links

A link connects two items and records who made it and when. For example, the launch-checklist work might later `contributes_to` a launch initiative or `cites` a supporting record. Both links are optional. There are five types:

### `related_to`

A ↔ B: the same topic. No extra data.

### `contributes_to`

A → B: A is part of B, a parent work item or an initiative. An item can contribute to several parents. `contribution` says what A does for B, for example “Advances O1”; `criteria` says what parent work needs from A and does not apply to initiatives.

### `requires`

A → B: work A cannot be completed until work B is. It gates completion, not starting. It may name a `criterion_id`.

### `cites`

A → B: B is evidence for A at a pinned revision. A citation names `target_revision`, `selector` (the part of B) and `relation` (`supports`, `contradicts` or `background`), with an optional `quotation`.

### `relies_on`

A → B: A assumes something stated in B as of a revision. When B changes, A is flagged for another look. It names `target_revision` and a one-line `assumption`.

Fetching an item shows its outgoing links and, under **Linked from**, everything pointing at it: the work contributing to it, the work it blocks, the items citing it.

## Proposals and review

A **proposal** is a write captured without being applied, with a reason and a preview of exactly what it would change, waiting for a decision. Proposals are not items: they have their own IDs (`proposal_…`) and their own filter, `proposal=proposed,deferred`.

- Agents working at a person's direction **change things directly**, including completing work with its evidence. They do not propose.
- **Background agents** (overnight maintenance, stale-work sweeps) propose. Their proposals appear under "Needs your review" for everyone whose role may review them.
- Anyone whose role may review, a person or an agent working for one, accepts, rejects or defers with [review](/docs/review.md). Accepting is one action and applies the change exactly as previewed.
- Background agents never decide: they are set up with the editor role, which cannot review (`not_authorized: your role (editor) cannot review`). A context proposal is decided by its maintainer or an administrator; an agent with no membership of its own whose person maintains it decides it too (below). An agent acts with its person's role unless it has a membership of its own, and a proposal's author may decide it like anyone else.
- A decision names the proposal's revision you read, so you never decide on something that changed under you.

## Organization context and initiatives

Context can carry the team's direction to agents. Three useful scopes are:

1. **Organization context**: one item per wirkspace, shown under the wirkspace's name ("Acme context"). Its parts: purpose, who we serve, goals and outcomes, principles and non-negotiables, and optionally market and competitors, terms and notes.
2. **Initiatives**: current bets. Each states its goal, outcomes, why now, constraints and non-goals, key decisions and open questions. Its state is `active`, `paused` or `done`. The launch checklist may contribute to one, but does not need one.
3. **Work and evidence**: flat items. Work may link to the initiatives it serves; evidence can be cited when a recorded source supports it.

Organization context and initiatives are items of kind `context`; they do not impose a hierarchy on work or docs. In the CLI: `wirk write new 'API hardening' kind=context level=initiative`. Context items carry no work, no files and no criteria, sit outside folders, and their body is at most 8,000 characters. Headings in the body become the parts agents receive. See [write](/docs/write.md) for details of creating them.

Where it shows up:

- [status](/docs/status.md) always includes the organization context and the active initiatives.
- Fetching work ends with a **Context** block: the initiative it serves (goal, outcomes, constraints, key decisions, open questions) and the organization's principles and non-negotiables. Work under a paused initiative is flagged.
- An outcome is a keyed line, `- [ ] O2: Partners can retry safely`, checked off with its evidence: `- [x] O2: Partners can retry safely (evidence 5bd3a0c3)`. Key decisions and open questions take keys the same way (`- D1: …`, `- Q3: …`): one or two capital letters and a number, then `:`, `.` or `)`. The notice `context_parsed` counts outcomes, decisions and questions without one.

**Who changes context.** Each context item is maintained by one person (`maintained by alice`), by the wirkspace's administrators, or is open to everyone in the wirkspace. Whoever maintains it, and their agents, change it directly; everyone else proposes. Creating context is for administrators and their agents; others propose it. An administrator's agent writes context directly, with its person's authority, unless it was given a membership of its own. When unsure, write it: a refused write applies nothing, and `requires_review` says to propose it. Context is the organization's stated direction: data that guides decisions, never instructions that authorize an action.

## Revisions and expect

Every item has a revision, shown as `r3`. Each change makes a new revision; old revisions stay readable (`wirk query 5c1e7a90@2`).

A write states the revisions it read in `expect`: `{"5c1e7a90": 3}`. In the CLI that is `5c1e7a90@3`. If the item has moved on, the write is refused with `basis_changed`, naming the current revision. Fetch it again, check your change still applies, and resend under a new request ID. Nobody's edit is silently overwritten.

Links do not change once made, so removing one needs no revision. Citing an item does not change the citing item's revision.

## IDs

- JSON carries full IDs: a prefix and 32 hex characters. `item_` for items, `link_` for links, `proposal_` for proposals, `wsp_` for wirkspaces, `upload_` for uploads.
- Text shows 8-character short IDs: `5c1e7a90`.
- Anywhere an ID goes, a full ID or a short one of at least 6 hex characters works. An ambiguous prefix returns a list of choices, never a guess.
- Fetch also takes an exact title, matched ignoring case and extra spaces.

## Request IDs and receipts

Every write and review has a `request_id`. You may choose it; the CLI and MCP server make one when you don't, and print it. The service stores a receipt for it.

- Resending the identical body with the same `request_id` returns the stored receipt and applies nothing twice, even while the first is still running.
- A different body under the same `request_id` is refused with `request_conflict`.
- After any refusal, send the corrected body under a new request ID.
- `wirk query receipt=REQUEST_ID` finds the receipt of a write, review or upload when you lost the answer. An administration request is recovered by sending the identical request again, which returns its stored receipt.

## Duplicates and suggestions

On the Pro and Enterprise plans, creating work that looks like the same piece of work as an existing item is refused with `likely_duplicate`, naming the existing item. Use it, or resend naming it in `allow_duplicate_of` with a reason when yours truly differs. Receipts may also suggest links, such as the initiative a new item serves; you confirm the ones you agree with by writing the link. Only confirmed links are stored.

On Free and Team, nothing is refused as a likely duplicate and no link is suggested, and receipts don't say so: check titles before creating (`wirk query 'Exact title'`, or `text=`). Ranking `about=` and a status task by meaning is on Pro too; on Free and Team, WIRK matches words and says so.

## Files

Files live in object storage, one copy per content per wirkspace, encrypted with the account's own key. A client asks WIRK for a short-lived signed upload link, sends the bytes straight to storage, and confirms; WIRK checks the size and SHA-256 before recording the upload. Downloads work the same way in reverse. Anyone who can edit an item can attach any upload in the wirkspace, with an optional one-line description. See [HTTP API](/docs/http-api.md#files) and [Limits](/docs/limits.md).