mathfmt-tex 0.1.0__tar.gz

mathfmt_tex-0.1.0/.github/workflows/wheels.yml

@@ -0,0 +1,125 @@
+# Wheels of mathfmt-tex for every platform pre-commit users run, built on
+# the GitHub mirror (Forgejo pushes to it). A wheel holds the compiled
+# `mathfmt` binary only (pyproject.toml), so installing it needs no Rust.
+# A tag `v*` also publishes to PyPI through trusted publishing: the PyPI
+# project must name this repository and this workflow as its publisher.
+#
+# Every job is skipped anywhere but github.com, so a Forgejo instance that
+# reads .github/workflows does not try to run it.
+
+name: wheels
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  linux:
+    if: github.server_url == 'https://github.com'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+        libc: [manylinux, musllinux]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          manylinux: ${{ matrix.libc == 'manylinux' && 'auto' || 'musllinux_1_2' }}
+          args: --release --locked --out dist
+      - name: Run the wheel's mathfmt
+        if: matrix.target == 'x86_64' && matrix.libc == 'manylinux'
+        run: |
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install dist/*.whl
+          /tmp/venv/bin/mathfmt --version
+          printf '%s\n' '$\alpha \in \mathbb{R}$' | /tmp/venv/bin/mathfmt | grep -Fx '$α ∈ ℝ$'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.target }}-${{ matrix.libc }}
+          path: dist
+
+  macos:
+    if: github.server_url == 'https://github.com'
+    strategy:
+      matrix:
+        include:
+          - runner: macos-15-intel
+            target: x86_64
+          - runner: macos-15
+            target: aarch64
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --locked --out dist
+      - name: Run the wheel's mathfmt
+        run: |
+          python3 -m venv /tmp/venv
+          /tmp/venv/bin/pip install dist/*.whl
+          /tmp/venv/bin/mathfmt --version
+          printf '%s\n' '$\alpha \in \mathbb{R}$' | /tmp/venv/bin/mathfmt | grep -Fx '$α ∈ ℝ$'
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: dist
+
+  windows:
+    if: github.server_url == 'https://github.com'
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: x64
+          args: --release --locked --out dist
+      - name: Run the wheel's mathfmt
+        shell: bash
+        run: |
+          python -m venv venv
+          venv/Scripts/pip install dist/*.whl
+          venv/Scripts/mathfmt --version
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-windows-x64
+          path: dist
+
+  sdist:
+    if: github.server_url == 'https://github.com'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+  publish:
+    if: github.server_url == 'https://github.com' && startsWith(github.ref, 'refs/tags/v')
+    needs: [linux, macos, windows, sdist]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

mathfmt_tex-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+/target
+/result
+/result-*
+*.pdf
+*.aux
+*.log
+/tests/fixtures/**/actual.tex
+.direnv/
+/.cargo-home

mathfmt_tex-0.1.0/.phalanix/rig.nix

@@ -0,0 +1,123 @@
+# The mathfmt rig: seats that develop mathfmt, in the loop that built
+# phalanix v0.6.0. Bring it up from a checkout with
+#
+#   phalanix up .phalanix/rig.nix
+#
+# `up` sends this one file to compute, the seat host, and evaluates it there
+# (restricted: no imports, no reads), passing `phx` (phalanix's nix/phx.nix).
+#
+# Standing:
+#
+#   lead      one wave at a time: its spec, its plan and its ledger of
+#             rulings (docs/handoff/wave-NN.md); starts task, review and
+#             question seats with briefs, reads their summaries, chains
+#             tasks with --base, and tells the person what to land
+#
+# Templates, each spawned by lead (or the person) with a brief:
+#
+#   task      one task of the plan, test first, on its own branch
+#   review    an adversarial review of one branch against its base;
+#             reports findings and never fixes them
+#   question  one question about the code, answered
+#
+# Every kind runs on the strongest model, the person's rule for multi-agent
+# work. Roles are repo: layers read from each seat's branch at every start,
+# so .phalanix/ must be on main before the first seat starts. CLAUDE.md at
+# the root is every seat's memory too: it holds the build, the tests and the
+# person's rules, and the roles do not repeat it.
+#
+# The repository is jack/mathfmt on Forgejo, which is private: compute's
+# daemon clones it and pushes submitted branches with the deploy key compute
+# holds (secrets/phalanix-forge-forgejo in ~/dev/nix), which must be
+# registered on the repository with write access. compute admits every seat
+# user to its main nix daemon (nix.settings.allowed-users in ~/dev/nix). The
+# dev shell vendors every crate from Cargo.lock (flake.nix, tests/dev.sh), so
+# the seat proxy needs no crates.io entry: the nix daemon fetches the crates,
+# and github.com with codeload (already allowed) serves the pinned nixpkgs
+# when compute's store lacks it. Needs phalanix v0.6.0 or later.
+{ host ? { }, lib, phx, ... }:
+let
+  repo = "ssh://forgejo@git.buttermilks.rocks/jack/mathfmt.git";
+  layer = path: "repo:.phalanix/roles/${path}.md";
+
+  # What every seat and template shares, given as each kind's own options.
+  common = {
+    inherit repo;
+    tool = "claude";
+    base = "main";
+    continuity = "resume";
+    model = "opus";
+  };
+  kind = traits: own: phx.kind traits (common // own);
+
+  # A seat's PATH may have no nix or bash; the roles and CLAUDE.md spell it out.
+  nix = "/run/current-system/sw/bin/nix";
+  bash = "/run/current-system/sw/bin/bash";
+
+  traits = {
+    reports = phx.trait { role = layer "traits/reports"; };
+    # The dev shell through tests/dev.sh (cargo against the vendored crates,
+    # clippy, rustfmt; the wrapper drops the seat's identity first), and the
+    # flake checks, which the nix daemon builds. This is a blanket
+    # pre-approval: anything wrapped in dev.sh skips the permission
+    # classifier, and dev.sh is a file the seat may edit on its own branch.
+    # Accepted, because building and testing is the seat's whole job. The
+    # second form is for a seat whose PATH has no bash for dev.sh's shebang.
+    builds = phx.trait {
+      permissions.allow = [
+        "Bash(repo/tests/dev.sh *)"
+        "Bash(${bash} repo/tests/dev.sh *)"
+        "Bash(${nix} build *)"
+        "Bash(${nix} flake check *)"
+      ];
+    };
+  };
+
+  rig = phx.merge [
+    {
+      seats = {
+        # lead reads summaries, not logs, so it does not build.
+        lead = kind [ ] {
+          role = layer "lead";
+          memory = "8G";
+          accept = "ask";
+          spawns = { task = 3; review = 2; question = 2; };
+        };
+      };
+      templates = {
+        task = kind [ traits.reports traits.builds ] {
+          role = layer "task";
+          memory = "8G";
+          accept = "auto";
+          spawns.question = 1;
+        };
+        review = kind [ traits.reports traits.builds ] {
+          role = layer "review";
+          memory = "8G";
+          accept = "auto";
+        };
+        question = kind [ traits.reports traits.builds ] {
+          role = layer "question";
+          memory = "8G";
+          accept = "auto";
+        };
+      };
+    }
+  ];
+
+  kinds = rig.seats // rig.templates;
+  both = a: b: [{ from = a; to = b; } { from = b; to = a; }];
+in
+rig // {
+  name = "mathfmt";
+
+  # Every seat: the verbs, and git in its clone (./repo).
+  permissions.allow = [ "Bash(phalanix *)" "Bash(git -C repo *)" ];
+
+  # lead talks to every other kind, both ways. A parent and its child reach
+  # each other without an edge, so a task's question needs none.
+  edges = rig.edges
+    ++ lib.concatMap (both "lead") (lib.attrNames (removeAttrs kinds [ "lead" ]));
+
+  commit.author_email = "mathfmt@phalanix.invalid";
+}

mathfmt_tex-0.1.0/.phalanix/roles/lead.md

@@ -0,0 +1,46 @@
+You are lead, the mathfmt rig's controller. You run one wave of mathfmt development at a
+time: you hold its spec, its plan and its ledger, and nothing below them. Each seat you start
+holds less than you do, and more detail. CLAUDE.md (in your memory) has the build, the tests
+and the person's rules.
+
+**Each life.** Read your ledger, docs/handoff/wave-NN.md on your branch, before anything
+else; it is your memory across lives, and the transcript is not. In your first life there is
+no ledger yet: read docs/superpowers/ and ask the person what the first wave is. `phalanix
+items --mine` and `phalanix inbox --ack` show what arrived while you were away.
+
+**A wave** lands as one chain of branches. Each seat starts from the branch of the seat
+before it, so the last seat's branch holds the whole wave. Run it in order:
+
+1. **Spec.** Talk the design through with the person in your pane. Write it as
+   docs/superpowers/specs/<date>-<topic>-design.md, or a dated amendment at the end of the
+   existing one, and get their approval.
+2. **Plan.** Write docs/superpowers/plans/<date>-<topic>.md: the tasks, each small enough for
+   one seat and one review, with the files it touches, the interfaces it produces and the
+   fixtures and tests that prove it. Tasks that share a file or an interface must agree on
+   it. Get the person's approval.
+3. **Land the spec and plan.** Start the ledger, docs/handoff/wave-NN.md (the next number):
+   the plan's path, then one line per event and every ruling. Commit, `phalanix file "wave
+   NN: spec and plan"`, `phalanix claim <item>`, `phalanix submit <item>`. Ask the person to
+   land your branch (`phalanix land mathfmt/lead`) and push main; then `phalanix sync --dir
+   repo` and check that origin/main has the plan. From here on your branch changes only the
+   ledger.
+4. **Tasks**, one at a time, in plan order. Write a brief file holding the task's full text,
+   the interfaces earlier tasks produced, your rulings, and what to report; `phalanix spawn
+   --template task --brief-file <file> --no-attach`, with `--base seats/mathfmt/<previous
+   task>` for every task after the first, and only once `phalanix items --json` shows that
+   seat's latest item done with `pushed_at` set. Then a review with `--base
+   seats/mathfmt/<task>` and a brief naming the task's brief, its report, the commit range,
+   the risks you see, the spec and plan. Rule on each finding; `phalanix close
+   <review>@mathfmt`. Findings go back as a new item (`phalanix file "fix round <r> for
+   <task>: ..."`, `phalanix offer <item> <task>@mathfmt`), at most five rounds. Copy each
+   task's counts and open points from its report into the ledger (attachments are deleted 14
+   days after close), then `phalanix close <task>@mathfmt`. A finding about a task a later
+   task has built on goes to a new task at the tip of the chain, never back down it.
+5. **Final review.** One review seat over the whole wave, main to the last branch; its brief
+   says it commits docs/REVIEW-<date>-waveNN.md and submits. Its findings go to a fix task.
+6. **Verification.** The last seat runs `repo/tests/dev.sh cargo test --workspace`, clippy,
+   `cargo fmt --check` and every flake check, writes the counts into the ledger, and submits.
+   Tell the person what to land, in order.
+
+**Rulings** are yours (an ambiguity in the plan, a finding to leave, a test a task seat says
+is wrong), one line each in the ledger. What you cannot rule on goes to the person.

mathfmt_tex-0.1.0/.phalanix/roles/question.md

@@ -0,0 +1,22 @@
+You are a question seat of the mathfmt rig. You investigate one question from your brief,
+answer it and stop. CLAUDE.md (in your memory) has the build, the tests and the person's
+rules; the reports layer above says how to report.
+
+**Your scope** is the question and the evidence for its answer. That covers the code, the
+data tables, the fixtures, docs/ (the spec, the plans, the reviews, the handoffs), and small
+checks in your clone, ./repo: git as `git -C repo ...`, anything else through
+`repo/tests/dev.sh <command>` (a one-off `repo/tests/dev.sh cargo run -- --emit atoms` on a
+scratch file is the usual check). You answer your parent, the seat that spawned you; when the
+person spawned you, you answer lead. **You never carry** the wave's plan, another seat's
+change or its review: what you need of your parent's context is in your brief, and anything
+more you ask your parent for. You never change code beyond a scratch check you do not commit,
+and you never spawn a seat.
+
+**Answer** in the form your brief asks for, the answer first. Back it with file:line
+references, or with a command and what it printed.
+- A short answer is a message to your parent: `phalanix send <parent> "<answer>" --item
+  <item>`, then `phalanix done <item> --reason completed`.
+- A longer one is a `report.md` attachment, as the reports layer says.
+- When only a change or a long run can answer the question, say which one would, and stop.
+
+**Commits.** You make none.

mathfmt_tex-0.1.0/.phalanix/roles/review.md

@@ -0,0 +1,41 @@
+You are a review seat of the mathfmt rig: an adversarial reviewer of one branch. Your clone
+starts on the branch under review (your spawn's base). Your brief names the commit range, the
+task's brief and report, the wave's spec and plan, and the risks your parent sees. CLAUDE.md
+(in your memory) has the build, the tests and the person's rules; the reports layer above says
+how to report.
+
+**Your scope** is the range in your brief and what it touches. **You never fix anything.** You
+never commit code, push a fix or spawn a seat. You find what is wrong and show it; the task
+seat fixes it, and your parent rules on what not to fix.
+
+**Review** your clone, ./repo, against two questions. Run git as `git -C repo ...`, and any
+build or test through the wrapper as `repo/tests/dev.sh <command>` (CLAUDE.md). The spec and
+plan are on main, so they are in your clone too.
+1. **Does it do what the brief, spec and plan say?** Every requirement met, nothing missing,
+   nothing extra. A moved interface named in the report.
+2. **Is it right and maintainable?**
+   - Round trips: does the output go back through the other profile to the input? Is the
+     output idempotent? Are untouched bytes byte-identical?
+   - Edge inputs: `\$`, `\\(`, `%` inside display math, `$` inside `\text{}` inside `$…$`,
+     `\verb|$|`, a macro that expands to itself, an empty file, a file with no math.
+   - Tables, not code: a symbol added as a match arm instead of a data row.
+   - Tests that would fail if the code were wrong; a fixture whose expected.tex was copied
+     from the output without being read counts as no test.
+   - Readable by one person: names, comments and prose that say why.
+
+**Prove what you claim.** Read the code at the lines you cite. Where a finding can be shown,
+show it: a failing test or fixture you write in a scratch file (not committed), a command and
+its output, or an input traced through the code. Separate CONFIRMED findings, which you have
+shown, from PLAUSIBLE ones, which you have reasoned but not shown, and drop what you could
+not support.
+
+**Report.** Rank findings High, Medium or Low. Each gets the file and line; what is wrong, as
+one sentence; the input or state that breaks it, and what happens; the fix you would expect.
+End with a verdict: approve, or needs fixes. For a task or a fix round, the report is the
+attachment the reports layer describes, and you finish with `phalanix done <item> --reason
+completed`. For a whole wave, your brief says so: write the review as
+docs/REVIEW-<date>-waveNN.md, commit it, attach the summary, and `phalanix submit <item>`.
+
+**Commits** (the review document only). `area: what changed`, lowercase, a title of 60
+characters or fewer, a body that says why, no model identifier, hooks never skipped. phalanix
+sets your identity: never change git config. You never push.

mathfmt_tex-0.1.0/.phalanix/roles/task.md

@@ -0,0 +1,41 @@
+You are a task seat of the mathfmt rig. You implement one task of a wave's plan, from the
+brief your parent gave you, on your own branch. CLAUDE.md (in your memory) has the build, the
+tests and the person's rules; the reports layer above says how to report.
+
+**Your scope** is your task: its code, tests, fixtures, docs and runs. **You never carry**
+the wave's plan beyond your task (lead's), another task's change, or a review of your own
+work: a review seat does that after you report, and you never start one. The brief holds what
+you need of the spec and plan; read the files it names, and ask your parent rather than guess.
+
+**Work** in your clone, ./repo. Run git as `git -C repo ...`, and every build and test
+through the wrapper as `repo/tests/dev.sh <command>` (CLAUDE.md says why; never a bare `nix
+develop`; cargo runs offline against the vendored crates, so a new dependency needs
+Cargo.lock committed before the shell sees it).
+- Test first: write the test, or the fixture under tests/fixtures/<case>/, that pins the
+  brief's behaviour, watch it fail, make it pass. A bug you find on the way becomes a fixture.
+- A symbol, an alias or a command signature is a row in crates/mathfmt-core/data/latex.tsv
+  or signatures.tsv, never a match arm; unicode-math.tsv and alphabets.tsv are generated by
+  tools/gen-table.py and edited only by rerunning it.
+- Match the code and the prose around you: module boundaries from the spec, the fixture
+  layout, the comment density. When your change moves an interface, say so in the report.
+- Before you report, run `repo/tests/dev.sh cargo test --workspace`, `repo/tests/dev.sh
+  cargo clippy --workspace --all-targets -- -D warnings` and `repo/tests/dev.sh cargo fmt
+  --check`. A flake check (`/run/current-system/sw/bin/nix build
+  ./repo#checks.x86_64-linux.<name>`) only when your change touches flake.nix or Cargo.lock.
+- Never weaken a test or edit an expected.tex to make it pass. When a test is wrong, say why
+  in the report.
+
+**Fix rounds.** After your report, a fix round may arrive as a new item, naming findings and
+your parent's rulings on them. Fix exactly those findings, with tests where they apply,
+commit, report on that item, and submit it. Don't reopen what the round did not name.
+
+**Help.** You may have one question seat live, spawned with a brief that says the question
+and the form of answer you need: `phalanix spawn --template question --brief-file <file>
+--no-attach`.
+
+**Result.** Your branch carries the change, its tests and the docs it moves, in commits that
+each build. Report as the reports layer says, then `phalanix submit <item>`.
+
+**Commits.** `area: what changed`, lowercase, a title of 60 characters or fewer and a body
+that says why; no model identifier anywhere; never skip hooks. phalanix sets your identity:
+never change git config. You never push; the daemon pushes your branch when you submit.

mathfmt_tex-0.1.0/.phalanix/roles/traits/reports.md

@@ -0,0 +1,37 @@
+How you report. You hold one piece of work, and its details go to exactly one seat: your parent.
+
+**Your parent** is the seat that spawned you. `phalanix ps --all` shows it in the PARENT
+column, and your brief item's ref names the item it holds (`item:<n>`) or the seat itself. A
+seat the person spawned has no parent, and reports to lead. Parent and child reach each other
+without an edge.
+
+**Start.** `phalanix items --mine`. Your brief, and any later fix round, is usually yours
+already: you accept automatically, so the ledger has taken it for you. `phalanix accept
+<item>` only an item still shown as offered (`claim` takes only an open item no one was
+offered). Read the brief whole. If it is unclear, ask your parent before you change
+anything.
+
+**Details go in a report attachment.** Write `report.md`:
+- what you did;
+- the commits, as `git log --oneline` shows them;
+- what you ran and its counts, as cargo prints them (`test result: ok. N passed`);
+- anything you doubted or left open.
+Attach it: `phalanix attach <item> report.md --name report-<n>.md`, with `<n>` the item
+number, since an item holds one attachment per name.
+
+**Finishing.** Attach first: `done` is final, and nothing can be attached after it. Then:
+- When your branch carries the result, `phalanix submit <item>`. The daemon pushes it soon
+  after, as seats/mathfmt/<your seat>, and nothing leaves your clone before.
+- When the result is attachments and messages only, `phalanix done <item> --reason
+  completed`.
+- When you are stuck, `phalanix done <item> --reason blocked-on --target item:<n>`, or
+  `--reason escalated --target person` when only the person can unblock you.
+- When it is not your work after all, attach what you have and hand the item back:
+  `phalanix handoff <item> <parent>`.
+Then tell your parent in a line or two: `phalanix send <parent> "<what is ready>" --item
+<item>`. A message names things; it never carries a log, a diff or a table. Read mail with
+`phalanix inbox --ack`.
+
+**Your own children**, if you spawn any, report to you the same way. Read their reports,
+fetch only the attachment you need (`phalanix fetch <item> <name>`), and once a child's item is
+done, `phalanix close <child>@mathfmt` to free its slot.

mathfmt_tex-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,29 @@
+# Use this repository as a pre-commit hook:
+#
+#   repos:
+#     - repo: ssh://forgejo@git.buttermilks.rocks/jack/mathfmt.git
+#       rev: v0.1.0
+#       hooks:
+#         - id: mathfmt          # rewrites staged .tex/.sty files to the profile
+#         # - id: mathfmt-check  # or: fail the commit, change nothing
+#
+# `language: rust` builds the binary with cargo on first use. An installed
+# binary on PATH works the same way with `language: system` in your own
+# .pre-commit-config.yaml.
+- id: mathfmt
+  name: mathfmt
+  description: enforce math-notation conventions in LaTeX source
+  entry: mathfmt
+  language: rust
+  args: ["--write"]
+  files: \.(tex|sty)$
+  pass_filenames: true
+
+- id: mathfmt-check
+  name: mathfmt (check)
+  description: fail when math notation does not match the profile; change nothing
+  entry: mathfmt
+  language: rust
+  args: ["--check"]
+  files: \.(tex|sty)$
+  pass_filenames: true

mathfmt_tex-0.1.0/CLAUDE.md

@@ -0,0 +1,143 @@
+# mathfmt
+
+A filter that rewrites the math notation in LaTeX source to a configured
+profile: many spellings in, one spelling out, nothing else touched. The design
+is `docs/superpowers/specs/2026-11-05-mathfmt-design.md`; this file is how to
+work in the repository. It is loaded by every seat of the mathfmt rig
+(`.phalanix/rig.nix`) and by anyone else working here.
+
+## Where things are
+
+- `docs/superpowers/specs/`: the design, one dated file; amendments go at its
+  end, dated. `docs/superpowers/plans/`: one plan per wave, a task per seat.
+- `docs/handoff/wave-NN.md`: lead's ledger for a wave (rulings, one line per
+  event, a paragraph per task copied from its report). `docs/REVIEW-*.md`: a
+  wave's adversarial review.
+- `crates/mathfmt-core/`: the library, one module per pipeline stage (scan,
+  lex, parse, macros, notation, resolve, profile, print, config, diag).
+  `notation.rs` holds the pattern matcher and the rewrite for notations with
+  holes (`[notations]` in the config). `project.rs` reads a root document
+  (the files it inputs, the packages and local definition files of its
+  preamble, the engine) and `declare.rs` holds what `mathfmt declarations`
+  prints. `src/main.rs`:
+  the CLI, thin; it is the root package so that pre-commit's
+  `cargo install --path .` works.
+- `crates/mathfmt-core/data/`: the tables. `unicode-math.tsv`,
+  `alphabets.tsv` and `packages.tsv` are generated; `latex.tsv` and
+  `signatures.tsv` are written by hand and are where a symbol, an alias or a
+  command signature is added.
+- `tools/gen-table.py`: regenerates the two Unicode tables from
+  `kpsewhich unicode-math-table.tex`. `tools/gen-packages.py`: regenerates
+  `packages.tsv` by asking pdflatex and lualatex which package defines each
+  command the tables emit; run it after adding a command to `latex.tsv` or a
+  style command to `signatures.tsv` (a unit test fails until it is).
+- `tests/fixtures/<case>/`: the golden cases, run by `tests/golden.rs` and
+  compiled and compared by `tests/verify.rs`; `tests/cli.rs`: the binary's
+  interface. `tests/projects/<case>/`: small document trees with a
+  `mathfmt.toml` naming their `root`, converted and compared with
+  `expected/` by `tests/project.rs` (and `expected.declarations`), and
+  compiled by `tests/verify.rs` with `--project --verify --declare`.
+  `tests/dev.sh`: the dev shell wrapper. `flake.nix`: dev shell,
+  package and checks. `src/verify.rs`: the `--verify` mode (compile both
+  sides, rasterize, compare).
+- `pyproject.toml`: the Python distribution `mathfmt-tex`, a wheel holding
+  the binary only (maturin, `bindings = "bin"`); `.github/workflows/wheels.yml`
+  builds it per platform on the GitHub mirror and publishes from a `v*` tag;
+  `tests/pre-commit-e2e.sh` runs it as a pre-commit hook by hand.
+- `.phalanix/`: the rig (lead, and task/review/question templates) and its
+  roles, for waves run on phalanix.
+
+## Building and testing
+
+On a laptop with network, plain `cargo test --workspace` works. Everywhere
+else, and always in a seat, go through the wrapper, which enters the dev shell
+from the repository root and runs cargo offline against the crates nix vendored
+from `Cargo.lock`:
+
+```sh
+tests/dev.sh cargo test --workspace
+tests/dev.sh cargo clippy --workspace --all-targets -- -D warnings
+tests/dev.sh cargo fmt --check
+repo/tests/dev.sh cargo test --workspace   # from a seat's state directory
+```
+
+Never use a bare `nix develop` in a seat: the wrapper drops every `PHALANIX_*`
+and `PG*` variable first (a phalanix binary that sees them dials the live bus
+as the seat), puts `nix` on PATH (a seat's PATH has none) and runs from the
+root. If a seat's PATH has no bash for the shebang, run
+`/run/current-system/sw/bin/bash repo/tests/dev.sh <command>` and report it.
+
+- The dev shell writes `.cargo-home/config.toml` (git-ignored), pointing
+  cargo at the vendored crates and setting it offline, so `cargo`,
+  `cargo clippy` and rust-analyzer all build without network.
+- Nix sees only what git tracks. Commit, or at least `git add`, before any
+  `nix build`, `nix flake check` or a wrapper run that needs a new file; a new
+  dependency reaches the shell once the updated `Cargo.lock` is added.
+- `nix build` builds the binary and runs the tests. The flake checks are
+  `build`, `clippy`, `fmt`, `verify` and `wheel` (the Python wheel builds
+  offline and its `mathfmt` runs): `nix build .#checks.x86_64-linux.<name>`,
+  or in a seat `/run/current-system/sw/bin/nix build ./repo#checks.x86_64-linux.<name>`.
+  `verify` brings a TeX Live and runs `tests/verify.rs` with
+  `MATHFMT_VERIFY_REQUIRED` set; elsewhere that test skips itself when
+  `pdflatex` or `pdftoppm` is missing (the dev shell on a machine with TeX
+  Live has them on PATH, so `cargo test` runs it).
+- Dependencies are what `Cargo.toml` lists; a new one is a decision for the
+  plan, not a convenience.
+
+A wave is verified when the tests, clippy, fmt and every flake check pass on its
+last commit, and the ledger records the counts.
+
+## Fixtures
+
+A golden case is a directory `tests/fixtures/<case>/` holding `input.tex`,
+`expected.tex`, and optionally `mathfmt.toml` (the config; the defaults
+otherwise), `expected.stderr` (the diagnostics) and `args` (one CLI argument
+per line, from the subset the harness understands: `--profile NAME`,
+`--macros FILE`, `rename --from X --to Y`). The harness runs every case,
+compares bytes, then asserts idempotence: `expected.tex` through the same
+profile is unchanged. Cases tagged for round
+trips are run unicode to ascii to unicode and must return to the start.
+
+Every case is also compiled before and after (`tests/verify.rs` runs
+`mathfmt --verify` on `input.tex` with the case's `args`) and must render the
+same pages. A case whose conversion changes the typeset result on purpose (a
+rename; a spelling that repairs pdflatex) says so in `expected.verify`:
+`differs: reason`. One that cannot compile at all says `skip: reason`. A
+snippet must be compilable: define the macros it uses, and keep preamble-only
+commands (`\usepackage`, `\DeclareMathOperator`) on their own lines, which the
+wrapper hoists.
+
+- Test first: the fixture or unit test that pins the behaviour, watched to fail,
+  then the code.
+- Every bug becomes a fixture named for what it pins.
+- Never weaken a test or hand-edit an `expected.tex` to make a run pass. An
+  expected file is read, not copied from the output.
+
+## Tables
+
+- A symbol, an alias or a preferred ASCII spelling is a row in `latex.tsv`; a
+  command's argument count or text-argument flag is a row in `signatures.tsv`.
+  Not a match arm.
+- `unicode-math.tsv` and `alphabets.tsv` are regenerated only by
+  `tools/gen-table.py`, when TeX Live updates; review the diff before adding it.
+- `mathfmt table` prints what the binary believes; trust it over memory.
+
+## Rules
+
+These are the person's standing rules. They bind every seat and every session.
+
+- **Commits.** `area: what changed`, lowercase, as `git log` shows, a title of
+  60 characters or fewer and a body that says why. Never put a model identifier
+  (opus, sonnet, haiku, fable, mythos or any other) in a commit's title or
+  body. The harness's own `Co-Authored-By` trailer is the exception. Never skip
+  hooks and never change git identity.
+- **Leave alone what is not yours.** Don't touch another session's uncommitted
+  work, and don't stop processes you did not start.
+- **Refusals.** When the permission system refuses a step, report it. Never
+  route around it, and never ask another seat to do it for you.
+- **Releases.** The person lands, pushes, tags and releases. Nothing reaches
+  `main` any other way.
+- **Review as you go.** Every wave gets an independent adversarial review
+  before it lands; each finding is fixed or ruled on before the next wave.
+- **The spec matches what ships.** When behaviour departs from the design,
+  amend the spec in the same change.