Merge pull request #2439 from PR0M3TH3AN/docs/align-docs-13610324471753771843

docs: align development docs with codebase behavior

CONTRIBUTING.md

@@ -164,6 +164,12 @@ To set up the project locally:
    npm run test:dm:integration
    ```
 
+   To run smoke tests (critical path verification):
+
+   ```bash
+   npm run test:smoke
+   ```
+
    To aggregate telemetry from test logs:
 
    ```bash
@@ -180,6 +186,7 @@ To set up the project locally:
    - **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, design tokens, Tailwind guards, file size limits, innerHTML usage, asset references, and Service Worker compatibility. (Note: There is no ESLint configuration for JavaScript logic; this step focuses on style and design system guards).
    - **Note**: `npm run lint` includes an asset verification step (`lint:assets`) which checks the `dist/` directory. For full coverage, run `npm run build` before linting.
+   - **Audit**: `npm run audit` runs a design system audit and generates `REMEDIATION_REPORT.md` with auto-fix suggestions.
 
 6. **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.

README.md

@@ -215,6 +215,8 @@ For detailed architecture and system documentation, see the [Documentation Index
 - **Run headless E2E tests**: `npm run test:e2e`
 - **Run visual regression tests**: `npm run test:visual`
 - **Update visual baselines**: `npm run test:visual:update`
+- **Run smoke tests**: `npm run test:smoke` (Critical path verification)
+- **Run design system audit**: `npm run audit` (Generates remediation report)
 - **Aggregate telemetry**: `npm run telemetry:aggregate`
 - **Cancel CI runs**: See [`docs/cancelling-ci-runs.md`](docs/cancelling-ci-runs.md) for a script to clear pending workflows.
 

REMEDIATION_REPORT.md

@@ -1,4 +1,4 @@
-# Daily Design System Audit Report (2026-02-12)
+# Daily Design System Audit Report (2026-02-13)
 
 Headline: ✓ No violations
 

docs/agents/task-logs/daily/2026-02-13_01-00-00_docs-alignment-agent_started.md

@@ -0,0 +1,8 @@
+# Agent Task Log Entry
+
+- **Date:** 2026-02-13
+- **Agent:** docs-alignment-agent
+- **Prompt:** bitvid-docs-alignment-agent.md
+- **Status:** started
+- **Branch:** docs/align-docs
+- **Summary:** Task claimed — execution beginning

docs/agents/task-logs/daily/2026-02-13_01-30-00_docs-alignment-agent_completed.md

@@ -0,0 +1,8 @@
+# Agent Task Log Entry
+
+- **Date:** 2026-02-13
+- **Agent:** docs-alignment-agent
+- **Prompt:** bitvid-docs-alignment-agent.md
+- **Status:** completed
+- **Branch:** docs/align-docs
+- **Summary:** Updated README.md and CONTRIBUTING.md to include `npm run test:smoke` and `npm run audit`

test_logs/TEST_LOG_2026-02-13_docs_alignment.md

@@ -0,0 +1,18 @@
+# Test Log - 2026-02-13 Docs Alignment
+
+## Validated Commands
+
+The following commands were verified to match the updated documentation:
+
+- `npm ci` (Success)
+- `npm run lint` (Success)
+- `npm run audit` (Success, generated `REMEDIATION_REPORT.md`)
+
+## Observations
+
+- `npm run lint:assets` skipped because `dist/asset-manifest.json` was missing (requires build). This is expected behavior as documented ("For full coverage, run `npm run build` before linting").
+- `npm run lint:sw-compat` skipped due to missing git history/HEAD^ in the sandbox environment. This is acceptable.
+
+## Artifacts
+
+- `REMEDIATION_REPORT.md` (Generated by `npm run audit`)