From dc82ecfad4c2591356122e3e33559de0f7753916 Mon Sep 17 00:00:00 2001
From: Phillip Cloud <417981+cpcloud@users.noreply.github.com>
Date: Tue, 14 Apr 2026 16:35:42 -0400
Subject: [PATCH 1/2] fix: retract old versions with mismatched module path

Old version tags (v1.0.0 through v1.80.0) declared module path
github.com/cpcloud/micasa, which conflicts with the current
github.com/micasa-dev/micasa path. This caused `go install
github.com/micasa-dev/micasa/cmd/micasa@latest` to fail.

Add a retract directive covering the v1.x range so Go skips those
versions when resolving @latest.

The v2.x tags (v2.0.0-v2.3.0) also used the old path but without a /v2
suffix, making them a different module from Go's perspective -- they
cannot be retracted from this module and do not cause conflicts.

closes #923
---
 go.mod                          |  7 ++++++
 plans/923-installation-error.md | 41 +++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 plans/923-installation-error.md

diff --git a/go.mod b/go.mod
index 37ff664a..500fdfa9 100644
--- a/go.mod
+++ b/go.mod
@@ -5,6 +5,13 @@ module github.com/micasa-dev/micasa
 
 go 1.26
 
+// Pre-v2.4.0 versions declared module path github.com/cpcloud/micasa
+// which conflicts with the current github.com/micasa-dev/micasa path.
+// The v2.x tags also used the old path without a /v2 suffix, so Go
+// treats them as a different module entirely; only v1.x is retractable
+// from this module.
+retract [v1.0.0, v1.80.0]
+
 require (
 	charm.land/fang/v2 v2.0.1
 	github.com/BurntSushi/toml v1.6.0
diff --git a/plans/923-installation-error.md b/plans/923-installation-error.md
new file mode 100644
index 00000000..fbbed322
--- /dev/null
+++ b/plans/923-installation-error.md
@@ -0,0 +1,41 @@
+# Issue #923: `go install` error
+
+## Root cause
+
+The repository was migrated from `github.com/cpcloud/micasa` to
+`github.com/micasa-dev/micasa`. Old version tags (v1.0.0 through v1.80.0 and
+v2.0.0 through v2.3.0) still have `module github.com/cpcloud/micasa` in their
+`go.mod`. When a user runs:
+
+```sh
+go install github.com/micasa-dev/micasa/cmd/micasa@latest
+```
+
+Go resolves `@latest` and finds these old tags. The mismatch between the
+requested module path (`github.com/micasa-dev/micasa`) and the module path
+declared in the old tags (`github.com/cpcloud/micasa`) causes Go to error.
+
+## Fix
+
+Add a `retract` directive to `go.mod` covering the v1.x range:
+
+```go
+retract [v1.0.0, v1.80.0]
+```
+
+This tells Go to skip those versions when resolving `@latest`.
+
+The v2.x tags (v2.0.0 through v2.3.0) also declared
+`module github.com/cpcloud/micasa` without a `/v2` suffix. Because the module
+path differs, Go treats them as a completely different module -- they do not
+conflict with `github.com/micasa-dev/micasa` and cannot be retracted from this
+module's `go.mod`.
+
+Starting from v2.4.0, all tags use the correct module path
+`github.com/micasa-dev/micasa`, so no further action is needed.
+
+## What was NOT changed
+
+- Module path stays `github.com/micasa-dev/micasa` (no `/v2` suffix)
+- No import path changes anywhere in the codebase
+- Install docs already used `@latest`, no changes needed

From 27a720762f41a12588cb45a4812ecf951d5bd715 Mon Sep 17 00:00:00 2001
From: Phillip Cloud <417981+cpcloud@users.noreply.github.com>
Date: Tue, 14 Apr 2026 18:12:07 -0400
Subject: [PATCH 2/2] docs: add license header to spec file

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 plans/923-installation-error.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/plans/923-installation-error.md b/plans/923-installation-error.md
index fbbed322..146d748f 100644
--- a/plans/923-installation-error.md
+++ b/plans/923-installation-error.md
@@ -1,3 +1,6 @@
+<!-- Copyright 2026 Phillip Cloud -->
+<!-- Licensed under the Apache License, Version 2.0 -->
+
 # Issue #923: `go install` error
 
 ## Root cause