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

# View

> A View is a published part of a project, and a login, key or agent limited to it reads only that part.

Concept · access

> **Use when**
>
> You share part of a project with a client, an agent or a key, or you need to know what a limited credential can read.

> **Looking for something else?**
>
> A group of Files (card [Collection](https://docs.pnbr.io/concepts/collection.md)). Who has access, what their agents may do and what they did (card [Brain](https://docs.pnbr.io/concepts/brain.md)). Which credential you hold (card [Credential](https://docs.pnbr.io/concepts/credential.md)).

## For

A View names part of a project: collections and single Files, Shapes, and the
entity and relationship types to show. A person, an API key or an agent that is
limited to a View reads only that part and can never write. Each read leaves
a read receipt. Everyone else reads the whole project as their role allows.

The limit belongs to the person, key or agent, and not to a URL. You publish a
View as numbered versions. A limit either follows the newest version or stays
on one version you pinned.

A Brain gives a View a name, agents and a list of who has access (card
[brain](https://docs.pnbr.io/concepts/brain.md)). Use a View alone when the person needs only the limit.

## Use when

* A client, an agent or a key must read some Files and entities, and nothing else.
* You must tell the person exactly what a limited credential can read.
* A limited credential reads less than the person expects.

## Not this

* A group of Files you extract from or search together: use a collection (card [Collection](https://docs.pnbr.io/concepts/collection.md)).
* Naming the agents, the instructions and the people who have access to one View: use a Brain (card [Brain](https://docs.pnbr.io/concepts/brain.md)).
* Finding out which credential you hold: use card [Credential](https://docs.pnbr.io/concepts/credential.md).

## Rules

1. `view.1` You publish a View as numbered versions, and a limit reads only
   published versions. **Your job:** an edit to the draft with
   `penumbra context slice update` changes nothing for anyone until you run
   `penumbra context slice publish`. A new definition replaces the old one in
   full, so repeat every collection, Shape and type that must stay.
2. `view.2` A View limits Files only when it names a collection or a File.
   **Your job:** name at least one collection or File. A View with neither
   shows every File in the project, even when it limits types. Penumbra
   publishes such a View without a warning. `penumbra context slice show`
   prints its scope as "the whole project" only when the View names nothing. A
   View that names only types or Shapes prints those, and still shows every
   File.
3. `view.3` Collections are read when someone reads, and types are fixed when
   you publish. **Your job:** a File that joins an included collection appears
   at once, and a File that leaves it disappears at once (card rule
   [collection.9](https://docs.pnbr.io/concepts/collection.md#rule-collection-9)). A type that a Shape gains later stays hidden until you
   publish the View again (problem [view-needs-republish](https://docs.pnbr.io/troubleshooting/view-needs-republish.md)).
4. `view.4` A limit follows the newest published version unless you pin it.
   **Your job:** pass `--version <number|id>` to `penumbra access attach`,
   `penumbra keys create` or `penumbra kits connections create` only when the
   person wants the content frozen. A pinned limit ignores later publishes.
5. `view.5` The graph mode decides which entities a limited credential sees.
   **Your job:** leave the default `backed`, which shows an entity with no
   File citations or with at least one citation inside the View. Choose `types`
   only when the person accepts that an entity of those types may repeat text
   from a File outside the View. Both modes hide citations to Files outside
   the View.
6. `view.6` A limited credential can only read. **Enforced:** attaching a
   View to a key or agent with a write scope is refused with
   `view_requires_read_only`. Giving a limited credential a write scope, or
   raising a limited login above viewer, is refused with
   `view_bounded_read_only`. **Your job:** remove the limit first only when the
   person means to widen access (rule [view.10](https://docs.pnbr.io/concepts/view.md#rule-view-10)).
7. `view.7` Only a client can be limited. **Enforced:** a member of the
   organization is refused with `view_requires_client`, and a project editor or
   admin is refused with `view_requires_viewer`. A client is a project viewer
   who belongs to no organization.
8. `view.8` Creating, editing and publishing a View take more than read
   access. **Enforced:** a person below editor is refused with
   `view_change_requires_editor`. A key or agent without the scope
   `context.view.write` is refused with `view_change_requires_scope`. A
   publish by a key or agent also waits for approval (card [approval](https://docs.pnbr.io/concepts/approval.md)).
9. `view.9` Attaching, removing, retiring and reading read receipts take a
   signed-in person who manages access. **Enforced:** a key or agent is
   refused with `human_session_required`, and any other person with
   `permission_denied`. Managers are organization owners and admins, and
   project owners and admins who belong to the organization.
10. `view.10` Removing a limit widens access. **Enforced:**
    `penumbra access remove` returns the key, agent or login to whole-project
    reads at once, and it asks to confirm. Without a terminal it needs `--yes`
    and otherwise exits with `confirmation_required`. **Your job:** to end
    someone's access, use `penumbra brains remove-door` or
    `penumbra keys revoke`, never `penumbra access remove`.
11. `view.11` Retiring a View cuts off everyone limited to it. **Enforced:**
    `penumbra context slice retire` asks to confirm. After it, every read by a
    limited credential fails with `view_unavailable` until you publish the View
    again. Publishing a retired View restores it.
12. `view.12` A publish is refused when a type name inside the View is also
    the name of a type outside it. **Enforced:** the refusal is
    `semantic_scope_ambiguous`, and its message names the labels. **Your job:**
    rename one of the types in its Shape, or choose the Shapes and types so
    that the names differ.
13. `view.13` Some reads are not part of any View. **Enforced:** a limited
    credential is refused with `view_operation_unavailable` for Graph
    workspaces, extraction runs, Graph history, the project ontology, Shape
    authoring and ad hoc Context. **Your job:** do that work with an unlimited
    credential.
14. `view.14` When a View limits types, a limited credential reads only the
    Shapes the View names. **Your job:** name the Shape, and not only its
    types, when the client's agent must read it. A View that names types
    without a Shape makes no Shape readable. A readable Shape shows its whole
    definition, including types the View leaves out.
15. `view.15` An item outside the View reads as missing. **Your job:** never
    tell the person that a File or entity does not exist when a limited
    credential could not find it (problem [hidden-reads-as-missing](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md)).
16. `view.16` Each read by a limited credential leaves a read receipt. **Your
    job:** use `penumbra access receipts <limit-id>` to show what was read.
    Take `<limit-id>` from the id that `penumbra access list` prints under
    "Limited to a View". A receipt holds the operation, the interface that
    made the read (the CLI prints it as `door`), the version and the count
    returned. It does not hold the question. Clients cannot read their own
    read receipts.

## Failure signs

* Every read by a limited credential fails with `view_republish_required`:
  problem [view-needs-republish](https://docs.pnbr.io/troubleshooting/view-needs-republish.md).
* A limited credential gets not found for something the person says exists:
  problem [hidden-reads-as-missing](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md).
* Counts under a View look small: problem [hidden-reads-as-missing](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md).
* You do not know what a credential can see: problem
  [what-can-this-credential-see](https://docs.pnbr.io/troubleshooting/what-can-this-credential-see.md).
* A publish exited with code 4: problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md).
* A client sees a File they should not: recipe [share-with-a-view](https://docs.pnbr.io/guides/share-with-a-view.md).

## Doors

| Door | Call |
| - | - |
| CLI (build the View) | `penumbra context slices`, `penumbra context slice show`, `penumbra context slice create`, `penumbra context slice update`, `penumbra context slice publish`, `penumbra context slice versions`, `penumbra context slice version`, `penumbra context slice retire` |
| CLI (limit a login, key or agent) | `penumbra access attach`, `penumbra access list`, `penumbra access remove`, `penumbra access receipts`, `penumbra keys create` and `penumbra kits connections create` with `--view` |
| CLI (check) | `penumbra access me`, `penumbra access list`, `penumbra context diff versions` |
| MCP | none. No MCP tool creates, edits, publishes, retires or attaches a View, and none reports a credential's View. Use the CLI. A connection limited to a View is refused extraction tools over MCP. |
| SDK | `context.slices` and `access` |

No CLI command invites a client. Ask the person to invite the client in the App
under **Give access**, and choose **Invite a client**.

## The CLI word

The CLI calls a View a Context Slice.

The usage lines of `penumbra access receipts` and `penumbra access remove` call
the id of a limit `<boundary-id>`.
`penumbra access list` prints it under "Limited to a View".

## HTTP reference

* [List views](https://docs.pnbr.io/api/http-views-slices-list.md)
* [Create view](https://docs.pnbr.io/api/http-views-slices-create.md)
* [Get view](https://docs.pnbr.io/api/http-views-slices-get.md)
* [Update view draft](https://docs.pnbr.io/api/http-views-slices-update.md)
* [List view versions](https://docs.pnbr.io/api/http-views-versions-list.md)
* [Publish view version](https://docs.pnbr.io/api/http-views-versions-publish.md)
* [Get view version](https://docs.pnbr.io/api/http-views-versions-get.md)
* [Read view context](https://docs.pnbr.io/api/http-views-versions-materialize.md)
* [Get context receipt](https://docs.pnbr.io/api/http-views-receipts-get.md)
* [Get context packet](https://docs.pnbr.io/api/http-views-receipts-packet.md)
* [Retire view](https://docs.pnbr.io/api/http-views-retire.md)

## Keep going

[Collection](https://docs.pnbr.io/concepts/collection.md) · [Brain](https://docs.pnbr.io/concepts/brain.md) · [Credential](https://docs.pnbr.io/concepts/credential.md) · [Share part of a project with a View](https://docs.pnbr.io/guides/share-with-a-view.md) · [A View does not follow a Shape change until it is published again](https://docs.pnbr.io/troubleshooting/view-needs-republish.md) · [Something outside the View reads as not found](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md) · [You do not know what your credential can see](https://docs.pnbr.io/troubleshooting/what-can-this-credential-see.md)

Penumbra Grammar 0.6.26


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