From one tool to a full toolkit: how I used AI to rename 4 products across 695 files in 3 days

I am a technical writer at an enterprise technology company. A few months ago, I was asked to lead the documentation side of a large product renaming project. Several products needed new names: all at once, with a hard deadline, and multiple writers working in parallel.

By the time the first leg of the project was done, we had renamed 4 products. In practical terms, that meant:

Roughly 695 files touched, with about 2,848 insertions and 2,816 deletions
349 URL mappings validated
71 redirect rules added or updated
486 screenshots audited and 29 reports generated

I am not a programmer. But I built every tool that made this possible by chatting with AI.

Metric	Count
Products renamed	4
Files touched	~695
Insertions / deletions	~2,848 / ~2,816
URL mappings validated	349
Redirect rules added/updated	71
Images audited	486
Images flagged for update	67
Reports generated	29
Commits	17
Execution window	3 days

What makes product renames hard

If you have never had to rename a product across a large documentation site, you might assume it is a find-and-replace job. It is not.

Our developer documentation is built with Astro and lives in a single GitHub repository with thousands of files. A product name does not just appear in prose. It shows up in:

YAML configuration files that define the product's metadata (ID, display name, icon, URL path)
Frontmatter in every documentation page (products: fields that link pages to their parent product)
Folder names that determine URL paths (rename the folder, every link to that section breaks)
Redirect rules that map old URLs to new ones (miss one, and a user's bookmark hits a 404)
Component props in MDX files that reference product IDs
Changelog entries tied to product identifiers
SVG icons named after the product
Cross-references in other products' documentation ("see the [Old Name] docs for more")
Screenshots showing the product's old name in the dashboard UI, sidebar, breadcrumbs, and page headers

Change any of these incorrectly and either the build crashes, the UI breaks, links go dead, or users see the wrong name. Now multiply that by four products, some of which rename together (a parent product and its sub-products), and you start to see why this is not a find-and-replace job.

On top of all this, some things must not be renamed at all: API field names, CLI tool names, code blocks, Terraform resource names, and historical changelog entries where the old name is the historically accurate one.

Building the first tool through conversation

The approach I took was conversational. I used OpenCode, an open-source AI coding agent that runs in the terminal, paired with Claude Opus 4.6 as the underlying model. Opus 4.6 might seem like overkill for documentation work, but in my experience lesser models struggle with the complexity of a large documentation site; they miss edge cases, misunderstand file relationships, and make more mistakes that you then have to fix. OpenCode lets you create reusable commands, essentially saved prompts with detailed instructions that the AI follows when you invoke them.

I started by describing the problem to the AI: "I need to rename a product across the documentation site. Here is what the site structure looks like. Here is what needs to change. Here are the things that must not change." I also pointed the AI to our Wiki page with the project plan, so it had a clear picture of the scope and timeline of the project, as well as the names of the products being renamed.

The first version of the rename command was rough. It missed edge cases, renamed things it should not have, and did not handle folder renames correctly. But each mistake became a rule. Each conversation refined the tool.

Over several iterations, the rename command grew to handle:

Safe lists: Terms that look like the old product name but must not be changed (API endpoints, CLI commands, code blocks, historical references).
Bundled renames: Products that need to be renamed together. When the parent product gets a new name, its sub-products need to follow.
Bridge phrasing: Adding "(formerly Old Name)" after the first mention of the new name on each page, so users who know the old name can orient themselves.
Two-pass execution: Pass 1 only touches files owned by the product being renamed. Pass 2 updates cross-references in other products' docs.
Batch mode: Content updates happen first on the original filenames (so diffs are clean and reviewable), then structural changes (folder renames, redirects) happen in a separate commit.

This is the point where the previous version of this story would have ended: one tool, built through conversation, ready to reuse. But as the project progressed, new problems kept surfacing, and each one pushed me to build another tool. What I did not anticipate was how much ground those tools would let me cover in such a short window of time.

One tool became six

As I started executing the actual renames, each new challenge pushed me back to the AI to build something new. None of the additional tools were planned upfront. Each one emerged from a specific problem I encountered during execution.

The rename tool is the core engine described above. To give you a sense of scale: the largest single rename touched 390 files across 5 commits, including 265 cross-reference files spanning 17 other products, 88 partial files, and roughly 70 render path updates. Just for one product.
The validation tool runs 16 automated checks against the repository to catch build-breaking issues without needing to run the actual site build. It detects stale product references, missing redirects, broken internal links, missing SVG icons, and more. It auto-detects which products have been renamed on the current branch and scopes its checks accordingly.
The image scanner uses the AI model's vision capability to scan documentation screenshots for outdated product names. It categorises images by type, resizes oversized ones (to avoid exceeding the AI memory limits), renders vectorized SVGs to PNG for visual review, and generates a full audit report.
The cleanup tool is designed to run 6 months from now to strip out all the "(formerly Old Name)" bridge phrasing once users have had time to learn the new names. There are roughly 300 of those instances across all products.

After the project-specific tools were built, I also created generic versions of the rename and image audit tools, usable by anyone for any product rename, not just this specific project. They replace hardcoded product rules with interactive questions.

Catching what humans miss: rename validation

The validation tool was one of the most valuable things I built. A product rename touches so many different file types and structures that a single missed reference can crash the build. Running the full Astro build to find out if there are issues takes time, and discovering a problem after the fact (after you have already opened a pull request and other people are waiting) is frustrating.

The tool runs 16 checks, each with a severity level:

BUILD: The site build will crash. A stale product ID in frontmatter, a changelog folder that does not match its YAML definition, a missing SVG icon.
RUNTIME: The build succeeds but the UI breaks. A component prop referencing a product ID that no longer exists.
CORRECTNESS: Wrong content served to users. A cross-reference link that still points to the old URL path, an anchor link that broke because a heading was renamed.
COSMETIC: Minor issues, no user-visible breakage. A leftover mention of the old name in a code comment.

Across all renames, the validator verified that roughly 80 API and CLI field names were correctly preserved in code blocks, that over 110 changelog historical prose entries were left unchanged, and that edge cases like Terraform resource names and community channel names were not accidentally renamed. For one product alone, 16 safe-list items were verified, with zero accidental renames of things that should have stayed the same.

The practical value is straightforward: instead of waiting for a slow build to tell you what broke, the validator can give you the same answer in seconds.

The tool that makes me proud: image recognition

This one came about from a question from another writer: "are we the ones that need to check the images the rename tool flagged?" Initially yes: the rename tool only found images referenced in the product and flagged them for manual review. But there were hundreds of images across all products, and manually checking each one was not realistic. So I started thinking: what if the AI could scan the images itself and tell us which ones actually needed an update?

Opus 4.6 can read images. So I built a command that feeds documentation screenshots to its vision capability and asks it to check for specific text in UI elements: sidebar navigation, page headers, breadcrumbs, tab labels, buttons, tooltips, and the URL bar.

The tool handles the practical challenges that come with scanning images at scale:

It finds all image references across documentation pages and reusable content partials, deduplicates them, and maps each image back to the pages that use it.
It triages images by type. Dashboard UI screenshots are scanned first (high priority). Third-party vendor integration screenshots are flagged for the user to decide (they show vendor UIs, not the documentation site's own product names). Hardware photos are deprioritized. SVG diagrams are text-searched with grep first, then visually scanned if needed.
Oversized images are automatically resized because the model has resolution limits.
Results come in batches of 10, with progress reports and the option to stop and resume.

In total, the tool processed 486 images. Of those, 310 were visually scanned by the AI, and 67 were flagged as needing a graphical update.

For the largest product rename alone, 279 images were scanned at 100% coverage. 55 needed updates, 224 were clean. The scan found old names in places I would not have thought to look, including dozens of third-party vendor integration screenshots with the old product name embedded in firewall object names, configuration labels, and network diagrams. 17 reference architecture SVGs contained the old names in diagram labels and topology views.

Two findings stand out.

First, all 113 SVGs in the scan were fully vectorized. That means grep and text search were completely ineffective. The old product names were baked into vector path data, not searchable text nodes. The only way to find them was to render the SVGs to PNG and have the AI read them visually. Without this tool, those 113 images would have been silently skipped, and users would see outdated names in architecture diagrams indefinitely.

Second, filename-based scanning gave a false sense of coverage. Among one set of vendor integration images, 33 had the old product name in their filename, but only 11 of those actually showed old names in the visible UI. Meanwhile, 10 additional images without the old name in their filename also contained old names. They were only found by the full visual scan.

After flagging, disclaimer notes were automatically added to all affected images' documentation pages, letting readers know the screenshots are pending a graphical update.

The safety net: a redirect validator

Renaming URLs across a large documentation site means hundreds of redirects. Getting even one wrong means a user hits a 404 from a bookmark, a search engine result, or a link in another product's docs.

For this I built something different: a standalone Python CLI tool, separate from the AI-powered commands. Redirect validation is deterministic. You do not need AI for "does this URL return 200?" You need a script that checks every URL methodically and reports what failed.

The tool has four stages that mirror the project workflow:

Scrape: Before any renames start, capture all current live URLs from the site using the sitemap. This creates a baseline of what exists today.
Compare: Cross-reference the baseline against a CSV mapping file that maps old URLs to new URLs. This finds gaps: URLs that exist on the live site but are not in the mapping, which means they would be missed during the rename.
Validate preview: Before merging a rename pull request, test against the preview deployment. The tool checks that all new URLs return 200 and all old URLs redirect (301) to the correct new URLs. It supports per-product filtering, so each writer can validate their own rename independently.
Validate production: After merging, run the same checks against the live site to confirm everything works.

The CSV mapping file contained 349 URL mappings across all products. 71 redirect rules were added or updated, covering three types: dynamic splat redirects for entire product sections, static redirects for individual pages with renamed slugs, and updated destinations for existing rules that pointed to URLs being renamed.

The tool also supports resuming from interruption, configurable request delays to avoid hammering the server, and JSON reports for each run.

What the AI suggested that I had not considered

The AI was helpful beyond executing instructions. In several cases it suggested design decisions I had not thought of.

Batch mode was one. The AI suggested splitting each rename into content updates first (on the original filenames, so diffs are clean and easy to review), then structural changes (folder renames and redirects) in a separate commit. This makes the pull request reviewable; you can see exactly what text changed without file renames cluttering the diff.

The two-pass approach was another. Separating product-owned files from cross-references was the AI's suggestion. It was initially designed to avoid merge conflicts, but as the project progressed its real value turned out to be producing more granular merge commits instead of one with hundreds of changes. And because the rename took so long to run, smaller commits also meant smaller chunks of work to review.

Severity classification in the validator was also AI-driven. Not all failures are equal: a missed rename in the middle of one page is not the end of the world, but a stale YAML reference crashes the build. Categorizing them lets you prioritize.

Image triage categories came from the AI too. Prioritizing dashboard screenshots over third-party vendor UIs was a practical suggestion that saved scanning time.

The AI also made mistakes. Early versions of the rename command changed redirect source URLs, the thing you must never change, because that is the URL that external links and bookmarks point to. It also missed that a sub-product should rename alongside its parent product. It had to be taught the distinction between two products that had similar names but completely different underlying implementations. Each mistake became a rule in the command, making the next rename more reliable.

From project-specific to reusable

After the project, I extracted the project-specific logic and created generic versions of the rename and image audit tools. The generic rename tool replaces hardcoded product tables with a series of questions: what is the old name, what is the new name, what terms should not be changed, are there related terms to rename alongside, what are the URL paths, has the dashboard been updated yet.

Anyone facing a similar large-scale documentation rename can use these tools by providing their own answers instead of needing to understand the specifics of a particular project.

Tools emerge from doing the work

After working with AI tools for a while, I am always thinking of that next tedious, large-scale documentation task, and how AI can help with building a reusable workflow. This project is what happens, I think, from taking my own advice. Not one command, but six tools, a standalone Python validator, and a workflow that made it possible to rename four products in three days.

The tools were not designed upfront. The image scanner was born when I realized I could not easily search screenshots. The validator came from a failed build caused by a missed YAML reference. The redirect tool came from the fear of breaking hundreds of bookmarks. Each problem, encountered during execution, became a conversation with AI, and each conversation became a tool.

In three days: 695 files touched, 71 redirects added, 486 images audited, 349 URL mappings verified. The tools did not just save time; they made the project feasible. Without them, this would have been weeks of error-prone manual work.

You do not need to plan an entire toolkit upfront. Start solving the immediate problem. As new problems come up, keep chatting with the AI. The tools will emerge naturally, and they will be better for it, because they are shaped by real needs, not hypothetical requirements.