From 75b1e2f68bffaca982c739c0bca11288057ed495 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 25 Aug 2026 02:03:11 +0000 Subject: [PATCH] Document source release deployment --- README.md | 14 ++++++++++++++ docs/internal/overview.md | 1 + docs/operations.md | 17 +++++++++++++++++ docs/policy/architecture.md | 10 ++++++++++ docs/roadmap/implementation.md | 2 +- 5 files changed, 43 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 22383cbc..3317ace0 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,20 @@ For the complete ordered D&D workflow, use [its synthetic transcript](examples/dnd-complete-transcript.json). It demonstrates all implemented D&D lanes and the supporting campaign references. +## Install A Source Release + +Install a pinned source release with Go: + +~~~ +GOWORK=off go install \ + gitea.maximumdirect.net/eric/notarius/cmd/notarius@ +~~~ + +Replace `` with a stable release tag such as `vMAJOR.MINOR.PATCH`. The +installed command's diagnostic version is described in the [CLI +reference](docs/cli.md); maintainers preparing a release should follow [Source +Releases](docs/release.md). + ## Documentation - [CLI reference](docs/cli.md) — commands, flags, output streams, and exits. diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 5c4531d7..c2ef559d 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -25,6 +25,7 @@ physical state roots. | Area | Implemented owners | Responsibility | | --- | --- | --- | | Executable and command boundary | **cmd/notarius**, **internal/cli** | Process entry, command dispatch, configuration discovery, production composition, runtime collaborator setup, durable file placement, and user-facing reporting. | +| Build information | **internal/buildinfo** | Resolves a stable linked release tag or build metadata for the diagnostic root version command. | | Configuration | **internal/core/config** | Defaults, strict YAML parsing, environment overrides, structural validation, effective resolution, redaction, and resolved-composition summaries. | | Generic models | **internal/core/source**, **internal/core/artifacts**, **internal/framework/contracts** | Source documents and chunks, manifests and provenance, plus typed artifact, reference, validation, output, and structured-completion contracts. | | Pipeline framework | **internal/framework/pipeline** | Registries, profile and reference resolution, typed preparation, validation, retry coordination, ordered execution, handoff, and result assembly. | diff --git a/docs/operations.md b/docs/operations.md index 2e554f94..ff98e28d 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -5,6 +5,23 @@ This is the canonical guide for operating Notarius runtime state. The [Configuration](config.md) owns fields, defaults, and precedence. Maintainers who need implementation mechanics should read [Run State Internals](internal/state.md). +## Source Deployment + +Linux is the supported deployment platform. Install a pinned source release +with the Go version declared in `go.mod` (currently Go 1.25.5): + +~~~sh +GOWORK=off go install \ + gitea.maximumdirect.net/eric/notarius/cmd/notarius@vMAJOR.MINOR.PATCH +~~~ + +Pin the exact tag in deployment automation rather than following a branch. +Use [`notarius --version`](cli.md#command-summary) as a diagnostic after +installation; its syntax and semantics are owned by the [CLI reference](cli.md). +The maintainer publication process, including tag guards and verification, +belongs to [Source Releases](release.md). macOS builds are best-effort for +development, and Windows is unsupported. + ## State Surfaces Each run can use independent roots with different retention and access-control diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index b515fffd..296709f2 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -261,6 +261,16 @@ contain application data and therefore inherits its sensitivity; operators own access controls and retention. Physical layout and operation are defined in [Operations](../operations.md). +## Platform And Distribution + +Linux is the supported deployment platform. macOS is supported only as a +best-effort development and compilation environment, while Windows is +unsupported. Notarius distributes source releases only: an immutable source +tag and its checked-in release note identify a release. The project does not +publish executable binaries, archives, installers, container images, +checksums, signatures, or package-manager entries. Maintainer release commands +and tag guards belong to [Source Releases](../release.md). + ## Architectural Non-Goals Notarius does not aim to provide: diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index e2712942..145f7d1f 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -314,7 +314,7 @@ home. matrix. - No historical or placeholder release note is introduced. -## Stage 5: Align Platform, Installation, And Operational Documentation +## Stage 5: Align Platform, Installation, And Operational Documentation ✅ ### Goal