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

# Tool sets

> Every code-shipped tool set in the Forge registry — composition, consumers, and notes.

Last updated 2026-11-11

·
applies to 2026-10-21

·
main

Code-shipped tool sets ship with the platform, each annotated with governance metadata. Each row in the table is one code-shipped tool set. Database-defined tool sets (Google Workspace, external HTTP integrations, MCP plugins) live in the `toolSets` table and are not enumerated here — see `/platform/tools` in the Forge Console for the live catalog.

For the conceptual frame — register, audit, publish, invoke — see [Tool Registry](https://docs.gloo.com/forge/concepts/tool-registry.md).

***

## Code tool sets

| Tool set | Composition | Used by | Notes |
| - | - | - | - |
| `platformQuery` | `queryOrgChart`, `queryPeople`, `queryAgents`, `queryAnalytics`, `querySkills`, `queryTools`, `queryBudgets`, `queryAgentTemplates`, `spawnTaskAgent`, `requestConsultation`, `checkDelegatedWork`, `cancelDelegatedWork` | Workflow Architect, Skill Builder, Agent Builder, Forge Analyst, Dashboard Architect | Universal baseline for read-only platform inspection. Includes task-delegation tools so any agent can spawn / consult / check work — the Trust Fabric `policyRules` gate (15th in the engine sequence) carries per-agent prohibition rules. |
| `customerDirectory` | `searchCustomers` | Agents explicitly granted this set | Read-only, bounded search of active organization Customers using Forge IDs, names, websites, or email domains as evidence. Tool governance requires `customers:read`; results are candidates for resolution, not authorization. |
| `factoryManagement` | *(none)* | Factory Manager, Foreman | Retired: grants no tools. The set name stays registered because stored agent definitions, skills, and workflow nodes name it. |
| `factoryChat` | *(none)* | Factory Manager, Comms Bug Fixer | Retired: grants no tools. The set name stays registered because stored agent definitions, skills, and workflow nodes name it. The chat dispatch path posts the agent's reply to the channel. |
| `factoryDispatch` | `dispatchCodingTask`, `createBranch`, `openPr`, `checkPr` | Factory Manager | GitHub branch + PR operations and Worker dispatch. Bridges manager-level intent into worker-level execution. |
| `factoryWorker` | *(none)* | Factory Worker (legacy) | Retired: grants no tools. The set name stays registered because stored agent definitions, skills, and workflow nodes name it. Workers use `sandbox_action`, bound at dispatch. |
| `graphAuthoring` | `createWorkflowDefinition`, `updateDefinition`, `createNode`, `createNodes`, `createEdge`, `createEdges`, `updateNode`, `updateNodes`, `updateEdge`, `updateEdges`, `deleteNode`, `deleteNodes`, `deleteEdge`, `deleteEdges`, `clearDraftGraph`, `validateGraph`, `walkDag`, `listAgentDefinitions`, `getExampleGraphs`, `getCurrentGraph`, `createSchemaComponent`, `defineSchemaProperty`, `defineSchemaProperties`, `listSchemaComponents` | Workflow Architect | Read-write graph authoring — node + edge CRUD, schema component composition, validation. Excludes the publish step. |
| `graphAuthoringPublish` | `publishWorkflow` | Workflow Architect | Single-tool set so the publish step can be granted independently of authoring rights. |
| `skillAuthoring` | `getSkill`, `listSkills`, `updateSkillContent`, `updateSkillMetadata`, `validateSkillDraft`, `requestInlineSkillReview`, `finalizeSkillDraft` | Skill Builder | Skill draft authoring + automated review request flow. |
| `agentAuthoring` | `getAgent`, `listAgents`, `listAvailableSkills`, `listAvailableToolSets`, `updatePrompt`, `updateAgentMetadata`, `updateCapabilities`, `validateAgentDraft`, `finalizeAgentDraft` | Agent Builder | Agent draft authoring — prompt, metadata, capability composition, validation, finalization. |
| `codeAnalysis` | *(none — retired)* | Factory Worker, Copilot Analysis (legacy grants) | Retired. Its codebase-search tools called a Convex module that no longer exists and were removed. The name stays registered with no members so existing agents, skills, and workflow nodes that name it still validate. Granting it adds no tools. |
| `fileValidation` | `checkFileIntegrity`, `validateCsv`, `validateJson` | Forge Analyst | Validator-agent infrastructure — file integrity + format checks. |
| `general` | `network_fetch`, `network_request`, `notification_send`, `getDatetime`, plus deprecated `webFetch` / `httpRequest` aliases | Workflow Architect, Skill Builder, Agent Builder, Forge Analyst, Copilot Analysis, Personal Agent, Compliance Agent | General-purpose I/O tools. File I/O is dispatch-injected as `file_get` / `file_put`, not granted by this set. |
| `taskManager` | `listSoftwareTasks`, `getSoftwareTask`, `createSoftwareTask`, `assignSoftwareTask`, `transitionSoftwareTask` | Task Manager | M6-renamed software-task surface. Bare verb forms (`createTask`, etc.) live in `factoryManagement` to avoid import collisions. |
| `runAnalysis` | `getRunContext`, `getStepResults`, `getStructuralTimeline`, `getStepDetail`, `getCostBreakdown` | Copilot Analysis, Compliance Agent | Read-only run inspection — context, step traces, structural timelines, cost breakdown. Copilot uses this to review completed runs; Compliance uses it for audit synthesis. |
| `forgeAnalyst` | `queryWorkflowRun`, `queryStepResults`, `fetchFileContent` | Forge Analyst | Workflow run + step result querying with file fetch — narrower than `runAnalysis`, scoped to the analyst's structured-output reporting flow. |
| `dashboard` | `listUserDashboards`, `listAvailableDataSources`, `createDashboard`, `createWidget`, `updateWidgetConfig`, `addWidgetToDashboard`, `getDashboardState`, `removeWidgetFromDashboard`, `updateDashboardLayout` | Dashboard Architect, Personal Agent | Dashboard authoring. Architect-only members (`getDashboardState`, `removeWidgetFromDashboard`, `updateDashboardLayout`) carry `accessTier: "architect"` in `TOOL_META` and are filtered out at composition time when the caller is not in `ARCHITECT_AGENT_IDS`. |

The registry changes as platform agents gain or retire capabilities. `TOOL_SETS` and `TOOL_SET_MEMBERS` are the source of truth; the Console's **Platform → Tools** page is the live operator catalog. Dispatch-injected tools are deliberately absent from both static and workspace sets.

***

## Database-defined tool sets

The following families are declared in `TOOL_SET_MEMBERS` (for governance metadata) but their tools are seeded as rows in `toolDefinitions` with a runtime type of `http_api`, `mcp_remote`, or `mcp_convex`. They appear on `/platform/tools` once the corresponding seeder runs.

| Tool set | Members | Notes |
| - | - | - |
| `googleDriveRead` | `driveList`, `driveGet` | Google Workspace, split per service into read and write. Bound to the agent at each dispatch. |
| `googleDriveWrite` | `driveUpload`, `driveShare` | Same. |
| `googleGmailRead` | `gmailListMessages`, `gmailGetMessage` | Same. |
| `googleGmailSend` | `gmailSendMessage` | Send-only — separated from read so an agent may have inbox visibility without send rights. |
| `googleDocsRead` | `docsGet` | Same. |
| `googleDocsWrite` | `docsCreate` | Same. |
| `googleSheetsRead` | `sheetsGetValues` | Same. |
| `googleSheetsWrite` | `sheetsUpdateValues` | Same. |
| `googleSlidesRead` | `slidesGet` | Same. |
| `googleSlidesWrite` | `slidesCreate` | Same. |
| `googleCalendarRead` | `calendarListEvents` | Same. |
| `googleCalendarWrite` | `calendarCreateEvent` | Same. |

Twelve Google Workspace splits, plus per-vendor MCP and HTTP integrations seeded from vendor manifests. The full live catalog — code-shipped + DB-defined + factory-bound — is the operator surface at [Platform → Tools](https://docs.gloo.com/forge/console/platform/tools).

***

## Factory-bound tools

These tools have `boundAtDispatch: true` in `TOOL_META`. They are constructed per-dispatch by a factory function (so their Zod input schema lives on the factory output, not on a static singleton) and surfaced in the catalog with a "Bound at dispatch" indicator.

| Tool | Bound by | Purpose |
| - | - | - |
| `sandbox_action` | Workflow produce execution and other sandbox-capable dispatch sites | Sandbox operations bound to the dispatch's `SandboxBinding` and `ExecutorContext`; the active sandbox capability selects the provider. |
| `load_skill` | Agent composition (when on-demand skills are active) | Loads the full content of a single skill the agent referenced from its menu. |
| `file_put` | Dispatch sites with an authorized writable file binding | Persists inline, rendered, uploaded, or sandbox-produced bytes and creates the permitted binding. Returns a `fileId`. `putFile` is a deprecated alias during migration. |
| `file_get` | Dispatch sites with authorized readable file IDs | Reads metadata or text, or copies an authorized file into the active sandbox. `getFile` is a deprecated alias during migration. |
| `knowledge_search` | Workflow node, chat, Factory Manager and Workflow Architect dispatch | Searches the knowledge the agent may read and records each hit it returns. |
| `knowledge_list` | Workflow node, chat, Factory Manager and Workflow Architect dispatch | Lists every synchronized record of the given kinds the agent may read, complete or refused. See [below](#knowledge_list-and-knowledge_get). |
| `knowledge_get` | Workflow node, chat, Factory Manager and Workflow Architect dispatch | Gets one case or synchronized record the agent may read. See [below](#knowledge_list-and-knowledge_get). |
| `knowledge_record` | Workflow node, chat and Factory Manager dispatch | Records a keyed, provisional case in the knowledge base. See [below](#knowledge_record). |
| `knowledge_report_outcome` | Workflow node dispatch | Reports a run's outcome as evidence for the cases it cited. See [below](#knowledge_report_outcome). |

This table is the complete set of dispatch-injected tools; `getFile` and `putFile` remain as deprecated aliases of `file_get` and `file_put`. Agent authors do not add any of these names to a tool set; the dispatch context decides whether a concrete, bound tool is available.

### `knowledge_search`

Every workflow node agent, chat agent, Factory Manager and the Workflow Architect receives `knowledge_search`. No tool set has to grant it; it is a dispatch-injected tool. The Workflow Architect searches `global`, `company`, its draft's channel and its own `agent:workflow-author` knowledge, and can still call it while a plan proposal waits for confirmation. Its hits carry no citation ref.

| Input | Type | Notes |
| - | - | - |
| `query` | string, 1–500 characters | What to look for. |
| `limit` | integer, 1–20, optional | Most hits to return. Default 8. |
| `scopes` | 1–8 `{ scopeType, scopeEntityId? }`, optional | Search only these scopes, each of which must be one the agent may read. |

Without `scopes`, Forge resolves the scopes from where the agent runs: `global`, `company`, the agent's own `agent:` and `team:` namespaces, and the factory, project and channel of the run or session. The search goes through the `knowledge` capability. Fresh search reads the synchronized Knowledge store only.

The tool returns `{ found: true, hits }`. Each hit carries `entryId`, `namespace`, `score`, `contentType`, `grade` and `text`, best first, and `similarity` (the cosine) when vector search found it. A hit with `revisionOf` is a pending revision: a proposed rewrite of the proven case that `revisionOf` names, which has not yet earned trust. Both are returned; the proven case ranks first at its higher grade weight. `score` is the rank score in (0, 1] from fusing vector and text search across every searched scope. `text` is cut to 1,000 characters.

Only hits that clear a relevance floor are returned. A native hit needs a `similarity` of at least 0.2, the same floor as the Knowledge API's [ask](https://docs.gloo.com/forge/reference/http-api/knowledge/ask.md); a native hit only text search found has no `similarity` and is not returned. The floor is applied before the `limit` cut, so a weak hit never takes a relevant one's place. 0.2 is an interim value that has not yet been measured against production data.

When no hit clears the floor, or the agent has no readable scope, the tool returns `{ found: false, reason: "no_results", message: "No relevant knowledge found for this query." }` and no weak matches. The tool's description tells the agent to say it doesn't know, or to ask for what it needs, and never to guess. Nothing is recorded in `contextManifests` for such a search.

When one of the requested `scopes` is not one the agent may read, the tool searches nothing and returns `{ found: false, reason: "permission_denied", refusedScope, message }`. `refusedScope` is that scope exactly as the agent sent it. The result is the same whether the scope does not exist or the agent may not read it, so it never shows which. A workflow step records the refusal in `contextManifests` as `permission_denied`.

When the agent answers a person, it reads only what that person can read.
That covers a chat reply, a personal agent, a Factory Manager reply to a person's message and a Workflow
Architect builder turn. A workflow step keeps the agent's own access, whoever started the run.

The `knowledge.agentOnBehalfNarrowing` platform setting decides how this applies. An operator sets it with
`platformSettings.set`.

| Mode | Effect |
| - | - |
| `shadow` (the default) | Searches as the agent and records how many hits `enforce` would have left out. |
| `enforce` | Searches only the agent's scopes that the person also reads, and only rows homed inside the person's `knowledge:read` scope. Typed `scopes` are narrowed the same way. |
| `off` | Changes nothing. |

When the person can't be identified, or has no access to shared knowledge, an enforced search reads nothing
and returns `{ found: false, reason: "not_readable_for_person", message }`, and the agent tells them it can't
look that up. Each such chat search writes one `contextManifests` row with `kind: "retrieval"` and a
`narrowing` field: the mode, the shadow count (`droppedCount`) and, when it read nothing, why
(`failedClosed`). No subject or content is recorded. In the Console, a chat turn's inspector lists each such
search under **Knowledge access**, by the person's name: **Measuring** with the shadow count, or **Limited**. `knowledge_list` and `knowledge_get` read through the
same narrowing. A record list also needs the person to hold `knowledge:read` at the record's source or
collection home, as Knowledge in the Console does.

`grade` says how far to trust a case:

| `grade` | Meaning |
| - | - |
| `proven` | The case has worked in past runs, or an operator approved it. |
| `provisional` | The case is new and untested. Every recorded case starts here. |
| `contested` | The case was judged to have failed, or someone disputed it. |
| `ungraded` | The hit is not a case: a document, an upload or a note. |

A `retired` case is never returned. An operator who holds `knowledge:manage` and can read the case's namespace sets any grade with the `knowledge.setCaseGrade` mutation, which logs the change on the case and writes a `knowledge_entry` audit event (`knowledge_entry_grade_changed`). Hits are ordered by the fused `score` × the grade's weight, so a proven case ranks above an equally relevant provisional one. The weights are the `knowledge.gradeRankWeights` platform setting: `proven` 1.0, `provisional` 0.8, `ungraded` 0.8, `contested` 0.4 unless an admin changes them with `platformSettings.set`. A stored value that is missing or breaks the order `proven` ≥ `provisional` ≥ `contested` > 0 falls back to these defaults. `score` is still the unweighted fused score.

Because a weight can lift a hit above ones with a higher fused score, Forge ranks a candidate window of three times `limit`. It doubles the window until no hit ranked below the window in the same search could outrank the last one returned. The window stops at 256 candidates. If the order is still not settled there, the result also carries `truncated: true`. The fused score depends on how deep the search reads, so the order is exact for the window the search stopped at. A hit outside that window in both the vector and the text search could rank higher in a deeper search, and this search does not read deeper to check.

Each hit writes one `contextManifests` row with `kind: "case"`, the `entryId`, the namespace and the score. Historical external references remain access-checked and show No longer available without querying their source. A workflow step's rows carry its run and node ids, and a chat turn's rows carry its session and turn ids. These rows record what each step or turn retrieved. They are deleted after 180 days, the same window as `stepResults`.

Each native hit also carries a `ref`, such as `k9jzjrs72`: `k` and eight characters derived from the case's `entryId`. A case has the same ref in every search and every turn, so a ref an earlier turn left in the conversation still names the same case. The tool asks the agent to cite a result its answer relies on inline, as `[ref:k9jzjrs72]`. The chat renders the tag as a citation link.

After the turn, Forge reads the refs cited in the agent's answer. For a node with a structured output, that is the reply before the structured output and the output itself. Each cited hit's `contextManifests` row is set to `cited: true`. Each cited case that is still active also gets one `knowledgeUses` row: the durable record that the case was used. A case gets one use per workflow run, credited to the first node that cited it, or one per chat turn. A cited ref counts only when it matches a case retrieved in the same workflow run or chat session. The ref may come from an earlier turn of that session. A turn-2 use of a case retrieved in turn 1 is credited to turn 2. A ref that matches no retrieved case is ignored, and so is a ref that two retrieved cases share. A case that is retrieved but not cited gets no use. `knowledgeUses` rows are not deleted by retention.

### `knowledge_list` and `knowledge_get`

Every agent that receives `knowledge_search` also receives `knowledge_list` and `knowledge_get`. Both
need `knowledge:read` and are dispatch-injected tools. They read through Forge's core
Knowledge read service as the agent, in the scopes `knowledge_search` reads without `scopes`. Inside
a workflow step, each read is recorded with the run, and a complete result is replayed to the same
request later in the run.

| Tool | Input | Result |
| - | - | - |
| `knowledge_list` | `kinds` (1–8 kinds of one provider), `sourceId` and `filter`, both optional | `status: "complete"` with `records`, `count`, `digest` and `sources`, or a refusal with a `reason`. |
| `knowledge_get` | `entryId`, or `sourceId`, `kind` and `externalId` together | The item with a `status` of `current`, `quarantined` or `stale`, or `not_found` / `permission_denied`. |

A list is never partial. A kind that is incomplete or stale, or that a source has not verified, is
refused rather than returned in part. A complete list too large for the agent's context comes back as
`too_large` with its count and digest.

### `knowledge_record`

Every workflow node agent, chat agent and Factory Manager gets `knowledge_record`. It stores something the agent learned as a **case**: a knowledge entry with `contentType: "case"` that other agents can find later.

| Input | Type | Notes |
| - | - | - |
| `key` | string, 1–200 chars, optional | A stable name for the case. Recording the same key again with new text **replaces** the case: there is still one entry, with the new text, and the old text is kept as a version. A rewrite of a `proven` case is held as a [pending revision](#pending-revisions) instead. Recording the same title and text again changes nothing. Omit it and the key is `sha256:` plus a hash of the title and content. |
| `title` | string, 1–200 chars | Short title. |
| `content` | string, 1–20,000 chars | The case itself, in markdown. |
| `scope` | `home` \| `factory` \| `project` \| `team`, optional | Where the case goes. Defaults to `home`: the run's project, else the run's factory, else the agent's team, else the agent itself. `factory` and `project` are the run's; `team` is the agent's org unit. |
| `kind` | `lesson` \| `policy` \| `how_to` \| `reference` \| `faq` \| `note`, optional | What the case is for. It is stored as the case's artifact kind, the same field a person sets in the Console's New artifact form, and is shown and filterable there. It doesn't change search or retrieval. A new kind applies at once, except on a rewrite of a `proven` case's text, where it waits on the [pending revision](#pending-revisions) until that is promoted. Omit it to leave a new case unclassified, or to keep an existing case's kind on a rewrite. |

The target must be a namespace the agent can read, and agents never write to `company` or `global`. A scope the agent has nothing for (for example `factory` outside a workflow run) is refused before anything is written.

Every case records the run, node and agent that wrote it, and starts with grade `provisional`. An agent's rewrite of a `proven` case does not replace it (see [pending revisions](#pending-revisions)). Any other replacement sets the case back to `provisional`, with its success and failure counts and its evidence cleared, except a `retired` case: it stays retired, and only an operator can restore it. Replacing also closes the case's pending review items (approval, contest, conflict), since they were about the old text. Each create writes a `knowledge_entry_created` audit event and each replace a `knowledge_entry_replaced` one (with `versionFrom` and `versionTo`), in the same transaction as the case. The tool returns `{ knowledgeEntryId, caseKey, namespace, replaced }`, plus `revisionOf` when the write was held as a pending revision, and `superseded: true` when nothing was stored (a newer write of the key landed first, or a person's edit of the case is waiting for review), or `{ error }` when it refuses.

A case keeps its history. Each replacement stores the old version (its text, grade, counts, evidence and the run that wrote it) in `knowledgeEntryVersions`, and the case keeps its entry id, so earlier uses still point at it. `knowledge.caseHistory.listCaseVersions` (`knowledge:read`) returns the 20 newest versions of a case in a namespace the caller can read. Deleting a case also clears the text of every version.

Every write is checked against the version of the key it read when it started, and a delete counts as a version. If the case is deleted after that read, the write is dropped and nothing is stored, so a deleted case never comes back from a write that started before the delete. A write that starts after the delete records a new case under the key. The call then fails with the message "the case was deleted while this write was in progress; nothing was stored". It returns no entry id, and the call's tool audit row is marked `failed` (`tool_error`).

#### Pending revisions

When an agent rewrites a `proven` case, or a case that already has a pending revision, the proven text keeps serving. The new text is stored as a **pending revision**: a second entry with no key of its own, whose `revisionOf` names the proven case. It starts `provisional` with its own entry id, so it is searched, cited and graded on its own. `knowledge_record` returns the revision's id with `revisionOf` set and `replaced: false`. Another agent rewrite replaces the pending revision's text, and the text it replaced is kept as a version with `disposition: "superseded"`. The same text again changes nothing. A case has at most one pending revision. While that revision is a person's edit made in the Console, which waits for a person's approval, an agent's rewrite stores nothing and returns `superseded: true`.

* **Promotion.** When the revision becomes `proven`, the proven case takes its text, version, counts and evidence, and the old text is kept as a version. A revision becomes `proven` through its own successes, or through a person's approval in a `company` or `global` scope. The revision entry is then deleted.
* **Discard.** A rewrite of the case by a person or by the system, or a person retiring the revision or the case, discards the revision. So does deleting the case. The revision's text is kept as a version with `disposition: "discarded"` until the case itself is deleted.
* **Conflicts.** Each revision is checked against the proven case by the `judge-knowledge-conflict` judge. If following one text would contradict the other, a `conflict` item names the proven case in the steward queue, and when the judge is confident the revision (never the proven case) also becomes `contested`. A contested revision stays until a person decides. If the judge is not available, the check is skipped.

`knowledge.caseHistory.getCaseRevision` (`knowledge:read`) returns a case's pending revision, or `null`, to a caller who can read the case's namespace. The Console cases list does not show revisions.

A version number is never reused: a pending or discarded revision counts toward the key's version.

### `knowledge_report_outcome`

Every workflow node agent gets `knowledge_report_outcome`. Chat agents and the Factory Manager do not, because an outcome needs a run. A step uses it to report how a run turned out: a close that tied out is a `success`, a reopened ticket is a `failure`.

| Input | Type | Notes |
| - | - | - |
| `signal` | `success` \| `failure` | How the run turned out. |
| `note` | string, 1–500 chars | What happened. It is kept on the case's evidence. |
| `targetRunId` | string, optional | The run to report on. Defaults to the current run. Another run must share the current run's home scope: the same project, or, when the current run has no project, the same factory. Any other run is refused with `{ error }`. |

Only a production run reports, and only on a production run: a test (draft) run is refused with `{ error }`, so a draft never grades a case. The report applies to every case the target run has cited so far (its `knowledgeUses`). It returns `{ runId, usesUpdated, promoted, contested, queued, continued, memorySignals }`; `memorySignals` counts the long-term memories whose signal for the run was recorded or changed (see [How a memory becomes a case](#how-a-memory-becomes-a-case)).

#### How outcomes grade a case

Four sources send outcome signals for a run's cited cases:

| Source | Signal |
| - | - |
| `domain_signal` | A `knowledge_report_outcome` call. |
| `operator_rating` | An operator's rating of the run: 4–5 stars is a success, 1–2 a failure. 3 stars is no signal, and it withdraws an earlier rating's signal. When several attempts are rated, the latest rating counts. |
| `judge` | The outcome Judge's verdict on a completed production run: `pass` is a success, `fail` a failure, `needs_work` no signal. |
| `system` | A failed production run is a failure. It counts against the run's cases but never contests them. |

A fifth source, `chat`, grades the cases an agent's chat answer cited. A person's 👍 on the answer counts +1 and a 👎 −1, in any skin tone. Above zero the answer is a success, below zero a failure, and at zero it gives no signal, which withdraws an earlier one. Other emoji and agents' reactions are not votes. On an answer that quotes source-restricted knowledge, only people allowed to read it count. The signal applies to the cases that answer's turn cited, and each case counts it once per answer however many people vote. So one answer weighs at most as much as one run's outcome. A chat turn has no other source, so `chat` is not part of `knowledge.signalPrecedence`.

Each case counts at most one signal per run. When sources disagree, the first in the list above wins, so a workflow's domain outcome outranks an operator's rating, and the rating outranks the Judge. When a run's rating and its domain outcome give opposite signals, the case also goes to the steward queue as a `contested` item that names both, without changing its grade. Sending the same signal again changes nothing. A new signal that reverses an earlier one moves the case's counters back.

A `provisional` case becomes `proven` after 3 successes in a row since its last failure, grade change or rewrite. A `company` or `global` case is never promoted automatically: it goes to the steward queue for a person to approve. A failure makes a `provisional` or `proven` case `contested` and queues it for a steward, unless it comes from `system`. A failed run doesn't show which cited case was wrong, so it counts as a failure and ends the streak but never contests. A failure from another source on the same run, before or after the run failed, contests the case whenever it decides the run's signal under `knowledge.signalPrecedence`. A `contested` or `retired` case only gains evidence; a person decides its grade with `knowledge.setCaseGrade`, which also closes its queued items. Rewriting a case restarts its streak and closes a pending approval, because the new text has not earned `proven`. A test run's outcome grades nothing. Every automatic grade change writes a `knowledge_entry_grade_changed` audit event with the actor `system:knowledge-outcome`.

These are platform settings, changed with `platformSettings.set`:

| Setting | Default |
| - | - |
| `knowledge.provenThresholds` | 3 successes for every scope type, as `{ "<scopeType>": { "provenAfterSuccesses": 3 } }` |
| `knowledge.signalPrecedence` | `["domain_signal", "operator_rating", "judge", "system"]` |
| `knowledge.ratingSignal` | `{ "successAtOrAbove": 4, "failureAtOrBelow": 2 }` |
| `knowledge.failedRunSignal` | `true` |
| `knowledge.memoryPromotionRetrievalThreshold` | `5` retrievals |

A missing or invalid value falls back to its default.

#### How a memory becomes a case

An agent's long-term memory becomes a case only when both of these hold:

1. It has been retrieved at least `knowledge.memoryPromotionRetrievalThreshold` times.
2. A production run that recalled it succeeded. A workflow node's memory recall is recorded in the run's context manifest, and each outcome signal for that run is recorded for every memory it recalled, with the same sources and precedence as for cases.

Retrieval count alone never promotes a memory, and neither does a failure. A memory recalled only in chat has no run outcome, so it is not promoted automatically; a person can still promote it from the Console. A daily sweep promotes the memories that qualify.

The promoted case starts `provisional` and earns `proven` like any other case. It is keyed to its memory (`memory:<memoryId>`), so a memory becomes at most one case, and its text is redacted before it is stored. It lands in the memory's originating scope, where the memory was written, never the scope of the run that recalled it: that run only supplies the outcome. A Factory Manager's memory lands in its factory, and a memory stored in a project stays in that project. A memory a run wrote lands in the agent's home scope for that run: its project, else its factory, else the agent's team or the agent itself. Any other memory lands in the agent's home scope. A personal assistant's memory is the exception: it is promoted automatically only into its owner's personal scope, whatever project or run it was written in, and not at all when the owner has no worker. A memory whose agent no longer exists isn't promoted automatically either. A person can still promote a memory anywhere they're allowed. When the originating scope can't be determined, because the run that wrote the memory is gone or was never recorded, the memory is never promoted. Every promotion writes a `knowledge_entry_created` audit event naming the memory and its tier, never its text. Forgetting the memory deletes a case promoted automatically; a case a person promoted stays.

#### Case curator

Every Monday at 03:00 UTC, the case curator sweeps the active cases, oldest first.

* **Identical cases are merged.** Two active cases in the same namespace with the same title and text are the same case. The curator finds them by the digest a keyed write stores, so it compares cases written by `knowledge_record` (every such case has a key); a case written before case versioning is compared once it is next rewritten. The curator keeps one: a `proven` case over a `provisional` one, then the one with more successes, then the older one. The kept case takes the other's success and failure counts and its evidence, and gets a `knowledge_entry_merged` audit event. The other case is deleted for real, like any deleted case: its text and its versions' text are cleared, and a write to its key that started before the merge is dropped. Its grade is not carried over, and no grade changes.
* **Some duplicates wait for a person.** A case a person wrote (an upload, a memory a person promoted, or a case a person recorded) is never deleted by the curator, and neither is a `contested` case. The curator queues each such copy for a steward as a `duplicate` review item that names the case it would keep. It withdraws the item once no identical case remains.
* **Unused cases are flagged, never retired.** A case is flagged when nobody has used or rewritten it for `knowledge.staleAfterDays` and no steward has answered a stale flag on it in that time. The curator queues it as a `stale` review item. The flag changes nothing on the case; only a steward retires one, with `knowledge.setCaseGrade`. The curator withdraws the flag once the case is used or rewritten again. Retiring a case closes its pending `stale` and `duplicate` items.

Uses and citations of a merged-away case keep pointing at its deleted entry, so a late outcome for a run that cited it grades nothing. Running the curator again changes nothing until the cases do.

| Setting | Default |
| - | - |
| `knowledge.staleAfterDays` | `180`: a whole number of days from 7 to 3650 |

### Durable blackboard notes

A blackboard is scratch state for one workflow run or chat session. It is archived when the run ends or the session closes, and the next run starts with an empty board. To keep a note past that point, the agent marks it `durable`:

| Tool | `durable` input | Effect |
| - | - | - |
| `blackboard_write` | boolean, optional, default `false` | Marks every top-level key the call writes as durable. A full replace also un-marks keys it removes. |
| `blackboard_patch` | boolean, optional, default `false` | Marks every top-level key the patch sets as durable. Patching a key to `null` deletes it and un-marks it. |

A board keeps at most 25 durable notes. A write or patch that would leave more is refused, and the board is unchanged.

A durable note becomes a case in its agent's home scope, so the board's scope must include the agent. A write or patch with `durable: true` is refused, and the board is unchanged, when the scope has no `agentId` (for example, when a scope override sets `agentId` to `null`).

`blackboard_read` returns the board as before. When any key is durable, the result also has a `$durableKeys` field that lists those keys. `$durableKeys` is read-only: a write or patch that includes it ignores it.

When the run ends (on any terminal path, including cancel) or the session closes, each durable note still on the board is recorded as a case, the same way `knowledge_record` records one:

* The note's key is the title (up to 200 characters). Its value is the content: a string is used as-is, and any other value is stored as JSON with sorted keys.
* The case goes in the agent's home scope, with grade `provisional` and source `agent_record`. It records the run that wrote it, if there was a run. Its `knowledge_entry` audit event has `origin: "blackboard"` in its detail.
* The key is `sha256:` plus a hash of the full note key and the content, taken before the title is cut to 200 characters. The same note from later runs stays one case, and two notes whose keys differ only after 200 characters are two cases. If a live case already has that key, it is left as it is, grade included.
* The title and content are redacted before the limits below are checked and before the key is hashed.

A note whose content is over 20,000 characters, or empty, is skipped. A note that fails to record is logged, and the board's other notes are still recorded. Recording is retried until each note is recorded, up to 5 attempts 15 minutes apart: a retry records only the notes that failed, and an attempt that stopped partway is run again. Each recorded note is marked on the board in the same write as its case, and a retry skips marked notes. A retry never creates a case twice, and never re-creates a case that was deleted after it was recorded. A note whose case was deleted while it was being recorded is not retried. If notes still fail after the last attempt, or the last attempt stops partway, their case keys are kept on the archived board as `promotionAbandoned`, and the failure is logged as `blackboard.durable_notes_abandoned`. Notes that are not durable are never recorded: they stay only on the archived board.

***

## Color legend

| Color | Tool set family |
| - | - |
| Workforce | Authoring, factory operations, dashboard composition — primitives that act on the workforce surface. |
| Substrate | Platform query, code analysis, file I/O, validation — primitives that read or interact with the underlying substrate. |
| Trust Fabric | Privileged actions (e.g. `graphAuthoringPublish`) gated independently from authoring. |
| Observability | Run analysis, structural timelines, cost breakdown, artifact persistence. |
| Production | Worker-level execution surface. |
| Operations | External integrations (Google Workspace, HTTP, MCP) seeded as DB rows. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.