From efa3d42a4dd68e4f2ebe0f00caa8b194c2a08788 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 12 Feb 2026 14:22:54 +0000
Subject: [PATCH] docs(ai): update quickstart and contributing (agent)

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

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ca386655..c30d2c06 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,6 +41,8 @@ Automated agents contributing to this repository should follow these rules:
 - **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 (like URL-first playback, token-first design system) and constraints before starting work.
+- **Review KNOWN_ISSUES.md**: Before starting development or debugging, review `KNOWN_ISSUES.md` to avoid investigating pre-existing failures or limitations.
+- **Dependency Upgrades**: Major or risky dependency upgrades must be documented by creating a Markdown file in the `issues/` directory (e.g., `issues/upgrade-<pkg>.md`) with a plan and risk assessment, rather than opening an immediate PR.
 - **Efficiency**: Prefer running targeted or sharded tests (e.g., `npm run test:unit:shard1`, `shard2`, or `shard3`) to conserve resources during iteration.
 
 ## Submitting a Pull Request
diff --git a/README.md b/README.md
index aada60a8..4d6c0b64 100644
--- a/README.md
+++ b/README.md
@@ -181,6 +181,8 @@ To run **bitvid** locally:
    npm run lint
    ```
 
+   _Tip: Use `npm run test:unit:shard1` (or `shard2`/`shard3`) for faster local feedback._
+
 #### Quick Reference
 
 - **Run unit tests**: `npm run test:unit`