docs: add more details about explicit version management (#156)

As a follow-up to #151, add a bit more prose to the docs about the existence of
explicitly-managed version numbers, and some recommendations about when to use
them.

Author: creachadair

docs/README.md

@@ -21,6 +21,7 @@ Setec is a lightweight secrets management service that uses Tailscale for access
 - [Operations and Maintenance](#operations-and-maintenance)
    - [Secret Rotation](#secret-rotation)
    - [Automatic Updates](#automatic-updates)
+   - [Explicit Version Management](#explicit-version-management)
    - [Bootstrapping and Availability](#bootstrapping-and-availability)
 - [Testing](#testing)
 
@@ -93,14 +94,24 @@ secret.
   version**. The active version is reported by default from the `get` method if
   the caller does not specify a specific version.
 
-- When a secret is first created, its initial value (version 1) becomes its
-  current active version.
+- When a secret is first created, its initial value becomes its current active
+  version.
+
+  The `put` API method assigns sequential versions starting from the largest
+  previously used (initially 1, for a new secret).
+  The `create-version` API method uses the version number specified by the caller.
+
+- Thereafter, the active version changes in the following ways:
+
+  The `activate` method updates the current active version to a specific
+  existing value.
+
+  A successful `create-version` method call automatically activates the new
+  version of the secret that it created.
+
+  Note that `put` does _not_ automatically update the active version, except
+  when creating the initial value of a new secret.
 
-- Thereafter, the `activate` method must be used to update the current active
-  version. This ensures the operator of the service has precise control over
-  which version of a secret should be used at a time.
-   - The special `create-version` method automatically activates the set
-     version and does not require a call to `activate`.
 
 ### Deleting Values
 
@@ -422,6 +433,26 @@ effects a poll of all known secrets synchronously. It is safe for the client to
 do this concurrently with a background poll; the store will coalesce the
 operations.
 
+### Explicit Version Management
+
+For some use cases, the caller may wish to explicitly control the version
+numbers of a secret. For example, a caller may wish to associate multiple
+secret values with one or more timestamps or other identifying values.
+
+To support this, the [API](api.md) supports a `create-version` method, allowing
+the caller to explicitly choose the version number assigned to a secret value.
+The `create-version` method automatically activates a newly-created version,
+but such values are otherwise normal, and can be fetched and deleted in the
+usual way. Note, however, that a particular version number cannot be reused
+once created, even if it is later deleted.
+
+Although it is safe to mix `put`, `activate` and `create-version` calls on the
+same secret, for clarity of use we recommend using _either_ `create-version`
+alone, _or_ `put` and `activate` together, but not both. Regardless which
+version management style you use, secret values can be [updated
+automatically](#automatic-updates) in the usual way.
+
+
 ### Bootstrapping and Availability
 
 A reasonable concern when fetching secrets from a network service is what

docs/api.md

@@ -1,7 +1,7 @@
 # setec API
 
 > WARNING: This API is still under active development, and subject to change.
-> This document is up-to-date as of 11-May-2024.
+> This document is up-to-date as of 15-Jan-2026.
 
 The setec service exports an API over HTTPS. All methods of the API are called
 via HTTPS POST, with request and response payloads transmitted as JSON.
@@ -33,8 +33,8 @@ The service defines named _actions_ that are subject to access control:
 
 - `put`: Denotes permission to put a new value of a secret.
 
-- `create-version`: Denotes permission to create a specific version of a secret, but not
-   override an existing version.
+- `create-version`: Denotes permission to create a specific version of a
+   secret, but not overwrite an existing version.
 
 - `activate`: Denotes permission to set one one of of the available versions of
   a secret as the active one.
@@ -130,7 +130,10 @@ The service defines named _actions_ that are subject to access control:
   secret, the server reports the existing active version without modifying the
   store.
 
-- `/api/create-version`: Creates a specific version of a secret, sets its value and immediately activates that version. It fails if this version of the secret already has a value. The specified version must be > 0.
+- `/api/create-version`: Creates a new version of a secret, sets its value and
+  immediately activates that version. It fails if the specified version number
+  has already been used for this secret (even if deleted).  The specified
+  version number must be > 0.
 
   **Requires:** `create-version` permission for the specified name.