Prepare veralang distribution for PyPI publication

.github/workflows/ci.yml

@@ -255,6 +255,48 @@ jobs:
       - name: Check wheel availability across supported platforms
         run: python scripts/check_wheel_availability.py
 
+  package-distribution:
+    # Build the exact artifacts that will eventually be uploaded under
+    # the `veralang` distribution name (#737).  This stays separate from
+    # release automation (#481): PR CI validates artifacts but publishes
+    # nothing.
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install packaging tools
+        run: pip install build twine
+
+      - name: Build and inspect distribution archives
+        run: |
+          python -m build
+          python -m twine check dist/*
+          python scripts/check_distribution.py dist
+
+      - name: Install and smoke-test the wheel outside the checkout
+        run: |
+          python -m venv "$RUNNER_TEMP/veralang-wheel-smoke"
+          "$RUNNER_TEMP/veralang-wheel-smoke/bin/python" -m pip install dist/*.whl
+          cp examples/hello_world.vera "$RUNNER_TEMP/hello_world.vera"
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/veralang-wheel-smoke/bin/vera" version
+          "$RUNNER_TEMP/veralang-wheel-smoke/bin/vera" check hello_world.vera
+          run_out="$("$RUNNER_TEMP/veralang-wheel-smoke/bin/vera" run hello_world.vera)"
+          printf '%s\n' "$run_out"
+          case "$run_out" in
+            *"Hello, World!"*) ;;
+            *) echo "::error::wheel smoke: unexpected 'vera run' output"; exit 1 ;;
+          esac
+
   sbom:
     permissions:
       contents: read

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **PyPI publication readiness** ([#737](https://github.com/aallan/vera/issues/737)) renames the Python distribution to `veralang` while preserving the `vera` command and import package, adds a dedicated registry README, and gates the built sdist/wheel contents plus an installed-wheel CLI smoke test in CI. The existing GitHub-source installation path remains supported; automated publication is still gated on [#481](https://github.com/aallan/vera/issues/481).
 - **Inference + JSON composition example** ([#379](https://github.com/aallan/vera/issues/379)) demonstrates an effectful model call flowing through pure JSON parsing, typed integer extraction, and a statically proved 0–100 normalization contract. Raw JSON and tagged or untagged fenced responses are accepted, with the original completion retained in malformed-response diagnostics.
 
 ### Fixed

LSP_SERVER.md

@@ -27,11 +27,18 @@ the introspection commands), see the CLI cookbook,
 The server lives behind the optional `[lsp]` extra (pure-Python
 dependencies: `pygls`, `lsprotocol`):
 
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install "veralang[lsp]"
+```
+
+To install the current GitHub source instead:
+
 ```bash
 git clone https://github.com/aallan/vera.git
 cd vera
-python -m venv .venv && source .venv/bin/activate
-pip install -e ".[lsp]"     # or ".[dev]", which includes it
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install -e ".[lsp]"     # or ".[dev]", which includes it
 ```
 
 Then:

PYPI_README.md

@@ -0,0 +1,71 @@
+# Vera
+
+Vera is a programming language designed for large language models to write. It
+has mandatory contracts, algebraic effects, typed slot references instead of
+variable names, and a compiler that emits WebAssembly.
+
+Full documentation, examples, and the language specification are available at
+[veralang.dev](https://veralang.dev) and in the
+[GitHub repository](https://github.com/aallan/vera).
+
+## Install a released version
+
+Vera requires Python 3.11 or later. Create a virtual environment and install
+the `veralang` distribution:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install veralang
+```
+
+On Windows, activate the environment with `.venv\Scripts\activate` instead.
+For editor and agent integration through the language server, install the LSP
+extra:
+
+```bash
+python -m pip install "veralang[lsp]"
+```
+
+The distribution is named `veralang`, but the installed command remains
+`vera`, and Python code still imports it as `import vera`. **Do not run `pip install vera`**: that name belongs to an unrelated
+ERAV citizen-science project on PyPI.
+
+## Install from GitHub source
+
+The source route remains supported for compiler development, unreleased
+changes, and testing the current `main` branch:
+
+```bash
+git clone https://github.com/aallan/vera.git
+cd vera
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+Use `python -m pip install -e ".[lsp]"` for the language server or
+`python -m pip install -e ".[dev]"` when working on the compiler.
+
+## Try it
+
+```vera
+public fn safe_divide(@Int, @Int -> @Int)
+  requires(@Int.1 != 0)
+  ensures(@Int.result == @Int.0 / @Int.1)
+  effects(pure)
+{
+  @Int.0 / @Int.1
+}
+```
+
+```bash
+vera check program.vera
+vera verify program.vera
+vera run program.vera
+```
+
+See the [CLI cookbook](https://github.com/aallan/vera/blob/main/TOOLCHAIN.md),
+[language reference](https://veralang.dev/SKILL.md),
+[supported-platform policy](https://github.com/aallan/vera#supported-platforms),
+and [issue tracker](https://github.com/aallan/vera/issues) for more.

README.md

@@ -115,15 +115,33 @@ Every diagnostic has a stable error code (`E001`–`E702`) and is available as s
 
 ### Installation
 
+Install the released `veralang` distribution from PyPI:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install veralang
+```
+
+The distribution is named `veralang`, but the installed command remains
+`vera`, and Python code still imports it as `import vera`. For editor and agent integration through the language server, install
+`python -m pip install "veralang[lsp]"`. Do not run `pip install vera`: that
+name belongs to an unrelated project on PyPI.
+
+The GitHub source route remains supported for compiler development, unreleased
+changes, and testing the current `main` branch:
+
 ```bash
 git clone https://github.com/aallan/vera.git
 cd vera
 python -m venv .venv
-source .venv/bin/activate
-pip install -e ".[dev]"
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install -e ".[dev]"
 ```
 
-`[dev]` includes everything (tests, linters, the language server). For a lighter install that only adds editor/agent support to the base toolchain, use `pip install -e ".[lsp]"` — see [LSP_SERVER.md](LSP_SERVER.md).
+`[dev]` includes everything (tests, linters, the language server). For a lighter
+source install that only adds editor/agent support to the base toolchain, use
+`python -m pip install -e ".[lsp]"` — see [LSP_SERVER.md](LSP_SERVER.md).
 
 
 #### Supported platforms

SKILL.md

@@ -9,15 +9,30 @@ Vera is a programming language designed for LLMs to write. It uses typed slot re
 
 ## Installation
 
-Vera requires Python 3.11 or later. Node.js 22+ is optional (only needed for `vera compile --target browser` and browser parity tests). Install from the repository:
+Vera requires Python 3.11 or later. Node.js 22+ is optional (only needed for `vera compile --target browser` and browser parity tests). Install the released `veralang` distribution from PyPI:
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install veralang
+```
+
+This installs the `vera` command and all runtime dependencies (Lark parser, Z3 solver, wasmtime). For editor/agent integration via the Language Server Protocol, install `python -m pip install "veralang[lsp]"` — see [LSP_SERVER.md](LSP_SERVER.md).
+
+The GitHub source route remains supported for unreleased changes and compiler development:
 
 ```bash
 git clone https://github.com/aallan/vera.git && cd vera
-python -m venv .venv && source .venv/bin/activate
-pip install -e .
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install -e .
+```
+
+For an editable source install with the language server, use `python -m pip install -e ".[lsp]"`. Verify the installed CLI — works for either route, with no checkout required:
+
+```bash
+vera version
 ```
 
-This installs the `vera` command and all runtime dependencies (Lark parser, Z3 solver, wasmtime). For editor/agent integration via the Language Server Protocol, install the optional extra instead: `pip install -e ".[lsp]"` — see [LSP_SERVER.md](LSP_SERVER.md). After installation, verify it works:
+From a source checkout you can also run the bundled example end to end:
 
 ```bash
 vera check examples/hello_world.vera    # should print "OK: examples/hello_world.vera"
@@ -27,14 +42,14 @@ vera run examples/hello_world.vera      # should print "Hello, World!"
 If you are working on the compiler itself, install development dependencies too:
 
 ```bash
-pip install -e ".[dev]"
+python -m pip install -e ".[dev]"
 ```
 
 > **Platform support**: Vera is tested in CI on macOS 15+ (Apple Silicon), Ubuntu 24.04 LTS (x86_64), and Windows Server 2022, against Python 3.11–3.13. macOS 14 (Sonoma) and earlier, and Ubuntu 22.04 LTS aarch64, are out of scope — install will fail at dependency resolution. See [README §Supported platforms](README.md#supported-platforms) for the full matrix, workarounds, and the data behind the baseline.
 >
 > **For agents running in a sandbox** (Claude.ai, Code Interpreter, container-based execution environments, etc.): the steps above work. Sandboxes typically have Python, `git`, `pip`, and outbound network access — that's all Vera needs. **Run the install commands and verify with `vera run examples/hello_world.vera` before concluding that Vera "isn't available." Don't assume the sandbox lacks the toolchain — try it.**
 >
-> One caveat: `pip install vera` (no source) installs a *different* package from PyPI (an ERAV citizen-science library — unrelated to this Vera). Always install from the GitHub source clone shown above.
+> One caveat: `pip install vera` installs a *different* package from PyPI (an ERAV citizen-science library — unrelated to this Vera). Use the `veralang` distribution or the GitHub source clone shown above; both install the `vera` command.
 
 ## Toolchain
 

docs/SKILL.md

@@ -9,15 +9,30 @@ Vera is a programming language designed for LLMs to write. It uses typed slot re
 
 ## Installation
 
-Vera requires Python 3.11 or later. Node.js 22+ is optional (only needed for `vera compile --target browser` and browser parity tests). Install from the repository:
+Vera requires Python 3.11 or later. Node.js 22+ is optional (only needed for `vera compile --target browser` and browser parity tests). Install the released `veralang` distribution from PyPI:
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install veralang
+```
+
+This installs the `vera` command and all runtime dependencies (Lark parser, Z3 solver, wasmtime). For editor/agent integration via the Language Server Protocol, install `python -m pip install "veralang[lsp]"` — see [LSP_SERVER.md](https://github.com/aallan/vera/blob/main/LSP_SERVER.md).
+
+The GitHub source route remains supported for unreleased changes and compiler development:
 
 ```bash
 git clone https://github.com/aallan/vera.git && cd vera
-python -m venv .venv && source .venv/bin/activate
-pip install -e .
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install -e .
+```
+
+For an editable source install with the language server, use `python -m pip install -e ".[lsp]"`. Verify the installed CLI — works for either route, with no checkout required:
+
+```bash
+vera version
 ```
 
-This installs the `vera` command and all runtime dependencies (Lark parser, Z3 solver, wasmtime). For editor/agent integration via the Language Server Protocol, install the optional extra instead: `pip install -e ".[lsp]"` — see [LSP_SERVER.md](https://github.com/aallan/vera/blob/main/LSP_SERVER.md). After installation, verify it works:
+From a source checkout you can also run the bundled example end to end:
 
 ```bash
 vera check examples/hello_world.vera    # should print "OK: examples/hello_world.vera"
@@ -27,14 +42,14 @@ vera run examples/hello_world.vera      # should print "Hello, World!"
 If you are working on the compiler itself, install development dependencies too:
 
 ```bash
-pip install -e ".[dev]"
+python -m pip install -e ".[dev]"
 ```
 
 > **Platform support**: Vera is tested in CI on macOS 15+ (Apple Silicon), Ubuntu 24.04 LTS (x86_64), and Windows Server 2022, against Python 3.11–3.13. macOS 14 (Sonoma) and earlier, and Ubuntu 22.04 LTS aarch64, are out of scope — install will fail at dependency resolution. See [README §Supported platforms](https://github.com/aallan/vera/blob/main/README.md#supported-platforms) for the full matrix, workarounds, and the data behind the baseline.
 >
 > **For agents running in a sandbox** (Claude.ai, Code Interpreter, container-based execution environments, etc.): the steps above work. Sandboxes typically have Python, `git`, `pip`, and outbound network access — that's all Vera needs. **Run the install commands and verify with `vera run examples/hello_world.vera` before concluding that Vera "isn't available." Don't assume the sandbox lacks the toolchain — try it.**
 >
-> One caveat: `pip install vera` (no source) installs a *different* package from PyPI (an ERAV citizen-science library — unrelated to this Vera). Always install from the GitHub source clone shown above.
+> One caveat: `pip install vera` installs a *different* package from PyPI (an ERAV citizen-science library — unrelated to this Vera). Use the `veralang` distribution or the GitHub source clone shown above; both install the `vera` command.
 
 ## Toolchain
 

docs/index.md

@@ -208,17 +208,25 @@ Serving HTTP on http://0.0.0.0:8080/
 
 ## Get Started
 
-Python 3.11+ and Git. Everything else installs into a virtual environment.
+Python 3.11+. Everything else installs into a virtual environment.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install veralang
+```
+
+Or install the current GitHub source for development:
 
 ```bash
-# Clone and install
 git clone https://github.com/aallan/vera.git
 cd vera
 python -m venv .venv
 source .venv/bin/activate
-pip install -e ".[dev]"
+python -m pip install -e ".[dev]"
+```
 
-# Check, verify, run, compile
+```bash
 vera check examples/absolute_value.vera
 vera verify examples/safe_divide.vera
 vera run examples/hello_world.vera

docs/llms-full.txt

@@ -15,15 +15,30 @@ Vera is a programming language designed for LLMs to write. It uses typed slot re
 
 ## Installation
 
-Vera requires Python 3.11 or later. Node.js 22+ is optional (only needed for `vera compile --target browser` and browser parity tests). Install from the repository:
+Vera requires Python 3.11 or later. Node.js 22+ is optional (only needed for `vera compile --target browser` and browser parity tests). Install the released `veralang` distribution from PyPI:
+
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install veralang
+```
+
+This installs the `vera` command and all runtime dependencies (Lark parser, Z3 solver, wasmtime). For editor/agent integration via the Language Server Protocol, install `python -m pip install "veralang[lsp]"` — see [LSP_SERVER.md](https://github.com/aallan/vera/blob/main/LSP_SERVER.md).
+
+The GitHub source route remains supported for unreleased changes and compiler development:
 
 ```bash
 git clone https://github.com/aallan/vera.git && cd vera
-python -m venv .venv && source .venv/bin/activate
-pip install -e .
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install -e .
+```
+
+For an editable source install with the language server, use `python -m pip install -e ".[lsp]"`. Verify the installed CLI — works for either route, with no checkout required:
+
+```bash
+vera version
 ```
 
-This installs the `vera` command and all runtime dependencies (Lark parser, Z3 solver, wasmtime). For editor/agent integration via the Language Server Protocol, install the optional extra instead: `pip install -e ".[lsp]"` — see [LSP_SERVER.md](https://github.com/aallan/vera/blob/main/LSP_SERVER.md). After installation, verify it works:
+From a source checkout you can also run the bundled example end to end:
 
 ```bash
 vera check examples/hello_world.vera    # should print "OK: examples/hello_world.vera"
@@ -33,14 +48,14 @@ vera run examples/hello_world.vera      # should print "Hello, World!"
 If you are working on the compiler itself, install development dependencies too:
 
 ```bash
-pip install -e ".[dev]"
+python -m pip install -e ".[dev]"
 ```
 
 > **Platform support**: Vera is tested in CI on macOS 15+ (Apple Silicon), Ubuntu 24.04 LTS (x86_64), and Windows Server 2022, against Python 3.11–3.13. macOS 14 (Sonoma) and earlier, and Ubuntu 22.04 LTS aarch64, are out of scope — install will fail at dependency resolution. See [README §Supported platforms](https://github.com/aallan/vera/blob/main/README.md#supported-platforms) for the full matrix, workarounds, and the data behind the baseline.
 >
 > **For agents running in a sandbox** (Claude.ai, Code Interpreter, container-based execution environments, etc.): the steps above work. Sandboxes typically have Python, `git`, `pip`, and outbound network access — that's all Vera needs. **Run the install commands and verify with `vera run examples/hello_world.vera` before concluding that Vera "isn't available." Don't assume the sandbox lacks the toolchain — try it.**
 >
-> One caveat: `pip install vera` (no source) installs a *different* package from PyPI (an ERAV citizen-science library — unrelated to this Vera). Always install from the GitHub source clone shown above.
+> One caveat: `pip install vera` installs a *different* package from PyPI (an ERAV citizen-science library — unrelated to this Vera). Use the `veralang` distribution or the GitHub source clone shown above; both install the `vera` command.
 
 ## Toolchain
 
@@ -2641,11 +2656,18 @@ the introspection commands), see the CLI cookbook,
 The server lives behind the optional `[lsp]` extra (pure-Python
 dependencies: `pygls`, `lsprotocol`):
 
+```bash
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install "veralang[lsp]"
+```
+
+To install the current GitHub source instead:
+
 ```bash
 git clone https://github.com/aallan/vera.git
 cd vera
-python -m venv .venv && source .venv/bin/activate
-pip install -e ".[lsp]"     # or ".[dev]", which includes it
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install -e ".[lsp]"     # or ".[dev]", which includes it
 ```
 
 Then: