Builds and releases; comline release

docs/docs/getting-started.md

@@ -69,9 +69,11 @@ struct Greeting {
 comline build
 ```
 
-This compiles and validates the schemas, then freezes the result as version
-`0.0.1` in a content-addressable store under `.comline/`. Later builds
-[bump the version automatically](reference/versioning.md) by the largest change
+This compiles and validates the schemas, then freezes the result as a build,
+`0.1.0-dev.1`, in a content-addressable store under `.comline/`. Builds lead up
+to a release; when you want a version consumers see, run `comline release`
+(the first is `0.1.0`), and later releases
+[take the bump automatically](reference/versioning.md) from the largest change
 since the last one.
 
 Validate without freezing — safe for editors and pre-commit hooks:

docs/docs/guide/index.md

@@ -27,8 +27,9 @@ and then **freezes** the result: the schema becomes a set of immutable [Intermed
 written into a Content Addressable Store, [`.comline/`](ir/cas.md), as a new
 commit in an append-only chain.
 
-The package version bumps automatically on each build, by the largest change
-since the last one — see [Versioning rules](../reference/versioning.md).
+Each build is recorded under a pre-release version leading to the next release;
+`comline release` creates that version, bumped by the largest change since the
+last one — see [Versioning rules](../reference/versioning.md).
 
 ## 3. [Generate code](codegen/generating-code.md)
 

docs/docs/proposals/schema-compatibility.md

@@ -407,6 +407,12 @@ Cargo's convention:
 
 ## Builds and releases
 
+> **Built** ([core#133](https://github.com/ComlineProject/core/pull/133),
+> [cli#90](https://github.com/ComlineProject/cli/pull/90)): builds carry
+> `X.Y.Z-dev.N`, the release they lead to; `comline release` with `--raise`
+> and `1.0`. Not yet: `--lower` (how consumers accept a package-wide loss of
+> version honesty is open) and assigning `@id`s at 1.0 (core#127).
+
 Decided 2026-10-20. Today every build that changes something creates a commit
 with a new version, so five edit-and-build cycles make five patch versions, and
 a commit records neither the computed bump nor a reason. Instead, **builds and

docs/docs/reference/cli.md

@@ -35,8 +35,9 @@ parse → resolve imports → validate → (freeze into .comline/) → (generate
 | `comline add <name> <dir>` / `comline add <name> --git <uri> --commit <sha> --version <v>` | Add a dependency to `config.idp`, imported as `use <name>::…`: resolved first (a git pin is fetched into `.comline/deps-cache/`), then written with its `hash` pinned. `--no-hash` skips the pin. If it has [`@unverified`](../guide/idl/protocol.md#giving-up-a-guarantee) protocols, what each gives up is shown and, on a terminal, you're asked to accept it (default no); without a terminal it refuses (exit `2`) unless `--accept-unverified`. |
 | `comline accept <name>[::<protocol>] [--yes]` | Accept what a dependency's [`@unverified`](../guide/idl/protocol.md#giving-up-a-guarantee) protocols give up: shows each one's given-up guarantees and reason, then writes `accept_unverified` into its `config.idp` entry, leaving the rest as written. Only protocols not already accepted for exactly their current set are asked about. On a terminal you're asked (default no); without one it refuses (exit `2`) unless `--yes` (`-y`). |
 | `comline check` | Parse, resolve and validate. No `.comline/` write (beyond fetching git dependencies), no version bump — safe for editors, hooks, CI. |
-| `comline build [--release] [--watch]` | Compile, validate, freeze a new immutable version into `.comline/`; print the changelog and the bump. `--release` is currently a no-op. |
+| `comline build [--release] [--watch]` | Compile, validate, and freeze a build into `.comline/` under a pre-release version (`0.3.0-dev.2`); print the changelog, the bump, and the next release. `--release` is currently a no-op (releasing is `comline release`). |
 | `comline generate [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--external-std] [--no-external-std] [--validate-on-decode <when>] [--dry-run] [--list] [--watch]` | Validate (no freeze), then write generated code. Location/layout from [`comline.toml`](congregation/comline-toml.md); targets from there or `config.idp`. |
+| `comline release [1.0] [--raise <level> --reason <text>] [--yes]` | Build, then release: create the version from the highest bump since the last release ([builds and releases](versioning.md#builds-and-releases)). `--raise patch\|minor\|major` goes higher, with a `--reason` recorded with the release; it never lowers. `1.0` makes a `0.x` package stable after showing what that commits to (its protocols, and what's worth settling first). Raising to major and `1.0` ask on a terminal; without one they refuse (exit `2`) unless `--yes` (`-y`). |
 | `comline diff <old> [<new>]` | Show schema changes between two built versions. Each argument is a version (`0.2.0`), a commit hash (4+ chars), or `HEAD` (`<new>` default). |
 | `comline clean [--dry-run]` | Remove generated code (the `generate` output root or files). Never touches `.comline/`. |
 | `comline reset [--force] [--dry-run]` | **Destructive.** Delete `.comline/` — the whole version history, no undo — *and* generated code. Next `build` starts over at `0.0.1`. On a terminal it shows how many versions will be lost and makes you type `reset`; without a terminal it refuses (exit `2`) unless `--force`. |
@@ -77,7 +78,7 @@ everything else goes to stderr.
 |---|---|
 | `0` | success |
 | `1` | ran but failed — invalid schema, unresolved `diff` argument, generator or filesystem error |
-| `2` | precondition not met — not a Comline project, nothing built yet, `reset` not confirmed, or unverified protocols not accepted (also `clap` usage errors) |
+| `2` | precondition not met — not a Comline project, nothing built yet, `reset` / a release not confirmed, or unverified protocols not accepted (also `clap` usage errors) |
 
 ## Versioning
 

docs/docs/reference/congregation/comline-toml.md

@@ -155,8 +155,8 @@ you want fewer.
 | Value | Effect |
 |---|---|
 | `"latest"` (default) | The working tree only. No `.comline/` read. `{{package_version}}` is the last committed version (empty if never built). |
-| `"all"` | Every committed version in the project's history. |
-| `["0.3.0", "0.4.0"]` | Exactly those versions (version strings or commit hashes). |
+| `"all"` | Every release in the project's history (not the builds between them). |
+| `["0.3.0", "0.4.0"]` | Exactly those versions: releases, builds (`0.3.0-dev.2`) or commit hashes. |
 
 Anything but `"latest"` reads the content-addressable store, so the project must
 have been built at least once. Selecting more than one version **requires**

docs/docs/reference/versioning.md

@@ -1,16 +1,46 @@
 # Versioning rules
 
-Comline versions a package **automatically**. Every `comline build` compares the
-new schemas against the previous frozen version and bumps the package version by
-the largest change it finds. You never write a version by hand — there is no
-version field in the manifest; it comes from the
-[content-addressable store](../guide/ir/cas.md).
-
-Versions follow [SemVer](https://semver.org/). The first build is `0.0.1`. A
-build that changes nothing keeps the version and adds no commit. A change that
-takes no bump, such as to `code_generation`, adds a commit at the same version.
+Comline versions a package **automatically**: the version comes from what
+changed, not from a field you write. There is no version in the manifest; it
+lives in the [content-addressable store](../guide/ir/cas.md).
+
+## Builds and releases
+
+**Builds** record history; **releases** are the versions consumers see.
+
+- **`comline build`** compares the schemas against the last *release* and
+  records a build under a pre-release version: the release it leads to, plus
+  a count of builds since the last release. After `0.1.0`, a build adding a
+  feature is `0.1.1-dev.1`; a breaking change in the next build makes it
+  `0.2.0-dev.2`. The build reports the next release and what calls for it.
+  Changes that cancel out between releases cancel out in the bump too. A build
+  that changes nothing adds no commit.
+- **`comline release`** builds, then creates the version from the **highest
+  bump since the last release**. It records the computed bump, the applied
+  one and any reason with the release. The first release is `0.1.0`.
+- **`--raise <level> --reason "…"`** releases a higher bump than the schema
+  shows, for a behaviour change it can't express. A raise the changes already
+  reach is recorded as covered, its reason kept as a note. The bump is never
+  lowered.
+- **`comline release 1.0`** makes a `0.x` package stable, after saying what
+  that commits to.
+
 `comline diff <old> <new>` runs the same comparison between any two stored
-versions on demand.
+versions, builds or releases, on demand.
+
+## Before 1.0
+
+Versions follow [SemVer](https://semver.org/), with Cargo's convention before
+1.0: while the version is `0.x`, the minor plays the part of the major.
+
+| Change | `0.x` | `1.0` and later |
+|---|---|---|
+| breaking | `0.3.2` → `0.4.0` | `1.3.2` → `2.0.0` |
+| new feature | `0.3.2` → `0.3.3` | `1.3.2` → `1.4.0` |
+| modification | `0.3.2` → `0.3.3` | `1.3.2` → `1.3.3` |
+
+Histories from before builds and releases were separate keep their versions,
+which all count as releases; from a `0.0.z` release the next one is `0.1.0`.
 
 ## Schema changes
 
@@ -59,7 +89,7 @@ git-inspired, no branches, never rewritten — so any past version stays
 reproducible.
 
 Nothing else holds this history — there is no `publish` yet — so losing
-`.comline/` means the next build starts over at `0.0.1`, with no undo.
+`.comline/` means the next build starts over at `0.1.0-dev.1`, with no undo.
 `comline clean` leaves it alone; only **`comline reset`** deletes it, behind a
 typed confirmation (or `--force`). See
 [the `clean` / `reset` split](../design/ir-generation.md#the-clean-reset-split).