AGENTS.md - Pages

Astro pages for the Baigon Portal. Marketing pages + authenticated portal pages.

Package Identity

Purpose: All public and protected pages for the Baigon platform
Framework: Astro 5 SSR with TailwindCSS 4
Output: Server-rendered (SSR) by default, opt-in static with export const prerender = true

Setup & Run

bun run dev     # Start dev server at localhost:4321
bun run build   # Build for production

Patterns & Conventions

Page Types

Type	Layout	Auth	Examples
Marketing	`MarketingLayout`	Public	`index.astro`, `about.astro`, `contact.astro`
Solutions	`MarketingLayout`	Public	`solutions/founder.astro`, `solutions/c-level.astro`
Portal	`PortalLayout`	Required	`dashboard.astro`, `admin.astro`
Auth	`BaseLayout`	Public	`login.astro`
Forms	`BaseLayout`	Public	`form.astro`
Legal	`MarketingLayout`	Public	`legal/terms.astro`, `legal/privacy.astro`

File Organization

pages/
├── index.astro              # Homepage (marketing, packages from DB)
├── about.astro              # About page
├── contact.astro            # Contact form
├── how-it-works.astro       # Product explainer
├── login.astro              # OTP login flow
├── form.astro               # Registration/intake form
├── dashboard.astro          # User portal (protected)
├── admin.astro              # Admin panel (admin-only)
├── file/[fileId].astro      # File viewer (protected)
├── profile/[id].astro       # User profile (protected)
├── solutions/               # Solution pages by persona
│   ├── index.astro
│   ├── founder.astro
│   ├── strategist.astro
│   ├── c-level.astro
│   ├── solo-expert.astro
│   └── startup-ai.astro
├── legal/                   # Legal pages
│   ├── terms.astro
│   ├── privacy.astro
│   └── refund.astro
└── api/                     # [see api/AGENTS.md]

Page Template Pattern

---
// 1. Imports
import MarketingLayout from '../layouts/MarketingLayout.astro';

// 2. Data fetching (optional, server-side)
const db = Astro.locals.runtime?.env?.DB;
const { results } = await db?.prepare('SELECT * FROM table').all() ?? { results: [] };
---

<!-- 3. HTML with TailwindCSS -->
<MarketingLayout title="Page Title" description="SEO description">
  <div class="max-w-7xl mx-auto px-6 py-12">
    <!-- Content -->
  </div>
</MarketingLayout>

Do’s and Don’ts

✅ DO: Use Layout components — see about.astro for marketing, dashboard.astro for portal
✅ DO: Access DB via locals: Astro.locals.runtime?.env?.DB
✅ DO: Use Astro.locals.user! in protected pages (guaranteed by middleware)
✅ DO: Use TailwindCSS utilities for styling
❌ DON’T: Write raw HTML without a layout wrapper
❌ DON’T: Import DB directly — always go through Astro.locals.runtime.env
❌ DON’T: Add auth checks in pages — middleware handles it
❌ DON’T: Use inline styles or custom CSS

Touch Points / Key Files

File	Lines	Purpose	Pattern
`index.astro`	~1035	Homepage with packages	DB fallback, Three.js effects
`dashboard.astro`	~1258	User portal	Portal layout + sidebar + tabs
`admin.astro`	~2441	Admin panel	Role check + admin tabs
`login.astro`	~352	OTP login	Client-side fetch to API
`form.astro`	~1461	Intake form	Multi-step form + payment

JIT Index Hints

# Find marketing pages
rg -l "MarketingLayout" src/pages

# Find protected pages (portal)
rg -l "PortalLayout" src/pages

# Find pages that fetch from DB
rg -n "Astro.locals.runtime.*DB" src/pages

# Find prerendered (static) pages
rg -n "prerender = true" src/pages

# Find client-side API calls
rg -n "fetch\('/api/" src/pages

# Find dynamic routes
find src/pages -name "\[*\].*"

Common Gotchas

Auth handled by middleware — Astro.locals.user is guaranteed on protected pages
DB may be undefined in dev edge cases — always use optional chaining: runtime?.env?.DB
TailwindCSS 4 syntax differs from v3 — check Tailwind v4 docs if patterns don’t work
SSR by default — add export const prerender = true only for static pages
Large pages (admin.astro ~2441 lines, form.astro ~1461 lines) — read specific sections

Pre-PR Checks

bun run build && bun run preview
# Then test the specific page you modified