Aurora Catalyst Docs

Documentation site for the Aurora Catalyst ecosystem — the catalyst CLI code generator (now packages/cli inside the aurora-catalyst monorepo) and the aurora-catalyst Angular + NestJS framework it scaffolds. Built with Astro Starlight, deployed to GitHub Pages.

Live site: https://avvale.github.io/aurora-catalyst-docs/
Languages: English (default) and Spanish (tuteo, neutral / international)
Content framework: Diátaxis

Requirements

Node.js ≥ 20
pnpm ≥ 9

Quick start

pnpm install
pnpm dev        # local dev server at http://localhost:4321/aurora-catalyst-docs/
pnpm build      # static site output into dist/
pnpm preview    # serve the built site locally
pnpm sync       # import auto-generated content from sibling repos (see below)

How the docs site is built

This repo has two kinds of content:

Human-curated pages — written and edited in this repo. They live under src/content/docs/{en,es}/{tutorials,guides,reference,concepts}/.
Auto-imported content — generated by sibling repos and mirrored here by pnpm sync. They live under src/content/docs/{en,es}/{changes,reference/cli-commands,reference/api}/.

Both kinds are committed to this repo. The GitHub Actions workflow that deploys to Pages does NOT have access to the sibling repos, so it trusts whatever is committed. This means you are responsible for running pnpm sync locally before committing any change that should reach production.

Where each section comes from

Section (under `src/content/docs/{en,es}/`)	Kind	Origin
`tutorials/`	Human-curated	Written in this repo
`guides/`	Human-curated	Written in this repo (optionally drafted by the `catalyst-docs-from-spec` skill)
`concepts/`	Human-curated	Written in this repo (optionally drafted by the `catalyst-docs-from-spec` skill)
`reference/` (top-level, e.g. YAML schema)	Human-curated	Written in this repo
`reference/cli-commands/`	Auto	`aurora-catalyst/packages/cli/docs/` — produced by `oclif readme --multi`
`reference/api/cli/`	Auto	`aurora-catalyst/packages/cli/docs-api/` — produced by TypeDoc
`reference/api/catalyst/`	Auto (future)	`aurora-catalyst/docs-api/` — not active yet
`changes/cli/`	Auto	`aurora-catalyst/openspec/changes/archive/` — filtered to changes scoped to `packages/cli/`
`changes/catalyst/`	Auto	`aurora-catalyst/openspec/changes/archive/` — filtered to changes scoped to the framework

Translation rule: auto-imported content is not translated — see the next section for the full rationale.

Translation of auto-imported content

The site is bilingual (English + Spanish) for human-curated content: tutorials, guides, concepts, and hand-written reference pages. Each page under src/content/docs/en/ has a symmetric counterpart under src/content/docs/es/, rewritten idiomatically in neutral / international Spanish with tuteo. Both locales ship in the same commit.

Auto-imported content (changes/, reference/cli-commands/, reference/api/) follows a different rule: the raw files are copied identically to both locales, so the technical body stays in the language of the source (typically English — JSDoc comments, oclif descriptions, openspec specs). What is localized are the wrappers around that content:

Section titles in the sidebar (Change history / Historial de cambios, Reference / Referencia, etc.).
Landing pages (index.md) for every auto-generated section, written by the sync script in both locales with a note that makes the policy explicit to the reader.
Titles injected by the sync script into openspec artifacts (Proposal / Propuesta, Design / Diseño, Tasks / Tareas).

Why we don't translate the technical body

It is the industry standard. Angular, NestJS, Astro, Starlight, Vue and React all keep their CLI/API reference in the source language while localizing tutorials and guides.
Technical reference changes every release. Translating it is a race nobody wins — translations drift and stop matching the source.
The parts that genuinely benefit from a native reader's voice are the conceptual ones: tutorials, guides, concepts. Those are always written in both locales manually.

How to surface this to the reader

The sync script injects a prominent note into every auto-generated landing in both languages:

Referencia autogenerada — Esta sección se genera automáticamente desde el código fuente del repo vinculado. Los envoltorios (títulos, breadcrumbs, landings) están localizados, pero el contenido técnico se mantiene en el idioma de la fuente para estar sincronizado con ella. Es el estándar de la industria para referencia técnica.

That note lives in scripts/import-from-sources.ts (TRANSLATION_NOTE constant) so it stays consistent across every auto-imported section.

Source repos and their responsibilities

Source repo	Slug	Contributes archives?	Contributes CLI commands?	Contributes API?
`aurora-catalyst-cli` — frozen, historical only	—	❌ (consolidated, see below)	❌	❌
`aurora-catalyst`	`cli`	✅ (shared archive, see next)	✅ (`packages/cli/docs/`)	✅ (`packages/cli/docs-api/`)
`aurora-catalyst`	`catalyst`	✅ (shared archive, see next)	❌ (no CLI)	❌ (TypeDoc not set up yet)

The CLI was consolidated into the aurora-catalyst monorepo as packages/cli (archived change 2026-08-03-consolidate-cli-into-monorepo). aurora-catalyst-cli is now frozen — do not sync from it, and never route new content there. Both the cli and catalyst slugs above resolve to the SAME repo: 'aurora-catalyst' and therefore scan the SAME shared archive at openspec/changes/archive/; the cli slug additionally reads its CLI-specific build outputs from the packages/cli/ subdirectory (sourceAssetsPath in scripts/lib/sources.ts). Because the archive is shared, the catalyst-changelog-sync skill — not the source repo — decides whether a given archived change belongs under changes/cli/ or changes/catalyst/ (see its routing rule).

Other repos (aurora-core-front, aurora-core-back, aurora-core-common, aurora-catalyst-prototype) are explicitly out of scope for automated docs. They are internal libraries or prototyping scratchpads.

If a source repo is added or removed later, the change lives in scripts/import-from-sources.ts in the SOURCES array.

End-to-end workflow

When you add / change a feature in a source repo

Steps below assume you just closed a change in aurora-catalyst — either scoped to packages/cli/ (the generator) or to the framework itself; both share the same archive and workflow.

Finish the change in the source repo.
- Implement, test, commit.
- Archive the openspec change: /opsx:archive <change-name> — this writes to openspec/changes/archive/YYYY-MM-DD-<change-name>/ at the monorepo root (shared by both the CLI and the framework).

Regenerate the auto-outputs, if the change touched packages/cli/.

In aurora-catalyst:

# `packages/cli` is deliberately excluded from the pnpm workspace, so its
# dependencies are NOT installed by the monorepo's root `pnpm install`.
# Install them once per checkout before the first `docs:api` run:
pnpm --dir packages/cli install

pnpm --dir packages/cli run docs:api   # TypeDoc → packages/cli/docs-api/
# `oclif readme --multi` also runs on `pnpm --dir packages/cli run prepack`,
# which produces packages/cli/docs/

If the change is scoped to the framework instead (not packages/cli/):

Nothing extra to run today. The archive directory is all that's consumed.

Come back to this repo and import.

cd /path/to/aurora-catalyst-docs
pnpm sync

Optional — draft new docs pages for the feature. The catalyst-docs-from-spec skill reads the archive you just cut and generates Diátaxis-compliant concept pages and guide stubs in both locales. See CLAUDE.md and .claude/skills/catalyst-docs-from-spec/SKILL.md for how to invoke it.

Review, commit, push.

git status                              # check that the expected dirs changed
git add .
git commit -m "docs: reflect <feature>"
git push

GitHub Actions deploys automatically. The workflow .github/workflows/deploy.yml runs on every push to main: installs deps, builds the Astro site, uploads the dist/ directory and publishes it to Pages.

When you only edit human-curated pages (no source repo involved)

Skip steps 1–4. Go straight to git add / commit / push. No need for pnpm sync.

`pnpm sync` — what it does exactly

The script scripts/import-from-sources.ts iterates over the SOURCES array and, for each source:

Archives (hasArchives: true): copies every directory under <repo>/openspec/changes/archive/ to src/content/docs/{en,es}/changes/<slug>/<YYYY-MM-DD-change>/, then injects a title: frontmatter into every .md (so Starlight accepts them).
CLI commands (hasCli: true): copies <repo>/docs/ to src/content/docs/{en,es}/reference/cli-commands/. Because only the CLI repo provides this, there is no per-slug subdirectory here.
API (hasApi: true): copies <repo>/docs-api/ to src/content/docs/{en,es}/reference/api/<slug>/.
Landing index.md files: generated automatically for each section and each source, so Starlight's sidebar renders correctly.

The operation is destructive in its targets — resetDir (rm -rf + mkdir) is called before each copy, so any hand-edit under those directories is overwritten. That's intentional: those sections are read-only mirrors.

If a source repo isn't found on disk or lacks an expected output folder, the script logs [skip] for that section and continues.

Useful flags

pnpm sync --source cli          # only refresh the CLI repo
pnpm sync --source catalyst     # only refresh the framework repo
pnpm sync --skip-cli-commands   # keep cli-commands/ as-is
pnpm sync --skip-api            # keep reference/api/ as-is
pnpm sync --skip-archives       # keep changes/ as-is
pnpm sync --help

Golden rules

Full rules live in CLAUDE.md. The key five:

Run pnpm sync before committing changes that should reach production docs. CI has no access to sibling repos — it trusts what is committed.
Never hand-edit files under reference/cli-commands/, reference/api/, or changes/. They are overwritten on every sync.
Every page exists in both locales. src/content/docs/en/<path>.md MUST have a mirror at src/content/docs/es/<path>.md (and vice versa). Both ship in the same commit.
Spanish is neutral / international with tuteo ("tú", "aquí", "empieza"). Not a literal translation — idiomatic.
Do not create directories outside the Diátaxis four (tutorials, guides, reference, concepts). The changes/ section is operational and reserved for auto-imports.

Deployment

.github/workflows/deploy.yml runs on every push to main:

Checkout this repo.
pnpm install --frozen-lockfile.
pnpm build.
Upload dist/ as a Pages artifact and deploy it.

Site URL: https://avvale.github.io/aurora-catalyst-docs/. Base path: /aurora-catalyst-docs. Both in dev and prod — avoid changing this without also updating the hardcoded base path inside Starlight hero actions.

License

MIT.

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
docs/superpowers		docs/superpowers
openspec		openspec
public		public
scripts		scripts
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
astro.config.mjs		astro.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

Aurora Catalyst Docs

Requirements

Quick start

How the docs site is built

Where each section comes from

Translation of auto-imported content

Why we don't translate the technical body

How to surface this to the reader

Source repos and their responsibilities

End-to-end workflow

When you add / change a feature in a source repo

When you only edit human-curated pages (no source repo involved)

`pnpm sync` — what it does exactly

Useful flags

Golden rules

Deployment

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Aurora Catalyst Docs

Requirements

Quick start

How the docs site is built

Where each section comes from

Translation of auto-imported content

Why we don't translate the technical body

How to surface this to the reader

Source repos and their responsibilities

End-to-end workflow

When you add / change a feature in a source repo

When you only edit human-curated pages (no source repo involved)

pnpm sync — what it does exactly

Useful flags

Golden rules

Deployment

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`pnpm sync` — what it does exactly