Authoring Workflow

Prerequisites

• Node.js 20 or newer
• pnpm installed globally (npm install -g pnpm)
• Optional: install Chrome/Chromium locally for Lighthouse CI (pnpm dlx puppeteer browsers install chrome)

Create or Edit Content

1. Add Markdown/MDX files under src/content/docs/.

2. Include the required front matter:

   ---
   title: Example Title
   description: One-sentence summary of the page.
   publishDate: 2025-10-08
   updatedDate: 2025-10-08 # optional
   draft: false
   tags:
     - example
   heroImage: ../../assets/example.webp # optional
   ---

3. Place images in public/ or src/assets/ and reference them with relative paths.

Local Validation Checklist

pnpm lint          # astro check – schema/types
pnpm test:links    # astro check --links – link validation
pnpm test:lighthouse  # build + Lighthouse CI (requires Chrome)

Run these commands before opening a pull request. Lighthouse CI saves reports in .lighthouseci/.

Development Server

pnpm dev

The site reloads automatically at http://localhost:4321 when you edit content or configuration.

Pull Request Workflow

1. Branch from main.
2. Make content/config changes.
3. Run the validation checklist.
4. Commit and push. The GitHub Actions workflow (.github/workflows/ci.yml) reruns the same checks in CI.
5. Review SWA preview (once infrastructure is provisioned) and gather evidence for the active milestone.

Troubleshooting

• Schema errors: ensure front matter fields match src/content.config.ts.
• Link errors: update broken URLs or add redirects.
• Lighthouse failures: verify Chrome is available locally/CI and adjust content or performance issues before retrying.

For milestone status and follow-ups see /docs/10_projects/agentic-compass/2-build/agentic-compass-v0/04-planning/milestones/MLS-AC-V0-0001.yaml.