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

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

@@ -4,6 +4,86 @@ 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).
 
+## 0.9.0 — 2026-06-23
+
+### Fixed
+
+- **Error-taxonomy correctness.** Audited the `_rc` → `ErrorKind` table against
+  StataCorp's `[P] error` manual (Stata 19) and corrected several
+  misclassifications: `not_sorted` is now `r(5)` (was the unrelated `r(119)`
+  "statement out of context" / `r(459)` "data is not…"); numlist errors
+  `r(122)`/`r(123)` are now `syntax` (were `invalid_name`); `r(322)` and
+  `r(1400)` map to `estimation_failure` (was `file_not_found` /
+  `estimation_sample_empty`); `r(480)` maps to `infeasible` (was
+  `out_of_memory`); local I/O `r(691)`–`r(693)` map to `file_io` (were
+  `network`). Misleading mappings for `r(9)`/`r(604)`/`r(615)`/`r(616)` were
+  removed (they fall through to `unknown` rather than assert a wrong kind).
+- **Command "did you mean?" now fires.** The `command_not_found` (rc 199) name
+  extractor expected `"<X> unrecognized command"`, but Stata's actual message is
+  `"command <X> is unrecognized"` — so the fuzzy suggestion never matched in
+  practice (synthetic unit tests passed the name in directly and hid it). Fixed
+  the regex and added a real-Stata integration test so a typo like `regresss`
+  now surfaces "Did you mean `regress`?".
+
+### Added
+
+- **Typed estimation contract.** `RunResult.results.estimation` now exposes a
+  frontend-neutral coefficient table derived from verified `r(table)` when
+  possible, or from inline `e(b)` / `e(V)` as a clearly marked fallback. New
+  public helpers `build_estimation_result()` and
+  `build_estimation_from_returns()` keep the contract unit-testable without
+  Stata. The contract also carries a coarse `command_family`
+  (ols/iv/gmm/panel/count/did/…) and command-aware `diagnostics` — identification
+  and specification tests surfaced from `e()` for the commands economists must
+  report (`ivreg2`/`ivreghdfe` weak-ID F and Hansen J, `xtabond2` AR(2)/Hansen,
+  `reghdfe` within-R²/absorbed FE, `xtreg` rho). Only scalars actually present in
+  `e()` are surfaced — never fabricated.
+- **Machine-readable recovery contract.** `error.recovery` now classifies each
+  `ErrorKind` by failure domain and tells agents whether an unchanged retry,
+  code edit, or user/out-of-band action is likely needed. Synthetic timeout,
+  cancellation, and adapter-crash errors carry the same recovery metadata as
+  ordinary Stata errors.
+- **Reproducibility provenance helpers.** New `Provenance`,
+  `build_provenance()`, and `build_reproducible_do()` helpers turn a completed
+  `RunResult` plus original code into a runtime provenance envelope and a
+  re-runnable `.do` script preamble with Stata `version`, `set more off`, and an
+  optional `set seed`. Provenance now also records **per-package dependencies**
+  parsed from the script (`extract_package_installs()` →
+  `Provenance.packages`: `ssc`/`net install` name, source, and `from()` URL),
+  and `build_submission_package()` assembles a self-contained
+  replication/journal-submission bundle (`analysis.do` + `PROVENANCE.json` +
+  a `README.md` manifest listing runtime, seed, and required community packages).
+- **Data-MCP handoff verifier.** New `verify_dataset()` and `DatasetCheck`
+  helpers validate imported datasets against provider metadata such as expected
+  row count, variable count, observation bounds, and required variables.
+- **`error.rc_label` is now populated for real Stata errors.** New
+  `RC_LABEL` table and `label_for_rc()` (public API) supply Stata's canonical
+  short message (e.g. `r(111)` → "variable not found") so agents have a stable,
+  transcript-independent descriptor to branch and group on. Unverified codes
+  yield an empty label rather than a guess.
+- **More return codes classified** (shrinking `unknown`): real network codes
+  `r(2)`/`r(631)`/`r(672)`/`r(677)` → `network`; `r(688)` → `file_corrupt`;
+  `r(907)` → `stata_limit`; `r(950)` → `out_of_memory`; numlist `r(124)`–`r(127)`
+  → `syntax`.
+- **Remediation suggestions for more error kinds.** `suggestions_for()` now
+  emits actionable hints for `network`, `infeasible`, `type_mismatch`,
+  `file_io`, `file_corrupt`, `permission`, `estimation_failure`, and
+  `matrix_missing`, so nearly every common failure ships a recovery hint.
+
+## 0.8.1 — 2026-06-20
+
+### Changed
+
+- **README & metadata refresh.** Documented the VS Code extension's
+  seven-view sidebar (added the **Data** variables browser and the
+  **Outputs** table/export-artifact panel), corrected the error taxonomy
+  count to 31 kinds, and sharpened the Claude Code plugin / VS Code
+  Marketplace descriptions to lead with the empirical-economics workflow
+  (DiD/IV/RDD, publication tables, StatsPAI cross-validation).
+- **Partner module.** Added a Stanford REAP × CoPaper.AI partner block
+  (logos, QR, links) to both the English and Chinese README, with the logo
+  assets bundled under `branding/partners/`.
+
 ## 0.8.0 — 2026-06-20
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stata-code
-Version: 0.8.0
+Version: 0.9.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
@@ -59,6 +59,24 @@ Description-Content-Type: text/markdown
 [![GitHub release](https://img.shields.io/github/v/release/brycewang-stanford/stata-code)](https://github.com/brycewang-stanford/stata-code/releases)
 [![GitHub stars](https://img.shields.io/github/stars/brycewang-stanford/stata-code?style=social)](https://github.com/brycewang-stanford/stata-code)
 
+<div align="center">
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://copaper.ai"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/copaper-logo.png" alt="CoPaper.AI" width="200" /></a>
+    </td>
+    <td width="48"></td>
+    <td align="center">
+      <a href="https://sccei.fsi.stanford.edu/reap"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/stanford-reap-logo.png" alt="Stanford REAP — Center on China's Economy & Institutions" width="280" /></a>
+    </td>
+  </tr>
+</table>
+
+<sub><strong>Stanford REAP × CoPaper.AI</strong> · an academic–industrial AI toolkit for empirical research</sub>
+
+</div>
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/github-instructions.png" alt="stata-code: agent-native Stata bridge — one Python core, multiple frontends (Jupyter kernel, MCP server, VS Code extension)" width="720" />
 </p>
@@ -166,12 +184,14 @@ Verify the local setup with the read-only doctor:
 stata-code doctor
 stata-code doctor --json          # machine-readable output
 stata-code doctor --no-stata-probe # skip live Stata initialization
+stata-code doctor --workspace /path/to/project --no-user-config-scan
 ```
 
 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.
+discovery, console scripts on `PATH`, common project/user MCP client config
+files, client/VS Code configuration hints, and a best-effort Stata
+version/edition probe. It never edits shell, Stata, Claude, Cursor, or VS Code
+config.
 
 ---
 
@@ -385,7 +405,7 @@ Then open Jupyter Notebook / JupyterLab (or a `.ipynb` in VS Code), pick **Stata
 
 ### As a VS Code Extension
 
-The companion extension is on the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode). It spawns `stata-code-mcp` as a child process and adds syntax highlighting, an Outline view for `**#` sections and `program define` blocks, code-lens "Run cell" and "Run section" actions on `.do` files, a sidebar (sessions / last result / run history / logs / graphs), status-bar indicators, completions, help lookup, conservative variable rename, and inline diagnostics from the v1.0 typed errors.
+The companion extension is on the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode). It spawns `stata-code-mcp` as a child process and adds syntax highlighting, an Outline view for `**#` sections and `program define` blocks, code-lens "Run cell" and "Run section" actions on `.do` files, a **seven-view sidebar** (sessions / last result / **data variables** / run history / logs / graphs / **outputs**) — including an agent-native equivalent of Stata's **Variables window** and an **Outputs** panel that surfaces the `esttab` tables and `export` files each run writes to disk — status-bar indicators, completions, help lookup, conservative variable rename, and inline diagnostics from the v1.0 typed errors.
 
 ```bash
 # from the VS Code CLI
@@ -400,7 +420,9 @@ 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.
+your shell. It also reads common MCP config files in the current workspace and
+user config directories so you can see whether a client is already wired to
+`stata-code`.
 
 #### Cell and section conventions
 
@@ -481,7 +503,7 @@ stata_code/
 | Jupyter kernel | ✓ | — | — | ✓ |
 | Unified result schema | ✓ ([SCHEMA.md](SCHEMA.md)) | per-tool | per-tool | per-tool |
 | Token-economy defaults | ✓ (log refs, graph refs) | — | — | — |
-| Typed errors + suggestions | ✓ (32 kinds) | — | — | — |
+| Typed errors + suggestions | ✓ (31 kinds) | — | — | — |
 | Multi-session | ✓ (Stata frames) | partial | — | — |
 | Mature ecosystem | early | ✓ (statamcp.com, cookbook) | ✓ (11k installs) | ✓ |
 
@@ -500,7 +522,7 @@ stata_code/
 - Graph capture: `png` / `svg` / `pdf` with ref store and source-command attribution
 - Log truncation with ref store
 - Warning extraction: 5 categories + generic notes
-- 32-kind error taxonomy with canonical suggestions
+- 31-kind error taxonomy with canonical suggestions
 - 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)
@@ -514,7 +536,7 @@ stata_code/
   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
+- 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, seven-view sidebar (sessions / last result / data variables / run history / logs / graphs / outputs), status bar, completions, conservative variable rename, diagnostics, MCP child-process spawn
 - Clean-room license policy ([LICENSE-POLICY.md](LICENSE-POLICY.md))
 
 ### Next Up
@@ -560,3 +582,36 @@ Stata is a registered trademark of StataCorp LLC. This project is independent an
 ## Acknowledgements
 
 The Stata tooling landscape that this project builds on and learns from is surveyed in [References-tools.md](References-tools.md). All listed projects retain their own licenses and authorship; please consult each repository before reuse.
+
+---
+
+<div align="center">
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://copaper.ai"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/copaper-logo.png" alt="CoPaper.AI" width="200" /></a>
+    </td>
+    <td width="40"></td>
+    <td align="center">
+      <a href="https://sccei.fsi.stanford.edu/reap"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/stanford-reap-logo.png" alt="Stanford REAP" width="280" /></a>
+    </td>
+  </tr>
+</table>
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://copaper.ai"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/copaper-qrcode.png" alt="Visit copaper.ai" width="160" /></a><br/>
+      <strong>Visit <a href="https://copaper.ai">copaper.ai</a></strong>
+    </td>
+    <td align="center">
+      <img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/copaper-wechat.jpg" alt="CoPaper.AI WeChat" width="160" /><br/>
+      <strong>WeChat: CoPaper.AI</strong>
+    </td>
+  </tr>
+</table>
+
+<sub>Maintained by <a href="https://copaper.ai"><strong>CoPaper.AI</strong></a>, incubated at <a href="https://sccei.fsi.stanford.edu/reap"><strong>Stanford REAP / SCCEI</strong></a> · AI Assistant for Empirical Research</sub>
+
+</div>

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

@@ -20,6 +20,24 @@
 [![GitHub release](https://img.shields.io/github/v/release/brycewang-stanford/stata-code)](https://github.com/brycewang-stanford/stata-code/releases)
 [![GitHub stars](https://img.shields.io/github/stars/brycewang-stanford/stata-code?style=social)](https://github.com/brycewang-stanford/stata-code)
 
+<div align="center">
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://copaper.ai"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/copaper-logo.png" alt="CoPaper.AI" width="200" /></a>
+    </td>
+    <td width="48"></td>
+    <td align="center">
+      <a href="https://sccei.fsi.stanford.edu/reap"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/stanford-reap-logo.png" alt="Stanford REAP — Center on China's Economy & Institutions" width="280" /></a>
+    </td>
+  </tr>
+</table>
+
+<sub><strong>Stanford REAP × CoPaper.AI</strong> · an academic–industrial AI toolkit for empirical research</sub>
+
+</div>
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/github-instructions.png" alt="stata-code: agent-native Stata bridge — one Python core, multiple frontends (Jupyter kernel, MCP server, VS Code extension)" width="720" />
 </p>
@@ -127,12 +145,14 @@ Verify the local setup with the read-only doctor:
 stata-code doctor
 stata-code doctor --json          # machine-readable output
 stata-code doctor --no-stata-probe # skip live Stata initialization
+stata-code doctor --workspace /path/to/project --no-user-config-scan
 ```
 
 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.
+discovery, console scripts on `PATH`, common project/user MCP client config
+files, client/VS Code configuration hints, and a best-effort Stata
+version/edition probe. It never edits shell, Stata, Claude, Cursor, or VS Code
+config.
 
 ---
 
@@ -346,7 +366,7 @@ Then open Jupyter Notebook / JupyterLab (or a `.ipynb` in VS Code), pick **Stata
 
 ### As a VS Code Extension
 
-The companion extension is on the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode). It spawns `stata-code-mcp` as a child process and adds syntax highlighting, an Outline view for `**#` sections and `program define` blocks, code-lens "Run cell" and "Run section" actions on `.do` files, a sidebar (sessions / last result / run history / logs / graphs), status-bar indicators, completions, help lookup, conservative variable rename, and inline diagnostics from the v1.0 typed errors.
+The companion extension is on the Marketplace as [`brycewang-stanford.stata-code-vscode`](https://marketplace.visualstudio.com/items?itemName=brycewang-stanford.stata-code-vscode). It spawns `stata-code-mcp` as a child process and adds syntax highlighting, an Outline view for `**#` sections and `program define` blocks, code-lens "Run cell" and "Run section" actions on `.do` files, a **seven-view sidebar** (sessions / last result / **data variables** / run history / logs / graphs / **outputs**) — including an agent-native equivalent of Stata's **Variables window** and an **Outputs** panel that surfaces the `esttab` tables and `export` files each run writes to disk — status-bar indicators, completions, help lookup, conservative variable rename, and inline diagnostics from the v1.0 typed errors.
 
 ```bash
 # from the VS Code CLI
@@ -361,7 +381,9 @@ 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.
+your shell. It also reads common MCP config files in the current workspace and
+user config directories so you can see whether a client is already wired to
+`stata-code`.
 
 #### Cell and section conventions
 
@@ -442,7 +464,7 @@ stata_code/
 | Jupyter kernel | ✓ | — | — | ✓ |
 | Unified result schema | ✓ ([SCHEMA.md](SCHEMA.md)) | per-tool | per-tool | per-tool |
 | Token-economy defaults | ✓ (log refs, graph refs) | — | — | — |
-| Typed errors + suggestions | ✓ (32 kinds) | — | — | — |
+| Typed errors + suggestions | ✓ (31 kinds) | — | — | — |
 | Multi-session | ✓ (Stata frames) | partial | — | — |
 | Mature ecosystem | early | ✓ (statamcp.com, cookbook) | ✓ (11k installs) | ✓ |
 
@@ -461,7 +483,7 @@ stata_code/
 - Graph capture: `png` / `svg` / `pdf` with ref store and source-command attribution
 - Log truncation with ref store
 - Warning extraction: 5 categories + generic notes
-- 32-kind error taxonomy with canonical suggestions
+- 31-kind error taxonomy with canonical suggestions
 - 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)
@@ -475,7 +497,7 @@ stata_code/
   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
+- 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, seven-view sidebar (sessions / last result / data variables / run history / logs / graphs / outputs), status bar, completions, conservative variable rename, diagnostics, MCP child-process spawn
 - Clean-room license policy ([LICENSE-POLICY.md](LICENSE-POLICY.md))
 
 ### Next Up
@@ -521,3 +543,36 @@ Stata is a registered trademark of StataCorp LLC. This project is independent an
 ## Acknowledgements
 
 The Stata tooling landscape that this project builds on and learns from is surveyed in [References-tools.md](References-tools.md). All listed projects retain their own licenses and authorship; please consult each repository before reuse.
+
+---
+
+<div align="center">
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://copaper.ai"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/copaper-logo.png" alt="CoPaper.AI" width="200" /></a>
+    </td>
+    <td width="40"></td>
+    <td align="center">
+      <a href="https://sccei.fsi.stanford.edu/reap"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/stanford-reap-logo.png" alt="Stanford REAP" width="280" /></a>
+    </td>
+  </tr>
+</table>
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://copaper.ai"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/copaper-qrcode.png" alt="Visit copaper.ai" width="160" /></a><br/>
+      <strong>Visit <a href="https://copaper.ai">copaper.ai</a></strong>
+    </td>
+    <td align="center">
+      <img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/copaper-wechat.jpg" alt="CoPaper.AI WeChat" width="160" /><br/>
+      <strong>WeChat: CoPaper.AI</strong>
+    </td>
+  </tr>
+</table>
+
+<sub>Maintained by <a href="https://copaper.ai"><strong>CoPaper.AI</strong></a>, incubated at <a href="https://sccei.fsi.stanford.edu/reap"><strong>Stanford REAP / SCCEI</strong></a> · AI Assistant for Empirical Research</sub>
+
+</div>

{stata_code-0.8.0 → stata_code-0.9.0}/SCHEMA.md

@@ -77,7 +77,38 @@ Every successful or failed Stata execution returns one result object:
         }
       }
     },
-    "last_estimation_cmd": "regress"
+    "last_estimation_cmd": "regress",
+    "estimation": {
+      "command": "regress",
+      "depvar": "mpg",
+      "n_obs": 74,
+      "df_model": 1,
+      "df_resid": null,
+      "statistic_kind": "z",
+      "source": "e_b_v",
+      "ci_level": 95.0,
+      "coefficients": [
+        {
+          "term": "weight",
+          "b": -0.006,
+          "se": null,
+          "statistic": null,
+          "p_value": null,
+          "ci_low": null,
+          "ci_high": null
+        },
+        {
+          "term": "_cons",
+          "b": 39.44,
+          "se": null,
+          "statistic": null,
+          "p_value": null,
+          "ci_low": null,
+          "ci_high": null
+        }
+      ],
+      "model_stats": {"N": 74, "df_m": 1, "r2": 0.219}
+    }
   },
 
   "dataset": {
@@ -140,7 +171,8 @@ A failed execution sets `ok: false`, `rc != 0`, and populates `error`:
 
   "results": { "r": {"scalars": {}, "macros": {}, "matrices": {}},
                "e": {"scalars": {}, "macros": {}, "matrices": {}},
-               "last_estimation_cmd": null },
+               "last_estimation_cmd": null,
+               "estimation": null },
 
   "dataset": { "frame": "default", "n_obs": 74, "n_vars": 12, "changed": false,
                "filename": "auto.dta", "variables": null },
@@ -167,7 +199,13 @@ A failed execution sets `ok: false`, `rc != 0`, and populates `error`:
     "suggestions": [
       {"action": "Check the variable name. Did you mean `mpg`?",
        "command": "describe"}
-    ]
+    ],
+    "recovery": {
+      "category": "user_code",
+      "retriable": false,
+      "needs_code_change": true,
+      "needs_user_input": false
+    }
   },
 
   "schema_version": "1.0",
@@ -315,6 +353,34 @@ Stata's `r()` and `e()` return dictionaries, structurally separated. Each follow
 | Field | Type | Notes |
 | --- | --- | --- |
 | `last_estimation_cmd` | `string \| null` | Mirrors `e(cmd)` for callers who don't want to dig into `e.macros`. After multi-command code, this reflects the *last* command that wrote to `e()`. `null` if no estimation has been performed. |
+| `estimation` | `EstimationResult \| null` | Typed coefficient table derived from `r(table)` or `e(b)` / `e(V)`. `null` when no inline `e(b)` is available. |
+
+**`EstimationResult` shape:**
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `command` | `string \| null` | Mirrors `e(cmd)` when available; falls back to `last_estimation_cmd`. |
+| `depvar` | `string \| null` | Mirrors `e(depvar)`. |
+| `n_obs` | `int \| null` | Integer form of `e(N)` when available. |
+| `df_model` | `number \| null` | Mirrors `e(df_m)`. |
+| `df_resid` | `number \| null` | Mirrors `e(df_r)`. |
+| `statistic_kind` | `"t" \| "z"` | Which statistic fills each coefficient's `statistic` field. |
+| `source` | `"r_table" \| "e_b_v"` | `r_table` means values were copied from Stata's displayed `r(table)` after verifying its columns and `b` row match `e(b)`; `e_b_v` means point estimates come from `e(b)` and inference, when present, is computed from `e(V)` with a normal approximation. |
+| `ci_level` | `number` | Confidence level used for `ci_low` / `ci_high`; currently `95.0`. |
+| `coefficients` | `array<Coefficient>` | One row per term in `e(b)`. |
+| `model_stats` | `dict<str, number \| null>` | High-signal subset of `e()` scalars such as `N`, `df_m`, `df_r`, `r2`, `F`, `chi2`, `ll`, and `rmse`. Full scalars remain under `results.e.scalars`. |
+
+**`Coefficient` shape:**
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `term` | `string` | Term / coefficient column name. |
+| `b` | `number \| null` | Point estimate. |
+| `se` | `number \| null` | Standard error when available. |
+| `statistic` | `number \| null` | `t` or `z`, per `EstimationResult.statistic_kind`. |
+| `p_value` | `number \| null` | Two-sided p-value when available. |
+| `ci_low` | `number \| null` | Lower confidence interval bound when available. |
+| `ci_high` | `number \| null` | Upper confidence interval bound when available. |
 
 **Empty is empty.** Sub-dicts are `{}` when Stata returned nothing — never absent, never `null`.
 
@@ -377,6 +443,7 @@ Populated iff `ok: false`. The schema's most important contribution to agent UX:
 | `varname` | `string \| null` | For `varname_not_found` and related, the variable name at issue. |
 | `name` | `string \| null` | For `name_conflict` and `invalid_name`, the conflicting/invalid name. |
 | `suggestions` | `array<Suggestion>` | Producer-supplied remediation hints. Empty when none apply. See below. |
+| `recovery` | `Recovery \| null` | Machine-readable recovery contract for agents. Present on current producers; old or third-party producers may omit it, so consumers should handle `null`. |
 
 **`context` shape:**
 
@@ -399,36 +466,47 @@ Populated iff `ok: false`. The schema's most important contribution to agent UX:
 
 Suggestions are best-effort; agents should treat them as hints, not directives. A suggestion is not consent to mutate source files or silently retry changed code; consumers should apply fixes automatically only in workflows where the user requested repair or approved iteration. The `kind` enum below documents what suggestions are typically populated.
 
+**`Recovery` shape:**
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `category` | `"user_code" \| "data" \| "model" \| "resource" \| "environment" \| "internal" \| "unknown"` | Broad failure domain for routing. |
+| `retriable` | `bool` | Whether re-running the exact same code may succeed. True mainly for transient environment or producer-side failures. |
+| `needs_code_change` | `bool` | Whether the submitted Stata code must change to succeed. |
+| `needs_user_input` | `bool` | Whether resolution likely requires a human or out-of-band action such as permissions, license/edition limits, or re-acquiring a corrupt file. |
+
 **`kind` enum (v1.0):**
 
+rc(s) below cite StataCorp `[P] error` (Stata 19, 2025). The code is authoritative; this table is a readable mirror.
+
 | `kind` | Typical rc(s) | Notes / suggestion seed |
 | --- | --- | --- |
-| `syntax` | 9, 100, 101, 102, 103, 121, 130, 132, 197, 198 | Generic parser failure. No automatic suggestion. |
+| `syntax` | 100, 101, 102, 103, 121–127, 130, 132, 197, 198 | Generic parser failure (incl. numlist errors 121–127). No automatic suggestion. |
 | `command_not_found` | 199 | Often resolved by `ssc install` or `net install`; suggestions populated when Stata reports a likely package name. |
 | `varname_not_found` | 111 | `varname` populated. Suggestions may include similar varnames from `dataset.variables`. |
-| `invalid_name` | 122, 123 | `name` populated. |
-| `type_mismatch` | 109, 408 | |
+| `invalid_name` | (no dedicated rc) | Stata folds "invalid name" into r(198). `name` populated when constructed by a producer. |
+| `type_mismatch` | 109, 408 | Suggestion: `destring`/`tostring`. |
 | `name_conflict` | 110 | `name` populated. Suggestion typically: `replace`. |
-| `not_sorted` | 119, 459 | Suggestion: `sort <varlist>`. |
+| `not_sorted` | 5 | Suggestion: `sort <varlist>`. |
 | `convergence` | 430 | |
-| `infeasible` | 491 | Distinct from convergence: starting values not feasible. |
-| `estimation_sample_empty` | 1400, 2000 (in estimation context) | |
-| `estimation_failure` | 1401, 1402 | |
+| `infeasible` | 480, 491 | Distinct from convergence: starting values not feasible (e.g. `nl`, `ml`). |
+| `estimation_sample_empty` | (no dedicated rc) | Empty estimation samples surface as r(2000); producer-set otherwise. |
+| `estimation_failure` | 322, 1400, 1401, 1402 | Postestimation/prefix saw an unexpected result, or numerical overflow. |
 | `no_estimation_results` | 301 | Common when calling `predict`/`margins` without prior estimation. |
 | `no_observations` | 2000, 2001 | |
 | `data_in_memory` | 4 | Suggestion: `clear`. |
 | `matrix_singular` | 506, 508 | Matrix not positive definite / not invertible. |
-| `matrix_conformability` | 503, 507 | Dimension mismatch. |
+| `matrix_conformability` | 503, 507 | Dimension mismatch; 507 is a `matrix post` row/col name conflict kept in the matrix bucket. |
 | `matrix_missing` | 504 | Matrix has missing values. |
-| `file_not_found` | 322, 601 | `path` populated. |
+| `file_not_found` | 601 | `path` populated. |
 | `file_exists` | 602 | `path` populated. Suggestion: pass `replace` option. |
-| `file_corrupt` | 604, 610 | `path` populated. Often "not a Stata file." |
-| `file_io` | 603, 691 (local) | `path` populated. Catch-all for open/read/write failures not otherwise classified. |
-| `network` | 691 (network), 692, 693 | URL fetches, network reads. |
-| `permission` | 608 | `path` populated. Includes Stata-license-limit errors (615/616 family that surface as permission denials). |
-| `encoding` | 615, 616 | Unicode / encoding-conversion failures. |
-| `stata_limit` | 901, 902, 903 | Edition / matsize / similar Stata-imposed caps. Distinct from OS OOM. Suggestion: `set maxvar` or upgrade edition. |
-| `out_of_memory` | 480, 909 | OS-level memory exhaustion. |
+| `file_corrupt` | 610, 688 | `path` populated. "Not a Stata file" (610) or genuinely corrupt (688). |
+| `file_io` | 603, 691, 692, 693 | `path` populated. Catch-all for open/read/write failures (691–693 are local filesystem I/O). |
+| `network` | 2, 631, 672, 677 | Connection timed out / host not found / server refused / remote connection failed. |
+| `permission` | 608 | `path` populated. File is read-only / not writable. |
+| `encoding` | (no dedicated rc) | Unicode / encoding-conversion failures; producer-set. |
+| `stata_limit` | 901, 902, 903, 907 | Edition / maxvar / width caps. Distinct from OS OOM. Suggestion: `set maxvar` or upgrade edition. |
+| `out_of_memory` | 909, 950 | OS-level memory exhaustion. Suggestion: `compress`. |
 | `interrupt` | 1 | User Break / Ctrl-C from a frontend. |
 | `cancelled` | (synthetic `rc: -3`) | Cancellation was requested. Subprocess-backed producers may terminate an in-flight worker; the direct in-process runner only short-circuits before Stata receives code. |
 | `timeout` | (synthetic `rc: -2`) | Adapter-imposed time limit exceeded. |
@@ -607,6 +685,8 @@ This section tracks how much of the schema is wired up in code. Not normative
   emit a `matrix://<request_id>/<r|e>/<name>` ref instead, retrievable
   via `get_matrix(ref)`.
 - `results.last_estimation_cmd` (mirrors `e(cmd)`).
+- `results.estimation` typed coefficient table, copied from verified
+  `r(table)` when possible and otherwise derived from inline `e(b)` / `e(V)`.
 - `dataset` block — `n_obs`, `n_vars`, `frame`, `changed`, `filename`,
   and `variables` (capped at 200 entries).
 - `graphs[]` with `ref` + on-disk capture pipeline; format restricted to
@@ -617,7 +697,8 @@ This section tracks how much of the schema is wired up in code. Not normative
   extracted from Stata's English error text by regex, structured
   `context` (`{before, failing, after}`), `commands_executed` parsed
   from pystata's multi-line transcript, `suggestions` generated by
-  `core.errors.suggestions_for`.
+  `core.errors.suggestions_for`, and `recovery` generated by
+  `core.errors.recovery_for`.
 - `request_id` (uuid4 hex), `started_at` (ISO 8601 UTC ms),
   `stata_elapsed_ms`, `capabilities`.
 - Multi-session via Stata frames — `session_id="main"` ↔ `default`