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

# Turn documents into structured knowledge

> Save source material, estimate extraction cost, extract through a Shape, and check the records against the original.

Use this when you have documents, web pages, or text that should become
searchable records and relationships in a Penumbra project.

The workflow uses Runtime. Open the Shapes MCP only if the catalog does not have
a Shape that fits the material.

## Before you start

* Name the target project.
* Gather the material or public URLs.
* List the records you expect to get from it.
* Set the maximum extraction cost you are willing to approve.

## Ask your agent

> In the Customer Discovery project, save the Q3 interview material as sources
> and turn it into structured research records. First check the project and find
> the best existing Shape. Show me the choice. Save and verify each source
> before extraction. Then estimate the extraction cost and wait for my approval.
> After the run, show the records, relationships, supporting passages, and actual
> cost. Mark anything not supported by the sources as an open question.

## Steps

<Steps>
  <Step title="Check the project and Shape">
    Inspect the active project and search the catalog. If no Shape can represent the records you listed, stop and [create one](/shapes/create-shape) before extraction.
  </Step>

  <Step title="Save the material as sources">
    Add each document, page, or text block with a recognizable title. If intake returns a receipt, poll that receipt rather than submitting the material again.
  </Step>

  <Step title="Quote each source">
    Retrieve one passage from every source. This confirms that the material—not only its filename—is available.
  </Step>

  <Step title="Estimate extraction">
    Run a dry run and review the source count, token count, estimated credits, and available balance.
  </Step>

  <Step title="Approve the paid run">
    Confirm the source set, Shape, and cost. Start extraction once, then poll the returned run until it completes or fails.
  </Step>

  <Step title="Inspect what extraction produced">
    Open representative records and relationships. Compare their claims with the source passages behind them.
  </Step>

  <Step title="Report the final state">
    State the actual cost and whether the records are live, staged, or waiting for review.
  </Step>
</Steps>

## Verify

Choose one extracted finding and ask the agent to:

1. open the complete record;
2. identify the Shape and record type;
3. quote the source passage that supports it;
4. identify any part of the finding that goes beyond the passage.

## Troubleshooting

* **Source intake is still running:** poll the same receipt.
* **The estimate is too high:** narrow the source set or stop.
* **No Shape fits:** describe the missing records and relationships, then create or fork a Shape.
* **Extraction is still running:** poll the existing run; starting another can spend credits twice.
* **The records misread the source:** determine whether the Shape or the extraction is at fault before retrying.

<Accordion title="Tool trace">
  ```text theme={null}
  penumbra_status
  → penumbra_shapes_list / penumbra_shapes_search
  → penumbra_shapes_add when approved and needed
  → penumbra_add_source
  → penumbra_add_source({ receipt }) until ready when needed
  → penumbra_source_rag
  → penumbra_introspect
  → penumbra_extract({ dry_run: true })
  → approval
  → penumbra_extract
  → penumbra_extract({ run }) until complete
  → penumbra_omnisearch
  → penumbra_read
  → penumbra_source_rag
  ```
</Accordion>