Skip to main content

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 Reference

WorkGraph is an optional realm-scoped subsystem. Agents mutate it through tools. Host RPC, REST, and CLI expose read-only observability/operator lookup.

​
WorkItem

FieldTypeDescription
idWorkItemIdUnique work item id
realm_idstringRealm that owns the item
namespaceWorkNamespaceNamespace within the realm, default default
titlestringShort title
descriptionstring?Optional detail
statusWorkStatusLifecycle status
priority`lowmediumhigh`Priority
labelsstring[]Filtering and grouping labels
ownerWorkOwner?Intended owner or assignee
claimWorkClaim?Active claim owner and optional lease
machine_stateobjectGenerated WorkGraph lifecycle machine state
revisionu64CAS revision for write tools
due_atRFC3339 timestamp?Due time
not_beforeRFC3339 timestamp?Earliest eligibility time
snoozed_untilRFC3339 timestamp?Snooze gate
created_atRFC3339 timestampCreation time
updated_atRFC3339 timestampLast update time
terminal_atRFC3339 timestamp?Terminal time
external_refsExternalWorkRef[]Typed pointers to external objects
evidence_refsWorkEvidenceRef[]Typed evidence pointers

​
Statuses

StatusMeaning
openCreated and not currently claimed
in_progressClaimed or actively being worked
blockedNot ready because a block exists or machine state is blocked
completedTerminal success
cancelledTerminal cancellation
failedTerminal failure
Terminal items cannot be claimed.

​
Edge Kinds

KindMeaning
blocksSource must resolve before target can be ready
parentHierarchical grouping
relatedNon-blocking association
supersedesSource replaces target
derived_fromSource was derived from target
WorkGraph rejects invalid endpoints, self edges, duplicate edges, and cycles for blocks and parent.

​
Owners And Claims

WorkOwnerKey.kind is one of:
  • principal
  • agent
  • session
  • mob
  • label
Claims are revision-based. Mutating tools require the current expected_revision. Optional leases allow abandoned work to become recoverable through machine- approved transitions.

​
Evidence Refs

WorkEvidenceRef contains:
FieldTypeDescription
kindstringEvidence type, such as artifact, pr, log, summary, or notification
idstringExternal or Meerkat-owned artifact id
labelstring?Human label
summarystring?Short explanation
Evidence refs are pointers. WorkGraph does not own the artifact content.

​
Agent Tools

ToolPurpose
workgraph_createCreate a work item
workgraph_getRead one item
workgraph_listList items
workgraph_readyList machine-derived ready items
workgraph_snapshotRead items, edges, ready ids, scope, timestamp, and event high-water mark
workgraph_eventsRead event history
workgraph_claimClaim an item with CAS revision
workgraph_releaseRelease an active claim
workgraph_updateUpdate mutable item fields
workgraph_blockPut an item into blocked state
workgraph_closeClose as completed, cancelled, or failed
workgraph_linkAdd a graph edge
workgraph_add_evidenceAdd an evidence reference

​
Read-Only RPC

MethodPurpose
workgraph/getRead one item
workgraph/listList items
workgraph/readyList ready items
workgraph/snapshotRead graph snapshot
workgraph/eventsRead event history
Mutating WorkGraph RPC methods are intentionally absent in v1.

​
Read-Only REST

MethodPathPurpose
GET/workgraph/itemsList items
GET/workgraph/items/{id}Read one item
GET/workgraph/readyList ready items
GET/workgraph/snapshotRead graph snapshot
GET/workgraph/eventsRead event history
Common query parameters: realm_id, namespace, all_namespaces, statuses, labels, include_terminal, limit, and after_seq for events.

​
Read-Only CLI

rkat workgraph list [--namespace <NS>] [--all-namespaces] [--status <STATUS>] [--label <LABEL>] [--include-terminal] [--limit <N>] [--json]
rkat workgraph show <ID> [--namespace <NS>] [--json]
rkat workgraph ready [--namespace <NS>] [--label <LABEL>] [--limit <N>] [--json]
rkat workgraph snapshot [--namespace <NS>] [--all-namespaces] [--status <STATUS>] [--label <LABEL>] [--include-terminal] [--limit <N>] [--json]
rkat workgraph events [--namespace <NS>] [--all-namespaces] [--after-seq <N>] [--limit <N>] [--json]
CLI commands use the same realm flags as other rkat commands.

​
Companion Skill

workgraph-workflow is an embedded builtin companion skill gated by the work_graph capability. It teaches agents how to use the WorkGraph tool family. It is discoverable through the normal skills inventory and is not automatically preloaded.