The rossoctl website — a Docusaurus site deployed to GitHub Pages from this repository (rossoctl/.github). It hosts the landing / ecosystem guide and the product Docs.

This repo also holds the rossoctl org's community-health files (profile/, .github/ISSUE_TEMPLATE/, .github/pull_request_template.md, and the org reusable workflows). Those are unrelated to the website — leave them in place.

The Docs section is not committed in this repo. It is synced at build time from the source of truth — the docs/ folder in rossoctl/rossoctl. Edit docs there, not here.

• scripts/sync-docs.sh mirrors rossoctl/rossoctl:docs/ → docs/ (git-ignored).
• CI runs npm run sync-docs before every build (see .github/workflows/deploy.yaml).
• Auto-sync: a push to docs/ in rossoctl/rossoctl fires a repository_dispatch (docs-updated) that rebuilds and redeploys this site. A daily cron is the fallback.

• Node.js 20 or newer (see engines in package.json).
• npm — this project is npm-based; a package-lock.json is committed. There is no yarn.lock/pnpm-lock.yaml, so don't use yarn or pnpm (they'd generate a competing lockfile). Every command below is an npm run script from package.json.

# 1. Install dependencies (clean, lockfile-exact install)
npm ci

# 2. Pull the Docs + Contributing content (git-ignored, regenerated each build).
#    a) From GitHub — no rossoctl clone needed (default branch: main):
npm run sync-docs
#    b) ...or from a local rossoctl clone, to preview edits you haven't pushed:
SRC_REPO=/path/to/rossoctl npm run sync-docs

# 3. Run the dev server with hot reload (docs must be synced first — step 2)
npm start            # http://localhost:3000/.github/  (Ctrl+C to stop)

We do not use npm start to run the dev server with hot reload, because we make heavy use of the draft feature, which is not suppressed by start.

npm run build        # production build into build/  (fails on broken links, type errors)
npm run serve        # preview that build locally
npm run typecheck    # TypeScript check only (tsc, no emit)

.github/workflows/deploy.yaml builds and publishes to GitHub Pages on push to main, on the docs-updated dispatch, on a daily schedule, and manually via workflow_dispatch. It uploads the Docusaurus build/ output as the Pages artifact.

Served today at https://rossoctl.github.io/.github/. To move to a custom domain, set baseUrl: '/' in docusaurus.config.ts and add static/CNAME.

Commits require DCO sign-off (git commit -s). See CLAUDE.md for the sign-off and attribution policy, and enable the hook with git config core.hooksPath scripts/hooks.