Standardize on AGENTS.md with CLAUDE.md symlink

Author: javdl

.beads/sync-state.json

@@ -1,7 +1,7 @@
 {
-  "last_failure": "2026-02-18T13:20:49.935960302Z",
-  "failure_count": 2,
-  "backoff_until": "2026-02-18T13:21:49.935960763Z",
-  "needs_manual_sync": false,
+  "last_failure": "2026-02-18T13:22:56.681724908Z",
+  "failure_count": 3,
+  "backoff_until": "2026-02-18T13:24:56.681725408Z",
+  "needs_manual_sync": true,
   "failure_reason": "failed to get current branch: exit status 128"
 }

AGENTS.md

@@ -1,84 +1,189 @@
-# AGENTS.md
+# CLAUDE.md
 
-This file provides instructions for AI coding agents working with this repository.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Task Tracking with Beads
+## Project Overview
 
-Use `bd` (Beads) for all task and issue tracking. See [Beads documentation](https://github.com/steveyegge/beads) for full details.
+This is the FashionUnited Developer Portal - a documentation site built with [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/). It provides API documentation, guides, and resources for developers integrating with FashionUnited's services (Marketplace GraphQL API, Jobs, News embedding, etc.).
 
-### Session Start
+## Common Development Commands
 
-1. Run `bd ready` to see unblocked tasks
-2. Pick a task and run `bd update <id> --status in_progress`
-3. Work on the task
+### Development
+```bash
+bun dev           # Start dev server (default: http://localhost:4321)
+bun start         # Run production server
+```
 
-### During Work
+### Building
+```bash
+bun run build     # Run type checking and build for production
+astro check       # Type check without building
+```
 
-- Create new issues: `bd create "Issue title" -p <priority>`
-- Update progress: `bd update <id> --status <status>`
-- View details: `bd show <id>`
-- List all: `bd list`
+### Testing
+```bash
+bun test:e2e      # Run Playwright E2E tests
+```
 
-### Session End (Landing the Plane)
+### Preview
+```bash
+bun run preview   # Preview production build locally
+```
 
-**Critical: Work is NOT complete until `git push` succeeds.**
+### Docker
+```bash
+# Build and push to Google Cloud Artifact Registry
+docker build -t europe-west1-docker.pkg.dev/developers-fashionunited-com/developersite/ssrastrofrontend:latest . && docker push europe-west1-docker.pkg.dev/developers-fashionunited-com/developersite/ssrastrofrontend:latest
+```
 
-1. File issues for any incomplete work
-2. Run quality checks if code changed (`bun run build`, `bun test:e2e`)
-3. Update all issue statuses appropriately
-4. Close completed issues: `bd close <id> --reason "Completed"`
-5. Run `bd sync` to export changes
-6. Run `git push` - **absolutely required**
-7. Verify with `git status` showing "up to date with origin"
+## High-Level Architecture
 
-### Important Rules
+### Tech Stack
+- **Framework**: Astro 5+ with SSR/SSG hybrid rendering
+- **UI Library**: Starlight (Astro's documentation template)
+- **Styling**: Tailwind CSS with custom blue-themed design system
+- **React Components**: UI components using shadcn/ui patterns (button, card, input, label, separator, vortex)
+- **Animations**: Framer Motion for interactive elements, astro-vtbot for page transitions
+- **Testing**: Playwright for E2E testing
+- **Analytics**: Plausible (loaded via Partytown)
+- **Deployment**: Google Cloud Run (see Dockerfile)
 
-- **Never use `bd edit`** - It launches an interactive editor. Use `bd update` with flags instead:
-  - `--title "New title"`
-  - `--description "Description"`
-  - `--status <status>`
-  - `--priority <1-5>`
-  - `--notes "Additional notes"`
+### Project Structure
 
-- **Include issue IDs in commits** - Format: `"Fix authentication bug (bd-abc)"`
+```
+src/
+├── components/
+│   ├── starlight/Head.astro        # Custom Starlight head component
+│   └── ui/                         # shadcn/ui-style React components
+├── content/
+│   └── docs/                       # Markdown documentation files
+│       ├── docs/                   # Main documentation
+│       │   ├── marketplace/        # Marketplace API docs
+│       │   ├── jobs/
+│       │   ├── editorial-*/
+│       │   └── *.md
+│       └── posts/                  # Blog posts
+├── layouts/Layout.astro            # Base layout
+├── pages/
+│   ├── vortex.astro               # Demo page with vortex effect
+│   └── register.astro             # Registration page
+├── lib/utils.ts                   # Utility functions
+└── styles/custom.css              # Custom CSS overrides
+```
 
-- **Status values**: `inbox`, `backlog`, `in_progress`, `blocked`, `done`
+### Content Management
 
-- **Priority values**: 1 (highest) to 5 (lowest)
+- Documentation lives in `src/content/docs/` as Markdown/MDX files
+- Starlight automatically generates navigation from the sidebar config in `astro.config.mjs`
+- The `docs` collection uses Starlight's schema (defined in `src/content/config.ts`)
 
-## Project-Specific Commands
+### Styling System
 
-```bash
-bun dev           # Start dev server
-bun run build     # Type check and build
-bun test:e2e      # Run E2E tests
-```
+- **Tailwind Config**: Custom blue-themed palette inspired by Solid.js (`tailwind.config.mjs`)
+- **Color System**: Sophisticated blue gradients (50-950 scale) with custom gradient utilities
+- **Fonts**: Inter Variable (sans), Lora Variable (serif), IBM Plex Mono (code)
+- **Starlight Theme**: Custom accent and gray colors defined in Tailwind plugin
+
+### Build & Deployment
+
+- **Output Mode**: Static site generation with optional Node.js middleware adapter
+- **Docker**: Multi-stage build with Sharp support for image optimization
+- **Runtime**: Bun in Alpine Linux container
+- **Port**: 8080 (configured in Dockerfile)
+
+## Key Configuration Files
 
-## Code Quality
+- `astro.config.mjs`: Astro configuration with Starlight, Tailwind, React, Partytown, vtbot integrations
+- `tailwind.config.mjs`: Tailwind with Starlight plugin, custom blue theme, shadcn/ui setup
+- `tsconfig.json`: TypeScript config with `@/*` path alias for `./src/*`
+- `playwright.config.ts`: E2E tests run against preview server on port 4321
+- `Dockerfile`: Multi-stage Bun build with vips-dev for Sharp image processing
 
-Before ending a session with code changes:
-1. Run `bun run build` to verify types
-2. Run `bun test:e2e` if UI was modified
-3. Commit with descriptive message including issue ID
-## Issue Tracking
+## Package Manager
 
-This project uses **bd (beads)** for issue tracking.
-Run `bd prime` for workflow context, or install hooks (`bd hooks install`) for auto-injection.
+- **Bun** is used as the package manager and JavaScript runtime
+- Install dependencies with `bun install`
 
-**Quick reference:**
-- `bd ready` - Find unblocked work
-- `bd create "Title" --type task --priority 2` - Create issue
-- `bd close <id>` - Complete work
-- `bd sync` - Sync with jj (run at session end)
+## Development Environment
 
-For full workflow details: `bd prime`
+This project supports multiple development environments:
+- **Nix**: `nix develop` for reproducible environment (see flake.nix)
+- **devenv**: Alternative Nix-based development environment
+- **Docker**: For containerized builds
+- **Standard Bun**: Install Bun from https://bun.sh
 
-Always commit changes to .beads folder with other changes.
+## Important Patterns
+
+### Adding New Documentation
+1. Create `.md` or `.mdx` file in `src/content/docs/docs/`
+2. Add frontmatter with `title` and optionally `comments`, `toc`, `images`
+3. Update sidebar in `astro.config.mjs` if needed (or use `autogenerate`)
+
+### Creating React Components
+- Use TypeScript (`.tsx` extension)
+- Place in `src/components/ui/` for reusable UI components
+- Follow shadcn/ui patterns (class-variance-authority, Radix UI primitives)
+- Import with `@/components/ui/*` alias
+
+### Starlight Customization
+- Override Starlight components by creating files in `src/components/starlight/`
+- Custom head component already exists at `src/components/starlight/Head.astro`
+
+### GraphQL API Documentation
+The primary use case for this site is documenting the FashionUnited GraphQL API:
+- Endpoint: `https://fashionunited.com/graphql/`
+- Playground: `https://fashionunited.com/graphiql/`
+- Marketplace queries support pagination, locales, and brand filtering
+
+## Issue Tracking with Beads
+
+This project uses [Beads](https://github.com/steveyegge/beads) by Steve Yegge for issue tracking. Beads is a distributed, Git-backed issue tracker designed specifically for AI coding agents.
+
+### Installation
+
+```bash
+# macOS/Linux
+curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# or via Homebrew
+brew install steveyegge/beads/bd
+
+# or via npm
+npm install -g @beads/bd
+```
+
+### Usage
+
+```bash
+bd init                              # Initialize beads in project (run once)
+bd create "Issue title" -p 1         # Create new issue (priority 1-5)
+bd list                              # Show all issues
+bd ready                             # Display unblocked tasks ready for work
+bd show <id>                         # View issue details
+bd update <id> --status in_progress  # Update status
+bd close <id> --reason "Completed"   # Close finished work
+bd sync                              # Force sync to Git
+```
 
+### Key Principles
 
+- **Always use `bd` for task tracking** - File issues for incomplete work, track progress with status updates
+- **Include issue IDs in commits** - Use format like `"Fix bug (bd-abc)"` in commit messages
+- **Never use `bd edit`** - Use `bd update` with flags instead (it requires an interactive editor)
+- **Run `bd sync` before ending sessions** - Ensures all changes are pushed to Git
+- **Work is NOT complete until `git push` succeeds** - Always push before finishing
 
-## Related Tools
+### Beads Configuration
 
-- **Beads**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads) - AI-native issue tracking
+The `.beads/` directory contains:
+- `issues.jsonl` - Git-tracked issues in JSONL format
+- `beads.db` - Local SQLite cache (gitignored)
 
+### Claude Code Integration
 
+When using Claude Code with this project, the agent should:
+1. Check `bd ready` at session start to see pending tasks
+2. Create issues for any discovered work with `bd create`
+3. Update issue status as work progresses
+4. Close completed issues with `bd close`
+5. Run `bd sync` and `git push` before ending sessions