docs(root): fix stale references and document sandbox workflow (#1464)

Co-authored-by: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -21,7 +21,9 @@ Refer to **[`CONTRIBUTING.md`](./CONTRIBUTING.md)** for setup, development, and
 | `packages/html`         | Web player—DOM/Browser‑specific implementation.                     |
 | `packages/react`        | React player—adapts core state to React components.                 |
 | `packages/react-native` | React Native player (planned, not yet implemented).                 |
+| `packages/cli`          | `@videojs/cli` — CLI for reading docs, and more in the future.      |
 | `apps/sandbox`          | Vite‑based dev playground (private, not published).                  |
+| `apps/e2e`              | Playwright end‑to‑end and visual snapshot tests (private).          |
 | `site/`                 | Astro‑based docs and website.                                       |
 
 ### Dependency Hierarchy
@@ -54,6 +56,7 @@ react-native    ← React Native player (planned, not yet implemented)
 utils ← element
 utils ← store ← core ← html / react
 utils ← spf ← core
+icons, skins → html / react
 ```
 
 ## Workspace
@@ -518,11 +521,12 @@ export type FeatureAvailability = 'available' | 'unavailable' | 'unsupported';
 
 ## Design Documents
 
-| Location           | Purpose                                                    |
+| Location              | Purpose                                                    |
-| ------------------ | ---------------------------------------------------------- |
+| --------------------- | ---------------------------------------------------------- |
-| `internal/design/` | Decisions you own — document for posterity                 |
+| `internal/design/`    | Architecture specs and feature designs you own             |
-| `rfc/`             | Proposals needing buy-in — get alignment before committing |
+| `internal/decisions/` | ADR-style records of single tactical decisions             |
-| `.claude/plans/`   | Implementation notes, AI-agent context, working drafts     |
+| `rfc/`                | Proposals needing buy-in — get alignment before committing |
+| `.claude/plans/`      | Implementation notes, AI-agent context, working drafts     |
 
 ### Design Doc vs RFC
 
@@ -532,7 +536,9 @@ export type FeatureAvailability = 'available' | 'unavailable' | 'unsupported';
 | **Approval**   | None needed            | Needs buy-in from others         |
 | **Purpose**    | Document for posterity | Get alignment first              |
 
-**Design Docs** — Decisions you own. Write one when making significant decisions in your area, choosing between approaches, or documenting architecture others will build on. See `internal/design/README.md`.
+**Design Docs** — Architecture specs and feature designs in your area. Longer-form, status ranges from `draft` → `decided` → `implemented` → `superseded`. See `internal/design/README.md`.
+
+**Decisions** — ADR-style records of a single tactical decision: what was chosen, why, what was ruled out. Short, always `decided`, often cross-reference each other. See `internal/decisions/README.md`.
 
 **RFCs** — Cross-team alignment. Write one when the decision affects multiple areas, changes shared API surface, or is hard to reverse. See `rfc/README.md`.
 

CONTRIBUTING.md

@@ -36,7 +36,7 @@ You’ll need the following installed:
 
 ```sh
 git clone https://github.com/{your-github-username}/v10.git
-cd vjs-10
+cd v10
 
 git remote add upstream git@github.com:videojs/v10.git
 git fetch upstream
@@ -84,10 +84,13 @@ pnpm dev
 This will run the entire workspace in developer mode, meaning all applications (examples and website) will also be started on their respective ports.
 
 ```sh
-# Run the documentation site
+pnpm dev:site       # just the documentation site
-pnpm dev:site
+pnpm dev:packages   # just the library packages (no apps)
+pnpm dev:sandbox    # just the sandbox playground
 ```
 
+See [Manual Testing with the Sandbox](#-manual-testing-with-the-sandbox) for how to use the sandbox to exercise player changes in the browser.
+
 Sometimes you may want to do (non-dev) builds, say, to validate the full build process or evaluate production artifacts.
 
 ```sh
@@ -113,12 +116,24 @@ For the bulk of our core code, we use [Biome](https://biomejs.dev). Between IDE
 To ensure your code follows our lint rules with:
 
 ```sh
-pnpm lint
+pnpm lint                    # check the whole workspace
-pnpm lint:fix
+pnpm lint:fix                # check and auto-fix the whole workspace
+pnpm lint:fix:file <file>    # check and auto-fix a single file
 ```
 
 Pre‑commit hooks automatically lint staged files via **simple-git-hooks** and **lint‑staged**.
 
+### 🔎 Typechecking
+
+We use TypeScript project references for fast, incremental typechecking across the workspace:
+
+```sh
+pnpm typecheck
+```
+
+> [!TIP]
+> Typecheck runs against built `.d.ts` files. If you add or change exported types in a package, run `pnpm -F <pkg> build` first so the new declarations are emitted before typechecking.
+
 ### 🧪 Testing
 
 We use [Vitest](https://vitest.dev) for unit testing.
@@ -163,6 +178,35 @@ pnpm test:e2e:vite               # Chromium only (fast feedback)
 > [!TIP]
 > Snapshot baselines are checked into git. When you update them, review the PNG diffs in your PR to make sure the visual changes are intentional.
 
+### 🏖 Manual Testing with the Sandbox
+
+The sandbox (`apps/sandbox/`) is a Vite playground for manually exercising player changes in a browser. The root URL renders an interactive shell — a navbar with dropdowns for platform, preset, skin, styling, and source — that previews the selected combination in an iframe. One-off templates outside the main matrix are reachable by navigating directly to `/<template-name>/`. See `apps/sandbox/templates/` for the full list.
+
+```sh
+pnpm dev:sandbox                 # sandbox + workspace package watch
+pnpm dev                         # also runs the docs site
+```
+
+Sandbox code lives in two parallel directories:
+
+- **`apps/sandbox/templates/`** — source of truth, checked into git.
+- **`apps/sandbox/src/`** — your scratch copy, fully gitignored.
+
+On `pnpm dev:sandbox`, `setup.ts` copies any file from `templates/` that doesn't already exist in `src/`. Existing files in `src/` are never overwritten, so your local changes persist across restarts.
+
+> [!IMPORTANT]
+> Because `src/` is gitignored, edits you make there will not appear in `git status`. When you want to promote a sandbox change into the repo, run `pnpm -F @videojs/sandbox sync` — it shows a diff of every changed file and prompts before copying `src/` → `templates/`. To throw away local edits and restore from templates, run `pnpm -F @videojs/sandbox reset`.
+
+See [`apps/sandbox/README.md`](./apps/sandbox/README.md) for the full model, including the `app/` shell, the `@app/*` alias for shared code, and how to add a new sandbox entry point.
+
+### ✅ Workspace Consistency
+
+Before opening a PR, run the workspace consistency check to catch common mistakes (CI coverage, scope mismatches, broken define imports, etc.):
+
+```sh
+pnpm check:workspace
+```
+
 ### 📦 Dependencies
 
 To add a dependency to a specific package, you can use [`pnpm` filtering][pnpm-filtering] from the workspace root:
@@ -190,25 +234,31 @@ Video.js 10 includes tooling for AI-assisted development with [Claude Code](http
 
 ### Slash Commands
 
-| Command          | Purpose                               |
+| Command          | Purpose                                           |
-| ---------------- | ------------------------------------- |
+| ---------------- | ------------------------------------------------- |
-| `/commit-pr`     | Commit changes and create/update a PR |
+| `/commit-pr`     | Commit changes and create/update a PR             |
-| `/review-branch` | Review changes in the current branch  |
+| `/review-branch` | Review changes in the current branch              |
-| `/gh-issue <n>`  | Analyze an issue and generate a plan  |
+| `/gh-issue <n>`  | Analyze an issue and generate a plan              |
+| `/create-issue`  | Create a GitHub issue following repo conventions  |
+| `/claude-update` | Update `CLAUDE.md` and skills for new patterns    |
+| `/create-skill`  | Scaffold a new skill                              |
 
 ### Skills
 
-Domain-specific knowledge lives in `.claude/skills/`:
+Domain-specific knowledge lives in `.claude/skills/`. A few of the most-used skills:
 
-| Skill       | Use When                                |
+| Skill           | Use When                                                 |
-| ----------- | --------------------------------------- |
+| --------------- | -------------------------------------------------------- |
-| `api`       | Designing APIs, reviewing architecture  |
+| `api`           | Designing APIs, reviewing architecture                   |
-| `component` | Building UI components                  |
+| `component`     | Building HTML or React components                        |
-| `aria`      | Accessibility implementation and review |
+| `aria`          | Accessibility implementation and review                  |
-| `docs`       | Writing documentation                  |
+| `docs`          | Writing concept guides, how-tos, and READMEs             |
-| `git`       | Commit messages, PR conventions         |
+| `api-reference` | Scaffolding component/util reference pages               |
+| `design`        | Writing internal Design Docs                             |
+| `rfc`           | Writing RFCs for proposals that need buy-in              |
+| `git`           | Commit messages, PR conventions                          |
 
-See [`.claude/skills/README.md`](./.claude/skills/README.md) for workflow mappings.
+See [`.claude/skills/README.md`](./.claude/skills/README.md) for the full list and workflow mappings.
 
 ### Maintaining AI Docs
 

README.md

@@ -17,8 +17,8 @@ Video.js v10 is close to stable. Try it out in real projects and share your feed
 ## Timeline
 
 - **Technical Preview (Complete):** Initial showcase for Demuxed.
-- **Alpha (Jan–Feb 2026):** [See milestone](https://github.com/videojs/v10/milestone/3)
+- **Alpha (Complete):** [See milestone](https://github.com/videojs/v10/milestone/3)
-- **Beta (Mar 2026):** [See milestone](https://github.com/videojs/v10/milestone/1)
+- **Beta (Complete):** [See milestone](https://github.com/videojs/v10/milestone/1)
 - **GA (Mid 2026):** [See milestone](https://github.com/videojs/v10/milestone/6) ← WIP
 - **Video.js (End of 2026):** Video.js core/contrib parity and supported plugins migrated.
 

apps/sandbox/README.md

@@ -1,45 +1,51 @@
 # @videojs/sandbox
 
-Vite-based playground for testing and developing Video.js 10 integrations. Each sandbox is a standalone entry point that demonstrates a different platform or scenario.
+Vite-based playground for testing and developing Video.js 10 integrations. Each sandbox is a standalone entry point that demonstrates a different platform, media engine, or scenario.
-
-## Sandboxes
-
-| Name                | Description                            |
-| ------------------- | -------------------------------------- |
-| `core`              | Framework-agnostic core API            |
-| `html`              | HTML player with skin switching        |
-| `html-background`   | Full-screen background video (HTML)    |
-| `html-tailwind`     | HTML player styled with Tailwind CSS   |
-| `react`             | React player with skin switching       |
-| `react-tailwind`    | React player styled with Tailwind CSS  |
-| `react-background`  | Full-screen background video (React)   |
 
 ## Getting started
 
 ```bash
 # From the repo root
-pnpm dev
+pnpm dev:sandbox             # sandbox + workspace package watch
-# Or just the sandbox
+pnpm dev                     # also runs the docs site
-pnpm -F sandbox dev
 ```
 
-This runs `setup.ts` first, which mirrors any missing files from `templates/` into `src/`, then starts the Vite dev server. Open the root URL to see links to all sandboxes.
+Open the printed URL. The root route renders an interactive shell — a navbar with dropdowns for platform (HTML, React, CDN), preset (`video`, `hls-video`, `audio`, etc.), skin, styling (CSS or Tailwind), and source — that previews the selected combination in an iframe. Use the **Open** button to pop the preview out into its own tab.
+
+The shell covers the main combinatorial matrix. One-off templates not in that matrix (e.g. `firefox-mse-repro`, `spf-segment-loading`, `simple-hls-html`) are reachable by navigating directly to `/<template-name>/`. See `apps/sandbox/templates/` for the full list.
 
 ## How it works
 
-The package has two parallel directories:
+Three directories participate:
 
-- **`templates/`** — Checked into git. The source of truth for each sandbox's starting point.
+- **`app/`** — The React-rendered shell served at `/`, plus shared helpers that sandboxes import via the `@app/*` alias. Checked into git.
-- **`src/`** — Gitignored (except `index.html`). Your working copy where you freely edit, experiment, and break things.
+- **`templates/`** — The source of truth for each sandbox. One subdirectory per entry point, each containing its own `index.html` and `main.ts` / `main.tsx`. Checked into git.
+- **`src/`** — Your working copy where you freely edit, experiment, and break things. Fully gitignored (`src/*`).
 
-On `pnpm dev`, `setup.ts` copies any file from `templates/` that doesn't already exist in `src/`. Existing files in `src/` are never overwritten, so your local changes are preserved across restarts.
+On `pnpm dev:sandbox`, `scripts/setup.ts` mirrors every file from `templates/` into `src/` that doesn't already exist there. Existing files in `src/` are never overwritten, so your local changes persist across restarts.
+
+Vite discovers sandbox entries by scanning `src/*` for subdirectories that contain an `index.html` — no manual registration is needed.
+
+> [!NOTE]
+> `src/index.html` is generated by the `serve-app-shell` Vite plugin on every dev/build — don't edit it by hand.
+
+### Sharing code with `@app/*`
+
+Templates can import shared helpers from the `app/` directory via the `@app` alias:
+
+```ts
+import '@app/styles.css';
+import { SOURCES } from '@app/shared/sources';
+```
+
+See `templates/html-video/main.ts` for a minimal reference, or `templates/react-video/main.tsx` for a React one.
 
 ## Syncing changes back to templates
 
 When you've made improvements in `src/` that should become the new baseline:
 
 ```bash
-pnpm -F sandbox sync
+pnpm -F @videojs/sandbox sync
 ```
 
 This shows a colored diff of every changed file, then prompts for confirmation before copying `src/` changes into `templates/`. Files that only exist in `templates/` are left untouched.
@@ -47,12 +53,20 @@ This shows a colored diff of every changed file, then prompts for confirmation b
 Sync when:
 
 - You've fixed a bug or improved a sandbox and want to preserve it for others.
-- You're preparing a commit — templates are what gets checked in.
+- You're preparing a commit — `templates/` is what gets checked in.
+
+## Resetting your sandbox
+
+To throw away your local `src/` edits and restore from `templates/`:
+
+```bash
+pnpm -F @videojs/sandbox reset
+```
+
+This previews every change first and prompts before doing anything. It overwrites modified files, deletes files that exist only in `src/`, and restores any missing template files. **Cannot be undone**, so commit or `sync` anything you want to keep first.
 
 ## Adding a new sandbox
 
 1. Create a directory in `templates/` (e.g. `templates/my-feature/`).
-2. Add an `index.html` entry point and a `main.ts` or `main.tsx`.
+2. Add an `index.html` entry point and a `main.ts` or `main.tsx`. Import shared helpers from `@app/*` as needed.
-3. Add a link to your sandbox in `templates/index.html`.
+3. Run `pnpm dev:sandbox` — `setup.ts` mirrors the new template into `src/`, and Vite picks it up automatically.
-4. Register the entry in `vite.config.ts` under `rollupOptions.input`.
-5. Run `pnpm dev` — `setup.ts` mirrors the new template into `src/` automatically.

internal/decisions/README.md

@@ -0,0 +1,66 @@
+# Decisions
+
+ADR-style records of single tactical decisions.
+
+## What Belongs Here
+
+A decision doc captures **one specific choice**: what was decided, why, and what was ruled out. Keep them short and focused — usually one page.
+
+Write one when:
+
+- You picked one approach over another and want the reasoning on record.
+- A decision depends on or supersedes an earlier one (link across docs).
+- You want future contributors to understand why the code is the way it is.
+
+## Decisions vs Design Docs
+
+Use a **design doc** (`internal/design/`) when you're specifying architecture, a feature, or a subsystem — forward-looking, often longer, status ranges from `draft` → `decided` → `implemented` → `superseded`.
+
+Use a **decision doc** here when you're recording a single trade-off within that work — short, always `status: decided`.
+
+A design doc often spawns several decision docs as implementation choices get made.
+
+## Format
+
+```markdown
+---
+status: decided
+date: 2026-01-27
+---
+
+# Title
+
+## Decision
+
+What you decided. Be direct.
+
+## Context
+
+Why this came up. What problem triggered the decision. Link related decisions.
+
+## Alternatives Considered
+
+- **Option A** — Why not chosen
+- **Option B** — Why not chosen
+
+## Rationale
+
+Why this choice wins. Keep concise.
+```
+
+## File Naming
+
+Lowercase with hyphens, name after the subject of the decision:
+
+```
+captions.md
+gestures-as-components.md
+provider-attach.md
+```
+
+## See Also
+
+- [Design Docs](/internal/design/README.md) — Architecture specs and feature designs
+- [RFCs](/rfc/README.md) — Proposals needing buy-in
+- [Plans](/.claude/plans/README.md) — Implementation notes
+- [CLAUDE.md](/CLAUDE.md#design-documents) — How these relate

internal/design/README.md

@@ -76,6 +76,7 @@ skin-theming.md
 
 ## See Also
 
+- [Decisions](/internal/decisions/README.md) — ADR-style single-decision records
 - [RFCs](/rfc/README.md) — Proposals needing buy-in
 - [Plans](/.claude/plans/README.md) — Implementation details
 - [CLAUDE.md](/CLAUDE.md#design-documents) — How these relate

package.json

@@ -8,7 +8,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/videojs/vjs-10-monorepo.git"
+    "url": "https://github.com/videojs/v10.git"
   },
   "engines": {
     "node": ">=22.19.0",

packages/cli/README.md

@@ -0,0 +1,63 @@
+# @videojs/cli
+
+[![package-badge]][package]
+
+> **⚠️ Beta** Experimental adoption in real projects.
+
+The Video.js 10 CLI. Read documentation from your terminal and generate installation snippets tailored to your setup (framework, preset, skin, media engine, package manager).
+
+## Install
+
+Run without installing:
+
+```bash
+npx @videojs/cli --help
+```
+
+Or install globally:
+
+```bash
+npm install -g @videojs/cli
+videojs --help
+```
+
+> Scripts below use `videojs` for brevity — substitute `npx @videojs/cli` if you don't install globally.
+
+## Examples
+
+Read a doc page:
+
+```bash
+videojs docs concepts/overview
+```
+
+Generate a framework-specific installation snippet interactively:
+
+```bash
+videojs docs how-to/installation \
+  --framework react \
+  --preset video \
+  --skin default \
+  --media hls \
+  --install-method pnpm \
+  --source-url https://example.com/video.m3u8
+```
+
+For full usage, run `videojs --help`, `videojs docs --help`, or `videojs config --help`.
+
+## Community
+
+If you need help with anything related to Video.js 10, or if you'd like to casually chat with other
+members:
+
+- [Join Discord Server][discord]
+- [See GitHub Discussions][gh-discussions]
+
+## License
+
+[Apache-2.0](./LICENSE)
+
+[package]: https://www.npmjs.com/package/@videojs/cli
+[package-badge]: https://img.shields.io/npm/v/@videojs/cli?label=@videojs/cli
+[discord]: https://discord.gg/JBqHh485uF
+[gh-discussions]: https://github.com/videojs/v10/discussions

packages/skins/README.md

@@ -0,0 +1,17 @@
+# @videojs/skins
+
+> **Internal package — do not install directly.**
+
+Shared skin CSS and Tailwind classname tokens for Video.js 10. Consumed by [`@videojs/html`](../html) and [`@videojs/react`](../react), which re-export the skins you actually use in an app.
+
+The package is private (`"private": true` in `package.json`) and is not published to npm.
+
+## Structure
+
+- `src/default/` — default skin tokens and CSS.
+- `src/minimal/` — minimal skin tokens and CSS.
+- `src/shared/` — tokens shared between skins.
+
+## License
+
+[Apache-2.0](../../LICENSE)