# Folder Rename Checklist: starsend/ -> recoil-visual/

Phase 12 of the FastAPI Migration. This checklist prepares for and documents
the rename of `~/Dropbox/CLAUDE_PROJECTS/starsend/` to `recoil-visual/`.

**Date prepared:** 2026-03-16

---

## Status (2026-04-20)

**State-namespace rename: COMPLETE.** Finished by the state-namespace-migration build. The `visual_state_namespace` config key is defined explicitly in `recoil/config/pipeline_config.json` and read from `recoil/core/paths.py`. All hardcoded `"starsend"` path constructions in active pipeline code migrated to `STATE_NAMESPACE`. Filesystem migration (`state/starsend/` → `state/visual/`) was completed earlier. No projects retain `state/starsend/` directories.

**Folder rename (`starsend/` → `recoil-visual/`): STILL DEFERRED.** This checklist covers that rename; the state-namespace portion above is independent and now closed.

---

## Pre-Rename Verification (DONE)

- [x] `visual_state_namespace` config key exists in `config/starsend_config.json` (value: `"starsend"`)
- [x] `STARSEND_ROOT` in `lib/constants.py` uses `Path(__file__).resolve().parent.parent` (auto-detection, no hardcoded path)
- [x] All `api/` route files use `STATE_NAMESPACE` from `deps.py` instead of hardcoded `"starsend"` for state paths
- [x] All 379 tests pass

## What Does NOT Need Changing (handled automatically)

These use `Path(__file__).parent.parent` or config-driven resolution -- the rename is transparent:

- `lib/constants.py` -- `STARSEND_ROOT` auto-detects from file location
- `api/__init__.py` -- `PROJECT_ROOT` auto-detects
- `api/state.py` -- `PROJECT_ROOT`, `EDITORS_DIR` auto-detect
- `api/deps.py` -- `PROJECT_ROOT` auto-detects; `STATE_NAMESPACE` reads from config
- `api/main.py` -- `PROJECT_ROOT` auto-detects
- All `_paths_for_project()` calls -- use config-driven `STATE_NAMESPACE`
- `PROJECTS_ROOT`, `RECOIL_ROOT` -- read from `starsend_config.json`, not derived from folder name

## What Does NOT Need Renaming (per BUILD_SPEC)

- `state/starsend/` directories inside each project (e.g., `projects/tartarus/state/starsend/`)
  -- The `visual_state_namespace` config key handles this. Value stays `"starsend"`.
- Config file rename (`starsend_config.json` -> `visual_pipeline_config.json`) is optional and deferred.

---

## Rename Steps (Manual -- JT executes)

### Step 1: Stop the server
```bash
# Kill any running review_server.py or uvicorn
pkill -f "review_server.py" 2>/dev/null
pkill -f "uvicorn api.main" 2>/dev/null
```

### Step 2: Rename the folder
```bash
cd ~/Dropbox/CLAUDE_PROJECTS
mv starsend recoil-visual
```

### Step 3: Verify server starts from new location
```bash
cd ~/Dropbox/CLAUDE_PROJECTS/recoil-visual
python3 -c "from lib.constants import STARSEND_ROOT; print(f'Root: {STARSEND_ROOT}')"
python3 -m pytest tests/ --tb=short -q
uvicorn api.main:app --host 127.0.0.1 --port 8431
# Test: curl http://127.0.0.1:8431/api/health
```

### Step 4: Update Claude project directory mapping
```bash
cd ~/.claude/projects
cp -r -- "-Users-joeturnerlin-Dropbox-CLAUDE-PROJECTS-starsend" \
         "-Users-joeturnerlin-Dropbox-CLAUDE-PROJECTS-recoil-visual" 2>/dev/null || true
```

### Step 5: Update project-level CLAUDE.md
File: `~/Dropbox/CLAUDE_PROJECTS/recoil-visual/CLAUDE.md`
- Update the naming note paragraph
- Search-replace path references from `starsend/` to `recoil-visual/`

### Step 6: Update Claude memory files (external)

| File | What to update |
|------|---------------|
| `~/.claude/projects/-Users-joeturnerlin-Dropbox-CLAUDE-PROJECTS/memory/MEMORY.md` | `CLAUDE_PROJECTS/starsend` -> `CLAUDE_PROJECTS/recoil-visual` |
| `~/.claude/projects/-Users-joeturnerlin-Dropbox-CLAUDE-PROJECTS/memory/scratchpad.md` | Path references |
| `~/.claude/projects/-Users-joeturnerlin-Dropbox-CLAUDE-PROJECTS/memory/starsend-context.md` | Path references |
| `~/.claude/projects/-Users-joeturnerlin-Dropbox-CLAUDE-PROJECTS/memory/scratchpads/state_visual-pipeline.md` | Path references |
| `~/.claude/projects/-Users-joeturnerlin-Dropbox-CLAUDE-PROJECTS/memory/scratchpads/state_ep001-pipeline.md` | Path references |
| `~/.claude/projects/-Users-joeturnerlin-Dropbox-CLAUDE-PROJECTS/memory/scratchpads/state_production-console.md` | Path references |
| `~/Dropbox/Claude_Config/memory/scratchpad.md` | Path references |
| `~/Dropbox/Claude_Config/memory/MEMORY.md` | Path references |
| `~/Dropbox/Claude_Config/memory/scratchpads/state_visual-pipeline.md` | Path references |
| `~/Dropbox/Claude_Config/memory/scratchpads/state_ep001-pipeline.md` | Path references |
| `~/Dropbox/Claude_Config/memory/scratchpads/state_production-console.md` | Path references |

### Step 7: Update Recoil engine cross-references

| File | What to update |
|------|---------------|
| `~/Dropbox/CLAUDE_PROJECTS/recoil/.claude/skills/editors/SKILL.md` | Path references |
| `~/Dropbox/CLAUDE_PROJECTS/recoil/.claude/skills/engine-check/SKILL.md` | Path references |

### Step 8: Update skills inside the project

| File | What to update |
|------|---------------|
| `.claude/skills/consult/SKILL.md` | Path references |
| `.claude/skills/starsend/SKILL.md` | Path references (consider renaming skill folder too) |

### Step 9: Update Obsidian vault references (low priority -- historical docs)

16 files in `$VAULT` reference `CLAUDE_PROJECTS/starsend`. These are mostly harness docs
and conversation archives. Update if convenient; they won't break anything if left stale.

---

## Files Inside the Project Containing "starsend" (informational)

These files contain the string "starsend" but most are either:
- **State path references** (`state/starsend/`) -- intentional, governed by `visual_state_namespace`
- **Logger names** (`logging.getLogger("starsend.xxx")`) -- cosmetic, no functional impact
- **Config filename** (`starsend_config.json`) -- not being renamed in this phase
- **Comments/docstrings** -- no functional impact
- **Test fixtures** -- create temp `state/starsend/` dirs, governed by the data format
- **Frontend function names** (`starsendGet`, `starsendPost`) -- internal JS naming, no user-visible impact
- **LocalStorage keys** (`starsend_taskq_`, `starsend_active_project`, etc.) -- functional but clearing localStorage is harmless

### Python files (52 files)
Core lib (rename-safe via auto-detection):
- `lib/constants.py` -- CONFIG_PATH uses `STARSEND_ROOT / "config" / "starsend_config.json"` (config filename, not state path)
- `lib/execution_store.py` -- `state/starsend/shots/`, `~/.cache/starsend/` (state namespace paths)
- `lib/recoil_bridge.py` -- `state/starsend/` paths (state namespace)
- `lib/keyframe_context.py` -- `state/starsend/` paths (state namespace)
- `lib/previz_context.py` -- `state/starsend/` paths (state namespace)
- `lib/client_bridge.py` -- `state/starsend` (state namespace)
- `lib/screen_test.py` -- `state/starsend` (state namespace)
- `lib/assembler.py` -- config path + `state/starsend/` (state namespace)
- `lib/asset_manager.py` -- config path
- `lib/render_schema.py` -- logger name
- `lib/ref_selector.py` -- logger name + docstring
- `lib/visual_sync.py` -- comment

API routes (FIXED in this phase -- now use STATE_NAMESPACE):
- `api/deps.py` -- fallback default only
- `api/routes/casting.py` -- FIXED: now uses STATE_NAMESPACE
- `api/routes/dailies.py` -- FIXED: now uses STATE_NAMESPACE
- `api/routes/console.py` -- FIXED: now uses get_config()
- `api/routes/generation.py` -- import alias only (`_get_starsend_config`)

Orchestrator:
- `orchestrator/step_types.py` -- `state/starsend/plans` (state namespace)
- `orchestrator/execution_plan.py` -- `state/starsend/plans` (state namespace)
- `orchestrator/pipeline.py` -- `starsend_config` variable name + logger
- `orchestrator/ingest_pipeline.py` -- `state/starsend` (state namespace)

Tools:
- `tools/starsend_check.py` -- tool name (cosmetic)
- `tools/starsend_checks/*.py` -- module names (cosmetic)
- `tools/generate_previs.py` -- `state/starsend/` (state namespace)
- `tools/build_upload_bundle.py` -- `state/starsend/` (state namespace)
- `tools/test_via_steprunner.py` -- `state/starsend/` + example project name
- `tools/prep_location_refs.py` -- `state/starsend/` (state namespace)
- `tools/prep_prop_refs.py` -- `state/starsend/` (state namespace)
- `tools/consult.py` -- config filename
- Various other tools -- logger names, comments, example args

Tests:
- `tests/conftest.py` -- comment
- `tests/test_project_isolation.py` -- `state/starsend` fixture paths
- `tests/test_previz_context.py` -- `state/starsend` fixture paths
- `tests/test_rejection_roundtrip.py` -- `state/starsend` fixture paths
- `tests/lib/test_screen_test.py` -- `state/starsend` fixture paths
- `tests/smoke_client_video.py` -- comment
- `tests/test_payload_schemas.py` -- comment

### JavaScript files (18 files)
All in `editors/` -- function names (`starsendGet`, `starsendPost`, `starsendPatch`,
`starsendPostResilient`) and localStorage keys (`starsend_*`). No path-based references
to the folder name. These are cosmetic/internal naming only.

### HTML files (1 file)
- `editors/review.html` -- CLI example text (`/starsend generate --episode 1`)

### Markdown files (39 files)
Build logs, design docs, consultation archives, skills. Update the skills;
the rest are historical.

### JSON files (1 file)
- `config/starsend_config.json` -- the `visual_state_namespace` key itself

---

## Post-Rename Validation

```bash
cd ~/Dropbox/CLAUDE_PROJECTS/recoil-visual

# 1. Auto-detection works
python3 -c "from lib.constants import STARSEND_ROOT; print(f'Root: {STARSEND_ROOT}')"

# 2. All tests pass
python3 -m pytest tests/ --tb=short -q

# 3. Config namespace resolves
python3 -c "from lib.constants import get_config; print(get_config().get('visual_state_namespace'))"

# 4. Server starts
uvicorn api.main:app --host 127.0.0.1 --port 8431 &
sleep 2
curl -s http://127.0.0.1:8431/api/health | python3 -m json.tool
kill %1

# 5. Legacy server starts
python3 editors/review_server.py --project tartarus &
sleep 2
curl -s http://127.0.0.1:8430/api/health | python3 -m json.tool
kill %1
```