Goal

Convert all reference numbering in the blurb files from the bare [1], [2], [3] form to the [<blurb-slug>-<n>] form, where <blurb-slug> is the short name of the blurb, lowercased and hyphenated where the blurb title is multi-word.

The convention is already in place in three blurbs (Tron, Automan, Ziggy); this task extends it repo-wide.

Files in scope

Every *.md file under blurbs/rec/. Read each file first to confirm the existing reference style and the slug to use, before editing.

Existing files in scope (as of 2026-10-15; confirm by find blurbs/rec -name "*.md" -type f):

• blurbs/rec/arts/sci-fi/ai-hollywood-movies.md — slug: aimovies
• blurbs/rec/arts/sci-fi/ai-in-movies-and-tv.md — slug: overview
• blurbs/rec/arts/sci-fi/jarvis.md — slug: jarvis
• blurbs/rec/arts/sci-fi/i-robot-movie-book.md — slug: irobot
• blurbs/rec/arts/sci-fi/laws-of-robotics.md — slug: laws
• blurbs/rec/arts/sci-fi/skynet.md — slug: skynet
• blurbs/rec/arts/sci-fi/tron.md — slug: tron (already migrated, skip)
• blurbs/rec/arts/sci-fi/tv/ai-in-sci-fi-tv.md — slug: aitv
• blurbs/rec/arts/sci-fi/tv/automan.md — slug: automan (already migrated, skip)
• blurbs/rec/arts/sci-fi/tv/max-headroom.md — slug: headroom
• blurbs/rec/arts/sci-fi/tv/quantum-leap-ziggy.md — slug: ziggy (already migrated, skip)
• blurbs/rec/arts/sci-fi/tv/star-trek-computer-lcars.md — slug: lcars
• blurbs/rec/arts/sci-fi/tv/star-trek-measure-of-a-man.md — slug: measure
• blurbs/rec/arts/sci-fi/tv/knight-rider/cast.md — slug: kr-cast
• blurbs/rec/arts/sci-fi/tv/knight-rider/fans.md — slug: kr-fans
• blurbs/rec/arts/sci-fi/tv/knight-rider/iconic-episodes.md — slug: kr-episodes
• blurbs/rec/arts/sci-fi/tv/knight-rider/kitt.md — slug: kitt
• blurbs/rec/arts/sci-fi/tv/knight-rider/reboots.md — slug: kr-reboots
• blurbs/rec/arts/sci-fi/tv/knight-rider/iconic-episodes/junk-yard-dog.md — slug: kr-junk
• blurbs/rec/arts/sci-fi/tv/knight-rider/iconic-episodes/knight-of-the-juggernaut.md — slug: kr-juggernaut
• blurbs/rec/arts/sci-fi/tv/knight-rider/iconic-episodes/knight-song.md — slug: kr-song
• blurbs/rec/arts/star-trek/emh.md — slug: emh
• blurbs/rec/arts/star-trek/ds9-awards.md — slug: ds9-awards
• blurbs/rec/arts/star-trek/ds9-making.md — slug: ds9-making
• blurbs/rec/arts/star-trek/ds9-milestones.md — slug: ds9-milestones
• blurbs/rec/arts/star-trek/ds9-people.md — slug: ds9-people
• blurbs/rec/arts/star-trek/sfa-making.md — slug: sfa-making
• blurbs/rec/arts/star-trek/sfa-milestones.md — slug: sfa-milestones
• blurbs/rec/arts/star-trek/sfa-people.md — slug: sfa-people
• blurbs/rec/arts/star-trek/tng-awards.md — slug: tng-awards
• blurbs/rec/arts/star-trek/tng-barclay.md — slug: tng-barclay
• blurbs/rec/arts/star-trek/tng-crossovers.md — slug: tng-crossovers
• blurbs/rec/arts/star-trek/tng-guinan.md — slug: tng-guinan
• blurbs/rec/arts/star-trek/tng-making.md — slug: tng-making
• blurbs/rec/arts/star-trek/tng-milestones.md — slug: tng-milestones
• blurbs/rec/arts/star-trek/tng-people.md — slug: tng-people
• blurbs/rec/arts/star-trek/tng-timesarrow.md — slug: tng-timesarrow
• blurbs/rec/arts/star-trek/tos-making.md — slug: tos-making
• blurbs/rec/arts/star-trek/tos-milestones.md — slug: tos-milestones
• blurbs/rec/arts/star-trek/tos-people.md — slug: tos-people

If the file list above is out of date, regenerate with find blurbs/rec -name "*.md" -type f and pick a slug for any new file following the convention in the existing list.

Files to skip (already migrated): tron.md, automan.md, quantum-leap-ziggy.md.

Slug rules

1. The slug is the short name of the blurb, lowercased.
2. If the blurb title is multi-word, join with single hyphens: "Skynet" stays skynet; "AI in Sci-Fi TV" becomes aitv; "Quantum Leap Ziggy" becomes ziggy.
3. For grouped content (Star Trek characters, Knight Rider sub-blurbs), use the franchise + topic: tng-barclay, kr-kitt, ds9-people, etc.
4. Slugs must be unique within the file's references section. If a single file references another blurb whose slug collides with an in-file slug, the colliding one is suffixed: e.g., a file that has both [tng-1] and a reference to the TNG people blurb would resolve the second as [tng-people-1]. (This is an unlikely edge case; if you hit it, ask before resolving.)

What to convert

In each file:

1. In-text citations of the form [N], [N, M], [N][M], [N-M] (the bare number form, with optional comma/bracket/caret combinations).
2. Reference entries in the references section of the form [N] [Title](url) or [N] text.

Both must be converted together so the rendered output continues to link.

What to leave alone

• Unnumbered references (footnotes, see-also style links in prose) — only numbered refs get prefixed.
• Square brackets that are not references (e.g., placeholder text like [citation needed], code blocks, image alt text). Use judgment; if a bracket pair looks like a reference (numeric content, links to a real URL), convert it; if it doesn't, leave it.
• Front matter (the --- block at the top of each file).
• Inline code, fenced code blocks, HTML comments.
• Cross-file links like [EMH blurb](../star-trek/emh) — these are navigation links, not references.

Mechanical procedure (per file)

For each file in scope (other than the three already-migrated ones):

1. Read the file end-to-end.
2. Identify the references section — usually the last ## References (or ## References and Notes, ## Sources, etc.) heading. If there is no ## References heading, look for a final --- separator followed by a list of [N] [Title](url) lines.
3. Build a map of bare numbers to slugs: every distinct bare number N that appears as a reference entry becomes the new key slug-N. For example, a file with references [1], [2], [3] becomes [<slug>-1], [<slug>-2], [<slug>-3].
4. Apply the map in two passes:
   • In-text pass: replace every bare-number reference (e.g., [1], [1][2], [1, 2], [1-3]) with its slugged form. Be careful with bracketed ranges like [1-3] — these mean "all of 1, 2, 3" and the corresponding new form is [<slug>-1][<slug>-2][<slug>-3]. The blade is a Markdown link-style citation system; treat [1, 2] as two adjacent references [1] and [2] and split them.
   • References-section pass: rename each [N] line to [<slug>-N].
5. Verify the diff: every original [N] should map to a unique [<slug>-N], and no new [<slug>-N] should exist without a corresponding original.
6. Commit the file as a single refactor(blurbs): migrate <file> to slug-N reference style commit.

Cross-file references

If file A contains a Markdown link to file B (e.g., [EMH blurb](../star-trek/emh.md)), do not touch it — it is a navigation link, not a citation. The new slug-style is only for numbered references inside a file.

If file A contains a prose reference like "see [1] for the franchise's awards list" and [1] is the only number in the file, the migration converts it to [<slug-of-A>-1]. The reader clicks through to the references section at the bottom of file A. This is the intended behavior; the slug does not need to match the source of the cited fact.

Commit order

Commit one file at a time. Suggested order (smallest blast radius first):

1. The Star Trek single-topic blurbs (tng-barclay, tng-guinan, tng-crossovers, tng-timesarrow, sfa-*, ds9-awards, tng-awards, etc.)
2. The Knight Rider sub-blurbs (kr-*).
3. The remaining sci-fi blurbs (jarvis, irobot, laws, headroom, lcars, measure, skynet).
4. The two overview-style blurbs last (aimovies, overview, aitv) because they have the most cross-references and the most citations.

If you convert a blurb that the Tron / Automan / Ziggy blurbs link to via [N], those links are navigation links and do not change. If you find a numbered reference inside one of the three already-migrated files that points to a now-migrated file, the link still works because the bare numbers in the source file and the slugged numbers in the destination file are independent — the reader is reading in the source file, where the citations are slugged in the source's style.

Pre-commit hook

The meta-repo's pre-commit hook will run on each commit. The hook checks submodule pointer divergence. None of these commits touch submodules or change the meta-repo's gitlinks, so the hook should pass on every commit. If the hook blocks, the most likely cause is untracked files in the working tree from other work; check git status and resolve before committing.

Verification

After all files are migrated, run:

grep -rEn '\[(achilles|[0-9]+)\]\s' blurbs/rec/ --include='*.md' | head -20

This should produce no output (or only a small handful of edge cases to inspect). If it produces matches, those are files where a bare [N] reference was missed.

Then run:

grep -rEn '\[(tron|automan|ziggy|skynet|jarvis|emh|headroom|lcars|measure|irobot|laws|aimovies|aitv|overview|kitt|kr-[a-z]+|tng-[a-z]+|tng-[0-9]+|sfa-[a-z]+|ds9-[a-z]+|tos-[a-z]+)-[0-9]+\]' blurbs/rec/ --include='*.md' | wc -l

This should produce a count of several hundred, indicating the new style is now in use across the tree.

Out of scope

• Renaming the slug list above if a file is renamed (the slug is keyed to the blurb's topic, not the file name; do not change slugs to match file names).
• Adding Amazon search links to blurbs that don't already have them. (That is a separate task.)
• Migrating rec/arts/... blurbs that are not under blurbs/rec/. (None exist at this time; if you find one, the procedure is the same.)
• Migrating blurbs in blurbs/alt/, blurbs/comp/, blurbs/ec/, or blurbs/usgov/. (This task is scoped to blurbs/rec/; if the user wants those migrated too, ask first.)