diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 661d44371..49fe962a8 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,171 +1,30 @@
-# ScriptCat Development Guide
+# ScriptCat — Copilot Instructions
 
-## Code Review
-
-When performing a code review, respond in Chinese.
-
-## Architecture Overview
-
-ScriptCat is a sophisticated browser extension that executes user scripts with a unique multi-process architecture:
-
-### Core Components
-- **Service Worker** (`src/service_worker.ts`) - Main background process handling script management, installations, and chrome APIs
-- **Offscreen** (`src/offscreen.ts`) - Isolated background environment for running background/scheduled scripts
-- **Sandbox** (`src/sandbox.ts`) - Secure execution environment inside offscreen for script isolation
-- **Content Scripts** (`src/content.ts`) - Injected into web pages to execute user scripts
-- **Inject Scripts** (`src/inject.ts`) - Runs in page context with access to page globals
-
-### Message Passing System
-ScriptCat uses a sophisticated message passing architecture (`packages/message/`):
-- **ExtensionMessage** - Chrome extension runtime messages between service worker/content/pages
-- **WindowMessage** - PostMessage-based communication between offscreen/sandbox
-- **CustomEventMessage** - CustomEvent-based communication between content/inject scripts
-- **MessageQueue** - Cross-environment event broadcasting system
-
-Key pattern: All communication flows through Service Worker → Offscreen → Sandbox for background scripts, or Service Worker → Content → Inject for page scripts.
-
-### Script Execution Flow
-1. **Page Scripts**: Service Worker registers with `chrome.userScripts` → injected into pages
-2. **Background Scripts**: Service Worker → Offscreen → Sandbox execution
-3. **Scheduled Scripts**: Cron-based execution in Sandbox environment
-
-## Key Development Patterns
-
-### Path Aliases
-```typescript
-"@App": "./src/"
-"@Packages": "./packages/"
-"@Tests": "./tests/"
-```
-
-### Repository Pattern
-All data access uses DAO classes extending `Repo<T>` base class:
-```typescript
-// Example: ScriptDAO, ResourceDAO, SubscribeDAO
-export class ScriptDAO extends Repo<Script> {
-  public save(val: Script) { return super._save(val.uuid, val); }
-}
-```
-
-### Service Layer Structure
-Services follow a consistent pattern with dependency injection:
-```typescript
-export class ExampleService {
-  constructor(
-    private group: Group,           // Message handling group
-    private messageQueue: IMessageQueue,  // Event broadcasting (MessageQueue's interface)
-    private dataDAO: DataDAO        // Data access
-  ) {}
-  
-  init() {
-    this.group.on("action", this.handleAction.bind(this));
-  }
-}
-```
-
-### Script Compilation & Sandboxing
-User scripts are compiled with sandbox context isolation:
-- `compileScriptCode()` - Wraps scripts with error handling and context binding
-- `compileInjectScript()` - Creates window-mounted functions for inject scripts
-- Sandbox uses `with(arguments[0])` for controlled variable access
-
-## Technology Stack
-
-- **React 19** - Component framework with automatic runtime
-- **shadcn/ui** - UI component library built on Radix UI
-- **Tailwind CSS** - Utility-first CSS framework for styling
-- **Rspack** - Fast bundler (Webpack alternative) with SWC
-- **TypeScript** - Type-safe development
-
-
-## Development Workflows
-
-### Build & Development
-```bash
-pnpm run dev           # Development with source maps
-pnpm run dev:noMap     # Development without source maps (needed for incognito)
-pnpm run build         # Production build
-pnpm run pack          # Create browser extension packages
-```
-
-### Testing
-```bash
-pnpm test              # Run all tests with Vitest
-pnpm run coverage      # Generate coverage reports
-```
+> **This file only holds Copilot-specific behavior and a router.** Architecture, coding conventions, commands,
+> and testing mechanics are owned by [`../AGENTS.md`](../AGENTS.md) and the docs it routes to
+> (`docs/develop.md`, `docs/architecture.md`, `docs/references/*`, `docs/verification.md`, `docs/design.md`,
+> `docs/translation.md`). Read those before reviewing or writing code — don't rely on a second, separately
+> maintained copy of them here; when this file and one of those docs disagree, the owning doc wins and this
+> file should be corrected to match.
 
-**Testing Patterns:**
-- Uses Vitest with happy-dom environment
-- Chrome extension APIs mocked via `@Packages/chrome-extension-mock`
-- Message system testing with `MockMessage` classes
-- Sandbox testing validates script isolation
-
-### Code Organization
-- **Monorepo structure** with packages in `packages/` (message, filesystem, etc.)
-- **Feature-based organization** in `src/app/service/` by environment
-- **Shared utilities** in `src/pkg/` for cross-cutting concerns
-- **Type definitions** in `src/types/` with global declarations
-
-### Browser Extension Specifics
-- **Manifest V3** with service worker background
-- **User Scripts API** for script injection (Chrome/Edge)
-- **Offscreen API** for DOM access in background contexts  
-- **Declarative Net Request** for script installation interception
-
-## Critical Integration Points
-
-### Script Installation Flow
-1. URL patterns trigger declarative net request rules
-2. Service Worker opens install page with cached script data
-3. Install page validates and processes script metadata
-4. Scripts registered with appropriate execution environment
-
-### GM API Implementation
-- Split across Content, Service Worker, and Offscreen contexts (each a `GMApi` in its own module)
-- Permission verification via `PermissionVerify` service
-- Value storage abstracted through `ValueService`
-- Cross-origin requests handled in service worker context
-
-### Resource Management
-- `ResourceService` handles script dependencies (@require, @resource)
-- Content Security Policy handling for external resources
-- Caching layer via `Cache` class with automatic expiration
-
-## Debug & Development Notes
-
-- Use `pnpm run dev:noMap` for incognito window development
-- Background script changes require extension reload
-- Message passing debugging available in service worker console
-- Sandbox script execution isolated from page context - use `unsafeWindow` for page access
-
-## File Structure Patterns
-- Tests co-located with source files (`.test.ts` suffix)
-- Template files use `.tpl` extension for build-time processing
-- Configuration files use factory pattern for environment-specific setup
-
-## Language
-- The code is developed and maintained by developers based in Mainland China.
-- Comments should preferably be written in Simplified Chinese.
-- The user interface supports multiple languages, with English set as the default for global users.
-
-## PR Review Policy
-
-When performing Pull Request (PR) reviews, Copilot must always conduct a **comprehensive and independent review** of the entire PR content.
-
-- **Full Review Every Time**  
-  Always review **all modified files** in every PR, regardless of previous reviews or user comments. Even during re-reviews, treat the PR as new and **do not rely on prior review states**.
-
-- **No Skipping of Files**  
-  Do not skip or ignore any text-based file types (including `.md`, `.json`, `.yml`, `.toml`, `.ts`, `.js`, `.py`, `.html`, `.css`, `.tsx`, `.vue`, `.sh`, etc.). Every file that is changed must be fully examined.
-
-- **Reference as Context Only**  
-  PR descriptions, commit messages, or user discussions serve only as **reference context**. The review must focus primarily on the **actual code and file changes**.
-
-- **Infer Intent from Code Changes**  
-  Always attempt to **infer the purpose and intent** of the changes directly from the modified content, rather than relying solely on user statements or PR titles.
-
-- **Critical Thinking Requirement**  
-  For each change, Copilot should assess correctness, consistency, and maintainability — ensuring that logic, style, and architectural impact align with project standards.
+## Code Review
 
-- **Independent Verification**  
-  Do not assume unchanged files or previously reviewed sections are safe; verify all code paths potentially affected by the modifications.
+- Respond in Chinese when performing a code review (用中文回复代码审查意见).
+- Conduct a **comprehensive and independent review** of the entire PR every time:
+  - **Full review every time** — review all modified files regardless of previous reviews or comments; treat
+    re-reviews as new, not relying on prior review state.
+  - **No skipping files** — examine every changed file regardless of type (`.md`, `.json`, `.yml`, `.toml`,
+    `.ts`, `.js`, `.py`, `.html`, `.css`, `.tsx`, `.vue`, `.sh`, etc.).
+  - **PR descriptions/commit messages/discussion are reference context only** — the review's conclusions must
+    be grounded in the actual code and file changes, inferring intent from the diff itself.
+  - **Independent verification** — don't assume an unchanged file or a previously reviewed section is safe;
+    verify code paths potentially affected by the current changes.
+
+## Minimal fallback (only if this surface can't reliably follow the link above)
+
+ScriptCat is a Manifest V3 browser extension (TypeScript + React 19 + Rspack, pnpm) that runs
+Tampermonkey-compatible userscripts across five isolated contexts — Service Worker, Content, Inject, Offscreen,
+Sandbox — communicating over `packages/message`. If you cannot load `AGENTS.md`, treat any architecture,
+persistence-pattern, or service-shape claim you're tempted to state here as unverified, and prefer asking the
+reviewer to confirm against `AGENTS.md` / `docs/architecture.md` over inventing a summary — this file is not
+the source of truth for those facts and must not re-accumulate a parallel copy of them.
diff --git a/AGENTS.md b/AGENTS.md
index 07b98949b..17091d115 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,10 +25,12 @@ This file provides guidance to AI coding agents (Claude Code, etc.) when working
 > (`src/locales/<locale>/*.json` namespace files, per-language docs, UI copy, or test snapshots), you must first
 > read that guide and follow the matching `docs/references/terminology-<locale>.md` if it exists.
 
-> **Before adding, editing, reorganizing, or reviewing any contributor doc (this file or `docs/*`), read
+> **Before adding, editing, reorganizing, or reviewing any tracked agent/contributor Markdown — this file,
+> `docs/*`, `.github/*.md`, package-local READMEs, and source-local READMEs — read
 > [`docs/DOC-MAINTENANCE.md`](docs/DOC-MAINTENANCE.md)** — keep the doc set organized (links resolve, index
-> current, no duplication) and every claim factually true against the current branch (*if you can't grep it on
-> this branch, don't claim it*).
+> current, no duplication, no cross-document policy conflicts) and every claim factually true against the current
+> branch (*if you can't grep it on this branch, don't claim it*). That guide owns the full checklist; don't copy
+> it into this always-loaded file.
 
 > **Before opening or updating a pull request, read [`docs/pull-request.md`](docs/pull-request.md)** — this
 > repo's PR description structure and evidence rules.
@@ -53,9 +55,9 @@ isn't universal, that's called out in the item itself.
 - **Fix root causes, not symptoms — refactor over patch.** No `as any` / `// @ts-ignore` / try-catch swallow / defensive skips to make errors disappear (宁愿重构也不要打补丁). If a test fails, fix the code, not the test — the narrow exceptions (a wrong test contract; a test that never carried value) are in [`docs/references/develop-testing.md`](docs/references/develop-testing.md#writing-meaningful-tests-what-to-clean-up--not-write).
 - **Confirm before you fix.** Before touching a reported bug, reproduce it and confirm it actually exists — never fix from assumption. Capture the reproduction, then fix, **in that order** (确定 bug 存在 → 写测试或记录验证证据 → 修复); how to reproduce and what counts as capture are in [`docs/verification.md`](docs/verification.md) and the TDD entry below.
 - **TDD/BDD first, for changes that alter observable behavior.** Write failing tests **before** implementing new or changed behavior, using BDD-style Chinese `describe`/`it` titles. Two narrow exceptions — neither a blanket file/task category — are in [`docs/references/develop-testing.md`](docs/references/develop-testing.md#when-tdd-doesnt-apply). (Runner, mocks, and how to run tests are in `docs/develop.md`.)
-- **SOLID, high cohesion & low coupling — applied to the existing extension points.** `Repo<T>` for new entities, `Group.on(...)` for new messages. Inject `Group` / `IMessageQueue` / DAOs via constructor; don't `new` them inside methods. Depend on narrow interfaces (`IMessageQueue`, not `MessageQueue`).
+- **SOLID, high cohesion & low coupling — applied to the existing extension points.** Persistence is a small backend taxonomy (`Repo<T>` / `DAO<T>` / `OPFSRepo` / a few custom repos), not one pattern to default to — pick by matching an existing entity with the same needs; see [`docs/references/architecture-data.md`](docs/references/architecture-data.md#adding-an-entity). For messages, use `Group.on(...)`. Not every service takes the same constructor shape — context services vs. the Agent subsystem differ; see [`docs/references/architecture-services.md`](docs/references/architecture-services.md#adding-a-service). Depend on narrow interfaces (`IMessageQueue`, not `MessageQueue`).
 - **Direct replacement over adapter sandwiches.** When swapping a backend/library, replace in place — no `interface Foo + LegacyImpl + NewImpl` unless both must coexist at runtime.
-- **Scope discipline — stay in your lane.** Bug fix ≠ cleanup PR. Touch only the files the task requires; leave unrelated files untouched (不要动和任务不相干的文件). Don't add helpers, abstractions, validation, or backwards-compat shims you don't need today. Three similar lines beats a premature abstraction.
+- **Scope discipline — stay in your lane.** Bug fix ≠ cleanup PR. Touch only the files the task requires; leave unrelated files untouched (不要动和任务不相干的文件). Don't add helpers, abstractions, validation, or backwards-compat shims you don't need today. Three similar lines beats a premature abstraction. Don't remove or narrow currently supported behavior just to simplify a fix — only do so when the task or an already-verified contract explicitly calls for that change.
 - **No dead code or `// removed` markers** — git remembers. Delete unused code outright.
 - **Comments explain "why", not "what".** Do not use ephemeral review labels such as `finding N` or review-round identifiers in comments or test names. Permanent issue or PR references are allowed when useful, but must supplement—not replace—the explanation. Do not restate code, duplicate enclosing documentation, or leave stale comments after code changes. See [`docs/develop.md`](docs/develop.md#comment-discipline) for the full policy.
 
@@ -93,9 +95,10 @@ Execution paths: page scripts → `chrome.userScripts`; background → SW → Of
 `ExtensionMessage` (chrome.runtime — SW ↔ Content / Inject / Offscreen), `WindowMessage` (postMessage — Offscreen ↔ Sandbox), `ServiceWorkerMessageSend` (`clients.matchAll()` + `postMessage` — SW → Offscreen on Chrome), `CustomEventMessage` (CustomEvent — Content ↔ Inject), `MessageQueue` (cross-context broadcast).
 
 ### Service & Data Layers
-- Services in `src/app/service/<context>/` — split by execution context. Constructor-injected `Group`, `IMessageQueue`, DAOs.
-- DAOs in `src/app/repo/` extend `Repo<T>` (chrome.storage + cache): `ScriptDAO`, `ValueDAO`, `ResourceDAO`, `PermissionDAO`, `SubscribeDAO`.
-- **GM API** split across content / SW / offscreen, each a `GMApi` (content built on `GM_Base`; SW — permission verify, cross-origin; offscreen — DOM-dependent background-script APIs); values via `ValueService`.
+- Services live under `src/app/service/` as **context services** (`content/`, `offscreen/`, `sandbox/`, `service_worker/`) plus **cross-cutting subsystems** (`agent/`, `extension/`, `queue.ts`) — not one uniform shape. Details, inventory, "adding a service": [`docs/references/architecture-services.md`](docs/references/architecture-services.md).
+- Persistence is a backend taxonomy (`Repo<T>` / `DAO<T>` / `OPFSRepo` / custom), not one pattern. Details, inventory, "adding an entity": [`docs/references/architecture-data.md`](docs/references/architecture-data.md).
+- **GM API** split across content / SW / offscreen, each a `GMApi`; values via `ValueService`. Adding a new GM API: [`docs/references/architecture-gm-api.md`](docs/references/architecture-gm-api.md).
+- **Agent subsystem** (`src/app/service/agent/`) is an AI-agent layer spanning the existing five contexts, not a sixth. Full write-up: [`docs/references/architecture-agent.md`](docs/references/architecture-agent.md).
 
 ### Browser Extension APIs (MV3)
 `chrome.userScripts` (page injection), Offscreen API (DOM in background), Declarative Net Request (intercepts `.user.js` URLs to trigger install flow).
diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md
index 990b64a11..88c39fa4d 100644
--- a/docs/DOC-MAINTENANCE.md
+++ b/docs/DOC-MAINTENANCE.md
@@ -1,12 +1,16 @@
 # Documentation Maintenance & Fact-Check Guide
 
-> **Read this before adding, editing, reorganizing, or reviewing any contributor doc** (`AGENTS.md`,
-> `docs/*`). It has two jobs: keep the doc set **organized** (links resolve, index current, no duplication)
-> and keep every claim **factually true against the current branch**.
+> **Read this before adding, editing, reorganizing, or reviewing any tracked agent/contributor Markdown** —
+> `AGENTS.md`, everything under `docs/*`, `.github/*.md`, and every package-local or source-local `README.md`.
+> Don't work off a fixed file list: run `git ls-files '*.md'` to discover the current set, including hidden
+> `.github` docs and READMEs that live next to source (e.g. `src/locales/README.md`,
+> `packages/*/README.md`). This guide has three jobs: keep the doc set **organized** (links resolve, index
+> current, no duplication), keep every claim **factually true against the current branch**, and keep
+> **cross-document policy consistent** (no two docs giving conflicting rules for the same situation).
 
 ## Why this exists
 
-The contributor docs describe a living codebase, so two failure modes recur:
+The contributor docs describe a living codebase, so several failure modes recur:
 
 - **Stale facts** — a class is renamed, a count changes, a file moves; the doc keeps the old value. Real
   examples caught in review: docs named the offscreen GM API `OffscreenGMApi` (no such class — it is `GMApi`),
@@ -14,6 +18,12 @@ The contributor docs describe a living codebase, so two failure modes recur:
 - **Branch leakage** — work that only lives on a feature branch gets documented as if it ships on `main`.
   Example: a subsystem committed only on a feature branch (not on `main`) gets written into `main`'s
   quick-map, misleading readers into expecting code that is not there.
+- **Policy conflict** — two docs state the same rule with different conditions (e.g. one says a TDD failing
+  test is unconditional, another defines an exception for it). An agent that reads only one of them then
+  follows a rule the other doc already narrowed or overturned.
+- **Stale-after-resolution** — code and docs change in the same PR, or a conflict gets resolved during rebase,
+  and the fact-check was only ever run against an old `HEAD`. The claim looks verified but was never checked
+  against the tree that actually ships.
 
 **Rule of thumb: if you can't `git grep` it in the committed code on this branch, don't claim it.** Verify with
 git-aware commands (`git grep`, `git ls-files`, `git ls-tree`) — never a plain `rg`/`ls`, which also match
@@ -21,6 +31,59 @@ git-aware commands (`git grep`, `git ls-files`, `git ls-tree`) — never a plain
 `main` will masquerade as shipped (this is exactly how a feature-branch-only subsystem sneaks into a `main` doc).
 Aspirational / feature-branch content belongs in that branch's docs, or is clearly marked as planned.
 
+## Baseline tree, working diff, proposed final tree
+
+A fact-check against a single snapshot isn't enough when code and docs change together:
+
+- **Baseline tree** — the committed state you started from (`git rev-parse HEAD`).
+- **Working diff** — your uncommitted changes, both code and docs, on top of the baseline.
+- **Proposed final tree** — what will actually exist after your change lands, including any rebase or
+  conflict resolution.
+
+If code and docs are changing in the same PR, checking only the old `HEAD` misses facts the working diff is
+about to introduce or remove. After a rebase, merge, or conflict resolution, re-run the fact-check against the
+**resolved final tree**, not your last pre-conflict result — conflict resolution can silently reintroduce a
+stale fact or drop a doc update.
+
+## Policy-consistency check
+
+Beyond individual facts, check that a rule stated in one doc doesn't contradict the same rule stated
+elsewhere. For every rule you touch or that a fact-check reveals, identify: **owner** (which doc holds the
+canonical version), **trigger** (when it applies), **action** (what to do), **exception** (documented
+carve-outs), **fallback** (what to do when the exception applies), **evidence** (how compliance is checked),
+**stop condition** (when the rule no longer applies). Search for absolute language that tends to hide an
+undocumented exception or a stale blanket rule:
+
+```bash
+git grep -n -Ei 'always|never|all |must|必须|绝不|所有' -- AGENTS.md .github/*.md docs/*.md docs/references/*.md
+git grep -n -Ei 'TDD|failing test|committed test|fix the code|自动化.*不可' -- '*.md'
+```
+
+Every hit is a review-queue entry, not an automatic rewrite — confirm whether the absolute wording is actually
+correct (some are intentional non-negotiables) before loosening it, and confirm a downstream doc's exception
+survives when you touch the upstream rule it narrows.
+
+## Lint / config documentation depth
+
+When a doc describes an ESLint rule, tsconfig setting, or similar config-driven behavior, record the
+**files/ignores/overrides that produce the effective result**, not just the rule name — a rule can be globally
+`"error"` and then `"off"` for a specific file glob, and only listing the rule name hides that. Verify against
+`eslint.config.mjs` (or the relevant config file) directly; don't infer scope from the rule name alone.
+
+## Batch edits: verify small, then scale
+
+For a mechanical, repeatable change across many files (heading rename, link format, boilerplate insert),
+validate the change on one representative file or a small batch first and check the diff before scaling up.
+This is advice for genuinely mechanical batch tooling — it is not a mandatory process for every small,
+one-off edit.
+
+## Privacy / sanitization gate
+
+Before committing or opening a PR, check the final diff and PR body for local absolute paths, home-directory
+shortcuts, `file://` URIs, temp-directory paths, private attachment names, and other identifying information
+that shouldn't leave the contributor's machine. This check needs human judgment — this guide's own examples
+of sanitization patterns can otherwise look like matches — so don't rely on a blind automated strip.
+
 ## Doc set & responsibilities (don't duplicate — cross-link)
 
 | Doc | Owns |
@@ -30,14 +93,17 @@ Aspirational / feature-branch content belongs in that branch's docs, or is clear
 | [`pull-request.md`](./pull-request.md) | Detailed PR description structure and guidance for agents and contributors; the human-facing template remains lightweight. |
 | [`design.md`](./design.md) | The design system: theme mechanism, shadcn component selection, new-page recipe; tokens split to [`references/design-tokens.md`](./references/design-tokens.md), component palette to [`references/design-components.md`](./references/design-components.md), layout/motion/state/a11y patterns to [`references/design-patterns.md`](./references/design-patterns.md). |
 | [`verification.md`](./verification.md) | Lightweight end-to-end functional verification — throwaway scratch scripts driving the real built extension; report template split to [`references/verification-report-template.md`](./references/verification-report-template.md), debugging FAQ to [`references/verification-debugging.md`](./references/verification-debugging.md). |
-| [`architecture.md`](./architecture.md) | Deep internals: process model, message passing; subsystem deep-dives split to [`references/architecture-services.md`](./references/architecture-services.md), [`references/architecture-data.md`](./references/architecture-data.md), [`references/architecture-gm-api.md`](./references/architecture-gm-api.md), [`references/architecture-execution.md`](./references/architecture-execution.md), [`references/architecture-build.md`](./references/architecture-build.md). |
+| [`architecture.md`](./architecture.md) | Deep internals: process model, message passing; subsystem deep-dives split to [`references/architecture-services.md`](./references/architecture-services.md), [`references/architecture-data.md`](./references/architecture-data.md), [`references/architecture-gm-api.md`](./references/architecture-gm-api.md), [`references/architecture-execution.md`](./references/architecture-execution.md), [`references/architecture-build.md`](./references/architecture-build.md), [`references/architecture-agent.md`](./references/architecture-agent.md). |
 | [`cloud-sync.md`](./cloud-sync.md) | Cloud sync internals: sync files, digest/status semantics, provider differences, error classification, retry policy. |
 | [`translation.md`](./translation.md) | Translation / localization single source of truth. |
-| [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: doc-set organization rules + fact-check / anti-drift discipline. |
+| [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | This guide: doc-set organization rules, fact-check / anti-drift discipline, and policy-consistency checks — for every tracked agent/contributor Markdown file, not just `AGENTS.md` + `docs/*`. |
 | [`README.md`](./README.md) | The index that points to all of the above. |
+| `.github/copilot-instructions.md` | Copilot-specific entry point and any genuine tool-specific differences; shared facts (architecture, commands, testing, design, translation, PR mechanics) route to the owning doc above instead of being copied. |
+| Package-local `README.md` (e.g. `packages/message/README.md`, `packages/filesystem/README.md`) | That package's purpose, boundaries, entry points, and local gotchas — not a duplicate of repo-wide architecture or coding policy. |
 
 When you move a fact, move it to the doc that **owns** it and cross-link — never copy the same fact into two
-places, or they drift apart.
+places, or they drift apart. To discover the current full set instead of relying on this table alone, run
+`git ls-files '*.md'`.
 
 ## Checklist 1 — Organization (every doc change)
 
@@ -97,22 +163,44 @@ echo "== eslint (project rule in eslint-rules/ vs userscript config in packages/
 git ls-files eslint-rules/; git grep -l "require-last-error-check" -- eslint.config.mjs; git ls-files packages/eslint/linter-config.ts
 ```
 
-Link integrity — confirm every relative markdown link in the core docs resolves:
+Link integrity — confirm every relative markdown link resolves, across **every tracked Markdown file**
+(`git ls-files '*.md'`), not a fixed list that silently misses new files (`.github/*.md`, package/source
+READMEs, a newly added `docs/references/*.md`):
 
 ```bash
-for doc in AGENTS.md docs/README.md docs/DOC-MAINTENANCE.md docs/develop.md docs/references/develop-testing.md docs/pull-request.md docs/design.md docs/references/design-tokens.md docs/references/design-components.md docs/references/design-patterns.md docs/architecture.md docs/references/architecture-services.md docs/references/architecture-data.md docs/references/architecture-gm-api.md docs/references/architecture-execution.md docs/references/architecture-build.md docs/verification.md docs/references/verification-debugging.md docs/references/verification-report-template.md docs/cloud-sync.md docs/translation.md; do
-  # the sed pipeline drops fenced code blocks and inline code spans first, so illustrative sample
-  # links inside ```md snippets or `single-backtick` text (e.g. references/verification-report-template.md's
-  # screenshot/resource examples, verification.md's "Evidence location" spans) aren't false-flagged as broken
-  sed '/^```/,/^```/d' "$doc" | sed -E 's/`[^`]*`//g' | grep -oE '\]\(([^)]+)\)' | sed -E 's/^\]\(|\)$//g' | grep -vE '^https?:|^#' | while read -r link; do
+git ls-files '*.md' | while IFS= read -r doc; do
+  # the sed pipeline drops fenced code blocks (``` and ~~~) and inline code spans first, so illustrative
+  # sample links inside ```md/~~~md snippets or `single-backtick` text (e.g.
+  # references/verification-report-template.md's screenshot/resource examples, verification.md's
+  # "Evidence location" spans) aren't false-flagged as broken
+  sed '/^```/,/^```/d; /^~~~/,/^~~~/d' "$doc" | sed -E 's/`[^`]*`//g' | grep -oE '\]\(([^)]+)\)' | sed -E 's/^\]\(|\)$//g' | grep -vE '^(https?:|mailto:|#|app:)' | while IFS= read -r link; do
     target="$(dirname "$doc")/${link%%#*}"
     [ -e "$target" ] && echo "ok     $doc → $link" || echo "BROKEN $doc → $link"
   done
 done
 ```
 
+Link integrity is a **best-effort signal**, not a proof of correctness: the shell pipeline above skips fenced
+and inline code, but it doesn't resolve reference-style links, complex Markdown link destinations, or GitHub's
+full heading-anchor slug rules. A clean run means no missing link *targets* were found — it does not mean every
+anchor fragment or every link's intent has been verified. Check changed fragment links by hand (or by rendering
+the page), especially around CJK text, punctuation, and duplicate-heading auto-suffixes (`#foo-1`). Only add an
+anchor when the link text explicitly points at one particular section; a link meant to reference the whole
+document should stay a file-level link without a fragment.
+
+Duplicate headings (exact or near-duplicate H1/H2 text across files) are a **review queue item, not an
+auto-fix**: check inbound links and whether the duplication is actually confusing before renaming or merging
+a heading — an external deep link into that heading breaks if you rename it without a compatibility anchor.
+
 ## When you find a discrepancy
 
 Fix the **doc** to match the code — the code on this branch is the source of truth. The exception: if the code
 itself is wrong (a real bug), fix the code and say so in the PR. Either way, never silently drop a check you
 couldn't satisfy — surface it in the PR description so a reviewer can confirm.
+
+## Honest completion claims
+
+Only say "full scan", "verified", or "all fixed" when the scope and evidence actually cover that claim — i.e.
+you ran the check against every file the claim implies, on the proposed final tree. A more accurate summary is
+usually narrower: which docs got a fact/policy audit and what evidence backs it, versus which docs (e.g.
+localized/user-facing/security docs) only got a structural check or were intentionally left unchanged.
diff --git a/docs/README.md b/docs/README.md
index f44bf3e58..13fc84aa4 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -6,21 +6,21 @@
 
 | 文档 | 说明 |
 | --- | --- |
-| [`../AGENTS.md`](../AGENTS.md) | 工程原则、架构速览、AI/贡献者约定的单一信息源(`CLAUDE.md` 仅导入它)。 |
+| [`../AGENTS.md`](../AGENTS.md) | 工程原则、架构速览、AI/贡献者约定的单一信息源 —— 但仅相对 `CLAUDE.md`(其仅导入它)成立;`.github/copilot-instructions.md` 是 Copilot 的独立入口,与本文件共享的事实需在两边都改动时做一致性核对(parity review)。 |
 | [`develop.md`](./develop.md) | 开发规范:命令、目录结构、编码风格、UI/主题、i18n、提交/PR 流程;测试机制(含 Vitest 性能)拆到 [`references/develop-testing.md`](./references/develop-testing.md)。**写代码前先读。** |
 | [`pull-request.md`](./pull-request.md) | PR 描述指南:代理与贡献者使用的详细章节、按变更类型取舍规则、验证与审查信息要求。 |
 | [`design.md`](./design.md) | 设计系统参考:主题机制、shadcn 组件选型、新建页面配方总览;令牌完整值拆到 [`references/design-tokens.md`](./references/design-tokens.md),组件清单拆到 [`references/design-components.md`](./references/design-components.md),布局/响应式/动效/状态/无障碍范式拆到 [`references/design-patterns.md`](./references/design-patterns.md)。**做页面/对话框/区块前先读。** |
 | [`verification.md`](./verification.md) | 功能验证指南:用一次性 scratch 脚本驱动真实扩展做端到端验证(不跑全量 E2E、不加永久用例);报告模板拆到 [`references/verification-report-template.md`](./references/verification-report-template.md),调试 FAQ 拆到 [`references/verification-debugging.md`](./references/verification-debugging.md)。**验证改动是否真正跑通时读。** |
-| [`architecture.md`](./architecture.md) | 内部原理总览:多进程模型、消息传递;各子系统深入拆到 [`references/architecture-services.md`](./references/architecture-services.md)(服务层)、[`references/architecture-data.md`](./references/architecture-data.md)(数据层)、[`references/architecture-gm-api.md`](./references/architecture-gm-api.md)(GM API)、[`references/architecture-execution.md`](./references/architecture-execution.md)(脚本执行)、[`references/architecture-build.md`](./references/architecture-build.md)(构建管线)。 |
+| [`architecture.md`](./architecture.md) | 内部原理总览:多进程模型、消息传递;各子系统深入拆到 [`references/architecture-services.md`](./references/architecture-services.md)(服务层)、[`references/architecture-data.md`](./references/architecture-data.md)(数据层)、[`references/architecture-gm-api.md`](./references/architecture-gm-api.md)(GM API)、[`references/architecture-execution.md`](./references/architecture-execution.md)(脚本执行)、[`references/architecture-build.md`](./references/architecture-build.md)(构建管线)、[`references/architecture-agent.md`](./references/architecture-agent.md)(Agent 子系统)。 |
 | [`cloud-sync.md`](./cloud-sync.md) | 云同步实现说明:同步文件语义、主流程、状态合并、provider 差异、错误分类、retry 策略和维护注意事项。 |
-| [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | 文档维护与事实核对指南:组织规则、逐条核对清单、一键校验脚本。**改/审文档前先读。** |
+| [`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md) | 文档维护与事实核对指南:组织规则、逐条核对清单、跨文档政策一致性核对、隐私清理、以及在 resolved final tree 上的复核方法,覆盖全部 tracked 的 agent/contributor Markdown(不止 `AGENTS.md` + `docs/*`,还包括 `.github/*.md`、package-local README)。**改/审文档前先读。** |
 
 ## 翻译 / Translation
 
 | 文档 | 说明 |
 | --- | --- |
 | [`translation.md`](./translation.md) | 翻译 / 本地化指南(单一信息源):术语与修改规则、工作流、提取翻译提示词。**翻译前先读。** |
-| [`translation.md` 术语规范表](./translation.md#各语言术语规范--per-locale-terminology) | 10 个语言地区的术语与界面文案规范 `terminology-<locale>.md`(en-US / zh-CN / zh-TW / ja-JP / ru-RU / de-DE / vi-VN / tr-TR / pt-BR / ko-KR)。 |
+| [`translation.md` 术语规范表](./translation.md#各语言术语规范--per-locale-terminology) | 当前 locale 清单与对应 `terminology-<locale>.md` 的 canonical table —— 数量与列表以该表为准,本索引不重复维护一份固定副本。 |
 
 ## 贡献指南 / Contributing
 
diff --git a/docs/architecture.md b/docs/architecture.md
index cbe6f5f7a..6edb0f766 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -16,10 +16,11 @@
 - [The Five Contexts (Process Model)](#the-five-contexts-process-model)
 - [Message Passing](#message-passing)
 - [Service layer](./references/architecture-services.md)
-- [Data layer (Repo<T> + DAOs)](./references/architecture-data.md)
+- [Data layer (backend taxonomy: Repo\<T\> / DAO\<T\> / OPFSRepo)](./references/architecture-data.md)
 - [GM API system](./references/architecture-gm-api.md)
 - [Script execution](./references/architecture-execution.md)
 - [Build pipeline & manifest](./references/architecture-build.md)
+- [Agent subsystem](./references/architecture-agent.md)
 - [Extending ScriptCat — Recipes](#extending-scriptcat--recipes)
 - [Testing the Internals](#testing-the-internals)
 
@@ -39,9 +40,13 @@ Three ideas explain almost everything in the codebase:
 - **One message layer, several transports.** [`packages/message`](../packages/message) abstracts
   `chrome.runtime`, `postMessage`, and DOM `CustomEvent` behind a single RPC + pub/sub API, so services are
   written against interfaces (`Server`/`Group`/`Client`/`IMessageQueue`), not raw browser APIs.
-- **Services are constructor-injected.** Domain logic lives in services that receive their `Group`,
-  `IMessageQueue`, and DAOs through the constructor and register message handlers in an `init()` method. This
-  is what makes the system testable with the mock message bus.
+- **Domain logic lives in services, wired explicitly.** Shared collaborators (a `Group`, `IMessageQueue`,
+  another service, a DAO owned elsewhere) typically come in through the constructor; message handlers and
+  subscriptions are registered through an explicit lifecycle method — commonly `init()`, though content and
+  Agent code have their own equivalents. The exact dependency set and lifecycle shape vary by service and
+  context — see [service layer](./references/architecture-services.md) for the real variance and the
+  exceptions, rather than assuming one uniform constructor/`init()` template. This explicit-wiring style is
+  what makes the system testable with the mock message bus.
 
 ```
                                 ┌───────────────────────────────────────────────┐
@@ -68,7 +73,9 @@ Three ideas explain almost everything in the codebase:
                           │  Server("inject")     │         │  Server("sandbox")        │
                           └──────────────────────┘         └──────────────────────────┘
 
-         MessageQueue (pub/sub) broadcasts state changes across ALL contexts.
+         MessageQueue (pub/sub) broadcasts state changes among the contexts that instantiate it — currently
+         Service Worker, Offscreen, and UI pages (see architecture-services.md for the exact list); content,
+         inject, and sandbox don't hold a MessageQueue instance.
 ```
 
 ---
@@ -139,7 +146,7 @@ communication styles** over **several transports**.
 | `CustomEventMessage` | [`custom_event_message.ts`](../packages/message/custom_event_message.ts) | Content ↔ Inject | DOM `CustomEvent` dispatch (bypasses page tampering) |
 | `WindowMessage` | [`window_message.ts`](../packages/message/window_message.ts) | Offscreen ↔ Sandbox | `window.postMessage` |
 | `ServiceWorkerMessageSend` | [`window_message.ts`](../packages/message/window_message.ts) | SW → Offscreen (Chrome) | `clients.matchAll()` + `postMessage` |
-| `MessageQueue` | [`message_queue.ts`](../packages/message/message_queue.ts) | All contexts (broadcast) | `chrome.runtime.sendMessage` + local `EventEmitter3` |
+| `MessageQueue` | [`message_queue.ts`](../packages/message/message_queue.ts) | Broadcast among the contexts that instantiate it — SW, Offscreen, UI pages | `chrome.runtime.sendMessage` + local `EventEmitter3` |
 | `MockMessage` | [`mock_message.ts`](../packages/message/mock_message.ts) | Tests | in-memory `EventEmitter3` |
 
 All transports implement the small `Message` / `MessageSend` / `MessageConnect` interfaces in
@@ -204,6 +211,22 @@ mock ([`@Packages/chrome-extension-mock`](../packages/chrome-extension-mock)) is
 
 ---
 
+## Agent Subsystem
+
+The Agent subsystem (`src/app/service/agent/`) is an AI-agent layer built **on top of** the five contexts
+above — it is not a sixth execution context. `AgentService` is assembled inside `ServiceWorkerManager`
+(`src/app/service/service_worker/index.ts`) from a set of narrower services (chat, task, skill, model, MCP,
+background session, sub-agent, compact, DOM automation, OPFS); a content-side `CAT.agent.*` API
+(`src/app/service/content/gm_api/cat_agent.ts`) exposes conversations to user scripts; offscreen and sandbox
+are used for skill-script execution the same way regular background/scheduled scripts are. The UI (chat/task
+pages) and userscript-driven conversations share the same streaming/tool-loop boundary in
+`core/tool_registry.ts` / `service_worker/tool_loop_orchestrator.ts` — there is one tool loop, not a separate
+implementation per caller. Full write-up, including the global vs. per-session tool registries, LLM
+streaming/retry/compact flow, background-session/sub-agent/scheduled-task lifecycle, storage backend choices,
+and the page/offscreen/sandbox delegation boundaries: [`references/architecture-agent.md`](./references/architecture-agent.md).
+
+---
+
 ## Extending ScriptCat — Recipes
 
 Map a change onto the existing extension points instead of inventing new structure:
@@ -212,10 +235,21 @@ Map a change onto the existing extension points instead of inventing new structu
   its `init()`, and call it from the other context with a `Client`. No new transport, no new wiring.
 - **A new broadcast event.** `this.mq.publish("myTopic", payload)` where state changes; `this.mq.subscribe(...)`
   wherever it matters. Use this, not RPC, for "X changed" notifications.
-- **A new persisted entity.** Subclass `Repo<T>` (see [data layer](./references/architecture-data.md#adding-an-entity-is-tiny)),
-  construct it in the manager, expose ops via `group.on`.
-- **A new service.** Constructor-inject `Group` + `IMessageQueue` + DAOs; register handlers in `init()`;
-  instantiate it in the relevant manager with its own `group("name")` (see [service layer](./references/architecture-services.md)).
+- **A new persisted entity.** Pick a backend by matching an existing entity with the same data-size/query/lifecycle
+  needs — `Repo<T>`, `DAO<T>`, or `OPFSRepo` (see [data layer](./references/architecture-data.md#adding-an-entity))
+  — then copy the nearest entity of that *same backend, in the same subsystem* for ownership and construction:
+  they don't all follow "construct in the manager, expose via `group.on`." Some context-service `Repo<T>`
+  entities do (e.g. `scriptDAO` built in `ServiceWorkerManager` and exposed through RPC); some Agent entities
+  don't — `AgentModelService` constructs its own `AgentModelRepo` internally by default rather than taking one
+  from a manager, and `AgentChatRepo` is a module-level singleton (`export const agentChatRepo = ...`) imported
+  directly rather than manager-constructed or exposed via `group.on`. Only route through the manager +
+  `group.on` when the entity is genuinely owned by a context composition root and needs to be reachable over
+  RPC.
+- **A new service.** First decide what kind: a context service (owned by one of `content/`, `offscreen/`,
+  `sandbox/`, `service_worker/`), an Agent/core component, or another cross-cutting subsystem — these do
+  **not** share one constructor shape. Then copy the nearest existing service of that kind. See
+  [service layer § Adding a service](./references/architecture-services.md#adding-a-service) for the decision
+  path; don't default to a `Group` + `IMessageQueue` + DAOs constructor for everything.
 - **A new GM API.** Decorate the method with `@GMContext.API` on the content side, add a privileged/offscreen
   handler if needed, register the `@grant` (see [GM API system](./references/architecture-gm-api.md#adding-a-gm-api-sketch)).
 
@@ -228,14 +262,24 @@ premature abstraction.
 ## Testing the Internals
 
 - **Unit (Vitest + happy-dom).** Co-locate `*.test.ts` next to source. `chrome.*` is mocked via
-  [`@Packages/chrome-extension-mock`](../packages/chrome-extension-mock) (`tests/vitest.setup.ts`); message-bus
-  behavior uses `MockMessage`. Run one file: `pnpm test -- --run path/to/file.test.ts`.
-- **TDD first.** Write the failing test before the implementation. When a test fails, fix the code — don't edit
-  the test to pass.
+  [`@Packages/chrome-extension-mock`](../packages/chrome-extension-mock) (`tests/vitest.setup.ts`). For the
+  message layer, keep the two pieces separate: `MockMessage` fakes the `Message` **transport** for `Server`/
+  `Group` RPC tests (`new Server("test", new MockMessage(...))`); a service's `IMessageQueue` dependency is
+  tested with a real `MessageQueue` instance (`new MessageQueue()`, with individual methods like `publish`
+  swapped for a spy when a test needs to assert on it) or a narrow fake written against `IMessageQueue` — not
+  `MockMessage`, which solves a different problem (see
+  [architecture-services.md](./references/architecture-services.md) for the detailed distinction). Run one
+  file: `pnpm test -- --run path/to/file.test.ts`.
+- **TDD.** See [AGENTS.md § Engineering Principles](../AGENTS.md#engineering-principles) for the write-failing-
+  test-first principle and [develop-testing.md § When TDD doesn't apply](./references/develop-testing.md#when-tdd-doesnt-apply)
+  for the narrow exceptions — this section only covers architecture-specific test mechanics, not the policy
+  itself.
 - **E2E (Playwright).** `e2e/*.spec.ts`, one worker, real Chromium. `pnpm run test:e2e` (first run:
   `pnpm run test:e2e:install`).
 - **Before a PR:** lint + the relevant suite — owned by [references/develop-testing.md](./references/develop-testing.md) → *Testing*.
 
-The DI + interface design is what makes this tractable: because services receive `IMessageQueue` and DAOs by
-constructor, a test builds a service with `MockMessage` and an in-memory DAO and exercises handlers directly,
-with no browser.
+The DI + interface design is what makes this tractable: because many services take `IMessageQueue`/DAOs
+through the constructor (dependency set varies — see [architecture-services.md](./references/architecture-services.md)),
+a test builds a service with a real `MessageQueue` (or a narrow fake) and an in-memory DAO and exercises
+handlers directly, with no browser. `MockMessage` is for the separate case of testing `Server`/`Group` RPC
+routing, not for standing in as a service's `IMessageQueue`.
diff --git a/docs/design.md b/docs/design.md
index c293ceb52..6fe767093 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -10,7 +10,7 @@
 
 | Owned here | Owned elsewhere |
 | --- | --- |
-| Color-token values, semantics, usage → [`tokens.md`](./references/design-tokens.md) | The hard rules that mandate them (no hard-coded colors, hover via pseudo-classes, `cn()` / CVA / `lucide`) → [`DEVELOP.md` UI section](./develop.md) |
+| Color-token values, semantics, usage → [`tokens.md`](./references/design-tokens.md) | The hard rules that mandate them (no hard-coded colors, hover via pseudo-classes, `cn()` / CVA / `lucide`) → [`DEVELOP.md` UI section](./develop.md#ui) |
 | Theming mechanism, `dark:` usage | Commands, structure, coding style, testing, i18n, commit/PR → [`DEVELOP.md`](./develop.md) |
 | Component palette, variants, selection guidance → [`components.md`](./references/design-components.md) | Process model, message passing, service layers, internals → [`ARCHITECTURE.md`](./architecture.md) |
 | Layout shell, responsive patterns, **layering (z-index)**, motion, state patterns, **accessibility** → [`patterns.md`](./references/design-patterns.md); **elevation (shadows)** → [`tokens.md`](./references/design-tokens.md#elevation-shadows); page recipe (this doc) | — |
diff --git a/docs/develop.md b/docs/develop.md
index 6c1d257f8..f4eb30c2d 100644
--- a/docs/develop.md
+++ b/docs/develop.md
@@ -68,6 +68,17 @@ Two conventions are enforced via built-in rules in `eslint.config.mjs`: `no-rest
 the `radix-ui` pattern of `no-restricted-imports`, and `no-restricted-syntax` — not `require-last-error-check`,
 and not the `sonner` pattern of `no-restricted-imports`.
 
+`src/pages/components/ui/toast.ts` has an override that turns `no-restricted-imports` **entirely off** for that
+one file — not just the `sonner` half of it. Only the `sonner` exception is intentional: this is the one place
+in `src/pages/**` allowed to import `sonner`'s `toast` directly (it's the wrapper `notify` is built on). The
+file happens to also lose the `@radix-ui/react-*` restriction as a side effect of the rule being off wholesale
+— it does not currently import from `@radix-ui/react-*` (or `radix-ui`) at all, and the merged-package
+convention still applies to it in spirit; `eslint-rules/harness.test.mjs`'s Radix case only exercises
+`dialog.tsx`, so a Radix-restricted import landing in `toast.ts` would not be caught by lint today. Don't read
+this override as "Radix single-package imports are permitted here" — treat it as a lint gap this file
+currently doesn't exploit, and prefer narrowing the override to the `sonner` import specifically (or adding a
+`toast.ts` case to the harness) over relying on the blanket `off`. Any other file still gets both restrictions.
+
 Separately, type-aware rules run on `src/pages/**` (tests excluded) via `projectService` —
 `@typescript-eslint/no-floating-promises`, `no-misused-promises` (with `checksVoidReturn.attributes: false`, so
 `async` JSX handlers are allowed), and `await-thenable`, all `error` — to catch missing `await`s and promises
diff --git a/docs/pull-request.md b/docs/pull-request.md
index bac8c4953..3ef4475d7 100644
--- a/docs/pull-request.md
+++ b/docs/pull-request.md
@@ -1,6 +1,12 @@
 # Pull Request Description Guide
 
-This guide defines the detailed PR description format for agents and contributors. Start from the human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) — it intentionally remains lightweight. Preserve its `Checklist / 检查清单` section, and expand its `Description / 描述` section only when the change needs more context.
+This guide owns the **PR body**: structure, evidence, and reviewer-handoff expectations. It does not own
+commit message or PR title rules — those live in
+[develop.md § Commit & Pull Request Guidelines](./develop.md#commit--pull-request-guidelines) (gitmoji prefix,
+single-purpose commits). Start from the human-facing template at
+[`../.github/pull_request_template.md`](../.github/pull_request_template.md) — it intentionally remains
+lightweight. Preserve its `Checklist / 检查清单` section, and expand its `Description / 描述` section only when
+the change needs more context.
 
 Whatever headings you use, this guide's checklist and evidence expectations still apply — `## Summary` /
 `## Test plan` headings don't exempt a PR from them. Use the structure below; its sections are
@@ -64,3 +70,12 @@ For non-trivial changes, make the description useful for review:
 - `已知限制` records unsupported cases, explicit scope boundaries, and follow-up work.
 - `建议审查重点` lists concrete behaviors or risks reviewers should verify.
 - `验证` lists exact commands and concise results, including known warnings or why a check was not run.
+
+## Documentation-only PRs
+
+For a PR that only changes Markdown, `验证` should reflect what a doc change actually needs, not an unrelated
+full code test suite: a fact check against the final tree, a relative-link/actual-anchor check, a
+cross-document policy-consistency check, and a privacy/sanitization scan (see
+[`DOC-MAINTENANCE.md`](./DOC-MAINTENANCE.md)). Before writing "all fixed" or "fully verified," re-review your
+own final diff and any nearby location sharing the same root cause — but only claim the scope you actually
+scanned; don't imply full-repo coverage you didn't perform.
diff --git a/docs/references/architecture-agent.md b/docs/references/architecture-agent.md
new file mode 100644
index 000000000..3055d3ddb
--- /dev/null
+++ b/docs/references/architecture-agent.md
@@ -0,0 +1,158 @@
+# Agent Subsystem
+
+> Deep-dive companion to [`../architecture.md`](../architecture.md). The Agent subsystem is an AI-agent layer
+> that runs **on top of** the five existing runtime contexts (service worker, content, inject, offscreen,
+> sandbox) — it is not a sixth context. Its code lives under
+> [`src/app/service/agent/`](../../src/app/service/agent/), split into a context-agnostic `core/` and a
+> `service_worker/` composition layer, plus a content-side API surface and offscreen/sandbox delegation
+> described below.
+
+## Service-worker composition
+
+[`AgentService`](../../src/app/service/agent/service_worker/agent.ts) is constructed once in
+[`ServiceWorkerManager`](../../src/app/service/service_worker/index.ts) (`new AgentService(this.api.group("agent"),
+this.offscreenSend, resource)`) and composes the narrower services below rather than being one large class.
+Each sub-service takes only the dependencies it needs — not a single `Group`/`IMessageQueue`/DAO triple applied
+uniformly:
+
+| Service | File | Responsibility |
+| --- | --- | --- |
+| `ChatService` | `chat_service.ts` | Chat request lifecycle: builds the system prompt, wires a per-request `SessionToolRegistry`, delegates the tool loop to the orchestrator. |
+| `AgentTaskService` | `task_service.ts` | CRUD + scheduling for `AgentTask` (cron-like triggers), runs tasks through the same tool-loop orchestrator. |
+| `SkillService` | `skill_service.ts` | Skill install/update/list from `.md` or `.zip` sources (`parseSkillMd`/`parseSkillZip`), backed by `SkillRepo`. |
+| `AgentModelService` | `model_service.ts` | Model config CRUD and default/summary-model selection, backed by `AgentModelRepo`. |
+| `MCPService` | `mcp.ts` | Manages `MCPClient` connections per configured server and registers/unregisters their tools on the shared `ToolRegistry`. |
+| `BackgroundSessionManager` | `background_session_manager.ts` | Tracks running background conversations (streaming state, listeners, pending `ask_user` prompts) so a UI can reattach to an in-flight session. |
+| `SubAgentService` | `sub_agent_service.ts` | Runs a sub-agent conversation through the shared tool loop with a type-scoped tool exclusion list. |
+| `CompactService` | `compact_service.ts` | Summarizes/compacts long conversation history via a dedicated compact prompt. |
+| `AgentDomService` | `dom.ts` (+ `dom_cdp.ts` helpers) | Page automation — see below for the default-vs-trusted split. |
+| `AgentOPFSService` | `opfs_service.ts` | Serves `CAT.agent.opfs` requests from both content scripts (no Blob support) and offscreen (Blob support), dispatched on whether the caller has a `sender`. |
+
+(Class names verified via `git grep -n "export class" -- src/app/service/agent/service_worker/` — re-run that
+before relying on a name here, since these are exactly the kind of detail that drifts.)
+
+Message actions are namespaced under the `agent` group (`this.api.group("agent")`), the same RPC pattern
+`architecture.md` describes for other services — the difference here is internal composition, not the wiring
+into `Group`/`Server`.
+
+## Tool registries
+
+[`ToolRegistry`](../../src/app/service/agent/core/tool_registry.ts) is the **global** registry: tools it holds
+persist for the process lifetime and are classified by `ToolSource` — `builtin` (permanent, e.g.
+`web_fetch`/`web_search`/`opfs_*`/the tab tools such as `list_tabs`/`open_tab`), `mcp` (from an
+`MCPService`-managed server), `skill` (skill meta-tools: `load_skill`, `execute_skill_script`,
+`read_reference`), `session` (registered per conversation: task tools, `ask_user`, `agent`, `execute_script`),
+and `script` (user-script-supplied tools passed through `conv.chat`, dispatched via a callback rather than
+stored in the map).
+
+Tool names don't always match their source file — the sub-agent tool defined in `sub_agent.ts` registers as
+`agent`, and `tab_tools.ts` registers `get_tab_content`/`list_tabs`/`open_tab`/`close_tab`/`activate_tab` with
+no shared prefix. Read the `name:` field, not the filename.
+
+[`SessionToolRegistry`](../../src/app/service/agent/core/session_tool_registry.ts) wraps a read-only reference
+to the global `ToolRegistry` with its own per-session `Map`. This exists because registering a same-named
+builtin tool (task tools, `ask_user`, `agent`) directly on the global registry would let concurrent
+sessions clobber each other's closures — a session-scoped tool needs to stay bound to its own
+`conversationId`/`sendEvent`. `getDefinitions()` merges session tools over parent tools (session shadows
+parent); `execute()` builds the merged map and delegates to `parent.executeTools()` so shared behavior (e.g.
+attachment persistence) isn't duplicated. A session's tools are reclaimed by garbage collection when the
+session ends — no explicit `unregister` loop is required.
+
+## LLM call: streaming, retry, compact, tool loop
+
+[`ToolLoopOrchestrator`](../../src/app/service/agent/service_worker/tool_loop_orchestrator.ts) drives one
+conversation turn: call the model, execute any tool calls the model requested, feed results back, and repeat
+until the model stops calling tools or `maxIterations` is hit. It depends on injected `callLLM` and
+`autoCompact` functions (rather than importing a concrete client) so tests can substitute spies.
+[`retry_utils.ts`](../../src/app/service/agent/service_worker/retry_utils.ts)'s `isRetryableError` matches an
+error message containing `429`, a `5xx` code, or a network-ish signal (`network`/`fetch`/`ECONNRESET`), then
+excludes it if the message also matches `400`, `401`, `403`, or `404` — it does not blanket-exclude every 4xx
+status, just those four specific codes (other 4xx codes simply don't match the retry-trigger pattern in
+practice unless their message happens to contain one of the trigger substrings). `withRetry` then applies
+exponential backoff, aborting immediately if the caller's `AbortSignal` fires. Context-window overflow triggers auto-compaction
+(`compact_service.ts` / `core/compact_prompt.ts`) before the loop continues. Provider-specific request/response
+shaping lives under `core/providers/` (`anthropic.ts`, `openai.ts`, `registry.ts`), keeping the orchestrator
+provider-agnostic.
+
+## Background session, sub-agent, and scheduled task lifecycle
+
+- **Background session** — `BackgroundSessionManager` keeps a `RunningConversation` (streaming buffer, tool
+  calls so far, pending `ask_user` state, abort controller) alive independent of whether a UI is currently
+  listening, so a popup/options page can attach, detach, and reattach to the same in-flight run.
+- **Sub-agent** — `SubAgentService` runs a nested conversation through the same `callLLMWithToolLoop` contract
+  as the top-level chat, but resolves an exclusion list via `resolveSubAgentType`/`getExcludeToolsForType`
+  (`core/sub_agent_types.ts`) so a sub-agent type doesn't get tools it shouldn't (e.g. spawning further
+  sub-agents).
+- **Scheduled task** — `AgentTaskService` persists `AgentTask` definitions (`AgentTaskRepo`) and run records
+  (`AgentTaskRunRepo`), computing next-fire times via `core/task_scheduler.ts` and `pkg/utils/cron`; the
+  service worker's `chrome.alarms` handler (`agentTaskScheduler`, wired in
+  `src/app/service/service_worker/index.ts`) calls `agent.onSchedulerTick()` to drive due tasks through the
+  same tool loop as interactive chat.
+
+## Storage backends
+
+The Agent subsystem does not use one persistence pattern; pick by data shape, matching
+[`architecture-data.md`](./architecture-data.md):
+
+- `Repo<T>` (`chrome.storage.local`) — `AgentModelRepo` (small config objects), `AgentTaskRepo` (task
+  definitions).
+- `OPFSRepo` (Origin Private File System) — `AgentChatRepo` (conversation history, can grow large and holds
+  attachments), `AgentTaskRunRepo` (task run history), `SkillRepo` (skill `.md`/script bundles).
+- `MCPServerRepo` (`Repo<T>`) — MCP server configs.
+
+## Page / offscreen / sandbox delegation and permission boundaries
+
+- **Content (`src/app/service/content/gm_api/cat_agent.ts`)** exposes the `CAT.agent.*` API to user scripts —
+  `ConversationInstance` wraps a conversation and dispatches tool-call handlers registered by the calling
+  script. It registers through the same `@GMContext.API` / `@PermissionVerify.API` / `@grant` path as the
+  traditional GM API, with dotted grant names and `connect()`-based chat streaming — see
+  [`architecture-gm-api.md`](./architecture-gm-api.md) for the differences that matter when adding one.
+- **DOM automation** runs from the service worker through a single `AgentDomService` (`dom.ts`), which handles
+  every action (`navigate`, `readPage`, `screenshot`, `click`, `fill`, `scroll`, `waitFor`, `executeScript`,
+  tab monitoring) and delegates to CDP helpers imported from `dom_cdp.ts` (`cdpClick`, `cdpFill`,
+  `cdpScreenshot`, `cdpStartMonitor`/`cdpStopMonitor`/`cdpPeekMonitor`) where it needs `chrome.debugger`.
+  `dom_cdp.ts` is a helper module `dom.ts` calls into, not an independent service with its own request path.
+  The default-vs-trusted split is **not uniform across actions** — check each one:
+  - **Navigation and tab bookkeeping** (`navigate`, `update`, `create`, `query`) always go through
+    `chrome.tabs`, never CDP.
+  - **`click`/`fill`** genuinely branch on the caller's `trusted` option: default mode drives them via
+    `chrome.scripting.executeScript`, "trusted" mode delegates to CDP for real synthetic input
+    (`isTrusted: true`), falling back to the non-trusted path if the CDP call fails.
+  - **`screenshot`** has its own logic independent of any `trusted` flag: a `selector`-scoped capture always
+    uses CDP; a background (non-active) tab tries CDP first and falls back to `chrome.tabs.captureVisibleTab`
+    on failure; an active tab with no selector uses `chrome.tabs.captureVisibleTab` directly.
+  - **Tab monitoring** (`startMonitor`/`stopMonitor`/`peekMonitor`) is unconditionally CDP-based — there is no
+    non-CDP path for it at all.
+
+  CDP attaches the debugger to a tab and carries the extra permission/user-visible-banner implications that
+  come with `chrome.debugger`; how often that applies depends on which action you're looking at, not a single
+  binary "default vs. trusted mode" switch.
+- **OPFS access** is dispatched by caller: `AgentOPFSService.handleOPFSApi` checks whether the request has a
+  `sender` (content script, no Blob support) or came over `postMessage` (offscreen, Blob support) and adjusts
+  behavior accordingly, rather than assuming one execution context.
+- **Skill scripts** execute through `core/skill_script_executor.ts`, delegating to the Sandbox the same way
+  regular background/scheduled scripts do (see [`architecture-execution.md`](./architecture-execution.md)) —
+  the Agent subsystem doesn't introduce a parallel script-execution path.
+
+## Tests
+
+Test file names in `service_worker/` don't all mirror their source file 1:1 — some group by behavior instead
+(e.g. `background.test.ts` covers `background_session_manager.ts`, `retry.test.ts` covers `retry_utils.ts`,
+`autocompact.test.ts` covers the compaction trigger path). At the time of writing, `agent.ts`, `task_service.ts`,
+`compact_service.ts`, and `model_service.ts` don't have an obviously corresponding test file by name — don't
+infer full coverage from this table; run `git ls-tree --name-only HEAD src/app/service/agent/service_worker/ |
+grep test` for the current test inventory and compare it against the source list above before relying on
+either "it's tested" or "it's untested." `core/` follows the same co-located `*.test.ts` convention and the
+same caveat applies. Vitest conventions generally: see
+[`../references/develop-testing.md`](./develop-testing.md).
+
+## Extending the Agent subsystem
+
+- **New tool** — add it under `core/tools/`, register it with the appropriate `ToolSource` (`builtin` at
+  startup, `session` inside the relevant service's session setup), and give it a `ToolExecutor`. Don't register
+  session-scoped tools on the global `ToolRegistry` — use `SessionToolRegistry` so sessions can't clobber each
+  other.
+- **New MCP-backed tool** — goes through `MCPService`, not manual registration; it already handles connecting,
+  naming (`mcp_<server>_<tool>`), and cleanup.
+- **New sub-agent type** — extend `core/sub_agent_types.ts` with its exclusion list rather than special-casing
+  it in `SubAgentService`.
diff --git a/docs/references/architecture-build.md b/docs/references/architecture-build.md
index 64f29ea00..f27d5128a 100644
--- a/docs/references/architecture-build.md
+++ b/docs/references/architecture-build.md
@@ -8,10 +8,14 @@
 
 ```
 context bundles : service_worker · offscreen · sandbox · content · inject · scripting
+shared          : common (pre-React bootstrap, e.g. early theme init — see src/pages/common.ts)
 UI pages (React): popup · options · install · batchupdate · confirm · import
-workers         : editor.worker · ts.worker (Monaco) · linter.worker
+workers         : editor.worker · ts.worker · json.worker (Monaco) · linter.worker
 ```
 
+For the exact current set, check [`rspack.config.ts`](../../rspack.config.ts)'s `entry` block directly — this
+list is a snapshot and can drift when an entry is added or removed.
+
 Output goes to `dist/ext/src/[name].js` (cleaned each build). Notable behavior:
 
 - **Path aliases** mirror `tsconfig.json`: `@App → src`, `@Packages → packages` (the `@Tests → tests` alias is
@@ -33,10 +37,10 @@ dist/ext/
 ├── manifest.json                 # version-stamped, browser-specialized at pack time
 ├── assets/  _locales/
 └── src/
-    ├── service_worker.js content.js inject.js scripting.js offscreen.js sandbox.js
+    ├── service_worker.js content.js inject.js scripting.js offscreen.js sandbox.js common.js
     ├── popup.html/.js options.html/.js install.html/.js …
     ├── offscreen.html sandbox.html
-    └── lib_*.js  editor.worker.js ts.worker.js linter.worker.js
+    └── lib_*.js  editor.worker.js ts.worker.js json.worker.js linter.worker.js
 ```
 
 ### Manifest (MV3)
diff --git a/docs/references/architecture-data.md b/docs/references/architecture-data.md
index 171041664..4eeeba92a 100644
--- a/docs/references/architecture-data.md
+++ b/docs/references/architecture-data.md
@@ -1,9 +1,17 @@
-# Data layer (Repo<T> + DAOs)
+# Data layer (backend taxonomy)
 
-## The Data Layer (`Repo<T>` + DAOs)
+## The Data Layer
 
-Persistence is a thin generic over `chrome.storage.local` with an optional in-memory cache, in
-[`src/app/repo/repo.ts`](../../src/app/repo/repo.ts).
+Persistence in `src/app/repo/` is **not one generic base class** — it's a small taxonomy of backends, each
+suited to a different shape of data. Pick by matching an existing entity with the same size/query/lifecycle
+needs (see [Adding an entity](#adding-an-entity) below), not by defaulting to `Repo<T>` for everything:
+
+| Backend | Backs | Use for | Base file |
+| --- | --- | --- | --- |
+| `Repo<T>` | `chrome.storage.local` | Small config/metadata objects, optionally cached in memory | [`repo.ts`](../../src/app/repo/repo.ts) |
+| `DAO<T>` | Dexie (IndexedDB) | Data needing indexed queries (`where`/pagination) | [`dao.ts`](../../src/app/repo/dao.ts) |
+| `OPFSRepo` | Origin Private File System | Larger JSON blobs / files that don't fit a key-value store (Agent chat history, skills) | [`opfs_repo.ts`](../../src/app/repo/opfs_repo.ts) |
+| Custom repository | Purpose-built | Only when none of the above fit (e.g. `TrashScriptDAO`) | e.g. [`trash_script.ts`](../../src/app/repo/trash_script.ts) |
 
 ### `Repo<T>`
 
@@ -35,19 +43,58 @@ Design notes:
 - **Storage errors are logged, not thrown** — `chrome.runtime.lastError` is checked and reads continue, since
   a transient storage hiccup should not crash the worker.
 
-### The DAOs
+### Repository inventory
 
-| DAO | File | Entity | Notes |
+Names ending in `DAO` don't all share one base class — check which backend before copying a pattern.
+
+**`Repo<T>` (`chrome.storage.local`)**
+
+| Repo | File | Entity | Notes |
 |---|---|---|---|
 | `ScriptDAO` | [`scripts.ts`](../../src/app/repo/scripts.ts) | `Script` (metadata) | Cached; companion `ScriptCodeDAO` stores source separately to keep metadata reads small; dedup via `searchExistingScript` |
 | `ValueDAO` | [`value.ts`](../../src/app/repo/value.ts) | `Value` (GM storage) | Keyed by storage name (per-script or shared `@storageName`) |
 | `ResourceDAO` | [`resource.ts`](../../src/app/repo/resource.ts) | `Resource` (`@require`/`@resource`) | Overrides `joinKey` to hash URLs; `CompiledResourceDAO` caches compiled deps with a version namespace |
 | `PermissionDAO` | [`permission.ts`](../../src/app/repo/permission.ts) | `Permission` | Composite key `<uuid>:<permission>:<value>` |
 | `SubscribeDAO` | [`subscribe.ts`](../../src/app/repo/subscribe.ts) | `Subscribe` | Keyed by feed URL |
-| `FaviconDAO`, `LocalStorageDAO`, `ExportDAO` | `src/app/repo/*.ts` | misc | Same `Repo<T>` pattern |
-| `LoggerDAO` | [`logger.ts`](../../src/app/repo/logger.ts) | `Logger` | Extends `DAO<T>` (Dexie/IndexedDB), **not** `Repo<T>` — logs need indexed queries |
+| `FaviconDAO`, `LocalStorageDAO`, `ExportDAO`, `TempStorageDAO` | `src/app/repo/*.ts` | misc | Same `Repo<T>` pattern |
+| `AgentModelRepo` | [`agent_model.ts`](../../src/app/repo/agent_model.ts) | `AgentModelConfig` | Agent model configs — small, no indexed query need |
+| `AgentTaskRepo` | [`agent_task.ts`](../../src/app/repo/agent_task.ts) | `AgentTask` | Scheduled agent task definitions |
+| `MCPServerRepo` | [`mcp_server_repo.ts`](../../src/app/repo/mcp_server_repo.ts) | `MCPServerConfig` | MCP server configs |
+
+**`DAO<T>` (Dexie/IndexedDB)**
+
+| DAO | File | Entity | Notes |
+|---|---|---|---|
+| `LoggerDAO` | [`logger.ts`](../../src/app/repo/logger.ts) | `Logger` | Logs need indexed queries (`where`/pagination) that `Repo<T>`'s prefix scan doesn't give you |
+
+**`OPFSRepo` (Origin Private File System)**
+
+| Repo | File | Entity | Notes |
+|---|---|---|---|
+| `AgentChatRepo` | [`agent_chat.ts`](../../src/app/repo/agent_chat.ts) | conversation metadata + messages | Can grow large and holds attachments; stored under `agents/conversations/` |
+| `AgentTaskRunRepo` | [`agent_task.ts`](../../src/app/repo/agent_task.ts) | task run history | Companion to `AgentTaskRepo` for run records |
+| `SkillRepo` | [`skill_repo.ts`](../../src/app/repo/skill_repo.ts) | skill `.md`/script bundles | Stored under `agents/skills/` |
+
+**Custom repository (neither of the above fits)**
+
+| Repo | File | Notes |
+|---|---|---|
+| `TrashScriptDAO` | [`trash_script.ts`](../../src/app/repo/trash_script.ts) | Purpose-built for the trash/restore flow; doesn't extend `Repo<T>` or `DAO<T>` |
+
+This list is a snapshot — for the current exact set, run `git grep -n -E 'class [A-Za-z0-9_]*(DAO|Repo)' --
+src/app/repo`.
+
+### Adding an entity
+
+Don't default to `Repo<T>`. Decide by the same questions the existing choices above answer:
+
+- **Data size and shape** — small config object → `Repo<T>`; larger blob/file-like data → `OPFSRepo`.
+- **Query pattern** — need indexed `where`/pagination queries → `DAO<T>` (Dexie); simple get/set/prefix-scan →
+  `Repo<T>`.
+- **Lifecycle** — matches an existing entity's access pattern closely → copy that entity's backend, not a
+  generic template.
 
-### Adding an entity is tiny
+Only once you've picked `Repo<T>` (the common case for small config-shaped entities) does this shape apply:
 
 ```ts
 export interface MyEntity { id: string; data: Record<string, unknown>; createtime: number; }
@@ -59,4 +106,6 @@ export class MyEntityDAO extends Repo<MyEntity> {
 }
 ```
 
-Then create it in the manager (`enableCache()` if hot), and expose operations via `group.on(...)`.
+Then create it in the manager (`enableCache()` if hot), and expose operations via `group.on(...)`. For `DAO<T>`
+or `OPFSRepo`, follow the nearest existing entity of that backend instead (e.g. `LoggerDAO` for Dexie,
+`AgentChatRepo`/`SkillRepo` for OPFS) — their construction and access patterns differ from `Repo<T>`.
diff --git a/docs/references/architecture-gm-api.md b/docs/references/architecture-gm-api.md
index 19bae745b..8f4f6db68 100644
--- a/docs/references/architecture-gm-api.md
+++ b/docs/references/architecture-gm-api.md
@@ -56,10 +56,30 @@ work.
 
 ### Adding a GM API (sketch)
 
-1. Add the method to the content `GMApi` with `@GMContext.API({ alias: "GM.foo" })`; for sync APIs return
-   directly, for async ones forward via `sendMessage`/`connect`.
-2. If it needs privilege (network, cookies, tabs), add the handler on the SW `GMApi` with
+1. Add the method to the content `GMApi` with `@GMContext.API({ alias: "GM.foo" })`.
+2. **Pick the transport by shape, not by habit** — check the nearest existing API of the same shape before
+   choosing:
+   - **Single request/reply** (a value lookup, a one-shot action) → `sendMessage`.
+   - **Streaming/progress, a large response, or a persistent bidirectional exchange** (e.g.
+     `GM_xmlhttpRequest`'s chunked response above) → `connect()` (`MessageConnect`).
+3. If it needs privilege (network, cookies, tabs), add the handler on the SW `GMApi`
+   ([`src/app/service/service_worker/gm_api/`](../../src/app/service/service_worker/gm_api)) with
    `@PermissionVerify.API(...)`.
-3. If it needs DOM, route through the offscreen GM API instead.
-4. Register the `@grant` so the linter and the context builder recognize it (see
-   [`packages/eslint`](../../packages/eslint)).
+4. If it needs DOM, route through the offscreen GM API instead:
+   [`src/app/service/offscreen/gm_api.ts`](../../src/app/service/offscreen/gm_api.ts).
+5. Register the `@grant` so the linter and the context builder recognize it — the grant/compat map lives in
+   [`packages/eslint/compat-grant.js`](../../packages/eslint/compat-grant.js) (not just "the `eslint` package"
+   generally; that package also ships unrelated compat tables like `compat-headers.js`, and
+   `linter-config.ts` holds the ESLint `rules`/`globals`/`env` config, no grant data).
+
+### Agent/CAT API is the same recipe with dotted grants
+
+The Agent subsystem's `CAT.agent.*` surface (`src/app/service/content/gm_api/cat_agent.ts` — see
+[`architecture-agent.md`](./architecture-agent.md)) goes through the *same* registration path as the
+traditional GM API: `@GMContext.API` on the content side
+([`cat_agent.ts`](../../src/app/service/content/gm_api/cat_agent.ts)), `@PermissionVerify.API` on the SW side
+([`gm_agent.ts`](../../src/app/service/service_worker/gm_api/gm_agent.ts)), and a registered grant in
+[`compat-grant.js`](../../packages/eslint/compat-grant.js). What differs is the naming and transport
+shape — the grant is dotted (`CAT.agent.conversation`) and bound with `follow:` rather than `alias:`, the SW
+handlers set `dotAlias: false`, and conversation chat streams over `connect()` instead of `sendMessage`. Copy
+the nearest existing `CAT.agent.*` method rather than a `GM_*` one.
diff --git a/docs/references/architecture-services.md b/docs/references/architecture-services.md
index 2c2797bd3..9c7ca8d81 100644
--- a/docs/references/architecture-services.md
+++ b/docs/references/architecture-services.md
@@ -2,24 +2,52 @@
 
 ## The Service Layer
 
-Services live under `src/app/service/<context>/` — **split by the context they run in** — and hold the domain
-logic. They are deliberately "dumb plumbing on the outside, smart logic on the inside": construction is pure DI,
-wiring happens once in a manager, and message handlers are registered in `init()`.
+`src/app/service/` holds two kinds of things, not one uniform pattern:
+
+- **Context services** — `content/`, `offscreen/`, `sandbox/`, `service_worker/` — split by the runtime context
+  they execute in. Shared or externally-owned collaborators (other services, the message `Group`, DAOs another
+  service also needs) are typically constructor-injected; whether a service also constructs its own *local*
+  DAO/helper internally varies per service — see below. Manager-level wiring happens once, and message
+  handlers/subscriptions are registered through an explicit lifecycle method — commonly `init()`, but not
+  always: content additionally has `contentInit()` (`ScriptRuntime` registers `runtime/addElement` there,
+  called by the content entry point before `init()`), and Agent code has its own equivalents (see
+  [`architecture-agent.md`](./architecture-agent.md)). Check the specific file, don't assume `init()` is the
+  only place registration happens.
+- **Cross-cutting subsystems** — `agent/` (see [`architecture-agent.md`](./architecture-agent.md); spans all
+  five contexts rather than living in one) and `extension/` (extension-wide environment helpers, e.g.
+  `extension_env.ts`) — plus `queue.ts` (shared `MessageQueue` **payload/type** definitions, e.g.
+  `TInstallScript`, `TDeleteScript` — not the `MessageQueue` implementation itself, which lives in
+  [`packages/message/message_queue.ts`](../../packages/message/message_queue.ts) and is instantiated by the
+  contexts that actually need pub/sub — currently Service Worker
+  ([`src/service_worker.ts`](../../src/service_worker.ts)), Offscreen
+  ([`src/app/service/offscreen/base.ts`](../../src/app/service/offscreen/base.ts)), and UI pages subscribing
+  to broadcasts ([`src/pages/store/global.ts`](../../src/pages/store/global.ts)) — not content, inject, or
+  sandbox, which don't instantiate it. Run
+  `git grep -n -E 'new MessageQueue\s*\(' -- src packages | grep -vE '\.(test|spec)\.[cm]?[jt]sx?:'` for
+  the current set rather than trusting this list to stay exhaustive — a plain `"new MessageQueue"` search also
+  matches `new MessageQueueGroup(...)` in `packages/message/message_queue.ts` and every test file that
+  constructs its own instance, neither of which are production instantiation sites.
 
 ```
 src/app/service/
-├── service_worker/   script.ts · value.ts · resource.ts · runtime.ts · popup.ts · subscribe.ts
-│                     synchronize.ts · system.ts · permission_verify.ts · clipboard.ts · download.ts
-│                     gm_api/ (SW-side GM handlers) · index.ts (ServiceWorkerManager)
+├── agent/            cross-cutting: core/ (provider-agnostic) + service_worker/ (composed services) —
+│                     see architecture-agent.md
+├── extension/         extension_env.ts (cross-cutting environment helpers)
+├── queue.ts           shared MessageQueue payload/type definitions (not the implementation)
+├── service_worker/    representative entry points: script.ts · value.ts · resource.ts · runtime.ts ·
+│                      popup.ts · subscribe.ts · synchronize.ts · system.ts · permission_verify.ts ·
+│                      clipboard.ts · download.ts · gm_api/ (SW-side GM handlers) · index.ts (ServiceWorkerManager)
+│                      — for the exact current set, run `git ls-tree --name-only HEAD src/app/service/service_worker/`
 ├── content/          script_runtime.ts · script_executor.ts · exec_script.ts · create_context.ts · gm_api/
-├── offscreen/        background-script runner, gm_api, event_page_manager.ts
+├── offscreen/        background-script runner, gm_api.ts, event_page_manager.ts, html_extractor.ts
 └── sandbox/          runtime.ts (background/scheduled eval + cron)
 ```
 
-### The DI pattern
+### The DI pattern — and its real variance
 
-Every service takes its collaborators through the constructor — never `new`s them internally. A representative
-signature ([`script.ts`](../../src/app/service/service_worker/script.ts)):
+Shared collaborators (the `Group`, `IMessageQueue`, another service, a DAO owned elsewhere) come in through the
+constructor rather than being reached for via a singleton/import. A representative signature
+([`script.ts`](../../src/app/service/service_worker/script.ts)):
 
 ```ts
 class ScriptService {
@@ -30,28 +58,58 @@ class ScriptService {
     private readonly valueService: ValueService,
     private readonly resourceService: ResourceService,
     private readonly scriptDAO: ScriptDAO      // data access
-  ) {}
+  ) {
+    // local setup omitted here — see below: the real constructor does real work
+  }
 
   init() {
     this.group.on("getAllScripts", this.getAllScripts.bind(this));
     this.group.on("install", this.installScript.bind(this));
     this.group.on("enable", this.enableScript.bind(this));
-    // … ~20 more handlers
+    // … many more handlers
   }
 }
 ```
 
-Two consequences worth internalizing:
+That's a trimmed illustration, not a literal copy of `script.ts` — don't infer an exact handler count from it
+(counts drift; check `git grep -c "this.group.on" src/app/service/service_worker/script.ts` for the current
+one) or assume the constructor body is empty.
+
+**Don't over-read the constructor as "never `new` internally, constructor never does work."** Several services
+break both of those:
 
-- **Depend on narrow interfaces** (`IMessageQueue`, not `MessageQueue`) so tests can pass `MockMessage`.
-- **No work in the constructor.** Handler registration and subscriptions belong in `init()`, called by the
-  manager after the whole graph is built (this avoids ordering hazards between mutually dependent services).
+- [`ScriptService`](../../src/app/service/service_worker/script.ts) itself: alongside the injected
+  `scriptDAO`, it self-constructs `ScriptCodeDAO`, `LocalStorageDAO`, `CompiledResourceDAO`, `TrashScriptDAO`,
+  and `SubscribeDAO` as field initializers, and its real constructor body sets up a logger, enables caching on
+  two of those DAOs, and builds a `ScriptUpdateCheck` helper.
+- [`ResourceService`](../../src/app/service/service_worker/resource.ts) constructs its own `ResourceDAO` as a
+  field initializer and does real setup in the constructor body (logger, `enableCache()`).
+- [`SubscribeService`](../../src/app/service/service_worker/subscribe.ts) self-constructs `SubscribeDAO` *and*
+  `ScriptDAO` as field initializers, alongside constructor-injecting `Group`, `mq`, and `ScriptService`.
+
+**There is no "shared DAO type ⇒ same instance" invariant to rely on.** `ScriptService` builds its own
+`SubscribeDAO`; `SubscribeService` builds a *separate* `SubscribeDAO` instance, and its own `ScriptDAO` rather
+than reusing the `scriptDAO` the manager passes to `ScriptService`/`RuntimeService`/`PopupService`. The
+existing choices are case-by-case, not governed by one rule — don't assume either "always inject" or "always
+self-construct." When you're deciding for a new service, weigh cache ownership (does another service need the
+same in-memory cache state?), lifetime (does it need to outlive this service?), and test substitution (does a
+test need to swap it for a fake?) — but that's design guidance for your decision, not a documented reason
+behind each existing instance; check the nearest existing service for the pattern it actually uses.
+
+**`MockMessage` is not an `IMessageQueue` substitute.** It implements the lower-level `Message` transport
+(used to build a `Server`/`Group` for RPC in tests, e.g. `new Server("test", new MockMessage(...))`); the
+`IMessageQueue` a service receives is still a real `MessageQueue` instance in tests (`new MessageQueue()`),
+with individual methods like `publish` swapped for a spy (`vi.fn()`) when a test needs to assert on it. If you
+need a lightweight `IMessageQueue` fake, write one against that narrow interface — don't reach for
+`MockMessage`, which solves a different problem.
 
 ### Wiring: `ServiceWorkerManager`
 
 [`src/app/service/service_worker/index.ts`](../../src/app/service/service_worker/index.ts) is the composition
-root for the SW context. It builds DAOs, hands each service its own `group("name")` namespace and the shared
-`mq`, then calls `init()`:
+root for the SW context. It creates a `group("name")` namespace **for the services that need one** and passes
+the shared `mq` **to the services that need pub/sub** — not every service gets both: `LogService` is
+constructed with `(group, systemConfig)` and no `mq`, and `AgentService` is constructed with
+`(group, this.offscreenSend, resource)`, no `mq` at all. Then it calls `init()` on the services that have one:
 
 ```ts
 const scriptDAO = new ScriptDAO();
@@ -65,9 +123,46 @@ const runtime  = new RuntimeService(systemConfig, this.api.group("runtime"), thi
                                     value, script, resource, scriptDAO, localStorageDAO); runtime.init();
 const popup    = new PopupService(this.api.group("popup"), this.mq, runtime, scriptDAO, systemConfig); popup.init();
 value.init(runtime, popup);   // late-bound cross deps resolved after construction
+const log      = new LogService(this.api.group("log"), systemConfig); log.init();              // no mq
+const agent    = new AgentService(this.api.group("agent"), this.offscreenSend, resource); agent.init(); // no mq
 // … synchronize, subscribe, system
 ```
 
 The `group("name")` call is what gives each service its action prefix (`resource/*`, `value/*`, `script/*`, …)
-on the single `serviceWorker` `Server`. Other contexts have their own managers (`OffscreenManager`,
-`SandboxManager`, `ScriptRuntime` for content/inject) following the same shape.
+on the single `serviceWorker` `Server`. Other contexts have their own composition roots
+(`OffscreenManager`, `SandboxManager`, `ScriptRuntime` for content/inject) that play a similar
+"wire dependencies, register handlers" role, but they are **not** built to the same dependency/initialization
+shape as `ServiceWorkerManager` or each other: `OffscreenManager`'s constructor wraps a `WindowMessage` +
+`Server` + `ServiceWorkerClient` into a shared base class; `SandboxManager` builds its own `Server` and hands
+it to a single `Runtime`; and `ScriptRuntime` (content/inject) additionally owns lifecycle methods the others
+don't have, such as `contentInit()` and `externalMessage()`. Read each manager's own file rather than assuming
+it mirrors `ServiceWorkerManager`.
+
+### Agent composition is different — by design
+
+Context services take *shared* collaborators through the constructor and register handlers through an explicit
+lifecycle method (the DI pattern above — commonly `init()`, sometimes another one like content's
+`contentInit()`), but the exact dependency set — and whether a service also self-constructs a local
+DAO/helper — varies per service (see the `ResourceService`/`SubscribeService` examples above); "`Group` +
+`IMessageQueue` + DAOs" is shorthand for "shared collaborators come in via constructor," not a fixed parameter
+list or a ban on any internal construction. The Agent subsystem's sub-services (`ChatService`, `AgentTaskService`, `SkillService`,
+`AgentModelService`, `MCPService`, etc. — see [`architecture-agent.md`](./architecture-agent.md)) are composed
+by `AgentService` instead of each independently owning a `Group`, and each takes only the narrower interface
+it actually needs (e.g. `AgentModelService` takes a `Group` and its own `AgentModelRepo`; `SubAgentService`
+takes a small `SubAgentOrchestrator` interface). When adding to the Agent subsystem, follow the pattern of the
+nearest existing sub-service rather than a context service's constructor shape.
+
+## Adding a service
+
+First decide what you're adding:
+
+- **A context service** (owned by exactly one of `content/`, `offscreen/`, `sandbox/`, `service_worker/`) —
+  follow the DI pattern and manager wiring above; copy the nearest existing service in that context.
+- **An Agent/core component or cross-cutting subsystem** — copy the nearest existing file under
+  `agent/core/` or `agent/service_worker/` and follow its narrower-interface style (see
+  [`architecture-agent.md`](./architecture-agent.md)), or extend `extension/` for extension-wide environment
+  concerns.
+
+Guessing the wrong shape (e.g. forcing a full `Group`/`IMessageQueue`/DAO constructor onto an Agent
+sub-service) creates an adapter sandwich the codebase doesn't otherwise have — copy the nearest neighbor
+instead of the generic template.
diff --git a/docs/references/design-components.md b/docs/references/design-components.md
index 6f4ec4f6e..ff154719d 100644
--- a/docs/references/design-components.md
+++ b/docs/references/design-components.md
@@ -2,7 +2,7 @@
 
 ## Component palette & usage
 
-The shadcn primitives live in [`src/pages/components/ui/`](../../src/pages/components/ui/) — `new-york` style, CSS variables enabled, no class prefix (`components.json`). Icons are always `lucide-react`; class merging is always `cn()` ([`src/pkg/utils/cn.ts`](../../src/pkg/utils/cn.ts)); variants are always CVA — these are the [`DEVELOP.md` UI section](../develop.md) hard rules, not repeated here. This section is "what exists and how to choose."
+The shadcn primitives live in [`src/pages/components/ui/`](../../src/pages/components/ui/) — `new-york` style, CSS variables enabled, no class prefix (`components.json`). Icons are always `lucide-react`; class merging is always `cn()` ([`src/pkg/utils/cn.ts`](../../src/pkg/utils/cn.ts)); variants are always CVA — these are the [`DEVELOP.md` UI section](../develop.md#ui) hard rules, not repeated here. This section is "what exists and how to choose."
 
 ### Primitives & shared composites
 
@@ -27,6 +27,7 @@ The shadcn primitives live in [`src/pages/components/ui/`](../../src/pages/compo
 | `toggle.tsx` / `toggle-group.tsx` | Toggle button / toggle group (base of `SegmentedControl`) |
 | `label.tsx` | Form label |
 | `progress.tsx` | Progress bar — `default` / `top` / `indeterminate` variants |
+| `slider.tsx` | Range slider |
 | `skeleton.tsx` | Loading-placeholder block |
 | `sonner.tsx` | Global toast container |
 | `use-hover-menu.ts` | Helper hook for hover-triggered menus |
diff --git a/docs/references/design-patterns.md b/docs/references/design-patterns.md
index 79cd808e3..8e06d3b68 100644
--- a/docs/references/design-patterns.md
+++ b/docs/references/design-patterns.md
@@ -55,7 +55,14 @@ Script list and Logger can hold thousands of rows. Keep large lists responsive:
 
 ### Text expansion (i18n)
 
-Copy is translated into 8 locales and German/Russian run ~30% longer than English. Layouts must **flex or truncate, never clip**: let labels wrap or `truncate` with a `title`/tooltip, give buttons/badges `min-w` room instead of fixed widths, and don't pin a control's width to its English string. Verify a long-locale on the tightest screens (mobile cards, the ActionBar). RTL is **not** a target for the current locale set.
+Copy is translated into the locale set [`translation.md`](../translation.md#各语言术语规范--per-locale-terminology)
+currently lists — don't hardcode a locale count here, it drifts. There's no maintained measurement of how much
+longer any given locale runs versus English, so don't cite a fixed percentage; instead pick an actual long
+string from the current locale resources as your test fixture. Layouts must **flex or truncate, never clip**:
+let labels wrap or `truncate` with a `title`/tooltip, give buttons/badges `min-w` room instead of fixed widths,
+and don't pin a control's width to its English string. Verify with a real long-locale fixture on the tightest
+screens (mobile cards, the ActionBar). RTL is not a target for the current locale set and product scope — reconfirm
+both before treating it as settled if either changes.
 
 ---
 
diff --git a/docs/references/design-tokens.md b/docs/references/design-tokens.md
index 09c614a53..5557dea81 100644
--- a/docs/references/design-tokens.md
+++ b/docs/references/design-tokens.md
@@ -7,7 +7,7 @@
 **Usage:**
 - Background `bg-<token>`, text `text-<token>`, border `border-<token>`, focus ring `ring-ring`.
 - Opacity modifiers compose directly: `bg-primary-background/90` (solid primary hover), `ring-destructive/20`, `bg-input/30`.
-- **Never hard-code a color value** — see Constraint 1 and [`DEVELOP.md` UI section](../develop.md). For dark-only tweaks use the `dark:` variant.
+- **Never hard-code a color value** — see Constraint 1 and [`DEVELOP.md` UI section](../develop.md#ui). For dark-only tweaks use the `dark:` variant.
 
 ### Base surfaces & text
 
diff --git a/docs/references/develop-testing.md b/docs/references/develop-testing.md
index fc4c1c6aa..034fd47a5 100644
--- a/docs/references/develop-testing.md
+++ b/docs/references/develop-testing.md
@@ -1,18 +1,21 @@
 # Testing
 
 > The **TDD/BDD-first principle** (write failing tests before implementation; fix code not tests) lives in
-> [`AGENTS.md`](../../AGENTS.md) → *Engineering Principles*. This section is the mechanics.
+> [AGENTS.md § Engineering Principles](../../AGENTS.md#engineering-principles). This section is the mechanics.
 
 Vitest + happy-dom. Per-test budgets live in `vitest.config.ts` per project: non-UI projects (`fast`,
 `isolated`) use 340ms; the `ui` project (`src/pages/**/*.test.{ts,tsx}` — React renders, including
 `renderHook` tests in `.ts` files) uses 850ms because a render + interaction case genuinely costs 100–200ms
 solo under coverage and worker parallelism multiplies that (fake-timer countdown cases have been observed at
 ~630ms under full local load). Don't pass `--test-timeout` on the CLI — it would override every project's
-budget at once. Chrome APIs mocked via
-`@Packages/chrome-extension-mock` (`tests/vitest.setup.ts`). `MockMessage` available for message-system tests.
+budget at once. Chrome APIs are mocked via
+`@Packages/chrome-extension-mock` (`tests/vitest.setup.ts`). `MockMessage` is available for message-system tests.
 `happy-dom` is patched via `patches/` (see `pnpm-workspace.yaml` `patchedDependencies`) to build its
 invalid-selector `DOMException` lazily — the upstream eager construction captures a deep stack on every
-`matches()`/`querySelector()` call and cost ~15% of TSX suite time.
+`matches()`/`querySelector()` call, which is measurably slower at TSX-suite scale. No specific percentage is
+tracked here since it isn't tied to a reproducible command/environment; if you need a number, measure
+before/after this patch in the same environment using the JSON-report method below rather than trusting a
+historical figure.
 
 - Co-locate `*.test.ts`/`*.test.tsx` next to source (or place in `tests`).
 - BDD-style Chinese `describe`/`it` titles. Use `describe.concurrent()` / `it.concurrent()` where independent.
diff --git a/docs/references/verification-debugging.md b/docs/references/verification-debugging.md
index fa3fc6d4f..c50b3d0ff 100644
--- a/docs/references/verification-debugging.md
+++ b/docs/references/verification-debugging.md
@@ -12,6 +12,13 @@ model in [`ARCHITECTURE.md`](../architecture.md)):
 | Background / scheduled script, DOM-needing GM APIs | **Offscreen** — `dist/ext/src/offscreen.html` context |
 | Cron scheduling, `with`-sandboxed execution | **Sandbox** — `dist/ext/src/sandbox.html` context |
 
+**Firefox note.** Firefox MV3 has no separate Offscreen document — there is no `offscreen.html` to inspect.
+`EventPageOffscreenManager` runs offscreen-equivalent logic (background/scheduled-script DOM work) inside the
+DOM-capable background event page instead, so look there for those logs on Firefox. The Sandbox iframe is
+still a separate execution boundary on both browsers. See
+[architecture.md § Chrome vs Firefox: the offscreen split](../architecture.md#chrome-vs-firefox-the-offscreen-split)
+for the full picture.
+
 In a scratch script, capture the page console (`page.on("console", …)`), take screenshots
 (`await page.screenshot({ path: "test-results/verify/<scenario>/screenshots/…png" })`), and write any manual
 notes to `test-results/verify/<scenario>/`. Playwright's automatic failure artifacts also go under
diff --git a/docs/references/verification-report-template.md b/docs/references/verification-report-template.md
index 0ead5e653..c757bd18d 100644
--- a/docs/references/verification-report-template.md
+++ b/docs/references/verification-report-template.md
@@ -4,7 +4,16 @@ Before running the browser, create a short verification record in the scenario d
 `test-results/verify/<scenario>/report.md`. Keep the reusable template headings in English, but write the actual
 record content in the user's language. Update it as the run proceeds instead of filling it in only at the end.
 
-```md
+**The snippet below is a filled *example* of the `## Evidence Index` shape** — it shows what a completed one
+looks like, not a second section to add. The full template further down has its own `## Evidence Index`
+heading; use that one heading and fill it following this example's shape.
+
+This record exists so a reader can judge whether the implementation is correct, so **evidence is embedded, not
+linked**: scrolling `report.md` top to bottom should show the pixels and the deciding log lines without opening
+a single side file. A bare link is the fallback for artifacts that genuinely cannot render inline (archives,
+binaries, multi-megabyte logs), and it carries a note saying what it holds.
+
+~~~md
 ## Evidence Index
 
 ### Screenshots
@@ -12,24 +21,49 @@ record content in the user's language. Update it as the run proceeds instead of
 ![Options root](screenshots/options-root.png)
 The script list page rendered and the view toggle is visible, proving the `/` route mounted successfully.
 
-![Settings](screenshots/settings.png)
-The settings page shell and content are visible, proving `/settings` did not render blank or crash during mount.
+| Light | Dark |
+| --- | --- |
+| ![Settings light](screenshots/settings-light.png) | ![Settings dark](screenshots/settings-dark.png) |
+
+The settings shell renders in both themes with readable contrast, proving `/settings` mounted and picked up the
+theme tokens rather than falling back to one palette.
 
 ### Videos
 
-- [videos/page@abc.webm](videos/page@abc.webm) — Full page-viewport recording from the script list to the
-  settings page; review it for the navigation and final stable state.
+<video src="videos/page@abc.webm" controls width="720"></video>
+
+Full page-viewport recording from the script list to the settings page; watch it for the navigation and the
+final stable state.
+
+Same run, decisive moments as stills — a video is neither skimmable nor playable in every viewer:
+
+![Before navigation](screenshots/nav-01-list.png)
+The script list before the click; the settings entry is enabled.
+
+![After navigation](screenshots/nav-02-settings.png)
+The settings page after the click; the route changed and the content painted.
 
 ### Logs
 
-- [console.log](console.log) — Browser console output captured during the run; confirms whether unexpected errors
-  appeared.
+The lines the verdict rests on:
+
+```text
+[verify] options url = chrome-extension://<id>/src/options.html#/settings
+[verify] script count after import = 3
+```
+
+Full capture: [console.log](console.log) — no unexpected errors appeared during the run.
 
 ### Resources
 
-- [resources/import.yaml](resources/import.yaml) — Input file used by the import verification; keep it to
-  reproduce the import flow.
+`resources/import.yaml` — the input the import verification consumed:
+
+```yaml
+scripts:
+  - name: demo-script
+    source: https://example.com/demo.user.js
 ```
+~~~
 
 Use this shape:
 
@@ -81,7 +115,7 @@ Use this shape:
 
 ## Evidence Index
 
-Embed screenshots inline, link videos / logs / resources, and annotate every item — see the shape above.
+Embed every artifact inline and annotate what it proves — see the shape above.
 ```
 
 Fill `Result` at the end — the honest verdict, per *Step 4 — Report honestly* in [`verification.md`](../verification.md).
@@ -97,3 +131,20 @@ Keep the checklist factual:
 - Check items only after the corresponding command/assertion has actually passed.
 - If a step is blocked, leave its checkbox unchecked and add a concrete entry under `Blockers`: what failed,
   where it failed, and what evidence was captured.
+
+Keep the evidence embedded:
+
+- **Screenshots** — `![alt](screenshots/….png)` plus a caption line stating what it proves. Put paired shots
+  (before/after, light/dark) in a two-column table so the comparison is one glance, not two scrolls.
+- **Videos** — `<video src="videos/….webm" controls width="720"></video>`. This renders as a player only in
+  viewers that allow inline HTML, and a recording is slow to review either way, so capture the deciding moments
+  as `page.screenshot()` calls *during* the run and embed those stills next to the video. The stills, not the
+  recording, are what carries the verdict.
+- **Logs** — paste the lines the verdict rests on into a fenced block, then link the full capture for the rest.
+  A link alone forces the reader to reconstruct which line mattered.
+- **Resources** — paste short text fixtures (YAML/JSON/userscript) inline in a fenced block. Link only what is
+  large or binary, and say what it contains.
+- Sanitize tokens, cookies, and real credentials *before* pasting log or resource content inline — embedding
+  puts it in front of every reader.
+- Keep every path relative to `report.md`. The scenario directory, not `report.md` alone, is the unit you hand
+  to a reviewer; moving the file out of it breaks every embed.
diff --git a/docs/translation.md b/docs/translation.md
index a05ffad54..18f0a517d 100644
--- a/docs/translation.md
+++ b/docs/translation.md
@@ -53,6 +53,15 @@
 - 为满足部分扩展市场要求，`chrome.i18n` 语言文件位于 `src/assets/_locales`。
 - i18n 方案的实现细节见 [`src/locales/README.md`](../src/locales/README.md)。
 
+### 自动化检查的真实范围
+
+[`src/locales/i18n-usage.test.ts`](../src/locales/i18n-usage.test.ts) 会扫描 `src/pages` 与
+`src/app/service/service_worker` 目录下非测试文件中双引号字面量的 `t()` / `i18n.t()` 调用，并按 `zh-CN`
+resources 解析对应 key 是否存在；动态/插值 key、`defaultValue` 内联回退，以及无法识别的 namespace 会被跳过,
+不计入检查范围。它**只**证明代码引用的 key 在 `zh-CN` 中存在，**不能**证明其他 locale 的 key 是否完整、
+译文措辞是否准确、或术语是否符合对应 `terminology-<locale>.md`——这些仍需人工或专项核对，不要把“测试通过”当成
+“翻译已核对”的证据。
+
 ## 提取翻译提示词 / Extract-translation prompt
 
 将 React 文件中的中文提取为 i18next key 时使用：
diff --git a/docs/verification.md b/docs/verification.md
index 81db6718c..a040d4e87 100644
--- a/docs/verification.md
+++ b/docs/verification.md
@@ -7,15 +7,33 @@
 > scripts and local-only evidence — kept out of Git and never deleted as part of a run; cleanup is the user's call.
 >
 > **What this is NOT.** It is *not* the test-suite reference. The mechanics of Vitest unit tests and the
-> permanent Playwright E2E suite live in [`DEVELOP.md`](./develop.md) → *Testing*; the TDD-first principle and
-> engineering rules live in [`../AGENTS.md`](../AGENTS.md). Read those for writing committed tests.
+> permanent Playwright E2E suite live in [develop.md § Testing](./develop.md#testing); the TDD-first principle
+> and engineering rules live in [AGENTS.md § Engineering Principles](../AGENTS.md#engineering-principles). Read
+> those for writing committed tests.
+
+## When to skip this guide
+
+This guide is **workflow routing**, not a TDD blanket exception — it applies when a change needs the built
+extension, real Chrome APIs, or cross-context behavior to observe. Skip it (and rely on typecheck + the
+relevant committed test instead) for:
+
+- Doc-only, comment-only, or type-only changes with no runtime behavior to observe.
+- Pure logic that a targeted unit test already exercises completely (a parser, a utility function, a reducer) —
+  write/run that test instead of driving a browser for it.
+- Any change fully reproducible and provable by a targeted committed test without the built extension.
+
+If you're unsure whether a change needs the built extension, the deciding question is: *does this depend on
+cross-context wiring or a real browser API that a unit test can't exercise?* If no, a targeted unit test is
+the whole verification; don't reach for this guide's scratch-script workflow just to "be thorough."
 
 ## The one rule: verification ≠ growing the E2E suite
 
 The full E2E suite is **heavy** (two-phase browser launch, real network fetches, multi-minute timeouts). When
 you only want to *check that a feature works*, do not pay that cost and do not leave anything behind:
 
-- ❌ **Never** run the whole suite (`pnpm run test:e2e`) just to verify one thing.
+- ❌ **Never** run the whole suite (`pnpm run test:e2e`) just to verify one thing *during casual verification*.
+  This rule scopes this guide's workflow — it is not a release/CI policy; CI and pre-release gates run the full
+  suite as their own separate, deliberate check.
 - ❌ **Never** add a permanent `e2e/*.spec.ts` as part of casual verification.
 - ✅ Write a **throwaway scratch script** under `e2e/scratch/` (git-ignored), run it, and keep any evidence local.
 
@@ -35,15 +53,23 @@ Choose the reproduction method by what the bug depends on: a failing unit test f
 bugs; this guide's scratch-script workflow (above) when it depends on the built extension, browser APIs, or
 cross-context behavior.
 
-## Prerequisite gate (cheap signals first)
+## Prerequisite gate (cheap signals first, proportional to risk)
 
-Driving a browser is the *last* check, not the first. Confirm the cheap signals are green before you build:
+Driving a browser is the *last* check, not the first. Confirm the cheap signals are green before you build —
+but scale which signals proportionally, not mechanically:
 
 ```bash
-pnpm run typecheck      # tsc --noEmit
-pnpm test               # Vitest unit tests (or target one file, see DEVELOP.md)
+pnpm run typecheck                        # tsc --noEmit — always
+pnpm test -- --run path/to/file.test.ts   # targeted unit test(s) for the change — the default
+pnpm test                                 # full Vitest suite — only when the change is broad/risky,
+                                           # touches shared code, or a repo gate/CI requires it
 ```
 
+Typecheck plus the targeted relevant test is the default prerequisite — it is not a requirement to run the
+full Vitest suite before every scratch verification. Run the broader suite when the change's blast radius
+isn't confirmed to be local (shared utilities, config, public interfaces) or when project policy requires it
+for the change type.
+
 Green unit tests do **not** mean the feature works — they mean the units you tested behave. Cross-context wiring
 (Service Worker ↔ Content ↔ Inject ↔ Offscreen ↔ Sandbox) and real Chrome APIs only exercise in a loaded
 extension. That gap is exactly what this guide closes.
@@ -91,15 +117,22 @@ Use `resources/` for any extra local inputs or outputs needed to understand or r
 - mock API responses, fixture JSON/YAML, import/export files, generated ZIPs, or downloaded artifacts
 - temporary HTML pages, saved network payloads, or before/after data snapshots
 
-Reference these resources from `report.md` with relative links such as `[Import file](resources/import.yaml)` or
-`[Mock response](resources/provider-response.json)`. Keep secrets and real credentials out of the resource directory;
-sanitize them before saving evidence.
+Surface these resources in `report.md` — short text fixtures pasted into a fenced block, anything large or
+binary as a relative link such as `[Exported backup](resources/backup.zip)`. Keep secrets and real credentials
+out of the resource directory; sanitize them before saving evidence, and again before pasting any of it inline.
 
-Embed screenshots inline with `![alt](screenshots/…png)` plus a caption line, so `report.md` renders as a visual
-record you can skim without opening files. Link videos, logs, and resources instead — markdown can't inline them.
-Never list bare links: every item carries a short note explaining what it proves and how to read it. Before running
-the browser, create the record following the Evidence Index shape in the
-[verification record template](./references/verification-report-template.md).
+`report.md` is read to decide whether the implementation is correct, so embed the evidence instead of linking
+it: screenshots as `![alt](screenshots/….png)`, videos as `<video src="videos/….webm" controls width="720">`
+alongside stills of the deciding moments, and the log lines or short fixtures that carry the verdict as fenced
+blocks. Scrolling the report should be enough to reach a verdict without opening a side file. Keep a bare link
+only for what cannot render inline — archives, binaries, a full log capture — and never list one bare: every
+item carries a short note explaining what it proves and how to read it.
+
+### Create `report.md` before you run the browser
+
+Before running the browser, create `test-results/verify/<scenario>/report.md` following the Evidence Index
+shape in the [verification record template](./references/verification-report-template.md). Fill it in as you
+go — don't reconstruct the run from memory afterward.
 
 ### Minimal template (drive a UI page)
 
@@ -237,6 +270,20 @@ discards the DOM event and calls the same message). State the substitution in `r
 
 > Hit a failure or a hang? See [debugging & common gotchas](./references/verification-debugging.md).
 
+### Verifying a UI change across light/dark theme
+
+The theme is stored in `localStorage` under the key `lightMode` with value `"light"` / `"dark"` / `"auto"`
+(see [`src/pages/components/theme-provider.tsx`](../src/pages/components/theme-provider.tsx) and
+[`src/pages/common.ts`](../src/pages/common.ts), which reads the same key during pre-render to avoid a theme
+flash). Setting this key **before** the page's own scripts run — e.g. via Playwright's `context.addInitScript`
+— is what makes the theme apply on first paint instead of flashing the default and then switching.
+
+Before relying on this in a scratch script, confirm it actually behaves that way for an `chrome-extension://`
+page in your Playwright setup — `addInitScript` timing relative to an extension page's own bootstrap can differ
+from a normal web page, so verify with a quick throwaway run rather than assuming it. Once confirmed for a
+scenario, capture one screenshot per theme (`light` and `dark`) as separate evidence — a single theme's
+screenshot doesn't demonstrate the other renders correctly.
+
 ## Step 4 — Report honestly
 
 Verification only counts if the result is reported as observed (this mirrors the engineering principle: evidence
@@ -247,8 +294,12 @@ before assertions).
 - If it fails or you could not verify a path, **say that plainly** with the console/output — do not soften it,
   do not claim success you did not see.
 - If you were **reproducing a bug**, state plainly whether it reproduced. If it did, the failing observation
-  (error, assertion diff, error screenshot) *is* the evidence — record it and move on to the failing-test → fix
-  cycle. If it did not reproduce, say so and note what you tried, instead of implying the bug is gone.
+  (error, assertion diff, error screenshot) *is* the evidence. In the general case, promote it into a committed
+  failing test before fixing (the failing-test → fix cycle). Under
+  [develop-testing.md § When TDD doesn't apply](./references/develop-testing.md#when-tdd-doesnt-apply)'s
+  infeasible-automated-coverage exception, keep this scratch reproduction as the evidence instead — fix the
+  code, then re-run the *same* reproduction script to confirm it now passes. If it did not reproduce, say so
+  and note what you tried, instead of implying the bug is gone.
   - Two honest framings for the scratch assertion: assert the **desired** behavior (the scratch stays *red* and
     directly shows the gap), or assert the **current buggy contract** (the scratch passes *green* while the bug
     is present, giving a deterministic re-runnable record) and note that the fix must flip it. Pick one and say
diff --git a/packages/cloudscript/README.md b/packages/cloudscript/README.md
index 9e7707a74..83a6417c3 100644
--- a/packages/cloudscript/README.md
+++ b/packages/cloudscript/README.md
@@ -1,3 +1,15 @@
-# 脚本上云
+# Cloud Script Export
 
+将单个脚本连同其数据打包为可独立执行的归档，而不是同步到远端云存储 —— 与 `packages/filesystem` 的云同步是两回事,
+不要混淆。
+
+`CloudScriptFactory`（[`factory.ts`](./factory.ts)）目前只有一个 target：`local`
+（[`local.ts`](./local.ts)）。它把脚本源码、`GM_*` values、cookies 和一份 `config.js` 元数据打进一个 zip,
+附带 `package.json`/`utils.js`/`index.js`（模板见 `src/template/cloudcat-package/`）。`package.json` 声明了外部
+依赖 `scriptcat-nodejs`，因此产出的包**不是**解压后即可直接 `node index.js` 运行 —— 需要先在解压目录执行
+`npm install`（安装 `scriptcat-nodejs`）,再 `npm run run`（等价于 `node index.js`），供脚本迁移或离线执行使用,
+不涉及任何远端上传。
+
+云端同步/备份（WebDAV、OneDrive、Google Drive、Dropbox、百度网盘、S3）由
+[`packages/filesystem`](../filesystem/README.md) 提供，语义细节见 [`docs/cloud-sync.md`](../../docs/cloud-sync.md)。
 
diff --git a/packages/filesystem/README.md b/packages/filesystem/README.md
index 5152ad5ee..7f9f1d641 100644
--- a/packages/filesystem/README.md
+++ b/packages/filesystem/README.md
@@ -1,8 +1,15 @@
 # 文件系统
 
-用于同步和备份至云端
+可插拔的 `FileSystem` 抽象（[`filesystem.ts`](./filesystem.ts) / [`factory.ts`](./factory.ts)），用于脚本同步与备份。
+当前 provider（见对应目录）：
 
-- zip
-- webdav
-- 百度网盘
-- onedrive
+- WebDAV（`webdav/`）
+- OneDrive（`onedrive/`）
+- Google Drive（`googledrive/`）
+- Dropbox（`dropbox/`）
+- 百度网盘（`baidu/`）
+- S3（`s3/`）
+- Zip（`zip/`）—— 同一个 `FileSystem` 抽象的归档/本地备份实现，不是远端 provider，导出为本地 zip 文件而非同步到云端。
+
+云同步的详细语义（同步文件、状态合并、错误分类、重试策略）见 [`docs/cloud-sync.md`](../../docs/cloud-sync.md)，
+不在本 README 重复。
diff --git a/packages/message/README.md b/packages/message/README.md
index 6ebb01776..7e15272ea 100644
--- a/packages/message/README.md
+++ b/packages/message/README.md
@@ -1,16 +1,21 @@
 # 消息
 
-对扩展内消息交互的抽象
+跨 context（service_worker / content / inject / offscreen / sandbox）消息交互的抽象层。按调用形态选择传输方式：
 
-主要会有以下几种类型的消息：
+- **单次 request/reply**（调用一次拿一次结果，例如大多数 GM API、扩展页面对 service_worker 的一次性调用）——
+  使用 `sendMessage`（`Server`/`Group`/`Client` 的 RPC 封装）。
+- **流式/进度/长响应，或需要持续双向交换**（例如需要分块返回大响应的 GM API、需要多次调用/多次结果的场景）——
+  使用 `connect()`（`MessageConnect`）建立持久连接。
+- **广播**（service_worker/offscreen 触发的状态变化需要通知所有页面）——使用 `MessageQueue` 的
+  `publish`/`subscribe`，而不是上面两种点对点方式。
 
-- 从脚本发起的GM请求，需要层层传递到service_worker/offscreen进行处理，有的GM只需要进行一次调用获取一次结果，有的需要进行
-  多次调用获取多次结果，使用connect的方式实现
-- 从service_worker/offscreen发起的请求，类似消息队列，其它页面进行监听，触发后广播给所有页面，使用sendMessage方式实现
-- 从扩展页面发起的请求，需要传递到service_worker/offscreen进行处理，如果只是单次调用，获取一次结果，使用sendMessage方式实现，如果需要
-  多次调用获取多次结果，使用connect方式实现
+Service Worker → Offscreen 在 Chrome 与 Firefox 上走不同路径（Chrome 使用
+`ServiceWorkerMessageSend`/`clients.matchAll()`；Firefox 用 `EventPageOffscreenManager` 替代真实的 offscreen
+document），细节见
+[`docs/architecture.md` § Chrome vs Firefox: the offscreen split](../../docs/architecture.md#chrome-vs-firefox-the-offscreen-split)。
 
 ## 注意点
 
-- service_worker和offscreen之间可以使用postMessage的方式进行通信，避免同时监听message与connect导致冲突的问题
-- service_worker会变为不活动的状态，尽量避免与service_worker建立长连接
+- service_worker 和 offscreen 之间可以使用 postMessage 的方式进行通信，避免同时监听 message 与 connect 导致冲突的问题。
+- service_worker 会在空闲后进入不活动状态；与它建立的 `connect()` 长连接会在此时中断，因此需要长连接的场景要考虑
+  重连/状态恢复，而不是假定连接一直存活——这不是禁止在 service_worker 上使用 `connect`，只是需要为其生命周期设计容错。
diff --git a/src/app/service/agent/core/session_tool_registry.ts b/src/app/service/agent/core/session_tool_registry.ts
index 1cea9f7d3..9d0f8186f 100644
--- a/src/app/service/agent/core/session_tool_registry.ts
+++ b/src/app/service/agent/core/session_tool_registry.ts
@@ -14,7 +14,7 @@ import type {
  *
  * 架构动机：
  * 原来的 ToolRegistry 是全局共享 Map，会话间 registerBuiltin 同名工具会互相覆盖闭包，
- * 导致并发会话的 task/ask_user/sub_agent 绑定到错误的 conversationId/sendEvent。
+ * 导致并发会话的 create_task/ask_user/agent 等会话级工具绑定到错误的 conversationId/sendEvent。
  *
  * 本类持有 parent: ToolRegistry 只读引用 + 自己的 sessionTools Map。
  * - register()：只写入 sessionTools（不污染 parent）
diff --git a/src/locales/README.md b/src/locales/README.md
index 8f7839594..f8954d47a 100644
--- a/src/locales/README.md
+++ b/src/locales/README.md
@@ -25,11 +25,13 @@ for example:
 
 ### Help Us Translate
 
-Translation files are located in `src/locales`, organized by namespace. If you're interested in helping translate, please submit a PR directly.
+For the translation workflow, terminology rules, and per-locale checklist, see
+[`docs/translation.md`](../../docs/translation.md) — this file only covers the i18n implementation, not the
+contribution workflow.
 
 # i18n 方案
 
-i18n 使用[i8next](https://www.i18next.com/)实现，之所以不是用`chrome.i18n`的原因是该方案不支持动态切换语言。但是为了某些扩展市场的要求，我们还是在`src/assets/_locales`目录下添加了`chrome.i18n`的语言文件。
+i18n 使用[i18next](https://www.i18next.com/)实现，之所以不是用`chrome.i18n`的原因是该方案不支持动态切换语言。但是为了某些扩展市场的要求，我们还是在`src/assets/_locales`目录下添加了`chrome.i18n`的语言文件。
 
 ## 语言文件
 
@@ -50,4 +52,5 @@ i18n 使用[i8next](https://www.i18next.com/)实现，之所以不是用`chrome.
 
 ### 帮助我们翻译
 
-翻译文件位于 `src/locales` 目录下，按命名空间划分。如果您有兴趣帮助翻译，请直接提交 PR。
+翻译工作流、术语规则与逐语言检查清单见 [`docs/translation.md`](../../docs/translation.md)——本文件只覆盖 i18n
+实现机制，不重复维护贡献流程。
diff --git a/src/pages/options/routes/Setting/i18nKeys.md b/src/pages/options/routes/Setting/i18nKeys.md
deleted file mode 100644
index c57054faa..000000000
--- a/src/pages/options/routes/Setting/i18nKeys.md
+++ /dev/null
@@ -1,163 +0,0 @@
-# 设置页 i18n key 映射
-
-设置页所有 key 的 `t(...)` 引用形式。`defaultNS` 为 `common`，其他命名空间需带前缀。
-
-## 全集 key → namespace:key
-
-### 通用 (General)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `language` | `settings:language` |
-| `select_interface_language` | `settings:select_interface_language` |
-| `general` | `settings:general` |
-
-### 界面 (Interface)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `interface_settings` | `settings:interface_settings` |
-| `extension_icon_badge` | `settings:extension_icon_badge` |
-| `display_type` | `settings:display_type` |
-| `badge_type_none` | `settings:badge_type_none` |
-| `badge_type_run_count` | `settings:badge_type_run_count` |
-| `badge_type_script_count` | `settings:badge_type_script_count` |
-| `extension_icon_badge_type` | `settings:extension_icon_badge_type` |
-| `background_color` | `settings:background_color` |
-| `badge_background_color_desc` | `settings:badge_background_color_desc` |
-| `text_color` | `settings:text_color` |
-| `badge_text_color_desc` | `settings:badge_text_color_desc` |
-| `script_menu` | `settings:script_menu` |
-| `display_right_click_menu` | `settings:display_right_click_menu` |
-| `display_right_click_menu_desc` | `settings:display_right_click_menu_desc` |
-| `expand_count` | `settings:expand_count` |
-| `auto_collapse_when_exceeds` | `settings:auto_collapse_when_exceeds` |
-| `favicon_service` | `settings:favicon_service` |
-| `favicon_service_scriptcat` | `settings:favicon_service_scriptcat` |
-| `favicon_service_google` | `settings:favicon_service_google` |
-| `favicon_service_duckduckgo` | `settings:favicon_service_duckduckgo` |
-| `favicon_service_icon-horse` | `settings:favicon_service_icon-horse` |
-| `favicon_service_local` | `settings:favicon_service_local` |
-| `favicon_service_desc` | `settings:favicon_service_desc` |
-
-### 同步 (Sync)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `script_sync` | `settings:script_sync` |
-| `enable_script_sync_to` | `settings:enable_script_sync_to` |
-| `backup_to` | `settings:backup_to` |
-| `sync_delete` | `settings:sync_delete` |
-| `sync_delete_desc` | `settings:sync_delete_desc` |
-| `save` | `save` (common) |
-| `save_success` | `save_success` (common) |
-
-### 更新 (Update)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `update` | `update` (common) |
-| `script_update_check_frequency` | `settings:script_update_check_frequency` |
-| `script_auto_update_frequency` | `settings:script_auto_update_frequency` |
-| `never` | `settings:never` |
-| `6_hours` | `settings:6_hours` |
-| `12_hours` | `settings:12_hours` |
-| `every_day` | `settings:every_day` |
-| `every_week` | `settings:every_week` |
-| `update_disabled_scripts` | `settings:update_disabled_scripts` |
-| `silent_update_non_critical_changes` | `settings:silent_update_non_critical_changes` |
-| `control_script_update_behavior` | `settings:control_script_update_behavior` |
-
-### 运行时 (Runtime)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `runtime` | `logs:runtime` |
-| `enable_background` | `settings:enable_background` (object) |
-| `storage_api` | `editor:storage_api` |
-| `use_file_system` | `editor:use_file_system` |
-| `open_directory` | `editor:open_directory` |
-| `not_set` | `editor:not_set` |
-| `in_use` | `editor:in_use` |
-| `storage_error` | `editor:storage_error` |
-| `settings` | `settings` (common) |
-| `reset` | `reset` (common) |
-
-### 安全 (Security)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `security` | `settings:security` |
-| `blacklist_pages` | `settings:blacklist_pages` |
-| `blacklist_pages_desc` | `settings:blacklist_pages_desc` |
-| `blacklist_placeholder` | `settings:blacklist_placeholder` |
-| `expression_format_error` | `settings:expression_format_error` |
-
-### 开发者 (Developer)
-
-| key | t(...) 引用 |
-|-----|-------------|
-| `development_tools` | `settings:development_tools` |
-| `enable_eslint` | `settings:enable_eslint` |
-| `check_script_code_quality` | `settings:check_script_code_quality` |
-| `eslint_rules` | `settings:eslint_rules` |
-| `custom_eslint_rules_config` | `settings:custom_eslint_rules_config` |
-| `enter_eslint_rules` | `settings:enter_eslint_rules` |
-| `eslint_rules_reset` | `editor:eslint_rules_reset` |
-| `eslint_rules_saved` | `editor:eslint_rules_saved` |
-| `eslint_config_format_error` | `editor:eslint_config_format_error` |
-| `editor_config` | `editor:editor_config` |
-| `editor_config_reset` | `editor:editor_config_reset` |
-| `editor_config_saved` | `editor:editor_config_saved` |
-| `editor_config_format_error` | `editor:editor_config_format_error` |
-| `editor_config_description` | `editor:editor_config_description` |
-| `editor_type_definition` | `editor:editor_type_definition` |
-| `editor_type_definition_reset` | `editor:editor_type_definition_reset` |
-| `editor_type_definition_saved` | `editor:editor_type_definition_saved` |
-| `editor_type_definition_description` | `editor:editor_type_definition_description` |
-
----
-
-## 新增到 settings.json 的 key（规则 3）
-
-以下 8 个 key 在 new-ui 任何命名空间均不存在，已从 v1.4 `translation.json` 迁移到 7 个 `src/locales/<locale>/settings.json`：
-
-| key | 位置 |
-|-----|------|
-| `badge_type_none` | `settings:badge_type_none` |
-| `badge_type_run_count` | `settings:badge_type_run_count` |
-| `badge_type_script_count` | `settings:badge_type_script_count` |
-| `script_menu` | `settings:script_menu` |
-| `display_right_click_menu` | `settings:display_right_click_menu` |
-| `display_right_click_menu_desc` | `settings:display_right_click_menu_desc` |
-| `expand_count` | `settings:expand_count` |
-| `auto_collapse_when_exceeds` | `settings:auto_collapse_when_exceeds` |
-
-## 映射到现有命名空间的 key（规则 2 — 不重复迁移）
-
-| key | 现有 namespace:key |
-|-----|-------------------|
-| `save` | `common:save` → `t("save")` |
-| `save_success` | `common:save_success` → `t("save_success")` |
-| `update` | `common:update` → `t("update")` |
-| `settings` | `common:settings` → `t("settings")` |
-| `reset` | `common:reset` → `t("reset")` |
-| `runtime` | `logs:runtime` → `t("logs:runtime")` |
-| `storage_api` | `editor:storage_api` → `t("editor:storage_api")` |
-| `use_file_system` | `editor:use_file_system` → `t("editor:use_file_system")` |
-| `open_directory` | `editor:open_directory` → `t("editor:open_directory")` |
-| `not_set` | `editor:not_set` → `t("editor:not_set")` |
-| `in_use` | `editor:in_use` → `t("editor:in_use")` |
-| `storage_error` | `editor:storage_error` → `t("editor:storage_error")` |
-| `eslint_rules_reset` | `editor:eslint_rules_reset` → `t("editor:eslint_rules_reset")` |
-| `eslint_rules_saved` | `editor:eslint_rules_saved` → `t("editor:eslint_rules_saved")` |
-| `eslint_config_format_error` | `editor:eslint_config_format_error` → `t("editor:eslint_config_format_error")` |
-| `editor_config` | `editor:editor_config` → `t("editor:editor_config")` |
-| `editor_config_reset` | `editor:editor_config_reset` → `t("editor:editor_config_reset")` |
-| `editor_config_saved` | `editor:editor_config_saved` → `t("editor:editor_config_saved")` |
-| `editor_config_format_error` | `editor:editor_config_format_error` → `t("editor:editor_config_format_error")` |
-| `editor_config_description` | `editor:editor_config_description` → `t("editor:editor_config_description")` |
-| `editor_type_definition` | `editor:editor_type_definition` → `t("editor:editor_type_definition")` |
-| `editor_type_definition_reset` | `editor:editor_type_definition_reset` → `t("editor:editor_type_definition_reset")` |
-| `editor_type_definition_saved` | `editor:editor_type_definition_saved` → `t("editor:editor_type_definition_saved")` |
-| `editor_type_definition_description` | `editor:editor_type_definition_description` → `t("editor:editor_type_definition_description")` |