Skip to main content
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.
  2. Penumbra reads the current version into passages. Search returns passages, and an answer cites them. Card passage.
  3. Search finds passages and entities. A new version is found by exact words first, and by meaning after processing finishes. Card search.
  4. Collections group Files. A collection is what you extract from, share and keep in sync with a folder. Card collection.
  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 and approval.
  8. The Graph holds entities and relationships. An entity keeps its properties, its revisions and its citations. Card entity.
  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.

​
Where to start

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 · Collection · Passage and citation · Search · Workspace · Entity · Approval · Citations to confirm · Find entities that rest on an old version or a trashed File · Make two entities one · Change a Shape and publish it · Share part of a project with a View