docs(spec): add Go/TS SDK columns to data-model client reference

[markturansky]

Summary

• Extends the CLI reference section in specs/platform/data-model.spec.md into a full client reference covering hsctl, the Go SDK, and the TypeScript SDK side by side
• Adds Go SDK and TypeScript SDK columns to all eight operation mapping tables so coverage can be verified end-to-end for every REST operation
• Auth & Context rows marked N/A for both SDKs (auth is at client construction, no login flow in either SDK)
• Corrects a spec error: removed fabricated POST /roles and DELETE /roles/{id} rows that did not exist on the server; the roles handler registers only GET routes and built-in roles are seeded by database migrations (gateway:creator, platform:admin, gateway:owner, gateway:viewer)

Drift surfaced (not fixed here)

components/sdk-go/client/role_api.go and components/sdk-typescript/src/role_api.ts both contain a stale Create method calling POST /roles - a ghost from when that route was planned. The server rejects it (no handler registered). These will be cleaned up by the next make generate-sdk run once there is confidence the OpenAPI spec will not grow a POST /roles back.

Test plan

• Verify spec tables render correctly in GitHub markdown
• Confirm SDK method names match components/sdk-go/client/*_api.go and components/sdk-typescript/src/*_api.ts
• Confirm roles handler in components/api-server/plugins/roles/plugin.go registers only GET routes (no POST/DELETE)

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. 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: Repository YAML (base), Central YAML (inherited)
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 9f5588ec-31d6-417a-9b7e-92900385ee4f

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

---

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

[hypershell-delivery]

Amber review

Status: Complete

View the submitted review.

[hypershell-delivery]

Verdict

This is a clean, well-scoped documentation change that extends the client-reference tables with Go/TS SDK columns, and the SDK method names I spot-checked (Gateways().Create, roles.list, OpenShellGatewayServiceAccounts().Revoke, etc.) match the committed SDK code. The accompanying claims are mostly accurate - roles are genuinely GET-only in the OpenAPI spec and route registration - but a couple of small factual gaps are worth tightening, and there is a cross-PR coordination issue around the gateway-create interface.

Findings

See inline comments. All findings are Minor; nothing blocks merge.

1. [Minor] Seeded-roles list is incomplete - the note omits managed-cluster-registrar, which is also seeded by migration (L407). Spec Completeness
2. [Minor] The committed SDKs are currently out of sync with openapi.yaml, so the "kept in sync by the build" claim and the make generate-sdk reference need a small correction (L351). Spec Consistency

Cross-PR coordination

PR #412 redefines the Gateway create interface that this PR documents: it changes the create request's required field from cluster_id to a placement (GatewayPlacementIntent) object, adds a new GET /gateways/placement-availability endpoint, and regenerates both SDKs. This PR's client-reference tables document hsctl create gateway ... --cluster-id <c> ... plus Gateways().Create / gateways.create against the current cluster_id-based model. Maintainers should decide merge order and agree who updates the gateway-create rows (and adds the new placement-availability operation): if #412 merges first, this PR's gateway-create documentation becomes inaccurate; if this PR merges first, #412 must carry the doc update. The same SDK regeneration in #412 is also what would drop the phantom Roles().Create / roles.create methods this PR already documents as absent, so the two changes share an assumption about the post-regeneration SDK surface.

Previous concerns

No prior Amber findings exist in the review history for this pull request, so there is nothing to re-verify.

Convention Checklist

Convention	Result
No em dashes (hyphens only)	Pass
Documentation matches code/spec (SDK method names)	Pass
Documentation matches code/spec (roles read-only)	Pass
Seeded-role list complete	Fail
SDK "in sync" / build-target reference accurate	Fail

[hypershell-delivery]

The committed SDKs are currently out of sync with openapi.yaml, which makes two parts of this sentence slightly inaccurate:

1. make generate-sdk from the repo root does not exist. The root Makefile only defines generate-sdk-go (which delegates to make -C components/api-server generate-sdk). Running make generate-sdk at the repo root hits No rule to make target. Consider make generate-sdk-go (root) or make -C components/api-server generate-sdk.

2. The clients are not actually in sync right now. The committed components/sdk-go/client/role_api.go (Roles().Create) and components/sdk-typescript/src/role_api.ts (roles.create) still POST /roles, but openapi.roles.yaml defines only GET for /roles and /roles/{id} and the roles plugin registers GET-only routes - so those create methods target a nonexistent endpoint. The TS header's Spec SHA256 also differs from the current openapi.yaml hash, confirming the generated SDK predates the current spec. This pre-existing drift is consistent with your decision to omit Roles().Create/roles.create from the table, but the SDKs should be regenerated so reality matches this new wording.

[hypershell-delivery]

This list omits a seeded role: migrations also seed managed-cluster-registrar (RoleManagedClusterRegistrar in components/api-server/plugins/roles/model.go, inserted in components/api-server/plugins/roles/migration.go). Please add it so the enumerated set is complete.

[bsquizz]

🤖 Automated message posted by a robot (coordination note from the author of #447).

Cross-PR coordination with #447 (gateway access management). We expect #447 to land after this PR, so the rebase burden is on #447 -- no changes are needed here. Flagging so you are aware of what grows:

• feat(gateway-access): gateway access management (owner/admin/viewer tiers) #447 introduces a new per-gateway built-in role gateway:admin (hierarchy Owner > Admin > Viewer). When feat(gateway-access): gateway access management (owner/admin/viewer tiers) #447 rebases onto your restructured "Client Reference", it will update the seeded built-in role enumeration you add to include gateway:admin (so the list becomes gateway:creator, platform:admin, gateway:owner, gateway:admin, gateway:viewer).
• feat(gateway-access): gateway access management (owner/admin/viewer tiers) #447 appends gatewayAccess rows to the RBAC operation table (plus a GET .../access/directory entry). It will re-add those rows in your new five-column Go/TS SDK format rather than the old three-column shape.

Nothing to do on your side; this is just a heads-up that #447 will reconcile onto your table shape once this merges. If the merge order changes, let us know and we will swap who rebases.