dotfiles-web

dotfiles-web is the public showcase and documentation hub for the dotgibson dotfiles system, described in the README as an eleven-repo, three-layer terminal environment (Core → OS-native → Role). It documents that system rather than configuring a machine, so it is explicitly not one of the three layers. The site is built with Astro, themed in Tokyo Night, and deployed to GitHub Pages. Structure The README lists five main routes: a landing page with the hero, three-layer model, repo map and install instructions; a getting-started page with per-platform install guidance; an architecture page covering the layer model, subtree rationale, the loader and deep dives; a docs hub with concepts, guides, reference and a generated page per repository; and a changelog that mirrors each repo's CHANGELOG.md. Data-driven content The site describes itself as data-driven and largely source-derived: showcase cards, per-repo docs pages, the "by the numbers" strip and the changelog come from files under src/data plus the sibling repos, so the docs can't silently drift from the code they describe. Editable inputs include src/data/site.ts (site name, owner, nav, GitHub links), src/data/repos.ts (repository map and per-repo prose plus status), src/data/install.ts (per-platform install steps) and Markdown pages under src/content/docs. Four collectors under scripts/ derive generated data from the sibling repos: collect-metrics.mjs produces generated.json from the eleven dotfiles repos; collect-snippets.mjs produces snippets.json from eight curated files across six repos; collect-corpus.mjs produces corpus.json from htpx; and collect-coverage.mjs produces coverage.json from dotfiles-Defense. Strictness and provenance guards npm run data is described as the publish path and is strict: a missing repo, or a sibling parked on a feature branch or carrying uncommitted edits in a file the collectors read, fails the run. The README explains this check exists because a dotfiles-core checked out on a feature branch once published a changelog entry not present on Core's main. Individual collectors and npm run data:lenient stay lenient for exploratory runs; the README distinguishes a harmless case (source repo absent — committed file untouched, exit 0) from one that still writes contaminated data (fleet present but unclean, stamped generatedFrom.clean: false). Two guards read that provenance verdict: a pre-commit hook installed by npm install or npm run hooks:install (one machine, covers generated.json and snippets.json) and a committed-data-provenance CI job in data-freshness.yml (every PR). The hook skips loudly when core.hooksPath is set and can be bypassed with DOTFILES_ALLOW_DIRTY_DATA=1 or --no-verify; the CI job cannot. Automation fleet-sync.yml runs all four collectors weekly and opens a PR when output drifts. data-freshness.yml fails CI when any of the four committed files no longer matches its source, and additionally when generated.json's Core version is behind the latest dotfiles-core release. Pushing to main triggers deploy.yml (Astro build → GitHub Pages), and source repos can request a rebuild via repository_dispatch, authenticated through a short-lived GitHub App token as described in docs/WEBHOOK-SETUP.md. Development Prerequisites are Node.js with npm; the project is a standard Astro project. Commands include npm run dev (local dev server), npm run build (production build into dist/), npm run preview and npm run check (Astro type and content-collection checks). Contributing guidance asks contributors to treat the source-of-truth repos as canonical, keep content in the data files rather than hard-coding it into pages, and pass npm run check and npm run build before pushing. An MIT License is stated.