sourcey git:20260715.f00df98A

Immutable. This exact content is served forever at /api/v1/blob/30b7e7396d54f0b6.

---
name: sourcey
description: Generate documentation for a project using Sourcey.
runx:
  category: content
---

# 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.

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 project 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:

```yaml
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` (required): project root directory.
- `repo_root`: optional alias for the project root when Sourcey is composed inside a parent graph that already uses `repo_root`.
- `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`:

```typescript
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

```typescript
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`.

```markdown
---
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.