latris 0.3.0__tar.gz

latris-0.3.0/.gitignore

@@ -0,0 +1,75 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual envs
+venv/
+.venv/
+env/
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Node
+node_modules/
+
+# Sample data
+sample_data.csv
+
+# Project
+*.log
+logs/
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pytest-run/
+.pytest-tmp/
+.pytest-tmp-*/
+pytest-cache-files-*/
+
+# Claude Code local settings
+.claude/
+
+# Demo / scratch modelling projects (each has its own git repo)
+projects/
+demo-project/
+
+# Build artefacts
+dist/
+
+# Inside an initialised modelling project (latris init):
+#   generated exports and layout files are not source of truth.
+reports/exports/
+layout/*.layout.yaml
+# Per-reference full-text artefacts (Phase 4b retrieval). Derived
+# content; the SourceSnapshot metadata in references.yaml is the
+# git-tracked record of when/where it was fetched.
+ai/reference-extracts/

latris-0.3.0/CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+Context for AI coding agents working in this repository.
+
+## What this is
+
+**Latris** — an evidence-native modelling workbench. This repo is the
+open-source core: the `latris` Python package (`src/latris/`), its CLI,
+and the FastAPI + WebSocket server backend. The Latris desktop app is
+built on this package from a separate private repository.
+
+Start at [README.md](./README.md) and [docs/README.md](./docs/README.md).
+
+## Where things live
+
+- [`src/latris/`](./src/latris/) — the package. Layered:
+  `schema/` → `repo/` → `operations/` → `cli/`, plus `ai/` (LLM layer),
+  `diff/` (semantic diffs), `exporters/` (DOT, Markdown, Word, HTML
+  packs), `server/` (FastAPI + WebSocket backend), `sync/` (client for
+  the collaboration control plane — the service itself is separate and
+  proprietary; `sync.latris.app` is its public URL).
+- [`tests/`](./tests/) — pytest suite mirroring the package layout.
+  Hermetic — env-var git identity and `LATRIS_AI_MOCK=1`; no network or
+  real keys required.
+- [`worked_example/`](./worked_example/) — living worked example
+  (acceptance test) and generated transcript.
+- [`docs/`](./docs/) — engineering reference. Start at
+  [docs/README.md](./docs/README.md).
+- [`scripts/`](./scripts/) — `dev-server.sh` / `dev-stop.sh` (backend
+  process lifecycle for dev), `bump-version.sh` (version + tag).
+
+## Working principles
+
+- **Design docs are source of truth.** Architectural commitments live in
+  [`docs/engineering/`](./docs/engineering/): `ARCHITECTURE.md`
+  (three-layer architecture), `SCHEMA_NOTES.md` (schema shape),
+  `AI_LAYER.md` (AI contract), `GIT_INTEGRATION.md` (commit model),
+  `TESTING.md` (test strategy). Don't drift from them silently; if you
+  think one needs to change, propose it.
+- **Schema before code-that-uses-schema.** New entities land as pydantic
+  models with round-trip tests before any operation depends on them.
+- **No business logic in `cli/`.** A CLI command is one parse + one call
+  into `operations/` + one print. The server also imports
+  `operations/` directly.
+- **Single chokepoints.** Five files own their concern: `repo/git.py`
+  (subprocess), `repo/yaml_io.py` (YAML), `repo/layout.py` (paths),
+  `operations/commit.py` (commits), `schema/ids.py` (IDs).
+- **No AI-authored commits.** Even AI-proposed mutations commit as the
+  responsible human; AI involvement records to `ai/interactions.jsonl`
+  and the commit's `Provenance:` trailer.
+- **No secrets on disk.** API keys live only in env vars or OS keyring;
+  `ai_config.yaml` is committed but rejects key-shaped fields
+  defensively.
+- **Keep help topics current.** User-facing help lives in
+  `src/latris/server/help.py` (served at `/api/help/topics`). When you
+  add, rename, or change a workflow phase, model type, or user-facing
+  concept, update the relevant help topic body so documentation stays
+  accurate.
+- **Commit after changes.** Commit work before finishing a session;
+  don't leave modified or untracked work uncommitted.
+- **Frozen constants.** The per-project state directory `.graph-tooling`
+  and the keyring service name `latris-sync` are data-format constants —
+  renaming them breaks existing users' projects/credentials. Never
+  rename.
+
+## Running tests
+
+`python -m pytest` runs the suite in parallel by default (`-n auto`, via
+`pytest-xdist`). For serial debugging — clean tracebacks, breakpoints,
+deterministic output ordering — pass `-n0`. Targeted runs
+(`pytest tests/ai/test_context.py`) are the inner-loop optimum.
+See [docs/engineering/TESTING.md](./docs/engineering/TESTING.md).
+
+## Worked example is the acceptance test
+
+Every new CLI command or user-facing feature must be added to
+[`worked_example/worked_example.py`](./worked_example/worked_example.py).
+After adding, run `pytest tests/test_worked_example.py --slow` to
+regenerate
+[`worked_example/worked_example_output.md`](./worked_example/worked_example_output.md).
+Commit both the script change and the updated transcript. A feature that
+isn't in the worked example isn't done. The transcript is living
+documentation — it always shows the tool's full current capabilities.
+
+## Versioning
+
+`src/latris/__init__.py` (`__version__`) is the single version string,
+read by hatchling. Never edit it by hand — use the bump script:
+
+```bash
+bash scripts/bump-version.sh 0.3.1        # bump + commit + tag
+bash scripts/bump-version.sh 0.3.1 --no-tag  # bump + commit only
+```
+
+Pushing a `v*` tag triggers `.github/workflows/publish.yml`, which
+publishes the package to PyPI. Remind the user to push tags after a
+bump; confirm version numbers with them rather than choosing
+unilaterally.

latris-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to Latris
+
+Thanks for helping build Latris. This document is the short version; the
+engineering docs under [`docs/engineering/`](docs/engineering/) are the
+source of truth.
+
+## Set up
+
+```bash
+git clone https://github.com/Shannon-Bengtson/latris.git
+cd latris
+python -m venv .venv
+# Windows: .venv\Scripts\activate   —   mac/linux: source .venv/bin/activate
+pip install -e ".[server,data,dev]"
+```
+
+Requires Python 3.11+ and git 2.40+ with a configured `user.name` /
+`user.email`.
+
+## Before you open a PR
+
+1. **Tests pass**: `python -m pytest` (parallel by default).
+2. **Lint clean**: `python -m ruff check src tests`.
+3. **Worked example updated** if you added or changed any CLI command or
+   user-facing feature: extend `worked_example/worked_example.py`, then
+   regenerate the transcript with
+   `pytest tests/test_worked_example.py --slow` and commit both. A
+   feature that isn't in the worked example isn't done.
+
+## Ground rules
+
+- No business logic in `cli/` — a command is one parse + one call into
+  `operations/` + one print.
+- Respect the single chokepoints: `repo/git.py` (all subprocess),
+  `repo/yaml_io.py` (all YAML), `repo/layout.py` (all paths),
+  `operations/commit.py` (all commits), `schema/ids.py` (all IDs).
+- No AI-authored commits; no secrets on disk (keys live in env vars or
+  the OS keyring).
+- The per-project state directory `.graph-tooling` is a frozen
+  data-format constant — do not rename it.
+- Layer discipline: `schema/` → `repo/` → `operations/` → `cli/`; never
+  import upward. `server/` sits beside `cli/` and consumes
+  `operations/`.
+
+## Versioning
+
+Never edit `src/latris/__init__.py` by hand — use
+`bash scripts/bump-version.sh <version>` (bumps, commits, and tags;
+pushing a `v*` tag triggers the PyPI publish workflow).
+
+## License
+
+By contributing you agree that your contributions are licensed under the
+[Apache-2.0 license](LICENSE) that covers the project.

latris-0.3.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) 2026 Shannon Bengtson
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

latris-0.3.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: latris
+Version: 0.3.0
+Summary: Latris — an AI-assisted, evidence-native causal-modelling workbench (Python CLI + server backend).
+Project-URL: Homepage, https://latris.app
+Project-URL: Repository, https://github.com/Shannon-Bengtson/latris
+Author: Shannon Bengtson
+License: Apache-2.0
+License-File: LICENSE
+Keywords: bayesian,causal,cld,evidence,git,latris,modelling,provenance,systems-thinking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Requires-Dist: bibtexparser<2,>=1.4
+Requires-Dist: click>=8.2
+Requires-Dist: httpx>=0.28
+Requires-Dist: instructor>=1.3
+Requires-Dist: jinja2>=3.1
+Requires-Dist: keyring>=25
+Requires-Dist: litellm>=1.40
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-docx>=1.1
+Requires-Dist: python-ulid>=2.2
+Requires-Dist: rich>=13.7
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer>=0.26
+Provides-Extra: data
+Requires-Dist: pandas>=2.0; extra == 'data'
+Requires-Dist: scipy>=1.11; extra == 'data'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-rerunfailures>=14; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: quant
+Requires-Dist: pgmpy>=1.1; extra == 'quant'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: pandas>=2.0; extra == 'server'
+Requires-Dist: pgmpy>=1.1; extra == 'server'
+Requires-Dist: python-multipart>=0.0.7; extra == 'server'
+Requires-Dist: scipy>=1.11; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.34; extra == 'server'
+Requires-Dist: watchfiles>=1.0; extra == 'server'
+Description-Content-Type: text/markdown
+
+# Latris
+
+**Structure for defensible reasoning.**
+
+Latris is an evidence-native modelling workbench for building defensible
+causal and systems models — structured provenance, challenge workflows,
+git-native versioning, AI-assisted drafting under human approval, and
+report generation.
+
+This repository is the open-source core: the Python package (`latris`),
+its CLI, and the FastAPI + WebSocket server backend. The Latris desktop
+app (React + Electron) is built on top of this package from a separate
+private repository.
+
+- Every modelling project is a **git repo** — every change is an
+  inspectable, reversible commit.
+- Evidence and provenance are **first-class data**, not annotations:
+  citations, assumptions, decisions, challenges, sign-offs.
+- AI assistance returns **structured proposals**, never free-form
+  mutations; a human approves before anything commits.
+- One substrate, many formalisms: qualitative CLD/DAG views today, a
+  built-in discrete **Bayesian Network engine** (state spaces, CPTs with
+  per-cell provenance, exact inference, parameter learning), and more
+  views on the architecture's path.
+
+Status: **alpha** (0.3.0). Apache-2.0 licensed.
+
+## Prerequisites
+
+- **Python 3.11+** on PATH
+- **git 2.40+** on PATH, with `user.name` and `user.email` configured
+  globally (Latris commits as you, and enforces that identity)
+
+## Install
+
+From PyPI (once published):
+
+```bash
+pip install "latris[server,data]"
+latris --version
+latris doctor          # verify git + identity
+```
+
+From source:
+
+```bash
+git clone https://github.com/Shannon-Bengtson/latris.git
+cd latris
+python -m venv .venv
+# Windows: .venv\Scripts\activate   —   mac/linux: source .venv/bin/activate
+pip install -e ".[server,data,dev]"
+latris doctor
+```
+
+Optional extras:
+
+| Extra | Brings in | For |
+|-------|-----------|-----|
+| `server` | FastAPI, uvicorn, pandas, scipy, pgmpy | The API server (`python -m latris.server`) |
+| `data` | pandas, scipy | Dataset wrangling and statistics |
+| `quant` | pgmpy | Quantitative inference (also in `server`) |
+| `dev` | pytest, xdist, ruff, build | Running the test suite |
+
+## Quickstart
+
+```bash
+# 1. Create a project (a git repo with the full model structure)
+latris init air-quality --question "What drives urban air quality?"
+
+cd air-quality
+
+# 2. Build a model: nodes, then edges
+latris node add "Traffic volume" --kind variable
+latris node add "NO2 concentration" --kind variable
+latris edge add <traffic-id> <no2-id> --kind causal
+
+# 3. Inspect — every step above was a git commit
+latris status
+latris log
+
+# 4. Export
+latris export md --output reports/report.md
+latris export dot --view cld --output reports/model.dot
+```
+
+The full command catalogue is in
+[`docs/engineering/CLI_REFERENCE.md`](docs/engineering/CLI_REFERENCE.md).
+
+## Run the API server
+
+```bash
+python -m latris.server --project-root ./air-quality
+```
+
+Serves the full CRUD/AI/export API on **http://127.0.0.1:8741** (the
+same backend the Latris desktop app embeds). `--help` lists flags.
+
+## AI layer (optional, bring your own key)
+
+AI calls go through a vendor-agnostic adapter (litellm + instructor);
+secrets live in your OS keyring, never on disk:
+
+```bash
+latris ai key set anthropic      # or openai / gemini / groq / ...
+latris ai config show            # default model lives in .graph-tooling/ai_config.yaml
+```
+
+Set `LATRIS_AI_MOCK=1` to stub all AI calls (used by the test suite and
+CI; the pre-rename `GRAPH_TOOLING_AI_MOCK` is still honoured for one
+release).
+
+## Tests
+
+```bash
+python -m pytest              # full suite, parallel via pytest-xdist
+python -m pytest -n0          # serial, for clean tracebacks
+python -m pytest tests/test_worked_example.py --slow   # acceptance test (regenerates the transcript)
+```
+
+## Documentation
+
+- [`docs/README.md`](docs/README.md) — documentation index
+- [`docs/engineering/ARCHITECTURE.md`](docs/engineering/ARCHITECTURE.md) — how it's built
+- [`docs/engineering/CLI_REFERENCE.md`](docs/engineering/CLI_REFERENCE.md) — command catalogue
+- [`worked_example/worked_example_output.md`](worked_example/worked_example_output.md) — a full end-to-end session transcript
+- [`llms.txt`](llms.txt) — machine-readable doc map for AI agents
+
+## License
+
+[Apache-2.0](LICENSE) — Copyright (c) 2026 Shannon Bengtson.
+
+---
+
+## For AI agents
+
+You are working with **Latris**, an evidence-native causal-modelling
+CLI + API server. Treat the engineering docs as the source of truth:
+start from [`llms.txt`](llms.txt) and
+[`docs/README.md`](docs/README.md).
+
+Setup (one shot):
+
+```bash
+pip install "latris[server,data]"
+```
+
+Minimal working session (init → node → edge → export → history):
+
+```bash
+latris init demo --question "Does X cause Y in context Z?"
+cd demo
+latris node add "X" --kind variable
+latris node add "Y" --kind variable
+latris edge add <x-id> <y-id> --kind causal   # IDs from the node add output
+latris export md --output reports/report.md
+latris log                                     # every mutation is a git commit
+```
+
+The complete, always-current demonstration of every command is the
+worked example:
+[`worked_example/worked_example_output.md`](worked_example/worked_example_output.md)
+(generated by `worked_example/worked_example.py`; the generator is the
+repo's acceptance test). Read it before asking the user how the tool
+behaves — and after changing CLI behaviour, regenerate it
+(`pytest tests/test_worked_example.py --slow`) and commit the updated
+transcript.
+
+Hard rules when modifying this repo: no business logic in `cli/` (one
+parse + one call into `operations/` + one print); respect the five
+chokepoints (`repo/git.py`, `repo/yaml_io.py`, `repo/layout.py`,
+`operations/commit.py`, `schema/ids.py`); no AI-authored commits; no
+secrets on disk. See [`CLAUDE.md`](CLAUDE.md) and
+[`src/latris/CLAUDE.md`](src/latris/CLAUDE.md).