fix: rename module path from instrospection to introspection

README.md

@@ -1,7 +1,7 @@
 # Introspection
 
-[![Go Report Card](https://goreportcard.com/badge/github.com/aretw0/instrospection)](https://goreportcard.com/report/github.com/aretw0/instrospection)
-[![Go Reference](https://pkg.go.dev/badge/github.com/aretw0/instrospection.svg)](https://pkg.go.dev/github.com/aretw0/instrospection)
+[![Go Report Card](https://goreportcard.com/badge/github.com/aretw0/introspection)](https://goreportcard.com/report/github.com/aretw0/introspection)
+[![Go Reference](https://pkg.go.dev/badge/github.com/aretw0/introspection.svg)](https://pkg.go.dev/github.com/aretw0/introspection)
 [![License](https://img.shields.io/github/license/aretw0/introspection.svg?color=red)](./LICENSE)
 [![Release](https://img.shields.io/github/release/aretw0/introspection.svg?branch=main)](https://github.com/aretw0/introspection/releases)
 
@@ -95,7 +95,7 @@ stateMachine := introspection.StateMachineDiagram(state, smConfig)
 ## Installation
 
 ```bash
-go get github.com/aretw0/instrospection
+go get github.com/aretw0/introspection
 ```
 
 ## Quick Start
@@ -106,7 +106,7 @@ package main
 import (
     "context"
     "fmt"
-    "github.com/aretw0/instrospection"
+    "github.com/aretw0/introspection"
 )
 
 // Define your component's state

VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2

docs/DECISIONS.md

@@ -13,6 +13,7 @@ This document captures key architectural and design decisions made for the intro
 7. [Backward Compatibility](#7-backward-compatibility)
 8. [Ubuntu-Only CI Testing](#8-ubuntu-only-ci-testing)
 9. [CI Workflow Optimization - Avoid Duplicate Runs](#9-ci-workflow-optimization---avoid-duplicate-runs)
+10. [Module Path Rename - instrospection → introspection](#10-module-path-rename---instrospection--introspection)
 
 ---
 
@@ -475,6 +476,49 @@ For a typical development cycle:
 
 ---
 
+## 10. Module Path Rename - instrospection → introspection
+
+### Decision
+
+Fix the Go module path from `github.com/aretw0/instrospection` to `github.com/aretw0/introspection`, delete old tags/releases, and publish a new version (`v0.1.2`).
+
+### Rationale
+
+**Problem**: The Go module was published with a typo in the module path (`instrospection` instead of `introspection`). This made the module path inconsistent with the GitHub repository URL, preventing `go get` from resolving the module correctly.
+
+**Options Considered**:
+1. **Rewrite git history**: Use `git filter-branch` or `git filter-repo` to fix the typo across all commits, then force-push and re-tag
+2. **New version with fix**: Fix the typo in a new commit, delete old tags, and publish a new version
+3. **New major version**: Start a `v2` module path with the correct spelling
+
+**Decision**: Option 2 — New version with fix
+
+### Trade-offs
+
+✅ **Pros**:
+- Clean fix without disrupting git history
+- Safe for Go module proxy and checksum database
+- Minimal disruption to any existing consumers
+- Old versions can be retracted
+
+❌ **Cons**:
+- Old tags/releases must be manually deleted
+- Requires manual steps after merging (see `docs/MODULE_RENAME.md`)
+
+### Why Not Rewrite History?
+
+Go modules have unique constraints that make history rewriting ineffective:
+
+1. **Module proxy caching**: `proxy.golang.org` permanently caches published versions
+2. **Checksum database**: `sum.golang.org` records hashes; changed hashes cause verification failures
+3. **Force push risks**: Breaks other contributors' local clones and CI
+
+### Post-Merge Steps
+
+See [`docs/MODULE_RENAME.md`](MODULE_RENAME.md) for the complete checklist of manual steps required after merging the fix.
+
+---
+
 ## Future Decisions
 
 These are questions we'll need to answer in future versions:

docs/MODULE_RENAME.md

@@ -0,0 +1,125 @@
+# Module Rename: instrospection → introspection
+
+This document describes the steps required after merging the module rename PR that fixes the typo `instrospection` → `introspection` in the Go module path.
+
+## Context
+
+The Go module was originally published as `github.com/aretw0/instrospection` (with an extra `r`). Since the GitHub repository has always been named `introspection`, the module path was inconsistent with the repository URL.
+
+PR #6 fixes the typo in `go.mod`, all import paths, and documentation. However, because Go modules are immutable once published, additional manual steps are required after merging.
+
+## Post-Merge Steps
+
+### 1. Delete Old Tags and Releases
+
+The existing tags (`v0.1.0`, `v0.1.1`) point to commits with the old (incorrect) module path. They must be removed and recreated so that `pkg.go.dev` and `go get` resolve the correct module.
+
+```bash
+# Delete remote tags
+git push origin :refs/tags/v0.1.0
+git push origin :refs/tags/v0.1.1
+
+# Delete local tags
+git tag -d v0.1.0
+git tag -d v0.1.1
+```
+
+Then delete the corresponding GitHub Releases via the GitHub UI:
+
+1. Go to https://github.com/aretw0/introspection/releases
+2. Delete the `v0.1.0` and `v0.1.1` releases
+
+### 2. Retract Old Versions (Optional but Recommended)
+
+If any users already consumed the old module path, add a `retract` directive to `go.mod` to signal that the old versions should not be used:
+
+```go
+module github.com/aretw0/introspection
+
+go 1.24.13
+
+retract (
+    v0.1.0 // Published with incorrect module path (instrospection)
+    v0.1.1 // Published with incorrect module path (instrospection)
+)
+```
+
+> **Note**: The `retract` directive only takes effect when a version **higher** than the retracted versions is published. It will be processed when `v0.1.2` (or later) is tagged.
+
+### 3. Bump Version and Re-Tag
+
+After the PR is merged into `main`, create a new release with the corrected module path:
+
+```bash
+# Ensure VERSION is updated
+echo "0.1.2" > VERSION
+git add VERSION
+git commit -m "Bump version to 0.1.2"
+git push origin main
+
+# Create and push the new tag
+git tag -a v0.1.2 -m "Release v0.1.2 - Fix module path typo"
+git push origin v0.1.2
+```
+
+This will trigger GoReleaser via GitHub Actions to create the release automatically.
+
+### 4. Verify pkg.go.dev
+
+After the new tag is pushed:
+
+1. Visit https://pkg.go.dev/github.com/aretw0/introspection
+2. If the page doesn't appear automatically, request indexing:
+   ```
+   https://pkg.go.dev/github.com/aretw0/introspection@v0.1.2
+   ```
+3. You can also trigger indexing via the Go module proxy:
+   ```bash
+   curl https://proxy.golang.org/github.com/aretw0/introspection/@v/v0.1.2.info
+   ```
+4. Verify the module documentation renders correctly
+
+### 5. Verify Go Report Card
+
+1. Visit https://goreportcard.com/report/github.com/aretw0/introspection
+2. Trigger a new report if needed
+
+### 6. Update Downstream Consumers
+
+If any other projects (e.g., `lifecycle`) depend on this module, update their imports:
+
+```bash
+# In the downstream project
+go get github.com/aretw0/introspection@v0.1.2
+```
+
+## Important Notes
+
+### Why Not Rewrite Git History?
+
+While the original issue mentions git history rewriting, this is **not recommended** for published Go modules because:
+
+1. **Go module proxy caching**: The Go module proxy (`proxy.golang.org`) caches module versions permanently. Rewriting history doesn't change what's cached.
+2. **Checksum database**: The Go checksum database (`sum.golang.org`) has recorded hashes for published versions. Changed hashes would cause verification failures.
+3. **Force push risks**: Force-pushing to `main` can break other contributors' local clones and CI pipelines.
+
+The **correct approach** for Go modules is to:
+- Delete the old tags/releases
+- Publish a new version with the fix
+- Optionally retract the old versions
+
+### Go Module Path vs Repository URL
+
+In Go, the module path in `go.mod` must match the repository URL for the module proxy to resolve it correctly. The old path `github.com/aretw0/instrospection` could never be fetched via `go get` since the repository is `github.com/aretw0/introspection`.
+
+## Checklist
+
+- [ ] Delete old tags (`v0.1.0`, `v0.1.1`) from remote
+- [ ] Delete old GitHub Releases
+- [ ] Optionally add `retract` directives to `go.mod`
+- [ ] Bump VERSION to `0.1.2`
+- [ ] Create and push `v0.1.2` tag
+- [ ] Verify GoReleaser creates the release
+- [ ] Verify pkg.go.dev indexes the correct module
+- [ ] Verify Go Report Card
+- [ ] Update downstream consumers (if any)

docs/PLANNING.md

@@ -1,6 +1,6 @@
 # Planning & Roadmap: Introspection
 
-## Current Version: 0.1.0
+## Current Version: 0.1.2
 
 This document outlines the current state and future direction of the introspection package.
 
@@ -48,6 +48,15 @@ This document outlines the current state and future direction of the introspecti
 
 - [x] Add pkg.go.dev example_test.go.
 
+### 🔄 In Progress (v0.1.2)
+
+- [x] Fix module path typo: `instrospection` → `introspection` (PR #6)
+- [x] Document post-merge steps for re-tagging and pkg.go.dev (`docs/MODULE_RENAME.md`)
+- [x] Add decision record for module rename (`docs/DECISIONS.md` #10)
+- [ ] Delete old tags and releases (manual, post-merge)
+- [ ] Re-tag as `v0.1.2` (manual, post-merge)
+- [ ] Verify pkg.go.dev indexing (manual, post-merge)
+
 ## Roadmap
 
 ### 🎯 v0.2.0 - Enhanced Visualization

example_test.go

@@ -5,7 +5,7 @@ import (
 	"fmt"
 	"time"
 
-	introspection "github.com/aretw0/instrospection"
+	introspection "github.com/aretw0/introspection"
 )
 
 // Example demonstrates basic usage of the introspection package

examples/basic/main.go

@@ -5,7 +5,7 @@ import (
 	"fmt"
 	"time"
 
-	"github.com/aretw0/instrospection"
+	"github.com/aretw0/introspection"
 )
 
 // WorkerState represents the state of a worker component.

examples/generic/main.go

@@ -5,7 +5,7 @@ import (
 	"fmt"
 	"time"
 
-	"github.com/aretw0/instrospection"
+	"github.com/aretw0/introspection"
 )
 
 // Example using a Task Scheduling domain (not worker/signal)

go.mod

@@ -1,3 +1,3 @@
-module github.com/aretw0/instrospection
+module github.com/aretw0/introspection
 
 go 1.24.13