Aurora Catalyst Docs

Documentation site for the Aurora Catalyst ecosystem — the aurora-catalyst-cli code generator and the aurora-catalyst Angular + NestJS framework. 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:

1. Human-curated pages — written and edited in this repo. They live under src/content/docs/{en,es}/{tutorials,guides,reference,concepts}/.
2. 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-cli/docs/ — produced by oclif readme --multi
reference/api/cli/	Auto	aurora-catalyst-cli/docs-api/ — produced by TypeDoc
reference/api/catalyst/	Auto (future)	aurora-catalyst/docs-api/ — not active yet
changes/cli/	Auto	aurora-catalyst-cli/openspec/changes/archive/
changes/catalyst/	Auto	aurora-catalyst/openspec/changes/archive/

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	cli	✅	✅	✅
aurora-catalyst	catalyst	✅	❌ (no CLI)	❌ (TypeDoc not set up yet)

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-cli (same pattern for aurora-catalyst, minus the CLI/API generation parts).

1. 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>/.

2. Regenerate the auto-outputs that apply to that source repo.

   In aurora-catalyst-cli:

   npm run docs:api   # TypeDoc → docs-api/
   # `oclif readme --multi` already runs on `npm run prepack`, which produces docs/

   In aurora-catalyst:

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

3. Come back to this repo and import.

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

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

5. Review, commit, push.

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

6. 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:

1. Run pnpm sync before committing changes that should reach production docs. CI has no access to sibling repos — it trusts what is committed.
2. Never hand-edit files under reference/cli-commands/, reference/api/, or changes/. They are overwritten on every sync.
3. 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.
4. Spanish is neutral / international with tuteo ("tú", "aquí", "empieza"). Not a literal translation — idiomatic.
5. 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:

1. Checkout this repo.
2. pnpm install --frozen-lockfile.
3. pnpm build.
4. 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.