ghostlab 0.2.0__tar.gz → 0.2.1__tar.gz

{ghostlab-0.2.0 → ghostlab-0.2.1}/.gitignore

@@ -227,7 +227,8 @@ ghostlab_workspace/
 .ghostlab/
 ghostlab.sqlite3
 
-# ghostlab jobs — track job.yaml + test-plan.*, ignore per-job run artifacts + db
-jobs/*/workspace/
-jobs/*/runs/
-jobs/*/ghostlab.sqlite3*
+# ghostlab jobs — runtime output (created by `ghostlab create`), not tracked
+jobs/
+
+# macOS
+.DS_Store

{ghostlab-0.2.0 → ghostlab-0.2.1}/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to MCP Rehearsal / Ghostlab
+# Contributing to Ghostlab
 
 Thanks for helping improve Ghostlab! This guide is written to be friendly to both
 humans and coding agents. For a machine-readable map of the project, see
@@ -50,7 +50,7 @@ Optional extras:
 
 ## Where to start
 
-Browse the [open issues](https://github.com/sajjadGG/Rehearsal/issues) — they are
+Browse the [open issues](https://github.com/sajjadGG/Ghostlab/issues) — they are
 labeled by pipeline stage (`pipeline:understand`, `pipeline:run`,
 `pipeline:evaluate`, …). Good first contributions: a new target/scenario/runner
 preset, an additional lint or assertion, or a per-widget MCP Apps assertion.

ghostlab-0.2.0/README.md → ghostlab-0.2.1/PKG-INFO

@@ -1,12 +1,52 @@
-# MCP Rehearsal / Ghostlab
+Metadata-Version: 2.4
+Name: ghostlab
+Version: 0.2.1
+Summary: Local end-to-end testing lab for any MCP server: coding agents role-play real users, drive your tools over multiple turns, score runs, and render/interact with MCP Apps ui:// widgets.
+Project-URL: Documentation, https://sajjadgg.github.io/Ghostlab/
+Project-URL: Homepage, https://github.com/sajjadGG/Ghostlab
+Project-URL: Repository, https://github.com/sajjadGG/Ghostlab
+Project-URL: Issues, https://github.com/sajjadGG/Ghostlab/issues
+Project-URL: Changelog, https://github.com/sajjadGG/Ghostlab/releases
+Author: Sajjad Gholamzadeh
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai-agents,claude,cli,codex,end-to-end-testing,evaluation,llm,llm-evaluation,mcp,mcp-apps,model-context-protocol,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Provides-Extra: apps
+Requires-Dist: playwright>=1.40; extra == 'apps'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mkdocs>=1.6; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: ui
+Requires-Dist: streamlit>=1.30; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# Ghostlab
 
 > A local, end-to-end **testing lab for any MCP server** — coding agents role-play
 > real users, drive your tools over multiple turns, and the harness captures
 > traces, scores outcomes, and even **renders and clicks through MCP Apps UI
 > widgets**.
 
-[![CI](https://github.com/sajjadGG/Rehearsal/actions/workflows/ci.yml/badge.svg)](https://github.com/sajjadGG/Rehearsal/actions)
-[![Docs](https://img.shields.io/badge/docs-wiki-blue)](https://sajjadgg.github.io/Rehearsal/)
+[![CI](https://github.com/sajjadGG/Ghostlab/actions/workflows/ci.yml/badge.svg)](https://github.com/sajjadGG/Ghostlab/actions)
+[![Docs](https://img.shields.io/badge/docs-wiki-blue)](https://sajjadgg.github.io/Ghostlab/)
 [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![llms.txt](https://img.shields.io/badge/llms.txt-✓-purple)](llms.txt)
@@ -18,12 +58,20 @@ user. Protocol-level checks (schema errors, a tool call that 500s) are useful
 sanity checks, but they aren't the real test — the real test is whether an
 agent can actually get a task done through your MCP, end to end.
 
-📖 **Docs wiki:** https://sajjadgg.github.io/Rehearsal/ · 🤖 **For agents:** [`llms.txt`](llms.txt) · 🛠 **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md)
+📖 **Docs wiki:** https://sajjadgg.github.io/Ghostlab/ · 🤖 **For agents:** [`llms.txt`](llms.txt) · 🛠 **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+> **Naming:** the project and repo are **Ghostlab** (formerly *Rehearsal*). The CLI
+> is `ghostlab`, with `rehearsal` kept as an alias, and the installed Python
+> package is `rehearsal` — all the same project.
+
+<p align="center">
+<img src="static/ghostlablogo.png" width="400" alt="Logo" align="center">
+</p>
 
 ## Quickstart
 
 ```bash
-python3.13 -m venv .venv
+python3 -m venv .venv                # Python 3.10+
 .venv/bin/pip install -e .            # add '.[ui]' for the web UI, '.[apps]' for widget rendering
 
 ghostlab create
@@ -74,6 +122,30 @@ generation/test defaults, gates — all editable), `test-plan.yaml`, `workspace/
 | **Test** | Multi-host execution results (`results.json`/`results.md`), a standalone HTML dashboard, and — for conversational cases — full dual-agent transcripts with structured tool-call capture |
 | **Review** | A readiness report: pass/fail gate verdict, failure clusters, and prioritized repairs |
 
+## See it in action
+
+**Watch a real coding-agent drive your MCP, turn by turn** — every tool call is
+captured with its pass/fail status. Below is the live trace of a Hugging Face
+MCP run, including two `hf_hub_query` calls that failed against the server:
+
+<p align="center">
+<img src="static/cli-run-trace.png" width="900" alt="CLI run trace showing per-tool-call status">
+</p>
+
+**Get a standalone HTML dashboard** — pass rate, per-case verdicts, and
+suite/host tags at a glance:
+
+<p align="center">
+<img src="static/results-dashboard.png" width="760" alt="HTML results dashboard with pass-rate KPIs and per-case list">
+</p>
+
+**Drill into any case** — the goal and persona, the judge's verdict with its
+reasoning, and the full dual-agent transcript with inline tool calls:
+
+<p align="center">
+<img src="static/case-report-transcript.png" width="760" alt="Per-case report with judge verdict and conversation transcript">
+</p>
+
 ## Goal
 
 Build a repeatable, sandboxed tester that can:
@@ -88,7 +160,7 @@ This lets you test with your existing Codex/Claude usage path, instead of wiring
 
 ## Scope
 
-Rehearsal is intentionally **app-agnostic**:
+Ghostlab is intentionally **app-agnostic**:
 
 - Works with any MCP server reachable by stdio/SSE/streamable HTTP.
 - Supports local or remote MCP endpoints.
@@ -101,6 +173,23 @@ No Cortex-specific assumptions are required in the core harness.
 Everything below is the individual-command reference and advanced usage —
 useful once you're past the first `ghostlab create` run, or scripting CI.
 
+### Spec vs job
+
+There are two ways to hold an evaluation's config; **for almost everyone the
+answer is a job.**
+
+- **Job** (recommended) — a self-contained `jobs/<name>/` folder created by
+  `ghostlab create`. Every command takes `--job <name>` (or auto-detects
+  `job.yaml` in the current dir). This is the mainstream path the whole
+  Quickstart uses.
+- **Spec** (advanced) — a single standalone `ghostlab.yaml` produced by
+  `ghostlab init`, addressed with `--spec <file>`. Useful for scripting or
+  keeping config outside the `jobs/` layout. Unless you specifically need that,
+  prefer a job.
+
+The commands overlap (`discover`/`plan`/`test`/`review` accept either `--job` or
+`--spec`); pick one model per evaluation and stay with it.
+
 ### Job folder layout
 
 ```text
@@ -139,7 +228,7 @@ Each test run points to a target definition:
 The package installs two equivalent console scripts: `ghostlab` and `rehearsal`.
 
 - `ghostlab create` — the end-to-end wizard described above.
-- `ghostlab init` — create a `job.yaml`/`ghostlab.yaml` from an existing target JSON, without the wizard prompts.
+- `ghostlab init` — advanced: scaffold a standalone `ghostlab.yaml` **spec** from a target JSON (see [spec vs job](#spec-vs-job) — most users want `ghostlab create`).
 - `ghostlab discover` — inspect the job's target, lint its contract, refresh capabilities.
 - `ghostlab plan` — generate (or curate) the coverage-driven test plan.
 - `ghostlab test` — execute the test plan across the job's host adapters.
@@ -150,6 +239,8 @@ The package installs two equivalent console scripts: `ghostlab` and `rehearsal`.
 - `ghostlab review-dataset` / `run-dataset` — curate and run a standalone dataset.
 - `ghostlab run` — run one dual-agent E2E scenario directly.
 - `ghostlab evaluate` — score a run into a pass/fail verdict (codex judge).
+- `ghostlab critique` — rate a run's tool ergonomics from the agent's perspective (codex).
+- `ghostlab scorecard` — roll run verdicts and critiques into a summary scorecard.
 - `ghostlab compare` — diff two dataset runs for regressions.
 - `ghostlab apps-probe` / `apps-render` — probe/render MCP Apps `ui://` widgets.
 - `ghostlab doctor` — check codex and validate runner presets.
@@ -178,7 +269,7 @@ Point it at a target and it introspects the server without any coding-agent
 credits or manual `curl`:
 
 ```bash
-ghostlab inspect --target targets/cortex-local.json
+ghostlab inspect --target examples/target.json
 ```
 
 This connects over the configured transport (stdio / streamable-HTTP / SSE),
@@ -239,7 +330,7 @@ confused, non-native, ...), and a domain `context` map (native_language,
 target_exam, level, ...). Pass one to a run with `--persona`:
 
 ```bash
-ghostlab run ... --persona personas/ielts-power-user.json
+ghostlab run ... --persona persona.json
 ```
 
 ### Build a dataset: `generate-dataset`
@@ -289,7 +380,7 @@ ghostlab review-dataset --dataset datasets/cortex \
 ```bash
 ghostlab run-dataset \
   --dataset datasets/cortex \
-  --target targets/cortex-local.json \
+  --target target.json \
   --aut-runner runners/codex-cortex-aut.json \
   --user-runner runners/codex-user-emulator.json \
   --limit 2
@@ -339,7 +430,7 @@ points to a `ui://…` HTML widget a compatible host is expected to render.
 `ui://` resource, and reports render-readiness and CSP diagnostics:
 
 ```bash
-ghostlab apps-probe --target targets/cortex-local.json
+ghostlab apps-probe --target target.json
 ```
 
 `apps-render` actually renders a `ui://` widget in headless Chrome, proving a
@@ -349,7 +440,7 @@ real tool input/result, and can drive a sequence of UI intents:
 
 ```bash
 pip install 'ghostlab[apps]' && playwright install chrome    # one-time
-ghostlab apps-render --target targets/cortex-local.json \
+ghostlab apps-render --target target.json \
   --tool views_generate_sentence_scramble \
   --arguments '{"target_sentence":"The cat sat on the mat","shuffled_elements":["mat","The","on","sat","cat","the"]}' \
   --intent '{"type":"reorder","value":["The","cat","sat","on","the","mat"]}' \
@@ -369,7 +460,7 @@ one codex session alive: turn 1 records the `thread_id`, and later turns run
 repeated cold-start noise.
 
 ```bash
-ghostlab run --target targets/cortex-local.json --scenario <scenario.json> \
+ghostlab run --target target.json --scenario <scenario.json> \
   --aut-runner runners/codex-cortex-local-session.json --user-runner <user.json>
 ```
 

ghostlab-0.2.0/PKG-INFO → ghostlab-0.2.1/README.md

@@ -1,52 +1,12 @@
-Metadata-Version: 2.4
-Name: ghostlab
-Version: 0.2.0
-Summary: Local end-to-end testing lab for any MCP server: coding agents role-play real users, drive your tools over multiple turns, score runs, and render/interact with MCP Apps ui:// widgets.
-Project-URL: Documentation, https://sajjadgg.github.io/Rehearsal/
-Project-URL: Homepage, https://github.com/sajjadGG/Rehearsal
-Project-URL: Repository, https://github.com/sajjadGG/Rehearsal
-Project-URL: Issues, https://github.com/sajjadGG/Rehearsal/issues
-Project-URL: Changelog, https://github.com/sajjadGG/Rehearsal/releases
-Author: Sajjad Gholamzadeh
-License: MIT
-License-File: LICENSE
-Keywords: agents,ai-agents,claude,cli,codex,end-to-end-testing,evaluation,llm,llm-evaluation,mcp,mcp-apps,model-context-protocol,testing
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development :: Quality Assurance
-Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.10
-Provides-Extra: apps
-Requires-Dist: playwright>=1.40; extra == 'apps'
-Provides-Extra: dev
-Requires-Dist: build>=1.2; extra == 'dev'
-Requires-Dist: mkdocs>=1.6; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: twine>=5.0; extra == 'dev'
-Provides-Extra: docs
-Requires-Dist: mkdocs>=1.6; extra == 'docs'
-Provides-Extra: ui
-Requires-Dist: streamlit>=1.30; extra == 'ui'
-Description-Content-Type: text/markdown
-
-# MCP Rehearsal / Ghostlab
+# Ghostlab
 
 > A local, end-to-end **testing lab for any MCP server** — coding agents role-play
 > real users, drive your tools over multiple turns, and the harness captures
 > traces, scores outcomes, and even **renders and clicks through MCP Apps UI
 > widgets**.
 
-[![CI](https://github.com/sajjadGG/Rehearsal/actions/workflows/ci.yml/badge.svg)](https://github.com/sajjadGG/Rehearsal/actions)
-[![Docs](https://img.shields.io/badge/docs-wiki-blue)](https://sajjadgg.github.io/Rehearsal/)
+[![CI](https://github.com/sajjadGG/Ghostlab/actions/workflows/ci.yml/badge.svg)](https://github.com/sajjadGG/Ghostlab/actions)
+[![Docs](https://img.shields.io/badge/docs-wiki-blue)](https://sajjadgg.github.io/Ghostlab/)
 [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![llms.txt](https://img.shields.io/badge/llms.txt-✓-purple)](llms.txt)
@@ -58,12 +18,20 @@ user. Protocol-level checks (schema errors, a tool call that 500s) are useful
 sanity checks, but they aren't the real test — the real test is whether an
 agent can actually get a task done through your MCP, end to end.
 
-📖 **Docs wiki:** https://sajjadgg.github.io/Rehearsal/ · 🤖 **For agents:** [`llms.txt`](llms.txt) · 🛠 **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md)
+📖 **Docs wiki:** https://sajjadgg.github.io/Ghostlab/ · 🤖 **For agents:** [`llms.txt`](llms.txt) · 🛠 **Contributing:** [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+> **Naming:** the project and repo are **Ghostlab** (formerly *Rehearsal*). The CLI
+> is `ghostlab`, with `rehearsal` kept as an alias, and the installed Python
+> package is `rehearsal` — all the same project.
+
+<p align="center">
+<img src="static/ghostlablogo.png" width="400" alt="Logo" align="center">
+</p>
 
 ## Quickstart
 
 ```bash
-python3.13 -m venv .venv
+python3 -m venv .venv                # Python 3.10+
 .venv/bin/pip install -e .            # add '.[ui]' for the web UI, '.[apps]' for widget rendering
 
 ghostlab create
@@ -114,6 +82,30 @@ generation/test defaults, gates — all editable), `test-plan.yaml`, `workspace/
 | **Test** | Multi-host execution results (`results.json`/`results.md`), a standalone HTML dashboard, and — for conversational cases — full dual-agent transcripts with structured tool-call capture |
 | **Review** | A readiness report: pass/fail gate verdict, failure clusters, and prioritized repairs |
 
+## See it in action
+
+**Watch a real coding-agent drive your MCP, turn by turn** — every tool call is
+captured with its pass/fail status. Below is the live trace of a Hugging Face
+MCP run, including two `hf_hub_query` calls that failed against the server:
+
+<p align="center">
+<img src="static/cli-run-trace.png" width="900" alt="CLI run trace showing per-tool-call status">
+</p>
+
+**Get a standalone HTML dashboard** — pass rate, per-case verdicts, and
+suite/host tags at a glance:
+
+<p align="center">
+<img src="static/results-dashboard.png" width="760" alt="HTML results dashboard with pass-rate KPIs and per-case list">
+</p>
+
+**Drill into any case** — the goal and persona, the judge's verdict with its
+reasoning, and the full dual-agent transcript with inline tool calls:
+
+<p align="center">
+<img src="static/case-report-transcript.png" width="760" alt="Per-case report with judge verdict and conversation transcript">
+</p>
+
 ## Goal
 
 Build a repeatable, sandboxed tester that can:
@@ -128,7 +120,7 @@ This lets you test with your existing Codex/Claude usage path, instead of wiring
 
 ## Scope
 
-Rehearsal is intentionally **app-agnostic**:
+Ghostlab is intentionally **app-agnostic**:
 
 - Works with any MCP server reachable by stdio/SSE/streamable HTTP.
 - Supports local or remote MCP endpoints.
@@ -141,6 +133,23 @@ No Cortex-specific assumptions are required in the core harness.
 Everything below is the individual-command reference and advanced usage —
 useful once you're past the first `ghostlab create` run, or scripting CI.
 
+### Spec vs job
+
+There are two ways to hold an evaluation's config; **for almost everyone the
+answer is a job.**
+
+- **Job** (recommended) — a self-contained `jobs/<name>/` folder created by
+  `ghostlab create`. Every command takes `--job <name>` (or auto-detects
+  `job.yaml` in the current dir). This is the mainstream path the whole
+  Quickstart uses.
+- **Spec** (advanced) — a single standalone `ghostlab.yaml` produced by
+  `ghostlab init`, addressed with `--spec <file>`. Useful for scripting or
+  keeping config outside the `jobs/` layout. Unless you specifically need that,
+  prefer a job.
+
+The commands overlap (`discover`/`plan`/`test`/`review` accept either `--job` or
+`--spec`); pick one model per evaluation and stay with it.
+
 ### Job folder layout
 
 ```text
@@ -179,7 +188,7 @@ Each test run points to a target definition:
 The package installs two equivalent console scripts: `ghostlab` and `rehearsal`.
 
 - `ghostlab create` — the end-to-end wizard described above.
-- `ghostlab init` — create a `job.yaml`/`ghostlab.yaml` from an existing target JSON, without the wizard prompts.
+- `ghostlab init` — advanced: scaffold a standalone `ghostlab.yaml` **spec** from a target JSON (see [spec vs job](#spec-vs-job) — most users want `ghostlab create`).
 - `ghostlab discover` — inspect the job's target, lint its contract, refresh capabilities.
 - `ghostlab plan` — generate (or curate) the coverage-driven test plan.
 - `ghostlab test` — execute the test plan across the job's host adapters.
@@ -190,6 +199,8 @@ The package installs two equivalent console scripts: `ghostlab` and `rehearsal`.
 - `ghostlab review-dataset` / `run-dataset` — curate and run a standalone dataset.
 - `ghostlab run` — run one dual-agent E2E scenario directly.
 - `ghostlab evaluate` — score a run into a pass/fail verdict (codex judge).
+- `ghostlab critique` — rate a run's tool ergonomics from the agent's perspective (codex).
+- `ghostlab scorecard` — roll run verdicts and critiques into a summary scorecard.
 - `ghostlab compare` — diff two dataset runs for regressions.
 - `ghostlab apps-probe` / `apps-render` — probe/render MCP Apps `ui://` widgets.
 - `ghostlab doctor` — check codex and validate runner presets.
@@ -218,7 +229,7 @@ Point it at a target and it introspects the server without any coding-agent
 credits or manual `curl`:
 
 ```bash
-ghostlab inspect --target targets/cortex-local.json
+ghostlab inspect --target examples/target.json
 ```
 
 This connects over the configured transport (stdio / streamable-HTTP / SSE),
@@ -279,7 +290,7 @@ confused, non-native, ...), and a domain `context` map (native_language,
 target_exam, level, ...). Pass one to a run with `--persona`:
 
 ```bash
-ghostlab run ... --persona personas/ielts-power-user.json
+ghostlab run ... --persona persona.json
 ```
 
 ### Build a dataset: `generate-dataset`
@@ -329,7 +340,7 @@ ghostlab review-dataset --dataset datasets/cortex \
 ```bash
 ghostlab run-dataset \
   --dataset datasets/cortex \
-  --target targets/cortex-local.json \
+  --target target.json \
   --aut-runner runners/codex-cortex-aut.json \
   --user-runner runners/codex-user-emulator.json \
   --limit 2
@@ -379,7 +390,7 @@ points to a `ui://…` HTML widget a compatible host is expected to render.
 `ui://` resource, and reports render-readiness and CSP diagnostics:
 
 ```bash
-ghostlab apps-probe --target targets/cortex-local.json
+ghostlab apps-probe --target target.json
 ```
 
 `apps-render` actually renders a `ui://` widget in headless Chrome, proving a
@@ -389,7 +400,7 @@ real tool input/result, and can drive a sequence of UI intents:
 
 ```bash
 pip install 'ghostlab[apps]' && playwright install chrome    # one-time
-ghostlab apps-render --target targets/cortex-local.json \
+ghostlab apps-render --target target.json \
   --tool views_generate_sentence_scramble \
   --arguments '{"target_sentence":"The cat sat on the mat","shuffled_elements":["mat","The","on","sat","cat","the"]}' \
   --intent '{"type":"reorder","value":["The","cat","sat","on","the","mat"]}' \
@@ -409,7 +420,7 @@ one codex session alive: turn 1 records the `thread_id`, and later turns run
 repeated cold-start noise.
 
 ```bash
-ghostlab run --target targets/cortex-local.json --scenario <scenario.json> \
+ghostlab run --target target.json --scenario <scenario.json> \
   --aut-runner runners/codex-cortex-local-session.json --user-runner <user.json>
 ```
 

{ghostlab-0.2.0 → ghostlab-0.2.1}/docs/cli.md

@@ -10,8 +10,8 @@ the project flow (`init` → `discover` → future `plan`/`test`/`review` stages
 every other command keeps accepting raw target/scenario JSON as before.
 
 ```bash
-ghostlab init --target targets/cortex-local.json          # writes ghostlab.yaml
-ghostlab init --target targets/cortex-local.json --out cortex.ghostlab.json
+ghostlab init --target target.json          # writes ghostlab.yaml
+ghostlab init --target target.json --out cortex.ghostlab.json
 ```
 
 Options: `--name` (display name), `--workspace` (artifact directory, default
@@ -215,7 +215,7 @@ Writes `readiness.json` / `readiness.md` next to the test results:
 Introspect a target MCP server.
 
 ```bash
-ghostlab inspect --target targets/cortex-local.json
+ghostlab inspect --target examples/target.json
 ```
 
 ## profile
@@ -282,8 +282,8 @@ Run one scenario.
 
 ```bash
 ghostlab run \
-  --target targets/example-stdio.json \
-  --scenario scenarios/basic-discovery.json \
+  --target examples/target.json \
+  --scenario examples/scenario.json \
   --aut-runner runners/mock-aut.json \
   --user-runner runners/mock-user.json
 ```
@@ -295,7 +295,7 @@ Run every case in a dataset. Use `--limit` for small development runs and `--app
 ```bash
 ghostlab run-dataset \
   --dataset datasets/cortex \
-  --target targets/cortex-local.json \
+  --target target.json \
   --aut-runner runners/codex-cortex-aut.json \
   --user-runner runners/codex-user-emulator.json \
   --limit 2

{ghostlab-0.2.0 → ghostlab-0.2.1}/docs/datasets-evaluation.md

@@ -76,7 +76,7 @@ run contains a call to that tool whose arguments include the given key/value pai
 
 ```bash
 ghostlab run-dataset --dataset datasets/cortex \
-  --target targets/cortex-local.json \
+  --target target.json \
   --aut-runner runners/codex-cortex-local-session.json \
   --evaluate --capabilities runs/<id>-inspect/capabilities.json
 ```

{ghostlab-0.2.0 → ghostlab-0.2.1}/docs/getting-started.md

@@ -3,11 +3,11 @@
 ## Install From A Checkout
 
 ```bash
-python3.13 -m venv .venv
-.venv/bin/pip install -r requirements-dev.txt
+python3 -m venv .venv          # Python 3.10+
+.venv/bin/pip install -e .
 ```
 
-This installs the package in editable mode and adds the `ghostlab` and `rehearsal` console scripts. Prefer `ghostlab` in new docs and scripts.
+This installs the package in editable mode and adds the `ghostlab` and `rehearsal` console scripts. Prefer `ghostlab` in new docs and scripts. (Contributors who also want the test/build/docs toolchain use `pip install -r requirements-dev.txt` instead — see `CONTRIBUTING.md`.)
 
 ```bash
 ghostlab --help
@@ -95,8 +95,8 @@ Mock runners let you exercise the orchestrator without spending coding-agent cre
 
 ```bash
 ghostlab run \
-  --target targets/example-stdio.json \
-  --scenario scenarios/basic-discovery.json \
+  --target examples/target.json \
+  --scenario examples/scenario.json \
   --aut-runner runners/mock-aut.json \
   --user-runner runners/mock-user.json
 ```
@@ -110,7 +110,7 @@ Run output is written under `runs/<run-id>/`:
 ## Inspect A Real MCP Target
 
 ```bash
-ghostlab inspect --target targets/cortex-local.json
+ghostlab inspect --target examples/target.json
 # or a standard MCP client config:
 ghostlab inspect --target ./mcp.json --server obsidian
 ```

{ghostlab-0.2.0 → ghostlab-0.2.1}/docs/ghostlab-vision-gap-and-roadmap.md

@@ -283,7 +283,7 @@ review:
 This artifact becomes the center of the system. All commands can still exist, but a new top-level flow should be:
 
 ```bash
-ghostlab init --target targets/cortex-local.json --out ghostlab.yaml
+ghostlab init --target target.json --out ghostlab.yaml
 ghostlab discover --spec ghostlab.yaml
 ghostlab plan --spec ghostlab.yaml
 ghostlab test --spec ghostlab.yaml --suite all --hosts codex-cli,claude-code

{ghostlab-0.2.0 → ghostlab-0.2.1}/docs/index.md

@@ -16,11 +16,11 @@ Use it when you want to test an MCP server through the same Codex or Claude Code
 ## Common Flow
 
 ```bash
-ghostlab inspect --target targets/cortex-local.json
+ghostlab inspect --target examples/target.json
 ghostlab profile --inspect runs/<id>-inspect/inspect.json
 ghostlab generate-dataset --profile runs/<id>-inspect/capabilities.json --name cortex
 ghostlab review-dataset --dataset datasets/cortex --profile runs/<id>-inspect/capabilities.json
-ghostlab run-dataset --dataset datasets/cortex --target targets/cortex-local.json --approved-only
+ghostlab run-dataset --dataset datasets/cortex --target target.json --approved-only
 ```
 
 Start with [Getting Started](getting-started.md), then use the [CLI Reference](cli.md) for the full command map.

{ghostlab-0.2.0 → ghostlab-0.2.1}/docs/publishing.md

@@ -14,7 +14,7 @@ The `Release` workflow publishes the `ghostlab` package to PyPI when a `v*.*.*`
 
 PyPI publishing uses Trusted Publishing. Create or claim the `ghostlab` project on PyPI and add a trusted publisher for:
 
-- Repository: `sajjadGG/Rehearsal`
+- Repository: `sajjadGG/Ghostlab`
 - Workflow: `.github/workflows/release.yml`
 - Environment: `pypi`
 

ghostlab-0.2.1/examples/README.md

@@ -0,0 +1,51 @@
+# Examples
+
+Ready-to-run sample configs so you can try Ghostlab without writing any JSON
+first. They point at the public Hugging Face MCP (`https://huggingface.co/mcp`),
+which can be **introspected without a token**, so the read-only commands below
+work with zero setup.
+
+| File | Shape | Used by |
+| --- | --- | --- |
+| `target.json` | Native Ghostlab target (`id` + `transport` + `connection`) | `ghostlab inspect`, `ghostlab run` |
+| `scenario.json` | A dual-agent scenario (persona, goal, success/failure criteria) | `ghostlab run` |
+| `mcp-config.json` | Standard `mcpServers` client config | `ghostlab create`, `ghostlab inspect` |
+
+## Try it
+
+Introspect the target with no auth (writes `inspect.json` + `inspect.md`):
+
+```bash
+ghostlab inspect --target examples/target.json
+```
+
+Run the mock dual-agent scenario end to end — no coding-agent credits, no
+network to the target (the mock runners don't call it):
+
+```bash
+ghostlab run \
+  --target examples/target.json \
+  --scenario examples/scenario.json \
+  --aut-runner runners/mock-aut.json \
+  --user-runner runners/mock-user.json
+```
+
+Scaffold a job straight from a standard `mcpServers` config:
+
+```bash
+ghostlab create --target examples/mcp-config.json
+```
+
+## Adding auth
+
+Most Hugging Face tools (beyond introspection) need a token. Add a bearer header
+to either config and export the referenced env var — the value is an env-var
+*reference*, never a literal secret in the file:
+
+```json
+"headers": { "Authorization": "Bearer ${HF_TOKEN}" }
+```
+
+```bash
+export HF_TOKEN=hf_...      # your token, kept out of the config file
+```

ghostlab-0.2.1/examples/mcp-config.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "huggingface": {
+      "url": "https://huggingface.co/mcp"
+    }
+  }
+}

ghostlab-0.2.0/scenarios/basic-discovery.json → ghostlab-0.2.1/examples/scenario.json

@@ -16,4 +16,3 @@
   ],
   "opening_message": "What can you help me do with this app? Pick one small useful thing and show me."
 }
-

ghostlab-0.2.0/targets/cortex-local.json → ghostlab-0.2.1/examples/target.json

@@ -1,8 +1,8 @@
 {
-  "id": "cortex-local",
+  "id": "huggingface",
   "transport": "streamable-http",
   "connection": {
-    "url": "http://localhost:8000/mcp",
+    "url": "https://huggingface.co/mcp",
     "headers": {}
   },
   "capabilities": {