stelz 0.2.0 → 0.2.1

package/docs/onboarding-acceptance.md

@@ -0,0 +1,79 @@
+# Onboarding acceptance
+
+## Reproduce the agent check
+
+Use local macOS ARM64 with a signed-in coding agent. Keep its existing approval protections.
+Build and pack a release candidate. Give a fresh agent only the bootstrap document, candidate archive, a new writable test directory, and this request:
+
+> Follow the bootstrap document. Install this archive into the supplied test prefix, use the supplied temporary STELZ_HOME, and create or reuse profile work. Install the canonical skill in this test project's supported location. Preserve global client configuration. Configure a project-scoped MCP connection if supported, otherwise write the exact connection arguments for a new session. Verify through your actual browser tools. Report Installed, Browser ready, Client configured, and Verified separately. Do not claim unavailable tools work. Leave the browser running after release.
+
+Record the agent's actions, errors, and intervention requests. A model must perform the browser interaction through its registered MCP tools.
+An SDK script can inspect the resulting state but cannot replace that evidence.
+If tools require a new session, start that session with the saved connection and the same profile. Resume only the verification step.
+Repeat the original onboarding prompt afterward. Require the same profile ID, port, secret references, browser lifetime, and saved local-page marker.
+
+After the agent demonstrates release and reuse, the test operator can explicitly stop the test profile and fixture server.
+Do not stop or remove real service profiles. Keep failed test state for inspection.
+
+## Automated coverage
+
+`tests/integration/profile-cli.test.ts` covers direct and proxy creation, environment input, repeated creation, concurrent creation, legacy catalogs, interrupted transactions, conflicts, redacted results, missing initialization, and unsafe service files.
+Existing catalog, lifecycle, and MCP suites cover port allocation, rollback, exclusive control, and browser survival after disconnect.
+The release verifier checks the installed CLI and bundled onboarding resources outside the source checkout.
+
+## Run record: 2026-11-05
+
+The assisted Codex acceptance check passed on local macOS ARM64.
+The host supplied Bun 1.4.4, Node.js 24.14.0, npm 11.16.0, and a compatible Camoufox executable.
+The target client was Codex CLI 0.142.4.
+The agent read the local bootstrap document and installed the supplied Stelz 0.2.0 archive into a new temporary npm prefix.
+The archive SHA-256 was `17cdaa57f05f47060a33afe9b8502537fd65de06f30a3256bf8d68b7c339dd94`.
+
+| State | Observed result |
+| --- | --- |
+| Installed | The fresh agent installed the archive with lifecycle scripts enabled, initialized an empty service directory, and prepared the runtime. |
+| Browser ready | The agent created native profile `work` on port 9377. Start and doctor confirmed the running service and owned processes. |
+| Client configured | The agent installed a symlink to the canonical skill and a project MCP entry. It preserved global client configuration. |
+| Verified | A fresh Codex session acquired control, opened the local fixture, read snapshots, clicked the observed reference, and verified the result. |
+
+The first session reported **Verified: pending** because it lacked the newly registered tools.
+The next session used the actual `stelz-work` MCP tools. It did not use an SDK probe for browser interaction.
+After release, status reported `ready` with no controller. Reacquisition returned the same page and result.
+
+The agent then repeated initialization, profile creation, and startup.
+Creation returned `created: false`. Profile ID, port, native storage, and catalog and secret-file hashes remained unchanged.
+The instance remained `2211f6d7-15e5-4225-8f1d-01956bc44233`.
+The fixture tab remained `086c8d6a-e9f9-4f10-9bbc-13a4d90171ef`.
+Its persistent count increased from 1 to 2 after a second observed click.
+The final release again left the same browser ready with no controller.
+After recording that evidence, the test operator stopped only the temporary `work` profile.
+The fixture server stopped separately. The test retained native profile data for inspection.
+
+## Required interventions
+
+- The installed Codex CLI initially rejected the user's model catalog before the agent could start.
+  The test operator supplied a temporary compatible catalog through a session-only flag.
+  The copy supplied missing model capability fields and disabled an incompatible optional response transport.
+  The global catalog, authentication, sandbox, and approval settings stayed unchanged.
+  This assistance prevents a claim of fully unattended onboarding on this host.
+- The first sandboxed desktop browser launch aborted. The agent inspected ownership, stopped only the failed test lifetime, and requested normal launch permission.
+  The approved launch succeeded. Protected project skill and MCP directories also required normal permission escalation.
+  Stopping the temporary fixture also required scoped permission.
+- The operator started a fresh Codex session after registration. The first session supplied exact connection arguments and a checkpoint.
+- No website authentication or new credentials were necessary for the local fixture.
+
+## Scope and limitations
+
+The test used a fresh package prefix, service directory, and project configuration. It reused host dependencies and the browser executable.
+It does not establish installation on a fresh operating system or exercise the missing-dependency download branches.
+The public bootstrap URL and npm release path were not the input to this development run.
+Publish the document and release before testing that public path.
+
+Claude Code and Hermes setup paths follow their official documentation.
+The installed Hermes skill loader also supports directory symlinks.
+Neither client completed this onboarding acceptance run. Claude Code was unavailable.
+Proxy creation, conflicts, legacy references, and interrupted transactions passed automated CLI checks. This agent check used direct networking.
+
+The implementation checks passed: 484 Bun tests, 97 Node regression tests, typecheck, build, and isolated release verification.
+Ten CLI tests include concurrent reuse, interrupted creation, and conflicting legacy paths.
+Local evidence is retained under `.state/onboarding-acceptance/` and the temporary acceptance project.

package/docs/profile-transfer.md

@@ -0,0 +1,89 @@
+# Import and export profiles
+
+Use a `.stelz-profiles.zip` archive to move one or more profiles between matching installations.
+The archive includes saved browser data, device settings, typing preferences, and available proxy credentials.
+It is not encrypted. Keep it private because saved browser data can contain active login sessions.
+Initialize the destination with `stelz init`. Both installations need the matching Camoufox executable.
+
+## Use the UI
+
+Stop the profiles cleanly before export. Export never stops a browser automatically.
+Open **Profiles**, select **Export**, and select the profiles to include.
+Use **Select all stopped** to select every eligible profile.
+Download the archive when preparation completes, then close the dialog.
+A stopped profile also has an export action in its details.
+
+Select **Import** and choose the ZIP archive.
+Review the profiles and their proposed IDs and display names. Select the profiles to import.
+Select **Import N**, where `N` is the selected count, to save the batch.
+The new profiles remain stopped until you start them explicitly.
+
+If an ID already exists, import proposes `ID-copy`, then `ID-copy-2`, and so on.
+Existing profiles and their data stay unchanged.
+A profile whose proxy credentials were unavailable at export remains blocked until you configure its proxy.
+It never changes to a direct connection automatically.
+
+The dialog reports transfer progress. Select **Cancel** to remove temporary files before you import profiles.
+During import, wait for the result. Turning off the UI is unavailable during an active transfer.
+Reloading the page restores an active transfer in the same UI session.
+If an upload needs the file again after reload, choose the ZIP again or cancel the transfer.
+A new UI server starts a new transfer session.
+
+## Use the CLI
+
+```sh
+stelz profile export work personal --output ./profiles.stelz-profiles.zip
+stelz profile export --all --output ./all-profiles.stelz-profiles.zip
+stelz profile import ./profiles.stelz-profiles.zip
+stelz profile import ./profiles.stelz-profiles.zip --profile work --rename work=work-laptop
+```
+
+Export refuses an existing output file. Use another filename.
+`--all` includes every configured profile. Every selected profile must be cleanly stopped.
+Repeat `--profile SOURCE_ID` to import a subset. Omit it to import the complete archive.
+Repeat `--rename SOURCE_ID=NEW_ID` to select explicit unused destination IDs.
+Add `--json` for structured results. Results contain profile mappings and do not include credentials.
+The destination service assigns new loopback ports and private secret references.
+Export saves the effective typing mode, including a mode inherited from the source service.
+Import saves that mode as a profile preference.
+
+## Compatibility and saved data
+
+Import requires the same operating system, CPU architecture, and exact Camoufox executable SHA-256.
+Export also checks saved fingerprints against the local executable.
+Stelz does not migrate browser versions or storage modes during import.
+Both native profiles and legacy checkpoint profiles keep their storage mode.
+Import maps checkpoint storage to the destination profile ID.
+
+The ZIP64-compatible archive contains a versioned `manifest.json` and SHA-256 hashes for its files.
+Native browser data remains intact, including SQLite sidecar files.
+The archive includes saved cookie inputs and reusable uploads.
+Export omits service files, including process records, `access-key`, logs, and temporary files.
+It also omits native browser lock files at the root of `browser-data/`.
+The archive contains neither the browser executable nor global service or client configuration.
+
+Import checks the archive before it changes the profile catalog.
+It rejects unsafe paths, links, unsupported entry types, duplicate entries, and failed file hashes.
+Import installs the data and secrets, then publishes the selected batch in one catalog update.
+An interrupted commit leaves a private journal. The next configuration operation or explicit start completes recovery.
+Read-only status does not change the journal. Conflicting manual edits require inspection.
+The private journal is `STELZ_HOME/.profile-import-transaction.json`.
+Run `stelz doctor ID` to inspect a pending import.
+Keep its journal and staging directories while recovery is pending.
+
+## Transfer limits
+
+Archives and expanded profile data each have a default limit of 10 GiB.
+The default entry limit is 100,000. The manifest limit is 64 MiB.
+Set these environment variables before starting the UI or CLI to change the transfer limits:
+
+| Variable | Unit |
+| --- | --- |
+| `STELZ_TRANSFER_ARCHIVE_BYTES` | Compressed archive bytes |
+| `STELZ_TRANSFER_EXPANDED_BYTES` | Expanded file bytes |
+| `STELZ_TRANSFER_ENTRIES` | ZIP entries |
+| `STELZ_TRANSFER_MANIFEST_BYTES` | Manifest bytes |
+
+Use positive integers. These limits apply to each transfer, not to the saved-profile count.
+Allow free disk space for the archive, the extracted data, and the staged import or export snapshot.
+Inactive UI transfer files expire after 30 minutes. Finish or cancel a transfer before turning off the UI.

package/docs/tests.md

@@ -6,19 +6,25 @@ Use the runtime requirements in [Use the service](README.md).
 
 ```sh
 bun install --frozen-lockfile --ignore-scripts
-bun run build
+bun run check
 bun run pack
 ```
 
-Build regenerates `packages/stelz/dist/` from source.
+Build regenerates `dist/` from source.
+Bun builds the CLI, supervisor, browser plugin, and early theme script. Vite builds the UI and emits local font files.
+The theme script runs before the first page frame. The build preserves the bundled UI licenses.
 The archive contains the CLI, supervisor, browser plugin, built local UI, documentation, client examples, and third-party notices.
 The diagnostic client runs from source. The archive excludes Stelz source files, tests, and browser state.
 It includes the prepared Camofox and camoufox-js dependencies. See [Distribution](distribution.md).
 
 ## Checks
 
+See [Onboarding acceptance](onboarding-acceptance.md) for the real-agent installation, restart, and browser-control check.
+`tests/integration/profile-cli.test.ts` checks profile creation, safe reuse, conflicts, and interrupted transactions through the CLI.
+
 | Command | Coverage |
 | --- | --- |
+| `bun run check` | Build, TypeScript checks, and all browser-free tests. No release archive. |
 | `bun run typecheck` | TypeScript checks. |
 | `bun run test:ui` | UI sessions, lifecycle dispatch, profile creation and deletion, interrupted saves, safe network edits, and redaction. |
 | `bun run test:ui:browser` | Built UI in Chrome, local sessions, offline assets, forms, and responsive layouts. |
@@ -26,20 +32,25 @@ It includes the prepared Camofox and camoufox-js dependencies. See [Distribution
 | `bun run test:integration` | Two checkpoint profiles, exclusive control, handoff, disconnect, client crash, pause, and restart. |
 | `bun run test:concurrency` | Three temporary native profiles, simultaneous starts, isolated storage, duplicate starts, and controller handoff on a local fixture. |
 | `bun run test:native` | Two native profiles, storage isolation, and repeated fingerprint samples across three browser lifetimes. |
+| `bun run test:transfer` | Native ZIP export/import, batch copies, saved sessions, fingerprint bytes, fresh access keys, and copied-profile window controls. |
 | `bun run test:window-close` | Close one isolated test window when prompted. Check clean shutdown, Stopped UI state, and explicit restart. |
 | `bun run test:windows` | Native profile labels, window focus, unchanged website titles, and controller preservation in two isolated Camoufox profiles. |
 | `bun run test:proxy` | Two distinct proxy exits, three browser lifetimes, expected IP pins, and isolated route failures during cached verification. |
 | `bun run test:manual` | Human interaction while paused, followed by MCP resume in the same browser and tab. |
-| `bun run test:public --profile ID` | Four public fingerprint checks in an existing Camoufox profile, with screenshots and verdict reports. |
-| `bun run verify:release` | Pack lifecycle, archive contents, installed dependency checks, CLI, HTTP UI, and staged setup validation with a fake executable. No browser. |
-| `bun run test:package` | Archive installation in an isolated npm prefix, an empty working directory, and browser acceptance. |
+| `bun run test:public` | Four public fingerprint checks in a disposable native profile, with screenshots and verdict reports. |
+| `bun run pack` | Build once and save one release archive with its hash and source metadata in `release-artifacts/`. |
+| `bun run verify:release` | Check the saved archive, installed dependencies, CLI, HTTP UI, and staged setup with a fake executable. No browser or rebuild. |
+| `bun run verify:release --archive FILE --native` | Ordinary isolated npm installation, SQLite queries, and Impit construction from the installed package and staged runtime. No browser. |
+| `bun run test:package` | Install the saved archive in an isolated npm prefix. Run checkpoint and native browser acceptance. |
 | `bun run test:package --archive FILE --native --proxy --manual` | Full supported-platform acceptance against one unchanged release candidate, including a real human action. |
+| `bun run test:package --archive FILE --native --proxy --waive-manual` | The owner-approved `0.2.1` release exception. All automated gates remain required. Human takeover remains untested in the record. |
 
 The earlier browser acceptance run passed on 2026-11-02 with macOS 26.5.2 on Apple Silicon.
 That run used Bun 1.4.4, Node.js 24.14.0, TypeScript 5.9.3, and Camoufox 152.0.4 beta.30.
 Camofox remains pinned to npm version 1.18.1.
 
-The regression suite also runs directly with Node. It does not require a browser.
+Tests in `tests/unit` and `tests/integration` run with Bun through directory discovery.
+Tests in `tests/regression` run directly with Node. They do not require a browser.
 The plugin tests use the actual hooks with simulated browser and network interfaces.
 They cover stalled actions, failed IP checks, explicit recheck, action serialization, cache expiry, and independent provider fallback.
 One hundred queued actions require one IP check with the default cache, compared with 101 checks in strict mode.
@@ -57,23 +68,58 @@ That check uses the actual UI API and isolated service files with simulated life
 It does not start Camoufox profiles.
 It uses installed Chrome on macOS. Set `STELZ_UI_CHROME` to select another Chrome or Chromium executable.
 Screenshots and its report are in `.state/ui-browser/`.
-The UI check also creates profiles with and without a proxy, confirms deletion, and checks profile archives.
+The UI check also creates profiles with and without a proxy and checks deletion archives.
+
+## Profile transfer acceptance
+
+The default test command includes ZIP format, transfer API, CLI, and import transaction checks.
+They cover ZIP64, unsafe paths and links, checksum failures, size limits, cancellation, credential redaction, conflicts, and crash recovery.
+
+Build the service, then run the native transfer check:
+
+```sh
+bun run build
+bun run test:transfer
+```
+
+This check requires desktop access for Camoufox.
+It creates a fresh `.state/transfer-native-*` service directory and uses synthetic data on a local fixture.
+It verifies cookies, localStorage, IndexedDB, fingerprint bytes, a fresh access key, and window controls after import.
+Its report is `.state/profile-transfer/report.json`. Cleanup stops only its test profiles.
+Native transfer acceptance passed on macOS arm64 on 2026-11-05.
+
+To check ZIP commands in an installed release without starting browsers, run this from the source checkout:
+
+```sh
+STELZ_TEST_CLI=/absolute/path/to/installed/stelz \
+  bun test tests/integration/profile-transfer-cli.test.ts
+```
+
+These tests use disposable service directories and a synthetic executable for compatibility hashes.
+They check batch copies, credentials, explicit destination IDs, output-file protection, mismatched engines, and unclean lifetimes.
+See [Import and export profiles](profile-transfer.md) for the supported behavior.
 
 ## Continuous integration
 
-GitHub Actions runs frozen installation, build, TypeScript checks, regression tests, and isolated browser-free archive verification on Linux and macOS.
+GitHub Actions runs frozen installation and `bun run check` on Linux and macOS.
+Normal checks do not pack archives or start live browsers.
 CI and release workflows use the root `package.json` `packageManager` pin (`bun@1.4.4`), Node.js 24, and read-only repository permissions.
-Release preparation requires these checks on both platforms, then uploads one verified archive.
+Release preparation requires these checks on both platforms, then builds and uploads one candidate archive.
+Linux and macOS download that same archive and check installation with scripts disabled and with ordinary native installation.
 The workflows skip browser downloads. Browser, proxy, and human acceptance checks run locally.
 
 ## Test data
 
 Browser checks use independent MCP SDK clients. Most checks use two profiles. `test:concurrency` uses three native profiles simultaneously.
+Routine tests use temporary catalogs and mocked browser or service interfaces.
+Lifecycle fixtures copy source into test packages and use mock plugin bytes. They do not require workspace build output.
+Live browser checks create disposable profiles in separate service directories. They never select an operator's saved profile.
 Checkpoint, native, and manual checks use explicit direct development mode. Proxy acceptance requires two supplied HTTP proxies.
 The isolated acceptance checks stop their test browsers. The public-site check saves its artifacts, then stops its selected browser.
 These checks require no model credentials.
 
-- `test:integration` uses `.state/standalone-acceptance/`. Set `STELZ_TEST_HOME` to select another test directory.
+- `test:integration` creates a fresh `.state/standalone-acceptance-*` directory.
+  `STELZ_TEST_HOME` can select only a directory created by `tests/helpers/test-home.ts`.
 - `test:native` creates a fresh `.state/native-acceptance-*` directory.
 - `test:windows` creates a fresh `.state/profile-windows-*` directory with native and checkpoint profiles.
 - `test:package` uses temporary install and service directories. Its report is `.state/package-test/report.json`.
@@ -130,11 +176,11 @@ Window acceptance passed on 2026-11-03 with both storage modes.
 
 ## Public fingerprint checks
 
-Start the selected Camoufox profile before this check. Use the same `STELZ_HOME` as the service.
+Build the service before this check:
 
 ```sh
-bun run start profile-02
-bun run test:public --profile profile-02
+bun run build
+bun run test:public
 ```
 
 The suite uses stelz MCP tools to visit these sites in order:
@@ -155,12 +201,11 @@ The suite does not request location permission or trigger Rebrowser's scripted p
 Rebrowser reports each native probe separately. Skipped and untriggered probes do not count as passed checks.
 Its overall result describes the applicable checks and states the remaining coverage limits.
 
-The suite acquires one running profile and creates four tabs sequentially.
-It keeps existing tabs during the checks. After saving its artifacts, it runs `stelz stop ID` to close that profile's windows.
-Cleanup also runs after failed or interrupted checks. Saved profile data remains available for the next explicit start.
-Cleanup applies only after successful acquisition. A controller conflict leaves the browser running.
-The suite does not start browsers. Other profiles remain unchanged.
-An active controller prevents acquisition. Release that controller before you retry.
+The suite creates its own native profile and starts one browser. It creates four tabs sequentially.
+After saving its artifacts, it stops that disposable profile. Cleanup also runs after failed or interrupted checks.
+The suite rejects `--profile` and ignores the operator's `STELZ_HOME`.
+To test a proxy route, set `PROXY_TEST_ENV` to a private file with `PROXY_TEST_URL` and optional `PROXY_TEST_EXPECTED_IP`.
+The suite copies these inputs into its temporary service directory and removes that credential copy after cleanup.
 
 The suite checks each page every two seconds for up to 120 seconds, excluding human authentication time.
 It waits for each MCP operation to finish. A service deadline blocks further browser actions and requires an explicit stop and start.
@@ -168,7 +213,7 @@ Individual site errors do not prevent later checks when the profile remains usab
 
 Authentication pauses the profile. Complete authentication in the same Camoufox window, then type `done` in the terminal.
 Without an interactive terminal, the suite records an incomplete result and stops the browser during cleanup.
-Cancelling authentication also ends the run and stops the browser. Start the profile before the next run.
+Cancelling authentication also ends the run and stops the browser. The next run creates another disposable profile.
 
 Artifacts are in `.state/public-sites/<run>/`. Each run creates `report.json` and `report.md`.
 Visited sites also have a PNG screenshot and a snapshot JSON file when capture succeeds.
@@ -202,10 +247,7 @@ The check explicitly stops its browser. Results are in `.state/typing-acceptance
 The default test command checks typing logic and runtime setup without starting a browser.
 It executes the upstream type route and tab lock with virtual timers to check long input, terminal timeouts, and action serialization.
 
-To use an existing stopped profile, run `bun run test:typing --profile ID`.
-Its service must already contain the current typing runtime.
-This mode starts and stops the selected profile once. It tests per-call overrides and skips profile default changes.
-The profile catalog and secrets file remain unchanged.
+The check rejects `--profile`. Every run creates a disposable profile.
 
 ## Diagnostics
 
@@ -251,14 +293,21 @@ Claude Code was not installed, so that client remains untested.
 Browser executable changes require an explicit migration.
 No test establishes that websites cannot detect automation.
 
+Broader validation on 2026-11-05 found a 30-second `camofox_scroll` timeout with one set of saved fingerprints.
+The same fingerprints reproduced the timeout on the pre-transfer baseline.
+The current version passed with the baseline fingerprints. Successful ZIP transfer checks do not establish complete browser acceptance.
+
 ## Source layout
 
-- `tests/unit/`: offline logic and verdict tests, including Node regression tests.
+- `tests/unit/`: offline logic, archive format, UI API, and verdict tests.
+- `tests/regression/`: browser plugin and persistence tests that run directly with Node.
 - `tests/integration/`: offline process, setup, catalog, and transaction checks.
 - `tests/browser/`: explicit browser acceptance commands.
 - `tests/qa/`: package, public-site, and human acceptance commands.
 - `tests/helpers/`: shared fixtures and verdict readers.
 - `scripts/call.ts`: development MCP diagnostic client.
 
-UI source is in `apps/ui/src/`. Its browser imports use only `packages/stelz/src/api/contracts.ts`.
-The contract contains no Node, Bun, or server imports. It is not a public package API.
+UI source is in `ui/src/`.
+It shares profile and transfer types through `src/api/contracts.ts` and `src/api/transfer-contracts.ts`.
+Server types use type-only imports. Server runtime modules stay on the backend.
+These contracts are not a public package API.

package/docs/ui.md

@@ -11,7 +11,7 @@ The browsers and their open pages remain active.
 Select **Turn off UI** in the header to end the UI session and stop its server.
 The button also expires the session cookie. Running browsers stay open.
 Finish active UI operations before using the button.
-The UI asks before discarding unsaved network edits.
+The UI asks before discarding unsaved edits.
 Start `stelz ui` again to obtain a new session URL.
 
 For a source checkout, first run `bun run build`.
@@ -45,7 +45,8 @@ Open **Profiles**. Select **New profile** and enter a name.
 Supply a proxy URL if necessary. Leave it blank to use a direct connection.
 Creation saves the profile without starting a browser.
 The service assigns its port and uses a native persistent profile.
-You can configure its network later in the Network tab.
+Overview contains its connection settings, typing preferences, and browser windows.
+Device and Logs contain the technical information.
 
 The profile table shows browser phase and controller ownership separately.
 A ready browser can still have an active MCP controller.
@@ -68,16 +69,31 @@ A failed IP check keeps actions blocked.
 An operation timeout can require an explicit stop and start.
 See [Use the service](README.md) for process inspection and recovery procedures.
 
+## Rename a profile
+
+Select the pencil beside the profile name. Enter the new name and select **Save name**.
+Escape or **Cancel rename** discards the edit.
+The name updates in the profile list and heading. It can change while the browser is running.
+The profile ID, saved data, proxy references, and MCP commands remain unchanged.
+Browser window title prefixes continue to show the stable profile ID.
+
+## Import and export
+
+Use **Import** or **Export** in the Profiles heading to transfer one or more profiles as a ZIP archive.
+Export requires cleanly stopped profiles. Import previews destination IDs and display names before saving the selected batch.
+The archive includes saved logins and available proxy credentials. Keep it private.
+See [Import and export profiles](profile-transfer.md) for compatibility requirements and CLI commands.
+
 ## Typing mode
 
 Open a profile's Overview tab. Select **Default typing mode** under **Typing**:
 
-- **Service default** inherits the service setting. Its label shows the inherited mode.
 - **Automatic** uses random pauses for text with an estimated typing duration of at most 10 seconds. Longer text uses bulk entry.
 - **Keyboard input** sends individual keystrokes without artificial delays.
 - **Instant input** enters the complete text at once.
 
 Changes save automatically and apply to future typing actions without a browser restart.
+The selector shows the profile's effective mode. Profiles without an override use the service setting until you choose another mode.
 Typing changes preserve unsaved network edits. Pending profile operations temporarily disable the selector.
 The setting applies only to the selected profile. Each agent can override it with the `camofox_type` tool's `mode` argument.
 
@@ -123,7 +139,7 @@ The installed Camoufox app remains unchanged.
 ## Delete a profile
 
 Stop the profile cleanly. Open its details and select **Delete profile**.
-Type its exact name to confirm deletion.
+Type its exact profile ID, shown above the confirmation field, to confirm deletion.
 The service removes the profile from the list and archives its complete directory under `STELZ_HOME/trash/`.
 The archive includes its configuration in `profile.json` and its saved browser data in `profile/`.
 The service retains secret values because other profiles can share them.
@@ -137,18 +153,18 @@ Read-only status does not change the transaction. Conflicting manual edits block
 ## Network configuration
 
 Stop a profile before you edit its network configuration.
-Direct mode is the default. A proxy is optional.
-Select **Direct (no proxy)** to use the connection without a proxy.
-Direct mode requires no IP lookup unless you set an expected exit IP.
-The Network tab permits direct or proxy mode, a replacement proxy URL, and an expected exit IP.
-Open **IP verification** to set an expected exit IP.
-A blank replacement proxy field preserves the saved credential.
-An empty expected IP removes that check in direct mode.
-Proxy mode always requires a successful browser-side IP check.
+A proxy is optional. An empty **Proxy URL** uses a direct connection.
+The **Connection** section in Overview shows the saved proxy address and optional expected exit IP.
+Change the address to replace the proxy. Clear it and save to remove the proxy.
+An unchanged address preserves its saved authentication, including when you change only the expected IP.
+These fields are visible without opening a disclosure or selecting a connection mode.
+A direct connection requires no IP lookup unless you set an expected exit IP.
+An empty expected IP removes that requirement for a direct connection.
+A proxy connection always requires a successful browser-side IP check.
 
 The UI never shows saved proxy authentication.
-Environment overrides make the affected fields read-only.
-The UI refuses edits to shared secret references.
+Environment overrides and shared secrets keep their values read-only.
+**Remove proxy** disconnects this profile from a managed proxy. It preserves the secret for other profiles.
 A conflicting save requires a fresh configuration before another save.
 The backend checks process ownership and configuration again before it writes.
 
@@ -158,7 +174,7 @@ Read-only status does not complete the transaction.
 Conflicting manual edits block recovery.
 Run `stelz doctor ID` to inspect the failure.
 
-Profile IDs cannot be renamed after creation. Storage mode, saved device properties, and browser versions remain read-only.
+Display names are editable. Profile IDs, storage mode, saved device properties, and browser versions remain read-only.
 All profile state stays under `STELZ_HOME`.
 The service has no saved-profile count limit or global active-browser limit.
 Each profile has at most one browser instance. Other running profiles do not disable Start.

package/examples/onboarding-fixture.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<title>Stelz onboarding check</title>
+<h1>Stelz onboarding check</h1>
+<p>This page contains only local test data.</p>
+<button id="verify" type="button">Verify Stelz</button>
+<p id="result" role="status">Not verified</p>
+<p id="count"></p>
+<script>
+const count = document.getElementById("count");
+const saved = Number(localStorage.getItem("stelz-onboarding-count") || 0);
+let checks = Number.isSafeInteger(saved) && saved >= 0 ? saved : 0;
+count.textContent = `Persistent check count: ${checks}`;
+document.getElementById("verify").onclick = () => {
+  checks++;
+  localStorage.setItem("stelz-onboarding-count", String(checks));
+  document.getElementById("result").textContent = "Stelz verified";
+  count.textContent = `Persistent check count: ${checks}`;
+};
+</script>
+</html>

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "stelz",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Standalone persistent Camoufox profiles with exclusive MCP control",
   "license": "MIT",
   "homepage": "https://github.com/souljorje/stelz#readme",
   "bugs": {
     "url": "https://github.com/souljorje/stelz/issues"
   },
-  "keywords": ["browser", "automation", "camoufox", "playwright", "mcp", "persistent-profiles"],
+  "keywords": [
+    "browser",
+    "automation",
+    "camoufox",
+    "playwright",
+    "mcp",
+    "persistent-profiles"
+  ],
   "bin": {
     "stelz": "dist/cli.js"
   },
@@ -29,8 +36,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/souljorje/stelz.git",
-    "directory": "packages/stelz"
+    "url": "https://github.com/souljorje/stelz.git"
   },
   "publishConfig": {
     "access": "public",
@@ -39,8 +45,36 @@
   "type": "module",
   "packageManager": "bun@1.4.4",
   "scripts": {
-    "build": "bun ../../scripts/build.ts",
-    "prepack": "bun run build"
+    "build": "bun scripts/build.ts",
+    "pack": "bun scripts/pack.ts",
+    "setup": "bun src/cli/cli.ts setup",
+    "start": "bun src/cli/cli.ts start",
+    "status": "bun src/cli/cli.ts status",
+    "stop": "bun src/cli/cli.ts stop",
+    "pause": "bun src/cli/cli.ts pause",
+    "resume": "bun src/cli/cli.ts resume",
+    "mcp": "bun src/cli/cli.ts mcp",
+    "ui": "bun --no-env-file src/cli/cli.ts ui",
+    "browser": "bun scripts/call.ts",
+    "fixture": "bun tests/helpers/fixture.ts",
+    "test": "bun test ./tests/unit ./tests/integration && bun run test:regression",
+    "test:ui": "bun test tests/integration/catalog-limits.test.ts tests/unit/profile-windows.test.ts tests/unit/ui-server.test.ts tests/integration/ui-model.test.ts tests/integration/profile-configuration.test.ts tests/integration/profile-rename.test.ts tests/unit/ui-api.test.ts tests/unit/ui-display.test.ts",
+    "test:ui:browser": "bun tests/browser/ui-browser.ts",
+    "test:regression": "node --experimental-transform-types --test tests/regression/*.test.ts",
+    "test:integration": "bun tests/browser/integration.ts",
+    "test:native": "bun tests/browser/native-integration.ts",
+    "test:window-close": "bun tests/browser/window-close.ts",
+    "test:windows": "bun --no-env-file tests/browser/profile-windows-browser.ts",
+    "test:proxy": "bun tests/browser/proxy-integration.ts",
+    "test:manual": "bun tests/qa/manual-integration.ts",
+    "test:typing": "bun --no-env-file tests/browser/typing-browser.ts",
+    "test:public": "bun --no-env-file tests/qa/public-sites.ts",
+    "test:package": "bun tests/qa/package.ts",
+    "typecheck": "tsc --noEmit",
+    "verify:release": "bun scripts/verify-release.ts",
+    "test:concurrency": "bun --no-env-file tests/browser/concurrency.ts",
+    "check": "bun run build && bun run typecheck && bun run test",
+    "test:transfer": "bun --no-env-file tests/browser/profile-transfer.ts"
   },
   "dependencies": {
     "@askjo/camofox-browser": "1.18.1",
@@ -49,10 +83,30 @@
     "hono": "4.13.16",
     "playwright-core": "1.62.1",
     "better-sqlite3": "13.0.1",
-    "impit": "0.14.8"
+    "impit": "0.14.8",
+    "stream-json": "3.8.0",
+    "yauzl": "3.4.0",
+    "yazl": "3.3.1"
   },
   "bundleDependencies": [
     "@askjo/camofox-browser",
     "camoufox-js"
-  ]
+  ],
+  "devDependencies": {
+    "@fontsource/ibm-plex-mono": "5.3.0",
+    "@fontsource/ibm-plex-sans": "5.3.0",
+    "@types/bun": "1.4.4",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "5.9.3",
+    "vite": "8.3.6",
+    "@types/yauzl": "3.4.0",
+    "@types/yazl": "3.3.1"
+  },
+  "patchedDependencies": {
+    "@askjo/camofox-browser@1.18.1": "patches/@askjo%2Fcamofox-browser@1.18.1.patch",
+    "camoufox-js@0.11.5": "patches/camoufox-js@0.11.5.patch"
+  }
 }

package/skills/stelz-browser/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stelz-browser
-description: Control an existing stelz browser profile through canonical MCP tools, with exclusive control and human authentication.
+description: Set up Stelz, create or reuse a persistent browser profile, connect the current agent, and control the browser through MCP with exclusive control and human authentication.
 ---
 
 # Instructions for agents
@@ -11,14 +11,18 @@ Each profile has at most one browser instance. Multiple windows can belong to th
 
 ## Procedure
 
+For installation, a missing profile, or missing tools, read [Onboarding](references/bootstrap.md).
+Use the authorized CLI setup and start commands when available. Reuse existing state and client settings.
+Do not treat MCP registration as proof that tools are available in this session.
+
 1. Call `profile_status`.
-2. Ask the operator to create an unknown profile in the UI. Ask them to start a stopped profile with `stelz start ID`.
+2. If the profile is missing or stopped, follow onboarding and run `stelz profile create ID --json` or `stelz start ID` as needed.
 3. Call `profile_acquire`.
 4. Read the open tabs with `camofox_list_tabs`.
 5. Read a fresh `camofox_snapshot` before you select an action.
 6. Use the returned element references for clicks and typing.
 7. Check the result with a fresh snapshot.
-8. Call `profile_release` when another client needs control.
+8. Call `profile_release` when the task is complete or another client needs control. Keep the browser available.
 
 An active controller causes another acquisition to fail. Wait for deliberate release or operator handoff.
 Do not start another browser to avoid a controller conflict.