tithon 0.2.2__tar.gz → 0.2.4__tar.gz

tithon-0.2.4/.git-blame-ignore-revs

@@ -0,0 +1,9 @@
+# Commits that only reformat. `git blame` skips these so it lands on the
+# commit that last changed the code, not the one that moved the whitespace.
+#
+# Enable locally with:
+#   git config blame.ignoreRevsFile .git-blame-ignore-revs
+# (GitHub honours this file automatically.)
+
+# style: format the tree with ruff and biome
+f6c1838afe7dc977d6f08e8b65f548db1f1091d3

tithon-0.2.4/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,100 @@
+name: Bug report
+description: Something behaved differently than you expected
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. The daemon outlives the client, so what the UI
+        showed is rarely enough to locate the fault — the log and the sequence
+        of session events below are what make a bug fixable.
+
+        Please write in English so the history stays searchable for everyone.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you expected, and what you got instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: >
+        As a sequence of session events. Whether the client disconnected, and
+        whether the daemon or the host restarted, are usually the decisive
+        details.
+      placeholder: |
+        1. start the daemon
+        2. run a cell that prints for 30s
+        3. close the VSCode window while it runs
+        4. reopen the file after it would have finished
+        5. the output up to the disconnect is missing
+    validations:
+      required: true
+
+  - type: textarea
+    id: log
+    attributes:
+      label: Daemon log
+      description: >
+        From `$TITHON_HOME/daemon.log` (`~/.tithon/daemon.log` by default). The
+        interesting window usually starts at the last `attach` before things
+        went wrong. Feel free to trim anything sensitive.
+      render: text
+    validations:
+      required: false
+
+  - type: textarea
+    id: status
+    attributes:
+      label: tithon status
+      description: Output of `tithon status`, if the daemon was still up.
+      render: text
+    validations:
+      required: false
+
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: Tithon (`pip show tithon`), the VSCode extension, VSCode, and Python.
+      placeholder: "tithon 0.2.3 / extension 0.2.3 / VSCode 1.99.0 / Python 3.12.4"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: connection
+    attributes:
+      label: How do you connect to the host?
+      description: Tithon's job is surviving a flaky link, so its shape is diagnostic.
+      options:
+        - Local (same machine)
+        - VSCode Tunnel
+        - Remote-SSH
+        - WSL
+        - Container / devcontainer
+        - Other (describe below)
+    validations:
+      required: true
+
+  - type: input
+    id: environment
+    attributes:
+      label: OS / host
+      description: "`uname -a`, or the platform if that doesn't apply."
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checked
+    attributes:
+      label: Before submitting
+      options:
+        - label: I checked [docs/known_issue.md](https://github.com/rnoro/tithon/blob/main/docs/known_issue.md) and the open issues.
+          required: true
+        - label: This is a failure I actually observed, not one I expect could happen.
+          required: true

tithon-0.2.4/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question or open-ended discussion
+    url: https://github.com/rnoro/tithon/discussions
+    about: Usage questions, setups that don't fit a bug report, and half-formed ideas.
+  - name: Contributing guide
+    url: https://github.com/rnoro/tithon/blob/main/CONTRIBUTING.md
+    about: Development setup, how changes are verified, and how to propose a design change.

tithon-0.2.4/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,60 @@
+name: Feature request / idea
+description: Propose a capability, a change in behavior, or a design change
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Ideas are welcome, including ones that change how Tithon works
+        internally — [docs/SPEC.md](https://github.com/rnoro/tithon/blob/main/docs/SPEC.md)
+        describes today's design, it is not a fence around it. Making the case
+        here first is how a change gets agreed before anyone writes code.
+
+        Please write in English so the history stays searchable for everyone.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: >
+        What you were trying to do, and where Tithon got in the way. Concrete
+        workflows persuade more than abstract capabilities.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you'd like instead
+      description: The behavior you want. A rough sketch is fine.
+    validations:
+      required: true
+
+  - type: textarea
+    id: design-impact
+    attributes:
+      label: Does this touch the current design?
+      description: >
+        If it changes something Tithon currently relies on — how kernels are
+        spawned, how sessions are scoped, how messages are journaled, how sync
+        or storage works, what the daemon binds to — say which property it
+        would replace and what would protect the same guarantee afterwards.
+        Unsure is a fine answer; say so and we'll work it out.
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you considered
+      description: Including workarounds you are using today.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: participation
+    attributes:
+      label: Participation
+      options:
+        - label: I'd be willing to work on this if we agree on the approach.
+          required: false

tithon-0.2.4/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: ci
+
+# The hermetic verification bundle (`make -C scripts fast`) drives real daemons
+# and detached kernels and is NOT run here — contributors run it locally and
+# paste its summary table into the pull request (see CONTRIBUTING.md).
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - develop
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - run: uv sync
+
+      - name: ruff check
+        if: matrix.python-version == '3.11'
+        run: uv run ruff check .
+
+      - name: ruff format --check
+        if: matrix.python-version == '3.11'
+        run: uv run ruff format --check .
+
+      - name: pytest
+        run: uv run pytest -q
+
+  extension:
+    name: extension
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: extension
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: extension/package-lock.json
+
+      - run: npm ci
+
+      - name: biome
+        run: npm run lint
+
+      - name: tsc
+        run: npm run build
+
+      - name: vitest
+        run: npm test
+
+  release-scripts:
+    name: release scripts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      # A plain assert script: `node --test` on the directory does not run it.
+      - run: node .github/scripts/format-release-pr-body.test.js

{tithon-0.2.2 → tithon-0.2.4}/.gitignore

@@ -67,8 +67,5 @@ Thumbs.db
 *.swp
 *~
 
-# vendored upstream reference checkout (docs/vscode-jupyter-comparison.md)
-vscode-jupyter/
-
 # demo recording work area (published assets live in docs/)
 scripts/demo/

tithon-0.2.4/.release-please-manifest.json

@@ -0,0 +1,4 @@
+{
+  ".": "0.2.4",
+  "extension": "0.2.4"
+}

tithon-0.2.4/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["charliermarsh.ruff", "biomejs.biome"]
+}

tithon-0.2.4/.vscode/settings.json

@@ -0,0 +1,28 @@
+{
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.organizeImports.ruff": "explicit"
+    }
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "biomejs.biome",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.organizeImports.biome": "explicit"
+    }
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "biomejs.biome",
+    "editor.formatOnSave": true
+  },
+  "[json]": {
+    "editor.defaultFormatter": "biomejs.biome",
+    "editor.formatOnSave": true
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "biomejs.biome",
+    "editor.formatOnSave": true
+  }
+}

{tithon-0.2.2 → tithon-0.2.4}/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.2.4](https://github.com/rnoro/tithon/compare/v0.2.3...v0.2.4) (2026-09-29)
+
+
+### Bug Fixes
+
+* **daemon:** inspect processes portably on macOS ([#18](https://github.com/rnoro/tithon/issues/18)) ([060da5b](https://github.com/rnoro/tithon/commit/060da5b81a8b68a30d741cb62e3586223d72eb1e))
+
+
+### Documentation
+
+* add a contributing guide, CI, and issue templates ([5c8300d](https://github.com/rnoro/tithon/commit/5c8300deb3708a0c3c81dfb3b12c75b1d6015b5c))
+* remove unused document ([0e316fd](https://github.com/rnoro/tithon/commit/0e316fd07af46c8ccdfad30f2a0d37d2bb1391c5))
+
+## [0.2.3](https://github.com/rnoro/tithon/compare/v0.2.2...v0.2.3) (2026-08-16)
+
+
+### Features
+
+* **extension:** let "open as Notebook" stick, per file ([08ba8c1](https://github.com/rnoro/tithon/commit/08ba8c157988a027edcdd71ee5be831b703ed48b))
+* share cell outputs through the project, not the journal ([1ba9d24](https://github.com/rnoro/tithon/commit/1ba9d24a7612bbc530a40da007517d4315be7651))
+
+
+### Bug Fixes
+
+* clear the lint backlog and undo two formatter regressions ([7cd4e10](https://github.com/rnoro/tithon/commit/7cd4e107269ca735d145cb9e2cf8b6b51346ff68))
+
+
+### Documentation
+
+* fix guide for Windows in readme ([bd77e14](https://github.com/rnoro/tithon/commit/bd77e14dd4a39c871a476d1139fc5191736c475e))
+* state invariants instead of naming the ledger ([35e4913](https://github.com/rnoro/tithon/commit/35e4913e696817d4bddd67ff8c7861bf54401aea))
+
 ## [0.2.2](https://github.com/rnoro/tithon/compare/v0.2.1...v0.2.2) (2026-08-12)
 
 

tithon-0.2.4/CONTRIBUTING.md

@@ -0,0 +1,209 @@
+# Contributing to Tithon
+
+Thanks for being here. Tithon keeps a Python session alive on a remote host
+independently of the client, so most of its interesting failures only show up on
+someone else's machine and under someone else's workflow — the things you hit
+that we never would are the point of this file.
+
+Tithon is alpha software with a written design: [docs/SPEC.md](docs/SPEC.md)
+describes how it currently works and why. It is a description of today's system,
+not a fence around it — see [Changing the design](#changing-the-design).
+
+**Everything here is in English** — issues, pull requests, commit messages, code
+comments, and docs
+
+## Open an issue first
+
+- **Bugs, questions, ideas** — [open an issue][issues]. Always welcome, no
+  ceremony needed.
+- **Code changes** — please sketch the approach in an issue before writing the
+  patch. This is about saving your time, not gatekeeping: a change that crosses
+  the daemon / journal / fold boundary is a design conversation, and it is
+  unfair to discover that after you have written the code.
+- Small, self-evident fixes (a typo, a broken link, a crash with a traceback
+  attached) can go straight to a pull request.
+
+Some rough edges are already tracked in
+[docs/known_issue.md](docs/known_issue.md) — worth a look first.
+
+## Reporting a bug
+
+The daemon outlives the client, so "what the UI showed" is rarely enough to
+locate the fault. Useful reports include:
+
+- **The daemon log** — `$TITHON_HOME/daemon.log` (`~/.tithon/daemon.log` by
+  default). The interesting window usually starts at the last `attach` before
+  things went wrong.
+- **`tithon status`** output.
+- **Versions** — Tithon (`pip show tithon`), the VSCode extension, VSCode, and
+  Python.
+- **Environment** — OS and how you connect: local, Tunnel, Remote-SSH, WSL,
+  container, cluster login node. Tithon's whole job is surviving a flaky link
+  between client and host, so how yours is shaped is diagnostic information.
+- **Reproduction as a sequence of session events** — "start daemon → run a cell
+  that prints for 30s → close the window → reopen after it finishes → output is
+  missing". Whether the client disconnected, and whether the daemon or the host
+  restarted, are usually the decisive details.
+
+If you are on a platform Tithon does not support yet, say so in the issue rather
+than assuming it is out of scope — that is how support gets planned.
+
+## Development setup
+
+You need Python **3.11 or newer** and Node for the extension. The repo is set up
+for [uv](https://docs.astral.sh/uv/) and npm, but nothing stops you using
+another toolchain as long as the checks below pass.
+
+Python — from the repo root:
+
+```bash
+uv sync                 # runtime deps + the dev group (pytest, ruff, matplotlib, tqdm, ipywidgets)
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+```
+
+`uv sync` provisions a matching interpreter for you, so an older default
+`python3` on your machine is not a problem. Run the CLI through `uv run tithon`
+(or the project venv) to be sure you are testing the tree and not an installed
+copy.
+
+VSCode extension — from `extension/`:
+
+```bash
+npm ci
+npm run lint            # biome
+npm run build           # tsc
+npm test                # vitest unit tests
+```
+
+The daemon runs in the foreground, so while debugging it is easiest to background
+it and tail the log rather than tie up a terminal.
+
+## Verifying a change
+
+Unit tests are not the whole safety net here. Most regressions in Tithon are
+cross-process — a kernel that should have survived, a snapshot that arrives one
+message short — and those are caught by the verification suite in
+[scripts/](scripts/), which drives real daemons and real kernels. It is grouped
+into topic bundles:
+
+```bash
+make -C scripts fast          # every hermetic test — the required gate
+make -C scripts restore       # just the reconnect/restore bundle, etc.
+```
+
+Topics: `core` `serializer` `backpressure` `widgets` `restore` `livesync`
+`kernels` `richoutputs` `notebook`. Meta bundles: `fast` (all hermetic),
+`vscode` (all real-VSCode), `all` (both). `scripts/run_verify.sh` documents what
+is in each.
+
+**What a pull request needs:**
+
+1. `make -C scripts fast` green, plus the topic bundle covering the area you
+   touched.
+2. That suite's summary table pasted into the PR body — "tests pass" without the
+   output is not something a reviewer can check.
+3. The language gates for the side you touched: `ruff check` / `ruff format
+   --check` for Python, `npm run lint` / `npm run build` for the extension.
+
+`make -C scripts vscode` drives a real VSCode instance and needs a display
+(xvfb) plus network, so it is a nice-to-have rather than a requirement — just
+say in the PR whether you could run it.
+
+New behavior should arrive with a test. If the behavior is cross-process, that
+means a script in `scripts/` and an entry in its bundle; if it is pure logic, a
+unit test is fine. Adding a case that fails before your fix and passes after is
+the most persuasive thing in a PR.
+
+One practical note: the scripts spawn **detached** kernels under a temporary
+`/tmp/tithon-*` home, so an interrupted run can leave some behind and make later
+runs flaky. Clear them with:
+
+```bash
+pkill -f '[i]pykernel_launcher.*-f /tmp/tithon'
+```
+
+The `[i]` character class is deliberate — a bare pattern also matches `pkill`'s
+own command line.
+
+## Changing the design
+
+Tithon's current behavior rests on a handful of decisions that a lot of the code
+quietly depends on. They are listed here so you can tell the difference between
+*changing* one and *breaking* one by accident — not to put them beyond
+discussion. Each exists for a reason, and a better reason supersedes it.
+
+- The kernel is spawned **detached** rather than as a child of the daemon, with
+  its connection file persisted, so it survives the daemon and can be
+  re-attached.
+- Sessions are **per file (uri)**, isolated from one another and created lazily.
+- Messages from the kernel are journaled **verbatim**, with a folded
+  per-execution snapshot derived from them, so a reconnecting client can be
+  served without replaying everything.
+- Client sync is **snapshot + delta over a monotonic sequence number**, which is
+  what makes a reconnect lossless rather than best-effort.
+- Rich output is stored as **files with references in the journal**, not
+  base64 inline, which is what keeps a long-running live plot from growing
+  without bound.
+- The client-facing binding is a **unix domain socket with 0600 permissions**,
+  which is what keeps a session on a shared host private.
+
+If you think one of these should change — a different transport, a different
+storage model, a platform that needs a different process model — that is a
+welcome conversation. Open an issue, make the case against the property it
+currently protects, and update [docs/SPEC.md](docs/SPEC.md) in the same PR that
+changes the behavior. The thing to avoid is a patch that silently invalidates
+one of them while the spec still claims it holds.
+
+## Keeping the tests honest
+
+The verification suite is only worth anything if it can still fail. Bug fixes,
+stronger assertions, better isolation, and new cases are all welcome. What is
+not: hardcoding a pass, skipping a test to get green, hiding a race by
+lengthening a `sleep`, or replacing a real-process check with a mock. If a
+script is wrong, fix the script and explain the reasoning in the PR — a test
+that no longer detects its failure is worse than no test.
+
+## Commits and pull requests
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/):
+`type(scope): summary`, where type is `feat` / `fix` / `refactor` / `test` /
+`docs` / `build` / `chore` and scope is optional (`daemon`, `extension`,
+`verify`, …).
+
+```text
+feat(extension): render ipywidget outputs
+fix(daemon): re-attach the kernel after a socket reset
+```
+
+This is load-bearing, not cosmetic:
+[release-please](https://github.com/googleapis/release-please) derives the
+version bump and the CHANGELOG from these subjects, so a malformed one shows up
+verbatim in a release note.
+
+- Keep subjects to 72 characters or fewer; bodies optional and short.
+- Investigation history belongs in the PR discussion, not in the permanent log.
+- Please leave AI model, provider, and reviewer names out of commit subjects and
+  bodies.
+- `main` is the release branch — base your work on `develop` unless the issue
+  says otherwise, and tidy up "fix typo" commits before asking for review.
+
+## Using AI tools
+
+You are welcome to use them. If you point an agent at this repo, give it this
+file and [docs/SPEC.md](docs/SPEC.md) — the design rationale is what an agent
+cannot infer from the code, and it is what keeps a patch from quietly
+invalidating a property something else depends on.
+
+The bar is the same either way, and it is on you rather than the tool: **run the
+bundles yourself and read the output before you submit.** A patch whose tests
+were never executed, or a bug report that is a model's speculation rather than
+an observed failure, costs more to review than it saves — those will be closed
+with a request for the missing evidence.
+
+## License
+
+Tithon is [MIT](LICENSE) licensed. By contributing you agree that your
+contribution is licensed under the same terms.
+
+[issues]: https://github.com/rnoro/tithon/issues

{tithon-0.2.2 → tithon-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tithon
-Version: 0.2.2
+Version: 0.2.4
 Summary: Tithon - The immortal Python REPL that will set you free.
 Project-URL: Homepage, https://github.com/rnoro/tithon
 Project-URL: Documentation, https://tithon.readthedocs.io/
@@ -47,6 +47,7 @@ Classifier: Topic :: Text Processing :: Linguistic
 Requires-Python: >=3.11
 Requires-Dist: ipykernel>=6
 Requires-Dist: jupyter-client>=8
+Requires-Dist: psutil>=5.9
 Requires-Dist: websockets>=12
 Description-Content-Type: text/markdown
 
@@ -105,7 +106,8 @@ moves it to the host.
   remote, connect over a Tunnel or Remote-SSH — the notebook then works exactly
   as it does locally.
 
-> Windows is not currently supported.
+> On Windows, we recommend running Tithon inside WSL and connecting with VS Code using the WSL extension.  
+> Native Windows is not currently supported.
 
 ## Install
 
@@ -241,6 +243,39 @@ Outputs live in `$TITHON_HOME/sessions/<session>/journal.db` (raw messages plus
 folded snapshots), with rich outputs written as files under
 `<workdir>/.tithon/outputs/` and referenced from the journal.
 
+### Sharing a notebook's outputs
+
+A percent-format `.py` holds only code, and the journal above is machine-local
+(binary, unbounded, unmergeable). So alongside it the daemon keeps the _folded_
+output state as text in your project:
+
+```
+<project>/.tithon/
+  cells/<relpath>.json   # what each cell currently shows
+  outputs/               # its images, sha256-deduplicated
+```
+
+Commit that directory and whoever clones the repository opens the file with your
+results already in it — what `.ipynb` gives you, without the outputs living in
+the `.py`. Images are referenced rather than embedded, so a plot redrawn every
+step of a training loop still commits one file, not one per frame. Leave the
+directory uncommitted (or `.gitignore` it) to keep your outputs to yourself;
+nothing else depends on it, and your own session restores from the journal
+either way.
+
+Terminating a kernel yourself (`tithon kill`, or **Tithon: Terminate Kernel…**)
+means you are done with that session, so reopening the file no longer restores
+its cells. The history is kept — **Tithon: Restore Previous Outputs** brings it
+back. Every involuntary loss (daemon restart, host reboot, dropped tunnel, idle
+GC) still restores automatically.
+
+## Contributing
+
+Bug reports are especially welcome — Tithon's job is surviving disconnects, and
+the ones that matter happen on setups we don't have. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for what makes a report actionable, how to
+set up a development environment, and how to propose a change to the design.
+
 ## License
 
 [MIT](LICENSE).

{tithon-0.2.2 → tithon-0.2.4}/README.md

@@ -53,7 +53,8 @@ moves it to the host.
   remote, connect over a Tunnel or Remote-SSH — the notebook then works exactly
   as it does locally.
 
-> Windows is not currently supported.
+> On Windows, we recommend running Tithon inside WSL and connecting with VS Code using the WSL extension.  
+> Native Windows is not currently supported.
 
 ## Install
 
@@ -189,6 +190,39 @@ Outputs live in `$TITHON_HOME/sessions/<session>/journal.db` (raw messages plus
 folded snapshots), with rich outputs written as files under
 `<workdir>/.tithon/outputs/` and referenced from the journal.
 
+### Sharing a notebook's outputs
+
+A percent-format `.py` holds only code, and the journal above is machine-local
+(binary, unbounded, unmergeable). So alongside it the daemon keeps the _folded_
+output state as text in your project:
+
+```
+<project>/.tithon/
+  cells/<relpath>.json   # what each cell currently shows
+  outputs/               # its images, sha256-deduplicated
+```
+
+Commit that directory and whoever clones the repository opens the file with your
+results already in it — what `.ipynb` gives you, without the outputs living in
+the `.py`. Images are referenced rather than embedded, so a plot redrawn every
+step of a training loop still commits one file, not one per frame. Leave the
+directory uncommitted (or `.gitignore` it) to keep your outputs to yourself;
+nothing else depends on it, and your own session restores from the journal
+either way.
+
+Terminating a kernel yourself (`tithon kill`, or **Tithon: Terminate Kernel…**)
+means you are done with that session, so reopening the file no longer restores
+its cells. The history is kept — **Tithon: Restore Previous Outputs** brings it
+back. Every involuntary loss (daemon restart, host reboot, dropped tunnel, idle
+GC) still restores automatically.
+
+## Contributing
+
+Bug reports are especially welcome — Tithon's job is surviving disconnects, and
+the ones that matter happen on setups we don't have. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for what makes a report actionable, how to
+set up a development environment, and how to propose a change to the design.
+
 ## License
 
 [MIT](LICENSE).