stata-code 0.7.1__tar.gz → 0.8.0__tar.gz

{stata_code-0.7.1 → stata_code-0.8.0}/CHANGELOG.md

@@ -4,7 +4,60 @@ All notable changes to `stata-code` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project adheres
 to semver-major.minor for the result schema (see `SCHEMA.md` §6).
 
-## Unreleased
+## 0.8.0 — 2026-06-20
+
+### Added
+
+- **Economist workflow coordination and roadmap.** Added
+  `AGENT_COORDINATION.md` for concurrent-agent lanes and
+  `docs/industry-leader-roadmap.md` for the one-month product plan: workflow
+  intelligence, parity audits, data-MCP handoff, editor/artifact polish, and
+  distribution diagnostics.
+- **Cross-stack and data-MCP workflow references.** The `stata-code` skill now
+  includes `references/parity-audit.md` and
+  `references/data-mcp-handoff.md`, plus cookbook examples for cross-stack
+  parity audits and external-data-MCP handoff into Stata.
+- **Modern empirical-economics package notes.** Added package references for
+  `csdid`, `drdid`, `did_imputation`, `eventstudyinteract`,
+  `did_multiplegt_dyn`, `rdrobust`, `ivreg2`, `ivreghdfe`, `boottest`, and
+  `outreg2`, and wired them into the skill routing table.
+- **MCP prompt discoverability for economist workflows.** Added
+  `plan_cross_stack_parity_audit`, `data_mcp_to_stata_handoff`,
+  `did_event_study`, `iv_2sls`, `rdd`, `publication_table`, and
+  `cross_validate_did` prompts so clients can discover the new protocols and
+  turnkey empirical recipes directly through MCP.
+- **Read-only installation diagnostics.** Added the top-level `stata-code`
+  console script with `doctor` / `verify` commands. The diagnostic reports
+  package/Python version, MCP and kernel extras, `pystata` discovery, console
+  scripts on `PATH`, client/VS Code hints, and an optional live Stata
+  version/edition probe without mutating user configuration.
+
+## 0.7.2 — 2026-06-20
+
+### Added
+
+- **Three convenience MCP tools** raise the tool surface from 15 to 18:
+  - `install_package(name, source?, url?, replace?, session_id?)` — installs a
+    community package via `ssc install` / `net install` without the agent
+    having to remember the syntax, then verifies it resolves with `which`.
+    Package names and URLs are validated to keep them out of the generated
+    command line; failures surface the typed `error` block (e.g. `network`).
+  - `search_log(ref, pattern, is_regex?, ignore_case?, context?, max_matches?)`
+    — greps within a truncated `log://` payload and returns only the matching
+    lines (with optional context), so a long log can be inspected without
+    pulling the whole transcript back through `get_log`.
+  - `inspect_data(varlist?, detail?, session_id?)` — runs `describe` +
+    `codebook` and returns the structured `dataset` block plus the codebook
+    log: a one-call "what's in this dataset" the agent doesn't have to spell out.
+- **On-demand Stata reference library** under `skills/stata-code/references/`
+  (~4,200 lines): topic files for core syntax, data management, econometrics,
+  causal inference, panel/time series, graphics, and table export; load-bearing
+  `error-codes.md` (the full `rc → kind → fix` table + self-repair loop, aligned
+  with the typed-error taxonomy) and `defensive-coding.md`; and per-package notes
+  for `reghdfe`, `coefplot`, `estout`, and `gtools`. `SKILL.md` gained a routing
+  table (read 1–3 files on demand) and a live-vs-offline execution-mode section.
+- **`scripts/build_skill_zip.py`** packages the skill into a deterministic
+  `build/stata-code-skill.zip` for upload as Claude.ai project knowledge.
 
 ## 0.7.1 — 2026-06-19
 

{stata_code-0.7.1 → stata_code-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stata-code
-Version: 0.7.1
+Version: 0.8.0
 Summary: Agent-native Stata bridge — one core, multiple frontends (MCP, Jupyter, VSCode)
 Project-URL: Homepage, https://github.com/brycewang-stanford/stata-code
 Project-URL: Repository, https://github.com/brycewang-stanford/stata-code
@@ -67,6 +67,22 @@ Description-Content-Type: text/markdown
 
 `stata-code` lets you drive Stata from modern environments: an LLM agent (Claude Code, Cursor, Claude Desktop), a Jupyter notebook, or a VS Code editor session. All frontends share one Python core and return a stable, structured, **agent-friendly** result schema.
 
+**For empirical economists.** Drive Stata in plain language: run **DiD, IV, RDD, and publication-ready `esttab` tables in one conversation** — then cross-check each estimate across Stata and Python so you only trust results that *agree* (the Cunningham cross-package robustness check).
+
+**Try it in 60 seconds** with [Claude Code](https://github.com/anthropics/claude-code) — no global install needed:
+
+```bash
+claude mcp add stata-code --scope user -- uvx --from "stata-code[mcp]" stata-code-mcp
+```
+
+Then just ask:
+
+> *"Using `data/cfps_panel.dta`, run a two-way fixed-effects regression of monthly wage on the treatment (controls: `age age2 edu industry`), then test heterogeneous effects with Callaway-Sant'Anna, and export an `esttab` table."*
+
+`stata-code` writes the do-file, runs it, returns the table, and interprets the result — and can re-estimate the same ATT with [StatsPAI](https://github.com/brycewang-stanford/StatsPAI) to confirm the two stacks agree. These workflows ship as one-call MCP prompts (`did_event_study`, `iv_2sls`, `rdd`, `publication_table`, `cross_validate_did`) backed by an on-demand [recipe library](skills/stata-code/references/recipes/).
+
+**Why `stata-code`:** MIT-licensed · ships as an MCP server, a bundled agent skill, a Jupyter kernel, **and** a VS Code extension · one structured, token-economy result schema (typed errors, native `r()` / `e()`) · cross-stack validation with StatsPAI for the Cunningham check.
+
 ```text
                     ┌────────────────────────────────────────┐
                     │     stata-code core (Python)           │
@@ -84,12 +100,18 @@ Description-Content-Type: text/markdown
               └─────────────┘  └────────────┘  └─────────────────┘
 ```
 
-**Status: v0.7 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
+**Status: v0.8 (June 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
 
-Two workflows the current release explicitly supports for end users:
+Three workflows the current tree explicitly supports for end users and agents:
 
 - **Run Stata code from a Jupyter notebook.** `pip install "stata-code[kernel]"` + `stata-code-kernel install --user` registers a **Stata** kernel that the Jupyter Notebook UI, JupyterLab, and the VS Code Jupyter extension all pick up by name. Cells render Stata logs, graphs, and warnings inline (the kernel logo bundled since v0.5 makes it appear in VS Code's kernel picker too). See [As a Jupyter Kernel](#as-a-jupyter-kernel).
 - **Optional agent "fix and rerun" loop.** `stata_run` returns typed `error.kind/line/context` plus `suggestions` on every failure. By default Claude Code only reports diagnostics — but if you explicitly say "fix this and rerun until it passes", the agent uses the same fields to edit your `.do` file and re-call `stata_run` until the run is green. The repair loop is **opt-in**: failed runs are diagnostics first, not automatic rewrite permission. See [Error Recovery in Agent Workflows](#error-recovery-in-agent-workflows).
+- **Economist workflow guides.** The bundled skill and cookbook now cover
+  modern DiD, IV/weak-IV, RDD, table export, data-MCP handoff, and
+  cross-stack parity audits. `stata-code` runs and audits the Stata leg; R,
+  Python, and official data MCPs remain separate tools with explicit handoff
+  files and source metadata. See [`skills/stata-code/references/`](skills/stata-code/references/)
+  and [`examples/`](examples/).
 
 ---
 
@@ -138,6 +160,19 @@ pip install -e ".[mcp,kernel]"
 
 Note: `pystata` is **not** on PyPI; it ships with Stata. `stata-code` auto-discovers it on macOS at `/Applications/Stata/utilities/pystata` and at equivalent Linux / Windows paths. If your install is elsewhere, add it to `PYTHONPATH` before importing.
 
+Verify the local setup with the read-only doctor:
+
+```bash
+stata-code doctor
+stata-code doctor --json          # machine-readable output
+stata-code doctor --no-stata-probe # skip live Stata initialization
+```
+
+The doctor reports the package/Python version, MCP and Jupyter extras, `pystata`
+discovery, console scripts on `PATH`, client/VS Code configuration hints, and a
+best-effort Stata version/edition probe. It never edits shell, Stata, Claude, or
+VS Code config.
+
 ---
 
 ## Quick Start
@@ -188,7 +223,7 @@ claude mcp add stata-code --scope local -- stata-code-mcp
 claude mcp add stata-code --scope project -- stata-code-mcp
 ```
 
-Then launch `claude` and type `/mcp` to confirm `stata-code` shows up with its 15 tools (`stata_run`, `stata_info`, `get_log`, `get_graph`, `get_matrix`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`).
+Then launch `claude` and type `/mcp` to confirm `stata-code` shows up with its 18 tools (`stata_run`, `stata_info`, `get_log`, `search_log`, `get_graph`, `get_matrix`, `inspect_data`, `install_package`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`).
 
 #### Error Recovery in Agent Workflows
 
@@ -276,15 +311,18 @@ If an OpenAI-backed client reports `API Error: 400 Invalid schema for function
 upgrade to `stata-code>=0.6.5`, then restart the MCP client. Older server
 processes keep advertising the stale schema until they are restarted.
 
-The MCP server registers 15 tools:
+The MCP server registers 18 tools:
 
 | Tool | Purpose |
 | --- | --- |
 | `stata_run` | Execute Stata code and return a v1.0 RunResult JSON |
 | `stata_info` | Report Stata edition, version, and capabilities |
 | `get_log` | Fetch the full log behind a `log://` ref |
+| `search_log` | Search matching lines inside a stored `log://` payload |
 | `get_graph` | Fetch graph bytes behind a `graph://` ref (`ImageContent`) |
 | `get_matrix` | Fetch matrix payloads behind a `matrix://` ref |
+| `inspect_data` | Run `describe` + `codebook` and return compact dataset metadata |
+| `install_package` | Install an SSC or explicit `net install` package and verify it resolves |
 | `list_sessions` | Enumerate live sessions |
 | `cancel_session` | Cancel a session; the subprocess-backed path terminates in-flight runs and short-circuits pending ones |
 | `reset_session` | Drop a session's data |
@@ -312,8 +350,11 @@ resources:
 
 MCP prompts are available for common agent workflows:
 `run_do_file_and_report`, `debug_stata_error`,
-`fix_and_rerun_until_passes`, `replication_audit`, and
-`summarize_estimation_results`.
+`fix_and_rerun_until_passes`, `replication_audit`,
+`plan_cross_stack_parity_audit`, `data_mcp_to_stata_handoff`,
+`summarize_estimation_results`, `run_notebook_cell_and_report`,
+`fix_and_rerun_notebook_cell`, `did_event_study`, `iv_2sls`, `rdd`,
+`publication_table`, and `cross_validate_did`.
 
 ### As a Jupyter Kernel
 
@@ -355,6 +396,12 @@ Or open the **Extensions** sidebar in VS Code and search `stata-code`. The exten
 
 On first activation the extension probes for `stata-code-mcp` on `PATH` (and in any workspace `.venv` / `venv`). If nothing resolves, it shows a one-time install hint with the exact `pip install "stata-code[mcp]"` command — choose **Don't show again** to silence it for the installed extension version.
 
+If the extension or an MCP client cannot find the server, run
+`stata-code doctor --no-stata-probe` in the same Python environment. It reports
+whether `stata-code-mcp` is on `PATH` and suggests absolute-path or
+`python -m stata_code.mcp` fallbacks for GUI clients whose `PATH` differs from
+your shell.
+
 #### Cell and section conventions
 
 The extension recognizes two complementary structural markers inside `.do` files. Either can be mixed in the same file; they do not conflict.
@@ -416,7 +463,7 @@ stata_code/
 │   ├── runner.py      # in-process execute(); collects everything via sfi
 │   └── _pool.py       # subprocess workers for public API / MCP hard timeouts
 ├── mcp/
-│   └── server.py      # MCP server (15 tools)
+│   └── server.py      # MCP server (18 tools)
 └── kernel/
     └── kernel.py      # Jupyter kernel
 ```
@@ -444,7 +491,7 @@ stata_code/
 
 ## Roadmap
 
-### Done (through v0.7 — May 2026)
+### Done (current tree)
 
 - v1.0 result schema ([SCHEMA.md](SCHEMA.md))
 - `pystata`-based runner with native-typed `r()`, `e()`, and matrices
@@ -454,12 +501,18 @@ stata_code/
 - Log truncation with ref store
 - Warning extraction: 5 categories + generic notes
 - 32-kind error taxonomy with canonical suggestions
-- MCP server: 15 tools, including notebook navigation / search / atomic edits and the run-bundle index (`list_runs`)
+- MCP server: 18 tools, including notebook navigation / search / atomic edits, the run-bundle index (`list_runs`), log grep (`search_log`), dataset inspection (`inspect_data`), and package installation (`install_package`)
 - Jupyter kernel: rewired to the v1.0 pipeline, kernel logos bundled
 - Matrix size cap + `get_matrix(ref)` for large matrices (>10k cells)
 - Subprocess-backed hard timeout and cancellation for the public Python API and MCP server: `timeout_ms`, `cancel(session_id)`, and MCP `cancel_session`
 - Per-cell repair loop on `.ipynb` via `notebook_outline` / `notebook_get_cell` / `notebook_edit_cell` with optimistic-concurrency `expected_source` guards and `origin_cell_id` echo on `RunResult`
 - Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok; page with limit / offset)
+- Read-only `stata-code doctor` / `verify` diagnostics for package version,
+  extras, `pystata` discovery, console scripts, client hints, and optional live
+  Stata version probing
+- Economist workflow layer: skill references and examples for modern DiD,
+  IV/weak-IV, RDD, table export, data-MCP handoff, and cross-stack parity
+  audits
 - JSON Schema artifact auto-generated from `schema.py`: [`schema/run_result.schema.json`](schema/run_result.schema.json)
 - VS Code extension published to the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode): syntax highlighting, section outline/navigation, code-lens cell and section runners, sidebar (sessions / last result / run history / logs / graphs), status bar, completions, conservative variable rename, diagnostics, MCP child-process spawn
 - Clean-room license policy ([LICENSE-POLICY.md](LICENSE-POLICY.md))

{stata_code-0.7.1 → stata_code-0.8.0}/README.md

@@ -28,6 +28,22 @@
 
 `stata-code` lets you drive Stata from modern environments: an LLM agent (Claude Code, Cursor, Claude Desktop), a Jupyter notebook, or a VS Code editor session. All frontends share one Python core and return a stable, structured, **agent-friendly** result schema.
 
+**For empirical economists.** Drive Stata in plain language: run **DiD, IV, RDD, and publication-ready `esttab` tables in one conversation** — then cross-check each estimate across Stata and Python so you only trust results that *agree* (the Cunningham cross-package robustness check).
+
+**Try it in 60 seconds** with [Claude Code](https://github.com/anthropics/claude-code) — no global install needed:
+
+```bash
+claude mcp add stata-code --scope user -- uvx --from "stata-code[mcp]" stata-code-mcp
+```
+
+Then just ask:
+
+> *"Using `data/cfps_panel.dta`, run a two-way fixed-effects regression of monthly wage on the treatment (controls: `age age2 edu industry`), then test heterogeneous effects with Callaway-Sant'Anna, and export an `esttab` table."*
+
+`stata-code` writes the do-file, runs it, returns the table, and interprets the result — and can re-estimate the same ATT with [StatsPAI](https://github.com/brycewang-stanford/StatsPAI) to confirm the two stacks agree. These workflows ship as one-call MCP prompts (`did_event_study`, `iv_2sls`, `rdd`, `publication_table`, `cross_validate_did`) backed by an on-demand [recipe library](skills/stata-code/references/recipes/).
+
+**Why `stata-code`:** MIT-licensed · ships as an MCP server, a bundled agent skill, a Jupyter kernel, **and** a VS Code extension · one structured, token-economy result schema (typed errors, native `r()` / `e()`) · cross-stack validation with StatsPAI for the Cunningham check.
+
 ```text
                     ┌────────────────────────────────────────┐
                     │     stata-code core (Python)           │
@@ -45,12 +61,18 @@
               └─────────────┘  └────────────┘  └─────────────────┘
 ```
 
-**Status: v0.7 (May 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
+**Status: v0.8 (June 2026)** — the core, MCP server, Jupyter kernel, and VS Code extension work end-to-end against Stata 18 MP. The test suite covers schema, runner, MCP, kernel, notebook, run-index, subprocess-pool, and VS Code modules; CI also checks linting, type safety, schema generation, package metadata, and VSIX packaging. License: **MIT**.
 
-Two workflows the current release explicitly supports for end users:
+Three workflows the current tree explicitly supports for end users and agents:
 
 - **Run Stata code from a Jupyter notebook.** `pip install "stata-code[kernel]"` + `stata-code-kernel install --user` registers a **Stata** kernel that the Jupyter Notebook UI, JupyterLab, and the VS Code Jupyter extension all pick up by name. Cells render Stata logs, graphs, and warnings inline (the kernel logo bundled since v0.5 makes it appear in VS Code's kernel picker too). See [As a Jupyter Kernel](#as-a-jupyter-kernel).
 - **Optional agent "fix and rerun" loop.** `stata_run` returns typed `error.kind/line/context` plus `suggestions` on every failure. By default Claude Code only reports diagnostics — but if you explicitly say "fix this and rerun until it passes", the agent uses the same fields to edit your `.do` file and re-call `stata_run` until the run is green. The repair loop is **opt-in**: failed runs are diagnostics first, not automatic rewrite permission. See [Error Recovery in Agent Workflows](#error-recovery-in-agent-workflows).
+- **Economist workflow guides.** The bundled skill and cookbook now cover
+  modern DiD, IV/weak-IV, RDD, table export, data-MCP handoff, and
+  cross-stack parity audits. `stata-code` runs and audits the Stata leg; R,
+  Python, and official data MCPs remain separate tools with explicit handoff
+  files and source metadata. See [`skills/stata-code/references/`](skills/stata-code/references/)
+  and [`examples/`](examples/).
 
 ---
 
@@ -99,6 +121,19 @@ pip install -e ".[mcp,kernel]"
 
 Note: `pystata` is **not** on PyPI; it ships with Stata. `stata-code` auto-discovers it on macOS at `/Applications/Stata/utilities/pystata` and at equivalent Linux / Windows paths. If your install is elsewhere, add it to `PYTHONPATH` before importing.
 
+Verify the local setup with the read-only doctor:
+
+```bash
+stata-code doctor
+stata-code doctor --json          # machine-readable output
+stata-code doctor --no-stata-probe # skip live Stata initialization
+```
+
+The doctor reports the package/Python version, MCP and Jupyter extras, `pystata`
+discovery, console scripts on `PATH`, client/VS Code configuration hints, and a
+best-effort Stata version/edition probe. It never edits shell, Stata, Claude, or
+VS Code config.
+
 ---
 
 ## Quick Start
@@ -149,7 +184,7 @@ claude mcp add stata-code --scope local -- stata-code-mcp
 claude mcp add stata-code --scope project -- stata-code-mcp
 ```
 
-Then launch `claude` and type `/mcp` to confirm `stata-code` shows up with its 15 tools (`stata_run`, `stata_info`, `get_log`, `get_graph`, `get_matrix`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`).
+Then launch `claude` and type `/mcp` to confirm `stata-code` shows up with its 18 tools (`stata_run`, `stata_info`, `get_log`, `search_log`, `get_graph`, `get_matrix`, `inspect_data`, `install_package`, `list_sessions`, `cancel_session`, `reset_session`, `notebook_outline`, `notebook_get_cell`, `notebook_locate`, `notebook_edit_cell`, `notebook_insert_cell`, `notebook_delete_cell`, `list_runs`).
 
 #### Error Recovery in Agent Workflows
 
@@ -237,15 +272,18 @@ If an OpenAI-backed client reports `API Error: 400 Invalid schema for function
 upgrade to `stata-code>=0.6.5`, then restart the MCP client. Older server
 processes keep advertising the stale schema until they are restarted.
 
-The MCP server registers 15 tools:
+The MCP server registers 18 tools:
 
 | Tool | Purpose |
 | --- | --- |
 | `stata_run` | Execute Stata code and return a v1.0 RunResult JSON |
 | `stata_info` | Report Stata edition, version, and capabilities |
 | `get_log` | Fetch the full log behind a `log://` ref |
+| `search_log` | Search matching lines inside a stored `log://` payload |
 | `get_graph` | Fetch graph bytes behind a `graph://` ref (`ImageContent`) |
 | `get_matrix` | Fetch matrix payloads behind a `matrix://` ref |
+| `inspect_data` | Run `describe` + `codebook` and return compact dataset metadata |
+| `install_package` | Install an SSC or explicit `net install` package and verify it resolves |
 | `list_sessions` | Enumerate live sessions |
 | `cancel_session` | Cancel a session; the subprocess-backed path terminates in-flight runs and short-circuits pending ones |
 | `reset_session` | Drop a session's data |
@@ -273,8 +311,11 @@ resources:
 
 MCP prompts are available for common agent workflows:
 `run_do_file_and_report`, `debug_stata_error`,
-`fix_and_rerun_until_passes`, `replication_audit`, and
-`summarize_estimation_results`.
+`fix_and_rerun_until_passes`, `replication_audit`,
+`plan_cross_stack_parity_audit`, `data_mcp_to_stata_handoff`,
+`summarize_estimation_results`, `run_notebook_cell_and_report`,
+`fix_and_rerun_notebook_cell`, `did_event_study`, `iv_2sls`, `rdd`,
+`publication_table`, and `cross_validate_did`.
 
 ### As a Jupyter Kernel
 
@@ -316,6 +357,12 @@ Or open the **Extensions** sidebar in VS Code and search `stata-code`. The exten
 
 On first activation the extension probes for `stata-code-mcp` on `PATH` (and in any workspace `.venv` / `venv`). If nothing resolves, it shows a one-time install hint with the exact `pip install "stata-code[mcp]"` command — choose **Don't show again** to silence it for the installed extension version.
 
+If the extension or an MCP client cannot find the server, run
+`stata-code doctor --no-stata-probe` in the same Python environment. It reports
+whether `stata-code-mcp` is on `PATH` and suggests absolute-path or
+`python -m stata_code.mcp` fallbacks for GUI clients whose `PATH` differs from
+your shell.
+
 #### Cell and section conventions
 
 The extension recognizes two complementary structural markers inside `.do` files. Either can be mixed in the same file; they do not conflict.
@@ -377,7 +424,7 @@ stata_code/
 │   ├── runner.py      # in-process execute(); collects everything via sfi
 │   └── _pool.py       # subprocess workers for public API / MCP hard timeouts
 ├── mcp/
-│   └── server.py      # MCP server (15 tools)
+│   └── server.py      # MCP server (18 tools)
 └── kernel/
     └── kernel.py      # Jupyter kernel
 ```
@@ -405,7 +452,7 @@ stata_code/
 
 ## Roadmap
 
-### Done (through v0.7 — May 2026)
+### Done (current tree)
 
 - v1.0 result schema ([SCHEMA.md](SCHEMA.md))
 - `pystata`-based runner with native-typed `r()`, `e()`, and matrices
@@ -415,12 +462,18 @@ stata_code/
 - Log truncation with ref store
 - Warning extraction: 5 categories + generic notes
 - 32-kind error taxonomy with canonical suggestions
-- MCP server: 15 tools, including notebook navigation / search / atomic edits and the run-bundle index (`list_runs`)
+- MCP server: 18 tools, including notebook navigation / search / atomic edits, the run-bundle index (`list_runs`), log grep (`search_log`), dataset inspection (`inspect_data`), and package installation (`install_package`)
 - Jupyter kernel: rewired to the v1.0 pipeline, kernel logos bundled
 - Matrix size cap + `get_matrix(ref)` for large matrices (>10k cells)
 - Subprocess-backed hard timeout and cancellation for the public Python API and MCP server: `timeout_ms`, `cancel(session_id)`, and MCP `cancel_session`
 - Per-cell repair loop on `.ipynb` via `notebook_outline` / `notebook_get_cell` / `notebook_edit_cell` with optimistic-concurrency `expected_source` guards and `origin_cell_id` echo on `RunResult`
 - Persistent run bundles + `list_runs` query over `manifest.json` files (filter by cell / origin / session / since / ok; page with limit / offset)
+- Read-only `stata-code doctor` / `verify` diagnostics for package version,
+  extras, `pystata` discovery, console scripts, client hints, and optional live
+  Stata version probing
+- Economist workflow layer: skill references and examples for modern DiD,
+  IV/weak-IV, RDD, table export, data-MCP handoff, and cross-stack parity
+  audits
 - JSON Schema artifact auto-generated from `schema.py`: [`schema/run_result.schema.json`](schema/run_result.schema.json)
 - VS Code extension published to the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode): syntax highlighting, section outline/navigation, code-lens cell and section runners, sidebar (sessions / last result / run history / logs / graphs), status bar, completions, conservative variable rename, diagnostics, MCP child-process spawn
 - Clean-room license policy ([LICENSE-POLICY.md](LICENSE-POLICY.md))

stata_code-0.8.0/docs/industry-leader-roadmap.md

@@ -0,0 +1,99 @@
+# stata-code Industry Leadership Roadmap
+
+This roadmap translates the June 2026 empirical-research MCP landscape into
+work that fits `stata-code`'s architecture. The project should win by being the
+most reliable agent-native Stata execution and audit layer for empirical
+economists, not by becoming a grab-bag data platform or a second R/Python
+runtime.
+
+## North Star
+
+`stata-code` should be the default way an AI agent runs, inspects, repairs, and
+audits Stata work:
+
+- one execution core across Python, MCP, Jupyter, and VS Code;
+- stable `RunResult` schema with typed errors and native `r()` / `e()` values;
+- token-efficient logs, graphs, matrices, and run bundles;
+- economist-facing workflows for DiD, IV, RDD, tables, data handoff, and
+  cross-package verification.
+
+## Product Pillars
+
+1. **Reliable execution contract.** Keep `SCHEMA.md` load-bearing. Agents
+   branch on `ok`, `error.kind`, `results.e`, refs, and run manifests instead
+   of parsing log prose.
+2. **Econometrics workflow intelligence.** Ship concise skill references and
+   prompts that know the Stata commands economists actually use: `csdid`,
+   `did_imputation`, `eventstudyinteract`, `rdrobust`, `ivreg2`,
+   `ivreghdfe`, `boottest`, `esttab`, `collect`, and related packages.
+3. **Cross-stack parity audits.** Treat R/Python/Stata disagreement as a first
+   class research risk. `stata-code` should run the Stata leg and define the
+   comparison protocol without pretending to own the R or Python runtimes.
+4. **Data-MCP handoff.** External MCP servers can discover and fetch official
+   data. `stata-code` should document and validate the handoff into Stata:
+   source metadata, stable raw files, key checks, and reproducible imports.
+5. **Editor and artifact ergonomics.** VS Code should make sessions, graphs,
+   logs, tables, data previews, and run bundles easy to inspect without hiding
+   the underlying structured result.
+6. **Distribution confidence.** Install and runtime checks should be easy to
+   verify without mutating user config. Prefer `doctor`/`verify` diagnostics
+   before any automatic config writer.
+
+## Scope Boundaries
+
+`stata-code` should not directly bundle data-provider APIs, R sessions, Python
+causal libraries, or paid services. Those are separate tools. The durable
+boundary is: external data/model tools produce files or results; `stata-code`
+executes and audits the Stata side with traceable artifacts.
+
+## One-Month Execution Plan
+
+### Week 1: Workflow Layer
+
+- Add cross-agent coordination and this roadmap.
+- Expand the skill reference library for modern DiD, IV/weak-IV, RDD,
+  table-export, data-MCP handoff, and parity audits.
+- Add examples that show how agents should use the workflows without claiming
+  unsupported automation.
+- Add MCP prompts for parity audit planning, data-MCP-to-Stata handoff, and
+  turnkey method templates for DiD/event study, IV/2SLS, RDD, and publication
+  tables.
+- Validate with skill packaging tests, MCP prompt tests, and markdown hygiene.
+
+### Week 2: Diagnostics and Setup Confidence
+
+- Ship a read-only `stata-code doctor` / `verify` command that reports Python,
+  `stata-code`, MCP extras, `pystata` discovery, Stata version/edition, PATH
+  resolution, and common client config hints.
+- Keep config writing out of scope until backups and dry-run behavior exist.
+- Add tests for missing `pystata`, missing MCP extra, path mismatch, and JSON
+  output.
+
+### Week 3: VS Code and Artifacts
+
+- Improve dataset preview from first-100 text output toward a paged/filterable
+  view or a clearly documented intermediate step.
+- Surface table/export artifacts from run bundles more explicitly.
+- Add tests around formatter and tree-provider behavior before broad UI work.
+
+### Week 4: Release Quality
+
+- Sweep README.md, README.zh.md, vscode/README.md, CHANGELOG.md, examples,
+  and skill docs for drift.
+- Run release-relevant checks: version guard, schema export, skill zip build,
+  MCP tests, core tests that do not require Stata, and VS Code compile/tests if
+  touched.
+- Prepare release notes that separate shipped features from roadmap items.
+
+## Success Criteria
+
+- Agents can find a documented path for the top empirical workflows without
+  loading the whole reference library.
+- Parity audits preserve sample definitions, package versions, estimator
+  defaults, failure/refusal behavior, and numeric tolerances.
+- Data pulled by external MCP servers enters Stata through a reproducible raw
+  file plus metadata handoff, not through unstated browser-copy steps.
+- User-facing docs explain that `stata-code` runs Stata and coordinates with
+  other MCP tools; they do not imply that it directly runs R/Python or hosts
+  official data APIs.
+- All changed surfaces have targeted validation evidence before handoff.

stata_code-0.8.0/examples/06-cross-stack-parity-audit.md

@@ -0,0 +1,101 @@
+# 06 — Cross-stack parity audit
+
+> **Goal:** show how an agent should use `stata-code` for the Stata leg of a
+> Stata/R/Python robustness audit without pretending that one tool owns every
+> runtime.
+
+This example is intentionally protocol-first. The exact R/Python calls depend
+on which external MCP servers or local runtimes the user has installed. The
+Stata leg is concrete and traceable through `stata_run`.
+
+## Step 1: freeze the common sample
+
+**Agent calls:**
+
+```json
+{
+  "tool": "stata_run",
+  "arguments": {
+    "code": "use data/panel.dta, clear\negen unit_id = group(firm_id), label\negen time_id = group(year), label\ngen byte audit_sample = !missing(y, first_treat, unit_id, time_id, x1, x2)\nkeep if audit_sample\nisid unit_id time_id\ncompress\ndatasignature set, reset\nsave data/derived/parity_sample.dta, replace\nexport delimited using data/derived/parity_sample.csv, replace",
+    "origin_path": "/abs/project/analysis/00_freeze_parity_sample.do",
+    "origin_kind": "file",
+    "persist_log_files": true
+  }
+}
+```
+
+**Agent reads:**
+
+- `ok`, `rc`, and any typed error.
+- `dataset.n_obs` and `dataset.n_vars`.
+- `log.files.directory` for the run bundle.
+- generated files copied into `outputs/` when persistence is enabled.
+
+The CSV is the handoff file for R/Python tools. The DTA is the Stata source for
+the Stata estimators. Do not let every package define its own missing-value
+sample.
+
+## Step 2: run the Stata estimator
+
+**Agent calls:**
+
+```json
+{
+  "tool": "stata_run",
+  "arguments": {
+    "code": "use data/derived/parity_sample.dta, clear\ncsdid y x1 x2, ivar(unit_id) time(time_id) gvar(first_treat) method(dripw)\nestat simple\nestat event\ncsdid_plot",
+    "session_id": "stata_csdid",
+    "origin_path": "/abs/project/analysis/01_stata_csdid.do",
+    "origin_kind": "file",
+    "persist_log_files": true
+  }
+}
+```
+
+**Agent reads:**
+
+- `results.e.scalars` for `N` and available fit/ATT scalars.
+- `results.e.matrices` for coefficient and VCE payloads.
+- `graphs[0].ref` for the event-study plot.
+- `warnings` and `log.error_window` for dropped cohorts or estimator refusal.
+
+If `csdid` is missing, the repair loop may call:
+
+```json
+{"tool": "install_package", "arguments": {"name": "csdid"}}
+```
+
+and, if needed:
+
+```json
+{"tool": "install_package", "arguments": {"name": "drdid"}}
+```
+
+## Step 3: run external legs with their own tools
+
+The agent should hand `data/derived/parity_sample.csv` plus the written parity
+contract to the R/Python tools that are actually available. `stata-code` should
+not claim those estimates. It should record their package versions, options,
+sample `N`, warnings/refusals, and output files in the comparison table.
+
+## Step 4: compare only like with like
+
+| Stack | Package | Target | N | Estimate | SE | Warning/refusal |
+| --- | --- | --- | ---: | ---: | ---: | --- |
+| Stata | `csdid` | overall ATT from `estat simple` | from `results.e` | from `e(b)`/scalar | from `e(V)` | from `warnings` |
+| R | external | same target | external | external | external | external |
+| Python | external | same target | external | external | external | external |
+
+Do not compare an overall ATT to an event-time coefficient. Do not hide package
+refusals. If sample `N` differs, stop and fix the sample before interpreting
+coefficient differences.
+
+## Step 5: report conservatively
+
+Use language like:
+
+- "The Stata `csdid` leg ran on the frozen sample and produced ..."
+- "The R/Python legs were run by external tools; stata-code only coordinated the
+  handoff and Stata audit trail."
+- "The estimates agree within the predeclared tolerance" or "they diverge, with
+  the likely source being sample/default/failure differences."