wyrd.foo

The catalog and documentation site for Wyrd Company's public tools: CLIs, MCP servers, apps, dev container features and dev container images, and coding harness plugins. Built with Astro and Tailwind.

The site is a static build with no backend. The front page holds the featured product, recent releases and the catalog. Each product has a product page, a releases page and, when it ships pages, a docs site. /releases lists every product's latest release. Subscribe to /releases.xml for the same releases with changelog notes, publication dates and stable identities per product and version. The releases page links the feed, and every page advertises it for RSS readers. Pagefind indexes the product, releases and docs pages.

Each product page also has a Markdown form at /tools/<key>.md, including feature entries, licence facts, all harness instructions, authored Compose/Kubernetes files with download links and commands, and the latest release. Embedded README and changelog content preserves each document’s reference scope and closes EOF-scoped Markdown blocks before the next section. Published sources are unchanged.

Apps and CLIs distributed as container images show their Docker command plus optional Docker Compose and Kubernetes method tabs. Tool repos author the YAML files under docs/user/, list them in assets, and declare compose and kubernetes paths on the relevant method: docker install entry. Dev container images accept the same fields on their kind block. Paths are relative to the product's docs folder, like media paths. The publisher preserves authored bytes; the site shows, downloads and copies the files with filename-specific commands. Only declared manifests appear. The default install command remains unchanged. See the publishing contract, container-manifests, for examples and validation.

Every page has a footer link to report a site problem in this repo. Product and docs pages also link to an issue draft in the product's owning repo, with page, version and source-file details where available. Visitors review and submit the draft on GitHub.

Design

• docs/concepts/wyrd-foo.yml: the concept: what the site is for and what it does.
• DESIGN.md: the visual design system, in the DESIGN.md format: colour tokens for both themes, type, spacing, shapes and components.
• docs/technical-designs/site.yml: the pages and their behaviour: home page, product page, install blocks, releases, docs, the 404 page, search, sitemap and /llms.txt.
• docs/technical-designs/publishing.yml: how a tool repo publishes: the docs/user/ contract, the publishing requirements, the publisher core, local mode, the reusable workflow and the JSON Schema.

Content model

Product metadata and documentation are data, not code. Each product has a self-contained folder under content/<key>/, in the layout the publisher (publisher/) writes from the tool repository's docs/user/ folder (publishing.yml, content):

content/<key>/
├── tool.yaml        # catalog metadata: name, tagline, category, status, kinds,
│                    # highlights, media, version, owner, release, licence, featured
├── README.md        # feature entries only: the page body
├── CHANGELOG.md     # the code changelog
├── manifest.json    # dev container image products only: the image manifest
└── docs/            # pages at any depth (title, product, order, install),
                     # assets, and the docs changelog CHANGELOG.md

A product self-registers by adding its folder: it then appears in the front-page catalog, gets a product page at /tools/<key> and, if it ships pages, a docs section at /docs/<key>. No page code changes are required. The docs contract in src/schema/ validates tool.yaml and page front matter, and the Astro content collections (src/content.config.ts) read the folders through it, so a product that breaks the contract fails the build.

The product facts show a Licence row when the publisher identifies the repo-root LICENSE. The ingest-owned licence is an SPDX expression linked to that file on GitHub. Missing or unknown licences produce a publisher warning and no row. Text matching accepts canonical MIT/Apache terms with bounded year and holder substitutions. An SPDX declaration cannot override changed or conflicting terms. Unusual notices can warn and omit; detection is conservative. The detection and multi-licence rules are in the publishing design.

Each docs page has an "Edit this page" link that opens its source file in GitHub.dev on the tool repository’s default branch. The link uses owner, docs-path and the page’s source path, including nested folders. It is also available in the page footer on narrow screens and on the docs changelog.

The collections read content/ unless WYRD_CONTENT_DIR names another folder, such as the dev content folder or a test fixture.

Publishing

A tool repo publishes its products from its own release tags: its workflow calls the reusable workflow .github/workflows/publish-docs.yml@v2 on a push of a code tag or a docs tag, or on a manual run. The workflow runs the publish-docs@v2 action, which validates the repo's docs/user/ against the shared schema, records release data and pushes content/<key>/ for each product to main. The push starts the deploy. The contract, the calling workflow and the requirements are in docs/technical-designs/publishing.yml.

A coding harness plugin is a full product with kind: coding-harness-plugin. Each install entry sets harness (the tab label), command (the complete install instructions, including marketplace setup), and optionally default. The first entry is selected when none is marked default. The same publisher, release units, docs pages, catalog filters and search apply to plugins. See the publishing design's plugin-install section for an example. When using the tool-docs template, replace the generated kinds block with that plugin block before publishing.

To onboard a tool repo, apply the Toha template in templates/tool-docs/ from gh:wyrd-company/wyrd.foo@main#templates/tool-docs. It writes the docs/user/ starter, the calling workflow and the Intentional docs unit, and toha apply --update brings later template changes into the repo.

The JSON Schema for docs/user/docs.yml is served at https://wyrd.foo/schemas/docs/v1.json.

Structure

DESIGN.md                    # the visual design system
docs/technical-designs/      # the site and publishing designs
content/                     # one folder per product (metadata + docs)
src/
├── content.config.ts        # collections: products, pages, changelogs, READMEs
├── schema/                  # the docs contract, shared with the publisher
├── lib/                     # read/query helpers
├── layouts/SiteLayout.astro # base document shell
├── components/              # shared, home, product and docs components
└── pages/
    ├── index.astro          # front-page catalog
    ├── releases.xml.ts      # RSS feed of every product’s latest release
    ├── releases.astro       # every product's latest release
    ├── 404.astro            # the page for every URL that has no page
    ├── tools/[key].astro    # product pages
    ├── tools/[key]/releases.astro  # each product's full changelog
    └── docs/[key]/          # docs pages
publisher/                   # the publisher core: publish, local and validate
templates/tool-docs/         # the Toha template that onboards a tool repo
.github/actions/publish-docs # the publish-docs@v2 action
.github/workflows/publish-docs.yml  # the reusable workflow tool repos call

Develop

Use Node.js 22.23.4 or later and the pnpm version declared in package.json. The Markdown renderer requires this Node minimum. The devcontainer installs Node 26; CI, site deployment and the publishing action provision Node 26. The site uses Astro 7 with Vite 8 and the Tailwind Vite plugin. Its explicit Unified Markdown processor keeps the heading plugin active; compressHTML: true preserves HTML-aware whitespace handling.

pnpm install
pnpm dev        # or: task dev  (binds 0.0.0.0 for the devcontainer)
pnpm build      # static build to dist/
pnpm preview

The PR build installs Task before pnpm test so the dev:v2 command tests run in hosted CI. With CI=true, missing Task fails those tests. Local runs without Task skip them with task is not on PATH.

Dev server over the tool repos

task dev:v2 builds the content from each tool repo's wyrd-foo-v2 branch, builds the site on it and serves the build, so search works:

1. The publisher (publisher/) runs in local mode over the repos in publisher/local-repos.yml. For the clone at /workspaces/tools/<name>, it fetches wyrd-foo-v2 from origin into origin/wyrd-foo-v2 only, then reads origin/wyrd-foo-v2 (else the local branch) through git objects: no checkout, no commit, no push. Set WYRD_TOOLS_DIR for another clone folder.
2. It writes .content-v2/<key>/ for every product (WYRD_CONTENT_DIR sets another folder) and prints each repo's warnings and errors. An unmet publishing requirement (no .intentional/, no GitHub Release, no wyrd-foo-v2 branch) is a warning. A repo with a schema or check error writes nothing and the run goes on (publishing.yml, local-mode).
3. pnpm build builds the site and its Pagefind search index into dist/ with WYRD_CONTENT_DIR set to that folder, and astro preview serves dist/. Run task dev:v2 again to see a content change. For live reload while working on the site itself, use task dev (no search index).

Arguments after -- go to the publisher; ASTRO_ARGS goes to astro preview.

task dev:v2               # reads GitHub Releases (GITHUB_TOKEN or GH_TOKEN if set)
task dev:v2 -- --offline  # no fetch; release data from local tags only
task dev:v2 ASTRO_ARGS="--port 4417"                # options for astro preview
task dev:v2 ASTRO_ARGS="--port 4417 --host" -- --offline  # both
task publish:local        # the publisher step only
task validate:repo -- ../gitpr                    # one checkout's working tree
task validate:repo -- ../gitpr --ref wyrd-foo-v2  # one ref of a checkout
task validate:repo -- ../gitpr --strict           # fail on what publish fails on

validate:repo reports a publishing requirement that the repo does not meet yet (no GitHub Release, no release tag, no changelog) as a warning, so a repo that does not publish yet can still be checked. Publish fails on the same finding. For a repo that already publishes, add --strict: it uses publish's severities, so the run fails before the tag push, not after it. --strict reads GitHub Releases, so it does not go with --offline.

validate:repo also checks scalar and array workflow_run.workflows filters in .github/workflows/. It uses each workflow's name:, or its repository-relative file path when name: is omitted. Matching is case-sensitive and supports *, alphanumeric bracket classes, and escaped special characters. An unmatched inclusion filter is a warning, or an error with --strict. For example, Release* matches Release package, while Release does not match release. Both .yml and .yaml files are read; --ref checks the workflows at that ref.

This is an existence check, not full GitHub Actions validation. Exclusion filters do not need to match a workflow. Filters containing unescaped ?, +, or ** are left unchecked: GitHub's semantics differ from the matching library. Names with dot path segments and patterns beyond the library's size limit are also left unchecked. Glob filters are left unchecked when a workflow name ends in /; literal names still use exact string matching. These forms remain valid inputs to the publisher, including with --strict. This check does not evaluate whether ordered exclusions leave any workflow enabled. See GitHub's workflow filter contract.

Dependency updates

renovate.json uses the shared Renovate preset. It limits updates to three concurrent PRs and two new PRs per hour. Check the Dependency Dashboard for detected updates under Rate-Limited before treating a missing PR as a detection failure. The shared throughput policy is tracked in the Renovate follow-up.

Browser tests

Behaviour that only a real browser shows (the theme before the first paint, the toggle, the system preference, the home page's tabs, filter, Copy and featured card, the product page's sections for each kind, the releases pages in each theme, the docs pages' sticky header and "On this page", and the 404 status and links of an unknown URL) is checked with Playwright Test in test/browser/. The suite serves the built site (dist/) with astro preview on a free port, and stops the server when the run ends, however it ends. The harness uses astro preview --ignore-lock so Playwright owns each foreground server and the fixture servers can run together. The home, docs and product page specs each run against a server of their own on a fixture build (dist-fixtures/home, dist-fixtures/docs and dist-fixtures/products, built from test/fixtures/*-content by pnpm test:browser, so the suite has no build step beyond pnpm build). The run fails when a fixture has no server port, so its specs cannot be skipped unnoticed.

pnpm exec playwright install chromium   # once; the version is pinned by @playwright/test
pnpm build                              # the suite reads dist/
pnpm test:browser                       # or: task test:browser

Hosted CI selects the Ubuntu HTTPS archive in the runner's apt mirror list before installing Chromium system dependencies, on both browser cache hits and misses.

With the browser missing, the run fails and names the install step. pnpm check includes the suite.

Deploy

Deployment runs from .github/workflows/cd.yml on push to main. The target is selected by the DEPLOY_TARGET repository variable (cf_pages for Cloudflare Pages or gh_pages for GitHub Pages); leaving it unset skips deployment.

Releases

The repo is one Intentional release unit, wyrd-foo. Its version is the version of the publish-docs contract that tool repos call, and CHANGELOG.md records each release. A change that tool repos or site users see adds an intent with intentional add. The PR build runs intentional check.

To release:

1. Run intentional status and confirm the next version.
2. Run intentional plan > release-plan.json, then intentional apply. Commit the result as chore(release): X.Y.Z, alone in its release PR.
3. When the release commit is on main, check it out and run intentional tag --plan release-plan.json. This makes the X.Y.Z tag.
4. Push the tag: git push origin X.Y.Z. The push runs .github/workflows/major-tag.yml, which publishes the GitHub Release with that version's notes from the tagged CHANGELOG.md, then moves vX to the release when it is the highest X.y.z.

The workflow uses its own contents: write token. A rerun preserves an existing published GitHub Release and retries the major-tag move. A failure to publish prevents the major-tag move; fix the failure and rerun the workflow. An existing unpublished release requires operator attention.

Release tags are bare versions, such as 2.0.0. The major tag keeps its v, such as v2, because tool repos call publish-docs.yml@v2. Intentional does not manage the major tag; the major-tag workflow does.