Document the distribution policy: git-clone now, PyPI veralang after the release workflow

[aallan]

Problem

README documents the git-clone install but never states it as policy, so "why isn't this on PyPI?" has no written answer. Meanwhile the PyPI name vera is taken by an unrelated package (an ERAV citizen-science data-model implementation, v1.0.0, verified 2026-06-12) — anyone who runs pip install vera gets something else entirely, and no Vera documentation warns about it.

Decision (2026-06-12)

• Now: git-clone is the supported installation path, stated as policy in README §Install and the FAQ, including an explicit warning that pip install vera installs an unrelated package.
• Later: publish under veralang (verified available on PyPI, 2026-06-12), gated on the automated release workflow (Auto-tag and auto-release on version bump in pyproject.toml #481) — manual PyPI uploads would add another forgettable release step, which is the exact failure mode Auto-tag and auto-release on version bump in pyproject.toml #481 exists to remove.

Audit reference: §3.4, Open Question 1. Size: S.

[aallan]

Planning update — 2026-07-13

This issue now owns the package identity/readiness and user-facing distribution policy side of publishing Vera. Issue #481 owns the release/publishing automation.

Installation policy

After publication, both installation routes remain documented and supported:

1. Released package: create a virtual environment, then python -m pip install veralang.
2. GitHub source: clone aallan/vera, then use python -m pip install -e . (or the existing .[lsp], .[dev], and .[mutation] extras).

The source route remains important for compiler contributors, source inspection, unreleased changes, and testing main. The vera executable, vera Python import package, source directory, and WASM import namespace do not change. Documentation will continue warning that pip install vera installs the unrelated ERAV project.

PR 1 — publication readiness (safe preparatory slice)

This PR will not publish anything or add release automation. It will:

• change the distribution name in pyproject.toml from vera to veralang;
• change self-referencing extras from vera[lsp] / vera[dev] to veralang[lsp] / veralang[dev];
• regenerate uv.lock and update distribution-name assumptions in version-sync and licence tooling;
• retain [project.scripts] vera = "vera.cli:main" and all code/runtime namespaces;
• add a concise PyPI-specific README using absolute links;
• add CI that builds the sdist and universal wheel, validates their metadata/contents, installs the wheel outside the checkout, and smoke-tests vera version, vera check, and vera run;
• document the one-time contributor migration: recreate the venv (or uninstall the old editable vera distribution) before reinstalling.

Public installation docs continue to lead with the GitHub route until the production package exists.

Completion after #481

Once #481's workflow and the maintainer-side PyPI/TestPyPI configuration are ready:

• TestPyPI receives a staging publication;
• the first production PyPI release is veralang==0.1.5;
• README, SKILL, FAQ, website, generated agent docs, and the PyPI README present both PyPI and GitHub installation routes;
• veralang[lsp] is documented for published LSP installs;
• this issue closes only when the package is live and the dual-route documentation is in place.

Planned sequence

1. Document the distribution policy: git-clone now, PyPI veralang after the release workflow #737 PR 1: publication readiness, no upload.
2. Auto-tag and auto-release on version bump in pyproject.toml #481 PR 2: release/Trusted Publishing automation, no version bump and therefore no production upload.
3. Maintainer configures GitHub environments plus pending publishers and validates TestPyPI.
4. Document the distribution policy: git-clone now, PyPI veralang after the release workflow #737/Auto-tag and auto-release on version bump in pyproject.toml #481 release PR: bump to 0.1.5, update dual-route docs, merge, approve production deployment, then verify PyPI and the GitHub Release.

[aallan]

Draft PR #1027 implements PR 1 / the publication-readiness slice of the plan documented above.

It:

• changes the Python distribution identity to veralang while preserving the vera CLI and vera import package;
• updates the self-referencing extras and lockfile;
• documents both pip install veralang and the retained GitHub editable-install route;
• builds, inspects, installs, and smoke-tests the wheel/sdist in CI; and
• adds a dedicated PyPI-facing README plus archive-content validation.

It intentionally stops before publication: the PR does not upload to TestPyPI or PyPI and adds no Trusted Publishing or release-trigger workflow. Review/merge and the first registry publication/verification remain under this issue; reusable release automation and approval policy remain the separate follow-up in #481.

[aallan]

One-time local environment migration after merge

This PR does not rename the CLI or import package: the command remains vera and Python imports remain import vera.

However, pip treats the old vera distribution metadata and the new veralang distribution metadata as different installed projects. An existing editable development environment should therefore be refreshed once after this change lands; merely installing the new name can leave stale vera metadata behind.

For an existing pip-managed development venv:

python -m pip uninstall -y vera veralang
python -m pip install -e ".[dev]"

This temporarily removes and then recreates the same vera command. Recreating .venv from scratch is the cleanest alternative, but it is optional rather than required.

For a uv-managed environment:

uv sync --extra dev

This is a one-time development-environment cleanup caused by the distribution rename; normal Vera CLI usage is otherwise unchanged.