docs(spec): Credential Kind — design spec for RHOAIENG-55817

[markturansky]

Summary

• Introduces Credential as a first-class Ambient Kind in the platform data model spec
• Adds docs/internal/design/credentials-session.md — full design spec with ERD, ownership model, API/CLI reference, usage examples, and open questions
• Updates docs/internal/design/ambient-model.spec.md to reflect the desired state: new Credential entity, RoleBinding.scope extended with credential, new roles (credential:owner, credential:reader), Credentials API and CLI sections

What this is

This is a spec-only PR — no code changes. The goal is design review before implementation begins. The reconciler will use this spec as the desired state to surface implementation gaps.

Key design decisions captured:

• Credential is platform-scoped (not project/agent-scoped) to support shared Robot Accounts
• Ownership via RoleBinding(scope=credential, role=credential:owner) — consistent with Agent ownership pattern
• Token is write-only; never returned via standard REST API
• Scope hierarchy (agent → project → global) for credential resolution at session ignition
• Runner token endpoint shape is marked TBD (open question in the design doc)

Test plan

• Design review — read docs/internal/design/credentials-session.md
• Verify ERD changes in ambient-model.spec.md are consistent with the design doc
• Answer open questions in credentials-session.md before implementation begins

Closes RHOAIENG-55817 (design phase)

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: a1d14a6e-53e4-49ae-8cab-6dd2b34ef3bd

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/RHOAIENG-55817-credentials-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[jwm4]

The basic idea here seems sound: it feels like credentials should be an important part of a data model. The enumerated types of credentials seem well aligned with the particular services that are of high priority for the platform. I'm not clear on how the "other" type credentials are intended to work or what purpose they are at this point so I have comments, but I'm not marking this as "request changes" because maybe everything here is fine and I just don't understand it.

[markturansky]

@jwm4 per our convo in slack, removing 'other'. that use case will be covered with BYOMCP.

[markturansky]

'other' removed. tests are green. validated locally. merging.