mimetic-cli 0.1.4 → 0.1.5

package/docs/product/open-source-install-experience.md

@@ -31,7 +31,7 @@ The npm package owns executable behavior:
 - binary: `mimetic`;
 - CLI framework: `commander`;
 - commands: `init`, `doctor`, `run`, `watch`, `review`, `verify`,
-  `feedback`;
+  `lab`, `feedback`;
 - schemas and validators;
 - synthetic starter templates;
 - observer static assets;
@@ -54,14 +54,33 @@ The skill should teach the user's coding agent how to:
 - run `mimetic init`;
 - inspect the target app's routes and dev command;
 - create synthetic personas and scenarios;
+- create public-safe `mimetic/labs/*.yaml` lab manifests;
+- keep private/local labs under ignored `.mimetic/labs/*.yaml` or
+  `.mimetic/local/labs/*.yaml`;
 - configure local app targets;
 - document E2B and OpenAI env var names without storing values;
+- use `--env-file <path>` for explicit local env hydration without persisting
+  values into artifacts;
 - run `doctor`, `watch`, `verify`, and `feedback issue`;
 - avoid PII, PHI, secrets, real customer data, and private artifacts.
 
 The skill should not hide critical behavior in chat memory. It should point to
 repo-owned `mimetic/` files and package-owned docs.
 
+## Project File Formats
+
+New projects should get a boring, legible format stack:
+
+- `.yaml` for human-authored Mimetic source such as personas, scenarios,
+  policies, labs, and review vocabulary;
+- `.ts` for executable integration such as `mimetic/config.ts` and adapters;
+- `.json` and `.ndjson` for generated run artifacts, Observer data, review
+  output, event streams, and synthetic fixtures.
+
+Use `.yml` only where an outside ecosystem convention already expects it, for
+example GitHub Actions workflows. Do not scaffold `.yml` for Mimetic source and
+do not use TOML unless a future scalar global-config case clearly needs it.
+
 ## First-Run Principles
 
 - No keys required for the first wow moment.
@@ -73,6 +92,35 @@ repo-owned `mimetic/` files and package-owned docs.
 - Safe dry-run should produce a valid synthetic run bundle and observer view.
 - The user should see what changed in git.
 
+## Lab Manifest Shape
+
+Labs are the public-safe way to name a reusable simulation run. A starter app
+gets a committed synthetic lab:
+
+```yaml
+schema: mimetic.lab.v1
+id: first-run
+kind: synthetic
+title: First-run synthetic Observer
+description: Public-safe starter lab that generates a synthetic run bundle and Observer without provider spend.
+sims: 4
+defaults:
+  dryRun: true
+  open: true
+```
+
+Resolution order:
+
+1. `mimetic/labs/<id>.yaml` for committed, reproducible labs.
+2. `.mimetic/labs/<id>.yaml` for ignored local labs.
+3. `.mimetic/local/labs/<id>.yaml` for ignored machine-specific overlays.
+4. explicit `.yaml` path, for example
+   `.mimetic/labs/local-dogfood.yaml`.
+
+Private repo targets, local env references, and maintainer dogfood variants
+belong in ignored lab manifests and should be invoked with explicit
+`--env-file`; do not make them package defaults.
+
 ## `mimetic init`
 
 `mimetic init` should:
@@ -94,10 +142,11 @@ Suggested scripts:
   "scripts": {
     "mimetic": "mimetic",
     "mimetic:doctor": "mimetic doctor",
-    "mimetic:run": "mimetic run --dry-run",
-    "mimetic:watch": "mimetic watch",
-    "mimetic:watch:ci": "mimetic watch --json --no-open",
-    "mimetic:verify": "mimetic verify"
+  "mimetic:run": "mimetic run --dry-run",
+  "mimetic:watch": "mimetic watch",
+  "mimetic:lab:list": "mimetic lab list",
+  "mimetic:watch:ci": "mimetic watch --json --no-open",
+  "mimetic:verify": "mimetic verify"
   }
 }
 ```
@@ -112,9 +161,13 @@ Suggested scripts:
 | `mimetic verify` | Validate bundle and public-safety gates | Fail closed on schema/evidence/redaction errors |
 | `mimetic review` | Build review packet from evidence | Summarize verdicts without inventing product proof |
 | `mimetic watch` | Run sims and watch the observer | Create a fresh four-lane bundle, render Observer, open it, and keep the shell attached |
+| `mimetic watch [lab]` | Run a named lab and watch it | Resolve committed or ignored `.yaml` lab manifests, then open/follow Observer |
 | `mimetic watch --json --no-open` | Agent/CI proof path | Create the same bundle and Observer artifacts without browser open or attached watch server |
-| `mimetic lab oss` | Watch public OSS meta-sims | Open the Observer-of-Observers with headed desktop lanes assigned by `--repos` |
-| `mimetic lab oss-smoke` | Try Mimetic on disposable public OSS clones | Shallow clone lightweight GitHub repos, run setup/proof/verify, report, and remove clones |
+| `mimetic lab list` | Discover available labs | List committed labs and ignored local labs with origin labels |
+| `mimetic lab inspect <lab>` | Read a lab manifest | Print lab id, kind, path, defaults, repos, and warnings without executing |
+| `mimetic lab run <lab>` | Run a lab manifest | Human or JSON execution path for synthetic, OSS meta, and smoke labs |
+| `mimetic lab run oss` | Maintainer dogfood example | Open the Observer-of-Observers with headed desktop lanes assigned by `--repos`, target app windows, nested Observers, runtime-only stream URLs, and redacted durable evidence for token-backed runs |
+| `mimetic lab run oss-smoke` | Maintainer smoke example | Shallow clone lightweight GitHub repos, run setup/proof/verify, report, and remove clones |
 | `mimetic feedback issue` | Produce public-safe issue draft | Print Markdown or prefilled issue URL, no GitHub API mutation |
 
 ## Live Capability Ladder
@@ -135,4 +188,6 @@ run.
 
 Live E2B desktop labs are an optional advanced path. Target projects that need
 them should install `@e2b/desktop` explicitly instead of receiving that
-substrate as part of the default Mimetic package install.
+substrate as part of the default Mimetic package install. When a GitHub token is
+present, repo labels are redacted in durable artifacts by default; live stream
+auth URLs are used only by the attached watch server and are not persisted.

package/docs/ramp/README.md

@@ -26,9 +26,11 @@ Mimetic is a persona simulation harness for apps, CLIs, and agent-facing product
 flows.
 
 - `mimetic/` is committed source: personas, scenarios, policy, adapters, and
-  project intent.
+  lab manifests.
 - `.mimetic/` is ignored runtime state: runs, Observer output, transcripts,
   reviews, temporary clones, and local evidence.
+- Mimetic source uses `.yaml` for human-authored simulation intent, `.ts` for
+  executable integration, and JSON/NDJSON for generated artifacts.
 - A run bundle is the source of truth.
 - The Observer is the projection that makes that truth reviewable.
 - Feedback commands turn verified evidence into public-safe issue drafts.
@@ -55,15 +57,22 @@ Implemented:
 - mission-control Observer over UI, CLI, TUI, and Codex UI stream contracts;
 - public-safe feedback issue drafts without GitHub API mutation;
 - skills.sh-compatible agent skill;
-- experimental public OSS lab and disposable OSS smoke harness.
+- first-class lab manifest resolution through `mimetic/labs/*.yaml` and
+  ignored `.mimetic/labs/*.yaml` overlays;
+- experimental maintainer OSS meta-lab and disposable OSS smoke harness;
+- OSS dogfood setup-quality filesystem artifacts rendered from the Observer Files
+  tab with private-run previews suppressed by default.
 
 Still not good enough:
 
-- live browser/user-journey proof is not yet first-class;
+- live `--app-url` browser proof exists for desktop/mobile render evidence, but
+  autonomous multi-step user-journey proof is not first-class yet;
 - live PTY and Codex UI lanes need stronger completion health;
-- OSS lab lanes need automatic nested Observer health readback;
-- the package needs fresh-agent install proof on real disposable public apps;
-- Observer evidence needs real screenshots/traces once browser adapters land.
+- OSS lab lanes can report nested Observer health, target app readiness, actor
+  evidence, and setup-quality filesystem checks when a target app starts, but
+  need repeated fresh-agent trials across more disposable public apps;
+- Observer evidence has real screenshots/traces for browser app proof; broader
+  adapter-driven persona navigation remains the next gap.
 
 ## First Commands
 
@@ -75,6 +84,7 @@ pnpm install --frozen-lockfile
 pnpm release:check
 pnpm mimetic -- watch --json --no-open
 pnpm mimetic -- runs --json
+pnpm mimetic -- lab list
 ```
 
 For local product feel:
@@ -86,8 +96,16 @@ pnpm mimetic -- watch
 For public OSS dogfood without credentials:
 
 ```bash
-pnpm mimetic -- lab oss --dry-run --json --no-open
-pnpm mimetic -- lab oss-smoke --limit 1 --json
+pnpm mimetic -- lab run oss --dry-run --json --no-open
+pnpm mimetic -- lab run oss-smoke --limit 1 --json
+```
+
+For private/local dogfood, author an ignored lab manifest under
+`.mimetic/labs/` or `.mimetic/local/labs/`, then invoke it explicitly with an
+ignored env file:
+
+```bash
+pnpm mimetic -- watch .mimetic/labs/local-dogfood.yaml --env-file .mimetic/local/provider.env
 ```
 
 ## How To Pick Work

package/docs/roadmap/world-class-open-source-v0.md

@@ -226,21 +226,43 @@ keeps the shell attached. The CI-safe form is `mimetic watch --json --no-open`.
 `--sims <n>` remains the explicit scale control, and `--run <id>` watches
 existing evidence.
 
-## Stage 6.9: OSS Meta-Lab
+## Stage 6.8: Lab Manifests
 
-Status: implemented as an experimental live Observer-of-Observers bootstrap
-with a retained disposable smoke harness.
+Status: implemented as the generic source shape for reusable runs.
 
-`mimetic lab oss` opens the top-level Observer for public OSS meta-sims. Each
-lane is assigned a public GitHub `owner/repo` slug from `--repos` or repeated
-`--repo` values and carries the headed E2B desktop + Codex TUI bootstrap prompt
-for setting up Mimetic inside that repo and keeping the nested Observer visible.
+Mimetic now resolves `.yaml` lab manifests from committed `mimetic/labs/`,
+ignored `.mimetic/labs/`, ignored `.mimetic/local/labs/`, or an explicit
+`.yaml` path. The human path is `mimetic watch <lab>`; the agent/CI path is
+`mimetic lab run <lab> --json --no-open`; discovery is `mimetic lab list` and
+`mimetic lab inspect <lab>`.
+
+Private or maintainer-only dogfood belongs in ignored lab manifests plus
+explicit `--env-file`; the public package should not hardcode private target
+names or require broad inherited job env.
+
+## Stage 6.9: Maintainer OSS Meta-Lab
+
+Status: implemented as repo-owned `mimetic/labs/oss.yaml` plus compatibility
+aliases, with a retained disposable smoke harness.
+
+`mimetic watch oss` opens the top-level Observer for authorized-repo meta-sims.
+Each lane is assigned a GitHub `owner/repo` slug from `--repos` or repeated
+`--repo` values and carries a headed E2B desktop for setting up Mimetic inside
+that repo, starting the target app where feasible, and keeping the nested
+Observer visible.
+Default public targets should be apps, CLIs, or agent-facing tools with
+observable user surfaces. Frameworks, starters, and utility libraries are
+acceptable only when the explicit scenario is developer-experience testing.
 When live keys are present, Mimetic launches E2B desktops, uploads the locally
 packed Mimetic package, starts visible bootstrap terminals, clones each assigned
-repo inside the desktop, runs nested Mimetic setup/proof commands, attempts a
-Codex TUI pass, and opens the nested Observer in the sandbox browser.
-
-`mimetic lab oss-smoke` keeps the earlier clone/discard proof loop: shallow
+repo inside the desktop, runs nested Mimetic setup/proof commands, opens
+desktop/mobile app windows plus the nested Observer in the sandbox browser, and
+starts a nonblocking Codex actor attempt. Attached watch mode overlays live E2B
+stream URLs only in memory; durable run artifacts keep screenshots/status, not
+auth-bearing URLs. Private repos are maintainer-only, require an authorized
+runtime GitHub token, and redact repo labels in durable artifacts by default.
+
+`mimetic lab run oss-smoke` keeps the earlier clone/discard proof loop: shallow
 clone lightweight public GitHub repositories into ignored `.mimetic/tmp`, apply
 Mimetic setup in disposable clones, run the four-lane synthetic Observer proof,
 verify it, record git-status evidence, write an ignored
@@ -249,15 +271,14 @@ verify it, record git-status evidence, write an ignored
 Proof:
 
 ```bash
-pnpm mimetic -- lab oss --detach --open --repos developit/mitt,lukeed/clsx
-pnpm mimetic -- lab oss --dry-run --json --no-open --repos developit/mitt,lukeed/clsx
-pnpm mimetic -- lab oss-smoke --limit 1 --json
+pnpm mimetic -- watch oss --detach --open --repos CorentinTh/it-tools,drawdb-io/drawdb
+pnpm mimetic -- lab run oss --dry-run --json --no-open --repos CorentinTh/it-tools,drawdb-io/drawdb
+pnpm mimetic -- lab run oss-smoke --limit 1 --json
 ```
 
-Next substrate work: poll the remote bootstrap logs and nested Observer health
-back into the top-level bundle so the Observer can graduate each lane from
-`running` to explicit `passed` or `failed` without relying on a human watching
-the E2B stream.
+Next substrate work: upgrade nested app-url render proof into provider-backed
+browser personas that drive the target app and add richer process/filesystem
+telemetry for Codex actor health.
 
 ## Stage 7: Local Browser And First Real Adapter
 
@@ -276,11 +297,11 @@ Proof:
 
 ## Non-Goals For V0
 
-- live E2B;
+- live E2B as required first-run behavior;
 - OpenAI computer-use actor;
 - live GitHub mutation;
 - hosted queues/databases/webhooks;
-- provider spend;
+- provider spend as required first-run behavior;
 - production deploys;
 - real user/persona data;
 - private upstream artifacts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mimetic-cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [
@@ -33,7 +33,7 @@
     "docs/architecture",
     "docs/assets",
     "docs/contracts",
-    "docs/goals",
+    "docs/goals/current.md",
     "docs/principles",
     "docs/product",
     "docs/ramp",
@@ -66,9 +66,10 @@
     "mimetic:dogfood": "pnpm mimetic -- watch",
     "mimetic:verify": "pnpm mimetic -- verify",
     "mimetic:feedback": "pnpm mimetic -- feedback issue --repo danielgwilson/mimetic-cli",
-    "mimetic:lab:oss": "pnpm mimetic -- lab oss",
-    "mimetic:lab:oss:ci": "pnpm mimetic -- lab oss --dry-run --json --no-open",
-    "mimetic:lab:oss:smoke": "pnpm mimetic -- lab oss-smoke"
+    "mimetic:lab:list": "pnpm mimetic -- lab list",
+    "mimetic:lab:oss": "pnpm mimetic -- lab run oss",
+    "mimetic:lab:oss:ci": "pnpm mimetic -- lab run oss --dry-run --json --no-open",
+    "mimetic:lab:oss:smoke": "pnpm mimetic -- lab run oss-smoke"
   },
   "repository": {
     "type": "git",
@@ -79,7 +80,8 @@
   },
   "homepage": "https://github.com/danielgwilson/mimetic-cli#readme",
   "dependencies": {
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "yaml": "^2.9.0"
   },
   "peerDependencies": {
     "@e2b/desktop": "^2.2.3"

package/skills/mimetic-cli/SKILL.md

@@ -15,9 +15,11 @@ tokens, raw private transcripts, private screenshots, raw customer data, raw
 patient data, or private upstream artifacts.
 
 Do not edit `.env` or secret files. Do not paste credential values. Use env var
-names only, usually `OPENAI_API_KEY` and `E2B_API_KEY`. Stop before live
-provider spend, hosted execution, deploys, public tunnels, or GitHub mutation
-unless the user explicitly approves that exact action.
+names only, usually `OPENAI_API_KEY` and `E2B_API_KEY`. For live local runs,
+prefer an explicit ignored env file passed with `--env-file <path>`; do not
+assume broad inherited job env is safe. Stop before live provider spend,
+hosted execution, deploys, public tunnels, or GitHub mutation unless the user
+explicitly approves that exact action.
 
 ## Setup Workflow
 
@@ -29,6 +31,12 @@ unless the user explicitly approves that exact action.
    npm i -D mimetic-cli
    ```
 
+   The package is `mimetic-cli`; the installed binary is `mimetic`. After
+   installation, `npx mimetic ...` resolves the local project binary. For a
+   one-shot command before installation, use
+   `npx --package mimetic-cli mimetic ...` so npm does not resolve an unrelated
+   package named `mimetic`.
+
 3. Preview setup:
 
    ```bash
@@ -44,9 +52,28 @@ unless the user explicitly approves that exact action.
 5. Confirm the layout:
    - commit `mimetic/` source files;
    - ignore `.mimetic/` runtime artifacts;
+   - keep committed labs under `mimetic/labs/*.yaml`;
+   - keep private/local labs under ignored `.mimetic/labs/*.yaml` or
+     `.mimetic/local/labs/*.yaml`;
    - keep `.env.example` commit-safe and value-free;
    - never commit generated run bundles.
 
+## Format Stack
+
+When creating or editing Mimetic files:
+
+- use `.yaml` for human-authored Mimetic source: personas, scenarios,
+  policies, labs, review vocabulary, and milestones;
+- use `.ts` for executable integration: `mimetic/config.ts`, adapters, route
+  catalogs, and app launch logic;
+- use `.json` or `.ndjson` for generated machine artifacts, Observer data, run
+  bundles, event streams, and synthetic fixtures.
+
+Do not create `.yml` files under `mimetic/`; `.yml` is for outside ecosystem
+conventions such as GitHub Actions workflows. Do not introduce TOML unless the
+target project has a concrete scalar global-config need that YAML, TypeScript,
+or JSON does not serve.
+
 ## Authoring Personas And Scenarios
 
 Create or edit only synthetic files under `mimetic/`.
@@ -60,9 +87,40 @@ Scenarios should define the target app surface, start URL, task intent,
 success signals, and failure signals. Keep app-specific truth in the target
 repo's `mimetic/` files, not in the package or this skill.
 
+## Authoring Labs
+
+Create reusable simulation runs as `.yaml` lab manifests:
+
+```yaml
+schema: mimetic.lab.v1
+id: first-run
+kind: synthetic
+title: First-run synthetic Observer
+sims: 4
+defaults:
+  dryRun: true
+  open: true
+```
+
+Use committed `mimetic/labs/*.yaml` for public-safe, reproducible labs. Use
+ignored `.mimetic/labs/*.yaml` or `.mimetic/local/labs/*.yaml` for private repo
+targets, local-only dogfood, or machine-specific settings. Never commit private
+repo names, stream URLs, credential values, screenshots, logs, source snippets,
+or operational details.
+
+Useful commands:
+
+```bash
+npx mimetic lab list
+npx mimetic lab inspect first-run
+npx mimetic watch first-run
+npx mimetic lab run first-run --json --no-open
+```
+
 ## First Proof Run
 
-Run the no-credentials path first:
+Run the no-credentials path first. This proves Mimetic artifact plumbing, not
+target app behavior:
 
 ```bash
 npx mimetic doctor
@@ -75,12 +133,27 @@ For CI or non-interactive proof:
 
 ```bash
 npx mimetic watch --json --no-open
+npx mimetic lab run first-run --json --no-open
 ```
 
 The feedback command prints a public-safe Markdown draft. It must not call the
 GitHub API, require a token, update Projects, use provider credits, or claim
 product behavior proof from a dry run.
 
+When the target app can run locally, prove real browser behavior with
+`run --app-url` after starting the app on loopback:
+
+```bash
+# in another terminal, start the target app on 127.0.0.1 or localhost
+npx mimetic run --app-url http://127.0.0.1:<port> --sims 2 --json
+npx mimetic verify --run latest --json
+npx mimetic watch --run latest --detach --no-open --json
+```
+
+Do not use `mimetic watch --sims ...` as a substitute for app-url proof.
+`watch` renders or follows Observer evidence; `run --app-url` is the command
+that captures live desktop/mobile browser evidence against a running app.
+
 ## Optional Live E2B Lab
 
 Live headed E2B desktop lanes are optional. Add the substrate dependency only
@@ -98,6 +171,18 @@ OPENAI_API_KEY
 ```
 
 Do not paste values into files, prompts, run bundles, issue drafts, or logs.
+Load local values only at invocation time:
+
+```bash
+npx mimetic watch .mimetic/labs/local-live.yaml --env-file .mimetic/local/provider.env
+```
+
+When choosing dogfood targets, prefer apps, CLIs, or agent-facing tools with a
+real observable user surface and local run path. Do not use libraries,
+frameworks, starters, or infrastructure packages as default targets unless the
+declared scenario is developer-experience testing. Private repos are allowed
+only as explicit maintainer-authorized runs with repo redaction left on; never
+publish their names, screenshots, logs, source snippets, or operational details.
 
 ## Reporting Back
 

package/skills/mimetic-cli/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Mimetic CLI"
   short_description: "Set up public-safe persona simulation"
-  default_prompt: "Use $mimetic-cli to install Mimetic in this repo, scaffold synthetic personas and scenarios, run the safe Observer proof, and report the public-safe artifacts."
+  default_prompt: "Use $mimetic-cli to install Mimetic in this repo, scaffold synthetic personas and scenarios, run the safe Observer proof, and report the public-safe artifacts. If the app can run locally, start it on loopback and use `mimetic run --app-url http://127.0.0.1:<port> --sims 2` before rendering Observer with `mimetic watch --run latest`; do not treat `watch --sims` as app behavior proof."
 
 policy:
   allow_implicit_invocation: true