nobrainer-tech-flow 0.0.0-stage → 2.4.0

package/skills/nobrainer-autoimprove/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: nobrainer-autoimprove
+description: "Use when the owner says nb-autoimprove, deep-autoresearch, code-autoresearch, nobrainer-capture-lesson, or nobrainer-continuous-improvement; asks to improve a skill or prompt; or wants a measurable bounded baseline-variant-evaluation loop instead of one subjective rewrite."
+---
+
+# NoBrainer Autoimprove
+
+Improve one artifact only when a frozen evaluation proves a candidate better.
+This independent adaptation applies Andrej Karpathy's
+[autoresearch](https://github.com/karpathy/autoresearch) measure-change-keep loop
+to skills, prompts, instructions and other reviewable artifacts; it is not an
+official Karpathy project.
+
+## Route the smallest fix
+
+Fix an obvious typo, dead link or deterministic defect directly and cover it
+with the normal test. Do not start an experiment when the objective cannot be
+measured, target/evaluator isolation is impossible, or the change needs an
+unapproved production, credential, publishing, safety or irreversible action.
+
+Treat owner correction as evidence, not permission for a global rewrite:
+
+- task-local clarification stays in the task;
+- a repeatable behavior gap becomes a regression scenario;
+- a verified durable fact or preference follows `LEARNING_WRITE_POLICY`:
+  `AUTO_SCOPED` writes one minimal sourced rule to one canonical store, `ASK`
+  prepares one exact diff, and `OFF` keeps it task-local: do not create a durable
+  diff in `AGENTS.md`, `tasks/lessons.md` or a wiki.
+
+On `AGENT_ERROR_CORRECTED`, preserve the failing scenario and error fingerprint,
+fix the active result first, then test the smallest reusable prevention. One
+anecdote never justifies a broad user trait or unrelated write.
+
+## Frame before mutation
+
+Freeze this contract before changing the target:
+
+```text
+TARGET: <one artifact and allowed write scope>
+OBJECTIVE: <one observable improvement>
+BASELINE_VERSION: <commit/hash/copy>
+DEVELOPMENT_EVAL: <representative iteration cases>
+HOLDOUT_EVAL: <unseen promotion cases>
+HARD_GATES: <format, safety and deterministic checks>
+SCORE: <criteria, aggregation, direction and meaningful delta>
+EVAL_INTEGRITY: <separate owners, access and calibration controls>
+SCORE_RECEIPT: <append-only trial identity, provenance, raw evidence and decision>
+NOISE_POLICY: <paired repetitions, dispersion and retry rule>
+BUDGET: <finite variants, rounds, repetitions, retries, time and resources>
+PLATEAU: <minimum delta and dry rounds>
+ROLLBACK: <retained baseline, restore and readback>
+OWNER_GATES: <action, owner and recorded evidence>
+```
+
+Preserve the baseline in an isolated copy, branch or worktree. One coordinator
+owns the champion and log; candidates never race on the same file.
+
+## Return a complete initial plan
+
+An initial plan comes from a completed experiment contract, not a summary of
+this skill. Resolve every field internally; the owner-facing plan need not mirror
+internal labels. Never omit a hard gate or replace exact evidence with
+"immutable receipt", "bounded budget" or similar shorthand.
+
+The plan must operationalize:
+
+- an observable access boundary: candidate write scope excludes evaluator
+  inputs, labels, logic, extractor, cases and holdout;
+- ordinary positive, known-bad and tailored deceptive controls for the literal
+  gaming, omission and unsafe-abstention risks;
+- fixed baseline/candidate identity, exact paired run count, blind or shuffled
+  presentation, seeds or sampling rule, dispersion, score math and threshold;
+- the complete per-trial receipt fields, not a mutable aggregate;
+- a disjoint holdout frozen before tuning, opened once, never reused for
+  iteration, with measurable primary delta, uncertainty rule and protected
+  usefulness, safety or regression guardrails;
+- every supplied ceiling or an explicit stricter one, honest terminal states,
+  and each named owner's approval identity, scope, timestamp/evidence and next
+  gate. An experiment win grants no live or durable authority.
+
+A ceiling needs a concrete quantity and unit; a label or promise to predeclare
+one later is not a ceiling.
+
+Unless the owner supplies another terminal, end plan-only output with
+`STATUS: READY_FOR_OWNER_REVIEW | BLOCKED` and `EXECUTION: NOT_STARTED`. Pending
+future gates normally mean ready for review. Use `BLOCKED` only when a missing
+fact, boundary or decision prevents a valid proposal. Never imply that
+calibration, trials or approval ran. Any owner-defined exact terminal values,
+including experiment-result terminals, suppress canonical status and execution.
+
+`STRICT_CAP` makes the owner's word limit a hard gate. Before applying either
+formula, if `limit <= 40` with a counter or `limit <= 50` without one, skip the
+reserved-offset formula and use the owner's actual cap for a minimal complete
+answer. Return `BLOCKED` within the cap only when required facts cannot fit;
+small limits alone are not a blocker. Otherwise apply the existing formula. At 250 words or
+fewer, budget the draft to `min(limit - 40, 140)` words in at most six nonblank lines.
+With a counter, compress until the owner limit passes; without one, target
+`min(limit - 50, 130)` and never claim an exact count. Print no heading, blank
+line, internal form, rollback explanation or duplicate terminal. Group only:
+access; sets/controls; trials/receipt; holdout/decision; limits/stops; gates.
+Preserve exact numbers, owners and negations; invent no optional mechanism.
+Treat scope and timing qualifiers, closed field sets and terminal value domains as
+non-compressible: reuse their literal wording instead of a plausible synonym.
+When a qualifier applies to each role or item, repeat it for each; collective
+shorthand is not equivalent.
+If the owner gives a word range or minimum, its lower bound is also a hard gate
+and overrides the compact budget. For an exact range, count the final draft with
+an available whitespace counter and adjust once. Without one, target the range
+midpoint and tally whitespace-delimited words before sending. For a bare minimum,
+leave at least 10% headroom. Never exceed a stated maximum.
+Count exact final text. For a serialized draft, pipe it through the bundled
+`scripts/count_words.py --escaped-newlines`; a raw `%s` count is invalid evidence.
+
+Run `CAP_AUDIT` before compact output: preserve disjoint one-time holdout and
+open-once semantics; reproduce an exact receipt field list with no additions;
+retain `immediately` when stops are immediate; and when the owner defines exact
+terminal values, append no canonical status or execution field. If required
+facts cannot fit, return `BLOCKED` within the cap rather than omitting them.
+Scan the complete draft once more: no later duty may contradict a role's `only`
+boundary, and every closed value domain retains its literal `only` or `no other`
+qualifier.
+
+## Protect evaluator integrity
+
+The evaluator owner and candidate owner must be separate. Candidate write scope
+excludes the rubric, development/holdout cases, score extractor and acceptance
+harness; keep them read-only and outside the candidate workspace when possible.
+A prompt-only prohibition is insufficient when the generator can mutate the
+score path. Record weaker isolation and do not promote a gameable result.
+
+Before baseline scoring, calibrate the complete path on ordinary positive,
+known-good, known-bad and tailored deceptive controls. It must rank good above
+bad, reject deceptive metric gaming, and self-test score extraction and hard
+failures. Trace every rubric requirement to the frozen request; a hidden
+judge-only requirement invalidates the evaluator. Missing ground truth or failed
+calibration is `BLOCKED`.
+
+Bind every score to an append-only immutable receipt containing: experiment and
+round ID; candidate ID and target hash; case-set, evaluator, rubric and extractor
+hashes; judge version/settings; seed or sampling policy and call order;
+input/data snapshot and configuration; timestamp, repetition ID, environment and
+budget identity; raw evidence; criterion vector, hard gates, inclusion,
+retry/error/stop and resulting decision; aggregation formula, inputs, math and
+aggregate. Content-address it and forbid post-hoc edits. Changed provenance makes
+results non-comparable: re-baseline instead of carrying a score forward.
+
+Predeclare at least three paired repetitions under identical conditions and
+compare aggregated gain with measured dispersion. Forbid cherry-picking and
+favorable retries. Retry only one predeclared transient failure; receipt and
+count it, never retry to change a result. A calibrated deterministic evaluator
+may run once when its receipt proves determinism.
+
+Production deployment, credentials, publishing, security or system changes,
+external contact, spend, destructive actions, durable policy, lessons or wiki
+writes remain named owner gates. Record the owner, decision and evidence
+reference before action; experiment success grants none of them.
+
+## Run the bounded loop
+
+`FRAME -> CALIBRATE -> BASELINE -> GENERATE -> HARD_GATE -> DEV_SCORE -> SELECT -> FINAL_HOLDOUT -> PROMOTE_OR_REVERT`
+
+Use development cases for common, edge, adversarial and non-trigger behavior.
+Prefer one behavioral change per round and three to six genuinely different
+candidate hypotheses. Run deterministic, public-clean and security gates before
+judge spend. A hard-gate failure, missing receipt or failed calibration is
+disqualified, not averaged down.
+
+Score on the unchanged development eval. Select only beyond measured noise; on
+a near-tie keep the simpler, shorter, lower-risk artifact. One optional graft may
+combine distinct strengths from a losing candidate, then rerun every gate.
+
+Open the sealed holdout exactly once for the unchanged baseline and champion.
+Promotion requires all hard gates, the predeclared meaningful primary gain, no
+protected regression, target-workflow review when subjective, retained baseline
+and tested rollback. A holdout loss is `REVERTED`; never tune on that holdout.
+Any next attempt needs a new holdout, new baseline and new experiment record.
+
+When nested under `nobrainer-tech-flow`, update its one canonical TODO after each
+auditable round and final holdout; do not create a second status owner.
+
+## Stop the experiment, not the outcome
+
+Stop the current experiment on its predeclared decision, failed evidence or
+safety anomaly, configured dry rounds, practical score ceiling, exhausted
+budget, converged candidates, hard-gate regression, holdout loss, or changed
+target/constraints/authorization. A null result retains the baseline.
+
+These stops do not close a still-open owner outcome. If proved improvement is
+still required, diagnose frozen evidence once, choose the smallest high-leverage
+change and start a fresh bounded experiment. Never reuse a failed holdout or
+substitute blind retries. Apply Pareto discipline: remove the largest observed
+failure before polishing lower-impact criteria. Close only when DoD passes or a
+concrete authority, access, budget or distinct-hypothesis blocker is reported.
+
+## Final report
+
+Return winner/baseline identity, development and holdout scores, criterion
+vectors, hard-gate output, noise/dispersion, calibrated evaluator status, budget,
+stop reason, diff, rollback and uncertainty. End with:
+
+```text
+PROMOTION: PROMOTED | NO_CHANGE | REVERTED | BLOCKED
+CHAMPION: <version/ref or BASELINE>
+HOLDOUT_RESULT: PASS | FAIL | NOT_RUN
+EVALUATOR_STATUS: CALIBRATED | FAILED | UNVERIFIED
+SCORE_RECEIPT: <immutable receipt ref or NONE>
+NOISE_RESULT: <replications, dispersion and comparable delta or NOT_APPLICABLE>
+```
+
+Use `NO_CHANGE` when no candidate proves better, `REVERTED` after holdout loss,
+and `BLOCKED` when a gate prevents a valid experiment. Never claim `PROMOTED`
+without paired comparable scores and a successful holdout.

package/skills/nobrainer-autoimprove/scripts/count_words.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+"""Count whitespace-delimited words in raw or newline-escaped text."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--escaped-newlines", action="store_true")
+    args = parser.parse_args()
+    text = sys.stdin.read()
+    if args.escaped_newlines:
+        text = text.replace("\\r\\n", "\n").replace("\\n", "\n").replace("\\r", "\n")
+    print(len(text.split()))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/nobrainer-browser/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: nobrainer-browser
+description: "Use when the owner says nb-browser or nobrainer-browser, asks to inspect or operate a rendered website, attach to an existing approved Chrome/Edge session, restart an approved non-default Chromium profile for loopback CDP, reproduce a browser flow, run Playwright tests, or record and analyze a Playwright trace. Prefer a current Playwright CLI with an explicit version readback; do not set up MCP or extra browser plugins by default."
+---
+
+# NoBrainer Browser
+
+Choose the browser path from the active client and the operation the task needs.
+In Codex desktop, prefer its built-in browser for ordinary rendered-site work;
+use Playwright CLI for repository browser tests, repeatable automation and trace
+analysis. Do not add a second browser framework merely because one exists.
+
+## Route the task
+
+| Need | Default |
+|---|---|
+| In Codex desktop, inspect or operate a rendered website or local app | Codex built-in browser (`@Browser`) when the active host exposes it |
+| In Codex desktop, use an already approved regular Chrome session | `@Chrome` through the approved browser extension when available; otherwise use the explicit CDP attach path below only when requested and approved |
+| In other clients, inspect or operate a rendered page | That client's documented native browser capability; do not assume Codex or Playwright features exist |
+| Run or debug repository tests | the repository's `npx playwright test` |
+| Record or inspect failure evidence | Playwright trace + `show-trace` |
+| Plain static content already available without a browser | use the cheaper read path |
+
+### Codex browser preference and capability
+
+On the first browser task in a Codex desktop task/session, check for an explicit
+browser preference in the current instructions or earlier owner choice. If none
+is recorded, tell the owner briefly: "I'll use Codex's built-in browser by
+default; tell me if you'd prefer an already approved Chrome session." Continue
+with the built-in browser without waiting for a reply when it exposes the
+operation needed. Do not ask again in the same task/session after a preference
+is known. A preference stated for one task applies to that task; change the
+default only when the owner says it is a lasting preference. Record and reuse a
+lasting choice through the client's supported personalization mechanism only
+when authorized; report when the client provides no such mechanism instead of
+claiming it was saved.
+
+The Codex desktop built-in browser can open pages and interact with rendered
+state, including clicks, typing, screenshots and result verification. Invoke
+or reference it as `@Browser` when the active Codex host supports browser use.
+It uses a separate browser profile and does not automatically inherit regular
+Chrome tabs, logins or session state. Ask for a preference when an existing
+authenticated session might matter, but keep the question non-blocking when the
+built-in browser can safely do the task. Use the approved Chrome extension path
+(`@Chrome`) when the owner chooses their regular browser session and that
+capability is available. Use CDP attach only under the existing-session rules
+below. Never copy cookies or profile data between browsers.
+
+Confirm the required operation is actually exposed before selecting a route.
+An `open_in_codex` browser-panel/display capability can show a URL or browser
+tab in the Codex UI; by itself it does not provide browser automation, page
+inspection, user approval or proof of a side effect. Do not treat it as an
+`@Browser` interaction capability. If the native browser is unavailable or
+cannot perform the needed operation, state the exact missing capability and
+use an available, authorized alternative (such as the Playwright CLI) only when
+it satisfies the task's login and safety needs. If no safe capable route is
+available, stop and report the limitation.
+
+For clients other than Codex, inspect that client's live/documented native
+browser support first. This preference rule does not make `@Browser`, `@Chrome`
+or Codex panel tools portable to other clients.
+
+Do not install MCP when the CLI covers the task. Do not install a browser
+plugin as the default path. Reuse an already configured MCP only when the
+current harness cannot perform the required operation and the MCP has fresh
+capability readback.
+
+## Capability and install gate
+
+First inspect local capabilities independently and keep the interactive and
+repository-test CLIs distinct:
+
+```bash
+global_cli_status=none
+local_test_cli_status=none
+
+if command -v playwright-cli >/dev/null 2>&1 &&
+   playwright-cli --version >/dev/null 2>&1; then
+  global_cli_status=usable
+fi
+
+if [ -f package.json ] &&
+   [ -x node_modules/.bin/playwright ] &&
+   node_modules/.bin/playwright --version >/dev/null 2>&1; then
+  local_test_cli_status=usable
+fi
+
+printf 'global_cli=%s\n' "$global_cli_status"
+printf 'local_test_cli=%s\n' "$local_test_cli_status"
+
+if [ "$global_cli_status" = usable ] ||
+   [ "$local_test_cli_status" = usable ]; then
+  printf 'some_playwright_capability=available\n'
+else
+  printf 'some_playwright_capability=none\n' >&2
+  exit 1
+fi
+```
+
+Use `global_cli=usable` for interactive `playwright-cli` work. Use
+`local_test_cli=usable` only for the repository's standard Playwright test CLI;
+it does not prove that interactive `playwright-cli` commands such as `attach`,
+`snapshot`, `click` or `fill` are available. If the capability required by the
+request is not usable and setup is not in scope, stop with the exact missing
+capability and one remediation; do not query npm or install.
+
+When setup is explicitly in scope and the required local capability is not
+available, use the current npm channel only to discover a version, then pin
+that exact version for execution and record the readback:
+
+```bash
+PLAYWRIGHT_CLI_VERSION="$(npm view @playwright/cli version)"
+test -n "$PLAYWRIGHT_CLI_VERSION"
+npm install -g "@playwright/cli@$PLAYWRIGHT_CLI_VERSION"
+playwright-cli --version
+playwright-cli --help
+playwright-cli --help attach
+```
+
+Package installation is a machine write. Perform it only when setup is within
+scope, and do not claim success until the binary readback passes. For a test
+repository, prefer its lockfile and package scripts over changing dependencies.
+
+The CLI also offers `playwright-cli install --skills`. Do not run it by default
+while `nobrainer-browser` owns browser routing: that would add another skill
+owner with overlapping triggers. Read the live CLI help instead. If the owner
+chooses the upstream Playwright skills, reconcile to one browser-skill owner
+rather than keeping both active.
+
+## Restart an approved profile for CDP attach
+
+Use this flow only when the owner explicitly approves closing the target browser
+and the target is an existing, dedicated Chromium user-data directory. It is
+not a way to make a daily/default Chrome profile remotely debuggable. Read the
+[bounded CDP profile restart reference](references/cdp-profile-restart.md)
+before any process or profile action; it separates identity readback, stopping,
+loopback launch, endpoint verification and CLI attach.
+
+## Existing-session attach
+
+Use attach when the owner needs the actual approved session, login or open tab:
+
+```bash
+playwright-cli attach --cdp=chrome
+playwright-cli attach --cdp=http://127.0.0.1:9222
+# Example for a separately configured Edge debugging endpoint:
+playwright-cli attach --cdp=http://127.0.0.1:9333
+```
+
+The current CLI accepts a supported channel such as `chrome` or an actual CDP
+endpoint URL; verify the live `attach` help because this interface can change.
+CDP attach is Chromium-only. Confirm the exact browser, profile, endpoint and
+write scope before acting. The CLI also exposes extension attach, but that is
+not the default because it requires a browser extension. If attach is
+unavailable, say so; do not bypass a saved browser permission block, copy or
+mirror a profile, extract cookies, reuse credentials, or silently launch a
+look-alike authenticated session. A request to inspect does not authorize form
+submission, purchase, publication, message sending, deletion or account
+changes.
+
+If no existing login is required, a disposable session is simpler:
+
+```bash
+playwright-cli open https://example.com
+```
+
+## Inspect and operate
+
+Take a fresh snapshot before using element references, and refresh it after a
+navigation or substantial DOM change:
+
+```bash
+playwright-cli snapshot
+playwright-cli find "Settings"
+playwright-cli click e4
+playwright-cli fill e7 "value"
+playwright-cli eval "el => el.textContent" e4
+```
+
+Prefer semantic refs and visible state over brittle coordinates. For each
+material action, verify the resulting URL, visible state or downloaded artifact
+instead of trusting command exit alone.
+
+## Tests and traces
+
+Use the repository's existing script/config first. Narrow the test target and
+record a trace when reproduction or evidence matters:
+
+```bash
+npx playwright test path/to/spec --trace on
+REPORT_PORT=9324  # replace with an available explicit port
+npx playwright show-report --port "$REPORT_PORT"
+npx playwright show-trace trace.zip
+```
+
+For a live CLI flow:
+
+```bash
+playwright-cli tracing-start
+playwright-cli snapshot
+# perform the bounded steps
+playwright-cli tracing-stop
+```
+
+Locate the actual trace artifact, preserve its path and open it. Review Actions,
+DOM snapshots, Network, Console and Source; a green status without the expected
+side effect is not proof. Use an available explicit report port; do not assume
+that `--port 0` selects an ephemeral port across CLI versions. Treat traces as
+sensitive artifacts: they may contain cookies, headers, form values, URLs,
+payloads and private page content. Keep them in a project-ignored or temporary
+path, inspect and redact before sharing, and never commit them as routine
+evidence. Do not edit project trace policy merely to inspect one failure when a
+CLI flag is sufficient.
+
+## Failure and closeout
+
+- If the CLI, target session or required permission is unavailable, stop with
+  the exact failed probe and one remediation.
+- If a trace cannot reproduce the issue, report `NOT_REPRODUCED`; do not invent
+  a cause.
+- For an attached external session use `playwright-cli detach`; never close it.
+  Restart or close an existing profile only through the explicit pre-attach flow
+  above. Close only a disposable session owned by this CLI run.
+- Report the exact CLI version, browser/session mode, pages or tests inspected,
+  trace/report paths, observed result, side effects, uncertainty and cleanup.
+
+Sources: [Codex and built-in browser](https://learn.chatgpt.com/docs/browser),
+[ChatGPT browser extension](https://learn.chatgpt.com/docs/chrome-extension),
+[Playwright attach](https://playwright.dev/agent-cli/commands/attach),
+[Playwright `connectOverCDP`](https://playwright.dev/docs/api/class-browsertype),
+[Playwright test CLI](https://playwright.dev/docs/test-cli),
+[Trace Viewer](https://playwright.dev/docs/trace-viewer),
+[Chrome remote-debugging security changes](https://developer.chrome.com/blog/remote-debugging-port),
+and [`@playwright/cli` on npm](https://www.npmjs.com/package/@playwright/cli).

package/skills/nobrainer-browser/references/cdp-profile-restart.md

@@ -0,0 +1,93 @@
+# Restart an approved profile for CDP attach
+
+Use this reference only when the owner explicitly approves closing the target
+browser and the target is an existing, dedicated Chromium user-data directory.
+The shell examples are POSIX; use the platform equivalent for process readback
+and graceful exact-PID stopping on another operating system.
+
+## Resolve and preflight
+
+Resolve these values without printing secrets or persisting the profile path:
+
+```text
+BROWSER_EXECUTABLE: <approved Chrome, Chromium or Edge binary>
+BROWSER_PID: <exact numeric PID read back from that executable and profile>
+BROWSER_USER_DATA_DIR: <existing, approved non-default user-data directory>
+BROWSER_PROFILE: <profile directory inside that user-data directory>
+CDP_PORT: <unused local port>
+PLAYWRIGHT_CLI_SESSION: <named CLI session>
+```
+
+Read the exact process identity and arguments, confirm the executable and data
+directory match, and check for unsaved work. Continue only when the readback is
+`PROCESS_MATCH=PASS`, `PROFILE_MATCH=PASS` and `UNSAVED_WORK=NONE`. Run the
+preflight and stop as separate invocations:
+
+```bash
+test -n "$BROWSER_PID"
+case "$BROWSER_PID" in
+  ''|*[!0-9]*) printf '%s\n' 'BROWSER_STOP_BLOCKED'; exit 1 ;;
+esac
+ps -p "$BROWSER_PID" -o pid=,comm=,args=
+```
+
+If any preflight match is missing, return `BROWSER_STOP_BLOCKED` and stop. Do
+not use a broad process matcher. A force stop requires a fresh identity readback
+and a second explicit owner approval for that exact PID.
+
+## Stop and relaunch
+
+After the pass readback, stop the exact process in a separate invocation:
+
+```bash
+kill -TERM "$BROWSER_PID"
+```
+
+After a bounded grace period, re-read the process list and profile lock. Require
+`BROWSER_PID=GONE` and `PROFILE_LOCK=GONE` before continuing. If the process
+remains or the profile is locked, return `BROWSER_STOP_BLOCKED` and stop; never
+continue against a locked profile.
+
+Start the same approved profile with CDP bound to loopback only:
+
+```bash
+"$BROWSER_EXECUTABLE" \
+  --remote-debugging-address=127.0.0.1 \
+  --remote-debugging-port="$CDP_PORT" \
+  --user-data-dir="$BROWSER_USER_DATA_DIR" \
+  --profile-directory="$BROWSER_PROFILE" \
+  about:blank &
+BROWSER_LAUNCH_PID=$!
+```
+
+Chrome 136 and newer requires `--user-data-dir` to point to a non-default data
+directory when remote debugging is enabled. Do not point this flow at the
+daily/default directory, copy or mirror a profile, extract cookies, add a
+permissive remote-origin wildcard, or bind CDP to a non-loopback address. If the
+only available session is the daily/default profile, use the approved extension
+attach path or a disposable/Chrome-for-Testing profile instead.
+
+## Verify and attach
+
+Read back the endpoint before attaching. If it does not respond, return
+`BROWSER_ATTACH_BLOCKED` and stop; do not silently switch to another profile or
+endpoint:
+
+```bash
+curl --fail --silent --show-error "http://127.0.0.1:${CDP_PORT}/json/version"
+playwright-cli attach --cdp="http://127.0.0.1:${CDP_PORT}" --session="$PLAYWRIGHT_CLI_SESSION"
+playwright-cli --session="$PLAYWRIGHT_CLI_SESSION" list
+playwright-cli --session="$PLAYWRIGHT_CLI_SESSION" snapshot
+```
+
+The endpoint, page list and snapshot prove connectivity only; they do not
+authorize form submission, publication or other external side effects. Confirm
+the expected browser, profile and tab before operating. Record the exact CLI
+version, browser/session mode and observed pages, but redact the profile path,
+cookies, headers and private page data.
+
+If the CLI created the browser itself, `playwright-cli close-all` or
+`playwright-cli kill-all` may be used only for those CLI-owned sessions after a
+fresh `playwright-cli list`. Do not use either command to close an externally
+attached profile. After an external attach, use `playwright-cli detach`; never
+close the attached browser from the CLI.