molecule-ai/docs
49
0
Fork 0
Code Issues Pull Requests 10 Actions Packages Projects Releases Wiki Activity

docs(platform-management-api): correct billing-mode/budget/provision surfaces #58

Closed
core-be wants to merge 0 commits from feat/docs-platform-management-api-corrections into main
pull from: feat/docs-platform-management-api-corrections
merge into: molecule-ai:main
Conversation 0 Commits - Files Changed -
+787
core-be commented 2026-06-01 06:43:35 +00:00
Member
Copy Link
Copy Source

Review fixes for PR #57, all verified against the #2056 OpenAPI SSOT (molecule-core workspace-server/docs/openapi/management.yaml on feat/openapi-management-spec) and the authoritative handler/client source.

  1. [HIGH] Billing-mode is a TENANT route, not CP. Rewrote tasks.mdx, reference.mdx, auth-model.mdx (+index.mdx note): it is PUT/GET /admin/workspaces/:id/llm-billing-mode on the tenant host, auth = Org API Key + X-Molecule-Org-Id, keyed by workspace id, body {"mode": platform_managed|byok|disabled} ({"mode":null} clears, {} -> 400). Removed the "not reachable with an Org API Key" callout and the CP llm-billing-mode reference row.
  2. [HIGH] Provision/deprovision moved to the stable /api/v1/workspaces/* surface (tasks.mdx, reference.mdx, auth-model.mdx, index.mdx). Deprovision security = provisionSecret (Authorization: Bearer) + the per-tenant admin token in X-Molecule-Admin-Token (verified in cp_provisioner.go), not Authorization / X-Molecule-Org-Id.
  3. [MED] Pinned budget route (GET/PATCH /workspaces/:id/budget, tenant, Org API Key, canonical multi-period budget_limits map per budget.go) and the billing-mode mode enum; dropped the "verify against handler" hedges on both.
  4. [LOW] Added the disabled enum value wherever billing-mode was described.
  5. [LOW] Fixed the broken anchor: scoped-roles--coming-soon (em-dash slugifies to a double hyphen; verified against built HTML).

Fumadocs build (next build) green; all internal links + heading anchors resolve, including the corrected scoped-roles anchor.

Co-Authored-By: Claude Opus 4.8 (1M context) noreply@anthropic.com

Review fixes for PR #57, all verified against the #2056 OpenAPI SSOT (molecule-core workspace-server/docs/openapi/management.yaml on feat/openapi-management-spec) and the authoritative handler/client source. 1. [HIGH] Billing-mode is a TENANT route, not CP. Rewrote tasks.mdx, reference.mdx, auth-model.mdx (+index.mdx note): it is PUT/GET /admin/workspaces/:id/llm-billing-mode on the tenant host, auth = Org API Key + X-Molecule-Org-Id, keyed by workspace id, body {"mode": platform_managed|byok|disabled} ({"mode":null} clears, {} -> 400). Removed the "not reachable with an Org API Key" callout and the CP llm-billing-mode reference row. 2. [HIGH] Provision/deprovision moved to the stable /api/v1/workspaces/* surface (tasks.mdx, reference.mdx, auth-model.mdx, index.mdx). Deprovision security = provisionSecret (Authorization: Bearer) + the per-tenant admin token in X-Molecule-Admin-Token (verified in cp_provisioner.go), not Authorization / X-Molecule-Org-Id. 3. [MED] Pinned budget route (GET/PATCH /workspaces/:id/budget, tenant, Org API Key, canonical multi-period budget_limits map per budget.go) and the billing-mode mode enum; dropped the "verify against handler" hedges on both. 4. [LOW] Added the `disabled` enum value wherever billing-mode was described. 5. [LOW] Fixed the broken anchor: scoped-roles--coming-soon (em-dash slugifies to a double hyphen; verified against built HTML). Fumadocs build (next build) green; all internal links + heading anchors resolve, including the corrected scoped-roles anchor. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
core-be added 2 commits 2026-06-01 06:43:36 +00:00
docs: add Platform Management API developer guide
Secret scan / secret-scan (pull_request) Successful in 14s
Details
CI / build (pull_request) Successful in 1m4s
Details
sop-checklist / all-items-acked (pull_request) acked: 0/7 — missing: comprehensive-testing, local-postgres-e2e, staging-smoke, +4 — body-unfilled: 7
Details
sop-checklist-gate / gate (pull_request) Successful in 3s
Details
10e3b0c0e3 
Adds a developer-facing Platform Management API section under
content/docs/platform-management-api/, filling the gap where the only
machine-readable spec was a /schedules-only swaggo stub.

Pages:
- index: two-service architecture (CP vs tenant), when to call which host
- getting-started: the Org API Key path (common entry point) + tenant-root
  security caveat
- auth-model: all six credential types (WorkOS session, CP admin bearer,
  provision-secret, Org API Key, per-workspace token, ADMIN_TOKEN) + the
  credential -> route tier matrix
- tasks: provision workspace, set workspace/org secret, mint/revoke Org API
  Key, create org from template, set billing-mode/budget — each with exact
  request + CLI + MCP equivalents
- reference: derives from / links to the OpenAPI SSOT
  (molecule-core workspace-server/docs/openapi/management.yaml) as the
  contract; does not re-author endpoint definitions

Endpoint shapes derive from the OpenAPI management spec (single source of
truth); prose/guides are written around it. Uncertain details are marked
"verify against handler". No secret values. Fumadocs next build green
(115/115 static pages); internal links + heading anchors verified.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
docs(platform-management-api): correct billing-mode/budget/provision surfaces
CI / build (pull_request) Waiting to run
Details
sop-checklist-gate / gate (pull_request) Waiting to run
Details
Secret scan / secret-scan (pull_request) Successful in 6s
Details
8e20336e67 
Review fixes for PR #57, all verified against the #2056 OpenAPI SSOT
(molecule-core workspace-server/docs/openapi/management.yaml on
feat/openapi-management-spec) and the authoritative handler/client source.

1. [HIGH] Billing-mode is a TENANT route, not CP. Rewrote tasks.mdx,
   reference.mdx, auth-model.mdx (+index.mdx note): it is
   PUT/GET /admin/workspaces/:id/llm-billing-mode on the tenant host,
   auth = Org API Key + X-Molecule-Org-Id, keyed by workspace id,
   body {"mode": platform_managed|byok|disabled} ({"mode":null} clears,
   {} -> 400). Removed the "not reachable with an Org API Key" callout
   and the CP llm-billing-mode reference row.
2. [HIGH] Provision/deprovision moved to the stable /api/v1/workspaces/*
   surface (tasks.mdx, reference.mdx, auth-model.mdx, index.mdx).
   Deprovision security = provisionSecret (Authorization: Bearer) + the
   per-tenant admin token in X-Molecule-Admin-Token (verified in
   cp_provisioner.go), not Authorization / X-Molecule-Org-Id.
3. [MED] Pinned budget route (GET/PATCH /workspaces/:id/budget, tenant,
   Org API Key, canonical multi-period budget_limits map per budget.go)
   and the billing-mode mode enum; dropped the "verify against handler"
   hedges on both.
4. [LOW] Added the `disabled` enum value wherever billing-mode was
   described.
5. [LOW] Fixed the broken anchor: scoped-roles--coming-soon (em-dash
   slugifies to a double hyphen; verified against built HTML).

Fumadocs build (next build) green; all internal links + heading anchors
resolve, including the corrected scoped-roles anchor.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
core-be closed this pull request 2026-06-01 07:27:41 +00:00
Some checks are pending
CI / build (pull_request) Waiting to run
Required
Details
sop-checklist-gate / gate (pull_request) Waiting to run
Details
Secret scan / secret-scan (pull_request) Successful in 6s
Required
Details

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
merge-queue
Ready for serialized Gitea merge queue
 tier:low
Low risk
 triaged
PM triaged
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
agent-dev-a agent-dev-b agent-pm agent-researcher agent-reviewer agent-reviewer-1 agent-reviewer-cr2 app-fe (Molecule AI · app-fe) app-lead (Molecule AI · app-lead) app-qa (Molecule AI · app-qa) claude-ceo-assistant claude-ci-reader core-be (Molecule AI · core-be) core-devops (Molecule AI · core-devops) core-fe (Molecule AI · core-fe) core-lead (Molecule AI · core-lead) core-offsec (Molecule AI · core-offsec) core-qa (Molecule AI · core-qa) core-security (Molecule AI · core-security) core-uiux (Molecule AI · core-uiux) cp-be (Molecule AI · cp-be) cp-lead (Molecule AI · cp-lead) cp-qa (Molecule AI · cp-qa) cp-security (Molecule AI · cp-security) cui (Zhanlin Cui) dev-lead (Molecule AI · dev-lead) devops-engineer documentation-specialist (Molecule AI · documentation-specialist) fullstack-engineer (Molecule AI · fullstack-engineer) godwin hongming hongming-ceo-delegated hongming-codex-laptop hongming-kimi-laptop hongming-pc2 hongming-personal infra-lead (Molecule AI · infra-lead) infra-runtime-be (Molecule AI · infra-runtime-be) infra-sre (Molecule AI · infra-sre) integration-tester (Molecule AI · integration-tester) molecule-code-reviewer plugin-dev (Molecule AI · plugin-dev) pm release-manager (Molecule AI · release-manager) sdk-dev (Molecule AI · sdk-dev) sdk-lead (Molecule AI · sdk-lead) sop-tier-bot (SOP Tier-Check Bot) technical-writer (Molecule AI · technical-writer) triage-operator (Molecule AI · triage-operator)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: molecule-ai/docs#58
Delete Branch "feat/docs-platform-management-api-corrections"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?