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

# Project

> A project is one body of work; its Files, entities, Shapes, Views and Brains belong to it, and each command works in one project.

Concept · core

> **Use when**
>
> You start a job, or you need to know which project you work in and what you may do there.

> **Looking for something else?**
>
> Which kind of credential you hold (card [Credential](https://docs.pnbr.io/concepts/credential.md)). Reading one document (card [File](https://docs.pnbr.io/concepts/file.md)).

## For

A project is the place for one body of work. It holds the Files you bring in
and the entities you extract or write from them. It holds the Shapes that give
those entities their types. It also holds the Views and Brains you share.

Work moves through a project in one direction. A File keeps its versions.
Search and extraction read the current version as passages. A citation ties an
entity to the passage that supports it. A collection groups Files, a View
includes collections, and a Brain includes a View.

Every command and tool acts on one project at a time. Orient first, so you
know which project it is and what your credential may do there.

## Use when

* You begin a job and do not yet know the project, your role or your limits.
* A command says no project is selected, or a project is not found.
* You must choose between several projects that one credential reaches.
* You need a short picture of what a project holds before you search it.

## Not this

* Which credential you hold and what it can do: use card [Credential](https://docs.pnbr.io/concepts/credential.md).
* Reading, replacing or trashing one document: use card [File](https://docs.pnbr.io/concepts/file.md).

## Rules

1. `project.1` Orient before you act. Run `penumbra status`. It shows who is
   signed in, the project, your role and up to four next steps. It then lists
   each command group that your credential cannot fully use or that may wait
   for approval. **Your job:** do this at the start of a job. A group that is
   not listed is fully open to you. `penumbra status --all` lists every group.
   A bare `penumbra` call prints a shorter version. Without it, you may plan a
   command your credential cannot run.
2. `project.2` The CLI chooses one project for each command, in this order: the
   `--project` flag, the `PENUMBRA_PROJECT` variable, the `penumbra.json` file,
   then the profile. **Your job:** read the project line in `penumbra status`.
   It names where the choice came from. A wrong choice writes into the wrong
   project.
3. `project.3` The command `penumbra use` writes `penumbra.json` in the current
   folder. With `--global`, it writes the profile instead. **Your job:** pass
   `--project` for one command. Use `penumbra use` only when the person wants
   the choice to last.
4. `project.4` A project command needs a project. **Enforced:** with none
   chosen, the CLI exits with code 2 and `project_not_selected`. It then lists
   the projects your credential reaches.
5. `project.5` A project API key reaches one project. A person's session or a
   connected agent can reach several, and `penumbra projects list` shows them
   with your role. **Enforced:** `penumbra use` refuses a project you cannot
   reach with `project_not_found`, except when you hold a key. **Your job:** pick
   from that list. A project that does not exist and one you may not enter look
   the same.
6. `project.6` Your role and credential limit what you can do. **Your job:** ask
   before you plan around a command you doubt. Run
   `penumbra status --explain "<command>"`. It says whether the command would
   run, wait for approval, or be refused, and why.
7. `project.7` One MCP connection can serve several projects. The tool
   `penumbra_projects` lists them and their IDs. With one project, calls use
   it. **Enforced:** with more than one, a project tool call uses its
   [project](https://docs.pnbr.io/concepts/project.md) field, else the session's project from `use_project`. With
   neither, the call is refused with `project_required`. **Your job:** call
   `use_project` once when you work in one project. Pass [project](https://docs.pnbr.io/concepts/project.md) to act in
   another project for one call. A client without an MCP session must pass
   [project](https://docs.pnbr.io/concepts/project.md) on each call.
8. `project.8` The tool `project_overview` returns a short summary: up to five
   recent Files, eight collections, eight Shapes and eight workspaces. **Your
   job:** read "not granted" or "unavailable" as unknown, never as empty. The
   result lists each missing section, and it never widens your grants.
9. `project.9` Each project tool result names its project: the [project](https://docs.pnbr.io/concepts/project.md)
   field and a last line, `Project: <name> (<id>)`. **Your job:** check that
   line before you report or change anything. A wrong project means a wrong
   answer.
10. `project.10` A connection reaches only the projects its owner added.
    **Enforced:** the tool `request_project_access` asks the person to add one
    of their existing projects. Nothing changes until they approve in the
    browser, and they choose the access, at most their own role. **Your job:**
    give the person the `review_url`, then poll `project_access_status`. After
    approval, refresh the tool list. To start a new project, use
    `request_project_creation`.
11. `project.11` A project's Grammar is Penumbra's rules for this project's own
    types, written from its Shapes. It names the Shapes, types and
    relationships and lists the recipes. A project keeps no File for it. In a
    repository, `penumbra domain sync` writes `.penumbra/` beside
    `penumbra.json`. `GRAMMAR.md` is the Grammar. `types/` holds the TypeScript
    of each published Shape. `lock.json` holds the digest of each file and the
    artifact of each Shape. Commit the folder like a lockfile. **Enforced:**
    `penumbra domain sync --check` writes nothing and exits 3 when a file is
    missing, differs or is not a published Shape. It changes only when a Shape
    or the Grammar's text changes, so run it in CI. A reader limited to a View
    gets only the Shapes it may see. **Your job:** when you start work in a
    project, read `.penumbra/GRAMMAR.md` if the repository has it. Otherwise
    call the `grammar` tool with no arguments. Use only the types it lists.
    After a Shape is published, run `penumbra domain sync` and commit the
    result. The folder is as current as the last sync, so call `grammar` with no
    arguments when a type you need is missing.

## Failure signs

* A command says no project is selected: rule [project.4](https://docs.pnbr.io/concepts/project.md#rule-project-4).
* A command writes into a project the person did not mean: rule [project.2](https://docs.pnbr.io/concepts/project.md#rule-project-2).
* Everything reads as missing, or the counts look small: problem
  [hidden-reads-as-missing](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md).
* You do not know what your credential can see: problem
  [what-can-this-credential-see](https://docs.pnbr.io/troubleshooting/what-can-this-credential-see.md).
* Text names a tool this connection does not have: problem
  [tool-named-but-missing](https://docs.pnbr.io/troubleshooting/tool-named-but-missing.md).
* A tool call is refused with `project_required`: rule [project.7](https://docs.pnbr.io/concepts/project.md#rule-project-7).
* The person names a project that `penumbra_projects` does not list: rule
  [project.10](https://docs.pnbr.io/concepts/project.md#rule-project-10).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra`, `penumbra status`, `penumbra projects list`, `penumbra use`, `penumbra whoami`, `penumbra guide` |
| MCP (default) | `project_overview`, `penumbra_projects`, `use_project`, `request_project_access` and `project_access_status` in the default catalog. |
| MCP (full catalog) | `project_overview`, `penumbra_projects` and `use_project`. |
| MCP (Kits) | `project_overview` in every Kit that selects it, such as the Files Kits. A Kit serves one project, so it has no `penumbra_projects`. |
| SDK | `platform.me.projectScopes.list` lists the projects a credential reaches. `accessProfile` on a project reads the role and what each command family allows. |

On a Kit, `project_overview` fills only the sections that the Kit's other read
tools back. On MCP, the tool list follows your current access. Refresh it at the start of
each client session.

## Keep going

[Credential](https://docs.pnbr.io/concepts/credential.md) · [Find out where you stand in a project](https://docs.pnbr.io/guides/orient.md) · [File](https://docs.pnbr.io/concepts/file.md) · [Search](https://docs.pnbr.io/concepts/search.md) · [Workspace](https://docs.pnbr.io/concepts/workspace.md)

Penumbra Grammar 0.6.26


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