Topic-first migration master plan

Topic-first migration master plan

0. How to use this file

This is the single source of truth for the full ZajLibrary topic-first migration.

Read protocol:

• Read this file before starting or resuming any migration slice.
• Trust live code and generated reports over old prose if they disagree.
• Patch this plan in place when reality changes; do not create parallel migration plans.

Write protocol:

• Mark task status as work progresses.
• Append revision-log entries at the bottom.
• Do not delete tasks. Mark them superseded if a better route replaces them.
• Do not hard-delete files during migration; archive obsolete helpers or docs.

Verification protocol:

• Every slice ends with verify gates, a working-flow demonstration, a git diff summary, and next-slice readiness.
• No worker owns final integration. The orchestrator reviews all worker output before merge or commit.
• No old URL redirects are allowed unless Malek explicitly reverses the hard-cutover decision.

1. Sequence at a glance

#	Task	Est	Plan-mode?	Status
0	Preflight and create this canonical plan	20 min	done	✅ done
1	Apply five CodeCanyon touch-up trims	30 min	no	✅ done
2	Create taxonomy registry	45 min	no	✅ done
3	Generate migration map and rewrite script	1-2 hr	no	✅ done
4	Move docs and rewrite frontmatter	1-2 hr	no	✅ done
5	Rewrite links and update nav/Browse/MCP/search	1-2 hr	no	✅ done
6	Final verification, browser proof, and local commits	45-90 min	no	✅ done

2. Naming and conventions

Target path shape:

app/src/content/docs/<category>/<subcategory>/<topic>/<shelf>/<kind>/...

Public URL shape:

/<category>/<subcategory>/<topic>/<shelf>/<kind>/...

Complete end state:

• All published docs live in topic-first paths.
• No active redirects exist for old shelf-first or /collections/ URLs.
• Nav, Browse, category/subcategory pages, search, MCP, sitemap, copy-as-prompt, and inbox rules all read the new topic-first model.
• Obsolete redirect helpers, old _meta.yaml, and provenance files are archived, not deleted.

Key final examples:

app/src/content/docs/tech-stack/laravel/codecanyon/index.mdx
app/src/content/docs/tech-stack/laravel/codecanyon/build/playbooks/setup-new/index.mdx
app/src/content/docs/tech-stack/laravel/codecanyon/build/playbooks/setup-new/03-local-dev/01-dependencies-assets.mdx
app/src/content/docs/tech-stack/laravel/codecanyon/resources/templates/deployment/01-deployer.mdx

app/src/content/docs/infrastructure/hosting/shared-hosting/index.mdx
app/src/content/docs/infrastructure/hosting/shared-hosting/learn/guides/setup-shared-hosting.mdx
app/src/content/docs/infrastructure/hosting/shared-hosting/build/playbooks/setup-shared-hosting/index.mdx

app/src/content/docs/zajlibrary/authoring/content-system/resources/reference/writing-style.md
app/src/content/docs/zajlibrary/system/platform/resources/reference/platform-architecture.md

Locked decisions:

• Slugs are lowercase.
• Topic-first is canonical.
• Hard cutover: old shelf-first URLs do not redirect.
• collection is legacy metadata during the migration, not the final IA axis.
• Commit footer: Agent: Codex-Jules-20260613.

3. Per-task plans

Task 1 — CodeCanyon content trims

Technical why: land known low-risk content corrections before the path move, so line-level edits do not get buried in migration churn.

Plain-English why: fix the five small leftovers first while the files are still easy to find.

Files touched:

• app/src/content/docs/tech-stack/laravel/codecanyon/build/playbooks/setup-new/10-audit-qa/03-performance-db-seo.mdx
• app/src/content/docs/tech-stack/laravel/codecanyon/build/playbooks/setup-new/11-pre-customer/01-technical-readiness.mdx
• app/src/content/docs/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/01-prerequisites.mdx
• app/src/content/docs/tech-stack/laravel/codecanyon/build/playbooks/setup-new/09-growth-polish/02-engagement.mdx

Exit criteria:

Gate	Required result
Verify gates	python3 scripts/playbook-step-contract.py app/src/content/docs/tech-stack/laravel/codecanyon/build/playbooks/setup-new passes; cd app && npm run build passes
Working flow	Touched pages build as Starlight pages and retain playbook-step structure
Git diff	Four content files changed only
Next readiness	Taxonomy registry can be created without pending CodeCanyon source trims

Task 2 — Taxonomy registry

Technical why: topic-first migration needs one controlled vocabulary for category, subcategory, topic, aliases, labels, and migration defaults.

Plain-English why: this prevents future “same thing, five names” drift.

Files touched:

• app/src/taxonomy.registry.yaml
• app/src/content.config.ts

Exit criteria:

Gate	Required result
Verify gates	Registry parses; topic field accepted by content schema
Working flow	Current major groups map to a canonical topic
Git diff	Registry + schema only
Next readiness	Migration map can reject unknown terms

Task 3 — Migration map and rewrite script

Technical why: Starlight routes docs from file paths, so every source file needs a deterministic destination before git mv.

Plain-English why: no mystery moves, no lost pages.

Files touched:

• scripts/topic-first-migration.mjs
• app/src/generated/topic-first-migration-map.json
• this canonical plan under app/src/content/docs/zajlibrary/authoring/content-system/resources/reference/content-architecture/

Exit criteria:

Gate	Required result
Verify gates	Dry run reports zero unmapped docs and zero duplicate destinations
Working flow	Old-to-new URL map includes every published Markdown/MDX doc
Git diff	Script + generated migration report
Next readiness	File move can run without manual decisions

Task 4 — File move and frontmatter rewrite

Technical why: the physical source tree must match the new URL and navigation model.

Plain-English why: the folders should look the way the library is meant to be understood.

Files touched:

• app/src/content/docs/**

Exit criteria:

Gate	Required result
Verify gates	New path audit passes after move
Working flow	Example CodeCanyon, shared-hosting, and ZajLibrary system paths exist
Git diff	git mv history-preserving file moves plus frontmatter updates
Next readiness	Link rewrite has a complete URL map

Task 5 — Links, navigation, Browse, MCP, and redirects

Technical why: Starlight, Browse, MCP, and search all derive URL and taxonomy behavior from code surfaces that currently assume shelf-first routes.

Plain-English why: moving files is not enough; readers and AI agents must land in the new structure everywhere.

Files touched:

• app/astro.config.mjs
• app/src/lib/taxonomy-routes.ts
• app/src/pages/browse/index.astro
• app/src/pages/categories/**
• app/src/pages/subcategories/**
• app/src/pages/collections/** or archived replacement
• app/scripts/build-mcp-index.ts
• app/src/routeData.ts
• redirect helper files, archived
• authoring/inbox docs and helper scripts

Exit criteria:

Gate	Required result
Verify gates	npm run doc:lint, npm run build, and npm run build:index pass
Working flow	/browse/ opens Category > Subcategory > Topic and old URL probe does not redirect
Git diff	Code/config/docs updates only, no deleted files
Next readiness	Final verification can run against one coherent IA

Task 6 — Final verification and local commits

Technical why: the full migration touches routing, generated indexes, docs content, and UI; all proof must run after integration.

Plain-English why: do not call this done until the site actually works locally.

Exit criteria:

Gate	Required result
Verify gates	content-path-audit, playbook-step-contract, doc:lint, build, and build:index pass
Working flow	Browser proof for /, /browse/, topic hubs, deep docs, MCP smoke, and old URL 404/no redirect
Git diff	Atomic commits with explicit pathspecs
Next readiness	Worktree clean except unrelated user/coworker changes

4. Stop-and-show bundle template

### Exit Bundle — Task <N>

1. Verify gates
   - <command>: <result>
2. Working flow
   - <route or command>: <observed result>
3. Git diff summary
   - <git diff --stat or commit SHA>
4. Next-task readiness
   - <ready/blocker>

5. Glossary

• Topic-first — category/subcategory/topic folders come before Learn/Build/Resources.
• Hard cutover — old URLs are not redirected; links must be rewritten.
• Registry — controlled list of accepted taxonomy slugs and labels.
• Migration map — old file/URL to new file/URL table used for moves and link rewrites.
• Worker — bounded helper agent; cannot own final integration decisions.

6. Revision log

• 2026-06-13 — Created canonical plan for centralized-swarm topic-first migration.
• 2026-06-13 — Landed CodeCanyon trims, taxonomy registry, migration map, hard-cutover file moves, nav/Browse/MCP/search rewrites, and authoring-rule updates.
• 2026-06-13 — Completed final gates: content path audit, playbook-step contract, doc lint, build, MCP index build, Playwright route proof for topic-first pages, and old URL 404/no-redirect proof.