yunti-browser-runtime 0.1.3 → 0.2.1

package/docs/EXTENSION_DISTRIBUTION.md

@@ -0,0 +1,146 @@
+# Extension Distribution Readiness
+
+This document tracks browser-store readiness for the Yunti Browser Runtime
+extension. It is intentionally an audit and submission plan first, not an
+immediate permission rewrite.
+
+## Current Goal
+
+Prepare for Chrome Web Store and Microsoft Edge Add-ons distribution while
+preserving Yunti's local-first browser automation purpose:
+
+- operate real user-opened Chrome/Edge pages through a local bridge;
+- keep the unpacked extension path for developers and npm installs;
+- avoid narrowing permissions until there is a tested replacement path;
+- explain broad permissions honestly before any store submission.
+
+## Official Policy Baseline
+
+The store-facing baseline for this project is:
+
+- Chrome permissions must be declared in the manifest, and some permissions
+  trigger install warnings. The current `debugger` permission is especially
+  sensitive because Chrome warns that it can access the page debugger backend
+  and read/change site data.
+- Chrome Web Store policy expects a narrow, easy-to-understand single purpose,
+  minimum permissions, and user-data use limited to the disclosed purpose.
+- Chrome Web Store privacy disclosures must match the extension behavior and
+  privacy policy, especially when handling page content, browsing activity,
+  request data, screenshots, or form data.
+- Edge Add-ons policy similarly requires permissions only when necessary for
+  the declared functionality, plus a privacy policy link and store metadata.
+- Edge Add-ons submission requires a zip package, required visual assets, a
+  listing description, and a privacy policy link.
+
+References:
+
+- Chrome permissions reference:
+  https://developer.chrome.com/docs/extensions/reference/permissions-list
+- Chrome permission declaration guide:
+  https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions
+- Chrome Web Store program policies:
+  https://developer.chrome.com/docs/webstore/program-policies/policies
+- Chrome Web Store Limited Use policy:
+  https://developer.chrome.com/docs/webstore/program-policies/limited-use
+- Microsoft Edge extensions overview and publishing requirements:
+  https://learn.microsoft.com/en-us/microsoft-edge/extensions/
+- Microsoft Edge Add-ons developer policies:
+  https://learn.microsoft.com/en-us/legal/microsoft-edge/extensions/developer-policies
+
+## Current Manifest Audit
+
+Current file: `extension/manifest.json`.
+
+| Manifest field | Current value | Why Yunti uses it | Store risk | P6.6.1 decision |
+| --- | --- | --- | --- | --- |
+| `manifest_version` | `3` | Required modern extension format. | Low. | Keep. |
+| `permissions.activeTab` | present | Visible-tab capture fallback and temporary page access semantics. | Low to medium; generally narrower than persistent host access. | Keep. |
+| `permissions.debugger` | present | CDP commands, target-level automation, console/runtime/network events, and low-level recovery. | High. Chrome shows a debugger warning and reviewers may ask why this is core. | Keep for now; store copy must explain this is the core browser automation transport. |
+| `permissions.scripting` | present | Programmatically inject packaged content scripts into already-open supported pages after extension load or recovery. | Medium with broad host access; reviewers may ask why dynamic injection is needed. | Keep for developer/npm path so install does not require manual page refresh; explain it as recovery/registration, not arbitrary remote code execution. |
+| `permissions.storage` | present | Local bridge URL, optional token, user id/name, and page match settings. | Low. | Keep. |
+| `permissions.tabs` | present | Tab inventory, active tab selection, switching, and metadata routing. | Medium. Chrome may warn about browsing history. | Keep for now; evaluate whether any read paths can use host/activeTab data later. |
+| `permissions.webRequest` | present | Sanitized network diagnostics and request observation. | Medium to high with broad hosts. | Keep for now; P6.6.2 should evaluate optionalizing network diagnostics. |
+| `host_permissions` | `http://*/*`, `https://*/*` | Register and operate arbitrary user-selected http/https pages. | High because it maps to broad site access. | Keep for developer/npm path; store submission must decide broad access vs optional/site-request flow. |
+| `host_permissions` | `http://127.0.0.1/*`, `http://localhost/*` | Local bridge communication. | Low but should be explained as local-only bridge access. | Keep. |
+| `content_scripts.matches` | `http://*/*`, `https://*/*` | Observe and act on arbitrary web pages once loaded. | High because content scripts imply broad page access. | Keep for now; evaluate `optional_host_permissions` or user-triggered site access later. |
+
+## Store Submission Checklist
+
+Required before submitting to either store:
+
+- Store description with one clear purpose:
+  "Local browser runtime that lets user-authorized AI agents inspect and
+  operate the user's own Chrome/Edge pages through a local bridge."
+- Permission rationale for every manifest permission above.
+- Privacy policy page that states:
+  - no hosted Yunti service is used in the default install path;
+  - observations are sent only to the local bridge on loopback by default;
+  - screenshots are visible pixels and may contain sensitive content;
+  - raw CDP diagnostics are a low-level exception and should be cleared;
+  - learning memory is local filesystem data;
+  - network/console/memory text is sanitized before storage or display;
+  - users can remove the extension and clear local memory.
+- Store privacy/data disclosure answers aligned with `docs/SECURITY.md`.
+- Visual assets:
+  - extension icon set for store and manifest;
+  - at least one screenshot of the optional local console;
+  - at least one screenshot or diagram of the extension popup zero-config state;
+  - optional short demo media showing local bridge + extension + agent workflow.
+- Package artifact:
+  - `npm run package-extension` zip;
+  - package/manifest version consistency verified by `npm run release:check`;
+  - no local-only residue in public docs.
+- Review notes:
+  - explain why `debugger` is core to browser automation;
+  - explain why broad host access exists in the developer/npm path;
+  - document the local-only bridge and no hosted relay default.
+
+## Permission Narrowing Options
+
+These are follow-up options, not P6.6.1 changes:
+
+| Option | Benefit | Cost / risk |
+| --- | --- | --- |
+| Keep broad host permissions for store release | Preserves current one-step operation after install. | Highest review and user-trust burden. |
+| Move broad hosts to optional host permissions | Better minimum-permission story. | Requires new UX for granting host access and robust recovery when not granted. |
+| Use `activeTab` for a user-invoked page grant path | Much smaller default warning surface. | Breaks always-on agent operation unless redesigned around explicit user gestures. |
+| Make network diagnostics optional | Reduces review surface for users who only need DOM actions. | Splits tool availability and recovery guidance; needs schema/tool hint updates. |
+| Keep unpacked-only for 0.2.0 and defer store listing | Avoids premature permission compromises. | Users still manually load the extension. |
+
+Recommended next slice: keep current manifest behavior, but draft store-facing
+permission and privacy copy. Then decide whether `webRequest` and broad hosts
+should become optional before a real store submission.
+
+## Store Copy Draft
+
+P6.6.2 store-facing copy is tracked in
+[EXTENSION_STORE_COPY.md](EXTENSION_STORE_COPY.md). It contains draft short and
+long descriptions, permission rationale, privacy-policy text, store data
+disclosure guidance, reviewer notes, and the final review checklist.
+
+## Permission Strategy Decision
+
+P6.6.3 pre-store permission strategy is tracked in
+[EXTENSION_PERMISSION_STRATEGY.md](EXTENSION_PERMISSION_STRATEGY.md). The
+current decision keeps the npm/unpacked developer path unchanged, does not
+recommend submitting the current broad-permission manifest unchanged by default,
+and defines a future store-candidate track for optional host access and optional
+network diagnostics.
+
+## Current P6.6.1 Outcome
+
+P6.6.1 completes when this audit is linked from public docs and the status files
+identify the next store-readiness slice. It does not change extension runtime
+behavior.
+
+## Current P6.6.2 Outcome
+
+P6.6.2 completes when the draft store copy pack is available and linked from
+this distribution readiness audit. It does not change extension runtime
+behavior or the submitted manifest strategy.
+
+## Current P6.6.3 Outcome
+
+P6.6.3 completes when the permission strategy decision is available and linked
+from this distribution readiness audit. It does not change extension runtime
+behavior or `extension/manifest.json`.

package/docs/EXTENSION_PERMISSION_STRATEGY.md

@@ -0,0 +1,167 @@
+# Extension Permission Strategy
+
+This document is the P6.6.3 pre-store permission strategy decision for Yunti
+Browser Runtime. It turns the manifest audit and store-copy draft into a clear
+product decision before any browser-store implementation work.
+
+## Decision Summary
+
+Yunti will keep the current npm/unpacked extension path unchanged for the
+current `0.2.0` development cycle:
+
+- broad `http` / `https` host access remains acceptable for the local developer
+  and npm-installed extension path;
+- `webRequest` remains available by default for local diagnostics;
+- `debugger`, `scripting`, `tabs`, screenshots, CDP, network, console, upload, and tab
+  capabilities remain part of Yunti's core local browser automation surface;
+- the current manifest should not be submitted to Chrome Web Store or Edge
+  Add-ons as the recommended store build without an explicit maintainer
+  decision.
+
+The recommended store-candidate direction is a two-track model:
+
+- **Developer/npm track**: preserve today's zero-config, broad-access local
+  runtime for users who intentionally install Yunti as a browser automation
+  tool.
+- **Store-candidate track**: design and test a lower-warning permission mode
+  before submission, likely using optional host access and optional network
+  diagnostics where the browser APIs and Yunti UX can support it reliably.
+
+This is a decision checkpoint, not a manifest rewrite.
+
+## Why This Decision
+
+Yunti's core product promise is real local browser automation for arbitrary
+user-opened Chrome/Edge pages. The current broad permissions support that
+promise: an agent can observe, click, fill, scroll, inspect diagnostics, switch
+tabs, and recover through CDP without forcing the user to grant site access on
+every page first.
+
+However, browser stores evaluate extension trust differently from a local
+developer install:
+
+- Chrome recommends optional permissions when functionality allows it, so users
+  get informed control over resource and data access.
+- Chrome permission and host declarations can trigger user-visible install
+  warnings.
+- Edge policy says extensions should request only permissions essential for the
+  declared functionality, and must clearly disclose dependency on non-integrated
+  software and testing steps.
+- Yunti's current `debugger`, `scripting`, broad host access, `tabs`, and `webRequest`
+  combination is truthful for a browser automation runtime, but it is also the
+  highest-review-burden shape.
+
+The safest product path is therefore:
+
+1. Do not weaken the local Yunti experience just to reduce store warnings.
+2. Do not submit a broad-permission store build casually.
+3. Build a store-candidate mode only after the permission UX and recovery
+   behavior are designed and tested.
+
+## Decision Matrix
+
+| Option | Decision | Reason |
+| --- | --- | --- |
+| Submit current manifest unchanged to stores | Not recommended by default. | It preserves functionality, but broad host access plus `debugger` and `webRequest` creates high reviewer and user-trust burden. |
+| Remove broad host permissions immediately | Rejected for now. | It would break the current zero-config observe/action workflow unless a replacement permission UX is implemented first. |
+| Make `webRequest` optional before store submission | Recommended for design/prototype. | Network diagnostics are valuable but not required for every click/fill/scroll workflow. Optionalizing them may reduce review surface. |
+| Move broad web access to optional host permissions | Recommended for design/prototype. | Better aligns with user-controlled access, but needs UX, content-script registration/injection changes, recovery guidance, and tests. |
+| Keep npm/unpacked as the only 0.2.0 distribution path | Acceptable fallback. | Preserves the core product while avoiding premature store compromises. |
+
+## Permission Strategy
+
+### Developer / npm Track
+
+Keep current behavior:
+
+- `permissions`: `activeTab`, `debugger`, `scripting`, `storage`, `tabs`, `webRequest`.
+- `host_permissions`: `http://*/*`, `https://*/*`, localhost bridge access.
+- Static content scripts for `http` / `https` pages.
+- Programmatic injection for already-open supported pages after extension load,
+  startup, bridge recovery, or target inventory refresh.
+- Popup remains zero-config by default.
+- Advanced page match patterns remain a runtime registration filter, not a
+  browser permission boundary.
+
+This track is the default for local users who intentionally install the runtime
+from npm and load the extension from the package directory.
+
+### Store-Candidate Track
+
+Do not implement this until the next slice has a concrete design. The target
+shape should evaluate:
+
+- `optional_host_permissions` for broad `http` / `https` page access.
+- A first-run or popup flow that clearly requests access for the current site
+  or all sites, without becoming a mandatory hub.
+- Recovery messages when the agent cannot observe a page because host access
+  has not been granted.
+- Whether content scripts should remain declarative, be dynamically registered,
+  or be injected after permission grant.
+- Optionalizing network diagnostics so `webRequest` is requested only when the
+  user enables debugging.
+- Whether `debugger` can remain required for the store candidate, with strong
+  single-purpose justification, or whether some workflows can operate before
+  debugger attachment.
+
+The store-candidate track must remain additive. It must not remove the
+developer/npm track or narrow Yunti into a page-only automation tool.
+
+## Required UX Before Store Submission
+
+Before any store build with narrowed permissions:
+
+- Popup should show a clear "grant access for this site" or equivalent action
+  when the current page is blocked by missing host permission.
+- Agent-facing errors should say whether the page is unavailable because host
+  permission is missing, the bridge is offline, the page is unsupported, or the
+  browser blocked automatic injection.
+- Tool hints and the packaged skill should explain how to recover:
+  `open page -> grant site access -> yunti_list_browser_targets`, with page
+  refresh only as a fallback.
+- Optional network diagnostics should be visibly separate from basic DOM
+  automation.
+- `doctor` should detect permission-mode problems and provide a human-readable
+  next step.
+
+## Required Engineering Work Before Store Submission
+
+If the store-candidate track proceeds, the next implementation slices should be
+small and testable:
+
+1. Add a permission-mode design/prototype for host access.
+2. Add a diagnostics-mode design/prototype for `webRequest`.
+3. Update extension popup state and background registration flow.
+4. Update MCP errors, `yunti_get_tool_usage_hints`, Tool Guide, and packaged
+   skill for missing-permission recovery.
+5. Add deterministic extension tests for permission-denied and permission-
+   granted paths.
+6. Add real-browser E2E coverage for:
+   - page blocked before host grant;
+   - grant access;
+   - auto-register existing pages;
+   - observe/action success;
+   - optional diagnostics enabled/disabled.
+7. Update store copy and privacy text after the final manifest strategy is
+   known.
+
+## Store Readiness Gate
+
+A browser-store submission should not proceed until all of these are true:
+
+- final manifest permissions match the submitted store copy;
+- privacy policy URL is published and matches runtime behavior;
+- support URL and reviewer test steps are confirmed;
+- screenshots use non-sensitive demo pages;
+- `npm run release:check` passes;
+- real-browser E2E passes with the submitted extension package;
+- no local token, private path, unpublished account detail, or internal-only
+  URL appears in store metadata;
+- maintainer explicitly accepts the remaining `debugger` and host-access
+  warnings.
+
+## P6.6.3 Outcome
+
+P6.6.3 completes when this decision is linked from distribution readiness docs
+and status files. It does not change `extension/manifest.json` or runtime
+behavior.

package/docs/EXTENSION_STORE_COPY.md

@@ -0,0 +1,213 @@
+# Extension Store Copy Draft
+
+This document is the P6.6.2 draft copy pack for future Chrome Web Store and
+Microsoft Edge Add-ons submissions. It is written as reviewable product copy and
+reviewer notes, not as a final legal policy.
+
+Current status: draft for maintainer review. Do not submit this text to a store
+until the maintainer has confirmed the final permission strategy, privacy-policy
+URL, support URL, screenshots, and test instructions.
+
+The current pre-store permission strategy decision is tracked in
+`docs/EXTENSION_PERMISSION_STRATEGY.md`. Store copy must be reviewed again after
+any manifest or permission-mode change.
+
+## Policy Baseline
+
+This copy follows the browser-store principles recorded in
+`docs/EXTENSION_DISTRIBUTION.md`:
+
+- Chrome extension permissions, host permissions, and content script matches
+  must be declared in the manifest. Some permissions and match patterns can
+  trigger install warnings.
+- Chrome recommends optional permissions when the feature can support runtime
+  user grants.
+- Chrome Web Store policy expects user data use to be limited to the disclosed
+  single purpose and the narrowest permissions needed for implemented features.
+- Edge Add-ons policy expects the extension to request only permissions
+  essential for functioning, clearly disclose data handling, and maintain a
+  relevant privacy policy.
+
+Official references:
+
+- Chrome permission declaration:
+  https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions
+- Chrome Web Store program policies:
+  https://developer.chrome.com/docs/webstore/program-policies/policies
+- Chrome Web Store Limited Use policy:
+  https://developer.chrome.com/docs/webstore/program-policies/limited-use
+- Microsoft Edge Add-ons developer policies:
+  https://learn.microsoft.com/en-us/legal/microsoft-edge/extensions/developer-policies
+
+## One-Sentence Purpose
+
+Local browser runtime that lets user-authorized AI agents inspect and operate
+the user's own Chrome or Edge pages through a local MCP bridge.
+
+## Short Description
+
+Yunti Browser Runtime connects MCP-capable AI agents to the user's local
+Chrome/Edge browser so the agent can inspect pages, click, type, switch tabs,
+capture screenshots, and read sanitized diagnostics through a local bridge.
+
+## Long Description Draft
+
+Yunti Browser Runtime is a local-first browser automation extension for users
+who want MCP-capable AI agents to operate their own Chrome or Edge pages.
+
+The extension connects pages in the user's browser to a local bridge running on
+the user's machine. Agents can then inspect the active page, click, type,
+select, scroll, switch tabs, capture screenshots when needed, and read sanitized
+network or console diagnostics. The default install path does not use a hosted
+Yunti service.
+
+Yunti is designed for explicit user-directed automation. The user installs the
+runtime, loads or installs the extension, starts an MCP-capable agent, and keeps
+control of which browser pages are open. The extension popup shows connection
+status and keeps advanced settings, such as a custom bridge URL or optional
+token, out of the default first-run path.
+
+The extension needs broad browser access because browser automation must work
+on user-selected websites, tabs, and application pages. Sensitive diagnostics
+are minimized by default: page observation redacts credential-like values,
+network and console summaries are sanitized before storage or display, and raw
+CDP diagnostics are a low-level debugging exception that should be cleared after
+use. Screenshots are real visible page pixels and may contain sensitive content,
+so agents should request or use them only when visual evidence is needed.
+
+## Permission Rationale Draft
+
+Use this table as the source for Chrome Web Store permission justification,
+Edge certification notes, and any public privacy-policy explanation.
+
+| Manifest item | User-facing reason | Reviewer-facing detail | Keep / decide |
+| --- | --- | --- | --- |
+| `activeTab` | Allows temporary access to the visible tab for user-directed capture and fallback operations. | Used as a narrower visible-tab fallback where possible. It does not replace persistent access needed for the current automation workflow. | Keep. |
+| `debugger` | Enables the local agent to control the user's browser tab through the browser's debugging protocol. | Core transport for CDP commands, target routing, console/runtime diagnostics, screenshots, and low-level recovery. This is high-sensitivity and must be explained as the product's primary browser automation mechanism. | Keep for current developer path; re-review before store submission. |
+| `scripting` | Lets the extension inject its packaged content scripts into supported pages that were already open before the extension loaded. | Used for automatic page registration and recovery after install, browser startup, or background service worker restart. It does not execute remote code. | Keep for current developer path so users do not need to refresh pages by default; re-review before store submission. |
+| `storage` | Saves local extension settings such as bridge URL, optional token, user id/name, and page match settings. | Stores local configuration only. It is not used for hosted sync by default. | Keep. |
+| `tabs` | Lets the agent list and switch the user's open browser tabs. | Needed for tab inventory, target selection, activation, and routing metadata. Store copy should explain that tab metadata is used only for user-directed local automation. | Keep for current workflow; evaluate narrower alternatives later. |
+| `webRequest` | Lets the runtime provide sanitized network diagnostics when debugging page automation. | Used for observation and diagnostics, not ad blocking or request modification. Because this combines with broad hosts, consider making network diagnostics optional in a later slice. | Keep for developer path; P6.6.3 should decide optionalization. |
+| `host_permissions` for `http://*/*` and `https://*/*` | Lets the extension work on the web pages the user wants the agent to operate. | Broad host access supports arbitrary user-selected business apps, websites, and local workflows. This has the highest trust and review burden. Store submission must choose between broad access and an optional/site-grant UX. | Decision required before store submission. |
+| `host_permissions` for `http://127.0.0.1/*` and `http://localhost/*` | Lets the extension communicate with the local bridge on the user's machine. | Required for local loopback communication. The default bridge URL is `http://127.0.0.1:48887`; no hosted relay is used by default. | Keep. |
+| `content_scripts.matches` for `http://*/*` and `https://*/*` | Lets the extension observe and act on user-selected web pages. | Required for DOM observation, fresh element ids, click/fill/select/scroll actions, and page registration. Consider optional host permission UX before a store release if broad install-time warnings are unacceptable. | Decision required before store submission. |
+
+## Privacy Policy Draft
+
+Yunti Browser Runtime is local-first software. In the default install path, the
+extension communicates with a bridge on the user's own machine at
+`http://127.0.0.1:48887`. Yunti does not provide a hosted relay service in the
+default install path.
+
+The extension may access page content, page titles, URLs, tab metadata, visible
+page pixels in screenshots, console messages, and network request metadata when
+the user directs an MCP-capable agent to inspect or operate browser pages. This
+access is used to provide the single purpose of local browser automation.
+
+The runtime minimizes sensitive data exposure where possible. Structured page
+observation redacts credential-like values by default and supports stricter
+redaction for likely personal information. Network URLs, headers, request
+bodies, console messages, learning-memory text, and diagnostic summaries are
+sanitized before storage or display. Cookies and raw authorization headers are
+not returned by the documented network tools.
+
+Screenshots are real visible page pixels and may contain sensitive information.
+Raw CDP diagnostics are a low-level debugging exception and may contain
+sensitive payloads. Users and agents should prefer sanitized observations and
+diagnostics, use screenshots and raw CDP only when needed, and clear raw CDP
+diagnostics after debugging.
+
+Learning memory, if used, is stored on the local filesystem under the user's
+Yunti data directory. Users can delete local learning memory and can remove the
+browser extension at any time.
+
+Yunti Browser Runtime does not intentionally collect data for advertising,
+profiling, resale, or cross-site tracking. External agents that call Yunti MCP
+tools may have their own data handling policies; users should review the agent
+they choose to connect.
+
+## Store Data Disclosure Draft
+
+These answers are draft guidance for store forms. Final answers must match the
+actual submitted build and privacy policy.
+
+| Data surface | Accessed? | Stored by Yunti by default? | Sent to hosted Yunti service? | Draft disclosure |
+| --- | --- | --- | --- | --- |
+| Page content / DOM text | Yes, when an agent observes or operates a page. | No persistent DOM storage by default. | No. | Used only for local browser automation and redacted by default for credential-like values. |
+| URLs and tab titles | Yes. | May appear in sanitized runtime summaries or local diagnostics. | No. | Used for tab selection, routing, and user-visible diagnostics. |
+| Screenshots | Yes, when requested by an agent/tool. | Not persisted by the extension by default. | No hosted Yunti service by default. | Visible pixels may contain sensitive content; use only when visual inspection is needed. |
+| Network diagnostics | Yes, for pages where the extension is active. | Sanitized summaries may be cached locally in memory. | No. | Used to debug page automation; cookies and raw authorization headers are not returned by documented tools. |
+| Console diagnostics | Yes. | Sanitized summaries may be cached locally in memory. | No. | Used to debug page automation and JavaScript errors. |
+| Learning memory | Optional MCP feature. | Yes, local filesystem only when the user/agent writes memory. | No. | Sanitized before disk writes; users can delete memory. |
+| Bridge settings | Yes. | Yes, in extension local storage. | No. | Stores bridge URL, optional token, user id/name, and page-match settings. |
+
+## Reviewer Notes Draft
+
+Yunti Browser Runtime depends on local software outside the extension: an MCP
+server and bridge installed through npm. The extension is not useful by itself;
+it is the browser-side component for the local runtime. Submission notes should
+include install and test steps:
+
+1. Install Node.js 22 or newer.
+2. Install the runtime package.
+3. Start or configure an MCP-capable agent so it launches the local bridge.
+4. Install the extension build.
+5. Open or keep an `http` or `https` page; the extension auto-registers
+   accessible pages and only needs a refresh if browser restrictions prevent
+   injection.
+6. Run `yunti-browser-runtime doctor`.
+7. Verify that the extension shows a connected page and that MCP tools can list
+   browser targets.
+
+Reviewer explanation for broad access:
+
+```text
+Yunti Browser Runtime is a local browser automation runtime. Its single purpose
+is to let a user-authorized MCP agent inspect and operate the user's own
+Chrome/Edge pages through a local bridge. Broad web access is currently required
+because the user may ask the agent to operate arbitrary websites and business
+applications that are already open in the browser. The default path does not use
+a hosted Yunti service; observations route to the local bridge on loopback.
+```
+
+Reviewer explanation for `debugger`:
+
+```text
+The debugger permission is part of the core automation transport. It lets the
+runtime use Chrome DevTools Protocol for target routing, tab-level automation,
+screenshots, console/runtime diagnostics, and low-level recovery. The extension
+does not use debugger access for advertising, profiling, or unrelated browsing
+history collection.
+```
+
+Reviewer explanation for local bridge dependency:
+
+```text
+The extension communicates with local software running on the user's own
+machine, normally at http://127.0.0.1:48887. This local bridge is installed as
+part of yunti-browser-runtime and is required for the extension's primary
+browser automation function.
+```
+
+## Final Review Checklist
+
+Before store submission:
+
+- Confirm whether broad `http` / `https` host access remains in the submitted
+  manifest or moves to optional host permissions.
+- Confirm whether `webRequest` remains always-on or becomes an optional
+  diagnostics feature.
+- Confirm the submitted build follows the accepted strategy in
+  `docs/EXTENSION_PERMISSION_STRATEGY.md`.
+- Confirm the final privacy-policy URL and support URL.
+- Confirm screenshots do not expose real private browser data.
+- Confirm all store form answers match the submitted manifest and package.
+- Confirm reviewer test steps work on a clean machine.
+- Confirm no npm token, local path, private account, or unpublished internal
+  detail appears in public store metadata.
+
+## P6.6.2 Outcome
+
+P6.6.2 is complete when this copy pack is linked from distribution readiness
+docs and status files. It intentionally does not change the extension manifest
+or runtime behavior.

package/docs/INSTALL.md

@@ -63,7 +63,8 @@ Development loading:
 2. Enable developer mode.
 3. Choose "Load unpacked".
 4. Select the project `extension/` directory.
-5. Open or refresh any `http` or `https` page.
+5. Open or keep any `http` or `https` page. The extension automatically tries
+   to inject and register accessible existing pages.
 6. Do not open the extension popup unless you want to confirm status or
    customize settings.
 
@@ -150,8 +151,9 @@ npm run print-config -- --agent cline --human
 ```
 
 Add the printed server entry to Cline's MCP settings. Keep the extension loaded
-in Chrome/Edge and refresh the target page so the content script registers a
-fresh `browserSessionId`.
+in Chrome/Edge. The extension should register accessible `http`/`https` pages
+automatically; refresh the target page only if browser restrictions or a failed
+doctor check make it necessary.
 
 ## Check Health
 
@@ -187,7 +189,9 @@ runs the unit test suite, and verifies the npm package contents with
 
 ## Common Recovery
 
-- If tools say no browser tab is connected, refresh the target page.
+- If tools say no browser tab is connected, call `yunti_list_browser_targets`
+  or run doctor first; the extension will try to auto-register accessible pages.
+  Refresh the target page only as a fallback.
 - If doctor reports `authorized: false` with `authRequired: true`, set
   `YUNTI_BROWSER_BRIDGE_TOKEN` and save the same token in the extension popup.
 - If an old `browserSessionId` fails, call `yunti_list_browser_targets` again
@@ -198,8 +202,9 @@ runs the unit test suite, and verifies the npm package contents with
   is rejected.
 - For closing a raw `tabId` or `targetId`, use `yunti_cdp_send_command` with
   `Target.closeTarget` instead of `yunti_close_page`.
-- If the extension was reloaded, refresh browser pages so the content script can
-  register again.
+- If the extension was reloaded, it should scan and register accessible pages
+  automatically. Refresh browser pages only if the page cannot be injected or
+  remains invisible after the recovery check.
 
 ## Real Browser Smoke Test
 
@@ -212,6 +217,7 @@ YUNTI_E2E=1 npm run test:e2e
 
 It uses Playwright with a persistent Chromium profile, loads the unpacked
 extension, starts a local test page, starts the bridge, and verifies MCP list
-targets, page snapshot, click/fill, and CDP `Runtime.evaluate`. Install
+targets, page snapshot, `observe -> click uid -> verify`, fill, and CDP
+`Runtime.evaluate`. Install
 Playwright and Chromium before enabling it. Failures print the artifact
 directory containing screenshot and error log paths.