Metadata-Version: 2.4
Name: megillah
Version: 2026.9.17.34
Summary: A planning technology for sustained, nonlinear work with AI collaborators
License-Expression: AGPL-3.0-or-later
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8.1
Requires-Dist: fastembed<0.9,>=0.8
Requires-Dist: httpx2<3,>=2.5
Requires-Dist: huggingface-hub<2,>=1.28
Requires-Dist: mcp<3,>=2.2
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pyyaml<7,>=6
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == "dev"
Requires-Dist: jsonschema<5,>=4.26; extra == "dev"
Requires-Dist: mypy<2,>=1.20; extra == "dev"
Requires-Dist: pytest<10,>=9; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
Requires-Dist: setuptools>=77; extra == "dev"
Requires-Dist: types-jsonschema<5,>=4.26; extra == "dev"
Requires-Dist: types-PyYAML<7,>=6; extra == "dev"
Requires-Dist: types-setuptools<81,>=80; extra == "dev"
Dynamic: license-file

# Megillah

Megillah is a planning technology for sustained, nonlinear work conducted with
AI collaborators. It keeps purposeful work — its framing, requirements,
commentary, evidence, and history — in one durable record that any client can
pick up cold.

The product argument and the domain that supports it are documented
separately:

- [Product thesis and design rationale](docs/product.md)
- [Domain specification](docs/domain.md)
- [Operating the Workspace store](docs/operations.md)

Reference for each surface, and for working on Megillah itself:

- [Using the CLI](docs/cli.md)
- [Serving the Workspace over HTTP](docs/serving.md)
- [Connecting an agent through MCP](docs/mcp.md)
- [The planning browser](docs/browser.md)
- [Development](docs/development.md)

## Attribution and provenance

Operations record the contributing Client, read from options or the
environment:

| Variable | Meaning |
| --- | --- |
| `MEGILLAH_STORE` | Path to the Workspace store |
| `MEGILLAH_CLIENT` | The Client recorded as provenance |
| `MEGILLAH_PROJECT` | The Project a command acting in one Project as a whole acts in |
| `MEGILLAH_HOST` | Interface `megillah serve` binds |
| `MEGILLAH_PORT` | Port `megillah serve` listens on |
| `MEGILLAH_ALLOWED_HOSTS` | Hostnames the instance answers to, comma separated |
| `MEGILLAH_LISTENER_URL` | Where `megillah mcp` reaches the boundary |
| `MEGILLAH_SHARED_SECRET` | The secret guarding the boundary, which `megillah mcp` presents |

`megillah mcp` takes no session Client. One server serves many conversations
across many Assignments, so each contribution is attributed to the Client its
connection negotiated. Nor does it take `MEGILLAH_PROJECT`: a tool acting in
one Project as a whole names it. Starting it with that configured says so
rather than quietly ignoring it.

## Versioning

Megillah's release is derived, not written down. It is read from the commit a
checkout is on: the UTC day that commit was made, and where it falls among
that day's commits — `2026.9.10` for the first, `2026.9.10.1` for the next,
and so on. The build stamps it into the distribution's metadata, and installed
processes report that.

Every merge adds a commit and changes the release, without a manual version
edit. An installed distribution keeps the release stamped at build time,
even when its source checkout advances. Reinstalling updates that metadata.

Building needs the whole history. A shallow checkout holds only the commits it
was given, so it would count fewer of the day's commits than exist and derive
a release another commit already carries; the build refuses that rather than
answer it. Continuous integration must check out with full depth, and a source
archive carries the release already stamped into it, so building from one
needs no history at all.

`uv run python -m megillah.versioning`, run in a checkout, prints the release
that checkout derives.

### Publishing a release

Every merge to `main` whose Verify run passes is published to PyPI under its
release. Nothing is tagged or chosen by hand. Verify builds the source archive
and wheel, installs the wheel alone, and serves the browser from it. Once every
job has passed on `main`, it uploads that same wheel. The source archive is
built and checked but not published, which keeps each release small.

Releases are unique along `main`'s first-parent line: each commit there
descends from every earlier one, so a later commit made the same day always
counts more of that day's commits. Every commit on that line gets its own
Verify run, and runs on `main` are never cancelled, so no merge is skipped. A
merge whose run fails is not published, and the next one that passes is.

The upload uses PyPI's trusted publishing: PyPI accepts a job running in this
repository's `pypi` environment by its GitHub identity, so no credential is
stored. That environment admits only `main`, so pull requests and other
branches never publish. A published release cannot be replaced, only yanked.

This release identifies artifacts built from this repository. It is not the
Workspace schema version and not an outside-process protocol version: the MCP
protocol revisions the server speaks are negotiated with each client and move
on their own schedule.

## License

Megillah is free software under the GNU Affero General Public License,
version 3 or later. See [LICENSE](LICENSE). Anyone may run, study, change,
and share it; anyone who offers a modified Megillah to others over a network
must offer them its source under the same terms.
