Metadata-Version: 2.5
Name: megillah
Version: 2026.9.23.644
Summary: A planning technology for sustained, nonlinear work with AI collaborators
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
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
Requires-Dist: click<9,>=8.1
Requires-Dist: fastapi<0.142,>=0.141
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: pydantic<3,>=2.13
Requires-Dist: pyjwt[crypto]<3,>=2.12
Requires-Dist: pyyaml<7,>=6
Requires-Dist: starlette<2,>=1.6
Requires-Dist: uvicorn<0.53,>=0.52
Requires-Dist: workos<11,>=10.4
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == 'dev'
Requires-Dist: editables<0.7,>=0.5; extra == 'dev'
Requires-Dist: hatch-vcs<0.6,>=0.5; extra == 'dev'
Requires-Dist: hatchling<2,>=1.27; 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: types-jsonschema<5,>=4.26; extra == 'dev'
Requires-Dist: types-pyyaml<7,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# 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), on FastAPI and uvicorn
- [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_WORKOS_CLIENT_ID` | The WorkOS environment a guarded instance logs its operator in through |
| `MEGILLAH_WORKOS_API_KEY` | That environment's API key |
| `MEGILLAH_OPERATOR_EMAIL` | The one email address a guarded instance admits |
| `MEGILLAH_BROWSER_URL` | The address a browser opens a guarded instance at |

## Versioning

A release names the UTC day its commit was made and the Verify run that built
it: `2026.9.18.413` is run 413, on a commit made on 18 September 2026. Nobody
writes it down. Continuous integration tags the commit with its release, and
the build reads that tag through [hatch-vcs](https://github.com/ofek/hatch-vcs)
into the distribution's metadata, which installed processes report.

Each merge to `main` gets its own Verify run, and GitHub numbers runs in the
order they start, so releases increase along `main`. Releases published
before this scheme counted the day's merges instead, so a day's first was
`2026.9.10`; run numbers had already passed those counts, so every earlier
release orders below.

A tagged commit builds its release from any checkout, shallow included, and a
source archive carries its release in its metadata, so building from one needs
no history. Any other commit builds as a development release, such as
`2026.9.18.414.dev3+g1a2b3c4` three commits past the last tag, or
`0.1.dev3+g1a2b3c4` where no tag has been fetched. An installed distribution
keeps the release it was built with, even when its checkout moves on;
reinstalling updates it. `git tag --points-at HEAD` names the release of a
tagged checkout.

### 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 tags the commit it checked
out, builds the source archive and wheel, installs the wheel alone, and serves
the browser from it. Once every job has passed on `main`, it pushes the tag to
GitHub and then uploads that same wheel, so every published release has its
tag. The source archive is built and checked but not published, which keeps
each release small.

Runs on `main` are never cancelled, so no merge is skipped. A merge whose run
fails is neither tagged nor published; a re-run keeps its run number, so it
publishes under the same release. Run numbers belong to `verify.yml`: renaming
it would start them again, below releases already published, and PyPI's trusted
publisher names it too.

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 tag or 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.
