From 110607318f22c3f0cfd03efbe6cd2d864dd1e27f Mon Sep 17 00:00:00 2001
From: Your Name <regina.xu1@gmail.com>
Date: Tue, 15 Sep 2026 12:33:29 +0530
Subject: [PATCH 1/6] Retract pkg/audit v1.0.0 and start the client at v0.1.0.

v1.0.0 was published before the team agreed the API is stable. Leave
existing tags in place and retract 1.x so @latest resolves to v0.1.0.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 CLAUDE.md                        |   6 +-
 README.md                        |   5 +-
 deployments/helm/argus/README.md |   2 +-
 docs/API.md                      |   2 +-
 docs/RELEASE.md                  | 111 +++++++++++++++++++++++++++++++
 go.mod                           |   4 +-
 go.sum                           |   2 -
 pkg/audit/go.mod                 |  11 +++
 8 files changed, 135 insertions(+), 8 deletions(-)
 create mode 100644 docs/RELEASE.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 05a98c7..fb0954a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -46,7 +46,7 @@ sidecar). By default (no `DB_TYPE`/`DB_PATH` set) the service uses an in-memory
 ### Two audiences, two packages
 
 - **`internal/`** — the Argus *service* itself (API, DB, pipeline). Not importable by other projects.
-- **`pkg/audit`** — the *client library* other Go services import (`go get github.com/LSFLK/argus/pkg/audit@latest`). Always pin a tagged release; do not use commit pseudo-versions.
+- **`pkg/audit`** — the *client library* other Go services import (`go get github.com/LSFLK/argus/pkg/audit@v0.1.0`). Always pin a tagged 0.x release; do not use v1.0.0 (retracted) or commit pseudo-versions.
   to send audit events to a running Argus instance. This is a separate logical module from the service;
   don't leak service-internal types into it, and don't assume service-side dependencies (GORM, sinks) are
   available here. `pkg/audit/security.go` implements client-side request signing (RSA/Ed25519) that mirrors
@@ -120,3 +120,7 @@ then pushed into `internal/api/v1/models` via `SetEnumConfig` for O(1) validatio
 
 The API is versioned by Go package path (`internal/api/v1/...`), not just by URL prefix — a `v2` would
 live alongside `v1` as a new package tree, mirroring the same handlers/services/models/database layers.
+
+Git tags, GitHub Releases, Helm chart versions, and the `pkg/audit` Go module are **separate** version
+lines and are immutable once published. See `docs/RELEASE.md` for the inventory of already-used names
+and the process for cutting a new client/chart release. Do not move, delete, or reuse those tags.
diff --git a/README.md b/README.md
index c09d547..33d0eb4 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@
 
 ### Step 1: Add Argus to your project
 ```bash
-go get github.com/LSFLK/argus/pkg/audit@latest
+go get github.com/LSFLK/argus/pkg/audit@v0.1.0
 ```
 
 ### Step 2: Initialize the hardened audit client
@@ -69,7 +69,7 @@ Argus is designed to be the centralized audit source of truth for any microservi
 ### 1. Installation
 In your application:
 ```bash
-go get github.com/LSFLK/argus/pkg/audit@latest
+go get github.com/LSFLK/argus/pkg/audit@v0.1.0
 ```
 
 ### 2. Global Initialization
@@ -180,6 +180,7 @@ For full Helm configuration parameters, GitOps umbrella chart integration, and O
 - [API Reference](docs/API.md)
 - [Architecture Deep Dive](docs/ARCHITECTURE.md)
 - [Database Setup](docs/DATABASE_CONFIGURATION.md)
+- [Release process](docs/RELEASE.md) (published tags are listed there — do not reuse them)
 
 ## License
 Distributed under the Apache 2.0 License. See [LICENSE](LICENSE) for more information.
diff --git a/deployments/helm/argus/README.md b/deployments/helm/argus/README.md
index b46c0ba..0d6e84a 100644
--- a/deployments/helm/argus/README.md
+++ b/deployments/helm/argus/README.md
@@ -82,7 +82,7 @@ argus:
 
 The Helm chart automation follows a standard GitOps setup:
 - **Application image (`.github/workflows/build-image.yml`)**: Builds and pushes `ghcr.io/lsflk/argus` (`:<git sha>` and `:latest`) on pushes to `main`. PRs that touch Go code or the Dockerfile build the image without pushing. After the first publish, set the GHCR package visibility to public under https://github.com/orgs/LSFLK/packages so clusters can pull without an imagePullSecret.
-- **Dev Chart (`.github/workflows/build-dev-chart.yml`)**: On pushes to `main` with chart changes (or manual dispatch), packages and publishes a dev chart (`0.0.0-dev.<run_number>`) to `oci://ghcr.io/lsflk/charts`. After the image push completes, publish the stable chart by dispatching this workflow with `version=0.1.1`.
+- **Dev Chart (`.github/workflows/build-dev-chart.yml`)**: On pushes to `main` with chart changes (or manual dispatch), packages and publishes a dev chart (`0.0.0-dev.<run_number>`) to `oci://ghcr.io/lsflk/charts`. After the image push completes, publish a **new** stable chart version by dispatching this workflow with an unpublished `version` (never reuse `0.1.1`). See [docs/RELEASE.md](../../../docs/RELEASE.md).
 - **Chart CI (`.github/workflows/helm-ci.yml`)**: Lints the chart and verifies template rendering on pull requests.
 
 ### Manual Packaging and Push
diff --git a/docs/API.md b/docs/API.md
index cb945fe..e674ace 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -192,7 +192,7 @@ curl http://localhost:3001/version
 ```json
 {
   "service": "argus",
-  "version": "1.0.0",
+  "version": "0.1.0",
   "buildTime": "2024-01-20T10:00:00Z",
   "gitCommit": "abc123def456"
 }
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
new file mode 100644
index 0000000..b983240
--- /dev/null
+++ b/docs/RELEASE.md
@@ -0,0 +1,111 @@
+# Release process
+
+Published versions are **immutable**. Do not delete, move, retarget, or reuse a tag, GitHub Release, Helm chart version, or container digest that has already been pushed. Go’s module proxy (`proxy.golang.org`) and checksum database (`sum.golang.org`) keep module versions even if the GitHub tag is later removed.
+
+Argus has **four independent version lines**. A number used in one line does not free it in another.
+
+| Line | Identity | How it is published |
+| --- | --- | --- |
+| Root git tags | `github.com/LSFLK/argus` | `vX.Y.Z` git tags. Other services should not import this module. |
+| Client module | `github.com/LSFLK/argus/pkg/audit` | Nested tags `pkg/audit/vX.Y.Z` (required for a module in a subdirectory). This is what `go get` consumes. The GitHub Release title may be `v0.1.0`; the git tag is still `pkg/audit/v0.1.0`. |
+| Helm chart | `oci://ghcr.io/lsflk/charts/argus` | Chart `version` in `deployments/helm/argus/Chart.yaml`. OCI versions cannot be overwritten. |
+| App image | `ghcr.io/lsflk/argus` | `:latest` (mutable) and `:<git sha>` only. There are no semver image tags. |
+
+## Already published — do not reuse
+
+These names are taken. Never create a new release, tag, or chart that recycles them.
+
+### Git tags
+
+| Tag | Points at | Status |
+| --- | --- | --- |
+| `v0.1.0` | Initial repo (`787b047`) | Root-module tag. Leave as-is. Do not move onto a later commit. |
+| `v1.0.0` | JSONB work (`61371c4`) | Root-module tag. Do not move or delete. |
+| `v1.0.1` | Client utilities (`2512797`) | Root-module tag. Do not move or delete. |
+| `pkg/audit/v1.0.0` | `85d5ea5` | **Retracted** Go client. Cached by the module proxy and checksum DB. Do not move, delete, or `gh release delete --cleanup-tag`. |
+| `pkg/audit/v1.0.1` | retract commit | Retract-announcement only (itself retracted). Not a usable 1.x client. |
+| `pkg/audit/v0.1.0` | retract commit | **Current Go client.** Pin this. Next client tag is `pkg/audit/v0.1.1` or `pkg/audit/v0.2.0`. |
+
+Root `v0.1.0` and client `pkg/audit/v0.1.0` are different tags. Do not retarget the root tag to “match” the client.
+
+### GitHub Releases
+
+| Release | Tag | Status |
+| --- | --- | --- |
+| `[RETRACTED] pkg/audit v1.0.0` | `pkg/audit/v1.0.0` | Retracted. Notes point at `v0.1.0`. Do not delete. |
+| `v0.1.0` | `pkg/audit/v0.1.0` | Current client release. |
+
+Do not backfill GitHub Releases onto root tags `v0.1.0` / `v1.0.0` / `v1.0.1`.
+
+### Helm
+
+| Chart version | Registry | Status |
+| --- | --- | --- |
+| `0.1.1` | `oci://ghcr.io/lsflk/charts/argus` | Published. Do not `helm push` this version again. Next chart is `0.1.2` or higher. |
+
+`Chart.yaml` `appVersion` is metadata only and must not be “fixed” by republishing `0.1.1`.
+
+### Container images
+
+Images are `ghcr.io/lsflk/argus:<git sha>` and `:latest`. Do not invent `:1.0.0` / `:0.1.0` tags for old SHAs.
+
+## Current policy
+
+The **product and client** stay on **0.x** until the team agrees a stable 1.0. Breaking changes on 0.x bump the minor (`0.1.0` → `0.2.0`). Client `v1.0.0` stays published and is **retracted** in `pkg/audit/go.mod` so `go get @latest` selects `v0.1.0`.
+
+`retract` does not unpublish a version. Pinning `@v1.0.0` still works. That is intentional.
+
+## Cutting a client release (`pkg/audit`)
+
+1. Land the change on `main`. Do not retarget an old tag.
+2. Tag `pkg/audit/vX.Y.Z` on that commit. Never reuse a tag from the table above. Next after `v0.1.0` is `v0.1.1` (patch) or `v0.2.0` (break).
+3. Push the new tag (`git push origin <tag>`). Do not `--force` tags.
+4. `gh release create 'pkg/audit/vX.Y.Z' --title 'vX.Y.Z' --notes '...'`
+
+Annotated tags, nested-module name:
+
+```bash
+git tag -a pkg/audit/v0.1.1 -m "pkg/audit v0.1.1"
+git push origin pkg/audit/v0.1.1
+```
+
+Consumers:
+
+```bash
+go get github.com/LSFLK/argus/pkg/audit@v0.1.0
+```
+
+This repo uses `replace github.com/LSFLK/argus/pkg/audit => ./pkg/audit` so service builds do not wait on the proxy.
+
+## Cutting a Helm chart release
+
+1. Bump `deployments/helm/argus/Chart.yaml` `version` to a **new** number (never `0.1.1` again).
+2. Merge to `main` or dispatch [build-dev-chart.yml](../.github/workflows/build-dev-chart.yml) with that version.
+3. A path-only change under `deployments/helm/` on `main` publishes `0.0.0-dev.<run_number>`, not a stable chart. That is expected.
+
+## What CI does (and does not)
+
+No workflow runs on git tags or GitHub Releases today. Tagging `pkg/audit/v0.1.0` does not publish an image or chart by itself.
+
+| Workflow | Trigger | Effect |
+| --- | --- | --- |
+| `build-image.yml` | Push/PR to `main` touching Go/Dockerfile paths | PR: build only. `main`: push `:sha` and retag `:latest`. |
+| `build-dev-chart.yml` | Push to `main` touching `deployments/helm/**`, or manual dispatch | Packages a chart. Empty input → `0.0.0-dev.<run_number>`. Dispatching an **already published** chart version will fail (OCI immutable). |
+| `helm-ci.yml` | PRs touching the chart | Lint/template only. |
+
+There is no Go test workflow. Run `go test ./...` locally before tagging.
+
+## Commands that are not allowed
+
+```bash
+# Do not — does not unpublish the Go module, and may delete the wrong tag.
+gh release delete v1.0.0 --cleanup-tag
+gh release delete 'pkg/audit/v1.0.0' --cleanup-tag
+
+git tag -d v0.1.0
+git push origin :refs/tags/v0.1.0
+git tag -f v0.1.0
+git tag -f pkg/audit/v0.1.0
+```
+
+To stop the toolchain from *selecting* a bad module version, add `retract` and ship a new tag. To warn humans, edit the GitHub Release notes. Do both; neither replaces the other.
diff --git a/go.mod b/go.mod
index 07bc31c..f211ea1 100644
--- a/go.mod
+++ b/go.mod
@@ -3,7 +3,7 @@ module github.com/LSFLK/argus
 go 1.24.6
 
 require (
-	github.com/LSFLK/argus/pkg/audit v1.0.0
+	github.com/LSFLK/argus/pkg/audit v0.1.0
 	github.com/aws/aws-sdk-go-v2 v1.41.7
 	github.com/aws/aws-sdk-go-v2/config v1.32.17
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.101.0
@@ -56,3 +56,5 @@ require (
 	golang.org/x/text v0.28.0 // indirect
 	google.golang.org/protobuf v1.36.8 // indirect
 )
+
+replace github.com/LSFLK/argus/pkg/audit => ./pkg/audit
diff --git a/go.sum b/go.sum
index c2edc58..e0a22e7 100644
--- a/go.sum
+++ b/go.sum
@@ -1,5 +1,3 @@
-github.com/LSFLK/argus/pkg/audit v1.0.0 h1:iM0nC7k/l3adpg7ywKZ/ar4gphiPL2F5kA+au6WzMl4=
-github.com/LSFLK/argus/pkg/audit v1.0.0/go.mod h1:VPLkj7lPFOPSTNZulUsf+OCWcjz9vdndCRhcc2hfQjM=
 github.com/aws/aws-sdk-go-v2 v1.41.7 h1:DWpAJt66FmnnaRIOT/8ASTucrvuDPZASqhhLey6tLY8=
 github.com/aws/aws-sdk-go-v2 v1.41.7/go.mod h1:4LAfZOPHNVNQEckOACQx60Y8pSRjIkNZQz1w92xpMJc=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 h1:gx1AwW1Iyk9Z9dD9F4akX5gnN3QZwUB20GGKH/I+Rho=
diff --git a/pkg/audit/go.mod b/pkg/audit/go.mod
index c4a6955..bd776b3 100644
--- a/pkg/audit/go.mod
+++ b/pkg/audit/go.mod
@@ -1,3 +1,14 @@
 module github.com/LSFLK/argus/pkg/audit
 
 go 1.24.6
+
+// v1.0.0 was tagged before the team agreed the client API is stable.
+// Do not move or delete pkg/audit/v1.0.0: proxy.golang.org and
+// sum.golang.org already cached it.
+// v1.0.1 exists only so the go command can discover these retract
+// directives (it reads them from the highest release, even if retracted).
+// Consumers should pin v0.1.0 (git tag pkg/audit/v0.1.0).
+retract (
+	v1.0.0
+	v1.0.1
+)

From 36859207c5572634963bded0ab87c69761b2280d Mon Sep 17 00:00:00 2001
From: Your Name <regina.xu1@gmail.com>
Date: Tue, 15 Sep 2026 13:10:10 +0530
Subject: [PATCH 2/6] Clarify that Helm chart 0.1.1 is not the Go client
 v0.1.0.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md       |  2 +-
 docs/RELEASE.md | 15 +++++++++++----
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 33d0eb4..c055963 100644
--- a/README.md
+++ b/README.md
@@ -147,7 +147,7 @@ Argus exports standard Prometheus metrics at `/metrics`:
 
 ## Deployment & Helm Chart
 
-Argus provides an official Helm chart published as an **OCI Artifact** to GitHub Container Registry (`ghcr.io/lsflk/charts/argus`), as well as local chart source at [`deployments/helm/argus`](deployments/helm/argus). The application container image is published to `ghcr.io/lsflk/argus` (`:latest` and `:<git sha>`).
+Argus provides an official Helm chart published as an **OCI Artifact** to GitHub Container Registry (`ghcr.io/lsflk/charts/argus`), as well as local chart source at [`deployments/helm/argus`](deployments/helm/argus). The application container image is published to `ghcr.io/lsflk/argus` (`:latest` and `:<git sha>`). Chart version `0.1.1` is the Helm package ([GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus)); it is not the Go client (`pkg/audit@v0.1.0`).
 
 ### Install via OCI Artifact (Recommended)
 ```bash
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index b983240..fda184a 100644
--- a/docs/RELEASE.md
+++ b/docs/RELEASE.md
@@ -2,6 +2,13 @@
 
 Published versions are **immutable**. Do not delete, move, retarget, or reuse a tag, GitHub Release, Helm chart version, or container digest that has already been pushed. Go’s module proxy (`proxy.golang.org`) and checksum database (`sum.golang.org`) keep module versions even if the GitHub tag is later removed.
 
+**`0.1.1` is the Helm chart, not the Go client.** They are not typos for each other:
+
+| Artifact | Current version | Where |
+| --- | --- | --- |
+| Go client (`pkg/audit`) | `v0.1.0` | [GitHub Release](https://github.com/LSFLK/argus/releases/tag/pkg/audit/v0.1.0) (`go get …@v0.1.0`) |
+| Helm chart | `0.1.1` | [GHCR `charts/argus`](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus) (`helm … --version 0.1.1`) |
+
 Argus has **four independent version lines**. A number used in one line does not free it in another.
 
 | Line | Identity | How it is published |
@@ -24,7 +31,7 @@ These names are taken. Never create a new release, tag, or chart that recycles t
 | `v1.0.1` | Client utilities (`2512797`) | Root-module tag. Do not move or delete. |
 | `pkg/audit/v1.0.0` | `85d5ea5` | **Retracted** Go client. Cached by the module proxy and checksum DB. Do not move, delete, or `gh release delete --cleanup-tag`. |
 | `pkg/audit/v1.0.1` | retract commit | Retract-announcement only (itself retracted). Not a usable 1.x client. |
-| `pkg/audit/v0.1.0` | retract commit | **Current Go client.** Pin this. Next client tag is `pkg/audit/v0.1.1` or `pkg/audit/v0.2.0`. |
+| `pkg/audit/v0.1.0` | retract commit | **Current Go client.** Pin this. A later client patch would be `pkg/audit/v0.1.1` (unrelated to Helm chart `0.1.1`). |
 
 Root `v0.1.0` and client `pkg/audit/v0.1.0` are different tags. Do not retarget the root tag to “match” the client.
 
@@ -41,7 +48,7 @@ Do not backfill GitHub Releases onto root tags `v0.1.0` / `v1.0.0` / `v1.0.1`.
 
 | Chart version | Registry | Status |
 | --- | --- | --- |
-| `0.1.1` | `oci://ghcr.io/lsflk/charts/argus` | Published. Do not `helm push` this version again. Next chart is `0.1.2` or higher. |
+| `0.1.1` | [`oci://ghcr.io/lsflk/charts/argus`](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus) | **Current Helm chart.** Published. Do not `helm push` this version again. Next chart is `0.1.2` or higher. |
 
 `Chart.yaml` `appVersion` is metadata only and must not be “fixed” by republishing `0.1.1`.
 
@@ -58,11 +65,11 @@ The **product and client** stay on **0.x** until the team agrees a stable 1.0. B
 ## Cutting a client release (`pkg/audit`)
 
 1. Land the change on `main`. Do not retarget an old tag.
-2. Tag `pkg/audit/vX.Y.Z` on that commit. Never reuse a tag from the table above. Next after `v0.1.0` is `v0.1.1` (patch) or `v0.2.0` (break).
+2. Tag `pkg/audit/vX.Y.Z` on that commit. Never reuse a tag from the table above.
 3. Push the new tag (`git push origin <tag>`). Do not `--force` tags.
 4. `gh release create 'pkg/audit/vX.Y.Z' --title 'vX.Y.Z' --notes '...'`
 
-Annotated tags, nested-module name:
+Annotated tags, nested-module name (example of a later client patch — not the Helm chart):
 
 ```bash
 git tag -a pkg/audit/v0.1.1 -m "pkg/audit v0.1.1"

From ddb144ee5b642f26e45d0ef8a0ef280b3c692cc4 Mon Sep 17 00:00:00 2001
From: Your Name <regina.xu1@gmail.com>
Date: Tue, 15 Sep 2026 13:36:43 +0530
Subject: [PATCH 3/6] Make release docs evergreen and point installs at latest.

Keep frozen history for retracted 1.x tags; look up current client and
chart versions from GitHub/GHCR instead of rewriting this file every bump.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 CLAUDE.md                        |   6 +-
 README.md                        |   9 ++-
 deployments/helm/argus/README.md |  13 ++--
 docs/API.md                      |   2 +-
 docs/RELEASE.md                  | 120 ++++++++++++-------------------
 pkg/audit/go.mod                 |   2 +-
 6 files changed, 59 insertions(+), 93 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index fb0954a..d40a74f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -46,7 +46,7 @@ sidecar). By default (no `DB_TYPE`/`DB_PATH` set) the service uses an in-memory
 ### Two audiences, two packages
 
 - **`internal/`** — the Argus *service* itself (API, DB, pipeline). Not importable by other projects.
-- **`pkg/audit`** — the *client library* other Go services import (`go get github.com/LSFLK/argus/pkg/audit@v0.1.0`). Always pin a tagged 0.x release; do not use v1.0.0 (retracted) or commit pseudo-versions.
+- **`pkg/audit`** — the *client library* other Go services import (`go get github.com/LSFLK/argus/pkg/audit@latest`). Pin the resolved tag in `go.mod`; do not use retracted 1.x versions or commit pseudo-versions.
   to send audit events to a running Argus instance. This is a separate logical module from the service;
   don't leak service-internal types into it, and don't assume service-side dependencies (GORM, sinks) are
   available here. `pkg/audit/security.go` implements client-side request signing (RSA/Ed25519) that mirrors
@@ -122,5 +122,5 @@ The API is versioned by Go package path (`internal/api/v1/...`), not just by URL
 live alongside `v1` as a new package tree, mirroring the same handlers/services/models/database layers.
 
 Git tags, GitHub Releases, Helm chart versions, and the `pkg/audit` Go module are **separate** version
-lines and are immutable once published. See `docs/RELEASE.md` for the inventory of already-used names
-and the process for cutting a new client/chart release. Do not move, delete, or reuse those tags.
+lines and are immutable once published. See `docs/RELEASE.md`. Do not move, delete, or reuse published
+tags. Install docs use `@latest` / the latest chart on GHCR so they do not need a rewrite every bump.
diff --git a/README.md b/README.md
index c055963..762ef74 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,7 @@
 
 ### Step 1: Add Argus to your project
 ```bash
-go get github.com/LSFLK/argus/pkg/audit@v0.1.0
+go get github.com/LSFLK/argus/pkg/audit@latest
 ```
 
 ### Step 2: Initialize the hardened audit client
@@ -69,7 +69,7 @@ Argus is designed to be the centralized audit source of truth for any microservi
 ### 1. Installation
 In your application:
 ```bash
-go get github.com/LSFLK/argus/pkg/audit@v0.1.0
+go get github.com/LSFLK/argus/pkg/audit@latest
 ```
 
 ### 2. Global Initialization
@@ -147,12 +147,11 @@ Argus exports standard Prometheus metrics at `/metrics`:
 
 ## Deployment & Helm Chart
 
-Argus provides an official Helm chart published as an **OCI Artifact** to GitHub Container Registry (`ghcr.io/lsflk/charts/argus`), as well as local chart source at [`deployments/helm/argus`](deployments/helm/argus). The application container image is published to `ghcr.io/lsflk/argus` (`:latest` and `:<git sha>`). Chart version `0.1.1` is the Helm package ([GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus)); it is not the Go client (`pkg/audit@v0.1.0`).
+Argus provides an official Helm chart published as an **OCI Artifact** to GitHub Container Registry (`ghcr.io/lsflk/charts/argus`), as well as local chart source at [`deployments/helm/argus`](deployments/helm/argus). The application container image is published to `ghcr.io/lsflk/argus` (`:latest` and `:<git sha>`). Chart versions and the Go client (`pkg/audit`) are versioned independently; omit `--version` to install the latest chart from [GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus).
 
 ### Install via OCI Artifact (Recommended)
 ```bash
 helm upgrade --install argus oci://ghcr.io/lsflk/charts/argus \
-  --version 0.1.1 \
   -n <your-namespace> \
   --create-namespace \
   -f custom-values.yaml
@@ -180,7 +179,7 @@ For full Helm configuration parameters, GitOps umbrella chart integration, and O
 - [API Reference](docs/API.md)
 - [Architecture Deep Dive](docs/ARCHITECTURE.md)
 - [Database Setup](docs/DATABASE_CONFIGURATION.md)
-- [Release process](docs/RELEASE.md) (published tags are listed there — do not reuse them)
+- [Release process](docs/RELEASE.md)
 
 ## License
 Distributed under the Apache 2.0 License. See [LICENSE](LICENSE) for more information.
diff --git a/deployments/helm/argus/README.md b/deployments/helm/argus/README.md
index 0d6e84a..6dfd3cd 100644
--- a/deployments/helm/argus/README.md
+++ b/deployments/helm/argus/README.md
@@ -25,18 +25,17 @@ This chart provisions:
 Argus Helm charts are published as OCI artifacts to the GitHub Container Registry (`ghcr.io`). 
 
 ```bash
-# Install directly from OCI registry
+# Install the latest published chart (omit --version). Pin --version only when you need a specific chart.
 helm upgrade --install argus oci://ghcr.io/lsflk/charts/argus \
-  --version 0.1.1 \
   --namespace <your-namespace> \
   --create-namespace \
   --values ./custom-values.yaml
 ```
 
-To pull the packaged chart locally:
+To pull the packaged chart locally (replace with a version from [GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus) if you need a pin):
 
 ```bash
-helm pull oci://ghcr.io/lsflk/charts/argus --version 0.1.1
+helm pull oci://ghcr.io/lsflk/charts/argus
 ```
 
 ### 2. Standalone Deployment from Source
@@ -57,7 +56,7 @@ When referencing Argus as a dependency in your umbrella chart (`Chart.yaml`):
 ```yaml
 dependencies:
   - name: argus
-    version: "0.1.1"
+    version: "x.y.z" # latest published chart: https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus
     repository: "oci://ghcr.io/lsflk/charts"
 ```
 
@@ -82,7 +81,7 @@ argus:
 
 The Helm chart automation follows a standard GitOps setup:
 - **Application image (`.github/workflows/build-image.yml`)**: Builds and pushes `ghcr.io/lsflk/argus` (`:<git sha>` and `:latest`) on pushes to `main`. PRs that touch Go code or the Dockerfile build the image without pushing. After the first publish, set the GHCR package visibility to public under https://github.com/orgs/LSFLK/packages so clusters can pull without an imagePullSecret.
-- **Dev Chart (`.github/workflows/build-dev-chart.yml`)**: On pushes to `main` with chart changes (or manual dispatch), packages and publishes a dev chart (`0.0.0-dev.<run_number>`) to `oci://ghcr.io/lsflk/charts`. After the image push completes, publish a **new** stable chart version by dispatching this workflow with an unpublished `version` (never reuse `0.1.1`). See [docs/RELEASE.md](../../../docs/RELEASE.md).
+- **Dev Chart (`.github/workflows/build-dev-chart.yml`)**: On pushes to `main` with chart changes (or manual dispatch), packages and publishes a dev chart (`0.0.0-dev.<run_number>`) to `oci://ghcr.io/lsflk/charts`. After the image push completes, publish a **new** stable chart by dispatching this workflow with a `version` that is not already on [GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus). See [docs/RELEASE.md](../../../docs/RELEASE.md).
 - **Chart CI (`.github/workflows/helm-ci.yml`)**: Lints the chart and verifies template rendering on pull requests.
 
 ### Manual Packaging and Push
@@ -97,7 +96,7 @@ helm package deployments/helm/argus -d .cr-release-packages/
 echo "$CR_PAT" | helm registry login ghcr.io -u <username> --password-stdin
 
 # 3. Push OCI artifact
-helm push .cr-release-packages/argus-0.1.1.tgz oci://ghcr.io/lsflk/charts
+helm push .cr-release-packages/argus-*.tgz oci://ghcr.io/lsflk/charts
 ```
 
 ---
diff --git a/docs/API.md b/docs/API.md
index e674ace..6f07895 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -192,7 +192,7 @@ curl http://localhost:3001/version
 ```json
 {
   "service": "argus",
-  "version": "0.1.0",
+  "version": "dev",
   "buildTime": "2024-01-20T10:00:00Z",
   "gitCommit": "abc123def456"
 }
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index fda184a..93ec0d1 100644
--- a/docs/RELEASE.md
+++ b/docs/RELEASE.md
@@ -1,118 +1,86 @@
 # Release process
 
-Published versions are **immutable**. Do not delete, move, retarget, or reuse a tag, GitHub Release, Helm chart version, or container digest that has already been pushed. Go’s module proxy (`proxy.golang.org`) and checksum database (`sum.golang.org`) keep module versions even if the GitHub tag is later removed.
+Published versions are **immutable**. Do not delete, move, retarget, force-push, or reuse a git tag, GitHub Release, Helm chart version, or container digest that has already been pushed. Go’s module proxy (`proxy.golang.org`) and checksum database (`sum.golang.org`) keep module versions even if the GitHub tag is later removed.
 
-**`0.1.1` is the Helm chart, not the Go client.** They are not typos for each other:
+Look up what already exists instead of copying numbers out of this file:
 
-| Artifact | Current version | Where |
-| --- | --- | --- |
-| Go client (`pkg/audit`) | `v0.1.0` | [GitHub Release](https://github.com/LSFLK/argus/releases/tag/pkg/audit/v0.1.0) (`go get …@v0.1.0`) |
-| Helm chart | `0.1.1` | [GHCR `charts/argus`](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus) (`helm … --version 0.1.1`) |
-
-Argus has **four independent version lines**. A number used in one line does not free it in another.
-
-| Line | Identity | How it is published |
-| --- | --- | --- |
-| Root git tags | `github.com/LSFLK/argus` | `vX.Y.Z` git tags. Other services should not import this module. |
-| Client module | `github.com/LSFLK/argus/pkg/audit` | Nested tags `pkg/audit/vX.Y.Z` (required for a module in a subdirectory). This is what `go get` consumes. The GitHub Release title may be `v0.1.0`; the git tag is still `pkg/audit/v0.1.0`. |
-| Helm chart | `oci://ghcr.io/lsflk/charts/argus` | Chart `version` in `deployments/helm/argus/Chart.yaml`. OCI versions cannot be overwritten. |
-| App image | `ghcr.io/lsflk/argus` | `:latest` (mutable) and `:<git sha>` only. There are no semver image tags. |
-
-## Already published — do not reuse
-
-These names are taken. Never create a new release, tag, or chart that recycles them.
-
-### Git tags
-
-| Tag | Points at | Status |
-| --- | --- | --- |
-| `v0.1.0` | Initial repo (`787b047`) | Root-module tag. Leave as-is. Do not move onto a later commit. |
-| `v1.0.0` | JSONB work (`61371c4`) | Root-module tag. Do not move or delete. |
-| `v1.0.1` | Client utilities (`2512797`) | Root-module tag. Do not move or delete. |
-| `pkg/audit/v1.0.0` | `85d5ea5` | **Retracted** Go client. Cached by the module proxy and checksum DB. Do not move, delete, or `gh release delete --cleanup-tag`. |
-| `pkg/audit/v1.0.1` | retract commit | Retract-announcement only (itself retracted). Not a usable 1.x client. |
-| `pkg/audit/v0.1.0` | retract commit | **Current Go client.** Pin this. A later client patch would be `pkg/audit/v0.1.1` (unrelated to Helm chart `0.1.1`). |
-
-Root `v0.1.0` and client `pkg/audit/v0.1.0` are different tags. Do not retarget the root tag to “match” the client.
-
-### GitHub Releases
-
-| Release | Tag | Status |
-| --- | --- | --- |
-| `[RETRACTED] pkg/audit v1.0.0` | `pkg/audit/v1.0.0` | Retracted. Notes point at `v0.1.0`. Do not delete. |
-| `v0.1.0` | `pkg/audit/v0.1.0` | Current client release. |
+| Line | How to see published names |
+| --- | --- |
+| Git tags | `git tag -l` / `git ls-remote --tags origin` |
+| GitHub Releases | https://github.com/LSFLK/argus/releases |
+| Helm chart | https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus |
+| App image | `ghcr.io/lsflk/argus` (`:latest` and `:<git sha>` only) |
 
-Do not backfill GitHub Releases onto root tags `v0.1.0` / `v1.0.0` / `v1.0.1`.
+## Four independent version lines
 
-### Helm
+A number used in one line does not occupy that number in another. Client `v0.1.0`, root tag `v0.1.0`, and Helm `0.1.1` can all exist without matching.
 
-| Chart version | Registry | Status |
+| Line | Identity | How it is published |
 | --- | --- | --- |
-| `0.1.1` | [`oci://ghcr.io/lsflk/charts/argus`](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus) | **Current Helm chart.** Published. Do not `helm push` this version again. Next chart is `0.1.2` or higher. |
+| Root git tags | `github.com/LSFLK/argus` | `vX.Y.Z`. Other services should not import this module. |
+| Client module | `github.com/LSFLK/argus/pkg/audit` | Nested tags `pkg/audit/vX.Y.Z`. This is what `go get` consumes. The GitHub Release title can be `vX.Y.Z`; the git tag is still `pkg/audit/vX.Y.Z`. |
+| Helm chart | `oci://ghcr.io/lsflk/charts/argus` | `version` in `deployments/helm/argus/Chart.yaml`. OCI versions cannot be overwritten. |
+| App image | `ghcr.io/lsflk/argus` | `:latest` (mutable) and `:<git sha>`. Do not invent semver image tags. |
 
-`Chart.yaml` `appVersion` is metadata only and must not be “fixed” by republishing `0.1.1`.
+Install docs should track **latest**, not a snapshot of today’s numbers:
 
-### Container images
+```bash
+go get github.com/LSFLK/argus/pkg/audit@latest
+helm upgrade --install argus oci://ghcr.io/lsflk/charts/argus
+```
 
-Images are `ghcr.io/lsflk/argus:<git sha>` and `:latest`. Do not invent `:1.0.0` / `:0.1.0` tags for old SHAs.
+`@latest` skips versions listed in `retract` in `pkg/audit/go.mod`. Pinning a retracted version (for example `@v1.0.0`) still works; that is intentional.
 
-## Current policy
+## Policy
 
-The **product and client** stay on **0.x** until the team agrees a stable 1.0. Breaking changes on 0.x bump the minor (`0.1.0` → `0.2.0`). Client `v1.0.0` stays published and is **retracted** in `pkg/audit/go.mod` so `go get @latest` selects `v0.1.0`.
+Stay on **0.x** until the team agrees a stable 1.0. On 0.x, breaking changes bump the minor. After a real 1.0, breaking changes bump the major.
 
-`retract` does not unpublish a version. Pinning `@v1.0.0` still works. That is intentional.
+To stop the toolchain from *selecting* a bad module version, add `retract` and ship a new tag. To warn humans, edit the GitHub Release notes. Do both; neither replaces the other. Do not `gh release delete --cleanup-tag` a published module version.
 
 ## Cutting a client release (`pkg/audit`)
 
-1. Land the change on `main`. Do not retarget an old tag.
-2. Tag `pkg/audit/vX.Y.Z` on that commit. Never reuse a tag from the table above.
-3. Push the new tag (`git push origin <tag>`). Do not `--force` tags.
-4. `gh release create 'pkg/audit/vX.Y.Z' --title 'vX.Y.Z' --notes '...'`
-
-Annotated tags, nested-module name (example of a later client patch — not the Helm chart):
+1. Land the change on `main`. Run `go test ./...`.
+2. Choose the next SemVer that does **not** already exist as `pkg/audit/vX.Y.Z`.
+3. Tag and push (no `--force`):
 
 ```bash
-git tag -a pkg/audit/v0.1.1 -m "pkg/audit v0.1.1"
-git push origin pkg/audit/v0.1.1
+git tag -a pkg/audit/vX.Y.Z -m "pkg/audit vX.Y.Z"
+git push origin pkg/audit/vX.Y.Z
+gh release create "pkg/audit/vX.Y.Z" --title "vX.Y.Z" --notes "..."
 ```
 
-Consumers:
-
-```bash
-go get github.com/LSFLK/argus/pkg/audit@v0.1.0
-```
-
-This repo uses `replace github.com/LSFLK/argus/pkg/audit => ./pkg/audit` so service builds do not wait on the proxy.
+This repo may `replace github.com/LSFLK/argus/pkg/audit => ./pkg/audit` so service builds do not wait on the proxy. Tags do not trigger image or chart workflows.
 
 ## Cutting a Helm chart release
 
-1. Bump `deployments/helm/argus/Chart.yaml` `version` to a **new** number (never `0.1.1` again).
-2. Merge to `main` or dispatch [build-dev-chart.yml](../.github/workflows/build-dev-chart.yml) with that version.
+1. Bump `deployments/helm/argus/Chart.yaml` `version` to a number that is **not** already on [GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus). Never republish an existing chart version (including to “fix” `appVersion`).
+2. Merge to `main`, or dispatch [build-dev-chart.yml](../.github/workflows/build-dev-chart.yml) with that unpublished `version`.
 3. A path-only change under `deployments/helm/` on `main` publishes `0.0.0-dev.<run_number>`, not a stable chart. That is expected.
 
-## What CI does (and does not)
-
-No workflow runs on git tags or GitHub Releases today. Tagging `pkg/audit/v0.1.0` does not publish an image or chart by itself.
+## What CI does
 
 | Workflow | Trigger | Effect |
 | --- | --- | --- |
 | `build-image.yml` | Push/PR to `main` touching Go/Dockerfile paths | PR: build only. `main`: push `:sha` and retag `:latest`. |
-| `build-dev-chart.yml` | Push to `main` touching `deployments/helm/**`, or manual dispatch | Packages a chart. Empty input → `0.0.0-dev.<run_number>`. Dispatching an **already published** chart version will fail (OCI immutable). |
+| `build-dev-chart.yml` | Push to `main` touching `deployments/helm/**`, or manual dispatch | Empty input → `0.0.0-dev.<run_number>`. An already-published chart version will fail (OCI immutable). |
 | `helm-ci.yml` | PRs touching the chart | Lint/template only. |
 
-There is no Go test workflow. Run `go test ./...` locally before tagging.
+There is no Go test workflow. No workflow runs on git tags or GitHub Releases.
+
+## Frozen history (do not rewrite)
 
-## Commands that are not allowed
+These names are already out. Leave them; do not retarget or delete.
+
+- Root tags `v0.1.0`, `v1.0.0`, `v1.0.1` — do not backfill GitHub Releases onto them. Root `v0.1.0` is not the Go client.
+- `pkg/audit/v1.0.0` — published client, **retracted**. Cached by the module proxy. GitHub Release is marked retracted.
+- `pkg/audit/v1.0.1` — retract-announcement tag only (itself retracted). Not a usable 1.x client.
 
 ```bash
-# Do not — does not unpublish the Go module, and may delete the wrong tag.
+# Do not.
 gh release delete v1.0.0 --cleanup-tag
 gh release delete 'pkg/audit/v1.0.0' --cleanup-tag
-
 git tag -d v0.1.0
 git push origin :refs/tags/v0.1.0
 git tag -f v0.1.0
 git tag -f pkg/audit/v0.1.0
 ```
-
-To stop the toolchain from *selecting* a bad module version, add `retract` and ship a new tag. To warn humans, edit the GitHub Release notes. Do both; neither replaces the other.
diff --git a/pkg/audit/go.mod b/pkg/audit/go.mod
index bd776b3..dd1786e 100644
--- a/pkg/audit/go.mod
+++ b/pkg/audit/go.mod
@@ -7,7 +7,7 @@ go 1.24.6
 // sum.golang.org already cached it.
 // v1.0.1 exists only so the go command can discover these retract
 // directives (it reads them from the highest release, even if retracted).
-// Consumers should pin v0.1.0 (git tag pkg/audit/v0.1.0).
+// Consumers should use a 0.x tag (`go get …@latest` skips retracted 1.x).
 retract (
 	v1.0.0
 	v1.0.1

From b19e3a8b094b9deb3b8e00b57fa2111b558bbfc0 Mon Sep 17 00:00:00 2001
From: Your Name <regina.xu1@gmail.com>
Date: Tue, 15 Sep 2026 13:39:06 +0530
Subject: [PATCH 4/6] Point version lookups at GitHub Releases instead of
 hardcoded numbers.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 CLAUDE.md                        |  4 ++--
 README.md                        |  4 +++-
 deployments/helm/argus/README.md |  6 +++---
 docs/RELEASE.md                  | 11 ++---------
 4 files changed, 10 insertions(+), 15 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index d40a74f..b807fca 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -46,7 +46,7 @@ sidecar). By default (no `DB_TYPE`/`DB_PATH` set) the service uses an in-memory
 ### Two audiences, two packages
 
 - **`internal/`** — the Argus *service* itself (API, DB, pipeline). Not importable by other projects.
-- **`pkg/audit`** — the *client library* other Go services import (`go get github.com/LSFLK/argus/pkg/audit@latest`). Pin the resolved tag in `go.mod`; do not use retracted 1.x versions or commit pseudo-versions.
+- **`pkg/audit`** — the *client library* other Go services import (`go get github.com/LSFLK/argus/pkg/audit@latest`). See [Releases](https://github.com/LSFLK/argus/releases) for tags. Pin the resolved tag in `go.mod`; do not use retracted 1.x versions or commit pseudo-versions.
   to send audit events to a running Argus instance. This is a separate logical module from the service;
   don't leak service-internal types into it, and don't assume service-side dependencies (GORM, sinks) are
   available here. `pkg/audit/security.go` implements client-side request signing (RSA/Ed25519) that mirrors
@@ -123,4 +123,4 @@ live alongside `v1` as a new package tree, mirroring the same handlers/services/
 
 Git tags, GitHub Releases, Helm chart versions, and the `pkg/audit` Go module are **separate** version
 lines and are immutable once published. See `docs/RELEASE.md`. Do not move, delete, or reuse published
-tags. Install docs use `@latest` / the latest chart on GHCR so they do not need a rewrite every bump.
+tags. Install docs use `@latest` and [Releases](https://github.com/LSFLK/argus/releases) so they do not need a rewrite every bump.
diff --git a/README.md b/README.md
index 762ef74..456d5ed 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,7 @@
 ```bash
 go get github.com/LSFLK/argus/pkg/audit@latest
 ```
+Current tags are listed at [github.com/LSFLK/argus/releases](https://github.com/LSFLK/argus/releases).
 
 ### Step 2: Initialize the hardened audit client
 ```go
@@ -71,6 +72,7 @@ In your application:
 ```bash
 go get github.com/LSFLK/argus/pkg/audit@latest
 ```
+See [Releases](https://github.com/LSFLK/argus/releases) for tagged versions.
 
 ### 2. Global Initialization
 Initialize the client in your main entry point. For high-scale systems, tune the batching settings to balance latency and throughput.
@@ -147,7 +149,7 @@ Argus exports standard Prometheus metrics at `/metrics`:
 
 ## Deployment & Helm Chart
 
-Argus provides an official Helm chart published as an **OCI Artifact** to GitHub Container Registry (`ghcr.io/lsflk/charts/argus`), as well as local chart source at [`deployments/helm/argus`](deployments/helm/argus). The application container image is published to `ghcr.io/lsflk/argus` (`:latest` and `:<git sha>`). Chart versions and the Go client (`pkg/audit`) are versioned independently; omit `--version` to install the latest chart from [GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus).
+Argus provides an official Helm chart published as an **OCI Artifact** to GitHub Container Registry (`ghcr.io/lsflk/charts/argus`), as well as local chart source at [`deployments/helm/argus`](deployments/helm/argus). The application container image is published to `ghcr.io/lsflk/argus` (`:latest` and `:<git sha>`). Chart versions and the Go client (`pkg/audit`) are versioned independently. Check [Releases](https://github.com/LSFLK/argus/releases) for current tags; omit `--version` to install the latest chart.
 
 ### Install via OCI Artifact (Recommended)
 ```bash
diff --git a/deployments/helm/argus/README.md b/deployments/helm/argus/README.md
index 6dfd3cd..2082b8e 100644
--- a/deployments/helm/argus/README.md
+++ b/deployments/helm/argus/README.md
@@ -22,7 +22,7 @@ This chart provisions:
 
 ### 1. Install via OCI Artifact (Recommended)
 
-Argus Helm charts are published as OCI artifacts to the GitHub Container Registry (`ghcr.io`). 
+Argus Helm charts are published as OCI artifacts to the GitHub Container Registry (`ghcr.io`). Check [Releases](https://github.com/LSFLK/argus/releases) for current tags.
 
 ```bash
 # Install the latest published chart (omit --version). Pin --version only when you need a specific chart.
@@ -32,7 +32,7 @@ helm upgrade --install argus oci://ghcr.io/lsflk/charts/argus \
   --values ./custom-values.yaml
 ```
 
-To pull the packaged chart locally (replace with a version from [GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus) if you need a pin):
+To pull the packaged chart locally (pin `--version` from [Releases](https://github.com/LSFLK/argus/releases) if you need a specific chart):
 
 ```bash
 helm pull oci://ghcr.io/lsflk/charts/argus
@@ -56,7 +56,7 @@ When referencing Argus as a dependency in your umbrella chart (`Chart.yaml`):
 ```yaml
 dependencies:
   - name: argus
-    version: "x.y.z" # latest published chart: https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus
+    version: "x.y.z" # https://github.com/LSFLK/argus/releases
     repository: "oci://ghcr.io/lsflk/charts"
 ```
 
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index 93ec0d1..35a4dff 100644
--- a/docs/RELEASE.md
+++ b/docs/RELEASE.md
@@ -2,14 +2,7 @@
 
 Published versions are **immutable**. Do not delete, move, retarget, force-push, or reuse a git tag, GitHub Release, Helm chart version, or container digest that has already been pushed. Go’s module proxy (`proxy.golang.org`) and checksum database (`sum.golang.org`) keep module versions even if the GitHub tag is later removed.
 
-Look up what already exists instead of copying numbers out of this file:
-
-| Line | How to see published names |
-| --- | --- |
-| Git tags | `git tag -l` / `git ls-remote --tags origin` |
-| GitHub Releases | https://github.com/LSFLK/argus/releases |
-| Helm chart | https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus |
-| App image | `ghcr.io/lsflk/argus` (`:latest` and `:<git sha>` only) |
+Look up what already exists at [github.com/LSFLK/argus/releases](https://github.com/LSFLK/argus/releases) instead of copying numbers out of this file. Git tags (`git tag -l`), the [Helm package on GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus), and `ghcr.io/lsflk/argus` (`:latest` / `:<git sha>`) are the other sources of truth.
 
 ## Four independent version lines
 
@@ -22,7 +15,7 @@ A number used in one line does not occupy that number in another. Client `v0.1.0
 | Helm chart | `oci://ghcr.io/lsflk/charts/argus` | `version` in `deployments/helm/argus/Chart.yaml`. OCI versions cannot be overwritten. |
 | App image | `ghcr.io/lsflk/argus` | `:latest` (mutable) and `:<git sha>`. Do not invent semver image tags. |
 
-Install docs should track **latest**, not a snapshot of today’s numbers:
+Install docs should track **latest**, not a snapshot of today’s numbers. See [Releases](https://github.com/LSFLK/argus/releases) for current tags.
 
 ```bash
 go get github.com/LSFLK/argus/pkg/audit@latest

From c8e97c209d2c5d751ceaf55b38cd5c1cc9e6ca33 Mon Sep 17 00:00:00 2001
From: Your Name <regina.xu1@gmail.com>
Date: Tue, 15 Sep 2026 15:44:39 +0530
Subject: [PATCH 5/6] List published tags as a denylist so they are never
 reused.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 CLAUDE.md                        |  5 +++--
 README.md                        |  2 +-
 deployments/helm/argus/README.md |  2 +-
 docs/RELEASE.md                  | 31 ++++++++++++++++++++++---------
 4 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index b807fca..afa717e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -122,5 +122,6 @@ The API is versioned by Go package path (`internal/api/v1/...`), not just by URL
 live alongside `v1` as a new package tree, mirroring the same handlers/services/models/database layers.
 
 Git tags, GitHub Releases, Helm chart versions, and the `pkg/audit` Go module are **separate** version
-lines and are immutable once published. See `docs/RELEASE.md`. Do not move, delete, or reuse published
-tags. Install docs use `@latest` and [Releases](https://github.com/LSFLK/argus/releases) so they do not need a rewrite every bump.
+lines and are immutable once published. See `docs/RELEASE.md` (taken-name denylist). Do not move,
+delete, or reuse those tags. Install docs use `@latest` and [Releases](https://github.com/LSFLK/argus/releases)
+so they do not need a rewrite every bump.
diff --git a/README.md b/README.md
index 456d5ed..e97b397 100644
--- a/README.md
+++ b/README.md
@@ -181,7 +181,7 @@ For full Helm configuration parameters, GitOps umbrella chart integration, and O
 - [API Reference](docs/API.md)
 - [Architecture Deep Dive](docs/ARCHITECTURE.md)
 - [Database Setup](docs/DATABASE_CONFIGURATION.md)
-- [Release process](docs/RELEASE.md)
+- [Release process](docs/RELEASE.md) (includes a denylist of tags you must not reuse)
 
 ## License
 Distributed under the Apache 2.0 License. See [LICENSE](LICENSE) for more information.
diff --git a/deployments/helm/argus/README.md b/deployments/helm/argus/README.md
index 2082b8e..c128d38 100644
--- a/deployments/helm/argus/README.md
+++ b/deployments/helm/argus/README.md
@@ -81,7 +81,7 @@ argus:
 
 The Helm chart automation follows a standard GitOps setup:
 - **Application image (`.github/workflows/build-image.yml`)**: Builds and pushes `ghcr.io/lsflk/argus` (`:<git sha>` and `:latest`) on pushes to `main`. PRs that touch Go code or the Dockerfile build the image without pushing. After the first publish, set the GHCR package visibility to public under https://github.com/orgs/LSFLK/packages so clusters can pull without an imagePullSecret.
-- **Dev Chart (`.github/workflows/build-dev-chart.yml`)**: On pushes to `main` with chart changes (or manual dispatch), packages and publishes a dev chart (`0.0.0-dev.<run_number>`) to `oci://ghcr.io/lsflk/charts`. After the image push completes, publish a **new** stable chart by dispatching this workflow with a `version` that is not already on [GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus). See [docs/RELEASE.md](../../../docs/RELEASE.md).
+- **Dev Chart (`.github/workflows/build-dev-chart.yml`)**: On pushes to `main` with chart changes (or manual dispatch), packages and publishes a dev chart (`0.0.0-dev.<run_number>`) to `oci://ghcr.io/lsflk/charts`. After the image push completes, publish a **new** stable chart by dispatching this workflow with a `version` that is not already on [GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus) or in the [taken-names denylist](../../../docs/RELEASE.md#taken-names--never-reuse).
 - **Chart CI (`.github/workflows/helm-ci.yml`)**: Lints the chart and verifies template rendering on pull requests.
 
 ### Manual Packaging and Push
diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index 35a4dff..ddb9daf 100644
--- a/docs/RELEASE.md
+++ b/docs/RELEASE.md
@@ -33,8 +33,8 @@ To stop the toolchain from *selecting* a bad module version, add `retract` and s
 ## Cutting a client release (`pkg/audit`)
 
 1. Land the change on `main`. Run `go test ./...`.
-2. Choose the next SemVer that does **not** already exist as `pkg/audit/vX.Y.Z`.
-3. Tag and push (no `--force`):
+2. Choose the next SemVer that does **not** already exist as `pkg/audit/vX.Y.Z` (`git tag -l 'pkg/audit/v*'` and the [Taken names](#taken-names--never-reuse) table).
+3. Tag and push (no `--force`). Append the new tag to [Taken names](#taken-names--never-reuse).
 
 ```bash
 git tag -a pkg/audit/vX.Y.Z -m "pkg/audit vX.Y.Z"
@@ -46,8 +46,8 @@ This repo may `replace github.com/LSFLK/argus/pkg/audit => ./pkg/audit` so servi
 
 ## Cutting a Helm chart release
 
-1. Bump `deployments/helm/argus/Chart.yaml` `version` to a number that is **not** already on [GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus). Never republish an existing chart version (including to “fix” `appVersion`).
-2. Merge to `main`, or dispatch [build-dev-chart.yml](../.github/workflows/build-dev-chart.yml) with that unpublished `version`.
+1. Bump `deployments/helm/argus/Chart.yaml` `version` to a number that is **not** already on [GHCR](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus) or in [Taken names](#taken-names--never-reuse). Never republish an existing chart version (including to “fix” `appVersion`).
+2. Merge to `main`, or dispatch [build-dev-chart.yml](../.github/workflows/build-dev-chart.yml) with that unpublished `version`. Append the new chart version to [Taken names](#taken-names--never-reuse).
 3. A path-only change under `deployments/helm/` on `main` publishes `0.0.0-dev.<run_number>`, not a stable chart. That is expected.
 
 ## What CI does
@@ -60,13 +60,26 @@ This repo may `replace github.com/LSFLK/argus/pkg/audit => ./pkg/audit` so servi
 
 There is no Go test workflow. No workflow runs on git tags or GitHub Releases.
 
-## Frozen history (do not rewrite)
+## Taken names — never reuse
 
-These names are already out. Leave them; do not retarget or delete.
+This is a **denylist**, not “what to install” (that is always [Releases](https://github.com/LSFLK/argus/releases) / `@latest`). Before tagging, run `git tag -l` and confirm the name is absent here **and** on origin. Append a row when you publish a new name. Never retarget, delete, or `gh release delete --cleanup-tag` a row that is already here.
 
-- Root tags `v0.1.0`, `v1.0.0`, `v1.0.1` — do not backfill GitHub Releases onto them. Root `v0.1.0` is not the Go client.
-- `pkg/audit/v1.0.0` — published client, **retracted**. Cached by the module proxy. GitHub Release is marked retracted.
-- `pkg/audit/v1.0.1` — retract-announcement tag only (itself retracted). Not a usable 1.x client.
+### Git tags
+
+| Tag | Notes |
+| --- | --- |
+| `v0.1.0` | Root module. Initial repo. Not the Go client. Do not backfill a GitHub Release onto this tag. |
+| `v1.0.0` | Root module. Do not move or delete. |
+| `v1.0.1` | Root module. Do not move or delete. |
+| `pkg/audit/v1.0.0` | Go client. **Retracted.** Cached by the module proxy and checksum DB. GitHub Release is marked retracted. |
+| `pkg/audit/v1.0.1` | Retract-announcement only (itself retracted). Not a usable 1.x client. |
+| `pkg/audit/v0.1.0` | Go client. GitHub Release title is `v0.1.0`; git tag is `pkg/audit/v0.1.0`. Distinct from root `v0.1.0`. |
+
+### Helm chart (GHCR)
+
+| Chart version | Notes |
+| --- | --- |
+| `0.1.1` | [`oci://ghcr.io/lsflk/charts/argus`](https://github.com/LSFLK/argus/pkgs/container/charts%2Fargus). Do not `helm push` this version again. |
 
 ```bash
 # Do not.

From ad45309706c6a4c37de60ee98b761ab9a20cf023 Mon Sep 17 00:00:00 2001
From: Your Name <regina.xu1@gmail.com>
Date: Wed, 16 Sep 2026 14:12:39 +0530
Subject: [PATCH 6/6] Drop the pkg/audit replace now that v0.1.0 is published.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/RELEASE.md | 2 +-
 go.mod          | 2 --
 go.sum          | 2 ++
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/RELEASE.md b/docs/RELEASE.md
index ddb9daf..c754b80 100644
--- a/docs/RELEASE.md
+++ b/docs/RELEASE.md
@@ -42,7 +42,7 @@ git push origin pkg/audit/vX.Y.Z
 gh release create "pkg/audit/vX.Y.Z" --title "vX.Y.Z" --notes "..."
 ```
 
-This repo may `replace github.com/LSFLK/argus/pkg/audit => ./pkg/audit` so service builds do not wait on the proxy. Tags do not trigger image or chart workflows.
+Tags do not trigger image or chart workflows.
 
 ## Cutting a Helm chart release
 
diff --git a/go.mod b/go.mod
index f211ea1..c9863e2 100644
--- a/go.mod
+++ b/go.mod
@@ -56,5 +56,3 @@ require (
 	golang.org/x/text v0.28.0 // indirect
 	google.golang.org/protobuf v1.36.8 // indirect
 )
-
-replace github.com/LSFLK/argus/pkg/audit => ./pkg/audit
diff --git a/go.sum b/go.sum
index e0a22e7..b4c0899 100644
--- a/go.sum
+++ b/go.sum
@@ -1,3 +1,5 @@
+github.com/LSFLK/argus/pkg/audit v0.1.0 h1:UjPm6Bsa0r/4mi9XtN2Q8lHsBrQmboyxuOLoYanTnao=
+github.com/LSFLK/argus/pkg/audit v0.1.0/go.mod h1:4VVVpK0P7nFEQLP+QU44rezK+Ds9PzE42ZyKw07abl0=
 github.com/aws/aws-sdk-go-v2 v1.41.7 h1:DWpAJt66FmnnaRIOT/8ASTucrvuDPZASqhhLey6tLY8=
 github.com/aws/aws-sdk-go-v2 v1.41.7/go.mod h1:4LAfZOPHNVNQEckOACQx60Y8pSRjIkNZQz1w92xpMJc=
 github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.10 h1:gx1AwW1Iyk9Z9dD9F4akX5gnN3QZwUB20GGKH/I+Rho=