feat(site): unify landing + docs into Astro Starlight site (#209)

Replaces the separate Vite landing (`packages/landing/`) and MkDocs docs
site with a single unified Astro 5 + Starlight site at `packages/site/`.

What changed:
- New `packages/site/` — Astro + Starlight unified site. Custom
marketing landing at `/`, Starlight docs served at `/<slug>/` (e.g.
`/getting-started/`, `/configuration/`), single design system shared
between both surfaces.
- Restored the original landing's hero, device frames, showcase videos,
and palette (the magic that was lost in PR #208).
- Migrated all 14 docs pages from `docs/*.md` into Starlight content
collections.
- Dropped Python from CI: `.github/workflows/pages.yml` now uses
`withastro/action@v2` — no more `pygments` / `pymdown-extensions`
version drift.
- Deleted: `docs/`, `mkdocs.yml`, `packages/landing/`,
`.github/workflows/landing.yml`.

Notes:
- Pinned `@astrojs/sitemap` to `3.6.0` via overrides because newer
versions import `zod/v4` which Astro 5.18 doesn't ship.
- All cross-links use relative slug paths (e.g.
`[text](../configuration/)`) so they resolve correctly under the
`/TermBeam` GitHub Pages base prefix.

Supersedes #208 (which will be closed).

Closes #207

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dorlugasigal

.github/copilot-instructions.md

@@ -118,25 +118,26 @@ TermBeam is a Node.js CLI tool that exposes a local PTY (pseudo-terminal) over H
 TermBeam has two layers of documentation that must stay in sync with code changes:
 
 - **`README.md`** — user-facing quick reference (features, CLI flags, security summary). Update when adding/removing CLI flags, features, or changing defaults.
-- **`docs/`** — full MkDocs Material site deployed to GitHub Pages. Navigation defined in `mkdocs.yml`. Update the relevant page when changing behavior:
-  - `docs/configuration.md` — CLI flags and env vars
-  - `docs/resume.md` — `termbeam resume` and `termbeam list` commands
-  - `docs/security.md` — auth, headers, threat model
-  - `docs/api.md` — HTTP and WebSocket API
-  - `docs/architecture.md` — system design
-  - `docs/getting-started.md` — installation and first run
+- **`packages/site/`** — unified Astro Starlight site (landing + docs) deployed to GitHub Pages. Navigation defined in `packages/site/astro.config.mjs` (sidebar groups). Docs content lives in `packages/site/src/content/docs/`. Update the relevant page when changing behavior:
+  - `configuration.md` — CLI flags and env vars
+  - `resume.md` — `termbeam resume` and `termbeam list` commands
+  - `security.md` — auth, headers, threat model
+  - `api.md` — HTTP and WebSocket API
+  - `architecture.md` — system design
+  - `getting-started.md` — installation and first run
 
-Preview docs locally: `pip install mkdocs-material && mkdocs serve`
+Use Starlight admonition syntax (`:::note`, `:::tip`, `:::caution`, `:::danger`) — not MkDocs `!!!` blocks. Cross-link with **relative slug paths** (e.g. `[text](../configuration/)`) — the browser resolves these against the current page URL, preserving the `/TermBeam` base prefix. Never use root-absolute paths like `/configuration/` (they bypass the base prefix and 404 on GitHub Pages) or `.md` paths (Astro content collections do not auto-rewrite `.md` extensions inside `src/content/docs/`).
 
-Changes to `docs/` or `mkdocs.yml` pushed to `main` auto-deploy to GitHub Pages.
+Preview locally: `cd packages/site && npm install && npm run dev`. Build: `npm run build` (outputs to `packages/site/dist/`).
+
+Changes to `packages/site/**` pushed to `main` auto-deploy to GitHub Pages.
 
 ## CI and Publishing
 
 - Release workflow: `.github/workflows/release.yml` bumps version, updates `CHANGELOG.md`, tags, and publishes to npm.
 - `prepublishOnly` runs `npm run build:frontend && npm test` before publish.
 - `postinstall` fixes `node-pty` prebuild permissions (spawn-helper).
-- Landing site (`packages/landing/`) deploys via `.github/workflows/landing.yml`.
-- Docs deploy via `.github/workflows/pages.yml`.
+- Site (landing + docs) deploys via `.github/workflows/pages.yml` from `packages/site/`.
 
 **IMPORTANT:** When asked to create a PR, open a PR, push to main, publish, release, or submit changes, **always use the `publish` skill**. It orchestrates the full workflow: local tests, lint, coverage, docs check, commit, push (or PR flow with proper branch naming), CI verification, and release. Do not manually run `gh pr create` or `git push origin main` — the skill handles all of this with the correct conventions.
 

.github/skills/publish/SKILL.md

@@ -64,11 +64,11 @@ git --no-pager diff HEAD
 Compare the changes against the documentation files. Check:
 
 - **`README.md`** — if any CLI flags, features, or defaults changed, README must reflect them.
-- **`docs/configuration.md`** — if CLI flags or env vars changed.
-- **`docs/security.md`** — if auth, headers, or security behavior changed.
-- **`docs/api.md`** — if HTTP or WebSocket API changed.
-- **`docs/architecture.md`** — if system design or module responsibilities changed.
-- **`docs/getting-started.md`** — if installation or first-run steps changed.
+- **`packages/site/src/content/docs/configuration.md`** — if CLI flags or env vars changed.
+- **`packages/site/src/content/docs/security.md`** — if auth, headers, or security behavior changed.
+- **`packages/site/src/content/docs/api.md`** — if HTTP or WebSocket API changed.
+- **`packages/site/src/content/docs/architecture.md`** — if system design or module responsibilities changed.
+- **`packages/site/src/content/docs/getting-started.md`** — if installation or first-run steps changed.
   and any other docs files relevant to the changes.
 
 Use read-only subagents to verify documentation accuracy. Assign each subagent
@@ -231,7 +231,7 @@ If CI or Security fails:
 
 ## Step 7 — Wait for docs pages deployment (if applicable)
 
-Only if docs files (`docs/**` or `mkdocs.yml`) were changed in the push:
+Only if site files (`packages/site/**`) were changed in the push:
 
 ```bash
 gh run list --workflow=pages.yml --branch=main --limit=1 --json databaseId,status,conclusion

.github/workflows/landing.yml

@@ -1,37 +1,56 @@
-name: Deploy Docs
+name: Deploy site
 
 on:
   push:
     branches: [main]
     paths:
-      - docs/**
-      - mkdocs.yml
+      - 'packages/site/**'
+      - '.github/workflows/pages.yml'
+  pull_request:
+    paths:
+      - 'packages/site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
 
 permissions:
   contents: read
   pages: write
   id-token: write
 
 concurrency:
-  group: pages
+  group: pages-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+  build:
     runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/site
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
-          python-version: '3.x'
-      - run: pip install --require-hashes -r docs/requirements.txt
-      - run: mkdocs build --strict
-      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
-      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: packages/site/package-lock.json
+      - name: Install dependencies
+        run: npm ci
+      - name: Build with Astro
+        run: npm run build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
         with:
-          path: site
-      - id: deployment
-        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+          path: packages/site/dist
+
+  deploy:
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.github/workflows/pages.yml

@@ -13,6 +13,12 @@ frontend/node_modules/
 
 # Build output from src/frontend/ (rebuilt by prepublishOnly)
 public/
+!packages/site/public/
 *.tsbuildinfo
 .playwright-mcp/
 test-diff.md
+
+# Astro Starlight site (packages/site/)
+packages/site/.astro/
+packages/site/dist/
+packages/site/node_modules/

.gitignore

@@ -24,10 +24,10 @@ https://github.com/user-attachments/assets/9dd4f3d7-f017-4314-9b3a-f6a5688e3671
 
 <table align="center">
   <tr>
-    <td align="center"><img src="docs/assets/screenshots/mobile-session-hub.jpeg" alt="Session hub on mobile" width="250" /></td>
-    <td align="center"><img src="docs/assets/screenshots/mobile-terminal.jpeg" alt="Terminal with touch bar on mobile" width="250" /></td>
-    <td align="center"><img src="docs/assets/screenshots/mobile-session-preview.jpeg" alt="File browser on mobile" width="250" /></td>
-    <td align="center"><img src="docs/assets/screenshots/mobile-command-palette.jpeg" alt="Command palette on mobile" width="250" /></td>
+    <td align="center"><img src="packages/site/public/mobile-session-hub.jpeg" alt="Session hub on mobile" width="250" /></td>
+    <td align="center"><img src="packages/site/public/mobile-terminal.jpeg" alt="Terminal with touch bar on mobile" width="250" /></td>
+    <td align="center"><img src="packages/site/public/mobile-session-preview.jpeg" alt="File browser on mobile" width="250" /></td>
+    <td align="center"><img src="packages/site/public/mobile-command-palette.jpeg" alt="Command palette on mobile" width="250" /></td>
   </tr>
 </table>