yunti-browser-runtime 0.1.0

package/docs/INSTALL.md

@@ -0,0 +1,205 @@
+# Install Guide
+
+## Requirements
+
+- Node.js 22 or newer.
+- Chrome, Edge, or another Chromium browser with extension developer mode.
+- An MCP-capable agent.
+
+## Start The Local Bridge
+
+From the project root:
+
+```bash
+npm install
+npm run bridge
+```
+
+By default the bridge listens on:
+
+```text
+http://127.0.0.1:48887
+```
+
+Use a custom port when needed:
+
+```bash
+YUNTI_BROWSER_BRIDGE_PORT=48999 npm run bridge
+```
+
+bridge 会在启动时读取或生成本地访问 token，并把请求头名称和值打印到 stderr。
+推荐在 MCP、doctor 和扩展里使用同一个显式 token：
+
+```bash
+YUNTI_BROWSER_BRIDGE_TOKEN="$(openssl rand -hex 24)" npm run bridge
+```
+
+需要自定义允许的 CORS 来源时：
+
+```bash
+YUNTI_BROWSER_BRIDGE_ALLOW_ORIGINS="http://127.0.0.1,http://localhost,chrome-extension://*" npm run bridge
+```
+
+When installed as an npm package, the equivalent CLI command is:
+
+```bash
+yunti-browser-runtime bridge
+```
+
+## Load The Extension
+
+Development loading:
+
+1. Open `chrome://extensions` or `edge://extensions`.
+2. Enable developer mode.
+3. Choose "Load unpacked".
+4. Select the project `extension/` directory.
+5. Click the extension icon and save the same bridge token printed by the bridge.
+6. Open any `http` or `https` page and click the extension icon to confirm the
+   page is connected.
+
+The extension registers browser pages with the local bridge. It does not create
+agent conversations or depend on a remote workspace.
+
+To create a distributable zip:
+
+```bash
+npm run package:extension
+```
+
+The package is written to `dist/yunti-browser-runtime-extension-<version>.zip`
+and contains only the extension runtime files.
+
+## Register MCP
+
+Print the MCP server configuration for your agent, then add it to your agent
+configuration:
+
+```bash
+npm run print-config
+npm run print-config -- --agent codex --human
+npm run print-config -- --agent claude-code --human
+npm run print-config -- --agent cursor --human
+npm run print-config -- --agent cline --human
+```
+
+The stdio MCP server starts or reuses the local bridge automatically. Running
+`npm run bridge` manually is useful for debugging, but not always required by
+agents that launch the MCP server themselves.
+
+### Agent Examples
+
+These examples intentionally use `npm run print-config` instead of hard-coded
+local paths. Copy the JSON printed by the command into the matching agent's MCP
+configuration file or UI.
+
+#### Codex
+
+```bash
+npm run print-config -- --agent codex --human
+```
+
+Then install the browser skill if your Codex setup supports skills:
+
+```bash
+mkdir -p ~/.codex/skills
+cp -R skills/yunti-browser-runtime ~/.codex/skills/
+```
+
+Start a new Codex session after adding the MCP server and skill. For browser
+tasks, the session should call `yunti_get_tool_usage_hints` first, then
+`yunti_list_browser_targets`.
+
+#### Claude Code
+
+```bash
+npm run print-config -- --agent claude-code --human
+```
+
+Add the printed `mcpServers.yunti-browser-runtime` block to Claude Code's MCP
+configuration. If using a bridge token, set `YUNTI_BROWSER_BRIDGE_TOKEN` in the
+same environment Claude Code uses to launch the MCP server, and save the same
+token in the extension popup.
+
+#### Cursor
+
+```bash
+npm run print-config -- --agent cursor --human
+```
+
+Add the printed `mcpServers` JSON to Cursor's MCP configuration. Restart or
+reload Cursor after saving the config, then run `npm run doctor` from this
+project to confirm the bridge and extension are healthy.
+
+#### Cline
+
+```bash
+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`.
+
+## Check Health
+
+```bash
+npm run doctor
+```
+
+Or through the package CLI:
+
+```bash
+yunti-browser-runtime doctor
+```
+
+Expected JSON output includes `ok: true` when the local setup is healthy.
+The command also prints a human-readable summary to stderr. If an agent needs
+machine-only output, run:
+
+```bash
+npm run doctor:json
+```
+
+## Release Check
+
+Before publishing or sharing a release candidate, run:
+
+```bash
+npm run release:check
+```
+
+This command checks public docs for local/internal residue, runs syntax checks,
+runs the unit test suite, and verifies the npm package contents with
+`npm pack --dry-run`.
+
+## Common Recovery
+
+- If tools say no browser tab is connected, refresh the target page.
+- If doctor reports `authorized: false`, 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
+  and use the latest returned session.
+- If a parameter error appears, call `yunti_get_tool_usage_hints` with the
+  failed tool name before retrying.
+- For `yunti_fill`, pass `value` plus `uid` or `selector`; coordinate-only fill
+  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.
+
+## Real Browser Smoke Test
+
+The real-browser E2E smoke test is opt-in so regular CI and local checks can run
+without launching a browser:
+
+```bash
+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
+Playwright and Chromium before enabling it. Failures print the artifact
+directory containing screenshot and error log paths.

package/docs/PROJECT_INTENT.md

@@ -0,0 +1,44 @@
+# Project Intent
+
+## Why This Project Exists
+
+Modern agents can reason well, but browser operation is still fragile when each
+agent invents its own automation path. Yunti Browser Runtime exists to provide a
+shared local browser operation layer that any agent can call through MCP.
+
+The project starts from a practical internal browser agent implementation and
+extracts the reusable foundation:
+
+- discover local browser tabs and targets;
+- inspect page state;
+- execute clicks, input, screenshots, file uploads, and navigation;
+- send Chrome DevTools Protocol commands;
+- capture network, console, and CDP observations;
+- keep multi-step operations routed to the intended browser page.
+
+## Design Principles
+
+- Local first: the first version runs on the user's own machine.
+- Simple deployment: install dependencies, load the extension, register MCP.
+- Fast execution: avoid heavyweight browser re-launches when the user's browser
+  is already open.
+- Agent agnostic: Claude Code, Codex, Cursor, Cline, OpenCode, and other MCP
+  clients should be able to use the same runtime.
+- Explicit safety: dangerous writes, downloads, uploads, and form submissions
+  should be visible to the agent and user.
+- No platform lock-in: the runtime must not depend on any company-internal
+  platform.
+
+## First Release Boundary
+
+The first release is a local single-user runtime:
+
+- one local bridge;
+- one user's browser extension;
+- local-only browser sessions;
+- no remote relay;
+- no multi-user server;
+- no shared market, skills, or workspace concepts.
+
+Remote multi-user deployment can be designed later as a separate layer. The
+local runtime should stay small and dependable.

package/docs/PROJECT_STATUS.md

@@ -0,0 +1,263 @@
+# Project Status
+
+## Current Phase
+
+Release readiness: local MVP is prepared for first public release. P4.19 formal
+npm publish is in progress and currently blocked only by npm two-factor
+authentication OTP.
+
+## Current State
+
+- Project directory created.
+- Project intent, install, tool, security, roadmap, and status docs exist.
+- Local-first architecture selected.
+- MCP server, local bridge, extension, runtime path helper, doctor command, and
+  bridge tests have been extracted.
+- A distributable agent skill exists at
+  `skills/yunti-browser-runtime/SKILL.md`.
+- README is Chinese-first and includes browser extension setup, MCP registration,
+  and agent skill installation steps.
+- A staged execution plan exists at `docs/EXECUTION_PLAN.md`.
+- Tool prefix is `yunti_*`.
+- MCP local mode defaults to `userId=local`.
+- Bridge HTTP routes now require `x-yunti-browser-token`; unauthenticated
+  `/health` only returns limited status.
+- Bridge CORS now echoes only local debug origins and browser extension origins
+  by default, with `YUNTI_BROWSER_BRIDGE_ALLOW_ORIGINS` as an override.
+- Extension popup can save the local bridge URL, token, and page match patterns.
+- Browser sessions now track `lastSeenAt`, `lastActivatedAt`, `expiresAt`, and
+  `staleReason`; extension polling refreshes heartbeat and expired sessions are
+  cleaned up with recovery guidance.
+- `npm run doctor` now checks Node version, bridge reachability, token validity,
+  registered sessions, active session, extension presence, MCP server path, and
+  skill path; it emits JSON plus a human-readable summary.
+- `npm run print-config` prints MCP configuration for Codex, Claude Code,
+  Cursor, and Cline, including project paths, bridge port, token guidance, and
+  skill installation hints.
+- `npm run package:extension` writes a minimal extension zip to `dist/` with
+  only extension runtime files.
+- `npm run release:dry-run` and `npm run release:publish` pin the official npm
+  registry at `https://registry.npmjs.org/`, avoiding accidental publication to
+  a locally configured mirror registry.
+- `npm run test:e2e` provides an opt-in real-browser Playwright smoke test for
+  extension loading, page registration, MCP target listing, snapshot, click/fill,
+  and CDP `Runtime.evaluate`.
+- Package metadata now includes bin, files, repository, keywords, homepage,
+  bugs, and packageManager fields. The `yunti-browser-runtime` CLI routes
+  `mcp`, `bridge`, `doctor`, `print-config`, and `package-extension`.
+- MCP tool schemas and usage hints have been split into `mcp/tools.js` so
+  `mcp/server.js` is focused on bridge, routing, and JSON-RPC behavior.
+- MCP JSON-RPC response wrappers, redaction/event normalization helpers, and
+  learning memory storage have been split into `mcp/json-rpc.js`,
+  `mcp/redaction.js`, and `mcp/memory.js`.
+- MCP session hub, request queueing, network/CDP/console event caches, and
+  bridge-local tool routing have been split into `mcp/bridge-hub.js`, while
+  `mcp/server.js` keeps compatibility re-exports.
+- MCP HTTP bridge server, CORS/token checks, route handlers, and body parsing
+  have been split into `mcp/http-server.js`, while `mcp/server.js` keeps
+  compatibility re-exports.
+- Extension settings/page matching and network monitoring have been split into
+  `extension/settings.js` and `extension/network-monitor.js`, and the extension
+  package script includes those module files.
+- Extension CDP target routing, debugger attach/detach, and tracing helpers
+  have been split into `extension/cdp.js`, and the extension package script
+  includes the module file.
+- Extension session registration, polling, popup state, bridge posting, and
+  console event forwarding have been split into `extension/session-manager.js`,
+  and the extension package script includes the module file.
+- Extension tool dispatch and page operation handlers have been split into
+  `extension/tool-handlers.js`, and the extension package script includes the
+  module file.
+- P3.2 tool argument validation is complete for `yunti_click`, `yunti_hover`,
+  `yunti_fill`, `yunti_close_page`, `yunti_cdp_send_command`, and
+  `yunti_forget_learning_memory`, with recovery-oriented errors and updated
+  usage hints.
+- `docs/TOOL_GUIDE.md` and `skills/yunti-browser-runtime/SKILL.md` now document
+  the common P3.2 parameter rules.
+- README and INSTALL now include P3.2 parameter recovery guidance.
+- SECURITY now documents `storage` permission usage and broad host permission
+  rationale for the local-first extension.
+- INSTALL now includes Codex, Claude Code, Cursor, and Cline MCP setup examples
+  based on `npm run print-config`.
+- Extension registers all `http` and `https` pages by default.
+- Product-specific fixed conversation, workspace, and side-panel entry points
+  have been removed from the standalone extension.
+
+## Decisions
+
+- Project name: `yunti-browser-runtime`.
+- Public package/tooling prefix: `yunti`.
+- Environment variable prefix: `YUNTI_BROWSER_`.
+- Tool prefix target: `yunti_*`.
+- `yunti_list_pages` is a compatibility alias for the live browser target
+  inventory, not a separate registration registry.
+- If a `browserSessionId` becomes stale, agents should call
+  `yunti_list_browser_targets` to refresh the route inventory.
+- The content script must not call product-specific login APIs in the
+  standalone runtime.
+
+## Open Work
+
+- Follow `docs/EXECUTION_PLAN.md` for the active P4.19 npm publish step.
+- P4.1 release-readiness docs and permission review is complete.
+- P4.2 Agent integration examples are complete.
+- P4.3 npm publishing URL confirmation is complete with the GitHub repository
+  `https://github.com/dingguangyi0/yunti-browser-runtime`; package metadata
+  points to that repository/homepage/issues URL set and all three URLs return
+  HTTP 200.
+- `npm view yunti-browser-runtime` currently returns E404, which is acceptable
+  only if `0.1.0` is intended to be the first npm release under this package
+  name.
+- Latest release gate checks passed after documenting P4.3: public-doc residue
+  check, `npm run check`, `npm test`, and `npm pack --dry-run`.
+- P4.4 release gate scripting is complete: `npm run release:check` now runs
+  public-doc residue checks, `npm run check`, `npm test`, and
+  `npm pack --dry-run`.
+- P4.5 release runbook is complete: `docs/RELEASE.md` documents external URL
+  confirmation, release gates, extension zip checks, optional E2E, and npm
+  publish steps.
+- Latest `npm run release:check` passed after adding the runbook; the npm
+  tarball includes `docs/RELEASE.md`.
+- P4.6 package metadata checking is complete: `npm run check:metadata` reports
+  public reachability for package repository/homepage/bugs URLs and npm package
+  status, returning non-zero while the GitHub URLs are unavailable.
+- Latest `npm run release:check` passed after adding metadata checking; the npm
+  tarball includes `scripts/check-package-metadata.js`.
+- P4.7 prepublish gate is complete: `npm run release:prepublish` now runs
+  metadata checks before the local release gate and is expected to fail until
+  P4.3 repository URLs are public.
+- Latest P4.7 validation: `npm run release:check` passed public-doc residue
+  checks, `npm run check`, `npm test`, and `npm pack --dry-run`; `npm run
+  release:prepublish` failed as expected at `check:metadata` because the current
+  repository and bugs URLs still return 404 or are not publicly reachable.
+- P4.3 blocker remediation is documented in `docs/PUBLISHING_BLOCKERS.md`;
+  latest `npm run release:check` passed after adding that guide, and the npm
+  tarball now includes the blocker guide with 39 total files.
+- P4.8 npm package contents gate is complete: `npm run release:check` now parses
+  `npm pack --json --dry-run` and fails if required runtime, extension, skill,
+  release documentation, or release helper files are missing from the tarball.
+- Latest P4.8 validation: `npm run release:check` passed public-doc residue
+  checks, `npm run check`, `npm test`, and the required npm package contents
+  check; the parsed npm pack output contained 39 files.
+- P4.9 extension zip contents gate is complete: `npm run release:check` now
+  runs `npm run package:extension`, parses the generated zip, and fails if the
+  archive is missing required extension runtime files or includes unexpected
+  files.
+- Latest P4.9 validation: `npm run release:check` passed public-doc residue
+  checks, `npm run check`, `npm test`, required npm package contents validation,
+  and extension zip contents validation; the generated extension zip contained
+  exactly 12 runtime files.
+- P4.10 package / extension version consistency gate is complete:
+  `npm run release:check` now fails if `package.json.version` and
+  `extension/manifest.json.version` are missing or different.
+- Latest P4.10 validation: `npm run release:check` passed public-doc residue
+  checks, version consistency check for `0.1.0`, `npm run check`, `npm test`,
+  required npm package contents validation, and extension zip contents
+  validation.
+- P4.11 npm bin CLI smoke gate is complete: `npm run release:check` now verifies
+  `package.json` bin mapping, `yunti-browser-runtime --help`, and
+  `yunti-browser-runtime --version` behavior through the local CLI entrypoint.
+- Latest P4.11 validation: `npm run release:check` passed public-doc residue
+  checks, version consistency check for `0.1.0`, CLI smoke check for `0.1.0`,
+  `npm run check`, `npm test`, required npm package contents validation, and
+  extension zip contents validation.
+- P4.12 Agent config smoke gate is complete: `npm run release:check` now
+  validates `print-config` JSON output for Codex, Claude Code, Cursor, and
+  Cline, plus the human-readable Codex output for token and skill guidance.
+- Latest P4.12 validation: `npm run release:check` passed public-doc residue
+  checks, version consistency check for `0.1.0`, CLI smoke check for `0.1.0`,
+  print-config smoke check for 4 agents, `npm run check`, `npm test`, required
+  npm package contents validation, and extension zip contents validation.
+- P4.13 doctor JSON smoke gate is complete: `npm run release:check` now runs
+  `scripts/doctor.js`, parses stdout JSON, validates Node/MCP/skill diagnostics,
+  and accepts bridge offline as a structured diagnostic state instead of a release
+  gate failure.
+- Latest P4.13 validation: `npm run release:check` passed public-doc residue
+  checks, version consistency check for `0.1.0`, CLI smoke check for `0.1.0`,
+  print-config smoke check for 4 agents, doctor smoke check with bridge offline,
+  `npm run check`, `npm test`, required npm package contents validation, and
+  extension zip contents validation.
+- P4.14 public Markdown link gate is complete: `npm run release:check` now scans
+  README, docs, and skills Markdown files and fails if a relative Markdown link
+  points to a missing local file.
+- Latest P4.14 validation: `npm run release:check` passed public-doc residue
+  checks, public Markdown link check for 11 Markdown files, version consistency
+  check for `0.1.0`, CLI smoke check for `0.1.0`, print-config smoke check for
+  4 agents, doctor smoke check with bridge offline, `npm run check`, `npm test`,
+  required npm package contents validation, and extension zip contents
+  validation. The release gate test run covered 59 tests, with 58 passed and 1
+  real-browser smoke test skipped by configuration.
+- Latest P4.3 validation: `git push -u origin main` succeeded, `npm run
+  check:metadata` passed with repository/homepage/bugs all returning HTTP 200,
+  and `npm run release:prepublish` passed end to end.
+- `npm run check:metadata` now retries transient repository/homepage/bugs HEAD
+  request failures, so temporary GitHub TLS disconnects do not immediately block
+  an otherwise reachable public URL set.
+- `npm run check:metadata` also reuses the repository HEAD result when homepage
+  resolves to the same GitHub URL, reducing duplicate external requests during
+  release gates.
+- P4.15 npm official registry publish scripts are complete:
+  `release:dry-run` and `release:publish` explicitly use
+  `https://registry.npmjs.org/`.
+- Latest P4.15 validation: local npm registry is
+  `https://registry.npmmirror.com`, while
+  `npm run release:dry-run` passed and showed the official npm registry as the
+  target; the dry-run tarball contained 39 files.
+- P4.16 publish script gate chaining is complete: `release:dry-run` and
+  `release:publish` now run `npm run release:prepublish` before reaching npm
+  publish or publish dry-run.
+- Latest P4.16 validation: `npm run release:dry-run` passed, entered
+  `release:prepublish` first, then completed npm publish dry-run against
+  `https://registry.npmjs.org/`; the tarball contained 39 files.
+- P4.17 npm auth preflight is complete: `release:whoami` checks login against
+  `https://registry.npmjs.org/`, and `release:publish` runs it before
+  `npm publish`.
+- Latest P4.17 validation: after npm login, `npm run release:whoami` succeeds
+  against `https://registry.npmjs.org/` and reports account `xuanzhu`.
+- P4.18 post-publish verification command is complete:
+  `release:verify-published` checks the published npm package name, version,
+  repository, homepage, bugs URL, and tarball URL against local `package.json`.
+- Latest P4.18 validation: `release:verify-published` currently fails with a
+  structured unpublished-package report for `yunti-browser-runtime@0.1.0`,
+  `node --check scripts/check-published-package.js` passes, and
+  `release:dry-run` passes with a 40-file npm tarball that includes the new
+  verifier.
+- P4.19 formal npm publish execution is in progress: `npm run release:publish`
+  passed metadata checks, release gates, `npm run release:whoami`, `npm run
+  check`, `npm test`, npm package contents validation, and extension zip
+  validation before reaching `npm publish`.
+- Latest P4.19 validation: official npm publish reached
+  `https://registry.npmjs.org/` with a 40-file tarball, then failed with npm
+  `E403` because the account requires two-factor authentication OTP or a
+  granular access token with bypass 2FA enabled.
+- A temporary npm token publish retry also reached official npm publish after
+  passing the full local release gate, but npm returned the same `E403`; the
+  token does not satisfy npm's publish-time bypass 2FA requirement.
+- A project-local `.npmrc` retry with the actual token also authenticated
+  successfully as `xuanzhu`, then failed at `npm publish` with the same `E403`;
+  `.npmrc` is ignored by git to avoid committing local npm credentials.
+- A second npm token written to the project-local `.npmrc` also authenticated
+  successfully as `xuanzhu`, then failed at `npm publish` with the same `E403`.
+- Next required release step: rerun
+  `npm run release:publish -- --otp=<6-digit-code>` with a current npm OTP, or
+  configure an npm granular access token that can publish with bypass 2FA; after
+  publish succeeds, run `npm run release:verify-published`.
+
+## Known Risks
+
+- Remote relay environment variables still exist in MCP code for compatibility
+  but are not documented as the first release path.
+- Tool argument validation is improved for the P3.2 focus tools, but broader
+  long-tail tools can still receive the same treatment before a later release.
+- Extension broad host permissions are now documented, but should still be
+  re-reviewed before any store-distributed release.
+- Package repository/homepage/bugs metadata is publicly reachable, and the
+  final npm publish is now waiting on npm 2FA OTP or a publish-capable granular
+  access token.
+- Tool names and descriptions must stay clear enough for agents to choose the
+  right route without relying on hidden model knowledge.
+
+## Maintenance Rule
+
+Every meaningful change to runtime behavior, tool schema, extension behavior,
+or install flow must update this file before commit/release.

package/docs/PUBLISHING_BLOCKERS.md

@@ -0,0 +1,110 @@
+# Publishing Blockers
+
+This document tracks release blockers that require external confirmation before
+publishing `yunti-browser-runtime`.
+
+## Active Blocker: npm 2FA Publish OTP
+
+Status: active as of 2026-07-03.
+
+`npm run release:publish` now passes local release gates and npm login preflight,
+then reaches `npm publish --registry=https://registry.npmjs.org/`. The registry
+rejects the publish with `E403` because the logged-in account requires
+two-factor authentication for package publishing.
+
+A temporary npm token retry also passed the local release gate and reached
+official npm publish, but npm returned the same `E403`. That token does not
+satisfy the publish-time bypass 2FA requirement.
+
+A project-root `.npmrc` retry with the actual token also authenticated
+successfully as `xuanzhu`, then failed at `npm publish` with the same `E403`.
+The local `.npmrc` is ignored by git and must not be committed.
+
+A second token written to the project-root `.npmrc` also authenticated
+successfully as `xuanzhu`, then failed at `npm publish` with the same `E403`.
+
+Resolution:
+
+```bash
+npm run release:publish -- --otp=<6-digit-code>
+```
+
+Use a fresh npm one-time password from the account authenticator. As an
+alternative, configure a granular npm access token with package publish
+permission and bypass 2FA enabled, then rerun `npm run release:publish`.
+
+After publish succeeds, run:
+
+```bash
+npm run release:verify-published
+```
+
+## Resolved Blocker: P4.3 Package URLs
+
+Status: resolved on 2026-07-02 with
+`https://github.com/dingguangyi0/yunti-browser-runtime`.
+
+The package metadata currently points to:
+
+- Repository: `https://github.com/dingguangyi0/yunti-browser-runtime`
+- Homepage: `https://github.com/dingguangyi0/yunti-browser-runtime#readme`
+- Issues: `https://github.com/dingguangyi0/yunti-browser-runtime/issues`
+
+The previous `yunti-ai/yunti-browser-runtime` metadata returned HTTP 404. The
+project moved to the `dingguangyi0/yunti-browser-runtime` GitHub repository,
+and the initial `main` push succeeded.
+
+## Resolution Options
+
+### Option A: Create Or Publicize The Current Repository
+
+Use this when the intended public home is a not-yet-created or private
+repository.
+
+Checklist:
+
+- Create the GitHub repository, or make the existing repository public.
+- Enable issues, or choose a different public issue tracker.
+- Confirm the repository URL and issues URL return non-404 responses.
+- Keep the current `package.json` metadata unchanged if these URLs are correct.
+- Run the validation commands below.
+
+### Option B: Update Package Metadata To A Different Public Repository
+
+Use this when the final public repository lives somewhere else.
+
+Checklist:
+
+- Update `package.json` `repository.url`.
+- Update `package.json` `homepage`.
+- Update `package.json` `bugs.url`.
+- Update README, release docs, and status docs if they name the old URL.
+- Run the validation commands below.
+
+## Validation Commands
+
+After either option is complete, run:
+
+```bash
+npm run check:metadata
+npm run release:prepublish
+```
+
+Actual result after P4.3 is resolved:
+
+- `npm run check:metadata` exits 0.
+- Repository, homepage, and issue URLs are publicly reachable.
+- `npm run release:prepublish` reaches and passes `npm run release:check`.
+- npm E404 is accepted only for the first publish under the intended package
+  name.
+
+Before the final publish, also run:
+
+```bash
+npm run release:dry-run
+```
+
+## Publish Readiness
+
+`npm run release:prepublish` now passes. Before running `npm run
+release:publish`, run and review `npm run release:dry-run`.