Update docs.

Author: milesj

website/blog/2026-07-23_proto-v0.59.mdx

@@ -63,8 +63,9 @@ designed for — calendar versions, partial versions, and tool-specific quirks.
 been a constant source of edge cases, so in this release, we threw it all away and wrote a custom
 grammar-based parser designed for how proto actually consumes versions.
 
-What does this unlock? For starters, first-class version scopes: a named prefix attached to a
-version or requirement, such as `openjdk-21.0.2`, `zulu-26`, or `pypy-2.1`. Scopes are what power
+What does this unlock? For starters, first-class
+[version scopes](/docs/proto/tool-spec#version-scopes): a named prefix attached to a version or
+requirement, such as `openjdk-21.0.2`, `zulu-26`, or `pypy-2.1`. Scopes are what power
 Java distributions above, are passed through the WASM plugin API for any plugin to consume, and
 remote version lists are now cached per scope.
 
@@ -112,10 +113,11 @@ This release fixes two long-standing `PATH` issues in `proto run` and shim execu
 
 ### Calendar version build segments
 
-As part of the new parser, the proto-specific underscore "micro/build" segment has been removed
-from calendar versions. Use standard build metadata instead.
+As part of the new parser, the proto-specific "micro" build segment (dot or underscore separated)
+has been removed from calendar versions. Use standard build metadata instead.
 
 ```
+2024-02-26.123          ->  2024-02-26+123
 2024-02-26_123-alpha.0  ->  2024-02-26-alpha.0+123
 ```
 

website/docs/proto/reporting.mdx

@@ -57,16 +57,54 @@ This is opt-in, and enabled with the following global options (or environment va
 
 - `--otel` (`PROTO_OTEL`) - Export traces and metrics over OTLP.
 - `--otel-logs` (`PROTO_OTEL_LOGS`) - Also export log events as OTLP logs.
-- `--otel-service-name <name>` (`PROTO_OTEL_SERVICE_NAME`) - The service name to report.
+- `--otel-service-name <name>` (`PROTO_OTEL_SERVICE_NAME`) - The service name to report. If not
+  provided, the standard `OTEL_SERVICE_NAME` environment variable is used.
+  <VersionLabel version="0.59.0" />
 
 The OTLP destination and transport are configured using the standard `OTEL_EXPORTER_OTLP_*`
 environment variables, like `OTEL_EXPORTER_OTLP_ENDPOINT`.
 
 ```shell
+$ export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
+$ proto --otel install node
+```
+
+### Transports<VersionLabel version="0.59.0" />
+
+OTLP payloads can be delivered over HTTP (`http/protobuf`) or gRPC (`grpc`). The transport is
+selected with the standard environment variables, where the per-signal variable takes precedence
+over the generic one:
+
+- `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`, `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`,
+  `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` - The transport for an individual signal.
+- `OTEL_EXPORTER_OTLP_PROTOCOL` - The transport for all signals. When not set, defaults to
+  `http/protobuf`.
+
+The same precedence applies to endpoints, using `OTEL_EXPORTER_OTLP_ENDPOINT` and the per-signal
+`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (and friends) variables. When an endpoint starts with
+`https://`, TLS is enabled, and the collector's certificate is verified against the operating
+system's trust store.
+
+```shell
+# OTLP over gRPC
+$ export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
 $ export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
 $ proto --otel install node
 ```
 
+:::caution
+
+The HTTP transport and TLS support are currently considered experimental.
+
+:::
+
+### Disabling signals<VersionLabel version="0.59.0" />
+
+The standard environment variables can also force signals off, even when the options above have
+enabled them. `OTEL_SDK_DISABLED=true` disables all signals, while `OTEL_TRACES_EXPORTER=none`,
+`OTEL_METRICS_EXPORTER=none`, and `OTEL_LOGS_EXPORTER=none` disable an individual signal. These
+variables can only disable a signal, never enable one.
+
 ### Metrics
 
 When OTEL is enabled, proto records the following metrics. Names ending in `.attempts` are counters,

website/docs/proto/tool-spec.mdx

@@ -120,7 +120,9 @@ tool = "1.2.3"
 ### Guidelines
 
 - major, minor, patch - `0-9` of any length
-- pre, build - `a-z`, `0-9`, `-`, `.`
+- pre, build - `a-z`, `A-Z`, `0-9`, `-`, `_`, `.`
+  - Must start with a letter or number.
+- A leading `v` or `V` prefix is accepted and ignored (`v1.2.3`).
 
 > [Learn more about this format!](https://semver.org/#backusnaur-form-grammar-for-valid-semver-versions)
 
@@ -138,31 +140,65 @@ tool = "2025-02-26"
 
 - `<year>-<month>` - 2024-02
 - `<year>-<month>-<day>` - 2024-02-26
-- `<year>-<month>-<day>.<build>` - 2024-02-26.123
-- `<year>-<month>-<day>_<build>` - 2024-02-26_123
-- `<year>-<month>-<day>.<build>-<pre>` - 2024-02-26.123-alpha.0
-- `<year>-<month>-<day>_<build>-<pre>` - 2024-02-26_123-alpha.0
 - `<year>-<month>-<day>-<pre>` - 2024-02-26-alpha.0
+- `<year>-<month>-<day>+<build>` - 2024-02-26+123
+- `<year>-<month>-<day>-<pre>+<build>` - 2024-02-26-alpha.0+123
 
 ### Guidelines
 
-- year - `0-9` of 1-4 length
+- year - `0-9` of 2-4 length
   - If the year is not YYYY format, it will use the year 2000 as the base. For example, `24` becomes
     `2024`, and `124` becomes `2124`.
 - month - `0-9` of 1-2 length
   - Supports with and without a leading zero (`02` vs `2`).
   - Does not support invalid months (`0` or `13`).
 - day - `0-9` of 1-2 length
-  - Can be omitted, even with build/pre.
+  - Can be omitted, even with pre/build.
   - Supports with and without a leading zero (`02` vs `2`).
   - Does not support invalid days (`0` or `32`).
-- build - `0-9` of any length
-  - Also known as a "micro" number.
-  - The leading dot `.` format is preferred.
-- pre - `a-z`, `0-9`, `-`, `.`
+- pre - `a-z`, `A-Z`, `0-9`, `-`, `_`, `.`
+  - Must start with a letter, so that it is not mistaken for a day number.
+- build - `a-z`, `A-Z`, `0-9`, `-`, `_`, `.`
+  - Uses the same `+` prefixed build metadata syntax as semver.
+- A leading `v` or `V` prefix is accepted and ignored (`v2024-02`).
+
+:::caution
+
+The dot (`2024-02-26.123`) and underscore (`2024-02-26_123`) suffixed "micro" build segments from
+older proto versions were removed in v0.59. Use build metadata instead, for example
+`2024-02-26+123`.
+
+:::
 
 > [Learn more about this format!](https://calver.org/#scheme)
 
+## Version scopes<VersionLabel version="0.59.0" />
+
+Both version formats support an optional scope, which is a named prefix attached to the version
+with a dash. What a scope represents is defined by each tool's plugin — for example, the built-in
+Java plugin uses scopes to choose a [distribution vendor](./tools) — but the format itself is
+universal.
+
+```toml title=".prototools"
+java = "openjdk-21.0.2"
+jdk = "temurin-21"
+```
+
+### Syntax
+
+- `<scope>-<version>` - openjdk-21.0.2, zulu-2026-01-15
+- `<scope>-<requirement>` - temurin-21, ^zulu-26
+
+### Guidelines
+
+- scope - `a-z`, `A-Z`, `0-9`, `-`, `_`, `.`
+  - Must start with a letter or number.
+  - May itself contain dashes, as the scope ends where a valid version or requirement begins. For
+    example, `graalvm-community-24.1.2` is the scope `graalvm-community` with the version `24.1.2`.
+- Scopes also work within [requirements and ranges](#requirements-and-ranges), for example
+  `temurin-21 || zulu-22`.
+- Available version lists are fetched and cached separately for each scope.
+
 ## Requirements and ranges
 
 Besides an explicit version, we also support partial versions known as version requirements or
@@ -178,8 +214,9 @@ tool-c = ">=2000-10"
 
 ### Syntax
 
-- Requirement - `[<op>]<pattern>` - `1.2.3`, `>4.5`, `~3`, `^2000-10`, etc
-- AND range - `<requirement>[,] <requirement> ...` - `>=1, <2`, `^1.3 <=1.3.9`, etc
+- Requirement - `[<op>]<pattern>` - `1.2.3`, `>4.5`, `~3`, `^2000-10`, `1.x`, etc
+- AND range - `<requirement>[,|&&] <requirement> ...` - `>=1, <2`, `>=1 && <2`, `^1.3 <=1.3.9`,
+  etc
 - OR range - `<requirement> || <requirement> ...` - `^1.2 || ^2.3`, `~2000-10 || ~2010-2`, etc
 
 ### Guidelines
@@ -191,9 +228,11 @@ tool-c = ">=2000-10"
     compatible)
   - To specify an _exact_ version, use the `=` operator explicitly.
 - pattern
-  - Dot-separated semver, with optional major and patch numbers.
+  - Dot-separated semver, with optional minor and patch numbers.
   - Dash-separated calver, with optional month and day numbers.
-  - Pre-release and build metadata are only supported when suffixed to full versions.
+  - Numbers may be a wildcard (`*`, `x`, `X`) to match any value, for example `1.x` or `2024-2-*`.
+  - May be prefixed with a [version scope](#version-scopes).
+  - Pre-releases may be suffixed to partial versions, but must start with a letter.
 
 For example, if you want to use `npm` 11.6.2 but 11.6.3 has an issue, use:
 `npm = "^11.6.4 || =11.6.2"`