sidebar-update

When This Applies

Fires when a docs file is moved or renamed — detected from:

• git mv docs/old-path.md docs/new-path.md in the conversation
• File rename via Edit/Write tool targeting a docs/ path
• User says "move [doc]", "rename [doc]", "relocate [doc]"
• A diff shows a docs file at a new path that differs from the old path

Does not apply to:

• Non-docs files (commands, skills, templates, etc.)
• New files with no prior sidebar entry
• Files outside docs/

---

Workflow

Step 1 — Identify old and new paths

Extract from context:

• OLD_PATH — original path relative to docs/ without .md (e.g., guides/foo)
• NEW_PATH — new path relative to docs/ without .md (e.g., guides/bar/foo)

Step 2 — Find the sidebar entry

grep -n "OLD_PATH" sidebars.js

If found: show the matching line(s) and the surrounding category context.

If not found: note "No sidebar entry found for OLD_PATH — the file may not have been in the sidebar yet." Offer to add a new entry for NEW_PATH and stop here.

Step 3 — Apply the sidebar update

Replace the stale id: value in sidebars.js:

OLD: {type: 'doc', id: 'OLD_PATH', label: '...'}
NEW: {type: 'doc', id: 'NEW_PATH', label: '...'}

Preserve the existing label: value unless the user provides a new one.

Step 4 — Scan for broken internal links

grep -r "OLD_PATH" docs/ --include="*.md" --include="*.mdx" -l

For each file found, show the matching lines. Offer to update them in place (replacing OLD_PATH references with NEW_PATH).

Step 5 — Confirm and summarize

sidebar-update complete:

✓ sidebars.js — updated id: 'OLD_PATH' → 'NEW_PATH'
✓ N internal link(s) updated (or: no internal links found)

---

Edge Cases

Situation	Behavior
File moved to a new category in the sidebar	Update id: but also ask if the entry should move to a different category block
Multiple sidebar entries for the same old path	Show all matches and confirm each update
Label should change with the rename	Ask: "Should the sidebar label also change from '[old label]' to '[suggested label]'?"
Old path not in sidebar	Offer to add a new entry; skip link scan
sidebars.js uses autogenerated sidebar	Note that autogenerated sidebars pick up the rename automatically; suggest verifying the id: frontmatter in the file is consistent