Thank you for helping improve the Stack Playground and documentation host. User-facing documentation content belongs in stack-sh/docs; this repository owns the browser application, VitePress integration, static assets, and deployment.
Use Node.js 22.14 or newer and install the locked dependency graph:
npm ciRun the local quality gates:
npm run format:check
npm run lint
npm test
npm run build
npm run cloudflare:checkFormatting and linting use Oxfmt and Oxlint. The production build compiles the React Playground into dist/, validates the English, Japanese, Simplified Chinese, and Korean documentation sets, and builds VitePress with a /docs/ base into dist/docs/.
User-facing Markdown and the published CLI identity are generated by stack-sh/docs. Update scripts/docs-source.json only after the Docs change is merged, using the final commit and SHA-256 of generated/manifest.json, then run:
npm run docs:source
npm run docs:check
npm run docs:testThe generated Markdown paths under docs/ are ignored build inputs and must not be edited. A missing resource, invalid manifest, unsafe path, duplicate path, or hash mismatch fails before the fetched bundle is written.
npm run docs:check verifies the four locale inventories, heading structure, canonical code blocks, links, anchors, external URL safety, code fences, and executable Stack examples. CI also runs the documented commands with the pinned and publicly attested CLI. Use an absolute verified binary when reproducing that smoke locally:
STACK_CLI_BIN=/absolute/path/to/stack npm run docs:smokeThe read-only Release freshness workflow reports when CLI, Docs, Web, or production pins drift. Resolve drift through reviewed provider and consumer pull requests; the workflow does not auto-merge or auto-publish.
The gallery and Playground share canonical .stack sources from the public specification commit in scripts/example-corpus.config.mjs. Previews render on the visitor's device with the pinned WebAssembly Engine and are never committed as documentation SVGs.
npm run examples:check
STACK_SPECIFICATION_ROOT=/path/to/specification npm run examples:sync
npm run examples:check:sourceAdvance the corpus only to a reviewed specification commit. Provider artwork is not fetched or redistributed by the gallery; its published examples require only builtin assets.
public/favicon.svg is the canonical Web logo mark; docs/public/favicon.svg must remain byte-identical. public/ogp.png is shared by Playground and Docs metadata. The pinned Docs bundle supplies homepage copy, localized Markdown alternatives, llms.txt, /machine/index.json, and immutable versioned machine resources. Keep old versioned machine files when changing a pin.
Do not maintain a second product story in Web or add pre-rendered example SVGs. Repository validation rejects logo drift, generated-resource drift, unsafe output, and rewritten immutable machine files.
Cloudflare configuration targets the stack-web Worker and publishes the combined Vite and VitePress output as static assets. Before a production deployment, run the complete build and dry-run checks, verify the exact Docs and Engine pins, and review the rendered Playground and all four documentation locales.
Keep changes focused, use English commit and pull request descriptions, and do not commit credentials, tokens, customer data, signing material, build output, or fetched private resources.