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

# Workspace

> Gathers changes to the Graph so a person or an agent checks and decides them as one set.

Concept · graph

A workspace (the App calls it a review) holds proposed Graph changes under a name, and nothing reaches the Graph until you submit it.

> **Use when**
>
> You add, change or delete several entities or relationships, or you review what an extraction found.

> **Looking for something else?**
>
> One change to one entity (card [Entity](https://docs.pnbr.io/concepts/entity.md)). Text you write and edit as a document (card [Document](https://docs.pnbr.io/concepts/document.md)). Starting an extraction, which opens its own workspace (card [Extraction](https://docs.pnbr.io/concepts/extraction.md)).

## For

A workspace is a named working set. You stage entities and relationships in it.
You can change what is staged. You can check out existing entities to change
or delete them. You can validate the whole set, and then you submit it. An
extraction opens its own new workspace for its findings, so a person can review
them before anything reaches the Graph.

A workspace has one status: `open`, `submitted`, `applied` or `closed`.
Changes to the workspace raise its revision number. A submit can use that
number as its guard.

## Use when

* You create several entities or relationships together.
* You change or delete existing entities, alone or together with new ones.
* An extraction finished and a person must review what it found.
* You want to stop now and continue later. Close it, and restore it by id.

## Not this

* One change to one entity: use `penumbra graph update` (card [Entity](https://docs.pnbr.io/concepts/entity.md)).
* Text a person reads as a document: use a document (card [Document](https://docs.pnbr.io/concepts/document.md)).

## Rules

1. `workspace.1` A workspace name stands for one working set. Open the same name
   again to continue an open workspace. An applied workspace opens again with
   its staged items cleared and the entities it created checked out for update.
   **Enforced:** opening the name of a closed workspace is refused with
   `workspace_closed`, which names `workspace_restore` and the id. **Your job:**
   use a new name for new work, and restore a closed workspace by its id.
2. `workspace.2` Staging changes the workspace only. Capture, modify and check
   out leave the Graph as it was. **Your job:** do not tell the person that a
   change is saved until a submit returns `applied`.
3. `workspace.3` Validate before you submit. `penumbra graph workspace validate`
   applies nothing and lists diagnostics. **Enforced:** a submit checks the
   workspace again, and any error diagnostic gives the outcome `rejected` with
   nothing applied. A warning, such as `duplicate_name`, does not stop a submit.
4. `workspace.4` Submit the revision you reviewed. Pass it to
   `penumbra graph workspace submit` as `--revision`. **Enforced when you ask:**
   a different current revision is refused with `workspace_review_conflict` and
   nothing is applied. Without `--revision`, nothing checks which revision
   applies.
5. `workspace.5` A submit can commit in up to three phases. The phases are
   changes to existing entities and relationships, new entities and
   relationships, and relationships from new entities to existing ones. Each
   phase is one commit, but the workspace is not. The outcome is `applied`,
   `partial`, `rejected` or `unknown`. A workspace read shows `unknown` as
   `submission: unresolved`. **Your job:** do not assume all or nothing. When a Shape in the project has rules, the whole submit runs as one
   transaction instead, and a failure keeps nothing from it.
6. `workspace.6` Never read `partial` or `unknown` as a rollback. `rejected`
   means nothing was applied. **Your job:** resume the same workspace with the
   same credential that submitted it, as problem [submit-partly-applied](https://docs.pnbr.io/troubleshooting/submit-partly-applied.md) says.
   Another credential cannot resume it, and the workspace read shows no resume
   line to it.
7. `workspace.7` A workspace has size limits. **Enforced:** a workspace holds at
   most 1,000 staged items (`workspace_full`). One submit creates at most 1,000
   entities and relationships (`create_plan_too_large`). One submit changes at
   most 100 existing entities and relationships (`lifecycle_plan_too_large`).
   One submit adds at most 100 relationships from new entities to existing ones
   (`link_plan_too_large`). Validate and submit both refuse an excess, and the
   workspace stays open.
8. `workspace.8` To change or delete an existing entity, check it out first with
   `penumbra graph workspace hydrate`. Use `--intent delete` to delete it.
   **Enforced:** if the entity changed after you checked it out, validate and
   submit report `witness_stale` for that item and apply nothing. Checking out
   an entity that is already checked out does not refresh it. Use
   `penumbra graph workspace refresh` (rule [workspace.13](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-13)).
9. `workspace.9` Only an open workspace takes new staged work. **Enforced:** a
   workspace that is `closed`, `applied` or `submitted` refuses staging with
   `workspace_not_open`. Restore a `closed` one, open an `applied` one by name,
   or resume the submission if it is `submitted`.
10. `workspace.10` A submit from an API key or a connected agent waits for
    approval under the default policy. **Enforced:** the result is `pending`
    with an approval URL. Rules [approval.1](https://docs.pnbr.io/concepts/approval.md#rule-approval-1) and [approval.3](https://docs.pnbr.io/concepts/approval.md#rule-approval-3) say what to do.
11. `workspace.11` Closing sets a workspace aside. The App calls this discarding
    a review. **Enforced:** `penumbra graph workspace close` closes only an open
    workspace, and any other status is refused with `workspace_not_open`.
    Nothing reaches the Graph, and no staged item is deleted. **Your job:** tell
    the person that nothing was added. Restore brings the workspace back with its
    items (rule [workspace.12](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-12)), so use a new name to start clean.
12. `workspace.12` Restore brings a closed workspace back by its id.
    **Enforced:** `penumbra graph workspace restore` refuses a workspace that is
    not closed with `workspace_not_closed`. Extracted entities are compared with
    the Graph again, so one that matches an entity added since updates that
    entity and makes no duplicate. An entity or relationship you pulled in that
    changed or was removed while the workspace was closed carries a flag. So does
    an item written under a Shape that has a newer version. Nothing refreshes on
    its own, and a submit still refuses a changed entity with `witness_stale`.
    **Your job:** read the flags before you submit, then refresh or remove each
    flagged item (rule [workspace.13](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-13)).
13. `workspace.13` Refresh brings one pulled-in entity up to date.
    **Enforced:** `penumbra graph workspace refresh <workspace> <handle>` reads
    the entity again at its current revision. Your change stays only on fields
    that did not change since you read the entity. A field that changed loses
    your change and is named in a `refresh_conflict` flag, and you set it again
    with `penumbra graph workspace modify`. An item that extraction linked to an
    entity is compared with the Graph again. An entity that was removed is
    refused with `refresh_unavailable`. **Your job:** read the conflict flag
    before you submit.

## Failure signs

* A submit is refused with `workspace_review_conflict`: problem
  [workspace-changed-since-you-read](https://docs.pnbr.io/troubleshooting/workspace-changed-since-you-read.md).
* A submit exits with code 4 and an approval URL: problem
  [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md).
* A submit ends with outcome `partial` or `unknown`: problem
  [submit-partly-applied](https://docs.pnbr.io/troubleshooting/submit-partly-applied.md).
* A command ended with no reply, or with `outcome: unknown`: problem
  [reply-lost](https://docs.pnbr.io/troubleshooting/reply-lost.md).
* A write is refused with `graph_write_busy`: problem [graph-busy](https://docs.pnbr.io/troubleshooting/graph-busy.md).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra graph workspace open`, `penumbra graph workspace list`, `penumbra graph workspace show`, `penumbra graph workspace capture`, `penumbra graph workspace modify`, `penumbra graph workspace hydrate`, `penumbra graph workspace validate`, `penumbra graph workspace submit`, `penumbra graph workspace close`, `penumbra graph workspace restore`, `penumbra graph workspace refresh` |
| MCP (default) | `execute` runs a program that calls `penumbra.workspaces.open()`, `penumbra.domain.stage()` and, on `penumbra.workspace(reference)`, `.read()`, `.validate()`, `.hydrate()`, `.modify()` and `.submitReviewed()`. `discover_actions` shows the exact calls. `review_work` and `check_status` read the state. |
| MCP (full catalog) | `workspace_open`, `workspace_list`, `workspace_read`, `capture`, `workspace_modify`, `workspace_hydrate`, `workspace_validate`, `workspace_submit`, `workspace_close`, `workspace_restore` |
| MCP (Kits) | A Kit with the Kit level propose, confirm or apply has `workspace_open`, `capture`, `workspace_read`, `workspace_hydrate`, `workspace_modify` and `workspace_validate`. Confirm and apply add `workspace_submit`. |
| SDK | `ProjectGraph.workspaces`, `GraphWorkspace` |

The default catalog has no call that closes or restores a workspace. Use the CLI,
the SDK or the full catalog.

## The CLI word

The CLI calls an entity a node in its workspace output.

## HTTP reference

* [List review workspaces](https://docs.pnbr.io/api/http-graph-workspaces-list.md)
* [Open review workspace](https://docs.pnbr.io/api/http-graph-workspaces-open.md)
* [Get review workspace](https://docs.pnbr.io/api/http-graph-workspaces-get.md)
* [Stage records](https://docs.pnbr.io/api/http-graph-workspaces-capture.md)
* [Stage existing records](https://docs.pnbr.io/api/http-graph-workspaces-hydrate.md)
* [Edit staged records](https://docs.pnbr.io/api/http-graph-workspaces-modify.md)
* [Validate review workspace](https://docs.pnbr.io/api/http-graph-workspaces-validate.md)
* [Submit review workspace](https://docs.pnbr.io/api/http-graph-workspaces-submit.md)
* [Close review workspace](https://docs.pnbr.io/api/http-graph-workspaces-close.md)
* [Restore review workspace](https://docs.pnbr.io/api/http-graph-workspaces-restore.md)
* [List workspace extractions](https://docs.pnbr.io/api/http-graph-workspaces-extractions.md)
* [Stop workspace extraction](https://docs.pnbr.io/api/http-graph-workspaces-stop-extraction.md)

## Keep going

[Entity](https://docs.pnbr.io/concepts/entity.md) · [Relationship](https://docs.pnbr.io/concepts/relationship.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [Extraction](https://docs.pnbr.io/concepts/extraction.md) · [Review a workspace and submit it](https://docs.pnbr.io/guides/review-and-submit.md)

Penumbra Grammar 0.6.26


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