mimetic-cli 0.1.3 → 0.1.5

package/docs/architecture/oss-lab-poc.md

@@ -1,48 +1,51 @@
-# OSS Lab POC
+# Maintainer OSS Meta-Lab
 
 Date: 2026-06-01
 
-Status: implemented as an experimental meta-lab command plus a retained smoke
-harness.
+Status: implemented as an experimental repo-owned lab manifest plus
+compatibility aliases.
 
 ## Decision
 
-`mimetic lab oss` is the public-OSS meta-simulation loop.
+`mimetic/labs/oss.yaml` is this repo's authorized-repo meta-simulation
+dogfood loop. It is intentionally a lab manifest, not the canonical consumer
+shape. Consumer projects should author their own `mimetic/labs/*.yaml` files
+and run them with `mimetic watch <lab>` or `mimetic lab run <lab>`.
 
-The command should feel like `mimetic watch`: it opens the Observer and, for
-human output, keeps the shell attached. Its top-level Observer is an
-Observer-of-Observers: each lane represents a headed E2B desktop that will run
-Codex TUI against a different lightweight public GitHub repository. Inside each
-desktop, Codex should clone the repo, get it into local dev mode where feasible,
-install and initialize Mimetic, author plausible public-safe personas/scenarios,
-run nested Mimetic proof commands, attempt a Codex TUI pass, and leave that
-nested Observer visible in the E2B browser.
+The lab should feel like `mimetic watch`: it opens the Observer and, for human
+output, keeps the shell attached. Its top-level Observer is an
+Observer-of-Observers: each lane represents a headed E2B desktop assigned to a
+GitHub `owner/repo` slug. Inside each desktop, the bootstrap clones the repo,
+gets it into local dev mode where feasible, installs and initializes Mimetic,
+runs nested Mimetic proof commands, starts the target app when a runnable
+script is present, opens desktop/mobile app windows plus the nested Observer in
+the E2B browser, and starts a nonblocking Codex actor attempt.
 
 The previous clone/discard proof loop remains useful, but it is now explicitly
-named `mimetic lab oss-smoke`.
+named `mimetic/labs/oss-smoke.yaml`.
 
 ## Commands
 
 Main operator path:
 
 ```bash
-mimetic lab oss
-mimetic lab oss --repos developit/mitt,lukeed/clsx,sindresorhus/is-plain-obj,ai/nanoid
-mimetic lab oss --repo developit/mitt --repo lukeed/clsx --count 4
+mimetic watch oss
+mimetic lab run oss
+mimetic lab run oss --repos CorentinTh/it-tools,drawdb-io/drawdb,maciekt07/TodoApp,lissy93/dashy
+mimetic lab run oss --repo CorentinTh/it-tools --repo drawdb-io/drawdb --count 4
 ```
 
 Agent/CI contract path:
 
 ```bash
-mimetic lab oss --dry-run --json --no-open
+mimetic lab run oss --dry-run --json --no-open
 ```
 
 Disposable clone smoke path:
 
 ```bash
-mimetic lab oss-smoke
-mimetic lab oss-smoke --limit 1 --keep
-mimetic lab oss --smoke --limit 1 --keep
+mimetic lab run oss-smoke
+mimetic lab run oss-smoke --limit 1 --keep
 ```
 
 Local dogfood shortcuts:
@@ -55,17 +58,47 @@ pnpm mimetic:lab:oss:smoke
 
 ## Repo Selection
 
-The default public targets are intentionally small JavaScript packages:
+The default public targets are product-like, locally runnable apps/tools:
 
-- `developit/mitt`
-- `lukeed/clsx`
-- `sindresorhus/is-plain-obj`
-- `ai/nanoid`
+- `CorentinTh/it-tools`
+- `drawdb-io/drawdb`
+- `maciekt07/TodoApp`
+- `lissy93/dashy`
+
+Target selection should minimize distance from a real user-facing journey.
+Good defaults expose an app, CLI, or agent-facing tool that can be tried out of
+the box, preferably with a local dev script and no account setup. Libraries,
+frameworks, starters, and infrastructure packages belong only in scenarios that
+explicitly test developer experience. They are poor defaults for proving
+Mimetic as a user-simulation harness because they add another abstract setup
+layer before any product behavior is visible.
 
 `--repos` accepts a comma-separated list. Repeated `--repo` is also supported.
 If `--count` is larger than the repo list, assignments cycle through the repo
-pool. Inputs must be public GitHub `owner/repo` slugs. Arbitrary URLs, local
-paths, tokens, SSH remotes, and private GitHub references are rejected.
+pool. Inputs must be GitHub `owner/repo` slugs. Arbitrary URLs, local paths,
+tokens, and SSH remotes are rejected. Private repos are maintainer-only and
+require an authorized `GH_TOKEN` or `GITHUB_TOKEN` at runtime; no token value is
+written to committed source or public issue text.
+
+## Private Product Labs
+
+Private products can be used for local maintainer dogfood, but they must stay
+out of the public package surface. Do not commit private repo names as defaults,
+fixtures, screenshots, README examples, npm assets, skill examples, or issue
+draft text.
+
+The safe local shape is:
+
+```bash
+mimetic watch .mimetic/labs/private-app.yaml --env-file .mimetic/local/provider.env
+```
+
+with an authorized runtime GitHub token and default repo redaction enabled.
+Do not pass `--no-redact-repos` for a private target. Public receipts for
+those runs should say `authorized private app target` and point only to ignored
+local artifact paths, redacted statuses, and verifier results. Never publish
+private screenshots, logs, app URLs, source snippets, branch names, issue
+names, stream URLs, or operational details.
 
 ## Runtime Shape
 
@@ -85,19 +118,45 @@ The meta-lab writes ignored local Observer evidence:
 
 Each stream lane records:
 
-- assigned repo slug;
-- live E2B desktop stream URL when keys are present;
-- Codex TUI bootstrap prompt;
-- current live-readiness state;
+- assigned repo slug for public runs, or a redacted lane label for token-backed
+  maintainer/private runs;
+- whether a live E2B desktop stream exists; auth-bearing stream URLs are
+  runtime-only for the attached Observer server and are not persisted;
+- target app URL/status when a runnable script becomes HTTP-ready inside the
+  sandbox;
+- nested Observer presence and nested verification status;
+- headed desktop visual-window status and browser window count;
+- Codex actor status, optionally moved before deterministic setup with
+  `MIMETIC_OSS_META_ACTOR_FIRST=1` and required through
+  `MIMETIC_OSS_META_REQUIRE_ACTOR=1`;
+- setup-quality filesystem evidence: shallow tree, Mimetic setup checks,
+  package scripts, study-quality rating, and allowlisted previews for public
+  runs;
+- public-safe remote bootstrap log tail;
 - public-safe gaps and events.
 
 The current implementation launches live E2B desktop streams when
-`E2B_API_KEY` and `OPENAI_API_KEY` are present, embeds those streams into the
-top-level Observer, and marks missing key or launch failures in-lane. It also
-packs the local Mimetic package, uploads it into each sandbox, raises a visible
-bootstrap terminal, clones the assigned public repo, runs nested Mimetic setup
-and proof commands, attempts a Codex TUI pass, and opens the nested Observer in
-the sandbox browser.
+`E2B_API_KEY` and `OPENAI_API_KEY` are present, overlays those stream URLs only
+in the attached Observer server, and marks missing key or launch failures
+in-lane. It also packs the local Mimetic package, uploads it into each sandbox,
+raises a visible bootstrap terminal, clones the assigned repo, runs nested
+Mimetic setup and proof commands, starts the target app, opens desktop/mobile
+app windows, opens the nested Observer in the sandbox browser, arranges visible
+browser windows for screenshot proof, and starts the Codex actor attempt. By
+default the actor remains nonblocking and runs after deterministic readback; with
+`MIMETIC_OSS_META_ACTOR_FIRST=1`, the actor attempts setup/use before
+deterministic validation; with `MIMETIC_OSS_META_REQUIRE_ACTOR=1`, the bootstrap
+waits up to `MIMETIC_OSS_META_ACTOR_TIMEOUT_MS` for terminal actor readback and
+will not mark the lane passed unless the actor exits cleanly.
+
+When the remote bootstrap completes, the host persists a local
+`setup-quality/<stream>-setup-quality.json` artifact. The Observer Files tab can
+render it inline from the served Observer. Static `file://` observers keep the
+artifact link openable but do not hydrate it inline. Token-backed/private runs
+suppress raw file previews by default while preserving the setup checks and
+tree shape. They also preserve `studyQuality` structural signals so an actor
+that merely installs Mimetic receives a `ceremonial` rating instead of being
+treated as successful user-study leverage.
 
 The live desktop substrate is an optional peer dependency. Install it in the
 project that runs live labs:
@@ -106,13 +165,13 @@ project that runs live labs:
 npm i -D @e2b/desktop
 ```
 
-Remaining substrate work: poll remote bootstrap completion and nested Observer
-health back into the top-level bundle instead of leaving completion review to
-the live desktop stream.
+Remaining substrate work: upgrade the nested `--app-url` browser proof into
+provider-backed personas that actually drive multi-step target-app journeys,
+and live-prove actor-first setup/use, not only deterministic bootstrap readback.
 
 ## Smoke Harness Runtime
 
-`mimetic lab oss-smoke` shallow clones lightweight public GitHub repos into
+`mimetic lab run oss-smoke` shallow clones lightweight public GitHub repos into
 ignored runtime state, applies Mimetic setup inside each throwaway clone, runs
 the synthetic four-lane proof path, verifies the generated bundle, records
 git-status evidence, writes an ignored report, and removes cloned repos by
@@ -140,7 +199,13 @@ ignored `.mimetic/lab/oss/<run-id>/`.
 
 ## Safety Rules
 
-- Public GitHub `owner/repo` slugs only.
+- GitHub `owner/repo` slugs only.
+- Private repos require an authorized runtime token. Token-backed runs redact
+  repo labels in durable artifacts by default and must not appear in committed
+  fixtures, docs examples, public issue text, or published media.
+- pnpm dependency build scripts may be allowed only inside the disposable E2B
+  lab so target app surfaces can start. Never use this as a host install
+  default.
 - No credential prompts; smoke clone calls set `GIT_TERMINAL_PROMPT=0`.
 - No commits, pushes, branches, tags, GitHub API mutation, deploys, or issue
   filing.
@@ -151,11 +216,13 @@ ignored `.mimetic/lab/oss/<run-id>/`.
 ## What This Proves
 
 The meta-lab proves the operator control surface and artifact contract for
-watching multiple Codex/E2B OSS setup attempts at once. The live path now proves
-E2B desktop fanout, visible bootstrap terminals, local-package upload, disposable
-public-repo setup, nested Mimetic proof generation, and nested Observer opening.
-It does not yet prove remote completion polling or a general provider-backed
-target-app persona runtime.
+watching multiple Codex/E2B setup attempts at once. The live path now detects
+E2B desktop fanout, visible bootstrap terminals, local-package upload,
+disposable authorized-repo setup, target app HTTP readiness when a runnable
+script is present, headed browser-window layout, nested live `--app-url`
+desktop/mobile browser proof when the target app runs, nested Observer opening,
+and top-level lane completion from remote evidence. It does not yet prove a
+general provider-backed multi-step target-app persona runtime.
 
 The smoke harness proves first-run Mimetic package compatibility against
 arbitrary public JavaScript repositories:
@@ -168,3 +235,8 @@ arbitrary public JavaScript repositories:
 
 Neither path may claim private product behavior proof without live, redacted,
 public-safe evidence.
+
+Feedback candidates are derived from this evidence when a lane records concrete
+setup-quality gaps, ceremonial/absent study quality, or actor-reported Mimetic
+CLI blockers. `mimetic feedback` uses those candidates before falling back to
+generic dry-run follow-up drafts.

package/docs/architecture/project-layout.md

@@ -13,9 +13,9 @@ mimetic/   # committed source of simulation intent
 .mimetic/  # ignored runtime state, evidence, local overlays, and secrets
 ```
 
-Do not gitignore all Mimetic state. Personas, scenarios, policies, adapters,
-coverage maps, and review vocabulary are the harness. They must be versioned,
-reviewed, and reproducible from a clean clone.
+Do not gitignore all Mimetic state. Labs, personas, scenarios, policies,
+adapters, coverage maps, and review vocabulary are the harness. They must be
+versioned, reviewed, and reproducible from a clean clone.
 
 Do not commit run bundles, raw screenshots, browser traces, transcripts,
 draft issue bodies before verification, local auth, local overrides, or secrets.
@@ -34,6 +34,8 @@ mimetic/
   scenarios/
     first-run-smoke.yaml
     onboarding-regression.yaml
+  labs/
+    first-run.yaml
   policies/
     redaction.yaml
     network.yaml
@@ -49,6 +51,29 @@ mimetic/
     synthetic-login-state.json
 ```
 
+## Mimetic Format Stack
+
+Use formats based on who edits the file and how it is consumed:
+
+- `.yaml` for human-authored Mimetic source: personas, scenarios, policies,
+  labs, review vocabulary, and review milestones. Prefer `.yaml` over `.yml`
+  for Mimetic-owned source files.
+- `.ts` for executable project integration: `mimetic/config.ts`, adapters,
+  route catalogs, app launch plans, and logic that benefits from imports or
+  type checking.
+- `.json` for generated machine artifacts and synthetic fixtures: run bundles,
+  observer data, review JSON, latest/history pointers, and fixture records.
+- `.ndjson` for appendable event or transcript streams.
+- `.yml` is acceptable for ecosystem files that conventionally use it, such as
+  `.github/workflows/*.yml`; do not use `.yml` for Mimetic-owned authored
+  source.
+
+Do not convert personas or scenarios to JSON because parser implementation is
+easier. Keep authored simulation intent readable, then validate it through
+schemas and CLI checks. TOML is not part of the current Mimetic stack; add it
+only if a concrete scalar global-config need appears that is better served by
+TOML than YAML, TypeScript, or JSON.
+
 Committed files must be public-safe:
 
 - synthetic personas only;
@@ -79,7 +104,11 @@ visible in PR review.
   cache/
   tmp/
   logs/
+  labs/
   local/
+    labs/
+    personas/
+    policies/
   secrets/
 ```
 
@@ -99,11 +128,16 @@ When a team needs private local personas or credentials, use ignored overlays:
 ```text
 .mimetic/local/personas/*.yaml
 .mimetic/local/policies/*.yaml
+.mimetic/local/labs/*.yaml
+.mimetic/labs/*.yaml
 .mimetic/secrets/*
 ```
 
-The CLI should warn that local overlays cannot be used for reproducible CI or
-public issue drafts unless redacted into committed synthetic equivalents.
+Committed `mimetic/labs/*.yaml` should be useful to anyone with a clean clone.
+Ignored `.mimetic/labs/*.yaml` and `.mimetic/local/labs/*.yaml` are for
+machine-specific or private dogfood labs. The CLI should warn that local
+overlays cannot be used for reproducible CI or public issue drafts unless
+redacted into committed synthetic equivalents.
 
 ## CI And Reproducibility
 
@@ -113,6 +147,7 @@ CI should reproduce proof from committed inputs:
 - `mimetic-cli` version;
 - `mimetic/config.ts`;
 - scenario and persona catalog;
+- lab manifest;
 - policy files;
 - synthetic fixtures;
 - declared env var names.
@@ -129,4 +164,3 @@ weakened personas or dropped hard paths.
 A partially tracked dotdir is possible but worse UX. Dotdirs read as local,
 editors hide them, and negated gitignore rules are easy to break. A visible
 `mimetic/` source root plus ignored `.mimetic/` runtime root is clearer.
-

package/docs/contracts/feedback.md

@@ -2,7 +2,7 @@
 
 Date: 2026-06-01
 
-Status: v0 dry-run contract implemented for local issue draft generation.
+Status: v0 local issue draft generation with run-candidate support.
 
 ## Purpose
 
@@ -42,12 +42,17 @@ mimetic feedback issue-url --run latest --repo owner/repo
 
 ### `list`
 
-Reads feedback candidates from the run bundle. Does not mutate.
+Reads feedback candidates from the run bundle. Does not mutate. Candidates are
+generated by lab/adapters when actor evidence identifies a concrete
+setup-quality gap, ceremonial/absent study quality, target-app blocker, or
+Mimetic CLI blocker. The OSS
+meta-lab is one maintainer dogfood example, not the only candidate source.
 
 ### `draft`
 
-Builds structured feedback from review output and raw evidence pointers. Writes
-a draft under the run bundle, not GitHub.
+Builds structured feedback from the strongest run candidate first. If no
+candidate is present, falls back to the dry-run contract follow-up. Writes a
+draft under the run bundle, not GitHub.
 
 ### `verify`
 
@@ -75,20 +80,20 @@ mimetic_feedback:
   persona_id: "<persona-id-or-class>"
   actor: "<actor-runtime>"
   substrate: "<substrate>"
-  failure_owner: "product_ux|agent_runtime|executor_substrate|payment_provider|model_provider|harness|unknown"
+  failure_owner: "harness|target-app|actor|environment|unknown"
   summary: "<public-safe concrete summary>"
   expected: "<public-safe expected behavior>"
   actual: "<public-safe observed behavior>"
   source_bundle: "<path-or-url>"
   evidence:
     - path: "<relative artifact pointer>"
-      kind: "screenshot|terminal|browser|state|media|review|trace"
+      kind: "screenshot|state|review|trace|log|filesystem"
       note: "<public-safe note>"
   redaction:
     status: "passed|failed|not_applicable"
     notes: "<public-safe note>"
   idempotency_key: "<stable-key>"
-  proposed_next_state: "watch|needs_spec|spec_ready|agent_ready|blocked|wontfix"
+  proposed_next_state: "watch|adapter-hardening|target-app-setup|actor-auth|setup-quality-review|study-quality-review"
   acceptance_proof:
     - "<command or artifact that would close this>"
 ```
@@ -97,12 +102,10 @@ mimetic_feedback:
 
 | Owner | Meaning |
 | --- | --- |
-| `product_ux` | The product confused, blocked, or failed the user/persona. |
-| `agent_runtime` | The actor model/tool runtime failed independent of product UX. |
-| `executor_substrate` | E2B, local browser, shell, filesystem, or network substrate failed. |
-| `payment_provider` | Hosted payment/provider behavior blocked the run. |
-| `model_provider` | Model/media provider behavior blocked the run. |
 | `harness` | Mimetic or adapter logic produced invalid evidence or execution. |
+| `target-app` | The target app setup, dev server, or local surface blocked the run. |
+| `actor` | The coding-agent/persona actor failed to complete a requested setup or usage path. |
+| `environment` | E2B, local browser, shell, filesystem, network, or dependency substrate failed. |
 | `unknown` | Evidence is useful but ownership is not yet clear. |
 
 ## Issue Draft Gates

package/docs/contracts/policy.md

@@ -73,6 +73,7 @@ for credentials.
 | `no_network` | No external network calls. | contract docs, local unit tests |
 | `local_only` | Localhost and loopback only. | Observer, local fixtures |
 | `public_oss` | Public GitHub clone/fetch of owner/repo slugs only. | disposable OSS smoke |
+| `authorized_private` | Token-backed clone/fetch of repos the maintainer is already authorized to access, with repo labels redacted by default. | local maintainer dogfood only |
 | `provider_substrate` | Explicit provider substrate such as hosted desktop streams. | live OSS lab with keys |
 | `custom_allowlist` | Adapter-declared public hosts. | target-specific adapters |
 
@@ -85,7 +86,8 @@ mode: public_oss
 allowedHosts:
   - github.com
 allowedRepoSlugs:
-  - developit/mitt
+  - CorentinTh/it-tools
+  - drawdb-io/drawdb
 denied:
   - private remotes
   - SSH remotes
@@ -93,6 +95,11 @@ denied:
   - target repo mutation
 ```
 
+Private maintainer dogfood must use `authorized_private` plus a redaction gate.
+The repo name, screenshots, logs, source snippets, branch names, issue names,
+and stream URLs remain local-only. Public receipts may include only redacted
+labels, ignored artifact paths, and verifier status.
+
 ## Spend Policy
 
 Spend policy names when provider costs may be incurred.
@@ -114,7 +121,7 @@ providerClasses:
   - model
   - desktop_substrate
 operatorIntent:
-  command: mimetic lab oss --json --no-open
+  command: mimetic lab run oss --json --no-open
   explicit: true
 budget:
   limit: unspecified

package/docs/contracts/run-bundle.md

@@ -50,6 +50,13 @@ artifacts:
 review:
   schema: mimetic.review.v1
   verdict: "contract_proof_only|pass|fail|blocked|timed_out"
+feedbackCandidates:
+  - schema: mimetic.feedback-candidate.v1
+    id: "<stable candidate id>"
+    failure_owner: "harness|target-app|actor|environment|unknown"
+    evidence:
+      - path: "<relative run artifact path>"
+        kind: "review|state|log|trace|screenshot|filesystem"
 ```
 
 ## Relative Artifact Layout
@@ -68,6 +75,61 @@ For run id `example-2026-06-02t10-00-00-000z-proof`, the core layout is:
 Absolute paths, traversal segments, remotes, hosted logs, and private artifact
 URLs are not part of the core layout.
 
+## Filesystem Evidence
+
+Filesystem setup evidence is first-class when a lane asks an actor to install
+or configure Mimetic inside another project. It is not a repo dump.
+
+The durable artifact kind is `filesystem`. The current schema is:
+
+```yaml
+schema: mimetic.setup-quality.v1
+status: "passed|needs_review|blocked"
+redaction:
+  status: "passed"
+  rawPreviews: "included|suppressed"
+checks:
+  - id: "mimetic-config"
+    ok: true
+tree:
+  - path: "mimetic/config.ts"
+    type: "file"
+previews:
+  - path: "mimetic/config.ts"
+    language: "typescript"
+studyQuality:
+  schema: mimetic.study-quality.v1
+  rating: "none|ceremonial|useful|high_leverage"
+  checks:
+    - id: "coverage-customized"
+      ok: true
+  signals:
+    appUrlProofBlocked: false
+    appUrlProofMentioned: true
+    actorInsightCaptured: true
+    coverageCustomized: true
+    personaCustomized: true
+    scenarioCustomized: true
+packageScripts:
+  mimetic: "mimetic watch"
+mimetic:
+  configPresent: true
+  personaCount: 1
+  scenarioCount: 1
+  packageScriptPresent: true
+  gitignoreContainsRuntimeIgnore: true
+```
+
+For public OSS runs, previews may include allowlisted setup files such as
+`package.json`, `.gitignore`, `mimetic/config.ts`, and
+`mimetic/labs/*.yaml` / `mimetic/personas/*.yaml` /
+`mimetic/scenarios/*.yaml`. For token-backed or private maintainer runs, raw
+previews are suppressed by default. Generated state, `.git`, `.env*`, `.npmrc`,
+browser profiles, `node_modules`, `.mimetic/`, and arbitrary source files are
+not included. `studyQuality` is deliberately structural: it stores booleans,
+checks, and a rating so private runs can preserve the useful quality signal
+without committing raw private persona, scenario, or coverage text.
+
 ## Latest And History
 
 The latest pointer is a small local index:

package/docs/contracts/schemas.md

@@ -27,6 +27,7 @@ workflow without leaking private upstream truth into core.
 | --- | --- | --- |
 | Run bundle | `mimetic.run-bundle.v1` | `synthetic-run-bundle` |
 | Adapter | `mimetic.adapter.v1` | `synthetic-cli-adapter` |
+| Lab | `mimetic.lab.v1` | `first-run` |
 | Persona | `mimetic.persona.v1` | `synthetic-maintainer` |
 | Scenario | `mimetic.scenario.v1` | `first-run-smoke` |
 | Actor | `mimetic.actor.v1` | `synthetic-dry-run-actor` |
@@ -37,6 +38,26 @@ workflow without leaking private upstream truth into core.
 | Policy | `mimetic.policy.v1` | `public-safety-policy` |
 | Feedback | `mimetic.feedback.v1` | `public-safe-feedback` |
 
+## Lab Manifest
+
+Lab manifests name reusable runs. They are human-authored `.yaml` source under
+`mimetic/labs/*.yaml` for committed public-safe labs, or ignored
+`.mimetic/labs/*.yaml` / `.mimetic/local/labs/*.yaml` for private local
+dogfood.
+
+Synthetic fixture:
+
+```yaml
+schema: mimetic.lab.v1
+id: first-run
+kind: synthetic
+title: First-run synthetic Observer
+sims: 4
+defaults:
+  dryRun: true
+  open: true
+```
+
 ## Run Bundle
 
 Run bundles are the canonical evidence record. Observer data, review Markdown,