refactor(docs)!: rename CLI binary to corestack-docs

go install names binaries after the directory, so cmd/docs installed an
ambiguous `docs` binary into $GOBIN that could clobber or be clobbered
by other tools. Move it to cmd/corestack-docs, matching corestack-goose,
and update goreleaser, CI, docs and usage text. Accepted ADRs keep their
text and gain a dated rename note.

BREAKING CHANGE: `go install go.auvem.com/corestack/cmd/docs@latest`
stops resolving after the next tag; use cmd/corestack-docs. @v0.1.0
still installs the old `docs` binary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.gitea/workflows/docs-check.yml

@@ -12,4 +12,4 @@ jobs:
         with:
           go-version-file: go.mod
           cache: false
-      - run: go run ./cmd/docs check
+      - run: go run ./cmd/corestack-docs check

.goreleaser.yaml

@@ -1,10 +1,10 @@
 version: 2
-project_name: docs
+project_name: corestack-docs
 
 builds:
-  - id: docs
-    main: ./cmd/docs
-    binary: docs
+  - id: corestack-docs
+    main: ./cmd/corestack-docs
+    binary: corestack-docs
     env:
       - CGO_ENABLED=0
     goos: [darwin, linux]
@@ -14,7 +14,7 @@ builds:
 
 archives:
   - formats: [tar.gz]
-    name_template: "docs_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    name_template: "corestack-docs_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
 
 checksum:
   name_template: checksums.txt

AGENTS.md

@@ -3,7 +3,7 @@
 ## Commands
 - Check: `go build ./...`, `go vet ./...`, `go test -race ./...`, `go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.15.0 run ./...`; from the project root, run the TODO check below.
 - Generate: No code generation is configured; format with `gofmt -w .`.
-- Documentation: `go run ./cmd/docs check`; create records with `go run ./cmd/docs new adr|plan "Title"`. This checker repository uses its local implementation as the source of truth.
+- Documentation: `go run ./cmd/corestack-docs check`; create records with `go run ./cmd/corestack-docs new adr|plan "Title"`. This checker repository uses its local implementation as the source of truth.
 
 ## Scope and decisions
 - Before editing under a directory with its own AGENTS.md, read it. Scoped files: none currently; this root governs the repository, including nested Go modules unless nearer instructions override it.
@@ -28,7 +28,7 @@
 
 Go module `go.auvem.com/corestack`.
 
-- Docs format (the spec `docs check` implements): `docs/docs-format.md`.
+- Docs format (the spec `corestack-docs check` implements): `docs/docs-format.md`.
 - Decisions live in `docs/adr/`, plans in `docs/plans/`. Records are permanent; never rename them.
 - Add dependencies only to the module that needs them; heavy dependencies go in nested modules (see the [module-boundary ADR](/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md)).
 

README.md

@@ -1,26 +1,26 @@
 # corestack go
 
-Shared Go building blocks. Includes `docs`, a checker for architecture decision records (ADRs) and implementation plans; `page`, Bob keyset pagination; and `lifecycle`, a service and worker coordinator.
+Shared Go building blocks. Includes `corestack-docs`, a checker for architecture decision records (ADRs) and implementation plans; `page`, Bob keyset pagination; and `lifecycle`, a service and worker coordinator.
 
 ## migrate
 
 [`migrate`](migrate/README.md) configures Goose providers for embedded SQL and Go
 migrations, with structured logging and Postgres startup locking.
 
-## docs
+## corestack-docs
 
 Install:
 
 ```sh
-go install go.auvem.com/corestack/cmd/docs@latest
+go install go.auvem.com/corestack/cmd/corestack-docs@latest
 ```
 
 Use, from a repository root:
 
 ```sh
-docs new adr "Use Example Queue for background jobs"   # creates docs/adr/<id>.md
-docs new plan "Adopt Example Queue"                    # creates docs/plans/<id>.md
-docs check [--root DIR]                                # prints path:line: message; exit 1 on problems
+corestack-docs new adr "Use Example Queue for background jobs"   # creates docs/adr/<id>.md
+corestack-docs new plan "Adopt Example Queue"                    # creates docs/plans/<id>.md
+corestack-docs check [--root DIR]                                # prints path:line: message; exit 1 on problems
 ```
 
 The format is specified in [docs/docs-format.md](docs/docs-format.md); that document is the complete rule set. Exit status is `0` when every record is valid, `1` when problems are reported and `2` for usage errors.

cmd/corestack-docs/main.go

@@ -1,4 +1,4 @@
-// Command docs creates and checks ADR and plan records. See docs/docs-format.md.
+// Command corestack-docs creates and checks ADR and plan records. See docs/docs-format.md.
 package main
 
 import (
@@ -12,8 +12,8 @@ import (
 )
 
 const usage = `usage:
-  docs new adr|plan "Title"
-  docs check [--root DIR]
+  corestack-docs new adr|plan "Title"
+  corestack-docs check [--root DIR]
 `
 
 func main() { os.Exit(run(os.Args[1:], os.Stdout, os.Stderr, time.Now())) }
@@ -32,13 +32,13 @@ func run(args []string, stdout, stderr io.Writer, now time.Time) int {
 		}
 		path, err := docs.New(".", args[1], args[2], now)
 		if err != nil {
-			fmt.Fprintf(stderr, "docs: %v\n", err)
+			fmt.Fprintf(stderr, "corestack-docs: %v\n", err)
 			return 1
 		}
 		fmt.Fprintln(stdout, path)
 		return 0
 	case "check":
-		fs := flag.NewFlagSet("docs check", flag.ContinueOnError)
+		fs := flag.NewFlagSet("corestack-docs check", flag.ContinueOnError)
 		fs.SetOutput(stderr)
 		root := fs.String("root", ".", "repository root")
 		if err := fs.Parse(args[1:]); err != nil || fs.NArg() != 0 {
@@ -49,7 +49,7 @@ func run(args []string, stdout, stderr io.Writer, now time.Time) int {
 		}
 		res, err := docs.Check(*root)
 		if err != nil {
-			fmt.Fprintf(stderr, "docs: %v\n", err)
+			fmt.Fprintf(stderr, "corestack-docs: %v\n", err)
 			return 1
 		}
 		for _, p := range res.Problems {

docs/adr/20261023T214738672Z-adopt-a-checked-format-for-adrs-and-implementation-plans.md

@@ -80,3 +80,5 @@ The format is specified in [docs-format](/docs/docs-format.md). It uses the MADR
 ## More Information
 
 MADR 4: https://adr.github.io/madr/. The specification is [docs-format](/docs/docs-format.md); the implementation lands in the same pull request that records this decision.
+
+Note (2026-10-28): the CLI was renamed from `docs` (`cmd/docs`) to `corestack-docs` (`cmd/corestack-docs`) so `go install` does not produce an ambiguous `docs` binary. The decision is unchanged.

docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md

@@ -49,3 +49,7 @@ This decision establishes the boundary before the planned packages are added. Th
 * Heavy-dependency and independently versioned packages avoid overlapping ownership of an import path with older root-module versions.
 * Each nested module needs its own dependency maintenance, checks, and prefixed release tags. That bookkeeping is reserved for packages that need the boundary.
 * Root-module consumers share version bumps even when only another core package changes. Moving a shipped root package into a nested module later still requires coordinated releases and consumer upgrades.
+
+## More Information
+
+Note (2026-10-28): `cmd/docs` was renamed to `cmd/corestack-docs`; read references to `cmd/docs` above as `cmd/corestack-docs`. The decision is unchanged.

docs/adr/README.md

@@ -26,4 +26,4 @@ Use `write-adr` and `review-adr` when available: they guide reasoning while defe
 
 ## Reconcile before final review and merge
 
-Compare the latest target branch plus the PR with the affected decisions and plans, not just the working branch's previous metadata. Update ADR implementation state and `implemented_by` with the real PR URL when delivery evidence supports it. Close finished plans with completion evidence and an Outcome; keep work active when scope remains. Never invent PR links, completed checks, owner acceptance, or delivery evidence. Run `docs check` using the pinned documentation command in the root AGENTS.md after reconciliation.
+Compare the latest target branch plus the PR with the affected decisions and plans, not just the working branch's previous metadata. Update ADR implementation state and `implemented_by` with the real PR URL when delivery evidence supports it. Close finished plans with completion evidence and an Outcome; keep work active when scope remains. Never invent PR links, completed checks, owner acceptance, or delivery evidence. Run `corestack-docs check` using the pinned documentation command in the root AGENTS.md after reconciliation.

docs/docs-format.md

@@ -1,6 +1,6 @@
 # Docs format
 
-This is the complete specification for architecture decision records (ADRs) and implementation plans checked by `docs check`. It is standalone: a file that follows this document is valid without running the tool. The words MUST, MUST NOT and MAY are used in their RFC 2119 sense.
+This is the complete specification for architecture decision records (ADRs) and implementation plans checked by `corestack-docs check`. It is standalone: a file that follows this document is valid without running the tool. The words MUST, MUST NOT and MAY are used in their RFC 2119 sense.
 
 The ADR body uses the [MADR 4](https://adr.github.io/madr/) layout; `Consequences` is mandatory. The frontmatter, naming and cross-reference rules are specific to this format.
 
@@ -135,7 +135,7 @@ Heading text is the raw source after the `#` markers, trimmed, with any closing
 
 ### 6.3 Placeholders
 
-A record is invalid if it still contains the exact marker `{{docs:todo}}` anywhere outside code, including inside a frontmatter string value or list item (write it quoted there: `summary: "{{docs:todo}}"`). A list item equal to the marker reports only the marker error, not the format error for its key. `docs new` writes this marker into each field and section it leaves for you to fill; replace it with content. No other text is treated as a placeholder, so words like TODO or TBD are fine. To mention the marker itself, put it in inline or fenced code.
+A record is invalid if it still contains the exact marker `{{docs:todo}}` anywhere outside code, including inside a frontmatter string value or list item (write it quoted there: `summary: "{{docs:todo}}"`). A list item equal to the marker reports only the marker error, not the format error for its key. `corestack-docs new` writes this marker into each field and section it leaves for you to fill; replace it with content. No other text is treated as a placeholder, so words like TODO or TBD are fine. To mention the marker itself, put it in inline or fenced code.
 
 ## 7. References and links
 
@@ -156,9 +156,9 @@ URL:
 
 Always allowed in body prose only: in-page anchors (`#section`) and `mailto:` links. Any other scheme is rejected.
 
-## 8. What `docs check` reports
+## 8. What `corestack-docs check` reports
 
-`docs check [--root DIR]` checks every record under `DIR` (default: the working directory) and prints one line per problem:
+`corestack-docs check [--root DIR]` checks every record under `DIR` (default: the working directory) and prints one line per problem:
 
 ```
 path:line: message