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

# Save facts a person tells you as entities

> Facts a person tells you are saved as entities, each citing a note of what was said, and none duplicates an entity that exists.

Guide · graph

> **Use when**
>
> A person tells you facts about people, companies or other things that the project's Shapes describe, and no File holds them yet.

> **Looking for something else?**
>
> Facts that a document already states (recipe [extract-files](https://docs.pnbr.io/guides/extract-files.md)). A change to an entity that is already in the Graph (card [entity](https://docs.pnbr.io/concepts/entity.md)).

## Outcome

Each fact is an entity or a relationship in the Graph, and it cites a note that
holds the person's words and the date. For each subject there is one entity.
The person knows what, if anything, still waits for approval.

## Before you start

* Orient first (recipe [orient](https://docs.pnbr.io/guides/orient.md)). A person's own session applies a submit
  directly. A key or a connected agent waits for approval at the submit (card
  rule [workspace.10](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-10)).
* Ask the person for the date of what they told you. It is the note's source
  date, and it is not today's date unless they said so.
* Write down each fact in the person's words before you go on.

## Steps

1. Learn the types. Use only types the Shapes have.
   * CLI: `penumbra shapes types`. Expect each Shape with its entity types,
     each with its title field and description, then a `relationships:` list,
     such as `Person —WORKS_AT→ Company`.
   * MCP: `grammar` with the domain, or `search_shapes` (card [shape](https://docs.pnbr.io/concepts/shape.md)).
   * A fact with no type to hold it needs a Shape change first (recipe
     [change-a-shape](https://docs.pnbr.io/guides/change-a-shape.md)).
2. Search for each subject before you create it. Penumbra does not compare an entity you stage by hand
   with the Graph (problem [extraction-duplicates-existing-entity](https://docs.pnbr.io/troubleshooting/extraction-duplicates-existing-entity.md)).
   * CLI: `penumbra graph search "<name>" --type <Type>`. If the answer warns
     `lexical_coverage_none` or `lexical_coverage_partial`, the search did not
     read the whole Graph. List the type instead with
     `penumbra graph nodes --type <Type>`.
   * MCP: `omnisearch` with the name, then `read` with `entity:<id>`.
   * If the subject exists, do not stage it again. Use it as an endpoint in
     step 5 (an existing entity's name or id), or change it (card [entity](https://docs.pnbr.io/concepts/entity.md)).
3. Save what the person said as a document, so every fact has a source to cite
   (card [document](https://docs.pnbr.io/concepts/document.md), card rule [passage.6](https://docs.pnbr.io/concepts/passage.md#rule-passage-6)).
   * CLI: `penumbra files new /notes/<date>-<topic>.md --from <file.md> --source-date <date>`.
   * MCP: `create_markdown` with the text, then `update_file` for the source
     date if the connection may set it (card rule [file.5](https://docs.pnbr.io/concepts/file.md#rule-file-5)).
   * Expect `created: /notes/<name>.md`, a File ID and a version ID.
4. Read the version you will cite.
   * CLI: `penumbra files versions /notes/<name>.md`. Expect the version ID and
     `content_digest sha256:…` on the line of the current version.
   * To cite one passage, take its passage ID from the search result or from
     `penumbra files chunks`, and add it to the citation as `chunk_id` (card
     [passage](https://docs.pnbr.io/concepts/passage.md)). `chunk_id` is optional, and the CLI
     needs no token for it.
   * MCP: `read` with the File reference returns a citation token for the
     version, or for exact words (card rule [passage.3](https://docs.pnbr.io/concepts/passage.md#rule-passage-3)).
5. Open a workspace with a new name, and stage the facts with their citations
   (card rules [workspace.1](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-1), [workspace.2](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-2) and [passage.2](https://docs.pnbr.io/concepts/passage.md#rule-passage-2)).
   * CLI: `penumbra graph workspace open "<name>" --description "<what>"`, then
     `penumbra graph workspace capture "<name>" <file.json>`. The file lists
     `entities` and `relationships`. An endpoint is a `ref` from the same file,
     or the name or id of an entity that already exists.

     ```json theme={null}
     {
       "entities": [
         {
           "ref": "dana",
           "type": "Person",
           "name": "Dana Reyes",
           "properties": { "name": "Dana Reyes", "role": "Head of Operations" },
           "evidence": [
             {
               "file_id": "<file-id>",
               "version_id": "<version-id>",
               "content_digest": "<content_digest>",
               "chunk_id": "<passage-id>"
             }
           ]
         }
       ],
       "relationships": [
         {
           "type": "WORKS_AT",
           "from": "dana",
           "to": "Acme Corporation",
           "evidence": [
             {
               "file_id": "<file-id>",
               "version_id": "<version-id>",
               "content_digest": "<content_digest>"
             }
           ]
         }
       ]
     }
     ```

   * Expect `staged N items into <name>`, one line for each item with its
     handle, and a note that the Shape is pinned for this workspace.

   * MCP: `capture` in the full catalog and in Kits, with `citation` tokens.

   * Program: `penumbra.workspaces.open({name})`, then
     `penumbra.domain.stage({workspace, entities, relationships})`. A staged
     relationship takes a type, `from` and `to`; it sets no properties and no
     citations here.
6. Check the whole workspace, and compare the counts with the facts.
   * CLI: `penumbra graph workspace validate "<name>"`. Expect `valid: yes`,
     `would apply: 2 entities, 1 relationships, 0 updates, 0 deletions` for
     the example above, and the submit command with its revision.
   * Validate warns about two staged entities with one name
     (`duplicate_name`). It does not warn that an entity with that name is
     already in the Graph.
7. Submit the revision you reviewed (recipe [review-and-submit](https://docs.pnbr.io/guides/review-and-submit.md)).
   * CLI: `penumbra graph workspace submit "<name>" --revision <n> --request-id <key>`.
   * Expect `submission: applied`, a counts line such as
     `created 1 entity and 0 relationships`, one line for each created
     entity with its ID, and exit code 0. Add `--detail` to list each
     relationship too. A key or a connected agent gets
     exit code 4 and `outcome: pending`; give the person the approval address
     and wait (problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md)).

## Check

* `penumbra context entity <entity-id>` shows the properties and a `from:`
  line that names the note, with its File and version IDs.
* `penumbra graph nodes --type <Type>` lists one entity for each subject you
  saved.
* `penumbra graph counts` shows the totals you expect.
* Nothing is saved until the submit says `applied` (card rule [workspace.2](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-2)).

## If it goes wrong

| You see | Read |
| - | - |
| `valid: no` or `schema_validation_failed` | card rule [entity.5](https://docs.pnbr.io/concepts/entity.md#rule-entity-5) |
| A citation is refused with `evidence_digest_mismatch` | card rule [passage.2](https://docs.pnbr.io/concepts/passage.md#rule-passage-2) |
| A warning `duplicate_name` on two staged entities | problem [same-name-two-entities](https://docs.pnbr.io/troubleshooting/same-name-two-entities.md) |
| Two entities with one name are in the Graph after the submit | problem [merge-duplicates](https://docs.pnbr.io/troubleshooting/merge-duplicates.md) |
| The submit is refused as `workspace_review_conflict` | problem [workspace-changed-since-you-read](https://docs.pnbr.io/troubleshooting/workspace-changed-since-you-read.md) |
| The submit returned `pending` or exit code 4 | problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md) |
| The workspace holds items you did not stage | card rule [workspace.1](https://docs.pnbr.io/concepts/workspace.md#rule-workspace-1) |
| The search finds nothing for a subject that you know exists | problem [search-returns-nothing](https://docs.pnbr.io/troubleshooting/search-returns-nothing.md) |

## Worth offering

* Offer to ask the person for facts you still lack, such as a role or a date,
  and to add them in a second workspace.
* If the person has documents that state the same facts, offer to extract from
  them (recipe [extract-files](https://docs.pnbr.io/guides/extract-files.md)). Extraction then adds citations to exact
  passages.
* Offer to relate the new entities to existing ones, such as a person to a
  company that the Graph already has.

## Report

List each entity and relationship you saved, with its ID. Name the note that
holds the person's words, its date and its version. Say which subjects already
existed and how you used them. Say what waits for approval and who decides.
Say that you saved only what the person told you, and name any fact that no
type could hold.

## Keep going

[Workspace](https://docs.pnbr.io/concepts/workspace.md) · [Entity](https://docs.pnbr.io/concepts/entity.md) · [Relationship](https://docs.pnbr.io/concepts/relationship.md) · [Shape](https://docs.pnbr.io/concepts/shape.md) · [Passage and citation](https://docs.pnbr.io/concepts/passage.md) · [Document](https://docs.pnbr.io/concepts/document.md) · [Review a workspace and submit it](https://docs.pnbr.io/guides/review-and-submit.md) · [Extract entities from Files](https://docs.pnbr.io/guides/extract-files.md) · [Two entities have the same name](https://docs.pnbr.io/troubleshooting/same-name-two-entities.md) · [Two entities in the Graph are one thing](https://docs.pnbr.io/troubleshooting/merge-duplicates.md) · [Approval](https://docs.pnbr.io/concepts/approval.md)

Penumbra Grammar 0.6.26


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