Skip to main content
Guide · core

Use when

You start a job, or a command is refused or held, or a read is smaller than expected. You do not yet know your project, role or limits.

Looking for something else?

Deciding what to do about a refusal or a held change (problem change-waits-for-approval). Learning how to do a job (read the Grammar).

​
Outcome

You can state five facts: the project, who you act as, your role, what limits your reads, and which changes would wait for a person. You read each from Penumbra, not from a guess.

​
Before you start

  • You have a way in: a stored login (penumbra login), a key in PENUMBRA_TOKEN, or an MCP connection. If you have none, ask the person to sign in or to give you a key.
  • Do not plan any change yet.

​
Steps

  1. Look at the project and the credential in one view.
    • CLI: penumbra with no arguments. Expect the project name and a line <org>/<project> · <source>. The source says where the choice came from: This folder, Saved in profile, Environment or Command flag. A short list of next commands follows. It prints no credential line: penumbra whoami names the credential (step 2). With no credential it says Not signed in. Start here. and lists penumbra login.
    • MCP: project_overview. A section that reads “not granted” or “unavailable” is unknown, not empty (card rule project.8).
  2. Name your credential (card rule credential.1).
    • CLI: penumbra whoami. Expect a credential: line, such as session via browser sign-in for a person or key for a key. Read the source in brackets: a key in PENUMBRA_TOKEN hides a stored login (card rule credential.2). This command does not check that Penumbra accepts the credential. A refused key shows at the first real command as authentication_invalid.
  3. Settle the project (card rules project.2 to project.5).
    • CLI: read the project: line of penumbra whoami. If the project is wrong or missing, run penumbra projects list, then pass --project <org>/<project> for one command. Run penumbra use <org>/<project> only when the person wants the choice to last.
    • MCP: penumbra_projects lists the projects and their IDs. With more than one project, call use_project once, or pass project on each call (card rule project.7). A project the person names that is not listed needs request_project_access (card rule project.10).
  4. Read your role and what limits your commands (card rule project.1).
    • CLI: penumbra status. Expect In <org>/<project> (from <source>) you are an owner (or admin, editor, viewer), then Next: with up to four commands. A person with full access then reads that every command is open. A key, a View or a Kit reads Not fully available: with one line for each limited group, and the commands that may wait for approval. penumbra status --all prints one line for every command group.
  5. Read what limits you.
    • CLI: penumbra access me. Expect one of two answers. Either you read the whole project, as your role allows, or you read only a named View (card rule credential.3, problem what-can-this-credential-see).
  6. Read the project’s Grammar (card rule project.11). Expect the project’s Shapes with their types and relationships, and the list of recipes. A project with no Shape lists none, and a View limits the list to the Shapes you may see; step 5 tells which.
    • Repository: read .penumbra/GRAMMAR.md beside penumbra.json. If the folder is missing, run penumbra domain sync and commit it.
    • No repository: call the grammar tool with no arguments (MCP), or run penumbra domain sync in a folder with a penumbra.json.
  7. Ask before you plan a change that might not run (card rule project.6).
    • CLI: penumbra status --explain "<command>" for each command you plan. Expect <command>: would run. and a reason line. A command that waits for approval or is refused says so, with the reason. The answer does not warn that a submit or a publish may wait (card rule approval.2). It shows no missing scope on a View command (card rule credential.3).
  8. See what already needs a person.
    • CLI: penumbra attention. Expect attention: <org>/<project>, as of <time> and either nothing is waiting for you or a list of workspaces to review, approvals and running work.
  9. See what the project holds, in a few calls.
    • CLI: penumbra shapes types for the types, penumbra files collections list for the collections, and penumbra files list --limit 5 for the newest Files.
    • MCP: the sections of project_overview that were not “unavailable”.
  10. Read the Grammar for the job you will do.
    • CLI: penumbra grammar search "<the job in your words>".
    • MCP: grammar with howto set to the job.

​
Check

  • You can fill in the five facts of the Outcome from the outputs of steps 2, 3, 4, 5 and 7.
  • penumbra whoami and penumbra status agree on the credential and the project.
  • If the project has a Shape, you can name its types from the project’s Grammar (.penumbra/GRAMMAR.md, or the grammar tool).
  • If a section said “not granted” or “unavailable”, you wrote down that it is unknown.

​
If it goes wrong

​
Worth offering

  • Offer a short summary of the project in the person’s words: its Shapes, its collections and its newest Files.
  • Offer to check penumbra attention again after your work, so the person sees what now waits for them.
  • If you hold a key or a connection and the job needs more, offer to list the permission that the person must add.

​
Report

Say which project you work in, who you act as, and your role. Say whether a View limits what you read. Name the commands you plan that would wait for approval, and anything that came back as unknown. Do not repeat the raw output.

​
Keep going

Project · Credential · Approval · View · You do not know what your credential can see · Something outside the View reads as not found · Text names a tool that your connection does not have