docs(ai): update quickstart and contributing (agent)

Co-authored-by: PR0M3TH3AN <[email protected]>

CONTRIBUTING.md

@@ -22,15 +22,15 @@ See [https://developercertificate.org/](https://developercertificate.org/) for t
 
 ## (Optional) Contributor License Agreement (CLA)
 
-If we later introduce **dual-licensing** options (e.g., commercial licenses for enterprises), we may add an *optional* CLA for contributors who want to grant relicense rights. You will be asked to agree explicitly in any PR that requires it. We will keep community use under GPL-3.0-or-later.
+If we later introduce **dual-licensing** options (e.g., commercial licenses for enterprises), we may add an _optional_ CLA for contributors who want to grant relicense rights. You will be asked to agree explicitly in any PR that requires it. We will keep community use under GPL-3.0-or-later.
 
 ## Code Guidelines
 
-* Prefer small, focused PRs.
-* Add tests where reasonable; keep UI accessible.
-* Follow existing formatting/lint rules.
-* Update docs and user-facing text when behavior changes.
-* Do not commit `css/tailwind.generated.css`; it is generated at build time.
+- Prefer small, focused PRs.
+- Add tests where reasonable; keep UI accessible.
+- Follow existing formatting/lint rules.
+- Update docs and user-facing text when behavior changes.
+- Do not commit `css/tailwind.generated.css`; it is generated at build time.
 
 ## Agent PR Conventions
 
@@ -40,7 +40,7 @@ Automated agents contributing to this repository should follow these rules:
 - **Descriptive Titles**: Use clear, semantic titles (e.g., `fix(ui): resolve upload modal overflow`).
 - **Commit Messages**: Use the convention `type(scope): description (agent)` (e.g., `fix(ai): formatting (agent)` or `docs(ai): update quickstart (agent)`).
 - **Reference Issues**: Link to relevant issues in the PR description.
-- **Review AGENTS.md**: Always consult `AGENTS.md` for specific architectural guidelines and constraints before starting work.
+- **Review AGENTS.md**: Always consult `AGENTS.md` for specific architectural guidelines (like URL-first playback, token-first design system) and constraints before starting work.
 - **Efficiency**: Prefer running targeted or sharded tests (e.g., `npm run test:unit:shard1`) to conserve resources during iteration.
 
 ## Submitting a Pull Request
@@ -94,46 +94,57 @@ To set up the project locally:
 
 1. **Install Dependencies**:
    Use `npm ci` to ensure you get the exact dependencies from `package-lock.json`.
+
    ```bash
    npm ci
    ```
 
 2. **Start the Application**:
+
    ```bash
    npm start
    ```
+
    This builds the project and starts a local server.
 
    **Or, build manually:**
+
    ```bash
    npm run build
    ```
+
    (This runs `npm run build:css` to generate Tailwind styles.)
 
 3. **Run Tests**:
+
    ```bash
    npm run test:unit
    ```
-   *Note: Running the full suite (`npm run test:unit`) is resource-intensive and may time out in some environments. We strongly recommend using sharded runs for local development: `npm run test:unit:shard1`.*
+
+   _Note: Running the full suite (`npm run test:unit`) is resource-intensive and may time out in some environments. We strongly recommend using sharded runs for local development: `npm run test:unit:shard1`._
 
    You can also run end-to-end and visual tests:
+
    ```bash
    npm run test:e2e
    npm run test:visual
    ```
 
    For Direct Message features, run:
+
    ```bash
    npm run test:dm:unit
    npm run test:dm:integration
    ```
 
 4. **Format & Lint**:
+
    ```bash
    npm run format
    npm run lint
    ```
-   *Note: `npm run format` currently targets CSS, HTML, Markdown, and Tailwind config files.*
+
+   _Note: `npm run format` currently targets CSS, HTML, Markdown, and Tailwind config files._
 
 5. **Git Hooks (Optional)**:
    We provide a script to set up a git pre-commit hook that runs linting and CSS builds automatically before you commit.
@@ -146,6 +157,7 @@ For a full guide, see the [Local Setup section in README.md](./README.md#local-s
 ### Troubleshooting
 
 - **Browserslist Warning**: If you see `Browserslist: caniuse-lite is outdated` during the build, run:
+
   ```bash
   npx update-browserslist-db@latest
   ```
@@ -159,6 +171,7 @@ For a full guide, see the [Local Setup section in README.md](./README.md#local-s
 This project includes a `.devcontainer` configuration for VS Code. It provides a pre-configured environment with Node.js 22, the GitHub CLI, and necessary extensions.
 
 To use it:
+
 1. Open the project in VS Code.
 2. When prompted, re-open in Container (or use the command palette: "Dev Containers: Reopen in Container").
 3. The container will automatically:

README.md

@@ -235,6 +235,7 @@ To programmatically publish videos, use the event builders in `js/nostrEventSche
 ```javascript
 import { buildVideoPostEvent } from "./js/nostrEventSchemas.js";
 
+// Ensure dependencies are installed (npm ci)
 // 1. Build the event object (useful for inspection or custom publishing)
 const event = buildVideoPostEvent({
   // Provide your hex pubkey (not npub)

css/docs.css

@@ -45,7 +45,8 @@
   border-radius: var(--radius-md);
   color: var(--text-muted);
   text-decoration: none;
-  transition: background-color var(--motion-duration-fast) ease,
+  transition:
+    background-color var(--motion-duration-fast) ease,
     color var(--motion-duration-fast) ease;
 }
 

package.json

@@ -11,10 +11,10 @@
     "build:beacon:bundle": "node scripts/build-beacon.mjs",
     "build:beacon": "npm run build:beacon:bundle && npm run lint:inline-styles",
     "ci:beacon": "npm run build:beacon",
-    "format": "prettier --cache --write css/tailwind.source.css css/tokens.css \"docs/**/*.html\" tailwind.config.cjs README.md",
+    "format": "prettier --cache --write css/tailwind.source.css css/tokens.css css/docs.css \"docs/**/*.html\" tailwind.config.cjs README.md CONTRIBUTING.md",
     "audit": "node scripts/daily-design-system-audit.mjs",
     "lint": "npm run lint:css && npm run lint:hex && npm run lint:inline-styles && npm run lint:tokens && npm run lint:tailwind-brackets && npm run lint:tailwind-colors",
-    "lint:css": "stylelint css/tailwind.source.css css/tokens.css",
+    "lint:css": "stylelint css/tailwind.source.css css/tokens.css css/docs.css",
     "lint:hex": "node scripts/check-hex.js",
     "lint:inline-styles": "node scripts/check-inline-styles.mjs",
     "lint:tokens": "node scripts/check-design-tokens.mjs --check=tokens",