Document Shelly permission baseline

Distinguish the GitHub App installation permissions from caller github.token permissions and document the Dependabot private-key trust boundary.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

docs/content/guides/github-app-authentication.md

@@ -33,11 +33,30 @@ jobs:
 The root reusable workflow forwards these two values to the Plan, Build-Module, and Publish-Module reusable jobs.
 Do not use `secrets: inherit` as a substitute for this mapping.
 
-For Dependabot pull requests, create `SHELLY_CLIENT_ID` and `SHELLY_PRIVATE_KEY` as Dependabot secrets as well as
-Actions secrets. Dependabot-triggered workflows cannot read regular Actions secrets, so the GitHub App token cannot
-be minted without separate Dependabot secret values.
+Dependabot-triggered workflows cannot read regular Actions secrets. Do not duplicate Shelly's private key into
+Dependabot secrets by default: a compromised dependency update could alter workflow code that receives the key before
+human review. If an organization requires the Process-PSModule workflow to run on Dependabot pull requests, its
+security owners must explicitly accept that trust boundary and provision separate Dependabot secrets. Otherwise,
+skip token-consuming jobs for Dependabot pull requests and run the full workflow after review or merge.
 
-## Token scope
+## GitHub App installation permissions
+
+Install Shelly only on repositories that the process must manage. The complete permission baseline for the current
+Process-PSModule GitHub App path is:
+
+| Repository permission | Access | Why it is needed |
+| --- | --- | --- |
+| Contents | Write | Read releases during version resolution; create, upload to, and delete releases during publish and cleanup. |
+| Pull requests | Write | Read pull-request files and labels; add process and release comments to pull requests. |
+| Metadata | Read | Read repository description, topics, and URL while building the module manifest. This permission is granted automatically to GitHub Apps. |
+
+Do not grant Shelly Actions, Issues, Statuses, Pages, Workflows, or administration permissions for the current
+Process-PSModule GitHub App path. Those permissions are not used by installation tokens minted here.
+
+The caller workflow's `permissions:` block is separate: it scopes only `github.token` for non-App operations such as
+artifact handling, linting, and Pages deployment. It cannot expand or restrict Shelly's installation token.
+
+## Per-workflow token scope
 
 Each job mints its own token with the repository that triggered the workflow:
 `${{ github.event.repository.name }}`.

docs/content/reference/workflow-inputs.md

@@ -35,9 +35,10 @@ credentials that are exposed. `secrets: inherit` is intentionally not required.
 
 See [passing test data](../guides/calling-the-workflow.md#passing-test-data) for how to build the `TestData` value.
 
-## Permissions
+## Workflow `github.token` permissions
 
-The following permissions are needed for the workflow to be able to perform all tasks.
+The following permissions are needed by the caller workflow's default `github.token` for operations that do not use
+Shelly, such as linting and GitHub Pages deployment:
 
 ```yaml
 permissions:
@@ -49,3 +50,10 @@ permissions:
 ```
 
 For more info, see [Deploy GitHub Pages site](https://github.com/marketplace/actions/deploy-github-pages-site).
+
+## GitHub App permissions
+
+The `permissions:` block above does not apply to Shelly's installation tokens. Shelly needs only the repository
+permissions documented in [GitHub App authentication](../guides/github-app-authentication.md#github-app-installation-permissions):
+Contents: write, Pull requests: write, and automatically granted Metadata: read. Each job requests a smaller,
+repository-scoped subset when it mints its token.