docs: add per-package READMEs and polish root docs for OSS launch

.github/workflows/ci.yml

@@ -26,8 +26,7 @@ jobs:
               - "packages/**"
               - "scripts/**"
               - "package.json"
-              - "pnpm-lock.yaml"
-              - "pnpm-workspace.yaml"
+              - "bun.lock"
               - "tsconfig*.json"
               - "Dockerfile*"
 
@@ -46,8 +45,10 @@ jobs:
       - run: bun install --frozen-lockfile
       - run: bun run build
 
-  lint-and-format:
-    name: Lint & Format
+  lint:
+    name: Lint
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -58,6 +59,18 @@ jobs:
           node-version: 22
       - run: bun install --frozen-lockfile
       - run: bun run lint
+
+  format:
+    name: Format
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: bun install --frozen-lockfile
       - run: bun run format:check
 
   typecheck:

CONTRIBUTING.md

@@ -86,10 +86,24 @@ gh pr create --title "chore: release v0.2.0" --base main
 - Search existing issues before creating a new one
 - Include reproduction steps for bugs
 
+## AI-Assisted Contributions
+
+We welcome contributions that use AI tools (GitHub Copilot, Claude, ChatGPT, etc.). If you used AI to help write a PR, there is no need to disclose it — we review all code on its merits. However:
+
+- You are responsible for the correctness of any code you submit, regardless of how it was generated.
+- AI-generated tests must actually test meaningful behavior, not just assert truthy values.
+- Do not submit AI-generated code you don't understand. If you can't explain what a change does during review, it will be rejected.
+
+## Governance
+
+Hyperframes uses a **BDFL (Benevolent Dictator for Life)** governance model. The core maintainers at HeyGen have final say on the project's direction, API design, and what gets merged. This keeps the project focused and moving fast.
+
+Community input is valued and encouraged — open issues, propose RFCs, and discuss in PRs. But final decisions rest with the maintainers.
+
 ## Code of Conduct
 
 This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
 
 ## License
 
-By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
+By contributing, you agree that your contributions will be licensed under the project's license. See [LICENSE](LICENSE) for details.

README.md

@@ -1,5 +1,7 @@
 # Hyperframes
 
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
+
 **Write HTML. Render video. Built for agents.**
 
 Hyperframes is an open-source video rendering framework that lets you create, preview, and render HTML-based video compositions — with first-class support for AI agents via MCP.
@@ -14,12 +16,14 @@ Hyperframes is an open-source video rendering framework that lets you create, pr
 ## Quick Start
 
 ```bash
-npx create-hyperframe my-video
+npx hyperframes init my-video
 cd my-video
 npx hyperframes dev      # preview in browser
 npx hyperframes render   # render to MP4
 ```
 
+**Requirements:** Node.js >= 22, FFmpeg
+
 ## How It Works
 
 Define your video as HTML with data attributes:
@@ -49,12 +53,24 @@ Define your video as HTML with data attributes:
 
 Preview instantly in the browser. Render to MP4 locally. Let AI agents compose videos using tools they already understand.
 
-<!-- TODO: Add packages table, AI agent integration section, comparison table, requirements, and docs link once packages are ported -->
+## Packages
+
+| Package                                      | Description                                                 |
+| -------------------------------------------- | ----------------------------------------------------------- |
+| [`hyperframes`](packages/cli)                | CLI — create, preview, lint, and render compositions        |
+| [`@hyperframes/core`](packages/core)         | Types, parsers, generators, linter, runtime, frame adapters |
+| [`@hyperframes/engine`](packages/engine)     | Seekable page-to-video capture engine (Puppeteer + FFmpeg)  |
+| [`@hyperframes/producer`](packages/producer) | Full rendering pipeline (capture + encode + audio mix)      |
+| [`@hyperframes/studio`](packages/studio)     | Browser-based composition editor UI                         |
+
+## Documentation
+
+Full docs at [hyperframes.heygen.com](https://hyperframes.heygen.com) — includes guides, concepts, API reference, and package documentation.
 
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute.
 
 ## License
 
-[MIT](LICENSE)
+See [LICENSE](LICENSE) for details.

packages/cli/README.md

@@ -0,0 +1,121 @@
+# hyperframes
+
+CLI for creating, previewing, and rendering HTML video compositions.
+
+## Install
+
+```bash
+npm install -g hyperframes
+```
+
+Or use directly with npx:
+
+```bash
+npx hyperframes <command>
+```
+
+**Requirements:** Node.js >= 22, FFmpeg
+
+## Commands
+
+### `init`
+
+Scaffold a new Hyperframes project from a template:
+
+```bash
+npx hyperframes init my-video
+cd my-video
+```
+
+### `dev`
+
+Start the live preview studio in your browser:
+
+```bash
+npx hyperframes dev
+# Server running at http://localhost:3000
+# Watching for changes...
+```
+
+### `render`
+
+Render a composition to MP4:
+
+```bash
+npx hyperframes render ./my-composition.html -o output.mp4
+```
+
+### `lint`
+
+Validate your Hyperframes HTML:
+
+```bash
+npx hyperframes lint ./my-composition.html
+```
+
+### `compositions`
+
+List compositions found in the current project:
+
+```bash
+npx hyperframes compositions
+```
+
+### `benchmark`
+
+Run rendering benchmarks:
+
+```bash
+npx hyperframes benchmark ./my-composition.html
+```
+
+### `doctor`
+
+Check your environment for required dependencies (Chrome, FFmpeg, Node.js):
+
+```bash
+npx hyperframes doctor
+```
+
+### `browser`
+
+Manage the bundled Chrome/Chromium installation:
+
+```bash
+npx hyperframes browser
+```
+
+### `info`
+
+Print version and environment info:
+
+```bash
+npx hyperframes info
+```
+
+### `docs`
+
+Open the documentation in your browser:
+
+```bash
+npx hyperframes docs
+```
+
+### `upgrade`
+
+Upgrade Hyperframes to the latest version:
+
+```bash
+npx hyperframes upgrade
+```
+
+## Documentation
+
+Full documentation: [hyperframes.heygen.com/packages/cli](https://hyperframes.heygen.com/packages/cli)
+
+## Related packages
+
+- [`@hyperframes/core`](../core) — types, parsers, frame adapters
+- [`@hyperframes/engine`](../engine) — rendering engine
+- [`@hyperframes/producer`](../producer) — render pipeline
+- [`@hyperframes/studio`](../studio) — composition editor UI