[codex] Add shared API SDK MCP shape profile

AGENTS.md

@@ -63,6 +63,34 @@ Use these defaults unless a repo-local task says otherwise:
 - Do one repo per PR unless the change is pure documentation.
 - Prefer complete migrations over partial churn: manifest updates, lockfiles,
   formatting, lint inheritance, docs, and verification should land together.
+- Keep public surfaces in sync by default. When a route, JSON-RPC method, schema,
+  SDK method, MCP tool, CLI command, fixture, README table, or generated client
+  changes, update every derived or mirrored surface in the same slice and add or
+  run the drift check that proves they still agree. Prefer generated or
+  fixture-pinned contracts over hand-maintained parallel descriptions. Treat
+  auth headers, env vars, CLI flags, timeout names, output formats, idempotency
+  fields, and SDK error shapes as public surface too. New client-facing HTTP
+  auth should prefer `Authorization: Bearer <token>` with any legacy
+  `x-<service>-api-key` header kept only as a documented compatibility alias
+  backed by the same verifier. If a repo exposes CLI and SDK clients, their
+  config names, auth precedence, timeout behavior, JSON output mode, and error
+  fields should match the shared API/SDK/MCP shape profile unless the PR records
+  a tested repo-local exception. For any client-facing repo that adds or changes
+  SDK, CLI, MCP, auth, or error behavior, add or update a client-surface manifest
+  matching `docs/client-surface-manifest.schema.json` and run
+  `scripts/audit-client-surface.py` or the repo-local copy of that check.
+- Do not let CLI, SDK, MCP, docs, examples, and manifests drift apart. Public
+  client-facing changes are not complete until every mirrored surface uses the
+  same canonical operation names, `base_url`/`token`/`timeout_ms` client config,
+  `--base-url`/`--token`/`--token-file`/`--timeout-ms`/`--output`/`--json` CLI
+  flags, service-prefixed `<SERVICE>_TOKEN` env vars, shared Bearer auth
+  semantics, and normalized `code`/`message`/`status`/`details`/`request_id`/
+  `retryable` error fields. Use
+  `python3 scripts/audit-client-surface.py --print-template <service>` when a
+  repo needs a new manifest, then keep that manifest in sync in the same PR as
+  the code, docs, fixtures, and generated clients. The long-term target is that
+  these repos can share one SDK transport/auth/error core; every repo-local
+  exception should be visible, tested, and temporary.
 - If an agent is already active on a PR, its next sequence of turns should first
   reconcile that repo/PR with the ecosystem pipeline before adding unrelated
   product scope. Treat `scripts/ecosystem-pipeline.sh report` as the handoff
@@ -106,8 +134,15 @@ Delete each item only after it is complete and verified.
 - [ ] Finish repo-local rename migrations so package names, binary names,
   generated clients, docs, fixtures, and local checkout folders converge on the
   Tempera product names above. Do not rename GitHub repositories through
-  automation unless the user explicitly asks for remote repo renames.
+  automation unless the user explicitly asks for remote repo renames. Use
+  `python3 scripts/check-local-checkouts.py --root <ecosystem-workspace>` to
+  audit legacy checkout names and print safe alias/remote commands before any
+  filesystem rename.
 - [ ] Enforce `docs/architecture-uniformity.md` across every repo. Remove
   repo-local exceptions unless they have benchmark, security, or product evidence.
+- [ ] Make `scripts/check-api-contracts.py` pass for the full configured API
+  registry. `data-engine` is the reference; Palette, cradle, and tempo remain
+  migration targets until their OpenAPI/MCP surfaces use the shared
+  project-scoped operation, error, pagination, idempotency, and conflict rules.
 - [ ] Promote `scripts/ecosystem-pipeline.sh gate` to the required CI path once
   `report` mode has no failures.

README.md

@@ -30,12 +30,26 @@ its own PR.
 - `scripts/check-ecosystem-binaries.py`: verifies declared binaries still exist.
 - `scripts/check-ecosystem-uniformity.py`: verifies manifests match the target
   state after migrations land.
+- `scripts/check-local-checkouts.py`: reports legacy checkout folder names and
+  remote mismatches without renaming user worktrees.
 - `scripts/run-ecosystem-verification.py`: runs declared per-repo verification
   commands.
 - `scripts/ecosystem-pipeline.sh`: staged report/gate pipeline for meta, repo,
   and E2E checks.
 - `scripts/watch-ecosystem-prs.py`: watches active PRs across sibling repos and
   posts one ecosystem compatibility redirect when needed.
+- `docs/api-sdk-mcp-shape.md`: shared API, SDK, CLI, auth, error, and MCP shape
+  profile for public client-facing surfaces.
+- `scripts/audit-openapi-shape.py`: portable OpenAPI profile audit for REST
+  services.
+- `scripts/check-api-contracts.py`: cross-repo OpenAPI/MCP style and conflict
+  audit that loads configured service contracts from `ecosystem.toml`.
+- `docs/client-surface-manifest.schema.json`: common manifest format for SDK,
+  CLI, auth, output, and error surfaces.
+- `docs/client-surface-manifest.example.json`: copyable known-good profile for
+  OpenAPI plus SDK, CLI, auth, error, and MCP catalog parity.
+- `scripts/audit-client-surface.py`: portable client-surface manifest audit for
+  SDK/CLI/auth parity.
 - `docs/ecosystem-pipeline.md`: pipeline and language policy.
 - `scripts/ecosystem-smoke.sh`: root smoke gate for meta-repo checks.
 
@@ -54,6 +68,9 @@ After the migration queues are complete, every repo should agree on:
 - Similar architecture in every repo: thin binaries, library-owned behavior,
   generated contracts, version/health/smoke surfaces, and documented storage
   boundaries
+- One public client-facing shape for services: canonical operation names, shared
+  error envelopes, consistent SDK config, CLI flags/env vars, auth handling, and
+  MCP/tool projections that derive from or drift-check against the same contract
 - Rust-first implementation by default, while allowing TypeScript, Python,
   platform languages, and SDK languages when they are the better fit and their
   boundary is explicit and tested
@@ -65,6 +82,12 @@ scripts/ecosystem-pipeline.sh report
 scripts/ecosystem-pipeline.sh gate
 python3 scripts/check-ecosystem-binaries.py
 python3 scripts/check-ecosystem-uniformity.py
+python3 scripts/check-local-checkouts.py --root /Users/jadenfix/Desktop/ecosystem
+python3 scripts/check-api-contracts.py --list
+python3 scripts/check-api-contracts.py --service data-engine
+python3 scripts/check-api-contracts.py --shared-gateway
+python3 scripts/audit-client-surface.py --print-template cradle
+python3 scripts/audit-client-surface.py path/to/client-surface.json
 python3 scripts/run-ecosystem-verification.py --list
 python3 scripts/run-ecosystem-verification.py --repo tempo
 python3 scripts/watch-ecosystem-prs.py
@@ -74,3 +97,21 @@ scripts/ecosystem-smoke.sh
 `check-ecosystem-uniformity.py` is expected to fail until the repo-local
 migration tasks are completed. That failure is useful: it is the remaining work
 list made executable.
+
+`check-api-contracts.py` has the same migration-gate shape. The data-engine
+contract is the strict reference. Palette and cradle are configured as
+`aip-target` services so the full check reports the remaining API migration work
+until those repos adopt project-scoped paths, dotted `projects.*` operationIds,
+shared error envelopes, cursor pagination, `Operation`, `Idempotency-Key`, and
+`If-Match`/`update_mask`. Use `--service data-engine` for the current
+reference-only proof and `--shared-gateway` to prove that an unprefixed combined
+gateway has no method/path collisions.
+
+Cradle's API-alignment branch can be checked before it merges by overriding the
+configured main checkout:
+
+```sh
+python3 scripts/check-api-contracts.py --service cradle \
+  --openapi cradle:/path/to/cradle/sdks/openapi.json \
+  --mcp-catalog cradle:/path/to/cradle/crates/beatbox-server/fixtures/mcp-tools.catalog.json
+```