[freeqaz]

Problem

A non-admin console walk that followed the IAM guide (dogfood finding D738) hit three gaps in docs/guides/topics/iam.md:

• An operator given Agent deploy without Secret operate on the bound Secrets was refused at deploy time; the guide does not say deploying needs it apart from update.
• The Agent Access tab offers only Share Agent, which grants full native administration. The guide does not say so, so a reader may use it for the limited "run an existing Agent" set.
• A person's principalId is shown once, in the account-creation response. The guide gives no way to read it again.

Change

• After step 2 of Add a person: no API lists accounts; with GitHub, Google or OIDC sign-in, GET /api/auth/accounts/$USER_ID returns principalId, and a signed-in person finds USER_ID in GET /api/auth/session.
• Let a person run an existing Agent: deploying needs operate on each Secret and credential source the Agent binds, also without update; the console has no form for these grants, and Share Agent grants full native administration, so use the CLI or HTTP API.

The product gaps behind these (no console least-privilege grant form; no principal ID lookup on a password-only Installation) are recorded separately, not changed here.

Verification

• Checked against the source: getAgentSecretPermissions/deployAgentWithAuthorization (deploy authorizes caller Secret operate on each bound Secret and a Secret authentication source), getAuthAccount (returns principalId, needs external sign-in), getAuthSession (user.id), and the Agent sharing guide.
• Docs-only change: Prettier on the file; no tests (per AGENTS.md). Page stays under the 1,500-word review threshold by a local estimate; CI Static Checks is the authority.

Risks

• Documentation only.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge.

What this changes

The IAM guide explains deployment credential permissions, Share Agent’s native administration grant, and how administrators can retrieve a person’s principal ID.

Example: An administrator grants Agent deploy access for an Agent with a bound Secret.

• Before: The guide does not explicitly explain that deployment requires Secret operate even without Agent update.
• After: The guide explicitly tells the administrator to grant operate on each bound Secret and credential source.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Useful, focused documentation with source-backed claims and no actionable findings; runtime proof is inapplicable.
Proof confidence	🌊 off-meta tidepool	Not applicable: Documentation-only clarification verified against current source and existing feature references; runtime proof is not required.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Administrators can miss deployment credential grants, confuse native administration with limited Agent operation, or fail to recover a principal ID.
Reason: The collaborator-authored clarification documents existing contracts and keeps broader product gaps outside this PR.

Merge readiness

✅ Ready for maintainer review

Keep this PR open: it makes useful, source-backed IAM documentation corrections, with no actionable defects found; collaborator authorship and repository policy also require keeping it open.

Priority: P3
Reviewed head: bbf2118eafc06e935095e3c2ed4217aacb192fec

Before merge

None.

Findings

None.

Agent review details

How this fits together

The IAM guide helps administrators translate account identities and intended Agent access into exact-resource Roles and AccessBindings enforced by the controller.

flowchart LR
  A[Administrator] --> B[IAM guide]
  B --> C[Account inspection API]
  B --> D[Roles and AccessBindings]
  D --> E[Controller authorization]
  E --> F[Agent deployment]

Loading

Technical review

Best possible solution:

Land the focused guide clarification while preserving the existing authorization and sharing contracts.

Do we have a high-confidence way to reproduce the issue?

The main-branch guide omits these explicit explanations, while controller authorization, account routes, and the existing sharing reference establish the documented behavior.

Is this the best way to solve the issue?

The small additions address the reported guidance gaps in their existing owning guide without changing permissions or promising unsupported account discovery.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 45aaad657728.

Provenance checked

• IAM provisioning and account identifiers keeps the original intent (58621a8: Provide a valid account-provisioning example and an exact-resource access procedure; later guidance retained account IDs for external identity attachment.)
• Existing-Agent operation grants keeps the original intent (40dd5fe: Document the grants a non-admin person needs to run an existing Agent, including Secret operate and per-revision access.)
• Agent revision terminology keeps the original intent (69097a7: Preserve official resource names and distinguish Agent revisions from general deployment versions.)

Security

None.

Evidence

What I checked:

• Focused documentation change: The pinned introduction diff changes only the IAM guide, adding account lookup guidance and clarifying deployment permissions and sharing scope. (docs/guides/topics/iam.md:70, bbf2118eafc0)
• Deployment authorization matches the clarification: Deployment invokes authorizeBindings for Configuration Secrets and admits Harness authentication and credential sources; authorizeBindings checks caller operate on every bound Secret independently of Agent update. (packages/occ/src/index.ts:9743, 45aaad657728)
• Account lookup contract: Account inspection returns principalId, requires a human Installation administrator and trusted Origin, and refuses the password-only profile when readAccount is unavailable; the surrounding guide already establishes the administrator session. (apps/controller/src/index.ts:3444, 45aaad657728)
• Sharing scope is already documented: The existing sharing reference defines namespace read plus exact-Agent read and administer, warns about full native administration, and explicitly excludes deployment, Configuration, Secret and stop permissions. (docs/reference/console/agent-sharing.md:9, 45aaad657728)
• Feature history and original intent: The guide’s provisioning and existing-Agent procedures were introduced in docs(iam): fix account provisioning example, add an add-a-person guide and create --help samples #715 and docs(iam): list the grants that let a person run an existing agent #1601; this PR preserves their exact-resource grant model. Follow-history inspection reached the documented missing-object boundary at the earlier rename. (docs/guides/topics/iam.md:189, 40dd5fe26e92)
• Discussion and policy: The full PR body and both comments were read; comments contain automated status updates and no substantive objections. Root AGENTS.md applies, no nested documentation instructions were found, and no maintainer-notes directory or pr-simplify skill was present. No tests or builds were run under the read-only review rules. (AGENTS.md, bbf2118eafc0)

Likely related people:

• freeqaz: Raw commit 40dd5fe adds docs/guides/topics/iam.md:130 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 40dd5fe26e92; files: docs/guides/topics/iam.md)

Labels

Label changes:

• add P3: This is a focused documentation correction for administrator IAM workflows without runtime changes.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

• P3: This is a focused documentation correction for administrator IAM workflows without runtime changes.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 25, 2026, 8:27 PM ET / October 26, 2026, 00:27 UTC.