isar-tools 0.1.0__tar.gz

isar_tools-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.pixi/
+__pycache__/
+*.egg-info/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+dist/
+build/

isar_tools-0.1.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+## 0.1.0 (2026-09-27)
+
+First release.
+
+- Packaging: the sdist holds sources, tests, and documentation only (no lock files or
+  demo recording); README links are absolute, so they work on PyPI.
+  `docs/RELEASING.md` describes a release, including the conda-forge recipe.
+- `-d DIR` must name an existing directory (exit status 2 otherwise), as with
+  `isabelle build -d`. Before, a mistyped `-d` was ignored, and commands of that
+  directory were silently read as part of the previous command.
+- `isar project names`: named declarations with qualified name (`Theory.locale.name`),
+  kind, command, session, location, and docstring (a directly preceding `text` block), as
+  text, JSON, CSV, or a Markdown index grouped by session and theory. `--kind` filters;
+  `--name` (base or exact qualified name) exits 1 for a name that declares nothing and
+  suggests the qualified names that exist. Replaces Voblint's
+  `extract_definitions.py --dump` and `check_theory_anchors.py`.
+- `isar ... | head` no longer prints a `BrokenPipeError` traceback.
+- `isar project extract NAME...`: the source of a declaration (command and, for a goal,
+  its proof), found by `name`, `locale.name`, `Theory.name`, or `Theory.locale.name`; a
+  name must identify exactly one declaration. `--manifest TOML --out DIR --write|--check`
+  keeps quoted declarations in a document in sync with the theories (the format of
+  Voblint's `thesis/shared/snippets.toml`).
+- `isar check docs`: opt-in documentation-coverage group, ported from Voblint's
+  `extract_definitions.py --lint`. `undocumented-theory` (no `text` before the first
+  declaration), `undocumented-heading` (no `text` right after or before a heading),
+  `undocumented-locale` and `undocumented-class` (no `text` right before the declaration).
+  `(* *)` comments, formal comments, and `text_raw` do not count as documentation.
+- `isar check locales` (opt-in group, code `locale-free-variable`): identifiers in the
+  terms of `locale` and unnamed `context` headers that are no parameter (own, `for`
+  clause, `defines`, or inherited from parent locales through imports), not bound in the
+  term, and not used anywhere else in the project or its `-d` imports; Isabelle would
+  generalize over them. Heuristic filter: at least four characters and an underscore.
+  `--allow NAME` (repeatable). Ported from Voblint's `check_locale_parameters.py`.
+- `isar project hierarchy` model: declarations also record `for` clause parameters,
+  `defines`, and term tokens; `context` headers parse too; `opening` ends a locale
+  expression.
+- Lexer: `\<in>`, `\<le>`, and other two-letter symbols are no longer identifier letters
+  (only doubled letters such as `\<AA>` are), and `\<^sup>`/`\<^bold>` no longer continue
+  an identifier.
+- `isar project hierarchy`: class and locale declarations (parents, fixes with type and
+  notation, assumes, parameter sorts) as text, JSON, or DOT; `--root` follows parents
+  through imports, including `-d` directories, and reports unresolved names.
+- Unqualified imports of global theory names (`Main`) resolve through the parent
+  session chain.
+- `isar stats build BUILD_LOG`: where theory elaboration time went in an `isabelle build -v`
+  log. Per building session: theories elaborated, cpu seconds, and the share spent on
+  theories owned by other sessions; theories elaborated more than once with the time
+  wasted (`--top N`); `--budget SESSION=N` (repeatable) exits 1 when SESSION's theories
+  are elaborated inside other sessions more than N times. Reads only the line format
+  `SESSION: theory OWNER.THEORY 100% (Ns cumulated time)`; a log without such lines, or one
+  in which a session elaborates a theory twice, is exit status 2 (`--allow-empty` accepts
+  an incremental build that rebuilt nothing). `build` is now a view
+  name, so a directory called `build` needs `isar stats ./build`.
+- `isar check` prints a summary line (`2 findings: 1 missing-theory, ...`) and colours
+  findings on a terminal; `fmt --diff` and `symbols normalize --diff` colour their diffs.
+  `--color auto|always|never`; `NO_COLOR` is honoured. Finding messages are shorter.
+- README demo GIF recorded by VHS from `docs/demo/demo.tape` (`pixi run demo`, in a
+  separate `demo` environment). It shows `isar fmt --diff`; `pixi run demo-check` runs the
+  tape's commands without recording and checks their exit status.
+- Source model: lossless outer-syntax lexer, Isabelle symbol table, theory headers,
+  command segmentation with per-theory keyword tables, and goal blocks.
+- Project model: ROOT parser with positioned diagnostics, `ROOTS` discovery, theory and
+  import resolution, reachability.
+- `isar stats` with views `summary`, `sessions`, `theories`, `proofs`, `commands`, and
+  `style`, in text, Markdown, JSON, and CSV.
+- `isar check` with groups `project`, `proofs`, `syntax` (default) and `symbols`; stable
+  finding codes, `--ignore`, text/JSON/CSV output, exit status 1 on findings.
+- `isar symbols normalize` (ASCII or Unicode spelling; `--check`, `--diff`).
+- `isar project sessions|theories|graph` (graph as text, JSON, or DOT).
+- `-d DIR` on `stats`, `check`, and `project`: sessions of DIR resolve imports and
+  commands, like `isabelle build -d`.
+- Source files are read and written byte-exactly, so CRLF line endings survive.
+- `isar fmt`: conservative formatter (indentation from proof structure, trailing
+  whitespace, blank lines); `--check`, `--diff`, `--normalize`, stdin via `-`. Changes
+  only layout, by construction and by test.
+- Opt-in corpus tests (`pixi run corpus` with `ISAR_CORPUS`).
+- Repository scaffold: pixi environment, package skeleton, `isar` CLI with
+  placeholder commands, tests, lint, type checking, and CI.

isar_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Lerchner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

isar_tools-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: isar-tools
+Version: 0.1.0
+Summary: Source tooling for Isabelle/Isar projects: formatting, checks, and statistics.
+Project-URL: Homepage, https://github.com/ManuelLerchner/isar-tools
+Project-URL: Repository, https://github.com/ManuelLerchner/isar-tools
+Project-URL: Issues, https://github.com/ManuelLerchner/isar-tools/issues
+Author: Manuel Lerchner
+License-Expression: MIT
+License-File: LICENSE
+Keywords: formatter,isabelle,isar,theorem-proving
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# isar-tools
+
+[![CI Status][ci-badge]][ci]
+[![License][license-badge]][license]
+
+[ci-badge]: https://img.shields.io/github/actions/workflow/status/ManuelLerchner/isar-tools/ci.yml?branch=main&style=flat-square&label=CI
+[ci]: https://github.com/ManuelLerchner/isar-tools/actions/workflows/ci.yml
+[license-badge]: https://img.shields.io/github/license/ManuelLerchner/isar-tools?style=flat-square
+[license]: https://github.com/ManuelLerchner/isar-tools/blob/main/LICENSE
+
+Source tooling for Isabelle/Isar projects: a formatter, project and source
+checks, and statistics. Pure Python. Works on `.thy` and `ROOT` files without
+running Isabelle.
+
+![Terminal recording: isar stats prints session and theory tables for a small
+demo project, isar check reports an unfinished proof (sorry), isar fmt --diff
+indents a proof and removes trailing whitespace and extra blank lines, and isar
+project graph prints the theory import graph.](https://raw.githubusercontent.com/ManuelLerchner/isar-tools/main/docs/demo/demo.gif)
+
+Status: pre-alpha. See [`CHANGELOG.md`](https://github.com/ManuelLerchner/isar-tools/blob/main/CHANGELOG.md) and
+[`docs/PLAN.md`](https://github.com/ManuelLerchner/isar-tools/blob/main/docs/PLAN.md).
+
+## Install
+
+```sh
+pip install isar-tools          # or: uv tool install isar-tools, pipx install isar-tools
+isar --help
+```
+
+Python 3.11 or newer; no runtime dependencies. A conda-forge package
+(`pixi global install isar-tools`) follows the first PyPI release.
+
+## Commands
+
+| Command                                  | What it does                                                                               |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `isar fmt [PATH...]`                     | Format theories: indentation, trailing whitespace, blank lines, and optional line wrapping |
+| `isar check [GROUP] [PATH...]`           | Report problems in ROOT files, proofs, syntax, symbols, docs, and locales                  |
+| `isar stats [VIEW] [PATH...]`            | Size, proof, and command statistics                                                        |
+| `isar stats build BUILD_LOG`             | Where theory elaboration time went in an `isabelle build -v` log                           |
+| `isar project sessions\|theories\|graph` | Sessions, theories, and the session or theory import graph                                 |
+| `isar project hierarchy`                 | Class and locale declarations: parents, parameters, assumptions                            |
+| `isar project names`                     | Named declarations: qualified name, kind, location, docstring; a Markdown index            |
+| `isar project extract NAME...`           | The source of a declaration by name; keeps quoted declarations in sync with a manifest     |
+| `isar symbols normalize PATH...`         | Rewrite symbols as `\<name>`, or as Unicode                                                |
+
+A path is a project directory, read like `isabelle build -D` (its `ROOT`, and
+`ROOTS` recursively), or a `.thy` file. Commands that read a project default to the current
+directory.
+
+Exit status: `0` success, `1` findings or differences, `2` invalid invocation or
+unreadable input. Data goes to stdout, diagnostics to stderr. JSON and CSV output
+use stable snake_case keys and are never coloured.
+
+### Formatting
+
+```sh
+isar fmt                          # format every .thy below the current directory
+isar fmt --check                  # list files that would change; exit 1 if any
+isar fmt --diff Foo.thy           # show the change without writing
+isar fmt --max-line-length 100    # also wrap long lines
+isar fmt -                        # stdin to stdout, for editors
+```
+
+The formatter only changes layout. It never changes a token, never touches the
+space between two tokens on a line, and never rewrites strings, cartouches,
+comments, or ML. By default it only indents lines that are too shallow for their
+proof structure; `--normalize` sets indentation exactly. See
+[`docs/FORMATTER.md`](https://github.com/ManuelLerchner/isar-tools/blob/main/docs/FORMATTER.md).
+
+As a git hook with [lefthook](https://github.com/evilmartians/lefthook):
+
+```yaml
+pre-commit:
+  jobs:
+    - name: isar-fmt
+      glob: "*.thy"
+      run: isar fmt {staged_files}
+      stage_fixed: true
+```
+
+### Checks
+
+```sh
+isar check                        # groups project, proofs, and syntax
+isar check symbols src/           # non-ASCII characters outside comments
+isar check docs src/              # theories, headings, locales, classes without a text block
+isar check locales -d ~/afp/thys  # free variables in locale headers
+isar check --ignore oops --format json
+```
+
+| Group     | Codes                                                                                                                                           |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project` | `root-syntax`, `duplicate-session`, `missing-theory`, `missing-directory`, `missing-document-file`, `duplicate-theory-name`, `unreached-theory` |
+| `proofs`  | `unfinished-proof` (`sorry`, `\<proof>`), `oops`, `unclosed-proof`                                                                              |
+| `syntax`  | `lexical-error`, `document-argument`                                                                                                            |
+| `symbols` | `non-ascii` (opt-in)                                                                                                                            |
+| `docs`    | `undocumented-theory`, `undocumented-heading`, `undocumented-locale`, `undocumented-class` (opt-in)                                             |
+| `locales` | `locale-free-variable` (opt-in, heuristic)                                                                                                      |
+
+Project checks run for directory arguments only. `isar check --help` describes
+every code.
+
+`locales` is heuristic. Inside the terms of a `locale` or `context` header,
+Isabelle reads an unknown identifier as a free variable and generalizes over
+it, so an assumption citing a deleted or misspelt constant still builds. The
+check reports identifiers that are no parameter of the header (its `fixes`,
+`for` clause, `defines`, or those of the locales it extends, resolved through
+imports), not bound in the term, and not used anywhere else in the project or
+in the `-d` theories it imports. Only names of at least four characters with an
+underscore (or `\<^sub>`) are reported; `--allow NAME` (repeatable) accepts a
+name. Inner syntax is approximated lexically: see `isar_tools/checks/locales.py`.
+
+### Commands of other sessions
+
+Whether a word is an Isar command depends on the theories a file imports. The
+built-in table covers Pure and HOL, and commands declared in the theory headers
+of the project are found automatically. For commands of other projects, such as
+AFP entries, pass their directory with `-d`, as with `isabelle build -d`:
+
+```sh
+isar check -d ~/afp/thys .
+isar project hierarchy --root numeric_domain -d ~/afp/thys --format json
+```
+
+### Names
+
+```sh
+isar project names --kind locale                  # every locale, as Theory.locale
+isar project names --format markdown > NAMES.md   # an index with docstrings
+isar project names --name Foo.loc.bar_lemma       # exit 1 if no such declaration
+```
+
+Names are qualified as Isabelle renders them: a lemma inside `context loc` is
+`Theory.loc.name`. With `--name`, a qualifier naming the wrong scope does not
+match, and the error suggests the names that exist, so links into rendered
+theories can be checked without building them. The docstring is a `text` block
+directly before the declaration.
+
+### Quoting declarations
+
+```sh
+isar project extract combine_env locale_name.lemma_name
+isar project extract --manifest snippets.toml --out generated/ --write   # regenerate
+isar project extract --manifest snippets.toml --out generated/ --check   # diff; exit 1 on drift
+```
+
+A name is `name`, `locale.name`, `Theory.name`, or `Theory.locale.name`, and
+must identify one declaration; its source is the command and, for a goal, its
+proof. A manifest lists names as TOML tables, so a document that quotes a
+definition fails its check when the definition changes or is renamed:
+
+```toml
+[snippets.combine_env]
+why = "shown in chapter 3"     # free text, ignored
+[snippets.succ_pos]
+file = "src/B.thy"             # choose between declarations of the same name
+```
+
+### Statistics
+
+```sh
+isar stats                               # sessions, then the largest theories
+isar stats proofs --top 10               # the longest proofs
+isar stats style --max-line-length 100   # long theories, long lines, sorry, watched methods
+isar stats build build.log --budget HOL-Library=0
+```
+
+## Limits
+
+- Nothing runs Isabelle, so nothing is type-checked or proved. A formatted file
+  is guaranteed to contain the same tokens; building it is the project's CI's
+  job.
+- The built-in command table is hand-written. A command of a session that is
+  neither built in nor passed with `-d` is read as part of the previous command.
+- `project extract` finds names that commands declare; derived names
+  (`foo_def`, `foo.simps`) and names made by interpretations are not found.
+- `project hierarchy` follows declared parents, not `sublocale`, `subclass`, or
+  `interpretation`.
+- `stats build` reads one log line format, observed in Isabelle2025 logs.
+
+## Development
+
+Requires [pixi](https://pixi.sh).
+
+```sh
+pixi run pre-commit-install  # git hooks
+pixi run test
+pixi run coverage            # 100% line and branch coverage required
+pixi run typecheck           # pyright, strict
+pixi run lint
+pixi run isar --help
+pixi run demo                # re-record docs/demo/demo.gif with VHS
+pixi run demo-check          # run the demo commands without recording
+ISAR_CORPUS=~/afp/thys pixi run corpus   # integration tests over real projects
+```
+
+Expected output lives in golden files under `tests/golden/` and
+`tests/formatter/`. `UPDATE_GOLDEN=1 pixi run test` rewrites them, so a change in
+output shows up as a diff in review.
+
+The demo GIF is generated by [VHS](https://github.com/charmbracelet/vhs) from
+[`docs/demo/demo.tape`](https://github.com/ManuelLerchner/isar-tools/blob/main/docs/demo/demo.tape), which runs the real commands on the
+small project in [`docs/demo/project`](https://github.com/ManuelLerchner/isar-tools/tree/main/docs/demo/project). The `demo` task uses
+its own pixi environment, so VHS, ttyd, and ffmpeg stay out of the default one.
+
+## License
+
+MIT

isar_tools-0.1.0/README.md

@@ -0,0 +1,209 @@
+# isar-tools
+
+[![CI Status][ci-badge]][ci]
+[![License][license-badge]][license]
+
+[ci-badge]: https://img.shields.io/github/actions/workflow/status/ManuelLerchner/isar-tools/ci.yml?branch=main&style=flat-square&label=CI
+[ci]: https://github.com/ManuelLerchner/isar-tools/actions/workflows/ci.yml
+[license-badge]: https://img.shields.io/github/license/ManuelLerchner/isar-tools?style=flat-square
+[license]: https://github.com/ManuelLerchner/isar-tools/blob/main/LICENSE
+
+Source tooling for Isabelle/Isar projects: a formatter, project and source
+checks, and statistics. Pure Python. Works on `.thy` and `ROOT` files without
+running Isabelle.
+
+![Terminal recording: isar stats prints session and theory tables for a small
+demo project, isar check reports an unfinished proof (sorry), isar fmt --diff
+indents a proof and removes trailing whitespace and extra blank lines, and isar
+project graph prints the theory import graph.](https://raw.githubusercontent.com/ManuelLerchner/isar-tools/main/docs/demo/demo.gif)
+
+Status: pre-alpha. See [`CHANGELOG.md`](https://github.com/ManuelLerchner/isar-tools/blob/main/CHANGELOG.md) and
+[`docs/PLAN.md`](https://github.com/ManuelLerchner/isar-tools/blob/main/docs/PLAN.md).
+
+## Install
+
+```sh
+pip install isar-tools          # or: uv tool install isar-tools, pipx install isar-tools
+isar --help
+```
+
+Python 3.11 or newer; no runtime dependencies. A conda-forge package
+(`pixi global install isar-tools`) follows the first PyPI release.
+
+## Commands
+
+| Command                                  | What it does                                                                               |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `isar fmt [PATH...]`                     | Format theories: indentation, trailing whitespace, blank lines, and optional line wrapping |
+| `isar check [GROUP] [PATH...]`           | Report problems in ROOT files, proofs, syntax, symbols, docs, and locales                  |
+| `isar stats [VIEW] [PATH...]`            | Size, proof, and command statistics                                                        |
+| `isar stats build BUILD_LOG`             | Where theory elaboration time went in an `isabelle build -v` log                           |
+| `isar project sessions\|theories\|graph` | Sessions, theories, and the session or theory import graph                                 |
+| `isar project hierarchy`                 | Class and locale declarations: parents, parameters, assumptions                            |
+| `isar project names`                     | Named declarations: qualified name, kind, location, docstring; a Markdown index            |
+| `isar project extract NAME...`           | The source of a declaration by name; keeps quoted declarations in sync with a manifest     |
+| `isar symbols normalize PATH...`         | Rewrite symbols as `\<name>`, or as Unicode                                                |
+
+A path is a project directory, read like `isabelle build -D` (its `ROOT`, and
+`ROOTS` recursively), or a `.thy` file. Commands that read a project default to the current
+directory.
+
+Exit status: `0` success, `1` findings or differences, `2` invalid invocation or
+unreadable input. Data goes to stdout, diagnostics to stderr. JSON and CSV output
+use stable snake_case keys and are never coloured.
+
+### Formatting
+
+```sh
+isar fmt                          # format every .thy below the current directory
+isar fmt --check                  # list files that would change; exit 1 if any
+isar fmt --diff Foo.thy           # show the change without writing
+isar fmt --max-line-length 100    # also wrap long lines
+isar fmt -                        # stdin to stdout, for editors
+```
+
+The formatter only changes layout. It never changes a token, never touches the
+space between two tokens on a line, and never rewrites strings, cartouches,
+comments, or ML. By default it only indents lines that are too shallow for their
+proof structure; `--normalize` sets indentation exactly. See
+[`docs/FORMATTER.md`](https://github.com/ManuelLerchner/isar-tools/blob/main/docs/FORMATTER.md).
+
+As a git hook with [lefthook](https://github.com/evilmartians/lefthook):
+
+```yaml
+pre-commit:
+  jobs:
+    - name: isar-fmt
+      glob: "*.thy"
+      run: isar fmt {staged_files}
+      stage_fixed: true
+```
+
+### Checks
+
+```sh
+isar check                        # groups project, proofs, and syntax
+isar check symbols src/           # non-ASCII characters outside comments
+isar check docs src/              # theories, headings, locales, classes without a text block
+isar check locales -d ~/afp/thys  # free variables in locale headers
+isar check --ignore oops --format json
+```
+
+| Group     | Codes                                                                                                                                           |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project` | `root-syntax`, `duplicate-session`, `missing-theory`, `missing-directory`, `missing-document-file`, `duplicate-theory-name`, `unreached-theory` |
+| `proofs`  | `unfinished-proof` (`sorry`, `\<proof>`), `oops`, `unclosed-proof`                                                                              |
+| `syntax`  | `lexical-error`, `document-argument`                                                                                                            |
+| `symbols` | `non-ascii` (opt-in)                                                                                                                            |
+| `docs`    | `undocumented-theory`, `undocumented-heading`, `undocumented-locale`, `undocumented-class` (opt-in)                                             |
+| `locales` | `locale-free-variable` (opt-in, heuristic)                                                                                                      |
+
+Project checks run for directory arguments only. `isar check --help` describes
+every code.
+
+`locales` is heuristic. Inside the terms of a `locale` or `context` header,
+Isabelle reads an unknown identifier as a free variable and generalizes over
+it, so an assumption citing a deleted or misspelt constant still builds. The
+check reports identifiers that are no parameter of the header (its `fixes`,
+`for` clause, `defines`, or those of the locales it extends, resolved through
+imports), not bound in the term, and not used anywhere else in the project or
+in the `-d` theories it imports. Only names of at least four characters with an
+underscore (or `\<^sub>`) are reported; `--allow NAME` (repeatable) accepts a
+name. Inner syntax is approximated lexically: see `isar_tools/checks/locales.py`.
+
+### Commands of other sessions
+
+Whether a word is an Isar command depends on the theories a file imports. The
+built-in table covers Pure and HOL, and commands declared in the theory headers
+of the project are found automatically. For commands of other projects, such as
+AFP entries, pass their directory with `-d`, as with `isabelle build -d`:
+
+```sh
+isar check -d ~/afp/thys .
+isar project hierarchy --root numeric_domain -d ~/afp/thys --format json
+```
+
+### Names
+
+```sh
+isar project names --kind locale                  # every locale, as Theory.locale
+isar project names --format markdown > NAMES.md   # an index with docstrings
+isar project names --name Foo.loc.bar_lemma       # exit 1 if no such declaration
+```
+
+Names are qualified as Isabelle renders them: a lemma inside `context loc` is
+`Theory.loc.name`. With `--name`, a qualifier naming the wrong scope does not
+match, and the error suggests the names that exist, so links into rendered
+theories can be checked without building them. The docstring is a `text` block
+directly before the declaration.
+
+### Quoting declarations
+
+```sh
+isar project extract combine_env locale_name.lemma_name
+isar project extract --manifest snippets.toml --out generated/ --write   # regenerate
+isar project extract --manifest snippets.toml --out generated/ --check   # diff; exit 1 on drift
+```
+
+A name is `name`, `locale.name`, `Theory.name`, or `Theory.locale.name`, and
+must identify one declaration; its source is the command and, for a goal, its
+proof. A manifest lists names as TOML tables, so a document that quotes a
+definition fails its check when the definition changes or is renamed:
+
+```toml
+[snippets.combine_env]
+why = "shown in chapter 3"     # free text, ignored
+[snippets.succ_pos]
+file = "src/B.thy"             # choose between declarations of the same name
+```
+
+### Statistics
+
+```sh
+isar stats                               # sessions, then the largest theories
+isar stats proofs --top 10               # the longest proofs
+isar stats style --max-line-length 100   # long theories, long lines, sorry, watched methods
+isar stats build build.log --budget HOL-Library=0
+```
+
+## Limits
+
+- Nothing runs Isabelle, so nothing is type-checked or proved. A formatted file
+  is guaranteed to contain the same tokens; building it is the project's CI's
+  job.
+- The built-in command table is hand-written. A command of a session that is
+  neither built in nor passed with `-d` is read as part of the previous command.
+- `project extract` finds names that commands declare; derived names
+  (`foo_def`, `foo.simps`) and names made by interpretations are not found.
+- `project hierarchy` follows declared parents, not `sublocale`, `subclass`, or
+  `interpretation`.
+- `stats build` reads one log line format, observed in Isabelle2025 logs.
+
+## Development
+
+Requires [pixi](https://pixi.sh).
+
+```sh
+pixi run pre-commit-install  # git hooks
+pixi run test
+pixi run coverage            # 100% line and branch coverage required
+pixi run typecheck           # pyright, strict
+pixi run lint
+pixi run isar --help
+pixi run demo                # re-record docs/demo/demo.gif with VHS
+pixi run demo-check          # run the demo commands without recording
+ISAR_CORPUS=~/afp/thys pixi run corpus   # integration tests over real projects
+```
+
+Expected output lives in golden files under `tests/golden/` and
+`tests/formatter/`. `UPDATE_GOLDEN=1 pixi run test` rewrites them, so a change in
+output shows up as a diff in review.
+
+The demo GIF is generated by [VHS](https://github.com/charmbracelet/vhs) from
+[`docs/demo/demo.tape`](https://github.com/ManuelLerchner/isar-tools/blob/main/docs/demo/demo.tape), which runs the real commands on the
+small project in [`docs/demo/project`](https://github.com/ManuelLerchner/isar-tools/tree/main/docs/demo/project). The `demo` task uses
+its own pixi environment, so VHS, ttyd, and ffmpeg stay out of the default one.
+
+## License
+
+MIT