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

# How review works

> Understand why Penumbra separates source material, proposed changes, and live project knowledge.

An agent can move quickly, but some mistakes are expensive: writing to the wrong
project, extracting through the wrong Shape, or turning a weak interpretation
into shared knowledge. Penumbra makes those mistakes easier to catch by
separating context, evidence, proposed work, and live results.

## Every operation has a project context

The active project determines which Shapes, sources, and records the agent can
see. That is why Runtime workflows begin by checking the current project.
Without that check, an otherwise correct operation can still happen in the
wrong place.

## Sources and findings are different things

A source preserves the original words. A finding is an interpretation of those
words through a Shape.

Keeping both lets an agent answer two separate questions:

* What does the project currently believe?
* What did the underlying material actually say?

When the answer matters, the agent should retrieve the record and the source
passage instead of treating either one as a substitute for the other.

## Changes are reviewed as a group

Captures and edits are collected in a workspace before submission. The
workspace gives you one place to inspect related entities and relationships,
run validation, and correct mistakes.

Submitting the workspace does not always mean the change is already live. The
project may apply it immediately or send it for review. The submission result
states which happened.

## Extraction starts with an estimate

Extraction uses model credits and can create many records at once. A dry run
shows the source count, token count, estimated cost, and available balance
before the paid run begins. The run then returns a handle the agent can poll;
polling that handle avoids charging twice for the same job.

## Shape publishing uses the same pause

A Shape draft does not affect Runtime. Before publishing it, the agent can
compile the draft, show the exact changes, preview what Runtime will expose,
and run publication without applying it. Only the final publish step changes
the project.

## Verification happens where the result will be used

After a change, read the result from Runtime:

* retrieve a new source and quote it;
* find and open a captured entity;
* inspect an edited value on the live record;
* confirm a published Shape and its fields.

This final read catches wrong-project mistakes, pending reviews, and successful
commands that did not produce the intended result.

<Columns cols={2}>
  <Card title="Capture knowledge" icon="pen-to-square" href="/runtime/capture-knowledge">
    Stage, validate, submit, and read back a new record.
  </Card>

  <Card title="Publish a Shape" icon="rocket" href="/shapes/review-and-publish">
    Review a draft and confirm the published result in Runtime.
  </Card>
</Columns>
