lazycodex-ai 5.1.61 → 5.1.63

package/packages/shared-skills/skills/refactor/SKILL.md

@@ -82,17 +82,15 @@ Should I proceed with [recommendation], or would you prefer differently?
 
 ## Step 0.3: Create Initial Todos
 
-**IMMEDIATELY after understanding the request, create todos:**
+**IMMEDIATELY after understanding the request, create these todos with the session's todo tool (all pending):**
 
 \`\`\`
-TodoWrite([
-  {"id": "phase-1", "content": "PHASE 1: Codebase Analysis - launch parallel explore agents", "status": "pending", "priority": "high"},
-  {"id": "phase-2", "content": "PHASE 2: Build Codemap - map dependencies and impact zones", "status": "pending", "priority": "high"},
-  {"id": "phase-3", "content": "PHASE 3: Test Assessment - analyze test coverage and verification strategy", "status": "pending", "priority": "high"},
-  {"id": "phase-4", "content": "PHASE 4: Plan Generation - invoke Plan agent for detailed refactoring plan", "status": "pending", "priority": "high"},
-  {"id": "phase-5", "content": "PHASE 5: Execute Refactoring - step-by-step with continuous verification", "status": "pending", "priority": "high"},
-  {"id": "phase-6", "content": "PHASE 6: Final Verification - full test suite and regression check", "status": "pending", "priority": "high"}
-])
+- phase-1: PHASE 1: Codebase Analysis - launch parallel explore agents
+- phase-2: PHASE 2: Build Codemap - map dependencies and impact zones
+- phase-3: PHASE 3: Test Assessment - analyze test coverage and verification strategy
+- phase-4: PHASE 4: Plan Generation - invoke Plan agent for detailed refactoring plan
+- phase-5: PHASE 5: Execute Refactoring - step-by-step with continuous verification
+- phase-6: PHASE 6: Final Verification - full test suite and regression check
 \`\`\`
 
 ---
@@ -155,14 +153,14 @@ While background agents are running, use direct tools:
 
 \`\`\`typescript
 // Find definition(s)
-LspGotoDefinition(filePath, line, character)  // Where is it defined?
+lsp_goto_definition(filePath, line, character)  // Where is it defined?
 
 // Find ALL usages across workspace
-LspFindReferences(filePath, line, character, includeDeclaration=true)
+lsp_find_references(filePath, line, character, includeDeclaration=true)
 
 // Get file structure
-LspDocumentSymbols(filePath)  // Hierarchical outline
-LspWorkspaceSymbols(filePath, query="[target_symbol]")  // Search by name
+lsp_symbols(filePath, scope="document")  // Hierarchical outline
+lsp_symbols(filePath, scope="workspace", query="[target_symbol]")  // Search by name
 
 // Get current diagnostics
 lsp_diagnostics(filePath)  // Errors, warnings before we start
@@ -171,8 +169,8 @@ lsp_diagnostics(filePath)  // Errors, warnings before we start
 ### AST-Grep Skill for Pattern Analysis:
 
 \`\`\`bash
-// Find structural patterns
-python3 scripts/ast_grep_helper.py search 'function $NAME($$$) { $$$ }' --lang ts src/
+// Find structural patterns — run this from the ast-grep skill's directory; this skill ships no scripts/
+python3 scripts/ast_grep_helper.py search 'function $NAME($$$) { $$$ }' src/ --lang ts
 
 # Preview refactoring first
 sg --pattern '[old_pattern]' --rewrite '[new_pattern]' --lang ts src/
@@ -181,7 +179,7 @@ sg --pattern '[old_pattern]' --rewrite '[new_pattern]' --lang ts src/
 ### Grep for Text Patterns:
 
 \`\`\`
-grep(pattern="[search_term]", path="src/", include="*.ts")
+grep(pattern="[search_term]", path="src/")  // narrow to *.ts with the grep tool's file-filter parameter
 \`\`\`
 
 ## 1.3: Collect Background Results
@@ -318,6 +316,11 @@ Which approach do you prefer?
 - Unit: \`bun test\` / \`npm test\` / \`pytest\` / etc.
 - Integration: [command if exists]
 - Type check: \`tsc --noEmit\` / \`pyright\` / etc.
+- Lint: [project's linter command, the one Phase 6.3 runs]
+
+### Baseline (before any change)
+- Pass counts: [X/Y passing per test command above]
+- lsp_diagnostics: [pre-existing diagnostics recorded in Phase 1.2]
 
 ### Verification Checkpoints
 After each refactoring step:
@@ -381,17 +384,14 @@ After receiving plan from Plan agent:
 
 ## 4.3: Register Detailed Todos
 
-Convert Plan agent output into granular todos:
+Convert Plan agent output into granular todos with the session's todo tool (each step from the plan becomes a todo, followed by its verify todo):
 
 \`\`\`
-TodoWrite([
-  // Each step from the plan becomes a todo
-  {"id": "refactor-1", "content": "Step 1: [description]", "status": "pending", "priority": "high"},
-  {"id": "verify-1", "content": "Verify Step 1: run tests", "status": "pending", "priority": "high"},
-  {"id": "refactor-2", "content": "Step 2: [description]", "status": "pending", "priority": "medium"},
-  {"id": "verify-2", "content": "Verify Step 2: run tests", "status": "pending", "priority": "medium"},
-  // ... continue for all steps
-])
+- refactor-1: Step 1: [description]
+- verify-1: Verify Step 1: run tests
+- refactor-2: Step 2: [description]
+- verify-2: Verify Step 2: run tests
+- ... continue for all steps
 \`\`\`
 
 **Mark phase-4 as completed.**
@@ -425,8 +425,8 @@ lsp_rename(filePath, line, character, newName)  // Execute rename
 // Preview first
 sg --pattern '[pattern]' --rewrite '[rewrite]' --lang ts path/to/file.ts
 
-// If preview looks good, execute
-python3 scripts/ast_grep_helper.py replace '[pattern]' '[rewrite]' --lang ts path/to/file.ts --apply
+// If preview looks good, execute (from the ast-grep skill's directory)
+python3 scripts/ast_grep_helper.py replace '[pattern]' '[rewrite]' path/to/file.ts --lang ts --apply
 \`\`\`
 
 **For Structural Changes:**
@@ -519,7 +519,7 @@ bun run build  # or npm run build, etc.
 \`\`\`typescript
 // Check all changed files
 for (file of changedFiles) {
-  lsp_diagnostics(file)  // Must all be clean
+  lsp_diagnostics(file)  // Must be clean or same as the Phase 1 baseline: zero new diagnostics
 }
 \`\`\`
 
@@ -585,8 +585,8 @@ You already know these tools. Use them intelligently:
 
 ## LSP Tools
 Leverage LSP tools for precision analysis. Key patterns:
-- **Understand before changing**: \`LspGotoDefinition\` to grasp context
-- **Impact analysis**: \`LspFindReferences\` to map all usages before modification
+- **Understand before changing**: \`lsp_goto_definition\` to grasp context
+- **Impact analysis**: \`lsp_find_references\` to map all usages before modification
 - **Safe refactoring**: \`lsp_prepare_rename\` → \`lsp_rename\` for symbol renames
 - **Continuous verification**: \`lsp_diagnostics\` after every change
 
@@ -650,17 +650,17 @@ Then choose the path:
 - **Team path (5.1-T)**: when the plan recommends \`team\` AND \`file_independent_steps >= 3\`. Members execute in parallel, Lead orchestrates, a \`deep-high\` verifier lives outside the team.
 - **Legacy path (5.1-L)**: otherwise. Use the original 5.1 / 5.2 / 5.3 flow from above.
 
-Record the chosen path in the TodoWrite list.
+Record the chosen path in the todo list.
 
 ## Phase 5.1-T: \`refactor-squad\` team execution
 
 **Precondition checks** (fail hard if any step fails):
 
-1. Load the \`team-mode\` skill via the \`skill\` tool for lifecycle, message protocol, and limits.
+1. When the session lists the \`team-mode\` skill, load it for lifecycle, message protocol, and limits.
 2. Call \`team_list\` and verify no active \`refactor-squad\` run exists; if one does, shutdown + delete the orphan before proceeding.
-3. If \`~/.omo/teams/refactor-squad/config.json\` is missing, write it using the spec below.
+3. If the project-level spec \`.omo/teams/refactor-squad/config.json\` (under the project root) is missing, write it using the spec below.
 
-**Team spec** (\`~/.omo/teams/refactor-squad/config.json\`):
+**Team spec** (\`<project root>/.omo/teams/refactor-squad/config.json\`):
 
 \`\`\`json
 {
@@ -724,7 +724,7 @@ While any team task is \`pending | claimed | in_progress\`:
     prompt=<files touched + verify-spec commands + instruction to return "PASS" or "FAIL:<failing test + specific error + suggested revert hunks>">
   )
   \`\`\`
-  If \`deep\` is unavailable, fall back to \`category="unspecified-high"\`. Do not create a commit checkpoint until the verifier returns PASS.
+  If \`deep-high\` is unavailable, fall back to \`category="unspecified-high"\`. Do not create a commit checkpoint until the verifier returns PASS.
 - On a verifier PASS: make the commit checkpoint for that step (see original 5.3). Proceed.
 - On a verifier FAIL: Lead decides:
   - **Retry with fix hint**: \`team_task_update(status=pending)\` on the original step + \`team_send_message(teamRunId=<id>, to=<original member>, summary="retry", body=<specific failure from verifier>)\`. Runtime reassigns.
@@ -741,7 +741,7 @@ If Phase 5 used the team path, dismantle \`refactor-squad\` BEFORE producing the
 2. \`team_delete(teamRunId=<id>)\`.
 3. \`team_list\` to confirm no residual \`refactor-squad\` run.
 
-The \`~/.omo/teams/refactor-squad/config.json\` declaration stays on disk; next session reuses it.
+The \`.omo/teams/refactor-squad/config.json\` declaration stays on disk in the project; next session reuses it.
 
 Append to the 6.6 summary a "Dispatch path" line and, when team path was used, team metrics (teamRunId, tasks created, verifier runs, team lifetime).
 

package/packages/shared-skills/skills/remove-ai-slops/SKILL.md

@@ -72,12 +72,12 @@ The agent looks for these ten categories. The first three are stylistic, the nex
 10. **Oversized modules** — any source file exceeding **250 pure LOC** (non-blank, non-comment lines). This is an architectural defect, not a style preference. Measure: `awk '!/^[[:space:]]*$/ && !/^[[:space:]]*(#|\/\/)/' <file> | wc -l`.
 
    **When found, do NOT just flag it. Execute a full modular refactoring:**
-   1. Run `check-no-excuse-rules.py` recursively on scope to list all violations.
+   1. List every oversized file in scope: run the `awk` measure above on each source file. For `.py` files you may instead run the `programming` skill's Python checker (`uv run <programming skill dir>/scripts/python/check-no-excuse-rules.py <paths>`, rule `oversized-module`); it scans only `.py` files, so it never covers another language.
    2. For each oversized file, identify distinct responsibilities (single-responsibility principle).
    3. Plan the split: name each new file after the concept it owns (never `utils.py`, `helpers.py`, `common.py`, `part_1.py`).
    4. Present the split plan to the user before executing.
    5. Extract into clean modules with explicit `__init__.py` re-exports (re-exports ONLY, no logic in `__init__.py`).
-   6. Verify: run `check-no-excuse-rules.py` again — every file must be ≤250 pure LOC. Run tests, typecheck, lint.
+   6. Verify: re-measure exactly as in step 1 — every file must be ≤250 pure LOC. Run tests, typecheck, lint.
 
    **Forbidden escapes**:
    - Counting blanks/comments toward budget.
@@ -86,7 +86,7 @@ The agent looks for these ten categories. The first three are stylistic, the nex
    - "It's generated" — only valid if the file lives in a build output directory.
    - "230 LOC, close enough" — a 230-LOC file about to grow is already over. Split now.
 
-   KEEP: genuinely self-contained single-responsibility scripts (e.g., a standalone CLI checker). Opt out with `# noqa: SIZE_OK` in first 5 lines and a comment explaining why.
+   KEEP: genuinely self-contained single-responsibility scripts (e.g., a standalone CLI checker). Opt out with the language's SIZE_OK marker in the first 10 lines (`# noqa: SIZE_OK` in Python, the form the Python checker reads; `// allow: SIZE_OK` in `//`-comment languages) and a comment explaining why.
 
 ---
 
@@ -106,7 +106,7 @@ A pass is complete only when all applicable gates are green. Skip gates that are
 
 ## Process
 
-### Phase 0: Plan with TodoWrite
+### Phase 0: Plan with the todo tool
 
 Create todos for all phases below. Mark `in_progress` one at a time.
 
@@ -246,8 +246,8 @@ If any gate fails or any checklist item flips:
 
 1. Identify the specific change that caused the failure.
 2. Explain why it broke things.
-3. `git checkout` the affected file (or use `git diff` + targeted `Edit` to revert just the problematic hunk).
-4. If genuine slop remains after revert, edit the file directly yourself — in parallel per file via multiple Edit calls — applying only the changes you can prove are safe.
+3. `git checkout` the affected file (or use `git diff` + targeted `edit` to revert just the problematic hunk).
+4. If genuine slop remains after revert, edit the file directly yourself — in parallel per file via multiple `edit` calls — applying only the changes you can prove are safe.
 5. Re-run the failing gate and re-walk the checklist for the affected file.
 6. Repeat until all gates green AND checklist clean.
 

package/packages/shared-skills/skills/review-work/SKILL.md

@@ -121,7 +121,7 @@ For GOAL, CONSTRAINTS, BACKGROUND - review the full conversation history. The us
 
 ## Phase 1: Manual QA (you run it)
 
-You are the QA lane. Do not delegate hands-on QA to a sub-agent: the orchestrator owns the real-surface proof, exactly as the ulw-loop final gate records `manualQa` under the main session.
+You are the QA lane. Do not delegate hands-on QA to a sub-agent: the orchestrator owns the real-surface proof, exactly as the ulw-loop final gate records `manualQa` under the main session. One exception: inside a `ulw-execute` run, whose root never runs QA itself, dispatch these scenarios to one QA worker and build the matrix from the artifacts it captures.
 
 1. **Reuse first.** If this session already captured real-surface evidence for the FINAL tree (an ultrawork or ulw-loop evidence directory, a `visual-qa` verdict on this same build), consume it as QA rows instead of re-running. A fix committed after a capture stales that capture: re-run the rows it covered.
 2. **Pick the channel that faithfully exercises the surface** and capture the artifact:
@@ -240,7 +240,7 @@ Store the lane verdicts independently:
 | Manual QA (Phase 1) | PASS/FAIL | rows, artifact paths |
 | Gate review | pending/APPROVE/REJECT/INCONCLUSIVE | - |
 
-If the reviewer stays silent after the reliability followup, record the lane INCONCLUSIVE and respawn one smaller reviewer scoped to the same inputs. If that retry also ends without a verdict, close the still-running agent if safe, keep the lane INCONCLUSIVE, and emit the final result naming the incomplete lane. Do not spin in repeated wait/followup cycles, and do not use a queued followup as a cancellation.
+If the reviewer ends without a verdict (it completed without one, answered ack-only to one follow-up, or reported `BLOCKED:`), record the lane INCONCLUSIVE and respawn one smaller reviewer scoped to the same inputs. A reviewer that is still running is alive, not silent. If that retry also ends without a verdict, close the still-running agent if safe, keep the lane INCONCLUSIVE, and emit the final result naming the incomplete lane. Do not spin in repeated wait/followup cycles, and do not use a queued followup as a cancellation.
 
 After the lane reaches a terminal state and before delivering the verdict, tear down the review worktree: run `git worktree unlock <path>` followed by `git worktree remove <path>`. The reviewer runs inside that worktree, so removing it earlier destroys its working directory; a crashed review leaves the locked tree as a recoverable marker for manual cleanup.
 

package/packages/shared-skills/skills/ultimate-browsing/SKILL.md

@@ -15,14 +15,14 @@ Web access for the hosts the user's browser cannot open (WAF / 403 / Cloudflare
 User request
   |
   +- a page the user's browser can open (read, click, screenshot, QA, login)  NOT this skill (browser skill, attached engine)
-  +- simple search query ------------------------------ NOT this skill (use web-search)
+  +- simple search query ------------------------------ NOT this skill (use web search)
   |
   +- URL blocked / 403 / Cloudflare / WAF ------------- TIER 1  insane-search
   +- YouTube/Vimeo/TikTok subtitles or metadata ------- TIER 1  insane-search (yt-dlp)
   +- archive snapshot of a dead or changed page ------- TIER 1  insane-search (surrogates, provenance-tagged)
   |
   +- Chinese platform (xhs/douyin/weibo/bilibili/v2ex/wechat)  TIER 1.5 agent-reach
-  +- podcast transcript / stock forum ----------------- TIER 1.5 agent-reach
+  +- podcast transcript ------------------------------- TIER 1.5 agent-reach
   +- Twitter feed / LinkedIn profile / GitHub via CLI - TIER 1.5 agent-reach
   |
   +- Tier 1/1.5 returned empty or partial ------------- TIER 2  2a owned engine (stealth)
@@ -71,8 +71,8 @@ The full engine harness (rules R1-R7, the Phase 0 official-API index, the no-sit
 | search | Exa AI | [references/agent-reach/search.md](references/agent-reach/search.md) |
 
 ```bash
-mcporter call 'douyin.parse_douyin_video_info(url: "<URL>")'   # douyin, zero-config
-curl -s "https://r.jina.ai/https://weibo.com/<uid>/<pid>"      # weibo via Jina
+mcporter call 'douyin.parse_douyin_video_info(share_link: "<URL>")'   # douyin, zero-config
+curl -s -H "Authorization: Bearer ${JINA_API_KEY}" "https://r.jina.ai/https://weibo.com/<uid>/<pid>"   # weibo via Jina (key required)
 yt-dlp --dump-json "<bilibili-url>"                            # Bilibili (overseas: add --cookies-from-browser)
 curl -s "https://www.v2ex.com/api/topics/hot.json"            # V2EX public API
 ```
@@ -115,17 +115,19 @@ When the blocked flow needs the user's account, drive the browser they are alrea
 
 ### Cookie login (cross-platform)
 
-`scripts/extract_cookies.py` reads cookies from a local Chromium-family or Firefox-family browser and optionally injects them into the running CDP session. It resolves browser profile paths and decrypts cookie values per-OS (macOS Keychain, Linux libsecret, Windows DPAPI):
+A login the user holds goes through Tier 2b, never through their cookies: the `browser` skill forbids copying a session out of the user's real browser profile (`references/owned-engine/network.md`, Cookies).
+
+`scripts/extract_cookies.py` reads cookies from the default profile store of a local Chromium-family or Firefox-family browser and optionally injects them over CDP. It resolves browser profile paths and decrypts cookie values per-OS (macOS Keychain, Linux libsecret, Windows DPAPI). Because it always reads that default store, run it only where that browser profile is not the user's live profile (for example a dedicated automation account whose browser the task owns); on the user's own machine it would copy their session, so use Tier 2b instead.
 
 ```bash
 # Extract cookies to a file:
 mkdir -p ~/.local/state/omo-cookies
 python3 -B scripts/extract_cookies.py --browser chrome --domain youtube.com --output ~/.local/state/omo-cookies/youtube.cookies.json
-# Extract and inject into the running CDP session:
+# Extract and inject over CDP (needs a browser started with --remote-debugging-port=9242; connectPipe opens no port):
 python3 -B scripts/extract_cookies.py --browser chrome --domain youtube.com --inject --cdp 9242
 ```
 
-Cookie export files are written with owner-only `0600` permissions. Do not place live auth cookies in shared temp directories or commit them to a repo. Cookie injection sends values to CDP over stdin rather than argv. Cookies apply on next navigation — reload after injecting. Google services use fingerprint-bound tokens that may not transfer across browser profiles. Limits in [references/chrome-stealth.md](references/chrome-stealth.md).
+For a Tier 2a owned page, load the exported file and call `omowright.injectCookies(page, cookies)` instead (see [references/chrome-stealth.md](references/chrome-stealth.md)). Cookie export files are written with owner-only `0600` permissions. Do not place live auth cookies in shared temp directories or commit them to a repo. Cookie injection sends values to CDP over stdin rather than argv. Cookies apply on next navigation — reload after injecting. Google services use fingerprint-bound tokens that may not transfer across browser profiles. Limits in [references/chrome-stealth.md](references/chrome-stealth.md).
 
 ## Reference docs
 
@@ -139,7 +141,8 @@ Cookie export files are written with owner-only `0600` permissions. Do not place
 
 ```bash
 # agent-reach auth: set the channel-specific env vars from each tool's docs only if you have access
-# insane-search needs no env vars — it auto-installs deps on first run
+# insane-search: JINA_API_KEY only for the Jina Reader route (the engine skips that surrogate without it)
+# insane-search Python deps: the install one-liner in references/insane-search/README.md
 ```
 
 ## Anti-patterns

package/packages/shared-skills/skills/ultimate-browsing/engine/AGENTS.md

@@ -61,7 +61,7 @@ is a regression, not an upgrade:
 - **Module split of the fetch chain** — `curl_probe` / `referers` / `url_transforms` /
   `waf_detector` / `validators` / `executor` / `summary` as separate modules rather than
   one monolith.
-- **The Python test suite** under `engine/tests/` with its HTML/JSON fixtures.
+- **The Python test suite** under `engine/tests/` with its HTML/JSON fixtures (source checkout only: the skill copy filter drops `engine/tests/` from every shipped edition).
 - **De-personalization** — no personal absolute paths, no personal auth token literals,
   no personal browser choice; enforced by `depersonalization-gate.test.ts`.
 - **Skill-level layering** — the engine is Tier 1 under a router that also owns Tier 1.5
@@ -115,7 +115,7 @@ Any future upstream sync preserves BOTH sides. Concretely:
 
 ## OVERVIEW
 
-A 17-module Python package embedded in the `ultimate-browsing` skill: a site-agnostic fetch chain that escalates from a cheap curl probe to a real browser, with declarative WAF and surrogate registries. Not "optional scripts" — it has its own CLI entry (`python3 -B -m engine URL`; `-B` keeps bytecode caches out of a signed app bundle, #11373), two YAML config schemas, a 4-file test suite, and a standalone CI guard. Package exports (`__init__.py`): `fetch`, `FetchResult`, `Attempt`, `Verdict`, `ValidationResult`, `validate`, `CHALLENGE_MARKERS`, `detect`, `TRANSFORMS`, `apply_transform`.
+A 13-file Python package (`__init__.py`, `__main__.py` and 11 modules) embedded in the `ultimate-browsing` skill: a site-agnostic fetch chain that escalates from a cheap curl probe to a real browser, with declarative WAF and surrogate registries. Not "optional scripts" — it has its own CLI entry (`python3 -B -m engine URL`; `-B` keeps bytecode caches out of a signed app bundle, #11373), two YAML config schemas, a 6-file test suite (source checkout only), and a standalone CI guard. Package exports (`__init__.py`): `fetch`, `FetchResult`, `Attempt`, `Verdict`, `ValidationResult`, `validate`, `CHALLENGE_MARKERS`, `detect`, `TRANSFORMS`, `apply_transform`.
 
 ## THE NO-SITE-NAME RULE (enforced in CI)
 
@@ -170,11 +170,11 @@ python3 -B -m engine URL [--selector S] [--device auto|desktop|mobile]
 
 ## TESTS
 
-`tests/` — `test_surrogate.py` (staleness, proxy gating, short-circuit), `test_surrogate_validators.py`, `test_fetch_chain.py`, `test_playwright_templates.py`, plus HTML/JSON fixtures under `tests/fixtures/`.
+`tests/` (source checkout only; not shipped with the skill) — `test_surrogate.py` (staleness, proxy gating, short-circuit), `test_surrogate_validators.py`, `test_fetch_chain.py`, `test_playwright_templates.py`, `test_playwright_stealth.py`, `test_executor_timeout.py`, plus HTML/JSON fixtures under `tests/fixtures/`.
 
 ## NOTES
 
 - `summary.py` emits an **R7 API-first hint** after >=3 challenge verdicts against a known WAF profile: look for `/api/`, `/graphql`, or `.json` endpoints, which usually carry weaker WAF protection than the HTML surface.
 - `templates/` holds the Playwright JS templates (`playwright_real_chrome.js`, `playwright_mobile_chrome.js`) the executor drives.
 - `url_transforms.py` transforms stay domain-agnostic (`mobile_subdomain`, `am_prefix`, `drop_www`).
-- Parent: [`packages/shared-skills/AGENTS.md`](../../../AGENTS.md).
+- Parent (source checkout only; not shipped with the skill): `packages/shared-skills/AGENTS.md`.

package/packages/shared-skills/skills/ultimate-browsing/references/agent-reach/README.md

@@ -25,13 +25,13 @@
 mcporter call 'exa.web_search_exa(query: "query", numResults: 5)'
 
 # 通用网页阅读
-curl -s "https://r.jina.ai/URL"
+curl -s -H "Authorization: Bearer ${JINA_API_KEY}" "https://r.jina.ai/URL"
 
 # GitHub 搜索
 gh search repos "query" --sort stars --limit 10
 
 # Twitter 搜索
-twitter search "query" --limit 10
+twitter search "query" -n 10
 
 # YouTube/B站字幕
 yt-dlp --write-sub --skip-download -o "/tmp/%(id)s" "URL"

package/packages/shared-skills/skills/ultimate-browsing/references/agent-reach/career.md

@@ -25,5 +25,5 @@ mcporter call 'linkedin-scraper.search_jobs(keyword: "software engineer", limit:
 如果 MCP 不可用，可以用 Jina Reader：
 
 ```bash
-curl -s "https://r.jina.ai/https://linkedin.com/in/username"
+curl -s -H "Authorization: Bearer ${JINA_API_KEY}" "https://r.jina.ai/https://linkedin.com/in/username"
 ```

package/packages/shared-skills/skills/ultimate-browsing/references/agent-reach/social.md

@@ -105,7 +105,7 @@ twitter likes
 
 ```bash
 # 使用 Jina Reader 读取
-curl -s "https://r.jina.ai/https://weibo.com/USER_ID/POST_ID"
+curl -s -H "Authorization: Bearer ${JINA_API_KEY}" "https://r.jina.ai/https://weibo.com/USER_ID/POST_ID"
 ```
 
 > 微博主要通过网页抓取，推荐使用通用网页读取方式。

package/packages/shared-skills/skills/ultimate-browsing/references/agent-reach/web.md

@@ -6,13 +6,13 @@
 
 ```bash
 # 读取任意网页内容
-curl -s "https://r.jina.ai/URL"
+curl -s -H "Authorization: Bearer ${JINA_API_KEY}" "https://r.jina.ai/URL"
 
 # 示例
-curl -s "https://r.jina.ai/https://example.com/article"
+curl -s -H "Authorization: Bearer ${JINA_API_KEY}" "https://r.jina.ai/https://example.com/article"
 ```
 
-**适用场景**: 大多数网页可以直接用 Jina Reader 读取。
+**适用场景**: 大多数网页可以直接用 Jina Reader 读取。匿名调用返回 401，必须带 `JINA_API_KEY`（见 [../insane-search/jina.md](../insane-search/jina.md)）。
 
 ## Web Reader (MCP)
 
@@ -69,7 +69,7 @@ for e in feedparser.parse('FEED_URL').entries[:5]:
 
 | 场景 | 推荐工具 |
 |-----|---------|
-| 通用网页 | Jina Reader (`curl r.jina.ai`) |
+| 通用网页 | Jina Reader (`curl r.jina.ai`，需 `JINA_API_KEY`) |
 | 需要图片/格式控制 | web-reader MCP |
 | 微信公众号 | Exa (搜索+阅读) / Camoufox (可选阅读) |
 | RSS 订阅 | feedparser |

package/packages/shared-skills/skills/ultimate-browsing/references/chrome-stealth.md

@@ -29,7 +29,8 @@ page that only a signed-in user can reach belongs to the attached engine, not to
 
 ## Cookie login limits
 
-`scripts/extract_cookies.py` still exports cookies from a local browser; inject them with
+`scripts/extract_cookies.py` still exports cookies from a local browser's default profile store (run it only where
+that profile is not the user's live one; see `../SKILL.md`, Cookie login); inject them with
 `injectCookies(page, cookies)` into an **owned** profile. It sanitizes the set (drops expired
 entries, keeps host-prefixed cookies secure and root-scoped). Limits that do not change:
 

package/packages/shared-skills/skills/ultimate-browsing/references/insane-search/README.md

@@ -17,7 +17,7 @@
 2. 즉시 다음을 실행:
    ```bash
    python3 -B -m engine "<URL>" [--selector "<CSS>"] [--device auto|desktop|mobile] [--trace] \
-                              [--no-retry] [--no-extract]
+                              [--timeout 25] [--max-attempts 12] [--no-playwright] [--allow-proxy] [--json]
    ```
 3. 종료코드 0(ok) 또는 1(fail) 받은 뒤 판단. trace를 먼저 읽고 재시도 결정.
 4. 실패 시에만 `--trace --json`으로 재호출해서 원인 진단 후 `--device` 또는 `user_hint` 조정.
@@ -46,7 +46,7 @@
 - Claude는 그 사이 foreground에서 MCP Playwright 정찰 루트를 진행
 - engine이 먼저 성공해도 좋고, MCP 정찰로 얻은 API가 먼저 성공해도 좋음. 빠른 쪽 결과 채택
 
-**MCP 정찰 루트**:
+**MCP 정찰 루트** (Playwright MCP가 로드된 세션 전용. 없으면 the `browser` skill's `references/owned-engine/network.md` 로 같은 XHR/fetch 목록을 모은다):
 1. `mcp__playwright__browser_navigate` → 대상 페이지 로드 (브라우저 렌더링)
 2. `mcp__playwright__browser_network_requests` → XHR/fetch 호출 목록 수집, `/api/`·`/graphql`·`\.json` 필터로 내부 엔드포인트 식별
 3. 식별된 JSON API URL을 `python3 -B -m engine <API_URL>`로 재호출 (백그라운드 engine과는 별개 호출). 대부분 API 레이어는 페이지 HTML보다 WAF 보호가 얕아 curl_cffi로 바로 수집됨
@@ -124,7 +124,7 @@
 ### 단일 진입점
 
 ```python
-from insane_search.engine import fetch
+from engine import fetch      # 스킬 디렉터리에서 실행 (패키지는 engine/)
 
 result = fetch(
     "https://example.com/path",
@@ -136,15 +136,13 @@ result = fetch(
 
 if result.ok:
     print(result.verdict)     # strong_ok | weak_ok
-    html = result.content     # raw body — 단, content-rescue가 발동한 경우 구조 텍스트
-    # v0.10.0 content-rescue: PDF 응답은 pypdf 추출 텍스트, visible text가 얇은
-    # SPA 셸은 JSON-LD articleBody / 렌더된 innerText로 대체될 수 있다.
-    # result.extraction_source로 판별: "raw"(원문 그대로) | pdf | json_ld | *+inner_text.
-    # 일반 HTML 성공은 항상 raw. 끄기: enable_extraction=False / --no-extract.
-    # 429/502/503/504는 probe에서 백오프 재시도(Retry-After 반영, 총 10초 캡);
-    # 끄기: enable_retry=False / --no-retry.
+    html = result.content     # raw body (내장 추출/변환 없음)
+    # 필드: ok, content, final_url, verdict, profile_used, trace, summary,
+    #       provenance, snapshot_timestamp, trust (engine/result_schema.py FetchResult).
+    # 업스트림 신버전의 content-rescue(PDF/JSON-LD 추출)와 Retry-After 백오프는
+    # 이 스냅샷에 없다 — engine/AGENTS.md의 WANT 목록. grid 시도 사이에는 짧은 jitter만 둔다.
 else:
-    # Phase 3 수동 개입 (Playwright MCP) 필요 — result.trace로 원인 진단
+    # result.trace로 원인 진단. 브라우저가 필요하면 아래 "needs_js_exec only 폴백 규칙"을 따른다
     pass
 ```
 
@@ -191,16 +189,17 @@ report     — FetchResult(ok, verdict, profile_used, trace, summary)
 | 태그 | 실행기 | 언제 |
 |------|--------|------|
 | `needs_real_tls_stack` + `needs_js_exec` | `playwright_real_chrome.js` (로컬 Node) | Akamai Bot Manager 등 — Chromium 번들 TLS는 탐지됨 |
-| `needs_js_exec` only | Playwright MCP (`mcp__playwright__*`) | Cloudflare 기본 방어 등 |
+| `needs_js_exec` only | 에이전트가 직접 띄우는 브라우저 (엔진은 stub만 반환, 아래 규칙) | Cloudflare 기본 방어 등 |
 | `needs_mobile_context` (+ real_tls) | `playwright_mobile_chrome.js` | 모바일 디바이스 에뮬레이션 필요 |
 
 자세한 선택 기준: [playwright.md](playwright.md).
 
-### Playwright MCP 호출 규칙
+### `needs_js_exec only` 폴백 규칙
 
-`fetch_chain`의 `needs_js_exec only` 케이스는 **Claude 세션에서 MCP 도구를 직접 호출**해야 한다. subprocess 경로 없음. 즉:
+`fetch_chain`의 `needs_js_exec only` 케이스는 subprocess 경로가 없어 **에이전트가 직접 브라우저를 다뤄야** 한다. 즉:
 1. `result.summary`에 "Playwright MCP must be invoked from the Claude session"이 포함되면
-2. `mcp__playwright__browser_navigate` → `browser_wait_for` → `browser_snapshot` 흐름으로 Claude가 직접 처리
+2. 엔진 문구가 MCP를 가리켜도 기본 경로는 Tier 2a owned engine이다: js eval에서 omowright `connectPipe`, 스텔스는 `connectCloakProfile` (`../../SKILL.md` Tier 2, the `browser` skill's `references/owned-engine/`)
+3. `mcp__playwright__*` 도구는 그 MCP가 이미 세션에 연결된 경우에만 쓴다. 없으면 새로 설치하지 않는다 ([playwright.md](playwright.md))
 
 ## Phase 2 — 수동 개입 (옵션)
 
@@ -233,7 +232,7 @@ Tier 1 추출 폴백 전용이며 에이전트가 직접 브라우저를 다루
 
 ```bash
 # 범용 웹 (Jina Reader — 일반 HTML만, WAF 사이트엔 무효)
-curl -s "https://r.jina.ai/{URL}"
+curl -s -H "Authorization: Bearer ${JINA_API_KEY}" "https://r.jina.ai/{URL}"
 
 # yt-dlp — 1,858 사이트 미디어 메타데이터
 yt-dlp --dump-json "URL"
@@ -290,7 +289,7 @@ yt-dlp --write-sub --write-auto-sub --sub-lang "en,ko" --skip-download -o "/tmp/
 | 파일 | 언제 읽는가 | 무엇을 다루는가 |
 |------|-------------|-----------------|
 | [`tls-impersonate.md`](tls-impersonate.md) | curl_cffi 격자가 전부 `challenge`/`blocked`로 끝날 때, 새 impersonate 타겟을 `waf_profiles.yaml`에 추가할 때 | curl_cffi로 Safari/Chrome/Firefox TLS(JA3/JA4) 지문 복제하는 방법, WAF(Akamai/Cloudflare/F5 등)별 최적 타겟 조합, 임퍼소네이션 타겟 버전 목록, `tls_impersonate_avoid`의 실증 근거 |
-| [`playwright.md`](playwright.md) | engine이 Playwright fallback으로 넘어가는데 MCP/Local Chrome 중 어디로 갈지 확인 필요할 때 | Approach 1 (`mcp__playwright__*` — Cloudflare급 챌린지), Approach 2 (Local Node + `channel:'chrome'` + stealth — Akamai Bot Manager급), 템플릿 파라미터 규격 |
+| [`playwright.md`](playwright.md) | engine이 Playwright fallback으로 넘어가는데 MCP/Local Chrome 중 어디로 갈지 확인 필요할 때 | Approach 1 (이미 연결된 경우의 `mcp__playwright__*`, 없으면 omowright owned engine — Cloudflare급 챌린지), Approach 2 (Local Node + `channel:'chrome'` + stealth — Akamai Bot Manager급), 템플릿 파라미터 규격 |
 | [`fallback.md`](fallback.md) | `verdict`가 애매하거나 Phase 전환 타이밍 결정 필요할 때 | engine의 Phase 0→1→2→3 에스컬레이션 원칙, 응답 성공/실패 판정 기준 세부, 각 Phase 종료 조건 |
 | [`metadata.md`](metadata.md) | 본문 전체를 못 가져왔지만 제목·요약·가격·저자 같은 핵심만이라도 필요할 때 | OGP 메타 태그, JSON-LD (Schema.org), Twitter Card 파싱, 구조화 데이터 추출 패턴 |
 
@@ -298,7 +297,7 @@ yt-dlp --write-sub --write-auto-sub --sub-lang "en,ko" --skip-download -o "/tmp/
 
 | 파일 | 언제 읽는가 | 무엇을 다루는가 |
 |------|-------------|-----------------|
-| [`jina.md`](jina.md) | WAF 없는 일반 웹(블로그·뉴스·Wiki)의 깨끗한 마크다운 추출 필요할 때 | `r.jina.ai/URL` 한 줄로 Puppeteer 기반 JS SPA 렌더링, 마크다운 변환, 무료 500 RPM, API 키 불필요 |
+| [`jina.md`](jina.md) | WAF 없는 일반 웹(블로그·뉴스·Wiki)의 깨끗한 마크다운 추출 필요할 때 | `r.jina.ai/URL` + `JINA_API_KEY` Bearer 헤더(익명 호출은 401)로 Puppeteer 기반 JS SPA 렌더링, 마크다운 변환 |
 | [`cache-archive.md`](cache-archive.md) | 원본 사이트가 차단됐지만 과거 스냅샷으로라도 접근 필요할 때 | Wayback Machine CDX API, archive.today, AMP Cache (Google Cache는 2024-07 종료됨) |
 | [`rss.md`](rss.md) | 뉴스·블로그·커뮤니티의 시계열 업데이트를 구조화해 받고 싶을 때 | RSS/Atom 자동 발견, 피드 파싱, 인증 불필요 — 가장 깔끔한 시계열 데이터 소스 |
 

package/packages/shared-skills/skills/ultimate-browsing/references/insane-search/fallback.md

@@ -23,9 +23,12 @@
 
 ## Phase 1: 경량 프로브 (병렬)
 
+> **R1 ([README.md](README.md))**: 차단된 URL에는 WebFetch나 즉흥 curl을 쓰지 않는다. `python3 -B -m engine "<URL>"`이
+> 아래 Phase 1-3(curl_cffi 프로브, Referer/변환/디바이스 격자, 서로게이트, Playwright 폴백)을 실행한다.
+> 이 문서는 `--trace` 출력을 읽기 위한 단계 설명이다.
+
 **먼저 시도** (동시):
-- WebFetch (Claude 내장)
-- Jina Reader (기본 / JSON / SPA 모드)
+- Jina Reader (기본 / JSON / SPA 모드, `JINA_API_KEY` 있을 때만)
 - curl Chrome Desktop UA
 
 **아직 성공 없으면 추가 시도**:
@@ -34,7 +37,6 @@
 - URL 변형 시도: `.json`, `/rss`, `/feed`
 
 **사이드카** (1차와 동시, low-trust):
-- Google AMP 캐시
 - archive.today
 - Wayback Machine
 → **원본이 하나라도 성공하면 사이드카는 참고만.** 전부 실패 시에만 사이드카 채택 (provenance 태깅 필수)
@@ -90,7 +92,7 @@ for target in TARGETS:
         session = requests.Session(impersonate=target)
         session.headers.update(HEADERS)
         resp = session.get("{URL}", timeout=20)
-        if resp.status_code == 200 and len(resp.text) > 300:
+        if resp.status_code == 200 and len(resp.text) >= 3072 and not any(m in resp.text for m in ("Access Denied", "Just a moment...", "DataDome", "sec-if-cpt-container")):
             # 성공 — JSON-LD도 같이 추출
             break
     except:
@@ -103,7 +105,7 @@ for target in TARGETS:
 
 ---
 
-## Phase 3: Playwright MCP (브라우저)
+## Phase 3: 브라우저 (owned engine, 또는 이미 연결된 Playwright MCP)
 
 **조건**: Phase 2도 실패 또는 JS 챌린지/CAPTCHA 감지
 
@@ -114,7 +116,9 @@ browser_evaluate → () => document.body.innerText  (Light Mode — 먼저)
 필요 시 browser_snapshot → 접근성 트리 전체
 ```
 
-**API 발견**: `browser_network_requests`로 숨은 JSON API를 찾으면 이후 curl_cffi로 재사용 가능.
+위 흐름은 Playwright MCP가 이미 세션에 연결된 경우의 도구 이름이다. 없으면 같은 단계를 Tier 2a owned engine(js eval의 omowright `connectPipe` / `connectCloakProfile`)으로 실행한다 — [README.md](README.md) "`needs_js_exec only` 폴백 규칙".
+
+**API 발견**: `browser_network_requests`(MCP) 또는 owned engine의 `createNetworkSnoop`(the `browser` skill's `references/owned-engine/network.md`)로 숨은 JSON API를 찾으면 이후 curl_cffi로 재사용 가능.
 
 상세: [playwright.md](playwright.md)