tabletalk 0.4.0__tar.gz → 0.6.0__tar.gz

{tabletalk-0.4.0 → tabletalk-0.6.0}/.github/workflows/db_provider_tests.yml

@@ -75,8 +75,21 @@ jobs:
           with ZipFile(wheel) as archive:
               names = archive.namelist()
           assert not any("/tests/" in name for name in names)
-          assert not any(".data/data/tabletalk/static/" in name for name in names)
-          assert "tabletalk/static/index.html" in names
+          assert not any("tabletalk/static/" in name for name in names)
+          assert "tabletalk/app.py" not in names
+          for required in (
+              "tabletalk/agents.py",
+              "tabletalk/evals/__init__.py",
+              "tabletalk/manifest.py",
+              "tabletalk/project.py",
+              "tabletalk/runtime/__init__.py",
+              "tabletalk/validation.py",
+          ):
+              assert required in names, f"missing wheel module: {required}"
+          for license_name in ("LICENSE", "LICENSE_HISTORY.md", "COMMERCIAL-LICENSE.md"):
+              assert any(name.endswith("licenses/" + license_name) for name in names), (
+                  f"missing wheel license file: {license_name}"
+              )
           PY
           uv venv .package-test
           uv pip install --python .package-test/bin/python dist/*.whl

{tabletalk-0.4.0 → tabletalk-0.6.0}/.github/workflows/publish.yml

@@ -46,13 +46,21 @@ jobs:
           with ZipFile(wheel) as archive:
               names = archive.namelist()
           assert not any("/tests/" in name for name in names)
-          assert not any(".data/data/tabletalk/static/" in name for name in names)
+          assert not any("tabletalk/static/" in name for name in names)
+          assert "tabletalk/app.py" not in names
           for required in (
-              "tabletalk/static/index.html",
-              "tabletalk/static/app.js",
-              "tabletalk/static/styles.css",
+              "tabletalk/agents.py",
+              "tabletalk/evals/__init__.py",
+              "tabletalk/manifest.py",
+              "tabletalk/project.py",
+              "tabletalk/runtime/__init__.py",
+              "tabletalk/validation.py",
           ):
-              assert required in names, f"missing wheel asset: {required}"
+              assert required in names, f"missing wheel module: {required}"
+          for license_name in ("LICENSE", "LICENSE_HISTORY.md", "COMMERCIAL-LICENSE.md"):
+              assert any(name.endswith("licenses/" + license_name) for name in names), (
+                  f"missing wheel license file: {license_name}"
+              )
           PY
 
       - name: Verify wheel installation

{tabletalk-0.4.0 → tabletalk-0.6.0}/.gitignore

@@ -71,6 +71,7 @@ examples/ecommerce/evals/fixtures/*.duckdb
 __pycache__
 
 # TableTalk generated output and per-user runtime state
+.tabletalk/
 /examples/*/manifest/
 .tabletalk_history.jsonl
 .tabletalk_favorites.json
@@ -81,6 +82,8 @@ __pycache__
 
 # dbt generated and per-user state
 .user.yml
+dbt_packages/
+logs/
 /examples/*/dbt_project/dbt_packages/
 /examples/*/dbt_project/logs/
 
@@ -145,6 +148,12 @@ docs/_build/
 .pybuilder/
 target/
 
+# The reference project's manifest is a dbt-generated acceptance fixture.
+!examples/dbt-analytics/target/
+examples/dbt-analytics/target/*
+!examples/dbt-analytics/target/manifest.json
+!examples/dbt-analytics/target/catalog.json
+
 # Jupyter Notebook
 .ipynb_checkpoints
 

tabletalk-0.6.0/COMMERCIAL-LICENSE.md

@@ -0,0 +1,12 @@
+# Commercial licensing
+
+The source code in this repository is available under the
+[PolyForm Noncommercial License 1.0.0](LICENSE). That license permits the
+personal and noncommercial uses described in its terms. It does not grant
+commercial-use rights.
+
+William Bates offers implementation, integration, semantic onboarding, and
+custom eval-suite development. Commercial use requires separate written
+permission. Contact [William Bates](mailto:wbates@palanbates.com).
+
+This notice is not itself a commercial license or an offer of specific terms.

tabletalk-0.6.0/LICENSE

@@ -0,0 +1,133 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+**As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.**
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+Required Notice: Copyright 2026 William Bates.

tabletalk-0.6.0/LICENSE_HISTORY.md

@@ -0,0 +1,9 @@
+# License history
+
+Earlier TableTalk revisions and releases were offered under Creative Commons
+Attribution-NonCommercial-NoDerivatives 4.0 terms. Those grants remain in
+effect for the revisions to which they applied.
+
+Revisions committed on or after August 9, 2026 are offered under the
+[PolyForm Noncommercial License 1.0.0](LICENSE). Commercial use of those
+revisions requires a separate written agreement.

tabletalk-0.6.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: tabletalk
+Version: 0.6.0
+Summary: dbt-native development, evaluation, and observability for trusted data agents
+Project-URL: Homepage, https://github.com/wtbates99/tabletalk
+Project-URL: Repository, https://github.com/wtbates99/tabletalk
+Project-URL: Commercial License, https://github.com/wtbates99/tabletalk/blob/main/COMMERCIAL-LICENSE.md
+Author-email: William Bates <wbates@palanbates.com>
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: COMMERCIAL-LICENSE.md
+License-File: LICENSE
+License-File: LICENSE_HISTORY.md
+Keywords: data-agents,dbt,evaluation,llm,observability,sql
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: sqlglot>=25.0
+Provides-Extra: all
+Requires-Dist: duckdb>=0.9; extra == 'all'
+Requires-Dist: snowflake-connector-python>=3.0; extra == 'all'
+Provides-Extra: duckdb
+Requires-Dist: duckdb>=0.9; extra == 'duckdb'
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python>=3.0; extra == 'snowflake'
+Description-Content-Type: text/markdown
+
+# TableTalk
+
+**Mount a dbt project. Review proposed agents and evaluations. Prove that your data agents are safe, grounded, and correct.**
+
+[![Tests](https://github.com/wtbates99/tabletalk/actions/workflows/db_provider_tests.yml/badge.svg)](https://github.com/wtbates99/tabletalk/actions/workflows/db_provider_tests.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/tabletalk)](https://pypi.org/project/tabletalk/)
+[![License](https://img.shields.io/badge/license-PolyForm%20Noncommercial-c9a84c)](LICENSE)
+
+TableTalk is the dbt-native development, evaluation, and observability layer for
+trusted data agents. It uses the analytical knowledge that a company already
+maintains in dbt. It creates reproducible agents and defensible evaluation
+evidence. It does not require a second large semantic configuration system.
+
+TableTalk is not a general agent framework. It is not a BI dashboard. It does
+not replace dbt.
+
+## What TableTalk proves
+
+- `manifest.json` defines the queryable resources.
+- Agent files contain dbt selectors and small TableTalk policies.
+- Every agent and eval starts as a review-only proposal.
+- Approval binds the exact proposal, manifest, base files, and resource bytes.
+- Trusted semantic statements record source evidence.
+- Inferred statements remain untrusted until a user confirms them.
+- SQL validation runs before every read-only warehouse query.
+- Live questions and evals use the same runtime.
+- Approved reference queries provide changing-data ground truth.
+- Inference artifacts support strict replay with no model request.
+- Reports include hard checks, trial metrics, uncertainty, paired comparisons,
+  and failure ownership.
+
+## Install
+
+```console
+pip install tabletalk
+pip install "tabletalk[duckdb]"
+pip install "tabletalk[snowflake]"
+```
+
+TableTalk requires Python 3.10 or newer. SQLite uses the Python standard
+library. The initial warehouse adapters are SQLite, DuckDB, and Snowflake.
+
+## Start from an existing dbt project
+
+```console
+cd my-dbt-project
+dbt parse
+dbt docs generate
+tabletalk init
+tabletalk propose
+tabletalk approve
+tabletalk eval run
+tabletalk ask revenue "What was recognized revenue last month?"
+```
+
+`tabletalk propose` analyzes dbt groups, tags, packages, paths, owners, access,
+metrics, semantic models, tests, constraints, descriptions, and lineage. It
+creates at most three coherent proposals. It prefers curated marts. It shows
+semantic gaps and exact file diffs. It does not write project resources.
+
+The approval command requires the exact proposal digest for automated use:
+
+```console
+tabletalk approve prp_EXAMPLE \
+  --yes \
+  --digest sha256:EXAMPLE \
+  --actor "$USER"
+```
+
+Approval fails if the manifest or a reviewed base file changed. TableTalk runs
+approved evals immediately.
+
+## Acquire missing meaning
+
+Provide a targeted answer:
+
+```console
+tabletalk propose \
+  --answer "time_basis:model.analytics.orders.booked_revenue=booked_date"
+```
+
+Preview an organizational query as evidence:
+
+```console
+tabletalk propose --sql-import finance/revenue.sql
+```
+
+Request optional model hypotheses:
+
+```console
+tabletalk propose --infer
+```
+
+TableTalk marks every model hypothesis as inferred. An inferred statement cannot
+support an answer. A user must confirm its meaning through a new proposal.
+
+## Evaluate and replay
+
+```console
+tabletalk eval run revenue --trials 3 --workers 2
+tabletalk eval run revenue --trials 3 --cache-policy replay
+tabletalk eval run revenue --baseline revenue-v1
+```
+
+Each run writes a concise terminal result and three detailed artifacts:
+
+- versioned JSON for tools
+- JUnit XML for CI
+- Markdown for a pull request.
+
+The report identifies the model, agent, manifest, semantic knowledge, prompt,
+runtime, warehouse, and inference fingerprint. It reports pass rate, a Wilson
+confidence interval, latency, tokens, configured cost, flaky outcomes, and
+deterministic failure diagnoses.
+
+## Security and retention
+
+- Use a warehouse identity with physical read-only permissions.
+- Treat connector permissions as the final security boundary.
+- TableTalk rejects writes, unsafe reads, unknown resources, unknown columns,
+  unsafe joins, excessive limits, and unapproved sensitive data.
+- TableTalk never treats lineage as proof that a join is correct.
+- TableTalk does not store credentials in traces, reports, or fingerprints.
+- Inference artifacts hash prompts by default. Set `persist_prompts: true` only
+  when exact raw-prompt retention is acceptable.
+- Traces and reports retain bounded evidence rows. Exact evidence is required
+  for deterministic replay and claim validation.
+- TableTalk does not delete artifacts automatically. The operator must apply a
+  retention policy to `.tabletalk/`.
+
+See the [commerce example](examples/dbt-analytics/README.md), the
+[getting-started guide](docs/getting-started.md), and the
+[research evidence](docs/research.md).
+
+## Development
+
+```console
+uv sync --locked --all-groups
+uv run pytest -q
+uv run ruff check tabletalk
+uv run mypy tabletalk
+uv build
+```
+
+The live Ollama smoke test is opt-in. It uses only `gemma4:31b-cloud`:
+
+```console
+TABLETALK_LIVE_OLLAMA=1 uv run pytest -m live_ollama
+```
+
+## License and services
+
+TableTalk is source-available under the
+[PolyForm Noncommercial License 1.0.0](LICENSE). The license permits the uses
+that its text defines. Commercial use requires separate written permission.
+
+William Bates offers implementation, integration, semantic onboarding, and
+custom eval-suite development. See the
+[commercial notice](COMMERCIAL-LICENSE.md). Earlier releases keep their earlier
+license grants. See [LICENSE_HISTORY.md](LICENSE_HISTORY.md).

tabletalk-0.6.0/README.md

@@ -0,0 +1,161 @@
+# TableTalk
+
+**Mount a dbt project. Review proposed agents and evaluations. Prove that your data agents are safe, grounded, and correct.**
+
+[![Tests](https://github.com/wtbates99/tabletalk/actions/workflows/db_provider_tests.yml/badge.svg)](https://github.com/wtbates99/tabletalk/actions/workflows/db_provider_tests.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/tabletalk)](https://pypi.org/project/tabletalk/)
+[![License](https://img.shields.io/badge/license-PolyForm%20Noncommercial-c9a84c)](LICENSE)
+
+TableTalk is the dbt-native development, evaluation, and observability layer for
+trusted data agents. It uses the analytical knowledge that a company already
+maintains in dbt. It creates reproducible agents and defensible evaluation
+evidence. It does not require a second large semantic configuration system.
+
+TableTalk is not a general agent framework. It is not a BI dashboard. It does
+not replace dbt.
+
+## What TableTalk proves
+
+- `manifest.json` defines the queryable resources.
+- Agent files contain dbt selectors and small TableTalk policies.
+- Every agent and eval starts as a review-only proposal.
+- Approval binds the exact proposal, manifest, base files, and resource bytes.
+- Trusted semantic statements record source evidence.
+- Inferred statements remain untrusted until a user confirms them.
+- SQL validation runs before every read-only warehouse query.
+- Live questions and evals use the same runtime.
+- Approved reference queries provide changing-data ground truth.
+- Inference artifacts support strict replay with no model request.
+- Reports include hard checks, trial metrics, uncertainty, paired comparisons,
+  and failure ownership.
+
+## Install
+
+```console
+pip install tabletalk
+pip install "tabletalk[duckdb]"
+pip install "tabletalk[snowflake]"
+```
+
+TableTalk requires Python 3.10 or newer. SQLite uses the Python standard
+library. The initial warehouse adapters are SQLite, DuckDB, and Snowflake.
+
+## Start from an existing dbt project
+
+```console
+cd my-dbt-project
+dbt parse
+dbt docs generate
+tabletalk init
+tabletalk propose
+tabletalk approve
+tabletalk eval run
+tabletalk ask revenue "What was recognized revenue last month?"
+```
+
+`tabletalk propose` analyzes dbt groups, tags, packages, paths, owners, access,
+metrics, semantic models, tests, constraints, descriptions, and lineage. It
+creates at most three coherent proposals. It prefers curated marts. It shows
+semantic gaps and exact file diffs. It does not write project resources.
+
+The approval command requires the exact proposal digest for automated use:
+
+```console
+tabletalk approve prp_EXAMPLE \
+  --yes \
+  --digest sha256:EXAMPLE \
+  --actor "$USER"
+```
+
+Approval fails if the manifest or a reviewed base file changed. TableTalk runs
+approved evals immediately.
+
+## Acquire missing meaning
+
+Provide a targeted answer:
+
+```console
+tabletalk propose \
+  --answer "time_basis:model.analytics.orders.booked_revenue=booked_date"
+```
+
+Preview an organizational query as evidence:
+
+```console
+tabletalk propose --sql-import finance/revenue.sql
+```
+
+Request optional model hypotheses:
+
+```console
+tabletalk propose --infer
+```
+
+TableTalk marks every model hypothesis as inferred. An inferred statement cannot
+support an answer. A user must confirm its meaning through a new proposal.
+
+## Evaluate and replay
+
+```console
+tabletalk eval run revenue --trials 3 --workers 2
+tabletalk eval run revenue --trials 3 --cache-policy replay
+tabletalk eval run revenue --baseline revenue-v1
+```
+
+Each run writes a concise terminal result and three detailed artifacts:
+
+- versioned JSON for tools
+- JUnit XML for CI
+- Markdown for a pull request.
+
+The report identifies the model, agent, manifest, semantic knowledge, prompt,
+runtime, warehouse, and inference fingerprint. It reports pass rate, a Wilson
+confidence interval, latency, tokens, configured cost, flaky outcomes, and
+deterministic failure diagnoses.
+
+## Security and retention
+
+- Use a warehouse identity with physical read-only permissions.
+- Treat connector permissions as the final security boundary.
+- TableTalk rejects writes, unsafe reads, unknown resources, unknown columns,
+  unsafe joins, excessive limits, and unapproved sensitive data.
+- TableTalk never treats lineage as proof that a join is correct.
+- TableTalk does not store credentials in traces, reports, or fingerprints.
+- Inference artifacts hash prompts by default. Set `persist_prompts: true` only
+  when exact raw-prompt retention is acceptable.
+- Traces and reports retain bounded evidence rows. Exact evidence is required
+  for deterministic replay and claim validation.
+- TableTalk does not delete artifacts automatically. The operator must apply a
+  retention policy to `.tabletalk/`.
+
+See the [commerce example](examples/dbt-analytics/README.md), the
+[getting-started guide](docs/getting-started.md), and the
+[research evidence](docs/research.md).
+
+## Development
+
+```console
+uv sync --locked --all-groups
+uv run pytest -q
+uv run ruff check tabletalk
+uv run mypy tabletalk
+uv build
+```
+
+The live Ollama smoke test is opt-in. It uses only `gemma4:31b-cloud`:
+
+```console
+TABLETALK_LIVE_OLLAMA=1 uv run pytest -m live_ollama
+```
+
+## License and services
+
+TableTalk is source-available under the
+[PolyForm Noncommercial License 1.0.0](LICENSE). The license permits the uses
+that its text defines. Commercial use requires separate written permission.
+
+William Bates offers implementation, integration, semantic onboarding, and
+custom eval-suite development. See the
+[commercial notice](COMMERCIAL-LICENSE.md). Earlier releases keep their earlier
+license grants. See [LICENSE_HISTORY.md](LICENSE_HISTORY.md).

tabletalk-0.6.0/docs/architecture.md

@@ -0,0 +1,53 @@
+# Architecture and safety boundaries
+
+The live and eval paths use one runtime:
+
+```text
+dbt artifacts -> semantic analysis -> proposal -> exact approval
+                                              |
+                                              v
+question -> resolved agent -> trusted meaning -> model inference
+         -> SQL AST validation -> read-only connector -> evidence rows
+         -> evidence-linked answer -> hard checks -> result artifact
+         -> deterministic metrics -> diagnosis -> reports
+```
+
+## Boundaries
+
+| Boundary | Module | Rule |
+|---|---|---|
+| dbt ingestion | `manifest.py` | `manifest.json` alone can add queryable resources. |
+| semantic analysis | `semantic_analysis.py` | Analysis labels trusted, confirmed, inferred, missing, and conflicting meaning. |
+| proposal | `proposal_service.py` | Generation is deterministic unless the user requests `--infer`. |
+| approval | `proposals.py` | Approval binds exact content, manifest digest, base digest, actor, and dependencies. |
+| inference | `runtime` and `inference.py` | Inference records are separate from metric computation. |
+| SQL safety | `validation.py` | The parsed AST determines actual resources and columns. |
+| execution | `connections.py` | The connector opens or governs a read-only target. |
+| evaluation | `evals` | Eval cases call the same runtime as live questions. |
+| metrics | `metrics.py` | Metrics use saved trial results and paired keys. |
+| diagnosis | `diagnostics.py` | Deterministic checks map to stable failure codes and owners. |
+| reports | `reports.py` | JSON, Markdown, and JUnit use one report object. |
+
+## Safety rules
+
+Validation rejects multiple statements, writes, commands, external-read
+functions, unknown or ambiguous relations, unknown columns, joins without a
+condition, excessive limits, and unapproved sensitive data.
+
+Lineage proves dependency. It does not prove join correctness. Join evidence
+must come from constraints, relationship tests, explicit metadata, or approved
+eval behavior.
+
+The connector permission is the final security boundary. SQL validation adds a
+second deterministic boundary.
+
+## Reproducibility
+
+An inference artifact has a content address and a complete configuration
+fingerprint. The cache index points from one fingerprint to one immutable
+artifact. The artifact stores a trace or one typed non-answer outcome. Strict
+replay makes no model request.
+
+The local executor uses bounded threads and preserves task order. Evaluation
+semantics do not depend on the executor. A future distributed executor can
+implement the same small interface. Apache Spark is not a core dependency.

tabletalk-0.6.0/docs/commands.md

@@ -0,0 +1,33 @@
+# Commands
+
+| Command | Result |
+|---|---|
+| `tabletalk init` | Mount a parsed dbt project and create small project directories. |
+| `tabletalk migrate [PATH]` | Add current schema identifiers to editable YAML resources. |
+| `tabletalk propose` | Analyze semantics and create at most three review-only proposals. |
+| `tabletalk proposal show [ID]` | Show exact proposal bytes, evidence, and diff. |
+| `tabletalk proposal edit ID FILE --from PATH` | Create a new immutable proposal from an edited file. |
+| `tabletalk proposal reject [ID] --reason TEXT` | Record a proposal rejection. |
+| `tabletalk approve [ID]` | Approve exact proposal bytes and run written evals. |
+| `tabletalk agent create` | Create a review-only agent proposal from explicit selectors. |
+| `tabletalk agent list` | List approved agents and resolved model counts. |
+| `tabletalk agent show NAME` | Show one approved agent and its resolved dbt scope. |
+| `tabletalk eval create NAME` | Execute reviewed SQL and create a review-only eval proposal. |
+| `tabletalk eval run [NAME]` | Run eval trials and write JSON, Markdown, and JUnit reports. |
+| `tabletalk baseline approve NAME --from REPORT` | Approve exact prior trial results as a baseline. |
+| `tabletalk baseline show NAME` | Show an approved baseline. |
+| `tabletalk ask NAME QUESTION` | Run the shared runtime and show answer provenance. |
+| `tabletalk doctor` | Validate artifacts, target access, selectors, and eval coverage. |
+
+`tabletalk propose` accepts `--sql-import`, `--bi-import`, `--history-import`,
+`--answer GAP=VALUE`, and `--infer`.
+
+`tabletalk eval run` accepts `--case`, `--trials`, `--workers`, `--baseline`, and
+`--cache-policy`. Cache policies are `normal`, `read-only`, `write-only`,
+`replay`, and `disabled`.
+
+`replay` fails on a cache miss. It never calls a model.
+
+Exit code 3 means that one or more eval hard checks failed. Exit code 4 means
+that a resource or approval failed validation. Exit code 1 means that an
+operational step failed.