studioflow 0.2.0 → 0.2.1

package/README.md

@@ -1,14 +1,16 @@
 # StudioFlow
 
-StudioFlow turns a plain-language demo request into a deterministic recorded run.
+StudioFlow turns a plain-language demo request into a deterministic recorded product run.
 
 This package includes:
 - a CLI runtime (`studioflow`) for deterministic artifact execution
-- bundled agent skills for Codex and Claude (`studioflow-investigate`, `studioflow-cli`)
+- bundled agent skills for Codex and Claude (`studioflow-investigate`, `studioflow-author`, `studioflow-cli`)
+
+StudioFlow supports both QuickTime Player and Screen Studio recording backends.
 
 ## Requirements
 
-- macOS (QuickTime/Screen Studio automation)
+- macOS (recorder automation is macOS-only)
 - Node.js 22+
 - QuickTime Player (built into macOS) or Screen Studio
 
@@ -18,70 +20,123 @@ This package includes:
 npm install -g studioflow
 ```
 
-## Setup Runtime + Skills
+## Quickstart (2 Minutes)
 
-`setup` installs Playwright Chromium, installs bundled skills for Codex and Claude, and checks permissions.
+1. Setup runtime dependencies and bundled skills:
 
 ```bash
 studioflow setup
+studioflow doctor
+studioflow config check
 ```
 
-## Default Workflow (Agent-First)
-
-You should not need to manually invoke multiple skills or manually run CLI commands for a normal demo request.
-Open Codex or Claude in your project and describe the demo you want.
-
-1. Start your agent from the project root.
-
-Codex:
+2. Open Codex or Claude from your project root:
 
 ```bash
 cd /path/to/your/project
 codex
+# or
+claude
 ```
 
-Claude Code:
+3. Ask in plain language:
 
-```bash
-cd /path/to/your/project
-claude
+```text
+Record a demo for onboarding and billing.
 ```
 
-If your launcher command differs, start your usual Codex or Claude session in this repo root.
+or
 
-2. Ask for the demo in plain language.
+```text
+Record a demo for onboarding and billing using Screen Studio.
+```
 
-Example:
+4. Expected successful run output includes:
 
 ```text
-Record a demo for onboarding and billing.
+Run completed successfully.
+Run ID: <timestamp-id>
+Artifacts: <path-to-run-dir>
 ```
 
-3. StudioFlow skills + CLI handle the rest:
-- investigate the codebase
-- generate deterministic artifacts (`artifacts/flow.json`, related context artifacts)
-- validate the flow
-- execute recording through the CLI runtime
+## Recorder Backends
+
+- `quicktime` (default): no extra app install required.
+- `screenstudio`: just specify Screen Studio in your agent request.
+
+Manual CLI mode still supports `--recorder screenstudio` when you want direct runtime control.
+
+## What `setup` Changes
+
+`studioflow setup`:
+- installs Playwright Chromium runtime
+- installs StudioFlow skills into:
+  - Codex: `$CODEX_HOME/skills` or `~/.codex/skills`
+  - Claude: `$CLAUDE_HOME/skills` or `~/.claude/skills`
+- runs permission diagnostics
+- writes setup state under `~/.studioflow` (or `$STUDIOFLOW_DATA_DIR`)
+
+## Command Cheat Sheet
+
+| Task | Command |
+| --- | --- |
+| Setup runtime + skills | `studioflow setup` |
+| Check permissions | `studioflow doctor` |
+| Show effective config | `studioflow config show` |
+| Validate config health | `studioflow config check` |
+| Validate flow artifact | `studioflow validate --flow artifacts/flow.json` |
+| Run deterministic demo | `studioflow demo --flow artifacts/flow.json --intent "your demo intent"` |
+| List built-in flows | `studioflow list-flows` |
+| QuickTime diagnostics | `studioflow quicktime-prep` |
+| Screen Studio diagnostics | `studioflow screenstudio-prep` |
+
+## Minimal Manual Flow (Optional)
+
+If you want to run the CLI directly without agent authoring first, start with a minimal artifact:
+
+```json
+{
+  "id": "landing_capture",
+  "description": "Capture the landing page",
+  "tags": ["smoke"],
+  "steps": [
+    { "id": "open-home", "action": "goto", "value": "/" },
+    { "id": "capture-home", "action": "screenshot", "value": "home" }
+  ]
+}
+```
+
+Then run:
+
+```bash
+studioflow validate --flow artifacts/flow.json
+studioflow demo --flow artifacts/flow.json --intent "landing page smoke"
+```
 
-`run`/`demo` automatically performs recorder preflight checks. QuickTime is the default backend; use `--recorder screenstudio` to opt into Screen Studio.
-Headed runs auto-open a maximized browser window for cleaner recording composition.
-Runs do not auto-export by default; include `recorder_export` in flow steps only when export is explicitly needed.
-Runs now also block `recorder_export` unless intent text explicitly asks for export, or `--allow-export true` is provided.
+## Quick Troubleshooting
 
-## Advanced Manual Mode (Optional)
+- Permission failures:
+  - `studioflow doctor` and approve macOS prompts.
+- QuickTime preflight failures:
+  - `studioflow quicktime-prep`
+- Screen Studio preflight failures:
+  - `studioflow screenstudio-prep`
+- App health timeout:
+  - `studioflow config show` and verify `baseUrl`, `startCommand`, `healthPath`.
+- Flow validation failures:
+  - `studioflow validate --flow <path>`
 
-If you want to run the runtime yourself:
+## Uninstall / Cleanup
 
 ```bash
-studioflow validate --flow artifacts/flow.json
-studioflow demo --flow artifacts/flow.json --intent "onboarding and billing demo"
+npm uninstall -g studioflow
 ```
 
-## Documentation
+Optional local cleanup:
+- remove `~/.studioflow` (or `$STUDIOFLOW_DATA_DIR`)
+- remove installed skill folders under `~/.codex/skills` and `~/.claude/skills` if you no longer want them
+
+## Contact
 
-- Day 0 runbook: https://github.com/ydarar/studioflow/blob/main/docs/day0-runbook.md
-- CLI reference: https://github.com/ydarar/studioflow/blob/main/docs/cli-reference.md
-- Configuration: https://github.com/ydarar/studioflow/blob/main/docs/configuration.md
-- Smoke checklist: https://github.com/ydarar/studioflow/blob/main/docs/testing-manual-smoke.md
-- Open intent tests: https://github.com/ydarar/studioflow/blob/main/docs/studioflow-open-intent-tests.md
-- Full docs map: https://github.com/ydarar/studioflow/blob/main/docs/README.md
+- X: https://x.com/Ydarar_dev (@Ydarar_dev)
+- GitHub: https://github.com/ydarar/studioflow/issues

package/bundled/skills/manifest.json

@@ -1,14 +1,17 @@
 {
   "schemaVersion": 1,
   "packageName": "studioflow",
-  "packageVersion": "0.2.0",
-  "generatedAt": "2026-02-14T18:48:19.096Z",
+  "packageVersion": "0.2.1",
+  "generatedAt": "2026-02-15T00:48:20.093Z",
   "skills": {
     "studioflow-cli": {
-      "hash": "4328ceed07012ece8406541b2e764d2ea686af473a6ce0206458a346f2e6eed8"
+      "hash": "ff59e41a56a6f1289c37e4d167d62eb00f80442fca08f571297444e45aa0e747"
     },
     "studioflow-investigate": {
-      "hash": "e2bf84ed56b7077575c2a875acc5b2c26cac7b34e84d8ceb213ff5d4357665fc"
+      "hash": "8e3034b43ea84834008900886e94a744f3bf22e7b05d2548c0123492f694f693"
+    },
+    "studioflow-author": {
+      "hash": "cd42e054957736b1d1d47e93839a5daf40bfe40cafda0c8d26380c0ac63d078d"
     }
   }
 }

package/bundled/skills/studioflow-author/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: studioflow-author
+description: Create or repair deterministic StudioFlow artifacts for a clarified demo intent. Use when `studioflow-investigate` routes to `patch-existing` or `create-new`, or when the user explicitly asks to generate/edit `artifacts/flow.json` and runtime handoff.
+---
+
+# StudioFlow Author
+
+Author and validate deterministic artifacts for runtime execution.
+
+## Workflow
+
+1. Consume clarified intent + routing context.
+
+Expected upstream context:
+- resolved anchors (`target_route`, `user_goal`, `done_assertion`)
+- recorder preference (`quicktime` or `screenstudio`)
+- route decision (`patch-existing` or `create-new`)
+
+2. Collect project context artifacts automatically. Do not ask the user to run these commands manually.
+
+```bash
+pnpm bootstrap -- --out artifacts/bootstrap.json
+pnpm discover -- --out artifacts
+```
+
+Fallback if workspace scripts are unavailable:
+
+```bash
+studioflow bootstrap --out artifacts/bootstrap.json
+studioflow discover --out artifacts
+```
+
+3. Review:
+- `artifacts/bootstrap.json`
+- `artifacts/structure-report.json`
+- `artifacts/navigation-graph.json`
+- existing `artifacts/flow.json` if present
+
+4. Author `artifacts/flow.json` for the clarified intent.
+
+Rules:
+- Deterministic steps only.
+- Prefer stable selectors (`data-testid`).
+- Include clear step IDs and assertions at key transitions.
+- Always synthesize pacing fields (`preDelayMs`, `postDelayMs`, `mouseMoveMs`, `highlightMs`, `dwellMs`) for interaction-heavy steps to keep demos human-looking.
+- Model scroll risk explicitly. For below-fold or overflow-container targets, add deterministic setup/wait steps before interaction.
+- Add `recorder_export` only when user explicitly asks for export at run completion.
+- If clarification context is still incomplete, generate best-effort deterministic flow with explicit assumptions.
+
+5. Validate the authored artifact:
+
+```bash
+pnpm validate -- --flow artifacts/flow.json
+```
+
+6. If validation fails, patch flow selectors/actions/pacing and rerun validation.
+
+7. Emit runtime handoff for `studioflow-cli`.
+
+Write:
+- `artifacts/studioflow-cli-handoff.json`
+
+Use `references/cli-handoff-spec.md`.
+Always include:
+- `runtimePacing`
+- `recorder`
+
+8. Handoff to `studioflow-cli` immediately when the user intent is to run/record now.
+
+## Output Requirements
+
+Always produce:
+1. `artifacts/bootstrap.json`
+2. `artifacts/structure-report.json`
+3. `artifacts/navigation-graph.json`
+4. `artifacts/flow.json`
+5. `artifacts/studioflow-cli-handoff.json`
+
+Include a concise authoring summary:
+- what changed (new vs patched)
+- assumptions
+- confidence (`high|medium|low`)
+
+Use references in:
+- `references/artifact-spec.md`
+- `references/cli-handoff-spec.md`

package/bundled/skills/{studioflow-investigate → studioflow-author}/references/artifact-spec.md

@@ -42,6 +42,6 @@ Recorder note:
 - Without `recorder_export`, StudioFlow stops recording and completes the run without export.
 - Recorder software selection is not encoded in `flow.json`; include it in `studioflow-cli-handoff.json` as `recorder`.
 
-## Open-intent fallback note
+## Fallback note
 
-When the user intent remains open after clarification rounds, the assistant should still generate deterministic `flow.json` and include assumptions + confidence in the response handoff.
+When clarification inputs remain incomplete, still generate deterministic `flow.json` and include assumptions + confidence in handoff summary.

package/bundled/skills/studioflow-author/references/cli-handoff-spec.md

@@ -0,0 +1,60 @@
+# CLI Handoff Spec
+
+Use this artifact to hand execution from `studioflow-author` to `studioflow-cli`.
+
+Path:
+
+- `artifacts/studioflow-cli-handoff.json`
+
+## JSON shape
+
+```json
+{
+  "version": 1,
+  "intentSummary": "Record only onboarding + CRM in Demo Lab",
+  "flowPath": "artifacts/flow.json",
+  "recorder": "screenstudio",
+  "baseUrl": "http://localhost:4280",
+  "startCommand": "pnpm dev:demo-lab",
+  "healthPath": "/",
+  "runtimePacing": {
+    "profile": "standard",
+    "cursorMoveMs": 430,
+    "cursorHighlightMs": 170,
+    "typingDelayMs": 55,
+    "clickPulseMs": 220,
+    "stepPreDelayMs": 90,
+    "stepPostDelayMs": 130,
+    "stepDwellMs": 180
+  },
+  "notes": [
+    "Use deterministic artifact execution only."
+  ]
+}
+```
+
+## Field rules
+
+- `version`: integer, currently `1`.
+- `intentSummary`: concise run label for CLI `--intent`.
+- `flowPath`: deterministic artifact path. Default: `artifacts/flow.json`.
+- `recorder`: recorder backend used by CLI `--recorder`.
+  - Allowed values: `quicktime`, `screenstudio`.
+  - Selection rule: if user explicitly requests Screen Studio/QuickTime, preserve that; otherwise default `quicktime`.
+- `baseUrl`: runtime host URL.
+- `startCommand`: command used when app is not already healthy.
+- `healthPath`: health probe path used by runtime.
+- `runtimePacing`: required runtime timing overrides derived from authored flow pacing.
+  - Allowed fields: `profile`, `cursorMoveMs`, `cursorHighlightMs`, `typingDelayMs`, `clickPulseMs`, `stepPreDelayMs`, `stepPostDelayMs`, `stepDwellMs`.
+  - `profile` values: `fast`, `standard`, `cinematic`.
+- `notes`: optional operator notes.
+
+## Invocation contract
+
+When handoff artifact is written and the user asked to run/record now, invoke `studioflow-cli` (or equivalent runtime workflow in same agent) to execute:
+
+1. `pnpm validate -- --flow <flowPath>`
+2. `pnpm demo -- --flow <flowPath> --intent "<intentSummary>" --recorder <recorder> --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
+3. Set matching `STUDIOFLOW_*` env vars from `runtimePacing` on the demo command.
+
+Do not ask the user to translate handoff into commands.

package/bundled/skills/studioflow-cli/SKILL.md

@@ -7,12 +7,27 @@ description: Execute validated demo artifacts with StudioFlow CLI. Use when the
 
 Run validated artifacts through deterministic execution.
 
+## Sandbox Escalation (Required)
+
+When executing StudioFlow CLI commands from Codex tool environments, run the commands below with `sandbox_permissions: require_escalated` on the first attempt. Do not run them in sandbox first and retry after failure.
+
+- `pnpm install` (when dependencies are missing)
+- `pnpm run setup`
+- `pnpm run doctor`
+- `pnpm quicktime-prep`
+- `pnpm screenstudio-prep`
+- `pnpm validate -- --flow <flowPath>`
+- `pnpm demo -- --flow <flowPath> --intent "<intent-summary>" --recorder <recorder> --base-url <baseUrl> --start-command "<startCommand>" --health-path <healthPath>`
+
+Reason: these commands can require network access, local IPC sockets (`tsx`), GUI automation, recorder control, and app process orchestration that are commonly blocked in sandboxed execution.
+
 ## Workflow
 
 0. Resolve handoff input (if present):
 - `artifacts/studioflow-cli-handoff.json`
 
 If handoff exists, use it as the source of truth for `flowPath`, `intentSummary`, `baseUrl`, `startCommand`, and `healthPath`.
+Handoff may be produced by `studioflow-author`, or reused by `studioflow-investigate` when routing to execute-existing.
 If handoff includes `recorder`, treat it as source of truth and preserve explicit user recorder choice.
 If present, also consume `runtimePacing` from handoff for runtime timing env values.
 

package/bundled/skills/studioflow-cli/references/handoff-spec.md

@@ -1,6 +1,6 @@
 # Handoff Input Spec
 
-`studioflow-cli` accepts a runtime handoff file from `studioflow-investigate`:
+`studioflow-cli` accepts a runtime handoff file from `studioflow-author` (or from `studioflow-investigate` when reusing existing artifacts):
 
 - `artifacts/studioflow-cli-handoff.json`
 

package/bundled/skills/studioflow-investigate/SKILL.md

@@ -1,37 +1,15 @@
 ---
 name: studioflow-investigate
-description: Investigate an arbitrary web project and generate deterministic StudioFlow artifacts. Use when the user asks to discover app structure, map routes/components/actions, synthesize artifacts/flow.json from natural-language intent, or clarify open/ambiguous intent before authoring a flow.
+description: Intake and route StudioFlow demo requests. Use when the user asks to run or record a demo from natural language and you must (1) clarify intent anchors, (2) decide whether existing artifacts already fit the request, and (3) route to `studioflow-author` (create/repair) or `studioflow-cli` (execute existing artifacts).
 ---
 
 # StudioFlow Investigate
 
-Generate deterministic demo-planning artifacts for any web app.
+Resolve intent and route execution to the right downstream skill.
 
 ## Workflow
 
-1. Inspect project root and identify framework, package manager, and startup command.
-2. Always collect project context artifacts before intent mapping.
-
-Do this automatically in the skill workflow. Do not ask the user to run these commands manually.
-
-```bash
-pnpm bootstrap -- --out artifacts/bootstrap.json
-pnpm discover -- --out artifacts
-```
-
-Fallback if `pnpm` workspace scripts are unavailable:
-
-```bash
-studioflow bootstrap --out artifacts/bootstrap.json
-studioflow discover --out artifacts
-```
-
-3. Review generated artifacts:
-- `artifacts/bootstrap.json`
-- `artifacts/structure-report.json`
-- `artifacts/navigation-graph.json`
-
-4. Resolve intent specificity before authoring `artifacts/flow.json`.
+1. Resolve intent specificity first.
 
 Open-intent detection:
 - Treat intent as open when one or more anchors are missing:
@@ -55,54 +33,53 @@ Clarification loop:
 - If host supports structured question-card requests, emit payloads from `references/question-card-spec.md`.
 - If structured cards are not supported, ask equivalent plain-language questions.
 - Track known/missing fields using `references/clarification-state.md`.
+- If anchors remain unclear after round 2, make a best-effort route decision with explicit assumptions.
 
-5. Author `artifacts/flow.json` from intent + discovered structure + clarified answers.
+2. Evaluate current artifact readiness after clarification.
 
-Rules for authored flow:
-- Deterministic steps only.
-- Prefer stable selectors (`data-testid`).
-- Include clear step IDs and assertions at key transitions.
-- Always synthesize pacing fields (`preDelayMs`, `postDelayMs`, `mouseMoveMs`, `highlightMs`, `dwellMs`) for interaction-heavy steps to keep demos human-looking.
-- Model scroll risk during authoring. For below-fold or overflow-container targets, add stable preconditions (`wait_for` on section/container) before interaction steps.
-- Add `recorder_export` only when the user explicitly asks for export at run completion.
-- If clarification remains incomplete after 2 rounds, generate best-effort flow with explicit assumptions.
+Check for:
+- `artifacts/flow.json`
+- optional `artifacts/studioflow-cli-handoff.json`
+- optional `artifacts/bootstrap.json`
+- optional `artifacts/structure-report.json`
+- optional `artifacts/navigation-graph.json`
 
-6. Validate candidate flow:
+3. Run intent-to-artifact fit evaluation using `references/artifact-fit-spec.md`.
 
-```bash
-pnpm validate -- --flow artifacts/flow.json
-```
+Classify route:
+- `execute-existing`: artifacts are present and intent fit is high enough to run safely.
+- `patch-existing`: artifacts exist but require targeted edits.
+- `create-new`: artifacts are missing or intent fit is low.
 
-7. If validation fails, edit flow actions/selectors and rerun validation.
+Write decision trace to:
+- `artifacts/intent-fit-report.json`
 
-8. Emit deterministic runtime handoff for `studioflow-cli`.
+4. Route deterministically based on classification.
 
-Write `artifacts/studioflow-cli-handoff.json` using `references/cli-handoff-spec.md`.
-- Always include `runtimePacing` in handoff, inferred from authored flow pacing and intent.
-- Always include `recorder` in handoff (`quicktime` or `screenstudio`), resolved from intent wording + defaults.
+- For `execute-existing`:
+  - Invoke `studioflow-cli` immediately with existing artifacts and handoff/default runtime anchors.
+- For `patch-existing` or `create-new`:
+  - Invoke `studioflow-author` to create/repair deterministic artifacts for this intent.
+  - After `studioflow-author` completes, invoke `studioflow-cli` in the same turn.
 
-9. Hand off execution to `studioflow-cli` immediately.
+5. Do not stop at command suggestions when the user asked to run/record a demo.
 
-- If your host supports explicit skill invocation, invoke `studioflow-cli` in the same turn using the handoff payload.
-- If explicit skill invocation is unavailable, execute the equivalent CLI run workflow directly in the same turn.
-- Do not stop at "here is the command to run" when the user intent is to run/record a demo.
+- If your host supports explicit skill invocation, invoke downstream skills directly.
+- If explicit invocation is unavailable, execute equivalent workflows directly.
 
 ## Output Requirements
 
-Always produce these files for handoff to runtime execution:
-1. `artifacts/bootstrap.json`
-2. `artifacts/structure-report.json`
-3. `artifacts/navigation-graph.json`
-4. `artifacts/flow.json`
-5. `artifacts/studioflow-cli-handoff.json`
+Always produce:
+1. `artifacts/intent-fit-report.json`
+2. concise route decision (`execute-existing|patch-existing|create-new`)
 
 Always include a concise handoff summary in the response:
 - resolved intent anchors
+- route decision and reason
 - unresolved assumptions (if any)
 - confidence (`high|medium|low`)
 
 Use references in:
-- `references/artifact-spec.md`
 - `references/question-card-spec.md`
 - `references/clarification-state.md`
-- `references/cli-handoff-spec.md`
+- `references/artifact-fit-spec.md`

package/bundled/skills/studioflow-investigate/references/artifact-fit-spec.md

@@ -0,0 +1,73 @@
+# Artifact Fit Spec
+
+Use this rubric to decide whether existing artifacts satisfy the clarified demo intent.
+
+## Inputs
+
+- Clarified intent anchors:
+  - `target_route`
+  - `user_goal`
+  - `done_assertion`
+  - `recorder_backend`
+  - optional run-feel/profile
+- Existing artifacts (if present):
+  - `artifacts/flow.json`
+  - `artifacts/studioflow-cli-handoff.json`
+  - `artifacts/bootstrap.json`
+  - `artifacts/structure-report.json`
+  - `artifacts/navigation-graph.json`
+
+## Fit dimensions
+
+Score each dimension as `pass|partial|fail`.
+
+1. Route coverage:
+- `flow.json` steps reach the intended route/workspace.
+
+2. Goal coverage:
+- Steps demonstrate the requested business outcome, not just generic navigation.
+
+3. Completion evidence:
+- Assertions/screenshots prove the requested done state.
+
+4. Runtime anchors:
+- `baseUrl`, `healthPath`, `startCommand` can be resolved from handoff/bootstrap/config.
+
+5. Recorder and style alignment:
+- Recorder preference (`quicktime|screenstudio`) and pacing profile are preserved.
+
+## Route decision rules
+
+- `execute-existing`:
+  - no `fail` dimensions
+  - at most one `partial`
+- `patch-existing`:
+  - artifacts exist and deterministic edits are enough (selectors, assertions, pacing, minor scope drift)
+- `create-new`:
+  - artifacts missing
+  - or core route/goal/done coverage is `fail`
+
+## Required output
+
+Write `artifacts/intent-fit-report.json`:
+
+```json
+{
+  "version": 1,
+  "decision": "execute-existing",
+  "confidence": "high",
+  "intentAnchors": {
+    "targetRoute": "/flows/crm",
+    "userGoal": "advance and create a CRM lead",
+    "doneAssertion": "Created L-300 for Aurora Systems.",
+    "recorder": "quicktime"
+  },
+  "dimensions": [
+    { "name": "route_coverage", "result": "pass", "notes": "Flow reaches /flows/crm." },
+    { "name": "goal_coverage", "result": "pass", "notes": "Includes lead advance and creation." }
+  ],
+  "reasons": ["Existing flow already matches clarified scope."]
+}
+```
+
+Keep notes concrete and tie them to selectors/steps whenever possible.

package/bundled/skills/studioflow-investigate/references/cli-handoff-spec.md

@@ -1,6 +1,6 @@
 # CLI Handoff Spec
 
-Use this artifact to hand execution from `studioflow-investigate` to `studioflow-cli`.
+Use this artifact when `studioflow-investigate` routes execution with an existing flow and needs to hand to `studioflow-cli` without re-authoring.
 
 Path: