spillwaycms.com: the project website and registry

The project website is built on Spillway itself, hosted through the fleet, and is where people learn the product, read the docs, and publish modules, themes and kits for everyone else. Clean and simple: one site, four jobs.

The four jobs

Publishing flow

1. A publisher runs spillway publish in a module, theme or kit folder with an API token, or uploads a tarball on the site.
2. The registry validates the manifest and version (semver, immutable), runs the sandbox smoke test on sandboxed modules, scans for secrets and disallowed capabilities, computes the sha256 and lists the version.
3. Sandboxed extensions, themes and kits go live at once with an automated-checks badge. Trusted modules (in-process code) wait for human review before the reviewed badge and before appearing in default search; until then they are reachable by direct link with a warning.
4. Publishers can deprecate or yank a version with a reason. Security advisories attach to versions and show on install.
5. The site signs the index with the project key. Every Spillway instance ships with the matching REGISTRY_PUBLIC_KEY, so downloads are verified.

Namespaces are first come with a dispute process. Organizations own namespaces: owners and admins publish under them, maintainers may be added per namespace, and a package page says "by <organization>" (registry.md).

Themes

A theme is a kit of tokens, blocks and page templates with screenshots. The theme directory is the kit registry filtered by kind (the ThemeGallery block). Every listed theme has a preview site at /registry/<name>/preview, rendered on demand from its tarball on an in-memory scratch site with its tokens (no fleet, no browser); the gallery's Preview button and the package page link there (registry.md).

Docs for people

How-to guides by task come first: "Publish a campaign page", "Connect HubSpot", "Set up SAML with Okta", "Import a website" (docs/guides/). Each guide is short, has a result the reader can check, and links to the reference. The reference is generated from code: OpenAPI for the HTTP API, the shared contract for types, the block definitions for blocks, the CLI help for commands. Docs carry a version field, are searchable with the site's own search, and every page links to its source in the repo and ends with "Was this page helpful?" (the DocsFeedback block, answers in the docs_feedback form and on the admin Dashboard); a version switcher per minor release is open.

Docs for agents

AI agents are first-class readers and builders.

• AGENTS.md in the repo: layout, commands, rules, where to add what. CLAUDE.md mirrors it.
• The site publishes llms.txt and llms-full.txt, the docs manifest, and the OpenAPI spec.
• An "Agent guides" section: connect Claude Code, Claude Desktop or any MCP client with an API token; recipes for building a module, a kit or a theme with an agent; the review rules an agent must respect (drafts only, publish gated); how to run the smoke tests.
• Every package page offers an agent-readable manifest so an agent can install and configure it from a conversation.

Where it lives

The website has its own repository, kwall-llc/spillwaycms.com (github.com/kwall-llc/spillwaycms.com; it is private, so the link opens only for maintainers). It holds the marketing kit (home, features, audiences, compare, registry landing, blog and release notes, community, security, trademark, governance, newsletter form, menus), the deployment files (fleet template, Fly config, brand profile, the provisioning and release steps) and the CI that checks the marketing pages. The site installs that kit first (its menus link to /docs), then this repository's docs kit; neither declares the other under requires, so the two installs stay separate steps.

What stays in this repository:

• packages/kits/docs/kit.json: the docs kit, whose content is generated from docs/ and tested in packages/core/src/test/kits-docs.test.ts. It declares no dependency on the website's kit, so it installs on any site on its own.
• packages/docs-tools (@spillway-cms/docs-tools): pnpm docs:build generates docs/reference/ (OpenAPI from the routes, types from the contract, blocks, CLI, permissions, llms.txt, llms-full.txt) and the docs kit's content; pnpm docs:check is the CI step that fails when they are stale.
• docs/guides/: the task-based how-to guides. docs/agents/: the agent guides (connect, rules, build a module, build a kit, build a theme, publish).
• The server serves /llms.txt (from the published pages), /llms-full.txt and /openapi.json (from docs/reference, or DOCS_DIR).

Tasks

• ☑ Marketing kit and site content: home, features, audiences, blog, comparisons, release notes (in kwall-llc/spillwaycms.com); showcase waits for real sites
• ☑ Docs kit: Markdown import from the repo (pnpm docs:build), version field, search, edit links, the feedback widget on every page with a Dashboard card (packages/kits/docs); a version switcher is open
• ☑ Registry module: packages, versions, publishers, namespaces, automated checks, review queue for trusted modules with optional four-eyes review (REGISTRY_FOUR_EYES), badges, advisories, signed index, download stats, deprecate and yank (packages/core/src/registry, docs/registry.md)
• ☑ spillway publish CLI and the publishing API with API tokens (registry.publish permission)
• ☑ Accounts: GitHub and native sign-in, publisher profiles, namespace maintainers, organizations (members with roles, namespaces moved into them, verified badge, public pages)
• ☑ Theme directory with per-theme preview sites (gallery and package pages, previews rendered from the tarball on a scratch site; screenshots stay the publisher's)
• ☑ Reference generation: OpenAPI from routes, types from the contract, blocks, CLI and permissions (packages/docs-tools, docs/reference, checked in CI, with pnpm docs:links checking every relative link in the docs)
• ☑ Agent docs: llms.txt, llms-full.txt, agent guides (docs/agents), agent-readable package manifests
• ☐ Operations: fleet template and Fly config (in kwall-llc/spillwaycms.com) and the release workflow (image, npm, GitHub release) are done; scheduled backups to object storage (BACKUP_TARGET=s3://... on Tigris or R2, BACKUP_SCHEDULE, encrypted, with the restore drill in CI) and the status page (every instance's /status and /status.json; a StatusBoard block on the site's /status page listing the project's instances with a 90-day uptime bar, probed every five minutes from the registry host) are done (install.md, Backups and Status); setting the backup bucket's secrets on Fly, publishing the /status page with the instance list, and the security reporting inbox (the SECURITY.md address is a placeholder) are open
• ☑ Governance pages: trademark, governance, security and community pages in the website's kit; contributor agreement and release calendar open

Spillway 0.1.0 · Edit this page on GitHub