docs(skills): sync CLI and SDK guidance with current APIs

[rgarcia]

Summary

Review and update every skill in the kernel-cli and kernel-sdks plugins against the current Kernel CLI README, the command changes from kernel/cli#140, current CLI source, and live API behavior.

This updates all 9 skill documents:

• debug-browser-session
• diff-profile-archives
• kernel-agent-browser
• kernel-auth
• kernel-browser-harness
• kernel-cli
• profile-website-bot-detection
• kernel-python-sdk
• kernel-typescript-sdk

Notable updates

• Current browser diagnostics, telemetry history, default-proxy controls, process env/TTY flags, and cleanup
• Current linked kernel-cli reference files for browsers, managed auth, process execution, profiles, and proxies
• Current profile download formats and archive comparison workflow
• Current managed-auth connection, telemetry, timeline, and canonical submit workflows
• Project/proxy/profile updates, API key rotation, and organization limits
• Current agent-browser session discovery and browser-harness CDP workflow
• Current Python and TypeScript SDK lifecycle, Playwright/CDP, proxy, profile, filesystem, and cleanup examples
• Fix the bundled bot-detection analyzer so it exits after writing its report without calling nonexistent Playwright Browser.disconnect()

The Homebrew command remains brew install kernel/tap/kernel; the current CLI README's onkernel/tap/kernel spelling is not copied here.

Live QA

A separate QA agent exercised every updated skill against the current CLI/SDKs:

• Built the CLI and ran go test ./cmd
• Ran live browser status, screenshots, Playwright, logs, curl, process, filesystem, telemetry, proxy A/B, and deleted-session diagnostics
• Downloaded empty QA profiles in both tar.zst and tar formats and ran the archive comparison workflow
• Tested agent-browser 0.33.0 and browser-harness 0.1.7 against ephemeral Kernel sessions
• Tested managed-auth read/validation paths without creating or modifying auth connections
• Ran real browser create → Playwright/CDP navigation → delete flows with:
  • Python kernel 0.83.0 + playwright 1.61.0
  • TypeScript @onkernel/sdk 0.83.0 + playwright-core 1.62.0
• Type-checked and live-ran the bot-detection analyzer against https://example.com

Safety and cleanup

• No existing resources were modified
• No API keys, projects, proxies, auth connections, org limits, apps, or deployments were mutated
• QA created 8 ephemeral browsers and 4 empty profiles
• QA deleted all 8 browsers and all 4 profiles
• Independent follow-up queries confirmed zero remaining skill-qa-* browsers and profiles

Validation

• All 9 skill frontmatter blocks parse
• All relative links resolve
• git diff --check
• No secrets or real resource IDs in the diff
• All changed skills remain below 500 lines

---

Note

Low Risk
Changes are documentation and a small test-script fix; no application runtime or security-sensitive platform code is modified.

Overview
Brings kernel-cli and kernel-sdks plugin skills in line with current CLI behavior, linked references, and live API semantics so agents follow up-to-date commands and safety patterns.

Browser diagnostics and routing — debug-browser-session adds soft-deleted session lookup (--include-deleted), browsers logs stream instead of raw log paths, Chrome-stack browsers curl vs VM curl, and guarded default-proxy A/B via browsers update --disable-default-proxy. Reference docs document the same update flags for explicit vs default stealth proxy.

Profiles and diffs — diff-profile-archives and profile references drop manual zstd/tar handling and misleading .zip flows; profiles download --to is documented as CLI-managed extraction (tar.zst / tar), with jq -S for JSON diffs and pre-download profiles get validation.

Managed auth — kernel-auth is rewritten around kernel auth connections (create/update/login/submit/follow/timeline), canonical --field-value / --choice-id, telemetry on connections and logins, and safer cleanup vs profile deletion.

Agent tooling — kernel-agent-browser corrects launch defaults (stealth opt-in, headless default), documents KERNEL_PROFILE_NAME breakage in 0.33.0 with a CLI create + CDP persistence path, CDP-endpoint session matching for live view, and runtime proxy toggles. kernel-browser-harness adds EXIT traps, private session JSON files, parallel worker cleanup, and default-proxy updates before harness connect.

Org/admin and references — kernel-cli adds safe operation, project archive/rename, API key rotation / --include-deleted, and org limits. Process reference adds --env and --allocate-tty; proxies add rename and proxies check.

Bot-detection skill — Comparative workflow now isolates network path (direct egress on stealth vs default proxy), uses trapped multi-step cleanup, and fixes test-kernel-bot-detection.ts by removing invalid browser.disconnect() and exiting explicitly after the report.

SDK skills — Python and TypeScript guides expand server-side vs CDP paths, try/finally session deletion, profiles (save_changes, download/rename caveats), proxy check/update, disable_default_proxy, and TypeScript binary via dedicated APIs (not playwright.execute).

^{Reviewed by Cursor Bugbot for commit 3c32b77. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Comparison step uses wrong HOST
  • Updated Step 4 to derive HOST directly from TARGET_URL so report paths always match the analyzer output directory.

Or push these changes by commenting:

@cursor push fac08bb7f1

Preview (fac08bb7f1)

diff --git a/plugins/kernel-cli/skills/profile-website-bot-detection/SKILL.md b/plugins/kernel-cli/skills/profile-website-bot-detection/SKILL.md
--- a/plugins/kernel-cli/skills/profile-website-bot-detection/SKILL.md
+++ b/plugins/kernel-cli/skills/profile-website-bot-detection/SKILL.md
@@ -78,8 +78,8 @@
 Compare the newest report from each mode rather than concatenating multiple JSON documents:
 
 ```bash
-# Set the hostname folder (e.g., chase-com for chase.com).
-HOST=chase-com
+# Derive the hostname folder from TARGET_URL (e.g., chase.com -> chase-com).
+HOST=$(node -e "console.log(new URL(process.env.TARGET_URL).hostname.replace(/\./g, '-'))")
 latest_report() {
   local reports=("$1"/report-*.json)
   [[ -e "${reports[0]}" ]] || return 1

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 867a159. Configure here.}

[dprevoznik]

KERNEL_PROFILE_NAME doesn't currently work with -p kernel — non-blocking, pre-existing

All line references below are plugins/kernel-cli/skills/kernel-agent-browser/SKILL.md.

Tested end-to-end against prod with agent-browser 0.33.0 (current npm latest):

run	result
agent-browser -p kernel open https://example.com	✓ navigates fine
same + KERNEL_PROFILE_NAME=<pre-created prod profile>	✗ 400 can't decode JSON body: json: cannot unmarshal string into Go struct field BrowserRequest.profile of type map[string]json.RawMessage
raw POST /browsers with profile: {name, save_changes: true}, same profile	✓ session created

cli/src/native/providers.rs:417 sends profile as a bare string and sets save_changes nowhere in the CLI source, so the API rejects the body before a session exists. The QA notes in the PR description are consistent with this — the agent-browser path passes cleanly as long as KERNEL_PROFILE_NAME is unset, which is why it wouldn't have surfaced.

Affected: the env-table row (L40), the recommended-config export (L51), the whole Profile Persistence section (L55-61), the manual-login step 4 (L161), gotcha 4 (L423), and the quick-reference export (L430).

One of those bullets is wrong independently of the serialization bug: "The profile is created if it doesn't exist" — the object form with an unknown name returns 400 profile not found, so profiles must be pre-created either way.

Two separate fixes:

1. This PR (optional, ~2 lines): flag it so the skill stops instructing agents into a 400.
2. Upstream: vercel-labs/agent-browser, not our fork — npm publishes from there, so patching kernel/agent-browser won't reach users. ~5 lines in providers.rs to send {"name": <profile>, "save_changes": true}.

Suggested edit for L51:

# export KERNEL_PROFILE_NAME=mysite   # unusable with -p kernel today — see Profile Persistence below

And for the Profile Persistence section, if you want it:

> **Note:** `KERNEL_PROFILE_NAME` does not currently work with `-p kernel`.
> agent-browser sends `profile` as a bare string where the Kernel API requires
> an object, so session creation fails with a 400 before the browser starts.
> Until that is fixed upstream, use `kernel browsers create --profile-name`
> and drive the session over CDP.

[dprevoznik]

LGTM - verified all tests you ran for updates and left comments where i saw discrepancies.

[rgarcia]

Addressed the KERNEL_PROFILE_NAME feedback in 3c32b77 across every affected section of kernel-agent-browser/SKILL.md:

• marks KERNEL_PROFILE_NAME unusable with -p kernel in agent-browser 0.33.0
• removes it from recommended config and quick reference
• removes the incorrect auto-create/save claims
• adds a CLI-created, pre-existing profile + --save-changes + agent-browser --cdp workaround
• clarifies -p kernel and --cdp are separate launch modes
• corrects manual-login and cleanup guidance

Live-tested with agent-browser 0.33.0: created an ephemeral profile/browser via the CLI, attached over CDP, navigated to Example Domain, closed agent-browser, deleted the Kernel session, verified the profile remained readable, then deleted it. Follow-up queries show zero skill-review-* browsers or profiles.

[dprevoznik]

Thanks for the updates. LGTM!