Skip to main content

​
CLAUDE.md - docs-site/

The public developer and API documentation, published to docs.scripxhq.com with Mintlify. Read README.md for the structure and the sync tooling.

​
What this is

Everything here is client-facing and public. Guides, the /v1 API reference bound to api-reference/openapi.json, the no-key /public surface pages, and the annexure. Assume a competitor, a partner, and a crawler all read every word.

​
Invariants

  1. Document only the /v1 and /public contracts. Nothing else exists as far as this site is concerned. No internal endpoint, no operator surface, no first-party money route.
  2. Contract, not process. Inputs, outputs, errors, guarantees, and limits. Never internal process, commercial terms, pricing mechanics, or how the exchange is operated.
  3. Nothing reveals an upstream integration. Not a name, a hostname, a field, an error string, or an implied mechanic. If a sentence would let a reader infer how we obtain something, cut it.
  4. “scrips”, never “scripts”. The sync check fails on this.
  5. No em dashes and no en dashes. The sync check fails on these too.
  6. No secret value in a sample. Placeholder keys only, and they must be obviously fake. Note that an Idempotency-Key in a curl sample is a client-chosen request id, not a secret; the secret scanner is configured to know that, but do not paste anything else.
  7. Every reference page binds to exactly one spec operation through its openapi frontmatter key. Prose pages that deliberately document no operation are listed explicitly in the sync script, and you add to that list only with a reason.
  8. Every page has a unique frontmatter title and description. Duplicates break per-page SEO and the machine-readable index.
  9. Every page is reachable from navigation. An orphan page is still indexed and still unreachable by a reader.
  10. api-reference/openapi.json is a copy of what the API serves at GET /v1/openapi.json. Refresh it from the running service. Never hand-edit it.

​
Run and verify

The sync check fails, listing every offender, on: a spec operation with no page, a page with no matching operation, an operation documented twice, a missing title or description, a navigation entry pointing at a missing file, an orphan page, a duplicated title or description, and an editorial breach (a dash, or “scripts” where the instrument is a “scrip”).

​
Mintlify quirks worth knowing

  • Top-level groups cannot collapse. The expanded key governs nested groups only. That is why each tab holds exactly one top-level group whose children are the real sections: nesting turns each section into a real disclosure, so the sidebar opens with “Get started” expanded and everything else collapsed. style.css hides the shell group label, which would otherwise repeat the tab name.
  • robots.txt here overrides Mintlify’s generated one. Delete it and the generic default comes back, losing the platform directives and the explicit crawler roster. Keep it in step with the one the landing site serves.
  • style.css carries layout corrections, not just brand. Removing a rule to “clean up” tends to bring back a component the theme renders in the wrong place.

​
What not to touch

  • Do not add a page for an endpoint that is not in the published spec.
  • Do not edit api-reference/openapi.json by hand.
  • Do not change navigation without running the sync check; an orphan or a dangling entry fails CI.
  • Do not add analytics, a chat widget, or any third-party script without an explicit decision. This is a public surface with its own privacy posture.
  • Do not change the support address or the documented API base URL without confirming the real one.