From a3cc4a7456dda585eff1bb6cd1bbd7ee9907b2d4 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Sun, 1 Feb 2026 16:37:07 +0000
Subject: [PATCH] docs: align build instructions and lint scope with codebase
 behavior

Updates CONTRIBUTING.md and README.md to accurately reflect that:
- `npm start` builds to and serves the `dist/` directory.
- `npm run format` targets CSS, HTML, MD, and config (not JS logic).
- `npm run lint` targets styles, tokens, and hex codes (no ESLint).
- Manual build steps should serve `dist` via `npx serve dist`.

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

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 265b42d9..1883c89f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -111,9 +111,10 @@ To set up the project locally:
 
    ```bash
    npm run build
+   npx serve dist
    ```
 
-   (This runs `npm run build:css` to generate Tailwind styles.)
+   (The build command populates the `dist/` directory, which you can then serve locally.)
 
 3. **Run Tests**:
 
@@ -144,8 +145,8 @@ To set up the project locally:
    npm run lint
    ```
 
-   _Note: `npm run format` currently targets CSS, HTML, Markdown, and Tailwind config files._
-   _Note: `npm run lint` checks for CSS errors, hex color usage (use tokens instead), inline styles, and design token compliance._
+   - **Format**: Targets CSS, HTML, Markdown, and config files. (Note: JavaScript files are not currently auto-formatted by this command).
+   - **Lint**: Checks for CSS errors, hex color usage, inline styles, and design token compliance. (Note: There is no ESLint configuration for JavaScript logic; this step focuses on style and design system guards).
 
 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 77fe9d71..a98c8d66 100644
--- a/README.md
+++ b/README.md
@@ -164,13 +164,13 @@ To run **bitvid** locally:
    http://localhost:3000
    ```
 
-   _Note: If you prefer manual steps, you can run `npm run build` followed by `npx serve` or `python -m http.server 8000`._
+   _Note: If you prefer manual steps, you can run `npm run build` followed by `npx serve dist`._
 
 #### Quick Reference
 
 - **Run unit tests**: `npm run test:unit`
-- **Format code**: `npm run format`
-- **Lint code**: `npm run lint`
+- **Format code**: `npm run format` (CSS, HTML, MD, Config)
+- **Lint code**: `npm run lint` (Styles, Tokens, Hex - no JS logic)
 
 ### Dev Container