@agentrhq/webcmd 0.1.2 → 0.2.1

package/skills/webcmd-autofix/SKILL.md

@@ -1,63 +1,67 @@
 ---
 name: webcmd-autofix
-description: Automatically fix broken Webcmd adapters when commands fail. Load this skill when a webcmd command fails — it guides you through collecting a trace artifact, patching the adapter, retrying, and filing an upstream GitHub issue after a verified fix. Works with any AI agent.
+description: Automatically fix broken Webcmd adapters when commands fail. Load this skill when a webcmd command fails; it guides you through collecting a trace artifact, patching the adapter, retrying, and filing an upstream GitHub issue after a verified fix. Works with any AI agent.
 allowed-tools: Bash(webcmd:*), Bash(gh:*), Read, Edit, Write
 ---
 
-# Webcmd AutoFix — Automatic Adapter Self-Repair
+# Webcmd AutoFix - Automatic Adapter Self-Repair
 
-When an `webcmd` command fails because a website changed its DOM, API, or response schema, **automatically diagnose, fix the adapter, and retry** — don't just report the error.
+When a `webcmd` command fails because a website changed its DOM, API, or response schema, diagnose, fix the adapter, and retry. Do not only report the error when the failure is repairable.
 
 ## Safety Boundaries
 
-**Before starting any repair, check these hard stops:**
+Hard stops before any code change:
 
-- **`AUTH_REQUIRED`** (exit code 77) — **STOP.** Do not modify code. Tell the user to log into the site in Chrome.
-- **`BROWSER_CONNECT`** (exit code 69) — **STOP.** Do not modify code. Tell the user to run `webcmd doctor`.
-- **CAPTCHA / rate limiting** — **STOP.** Not an adapter issue.
+- **`AUTH_REQUIRED`** (exit code 77): stop. Tell the user to log into the site in Chrome or the webcmd-managed browser profile.
+- **`BROWSER_CONNECT`** (exit code 69): stop. Tell the user to run `webcmd doctor`.
+- **CAPTCHA / rate limiting / IP block:** stop. This is not an adapter issue.
 
-**Scope constraint:**
-- **Only modify the file at `adapterSourcePath` in the trace `summary.md` front matter** — this is the authoritative adapter location (may be `clis/<site>/` in repo or `~/.webcmd/clis/<site>/` for npm installs)
-- **Never modify** `src/`, `extension/`, `tests/`, `package.json`, or `tsconfig.json`
+Scope constraint:
 
-**Retry budget:** Max **3 repair rounds** per failure. If 3 rounds of diagnose → fix → retry don't resolve it, stop and report what was tried.
+- Modify only the file at `adapterSourcePath` in the trace `summary.md` front matter. That path is authoritative and may be `clis/<site>/...` in the repo or `~/.webcmd/clis/<site>/...` for user-local installs.
+- Never modify `src/`, `extension/`, `tests/`, `package.json`, or `tsconfig.json` during autofix.
 
-## Prerequisites
+Retry budget: maximum **3 repair rounds** per failure. A round is diagnose -> patch -> retry. If 3 rounds do not resolve it, stop and report what was tried.
+
+## Prerequisite
 
 ```bash
-webcmd doctor    # Verify extension + daemon connectivity
+webcmd doctor
 ```
 
-## When to Use This Skill
+This verifies extension and daemon connectivity for browser-dependent repairs.
+
+## When To Use
 
-Use when `webcmd <site> <command>` fails with repairable errors:
-- **SELECTOR** — element not found (DOM changed)
-- **EMPTY_RESULT** — no data returned (API response changed)
-- **API_ERROR** / **NETWORK** — endpoint moved or broke
-- **PAGE_CHANGED** — page structure no longer matches
-- **COMMAND_EXEC** — runtime error in adapter logic
-- **TIMEOUT** — page loads differently, adapter waits for wrong thing
+Use this skill when `webcmd <site> <command>` fails with repairable errors:
 
-## Before Entering Repair: "Empty" ≠ "Broken"
+- **SELECTOR:** element not found or DOM changed.
+- **EMPTY_RESULT:** no data returned and evidence suggests a schema/API drift.
+- **API_ERROR / NETWORK:** endpoint moved, params changed, or network contract broke.
+- **PAGE_CHANGED:** page structure no longer matches the adapter.
+- **COMMAND_EXEC:** runtime error in adapter logic.
+- **TIMEOUT:** page loads differently or waits for the wrong signal.
 
-`EMPTY_RESULT` — and sometimes a structurally-valid `SELECTOR` that returns nothing — is often **not an adapter bug**. Platforms actively degrade results under anti-scrape heuristics, and a "not found" response from the site doesn't mean the content is actually missing. Rule this out **before** committing to a repair round:
+## Before Repair: Empty Does Not Always Mean Broken
 
-- **Retry with an alternative query or entry point.** If `webcmd xiaohongshu search "X"` returns 0 but `webcmd xiaohongshu search "X 攻略"` returns 20, the adapter is fine — the platform was shaping results for the first query.
-- **Spot-check in a normal Chrome tab.** If the data is visible in the user's own browser but the adapter comes back empty, the issue is usually authentication state, rate limiting, or a soft block — not a code bug. The fix is `webcmd doctor` / re-login, not editing source.
-- **Look for soft 404s.** Sites like xiaohongshu / weibo / douyin return HTTP 200 with an empty payload instead of a real 404 when an item is hidden or deleted. The snapshot will look structurally correct. A retry 2-3 seconds later often distinguishes "temporarily hidden" from "actually gone".
-- **"0 results" from a search is an answer.** If the adapter successfully reached the search endpoint, got an HTTP 200, and the platform returned `results: []`, that is a valid answer — report it to the user as "no matches for this query" rather than patching the adapter.
+`EMPTY_RESULT`, and sometimes a structurally valid selector that returns no rows, may be a real platform answer rather than an adapter bug. Rule this out before a repair round:
 
-Only proceed to Step 1 if the empty/selector-missing result is **reproducible across retries and alternative entry points**. Otherwise you're patching a working adapter to chase noise, and the patched version will break the next working path.
+- Retry with an alternative query or entry point. If `webcmd reddit search "X"` returns 0 but `webcmd reddit search "X guide"` returns 20, the adapter is likely fine and the first query was too narrow.
+- Spot-check in a normal browser tab. If the data is visible there but the adapter is empty, the issue may be auth state, soft blocking, or rate limiting; use `webcmd doctor` or re-login rather than editing source.
+- Look for soft 404s. Some platforms return HTTP 200 with an empty payload when an item is hidden, deleted, or temporarily unavailable. A retry after a short wait can distinguish transient hiding from real deletion.
+- Treat a successful empty search as an answer. If the adapter reached the endpoint, got HTTP 200, and the platform returned `results: []`, report "no matches" instead of patching.
+
+Proceed only when the empty or missing-selector result is reproducible across retries and alternative entry points.
 
 ## Step 1: Collect Trace Context
 
-Run the failing command with failure-retained trace enabled:
+Run the failing command with retained trace:
 
 ```bash
 webcmd <site> <command> [args...] --trace retain-on-failure 2>trace-error.yaml
 ```
 
-On failure, stderr contains the normal error envelope plus a small `trace` block:
+On failure, stderr contains the normal error envelope plus a `trace` block:
 
 ```yaml
 ok: false
@@ -73,7 +77,7 @@ trace:
   receiptPath: "/path/to/.webcmd/profiles/default/traces/.../receipt.json"
 ```
 
-Read `summaryPath` first. It is the LLM-oriented entry point and includes front matter:
+Read `summaryPath` first. It is the LLM-oriented entry point and includes:
 
 ```yaml
 ---
@@ -89,137 +93,122 @@ errorMessage: "Could not find element: .old-selector"
 ---
 ```
 
-The artifact directory contains:
+Trace artifacts include:
 
 ```text
-summary.md      # start here
-receipt.json    # machine-readable trace receipt
-trace.jsonl     # full redacted timeline
-network.jsonl   # redacted network events
-console.jsonl   # redacted console events
-state/          # final snapshots when available
-screenshots/    # final screenshots when available
+summary.md
+receipt.json
+trace.jsonl
+network.jsonl
+console.jsonl
+state/
+screenshots/
 ```
 
-If you redirected stderr to a file, read that file and copy `trace.summaryPath`.
+Do not ask the user to rerun with legacy diagnostic environment variables. Trace artifacts are the repair evidence path.
 
-Do not ask the user to rerun with legacy diagnostic env vars. Trace is the repair evidence path.
+## Step 2: Analyze The Failure
 
-## Step 2: Analyze the Failure
+Read the trace summary and adapter source. Classify root cause:
 
-Read the trace summary and the adapter source. Classify the root cause:
+| Error code | Likely cause | Repair strategy |
+| --- | --- | --- |
+| SELECTOR | DOM restructured or class/id changed | Explore current DOM and find a stable selector |
+| EMPTY_RESULT | API response schema changed, data moved, or real empty result | Check network and visible page before patching |
+| API_ERROR | Endpoint URL changed or new params required | Discover current API through network evidence |
+| AUTH_REQUIRED | Login flow changed or cookies expired | Stop; ask user to log in |
+| TIMEOUT | Page loads differently or lazy-load signal changed | Update wait conditions |
+| PAGE_CHANGED | Major redesign | May need full adapter rewrite through `webcmd-adapter-author` |
 
-| Error Code | Likely Cause | Repair Strategy |
-|-----------|-------------|-----------------|
-| SELECTOR | DOM restructured, class/id renamed | Explore current DOM → find new selector |
-| EMPTY_RESULT | API response schema changed, or data moved | Check network → find new response path |
-| API_ERROR | Endpoint URL changed, new params required | Discover new API via network intercept |
-| AUTH_REQUIRED | Login flow changed, cookies expired | **STOP** — tell user to log in, do not modify code |
-| TIMEOUT | Page loads differently, spinner/lazy-load | Add/update wait conditions |
-| PAGE_CHANGED | Major redesign | May need full adapter rewrite |
+Answer these questions:
 
-**Key questions to answer:**
-1. What is the adapter trying to do? (Read the file at `adapterSourcePath`)
-2. What did the page look like when it failed? (Read `summary.md`, then `state/` if needed)
-3. What network requests happened? (Read `Failed Network` in `summary.md`, then `network.jsonl` if needed)
-4. What's the gap between what the adapter expects and what the page provides?
+1. What is the adapter trying to do? Read `adapterSourcePath`.
+2. What did the page look like when it failed? Read `summary.md`, then `state/` if needed.
+3. What network requests happened? Read failed network in `summary.md`, then `network.jsonl` if needed.
+4. What gap exists between adapter expectations and current page reality?
 
-## Step 3: Explore the Current Website
+## Step 3: Explore The Current Website
 
-Use `webcmd browser` to inspect the live website. **Never use the broken adapter** — it will just fail again.
+Use `webcmd browser` to inspect the live site. Do not use the broken adapter for exploration.
 
-### DOM changed (SELECTOR errors)
+For DOM changes:
 
 ```bash
-# Open the page and inspect current DOM
-webcmd browser open https://example.com/target-page && webcmd browser state
-
-# Look for elements that match the adapter's intent
-# Compare the snapshot with what the adapter expects
+webcmd browser open https://example.com/target-page
+webcmd browser state
 ```
 
-### API changed (API_ERROR, EMPTY_RESULT)
+For API changes:
 
 ```bash
-# Open page with network interceptor, then trigger the action manually
-webcmd browser open https://example.com/target-page && webcmd browser state
-
-# Interact to trigger API calls
-webcmd browser click <N> && webcmd browser network
-
-# Narrow to the request you care about by the fields its body should have
+webcmd browser open https://example.com/target-page
+webcmd browser state
+webcmd browser click <N>
+webcmd browser network
 webcmd browser network --filter author,text,likes
-
-# Inspect specific API response (key is the `key` field from the default JSON output)
 webcmd browser network --detail <key>
 ```
 
-## Step 4: Patch the Adapter
+Use the `key` field from network output with `--detail`.
 
-Read the adapter source file at `adapterSourcePath` from the trace summary front matter and make targeted fixes. This path is authoritative — it may be in the repo (`clis/`) or user-local (`~/.webcmd/clis/`).
+## Step 4: Patch The Adapter
 
-Use the `Read` tool on the exact path from summary.md front matter.
+Patch only `adapterSourcePath`.
 
-### Common Fixes
+Common fixes:
 
-**Selector update:**
-```typescript
-// Before: page.evaluate('document.querySelector(".old-class")...')
-// After:  page.evaluate('document.querySelector(".new-class")...')
+```js
+// Selector update
+document.querySelector('.new-class')
 ```
 
-**API endpoint change:**
-```typescript
-// Before: const resp = await page.evaluate(`fetch('/api/v1/old-endpoint')...`)
-// After:  const resp = await page.evaluate(`fetch('/api/v2/new-endpoint')...`)
+```js
+// Endpoint update
+fetch('/api/v2/search')
 ```
 
-**Response schema change:**
-```typescript
-// Before: const items = data.results
-// After:  const items = data.data.items  // API now nests under "data"
+```js
+// Response schema update
+const items = data.data.items;
 ```
 
-**Wait condition update:**
-```typescript
-// Before: await page.wait({ selector: '.loading-spinner', hidden: true })
-// After:  await page.wait({ selector: '[data-loaded="true"]' })
+```js
+// Wait condition update
+await page.wait({ selector: '[data-loaded="true"]' });
 ```
 
-### Rules for Patching
+Rules:
 
-1. **Make minimal changes** — fix only what's broken, don't refactor
-2. **Keep the same output structure** — `columns` and return format must stay compatible
-3. **Prefer API over DOM scraping** — if you discover a JSON API during exploration, switch to it
-4. **Use `@agentrhq/webcmd/*` imports only** — never add third-party package imports
-5. **Test after patching** — run the command again to verify
-6. **Never relax `verify/<cmd>.json` fixtures to silence a failure.** A failing `patterns` / `notEmpty` / `mustNotContain` / `mustBeTruthy` rule means the adapter's output is broken. Tighten the adapter so it produces correct values; do not loosen the fixture to accept the broken values. The one legitimate reason to edit a fixture during repair is when the **site itself** changed shape (e.g. URL format migration) — in that case update the fixture and note the change in `~/.webcmd/sites/<site>/notes.md`. Otherwise editing the fixture is covering up a silent correctness regression.
+1. Make minimal changes; do not refactor unrelated code.
+2. Keep output structure compatible: `columns` and row keys must remain aligned.
+3. Prefer stable API evidence over brittle DOM scraping when discovered.
+4. Use only `@agentrhq/webcmd/*` imports; do not add third-party packages.
+5. Test after patching.
+6. Never relax `verify/<cmd>.json` fixtures to silence a failure. A failing `patterns`, `notEmpty`, `mustNotContain`, or `mustBeTruthy` rule usually means adapter output is wrong. Edit a fixture only when the site itself legitimately changed shape, such as a URL format migration, and note the change in `~/.webcmd/sites/<site>/notes.md`.
 
-## Step 5: Verify the Fix
+## Step 5: Verify The Fix
+
+Run:
 
 ```bash
-# Run the command normally
 webcmd <site> <command> [args...]
 ```
 
-If it still fails, go back to Step 1 and collect a fresh trace. You have a budget of **3 repair rounds** (trace → fix → retry). If the same error persists after a fix, try a different approach. After 3 rounds, stop and report what was tried.
+If it still fails, collect a fresh trace and start another round. Stop after 3 rounds.
 
-## Step 6: File an Upstream Issue
+## Step 6: File An Upstream Issue
 
-If the retry **passes**, the local adapter has drifted from upstream. File a GitHub issue so the fix flows back to `agentrhq/webcmd`.
+If the retry passes, prepare an upstream issue so the local fix can flow back to `agentrhq/webcmd`.
 
-**Do NOT file for:**
-- `AUTH_REQUIRED`, `BROWSER_CONNECT`, `ARGUMENT`, `CONFIG` — environment/usage issues, not adapter bugs
-- CAPTCHA or rate limiting — not fixable upstream
-- Failures you couldn't actually fix (3 rounds exhausted)
+Do not file for:
 
-**Only file after a verified local fix** — the retry must pass first.
+- `AUTH_REQUIRED`, `BROWSER_CONNECT`, `ARGUMENT`, or `CONFIG`
+- CAPTCHA or rate limiting
+- failures you could not fix
 
-**Procedure:**
+Only file after a verified local fix.
 
-1. Prepare the issue content from the trace summary you already have:
-   - **Title:** `[autofix] <site>/<command>: <error_code>` (e.g. `[autofix] zhihu/hot: SELECTOR`)
-   - **Body** (use this template):
+Draft:
 
 ```markdown
 ## Summary
@@ -240,15 +229,13 @@ Webcmd autofix repaired this adapter locally, and the retry passed.
 ## Local fix summary
 
 ~~~
-<1-2 sentence description of what you changed and why>
+<1-2 sentence description of what changed and why>
 ~~~
 
 _Issue filed by Webcmd autofix after a verified local repair._
 ```
 
-2. **Ask the user before filing.** Show them the draft title and body. Only proceed if they confirm.
-
-3. If the user approves and `gh auth status` succeeds:
+Ask the user before filing. Show the draft title and body. If they approve and `gh auth status` succeeds:
 
 ```bash
 gh issue create --repo agentrhq/webcmd \
@@ -256,42 +243,48 @@ gh issue create --repo agentrhq/webcmd \
   --body "<the body above>"
 ```
 
-If `gh` is not installed or not authenticated, tell the user and skip — do not error out.
+If `gh` is unavailable or unauthenticated, tell the user and skip issue creation.
+
+## When To Stop
 
-## When to Stop
+Hard stops:
 
-**Hard stops (do not modify code):**
-- **AUTH_REQUIRED / BROWSER_CONNECT** — environment issue, not adapter bug
-- **Site requires CAPTCHA** — can't automate this
-- **Rate limited / IP blocked** — not an adapter issue
+- `AUTH_REQUIRED` / `BROWSER_CONNECT`: environment issue, not adapter bug.
+- Site requires CAPTCHA.
+- Rate limited or IP blocked.
 
-**Soft stops (report after attempting):**
-- **3 repair rounds exhausted** — stop, report what was tried and what failed
-- **Feature completely removed** — the data no longer exists
-- **Major redesign** — needs full adapter rewrite via `webcmd-adapter-author` skill
+Soft stops:
 
-In all stop cases, clearly communicate the situation to the user rather than making futile patches.
+- 3 repair rounds exhausted.
+- Feature completely removed.
+- Major redesign requiring `webcmd-adapter-author`.
+
+In all stop cases, clearly report the situation instead of making speculative patches.
 
 ## Example Repair Session
 
-```
-1. User runs: webcmd zhihu hot
-   → Fails: SELECTOR "Could not find element: .HotList-item"
+```text
+1. User runs: webcmd reddit hot
+   -> Fails: SELECTOR "Could not find element: .old-post-selector"
 
-2. AI runs: webcmd zhihu hot --trace retain-on-failure 2>trace-error.yaml
-   → Gets trace summary with final state and failed action evidence
+2. Agent runs: webcmd reddit hot --trace retain-on-failure 2>trace-error.yaml
+   -> Gets trace summary with final state and failed action evidence
 
-3. AI reads summary/state: page loaded but uses ".HotItem" instead of ".HotList-item"
+3. Agent reads summary/state:
+   -> Page loaded, but post cards now use "[data-testid=post-container]"
 
-4. AI explores: webcmd browser open https://www.zhihu.com/hot && webcmd browser state
-   → Confirms new class name ".HotItem" with child ".HotItem-content"
+4. Agent explores:
+   -> webcmd browser open https://www.reddit.com && webcmd browser state
 
-5. AI patches: Edit adapter at `adapterSourcePath` — replace ".HotList-item" with ".HotItem"
+5. Agent patches adapterSourcePath:
+   -> Replace old selector with stable scoped selector
 
-6. AI verifies: webcmd zhihu hot
-   → Success: returns hot topics
+6. Agent verifies:
+   -> webcmd reddit hot
+   -> Success: returns hot posts
 
-7. AI prepares upstream issue draft, shows it to the user
+7. Agent prepares upstream issue draft and asks the user
 
-8. User approves → AI runs: gh issue create --repo agentrhq/webcmd --title "[autofix] zhihu/hot: SELECTOR" --body "..."
+8. User approves:
+   -> gh issue create --repo agentrhq/webcmd --title "[autofix] reddit/hot: SELECTOR" --body "..."
 ```

package/skills/webcmd-sitemap-author/SKILL.md

@@ -6,58 +6,51 @@ allowed-tools: Bash(webcmd:*), Read, Edit, Write, Grep
 
 # webcmd-sitemap-author
 
-You are authoring a **task execution graph for agents**, not an SEO sitemap. The artifact should help an agent using `webcmd browser` decide where it is, what path to take next, which Webcmd adapter to prefer, and how to recover when the page disagrees with memory.
+You are authoring a **task execution graph for agents**, not an SEO sitemap. The artifact helps an agent using `webcmd browser` decide where it is, what path to take next, which Webcmd adapter to prefer, and how to recover when the page disagrees with memory.
 
 Keep the sitemap small and verified. Do not crawl a whole site. Capture only task-relevant paths that you actually observed.
 
----
-
 ## Storage Model
 
 Two layers:
 
-- **Global seed**: `sitemaps/<site>/` (top-level)
-- **Local overlay**: `~/.webcmd/sites/<site>/sitemap/`
+- **Global seed:** `sitemaps/<site>/`
+- **Local overlay:** `~/.webcmd/sites/<site>/sitemap/`
 
-Local overlay wins by stable id. Write new discoveries to local first. Promote to global only after review.
+Local overlay wins by stable id. Write new discoveries locally first. Promote to global only after review.
 
 Recommended layout:
 
 ```text
 sitemap/
-  SITE.md                 # site purpose, auth assumptions, stable page ids
-  pages/<page-id>.md      # page state signatures, actions, linked APIs
-  pages/_<partial>.md     # cross-page UI partial (e.g. _tweet_card.md)
-  workflows/<task-id>.md  # best path, fallback path, avoid list
-  pitfalls.md             # durable failure modes and stale areas
+  SITE.md
+  pages/<page-id>.md
+  pages/_<partial>.md
+  workflows/<task-id>.md
+  pitfalls.md
 ```
 
-### Size guidance（实测启发式）
-
-`references/sitemap-schema.md` §1.1 spec 硬 800 token，但 PoC 实测简单站单 page 1-2 action 自然落到 800-2000 token。强拆反碎，author 用下表决策：
+### Size Guidance
 
-> spec 800 是 lazy-load 优化目标 + Phase 2 audit 阈值；下表是 author 实战决策辅助，**不替代 spec hard 限制**。超 800 的文件 audit 会 flag，author 解释（"5 个 cohesive UI primitive 一起放"）或拆。
+`references/sitemap-schema.md` defines an 800-token target for lazy loading and audit. In real authoring, small pages with one or two actions may naturally land between 800 and 2000 tokens. Use this table:
 
-| 文件 token | 决策 |
-|---|---|
-| < 1500 | 自然 size，不动 |
-| 1500-3000 | 看 cohesion — 5 个 cohesive UI primitive 一起放 OK；mixed 内容拆 |
-| > 3000 | **必拆** sub-file 或 partial（agent lazy load budget 真有限制） |
+| File tokens | Decision |
+| --- | --- |
+| < 1500 | Natural size; leave it. |
+| 1500-3000 | Keep only if cohesive; split mixed content. |
+| > 3000 | Split into a sub-file or partial. |
 
-Phase 2 cron audit 按 token count 不按 byte count（CJK 中文 token-per-char 比 English 高 30-50%）。
-
----
+The 800-token target remains the audit threshold. If a file exceeds it, either explain the cohesive reason or split.
 
 ## Authoring Loop
 
-1. **Load existing memory**: read local overlay first, then global seed if present.
-2. **Verify reality**: use `webcmd browser <session> state`, `find`, `network`, and `analyze`; browser state is truth. If you just completed an `webcmd-adapter-author` session for this site, start from the retained browse trace under `~/.webcmd/sites/<site>/traces/` as seed evidence instead of re-discovering the path from zero.
-3. **Record only durable structure**: page purpose, stable anchors, state signature, actions, workflows, API references, pitfalls.
-4. **Use stable ids**: page/action/workflow ids should survive URL params, locale text drift, and minor layout changes.
-5. **Write local draft**: update `~/.webcmd/sites/<site>/sitemap/...` unless explicitly promoting to repo.
-6. **Mark stale on conflict**: if existing sitemap disagrees with current browser state, trust browser state and mark the item stale rather than forcing the old path.
-
----
+1. Load existing memory: local overlay first, then global seed if present.
+2. Verify reality with `webcmd browser <session> state`, `find`, `network`, and `analyze`. Browser state is truth.
+3. If you just completed `webcmd-adapter-author` for this site, seed from retained browse traces under `~/.webcmd/sites/<site>/traces/` instead of rediscovering from zero.
+4. Record durable structure only: page purpose, stable anchors, state signatures, actions, workflows, API references, pitfalls.
+5. Use stable ids for pages, actions, and workflows. They should survive URL params, locale text drift, and minor layout changes.
+6. Write the local draft under `~/.webcmd/sites/<site>/sitemap/...` unless explicitly promoting to repo.
+7. On conflict, trust current browser state and mark stale memory instead of forcing the old path.
 
 ## Required Action Schema
 
@@ -73,49 +66,52 @@ recover: <fallback instruction>; adapter_health_update: <adapter> -> suspect
 evidence: webcmd browser <cmd> or trace:<path>
 ```
 
-Use this compact form by default. Use the longer Markdown form from `references/sitemap-schema.md` only when an action genuinely needs long explanation. `verified_at` and `source` are inherited from file frontmatter; do not repeat them per action.
+Use this compact form by default. Use the longer Markdown form from `references/sitemap-schema.md` only when an action genuinely needs longer explanation. `verified_at` and `source` are inherited from file front matter; do not repeat them per action.
 
 Do not promote an action without evidence. If a recovery path marks `adapter_health_update`, the browser-sitemap consumer must write that health update to the local overlay so the next agent does not retry a known-suspect adapter.
 
-### Partial pages（跨页通用 UI）
+## Partial Pages
 
-partial 文件 (`_<name>.md`，`url_patterns: []`) 装跨页 UI 原语（如 `_tweet_card.md` 的 like/reply/repost/bookmark）。被多 page 通过 `action:<id> in pages/_<name>.md` 引用。
+Partial files (`_<name>.md`, `url_patterns: []`) hold cross-page UI primitives, such as a reusable post card with like/reply/share actions. Multiple page files can reference `action:<id> in pages/_<name>.md`.
 
-**Partial scope rule**：partial 内所有 selector（testid / a11y / structural）**必须 scoped 到 partial root**，不能是 page-level first match。例如 `_tweet_card.md`:
+**Partial scope rule:** every selector inside a partial, whether testid, accessibility, or structural, must be scoped to the partial root. It must not rely on a page-level first match.
+
+Bad:
 
 ```yaml
-# ❌ 错：page-level first match，会点到 timeline 首条非 target card
 do: click [data-testid="like"]
+```
 
-# ✅ 对：scoped 到 article root
+Good:
+
+```yaml
 do: click [data-testid="like"] in article[role="article"] (card scope)
 ```
 
-partial 文件顶部写明 scope root 一行：
+At the top of the partial file, state the scope root:
 
 ```md
-## Card scope rule
-所有 testid selector 必须 scoped 到 `article[role="article"]`，不能用 page-level first match。
-```
+## Card Scope Rule
 
----
+All testid selectors must be scoped to `article[role="article"]`; do not use page-level first match.
+```
 
 ## Workflow Fields
 
 Each workflow should answer:
 
-- **Goal**: user-facing task this workflow solves.
-- **State signature**: minimal observable checkpoint for resume after sleep/compaction.
-- **Best path**: prefer existing `webcmd <site> <command>` adapter if it covers the goal.
-- **Fallback path**: browser workflow if the adapter is missing or failing.
-- **Avoid**: tempting paths that waste turns, trigger modals, or rely on unstable selectors.
-- **Stale markers**: last verified date and known layout/API drift signals.
+- **Goal:** user-facing task this workflow solves.
+- **State signature:** minimal observable checkpoint for resume after sleep or compaction.
+- **Best path:** prefer existing `webcmd <site> <command>` adapter if it covers the goal.
+- **Fallback path:** browser workflow if the adapter is missing or failing.
+- **Avoid:** tempting paths that waste turns, trigger modals, or rely on unstable selectors.
+- **Stale markers:** last verified date and known layout/API drift signals.
 
 Endpoint/API knowledge should reference ids from `endpoints.json` when available. Do not duplicate full endpoint schemas inside sitemap files.
 
-### Fallback `on_adapter_fail:` convention（推荐）
+### `on_adapter_fail:` Fallback Convention
 
-Fallback path 第一行声明触发条件 + adapter_health_update directive，把"为什么走 fallback"和"标 adapter suspect"放一起：
+Start fallback paths with trigger condition plus `adapter_health_update`:
 
 ```yaml
 on_adapter_fail:
@@ -123,39 +119,34 @@ on_adapter_fail:
   - webcmd browser state (verify current page)
   - if not on /home: goto /home
   - action:open_compose in pages/home.md
-  - ...
 ```
 
-比纯 step list 清晰：consumption skill 看到 `on_adapter_fail:` key 知道这是 adapter-trigger 而非 entry-point fallback，directive 先执行后续才走 steps。schema v1.2 candidate，目前作为 SKILL guideline 推荐。
+This tells the consuming skill that fallback was triggered by adapter failure, not by an entry-point choice. The health update comes first, then recovery steps.
 
-## SITE.md `Top-level routes` — 标 uncovered routes
+## `SITE.md` Top-Level Routes
 
-`SITE.md` 的 `Top-level routes` 不仅列已覆盖的 page，也应**显式标存在但 sitemap 不导航**的 route，避免 agent 默认"sitemap 没列 → 不存在"：
+`SITE.md` should list covered routes and explicitly mark known routes that the sitemap does not navigate. This prevents agents from assuming "not listed" means "does not exist."
 
 ```md
 ## Top-level routes
 
-- /home → pages/home.md
-- /search → pages/search.md
-- /messages → pages/messages.md（DM，本 PoC v1 不覆盖）   # ← 显式 uncovered marker
-- /settings → 不在 sitemap scope，agent 自探         # ← 同上
+- /home -> pages/home.md
+- /search -> pages/search.md
+- /messages -> uncovered in this sitemap; agent must explore live
+- /settings -> out of sitemap scope; agent must explore live
 ```
 
-不写 = agent 不知该 route 存在；写 + 标 uncovered = agent 知道存在但 sitemap 帮不上忙，自己探。
-
----
+Writing uncovered markers tells the agent the route exists but sitemap help is limited.
 
 ## Red Lines
 
 - Sitemap is a hint; current browser state is truth.
-- Do not write secrets, cookies, user-private ids, private messages, or account-specific values.
+- Do not write secrets, cookies, private ids, private messages, or account-specific values.
 - Do not document bypasses for CAPTCHA, WAF, access control, rate limits, or paid gates.
 - Do not store brittle snapshot indices like `[17]` as durable targets. Store semantic anchors and recovery instructions.
 - Do not describe unverified paths as facts. Use `draft` or `stale` labels.
-- Drafts go inside `sitemap/draft-<topic>.md`, not `~/.webcmd/sites/<site>/sitemap.draft.md` at the parent level — the latter is invisible to `webcmd browser` sitemap availability detection.
-
----
+- Drafts go inside `sitemap/draft-<topic>.md`, not `~/.webcmd/sites/<site>/sitemap.draft.md` at the parent level. The parent-level draft is invisible to sitemap availability detection.
 
-## Detailed schema
+## Detailed Schema
 
-See [`references/sitemap-schema.md`](./references/sitemap-schema.md) for the full field-level spec — `SITE.md` / `pages/<id>.md` / `workflows/<id>.md` / `apis.md` / `pitfalls.md` schemas, action-level state signatures, `adapter_health` enum (healthy / suspect / broken), endpoint reference rules, two-layer overlay semantics, draft placement, and Phase 2 validation rules.
+See [`references/sitemap-schema.md`](./references/sitemap-schema.md) for the full field-level spec: `SITE.md`, `pages/<id>.md`, `workflows/<id>.md`, `apis.md`, `pitfalls.md`, action-level state signatures, `adapter_health` enum (`healthy`, `suspect`, `broken`), endpoint references, two-layer overlay semantics, draft placement, and validation rules.