Migrate documentation content to Starlight

[kmcginnes]

Parent PRD

• Part of Migrate documentation to Starlight (Astro) #1754

What to build

Migrate all 25 existing Markdown files from docs/ into the Starlight project at packages/docs/src/content/docs/. This is a content-only change — the project scaffold and config already exist from the previous task.

End-to-end, this means:

1. Move files into the Starlight content directory:
   • docs/getting-started/README.md → src/content/docs/getting-started/index.md
   • docs/features/README.md → src/content/docs/features/index.md
   • docs/features/*.md → src/content/docs/features/
   • docs/guides/README.md → src/content/docs/guides/index.md
   • docs/guides/*.md → src/content/docs/guides/
   • docs/references/README.md → src/content/docs/references/index.md
   • docs/references/*.md → src/content/docs/references/
   • docs/development.md → src/content/docs/references/development.md
   • docs/architecture.md → src/content/docs/references/architecture.md
   • docs/README.md → src/content/docs/index.mdx (landing page)
2. Add frontmatter to each file (at minimum title, derived from the existing # Heading)
3. Remove the top-level # Heading from each file (Starlight renders the title from frontmatter)
4. Convert GitHub-flavored alerts to Starlight asides (12 occurrences across 8 files):
   • > [!TIP] → :::tip
   • > [!NOTE] → :::note
   • > [!CAUTION] → :::caution
   • > [!IMPORTANT] → :::note[Important]
5. Move image assets:
   • docs/guides/deploy-to-ecs-fargate/*.png → src/assets/guides/
   • Update image references in the ECS Fargate guide
6. Move non-image assets to public/:
   • docs/guides/deploy-to-sagemaker/*.sh → public/scripts/
   • docs/guides/deploy-to-sagemaker/*.json → public/policies/
   • Update download references in the SageMaker guide
7. Add sidebar.order frontmatter where needed to control page ordering
8. Fix any internal links between docs pages to use Starlight-compatible relative paths
9. Remove the template placeholder content that was created in the scaffold task
10. Verify all pages render correctly with pnpm docs:dev

Acceptance criteria

• All 25 existing docs pages are present and render in the Starlight site
• No content is lost compared to the original Markdown files
• All GFM alerts are converted to Starlight ::: aside syntax
• Images render correctly in the ECS Fargate guide
• Internal links between pages work (no 404s when navigating)
• pnpm docs:build exits 0 with all content in place
• Sidebar shows pages in a logical order within each group

Blocked by

• Blocked by Scaffold Starlight project with Tailwind, configure for GitHub Pages, and integrate with monorepo #1755

User stories addressed

• User story 11 (admonitions render with clear styling)
• User story 12 (getting-started tutorial easy to find)