Update agents.md

[zastrowm]

Overview

After the recent transfer from MkDocs to Astro/Starlight CMS, the AGENTS.md file needs to be updated to reflect the new architecture. Both README.md and CONTRIBUTING.md have already been updated, but AGENTS.md still references the old MkDocs system.

Implementation Requirements

Context

• OLD CMS: MkDocs with PyMdown extensions
• NEW CMS: Astro with Starlight theme
• Reference Files: README.md, CONTRIBUTING.md, SITE-ARCHITECTURE.md have been updated and should serve as templates

Changes Required

1. Development Commands

Update build/preview commands from MkDocs to Astro:

• Replace mkdocs build → npm run build
• Replace mkdocs serve → npm run dev
• Replace 127.0.0.1:8000 → localhost:4321

2. Setup Instructions

Update installation instructions:

• Replace pip install . → npm install
• Keep Python 3.10+ as prerequisite (still needed for API doc generation)
• Keep Node.js 20+ prerequisite

3. Code Tab Syntax

Update code tab documentation from MkDocs syntax to Astro components:

• Replace === "Python" / === "TypeScript" syntax with <Tabs> / <Tab label="..."> components
• Note that these components are auto-imported (no import statement needed)
• Reference SITE-ARCHITECTURE.md for detailed component documentation

4. Directory Structure

Update the directory tree to include the new src/ directory structure:

• src/components/ - Custom Astro components
• src/content/docs/ - Symlinked to docs/ directory
• src/layouts/ - Custom layouts
• src/pages/ - Astro pages
• src/util/ - Utility functions

5. Quality Checks Section

Update to reflect current npm scripts:

• npm test - TypeScript type checking
• npm run lint - Linting
• npm run format:check - Formatting

6. References

• Add reference to SITE-ARCHITECTURE.md for detailed customization documentation
• Update any mkdocs.yml references to note it's used for navigation structure (still relevant)
• Clarify that MkDocs snippet syntax (--8<--) still works via the remark plugin

7. TypeScript Code Examples Section

This section can largely remain but should be updated to:

• Reference SITE-ARCHITECTURE.md for full details on snippet integration
• Note the Astro-specific context for how snippets are processed

Files to Modify

• AGENTS.md - Primary file requiring updates

Reference Documents

• README.md - Already updated, use as template for commands
• CONTRIBUTING.md - Already updated, use as template for development setup
• SITE-ARCHITECTURE.md - Comprehensive documentation of new CMS architecture

Acceptance Criteria

• All MkDocs-specific commands replaced with Astro equivalents
• Directory structure reflects actual repository state (including src/)
• Code tab syntax examples use <Tabs>/<Tab> components
• References to SITE-ARCHITECTURE.md added where appropriate
• Document can be followed by an agent to successfully build and preview the site
• Pre-commit hooks and quality checks documented correctly

Notes for Implementer

• The snippet syntax (--8<-- "path/to/file.ts:section") still works in the new CMS via src/plugins/remark-mkdocs-snippets.ts
• mkdocs.yml is still used for sidebar navigation (loaded by src/sidebar.ts)
• Consider reviewing CMS-TODO.md for additional context on migration status

[zastrowm]

/strands

[zastrowm]

/strands implement