docs: entity-scoped API key recipe + control/data plane model

[marslavish]

Summary

• constructive-principals: new entity-scoped-keys.md reference — end-to-end recipe (entity type → scoped principal → step-up → createApiKey → use/revoke) with the create-time-scoping probe, the flat createPrincipal SDK gap, live-proven verifyPassword semantics (wrong password → result: null), and the identity-user-id vs principal-row-id distinction
• constructive-architecture: control plane vs data plane section (endpoints, tokens, operations) and the modules.<host> endpoint in the map
• features.md: routing row for principals/API keys

Review notes

• All behavioral claims were verified against a live deployment during the tooling task's QA run (mint, revoke, step-up window, PRINCIPAL_NOT_OWNED on the row id)

[devin-ai-integration]

Follow-up commit: giving each fact one owner

The plane model and the routing row are exactly the gaps we had — three skills (constructive-gotchas, constructive-troubleshooting, constructive-harness) already said "control-plane endpoint" with no canonical definition anywhere, and the modules.<host> row was missing from the endpoint map. Those stay as you wrote them; I only added back-links from those three so their mentions now resolve to your new section.

The rest of the review was about duplication: entity-scoped-keys.md re-taught three things that already have owners in this repo. I pushed a commit onto this branch that redistributes them rather than reverting anything — same facts, one home each.

What moved where

Fact	Was	Now lives in
Entity-type provisioning (Step 0)	Inlined in entity-scoped-keys.md, with a different call shape (modules.entityTypeProvision…unwrap()) than the existing doc (db.entityTypeProvision…execute(), outMembershipType)	constructive-entities/references/orm-provisioning.md — which already covered this in 237 lines. It was only missing your two new facts, so I added them there: the control-plane endpoint/token, and registration immutability (delete drops the registration, not the table)
createApiKey mint / step-up / revoke / bearer usage (Steps 3–4)	Inlined; also already stated in constructive-principals/references/api-keys.md and constructive-secrets-config §3.1	api-keys.md — now carries your verify-and-retry snippet plus the live-proven verifyPassword semantics (wrong password → result: null, same-session requirement), and the principalId row documents identity-user-id vs row id → PRINCIPAL_NOT_OWNED. secrets-config §3.1 now links there instead of restating
The entityIds create-time-scoping probe (Step 1)	Inlined	org-scoping.md — that file already owns "how a principal gets scoped", so both surfaces and the probe now sit side by side in one table

Two things worth flagging beyond placement

1. The recipe said the generated db.principal.create is broken (nested { principal } vs the flat deployed input) while the same skill's ORM quick-reference table advertises db.principal full CRUD. Both shipped unmarked in one skill — I annotated the table row so a reader hits the caveat where they'd hit the API.
2. I'd treat CreatePrincipalInput.entityIds vs principalEntity as SDK/schema version skew, not two durable deployment variants — documenting a probe as the permanent contract bakes the skew in. Kept the probe, date-stamped it (observed 2026-08), and framed it as a compatibility check. Both the flat-input mismatch and this are worth an issue against the SDK so the docs aren't the only record.

Net effect: entity-scoped-keys.md goes from 126 lines of re-explanation to ~50 lines of what's genuinely specific to entity scoping — a plane/token table for the 5 steps, the three constraints that fix the order, and the createPrincipal gap. Everything else links out, matching the AGENTS.md convention (SKILL.md router → focused reference per topic, cross-link rather than restate).

Happy to drop any of it if you disagree with a call.