docs: clarify CODEOWNERS roles and CI gate scope

Author: clean6378-max-it

.github/CODEOWNERS

@@ -1,16 +1,20 @@
 # Code owners — auto-requested as reviewers on matching paths.
 # Last match wins; see https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 #
-# Review expectation: PR authors wait for at least one CODEOWNERS approval before merge.
-# Do not self-merge without review, even on docs-only changes.
+# Roles:
+#   Development + code review: @clean6378-max-it (Chen), @timon0305 (Zilin)
+#   Final approval + merge:    @wpak-ai (Will Pak)
+#
+# PR authors do not self-merge. Get a code review from Chen or Zilin, then final
+# approval from Will before merge.
 
-# Default owner for the repository.
-*                       @clean6378-max-it
+# Default owners for the repository.
+*                       @clean6378-max-it @timon0305 @wpak-ai
 
 # Docs and contributor process
-/docs/                  @clean6378-max-it
-/CONTRIBUTING.md        @clean6378-max-it
-/README.md              @clean6378-max-it
+/docs/                  @clean6378-max-it @timon0305 @wpak-ai
+/CONTRIBUTING.md        @clean6378-max-it @timon0305 @wpak-ai
+/README.md              @clean6378-max-it @timon0305 @wpak-ai
 
 # CI and workflow changes
-/.github/               @clean6378-max-it
+/.github/               @clean6378-max-it @timon0305 @wpak-ai

README.md

@@ -145,7 +145,7 @@ claude-code-chat-browser/
 
 See **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for full setup, conventions, and where to change each layer. New contributors should follow **[`docs/onboarding.md`](docs/onboarding.md)** for a first-PR walkthrough and reading order.
 
-**Maintainer coverage:** commit activity is currently concentrated on a small set of identities (bus-factor risk). Mitigations: [`.github/CODEOWNERS`](.github/CODEOWNERS) for review routing and [`docs/onboarding.md`](docs/onboarding.md) so additional contributors can ramp quickly.
+**Maintainer coverage:** commit activity is currently concentrated on a small set of identities (bus-factor risk). Mitigations: [`.github/CODEOWNERS`](.github/CODEOWNERS) splits development/code review (@clean6378-max-it, @timon0305) from final approval and merge (@wpak-ai), plus [`docs/onboarding.md`](docs/onboarding.md) for contributor ramp-up.
 
 Quick start:
 

docs/onboarding.md

@@ -62,14 +62,14 @@ python app.py --port 5000
 
 ### 5. Run the full local gate
 
-CI runs these on Ubuntu, Windows, and macOS. Run them locally before opening a PR:
+Run these locally before opening a PR. In CI, **ruff** (`check` + `format --check`) runs on Ubuntu, Windows, and macOS. **mypy** runs only in the Ubuntu job; run it locally before Python-heavy changes. **pip-audit**, **pytest**, integration tests, and **Vitest** also run on all three platforms in CI.
 
 ```bash
-# Lint + format (required)
+# Lint + format (CI: Ubuntu + Windows + macOS)
 ruff check .
 ruff format --check .
 
-# Type check (Ubuntu CI job; run locally before Python-heavy changes)
+# Type check (CI: Ubuntu only)
 mypy -p api -p utils -p models -p scripts
 
 # Security audit (production deps)
@@ -102,7 +102,12 @@ Open a pull request against **`master`** on `cppalliance/claude-code-chat-browse
 
 ### 7. Review
 
-[`.github/CODEOWNERS`](../.github/CODEOWNERS) auto-requests reviewers on new PRs. **Do not self-merge** — wait for at least one approval. Address review feedback in follow-up commits on the same branch.
+[`.github/CODEOWNERS`](../.github/CODEOWNERS) auto-requests reviewers on new PRs. **Do not self-merge.**
+
+1. **Code review** from @clean6378-max-it (Chen) or @timon0305 (Zilin). They own development and technical review on this repo.
+2. **Final approval and merge** from @wpak-ai (Will Pak) after code review is done.
+
+Address review feedback in follow-up commits on the same branch.
 
 ## Good first issues
 
@@ -120,7 +125,7 @@ Recent commit history is concentrated on a small set of identities. If those mai
 
 **Mitigations in this repo:**
 
-- **[`.github/CODEOWNERS`](../.github/CODEOWNERS)** — routes review requests so PRs do not rely on ad-hoc pings.
-- **This onboarding path** — lowers the ramp for a second reviewer or contributor to run gates and ship safely.
+- **[`.github/CODEOWNERS`](../.github/CODEOWNERS)** — @clean6378-max-it and @timon0305 for development and code review; @wpak-ai for final approval and merge.
+- **This onboarding path** — lowers the ramp for additional contributors to run gates and ship safely.
 
 If you are joining as a reviewer, read the [suggested reading order](#suggested-reading-order) and run the [full local gate](#5-run-the-full-local-gate) once on `master` before approving your first PR.