> ## Documentation Index
> Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Publishing a Keystone bolt-on

> Take a Keystone bolt-on from scaffold to a published, installable package. Build the wheel, publish to PyPI or a self-hosted index, and confirm it is auto-discovered by any Keystone panel or verifier.

A Keystone bolt-on is a small package that declares an `algovoi.keystone.steps` entry
point. Once it is installed, it is discovered automatically by any Keystone control panel
or conformance verifier, with no catalogue edit and no coordination required. This guide
takes a bolt-on from an idea to a published, installable package.

## 1. Create the package

The quickest way is the control panel: install it and open the **Create a Keystone
bolt-on** card.

```bash theme={null}
pip install algovoi-keystone-control
algv-keystone
```

Enter a name, choose the canonical ref you want to alias onto, and download the zip. (The
`keystone-alias` scaffolder in the AlgoVoi verifier toolkit produces the same skeleton from
the command line.)

Either way you get:

```
<name>/
  pyproject.toml            # declares the algovoi.keystone.steps entry point
  <module>.py               # your ref() builder + keystone_step() descriptor
  tests/test_conformance.py # determinism + descriptor checks (passes out of the box)
  NOTICE
```

## 2. Make it yours

* In `<module>.py`, set the fields your reference commits to inside `<name>_ref(payload)`.
  Keep the construction as `"sha256:" + SHA-256(RFC 8785 JCS(payload))` so anyone can
  recompute and verify it with the two open standards, no special software.
* In `keystone_step()`, set `order` (the position in the chain) and a one line `posture`.
* Leave `alias_of` pointing at the canonical Keystone ref you are extending.

## 3. Build the wheel

Bolt-ons are pure Python, so the wheel builds anywhere and installs on any platform:

```bash theme={null}
python -m pip install build
python -m build --wheel
# -> dist/<name>-0.1.0-py3-none-any.whl
```

## 4. Publish

<Tabs>
  <Tab title="PyPI (public)">
    ```bash theme={null}
    python -m pip install twine
    twine upload dist/*
    ```
  </Tab>

  <Tab title="Self-hosted index">
    Copy the wheel into your index's `packages/` directory and add it to the PEP 503
    `simple/` listing (one entry per file, plus the project in the root index). Any
    `pip install --extra-index-url <your-index-url> <name>` then resolves it.
  </Tab>
</Tabs>

## 5. Verify and confirm discovery

```bash theme={null}
pip install <name>
keystone-verify <name>     # checks the descriptor + recompute
```

A pass means the bolt-on recomputes its reference deterministically and declares a valid
alias onto a canonical layer. From that point on it appears in the Keystone control panel
and is picked up by any conformance verifier automatically, because discovery runs through
the entry point rather than a fixed list.

## Versioning

To ship an update, bump `version` in `pyproject.toml`, rebuild the wheel, and publish it
alongside the previous version. Consumers pin with `<name>==x.y.z` for reproducible
installs.