> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkGraph

> Use WorkGraph tools to create, link, claim, evidence, close, and observe durable work.

# WorkGraph

Use this guide when an agent should coordinate durable work across sessions,
compaction, restarts, schedules, or multiple agents.

<Note>
  Agents write general WorkGraph items through tools. RPC and REST are public
  observability surfaces; the CLI also has narrow session-goal and attention
  controls for trusted local operators.
</Note>

## Create Work

Use `workgraph_create` for a durable commitment.

```json theme={null}
{
  "title": "Prepare dentist transport reminder",
  "description": "Create a reminder for L to explain to A that car P is in the workshop.",
  "namespace": "homecare",
  "priority": "high",
  "labels": ["family-logistics", "autism-support"],
  "due_at": "2026-05-19T08:00:00Z",
  "external_refs": [
    {
      "kind": "calendar_event",
      "id": "dentist-a-2026-05-20"
    }
  ]
}
```

## Link Dependencies

Use `workgraph_link` to describe relationships.

```json theme={null}
{
  "kind": "blocks",
  "from_id": "work_check_car_status",
  "to_id": "work_prepare_dentist_reminder",
  "namespace": "homecare"
}
```

For `blocks`, the target is not ready until the blocker is terminally resolved.
Use `related`, `parent`, `supersedes`, or `derived_from` when readiness should
not be blocked.

## Find Ready Work

Use `workgraph_ready` instead of inferring readiness.

```json theme={null}
{
  "namespace": "homecare",
  "labels": ["family-logistics"],
  "limit": 10
}
```

Ready work is non-terminal, not blocked, due or eligible, and claimable.

## Claim Before Shared Work

Use `workgraph_claim` before doing durable work. Include the current
`expected_revision`.

```json theme={null}
{
  "id": "work_prepare_dentist_reminder",
  "namespace": "homecare",
  "expected_revision": 3,
  "owner": {
    "key": { "kind": "agent", "id": "homecore/logistics-agent" },
    "display_name": "Homecore logistics agent"
  },
  "lease_seconds": 1800
}
```

If a write returns a stale revision error, reload with `workgraph_get` or
`workgraph_snapshot`, then decide whether the action still makes sense.

## Update And Add Evidence

Use `workgraph_update` for title, description, priority, labels, due gates, and
external references. Use `workgraph_add_evidence` for proof of progress or
completion.

```json theme={null}
{
  "id": "work_prepare_dentist_reminder",
  "namespace": "homecare",
  "expected_revision": 4,
  "evidence": {
    "kind": "notification",
    "id": "sms-draft-l-2026-05-19",
    "label": "Reminder prepared",
    "summary": "Reminder explains that car P is unavailable and names the replacement car."
  }
}
```

Evidence refs point to external or Meerkat-owned artifacts. WorkGraph stores the
reference, not the artifact bytes.

## Close Or Release

Use `workgraph_close` only when terminal truth exists.

```json theme={null}
{
  "id": "work_prepare_dentist_reminder",
  "namespace": "homecare",
  "expected_revision": 5,
  "status": "completed"
}
```

Use `workgraph_release` if you stop before terminal completion and another
agent should be able to claim the item.

## Observe From Host Surfaces

Operators and UIs can inspect WorkGraph without broad graph mutation:

* CLI: `rkat workgraph list`, `show`, `ready`, `snapshot`, `events`; plus
  narrow `goal-*` and `attention-*` controls for session-bound goals
* REST: `GET /workgraph/items`, `/workgraph/ready`, `/workgraph/snapshot`,
  `/workgraph/events`, plus public `POST /workgraph/goal/status` and
  `/workgraph/attention/list` observability routes
* RPC: `workgraph/get`, `workgraph/list`, `workgraph/ready`,
  `workgraph/snapshot`, `workgraph/events`, plus public
  `workgraph/goal/status` and `workgraph/attention/list` observability methods

Goal and attention mutation APIs are trusted in-process host/runtime authority.
The CLI exposes only the local session-first subset it can complete safely;
public REST and JSON-RPC keep these as observability-only.

## Agent Instruction Manual

When skills are enabled and WorkGraph capability is available, agents can load
the `workgraph-workflow` companion skill for operating guidance.