Skip to main content
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). Reading one document (card File).

​
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.
  • Reading, replacing or trashing one document: use card File.

​
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 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 to act in another project for one call. A client without an MCP session must pass project 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 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

​
Doors

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 · Find out where you stand in a project · File · Search · Workspace