Fix a broken upstream path without rewriting every note
Delete or move a file and lists that named it stay broken on purpose. Relink, Relink Everywhere, and Show Upstream Issues fix them as one undoable step.
You rename notes/schema.md to notes/data-model.md. Three other notes still list the old path in their upstream. Those entries go red. That is intentional.
BaseHalf does not silently rewrite every list when a path disappears. A missing target is still a signal until you decide what to do with it. Broken entries stay until Relink, Relink Everywhere, or Remove. The Command Palette also has BaseHalf: Show Upstream Issues when you want the full set in one place.
Why broken entries stay
Upstream lists live in plain text: Markdown frontmatter upstream:, or .bh/mirror/<path>/upstream.yaml for other files. Agents and tools can edit those lists themselves. BaseHalf uses whatever is in the file.
If we auto-healed every stale path, you would lose the chance to notice drift. A delete that should have been a move looks the same as a typo until you look. Keeping the broken entry visible makes the ops step explicit: fix the pointer, or drop it.
Moving or renaming through BaseHalf updates entries by content recognition when it can. Deletes, external renames, and hand-edited paths are where the badge warning shows up.
Relink, Relink Everywhere, Remove
When a card's badge warns about Upstream, open it and pick the action that matches the situation.
| Action | What it does |
|---|---|
| Relink | Point this one broken entry at a file you choose |
| Relink Everywhere | Find the same broken path across the workspace and retarget all of them in one step |
| Remove | Drop the broken entry from this list |
Relink Everywhere is the one to reach for after a rename that left many notes pointing at the old name. Relink is enough when only this card is wrong. Remove is for paths that should no longer be upstream of anything here.
These fixes are ordinary edits to the lists. They undo as one step with the rest of your canvas undo, so a bad retarget is cheap to reverse.
Ops after the graph drifts
This is the maintenance pass after structure moves. Putting context in upstream lists (instead of pasting it into every prompt) is the design. Day-to-day, files move and lists lag. Show Upstream Issues, Relink Everywhere, and Remove keep the graph honest without opening every note by hand.
Open the palette, run BaseHalf: Show Upstream Issues, clear the red paths, and commit the updated lists. The next Claude Code or Codex session reads the repaired files the same way git does.