docs(site): add the screenshot tool, welcome page and getting started guide

Merged
GN
2d ago
+1802-47

Summary

First of six stacked PRs that add a plain-language Termul user guide with screenshots. Stacked on the Fumadocs foundation PR. This one adds the screenshot tool, the welcome page and the Getting started section.

Screenshots come from a script so they can be re-taken after any UI change. website-docs/scripts/screenshots/capture.ts starts a throwaway termul-server with demo projects under /home/demo/projects, a demo home directory and a scrubbed environment (so no real accounts, skills or host names appear), and a scripted demo agent. Then it drives the browser build with Playwright. Each shots/*.ts file is one section and gets a fresh server.

Related Issue

No issue: the user guide was requested directly by the maintainer. Builds on the foundation PR.

Type of Change

  • docs: documentation only
  • chore: maintenance or tooling

What Changed

  • website-docs/scripts/screenshots/: capture runner, demo server, demo agent, helpers.
  • website-docs/README.md: how to re-take screenshots.
  • content/docs/index.mdx (welcome page), content/docs/meta.json (section order).
  • Getting started: install, first project, window tour, projects, command palette, keyboard shortcuts.

The welcome page links to sections that later PRs in the stack add.

How It Was Tested

  • bun run types:check and bun run build in website-docs/ at this branch
  • biome ci website-docs/scripts
  • Internal link check over the built site (every /docs/... link and #anchor resolves at the top of the stack)
  • Manual verification completed: every screenshot was opened and checked against its page
  • bun run test, cargo checks: not applicable (docs and a dev-only script; no app code changes)

CI & Review Gate

  • All CI checks pass
  • Code review comments from CodeRabbit / Claude have been addressed or resolved
  • No unresolved review findings remain

Checklist

  • My PR title follows the conventional commit format used by this repo
  • I linked the related issue or explained why none exists
  • I updated docs when needed
  • I added or updated tests when needed (not applicable)
  • I verified the change does not introduce unrelated modifications
  • I read AGENTS.md and followed the contributor guidelines
  • A human reviewed the complete diff before submission

Summary by cubic

Adds a Termul welcome page, the Getting started guide (install, first project, window tour, projects, command palette, keyboard shortcuts), and the script that captures their screenshots.

  • website-docs/scripts/screenshots/ starts a throwaway termul-server with demo projects under /home/demo/projects, a scrubbed demo environment, and a scripted agent, then drives the browser build with Playwright. The README documents how to re-take every shot with bun scripts/screenshots/capture.ts after a UI change.
  • tsconfig.json now excludes scripts/ from the site typecheck, because those scripts import Playwright and the e2e helpers from the repo root, which the docs deploy job doesn't install.
  • The build now ships the SPA fallback as 404.html and drops the public/_redirects rewrite, which caused a redirect loop on Cloudflare Pages.
  • The welcome page's cards link to sections that later PRs in this stack add; those links only fully resolve once the stack lands.

No migration needed; docs and a dev-only script only, no app code changes.

Summary by CodeRabbit

  • Documentation
    • Added a Getting Started guide covering installation, project setup and management, the app layout, the command palette, and keyboard shortcuts.
    • Updated the documentation home page with an overview of desktop, browser, and phone experiences, plus links to key topics.
    • Added guidance for capturing documentation screenshots and organizing page navigation.
  • Chores
    • Updated the docs build to serve a 404 page for unmatched routes.