Release channels: dev (default) and stable

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
   "name": "heph-marketplace",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Claude Code plugins for the heph build system, co-located with the docs.",
   "owner": {
     "name": "hephbuild",

plugins/heph-expert/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin.json",
   "name": "heph-expert",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Expert assistance for the heph build system: author BUILD files, debug caching and sandbox issues, wire up CI, and explain the target graph.",
   "author": {
     "name": "hephbuild"

plugins/heph-expert/skills/heph/references/cli.md

@@ -104,3 +104,11 @@ Print the heph version string and exit.
 ```bash
 curl -fsSL https://hephbuild.github.io/install.sh | sh
 ```
+
+Releases come from a **release channel**: `dev` (default, from
+`hephbuild/heph-artifacts-v1`) or `stable` (from `hephbuild/heph`). Pick one with
+`HEPH_CHANNEL`, and a tag within it with `HEPH_VERSION`:
+
+```bash
+HEPH_CHANNEL=stable HEPH_VERSION=v1.2.3 curl -fsSL https://hephbuild.github.io/install.sh | sh
+```

plugins/heph-expert/skills/heph/references/configuration.md

@@ -15,7 +15,7 @@ plugins:
 
 | Key | Type | Default | Description |
 |---|---|---|---|
-| `version` | semver string | — | Pins the heph release that runs this workspace, so every machine/CI job resolves the same toolchain. Set it once at the top. |
+| `version` | semver string | — | Pins the heph release that runs this workspace, so every machine/CI job resolves the same toolchain. Set it once at the top. The tag names a release in a channel: `dev` (default, `hephbuild/heph-artifacts-v1`) or `stable` (`hephbuild/heph`). |
 | `versionFlavour` | string | `""` (std) | Which release flavour self-upgrade downloads: `""` for the default stripped "std" build, or `debug` for the unstripped build (symbolicated backtraces). |
 | `plugins` | list of plugin entries | `[]` | Plugins to register. Each entry sets exactly one of `builtin`, `path`, or `url`, plus an optional `options` map. |
 | `homeDir` | path | unset | Where heph keeps its home and cache. |

plugins/heph-go/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin.json",
   "name": "heph-go",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Set up and maintain Go in a heph workspace correctly: enable the go provider and drivers, wire generated code (go_src / go_codegen_root / go_codegen_deps) and test fixtures (go_test_data), and keep :build/:test green.",
   "author": {
     "name": "hephbuild"

plugins/heph-go/skills/heph-go/references/go-plugin.md

@@ -29,9 +29,13 @@ You should not interact with these drivers directly; they are internal plumbing.
 The Go plugin is an **external plugin** (not compiled into the heph binary). A
 single `plugins:` entry loads the provider and all four drivers:
 
+The URL points at a release in a channel — `dev`
+(`hephbuild/heph-artifacts-v1`, the default) or `stable` (`hephbuild/heph`).
+Keep it on the same channel as the `version:` pin.
+
 ```yaml title=".hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/<HEPH_VERSION_URL>/heph-go-plugin.json
+  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/v<HEPH_VERSION_URL>/heph-go-plugin.json
     options:
       gotool: "1.27.0"       # required — pinned version, "host", or a target address
       skip: []               # optional

website/docs/getting-started.md

@@ -9,7 +9,7 @@ description: Install heph and write your first .hephconfig.
 Install heph:
 
 ```bash title="terminal"
-curl -fsSL https://hephbuild.github.io/install.sh | sh
+<HEPH_INSTALL_ENV>curl -fsSL https://hephbuild.github.io/install.sh | sh
 ```
 
 Then drop a `.hephconfig` at the root of your repository. Pin the version so
@@ -19,5 +19,9 @@ every machine and CI run resolves the same toolchain — byte for byte:
 version: <HEPH_VERSION>
 ```
 
+The version above comes from a [release channel](/docs/reference/release-channels)
+— `dev` by default. Switch the selector on any code block to read the page
+for the other channel.
+
 From here, enable the [plugins](/docs/plugins) that you require and get building!
 A good plugin to get started is [buildfile](/docs/plugins/buildfile).

website/docs/guides/ci.md

@@ -70,7 +70,7 @@ from a `ci.hephconfig` overlay so it only activates in CI:
 
 ```yaml title="ci.hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/v<HEPH_VERSION_URL>/heph-gha-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-gha-plugin.json
 ```
 
 ```yaml title=".github/workflows/build.yml"

website/docs/plugins/devenv.md

@@ -26,7 +26,7 @@ via the `bin` option below).
 
 ```yaml title=".hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/v<HEPH_VERSION_URL>/heph-devenv-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-devenv-plugin.json
     checksum: sha256:<hex>   # optional; pin from heph-devenv-plugin.json.sha256
 ```
 

website/docs/plugins/gha.md

@@ -46,7 +46,7 @@ The GHA plugin is an **external plugin** — it ships as a shared library
 
 ```yaml title=".hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/v<HEPH_VERSION_URL>/heph-gha-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-gha-plugin.json
     checksum: sha256:<hex>   # optional; pin from heph-gha-plugin.json.sha256
 ```
 
@@ -60,7 +60,7 @@ a profile overlay so local runs are unaffected:
 
 ```yaml title="ci.hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/v<HEPH_VERSION_URL>/heph-gha-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-gha-plugin.json
     checksum: sha256:<hex>
 ```
 
@@ -104,7 +104,7 @@ message is emitted. The step summary is always written regardless.
 
 ```yaml title="ci.hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/v<HEPH_VERSION_URL>/heph-gha-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-gha-plugin.json
     options:
       refreshSecs: 30          # optional
       summaryPath: ""          # optional

website/docs/plugins/go.md

@@ -34,7 +34,7 @@ Use `url:` to have heph fetch and cache the plugin automatically:
 
 ```yaml title=".hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/v<HEPH_VERSION_URL>/heph-go-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-go-plugin.json
     checksum: sha256:<hex>   # optional; pin from heph-go-plugin.json.sha256
 ```
 
@@ -47,7 +47,7 @@ for details.
 
 ```yaml title=".hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/v<HEPH_VERSION_URL>/heph-go-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-go-plugin.json
     checksum: sha256:<hex>   # optional
     options:
       gotool: "1.27.0"       # required — pinned version, "host", or a target address
@@ -119,7 +119,7 @@ Each pattern is matched against the workspace-relative path of the directory.
 
 ```yaml title=".hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/v<HEPH_VERSION_URL>/heph-go-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-go-plugin.json
     options:
       gotool: "1.27.0"
       skip:

website/docs/plugins/oci.md

@@ -30,7 +30,7 @@ binary. It ships as a shared library (cdylib) with a manifest file
 
 ```yaml title=".hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/v<HEPH_VERSION_URL>/heph-oci-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-oci-plugin.json
     checksum: sha256:<hex>   # optional; pin from heph-oci-plugin.json.sha256
 ```
 

website/docs/reference/configuration.md

@@ -24,7 +24,9 @@ version: v1.2.3
 ```
 
 `version` pins the heph release for this workspace so every machine and CI job
-runs the same binary. When the running binary differs from the pin, heph
+runs the same binary. The tag names a release in a
+[release channel](/docs/reference/release-channels) — `dev` by default,
+`stable` for slower-moving pins. When the running binary differs from the pin, heph
 automatically downloads the pinned release and re-execs into it on startup —
 the rest of the run is served by the pinned version. The downloaded binary is
 cached in `~/.heph/versions/<tag>/` and reused on subsequent runs.
@@ -67,7 +69,7 @@ Every key below is optional.
 
 | Key         | Type                          | Default | Description |
 |-------------|-------------------------------|---------|-------------|
-| `version`   | string                        | unset   | Pins the heph release for this workspace. When set, heph automatically downloads and re-execs into the pinned version on startup. See [Pinning the version](#pinning-the-version). |
+| `version`   | string                        | unset   | Pins the heph release for this workspace. When set, heph automatically downloads and re-execs into the pinned version on startup. See [Pinning the version](#pinning-the-version) and [Release channels](/docs/reference/release-channels). |
 | `versionFlavour` | string                   | `""` (std) | Selects which release flavour self-upgrade downloads: `""` for std, or `debug` for the unstripped build. See [Pinning a release flavour](#pinning-a-release-flavour). |
 | `plugins`   | list of plugin entries        | `[]`    | Plugins to register. Each entry sets exactly one of `builtin`, `path`, or `url`, plus an optional `options` map and, for `url:` entries, an optional `checksum`. |
 | `homeDir`   | path                          | unset   | Where heph keeps its home and cache. |
@@ -137,7 +139,7 @@ plugins:
   - path: ./path/to/my-plugin.json
 
   # Remote manifest — downloaded and cached automatically
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/<HEPH_VERSION_URL>/heph-go-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-go-plugin.json
 ```
 
 `path:` and `url:` plugins are supported on Unix only.
@@ -150,7 +152,7 @@ trusting anything it declares — a mismatch is a hard error.
 
 ```yaml title=".hephconfig"
 plugins:
-  - url: https://github.com/hephbuild/heph-artifacts-v1/releases/download/<HEPH_VERSION_URL>/heph-go-plugin.json
+  - url: <HEPH_ARTIFACTS_URL>/heph-go-plugin.json
     checksum: sha256:<hex>
 ```
 

website/docs/reference/release-channels.md

@@ -0,0 +1,70 @@
+---
+title: "Release channels"
+sidebar_position: 4
+description: Where heph releases come from — dev and stable — and how to pick one.
+---
+
+# Release channels
+
+A **release channel** is the stream a heph release comes from: the `heph`
+binary, the plugin manifests published beside it, and their checksums. Every
+channel publishes the same asset names — only the cadence and the repository
+differ.
+
+| Channel   | Cadence | Releases |
+|-----------|---------|----------|
+| `dev`     | Cut from every change on main. Newest features, fastest moving. **Default.** | [hephbuild/heph-artifacts-v1](https://github.com/hephbuild/heph-artifacts-v1/releases/latest) |
+| `stable`  | Tagged releases. Fewer, slower, vetted. | [hephbuild/heph](https://github.com/hephbuild/heph/releases/latest) |
+
+:::note
+`dev` is the default everywhere today — the installer, and every version and
+URL these docs show. Pick `stable` when you want a slower-moving pin.
+:::
+
+## Reading the docs on a channel
+
+Every code block that carries a version or a plugin URL has a channel selector
+above it. Pick a channel and the whole page rewrites: the `version:` pin, the
+plugin manifest URLs, and the install command all switch to that channel. The
+choice sticks across pages.
+
+:::tip
+`?channel=stable` on any docs URL pins the page to that channel for the visit,
+without changing your saved choice — handy for sharing a link that reads the way
+you meant it.
+:::
+
+## Installing from a channel
+
+The installer takes the channel in `HEPH_CHANNEL`:
+
+```bash title="terminal"
+HEPH_CHANNEL=stable curl -fsSL https://hephbuild.github.io/install.sh | sh
+```
+
+Omit it for `dev`. `HEPH_VERSION` pins a tag within the channel:
+
+```bash title="terminal"
+HEPH_CHANNEL=stable HEPH_VERSION=v1.2.3 curl -fsSL https://hephbuild.github.io/install.sh | sh
+```
+
+## Pinning plugins from a channel
+
+A `url:` plugin entry names the release it comes from, so it carries the channel
+in its URL — keep it on the same channel as the version you pinned:
+
+```yaml title=".hephconfig"
+version: <HEPH_VERSION>
+plugins:
+  - url: <HEPH_ARTIFACTS_URL>/heph-go-plugin.json
+```
+
+See [Configuration](/docs/reference/configuration#pinning-the-version) for the
+`version` key and [Pinning manifests with checksums](/docs/reference/configuration#pinning-manifests-with-checksums)
+for locking a manifest to a digest.
+
+## Switching channels
+
+Nothing is stateful about a channel: change the `version:` pin and the plugin
+URLs in `.hephconfig`, and the next run downloads and re-execs into the release
+you named. Binaries are cached per tag, so switching back is instant.

website/sidebars.ts

@@ -59,7 +59,7 @@ const sidebars: SidebarsConfig = {
       type: 'category',
       label: 'Reference',
       collapsible: false,
-      items: ['reference/configuration', 'reference/addresses', 'reference/cli'],
+      items: ['reference/configuration', 'reference/release-channels', 'reference/addresses', 'reference/cli'],
     },
   ],
 };

website/src/components/ReleaseChannelSelector.tsx

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react';
+import { Tooltip } from '@heph/uikit';
+import { useReleaseChannel } from '../hooks/useReleaseChannel';
+import {
+  DEFAULT_RELEASE_CHANNEL,
+  RELEASE_CHANNELS,
+  RELEASE_CHANNEL_IDS,
+} from '../releaseChannels';
+
+/**
+ * Segmented control sitting on top of a code block whose contents depend on the
+ * release channel — the version pin, plugin manifest URLs, the installer.
+ * Picking a channel switches every such block on the page at once.
+ */
+export function ReleaseChannelSelector(): ReactNode {
+  const { channel, setChannel } = useReleaseChannel();
+
+  return (
+    <div className="hephChannelBar">
+      <span className="hephChannelBar__label">channel</span>
+      <div className="hephChannelBar__group" role="radiogroup" aria-label="Release channel">
+        {RELEASE_CHANNEL_IDS.map((id) => {
+          const c = RELEASE_CHANNELS[id];
+          const selected = id === channel;
+          return (
+            <Tooltip key={id} title={c.description}>
+              <button
+                type="button"
+                role="radio"
+                aria-checked={selected}
+                className={`hephChannelBar__option${selected ? ' hephChannelBar__option--on' : ''}`}
+                onClick={() => setChannel(id)}
+              >
+                {c.label}
+                {id === DEFAULT_RELEASE_CHANNEL && <span className="hephChannelBar__default">default</span>}
+              </button>
+            </Tooltip>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

website/src/components/landing/Nav.tsx

@@ -12,6 +12,7 @@ const STATUS_TAIL = [
 
 /** Technical status strip + minimal mono nav. */
 export function Nav() {
+  // Marketing chrome always quotes the default release channel.
   const { version } = useLatestVersion();
   const status = [{ label: version ? `v${version}` : 'v…' }, ...STATUS_TAIL];
   return (