SPAPS Docs Release Governance

Maintainer-only release authority. Receipts, deployment gates, and rollback controls here belong to operation of the hosted SPAPS service, not the customer integration path.

Use this checklist when the upstream Sweet Potato runtime, CLI, SDKs, packages, or security behavior changes. The docs site should move only after the source artifact and the validation command agree.

Change-To-Docs Checklist

Upstream change	Source artifact to refresh	Docs likely affected	Required proof
Operational route or route group changes	`fixtures/docs-contract/spaps-contract-fixture.json` or `../sweet-potato/docs/manifest.json`	Endpoint reference, Request lifecycle, Troubleshooting	`npm run docs-contract:validate`; optionally `npm run docs-contract:upstream` when `../sweet-potato` is present
CLI command or package surface changes	`fixtures/docs-contract/spaps-contract-fixture.json`, package manifests	Packages, SPAPS CLI quickstart, Field kit	`npm run docs-contract:validate`; `npm run first-run:dry-run` for field-kit paths
Settings, env vars, or startup invariants change	`fixtures/docs-contract/spaps-contract-fixture.json`, settings source in upstream	Settings reference, Security invariants, Deployment validation	`npm run docs-contract:validate`; `npm run docs-metadata:lint`
Local-mode behavior changes	health/local-mode source and first-run scenario manifest	Auth and local mode, Local development, Troubleshooting	`npm run first-run:dry-run`; `npm run docs-contract:validate`
Webhook destination or signing policy changes	webhook docs, settings source, route manifest	Webhooks and event delivery, Security invariants, Deployment validation	`npm run docs-contract:validate`; link-check
Field-kit scenario changes	`first-run-scenarios.json`	Start here, Field kit, Troubleshooting	`npm run first-run:validate`; `npm run first-run:dry-run`; `npm run test:first-run-scenarios`

Do not update prose-only pages for high-risk surfaces without refreshing lastVerified metadata and naming the command that proves the page.

Field-Kit Leave-Behind Template

Field	Capture
App slug	The provisioned or scaffolded app slug
Auth mode	Local persona, magic link, wallet, JWT-backed session, or explicit blocker
Revenue trigger	Checkout, subscription, manual grant, wallet payment, or deferred
Entitlement	Feature key and owning app
Verification output	`npx spaps quickstart --json`, `npx spaps verify --json`, and failed checks
Runtime mode	Local runtime, upstream development stack, or production candidate
Security boundary	Allowed origins, secret locations, webhook destination policy, PII startup invariant
Troubleshooting row	Link to the symptom row used if any command failed
Next operator skill	`issue-reporting-setup`, `sweet-potato-usage-audit`, `bookme`, `documentation-website-for-software-project`, or a project-specific skill

Required Local Docs Gates


npm test
npm run docs-contract:upstream
npm run build
npm run pages:verify
npm run test:release
npm run test:e2e:docs

npm test is the canonical wrapper for its 16 constituent checks. The remaining commands bind the sibling source, static artifact, controller, and browser surface. If a local policy blocks the aggregate wrapper, run its exact package.json command chain and preserve every exit code; never convert a blocked wrapper into a PASS.

For focused diagnosis, the canonical wrapper expands to:


npm run typecheck
npm run lint
npm run format:check
npm run link-check
npm run test:link-check
npm run first-run:dry-run
npm run test:first-run-scenarios
npm run docs-contract:fixtures
npm run test:docs-contract-fixtures
npm run docs-contract:validate
npm run test:docs-contract-validation
npm run docs-metadata:lint
npm run test:docs-metadata-lint
npm run reference-inventory:validate
npm run test:reference-inventory
npm run role-links:check