From 653d66e70075ca60ecdbd2b12e6470b3640af303 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Mon, 28 Sep 2026 15:29:02 +0300
Subject: [PATCH 01/16] ci: add contributor guidelines, agent skills and commit
 message checks

Contributors and AI agents had no shared rules for commits, code or UI,
so every change drifted a little from the last one. Add guides for the
commit format, coding standards, UI and fixup commits, skills and roles
that carry the same rules for agents, git hooks that format staged files
and check commit messages, a CI workflow that validates the pull request
title and every commit, a skills check, and pull request and issue
templates.
---
 .claude/agents/a11y-reviewer.md               |  11 ++
 .claude/agents/devtools-reviewer.md           |  17 ++
 .claude/agents/inspector-engineer.md          |  12 ++
 .claude/agents/ui-engineer.md                 |  12 ++
 .claude/skills/devtools-commit/SKILL.md       |  34 ++++
 .claude/skills/devtools-inspector/SKILL.md    |  53 +++++++
 .claude/skills/devtools-ui/SKILL.md           |  36 +++++
 .claude/skills/devtools-verify/SKILL.md       |  57 +++++++
 .gitattributes                                |   4 +
 .githooks/commit-msg                          |   3 +
 .githooks/pre-commit                          |   8 +
 .github/ISSUE_TEMPLATE/bug_report.yml         |  48 ++++++
 .github/ISSUE_TEMPLATE/feature_request.yml    |  29 ++++
 .github/PULL_REQUEST_TEMPLATE.md              |  26 ++++
 .github/workflows/ci.yml                      |   3 +
 .github/workflows/commit-message.yml          |  32 ++++
 .gitmessage                                   |  16 ++
 AGENTS.md                                     |  17 ++
 CLAUDE.md                                     |  17 ++
 CONTRIBUTING.md                               | 131 +++++++++-------
 README.md                                     |  21 +++
 docs/contributing/coding-standards.md         |  50 ++++++
 .../contributing/commit-message-guidelines.md | 104 +++++++++++++
 docs/contributing/ui-guidelines.md            |  69 +++++++++
 docs/contributing/using-fixup-commits.md      |  35 +++++
 package.json                                  |   3 +
 scripts/commit-message.mjs                    | 145 ++++++++++++++++++
 scripts/validate-skills.mjs                   |  85 ++++++++++
 28 files changed, 1025 insertions(+), 53 deletions(-)
 create mode 100644 .claude/agents/a11y-reviewer.md
 create mode 100644 .claude/agents/devtools-reviewer.md
 create mode 100644 .claude/agents/inspector-engineer.md
 create mode 100644 .claude/agents/ui-engineer.md
 create mode 100644 .claude/skills/devtools-commit/SKILL.md
 create mode 100644 .claude/skills/devtools-inspector/SKILL.md
 create mode 100644 .claude/skills/devtools-ui/SKILL.md
 create mode 100644 .claude/skills/devtools-verify/SKILL.md
 create mode 100644 .gitattributes
 create mode 100755 .githooks/commit-msg
 create mode 100755 .githooks/pre-commit
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .github/workflows/commit-message.yml
 create mode 100644 .gitmessage
 create mode 100644 docs/contributing/coding-standards.md
 create mode 100644 docs/contributing/commit-message-guidelines.md
 create mode 100644 docs/contributing/ui-guidelines.md
 create mode 100644 docs/contributing/using-fixup-commits.md
 create mode 100755 scripts/commit-message.mjs
 create mode 100644 scripts/validate-skills.mjs

diff --git a/.claude/agents/a11y-reviewer.md b/.claude/agents/a11y-reviewer.md
new file mode 100644
index 0000000..7c3d02a
--- /dev/null
+++ b/.claude/agents/a11y-reviewer.md
@@ -0,0 +1,11 @@
+---
+name: a11y-reviewer
+description: Audits the devtools panel and the demo app for accessibility and visual consistency with axe, contrast checks and keyboard walkthroughs. Use before a pull request that changes UI, or when asked to review a page.
+tools: Read, Grep, Glob, Bash
+---
+
+You review accessibility and visual consistency. You don't edit files; you report.
+
+Follow the browser checks in the `devtools-verify` skill: run axe on each page in dark and light color schemes, check horizontal overflow at 1280px and 360px, and walk every interactive element with the keyboard (focus visible, arrow keys in trees and lists, `Escape` closes popups and clears search). Check text contrast by hand where axe can't (gradients, text over images) and compare each page against `docs/contributing/ui-guidelines.md`.
+
+Report findings ranked by user impact, each with the page, the element, what fails (rule or measured contrast), and a concrete fix. Say which pages you checked and how.
diff --git a/.claude/agents/devtools-reviewer.md b/.claude/agents/devtools-reviewer.md
new file mode 100644
index 0000000..3f5bec5
--- /dev/null
+++ b/.claude/agents/devtools-reviewer.md
@@ -0,0 +1,17 @@
+---
+name: devtools-reviewer
+description: Reviews a change or pull request against this repository's coding standards, commit guidelines and data-collection rules. Use before opening a pull request or when asked to review a diff.
+tools: Read, Grep, Glob, Bash
+---
+
+You review changes to the Angular devtools. You don't edit files; you report.
+
+Check the diff against:
+
+- `docs/contributing/coding-standards.md`: TypeScript and Angular rules, and the page-side rules (debug APIs, stable ids, no DOM writes, `pageId`, expiry, cheap pushes, safe serialization).
+- `docs/contributing/ui-guidelines.md` for anything under `app/`.
+- `docs/contributing/commit-message-guidelines.md` for commit messages and the pull request title.
+- Tests: every behavior change has one, and agent tools changed together with their tests and descriptions.
+- Generated output: `extension/ui` rebuilt and committed when `app/` changed.
+
+Verify claims by reading the code, and run `pnpm test:devtools` and the `ngc` template check when in doubt. Report only real problems, ranked by impact, each with file:line, what is wrong, why it matters and a concrete fix.
diff --git a/.claude/agents/inspector-engineer.md b/.claude/agents/inspector-engineer.md
new file mode 100644
index 0000000..1ba46c5
--- /dev/null
+++ b/.claude/agents/inspector-engineer.md
@@ -0,0 +1,12 @@
+---
+name: inspector-engineer
+description: Owns how inspectors collect data from the running app and serve it to the panel and to agents. Use for new inspectors, wrong or noisy data, unstable ids, tabs overwriting each other, heavy polling, and new MCP tools.
+---
+
+You are the inspector engineer for the Angular devtools.
+
+Follow the `devtools-inspector` skill and the "Reading data from the page" section of `docs/contributing/coding-standards.md`. Read Angular through its debug APIs and check every field you rely on against `node_modules/@angular/core/fesm2022`. Keep ids stable with `WeakMap`s, never write to the app's DOM, send `pageId` with every report, expire and forget pages on the server, and skip unchanged pushes.
+
+Put new logic in its own module and keep edits to `overlay.ts` and `devframe.ts` small. Add jsdom tests with a fake `ng` for every collector change and keep `pnpm test:devtools` green.
+
+Return a short summary: what was wrong, what you changed (file:line), the tests you added, and anything left undone.
diff --git a/.claude/agents/ui-engineer.md b/.claude/agents/ui-engineer.md
new file mode 100644
index 0000000..9e9d631
--- /dev/null
+++ b/.claude/agents/ui-engineer.md
@@ -0,0 +1,12 @@
+---
+name: ui-engineer
+description: Builds and restyles pages in the devtools panel (app/) so they match the design system, work with the keyboard and pass axe. Use for new inspector pages, UI polish, dropdowns, toolbars, empty states and theme changes.
+---
+
+You are the UI engineer for the Angular devtools panel.
+
+Follow the `devtools-ui` skill and `docs/contributing/ui-guidelines.md`. Use the theme variables and SCSS mixins, the shared `app-select` dropdown and the page anatomy (intro, sticky toolbar, list or tree with a detail panel, loading, error, empty and no-match states). Headings start at `h2`.
+
+Don't change RPC names, data shapes or behavior. If the data a page shows is wrong, stop and report it for the inspector engineer instead of working around it in the template.
+
+Before you finish, run the checks in the `devtools-verify` skill that apply to UI (format, `ngc` template check, the axe and 360px audit on the pages you touched) and list what you ran. Return a short summary of what changed, per file.
diff --git a/.claude/skills/devtools-commit/SKILL.md b/.claude/skills/devtools-commit/SKILL.md
new file mode 100644
index 0000000..8a7ec5a
--- /dev/null
+++ b/.claude/skills/devtools-commit/SKILL.md
@@ -0,0 +1,34 @@
+---
+name: devtools-commit
+description: Write commit messages and pull request titles and descriptions for this repository, following this project's commit format and scopes. Use whenever you commit, split work into commits, or open or update a pull request.
+---
+
+# Commits and pull requests
+
+The rules are in `docs/contributing/commit-message-guidelines.md`. Summary:
+
+```
+<type>(<scope>): <short summary>
+
+<body: why the change is needed, old vs new behavior, imperative tense, 20+ characters>
+
+<footer: Fixes #123 | BREAKING CHANGE: ... | DEPRECATED: ...>
+```
+
+- Types: `feat`, `fix`, `perf`, `refactor`, `test`, `docs`, `build`, `ci`, `revert`.
+- Scopes: `hub`, `ui`, `popup`, `overlay`, `components`, `signals`, `injectors`, `router`, `forms`, `store`, `pipes`, `http`, `analog`, `mcp`, `extension`, `vite`, `demo`, `deps`. Leave the scope out for cross-cutting changes.
+- Summary: imperative, lowercase first letter, no period, header under 100 characters.
+
+## Pull requests
+
+- Pull requests are squash merged; the title becomes the commit on `main`, so it must follow the header format.
+- A `commit-msg` hook (`scripts/commit-message.mjs`, enabled by `pnpm install`) warns about a bad message as you commit; CI rejects it, checking the title and every commit in the pull request. Run `pnpm commit:check` before pushing, and fix flagged messages with `git commit --amend` or a reword rebase.
+- Address review feedback with fixup commits (`docs/contributing/using-fixup-commits.md`).
+- One feature per pull request, with its tests (including agent tool tests when tools change).
+- Rebuild and commit `extension/ui` when `app/` changed.
+- Fill in `.github/PULL_REQUEST_TEMPLATE.md`: what changed and why, how it was verified (see the `devtools-verify` skill), screenshots for UI changes.
+- Don't add AI attribution lines to commits or pull requests unless the maintainers ask for them.
+
+## Splitting work
+
+Group commits by area (the scope), keep each one building and passing tests where practical, and put generated output (`extension/ui`, lockfile) in the commit that needs it.
diff --git a/.claude/skills/devtools-inspector/SKILL.md b/.claude/skills/devtools-inspector/SKILL.md
new file mode 100644
index 0000000..8016d8b
--- /dev/null
+++ b/.claude/skills/devtools-inspector/SKILL.md
@@ -0,0 +1,53 @@
+---
+name: devtools-inspector
+description: Add or fix how an inspector collects data, from the page-side overlay through the devframe server to the panel and the MCP tools. Use for new inspectors, wrong or noisy data, unstable selection, tabs overwriting each other, heavy polling, and new agent tools.
+---
+
+# Inspector data pipeline
+
+Every inspector follows the same path:
+
+```
+app page (overlay.ts + <area>-collector.ts)
+  -> rpc.call('push-<area>', { pageId, ... })
+  -> devframe.ts: per-page Map, shared state '<area>', expiry, forget-<area>-page
+  -> panel page (app/src/pages/<area>.ts) via rpc.sharedState('<area>')
+  -> agent tools (ctx.agent.registerTool) and MCP resources
+```
+
+Read `docs/contributing/coding-standards.md` ("Reading data from the page") before you start.
+
+## Page side (`packages/ng-devtools/src`)
+
+- Put collection logic in its own module (`<area>-collector.ts`) and keep `overlay.ts` changes to wiring: import, attach, push, `leave()` and the returned cleanup.
+- Read Angular through the debug APIs on `window.ng` and verify each field against `node_modules/@angular/core/fesm2022` (or the library's fesm build). Known helpers:
+  - `element-id.ts`: stable `WeakMap` ids for elements (`elementId`, `elementById`).
+  - `injector-tree.ts`: `className()` strips bundler `_` prefixes, `tokenName()`, `dependenciesOf()`, environment injector walk.
+  - `serialize.ts`: safe, size-limited serialization.
+  - `router.ts` `providerOf()`: find a service through the injector resolution path.
+- Never write attributes into the app's DOM. Never run app code (validators, guards) on a timer unless the user turned recording on.
+- Pushes: send on change, skip unchanged payloads (compare with the last JSON), re-send every few cycles so the server doesn't expire the page, and avoid full DOM scans on a timer (cache, rescan after a `MutationObserver` signal).
+- Every report carries `pageId` from `claimPageId()`. Call `forget-<area>-page` from `leave()`.
+
+## Server side (`devframe.ts`, `rpc/`)
+
+- Keep a `Map<pageId, report>` with `reportedAt`, drop pages older than 15 seconds in the shared expiry interval, and write the combined value into the shared state.
+- Page actions that the panel triggers (restore, highlight, run) go panel -> `request-<area>-action` -> broadcast `<area>-action` to the page -> `<area>-action-result`, keyed by `requestId`, with a timeout.
+- Source scans in `rpc/` enrich or stand in for live data. They must return a `kind` for anything the Dashboard counts.
+
+## Panel side
+
+- Subscribe with `const state = await rpc.sharedState('<area>'); apply(state.value()); state.on('updated', apply)` and remove the listener through `DestroyRef`. There is no `subscribe()` on shared state.
+- Filter to the current page with the `?pageId` host parameter when the page can show several tabs; offer an "All pages" option.
+- Then follow the `devtools-ui` skill for the page itself.
+
+## Agent tools
+
+- Describe what the tool returns, where the data comes from and what an empty answer means. Answer in markdown.
+- Update descriptions in `devframe.ts` when data shapes change, and the README tool list.
+
+## Tests
+
+- Collector tests run in jsdom with a fake `ng` (see `__tests__/injector-tree.test.ts`, `component-tree.test.ts`, `ngrx-collector.test.ts`). Cover stable ids, dedupe, expiry and the Angular shapes you rely on.
+- Server tests call the RPC handlers directly (see `http-server.test.ts`, `agent-tools.test.ts`).
+- `pnpm test:devtools` must stay green.
diff --git a/.claude/skills/devtools-ui/SKILL.md b/.claude/skills/devtools-ui/SKILL.md
new file mode 100644
index 0000000..de0c4b8
--- /dev/null
+++ b/.claude/skills/devtools-ui/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: devtools-ui
+description: Build or change any page, component or style in the devtools panel (app/). Use for new inspector pages, restyles, dropdowns, toolbars, empty states, theme or palette changes, and any UI/UX or accessibility work in the panel.
+---
+
+# Devtools panel UI
+
+Read `docs/contributing/ui-guidelines.md` first; it is the source of truth for the theme, tokens and page anatomy. This skill is the working checklist.
+
+## Before you write code
+
+1. Open two recently built pages as references: `app/src/pages/di-inspector.ts` (tree + detail, keyboard, highlight) and `app/src/pages/network-inspector.ts` (toolbar, tables, forms, `app-select`).
+2. Check which data the page gets and from where (`client.scope('ng-devtools').rpc.call(...)` or `rpc.sharedState(...)`). UI work must not change RPC names or data shapes; if the data is wrong, use the `devtools-inspector` skill.
+
+## Rules
+
+- Styles are SCSS in the component `styles` field, starting with `@use 'mixins' as m;`.
+- Colors only through CSS variables (`--surface`, `--text-2`, `--accent`, ...). No hex values except brand colors on their own view (NgRx purple, Angular gradient, Analog, NativeScript, Capacitor).
+- Controls are `var(--control-h)` tall. Use `app/src/ui/select.ts` for every dropdown; never a native `<select>`.
+- Page structure: intro line, sticky toolbar (search with icon and `Escape` to clear, filters, count, actions), content (list or tree plus sticky detail on wide screens), and loading, error with Retry, empty and no-match states.
+- Headings start at `h2` and never skip a level. Section labels use `m.label`.
+- Rows are keyboard reachable (buttons or ARIA tree items with arrow keys). Selection is keyed by stable ids from the page.
+- Rows that map to an element in the app call `request-page-highlight` on hover and focus, and clear it on leave and blur.
+- Focus: `m.focus-ring` (use `-2px` inside scroll containers). Inputs use `m.field-focus`.
+- Motion 150 to 350ms, disabled under `prefers-reduced-motion`.
+- Angular: signals, `computed`, `linkedSignal`, `input`/`output`/`model`, `inject`, native control flow, `class`/`style` bindings, `host` object. No `any` in new code.
+- Copy: short and plain, no em dashes, never compare with other tools.
+- A new tab also needs: the `Tab` union in `app/src/types/tab.types.ts`, `allTabs` and the template switch in `app/src/app.ts`, an icon case in `tab-icon.ts`, and usually a Dashboard card.
+
+## Changing the brand
+
+Edit `app/src/styles/main.scss` (`$accent`) or the maps in `_palette.scss`. Never override tokens inside a page.
+
+## Verify
+
+Use the `devtools-verify` skill: template check with `ngc`, rebuild `extension/ui`, then the axe and 360px overflow audit on every page you touched, in the popup and at `/__devframes/`.
diff --git a/.claude/skills/devtools-verify/SKILL.md b/.claude/skills/devtools-verify/SKILL.md
new file mode 100644
index 0000000..21fda29
--- /dev/null
+++ b/.claude/skills/devtools-verify/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: devtools-verify
+description: Verify a devtools change the way CI and a reviewer would, then check it in a real browser with axe. Use before saying a change is done, before committing, and before opening a pull request.
+---
+
+# Verify a change
+
+## 1. The CI checks
+
+Run them in this order; all must pass:
+
+```sh
+pnpm format:check
+pnpm commit:check
+pnpm skills:check
+pnpm typecheck
+pnpm test
+pnpm test:devtools
+pnpm build
+pnpm extension:build
+pnpm devtools:build-pkg
+git status --porcelain -- extension/ui   # must be committed when app/ changed
+```
+
+`pnpm typecheck` does not type-check panel templates. Also run:
+
+```sh
+NO_COLOR=1 pnpm exec ngc -p app/tsconfig.json --noEmit
+```
+
+and treat any `error TS` or `error NG` line as a failure. Strip color codes before grepping the output, or errors slip through.
+
+## 2. Run the demos
+
+`pnpm build` is a production build and turns the in-page launcher off. For manual checks rebuild in development mode:
+
+```sh
+pnpm build --configuration development
+node dist/angular-devtools/server/server.mjs   # Angular Travel on :4000
+pnpm analog:dev                                 # Analog demo on :5173
+```
+
+Open the panel through the amber launcher on the page, at `/__devframes/`, and directly at `/__devframes/ng-devtools/?view=angular#tab=<tab>`.
+
+## 3. Browser checks
+
+With Playwright and `@axe-core/playwright` (install them in a scratch folder, not in the repo):
+
+- Every page you touched, in dark and light color schemes: axe reports no violations, there are no page errors, and `document.documentElement.scrollWidth <= innerWidth` at 1280px and 360px wide.
+- Hub docks: clicking each rail button shows the matching view and only one frame (the rail selection and the content must match after fast switching and after a reload).
+- The feature itself, with real data from the demo app (for example `/examples/<area>`).
+
+Exclude the launcher (`#ng-devtools-popup-root`) from axe runs on demo pages; it is checked through the panel.
+
+## 4. Report honestly
+
+Say which checks ran and their results. If something was skipped (no browser, no build), say so.
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..74f1113
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,4 @@
+extension/ui/** linguist-generated=true
+pnpm-lock.yaml linguist-generated=true
+*.mjs text eol=lf
+.githooks/* text eol=lf
diff --git a/.githooks/commit-msg b/.githooks/commit-msg
new file mode 100755
index 0000000..5434568
--- /dev/null
+++ b/.githooks/commit-msg
@@ -0,0 +1,3 @@
+#!/bin/sh
+node "$(git rev-parse --show-toplevel)/scripts/commit-message.mjs" --file "$1" || echo "WARNING: this commit message does not follow the guidelines."
+exit 0
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100755
index 0000000..4c25ea9
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,8 @@
+#!/bin/sh
+root="$(git rev-parse --show-toplevel)"
+files="$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.(ts|mjs|js|json|scss|css|html|md|yml|yaml)$' | grep -v '^extension/ui/')"
+[ -z "$files" ] && exit 0
+cd "$root" || exit 0
+echo "$files" | xargs pnpm --silent exec prettier --write --ignore-unknown >/dev/null 2>&1 || echo "WARNING: failed to format staged files."
+echo "$files" | xargs git add -- 2>/dev/null
+exit 0
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..ea65137
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,48 @@
+name: Bug report
+description: Something in the devtools shows wrong data, breaks, or looks wrong
+labels: [bug]
+body:
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Components
+        - Signals
+        - Injectors
+        - Router
+        - Forms
+        - NgRx store
+        - Pipes
+        - SSR & HTTP
+        - Analog
+        - Dashboard or panel shell
+        - Chrome extension
+        - Agent tools (MCP)
+        - Vite plugin or setup
+        - Demo app
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you saw, and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: Steps, a minimal repository, or the page of the demo app where it happens.
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: Angular, @santoshyadavdev/ng-devtools, browser, and Analog if used.
+  - type: textarea
+    id: extra
+    attributes:
+      label: Screenshots or logs
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..e99a38a
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,29 @@
+name: Feature request
+description: Suggest an inspector, a view or an agent tool
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to understand or debug in your Angular app?
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: What you'd like to see
+      description: The view, data or agent tool that would help. Mockups are welcome.
+    validations:
+      required: true
+  - type: textarea
+    id: angular
+    attributes:
+      label: Angular APIs involved
+      description: Debug APIs or framework internals that could provide the data, if you know them.
+  - type: checkboxes
+    id: help
+    attributes:
+      label: Contributing
+      options:
+        - label: I'd like to work on this
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..c2121af
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,26 @@
+<!--
+Title format (becomes the squash commit on main):
+<type>(<scope>): <short summary>
+See docs/contributing/commit-message-guidelines.md
+-->
+
+## What and why
+
+<!-- What does this change, and why is it needed? Link the issue: Fixes #123 -->
+
+## How it was verified
+
+- [ ] `pnpm commit:check` (commit messages follow the guidelines)
+- [ ] `pnpm format:check`
+- [ ] `pnpm typecheck` and the `ngc` template check (`pnpm exec ngc -p app/tsconfig.json --noEmit`)
+- [ ] `pnpm test` and `pnpm test:devtools`
+- [ ] `pnpm extension:build` and `extension/ui` committed (when `app/` changed)
+- [ ] Checked in the browser with axe (when the UI changed)
+
+## Screenshots
+
+<!-- For UI changes: before and after, dark theme, and a narrow width if layout changed. -->
+
+## Notes for reviewers
+
+<!-- Anything unusual: trade-offs, follow-ups, known limits. -->
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3355490..26cc48f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -39,6 +39,9 @@ jobs:
       - name: Check formatting
         run: pnpm format:check
 
+      - name: Validate agent skills and roles
+        run: pnpm skills:check
+
       - name: Type-check
         run: pnpm typecheck
 
diff --git a/.github/workflows/commit-message.yml b/.github/workflows/commit-message.yml
new file mode 100644
index 0000000..c6b2ce4
--- /dev/null
+++ b/.github/workflows/commit-message.yml
@@ -0,0 +1,32 @@
+name: Commit message
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+
+      - name: Pull request title
+        env:
+          TITLE: ${{ github.event.pull_request.title }}
+        run: node scripts/commit-message.mjs --title "$TITLE"
+
+      - name: Commit messages
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+        run: node scripts/commit-message.mjs --range "$BASE..$HEAD"
diff --git a/.gitmessage b/.gitmessage
new file mode 100644
index 0000000..8bf0c3e
--- /dev/null
+++ b/.gitmessage
@@ -0,0 +1,16 @@
+
+# <type>(<scope>): <short summary>
+#   │       │             │
+#   │       │             └─> Imperative, present tense. No period at the end.
+#   │       │
+#   │       └─> hub|ui|popup|overlay|components|signals|injectors|router|forms|store|
+#   │           pipes|http|analog|mcp|extension|vite|demo|deps (or leave it out)
+#   │
+#   └─> feat|fix|perf|refactor|test|docs|build|ci|revert
+#
+# Body (required except for docs, 20+ characters): why the change is needed,
+# and how the old behavior compares with the new one.
+#
+# Footer (optional): Fixes #123, BREAKING CHANGE: ..., DEPRECATED: ...
+#
+# See docs/contributing/commit-message-guidelines.md
diff --git a/AGENTS.md b/AGENTS.md
index f6acb89..38ac4c0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -66,3 +66,20 @@ You are an expert in TypeScript, Angular, and scalable web application developme
 - The devtools popup appears on the demo app page; click it to open the inspector panel
 - Changes to `app/src/` (devtools SPA) are visible live via `pnpm devtools:dev`; the SSR server serves the SPA built into `packages/ng-devtools/dist/public` (or the npm-published copy when it has not been built), so run `pnpm devtools:build-pkg` to refresh it
 - To publish: update the version in `packages/ng-devtools/package.json`, then run `pnpm devtools:publish` (the package build bundles the SPA)
+
+## Project guidelines, skills and roles
+
+Follow the repository guides in `docs/contributing/`:
+
+- `commit-message-guidelines.md`: `type(scope): summary` commits and pull request titles (types and this repo's scopes).
+- `coding-standards.md`: TypeScript and Angular rules, and how collectors read the inspected page (debug APIs, stable `WeakMap` ids, no DOM writes, `pageId` with expiry, cheap pushes).
+- `ui-guidelines.md`: theme tokens, brand palette, page anatomy and accessibility for the panel.
+
+Use the matching skill for the task:
+
+- `.claude/skills/devtools-ui` for panel UI work.
+- `.claude/skills/devtools-inspector` for data collection, the server side and agent tools.
+- `.claude/skills/devtools-verify` before calling a change done.
+- `.claude/skills/devtools-commit` for commits and pull requests.
+
+Roles for delegating work live in `.claude/agents/`: `ui-engineer`, `inspector-engineer`, `a11y-reviewer` and `devtools-reviewer`.
diff --git a/CLAUDE.md b/CLAUDE.md
index a34c8f6..84f6b98 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -57,3 +57,20 @@ You are an expert in TypeScript, Angular, and scalable web application developme
 - Use the `providedIn: 'root'` option for singleton services
 - Prefer the `@Service` decorator over `@Injectable({providedIn: 'root'})` for new singleton services (Angular v22+)
 - Use the `inject()` function instead of constructor injection
+
+## Project guidelines, skills and roles
+
+Follow the repository guides in `docs/contributing/`:
+
+- `commit-message-guidelines.md`: `type(scope): summary` commits and pull request titles (types and this repo's scopes).
+- `coding-standards.md`: TypeScript and Angular rules, and how collectors read the inspected page (debug APIs, stable `WeakMap` ids, no DOM writes, `pageId` with expiry, cheap pushes).
+- `ui-guidelines.md`: theme tokens, brand palette, page anatomy and accessibility for the panel.
+
+Use the matching skill for the task:
+
+- `.claude/skills/devtools-ui` for panel UI work.
+- `.claude/skills/devtools-inspector` for data collection, the server side and agent tools.
+- `.claude/skills/devtools-verify` before calling a change done.
+- `.claude/skills/devtools-commit` for commits and pull requests.
+
+Roles for delegating work live in `.claude/agents/`: `ui-engineer`, `inspector-engineer`, `a11y-reviewer` and `devtools-reviewer`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 94cd540..2385338 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,15 @@
 # Contributing to Angular DevTools
 
-Thanks for your interest in contributing! This guide covers how to set up the project and submit changes.
+Thanks for your interest in contributing! This guide covers how to set up the project, the rules we follow, and how to get a change merged.
+
+## Guidelines
+
+| Guide                                                                       | What it covers                                                    |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| [Commit message guidelines](docs/contributing/commit-message-guidelines.md) | `type(scope): summary`, types, scopes, body and footer            |
+| [Coding standards](docs/contributing/coding-standards.md)                   | TypeScript and Angular rules, how collectors read the page, tests |
+| [UI guidelines](docs/contributing/ui-guidelines.md)                         | Theme tokens, the brand palette, page anatomy, accessibility      |
+| [`AGENTS.md`](AGENTS.md)                                                    | Angular best practices for people and AI agents                   |
 
 ## Prerequisites
 
@@ -15,77 +24,93 @@ cd angular-devtools
 pnpm install
 ```
 
-## Project Structure
+`pnpm install` also turns on the git hooks in `.githooks/`: `pre-commit` formats the files you stage with Prettier, and `commit-msg` checks your message against the [commit message guidelines](docs/contributing/commit-message-guidelines.md) and warns when it doesn't follow them. It also sets [`.gitmessage`](.gitmessage) as your commit template.
+
+## Project structure
 
 ```
-app/                          # Devtools UI SPA (Angular + Vite)
-  src/app.ts                  # Root component with tab navigation
-  src/pages/                  # Dashboard, Components, Routes, Signals, Injectors, Store, Forms
-  vite.config.ts              # Vite config with Analog Angular plugin
+app/                          # The devtools panel (Angular + Vite), one view per hub dock
+  src/app.ts                  # Panel shell: header, tabs, dock views
+  src/pages/                  # Inspector pages (components, routes, signals, injectors, store, forms, pipes, network, analog, dashboard)
+  src/ui/                     # Shared UI (the dropdown)
+  src/styles/                 # Theme: palette, tokens, mixins
 packages/
-  ng-devtools/                # Publishable npm package
-    src/devframe.ts           # defineDevframe() — tool definition
-    src/overlay.ts            # Client script running in user's page
-    src/rpc/                  # Node-side RPC functions
-extension/                    # Chrome DevTools extension
-src/                          # Angular host app (demo/playground)
+  ng-devtools/                # The publishable package
+    src/hub.ts, hub-docks.ts  # @devframes/hub setup and the dock list
+    src/devframe.ts           # Server side: RPC, shared state, agent tools
+    src/overlay.ts            # Script that runs in the inspected page
+    src/*-collector.ts        # What each inspector reads from the page
+    src/popup.ts, vite.ts     # In-page launcher, Vite plugin
+    src/rpc/                  # Source scans and agent tool helpers
+extension/                    # Chrome extension (extension/ui is generated)
+src/                          # Angular Travel, the demo app
+examples/analog/              # Analog demo app
+docs/contributing/            # The guides above
+.claude/skills/, .claude/agents/  # Skills and roles for AI agents
 ```
 
 ## Development
 
 ```sh
-# Devtools UI with live RPC
-pnpm devtools:dev
-
-# Build the devtools SPA
-pnpm devtools:build
-
-# Run the Angular host app
-pnpm start
-
-# Build Chrome extension
-pnpm extension:build
+pnpm start                  # Angular Travel with the devtools on :4200
+pnpm build --configuration development && node dist/angular-devtools/server/server.mjs
+                            # SSR demo on :4000 (a plain `pnpm build` turns the launcher off)
+pnpm analog:dev             # Analog demo on :5173
+pnpm devtools:dev           # The panel on its own
+pnpm extension:build        # Rebuild the panel into extension/ui
 ```
 
-## Making Changes
+## Making changes
 
-### Adding a new RPC function
+- **A new inspector or a data fix:** follow [Reading data from the page](docs/contributing/coding-standards.md#reading-data-from-the-page-packagesng-devtools). Collection goes in its own module, reports carry a `pageId`, and the server expires and forgets pages.
+- **A new tab:** add it to `app/src/types/tab.types.ts`, `allTabs` and the template in `app/src/app.ts`, an icon in `app/src/pages/tab-icon.ts`, and usually a Dashboard card.
+- **UI changes:** follow the [UI guidelines](docs/contributing/ui-guidelines.md); use the theme variables, the SCSS mixins and the shared dropdown.
+- **Agent tools:** register them with `ctx.agent.registerTool()` or an RPC function's `agent` field, describe what they return and when they are empty, and add tests.
 
-1. Create the function in `packages/ng-devtools/src/rpc/`
-2. Register it in `packages/ng-devtools/src/devframe.ts`
-3. Call it from the UI in `app/src/pages/`
+## Testing
 
-### Adding a new tab
+```sh
+pnpm format:check
+pnpm commit:check                             # commit messages on your branch
+pnpm skills:check                             # agent skills and roles
+pnpm typecheck
+pnpm exec ngc -p app/tsconfig.json --noEmit   # panel template check
+pnpm test                                     # demo app
+pnpm test:devtools                            # devtools package
+```
 
-1. Create a component in `app/src/pages/`
-2. Import and add it to `app/src/app.ts` (imports array, tabs array, template switch)
-3. Add a card to `app/src/pages/dashboard.ts`
+For UI changes, also check the pages in a browser with axe, in dark and light themes and at a narrow width. The [devtools-verify skill](.claude/skills/devtools-verify/SKILL.md) lists the exact steps.
 
-### Adding agent tools
+## Submitting a pull request
 
-Add `agent: { description }` to any RPC function, or use `ctx.agent.registerTool()` in the devframe setup.
+1. Search the open issues and pull requests first. For a bigger feature, open an issue to discuss it before you start.
+2. Fork the repository and create a branch from `main`.
+3. Keep one feature per pull request, with its tests (and agent tool tests when tools change).
+4. If you changed `app/`, run `pnpm extension:build` and commit `extension/ui`. CI fails when it is stale.
+5. Make sure all the checks above pass.
+6. Open the pull request against `main` and fill in the template. **The title must follow the [commit message format](docs/contributing/commit-message-guidelines.md)**, for example `feat(router): show guard results for lazy routes`; it becomes the commit on `main` when the pull request is squash merged. CI checks the title and every commit message; a local `commit-msg` hook (enabled by `pnpm install`) checks each commit as you make it, and `pnpm commit:check` checks your whole branch.
+7. Address review feedback with [fixup commits](docs/contributing/using-fixup-commits.md); don't force-push over a review in progress unless asked.
 
-## Code Style
+## Working with AI agents
 
-- Follow the conventions in `AGENTS.md`
-- Use `signal()`, `computed()`, `input()`, `output()` — not decorators
-- Use `@if`/`@for`/`@switch` control flow — not structural directives
-- Keep components small with inline templates where practical
+The repository ships skills and roles for AI coding agents, so changes made with an agent follow the same rules as everyone else's. Claude Code picks them up automatically from `.claude/`; other agents can read the same files.
 
-## Testing
+### Skills (`.claude/skills/`)
 
-```sh
-pnpm test            # host app
-pnpm test:devtools   # devtools package
-pnpm typecheck       # host app + specs, devtools UI, devtools package + its tests
-pnpm format:check
-```
+| Skill                                                              | Use it when                                                                |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| [`devtools-ui`](.claude/skills/devtools-ui/SKILL.md)               | Building or restyling anything in the panel                                |
+| [`devtools-inspector`](.claude/skills/devtools-inspector/SKILL.md) | Adding an inspector or fixing the data it shows, including agent tools     |
+| [`devtools-verify`](.claude/skills/devtools-verify/SKILL.md)       | Checking a change like CI and a reviewer would, including axe in a browser |
+| [`devtools-commit`](.claude/skills/devtools-commit/SKILL.md)       | Writing commits, pull request titles and descriptions                      |
+
+### Roles (`.claude/agents/`)
 
-## Submitting a PR
+| Role                                                         | Does                                                    |
+| ------------------------------------------------------------ | ------------------------------------------------------- |
+| [`ui-engineer`](.claude/agents/ui-engineer.md)               | Builds and restyles panel pages to the design system    |
+| [`inspector-engineer`](.claude/agents/inspector-engineer.md) | Owns data collection, the server side and agent tools   |
+| [`a11y-reviewer`](.claude/agents/a11y-reviewer.md)           | Audits accessibility and visual consistency (read only) |
+| [`devtools-reviewer`](.claude/agents/devtools-reviewer.md)   | Reviews a diff against these guidelines (read only)     |
 
-1. Fork and create a branch from `main`
-2. Make your changes
-3. Verify `pnpm devtools:build` succeeds
-4. If you changed `app/`, run `pnpm extension:build` and commit `extension/ui`. CI fails when it is stale
-5. Test with `pnpm devtools:dev`
-6. Open a PR against `main`
+When you add a new area or change a rule, update the matching guide, skill and role in the same pull request so they don't drift apart. `pnpm skills:check` (also run in CI) validates their frontmatter and checks that the files and links they mention exist.
diff --git a/README.md b/README.md
index de8669f..01b887e 100644
--- a/README.md
+++ b/README.md
@@ -460,6 +460,27 @@ cp -r dist/devtools-ui/* extension/ui/
 
 The extension panel loads the SPA in static mode by default. To connect it to a live dev server for real-time RPC, the extension's content script or background service worker needs to detect the devframe's `__connection.json` on the inspected page and pass the connection to the panel. This is the same pattern the official Angular DevTools Chrome extension uses — a content script bridges the inspected page and the DevTools panel via `chrome.runtime.connect`.
 
+## Contributing
+
+Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), then the guides it links to:
+
+- [Commit message guidelines](docs/contributing/commit-message-guidelines.md): `type(scope): summary`. Pull request titles follow it too, and CI checks them.
+- [Coding standards](docs/contributing/coding-standards.md): TypeScript and Angular rules, and how inspectors read the running app.
+- [UI guidelines](docs/contributing/ui-guidelines.md): theme tokens, the brand palette (change it in one line in `app/src/styles/main.scss`), page anatomy and accessibility.
+
+### Skills and roles for AI agents
+
+If you work with an AI coding agent, the repository ships skills in [`.claude/skills/`](.claude/skills) and roles in [`.claude/agents/`](.claude/agents) that carry these rules, so agent-made changes follow the same conventions.
+
+| Skill                | For                                                           |
+| -------------------- | ------------------------------------------------------------- |
+| `devtools-ui`        | Panel UI and UX work                                          |
+| `devtools-inspector` | How inspectors collect data, the server side and agent tools  |
+| `devtools-verify`    | Checking a change like CI and a reviewer would, including axe |
+| `devtools-commit`    | Commits and pull requests                                     |
+
+Roles: `ui-engineer`, `inspector-engineer`, `a11y-reviewer` (read only) and `devtools-reviewer` (read only). See [CONTRIBUTING.md](CONTRIBUTING.md#working-with-ai-agents) for details.
+
 ## Community
 
 Join the conversation, ask questions, and share feedback on [Discord](https://discord.gg/YRTyJd6Qx).
diff --git a/docs/contributing/coding-standards.md b/docs/contributing/coding-standards.md
new file mode 100644
index 0000000..a0ea087
--- /dev/null
+++ b/docs/contributing/coding-standards.md
@@ -0,0 +1,50 @@
+# Coding standards
+
+These rules go together with the Angular rules in [`AGENTS.md`](../../AGENTS.md). Prettier formats everything; run `pnpm format` before you commit.
+
+## TypeScript
+
+- Strict mode everywhere. Avoid `any`; use `unknown` and narrow it, or a small local interface.
+- Prefer `const`. Use `readonly` for members that never change.
+- Names describe what a thing is or does. Spell words out. Booleans start with `is`, `has` or `should`.
+- No `I` prefix on interfaces and no `$` suffix on observables.
+- Prefer `for...of` over `forEach` when the loop has side effects.
+- Only catch errors you expect, and say what happens instead (fall back, skip, report).
+- Comment the why, not the what. Public functions and exported types in `packages/ng-devtools` get a short doc comment when the name alone doesn't explain them.
+
+## Angular (panel UI and demo app)
+
+- Standalone components, `input()`, `output()`, `model()`, `computed()`, `linkedSignal()` and `inject()`.
+- Don't set `standalone: true` or `changeDetection: OnPush`; both are defaults.
+- Native control flow (`@if`, `@for`, `@switch`); `class` and `style` bindings instead of `ngClass` and `ngStyle`.
+- Host bindings go in the `host` object, never `@HostBinding` or `@HostListener`.
+- Derived state is a `computed()`. Don't write signals from an `effect()` when a `computed()` or `linkedSignal()` would do.
+- Clean up subscriptions and listeners with `DestroyRef`.
+
+The panel's visual rules are in the [UI guidelines](./ui-guidelines.md).
+
+## Reading data from the page (`packages/ng-devtools`)
+
+The overlay runs inside the user's app, so it must be correct, cheap and invisible.
+
+- **Use Angular's debug APIs**, not guesses: `ng.getComponent`, `ng.getDirectives`, `ng.getDirectiveMetadata`, `ng.getListeners`, `ng.getInjector`, `ng.ɵgetInjectorProviders`, `ng.ɵgetInjectorResolutionPath`, `ng.ɵgetDependenciesFromInjectable`, `ng.ɵgetSignalGraph`. Check the shapes in `node_modules/@angular/core/fesm2022` before relying on a field.
+- **Never write to the app's DOM.** Give elements and objects ids through a `WeakMap` (`element-id.ts`, `idFor` in `injector-tree.ts`), so ids stay stable between pushes and selection survives a refresh.
+- **Strip bundler prefixes** from class names (`className()` in `injector-tree.ts`), so `_App` shows as `App`.
+- **Don't match `_nghost-*` or `_ngcontent-*` attributes** with exact selectors; their names carry a suffix. Start from `[ng-version]` roots and the debug APIs.
+- **Keep pushes cheap.** Skip unchanged reports (compare with the last JSON sent), re-send now and then so the server doesn't expire the page, and avoid `querySelectorAll('*')` on a timer; cache and rescan on a `MutationObserver` signal.
+- **Serialize safely** with `serialize()` from `serialize.ts`: it limits depth and size and handles `Map`, `Set`, `Date`, class instances, cycles and Angular's signal sentinels.
+- **Every report carries a `pageId`.** The server keeps one entry per page, expires it after 15 seconds without a push, and forgets it on `pagehide` (`forget-<area>-page`). Two open tabs must never overwrite each other.
+- **Don't change app behavior.** Don't run the app's validators, guards or effects to learn something unless the user asked for it (recording, instrumenting), and say so in the UI.
+
+## Server side and agent tools
+
+- Register RPC functions with `defineRpcFunction` and valibot schemas; give them an `agent` description when an agent should call them.
+- Agent tools (`ctx.agent.registerTool`) answer in markdown, say where the data came from (live page or source scan), and say what to do when there is no data.
+- Source scans (`rpc/source-scan.ts` and friends) are a fallback and an enrichment for live data, not a replacement.
+
+## Tests
+
+- Every behavior change comes with a test in `packages/ng-devtools/src/__tests__` or `packages/ng-devtools/src/rpc/__tests__`.
+- Page-side collectors are tested in jsdom with a fake `ng` object; see `injector-tree.test.ts` and `component-tree.test.ts`.
+- Test names read as sentences: `it('keeps ids stable between collections')`.
+- Run `pnpm test:devtools` and `pnpm test` before you push.
diff --git a/docs/contributing/commit-message-guidelines.md b/docs/contributing/commit-message-guidelines.md
new file mode 100644
index 0000000..8b3f8d2
--- /dev/null
+++ b/docs/contributing/commit-message-guidelines.md
@@ -0,0 +1,104 @@
+# Commit message guidelines
+
+Every commit follows one format, with scopes that match the areas of this repository. A consistent history makes the changelog easy to write and lets reviewers see what a change touches at a glance.
+
+Every commit is checked twice:
+
+- **Locally**, by a `commit-msg` git hook that `pnpm install` turns on (it sets `core.hooksPath` to `.githooks` and `commit.template` to [`.gitmessage`](../../.gitmessage)). It warns and lets the commit through; fix the message with `git commit --amend` before you push.
+- **In CI**, on every pull request: each commit and the pull request title. Pull requests are squash merged, so **the title becomes the commit on `main`**.
+
+Run `pnpm commit:check` to check the commits on your branch before you push. To fix an older commit, reword it with `git rebase -i` and force-push your branch. While a review is in progress, prefer [fixup commits](./using-fixup-commits.md). `fixup!` and `squash!` commits and merge commits are skipped.
+
+## Format
+
+```
+<type>(<scope>): <short summary>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+The header is required. The body is required for every type except `docs`. The footer is optional.
+
+### Type
+
+| Type       | Use it for                                                |
+| ---------- | --------------------------------------------------------- |
+| `feat`     | A new feature                                             |
+| `fix`      | A bug fix                                                 |
+| `perf`     | A change that improves performance                        |
+| `refactor` | A code change that neither fixes a bug nor adds a feature |
+| `test`     | Adding missing tests or correcting existing ones          |
+| `docs`     | Documentation only                                        |
+| `build`    | Build system, packaging or dependencies                   |
+| `ci`       | CI configuration and scripts                              |
+| `revert`   | Reverting an earlier commit                               |
+
+### Scope
+
+Use the area of the devtools the change is about. Leave the scope out when a change spans many areas.
+
+| Scope        | Area                                                                                 |
+| ------------ | ------------------------------------------------------------------------------------ |
+| `hub`        | `@devframes/hub` integration, docks, `hub.ts`, `hub-docks.ts`                        |
+| `ui`         | The panel shell, theme, shared UI (`app/src/app.ts`, `app/src/styles`, `app/src/ui`) |
+| `popup`      | The in-page launcher and popup (`popup.ts`)                                          |
+| `overlay`    | The page-side script and its collectors (`overlay.ts`)                               |
+| `components` | Components inspector                                                                 |
+| `signals`    | Signals inspector                                                                    |
+| `injectors`  | Injectors (DI) inspector                                                             |
+| `router`     | Router inspector                                                                     |
+| `forms`      | Forms inspector                                                                      |
+| `store`      | NgRx store inspector                                                                 |
+| `pipes`      | Pipes inspector                                                                      |
+| `http`       | SSR & HTTP inspector                                                                 |
+| `analog`     | Analog support                                                                       |
+| `mcp`        | Agent tools and MCP resources                                                        |
+| `extension`  | The Chrome extension                                                                 |
+| `vite`       | The Vite plugin                                                                      |
+| `demo`       | The Angular Travel demo app (`src/`) and `examples/`                                 |
+| `deps`       | Dependency updates (with `build`)                                                    |
+
+### Summary
+
+- Use the imperative, present tense: "add", not "added" or "adds".
+- Don't capitalize the first letter, unless it starts a name (Analog, NgRx, SSR).
+- No period at the end.
+- Keep the whole header under 100 characters.
+
+### Body
+
+- Use the imperative, present tense.
+- Explain why the change is needed. Compare the old behavior with the new one when that helps.
+- At least 20 characters.
+
+### Footer
+
+- Reference issues and pull requests: `Fixes #123`, `Closes #45`.
+- Breaking changes start with `BREAKING CHANGE: ` followed by a summary, a blank line, and a description with migration steps.
+- Deprecations start with `DEPRECATED: ` followed by the recommended replacement.
+
+### Revert commits
+
+Start the header with `revert: ` followed by the header of the reverted commit. The body must say `This reverts commit <SHA>` and why.
+
+## Examples
+
+```
+feat(injectors): show which injector supplies each dependency
+
+The Injectors page listed every DOM element and the same built-in
+tokens on each row. Collect only elements that carry a component or
+directive, and report what each one injected and where Angular found it.
+
+Fixes #40
+```
+
+```
+fix(router): pass match options to isActive when paths is set
+```
+
+```
+docs: document the panel design tokens
+```
diff --git a/docs/contributing/ui-guidelines.md b/docs/contributing/ui-guidelines.md
new file mode 100644
index 0000000..cb5a372
--- /dev/null
+++ b/docs/contributing/ui-guidelines.md
@@ -0,0 +1,69 @@
+# UI guidelines
+
+The devtools panel (`app/`) is a dark, dense tool that people keep open next to their app. Every page should look like it belongs to the same product, work with the keyboard, and pass axe with WCAG AA contrast.
+
+## Theme
+
+The palette lives in `app/src/styles/_palette.scss` and becomes CSS variables in `_theme.scss`. Change the brand in one place, `app/src/styles/main.scss`:
+
+```scss
+@use 'theme' with (
+  $accent: amber
+);
+```
+
+Accents available: `amber` (default), `ember`, `gold`. Add one by extending `$accents` in `_palette.scss`.
+
+Always use the variables, never hex values:
+
+| Variable                                          | Use                                                                     |
+| ------------------------------------------------- | ----------------------------------------------------------------------- |
+| `--bg`                                            | Page background, input fields                                           |
+| `--surface`, `--surface-2`, `--surface-3`         | Cards and panels, hover, pressed or nested                              |
+| `--border`, `--border-strong`                     | Dividers, control borders                                               |
+| `--text-strong`, `--text`, `--text-2`, `--text-3` | Headings, body, secondary, hints                                        |
+| `--accent`, `--accent-hover`, `--accent-ink`      | Primary actions and selection; `--accent-ink` is text on an accent fill |
+| `--accent-soft`, `--accent-line`                  | Selected backgrounds, focus glow, accent borders                        |
+| `--ok`, `--warn`, `--danger`                      | Status                                                                  |
+| `--radius`, `--radius-sm`                         | Cards, controls                                                         |
+| `--control-h`                                     | 34px, the height of every input, select and button                      |
+| `--ease`, `--font-mono`                           | Motion curve, code and tokens                                           |
+
+Brand colors belong only to the brand they represent: NgRx keeps its purple on the NgRx view, the Angular view uses the Angular gradient for its logo and title, and Analog, NativeScript and Capacitor use their own colors on their pages. Everything else is amber.
+
+## Shared building blocks
+
+- **SCSS mixins** in `app/src/styles/_mixins.scss`, used with `@use 'mixins' as m;` in component styles: `m.focus-ring($offset)`, `m.field-focus`, `m.panel($level)`, `m.label`, `m.soft($color)`, `m.truncate`, `m.enter($duration)`.
+- **Dropdown**: `app/src/ui/select.ts` (`<app-select [options] [(value)] ariaLabel|labelledBy>`). Never use a native `<select>`; the system popup ignores the theme.
+- **Tab icons**: `app/src/pages/tab-icon.ts`, Lucide-style 24px strokes. Add a case when you add a tab.
+- **Global baselines** in `_base.scss`: tabular numbers, textarea sizing, focus fallback, reduced motion.
+
+## Anatomy of an inspector page
+
+1. **Intro**: one or two sentences saying what the page shows and where the data comes from (live page or source scan).
+2. **Toolbar**: sticky, with a search field (icon, `Escape` clears), filters as chips or `app-select`, a count ("12 of 40"), and actions. Controls are `var(--control-h)` tall.
+3. **Content**: a list or tree on the left, a detail panel on the right on wide screens (sticky), stacked below 880px.
+4. **States**: every page has loading, error (with Retry), empty (explains how to get data) and no-match (with Clear filters) states. Never leave a blank area.
+
+Headings start at `h2` inside a page (the shell owns the `h1`) and never skip a level. Use `m.label` for small uppercase section labels.
+
+## Interaction
+
+- Rows are buttons or ARIA tree items; arrow keys move, `Home` and `End` jump, `Enter` selects, left and right collapse and expand.
+- Hovering or focusing a row that maps to an element in the app highlights it there through the `request-page-highlight` RPC.
+- Selection is keyed by a stable id from the page, so it survives refreshes.
+- Motion is short (150 to 350ms) and respects `prefers-reduced-motion`.
+
+## Accessibility checklist
+
+- Text contrast at least 4.5:1 (3:1 for large text and UI outlines). Check gradients at their darkest stop.
+- Every control has a label (`<label>`, `aria-label` or `aria-labelledby`).
+- Visible focus on everything; use `m.focus-ring(-2px)` inside scroll containers so the ring isn't clipped.
+- Landmarks have unique names; don't nest interactive elements.
+- Run the axe check described in the [devtools-verify skill](../../.claude/skills/devtools-verify/SKILL.md) before you open a pull request.
+
+## Writing in the UI
+
+- Short, plain sentences. Say what to do next in empty and error states.
+- No em dashes; use a period, comma or parentheses.
+- Don't compare the project with other tools.
diff --git a/docs/contributing/using-fixup-commits.md b/docs/contributing/using-fixup-commits.md
new file mode 100644
index 0000000..52fcc90
--- /dev/null
+++ b/docs/contributing/using-fixup-commits.md
@@ -0,0 +1,35 @@
+# Using fixup commits
+
+When you address review feedback, add fixup commits instead of rewriting the commits a reviewer has already read. The reviewer then sees only what changed since their last pass, and the history is cleaned up just before merge.
+
+## Making a fixup commit
+
+Point the fixup at the commit it belongs to:
+
+```sh
+git add <files>
+git commit --fixup <sha>   # or --fixup HEAD for the latest commit
+git push
+```
+
+The commit is named `fixup! <original header>`. The commit message checks skip these commits.
+
+## Before merge
+
+Pull requests are squash merged, so fixup commits disappear on `main`. If a maintainer asks you to clean up the branch first, fold the fixups into their targets and force-push:
+
+```sh
+git rebase -i --autosquash main
+git push --force-with-lease
+```
+
+## Rewording a commit message
+
+If the check in CI flags a commit message, reword it:
+
+```sh
+git rebase -i main          # mark the commit as "reword"
+git push --force-with-lease
+```
+
+Or, for the latest commit only, `git commit --amend` and push with `--force-with-lease`.
diff --git a/package.json b/package.json
index f5497fd..52bab84 100644
--- a/package.json
+++ b/package.json
@@ -7,6 +7,9 @@
   },
   "scripts": {
     "ng": "ng",
+    "prepare": "git config core.hooksPath .githooks && git config commit.template .gitmessage || true",
+    "commit:check": "node scripts/commit-message.mjs --branch",
+    "skills:check": "node scripts/validate-skills.mjs",
     "start": "pnpm devtools:build-pkg && nx serve",
     "build": "nx build",
     "watch": "nx build --watch --configuration development",
diff --git a/scripts/commit-message.mjs b/scripts/commit-message.mjs
new file mode 100755
index 0000000..504814d
--- /dev/null
+++ b/scripts/commit-message.mjs
@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+
+export const TYPES = ['feat', 'fix', 'perf', 'refactor', 'test', 'docs', 'build', 'ci', 'revert'];
+
+export const SCOPES = [
+  'hub',
+  'ui',
+  'popup',
+  'overlay',
+  'components',
+  'signals',
+  'injectors',
+  'router',
+  'forms',
+  'store',
+  'pipes',
+  'http',
+  'analog',
+  'mcp',
+  'extension',
+  'vite',
+  'demo',
+  'deps',
+];
+
+const MAX_HEADER = 100;
+const MIN_BODY = 20;
+const HEADER = /^(\w+)(?:\(([^)]+)\))?(!)?: (.+)$/;
+const GUIDE = 'docs/contributing/commit-message-guidelines.md';
+
+export function validate(message, { requireBody = true } = {}) {
+  const lines = message
+    .split('\n')
+    .filter((line) => !line.startsWith('#'))
+    .join('\n')
+    .trim()
+    .split('\n');
+  const header = lines[0] ?? '';
+  const errors = [];
+
+  if (/^(Merge |fixup! |squash! |amend! )/.test(header)) return errors;
+
+  if (!header) return ['The commit message is empty.'];
+  if (header.length > MAX_HEADER) {
+    errors.push(`The header is ${header.length} characters; keep it under ${MAX_HEADER}.`);
+  }
+
+  const match = HEADER.exec(header);
+  if (!match) {
+    errors.push(`The header must look like "type(scope): summary", got "${header}".`);
+    return errors;
+  }
+  const [, type, scope, , summary] = match;
+  if (!TYPES.includes(type)) {
+    errors.push(`"${type}" is not a type. Use one of: ${TYPES.join(', ')}.`);
+  }
+  if (scope !== undefined && !SCOPES.includes(scope)) {
+    errors.push(`"${scope}" is not a scope. Use one of: ${SCOPES.join(', ')}, or leave it out.`);
+  }
+  if (/^\s/.test(summary)) errors.push('Put exactly one space after the colon.');
+  if (/\.$/.test(summary)) errors.push("Don't end the summary with a period.");
+
+  const body = lines.slice(1).join('\n').trim();
+  if (lines.length > 1 && lines[1].trim() !== '') {
+    errors.push('Leave a blank line between the header and the body.');
+  }
+  if (type === 'revert' && !/This reverts commit [0-9a-f]{7,}/.test(body)) {
+    errors.push('A revert must say "This reverts commit <sha>" in the body, and why.');
+  }
+  if (requireBody && type !== 'docs' && body.length < MIN_BODY) {
+    errors.push(
+      `Add a body of at least ${MIN_BODY} characters that explains why the change is needed.`,
+    );
+  }
+  return errors;
+}
+
+function report(label, errors) {
+  if (!errors.length) return true;
+  console.error(`\n${label}`);
+  for (const error of errors) console.error(`  - ${error}`);
+  return false;
+}
+
+function main(args) {
+  const [mode, value] = args;
+
+  if (mode === '--file') {
+    const ok = report('Commit message check failed:', validate(readFileSync(value, 'utf8')));
+    if (!ok) {
+      console.error(`\nSee ${GUIDE}. CI will reject it; fix it with "git commit --amend".\n`);
+    }
+    return ok;
+  }
+
+  if (mode === '--title') {
+    const ok = report(
+      'Pull request title check failed:',
+      validate(value ?? '', { requireBody: false }),
+    );
+    if (!ok) console.error(`\nThe title becomes the squash commit on main. See ${GUIDE}.\n`);
+    return ok;
+  }
+
+  if (mode === '--branch') {
+    const base = ['upstream/main', 'origin/main', 'main'].find((ref) => {
+      try {
+        execFileSync('git', ['rev-parse', '--verify', '--quiet', ref], { stdio: 'ignore' });
+        return true;
+      } catch {
+        return false;
+      }
+    });
+    if (!base) {
+      console.error('No main branch found to compare with.');
+      return false;
+    }
+    return main(['--range', `${base}..HEAD`]);
+  }
+
+  if (mode === '--range') {
+    const shas = execFileSync('git', ['rev-list', '--no-merges', value], { encoding: 'utf8' })
+      .split('\n')
+      .filter(Boolean);
+    let ok = true;
+    for (const sha of shas) {
+      const message = execFileSync('git', ['log', '-1', '--format=%B', sha], { encoding: 'utf8' });
+      ok = report(`${sha.slice(0, 8)}: ${message.split('\n')[0]}`, validate(message)) && ok;
+    }
+    if (!ok) console.error(`\nSee ${GUIDE}. Reword with "git rebase -i" and force-push.\n`);
+    else console.log(`${shas.length} commit message(s) OK.`);
+    return ok;
+  }
+
+  console.error(
+    'Usage: commit-message.mjs --file <path> | --title <title> | --range <a..b> | --branch',
+  );
+  return false;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(main(process.argv.slice(2)) ? 0 : 1);
+}
diff --git a/scripts/validate-skills.mjs b/scripts/validate-skills.mjs
new file mode 100644
index 0000000..5dcb5ac
--- /dev/null
+++ b/scripts/validate-skills.mjs
@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, normalize } from 'node:path';
+
+const root = join(dirname(new URL(import.meta.url).pathname), '..');
+const errors = [];
+
+function frontmatter(file) {
+  const text = readFileSync(file, 'utf8');
+  const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(text);
+  if (!match) {
+    errors.push(`${file}: missing the --- frontmatter block`);
+    return null;
+  }
+  const fields = {};
+  for (const line of match[1].split('\n')) {
+    const field = /^(\w[\w-]*):\s*(.*)$/.exec(line);
+    if (field) fields[field[1]] = field[2].trim();
+  }
+  return { fields, body: match[2] };
+}
+
+function checkLinks(file, body) {
+  for (const [, link] of body.matchAll(/\]\(([^)\s]+)\)/g)) {
+    if (/^(https?:|#|mailto:)/.test(link)) continue;
+    const target = normalize(join(dirname(file), link.split('#')[0]));
+    if (!existsSync(target)) errors.push(`${file}: broken link ${link}`);
+  }
+  for (const [, path] of body.matchAll(
+    /`((?:app|packages|docs|scripts|src|\.claude|\.github)\/[^`\s*<>]+)`/g,
+  )) {
+    if (!existsSync(join(root, path))) errors.push(`${file}: ${path} does not exist`);
+  }
+}
+
+function check(file, name, kind) {
+  const parsed = frontmatter(file);
+  if (!parsed) return;
+  const { fields, body } = parsed;
+  if (fields.name !== name) {
+    errors.push(
+      `${file}: name must be "${name}" (the ${kind === 'skill' ? 'folder' : 'file'} name)`,
+    );
+  }
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
+    errors.push(`${file}: use lowercase words joined by hyphens for the name`);
+  }
+  if (!fields.description || fields.description.length < 40) {
+    errors.push(`${file}: add a description of at least 40 characters that says when to use it`);
+  }
+  if (body.trim().length < 100) errors.push(`${file}: the instructions are too short`);
+  checkLinks(file, body);
+}
+
+const skills = join(root, '.claude/skills');
+const agents = join(root, '.claude/agents');
+let count = 0;
+
+if (existsSync(skills)) {
+  for (const name of readdirSync(skills)) {
+    const dir = join(skills, name);
+    if (!statSync(dir).isDirectory()) continue;
+    const file = join(dir, 'SKILL.md');
+    if (!existsSync(file)) {
+      errors.push(`${dir}: missing SKILL.md`);
+      continue;
+    }
+    check(file, name, 'skill');
+    count++;
+  }
+}
+
+if (existsSync(agents)) {
+  for (const entry of readdirSync(agents)) {
+    if (!entry.endsWith('.md')) continue;
+    check(join(agents, entry), entry.replace(/\.md$/, ''), 'agent');
+    count++;
+  }
+}
+
+if (errors.length) {
+  console.error(errors.map((error) => `- ${error}`).join('\n'));
+  process.exit(1);
+}
+console.log(`${count} skills and roles OK.`);

From 89305473dcec54b04ad64fa2f300321c9663fb1e Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 10:23:34 +0300
Subject: [PATCH 02/16] ci: match the commit rules to the repository history

The checker rejected most of main: there was no chore or style type
and no docs or release scope, so every release commit and every docs
site commit failed. Add those types and scopes, require a body only for
feat, fix, perf and refactor, and add a --warn flag that reports
problems without failing.

The script also exited 0 without checking anything when its path had a
space or went through a symlink, because it compared import.meta.url
with a hand-built file URL. Compare real paths instead.
---
 .claude/skills/devtools-commit/SKILL.md       |  8 +--
 .gitmessage                                   |  7 +--
 .../contributing/commit-message-guidelines.md | 17 +++++--
 scripts/commit-message.mjs                    | 49 ++++++++++++++++---
 4 files changed, 64 insertions(+), 17 deletions(-)

diff --git a/.claude/skills/devtools-commit/SKILL.md b/.claude/skills/devtools-commit/SKILL.md
index 8a7ec5a..1573e4e 100644
--- a/.claude/skills/devtools-commit/SKILL.md
+++ b/.claude/skills/devtools-commit/SKILL.md
@@ -10,19 +10,19 @@ The rules are in `docs/contributing/commit-message-guidelines.md`. Summary:
 ```
 <type>(<scope>): <short summary>
 
-<body: why the change is needed, old vs new behavior, imperative tense, 20+ characters>
+<body: why the change is needed, old vs new behavior, imperative tense, 20+ characters; required for feat, fix, perf, refactor>
 
 <footer: Fixes #123 | BREAKING CHANGE: ... | DEPRECATED: ...>
 ```
 
-- Types: `feat`, `fix`, `perf`, `refactor`, `test`, `docs`, `build`, `ci`, `revert`.
-- Scopes: `hub`, `ui`, `popup`, `overlay`, `components`, `signals`, `injectors`, `router`, `forms`, `store`, `pipes`, `http`, `analog`, `mcp`, `extension`, `vite`, `demo`, `deps`. Leave the scope out for cross-cutting changes.
+- Types: `feat`, `fix`, `perf`, `refactor`, `test`, `docs`, `style`, `build`, `ci`, `chore`, `revert`.
+- Scopes: `hub`, `ui`, `popup`, `overlay`, `components`, `signals`, `injectors`, `router`, `forms`, `store`, `pipes`, `http`, `analog`, `mcp`, `extension`, `vite`, `demo`, `docs` (the docs site in `apps/docs`), `release`, `deps`. Leave the scope out for cross-cutting changes.
 - Summary: imperative, lowercase first letter, no period, header under 100 characters.
 
 ## Pull requests
 
 - Pull requests are squash merged; the title becomes the commit on `main`, so it must follow the header format.
-- A `commit-msg` hook (`scripts/commit-message.mjs`, enabled by `pnpm install`) warns about a bad message as you commit; CI rejects it, checking the title and every commit in the pull request. Run `pnpm commit:check` before pushing, and fix flagged messages with `git commit --amend` or a reword rebase.
+- A `commit-msg` hook (`scripts/commit-message.mjs`, enabled by `pnpm install`) warns about a bad message as you commit; CI checks the title and every commit in the pull request and, for now, reports problems as warnings. Run `pnpm commit:check` before pushing, and fix flagged messages with `git commit --amend` or a reword rebase.
 - Address review feedback with fixup commits (`docs/contributing/using-fixup-commits.md`).
 - One feature per pull request, with its tests (including agent tool tests when tools change).
 - Rebuild and commit `extension/ui` when `app/` changed.
diff --git a/.gitmessage b/.gitmessage
index 8bf0c3e..80d7cb9 100644
--- a/.gitmessage
+++ b/.gitmessage
@@ -4,11 +4,12 @@
 #   │       │             └─> Imperative, present tense. No period at the end.
 #   │       │
 #   │       └─> hub|ui|popup|overlay|components|signals|injectors|router|forms|store|
-#   │           pipes|http|analog|mcp|extension|vite|demo|deps (or leave it out)
+#   │           pipes|http|analog|mcp|extension|vite|demo|docs|release|deps
+#   │           (or leave it out)
 #   │
-#   └─> feat|fix|perf|refactor|test|docs|build|ci|revert
+#   └─> feat|fix|perf|refactor|test|docs|style|build|ci|chore|revert
 #
-# Body (required except for docs, 20+ characters): why the change is needed,
+# Body (required for feat, fix, perf and refactor, 20+ characters): why the change is needed,
 # and how the old behavior compares with the new one.
 #
 # Footer (optional): Fixes #123, BREAKING CHANGE: ..., DEPRECATED: ...
diff --git a/docs/contributing/commit-message-guidelines.md b/docs/contributing/commit-message-guidelines.md
index 8b3f8d2..d4fbaef 100644
--- a/docs/contributing/commit-message-guidelines.md
+++ b/docs/contributing/commit-message-guidelines.md
@@ -5,7 +5,7 @@ Every commit follows one format, with scopes that match the areas of this reposi
 Every commit is checked twice:
 
 - **Locally**, by a `commit-msg` git hook that `pnpm install` turns on (it sets `core.hooksPath` to `.githooks` and `commit.template` to [`.gitmessage`](../../.gitmessage)). It warns and lets the commit through; fix the message with `git commit --amend` before you push.
-- **In CI**, on every pull request: each commit and the pull request title. Pull requests are squash merged, so **the title becomes the commit on `main`**.
+- **In CI**, on every pull request: each commit and the pull request title. Pull requests are squash merged, so **the title becomes the commit on `main`**. For now the CI check only warns: problems show up as annotations on the pull request, and the check stays green.
 
 Run `pnpm commit:check` to check the commits on your branch before you push. To fix an older commit, reword it with `git rebase -i` and force-push your branch. While a review is in progress, prefer [fixup commits](./using-fixup-commits.md). `fixup!` and `squash!` commits and merge commits are skipped.
 
@@ -19,7 +19,7 @@ Run `pnpm commit:check` to check the commits on your branch before you push. To
 <footer>
 ```
 
-The header is required. The body is required for every type except `docs`. The footer is optional.
+The header is required. The body is required for `feat`, `fix`, `perf` and `refactor`, and optional for the other types. The footer is optional.
 
 ### Type
 
@@ -31,8 +31,10 @@ The header is required. The body is required for every type except `docs`. The f
 | `refactor` | A code change that neither fixes a bug nor adds a feature |
 | `test`     | Adding missing tests or correcting existing ones          |
 | `docs`     | Documentation only                                        |
+| `style`    | Formatting only, no change in behavior                    |
 | `build`    | Build system, packaging or dependencies                   |
 | `ci`       | CI configuration and scripts                              |
+| `chore`    | Releases and housekeeping that fit no other type          |
 | `revert`   | Reverting an earlier commit                               |
 
 ### Scope
@@ -58,6 +60,8 @@ Use the area of the devtools the change is about. Leave the scope out when a cha
 | `extension`  | The Chrome extension                                                                 |
 | `vite`       | The Vite plugin                                                                      |
 | `demo`       | The Angular Travel demo app (`src/`) and `examples/`                                 |
+| `docs`       | The documentation site (`apps/docs`)                                                 |
+| `release`    | Version bumps and publishing (with `chore`)                                          |
 | `deps`       | Dependency updates (with `build`)                                                    |
 
 ### Summary
@@ -71,7 +75,7 @@ Use the area of the devtools the change is about. Leave the scope out when a cha
 
 - Use the imperative, present tense.
 - Explain why the change is needed. Compare the old behavior with the new one when that helps.
-- At least 20 characters.
+- At least 20 characters when the body is required.
 
 ### Footer
 
@@ -97,6 +101,13 @@ Fixes #40
 
 ```
 fix(router): pass match options to isActive when paths is set
+
+The router inspector called isActive with the default options, so a
+route with query parameters never showed as active.
+```
+
+```
+chore(release): ng-devtools 0.0.5
 ```
 
 ```
diff --git a/scripts/commit-message.mjs b/scripts/commit-message.mjs
index 504814d..e8ca2d0 100755
--- a/scripts/commit-message.mjs
+++ b/scripts/commit-message.mjs
@@ -1,8 +1,23 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const TYPES = [
+  'feat',
+  'fix',
+  'perf',
+  'refactor',
+  'test',
+  'docs',
+  'style',
+  'build',
+  'ci',
+  'chore',
+  'revert',
+];
 
-export const TYPES = ['feat', 'fix', 'perf', 'refactor', 'test', 'docs', 'build', 'ci', 'revert'];
+export const BODY_REQUIRED = ['feat', 'fix', 'perf', 'refactor'];
 
 export const SCOPES = [
   'hub',
@@ -22,6 +37,8 @@ export const SCOPES = [
   'extension',
   'vite',
   'demo',
+  'docs',
+  'release',
   'deps',
 ];
 
@@ -69,7 +86,7 @@ export function validate(message, { requireBody = true } = {}) {
   if (type === 'revert' && !/This reverts commit [0-9a-f]{7,}/.test(body)) {
     errors.push('A revert must say "This reverts commit <sha>" in the body, and why.');
   }
-  if (requireBody && type !== 'docs' && body.length < MIN_BODY) {
+  if (requireBody && BODY_REQUIRED.includes(type) && body.length < MIN_BODY) {
     errors.push(
       `Add a body of at least ${MIN_BODY} characters that explains why the change is needed.`,
     );
@@ -77,8 +94,14 @@ export function validate(message, { requireBody = true } = {}) {
   return errors;
 }
 
+let warnOnly = false;
+
 function report(label, errors) {
   if (!errors.length) return true;
+  if (warnOnly && process.env.GITHUB_ACTIONS) {
+    const text = `${label} ${errors.join(' ')}`.replace(/%/g, '%25').replace(/\r?\n/g, '%0A');
+    console.log(`::warning title=Commit message::${text}`);
+  }
   console.error(`\n${label}`);
   for (const error of errors) console.error(`  - ${error}`);
   return false;
@@ -90,7 +113,7 @@ function main(args) {
   if (mode === '--file') {
     const ok = report('Commit message check failed:', validate(readFileSync(value, 'utf8')));
     if (!ok) {
-      console.error(`\nSee ${GUIDE}. CI will reject it; fix it with "git commit --amend".\n`);
+      console.error(`\nSee ${GUIDE}. CI flags it too; fix it with "git commit --amend".\n`);
     }
     return ok;
   }
@@ -135,11 +158,23 @@ function main(args) {
   }
 
   console.error(
-    'Usage: commit-message.mjs --file <path> | --title <title> | --range <a..b> | --branch',
+    'Usage: commit-message.mjs --file <path> | --title <title> | --range <a..b> | --branch [--warn]',
   );
   return false;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
-  process.exit(main(process.argv.slice(2)) ? 0 : 1);
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isEntryPoint()) {
+  const args = process.argv.slice(2);
+  warnOnly = args.includes('--warn');
+  const ok = main(args.filter((arg) => arg !== '--warn'));
+  if (!ok && warnOnly) console.error('Warn-only mode: not failing the check.');
+  process.exit(ok || warnOnly ? 0 : 1);
 }

From c68906fe7f8e2eb4386a1a7f7dc4e6e892177954 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 10:23:55 +0300
Subject: [PATCH 03/16] ci: run the commit message check in warn-only mode

Until the maintainers agree on the types and scopes, a failing check
would block their own release pull requests. Report problems as
warning annotations instead, and match ci.yml's hardening: cancel
superseded runs and don't leave the token in the checkout.
---
 .github/workflows/commit-message.yml | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/commit-message.yml b/.github/workflows/commit-message.yml
index c6b2ce4..9d0be3b 100644
--- a/.github/workflows/commit-message.yml
+++ b/.github/workflows/commit-message.yml
@@ -7,6 +7,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   check:
     runs-on: ubuntu-latest
@@ -15,6 +19,7 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - uses: actions/setup-node@v7
         with:
@@ -23,10 +28,10 @@ jobs:
       - name: Pull request title
         env:
           TITLE: ${{ github.event.pull_request.title }}
-        run: node scripts/commit-message.mjs --title "$TITLE"
+        run: node scripts/commit-message.mjs --title "$TITLE" --warn
 
       - name: Commit messages
         env:
           BASE: ${{ github.event.pull_request.base.sha }}
           HEAD: ${{ github.event.pull_request.head.sha }}
-        run: node scripts/commit-message.mjs --range "$BASE..$HEAD"
+        run: node scripts/commit-message.mjs --range "$BASE..$HEAD" --warn

From 0dd1c929e42fd822af83e8e03af5f3d076cfd1c6 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 10:24:24 +0300
Subject: [PATCH 04/16] ci: make the skills check work from any checkout path

The validator built the repository root from the URL pathname, which
keeps %20 for a space. With a space in the path it found no skills and
printed "0 skills and roles OK". Use fileURLToPath.

It also only matched LF frontmatter, so a Windows checkout with
autocrlf failed every skill. Accept CRLF, and check text files out with
LF everywhere through .gitattributes.
---
 .gitattributes              | 7 +++++--
 scripts/validate-skills.mjs | 7 ++++---
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/.gitattributes b/.gitattributes
index 74f1113..dbf6ce4 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,4 +1,7 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary
+*.ico binary
+*.zip binary
 extension/ui/** linguist-generated=true
 pnpm-lock.yaml linguist-generated=true
-*.mjs text eol=lf
-.githooks/* text eol=lf
diff --git a/scripts/validate-skills.mjs b/scripts/validate-skills.mjs
index 5dcb5ac..84584f7 100644
--- a/scripts/validate-skills.mjs
+++ b/scripts/validate-skills.mjs
@@ -1,19 +1,20 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, normalize } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-const root = join(dirname(new URL(import.meta.url).pathname), '..');
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
 const errors = [];
 
 function frontmatter(file) {
   const text = readFileSync(file, 'utf8');
-  const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(text);
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(text);
   if (!match) {
     errors.push(`${file}: missing the --- frontmatter block`);
     return null;
   }
   const fields = {};
-  for (const line of match[1].split('\n')) {
+  for (const line of match[1].split(/\r?\n/)) {
     const field = /^(\w[\w-]*):\s*(.*)$/.exec(line);
     if (field) fields[field[1]] = field[2].trim();
   }

From 322577e91ebfba750bd5b876c878476593a7b716 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 10:25:14 +0300
Subject: [PATCH 05/16] ci: keep the git hooks from staging work you left out

The pre-commit hook ran git add on every staged file after formatting
it, which also staged hunks left out on purpose with git add -p, and
xargs split file names with spaces. Skip files that have unstaged
changes, with a warning, and pass names NUL separated.

pnpm install also overwrote core.hooksPath and commit.template on every
run, which switched off any hooks a contributor had set up. Only set
them when they are unset.
---
 .githooks/pre-commit | 28 +++++++++++++++++++++++-----
 package.json         |  2 +-
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index 4c25ea9..a4cffaf 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -1,8 +1,26 @@
 #!/bin/sh
-root="$(git rev-parse --show-toplevel)"
-files="$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.(ts|mjs|js|json|scss|css|html|md|yml|yaml)$' | grep -v '^extension/ui/')"
-[ -z "$files" ] && exit 0
+root="$(git rev-parse --show-toplevel)" || exit 0
 cd "$root" || exit 0
-echo "$files" | xargs pnpm --silent exec prettier --write --ignore-unknown >/dev/null 2>&1 || echo "WARNING: failed to format staged files."
-echo "$files" | xargs git add -- 2>/dev/null
+
+list="$(mktemp)" || exit 0
+trap 'rm -f "$list"' EXIT
+
+unstaged="$(git -c core.quotePath=false diff --name-only)"
+
+git -c core.quotePath=false diff --cached --name-only --diff-filter=ACMR |
+  grep -E '\.(ts|mjs|js|json|scss|css|html|md|yml|yaml)$' |
+  grep -v '^extension/ui/' |
+  while IFS= read -r file; do
+    if printf '%s\n' "$unstaged" | grep -qxF -- "$file"; then
+      echo "pre-commit: not formatting $file because it has unstaged changes. Run pnpm format:check before you push." >&2
+    else
+      printf '%s\n' "$file"
+    fi
+  done >"$list"
+
+[ -s "$list" ] || exit 0
+
+tr '\n' '\0' <"$list" | xargs -0 pnpm --silent exec prettier --write --ignore-unknown >/dev/null 2>&1 ||
+  echo "WARNING: failed to format staged files." >&2
+tr '\n' '\0' <"$list" | xargs -0 git add --
 exit 0
diff --git a/package.json b/package.json
index 52bab84..66f9137 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,7 @@
   },
   "scripts": {
     "ng": "ng",
-    "prepare": "git config core.hooksPath .githooks && git config commit.template .gitmessage || true",
+    "prepare": "(git config core.hooksPath >/dev/null || git config core.hooksPath .githooks) && (git config commit.template >/dev/null || git config commit.template .gitmessage) || true",
     "commit:check": "node scripts/commit-message.mjs --branch",
     "skills:check": "node scripts/validate-skills.mjs",
     "start": "pnpm devtools:build-pkg && nx serve",

From 9a388937e7858d2fdeb789aec1f7be56842d4fd5 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 10:27:56 +0300
Subject: [PATCH 06/16] docs: point the contributor guides and skills at the
 docs site

The docs site in apps/docs now owns the setup, project structure,
commands, CI steps and the tool list, and the devtools-docs skill owns
the writing rules. Link to those instead of repeating them: cut
CONTRIBUTING to the rules, hooks, pull request process and agent
skills, drop the README contributing section, and list devtools-docs
with the other skills.

devtools-inspector now updates the tool list on the docs site,
devtools-verify runs the docs build checks and nx affected, and
devtools-reviewer checks docs changes against devtools-docs.
---
 .claude/agents/devtools-reviewer.md        |  1 +
 .claude/skills/devtools-inspector/SKILL.md |  2 +-
 .claude/skills/devtools-verify/SKILL.md    |  4 ++
 AGENTS.md                                  | 19 ++---
 CLAUDE.md                                  |  1 +
 CONTRIBUTING.md                            | 80 +++++-----------------
 README.md                                  | 21 ------
 7 files changed, 36 insertions(+), 92 deletions(-)

diff --git a/.claude/agents/devtools-reviewer.md b/.claude/agents/devtools-reviewer.md
index 3f5bec5..cbd0cec 100644
--- a/.claude/agents/devtools-reviewer.md
+++ b/.claude/agents/devtools-reviewer.md
@@ -13,5 +13,6 @@ Check the diff against:
 - `docs/contributing/commit-message-guidelines.md` for commit messages and the pull request title.
 - Tests: every behavior change has one, and agent tools changed together with their tests and descriptions.
 - Generated output: `extension/ui` rebuilt and committed when `app/` changed.
+- Docs: when the diff touches the docs site (apps/docs) or `README.md`, check it against the `devtools-docs` skill.
 
 Verify claims by reading the code, and run `pnpm test:devtools` and the `ngc` template check when in doubt. Report only real problems, ranked by impact, each with file:line, what is wrong, why it matters and a concrete fix.
diff --git a/.claude/skills/devtools-inspector/SKILL.md b/.claude/skills/devtools-inspector/SKILL.md
index 8016d8b..2dab1e0 100644
--- a/.claude/skills/devtools-inspector/SKILL.md
+++ b/.claude/skills/devtools-inspector/SKILL.md
@@ -44,7 +44,7 @@ Read `docs/contributing/coding-standards.md` ("Reading data from the page") befo
 ## Agent tools
 
 - Describe what the tool returns, where the data comes from and what an empty answer means. Answer in markdown.
-- Update descriptions in `devframe.ts` when data shapes change, and the README tool list.
+- Update descriptions in `devframe.ts` when data shapes change, and the tool list on the docs site (apps/docs/src/content/agents/tools.md). Use the `devtools-docs` skill for that edit.
 
 ## Tests
 
diff --git a/.claude/skills/devtools-verify/SKILL.md b/.claude/skills/devtools-verify/SKILL.md
index 21fda29..f836a2a 100644
--- a/.claude/skills/devtools-verify/SKILL.md
+++ b/.claude/skills/devtools-verify/SKILL.md
@@ -22,6 +22,10 @@ pnpm devtools:build-pkg
 git status --porcelain -- extension/ui   # must be committed when app/ changed
 ```
 
+CI runs `pnpm exec nx affected -t test build` instead of the plain `pnpm test` and `pnpm build`; run it too when your change touches more than one project.
+
+When the change touches the docs site (apps/docs) or `README.md`, also run the build checks in the `devtools-docs` skill.
+
 `pnpm typecheck` does not type-check panel templates. Also run:
 
 ```sh
diff --git a/AGENTS.md b/AGENTS.md
index 38ac4c0..15f6ab8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -58,15 +58,6 @@ You are an expert in TypeScript, Angular, and scalable web application developme
 - Prefer the `@Service` decorator over `@Injectable({providedIn: 'root'})` for new singleton services (Angular v22+)
 - Use the `inject()` function instead of constructor injection
 
-## Serving Locally
-
-- **Demo app (SSR):** `pnpm build --configuration development && node dist/angular-devtools/server/server.mjs` → http://localhost:4000
-- **Devtools SPA (hot reload):** `pnpm devtools:dev` → http://localhost:5173 (requires the SSR server running for RPC data)
-- **Demo app (SPA, no SSR):** `pnpm start` → http://localhost:4200 (runs `ng serve` with SSR and hot reload; devtools popup + RPC work without a separate server)
-- The devtools popup appears on the demo app page; click it to open the inspector panel
-- Changes to `app/src/` (devtools SPA) are visible live via `pnpm devtools:dev`; the SSR server serves the SPA built into `packages/ng-devtools/dist/public` (or the npm-published copy when it has not been built), so run `pnpm devtools:build-pkg` to refresh it
-- To publish: update the version in `packages/ng-devtools/package.json`, then run `pnpm devtools:publish` (the package build bundles the SPA)
-
 ## Project guidelines, skills and roles
 
 Follow the repository guides in `docs/contributing/`:
@@ -79,7 +70,17 @@ Use the matching skill for the task:
 
 - `.claude/skills/devtools-ui` for panel UI work.
 - `.claude/skills/devtools-inspector` for data collection, the server side and agent tools.
+- `.claude/skills/devtools-docs` for the docs site (`apps/docs`) and `README.md`.
 - `.claude/skills/devtools-verify` before calling a change done.
 - `.claude/skills/devtools-commit` for commits and pull requests.
 
 Roles for delegating work live in `.claude/agents/`: `ui-engineer`, `inspector-engineer`, `a11y-reviewer` and `devtools-reviewer`.
+
+## Serving Locally
+
+- **Demo app (SSR):** `pnpm build --configuration development && node dist/angular-devtools/server/server.mjs` → http://localhost:4000
+- **Devtools SPA (hot reload):** `pnpm devtools:dev` → http://localhost:5173 (requires the SSR server running for RPC data)
+- **Demo app (SPA, no SSR):** `pnpm start` → http://localhost:4200 (runs `ng serve` with SSR and hot reload; devtools popup + RPC work without a separate server)
+- The devtools popup appears on the demo app page; click it to open the inspector panel
+- Changes to `app/src/` (devtools SPA) are visible live via `pnpm devtools:dev`; the SSR server serves the SPA built into `packages/ng-devtools/dist/public` (or the npm-published copy when it has not been built), so run `pnpm devtools:build-pkg` to refresh it
+- To publish: update the version in `packages/ng-devtools/package.json`, then run `pnpm devtools:publish` (the package build bundles the SPA)
diff --git a/CLAUDE.md b/CLAUDE.md
index 84f6b98..428656b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -70,6 +70,7 @@ Use the matching skill for the task:
 
 - `.claude/skills/devtools-ui` for panel UI work.
 - `.claude/skills/devtools-inspector` for data collection, the server side and agent tools.
+- `.claude/skills/devtools-docs` for the docs site (`apps/docs`) and `README.md`.
 - `.claude/skills/devtools-verify` before calling a change done.
 - `.claude/skills/devtools-commit` for commits and pull requests.
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2385338..86ace52 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 # Contributing to Angular DevTools
 
-Thanks for your interest in contributing! This guide covers how to set up the project, the rules we follow, and how to get a change merged.
+Thanks for your interest in contributing. This guide covers the rules a change follows and how to get it merged. For setup, the project structure, the commands and what CI runs, see [Development setup](./apps/docs/src/content/contributing/development.md) on the docs site.
 
 ## Guidelines
 
@@ -9,91 +9,48 @@ Thanks for your interest in contributing! This guide covers how to set up the pr
 | [Commit message guidelines](docs/contributing/commit-message-guidelines.md) | `type(scope): summary`, types, scopes, body and footer            |
 | [Coding standards](docs/contributing/coding-standards.md)                   | TypeScript and Angular rules, how collectors read the page, tests |
 | [UI guidelines](docs/contributing/ui-guidelines.md)                         | Theme tokens, the brand palette, page anatomy, accessibility      |
+| [Writing guide](apps/docs/src/content/contributing/writing-docs.md)         | Voice, style and structure for the docs site and the README       |
 | [`AGENTS.md`](AGENTS.md)                                                    | Angular best practices for people and AI agents                   |
 
-## Prerequisites
+## Set up the git hooks
 
-- Node.js 24+
-- pnpm 10+
+`pnpm install` turns on the git hooks in `.githooks/` and sets [`.gitmessage`](.gitmessage) as your commit template, unless you already set `core.hooksPath` or `commit.template` yourself:
 
-## Setup
+- `pre-commit` formats the staged files with Prettier. It skips a file that also has unstaged changes, so hunks you left out with `git add -p` stay out.
+- `commit-msg` checks your message against the [commit message guidelines](docs/contributing/commit-message-guidelines.md) and warns when it doesn't follow them. It never blocks the commit.
 
-```sh
-git clone https://github.com/santoshyadavdev/angular-devtools.git
-cd angular-devtools
-pnpm install
-```
-
-`pnpm install` also turns on the git hooks in `.githooks/`: `pre-commit` formats the files you stage with Prettier, and `commit-msg` checks your message against the [commit message guidelines](docs/contributing/commit-message-guidelines.md) and warns when it doesn't follow them. It also sets [`.gitmessage`](.gitmessage) as your commit template.
-
-## Project structure
-
-```
-app/                          # The devtools panel (Angular + Vite), one view per hub dock
-  src/app.ts                  # Panel shell: header, tabs, dock views
-  src/pages/                  # Inspector pages (components, routes, signals, injectors, store, forms, pipes, network, analog, dashboard)
-  src/ui/                     # Shared UI (the dropdown)
-  src/styles/                 # Theme: palette, tokens, mixins
-packages/
-  ng-devtools/                # The publishable package
-    src/hub.ts, hub-docks.ts  # @devframes/hub setup and the dock list
-    src/devframe.ts           # Server side: RPC, shared state, agent tools
-    src/overlay.ts            # Script that runs in the inspected page
-    src/*-collector.ts        # What each inspector reads from the page
-    src/popup.ts, vite.ts     # In-page launcher, Vite plugin
-    src/rpc/                  # Source scans and agent tool helpers
-extension/                    # Chrome extension (extension/ui is generated)
-src/                          # Angular Travel, the demo app
-examples/analog/              # Analog demo app
-docs/contributing/            # The guides above
-.claude/skills/, .claude/agents/  # Skills and roles for AI agents
-```
-
-## Development
-
-```sh
-pnpm start                  # Angular Travel with the devtools on :4200
-pnpm build --configuration development && node dist/angular-devtools/server/server.mjs
-                            # SSR demo on :4000 (a plain `pnpm build` turns the launcher off)
-pnpm analog:dev             # Analog demo on :5173
-pnpm devtools:dev           # The panel on its own
-pnpm extension:build        # Rebuild the panel into extension/ui
-```
-
-## Making changes
+## Make changes
 
 - **A new inspector or a data fix:** follow [Reading data from the page](docs/contributing/coding-standards.md#reading-data-from-the-page-packagesng-devtools). Collection goes in its own module, reports carry a `pageId`, and the server expires and forgets pages.
-- **A new tab:** add it to `app/src/types/tab.types.ts`, `allTabs` and the template in `app/src/app.ts`, an icon in `app/src/pages/tab-icon.ts`, and usually a Dashboard card.
-- **UI changes:** follow the [UI guidelines](docs/contributing/ui-guidelines.md); use the theme variables, the SCSS mixins and the shared dropdown.
-- **Agent tools:** register them with `ctx.agent.registerTool()` or an RPC function's `agent` field, describe what they return and when they are empty, and add tests.
+- **A new tab, RPC function or agent tool:** follow the steps in [Development setup](./apps/docs/src/content/contributing/development.md). Describe what an agent tool returns and when it is empty, and add tests.
+- **UI changes:** follow the [UI guidelines](docs/contributing/ui-guidelines.md). Use the theme variables, the SCSS mixins and the shared dropdown.
+- **Docs changes:** follow the [writing guide](./apps/docs/src/content/contributing/writing-docs.md). Run the docs site with `pnpm docs:dev`.
+
+## Run the checks
 
-## Testing
+Run the checks from [Development setup](./apps/docs/src/content/contributing/development.md), plus these:
 
 ```sh
-pnpm format:check
 pnpm commit:check                             # commit messages on your branch
 pnpm skills:check                             # agent skills and roles
-pnpm typecheck
 pnpm exec ngc -p app/tsconfig.json --noEmit   # panel template check
-pnpm test                                     # demo app
-pnpm test:devtools                            # devtools package
 ```
 
 For UI changes, also check the pages in a browser with axe, in dark and light themes and at a narrow width. The [devtools-verify skill](.claude/skills/devtools-verify/SKILL.md) lists the exact steps.
 
-## Submitting a pull request
+## Submit a pull request
 
 1. Search the open issues and pull requests first. For a bigger feature, open an issue to discuss it before you start.
 2. Fork the repository and create a branch from `main`.
 3. Keep one feature per pull request, with its tests (and agent tool tests when tools change).
 4. If you changed `app/`, run `pnpm extension:build` and commit `extension/ui`. CI fails when it is stale.
 5. Make sure all the checks above pass.
-6. Open the pull request against `main` and fill in the template. **The title must follow the [commit message format](docs/contributing/commit-message-guidelines.md)**, for example `feat(router): show guard results for lazy routes`; it becomes the commit on `main` when the pull request is squash merged. CI checks the title and every commit message; a local `commit-msg` hook (enabled by `pnpm install`) checks each commit as you make it, and `pnpm commit:check` checks your whole branch.
-7. Address review feedback with [fixup commits](docs/contributing/using-fixup-commits.md); don't force-push over a review in progress unless asked.
+6. Open the pull request against `main` and fill in the template. **The title must follow the [commit message format](docs/contributing/commit-message-guidelines.md)**, for example `feat(router): show guard results for lazy routes`. It becomes the commit on `main` when the pull request is squash merged. CI checks the title and every commit message, and for now reports problems as warnings.
+7. Address review feedback with [fixup commits](docs/contributing/using-fixup-commits.md). Don't force-push over a review in progress unless asked.
 
-## Working with AI agents
+## Work with AI agents
 
-The repository ships skills and roles for AI coding agents, so changes made with an agent follow the same rules as everyone else's. Claude Code picks them up automatically from `.claude/`; other agents can read the same files.
+The repository ships skills and roles for AI coding agents, so changes made with an agent follow the same rules as everyone else's. Claude Code picks them up automatically from `.claude/`. Other agents can read the same files.
 
 ### Skills (`.claude/skills/`)
 
@@ -101,6 +58,7 @@ The repository ships skills and roles for AI coding agents, so changes made with
 | ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
 | [`devtools-ui`](.claude/skills/devtools-ui/SKILL.md)               | Building or restyling anything in the panel                                |
 | [`devtools-inspector`](.claude/skills/devtools-inspector/SKILL.md) | Adding an inspector or fixing the data it shows, including agent tools     |
+| [`devtools-docs`](.claude/skills/devtools-docs/SKILL.md)           | Writing or reviewing the docs site and the README                          |
 | [`devtools-verify`](.claude/skills/devtools-verify/SKILL.md)       | Checking a change like CI and a reviewer would, including axe in a browser |
 | [`devtools-commit`](.claude/skills/devtools-commit/SKILL.md)       | Writing commits, pull request titles and descriptions                      |
 
diff --git a/README.md b/README.md
index 01b887e..de8669f 100644
--- a/README.md
+++ b/README.md
@@ -460,27 +460,6 @@ cp -r dist/devtools-ui/* extension/ui/
 
 The extension panel loads the SPA in static mode by default. To connect it to a live dev server for real-time RPC, the extension's content script or background service worker needs to detect the devframe's `__connection.json` on the inspected page and pass the connection to the panel. This is the same pattern the official Angular DevTools Chrome extension uses — a content script bridges the inspected page and the DevTools panel via `chrome.runtime.connect`.
 
-## Contributing
-
-Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), then the guides it links to:
-
-- [Commit message guidelines](docs/contributing/commit-message-guidelines.md): `type(scope): summary`. Pull request titles follow it too, and CI checks them.
-- [Coding standards](docs/contributing/coding-standards.md): TypeScript and Angular rules, and how inspectors read the running app.
-- [UI guidelines](docs/contributing/ui-guidelines.md): theme tokens, the brand palette (change it in one line in `app/src/styles/main.scss`), page anatomy and accessibility.
-
-### Skills and roles for AI agents
-
-If you work with an AI coding agent, the repository ships skills in [`.claude/skills/`](.claude/skills) and roles in [`.claude/agents/`](.claude/agents) that carry these rules, so agent-made changes follow the same conventions.
-
-| Skill                | For                                                           |
-| -------------------- | ------------------------------------------------------------- |
-| `devtools-ui`        | Panel UI and UX work                                          |
-| `devtools-inspector` | How inspectors collect data, the server side and agent tools  |
-| `devtools-verify`    | Checking a change like CI and a reviewer would, including axe |
-| `devtools-commit`    | Commits and pull requests                                     |
-
-Roles: `ui-engineer`, `inspector-engineer`, `a11y-reviewer` (read only) and `devtools-reviewer` (read only). See [CONTRIBUTING.md](CONTRIBUTING.md#working-with-ai-agents) for details.
-
 ## Community
 
 Join the conversation, ask questions, and share feedback on [Discord](https://discord.gg/YRTyJd6Qx).

From f79f407fe2219aa9277f822e51543fb86fb38b0d Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 10:28:35 +0300
Subject: [PATCH 07/16] docs: add a security policy and a code of conduct

The repository had neither, so a vulnerability report had nowhere
private to go and GitHub's community profile listed both as missing.
SECURITY.md sends reports to GitHub's private vulnerability reporting.
The code of conduct is the Contributor Covenant 2.1, with the
maintainers on GitHub and Discord as the contact.
---
 CODE_OF_CONDUCT.md | 119 +++++++++++++++++++++++++++++++++++++++++++++
 CONTRIBUTING.md    |   2 +
 SECURITY.md        |  24 +++++++++
 3 files changed, 145 insertions(+)
 create mode 100644 CODE_OF_CONDUCT.md
 create mode 100644 SECURITY.md

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..e340e93
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,119 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race, caste, color, religion,
+or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive,
+and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from
+  the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their
+  explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable
+behavior and will take appropriate and fair corrective action in response to any behavior that
+they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits,
+code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct,
+and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is
+officially representing the community in public spaces. Examples of representing our community
+include using an official e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project
+maintainers, by contacting @santoshyadavdev on GitHub or a maintainer on the project's
+[Discord](https://discord.gg/YRTyJd6Qx). All complaints will be reviewed and investigated promptly
+and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any
+incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences
+for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or
+unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the
+nature of the violation and an explanation of why the behavior was inappropriate. A public apology
+may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the
+people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a
+specified period of time. This includes avoiding interactions in community spaces as well as
+external channels like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained
+inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the
+community for a specified period of time. No public or private interaction with the people
+involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed
+during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including
+sustained inappropriate behavior, harassment of an individual, or aggression toward or
+disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available
+at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement
+ladder][mozilla-coc].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla-coc]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 86ace52..73e0b77 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,6 +2,8 @@
 
 Thanks for your interest in contributing. This guide covers the rules a change follows and how to get it merged. For setup, the project structure, the commands and what CI runs, see [Development setup](./apps/docs/src/content/contributing/development.md) on the docs site.
 
+By taking part you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md). Report security issues privately, as [SECURITY.md](./SECURITY.md) describes.
+
 ## Guidelines
 
 | Guide                                                                       | What it covers                                                    |
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..6ac1457
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,24 @@
+# Security policy
+
+## Supported versions
+
+Angular DevTools is in early development. Only the latest published release of
+`@santoshyadavdev/ng-devtools` is supported. There are no older release lines to backport a fix to.
+
+## Reporting a vulnerability
+
+Report a vulnerability privately through GitHub's
+[private vulnerability reporting](https://github.com/santoshyadavdev/angular-devtools/security/advisories/new)
+("Report a vulnerability" on the repository's Security tab). Don't open a public issue for a
+security report.
+
+Include what you'd include in any bug report: the version affected, how the devtools are set up
+(Angular CLI with Express, Vite, Analog, the standalone CLI, the MCP server or the Chrome
+extension), a description of the issue and, if you have one, a minimal reproduction.
+
+## What to expect
+
+This is a small project maintained in spare time, so there is no formal SLA. Expect an
+acknowledgement within a few days, and a fix or a public response once the report has been
+triaged. If the issue is confirmed, the fix goes out in the next release and the advisory credits
+you unless you ask otherwise.

From fcaaa75c887828f0770add85ece5d59cb80dca53 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 10:29:00 +0300
Subject: [PATCH 08/16] ci: route issues, reviews and sponsorship through
 GitHub

Turn off blank issues and send questions to Discord and security
reports to private vulnerability reporting, request a maintainer review
on every pull request through CODEOWNERS, and show the Sponsor button
the README already asks for. Add the docs site to the bug report areas,
and the skills and docs checks to the pull request checklist.
---
 .github/CODEOWNERS                    | 1 +
 .github/FUNDING.yml                   | 1 +
 .github/ISSUE_TEMPLATE/bug_report.yml | 1 +
 .github/ISSUE_TEMPLATE/config.yml     | 8 ++++++++
 .github/PULL_REQUEST_TEMPLATE.md      | 2 ++
 5 files changed, 13 insertions(+)
 create mode 100644 .github/CODEOWNERS
 create mode 100644 .github/FUNDING.yml
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 0000000..5a3bbe3
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1 @@
+* @santoshyadavdev
diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml
new file mode 100644
index 0000000..4e8a97b
--- /dev/null
+++ b/.github/FUNDING.yml
@@ -0,0 +1 @@
+github: [santoshyadavdev]
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index ea65137..b5629b2 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -21,6 +21,7 @@ body:
         - Agent tools (MCP)
         - Vite plugin or setup
         - Demo app
+        - Documentation site
     validations:
       required: true
   - type: textarea
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..87b02a6
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions and ideas
+    url: https://discord.gg/YRTyJd6Qx
+    about: Ask how to do something, or float an idea before it becomes a feature request.
+  - name: Security vulnerabilities
+    url: https://github.com/santoshyadavdev/angular-devtools/security/advisories/new
+    about: Report privately, as SECURITY.md describes, not as a public issue.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index c2121af..37881e0 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -14,6 +14,8 @@ See docs/contributing/commit-message-guidelines.md
 - [ ] `pnpm format:check`
 - [ ] `pnpm typecheck` and the `ngc` template check (`pnpm exec ngc -p app/tsconfig.json --noEmit`)
 - [ ] `pnpm test` and `pnpm test:devtools`
+- [ ] `pnpm skills:check` (when `.claude/` changed)
+- [ ] `pnpm docs:build` and the docs updated (when behavior, options or agent tools changed)
 - [ ] `pnpm extension:build` and `extension/ui` committed (when `app/` changed)
 - [ ] Checked in the browser with axe (when the UI changed)
 

From 4410d1831b69d687fde8bb3e71bcecab742bdf46 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 10:32:34 +0300
Subject: [PATCH 09/16] ci: label pull requests by area and group release notes
 by label

Reviewers can't tell from the list which part of the repository a pull
request touches. Label each one from the paths it changes (panel,
package, extension, demo, documentation, agents, ci) with
actions/labeler, which runs on pull_request_target without checking
out the pull request's code. GitHub's generated release notes then
group the merged pull requests by the same labels.
---
 .github/labeler.yml           | 27 +++++++++++++++++++++++++++
 .github/release.yml           | 14 ++++++++++++++
 .github/workflows/labeler.yml | 20 ++++++++++++++++++++
 3 files changed, 61 insertions(+)
 create mode 100644 .github/labeler.yml
 create mode 100644 .github/release.yml
 create mode 100644 .github/workflows/labeler.yml

diff --git a/.github/labeler.yml b/.github/labeler.yml
new file mode 100644
index 0000000..a3f8908
--- /dev/null
+++ b/.github/labeler.yml
@@ -0,0 +1,27 @@
+'area: panel':
+  - changed-files:
+      - any-glob-to-any-file: ['app/**']
+
+'area: package':
+  - changed-files:
+      - any-glob-to-any-file: ['packages/ng-devtools/**', 'bin.mjs']
+
+'area: extension':
+  - changed-files:
+      - any-glob-to-any-file: ['extension/**']
+
+'area: demo':
+  - changed-files:
+      - any-glob-to-any-file: ['src/**', 'public/**', 'examples/**']
+
+documentation:
+  - changed-files:
+      - any-glob-to-any-file: ['apps/docs/**', 'docs/**', '*.md']
+
+'area: agents':
+  - changed-files:
+      - any-glob-to-any-file: ['.claude/**', 'AGENTS.md', 'CLAUDE.md']
+
+ci:
+  - changed-files:
+      - any-glob-to-any-file: ['.github/**', '.githooks/**', 'scripts/**']
diff --git a/.github/release.yml b/.github/release.yml
new file mode 100644
index 0000000..3db2d03
--- /dev/null
+++ b/.github/release.yml
@@ -0,0 +1,14 @@
+changelog:
+  exclude:
+    labels: [ignore-for-release]
+  categories:
+    - title: Package
+      labels: ['area: package']
+    - title: Panel
+      labels: ['area: panel']
+    - title: Chrome extension
+      labels: ['area: extension']
+    - title: Documentation
+      labels: [documentation]
+    - title: Other changes
+      labels: ['*']
diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml
new file mode 100644
index 0000000..0b3f27a
--- /dev/null
+++ b/.github/workflows/labeler.yml
@@ -0,0 +1,20 @@
+name: Labeler
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/labeler@v7

From c2ee7eb8a4660ef7c982a471a0a2694bf421f801 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 10:33:31 +0300
Subject: [PATCH 10/16] docs: recognize contributors with all-contributors

The README thanked sponsors but not the people who wrote the code. Add
the all-contributors list, seeded with the four people in the commit
history, so the all-contributors bot can add anyone else, for any kind
of contribution, from a pull request comment. Prettier skips the
config, since the bot rewrites it in its own style.
---
 .all-contributorsrc | 43 +++++++++++++++++++++++++++++++++++++++++++
 .prettierignore     |  1 +
 README.md           | 25 +++++++++++++++++++++++++
 3 files changed, 69 insertions(+)
 create mode 100644 .all-contributorsrc

diff --git a/.all-contributorsrc b/.all-contributorsrc
new file mode 100644
index 0000000..c210063
--- /dev/null
+++ b/.all-contributorsrc
@@ -0,0 +1,43 @@
+{
+  "files": ["README.md"],
+  "imageSize": 100,
+  "commit": false,
+  "commitType": "docs",
+  "commitConvention": "angular",
+  "contributors": [
+    {
+      "login": "santoshyadavdev",
+      "name": "Santosh Yadav",
+      "avatar_url": "https://avatars.githubusercontent.com/u/11923975?v=4",
+      "profile": "https://santoshyadav.dev",
+      "contributions": ["code", "maintenance"]
+    },
+    {
+      "login": "erkamyaman",
+      "name": "erKam",
+      "avatar_url": "https://avatars.githubusercontent.com/u/88717125?v=4",
+      "profile": "https://erkamyaman.dev",
+      "contributions": ["code"]
+    },
+    {
+      "login": "abiramcodes",
+      "name": "Abiram",
+      "avatar_url": "https://avatars.githubusercontent.com/u/131433061?v=4",
+      "profile": "https://www.abikb.xyz/",
+      "contributions": ["code"]
+    },
+    {
+      "login": "Kaap10",
+      "name": "Vardhman Gupta",
+      "avatar_url": "https://avatars.githubusercontent.com/u/112063624?v=4",
+      "profile": "https://kaap10.github.io/portfolio",
+      "contributions": ["code"]
+    }
+  ],
+  "contributorsPerLine": 7,
+  "skipCi": true,
+  "repoType": "github",
+  "repoHost": "https://github.com",
+  "projectName": "angular-devtools",
+  "projectOwner": "santoshyadavdev"
+}
diff --git a/.prettierignore b/.prettierignore
index 00b7438..140eaa8 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -4,3 +4,4 @@ dist
 pnpm-lock.yaml
 extension/ui
 docs/privacy-policy.html
+.all-contributorsrc
diff --git a/README.md b/README.md
index de8669f..868554d 100644
--- a/README.md
+++ b/README.md
@@ -477,6 +477,31 @@ Thanks to our current sponsors:
 <a href="https://github.com/Sonichigo"><img src="https://github.com/Sonichigo.png?size=60" width="60" height="60" alt="Sonichigo" /></a>
 <!-- /sponsors -->
 
+## Contributors
+
+Thanks to everyone who has contributed:
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://santoshyadav.dev"><img src="https://avatars.githubusercontent.com/u/11923975?v=4?s=100" width="100px;" alt="Santosh Yadav"/><br /><sub><b>Santosh Yadav</b></sub></a><br /><a href="https://github.com/santoshyadavdev/angular-devtools/commits?author=santoshyadavdev" title="Code">💻</a> <a href="#maintenance-santoshyadavdev" title="Maintenance">🚧</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://erkamyaman.dev"><img src="https://avatars.githubusercontent.com/u/88717125?v=4?s=100" width="100px;" alt="erKam"/><br /><sub><b>erKam</b></sub></a><br /><a href="https://github.com/santoshyadavdev/angular-devtools/commits?author=erkamyaman" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://www.abikb.xyz/"><img src="https://avatars.githubusercontent.com/u/131433061?v=4?s=100" width="100px;" alt="Abiram"/><br /><sub><b>Abiram</b></sub></a><br /><a href="https://github.com/santoshyadavdev/angular-devtools/commits?author=abiramcodes" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://kaap10.github.io/portfolio"><img src="https://avatars.githubusercontent.com/u/112063624?v=4?s=100" width="100px;" alt="Vardhman Gupta"/><br /><sub><b>Vardhman Gupta</b></sub></a><br /><a href="https://github.com/santoshyadavdev/angular-devtools/commits?author=Kaap10" title="Code">💻</a></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome.
+
 ## License
 
 MIT

From 11164b732ddaa3670800ef806e242352da5f5257 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 12:14:15 +0300
Subject: [PATCH 11/16] ci: ask pull requests to update the docs with the code

Add the rule to CONTRIBUTING, the pull request template and the verify
and reviewer skills, and a warn-only Docs check workflow that flags code
changes without an apps/docs change unless the no-docs label is set.
---
 .claude/agents/devtools-reviewer.md     |  2 +-
 .claude/skills/devtools-verify/SKILL.md |  2 +-
 .github/PULL_REQUEST_TEMPLATE.md        |  2 +-
 .github/workflows/docs-check.yml        | 42 +++++++++++++++++++++++++
 CONTRIBUTING.md                         |  1 +
 5 files changed, 46 insertions(+), 3 deletions(-)
 create mode 100644 .github/workflows/docs-check.yml

diff --git a/.claude/agents/devtools-reviewer.md b/.claude/agents/devtools-reviewer.md
index cbd0cec..3d0973a 100644
--- a/.claude/agents/devtools-reviewer.md
+++ b/.claude/agents/devtools-reviewer.md
@@ -13,6 +13,6 @@ Check the diff against:
 - `docs/contributing/commit-message-guidelines.md` for commit messages and the pull request title.
 - Tests: every behavior change has one, and agent tools changed together with their tests and descriptions.
 - Generated output: `extension/ui` rebuilt and committed when `app/` changed.
-- Docs: when the diff touches the docs site (apps/docs) or `README.md`, check it against the `devtools-docs` skill.
+- Docs: when the diff touches the docs site (apps/docs) or `README.md`, check it against the `devtools-docs` skill. When the diff changes behaviour, an option, a UI label or an agent tool and no page in `apps/docs` changed, flag it (unless the pull request has the `no-docs` label and says why).
 
 Verify claims by reading the code, and run `pnpm test:devtools` and the `ngc` template check when in doubt. Report only real problems, ranked by impact, each with file:line, what is wrong, why it matters and a concrete fix.
diff --git a/.claude/skills/devtools-verify/SKILL.md b/.claude/skills/devtools-verify/SKILL.md
index f836a2a..6ae060e 100644
--- a/.claude/skills/devtools-verify/SKILL.md
+++ b/.claude/skills/devtools-verify/SKILL.md
@@ -24,7 +24,7 @@ git status --porcelain -- extension/ui   # must be committed when app/ changed
 
 CI runs `pnpm exec nx affected -t test build` instead of the plain `pnpm test` and `pnpm build`; run it too when your change touches more than one project.
 
-When the change touches the docs site (apps/docs) or `README.md`, also run the build checks in the `devtools-docs` skill.
+When the change affects behaviour, an option, a UI label or an agent tool, update the matching page in `apps/docs` in the same change (use the `devtools-docs` skill). When the change touches the docs site (apps/docs) or `README.md`, also run the build checks in the `devtools-docs` skill.
 
 `pnpm typecheck` does not type-check panel templates. Also run:
 
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 37881e0..782f289 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -15,7 +15,7 @@ See docs/contributing/commit-message-guidelines.md
 - [ ] `pnpm typecheck` and the `ngc` template check (`pnpm exec ngc -p app/tsconfig.json --noEmit`)
 - [ ] `pnpm test` and `pnpm test:devtools`
 - [ ] `pnpm skills:check` (when `.claude/` changed)
-- [ ] `pnpm docs:build` and the docs updated (when behavior, options or agent tools changed)
+- [ ] Docs in `apps/docs` updated and `pnpm docs:build` passes (when behavior, options, UI labels or agent tools changed), or the `no-docs` label added with the reason below
 - [ ] `pnpm extension:build` and `extension/ui` committed (when `app/` changed)
 - [ ] Checked in the browser with axe (when the UI changed)
 
diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml
new file mode 100644
index 0000000..87f8763
--- /dev/null
+++ b/.github/workflows/docs-check.yml
@@ -0,0 +1,42 @@
+name: Docs check
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Docs updated with the code
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+          NO_DOCS: ${{ contains(github.event.pull_request.labels.*.name, 'no-docs') }}
+        run: |
+          changed=$(git diff --name-only "$BASE...$HEAD")
+          code=$(printf '%s\n' "$changed" | grep -E '^(packages/ng-devtools/src/|app/src/|extension/[^/]+$)' | grep -vE '(__tests__/|\.(spec|test)\.ts$)' || true)
+          docs=$(printf '%s\n' "$changed" | grep -E '^apps/docs/src/content/' || true)
+          if [ -z "$code" ]; then
+            echo "No code changes that need docs."
+          elif [ -n "$docs" ]; then
+            echo "Code and docs both changed."
+          elif [ "$NO_DOCS" = "true" ]; then
+            echo "Code changed without docs, marked no-docs."
+          else
+            echo "::warning title=Docs not updated::This pull request changes code but no page in apps/docs/src/content. Update the docs in this pull request, or add the no-docs label and say why in the description."
+            printf '%s\n' "$code"
+          fi
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 73e0b77..2b6db30 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,6 +27,7 @@ By taking part you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md). Report
 - **A new tab, RPC function or agent tool:** follow the steps in [Development setup](./apps/docs/src/content/contributing/development.md). Describe what an agent tool returns and when it is empty, and add tests.
 - **UI changes:** follow the [UI guidelines](docs/contributing/ui-guidelines.md). Use the theme variables, the SCSS mixins and the shared dropdown.
 - **Docs changes:** follow the [writing guide](./apps/docs/src/content/contributing/writing-docs.md). Run the docs site with `pnpm docs:dev`.
+- **Keep the docs in step with the code:** when a pull request changes behaviour, an option, a UI label or an agent tool, update the matching page in `apps/docs` in the same pull request. If no docs change is needed, add the `no-docs` label and say why in the description. The Docs check workflow warns when code changes without docs.
 
 ## Run the checks
 

From 0dcbf2a18d31ce0118334525283b92c445e5122e Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 12:47:30 +0300
Subject: [PATCH 12/16] ci: ask for the setup in bug reports and the docs
 impact in feature requests

---
 .github/ISSUE_TEMPLATE/bug_report.yml      | 15 +++++++++++++++
 .github/ISSUE_TEMPLATE/feature_request.yml | 12 ++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index b5629b2..7881994 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -24,6 +24,21 @@ body:
         - Documentation site
     validations:
       required: true
+  - type: dropdown
+    id: setup
+    attributes:
+      label: Setup
+      description: How the devtools are mounted in your app.
+      options:
+        - Angular CLI with Express (initNgDevtoolsHub)
+        - Vite plugin
+        - Analog
+        - Standalone CLI (ng-devtools dev)
+        - Chrome extension
+        - MCP server (stdio or HTTP)
+        - Other
+    validations:
+      required: true
   - type: textarea
     id: what
     attributes:
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
index e99a38a..a1b1082 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -21,6 +21,18 @@ body:
     attributes:
       label: Angular APIs involved
       description: Debug APIs or framework internals that could provide the data, if you know them.
+  - type: dropdown
+    id: docs
+    attributes:
+      label: Docs impact
+      description: Pages in the docs site that the change would need to update.
+      options:
+        - A new or changed inspector page
+        - Agent tools or resources
+        - Setup or options
+        - Security
+        - None
+        - Not sure
   - type: checkboxes
     id: help
     attributes:

From 018d064f55eef106646c8f3fdc4cbf1cb7896c2f Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 12:52:21 +0300
Subject: [PATCH 13/16] fix(ci): check git prefixes in pull request titles and
 restage files literally

A pull request title like "fixup! ..." now fails the title check,
because the title becomes the squash commit. The pre-commit hook restages
files with literal pathspecs, so a name like item[1].ts can't also stage
item1.ts.
---
 .githooks/pre-commit       | 2 +-
 scripts/commit-message.mjs | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index a4cffaf..7364808 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -22,5 +22,5 @@ git -c core.quotePath=false diff --cached --name-only --diff-filter=ACMR |
 
 tr '\n' '\0' <"$list" | xargs -0 pnpm --silent exec prettier --write --ignore-unknown >/dev/null 2>&1 ||
   echo "WARNING: failed to format staged files." >&2
-tr '\n' '\0' <"$list" | xargs -0 git add --
+tr '\n' '\0' <"$list" | xargs -0 git --literal-pathspecs add --
 exit 0
diff --git a/scripts/commit-message.mjs b/scripts/commit-message.mjs
index e8ca2d0..a8e0dd7 100755
--- a/scripts/commit-message.mjs
+++ b/scripts/commit-message.mjs
@@ -47,7 +47,7 @@ const MIN_BODY = 20;
 const HEADER = /^(\w+)(?:\(([^)]+)\))?(!)?: (.+)$/;
 const GUIDE = 'docs/contributing/commit-message-guidelines.md';
 
-export function validate(message, { requireBody = true } = {}) {
+export function validate(message, { requireBody = true, allowGitPrefixes = true } = {}) {
   const lines = message
     .split('\n')
     .filter((line) => !line.startsWith('#'))
@@ -57,7 +57,7 @@ export function validate(message, { requireBody = true } = {}) {
   const header = lines[0] ?? '';
   const errors = [];
 
-  if (/^(Merge |fixup! |squash! |amend! )/.test(header)) return errors;
+  if (allowGitPrefixes && /^(Merge |fixup! |squash! |amend! )/.test(header)) return errors;
 
   if (!header) return ['The commit message is empty.'];
   if (header.length > MAX_HEADER) {
@@ -121,7 +121,7 @@ function main(args) {
   if (mode === '--title') {
     const ok = report(
       'Pull request title check failed:',
-      validate(value ?? '', { requireBody: false }),
+      validate(value ?? '', { requireBody: false, allowGitPrefixes: false }),
     );
     if (!ok) console.error(`\nThe title becomes the squash commit on main. See ${GUIDE}.\n`);
     return ok;

From 48fed0fa2460e8359d09449e4bbf62d7111f0eb3 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 13:03:33 +0300
Subject: [PATCH 14/16] ci: check skill references into apps/ now that the docs
 site exists

The skills check skipped paths under apps/ because apps/docs was not on main yet. It is now, so references to the docs site are validated like the rest.
---
 scripts/validate-skills.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/validate-skills.mjs b/scripts/validate-skills.mjs
index 84584f7..7371b11 100644
--- a/scripts/validate-skills.mjs
+++ b/scripts/validate-skills.mjs
@@ -28,7 +28,7 @@ function checkLinks(file, body) {
     if (!existsSync(target)) errors.push(`${file}: broken link ${link}`);
   }
   for (const [, path] of body.matchAll(
-    /`((?:app|packages|docs|scripts|src|\.claude|\.github)\/[^`\s*<>]+)`/g,
+    /`((?:app|apps|packages|docs|scripts|src|\.claude|\.github)\/[^`\s*<>]+)`/g,
   )) {
     if (!existsSync(join(root, path))) errors.push(`${file}: ${path} does not exist`);
   }

From 9a9f64d87a5bfcde783791fbfbd44a46af59f155 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 13:03:33 +0300
Subject: [PATCH 15/16] docs: describe the git hooks and pull request checks in
 development setup

Cover the hooks pnpm install turns on, pnpm skills:check and pnpm commit:check, the skills step in CI, the warn-only Commit message and Docs check workflows, and the no-docs label.
---
 .../src/content/contributing/development.md   | 28 +++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/apps/docs/src/content/contributing/development.md b/apps/docs/src/content/contributing/development.md
index f3d1fd4..d9cecd7 100644
--- a/apps/docs/src/content/contributing/development.md
+++ b/apps/docs/src/content/contributing/development.md
@@ -32,6 +32,15 @@ pnpm install
 
 `pnpm-workspace.yaml` lists `packages/*`, `examples/*` and `apps/*`, so one install covers every project.
 
+### Git hooks
+
+`pnpm install` sets `core.hooksPath` to `.githooks` and `commit.template` to `.gitmessage`. If you already set either one yourself, it keeps your value.
+
+| Hook         | What it does                                                                                                                                                                                                               |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pre-commit` | Formats the staged files with Prettier and stages the result. It skips a file that also has unstaged changes, so hunks you left out with `git add -p` stay out of the commit.                                              |
+| `commit-msg` | Checks the message against the [commit message guidelines](https://github.com/santoshyadavdev/angular-devtools/blob/main/docs/contributing/commit-message-guidelines.md). It prints a warning and never blocks the commit. |
+
 ## Project structure
 
 ```text
@@ -126,8 +135,12 @@ pnpm typecheck                      # Host app + specs, devtools UI, devtools pa
 pnpm exec nx affected -t test build # Test and build affected projects
 pnpm test:devtools                  # Devtools package tests (Vitest)
 pnpm extension:build                # Chrome extension
+pnpm skills:check                   # Agent skills and roles in .claude/
+pnpm commit:check                   # Commit messages on your branch
 ```
 
+`pnpm skills:check` validates the frontmatter of every skill and role and checks that the files and links they mention exist. `pnpm commit:check` checks every commit on your branch that is not on `main` (it compares with `upstream/main`, then `origin/main`, then `main`).
+
 ### What CI runs
 
 `.github/workflows/ci.yml` runs on pushes and pull requests to `main`, in this order:
@@ -136,8 +149,8 @@ pnpm extension:build                # Chrome extension
   <ngmd-step title="Install">
     <code>pnpm install --frozen-lockfile</code> on the Node version from <code>.nvmrc</code>.
   </ngmd-step>
-  <ngmd-step title="Check formatting and types">
-    <code>pnpm format:check</code>, then <code>pnpm typecheck</code>.
+  <ngmd-step title="Check formatting, skills and types">
+    <code>pnpm format:check</code>, <code>pnpm skills:check</code>, then <code>pnpm typecheck</code>.
   </ngmd-step>
   <ngmd-step title="Test and build affected projects">
     <code>nx affected -t test build</code>, compared against the last green commit on <code>main</code>.
@@ -153,6 +166,17 @@ pnpm extension:build                # Chrome extension
   </ngmd-step>
 </ngmd-workflow>
 
+### Pull request checks
+
+Two more workflows run on pull requests. Both only warn. They never fail the pull request.
+
+| Workflow         | File                                   | What it checks                                                                                                                                                     |
+| ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Commit message` | `.github/workflows/commit-message.yml` | The pull request title and every commit message. The title becomes the commit on `main` when the pull request is squash merged.                                    |
+| `Docs check`     | `.github/workflows/docs-check.yml`     | That a change to `packages/ng-devtools/src/`, `app/src/` or the top-level files in `extension/` also changes a page in `apps/docs/src/content`. Tests don't count. |
+
+If a code change needs no docs change, add the `no-docs` label to the pull request and say why in the description. The `Docs check` workflow then skips the warning.
+
 ## Make changes
 
 ### Add an RPC function

From 8b9e6fd1fde715daea08a258aebef9ada6a6eef2 Mon Sep 17 00:00:00 2001
From: Kam <erkamyaman35@gmail.com>
Date: Wed, 30 Sep 2026 13:46:05 +0300
Subject: [PATCH 16/16] ci: use Angular-style labels in the templates, labeler
 and release notes

Issue forms add bug or feature with needs triage, the labeler uses area:
labels only, release notes group by change type, and CONTRIBUTING lists
every label.
---
 .github/ISSUE_TEMPLATE/bug_report.yml      |  2 +-
 .github/ISSUE_TEMPLATE/feature_request.yml |  2 +-
 .github/labeler.yml                        | 16 +++++++++-------
 .github/release.yml                        | 16 ++++++++--------
 CONTRIBUTING.md                            | 15 +++++++++++++++
 5 files changed, 34 insertions(+), 17 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 7881994..53c6744 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -1,6 +1,6 @@
 name: Bug report
 description: Something in the devtools shows wrong data, breaks, or looks wrong
-labels: [bug]
+labels: [bug, needs triage]
 body:
   - type: dropdown
     id: area
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
index a1b1082..0282442 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -1,6 +1,6 @@
 name: Feature request
 description: Suggest an inspector, a view or an agent tool
-labels: [enhancement]
+labels: [feature, needs triage]
 body:
   - type: textarea
     id: problem
diff --git a/.github/labeler.yml b/.github/labeler.yml
index a3f8908..49276bc 100644
--- a/.github/labeler.yml
+++ b/.github/labeler.yml
@@ -6,6 +6,11 @@
   - changed-files:
       - any-glob-to-any-file: ['packages/ng-devtools/**', 'bin.mjs']
 
+'area: agents':
+  - changed-files:
+      - any-glob-to-any-file:
+          ['packages/ng-devtools/src/devframe.ts', 'packages/ng-devtools/src/rpc/**']
+
 'area: extension':
   - changed-files:
       - any-glob-to-any-file: ['extension/**']
@@ -14,14 +19,11 @@
   - changed-files:
       - any-glob-to-any-file: ['src/**', 'public/**', 'examples/**']
 
-documentation:
+'area: docs':
   - changed-files:
       - any-glob-to-any-file: ['apps/docs/**', 'docs/**', '*.md']
 
-'area: agents':
-  - changed-files:
-      - any-glob-to-any-file: ['.claude/**', 'AGENTS.md', 'CLAUDE.md']
-
-ci:
+'area: ci':
   - changed-files:
-      - any-glob-to-any-file: ['.github/**', '.githooks/**', 'scripts/**']
+      - any-glob-to-any-file:
+          ['.github/**', '.githooks/**', 'scripts/**', '.claude/**', 'AGENTS.md', 'CLAUDE.md']
diff --git a/.github/release.yml b/.github/release.yml
index 3db2d03..294653a 100644
--- a/.github/release.yml
+++ b/.github/release.yml
@@ -1,14 +1,14 @@
 changelog:
   exclude:
-    labels: [ignore-for-release]
+    labels: ['release: skip']
   categories:
-    - title: Package
-      labels: ['area: package']
-    - title: Panel
-      labels: ['area: panel']
-    - title: Chrome extension
-      labels: ['area: extension']
+    - title: Breaking changes
+      labels: ['breaking changes']
+    - title: Features
+      labels: [feature]
+    - title: Bug fixes
+      labels: [bug]
     - title: Documentation
-      labels: [documentation]
+      labels: ['area: docs']
     - title: Other changes
       labels: ['*']
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2b6db30..c99716e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -29,6 +29,21 @@ By taking part you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md). Report
 - **Docs changes:** follow the [writing guide](./apps/docs/src/content/contributing/writing-docs.md). Run the docs site with `pnpm docs:dev`.
 - **Keep the docs in step with the code:** when a pull request changes behaviour, an option, a UI label or an agent tool, update the matching page in `apps/docs` in the same pull request. If no docs change is needed, add the `no-docs` label and say why in the description. The Docs check workflow warns when code changes without docs.
 
+## Labels
+
+The labels follow the Angular repository.
+
+| Label                                                                             | Use                                                                                                                                                                      |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `bug`, `feature`, `breaking changes`                                              | What kind of change it is. Issue forms add `bug` or `feature` with `needs triage`.                                                                                       |
+| `P0` to `P3`                                                                      | Priority, from broken for most users (`P0`) to not urgent (`P3`).                                                                                                        |
+| `area: *`                                                                         | The part of the repository: panel, package, agents, extension, demo, docs, security, performance, accessibility, ci. Pull requests get these from the paths they change. |
+| `needs triage`, `needs reproduction`, `needs: clarification`, `needs: discussion` | What an issue is waiting for.                                                                                                                                            |
+| `state: confirmed`, `state: has PR`, `state: blocked`, `state: WIP`               | Where an issue stands.                                                                                                                                                   |
+| `action: review`, `action: cleanup`, `action: merge`, `action: discuss`           | What a pull request needs next.                                                                                                                                          |
+| `good first issue`, `help wanted`                                                 | Issues open to new contributors.                                                                                                                                         |
+| `no-docs`, `release: skip`                                                        | No docs change needed; leave out of the release notes.                                                                                                                   |
+
 ## Run the checks
 
 Run the checks from [Development setup](./apps/docs/src/content/contributing/development.md), plus these: