libretto 0.6.12 → 0.6.14

package/skills/libretto/SKILL.md

@@ -4,7 +4,7 @@ description: "Browser automation CLI for building, maintaining, and running brow
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.6.12"
+  version: "0.6.14"
 ---
 
 ## How Libretto Works
@@ -19,25 +19,29 @@ The npm package includes `src/` (full TypeScript source) and `docs/` for deeper
 
 Full documentation is published at [libretto.sh](https://libretto.sh). Available pages:
 
-- Get started: [introduction](https://libretto.sh/get-started/introduction), [installation](https://libretto.sh/get-started/installation), [configuration](https://libretto.sh/get-started/configuration)
-- Fundamentals: [core concepts](https://libretto.sh/fundamentals/core-concepts), [how workflow generation works](https://libretto.sh/fundamentals/how-workflow-generation-works), [automation and bot detection](https://libretto.sh/fundamentals/automation-and-bot-detection), [website authentication](https://libretto.sh/fundamentals/website-authentication)
-- Workflow guides: [one-shot generation](https://libretto.sh/workflow-guides/one-shot-workflow-generation), [interactive building](https://libretto.sh/workflow-guides/interactive-workflow-building), [debugging workflows](https://libretto.sh/workflow-guides/debugging-workflows), [convert to network requests](https://libretto.sh/workflow-guides/convert-to-network-requests)
-- CLI reference: [open and connect](https://libretto.sh/cli-reference/open-and-connect), [sessions](https://libretto.sh/cli-reference/sessions), [profiles](https://libretto.sh/cli-reference/profiles), [snapshot](https://libretto.sh/cli-reference/snapshot), [exec](https://libretto.sh/cli-reference/exec), [run and resume](https://libretto.sh/cli-reference/run-and-resume), [session logs](https://libretto.sh/cli-reference/session-logs), [pages](https://libretto.sh/cli-reference/pages)
-- Library API: [workflow](https://libretto.sh/library-api/workflow), [AI extraction](https://libretto.sh/library-api/ai-extraction), [network requests](https://libretto.sh/library-api/network-requests), [file downloads](https://libretto.sh/library-api/file-downloads)
-- Hosting: [introduction](https://libretto.sh/hosting/introduction), [GCP](https://libretto.sh/hosting/gcp), [AWS](https://libretto.sh/hosting/aws)
+- Get started: [quickstart](https://libretto.sh/docs/get-started/quickstart), [first workflow](https://libretto.sh/docs/get-started/first-workflow), [deploying](https://libretto.sh/docs/get-started/deploying)
+- Fundamentals: [core concepts](https://libretto.sh/docs/understand-libretto/core-concepts), [how workflow generation works](https://libretto.sh/docs/understand-libretto/how-workflow-generation-works), [automation and bot detection](https://libretto.sh/docs/understand-libretto/automation-and-bot-detection), [website authentication](https://libretto.sh/docs/understand-libretto/website-authentication)
+- Workflow guides: [one-shot generation](https://libretto.sh/docs/guides/one-shot-workflow-generation), [interactive building](https://libretto.sh/docs/guides/interactive-workflow-building), [debugging workflows](https://libretto.sh/docs/guides/debugging-workflows), [convert to network requests](https://libretto.sh/docs/guides/convert-to-network-requests)
+- CLI reference: [open and connect](https://libretto.sh/docs/reference/cli/open-and-connect), [sessions](https://libretto.sh/docs/reference/cli/sessions), [profiles](https://libretto.sh/docs/reference/cli/profiles), [snapshot](https://libretto.sh/docs/reference/cli/snapshot), [exec](https://libretto.sh/docs/reference/cli/exec), [run and resume](https://libretto.sh/docs/reference/cli/run-and-resume), [session logs](https://libretto.sh/docs/reference/cli/session-logs), [pages](https://libretto.sh/docs/reference/cli/pages)
+- Library API: [workflow](https://libretto.sh/docs/reference/runtime/workflow), [AI extraction](https://libretto.sh/docs/reference/runtime/ai-extraction), [network requests](https://libretto.sh/docs/reference/runtime/network-requests), [file downloads](https://libretto.sh/docs/reference/runtime/file-downloads)
+- Libretto Cloud Hosting: [overview](https://libretto.sh/docs/libretto-cloud-hosting/overview), [authentication](https://libretto.sh/docs/libretto-cloud-hosting/authentication), [deployments](https://libretto.sh/docs/libretto-cloud-hosting/deployments)
+- Alternative providers: [overview](https://libretto.sh/docs/alternative-providers/overview), [Kernel](https://libretto.sh/docs/alternative-providers/kernel), [Browserbase](https://libretto.sh/docs/alternative-providers/browserbase), [GCP](https://libretto.sh/docs/alternative-providers/gcp), [AWS](https://libretto.sh/docs/alternative-providers/aws)
 
 ## Default Integration Approach
 
-- Prefer network requests first for new integrations unless the user explicitly asks for Playwright or UI automation, then do not use the site's internal API.
-- Read `references/site-security-review.md` before committing to a network-first approach on a new site.
-- Fall back to passive interception or Playwright-driven UI automation when the security review rules network requests out, the request path is not workable, or the user explicitly asks for Playwright.
+- Use Playwright for navigation and other non-fetch browser behavior, including document and asset loads.
+- Prefer browser-context `fetch()` for data extraction and form submission when the target is a real site fetch/XHR endpoint and `references/site-security-review.md` says the path is safe and workable.
+- Use passive interception when the UI already triggers useful fetch/XHR requests or active fetch is risky.
+- Fall back to Playwright UI automation when fetch is ruled out, the request path is not workable, or the user explicitly asks for Playwright/UI automation.
 
 ## Setup
 
-- Use `npx libretto setup` for first-time workspace onboarding. It installs Chromium, syncs skills, and pins the default snapshot model to `.libretto/config.json` when provider credentials are available.
-- Re-running `setup` on a healthy workspace shows the current configuration. If credentials are missing for a configured provider, it offers an interactive repair flow.
-- Use `npx libretto status` to inspect AI configuration health and open sessions without triggering setup.
-- Use `npx libretto ai configure openai|anthropic|gemini|vertex` to explicitly change the snapshot model or provider (advanced override).
+- Use `npx libretto setup` for first-time workspace onboarding. It installs Chromium and syncs skills.
+- Use `npx libretto status` to inspect open sessions without triggering setup.
+
+## Experiments
+
+- Use `npx libretto experiments` to list internal feature flags and `npx libretto experiments describe <name>` for usage notes when an experiment is enabled.
 
 ## Working Rules
 
@@ -46,8 +50,8 @@ Full documentation is published at [libretto.sh](https://libretto.sh). Available
 - Do not treat visibility as interactivity. If an element will not act, inspect blockers before retrying.
 - Defer repo/code review until you begin generating code, unless the user explicitly asks for it earlier.
 - Read and follow guidelines in `references/code-generation-rules.md` before generating or editing production workflow code.
-- Validation requires a successful clean `run --headless` with confirmation of the actual returned output, not just process success. If the user wants to watch the finished workflow, do a final headed `run` after headless validation succeeds.
-- After validation, always show the user: (1) the output/results from the headless validation run, and (2) a headed version of the same command so they can re-run it themselves and watch the browser (e.g. replace `--headless` with `--headed`). Include any `--params` or `--auth-profile` flags the workflow needs.
+- Validation requires a successful clean `run` with confirmation of the actual returned output, not just process success. Use the same headed or headless mode that the workflow run is already using.
+- After validation, always show the user: (1) the output/results from the validation run, and (2) the same command so they can re-run it themselves. Include any `--params`, `--headed`, `--headless`, or `--auth-profile` flags the workflow needs.
 - Treat exploration sessions as disposable unless the user explicitly wants one kept open.
 - Get explicit user confirmation before mutating actions or replaying network requests that may have side effects.
 - Never run multiple `exec` commands at the same time.
@@ -95,20 +99,15 @@ npx libretto session-mode --session my-session
 ### `snapshot`
 
 - Use `snapshot` as the primary page observation tool.
-- Always provide both `--objective` and `--context`.
-- A single snapshot objective can include multiple questions or analysis tasks.
+- Run `snapshot` without `--objective` or `--context`; the command prints a screenshot path and compact accessibility tree for the current page.
+- Run `snapshot <ref>` to inspect a subtree from the latest full snapshot. Use ref forms printed in the tree, such as `l16`; numeric-suffix aliases such as `e16` also match `l16`.
+- Run an unscoped snapshot before using refs. Subtree snapshots capture a fresh screenshot but reuse the latest cached tree.
 - Use it before guessing at selectors, after workflow failures, and whenever the visible page state is unclear.
-- When analysis is involved, expect it to take time. Use a timeout of at least 2 minutes for shell-wrapped calls.
 
 ```bash
-npx libretto snapshot \
-  --objective "Find the sign-in form and submit button" \
-  --context "I just opened the login page and need the email field, password field, and submit button."
-npx libretto snapshot \
-  --session debug-example \
-  --page <page-id> \
-  --objective "Explain why the table is empty" \
-  --context "I opened the referrals page, applied filters, and expected rows to appear."
+npx libretto snapshot --session debug-example
+npx libretto snapshot <ref> --session debug-example
+npx libretto snapshot --session debug-example --page <page-id>
 ```
 
 ### `exec`
@@ -116,16 +115,18 @@ npx libretto snapshot \
 - Use `exec` for focused inspection and short-lived interaction experiments.
 - Use `exec` to validate selectors, inspect data, or prototype a step before you encode it in the workflow file.
 - Use `exec -` to run multi-line scripts from stdin, especially when the code is too long or complex for a command line argument.
-- Available globals: `page`, `context`, `browser`, `state`, `fetch`, `Buffer`.
+- The `exec` REPL is persistent for each browser session. Define helper functions once and reuse them in later `exec` calls.
+- Available globals: `page`, `frame`, `context`, `browser`, `fetch`, `Buffer`.
 - Let failures throw. Do not hide `exec` failures with `try/catch` or `.catch()`.
 - Do not run multiple `exec` commands in parallel.
 - Do not use `exec` in read-only diagnosis flows. Use `readonly-exec` from the `libretto-readonly` skill for those sessions.
+- After successful mutations, `exec` prints page-change diffs from compact snapshots.
 
 ```bash
-npx libretto exec "return await page.url()"
-npx libretto exec "return await page.locator('button').count()"
+npx libretto exec "await page.url()"
 npx libretto exec "await page.locator('button:has-text(\"Continue\")').click()"
-echo "return await page.url()" | npx libretto exec - --session debug-example
+echo "async function textOf(selector) { return await page.locator(selector).textContent(); }" | npx libretto exec - --session debug-example
+npx libretto exec --session debug-example "await textOf('h1')"
 ```
 
 ### `pages`
@@ -135,13 +136,13 @@ echo "return await page.url()" | npx libretto exec - --session debug-example
 
 ```bash
 npx libretto pages --session debug-example
-npx libretto exec --session debug-example --page <page-id> "return await page.url()"
+npx libretto exec --session debug-example --page <page-id> "await page.url()"
 ```
 
 ### `run`
 
-- Use `run` to verify a workflow file after creating it or editing it, preferring `run --headless` for the normal fix/verify loop.
-- Plain `run` defaults to headed mode.
+- Use `run` to verify a workflow file after creating it or editing it. Use the same headed or headless mode for validation that the workflow run is already using.
+- Plain `run` defaults to headed mode. Do not use `--headless` unless the user asks for headless mode or the existing workflow run already uses it.
 - Successful runs close the browser by default. Pass `--stay-open-on-success` when you need to inspect the completed state with `pages`, `snapshot`, or `exec`.
 - Pass `--read-only` if the preserved session should come back locked for follow-up terminal inspection after the workflow run.
 - If the workflow fails, Libretto keeps the browser open. Inspect the failed state with `snapshot` and `exec` before editing code.
@@ -150,9 +151,9 @@ npx libretto exec --session debug-example --page <page-id> "return await page.ur
 - Re-run the same workflow after each fix to verify the browser behavior end to end.
 
 ```bash
-npx libretto run ./integration.ts --headless --params '{"status":"open"}'
-npx libretto run ./integration.ts --headless --read-only
-npx libretto run ./integration.ts --headless --stay-open-on-success
+npx libretto run ./integration.ts --params '{"status":"open"}'
+npx libretto run ./integration.ts --read-only
+npx libretto run ./integration.ts --stay-open-on-success
 npx libretto run ./integration.ts --auth-profile app.example.com
 ```
 
@@ -227,15 +228,15 @@ Key fields: `ts` (ISO timestamp), `method` (HTTP method, e.g. `GET`, `POST`), `u
 Assistant: I'll inspect the real site first if needed, but before I finish I'll create `target-workflow.ts` so the task produces reusable automation code.
 Assistant: [Runs `npx libretto open https://target.example.com --headed`]
 Assistant: [Reads `references/site-security-review.md` before choosing between passive network inspection, direct browser fetch calls, and Playwright-first automation]
-Assistant: [Runs `npx libretto snapshot --objective "Find the next required action" --context "We are starting the workflow from the landing page and need the first meaningful step."`]
+Assistant: [Runs `npx libretto snapshot --session <session>`]
 Assistant: [Uses `snapshot` and `exec` as needed to understand the site and decide the implementation path]
 Assistant: [Reads `references/code-generation-rules.md` before writing production workflow code]
 Assistant: I found the working path. I'll now create the workflow file and verify it.
 Assistant: [Creates or edits `target-workflow.ts` following `references/code-generation-rules.md`]
-Assistant: [Runs `npx libretto run ./target-workflow.ts --headless --params '{"status":"open"}'` to validate]
+Assistant: [Runs `npx libretto run ./target-workflow.ts --params '{"status":"open"}'` to validate]
 Assistant: Validation passed. Here are the results:
-[Shows the output/results from the headless run]
-To watch it yourself in a browser, run: npx libretto run ./target-workflow.ts --headed --params '{"status":"open"}'
+[Shows the output/results from the validation run]
+To run it again, use: npx libretto run ./target-workflow.ts --params '{"status":"open"}'
 </example>
 ```
 
@@ -245,25 +246,26 @@ To watch it yourself in a browser, run: npx libretto run ./target-workflow.ts --
 <example>
 [Context: The user has an existing Libretto workflow that is failing]
 Assistant: I'll reproduce the failure first so we can inspect the exact browser state it leaves behind.
-Assistant: [Runs `npx libretto run ./integration.ts --session debug-flow --headed`]
+Assistant: [Runs `npx libretto run ./integration.ts --session debug-flow`]
 Assistant: The workflow failed and Libretto kept the browser open. I'll inspect the page state before changing code.
-Assistant: [Runs `npx libretto snapshot --session debug-flow --objective "Find the blocking error or broken selector target" --context "The workflow just failed after trying to continue from the review step, and I need to identify the visible blocker on the current page."`]
+Assistant: [Runs `npx libretto snapshot --session debug-flow`]
 Assistant: [Runs `npx libretto exec --session debug-flow "...focused inspection or prototype..."`]
 Assistant: [Reads `references/code-generation-rules.md` before patching the workflow file]
 Assistant: I found the issue. I'll patch the workflow code and verify.
 Assistant: [Edits `integration.ts` following `references/code-generation-rules.md`]
-Assistant: [Runs `npx libretto run ./integration.ts --headless` to validate the fix]
+Assistant: [Runs `npx libretto run ./integration.ts` to validate the fix]
 Assistant: Fix verified. Here are the results:
-[Shows the output/results from the headless run]
-To watch it yourself in a browser, run: npx libretto run ./integration.ts --headed
+[Shows the output/results from the validation run]
+To run it again, use: npx libretto run ./integration.ts
 </example>
 ```
 
 ## References
 
-- Read `references/configuration-file-reference.md` when you need to inspect or change `.libretto/config.json` for snapshot model selection or viewport defaults.
+- Read `references/configuration-file-reference.md` when you need to inspect or change `.libretto/config.json` for viewport or session defaults.
 - Read `references/site-security-review.md` before reviewing the site's security posture and deciding whether to lead with network requests, passive interception, or Playwright DOM automation on a new site.
 - Read `references/code-generation-rules.md` before writing or editing production workflow files.
 - Read `references/auth-profiles.md` when auth-profile behavior is relevant.
 - Read `references/pages-and-page-targeting.md` when a session has multiple open pages or you need `--page`.
 - Read `references/action-logs.md` for full action log field descriptions and user-vs-agent event semantics.
+- If the workflow code is deployed to the Libretto Cloud platform and you need to reference its API docs, fetch [https://libretto.sh/docs/llms.txt](https://libretto.sh/docs/llms.txt) and follow the relevant page links.

package/skills/libretto/references/code-generation-rules.md

@@ -117,6 +117,12 @@ Do not rely on broad DOM querying inside `page.evaluate()` for production flows
 
 ## Network Request Methods
 
+Network request methods are for active fetch/XHR endpoints the site already uses. Prefer them for data extraction or form submissions when the security review shows the path is safe and workable.
+
+Before codifying a network request, confirm that the browser primitive matches how the site normally makes that request. Use `page.goto()` or link clicks for document navigation. Use `page.evaluate(fetch)` only for endpoints the site calls with fetch/XHR. Let the DOM load scripts, images, stylesheets, and iframes naturally, or create the corresponding DOM element if you truly need that request type.
+
+Do not use `fetch()` to avoid UI navigation for page HTML or asset URLs. The request still comes from the browser, but the browser marks it as fetch/XHR with different request-context headers than a navigation, script, image, stylesheet, or iframe load. Do not try to fix that by copying headers, because the browser controls the request context. Prefer passive network interception when the site's own UI already triggers the useful request.
+
 When codifying network-based data extraction or form submissions, wrap `page.evaluate(() => fetch(...))` calls in typed methods on a shared API client class:
 
 ```typescript

package/skills/libretto/references/configuration-file-reference.md

@@ -1,25 +1,26 @@
 # Configuration File Reference
 
-Use this reference when you need to inspect or change the workspace configuration that powers `snapshot` analysis and default viewport behavior.
+Use this reference when you need to inspect or change workspace configuration for default browser behavior.
 
 ## When to Use This
 
-- You want to confirm which AI model `snapshot` will use.
 - You want to understand where Libretto stores workspace-level settings.
 - You want a persistent default viewport for `open` or `run`.
+- You want a persistent default browser provider, such as Kernel or Browserbase.
 
 ## File Location
 
 Libretto reads workspace config from `.libretto/config.json`.
 
-- The file is created by `npx libretto setup` during first-time onboarding (auto-pins the default model for the detected provider) or by `npx libretto ai configure ...` for explicit overrides.
-- API credentials come from your shell environment or a `.env` file **at the repository root** (next to your `.git` directory). The config file stores the selected model, not the secret itself. Set `LIBRETTO_DISABLE_DOTENV=1` to skip `.env` loading (useful in CI).
-- Use `npx libretto status` to inspect the current AI configuration and open sessions without changing anything.
+- The file is created by `npx libretto setup` during first-time onboarding.
+- Use `npx libretto status` to inspect open sessions without changing anything.
 - For first-time setup instructions, follow the main `SKILL.md` flow instead of expanding this reference.
 
 ## Supported Settings
 
-- `snapshotModel` selects the configured analysis model for `snapshot`.
+- `provider` is an optional top-level setting used by `open` and `run` when you do not pass `--provider` and do not set `LIBRETTO_PROVIDER`. Must be `"local"`, `"kernel"`, `"browserbase"`, or `"libretto-cloud"`.
+- Provider precedence is: CLI `--provider`, then `LIBRETTO_PROVIDER`, then `.libretto/config.json`, then `"local"`.
+- Provider credentials belong in the repo root `.env` file, which Libretto loads automatically before running CLI commands.
 - `viewport` is an optional top-level setting used by `open` and `run` when you do not pass `--viewport`.
 - Viewport precedence is: CLI `--viewport`, then `.libretto/config.json`, then the default `1366x768`.
 - `sessionMode` sets the default session access mode for new sessions created by `open`, `connect`, and `run`. Must be `"read-only"` or `"write-access"`. When omitted, defaults to `"write-access"`. Pass `--read-only` or `--write-access` to `open`, `connect`, or `run` to override when creating a session.
@@ -29,7 +30,7 @@ Example:
 ```json
 {
   "version": 1,
-  "snapshotModel": "openai/gpt-5.4",
+  "provider": "kernel",
   "viewport": {
     "width": 1280,
     "height": 800
@@ -41,15 +42,16 @@ Example:
 ## Common Commands
 
 ```bash
-npx libretto setup                                         # first-time onboarding, auto-pins default model
-npx libretto status                                        # inspect AI config and open sessions
-npx libretto ai configure openai                           # explicitly change provider/model
+npx libretto setup                                         # first-time onboarding
+npx libretto status                                        # inspect open sessions
+npx libretto open https://example.com --provider kernel
+npx libretto run ./integration.ts --provider browserbase
 npx libretto open https://example.com --viewport 1440x900
 npx libretto run ./integration.ts --viewport 1440x900
 ```
 
 ## Notes
 
+- If you want a persistent default provider for the workspace, add `provider` to `.libretto/config.json` instead of repeating `--provider` on every command.
 - If you want a persistent default viewport for the workspace, add `viewport` to `.libretto/config.json` instead of repeating `--viewport` on every command.
-- If `snapshot` analysis is not configured yet, run `npx libretto setup` to auto-configure, or see the main `SKILL.md` flow.
-- Run `npx libretto status` at any time to check which model is active and whether credentials are present.
+- Run `npx libretto status` at any time to check open sessions.

package/skills/libretto/references/pages-and-page-targeting.md

@@ -19,7 +19,7 @@ Use this reference when a Libretto session has multiple open pages and you need
 ```bash
 npx libretto pages --session debug-flow
 npx libretto exec --session debug-flow --page <page-id> "return await page.url()"
-npx libretto snapshot --session debug-flow --page <page-id> --objective "Find the active form"
+npx libretto snapshot --session debug-flow --page <page-id>
 ```
 
 ## Notes

package/skills/libretto/references/site-security-review.md

@@ -60,10 +60,11 @@ Use the review above to decide what is safe to prioritize. Every integration use
 
 ### Strategy A: Prioritize `page.evaluate(fetch(...))`
 
-Make fetch calls directly from within the browser's JavaScript context. The requests share the browser's TLS fingerprint, cookies, and origin. They look identical to requests the site's own JS would make.
+Make fetch calls directly from within the browser's JavaScript context. Use this only for endpoints the site already calls with fetch/XHR, not for page navigation or asset loads.
 
 When to prioritize this:
 
+- The target endpoint is normally called by the site with fetch/XHR
 - No enterprise bot protection is detected
 - `fetch` is not monkey-patched
 - The API responses are parseable and useful
@@ -71,7 +72,7 @@ When to prioritize this:
 
 Why: maximum control and efficiency. You call exactly the endpoints you want with the parameters you want, skip UI rendering, and get structured JSON back. On sites without aggressive detection, this is the fastest and cleanest approach.
 
-Risk: if the site monitors fetch call stacks, your calls may be flagged because they do not originate from the site's bundled code. This is uncommon but exists on high-security sites.
+Risk: fetch is the wrong primitive for page HTML and asset URLs; use Playwright navigation or DOM-driven loads for those. Sites can also monitor fetch call stacks and flag calls that do not originate from the site's bundled code.
 
 You will still use Playwright for initial navigation, login/auth flows, cookie consent, and any UI interactions needed to establish session state before making fetch calls.
 
@@ -111,10 +112,9 @@ Trade-off: it is slower, more fragile against DOM changes, and you only get data
 
 | Site Profile | Primary Strategy | Supplement With |
 | --- | --- | --- |
-| No bot protection, fetch not patched | A (`page.evaluate(fetch)`) | Playwright for navigation/auth |
-| No bot protection, fetch is patched | B (`page.on('response', ...)`) | Playwright for navigation; DOM extraction as fallback |
-| Bot protection detected, fetch not patched | B (`page.on('response', ...)`) | Playwright for navigation; cautious use of `page.evaluate(fetch)` only if needed |
-| Bot protection detected, fetch is patched | B (`page.on('response', ...)`) | Playwright for navigation; DOM extraction as fallback |
+| No bot protection, fetch/XHR endpoint, fetch not patched | A (`page.evaluate(fetch)`) | Playwright for navigation/auth |
+| No bot protection, fetch is patched or endpoint is not fetch/XHR | B (`page.on('response', ...)`) | Playwright for navigation; DOM extraction as fallback |
+| Bot protection detected | B (`page.on('response', ...)`) | Playwright for navigation; cautious use of `page.evaluate(fetch)` only if needed |
 | Server-rendered content (no API calls) | C (DOM extraction) | Playwright for all interaction |
 
 ## Output: Site Assessment Summary

package/skills/libretto-readonly/SKILL.md

@@ -4,7 +4,7 @@ description: "Read-only Libretto workflow for diagnosing live browser state with
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.6.12"
+  version: "0.6.14"
 ---
 
 ## How Libretto Read-Only Works
@@ -49,14 +49,7 @@ npx libretto pages --session failed-job-debug
 ### `snapshot`
 
 - Use `snapshot` as the first high-level observation tool.
-- Always provide both `--objective` and `--context`.
-
-```bash
-npx libretto snapshot \
-  --session failed-job-debug \
-  --objective "Identify the visible failure state and likely blocking UI condition" \
-  --context "The workflow already failed and the preserved browser must remain read-only."
-```
+- Run `snapshot <ref>` to inspect a subtree from the latest full snapshot.
 
 ### `readonly-exec`
 

package/src/cli/cli.ts

@@ -1,6 +1,4 @@
-import { resolveAiSetupStatus } from "./core/ai-model.js";
 import { ensureLibrettoSetup } from "./core/context.js";
-import { librettoCommand } from "../shared/package-manager.js";
 import { createCLIApp } from "./router.js";
 import { warnIfInstalledSkillOutOfDate } from "./core/skill-version.js";
 import { loadEnv } from "../shared/env/load-env.js";
@@ -17,28 +15,6 @@ Docs (agent-friendly): https://libretto.sh/docs
 
 function printSetupAudit(): void {
   warnIfInstalledSkillOutOfDate();
-
-  const status = resolveAiSetupStatus();
-  switch (status.kind) {
-    case "ready":
-      console.log(`✓ Snapshot model: ${status.model}`);
-      break;
-    case "configured-missing-credentials":
-      console.log(
-        `✗ ${status.provider} configured (model: ${status.model}), but credentials are missing. Run \`${librettoCommand("setup")}\` to repair.`,
-      );
-      break;
-    case "invalid-config":
-      console.log(
-        `✗ AI config is invalid. Run \`${librettoCommand("setup")}\` to reconfigure.`,
-      );
-      break;
-    case "unconfigured":
-      console.log(
-        `✗ No AI model configured. Run \`${librettoCommand("setup")}\` or \`${librettoCommand("ai configure")}\` to set up.`,
-      );
-      break;
-  }
 }
 
 function isRootHelpRequest(rawArgs: readonly string[]): boolean {

package/src/cli/commands/auth.ts

@@ -1,15 +1,15 @@
 /**
- * Experimental auth commands for the libretto hosted platform.
+ * Hosted-platform auth commands.
  *
- *   libretto experimental auth signup
- *   libretto experimental auth login
- *   libretto experimental auth logout
- *   libretto experimental auth invite <email> [--role member|admin|owner]
- *   libretto experimental auth accept-invite <tenantSlug> <invitationId>
- *   libretto experimental auth api-key issue [--label <label>]
- *   libretto experimental auth api-key list
- *   libretto experimental auth api-key revoke <id>
- *   libretto experimental auth whoami
+ *   libretto cloud auth signup
+ *   libretto cloud auth login
+ *   libretto cloud auth logout
+ *   libretto cloud auth invite <email> [--role member|admin|owner]
+ *   libretto cloud auth accept-invite <tenantSlug> <invitationId>
+ *   libretto cloud auth api-key issue [--label <label>]
+ *   libretto cloud auth api-key list
+ *   libretto cloud auth api-key revoke <id>
+ *   libretto cloud auth whoami
  *
  * Credentials live at ~/.libretto/auth.json (mode 0600). The CLI sends either
  * the stored API key or the stored session cookie depending on what's
@@ -17,15 +17,15 @@
  */
 
 import { z } from "zod";
-import { SimpleCLI } from "../framework/simple-cli.js";
+import { SimpleCLI } from "affordance";
 import {
   ApiCallError,
   betterAuthCall,
-  HOSTED_API_URL,
   NOT_AUTHENTICATED_MESSAGE,
   orpcCall,
   pickCredential,
   resolveApiUrl,
+  resolveHostedApiUrl,
 } from "../core/auth-fetch.js";
 import {
   authStatePath,
@@ -198,11 +198,10 @@ async function issueApiKey(
 
 export const signupCommand = SimpleCLI.command({
   description: "Create a new hosted-platform account and organization",
-  experimental: true,
 })
   .input(SimpleCLI.input({ positionals: [], named: {} }))
   .handle(async () => {
-    const apiUrl = HOSTED_API_URL;
+    const apiUrl = resolveHostedApiUrl();
     console.log("Sign up for libretto cloud");
     console.log();
     console.log("Heads up: a libretto user can only belong to one organization.");
@@ -215,7 +214,7 @@ export const signupCommand = SimpleCLI.command({
     const name = await prompt("Your name:");
     if (name.toLowerCase() === "q" || name.length === 0) {
       console.log(
-        "OK — ask an existing teammate to run `libretto experimental auth invite <your-email>` and then run `libretto experimental auth accept-invite <slug> <invitation-id>` from this machine.",
+        "OK — ask an existing teammate to run `libretto cloud auth invite <your-email>` and then run `libretto cloud auth accept-invite <slug> <invitation-id>` from this machine.",
       );
       return;
     }
@@ -294,7 +293,7 @@ export const signupCommand = SimpleCLI.command({
     console.log(`Session saved to ${authStatePath()}`);
     console.log();
     console.log("To generate an API key, run:");
-    console.log("  libretto experimental auth api-key issue --label <label>");
+    console.log("  libretto cloud auth api-key issue --label <label>");
     console.log("Then add LIBRETTO_API_KEY=<key> to your project's .env file.");
   });
 
@@ -304,11 +303,10 @@ export const signupCommand = SimpleCLI.command({
 
 export const loginCommand = SimpleCLI.command({
   description: "Sign in to an existing hosted-platform account",
-  experimental: true,
 })
   .input(SimpleCLI.input({ positionals: [], named: {} }))
   .handle(async () => {
-    const apiUrl = HOSTED_API_URL;
+    const apiUrl = resolveHostedApiUrl();
 
     const email = await prompt("Email:");
     const password = await promptPassword("Password:");
@@ -375,7 +373,6 @@ export const loginCommand = SimpleCLI.command({
 
 export const logoutCommand = SimpleCLI.command({
   description: "Clear local libretto credentials",
-  experimental: true,
 })
   .handle(async () => {
     const state = await readAuthState();
@@ -400,7 +397,6 @@ export const logoutCommand = SimpleCLI.command({
 
 export const inviteCommand = SimpleCLI.command({
   description: "Invite a teammate to your active organization",
-  experimental: true,
 })
   .input(
     SimpleCLI.input({
@@ -475,7 +471,7 @@ export const inviteCommand = SimpleCLI.command({
     console.log();
     console.log("Tell them to run:");
     console.log(
-      `  libretto experimental auth accept-invite ${orgSlug} ${data.id}`,
+      `  libretto cloud auth accept-invite ${orgSlug} ${data.id}`,
     );
   });
 
@@ -485,7 +481,6 @@ export const inviteCommand = SimpleCLI.command({
 
 export const acceptInviteCommand = SimpleCLI.command({
   description: "Accept an organization invitation",
-  experimental: true,
 })
   .input(
     SimpleCLI.input({
@@ -514,7 +509,7 @@ export const acceptInviteCommand = SimpleCLI.command({
   )
   .handle(async ({ input }) => {
     const stored = await readAuthState();
-    const apiUrl = HOSTED_API_URL;
+    const apiUrl = resolveHostedApiUrl();
     const credential = pickCredential(stored);
     const expectedTenantSlug = input.tenantSlug;
 
@@ -535,7 +530,7 @@ export const acceptInviteCommand = SimpleCLI.command({
           [
             "You're already a member of an organization.",
             "A libretto user can only belong to one organization at a time.",
-            "To accept this invite: log out, delete the existing account, and re-run `auth accept-invite` with a new account (or a fresh email).",
+            "To accept this invite: log out, delete the existing account, and re-run `libretto cloud auth accept-invite` with a new account (or a fresh email).",
           ].join("\n"),
         );
       }
@@ -611,7 +606,7 @@ export const acceptInviteCommand = SimpleCLI.command({
     console.log();
     console.log("Email verified. You're logged in and a member of the organization.");
     console.log("To generate an API key, run:");
-    console.log("  libretto experimental auth api-key issue --label <label>");
+    console.log("  libretto cloud auth api-key issue --label <label>");
     console.log("Then add LIBRETTO_API_KEY=<key> to your project's .env file.");
   });
 
@@ -621,7 +616,6 @@ export const acceptInviteCommand = SimpleCLI.command({
 
 export const apiKeyIssueCommand = SimpleCLI.command({
   description: "Issue a new API key for the active organization",
-  experimental: true,
 })
   .input(
     SimpleCLI.input({
@@ -658,7 +652,6 @@ export const apiKeyIssueCommand = SimpleCLI.command({
 
 export const apiKeyListCommand = SimpleCLI.command({
   description: "List API keys for the active organization",
-  experimental: true,
 })
   .handle(async () => {
     const stored = await readAuthState();
@@ -691,13 +684,12 @@ export const apiKeyListCommand = SimpleCLI.command({
 
 export const apiKeyRevokeCommand = SimpleCLI.command({
   description: "Revoke an API key by id",
-  experimental: true,
 })
   .input(
     SimpleCLI.input({
       positionals: [
         SimpleCLI.positional("id", z.string().min(1), {
-          help: "API key id (from `auth api-key list`).",
+          help: "API key id (from `libretto cloud auth api-key list`).",
         }),
       ],
       named: {},
@@ -720,7 +712,7 @@ export const apiKeyRevokeCommand = SimpleCLI.command({
 
     console.log(`API key ${input.id} revoked.`);
     console.log(
-      "If this key was in your .env, remove the LIBRETTO_API_KEY value and issue a new one with `auth api-key issue --label <label>`.",
+      "If this key was in your .env, remove the LIBRETTO_API_KEY value and issue a new one with `libretto cloud auth api-key issue --label <label>`.",
     );
   });
 
@@ -730,7 +722,6 @@ export const apiKeyRevokeCommand = SimpleCLI.command({
 
 export const whoamiCommand = SimpleCLI.command({
   description: "Print the active session and credential source",
-  experimental: true,
 })
   .handle(async () => {
     const stored = await readAuthState();
@@ -740,13 +731,13 @@ export const whoamiCommand = SimpleCLI.command({
 
     if (credential.source === "none") {
       console.log(
-        "Not authenticated. Run `libretto experimental auth signup`, `login`, or set LIBRETTO_API_KEY in your env.",
+        "Not authenticated. Run `libretto cloud auth signup`, `libretto cloud auth login`, or set LIBRETTO_API_KEY in your env.",
       );
       return;
     }
 
     console.log(`Auth source:      ${credential.source}`);
-    console.log(`API URL:          ${HOSTED_API_URL}`);
+    console.log(`API URL:          ${resolveHostedApiUrl()}`);
     console.log(
       `LIBRETTO_API_KEY: ${envKey ? `set in env (${envKey.slice(0, 6)}…)` : "not set in env"}`,
     );

package/src/cli/commands/billing.ts

@@ -6,8 +6,8 @@
  * them switch between any of the configured Subscription Update
  * products (Free / Pro / Team).
  *
- *   libretto experimental billing portal   → Stripe Customer Portal
- *   libretto experimental billing status   → plan + usage + period end
+ *   libretto cloud billing portal   → Stripe Customer Portal
+ *   libretto cloud billing status   → plan + usage + period end
  *
  * `libretto init` is unchanged. New tenants start on Free automatically
  * (with a real Stripe Customer + Free Subscription created at signup).
@@ -15,7 +15,7 @@
  * Auth: requires a session cookie (or LIBRETTO_API_KEY).
  */
 
-import { SimpleCLI } from "../framework/simple-cli.js";
+import { SimpleCLI } from "affordance";
 import {
   NOT_AUTHENTICATED_MESSAGE,
   orpcCall,
@@ -71,7 +71,6 @@ function formatLimit(limit: number | null): string {
 
 export const billingPortalCommand = SimpleCLI.command({
   description: "Open the libretto plans page (current plan + switch options)",
-  experimental: true,
 })
   .handle(async () => {
     const { apiUrl, credential } = await requireAuth();
@@ -97,7 +96,6 @@ export const billingPortalCommand = SimpleCLI.command({
 
 export const billingStatusCommand = SimpleCLI.command({
   description: "Print the current plan, status, and browser-hour usage",
-  experimental: true,
 })
   .handle(async () => {
     const { apiUrl, credential } = await requireAuth();