@@ -0,0 +1,135 @@
+name: Publish dev build to PyPI
+
+# Every merge to main publishes a PEP 440 dev release (e.g. 0.3.10.dev7) to
+# PyPI, so the latest main is always installable from the real index with real
+# dependency resolution. Dev releases are pre-releases: pip and uv skip them
+# unless asked, so ordinary installs keep getting the latest stable.
+#
+# Tagged releases (including rc/beta/alpha) are handled by publish-to-pypi.yml.
+on:
+  push:
+    branches: [main]
+  # Ad-hoc runs, e.g. re-publishing after a PyPI outage.
+  workflow_dispatch:
+
+# Least privilege by default: jobs get no GITHUB_TOKEN scopes unless they
+# opt in below.
+permissions: {}
+
+# Serialize publishes so versions land in merge order. Queued runs are not
+# cancelled — each merge should still get its own dev build.
+concurrency:
+  group: publish-dev-to-pypi
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build dev distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      should-publish: ${{ steps.version.outputs.should-publish }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # hatch-vcs derives the version from git tags, so we need full history.
+          fetch-depth: 0
+
+      - name: Install uv
+        # uv provisions its own Python (honoring requires-python), so no
+        # separate actions/setup-python step is needed.
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Compute dev version
+        id: version
+        # Between releases hatch-vcs produces something like
+        # "0.3.10.dev16+gb710c2982". The "+g..." local version segment is valid
+        # PEP 440 but is rejected by PyPI on upload, so it has to go. We keep
+        # setuptools-scm's own next-version guess (0.3.10 — the patch bump
+        # after the latest tag) rather than re-deriving it here, and use the
+        # run number as the dev counter: it is strictly increasing, so each
+        # merge sorts after the last and re-runs never collide.
+        run: |
+          RAW=$(uvx --from setuptools-scm python -c \
+            "from setuptools_scm import get_version; print(get_version())")
+          echo "setuptools-scm reports: $RAW"
+
+          # On a commit that IS a release tag, setuptools-scm returns a clean
+          # version with no .dev component (e.g. "0.3.9" or "0.4.0rc1").
+          # Appending ".dev<run>" to that yields 0.3.9.dev42, which sorts BELOW
+          # the released 0.3.9 — newer code would look older. A tagged commit
+          # is a real release and is published by publish-to-pypi.yml, so there
+          # is no dev build to make here.
+          case "$RAW" in
+            *.dev*) ;;
+            *)
+              echo "::notice::$RAW is a tagged release; skipping dev build."
+              echo "should-publish=false" >> $GITHUB_OUTPUT
+              exit 0
+              ;;
+          esac
+
+          BASE=${RAW%%+*}
+          BASE=${BASE%%.dev*}
+          VERSION="${BASE}.dev${GITHUB_RUN_NUMBER}"
+          echo "Derived version: $RAW -> $VERSION"
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION=$VERSION" >> $GITHUB_ENV
+          echo "should-publish=true" >> $GITHUB_OUTPUT
+
+      - name: Build package
+        if: steps.version.outputs.should-publish == 'true'
+        # hatch-vcs reads SETUPTOOLS_SCM_PRETEND_VERSION in place of the tag.
+        run: |
+          uv build
+          echo "Built distributions:"
+          ls -l dist/
+
+      - name: Store the distribution packages
+        if: steps.version.outputs.should-publish == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dev-package-distributions
+          path: dist/
+
+  publish-dev:
+    name: Publish dev build to PyPI
+    needs: build
+    if: needs.build.outputs.should-publish == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/codeplain
+    permissions:
+      # Mint a short-lived OIDC token so PyPI Trusted Publishing can
+      # authenticate this run — no long-lived API token needed.
+      id-token: write
+
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: dev-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # PyPI uploads are immutable, so a re-run of an already-published
+          # version should be a no-op, not a red build.
+          skip-existing: true
+
+      # Success is deliberately quiet: this runs on every merge to main, which
+      # is already announced elsewhere. Only failures ping.
+      - name: Notify Slack (failure)
+        if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -s -X POST "$SLACK_WEBHOOK_URL" \
+            -H 'Content-type: application/json' \
+            --data "{\"text\":\"*Codeplain Client*: Publishing dev build to PyPI FAILED :x: (commit \`${{ github.sha }}\`). See <${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|the run log>.\"}"
@@ -91,10 +91,23 @@ jobs:
 
       - name: Notify Slack (success)
         if: ${{ success() && env.SLACK_WEBHOOK_URL != '' }}
+        env:
+          # GitHub marks the release itself as a pre-release; the tag
+          # (v0.4.0rc1) carries the same intent for PEP 440.
+          IS_PRERELEASE: ${{ github.event.release.prerelease }}
+          TAG: ${{ github.ref_name }}
         run: |
+          VERSION="${TAG#v}"
+          if [ "$IS_PRERELEASE" = "true" ]; then
+            # pip and uv skip pre-releases by default, so "--upgrade" would
+            # NOT pick this up. Tell people the command that actually works.
+            TEXT="*Codeplain Client*: pre-release \`$TAG\` published to PyPI :test_tube:. Normal installs are unaffected — try it with \`pip install --pre codeplain==$VERSION\`."
+          else
+            TEXT="*Codeplain Client*: \`$TAG\` published to PyPI :white_check_mark:. Install with \`pip install --upgrade codeplain\`."
+          fi
           curl -s -X POST "$SLACK_WEBHOOK_URL" \
             -H 'Content-type: application/json' \
-            --data "{\"text\":\"*Codeplain Client*: \`${{ github.ref_name }}\` published to PyPI :white_check_mark:. Install with \`pip install --upgrade codeplain\`.\"}"
+            --data "$(jq -n --arg t "$TEXT" '{text:$t}')"
 
       - name: Notify Slack (failure)
         if: ${{ failure() && env.SLACK_WEBHOOK_URL != '' }}
 
@@ -67,3 +67,71 @@ Include:
 * the related issue, when applicable,
 * how the change was tested,
 * the `plainlang-examples` example used, when relevant.
+
+## Pre-Releases
+
+Everything below happens on real PyPI — there is no separate test index.
+Pre-releases are invisible to ordinary installs: pip and uv skip them during
+resolution, so `pip install codeplain` and `pip install --upgrade codeplain`
+always serve the latest *stable* release.
+
+### Dev builds (automatic)
+
+Every merge to `main` publishes a dev release such as `0.3.10.dev7`, so the tip
+of main is always installable from the real index:
+
+```bash
+pip install --pre codeplain==0.3.10.dev7
+uv tool install --prerelease allow codeplain
+```
+
+Versions are `<next-patch>.dev<run-number>`, so they sort after the last
+release and before the next one. See `.github/workflows/publish-dev-to-pypi.yml`.
+If that workflow is ever dispatched against a commit that is itself a release
+tag, it skips rather than publishing a dev build that would sort below the
+release.
+
+### Release candidates (manual)
+
+To get a specific build in front of people before it becomes the default
+install, cut a PEP 440 pre-release.
+
+Tag and publish a GitHub release as usual, but with a pre-release version and
+the release marked "pre-release":
+
+```
+v0.4.0a1    alpha
+v0.4.0b1    beta
+v0.4.0rc1   release candidate
+```
+
+`publish-to-pypi.yml` handles these with no special casing: hatch-vcs reads the
+version straight off the tag (`v0.4.0rc1` -> `0.4.0rc1`).
+
+Opt in the same way:
+
+```bash
+pip install --pre codeplain==0.4.0rc1
+```
+
+### Which API a build talks to
+
+Pre-release builds default to the **test** API, so an unreleased client is
+exercised against the unreleased backend:
+
+| build | default API |
+| --- | --- |
+| stable release (`0.3.9`) | `https://api.codeplain.ai` |
+| dev build (`0.3.10.dev7`) | `https://api.test.codeplain.ai` |
+| alpha/beta/rc (`0.4.0rc1`) | `https://api.test.codeplain.ai` |
+
+`--api` always overrides this. Resolution lives in
+`system_config._resolve_default_api_url`, keyed off the version baked into the
+package at build time — so nothing needs configuring at install time.
+
+A source checkout reports the nearest git tag as its version, so it is treated
+as stable and keeps pointing at production; use `--api` to aim it elsewhere.
+
+Because every build above goes to real PyPI, dependency resolution and the
+install path are exactly what an end user gets — the main reason this is
+preferred over publishing to TestPyPI.
@@ -345,7 +345,7 @@ def main():  # noqa: C901
             sys.exit(1)
 
         if not args.api:
-            args.api = "https://api.codeplain.ai"
+            args.api = system_config.default_api_url
 
         try:
             print_status(args.api_key, args.api, system_config.client_version)
@@ -389,7 +389,7 @@ def main():  # noqa: C901
     event_bus = EventBus()
 
     if not args.api:
-        args.api = "https://api.codeplain.ai"
+        args.api = system_config.default_api_url
 
     run_state = RunState(spec_filename=args.filename, replay_with=args.replay_with)
 
 
@@ -6,6 +6,7 @@
 from plain2code_console import console
 from plain2code_exceptions import AmbiguousConfigFileError
 from plain2code_read_config import get_args_from_config
+from system_config import system_config
 
 # Attribute on the parsed Namespace mapping each argument dest to its source:
 # "cli" (explicit on the command line), "config" (from config.yaml), or
@@ -329,8 +330,10 @@ def create_parser():
         "--api",
         type=str,
         nargs="?",
-        const="https://api.codeplain.ai",
-        help="Alternative base URL for the API. Default: `https://api.codeplain.ai`",
+        # Pre-release builds default to the test API; see
+        # system_config._resolve_default_api_url.
+        const=system_config.default_api_url,
+        help=f"Alternative base URL for the API. Default: `{system_config.default_api_url}`",
     )
     _add_arg(
         parser,
 
@@ -1,5 +1,6 @@
 import importlib.resources
 import os
+import re
 import sys
 
 import yaml
@@ -10,6 +11,15 @@
 PRODUCTION_ENV = "production"
 DEVELOPMENT_ENV = "development"
 
+PRODUCTION_API_URL = "https://api.codeplain.ai"
+TEST_API_URL = "https://api.test.codeplain.ai"
+
+# PEP 440 pre-release markers, matched against the end of the release segment:
+# alpha/beta/release-candidate (0.4.0a1, 0.4.0b2, 0.4.0rc1) or a dev release
+# (0.3.10.dev7, published on every merge to main). ".postN" alone is NOT a
+# pre-release and must not match.
+_PRERELEASE_RE = re.compile(r"(?:a|b|rc)\d+$|\.dev\d+$", re.IGNORECASE)
+
 
 def _resolve_version() -> str:
     """Resolve the client version.
@@ -79,9 +89,33 @@ def _resolve_environment(installed: bool) -> str:
     return PRODUCTION_ENV if installed else DEVELOPMENT_ENV
 
 
+def _is_prerelease(version: str) -> bool:
+    """Return True if ``version`` is a PEP 440 pre-release (alpha, beta, rc or dev).
+
+    Deliberately dependency-free rather than using ``packaging``: that library
+    is not a runtime dependency (it only reaches this checkout via dev tools),
+    so it is absent from a real user install. The only versions that reach here
+    are the ones our own build pipeline produces.
+    """
+    # Drop any local version segment ("+gb710c298") before inspecting.
+    return _PRERELEASE_RE.search(version.split("+", 1)[0]) is not None
+
+
+def _resolve_default_api_url(version: str) -> str:
+    """Resolve the API this client talks to when ``--api`` is not given.
+
+    Pre-release builds — the dev build published on every merge to main, and
+    any alpha/beta/rc release — default to the test API, so an unreleased
+    client is exercised against the unreleased backend. Stable releases default
+    to production. ``--api`` always wins over this.
+    """
+    return TEST_API_URL if _is_prerelease(version) else PRODUCTION_API_URL
+
+
 __version__ = _resolve_version()
 __installed__ = _resolve_installed()
 __environment__ = _resolve_environment(__installed__)
+__default_api_url__ = _resolve_default_api_url(__version__)
 
 
 class SystemConfig:
@@ -95,6 +129,7 @@ def __init__(self):
         self.client_version = __version__
         self.installed = __installed__
         self.environment = __environment__
+        self.default_api_url = __default_api_url__
         self.error_messages = self.config["error_messages"]
 
     def _load_config(self):
 
@@ -5,7 +5,11 @@
 from system_config import (
     DEVELOPMENT_ENV,
     ENVIRONMENT_VAR,
+    PRODUCTION_API_URL,
     PRODUCTION_ENV,
+    TEST_API_URL,
+    _is_prerelease,
+    _resolve_default_api_url,
     _resolve_environment,
     system_config,
 )
@@ -56,3 +60,36 @@ def test_system_config_exposes_resolved_environment():
 
 if __name__ == "__main__":
     pytest.main([__file__])
+
+
+@pytest.mark.parametrize(
+    "version",
+    [
+        "0.3.10.dev7",  # dev build published on every merge to main
+        "0.3.10.dev16+gb710c2982",  # local segment must not defeat detection
+        "0.4.0a1",
+        "0.4.0b2",
+        "0.4.0rc1",
+        "0.3.9.post1.dev2",
+    ],
+)
+def test_prerelease_versions_default_to_test_api(version):
+    assert _is_prerelease(version) is True
+    assert _resolve_default_api_url(version) == TEST_API_URL
+
+
+@pytest.mark.parametrize(
+    "version",
+    [
+        "0.3.9",
+        "1.0.0",
+        "0.3.9.post1",  # a post-release is NOT a pre-release
+    ],
+)
+def test_stable_versions_default_to_production_api(version):
+    assert _is_prerelease(version) is False
+    assert _resolve_default_api_url(version) == PRODUCTION_API_URL
+
+
+def test_system_config_exposes_default_api_url():
+    assert system_config.default_api_url in (PRODUCTION_API_URL, TEST_API_URL)