> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage and Command Reference

> Complete MonoSurf 0.11.3 guide: profiles, collision-safe managed-CDP ownership, explicit cookie bridge import, bound navigation proof, external attach, browsing, collection, network capture, web QA, site commands, grants, and diagnostics.

# Usage and Command Reference

This page covers the complete supported MonoSurf command surface and the
important compatibility boundaries around it.

*Verified against `monosurf 0.11.3`, OpenCLIs build
`2026-07-19-222928`.*

## Install and Inspect the Contract

```bash theme={null}
openclis install monosurf

monosurf version
monosurf
monosurf docs
```

`monosurf` with no arguments prints the current command and option guide.
`monosurf version` prints only the installed version. The installed guide is
the exact syntax authority when it differs from an older web page.

OpenCLIs exposes the public discovery guide and command-aware wrapper steps:

```bash theme={null}
openclis init monosurf
OPENCLIS_NEXT=1 openclis monosurf browse https://example.com --extract
```

The wrapper preserves the full native output and adds bounded guidance for
`browse`, `bridge`, `postcondition`, `start`, `stop`, `profile`, and `doctor`,
including the foreign-port and login/permission failure paths. Run the native
binary directly when no wrapper guidance is needed.

## Release Provenance

The current OpenCLIs release is monosurf 0.11.3, build
`2026-07-19-222928`. `latest.json`, every platform entry, the immutable
`monosurf-v0.11.3` tag, and the main branch all resolve to clean source commit
`75af74b0132b5e9308f50c4e94b2c0407d814bc9` with `source_dirty: false`.

| Public platform   | Archive SHA-256                                                    | Extracted payload SHA-256                                          | Distribution and runtime proof                                                                                                                                 |
| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `darwin-aarch64`  | `6b077a4530485b5bd6b886b642a07db97a7051157ab26a2cc97f34070ec242fa` | `3be1607b2b2ceb46170328962961a358dfb7eb6e44cd5a8c504ee0cf31ec30a4` | Mach-O arm64; installed and executed; strict Developer ID verification and Apple notarization accepted                                                         |
| `linux-x86_64`    | `3d46e6ac5fef87036d4933acbfd6b376f67709854f1dd4218f8afa6e71666578` | `7b0e2ee486fe4a5fb21a00d06af1ec3230245b3b1d4cbc2f9a5e8b2e19528dd2` | Dynamically linked x86-64 ELF; installed and executed in Ubuntu 24.04 WSL; version, bridge/postcondition help, and doctor passed                               |
| `linux-aarch64`   | `b5313ab669253ee9c5f52311a81092df946955c11e7a745f1b30276704a6cdb4` | `bed4ea6cfde4d31e134b4c411006d7915fba581416d0f88457d43e715b2e4324` | Dynamically linked AArch64 ELF; built on the Linux ARM64 runner and independently downloaded, hash-checked, and format-checked                                 |
| `windows-x86_64`  | `608d72322ac532c16b0c1f711fd1f25dae55ef17d35df9b6c3fbd3bdd037edee` | `8fd7c3256aacc0e4a776f8e399c70bf2192fc3ed21a8427efa43172c677739b3` | PE32+ x86-64; publicly downloaded and installed with matching hashes; version, bridge/postcondition help, and doctor later executed successfully on Windows 11 |
| `windows-aarch64` | `5e40ebd7a2db78a5bfe8996edba084b6a37534d76e90a2d1e441af084771be74` | `f0054d86f292183409e6a7b9e9abbbd5cd050e385cbc022b0c3123950cbdf3a2` | PE32+ AArch64; built on the Windows ARM64 runner, published by the Ubuntu follow-up job, then independently downloaded, hash-checked, and format-checked       |

All five platform archives are public and match immutable `meta.json` hashes.
Each contains the same seven source-owned guide files, including
`initiate.json`; their text matches the tagged source after normalizing Windows
line endings.

Those CLI archives do not bundle `monolex-native-host`. Main/public registry
commit `ade36c68f9d2e7cc1982b4412105e933317d6fe9` adds the explicit Monolex
desktop prerequisite after the release tag; this is a documentation and
registry correction, not a replacement artifact or changed release hash.

The installed macOS payload reported monosurf 0.11.3, passed `doctor`, and
completed a real extension/native-host bridge test using the shared host staged
by Monolex desktop, with fixed extension id
`cclkmkgheebiiommelcnjindolniongm`. The test imported an exact HttpOnly cookie
with its security attributes, reopened the same managed profile, hydrated an
empty target before navigation, verified the resulting session, and cleaned up
the temporary state.

Windows publication is intentionally separate from Windows trust policy. The
0.11.3 x86-64 archive was published and installed successfully, and the
installed file had no Mark-of-the-Web stream; its Authenticode status was
`NotSigned`. On its first installation, Windows 11 Smart App Control/WDAC Code
Integrity events 3077
and 3033 rejected the new hash at the Enterprise signing level under policy
`{0283ac0f-fff1-49ae-ada1-8a933130cad6}`. Rolling back made the previous
trusted monosurf 0.10.5 payload runnable. A later 0.11.3 installation of the
same verified payload executed successfully and returned a clean doctor report;
no signing or hash change explains that transition. Treat execution of a new
unsigned hash as host-policy and reputation dependent. The artifact was public
throughout; an initial policy block is not evidence of an absent Windows
release.

A platform archive proves distribution and integrity. Direct execution proves
runtime behavior only on the host where it ran; the ARM64 rows above are
archive/format and CI witnesses, not local runtime claims.

Kernel CLI 0.26.8 embeds the `lib-monosurf 0.11.3` facade and
`lib-monosurf-core` engine. Every command family on this page can also be
entered after the `kernel-cli websurf` prefix. Both entry points share the
command and state contract, profile TUI, profiles, plugins, grants, and browser
state; neither needs to launch the other as a subprocess:

```bash theme={null}
kernel-cli websurf --help
kernel-cli websurf browse https://example.com --extract
kernel-cli websurf profile info work
```

The standalone 0.11.3 artifact and Kernel CLI 0.26.8 expose the same facade,
engine, command, and state contract. Their independently published executables
are not byte-identical.

The typed MCP `websurf` adapter intentionally exposes only `plan`, `browsers`,
`profiles`, and `site`; use either terminal prefix for the complete
compatibility surface documented here.

When a page flow reaches browser chrome or a native dialog, leave the DOM
surface and continue with Kernel CLI `targets` → `act`, then return to the page
to verify. Kernel CLI 0.26.8 emits browser-aware guidance for shallow native
targets, verified coordinate entry into a browser, and a browser URL hidden
from accessibility. It also distinguishes a non-browser embedded webview from
a CDP-attachable browser and binds route/order guidance with SOP v2. It still
reserves `websurf.native_dialog` for a future
positive handoff signal rather than emitting it from every web call. See the [Kernel CLI routing
contract](/kernel-cli/reference#result-guided-routing).

## Quick Start

Read a public page in a clean temporary session:

```bash theme={null}
monosurf browse https://example.com
monosurf browse https://example.com --extract
```

Create a persistent browser identity for logged-in work:

```bash theme={null}
monosurf profile new work
monosurf start --profile work
# Log in through the Chrome window.

monosurf auth grant read 1h
monosurf x trending --profile work
```

## Supported Command Map

| Command         | What it does                                                                                                          | Important controls or aliases                                   |
| --------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `start`         | Starts the managed Chromium instance for a named profile, or reuses only a listener that passes the ownership policy. | `--profile`, `--headless`, `--browser`, `--allow-binary-change` |
| `stop`          | Stops a managed profile's browser without deleting its login state; the port fallback signals only a verified owner.  | `--profile`                                                     |
| `profiles`      | Lists registered profiles, account labels, running state, and the default.                                            | `status` is an alias; add `--json` for automation.              |
| `profile`       | Creates, selects, inspects, renames, labels, and removes profiles, or opens the human TUI.                            | Subcommands are listed below.                                   |
| `browsers`      | Discovers supported local Chromium engines and their identities.                                                      | `--json`                                                        |
| `login`         | Opens a site login flow and records the resulting account/session state.                                              | Domain or platform argument, `--profile`                        |
| `browse`        | Opens a URL for text, structured extraction, JavaScript evaluation, collection, network capture, or web QA.           | `b` is an alias; all browse controls are listed below.          |
| `postcondition` | Clicks one exact control and binds the write to navigation/viewport/target/header or toast evidence.                  | `navigation`, `toast`, `--cdp-url`, bounded `--timeout`         |
| `bridge`        | Installs the fixed-ID Chrome bridge or receives explicit cookie Sync clicks into protected snapshot storage.          | `install`, optional `[domain]`, `--keep`                        |
| `x`             | Runs the installed X site plugin.                                                                                     | `x.com` is an alias.                                            |
| `<domain>`      | Runs any installed JSON site plugin by domain.                                                                        | Command names and intent come from that plugin.                 |
| `sites`         | Lists, searches, verifies, installs, publishes, resets, and indexes site plugins.                                     | Subcommands are listed below.                                   |
| `batch`         | Reports or stops a background batch-posting job.                                                                      | `status`, `stop`; a site plugin starts the job.                 |
| `auth`          | Grants, revokes, or reports time-limited read/write access.                                                           | `grant`, `revoke`, `status`                                     |
| `doctor`        | Reconciles profile registry, browser directories, pid records, and temporary-session debris.                          | `fsck` is an alias; default is read-only.                       |
| `selftest`      | Runs offline regression checks for typing, temporary-profile cleanup, or collection stall handling.                   | `typing`, `leak`, `collect`                                     |
| `docs`          | Lists or prints documentation embedded in the installed binary.                                                       | Topics: `index`, `profiles`, `doctor`, `security`               |
| `help`          | Prints the full installed usage guide.                                                                                | `-h`; no arguments and `--help` also show the guide.            |
| `version`       | Prints the installed version.                                                                                         | `-v`                                                            |

### Command aliases

| Alias                            | Canonical form                         |
| -------------------------------- | -------------------------------------- |
| `status`                         | `profiles`                             |
| `b`                              | `browse`                               |
| `x.com`                          | `x`                                    |
| `fsck`                           | `doctor`                               |
| `profile list`                   | `profile ls`                           |
| `sites ls`, `sites s`, `sites i` | `sites`, `sites search`, `sites index` |
| `batch s`, `batch kill`          | `batch status`, `batch stop`           |

## Profiles and Browser Engines

A profile is an isolated, persistent browser identity. Stopping its browser is
normal: the login state lives in the profile and survives close and reboot.
Removing the profile is the operation that deletes that state.

```bash theme={null}
monosurf start --profile work
monosurf profiles --json
monosurf stop --profile work
```

### Profile commands

| Command                                   | Purpose                                                                     | Boundary                                                         |
| ----------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `monosurf profile tui`                    | Opens the interactive profile manager.                                      | Intended for a person at a terminal.                             |
| `monosurf profile ls`                     | Lists profiles and marks the default and running state.                     | `list` is an alias; supports `--json`.                           |
| `monosurf profile new <name>`             | Registers a profile and creates its browser state without launching Chrome. | A later command can auto-start it.                               |
| `monosurf profile use <name>`             | Sets the persistent default used by later commands.                         | `use --clear` removes the default.                               |
| `monosurf profile info <name>`            | Shows state, account label, port, storage size, and pinned browser engine.  | Supports `--json`.                                               |
| `monosurf profile rename <old> <new>`     | Renames a stopped profile and keeps the default pointer aligned.            | Refuses while the profile is running.                            |
| `monosurf profile account <name> <label>` | Sets the account label shown in profile lists.                              | This label is not a login credential.                            |
| `monosurf profile rm <name>`              | Removes the profile and its login data.                                     | Irreversible; confirms on a TTY and requires `--yes` in scripts. |

### Selection order

Site and profile-backed commands resolve a profile in this order:

```text theme={null}
--profile
    ↓
MONOSURF_PROFILE
    ↓
persistent default from profile use
    ↓
single registered profile
    ↓
interactive picker, or a non-interactive error
```

Browse deliberately has a safer final step: after explicit `--profile`, the
environment, and the persistent default, it creates an ephemeral session. It
does not silently adopt the only registered profile.

### Browser discovery and engine pinning

```bash theme={null}
monosurf browsers
monosurf start --profile work --browser 2
monosurf profile info work
```

MonoSurf can discover system Chrome and compatible Playwright, Puppeteer, or
headless-shell Chromium installations. The first successful profile launch
pins the browser kind and signing identity that own its encrypted cookies. If
discovery later resolves a different kind, MonoSurf fails clearly instead of
quietly presenting a logged-out profile. Use `--allow-binary-change` only when
you accept the switch and expect to sign in again.

### CDP port ownership guard

Version 0.11.3 never treats an open profile port as proof that MonoSurf
launched the listener. A new profile skips every active unregistered port,
launches on the selected free port, and proves that exact listener's
`--user-data-dir` before committing the profile record. Existing managed
`start`, profile-backed connect, site-command, and batch paths apply the same
ownership test.

| Observed listener                         | Connect/start behavior                                                            | Stop behavior                               |
| ----------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------- |
| Exact profile owner                       | Reuse it; repair the pid file when the ownership proof supplies a current pid.    | The port fallback may signal it.            |
| Readable foreign owner                    | Fail with pid/command evidence and point intentional attach users to `--cdp-url`. | Refuse to signal it.                        |
| Ownership temporarily cannot be inspected | Retry only for a bounded settle interval, then fail closed.                       | Refuse to signal through the port fallback. |

If a pid file points to a live, readable process whose command line belongs to
something else, MonoSurf treats the number as recycled: it removes the stale
record without killing the process. On Unix, port discovery filters for the
`LISTEN` socket so a connected CDP client is not selected instead of Chrome.
The exact chosen port is threaded through launch verification and failed-launch
cleanup, avoiding a second allocation decision after Chrome has bound it.

## Browse and Attach

MonoSurf has three ways to obtain a page session:

| Mode            | Command                                                 | Ownership                                                                                                                 |
| --------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Ephemeral       | `monosurf browse <url>`                                 | MonoSurf launches a temporary browser and removes its profile on close.                                                   |
| Managed profile | `monosurf browse <url> --profile work`                  | MonoSurf connects to the named persistent profile and leaves its login state intact.                                      |
| External CDP    | `monosurf browse <url> --cdp-url http://127.0.0.1:9222` | MonoSurf attaches to an existing Electron, WebView2, Tauri, or Chromium endpoint; it does not launch or own that browser. |

Use `--ephemeral` to force a clean temporary session even when an environment
or persistent default profile is configured. `--profile` and `--ephemeral`
cannot be combined. With `--cdp-url`, a managed profile selection is ignored
because the external endpoint owns the session. `--use-profile <name>` remains
a browse-only alias for `--profile <name>`.

The external Chromium-family process must already expose CDP, commonly by
being launched with its own `--remote-debugging-port=<port>` flag. That is a
browser launch option, not a MonoSurf option; MonoSurf receives the resulting
endpoint through `--cdp-url` and never assumes ownership of the attached
process.

### Primary page output

| Control           | Result                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------- |
| No output flag    | Prints readable page text.                                                              |
| `--extract`       | Emits structured URL, title, headings, links, and text.                                 |
| `--json`          | Acts as an alias for `--extract` in browse mode.                                        |
| `--eval <js>`     | Evaluates JavaScript in the page and prints the requested value.                        |
| `--output <file>` | Writes the primary output to a file; single-shot writes are atomic.                     |
| `--visible`       | Shows the temporary browse window instead of running headless.                          |
| `--insecure`      | Bypasses invalid TLS certificates for deliberate testing only.                          |
| `--timeout <ms>`  | Sets selector wait/assert time and the deterministic evaluation or extraction deadline. |

Strict TLS is the default. A requested output that fails, times out, cannot be
written, or navigates to an unreachable HTTP endpoint returns a non-zero exit
instead of silently succeeding.

## Browser QA and Dev Loop

The QA controls run inside the same CDP page session:

| Control                       | What it verifies or captures                                                      |
| ----------------------------- | --------------------------------------------------------------------------------- |
| `--shot <file>`               | Saves a PNG screenshot of the page.                                               |
| `--full-page`                 | Extends the screenshot through the full scroll height.                            |
| `--console`                   | Returns console messages and uncaught page errors.                                |
| `--net`                       | Returns navigation timing, HTTP status, and failed 4xx/5xx resources.             |
| `--wait <selector>`           | Waits for asynchronous content before later output is captured.                   |
| `--expect <selector>`         | Polls for a smoke-test assertion and returns non-zero when it never appears.      |
| `--viewport <width>x<height>` | Renders at a controlled responsive viewport such as `375x812`.                    |
| `--timeout <ms>`              | Bounds the wait, expectation, evaluation, or extraction requested by the command. |

```bash theme={null}
monosurf browse https://example.com \
  --viewport 375x812 \
  --wait "main" \
  --expect "h1" \
  --shot mobile.png \
  --console \
  --net
```

## Chrome Cookie Bridge

The bridge is an explicit cookie snapshot workflow, not profile reuse:

```bash theme={null}
monosurf bridge install
monosurf bridge example.com
monosurf bridge example.com --keep
```

`bridge install` materializes the versioned unpacked extension, installs the
existing Monolex shared native host under the `monosurf-native-host` routing
name, and writes the native-host manifest. The extension's manifest key pins ID
`cclkmkgheebiiommelcnjindolniongm`; load the printed extension directory once
from `chrome://extensions` with Developer mode enabled.

The prerequisite is `~/.niia/bin/monolex-native-host`, staged by the Monolex
desktop app (`monolex-native-host.exe` on Windows). The standalone monosurf
0.11.3 archives do not bundle it. When it is absent, `bridge install` exits
non-zero after it may already have materialized the unpacked extension assets;
do not load that partial result as a completed bridge installation. Install or
launch Monolex desktop to stage the matching shared host, then rerun the command.

For each import, start `bridge` first, open the logged-in target tab in Chrome,
then click the extension's Sync action. The receiver filters expired entries
and writes the active tab's matching cookies to the OpenCLIs Vault-backed
snapshot. Before a later JSON site command navigates, the live jar is read
first. Only an empty jar is hydrated; a non-empty live session always wins.

Hydration validates every scope, supplies an explicit HTTP(S) origin, preserves
domain, path, HttpOnly, Secure, SameSite, and expiry, and fails the whole
command on any invalid scope or CDP error. It does not copy localStorage,
IndexedDB, service workers, passwords, the daily Chrome profile, the Chrome
process, or cookies unrelated to the active tab.

The [Monolex Agent Browser path](/ai-clis/monolex-cli) is intentionally
different: **Sign In with Chrome → Open in Agent** reuses one owned managed
profile so cookies, localStorage, IndexedDB, service workers, and passkey state
stay together without serialization. It never adopts or relaunches daily
Chrome. [OpenCLIs Vault](/ai-clis/openclis-vault) owns stable protected snapshot
storage; [MonoPass](/ai-clis/monopass) owns passkey/WebAuthn ceremonies.

## Bound Navigation and Toast Proof

Use `postcondition` when one click and its evidence must be inseparable:

```bash theme={null}
monosurf postcondition navigation \
  --cdp-url http://127.0.0.1:9222 \
  --link-text Events --container footer \
  --expected-url /events --url-match path \
  --target 'main h1' --target-text Events \
  --header header --scroll top
```

The command scopes an exact normalized-text link or button to one container,
reveals it, performs a real CDP click, and reports before/after canonical URL,
history length, scroll, viewport intersection, destination target, and fixed-
header clearance. Duplicate controls, missing targets, URL drift,
covered/off-screen targets, and bounded timeouts return non-zero.

For actions whose success is a visible message and intentionally unchanged URL:

```bash theme={null}
monosurf postcondition toast --cdp-url http://127.0.0.1:9222 \
  --link-text Save --container main \
  --toast '[role=status]' --toast-text Saved
```

The supported timeout range is 250–30000 ms.

## Harvest Growing Pages

`--collect` repeatedly extracts matching elements, scrolls, deduplicates, and
streams each new item as JSONL. It makes a feed that stopped growing visible
instead of returning an unexplained partial result.

```bash theme={null}
monosurf browse "https://x.com/search?q=monolex" --profile work \
  --collect '[data-testid="tweet"]' \
  --max-items 100 \
  --output items.jsonl \
  --net-log network.jsonl
```

| Control                   | Purpose                                                       | Default                 |
| ------------------------- | ------------------------------------------------------------- | ----------------------- |
| `--collect <selector>`    | Selects one repeated feed item.                               | Required for collection |
| `--collect-js <function>` | Maps each matching element to a custom JSON value.            | Text, links, and images |
| `--max-items <n>`         | Stops after the requested unique item count.                  | Unlimited               |
| `--max-rounds <n>`        | Bounds the total extract-and-scroll rounds.                   | 500                     |
| `--delay <ms>`            | Sets the jittered pause between rounds.                       | 1200 ms                 |
| `--stall-rounds <n>`      | Declares how many no-growth rounds trigger a recovery jiggle. | 3                       |
| `--stall-retries <n>`     | Bounds fruitless recovery attempts before `no_growth`.        | 2                       |

Items flush as they arrive, so an interrupted long run keeps the JSONL already
written. The end report includes item and round counts, first and last keys, and
a `stall_reason` such as `max_items`, `max_rounds`, `no_growth`, or an evaluation
error. Zero collected items and failed collection evaluation return non-zero.

## Capture Page Network Traffic

`--net-log <file>` records every CDP network response as JSONL from before
navigation through the end of the session. It can reveal media manifests,
original CDN assets, and XHR endpoints that never appear in the DOM.

| Control                | Purpose                                                     |
| ---------------------- | ----------------------------------------------------------- |
| `--net-log <file>`     | Streams response URL, resource type, MIME type, and status. |
| `--net-filter <regex>` | Keeps only response URLs matching the regular expression.   |

Combine network logging with collection in one pass. This avoids scrolling a
feed once for DOM items and again for the network evidence behind them.

## Logged-In Site Commands

Site commands come from installed JSON plugins. Read actions require an active
read grant; posts, replies, deletes, and other writes require a write grant.
The installed plugin remains the authority because local and registry plugins
can evolve independently of the binary.

Current bundled domains expose these command names:

| Domain                 | Read commands                                 | Write commands            |
| ---------------------- | --------------------------------------------- | ------------------------- |
| `x` / `x.com`          | `search`, `timeline`, `read`, `trending`      | `post`, `reply`, `delete` |
| `threads.net`          | `feed`, `search`, `profile`, `read`           | `post`, `reply`, `delete` |
| `reddit.com`           | `front`, `hot`, `new`, `read`, `search`       | None bundled              |
| `news.ycombinator.com` | `top`, `new`, `ask`, `show`, `search`, `read` | None bundled              |
| `github.com`           | `trending`, `trending-weekly`, `search`       | None bundled              |
| `producthunt.com`      | `today`                                       | None bundled              |

```bash theme={null}
monosurf auth grant read 1h
monosurf x search "AI agents" --profile work --limit 20
monosurf github.com trending --limit 10

monosurf auth grant write 30m
monosurf x post "Hello from MonoSurf" --profile work
```

Run `monosurf sites` to inspect installed domains. Use `monosurf sites search <query>`
to see their declared command names and tags.

## Grants, Login, and Batch Posting

### Time-limited grants

```bash theme={null}
monosurf auth grant read 1h
monosurf auth grant write 30m
monosurf auth revoke read
monosurf auth revoke all
monosurf auth status
```

Read and write are separate scopes. `auth status` is read-only and also reports
which secure storage backend currently owns each known session key.

### Login

```bash theme={null}
monosurf login x --profile work
monosurf login reddit.com --profile work
```

Login opens the selected profile for manual authentication and preserves the
live browser session. The protected session snapshot can bootstrap an empty
cookie jar, while an already-live browser session wins when the site rotates
tokens.

### Batch posting

```bash theme={null}
monosurf x batch posts.txt --interval 1h --jitter 15m
monosurf batch status
monosurf batch stop
```

A site plugin starts the background job. `batch status` reports progress and
the next post; `batch stop` finishes the current post and stops gracefully.
Separate posts in the input file with `---` on its own line. The first post is
sent immediately, then the interval and jitter apply.

## Site Plugin Management

| Command                           | Purpose                                                    | Write boundary                            |
| --------------------------------- | ---------------------------------------------------------- | ----------------------------------------- |
| `monosurf sites`                  | Lists installed domains.                                   | Read-only; supports `--json`.             |
| `monosurf sites search <query>`   | Searches indexed plugin descriptions, tags, and commands.  | Read-only.                                |
| `monosurf sites verify`           | Checks every installed plugin's integrity status.          | Read-only.                                |
| `monosurf sites sources`          | Shows whether each plugin is local or official.            | Read-only.                                |
| `monosurf sites sign <domain>`    | Re-seals a plugin after an intentional local edit.         | Changes the local integrity seal.         |
| `monosurf sites pull <domain>`    | Downloads an official plugin after signature verification. | Replaces or installs local plugin data.   |
| `monosurf sites reset <domain>`   | Restores the official version.                             | Replaces local changes.                   |
| `monosurf sites index`            | Rebuilds plugin discovery data.                            | Updates the local index; `i` is an alias. |
| `monosurf sites push <domain>`    | Uploads a development plugin.                              | Requires developer authentication.        |
| `monosurf sites publish <domain>` | Publishes an official plugin version.                      | Release-authority operation.              |
| `monosurf sites help`             | Prints the installed plugin schema and action guide.       | Read-only.                                |

See [Site Plugins](/monosurf/site-plugins) before authoring or publishing a
workflow that will run inside a logged-in session.

## Safety, Health, and Self-Tests

### Doctor

`monosurf doctor` is read-only by default. It compares registered profiles,
profile directories, process records, the default pointer, and temporary
session leftovers.

| Mode                      | Action                                                         | Safety class                              |
| ------------------------- | -------------------------------------------------------------- | ----------------------------------------- |
| `monosurf doctor`         | Reports drift in human-readable form.                          | Read-only                                 |
| `monosurf doctor --json`  | Returns the report for automation and ignores fix flags.       | Read-only by contract                     |
| `monosurf doctor --fix`   | Removes only stale bookkeeping and safe temporary debris.      | Non-destructive cleanup                   |
| `monosurf doctor --adopt` | Registers forgotten profile directories without deleting them. | Additive                                  |
| `monosurf doctor --prune` | Deletes orphan profile directories.                            | Destructive; confirms or requires `--yes` |

### Offline self-tests

| Command                     | Contract it tests                                                                |
| --------------------------- | -------------------------------------------------------------------------------- |
| `monosurf selftest typing`  | Character, URL, CJK, and editor typing behavior.                                 |
| `monosurf selftest leak`    | Temporary browse profile and child-browser cleanup.                              |
| `monosurf selftest collect` | Complete feed collection, stable deduplication, and `no_growth` stall reporting. |

Each self-test is local and returns non-zero when its hard contract fails.

### Embedded documentation

```bash theme={null}
monosurf docs
monosurf docs index
monosurf docs profiles
monosurf docs doctor
monosurf docs security
```

These topics travel with the installed binary and explain profile persistence,
engine identity, doctor safety classes, grants, and secret-storage boundaries.

## Legacy Compatibility Entry Point

The old cookie-source selector remains only as a compatibility message:

| Entry point          | Current contract                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `cookies <platform>` | Compatibility message only. Direct browser-database import was removed; use `login`, a managed profile, or the explicit `bridge` workflow. |

This boundary prevents a legacy platform selector from being mistaken for
silent Chrome-profile extraction. `bridge` is now the supported, user-triggered
cookie-only path; it is not an alias for profile cloning.

## When to Hand Off to Kernel CLI

MonoSurf can operate only inside the CDP-visible page. Hand the workflow to
[Kernel CLI](/kernel-cli) when it reaches:

* a native file, print, or save dialog;
* Face ID, Keychain, or another operating-system permission prompt;
* the browser address bar, tabs, menus, extensions, or other browser chrome;
* a non-Chromium desktop application.

```text theme={null}
MonoSurf acts in the page
          ↓
native surface appears
          ↓
Kernel CLI resolves and completes it
          ↓
MonoSurf returns to the page and verifies
```

See [Kernel CLI Complete Command Reference](/kernel-cli/commands) for the
native observation, accessibility, OCR, input, app, and window surfaces.

## Related Guides

<CardGroup cols={2}>
  <Card title="MonoSurf Overview" icon="globe" href="/monosurf/index">
    Understand the page boundary, connection modes, and companion-tool map.
  </Card>

  <Card title="Site Plugins" icon="plug" href="/monosurf/site-plugins">
    Learn how installed domains expose reusable read and write commands.
  </Card>

  <Card title="Auth Gate" icon="lock" href="/monosurf/auth-gate">
    Review grants and protected session access in more detail.
  </Card>

  <Card title="Kernel CLI" icon="microchip" href="/kernel-cli">
    Continue automation across the native desktop outside the web page.
  </Card>
</CardGroup>