1 files changed, 44 insertions, 0 deletions
diff --git a/.ai/workflows/rename-artifact.org b/.ai/workflows/rename-artifact.org
new file mode 100644
index 0000000..7b9f15b
--- /dev/null
+++ b/.ai/workflows/rename-artifact.org
@@ -0,0 +1,44 @@
+#+TITLE: Rename an .ai Artifact
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-05-31
+
+* Summary
+
+Rename a workflow or a script that lives in the =.ai/= tree, without leaving the canonical copy, the mirror copy, the INDEX, or any reference behind. The work is mechanical and easy to do incompletely by hand — a missed reference or a forgotten mirror copy is the classic failure. The =rename-ai-artifact.sh= script does it the same way every time, so reach for the script rather than renaming files by hand.
+
+Quick contract — what it does:
+- Moves the artifact in both =claude-templates/.ai/= (canonical) and =.ai/= (mirror), in lockstep.
+- Rewrites every reference to the artifact's stem, repo-wide, on a token boundary so renaming =foo= can't corrupt =foobar= or =foo-bar=.
+- Rewrites the underscore module-name variant too — a hyphenated script imported as =foo_bar= via importlib, not just the =foo-bar.py= path.
+- Leaves =sessions/= (both trees) untouched — archived session records are history.
+- Runs =workflow-integrity.py= and =sync-check.sh= afterward to prove no drift.
+
+* Execution
+
+Run once per file. For a family (a workflow plus its helper scripts), run it once per artifact; order doesn't matter because reference matching is token-bounded.
+
+#+begin_example
+scripts/rename-ai-artifact.sh OLD-BASENAME NEW-BASENAME
+
+# examples
+scripts/rename-ai-artifact.sh old-workflow.org new-workflow.org
+scripts/rename-ai-artifact.sh old-helper.py    new-helper.py
+#+end_example
+
+After the last file in a family is renamed, review =git status= and the diff, then commit through the normal publish flow.
+
+* Reference
+
+** When to use
+
+Any time an =.ai/= workflow or script changes name. Also the right tool when only the *concept* is being renamed and you want every trigger phrase, =file:= link, and prose mention updated to match.
+
+** What it will not do
+
+- It won't touch =sessions/= records (history stays accurate to when it was written).
+- It won't rename across directories — the artifact keeps its home directory; only the basename changes.
+- It renames one artifact per call and refuses if the source is missing or the target name already exists.
+
+** If a verify step reports drift
+
+The script still completes the rename, then warns. Read the =workflow-integrity= / =sync-check= output, fix by hand (usually a stale INDEX row the stem rewrite didn't reach because the row used different wording), and re-run the checks before committing.