DocHub Starlight Migration — Project Brief

This is the primary brief for migrating iSu Technologies’ DocHub from MkDocs Material to Starlight (Astro). Read this file completely before taking any action. The canonical technical reference for how to migrate is TECHNICAL_DESIGN_DOCUMENT.md at the repo root. This brief defines project execution — staging, scope, conventions, guardrails, and decisions that the design document does not cover.

Project summary

Migrate isutech-knowledge-hub from MkDocs Material 9.6.23 to Astro Starlight, preserving all 251 markdown documents, all current functionality, and all live URLs at https://docs.isutech.co.za.

The migration is the only project in scope. Content reorganisation, category consolidation, knowledge-base typing, and structural refactors are explicitly out of scope and deferred. The single content-shaping activity included here is adding lifecycle metadata frontmatter during the file-by-file migration pass — because every file is being touched anyway, the marginal cost is small.

Canonical sources

TECHNICAL_DESIGN_DOCUMENT.md — authoritative for migration approach, feature parity mapping, theme porting, component creation, build integration, and Starlight specifics. Section 11.3 (“Migration to Starlight”) is the migration playbook. Section 4 (“Feature & Function Specifications”) defines what must be preserved.
This brief — authoritative for project staging, scope boundaries, lifecycle metadata schema, URL preservation policy, and review gates.
When the two conflict: defer to the design document for what to do; defer to this brief for how the project runs. Flag any conflict in _migration-notes.md rather than resolving silently.

Non-negotiables

These decisions are made. Implement faithfully; do not revisit.

Target platform: Astro Starlight. No alternative platforms re-evaluated during this project.
Folder structure preserved: All 21 top-level content directories (docs/00-INDEX/, docs/about/, docs/products/, etc.) keep their names and contents. No reorganisation, consolidation, or splitting.
All 251 files migrate. Nothing is removed during this migration. Content judgement (what’s stale, what’s redundant) is out of scope.
Live URLs preserved. Every https://docs.isutech.co.za/... URL that exists today resolves after migration — either to the same content at the same path, or via redirect to the new path. No exceptions.
Branch-per-stage workflow. Every stage runs on its own branch (migrate/stage-N-description), is previewed via astro dev and astro build, awaits explicit human sign-off, and merges to main before the next stage branches.
Never work on main directly.
Preserve git history via git mv for every file move. Never delete-and-recreate.
The current MkDocs site stays live until the final stage’s deployment cutover. Production at docs.isutech.co.za is not touched until Stage 7.
update-frontpage.py automation must survive. The Python script that generates hero stats and “What’s New” cards is critical custom automation. Adapt it for Starlight’s src/content/docs/index.md rather than removing it.
No content rewrites. Adding required frontmatter is in scope. Editing prose, fixing what looks like outdated information, or “improving” wording is not.
Production resource validation before any production-touching work. Stage 7 cannot begin until disk space, memory, and CPU headroom on production-server-01 are confirmed sufficient for the new Node.js + Astro build pipeline (see Stage 7 pre-cutover checklist).

Scope clarifications

In scope

Astro project initialisation alongside existing MkDocs setup
All 251 markdown files moved to src/content/docs/ with required Starlight frontmatter
Content Collections schema definition with Zod validation (this brief specifies it; design document does not)
Sidebar configuration in astro.config.mjs matching current mkdocs.yml nav structure (13 sections, 100+ pages)
Theme port: 6 CSS custom properties + selected critical custom classes (not all 1,256 lines verbatim — Starlight’s theming approach is simpler)
Custom Astro components for hero, metrics, timeline, ROI calculator, tech stack, testimonial — to replace the MkDocs custom HTML/CSS equivalents
update-frontpage.py adaptation for Starlight’s index.md location and marker-comment format
Pagefind search configuration (Starlight built-in)
Mermaid diagram support
Light/dark mode preservation with the gold accent palette
Edit-on-GitHub link configuration
Lifecycle metadata frontmatter installed during the file-by-file pass (schema defined below)
URL preservation strategy: an audit + redirects map for any path that changes
Build pipeline migration: update-docs.sh adapted for npm run build instead of mkdocs build
Nginx config update: root directive points to dist/ instead of site/
DEPLOYMENT_CHECKLIST.md and MAINTENANCE_GUIDE.md updates reflecting new stack

Out of scope (explicitly deferred)

Content reorganisation of any kind
Category consolidation (the business-analysis/ ↔ business-development/ ↔ sales-enablement/ cluster)
Knowledge-base typing into post-mortems / decision-records / playbooks / etc.
Adding partners/, delivery/, or other new top-level domains
Document versioning (the mike equivalent in Starlight)
i18n / multi-language support
Algolia DocSearch evaluation (Pagefind built-in is the choice)
GitHub Actions CI/CD migration (cron stays as the build trigger)
Auth-per-section activation
ConformEdge or other product repo integration
Any work on the all-business repo

If something arises during migration that suggests one of the above is necessary, flag it in _migration-notes.md as [OUT OF SCOPE — DEFER] and proceed without it.

Lifecycle metadata schema

This is the single content-shaping activity included in the migration. Every file gets this frontmatter during its migration pass.

Required Starlight fields

title: <Human-readable page title — derive from H1 if absent, ask if H1 is also absent>
description: <One-sentence summary, under 160 characters — derive from first paragraph if not specified>

iSuTech lifecycle fields (added by this migration)

owner: Nhlanhla
last_reviewed: 2026-04-25       # the migration date for migrated content
review_cadence: quarterly        # weekly | monthly | quarterly | annually | none
status: current                  # draft | current | outdated | archived
tags: []                         # leave empty for migrated content; populate organically over time

Defaults to apply during migration

owner: Nhlanhla for every file unless an existing author or owner field is present
last_reviewed: 2026-04-25 for every migrated file (or substitute the actual migration date)
review_cadence: quarterly as universal default
status: current for every file unless its content explicitly references events more than 18 months stale, in which case status: outdated (do not delete or rewrite — just flag)
tags: [] (intentionally empty; populating tags is a separate post-migration activity)

Content Collections schema (Zod)

Define this in src/content/config.ts:

import { defineCollection, z } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({
    schema: docsSchema({
      extend: z.object({
        owner: z.string().default('Nhlanhla'),
        last_reviewed: z.date().optional(),
        review_cadence: z.enum(['weekly', 'monthly', 'quarterly', 'annually', 'none']).default('quarterly'),
        status: z.enum(['draft', 'current', 'outdated', 'archived']).default('current'),
        tags: z.array(z.string()).default([]),
      }),
    }),
  }),
};

The schema extends Starlight’s built-in docs schema rather than replacing it — this preserves Starlight’s own frontmatter handling (sidebar config, hero, etc.) while adding iSuTech’s lifecycle layer.

Migration policy for existing frontmatter

Where existing files have title:, keep it
Where existing files have other Starlight-recognised fields (description:, lastUpdated:, template:), keep them
Where existing files have iSuTech-specific fields not in this schema, log them in _migration-notes.md as [FRONTMATTER REVIEW] and ask before discarding
Where existing files have no frontmatter at all, add the full schema with defaults

URL preservation

The design document does not fully address this; this brief specifies the policy.

MkDocs → Starlight URL behaviour

MkDocs default: docs/foo/bar.md renders at /foo/bar/ (with use_directory_urls: true, which is the default and is configured in this repo)
Starlight default: src/content/docs/foo/bar.md renders at /foo/bar/
Outcome: most paths are preserved without intervention

Cases requiring redirects

README.md → index.md rename: MkDocs renders docs/products/conformedge/README.md at /products/conformedge/. Starlight renders src/content/docs/products/conformedge/index.md at the same URL. The path-after-rename is identical — no redirect needed if the rename is the only change.
Any file Starlight slugifies differently: if Starlight’s slug rules differ from MkDocs’ (e.g. uppercase characters, special characters in filenames), the new URL must redirect to from the old.
docs/index.md → src/content/docs/index.md: serves at /, no redirect needed.

Required deliverable

Stage 4 produces _migration-notes.md entry URL AUDIT listing every URL that is not preserved verbatim, along with the redirect that handles it. Stage 6 implements those redirects in nginx (preferred — single point of truth, runs before any application logic) or in Astro config if nginx redirects are not feasible.

Verification gate

Stage 7 cannot complete until a sample of 30 representative URLs (selected to cover all 13 sidebar sections) all resolve correctly post-cutover. The sample list is generated in Stage 0 audit.

Stages

The migration runs in seven stages. Each is a separate branch, previewed, reviewed, merged. The next stage branches from updated main.

Stage 0 — Audit and baseline

Branch: migrate/stage-0-audit

Goal: Understand current state precisely before any changes.

Deliverables:

_migration-notes.md at repo root — working log file for the entire migration
STAGE_0_AUDIT.md at repo root — comprehensive audit report

Audit must cover:

Confirmed file count (target: 251 from design document — flag any discrepancy)
Per-directory file count (all 21 top-level dirs)
Frontmatter inventory: which files have what frontmatter fields, which have none
Custom MkDocs syntax inventory: count of !!! note-style admonitions, === "Tab" content tabs, :material-icon: icon references, <div class="grid cards"> blocks, mermaid blocks
Custom CSS class usage: scan docs/**/*.md for any class="..." attributes and produce a frequency-ranked list (this informs which custom classes need Astro components)
URL inventory: every URL the current build produces, derived from mkdocs.yml nav and file structure — this becomes the verification baseline
Sample URL set for Stage 7 verification: 30 URLs covering all sections
External links audit: count of external URLs in content (don’t fix; just count)
Asset inventory: images, files, anything in docs/assets/
Estimated migration risk per directory (low/medium/high) based on custom syntax density
Production resource advisory (early-warning): SSH to production-server-01 and run a read-only check of available disk, memory, swap, CPU cores, and current Node.js version. The full pre-cutover validation happens at Stage 7, but surfacing severe constraints now (e.g. less than 2 GB free disk, no swap, no Node.js installed) lets the human resolve them in parallel with the rest of the migration rather than discovering them at cutover. Use the Stage 7 thresholds as the reference. Record findings in _migration-notes.md under STAGE 0 — PRODUCTION RESOURCE ADVISORY. Flag any failure as [ADVISORY — RESOLVE BEFORE STAGE 7]. Do not modify production. Read-only checks only.

No content changes in this stage. Audit only.

Exit criteria: Human reviews STAGE_0_AUDIT.md and approves Stage 1 to proceed.

Stage 1 — Astro project initialisation alongside MkDocs

Branch: migrate/stage-1-astro-init

Goal: Stand up a working Starlight project in the repo without touching MkDocs.

Deliverables:

package.json at repo root with Astro and Starlight dependencies
astro.config.mjs with minimal Starlight integration (no sidebar yet)
tsconfig.json for Astro/TypeScript
src/content/config.ts with the Content Collections schema specified above
src/content/docs/index.md — placeholder page so astro dev runs
src/styles/custom.css — empty placeholder, ready for theme port
.gitignore updated to exclude node_modules/, dist/, .astro/
npm install, npm run dev, and npm run build all succeed locally
MkDocs setup remains untouched and continues to work
_migration-notes.md entry recording any deviations from TECHNICAL_DESIGN_DOCUMENT.md Section 11.3 Step 1

No content migration in this stage. Plumbing only.

Exit criteria: astro dev serves the placeholder page, astro build produces dist/ output, MkDocs build still works. Human reviews and approves.

Stage 2 — Content migration (the big stage)

Branch: migrate/stage-2-content

Goal: Move all 251 files into src/content/docs/ with required frontmatter and lifecycle metadata.

This is the largest stage. Take it in directory-sized batches; commit each batch separately so review and rollback are tractable.

Process per batch (one top-level directory at a time):

Identify files in source directory
For each file:
- Determine target path: docs/{dir}/{file}.md → src/content/docs/{dir}/{file}.md
- Rename README.md → index.md if applicable
- git mv to preserve history
- Apply frontmatter: required Starlight fields + iSuTech lifecycle fields per schema
- Convert !!! note-style admonitions to :::note Starlight Asides
- Convert === "Tab" content tabs to <Tabs> + <TabItem> (if present — only converts files using .mdx extension; defer decision until needed)
- Convert :material-icon: references to Starlight <Icon name="..." /> where the file is being upgraded to MDX, otherwise leave as text and flag in _migration-notes.md
- Custom HTML/CSS classes: leave in place; Stage 5 ports them to Astro components
Commit batch with message feat(content): migrate {dir-name} to src/content/docs (N files)
Run astro build after each batch — surface any schema validation errors immediately
Log batch completion in _migration-notes.md

Order of batches (lowest-risk first):

00-INDEX/ (7 files, mostly standards documents — low syntax complexity)
about/ (3 files)
assets/ (no migration needed — references update only)
case-studies/ (4 files)
document-templates/ (4 files)
sales-enablement/ (5 files)
marketing/ (10+ files)
operations/ (20+ files)
products/ (50+ files — largest single directory, do in sub-batches per product)
prospects/ (60+ files — second-largest, do in sub-batches per prospect)
Remaining directories
index.md and the update-frontpage.py markers — last, because the homepage references everything else

Out of scope in this stage:

Custom Astro component creation (Stage 5)
Custom CSS theme port (Stage 5)
Sidebar configuration (Stage 3)
update-frontpage.py adaptation (Stage 6)

Exit criteria: All 251 files in src/content/docs/, every batch committed separately, astro build succeeds with no schema validation errors. MkDocs site still builds (the source docs/ is being moved, so MkDocs will fail at the end of this stage — that’s expected; the cutover gate is Stage 7). Human reviews migration log and approves.

Branch: migrate/stage-3-navigation

Goal: Convert mkdocs.yml nav (13 sections, 100+ entries) to astro.config.mjs sidebar configuration.

Deliverables:

astro.config.mjs sidebar matching current MkDocs nav structure exactly
Use autogenerate: { directory: '...' } for directories with stable contents (e.g. products/, prospects/)
Use explicit items: [...] for sections requiring custom ordering (e.g. 00-INDEX/)
Verify every page reachable via sidebar in astro dev
Edit-on-GitHub link working (Section 11.3 Step 2 of design document)

Exit criteria: Sidebar in dev preview matches MkDocs nav; clicking through 30-URL sample set works. Human reviews and approves.

Stage 4 — URL preservation and redirects

Branch: migrate/stage-4-urls

Goal: Audit URL changes between MkDocs build and Starlight build; produce redirects for every difference.

Deliverables:

Run mkdocs build against the original docs/ (kept on this branch via git) to produce the reference URL set
Run astro build to produce the Starlight URL set
Diff the two; produce _migration-notes.md entry URL AUDIT listing every difference
For each difference, define the redirect (old URL → new URL)
Implement redirects in deployment/nginx-docs.conf as rewrite rules (preferred) or in astro.config.mjs if nginx is not feasible for a particular case
Verify all 30 URLs from sample set resolve correctly via curl against a local nginx instance pointing at dist/

Exit criteria: URL audit complete, redirects in place, sample URLs verified locally. Human reviews and approves.

Stage 5 — Theme, components, and visual fidelity

Branch: migrate/stage-5-theme

Goal: Port branding and custom components.

Deliverables:

src/styles/custom.css with the 6 CSS custom properties (gold palette per design document Section 5)
Critical custom classes ported (those that appear in 5+ files per Stage 0 audit; others can be addressed reactively)
Custom Astro components created for: Hero, MetricCard, Timeline, ROICalculator, TechStack, Testimonial (per design document Section 11.3 Step 6)
Light/dark mode toggle working with gold accent palette
Mermaid integration installed and tested with one diagram from existing content
Logo asset moved from docs/assets/images/isutech-logo.png to src/assets/isutech-logo.png and referenced in astro.config.mjs
Visual diff check: pick 5 pages with rich custom HTML, screenshot MkDocs vs Starlight side by side, log differences in _migration-notes.md

Out of scope: pixel-perfect parity with the 1,256-line MkDocs CSS. Starlight’s theming is simpler and the design document explicitly calls this out as an advantage. Aim for brand fidelity (colours, fonts, accent), not selector-by-selector replication.

Exit criteria: Branded preview matches iSuTech identity, key custom components render, no obvious visual regressions on sampled pages. Human reviews and approves.

Stage 6 — Build pipeline and `update-frontpage.py`

Branch: migrate/stage-6-pipeline

Goal: Adapt the deployment automation for Starlight.

Deliverables:

deployment/update-docs.sh rewritten to run npm ci --production && npm run build instead of mkdocs build
deployment/update-frontpage.py adapted to target src/content/docs/index.md instead of docs/index.md, with marker-comment format compatible with Starlight’s frontmatter (the Python script must not corrupt YAML frontmatter when splicing content)
deployment/update-frontpage.py tested in --dry-run mode against the new index file
deployment/nginx-docs.conf updated: root directive points to /var/www/docs/repo/dist/ (was /var/www/docs/repo/site/)
Redirects from Stage 4 incorporated into the new nginx config
requirements.txt retained (the Python script still needs its dependencies)
package.json build scripts finalised
deployment/MAINTENANCE_GUIDE.md updated to reflect Node.js installation, npm caching, and new build commands
deployment/DEPLOYMENT_CHECKLIST.md updated with Starlight-specific checks

Cutover plan section added to _migration-notes.md:

Pre-cutover: Node.js installed on production server, npm ci cached, smoke-test build
Cutover: nginx reload with new config + symlink swap
Rollback: previous nginx config saved, can revert in under 60 seconds

Out of scope: actually running the new pipeline on production. That’s Stage 7.

Exit criteria: Build pipeline tested locally end-to-end, update-frontpage.py produces a valid Starlight index.md, nginx config dry-run validates. Human reviews and approves.

Stage 7 — Production cutover

Branch: migrate/stage-7-cutover

Goal: Switch docs.isutech.co.za from MkDocs to Starlight.

This stage involves production. It runs only after every preceding stage is merged and reviewed.

Pre-cutover checklist:

All preceding stages merged to main
Production resource pre-flight passed (mandatory — see below)
Production server has Node.js 20+ installed
Production server has cached npm ci install (test run)
Backup of current MkDocs site/ directory taken
Backup of current nginx-docs.conf taken
Maintenance window communicated (if relevant)

Production resource pre-flight (mandatory):

Before any production work, Claude Code must SSH to production-server-01 and verify the server has sufficient resources for the new stack. Document findings in _migration-notes.md under STAGE 7 — RESOURCE PRE-FLIGHT.

Required checks and minimum thresholds:

Resource	Command	Minimum required	Reason
Free disk space (root or `/var/www`)	`df -h /var/www`	5 GB free	`node_modules/` for Starlight is ~400–600 MB; build output `dist/` is ~50 MB; npm cache is ~200–400 MB; safety margin for builds, logs, backups
Free disk space (where `npm` cache lives, usually `~/.npm`)	`df -h ~`	2 GB free	npm cache grows over time; Astro/Starlight pulls many transitive deps
Total RAM	`free -h`	2 GB total minimum, 4 GB recommended	Astro builds are memory-intensive vs MkDocs (Vite/esbuild + TypeScript compilation)
Free RAM during build	`free -h` (run during a test build)	1 GB free during build	Astro build of 250+ docs can spike memory usage
Swap configured	`swapon --show`	At least 2 GB swap	Safety net for build-time memory spikes if RAM is tight
CPU cores	`nproc`	2+ cores	npm install + Astro build benefit from parallelism
Node.js installed	`node --version`	v20.x or v22.x	Astro 4+ requires Node 18.17.1+ or 20.3.0+; Node 20 LTS recommended
npm installed	`npm --version`	v10+	Comes with Node 20
Inodes available	`df -i /var/www`	At least 100k free inodes	`node_modules/` creates many small files; some filesystems can exhaust inodes before bytes
Existing build artefacts disk usage	`du -sh /var/www/docs/repo/site/`	(informational)	Document current footprint for comparison

If any check fails, stop and flag in _migration-notes.md as [BLOCKER — PRODUCTION RESOURCE INSUFFICIENT]. Do not proceed with cutover. Resolution options to propose to the human:

Extend Hetzner volume (CAX21 has known limits — verify with lsblk and Hetzner console)
Upgrade to a larger Hetzner plan (CAX31 or CCX-series)
Move node_modules/ to a different volume via symlink
Configure swap if not present
Set Node --max-old-space-size=2048 flag if memory is tight (slower builds but works)

Test build on production before cutover:

Once resource checks pass, run a full test build on production server before swapping nginx config:

cd /var/www/docs/repo
git pull origin main (latest with all migration stages merged)
npm ci — verify install completes; note time and disk impact
npm run build — verify build completes; note time, peak memory, and final dist/ size
Compare metrics to expected (~15–25s build, ~50 MB dist/)
Run du -sh node_modules/ dist/ ~/.npm/ to confirm actual disk impact
Document all measurements in _migration-notes.md

If the test build fails or exceeds resource budgets, abort cutover and address the resource issue before retrying.

Cutover sequence:

SSH to production server
cd /var/www/docs/repo && git pull origin main
Run new update-docs.sh manually — verify dist/ is produced
Verify dist/ size and content sanity
Reload nginx with new config: sudo nginx -t && sudo systemctl reload nginx
Run smoke tests against all 30 URLs in the sample set
Verify search works (Pagefind index built)
Verify dark mode toggle
Verify edit-on-GitHub links resolve
Update cron entry if the script path or arguments changed
Monitor /var/log/nginx/docs-error.log for 30 minutes post-cutover

Post-cutover within 24 hours:

Remove old MkDocs build artefacts (site/ directory)
Archive old mkdocs.yml, requirements.txt MkDocs entries to a legacy/ folder rather than deleting (history preservation)
Update TECHNICAL_DESIGN_DOCUMENT.md to reflect new live stack: change “Current Stack (MkDocs Material)” section to “Current Stack (Astro Starlight)”; move MkDocs detail to a “Previous Stack” section
Update README.md with new build instructions
Tag the migration commit: git tag -a v2.0-starlight -m "DocHub migrated from MkDocs Material to Astro Starlight"

Rollback plan:

If cutover fails: restore previous nginx-docs.conf, nginx -s reload, restore old site/ from backup, MkDocs site is live again
Decision criteria for rollback: any production URL returning 5xx for more than 5 minutes, or sample URL set failing more than 10% of checks

Exit criteria: Production live on Starlight, monitored for 24 hours with no significant incidents, sample URL set passing, search working. Human approves project closure.

Guardrails

Things Claude Code must NOT do

Touch production directly during stages 0–6. Production stays on MkDocs until Stage 7’s cutover.
Delete content. No file removal during migration.
Modify content prose. Frontmatter additions are in scope; editing paragraphs is not.
Reorganise content. No moves between top-level directories.
Skip the per-stage review gate. Every stage requires explicit human approval before the next begins.
Work on main directly.
Bundle multiple stages on one branch.
Resolve apparent contradictions between this brief and TECHNICAL_DESIGN_DOCUMENT.md silently. Flag them in _migration-notes.md and pause.
Substitute alternative platforms. Starlight is the chosen target.
Touch other repos (all-business, ConformEdge, etc.).

Things Claude Code should flag

Add [QUESTION], [FRONTMATTER REVIEW], [OUT OF SCOPE — DEFER], [RISK], or [STAGE GATE] entries in _migration-notes.md for:

Any file with frontmatter fields not in the defined schema
Any file with content that fails Zod validation in unexpected ways
Any custom MkDocs syntax not covered by the design document’s parity mapping
Any URL that cannot be preserved or redirected cleanly
Any production-cutover risk surfaced during preparation
Any update-frontpage.py behaviour that doesn’t translate cleanly to Starlight’s marker-comment expectations
Any architectural decision that would deviate from TECHNICAL_DESIGN_DOCUMENT.md

Batch questions per stage. Don’t pause work for every individual question — collect them and present at stage gate.

Session start prompt for the human to use

When opening a Claude Code session for this migration, the human will paste:

I’m working on the DocHub Starlight migration. Read these in order:

MIGRATION_BRIEF.md at the repo root (this brief)

TECHNICAL_DESIGN_DOCUMENT.md at the repo root (canonical technical reference)

_migration-notes.md at the repo root (working log — may not exist yet on Stage 0)

Then tell me:

Which stage we’re on

What’s been completed

What the next action should be

Any blockers, questions, or decisions awaiting human review

Wait for my explicit instruction before acting.

Success criteria for the whole project

All 251 files live on Starlight at https://docs.isutech.co.za
Every URL preserved (verbatim or via redirect)
Search works (Pagefind)
Dark mode works
Edit-on-GitHub links work
Mermaid diagrams render
iSuTech gold-accent branding visible
Lifecycle metadata frontmatter present on all files
Cron-based 10-minute auto-deploy continues working
update-frontpage.py continues generating hero stats and What’s New cards
TECHNICAL_DESIGN_DOCUMENT.md updated to reflect live stack
No content lost
No prolonged downtime during cutover
Rollback path tested and documented
Permanent record of migration available for future reference

What’s out of scope (reiterated for clarity)

Content reorganisation
Category consolidation
Knowledge-base typing
Document versioning
Search provider change beyond Pagefind
CI/CD migration to GitHub Actions
Tag population (schema includes the field; populating is a separate post-migration activity)
Any work on other iSuTech repos
ConformEdge integration
i18n
Auth-per-section activation

If reality during execution suggests any of these are necessary, flag and defer; do not expand scope.

This brief is the contract for project execution. The design document is the contract for technical approach. If reality differs from either, log the discrepancy in _migration-notes.md and stop for human review.

Last updated: 2026-04-25 by Nhlanhla (drafted with Claude)

DocHub Starlight Migration — Project Brief

DocHub Starlight Migration — Project Brief

Project summary

Canonical sources

Non-negotiables

Scope clarifications

In scope

Out of scope (explicitly deferred)

Lifecycle metadata schema

Required Starlight fields

iSuTech lifecycle fields (added by this migration)

Defaults to apply during migration

Content Collections schema (Zod)

Migration policy for existing frontmatter

URL preservation

MkDocs → Starlight URL behaviour

Cases requiring redirects

Required deliverable

Verification gate

Stages

Stage 0 — Audit and baseline

Stage 1 — Astro project initialisation alongside MkDocs

Stage 2 — Content migration (the big stage)

Stage 3 — Sidebar and navigation

Stage 4 — URL preservation and redirects

Stage 5 — Theme, components, and visual fidelity

Stage 6 — Build pipeline and update-frontpage.py

Stage 7 — Production cutover

Guardrails

Things Claude Code must NOT do

Things Claude Code should flag

Session start prompt for the human to use

Success criteria for the whole project

What’s out of scope (reiterated for clarity)

Stage 6 — Build pipeline and `update-frontpage.py`