docs(site): add Astro Starlight docs site + GitHub Pages deploy#34
Merged
Conversation
Adds `packages/docs/` as a private workspace package (Astro 6 + @astrojs/starlight 0.38) with 34 authored pages covering user guide, MCP tool reference, contributing guide, and architecture notes. Deployment is wired to GitHub Pages via `.github/workflows/pages.yml` and the deployed site is https://theagenticguy.github.io/opencodehub/. Changes: - `packages/docs/` — Astro Starlight scaffold + 34 content pages - `.github/workflows/pages.yml` — build + deploy-pages, mise-action, correct Pages permissions, concurrency group `pages` - `mise.toml` — `docs:dev`, `docs:build`, `docs:preview` tasks - `biome.json` — exclude `.astro`/`.mdx`/content tree - `.gitignore` — `packages/docs/.astro/` - `README.md` — Docs badge + Documentation section - `pnpm-lock.yaml` — astro + starlight + transitive deps - `.erpaval/` — session packets + 2 durable lessons
Closed
theagenticguy
added a commit
that referenced
this pull request
May 1, 2026
## Summary - New `packages/docs/` Starlight site (Astro 6 + @astrojs/starlight 0.38) with 34 authored pages - `.github/workflows/pages.yml` deploys to GitHub Pages on push to `main` - Deployed URL: **https://theagenticguy.github.io/opencodehub/** - Pages already enabled on the repo (build_type: workflow) ## What's in the docs - **Start here** (4): what-is, install, quick-start, first-query - **User guide** (9): indexing, using-with-{claude-code,cursor,codex,windsurf,opencode}, cross-repo-groups, ci-integration, troubleshooting - **Reference** (4): cli, configuration, error-codes, languages - **MCP** (4): overview, tools (all 28), resources, prompts - **Contributing** (7): overview, dev-loop, commit-conventions, release-process, ip-hygiene, adding-a-language-provider, testing - **Architecture** (5): overview, monorepo-map, adrs, determinism, supply-chain ## Repo hygiene - `biome.json` — exclude `.astro`/`.mdx`/content tree (Biome 2.4 doesn't parse them) - `mise.toml` — `docs:dev`, `docs:build`, `docs:preview` - `packages/docs` is `private: true` — excluded from the production license audit by design - No banned-strings leaks (verified) - `pnpm-lock.yaml` regenerated; `--frozen-lockfile` in CI works against this commit ## Drift documented (not fixed in this PR) The docs call out three pre-existing drifts so the next session can target them: 1. `scripts/smoke-mcp.sh` `EXPECTED_TOOLS=19` vs `server.ts=28` 2. `scripts/acceptance.sh` gate 5 license allowlist missing `BlueOak-1.0.0` / `0BSD` 3. `README.md` says "27 tools" (stale) ## Test plan - [x] `pnpm -F @opencodehub/docs build` — 35 HTML pages, pagefind index, sitemap, 3.89s - [x] `pnpm exec biome check .` — 583 files, 0 errors, 0 warnings - [x] `pnpm -r exec tsc --noEmit` — exit 0 - [x] `bash scripts/check-banned-strings.sh` — PASS - [x] `pnpm exec license-checker-rseidelsohn ... --production` — exit 0 - [ ] GitHub Pages deploy succeeds after merge (first workflow run) - [ ] https://theagenticguy.github.io/opencodehub/ renders with working nav + search
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
packages/docs/Starlight site (Astro 6 + @astrojs/starlight 0.38) with 34 authored pages.github/workflows/pages.ymldeploys to GitHub Pages on push tomainWhat's in the docs
Repo hygiene
biome.json— exclude.astro/.mdx/content tree (Biome 2.4 doesn't parse them)mise.toml—docs:dev,docs:build,docs:previewpackages/docsisprivate: true— excluded from the production license audit by designpnpm-lock.yamlregenerated;--frozen-lockfilein CI works against this commitDrift documented (not fixed in this PR)
The docs call out three pre-existing drifts so the next session can target them:
scripts/smoke-mcp.shEXPECTED_TOOLS=19vsserver.ts=28scripts/acceptance.shgate 5 license allowlist missingBlueOak-1.0.0/0BSDREADME.mdsays "27 tools" (stale)Test plan
pnpm -F @opencodehub/docs build— 35 HTML pages, pagefind index, sitemap, 3.89spnpm exec biome check .— 583 files, 0 errors, 0 warningspnpm -r exec tsc --noEmit— exit 0bash scripts/check-banned-strings.sh— PASSpnpm exec license-checker-rseidelsohn ... --production— exit 0