putitoutthere 0.1.42 → 0.1.44

package/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to `putitoutthere` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+Every PR that changes public API adds an entry here (see
+[`AGENTS.md`](./AGENTS.md#changelog-and-migration-policy)). Breaking changes
+are prefixed `**BREAKING**` and link to the matching section in
+[`MIGRATIONS.md`](./MIGRATIONS.md).
+
+## Unreleased
+
+### Added
+
+- **Reusable workflow `.github/workflows/release.yml` (`workflow_call`).** The single user-facing surface. Consumer integration is one `uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v1` line in their own `release.yml`; pinned action versions, plan/build/publish orchestration, and GitHub Release creation all live inside. Three optional inputs: `environment` (default `release`), `node_version` (default `24`), `python_version` (default `3.12`). No `dry_run`, `working_directory`, or `config` inputs — the plan job is already side-effect-free, the config file is `putitoutthere.toml` at the repo root, period. The engine is invoked via `uses: thekevinscott/putitoutthere@v1` so the workflow file and the engine always agree on a single git ref.
+
+- **`[package.bundle_cli]` recipe for maturin pypi packages** (#217). Opt-in declarative shape for libraries that ship a Rust CLI inside each wheel (the `ruff` / `uv` / `pydantic-core` pattern). Declare `bin`, `stage_to`, and optional `crate_path`; the reusable workflow cross-compiles the binary per target, stages it into the package source tree, and maturin picks it up via `[tool.maturin].include`. Requires `build = "maturin"` and non-empty `targets`. See [README → Recipes → Rust CLI inside a PyPI wheel](./README.md#rust-cli-inside-a-pypi-wheel). No behavior change for existing packages that don't declare the block.
+
+### Changed
+
+- **Public consumer surface collapsed to the README + the reusable workflow.** The CLI, the JS action (`action.yml`), and the diagnostic subcommands (`doctor`, `preflight`) are internal seams the reusable workflow invokes; consumers do not call them. The entire `docs/` directory is removed — `README.md` is the single user-facing surface. See [MIGRATIONS.md](./MIGRATIONS.md#public-surface-collapsed-to-a-reusable-workflow) for the before/after.
+- **Auth is OIDC trusted publishers only.** The reusable workflow does not pass long-lived registry tokens (`NPM_TOKEN`, `PYPI_API_TOKEN`, `CARGO_REGISTRY_TOKEN`) as secrets. The engine's env-var fallback code paths still exist (in `src/auth.ts`); they're just not reachable through the reusable workflow.
+- **Repository renamed `put-it-out-there` → `putitoutthere`.** GitHub auto-redirects the old slug, but consumers with the old URL pinned in `package.json`, `Cargo.toml`, `pyproject.toml`, or workflow files should update them. See [MIGRATIONS.md](./MIGRATIONS.md#repository-renamed-put-it-out-there--putitoutthere).
+
+### Deprecated
+
+- _nothing yet_
+
+### Removed
+
+- **The entire `docs/` directory** (VitePress site, all guide pages, all shape walkthroughs). README is the single user-facing surface. Engine contracts that were documented in `docs/guide/{artifact-contract,runner-prerequisites}.md` moved to `notes/internals/` — internal references the reusable workflow honors so consumers don't have to know them.
+- **`.github/workflows/docs.yml` and `docs-test.yml`** — the docs site no longer exists.
+- **`build_workflow:` config field.** Removed from the schema in `src/config.ts`; configs declaring it now fail validation.
+- **`putitoutthere init` subcommand** and the templates it scaffolded. Source removed (`src/init.ts`, `src/templates.ts`, plus tests, plus `--force` and `--cadence` flag plumbing).
+- **`migrations/` directory** moved to `notes/migrations-pre-rewrite/`. Stale plans drafted against the prior hand-written-`release.yml` model.
+
+### Fixed
+
+- **Scaffolded `release.yml` now forwards `GITHUB_TOKEN` to the publish
+  step.** piot has cut GitHub Releases alongside tag pushes since #26, but
+  Actions doesn't auto-mount the runner token as an env var, so the
+  scaffolded workflow's publish step ran without `GITHUB_TOKEN` and
+  silent-skipped Release creation — leaving consumers with tags but no
+  Releases page entries. The publish job's `env:` block now includes
+  `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}`. Existing `release.yml` files
+  need a one-line patch — see
+  [MIGRATIONS.md](./MIGRATIONS.md#scaffolded-releaseyml-now-forwards-github_token).
+- **`/` in `[[package]].name` is now safe — planner encodes it for
+  `actions/upload-artifact@v4`** (#230). Polyglot-monorepo grouping
+  shapes (e.g. `name = "py/cachetta"`, `"js/cachetta"`) used to
+  produce `artifact_name` values containing `/`, which
+  `actions/upload-artifact@v4` rejects with
+  `The artifact name is not valid: ... Contains the following character: Forward slash /`,
+  failing the build job before piot ever ran. The planner now encodes
+  each `/` to `__` in `artifact_name` (so `py/cachetta` →
+  `py__cachetta-sdist`) and config validation reserves `__` in
+  `pkg.name` so the round-trip stays unambiguous. Other
+  upload-artifact-forbidden characters (`\`, `:`, `<`, `>`, `|`,
+  `*`, `?`, `"`) are now rejected at config load. Read sites
+  (`publish`, `doctor`, `preflight`, `completeness`) consume
+  `artifact_name` verbatim and need no changes; consumers running
+  the `cachetta#26` encode/decode workaround should remove it once
+  they upgrade. See [MIGRATIONS.md](./MIGRATIONS.md#package-names-with--no-longer-need-an-encode-decode-workaround) and
+  [Artifact contract → notes](./notes/internals/artifact-contract.md#naming-convention-reference).
+- **Documentation accuracy pass** (#231). A docs-vs-code audit caught
+  several places where reference material lagged behind shipped behavior.
+  No code paths changed beyond a stale help-text line; existing configs
+  and workflows are unaffected.
+  - `putitoutthere --help` text for `--json` no longer claims "(plan
+    only)" — the flag has worked across every command that emits a
+    result since their respective additions. `docs/api/cli.md` now lists
+    the supported commands explicitly.
+  - `docs/api/cli.md` documents short flags (`-h`, `-v`, `--version`)
+    and exit codes (`0` / `1` / `4`).
+  - `docs/api/action.md` documents the `outputs.matrix` contract
+    (output key omitted when empty, not "empty string"), the matrix-row
+    field schema, and the GitHub Release body shape.
+  - `action.yml`'s `command` description and `docs/api/action.md`
+    clarify that the action shells through to any putitoutthere CLI
+    subcommand, not just `plan` / `publish` / `doctor`.
+  - `docs/guide/configuration.md` adds the previously-shape-only `pypi`
+    field to the central `kind = "pypi"` table.
+  - `docs/guide/trailer.md` documents the package-name character
+    grammar, leading-whitespace tolerance, and last-wins semantics.
+  - `README.md`'s scaffolding description now correctly mentions both
+    workflow files written by `putitoutthere init`.
+- **Publish path works end-to-end for slash-containing `pkg.name`** (#237).
+  Two follow-up bugs that #230 didn't catch: (1) `pypi.ts.collectArtifacts`
+  and `npm-platform.ts.synthesizePlatformPackage` both built directory
+  lookups from raw `pkg.name`, so a package called `py/foo` couldn't
+  match the encoded on-disk directory `py__foo-sdist/` and the publish
+  step reported `pypi: no artifacts found for py/foo under <root>`.
+  (2) The planner emitted glob `artifact_path` values
+  (`${pkg.path}/dist/*.tar.gz`, `${pkg.path}/dist/*.whl`,
+  `${pkg.path}/target/package/*.crate`), which `actions/upload-artifact@v4`
+  treats differently from a directory `path:` — it preserves the
+  workspace-relative path, so the file lands at
+  `<name>/packages/python/dist/foo.tar.gz` instead of `<name>/foo.tar.gz`.
+  Both bugs fixed: handlers now encode `pkg.name` via
+  `sanitizeArtifactName` and walk the artifact directory recursively
+  for the expected file extensions; planner emits directory-shaped
+  `artifact_path` values for the three slots that previously used a
+  glob. Consumers using `${{ matrix.artifact_path }}` verbatim see no
+  required workflow changes; consumers who hand-coded a glob path
+  should switch to the directory shape — see
+  [MIGRATIONS.md](./MIGRATIONS.md#publish-path-works-end-to-end-for-slash-containing-pkgname).

package/MIGRATIONS.md

@@ -0,0 +1,555 @@
+# Migration guide
+
+How to upgrade between versions of `putitoutthere`. Sections are ordered
+newest-first; each one is self-contained. Every observable change to
+public API gets a section — additive changes as well as breaking ones —
+because versioning is not yet strictly semver.
+
+Each section covers five things, in order:
+
+1. **Summary** — what changed and why.
+2. **Required changes** — before/after diffs for config, CLI flags, and
+   action inputs.
+3. **Deprecations removed** — anything previously warned about that is
+   now gone.
+4. **Behavior changes without code changes** — same API, different
+   runtime behavior (tag format, exit codes, default values).
+5. **Verification** — commands you can run to confirm the upgrade
+   worked, with the expected output.
+
+---
+
+## Unreleased
+
+### Public surface collapsed to a reusable workflow
+
+**Summary.** The consumer surface is now one line in a `release.yml`:
+
+```yaml
+on:
+  push: { branches: [main] }
+
+jobs:
+  release:
+    uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v1
+    permissions:
+      contents: write
+      id-token: write
+```
+
+Plus the consumer's existing `putitoutthere.toml`. Triggers live in
+the consumer's file; everything below them — pinned action versions,
+plan/build/publish orchestration, runner toolchain setup, artifact
+upload/download, GitHub Release creation — lives in the reusable
+workflow that piot ships. The CLI and the JS action are internal
+seams the reusable workflow invokes; consumers do not call them.
+Auth is OIDC trusted publishers only — long-lived registry tokens
+are not reachable through the workflow. See [design
+commitments](https://github.com/thekevinscott/putitoutthere/blob/main/notes/design-commitments.md)
+for the authoritative non-goals.
+
+**Required changes.**
+
+| Before (hand-written `release.yml`) | After |
+|-----|-----|
+| ~100 lines of YAML: plan/build/publish jobs, twine install, git identity, GitHub Release backfill, hand-pinned action majors | `uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v1` |
+| `putitoutthere init` to scaffold the workflow | Subcommand removed; consumers add the snippet above by hand |
+| `[[package]].build_workflow = "publish-foo.yml"` for unsupported shapes | Removed. Shapes that don't fit piot's named build modes write their own release workflow that doesn't use piot |
+| Long-lived registry tokens (`NPM_TOKEN`, `PYPI_API_TOKEN`, `CARGO_REGISTRY_TOKEN`) passed to a hand-written publish step | Not reachable through the reusable workflow. Register an OIDC trusted publisher per registry once |
+| Optional inputs `dry_run`, `working_directory`, `config` | Removed. Plan job already prints the matrix without side effects; config lives at `putitoutthere.toml` in the repo root, no override |
+| Documentation site (`docs/`) | Removed. README is the single user-facing surface; `notes/internals/` holds the contracts the reusable workflow honors so consumers don't have to know them |
+
+**Deprecations removed.** `build_workflow:` is no longer in the
+config schema (`src/config.ts`); configs that declare it now fail
+validation. `putitoutthere init`, `--cadence`, and `--force` flags
+are removed from the CLI.
+
+**Behavior changes without code changes.** Engine behavior (plan,
+cascade, version bump, registry handlers, completeness check,
+idempotency, OIDC trust-policy validation) is unchanged. The
+reusable workflow internally pins:
+
+- `actions/checkout@v4` (`fetch-depth: 0`)
+- `actions/setup-node@v4`
+- `actions/setup-python@v5`
+- `actions/upload-artifact@v4`
+- `actions/download-artifact@v4`
+- `PyO3/maturin-action@v1`
+
+If a consumer was running newer majors (e.g. coaxer hit
+`download-artifact@v8` defaults that broke the artifact-naming
+contract), the reusable workflow standardises everyone on the
+known-tested versions.
+
+**Verification.**
+
+- `pnpm test:unit` passes in the main repo.
+- A consumer's first cutover: drop in the 12-line `release.yml`
+  shown above, push a commit that touches a `[[package]].paths`
+  glob, and watch for a tag push + GitHub Release on the next
+  workflow run.
+
+### Publish path works end-to-end for slash-containing `pkg.name`
+
+**Summary.** Follow-up to the [`/`-encoding fix](#package-names-with--no-longer-need-an-encode-decode-workaround)
+([#230](https://github.com/thekevinscott/putitoutthere/issues/230)).
+Two bugs prevented slash-containing names from actually publishing
+even after the planner started encoding `/` to `__`
+([#237](https://github.com/thekevinscott/putitoutthere/issues/237)):
+
+1. The pypi handler (`src/handlers/pypi.ts`) and the npm-platform
+   synthesizer (`src/handlers/npm-platform.ts`) both built artifact
+   directory lookups from the raw `pkg.name`, so a package called
+   `py/foo` couldn't match the encoded on-disk directory
+   `py__foo-sdist/`. Symptom: `pypi: no artifacts found for py/foo
+   under <root>` at publish time.
+2. The planner emitted glob-shaped `artifact_path` values for crates
+   tarballs, pypi sdists, and pypi wheels (e.g.
+   `${pkg.path}/dist/*.tar.gz`). `actions/upload-artifact@v4` treats
+   a glob `path:` differently from a directory `path:` — it preserves
+   the workspace-relative path, so the sdist landed at
+   `artifacts/<name>/packages/python/dist/foo.tar.gz` instead of
+   `artifacts/<name>/foo.tar.gz`. Even after fix (1), the publish
+   handler couldn't find files inside that nested layout.
+
+Both fixed:
+
+- Handlers route directory lookups through `sanitizeArtifactName`,
+  matching whatever the planner emitted on the matrix row.
+- Handlers walk the artifact directory recursively for the expected
+  file extensions (`.tar.gz` / `.whl` / `.crate`), so any layout
+  (flat or nested) works.
+- Planner emits directory-shaped `artifact_path` values for the
+  three slots that used a glob:
+
+  | Slot | Before | After |
+  |---|---|---|
+  | crates tarball | `${pkg.path}/target/package/*.crate` | `${pkg.path}/target/package` |
+  | pypi maturin wheel | `${pkg.path}/dist/*.whl` | `${pkg.path}/dist` |
+  | pypi sdist | `${pkg.path}/dist/*.tar.gz` | `${pkg.path}/dist` |
+
+**Required changes.**
+
+- **None for repos that pass `matrix.artifact_path` straight through**
+  to `actions/upload-artifact@v4` (the canonical pattern shown in
+  `docs/guide/shapes/*`). The matrix field already carries the new
+  directory shape; on-disk artifact layout becomes flat
+  (`<name>/foo.tar.gz` instead of `<name>/packages/python/dist/foo.tar.gz`),
+  but consumer workflows see no observable change.
+- **Repos that hand-coded a glob path** should switch to the
+  directory shape (or — better — replace the hard-coded value with
+  the matrix field):
+
+  ```diff
+   - uses: actions/upload-artifact@v4
+     with:
+       name: ${{ matrix.artifact_name }}
+  -    path: packages/python/dist/*.tar.gz
+  +    path: ${{ matrix.artifact_path }}     # or "packages/python/dist"
+  ```
+
+  The recursive reader keeps glob layouts working as a safety net,
+  but the directory shape is the canonical contract going forward.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.**
+
+- Artifact directory layout is now flat: `artifacts/<name>/<file>`
+  instead of `artifacts/<name>/<workspace-relative-path>/<file>`.
+  Anything reading the artifact tree (the docs page, debugging
+  scripts, custom verification jobs) should expect files at the
+  artifact root.
+- The publish-side handlers now walk subdirectories recursively
+  when looking for `.whl` / `.tar.gz` / `.crate` files. This is
+  defensive for consumers whose build steps write to a non-standard
+  location inside `<name>/`; the planner's directory `artifact_path`
+  remains the canonical contract.
+
+**Verification.**
+
+```sh
+putitoutthere plan --json | jq '.[] | {name, artifact_name, artifact_path}'
+```
+
+Expect every `artifact_path` to be a plain directory (no `*`):
+
+```json
+{ "name": "py/cachetta", "artifact_name": "py__cachetta-sdist", "artifact_path": "py/cachetta/dist" }
+```
+
+After the next release run, the `actions/upload-artifact@v4` step
+uploads `py/cachetta/dist/` contents flat under
+`artifacts/py__cachetta-sdist/` (no nested `packages/python/dist/`
+prefix), and the publish step finds the sdist immediately.
+
+### Scaffolded `release.yml` now forwards `GITHUB_TOKEN`
+
+**Summary.** piot has supported cutting a GitHub Release alongside each
+tag push since #26, but the scaffolded `release.yml` template never
+forwarded `GITHUB_TOKEN` to the publish step. GitHub Actions does not
+auto-mount the runner token as an env var — `permissions: contents:
+write` only grants the token *scope* to write Releases; the token still
+has to be exposed via `env:` for piot's `release.ts` to read it from
+`process.env.GITHUB_TOKEN`. Without it, piot silent-skipped Release
+creation and consumers got tags but no Release entries on the repo's
+Releases page. Fresh `piot init` runs now scaffold the env line.
+
+**Required changes.** Existing repos that ran `piot init` before this
+change need a one-line addition to `.github/workflows/release.yml`:
+
+```diff
+       - uses: thekevinscott/putitoutthere@v0
+         with:
+           command: publish
+           dry_run: ${{ inputs.dry_run || 'false' }}
+         env:
+           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_TOKEN }}
+           PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
++          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+The publish job already declares `permissions: contents: write`, which
+is the scope GitHub's runner-supplied `GITHUB_TOKEN` needs to create
+Releases — no additional permission changes required.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Repos that adopt the new
+template (or apply the diff above) start seeing GitHub Release entries
+appear under the repo's `/releases` page after each publish. The
+Release body is the output of:
+
+```sh
+git log <prev-tag>..<this-tag> --format='- %s' --no-merges
+```
+
+Tags suffixed with `-rc`, `-beta`, or `-alpha` are flagged
+`prerelease: true`. Release creation is best-effort: a 4xx/5xx from
+the GitHub API surfaces as a `publish: GitHub Release creation
+failed` warning but does not fail the publish run — the registry
+publish and tag push remain authoritative.
+
+**Verification.** After the next release run on a repo that adopted the
+fix:
+
+```bash
+# Inspect the publish job log:
+#   "publish: GitHub Release created at https://github.com/.../releases/tag/<name>-v<x.y.z>"
+
+# Or hit the API directly:
+gh release view <name>-v<x.y.z> --repo <owner>/<repo>
+```
+
+If you previously saw the warning `publish: GitHub Release creation
+failed` in your publish logs, the warning should be gone and the
+Releases page should populate.
+
+### Package names with `/` no longer need an encode/decode workaround
+
+**Summary.** Polyglot-monorepo repos that group packages by language
+(e.g. `name = "py/foo"`, `"js/bar"`) used to fail at the build job
+with:
+
+```
+The artifact name is not valid: py/foo-sdist.
+Contains the following character: Forward slash /
+```
+
+…because `actions/upload-artifact@v4` forbids `/` in artifact names
+and the planner emitted `artifact_name` verbatim from `pkg.name`
+([#230](https://github.com/thekevinscott/putitoutthere/issues/230)).
+The planner now encodes each `/` to `__`
+(`py/foo` → `py__foo-sdist`), so the build job's
+upload-artifact step works without modification — pass the matrix
+`artifact_name` field through verbatim and the encoding happens
+upstream.
+
+**Required changes.**
+
+- **None for repos with slash-free `pkg.name`** — `artifact_name`
+  is byte-identical to the previous version.
+- **Repos that ran the [`cachetta#26`-style](https://github.com/thekevinscott/cachetta/pull/26)
+  encode/decode workaround should remove it.** The planner now
+  does the encoding natively; leaving the workaround in place
+  produces double-encoded names like `py____foo-sdist`, which the
+  publish-side reader will treat as a missing artifact.
+
+  ```diff
+   - uses: actions/upload-artifact@v4
+     with:
+  -    name: ${{ format('{0}', matrix.artifact_name) }}  # any sed/format encode
+  -    path: ${{ matrix.artifact_path }}
+  +    name: ${{ matrix.artifact_name }}                 # use the field as-is
+  +    path: ${{ matrix.artifact_path }}
+  ```
+
+  ```diff
+   - uses: actions/download-artifact@v4
+     with:
+       path: artifacts
+  - - name: Decode artifact dir names
+  -   run: |
+  -     # rename artifacts/py__foo-sdist back to artifacts/py/foo-sdist
+  -     ...
+  ```
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.**
+
+- `pkg.name` containing `__` (the new encoding sequence) is now
+  rejected at config load with: `package name must not contain "__"
+  (reserved: piot encodes "/" to "__" for artifact-name slots; pick
+  a different separator)`. If your config uses `__` in a package
+  name today, rename to use `-` or `_` and update any tags / consumer
+  references; piot can't safely sanitize it without ambiguity.
+- `pkg.name` containing `\`, `:`, `<`, `>`, `|`, `*`, `?`, or `"`
+  is now rejected at config load. None of these are valid in npm,
+  PyPI, or crates.io names, so any config that previously contained
+  them was already broken at publish time — the change just moves
+  the failure earlier with a clearer message.
+
+**Verification.**
+
+```sh
+putitoutthere plan --json | jq '.[].artifact_name'
+```
+
+Expect every emitted `artifact_name` to contain only ASCII letters,
+digits, `-`, `_`, and `.` — no `/` and no other forbidden chars.
+For a repo with `name = "py/cachetta"`:
+
+```
+"py__cachetta-sdist"
+"py__cachetta-wheel-x86_64-unknown-linux-gnu"
+```
+
+After the next release, the build job's `actions/upload-artifact@v4`
+step uploads under `py__cachetta-sdist/` (a single flat directory
+under `artifacts/`), and piot's publish-side reader consumes the
+same path.
+
+### Documentation accuracy pass (#231)
+
+**Summary.** A docs-vs-code audit found several places where reference
+material lagged behind shipped behavior. Existing configs and workflows
+keep working — the only consumer-observable change is that `putitoutthere
+--help` no longer mislabels `--json` as "plan only".
+
+**Required changes.** None.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.**
+
+- `putitoutthere --help` output: the `--json` line now reads `emit
+  machine-readable output (most commands)` instead of `(plan only)`. The
+  flag has always been accepted on every command that emits a result;
+  only the help text was wrong.
+- No other behavior changes. All other audit findings were addressed by
+  updating documentation (`docs/api/cli.md`, `docs/api/action.md`,
+  `docs/guide/configuration.md`, `docs/guide/trailer.md`, `README.md`,
+  `action.yml` description text, VitePress sidebar).
+
+**Verification.**
+
+```sh
+putitoutthere --help | grep -- '--json'
+# Expected: --json            emit machine-readable output (most commands)
+```
+
+### Python shape examples now use `uv build`
+
+**Summary.** Documentation examples for the Python library, Python
+cibuildwheel, and dynamic-versions shapes switched the sdist-build
+step from `python -m build --sdist` to `uv build --sdist`. piot's
+contract is unchanged — backends, artifact names, the
+`matrix.artifact_name` / `matrix.artifact_path` fields, and the
+publish-side completeness check all work identically. The change
+removes a `pip install build` round-trip and aligns the docs with
+`uv` as the recommended Python toolchain.
+
+**Required changes.** None. `python -m build` still works. To
+follow the new examples in your own `release.yml`:
+
+```diff
+ build:
+   ...
+   steps:
+-    - uses: actions/setup-python@v5
+-      with: { python-version: '3.12' }
+     - name: Build sdist
+-      run: |
+-        cd ${{ matrix.path }}
+-        python -m pip install build
+-        python -m build --sdist --outdir dist
++      working-directory: ${{ matrix.path }}
++      run: uv build --sdist
++    # uv installs and manages Python itself; no setup-python step needed.
++    # Add this once at the top of the build job:
++    - uses: astral-sh/setup-uv@v3
+```
+
+`uv build --sdist` writes to `dist/` inside the working directory
+(same as `python -m build --outdir dist`), so
+`matrix.artifact_path` keeps pointing at the right place. The
+publish job is unchanged — `setup-python` + `pip install twine` is
+still the recommended path there because piot's PyPI handler shells
+out to `twine`.
+
+**When *not* to follow this example.** Stay on `python -m build`
+if:
+
+- Your CI image already has Python pre-installed and adding
+  `setup-uv` would slow the cold cache.
+- Your `pyproject.toml` exercises a build backend feature that uv's
+  isolated build environment doesn't yet handle (rare; uv's build
+  isolation matches `python -m build`'s).
+- Your team's runbook standardises on `python -m build` and the
+  consistency cost of switching outweighs the per-run speedup.
+
+`python -m build` is not deprecated and will keep working.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** None.
+
+**Verification.**
+
+```bash
+# After the build job runs:
+ls artifacts/<pkg.name>-sdist/
+# Expected: <pypi-name>-X.Y.Z.tar.gz   (no .devN suffix)
+```
+
+If you see the expected sdist, the switch worked. If you see a
+`.devN` suffix, your project uses dynamic versioning — see
+[dynamic versions](https://thekevinscott.github.io/putitoutthere/guide/dynamic-versions)
+for the env-var handoff (unchanged by this migration).
+
+### Repository renamed `put-it-out-there` → `putitoutthere`
+
+**Summary.** The GitHub repository slug collapsed from `put-it-out-there`
+to `putitoutthere`, matching the npm package and CLI binary name. The
+human-readable name "Put It Out There" (with spaces) is unchanged. GitHub
+auto-redirects the old URL, but any place a consumer has hard-coded the
+old slug — npm/Cargo/pyproject `repository` URLs, GitHub Actions
+references, OIDC trust policy `repository:` claims, docs links — should
+be updated.
+
+**Required changes.**
+
+```diff
+ # package.json (or Cargo.toml / pyproject.toml)
+-"repository": "https://github.com/<owner>/put-it-out-there"
++"repository": "https://github.com/<owner>/putitoutthere"
+```
+
+```diff
+ # .github/workflows/release.yml — if you reference the action by full repo path
+-uses: thekevinscott/put-it-out-there/.github/actions/<...>
++uses: thekevinscott/putitoutthere/.github/actions/<...>
+```
+
+```diff
+ # OIDC trust policies (PyPI, npm) that gate on the source repo
+-"repository": "<owner>/put-it-out-there"
++"repository": "<owner>/putitoutthere"
+```
+
+If you only ever invoked `putitoutthere` via the npm package
+(`npx putitoutthere`, `pnpm add -D putitoutthere`) or the published
+GitHub Action, no change is required — those references already used the
+collapsed name.
+
+**Deprecations removed.** None. The old slug continues to redirect at
+the GitHub layer.
+
+**Behavior changes without code changes.**
+
+- Documentation site moved from
+  `https://thekevinscott.github.io/put-it-out-there/` to
+  `https://thekevinscott.github.io/putitoutthere/`. The old URL
+  redirects.
+- `git remote -v` will still show the old URL until you `git remote
+  set-url origin https://github.com/thekevinscott/putitoutthere.git`.
+  Push and fetch keep working via redirect, but updating the remote
+  avoids surprise breakage if the redirect is ever retired.
+
+**Verification.**
+
+```sh
+# Confirm no stale references in your repo
+grep -r "put-it-out-there" .
+```
+
+Expect no hits outside historical changelog/migration entries.
+
+### `[package.bundle_cli]` — stage a Rust CLI into every maturin wheel (#217)
+
+**Summary.** New optional sub-table under `[[package]]` for pypi packages
+that want the `ruff` / `uv` / `pydantic-core` wheel shape: a companion
+Rust CLI binary, cross-compiled per target and staged into the Python
+source tree before maturin runs, so each wheel ships the binary as
+package data and `pip install <pkg>` gets a working CLI on `PATH` with
+no Rust toolchain on the user's machine. Additive — existing
+configurations are unchanged.
+
+**Required changes.** None for existing configs. To opt in:
+
+```diff
+ [[package]]
+ name       = "my-py"
+ kind       = "pypi"
+ build      = "maturin"
+ path       = "packages/python"
+ paths      = ["packages/python/**"]
+ targets    = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]
++
++[package.bundle_cli]
++bin        = "my-cli"
++stage_to   = "src/my_py/_binary"
++crate_path = "crates/my-rust"   # defaults to "." (repo workspace root)
+```
+
+And in the Python package's `pyproject.toml`:
+
+```diff
++[project.scripts]
++my-cli = "my_py._binary:entrypoint"    # small os.execv launcher stub
++
+ [tool.maturin]
+-include = ["..."]
++include = ["...", "src/my_py/_binary/**"]  # ship the staged binary
+```
+
+See [Polyglot Rust library → Shipping a Rust CLI inside the PyPI wheel](https://github.com/thekevinscott/putitoutthere/blob/main/docs/guide/shapes/polyglot-rust.md#shipping-a-rust-cli-inside-the-pypi-wheel)
+for the full worked example including the launcher stub.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** None for existing configs.
+Packages that declare `[package.bundle_cli]` get two new steps emitted
+in the scaffolded build job (`Setup Rust (if pypi bundle_cli)` +
+`Build + stage bundled CLI`), both gated on
+`matrix.kind == 'pypi' && matrix.bundle_cli.bin != '' && matrix.target != 'sdist'`
+so packages without the block see no change.
+
+**Verification.** For a repo that opts in:
+
+```bash
+# After piot's build job runs on one target:
+ls packages/python/src/my_py/_binary/
+# Expected: my-cli  (or my-cli.exe on Windows targets)
+
+# After the wheel is built:
+python -m zipfile -l packages/python/dist/*.whl | grep _binary
+# Expected: one entry per target listing the staged binary.
+
+# End-to-end on a released wheel:
+pip install my-py==<published-version>
+which my-cli
+my-cli --version
+```