> ## 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.

# Review a workspace and submit it

> A workspace's changes are applied, or the person knows exactly what waits and why.

Guide · graph

> **Use when**
>
> A workspace holds staged changes, from your own capture or from an extraction, and they are ready to reach the Graph.

> **Looking for something else?**
>
> Creating the staged items (recipes capture-by-hand and extract-files). One change to one entity (card [Entity](https://docs.pnbr.io/concepts/entity.md)).

## Outcome

The workspace has status `applied`, and each entity and relationship it held is
in the Graph. If that is not yet true, the person knows what waits, who must
act, and why.

## Before you start

1. Name the workspace and read it: `penumbra graph workspace show "<name>"`.
   The first line shows its status and revision. It must show `open`. If it
   shows `submitted`, go to problem [submit-partly-applied](https://docs.pnbr.io/troubleshooting/submit-partly-applied.md) (rule
   [workspace.9](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-9)). If it says `items: none of 0 here`, stage items first.
2. Know your credential: `penumbra whoami`. An API key or a connected agent
   waits for approval at the submit (rules [approval.1](https://docs.pnbr.io/concepts/approval.md#rule-approval-1) and [approval.2](https://docs.pnbr.io/concepts/approval.md#rule-approval-2)). A
   person's own session does not.
3. Plan to use one credential for the whole recipe. Only the credential that
   submits can resume a partial submit (rule [workspace.6](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-6)).
4. Choose a request id for the submit, such as `--request-id submit-<name>-1`.
   You need it to recover a lost reply (problem [reply-lost](https://docs.pnbr.io/troubleshooting/reply-lost.md)).

## Steps

1. Read the workspace and note its revision.
   * CLI: `penumbra graph workspace show "<name>"`.
   * MCP: `review_work` with the workspace id (default catalog), or
     `workspace_read` (full catalog and Kits).
   * Expect: a list of items with handles, then `submission: not started` and
     `submit with --revision <n>`.
2. Review every item against its source. An item that says `updates existing`
   came from an extraction. It changes the entity it names, and the submit
   makes a new revision of that entity. Check that it is the same thing. If it
   is not, run `penumbra graph workspace keep-new "<name>" <handle>` (problem
   [extraction-duplicates-existing-entity](https://docs.pnbr.io/troubleshooting/extraction-duplicates-existing-entity.md)). If you must correct an item, edit it
   with `penumbra graph workspace modify "<name>" <file>`. An item for an
   entity that exists takes a patch, and the patch keeps the properties you
   leave out (rule [entity.2](https://docs.pnbr.io/concepts/entity.md#rule-entity-2)). An item that is new in this workspace has no
   earlier properties. An edit of its `properties` replaces the whole map, so
   send every property you want to keep. Then read the workspace again, because
   each edit changes the revision (card [workspace](https://docs.pnbr.io/concepts/workspace.md)).
3. Check the whole workspace.
   * CLI: `penumbra graph workspace validate "<name>"`.
   * MCP: `workspace_validate`, or `penumbra.workspace(reference).validate()`
     inside `execute`.
   * Expect: `valid: yes`, a `review:` line, a line `would apply:` with
     counts, and a `next:` line. With no review flags it is
     `next: penumbra graph workspace submit "<name>" --revision <n>`. If items carry review
     flags, it is `next: penumbra graph workspace show "<name>"`: read the
     flagged items, then take the revision from `show`. A line
     `N extracted items update a record the project already has` can follow.
     Fix every line that starts with `error` and validate again (rule
     [workspace.3](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-3)). Tell the person about each warning.
4. If the `would apply:` line shows deletions, tell the person which entities
   it deletes before you go on. A delete removes the entity's relationships
   too (rule [entity.3](https://docs.pnbr.io/concepts/entity.md#rule-entity-3)).
5. Submit the revision that validate or show printed.
   * CLI: `penumbra graph workspace submit "<name>" --revision <n> --request-id <key>`.
   * MCP: `workspace_submit` with `expected_revision` (full catalog and Kits at
     confirm or apply), or `penumbra.workspace(reference).submitReviewed` with
     `expectedRevision` inside `execute` (default catalog).
   * Expect: `submission: applied`, a counts line, one line for each created,
     updated or deleted entity (add `--detail` to list relationships too),
     and exit code 0. See rules [workspace.4](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-4) and [workspace.5](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-5).
6. If the CLI exits with code 4 and prints `outcome: pending`, the change waits
   for approval. Give the person the approval URL and tell them that nothing has
   changed yet. Then follow it: `penumbra operations wait <handle>` (rules
   [approval.3](https://docs.pnbr.io/concepts/approval.md#rule-approval-3) and [approval.4](https://docs.pnbr.io/concepts/approval.md#rule-approval-4)). In the default catalog, use `check_status`
   with the approval reference.
7. When the wait ends, read the workspace again with step 1 and go to Check.

## Check

1. Run `penumbra graph workspace show "<name>"`. The first line must show
   `[applied <id>]`, and the line `submission:` must read `applied`.
2. Run `penumbra graph get <id>` for two of the ids that the submit printed. Each
   must show the type you staged and a `revision`.
3. If the check fails, do not submit again. Use the table below.

## If it goes wrong

| What you see | Go to |
| - | - |
| Exit code 4, `outcome: pending` and an approval URL | problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md) |
| `workspace_review_conflict`, or a `witness_stale` diagnostic | problem [workspace-changed-since-you-read](https://docs.pnbr.io/troubleshooting/workspace-changed-since-you-read.md) |
| `submission: partial` or `submission: unknown` | problem [submit-partly-applied](https://docs.pnbr.io/troubleshooting/submit-partly-applied.md) |
| Exit code 4 with `outcome: unknown`, or no reply at all | problem [reply-lost](https://docs.pnbr.io/troubleshooting/reply-lost.md) |
| `graph_write_busy` | problem [graph-busy](https://docs.pnbr.io/troubleshooting/graph-busy.md) |
| `workspace_not_open` | rule [workspace.9](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-9) |
| `create_plan_too_large`, `lifecycle_plan_too_large` or `link_plan_too_large` | rule [workspace.7](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-7) |
| `submission: rejected` with error lines | Fix each error with `penumbra graph workspace modify`, then start again at step 3. Nothing was applied. |

## Worth offering

* If the submit waits for approval, offer the owner a short list of what it
  changes, one line for each change.
* Offer to check what else the applied change touches (reference
  [how-penumbra-fits-together](https://docs.pnbr.io/understand/how-penumbra-fits-together.md)).

## Report

Tell the person:

* The outcome: applied, waiting for approval, partly applied, or rejected.
* How many entities and relationships were created, changed or deleted, by type.
* What still waits, who must approve it, and the approval URL.
* Each warning that validate gave, and what you did about it.
* The request id of the submit.

## Keep going

[Workspace](https://docs.pnbr.io/concepts/workspace.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [Entity](https://docs.pnbr.io/concepts/entity.md) · [A change returned pending](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md) · [A submit is partly applied or unresolved](https://docs.pnbr.io/troubleshooting/submit-partly-applied.md) · [The workspace changed since you read it](https://docs.pnbr.io/troubleshooting/workspace-changed-since-you-read.md) · [The reply to a change was lost](https://docs.pnbr.io/troubleshooting/reply-lost.md) · [A Graph write returned graph\_write\_busy](https://docs.pnbr.io/troubleshooting/graph-busy.md)

Penumbra Grammar 0.6.26


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