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

# Find out where you stand in a project

> You know which project you work in, which credential you hold, what you may do and see there, and what waits for a person.

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](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md)). 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](https://docs.pnbr.io/concepts/project.md#rule-project-8)).
2. Name your credential (card rule [credential.1](https://docs.pnbr.io/concepts/credential.md#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](https://docs.pnbr.io/concepts/credential.md#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](https://docs.pnbr.io/concepts/project.md#rule-project-2) to [project.5](https://docs.pnbr.io/concepts/project.md#rule-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](https://docs.pnbr.io/concepts/project.md) on each call
     (card rule [project.7](https://docs.pnbr.io/concepts/project.md#rule-project-7)). A project the person names that is not listed
     needs `request_project_access` (card rule [project.10](https://docs.pnbr.io/concepts/project.md#rule-project-10)).
4. Read your role and what limits your commands (card rule [project.1](https://docs.pnbr.io/concepts/project.md#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](https://docs.pnbr.io/concepts/credential.md#rule-credential-3), problem [what-can-this-credential-see](https://docs.pnbr.io/troubleshooting/what-can-this-credential-see.md)).
6. Read the project's Grammar (card rule [project.11](https://docs.pnbr.io/concepts/project.md#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](https://docs.pnbr.io/concepts/project.md#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](https://docs.pnbr.io/concepts/approval.md#rule-approval-2)). It shows no
     missing scope on a View command (card rule [credential.3](https://docs.pnbr.io/concepts/credential.md#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

| You see | Read |
| - | - |
| `project_not_selected` and exit code 2 | card rule [project.4](https://docs.pnbr.io/concepts/project.md#rule-project-4) |
| `project_not_found` for a project that should exist | card rule [project.5](https://docs.pnbr.io/concepts/project.md#rule-project-5) |
| `authentication_invalid` or "Not signed in" | card rule [credential.1](https://docs.pnbr.io/concepts/credential.md#rule-credential-1) |
| `whoami` names a credential that is not the one you meant | card rule [credential.2](https://docs.pnbr.io/concepts/credential.md#rule-credential-2) |
| `status` says it could not confirm what the credential may do | run it again, then `penumbra whoami` |
| A key is refused for a missing scope, or as "not active" | card rule [credential.5](https://docs.pnbr.io/concepts/credential.md#rule-credential-5) |
| Everything reads as missing, or counts look small | problem [hidden-reads-as-missing](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md) |
| A tool in the text is not in your tool list | problem [tool-named-but-missing](https://docs.pnbr.io/troubleshooting/tool-named-but-missing.md) |
| A command returned `pending` or exit code 4 | problem [change-waits-for-approval](https://docs.pnbr.io/troubleshooting/change-waits-for-approval.md) |

## 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](https://docs.pnbr.io/concepts/project.md) · [Credential](https://docs.pnbr.io/concepts/credential.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [View](https://docs.pnbr.io/concepts/view.md) · [You do not know what your credential can see](https://docs.pnbr.io/troubleshooting/what-can-this-credential-see.md) · [Something outside the View reads as not found](https://docs.pnbr.io/troubleshooting/hidden-reads-as-missing.md) · [Text names a tool that your connection does not have](https://docs.pnbr.io/troubleshooting/tool-named-but-missing.md)

Penumbra Grammar 0.6.26


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