From 7b9e08de9ce2953fbc2a50432db2d06d124d825f Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 29 Jan 2026 14:28:51 +0000
Subject: [PATCH] docs(ai): update quickstart and contributing (agent)

- Update `README.md`:
  - Change `npm install` to `npm ci` for consistent setup.
  - Add "Quick Reference" section for common commands.
  - Explicitly label the video post example as "Quickstart: Send your first video post" and refine intro text.
  - Correct `npm run format` description.
- Update `CONTRIBUTING.md`:
  - Clarify `npm run format` targets.
  - Minor refinements to "Submitting a Pull Request" and "Agent PR Conventions" sections.
- Verified all documentation matches current codebase state.

Co-authored-by: PR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
---
 CONTRIBUTING.md |  5 +++--
 README.md       | 14 ++++++++++----
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0ca16ea0..576ddbe5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -35,6 +35,7 @@ If we later introduce **dual-licensing** options (e.g., commercial licenses for
 ## Agent PR Conventions
 
 Automated agents contributing to this repository should follow these rules:
+
 - **Atomic Commits**: Keep changes small, focused, and self-contained.
 - **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)`).
@@ -46,7 +47,7 @@ Automated agents contributing to this repository should follow these rules:
 
 1. Fork the repository and create a new branch from `main`.
 2. Make your changes, adding tests if applicable.
-3. Run `npm run format`, `npm run lint`, and unit tests (e.g. `npm run test:unit` or a shard like `npm run test:unit:shard1`) to ensure quality.
+3. Run `npm run format`, `npm run lint`, and unit tests (e.g. `npm run test:unit` or a shard like `npm run test:unit:shard1`) to ensure quality before pushing.
 4. (Optional) Run `npm run test:visual` if you made UI changes.
 5. (Optional) Run domain-specific tests if relevant (e.g., `npm run test:dm:unit` for Direct Messages).
 6. Push your branch and open a Pull Request against the `main` branch.
@@ -132,7 +133,7 @@ To set up the project locally:
    npm run format
    npm run lint
    ```
-   *Note: `npm run format` currently only targets CSS, HTML, and Markdown 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.
diff --git a/README.md b/README.md
index 425ee671..32c951a5 100644
--- a/README.md
+++ b/README.md
@@ -166,6 +166,12 @@ To run **bitvid** locally:
 
    _Note: If you prefer manual steps, you can run `npm run build` followed by `npx serve` or `python -m http.server 8000`._
 
+#### Quick Reference
+
+- **Run unit tests**: `npm run test:unit`
+- **Format code**: `npm run format`
+- **Lint code**: `npm run lint`
+
 ### Dev Container
 
 This project includes a `.devcontainer` configuration. If you use VS Code, you can open the project in a container to get a pre-configured environment with all dependencies installed.
@@ -222,9 +228,9 @@ To quickly view the location of these artifacts:
 
 Use these artifacts to inspect the UI state at the moment of failure and diagnose rendering issues or regressions.
 
-### Send your first video post
+### Quickstart: Send your first video post
 
-Use the event builders in `js/nostrEventSchemas.js` (the source of truth for all event definitions) to construct valid video notes. See [`docs/nostr-event-schemas.md`](docs/nostr-event-schemas.md) for full schema documentation.
+To programmatically publish videos, use the event builders in `js/nostrEventSchemas.js` (the source of truth for all event definitions) to construct valid video notes. See [`docs/nostr-event-schemas.md`](docs/nostr-event-schemas.md) for full schema documentation.
 
 ```javascript
 import { buildVideoPostEvent } from "./js/nostrEventSchemas.js";
@@ -279,7 +285,7 @@ package scripts to keep formatting, linting, and generated output consistent:
 - **Core scripts:**
 
   ```bash
-  npm run format    # normalize CSS/HTML/JS/MD sources with Prettier + tailwindcss plugin
+  npm run format    # normalize CSS/HTML/MD/Config sources with Prettier + tailwindcss plugin
   npm run lint:css  # enforce design token usage and guard against raw hex colors
   npm run build     # run the Tailwind build locally (output remains gitignored)
   ```
@@ -308,7 +314,7 @@ commands from the repo root:
 1. Install dependencies (only required after cloning or when packages change):
 
    ```bash
-   npm install
+   npm ci
    ```
 
 2. Rebuild the Tailwind bundle for local verification (the output stays