sourcey

Sourcey

Generate a documentation site for a project using Sourcey. Sourcey is a static documentation generator that produces HTML sites from markdown pages, OpenAPI specs, Doxygen XML, and MCP server snapshots.

What this skill does

By default, runx executes Sourcey as a governed mixed-runner skill:

1. discover the bounded documentation scope, evidence, and plan
2. request approval
3. author the bounded docs/config bundle
4. write the source bundle deterministically
5. build docs deterministically
6. critique the built output in one bounded pass
7. apply at most one bounded revision pass
8. rebuild and verify the output deterministically

For already-configured projects, the same sourcey runner stays narrow: the discover step can confirm existing config, the author/revise passes can return empty bundles, and the deterministic tool steps still perform the build and verification work.

A direct zero-input invocation targets the current workspace, so runx skill sourcey reaches bounded discovery immediately. A composed chain targeting a different project should pass both project and repo_root explicitly so discovery, authored-source writes, and deterministic builds stay on the same workspace boundary.

For repository-backed projects, Sourcey owns two separate surfaces: committed docs source and generated site output. Keep those separate. Do not mix emitted HTML, search indexes, or OG assets back into the authored docs tree.

When to use this skill

• A project needs a maintainer-grade documentation site generated from real repository evidence, existing docs, API specs, Doxygen XML, or MCP snapshots.
• A branded package or product needs Sourcey output with governed discovery, approval, authoring, deterministic build, critique, revision, and receipt proof.
• A workflow needs to separate authored docs source from generated site output while preserving a reviewable receipt trail.
• A maintainer wants CI or deploy to rebuild docs without inventing scope, prose, or information architecture at deploy time.

When not to use this skill

• To manufacture documentation when the repository evidence is too thin. Return needs_more_evidence or needs_review instead of confident filler.
• To write generated HTML, search indexes, or Open Graph assets back into the source docs tree.
• To bypass approval for a new docs plan or to run open-ended critique/revision loops.
• To document APIs by hand when an OpenAPI, Doxygen, or MCP source can be used directly by Sourcey.

Documentation rules

Sourcey output should read like native project documentation that a maintainer would stand behind:

• build from project evidence, but do not expose the evidence-gathering process as page prose
• preserve the project's own terms, priorities, and level of ambition
• make fewer pages with real substance rather than many generic pages
• make a real developer action easier—install, evaluate, integrate, operate, or contribute; a polished site with thin content is a failed run
• never use "generated by Sourcey", preview, adoption, migration, scaffold, or demo framing unless the project itself uses that framing
• never describe pages as machine output, agent output, or AI-generated docs; the site should read like the project maintainer wrote and stands behind it
• when publishing public docs, use a credible durable project, maintainer, organization, product, or documentation home. Random personal domains, placeholder parent sites, sandbox hosts, preview deploys, throwaway subdomains, and unrelated novelty domains are not publication-quality homes
• if the repo evidence is too thin for a strong docs page, surface that as an evidence gap instead of manufacturing confident filler

Canonical semantics

Complex runx skills share a reusable phase language:

• scope
• ingest
• model
• materialize
• evaluate
• revise
• verify
• ratify

The current Sourcey runner deliberately uses a bounded subset:

• discover folds scope + ingest + model
• approve is ratify
• author + write-docs + build form materialize
• critique is evaluate
• revise + write-revisions + rebuild form revise
• verify is verify

The current slice uses exactly one bounded revision window. It never loops until good and it never critiques indefinitely.

When docs_inputs is supplied explicitly, treat that as a bounded instruction to use the existing config target. Do not overwrite the referenced config or invent replacement docs files merely because repository inspection evidence is thin. Missing evidence is not the same as missing files.

Procedure

1. Inspect the current workspace by default, or the explicit project root supplied by a chain, and discover a bounded documentation plan from real project evidence.
2. Approve the discovered plan before authoring.
3. Author the bounded Sourcey source bundle.
4. Persist that bundle deterministically.
5. Run sourcey build deterministically with the discovered or authored config.
6. Critique the built output in one bounded evaluation pass.
7. Apply at most one bounded revision pass from that critique.
8. Rebuild deterministically after the revision bundle is written.
9. Verify the output directory contains index.html.
10. Inspect the receipt and generated site.

The deterministic build report should carry enough rendered evidence for an external reviewer to reason about the site without hidden file access. At minimum that means the generated file list plus index-page title, headings, and an excerpt when index.html exists.

Discovery contract

discovery_report may include additional planning metadata, but the canonical resolved docs inputs must live under:

• discovery_report.discovered.brand_name
• discovery_report.discovered.homepage_url
• discovery_report.discovered.docs_inputs

Downstream deterministic build steps consume that nested discovered object.

Output schema

Sourcey build produces: HTML pages, sourcey.css, sourcey.js, search-index.json, sitemap.xml, llms.txt, llms-full.txt, and _og/ directory with generated Open Graph images.

The sealed package includes:

discovery_report:
  discovered:
    brand_name: string | null
    homepage_url: string | null
    docs_inputs: object | null
doc_bundle:
  files: array
  summary: string
sourcey_build_report:
  generated_files: array
  index_title: string
  index_headings: array
  index_excerpt: string
evaluation_report: object
revision_bundle:
  files: array
  summary: string
sourcey_verification_proof:
  verified: boolean
  index_path: string
receipt_notes:
  authority: governed docs plan approval
  mutation: authored docs source writes only

Worked example

Input: a project contains README.md, package.json, and a partial docs/ tree, but no Sourcey config.

Output: decision: ready after approval; Sourcey discovers the project name, homepage, and docs inputs, writes a bounded docs/sourcey.config.ts plus only the highest-value missing docs pages, builds to .sourcey/runx-docs, critiques the rendered index.html, applies at most one revision bundle, verifies the output, and seals a receipt with the build report and verification proof.

If the project evidence does not support a maintainer-grade site, the run stops with needs_more_evidence or needs_review instead of producing filler.

Inputs

• project: project root directory (default: the current workspace).
• repo_root: filesystem root for authored-source writes (default: the current workspace). When a composed chain targets another project, pass both project and repo_root explicitly and keep them aligned.
• brand_name: project name (discovered from package evidence if omitted).
• homepage_url: project homepage (discovered from project evidence if omitted).
• docs_inputs: structured docs inputs, e.g. {"mode":"config","config":"docs/sourcey.config.ts"} or {"mode":"openapi","spec":"openapi.yaml"}. Discovered if omitted and may point at authored config produced by the skill.
• project_brief: optional grounded brief carrying brand cues, docs audit, IA direction, and writing constraints. When present, the authored docs should feel like native project docs rather than generic generated scaffolding.
• output_dir: generated site output path (default: <project>/.sourcey/runx-docs).
• sourcey_bin: explicit sourcey executable path (default: SOURCEY_BIN env or sourcey on PATH).

Repository Contract

• Keep authored docs source in the repository, usually under docs/ when using docs/sourcey.config.ts.
• Keep generated site output in output_dir, separate from the source tree.
• The default generated output path is <project>/.sourcey/runx-docs.
• Generated output should be gitignored unless the project explicitly chooses to version release artifacts.
• CI or deploy may run deterministic sourcey build from committed source.
• Deploy must not be the step where docs scope, prose, or IA is invented. Do discovery, authoring, and review before deploy.
• For Astro host apps, prefer the first-class sourcey/astro integration over a separate prebuild script that writes into public/docs. Keep docs/sourcey.config.ts and markdown/spec inputs as source; let astro dev serve Sourcey through Vite and astro build write generated docs into the final output under the configured route.
• For public publication, include enough proof for an external reviewer to inspect the target project, source commit, Sourcey config or input source, generated page list, deployment URL, parent domain, and durability of the hosting choice.

Astro host pattern

Use this shape when the target already uses Astro and docs should live at a path such as /docs:

import { defineConfig } from "astro/config";
import sourcey from "sourcey/astro";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    sourcey({
      config: "./docs/sourcey.config.ts",
      routeBase: "/docs",
    }),
  ],
});

Do not add prebuild, build:docs, or committed public/docs artifacts for this path unless the project explicitly cannot use Astro integrations. The generated output remains reproducible build output, not authored source.

Config reference

import { defineConfig } from "sourcey";

export default defineConfig({
  name: "Project Name",
  theme: {
    preset: "default",             // "default" | "minimal" | "api-first"
    colors: {
      primary: "#hex",             // required
      light: "#hex",               // optional, derived from primary
      dark: "#hex",                // optional, derived from primary
    },
    fonts: {
      sans: "Inter",               // optional
      mono: "monospace",           // optional
    },
    layout: {
      sidebar: "18rem",            // optional
      toc: "19rem",                // optional
      content: "44rem",            // optional
    },
    css: ["path/to/custom.css"],   // optional
  },
  logo: "path/to/logo.png",       // or { light, dark, href }
  favicon: "path/to/favicon.ico",
  repo: "https://github.com/org/repo",
  editBranch: "main",
  editBasePath: "docs",            // path from repo root to docs source
  codeSamples: ["curl", "javascript", "python"],  // for OpenAPI tabs
  navigation: {
    tabs: [
      // Markdown pages tab
      {
        tab: "Documentation",
        slug: "",                  // empty = default tab
        groups: [
          { group: "Getting Started", pages: ["introduction", "quickstart"] },
          { group: "Guides", pages: ["configuration", "deployment"] },
        ],
      },
      // OpenAPI tab
      {
        tab: "API Reference",
        openapi: "path/to/openapi.yaml",
      },
      // Doxygen tab
      {
        tab: "C++ API",
        doxygen: {
          xml: "path/to/doxygen/xml",
          language: "cpp",         // "cpp" | "java"
          groups: true,            // use doxygen groups for nav
          index: "auto",           // "auto"|"rich"|"structured"|"flat"|"none"
        },
      },
      // MCP tab
      {
        tab: "Tools",
        mcp: "path/to/mcp.json",
      },
    ],
  },
  navbar: {
    links: [
      { type: "github", href: "https://github.com/org/repo" },
      // types: github, twitter, discord, linkedin, youtube, slack,
      //        mastodon, bluesky, reddit, npm, link
    ],
    primary: { type: "button", label: "Demo", href: "/demo" },
  },
  footer: {
    links: [{ type: "github", href: "https://github.com/org/repo" }],
  },
  search: {
    featured: ["introduction", "quickstart"],  // top results when empty query
  },
});

Page format

Pages are markdown files resolved relative to the config file directory. If config is at docs/sourcey.config.ts, then page "quickstart" resolves to docs/quickstart.md.

---
title: Page Title
description: One-line description for search and meta tags
---

Content here. Standard markdown with code blocks, tables, links.

Card Icon Contract

Sourcey card icons are Heroicons v2 outline names in kebab-case. The renderer returns an empty icon for unknown names, so authoring must use exact names.

Known-good names for documentation cards include: academic-cap, arrow-path, bell, bolt, book-open, chart-bar, check-circle, cloud-arrow-up, code-bracket, command-line, cpu-chip, cube, document, document-text, exclamation-triangle, globe-alt, key, lifebuoy, light-bulb, lock-closed, magnifying-glass, map, rocket-launch, server-stack, shield-check, sparkles, and wrench-screwdriver.

Invalid card icon names are a blocking quality issue. The build report includes icon_validation; critique and revision must fix any icon_validation.status: "invalid" result before the run is accepted.

Edge cases and stop conditions

• Only create tabs for content types the project actually has. Do not add an OpenAPI tab if there is no spec file. Do not add a Doxygen tab without XML.
• Do not document APIs by hand when a spec file exists — use the spec tab.
• Keep navigation shallow: 1-2 tabs, 2-4 groups for most projects.
• Use project brand colors if identifiable. Otherwise use a neutral palette.
• Use only exact Heroicons v2 outline names for Sourcey card icon attributes; never invent icon names.
• When a grounded brief provides logo, favicon, color, or IA guidance, prefer that over generic defaults.
• Match the project's existing voice and terminology.
• Never write docs that describe themselves as a preview, adoption, migration, or tool-generated scaffold unless the repo's own evidence explicitly uses that framing.
• Do not write generated HTML, search indexes, or OG assets into the authored docs source tree.
• If output_dir lives under the repo root, gitignore it or call out the missing ignore rule as an operational gap.
• Build output may be regenerated in CI or deploy, but deploy must not author or revise docs content.
• Public deployments must be durable and socially credible. Do not treat a throwaway preview URL, unrelated personal domain, placeholder parent site, or sandbox subdomain as a completed public docs home.
• Do not encode open-ended critique or revision behavior. Critique is one bounded evaluation pass. Revision is at most one explicit bounded pass.

Agent task contracts

sourcey-discover

Inspect the target project and produce a bounded discovery_report for Sourcey. Prefer explicit input values when supplied. Otherwise infer brand_name, homepage_url, and docs_inputs from real project evidence such as package.json, README, existing docs, and specs. Do not invent APIs or pages. When config does not already exist, propose a practical docs_inputs object pointing to the config or spec path the next step should build from. Treat authored docs source and generated site output as separate surfaces. Prefer committed docs source in the config-relative docs tree and generated output under /.sourcey/runx-docs unless explicit inputs say otherwise. Do not propose writing built HTML back into the docs source tree. If the chosen output directory is inside the repo and not gitignored, record that as an operational gap. Treat this as a bounded scope/ingest/model pass. Do not author docs, build the site, or propose open-ended revision. When project_brief is supplied, treat it as grounded evidence about brand, current docs quality, information architecture, and writing direction. Use it to resolve a better documentation plan, but do not widen scope beyond the repo evidence and the brief's stated priorities. When the brief includes an existing_surface inventory, carry it forward as a real coverage requirement instead of treating it as optional context. discovery_report must use this canonical shape: { "discovered": { "brand_name": string|null, "homepage_url": string|null, "docs_inputs": object|null } } Additional fields are allowed, but brand_name, homepage_url, and docs_inputs must live under discovery_report.discovered.

sourcey-author

Author a bounded Sourcey source bundle from the approved discovery plan. doc_bundle must include a files array of { path, contents } entries to write under the target project, plus a summary of what was authored. When the project already has a complete Sourcey config and pages, keep the bundle minimal. When config or pages are missing, create only the files required to build a strong first documentation site grounded in the discovered evidence. If docs_inputs was supplied explicitly and discovery did not establish that the referenced config or docs files are missing, preserve the existing repo contents and return an empty files array rather than overwriting the config with a weaker placeholder bundle. Lack of repository inspection evidence is not evidence that the files are absent. Only write source docs, config, assets, and minimal supporting repo metadata. Never write generated HTML, search indexes, or OG assets into the source docs tree. When the approved plan uses a generated output_dir under the repo root and the repo does not already ignore it, include the minimal .gitignore change needed to ignore that build artifact. This is one bounded materialize pass, not an open-ended iteration loop. When project_brief is supplied, it is the quality bar:

• Use the brief's brand_system to set logo, favicon, colours, and visual direction when the evidence supports it.
• Use the brief's current_docs_audit and information_architecture to preserve what works and fill only the highest-value gaps.
• If the brief includes existing_surface.visible_paths, preserve a maintainable equivalent of that visible docs footprint. Do not drop notebook-backed examples, API reference sections, or other current pages just because they were not called out as priority pages.
• Use the brief's writing_directives to keep terminology, audience, and tone native to the project.
• Never write docs that call themselves a preview, migration, adoption, scaffold, or vendor-generated artifact unless the repo's own evidence already uses those words.
• A maintainer should be able to read the result and believe it is their project's docs, not a demo site. The generated site should feel like a fuller, better version of the current docs surface, not a smaller demo.
• Sourcey card icons must be exact Heroicons v2 outline kebab-case names. Do not invent icon names. Known-good card icons include academic-cap, arrow-path, bell, bolt, book-open, chart-bar, check-circle, cloud-arrow-up, code-bracket, command-line, cpu-chip, cube, document, document-text, exclamation-triangle, globe-alt, key, lifebuoy, light-bulb, lock-closed, magnifying-glass, map, rocket-launch, server-stack, shield-check, sparkles, and wrench-screwdriver.

sourcey-critique

Evaluate the built Sourcey site against the discovered plan and the authored source bundle. Use the build_report as the primary evidence packet for rendered output, especially generated_files, index_title, index_headings, and index_excerpt. When that evidence is absent or thin, call it out as an evidence gap rather than inventing site content. Produce one bounded evaluation_report covering grounding, clarity, navigation quality, brand alignment, voice integrity, coverage, and obvious gaps. Flag operational mistakes such as generated output living in source control without intent or deploy-time authoring assumptions. Explicitly call out any wording that reads like a preview, adoption pitch, migration pitch, or tool scaffolding instead of native project docs. Treat build_report.icon_validation.status == "invalid" as a blocking quality failure: cite invalid_icons and require exact Heroicons v2 outline replacements before passing the run. When project_brief includes existing_surface.visible_page_count or visible_paths, compare the built site against that inventory and treat coverage regression as a blocking quality failure. Do not propose open-ended revision loops here.

sourcey-revise

Apply at most one bounded revision pass using the evaluation_report. revision_bundle must include a files array of { path, contents } entries to update under the target project, plus a summary of the deltas applied. If the first build is already strong, return an empty files array and explain why. Do not open a second critique loop, do not widen scope beyond the discovered plan, and do not turn generated site output into committed source. Prioritize fixing brand-fit errors, generic vendor framing, shallow IA, and missing maintainer-grade coverage before making cosmetic changes. If the brief or evaluation report shows that the current build is smaller than the maintainer's existing visible docs surface, spend the revision pass on closing that coverage gap first. If evaluation_report or build_report identifies invalid Sourcey card icons, replace them with exact Heroicons v2 outline kebab-case names before making lower-priority prose edits.