> ## 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 Penumbra fits together

> Penumbra's parts form one chain from documents to answers, and a change at one part can leave work at the parts after it.

Overview · core

> **Use when**
>
> You start a job you have not done in this project, or you need to know what else a change touches.

> **Looking for something else?**
>
> How one part works in detail (its card). The steps of one job (its recipe).

## The chain

A project holds one body of knowledge. Its parts connect in this order.

1. **Files** hold documents. A File keeps every version, and one version is
   current. Card [file](https://docs.pnbr.io/concepts/file.md).
2. Penumbra reads the current version into **passages**. Search returns
   passages, and an answer cites them. Card [passage](https://docs.pnbr.io/concepts/passage.md).
3. **Search** finds passages and entities. A new version is found by exact
   words first, and by meaning after processing finishes. Card [search](https://docs.pnbr.io/concepts/search.md).
4. **Collections** group Files. A collection is what you extract from, share
   and keep in sync with a folder. Card [collection](https://docs.pnbr.io/concepts/collection.md).
5. A **Shape** names the kinds of things a domain cares about: their types,
   properties and relationships.
6. **Extraction** reads Files with a Shape. It proposes entities and
   relationships in a workspace. Each proposal cites the passages it came from,
   in the version it read.
7. A **workspace** holds Graph changes until you submit them. A submit by an API
   key or a connected agent can wait for approval. Cards [workspace](https://docs.pnbr.io/concepts/workspace.md) and
   [approval](https://docs.pnbr.io/concepts/approval.md).
8. The **Graph** holds entities and relationships. An entity keeps its
   properties, its revisions and its citations. Card [entity](https://docs.pnbr.io/concepts/entity.md).
9. A **View** chooses part of the project, and a **Brain** gives that part to
   a client with agents and access.

So a fact moves from a document, to a passage, to a cited entity, to an
answer. Each step keeps a pointer back to the step before it.

## What a change touches

A change is complete only when the parts after it agree with it.

| You change | What follows by itself | What is left for you | Read |
| - | - | - | - |
| A document has a new edition | Replacing the File makes the new version current. Search stops returning the old passages. | Entities still cite the old version. Nothing extracts the new one. Find those entities and compare. | recipe [new-edition](https://docs.pnbr.io/guides/new-edition.md), problem [entities-cite-replaced-version](https://docs.pnbr.io/troubleshooting/entities-cite-replaced-version.md) |
| A new edition is uploaded as a separate File | Both Files stay in search. | Nothing says which one is newer. Replace instead. | problem [two-editions-two-files](https://docs.pnbr.io/troubleshooting/two-editions-two-files.md) |
| A File arrives with no source date | Penumbra knows when it arrived, not when it was written. | Set the source date, or entities from it carry no source time. | problem [file-has-no-source-date](https://docs.pnbr.io/troubleshooting/file-has-no-source-date.md) |
| A File was uploaded seconds ago | Search finds it by exact words first. | Wait for processing before you trust a search that finds nothing. | problem [new-file-not-searchable-yet](https://docs.pnbr.io/troubleshooting/new-file-not-searchable-yet.md) |
| You edit an entity by hand | Citations it may no longer stand on wait for an answer. | Confirm or answer each one. | card [citations-to-confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md) |
| You stage Graph changes | Nothing reaches the Graph. | Submit, and follow the outcome to the end. | recipe [review-and-submit](https://docs.pnbr.io/guides/review-and-submit.md) |
| A submit returns `pending` | Nothing has changed yet. | Give the person the approval URL. Do not send it again. | problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md) |
| A File is trashed | Its cited text reads as not found. | Entities that cite it stay, and nothing flags them. Find them. | recipe [find-stale-entities](https://docs.pnbr.io/guides/find-stale-entities.md) |
| A Shape changes | A new workspace uses the new version. | Existing entities stay on their version. Nothing re-extracts. | recipe [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md), problem [breaking-shape-change](https://docs.pnbr.io/troubleshooting/breaking-shape-change.md) |
| Two entities turn out to be one thing | Nothing. Penumbra has no merge. | Move the relationships and properties, then delete the extra one. | recipe [resolve-duplicates](https://docs.pnbr.io/guides/resolve-duplicates.md) |
| A Shape adds a type that a View should show | The View keeps the type names it had at publish. | Publish the View again. | problem [view-needs-republish](https://docs.pnbr.io/troubleshooting/view-needs-republish.md) |

## Where to start

| The person wants | Start with |
| - | - |
| Documents in the project, ready to search and cite | recipe [bring-in-a-corpus](https://docs.pnbr.io/guides/bring-in-a-corpus.md) |
| An answer from the project's documents | recipe [answer-with-citations](https://docs.pnbr.io/guides/answer-with-citations.md) |
| A newer copy of a document the project has | recipe [new-edition](https://docs.pnbr.io/guides/new-edition.md) |
| Changes to entities or relationships | recipe [review-and-submit](https://docs.pnbr.io/guides/review-and-submit.md) |
| Entities that may rest on old or trashed Files | recipe [find-stale-entities](https://docs.pnbr.io/guides/find-stale-entities.md) |
| Two entities that are one thing made one | recipe [resolve-duplicates](https://docs.pnbr.io/guides/resolve-duplicates.md) |
| A change to a Shape's types or properties | recipe [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md) |
| A Shape for a domain that no Shape covers | recipe [create-a-shape](https://docs.pnbr.io/guides/create-a-shape.md) |
| Part of the project shown to a client or an agent | recipe [share-with-a-view](https://docs.pnbr.io/guides/share-with-a-view.md) |

When nothing fits, build the job from the cards, and say so in your report.

## Doors

The same parts have the same names in every door. The CLI is `penumbra`. An
MCP connection reaches them through tools. The SDK reaches them from code.
Each card's Doors table names the command, tool and SDK call for its part.
Some parts have no door in some places. The card says so.

## Reading the Grammar

The Grammar is Penumbra's own rules: the cards, recipes and problems that you
are reading. The word does not name a Shape. A Shape is the model of one
domain. On the default MCP connection the `grammar` tool has two modes. Call it
with `howto` to read the Grammar, and pass an entry id, the job or what you
saw. Call it with `domain` or `refs`, or with neither for the project glossary,
to read the project's domain: its types, relationships and properties. A
connection that serves the Grammar as its own `grammar` tool takes `query` or
`id` and reads the Grammar only. In the CLI, `penumbra grammar search` and
`penumbra grammar show` read the Grammar.

## Keep going

[File](https://docs.pnbr.io/concepts/file.md) · [Collection](https://docs.pnbr.io/concepts/collection.md) · [Passage and citation](https://docs.pnbr.io/concepts/passage.md) · [Search](https://docs.pnbr.io/concepts/search.md) · [Workspace](https://docs.pnbr.io/concepts/workspace.md) · [Entity](https://docs.pnbr.io/concepts/entity.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [Citations to confirm](https://docs.pnbr.io/concepts/citations-to-confirm.md) · [Find entities that rest on an old version or a trashed File](https://docs.pnbr.io/guides/find-stale-entities.md) · [Make two entities one](https://docs.pnbr.io/guides/resolve-duplicates.md) · [Change a Shape and publish it](https://docs.pnbr.io/guides/change-a-shape.md) · [Share part of a project with a View](https://docs.pnbr.io/guides/share-with-a-view.md)

Penumbra Grammar 0.6.26


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