---
name: sourcey
description: Generate documentation for a project using 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.

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.

## Quality Bar

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
- 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
- if the repo evidence is too thin for a strong docs page, surface that as an
  evidence gap instead of manufacturing confident filler

## Quality Profile

- Purpose: produce native project documentation, not a generic generated docs
  demo.
- Audience: developers evaluating or using the target project, plus the
  maintainer who owns the docs.
- Artifact contract: bounded docs plan, authored source bundle, deterministic
  build output, critique, at most one revision pass, and verification evidence.
- Evidence bar: infer docs structure from the repository, existing docs,
  package metadata, API specs, examples, and project terminology. Missing
  evidence narrows the docs; it does not justify filler.
- Voice bar: match the project's own vocabulary, confidence level, and
  ambition. Never expose discovery, build, or critique mechanics as page prose.
- Strategic bar: the docs should make a real user action easier: install,
  evaluate, integrate, operate, or contribute. A pretty site with thin content
  is a failed run.
- Stop conditions: return `needs_more_evidence`, `needs_review`, or an empty
  author/revise bundle when the repo already has the right docs or the evidence
  does not support new pages.

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

## Steps

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

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.

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

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

## Constraints

- 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.
- Do not encode open-ended critique or revision behavior. Critique is one
  bounded evaluation pass. Revision is at most one explicit bounded pass.