docs: consumers setting permissions must grant the union of all executor jobs (startup_failure footgun)

Summary

A consumer job that sets an explicit permissions: block when calling claude-orchestrator.yml must grant the union of all downstream executor jobs' permissions — not just what the chosen path needs. GitHub validates the permissions of every job in the called reusable-workflow tree at startup, including jobs gated off by if: for the selected provider. Under-granting yields an instant startup_failure with no API-visible annotation (only the web UI shows the reason), which is painful to diagnose.

Repro

A codex (openai-mantle) consumer that only needs read + OIDC:

jobs:
  codex-review:
    permissions:
      id-token: write
      contents: read        # <-- too low
      pull-requests: write
    uses: dotCMS/ai-workflows/.github/workflows/claude-orchestrator.yml@v3.1.0
    with:
      trigger_mode: automatic
      model_id: openai.gpt-oss-120b
      bedrock_role_arn: ${{ vars.BEDROCK_ROLE_ARN }}

→ startup_failure in ~1s, no jobs created. Cause: the gated-off claude-anthropic job (claude-executor.yml) declares contents: write + issues: write, which exceed the caller's grant. The openai path never runs that job, but its static permissions are still validated.

Fix (works)

Grant the union of every executor's declared permissions:

    permissions:
      id-token: write
      contents: write
      pull-requests: write
      issues: write

Consumers that omit permissions: entirely inherit the repo default and sidestep this (which is why the existing infrastructure-as-code consumer never hit it).

Ask

• Add a consumer permissions section to CLAUDE.md / README.md stating the union requirement and listing the executors' declared scopes (claude-executor: contents/pull-requests/issues/id-token: write; codex/bedrock-generic: contents: read, pull-requests/id-token: write).
• Optionally: have the orchestrator docs recommend the minimal safe block above.

Found during the v3.1.0 codex e2e (see the GPT-5.x availability issue for context).

Start by reading CLAUDE.md, README.md, and the executor permission declarations referenced in the issue. Add consumer guidance explaining that callers must grant the union of all executor scopes, including the minimal safe block, and verify the documented scopes match the listed workflows.