---
title: Agents Guide
description: Guidance for AI coding agents working with this repository.
last_updated: "2026-05-27"
---

# Agents Guide — formalsnake.dev

Personal site of Kyan De Sutter, built with Astro 6 and React 19.
This file orients AI coding agents (Claude Code, Copilot, Cursor, etc.)
working on the repo.

## Project Overview

- **Stack:** Astro 7 (static site) + React 19 islands + Tailwind CSS v4 + MDX
- **Content:** Markdown/MDX collections under `src/content/` (blog, projects)
- **Deploy target:** `https://www.formalsnake.dev`
- **Package manager:** Bun (lockfile is `bun.lock`)

## Installation

```bash
bun install
```

## Development

```bash
bun run dev        # start dev server at http://localhost:4321
bun run build      # produce static output in ./dist
bun run preview    # preview the production build
bun run astro check  # type-check (via @astrojs/check)
```

## Configuration

Site-wide configuration lives in `src/config/site.ts`. The Astro config
in `astro.config.mjs` registers integrations (`@astrojs/react`,
`@astrojs/mdx`, `@astrojs/sitemap`) and Tailwind via Vite.

```typescript
// src/config/site.ts
export const site = {
  name: "Kyan De Sutter",
  title: "FormalSnake",
  url: "https://www.formalsnake.dev",
  // ...
};
```

## Project Layout

```
src/
  components/      # Astro + React components
  config/          # Site-wide configuration
  content/         # Content collections
    blog/          # Blog posts (MDX, one folder per post)
    projects/      # Project entries
  content.config.ts  # Collection schemas (Zod)
  layouts/         # Page layouts (Base.astro, Post.astro)
  pages/           # Routes
    blog/          # Blog index + post pages + .md mirrors
    projects/      # Projects index
    tools/         # Tools pages (SEO preview)
    robots.txt.ts  # robots.txt with AI-bot allowlist
    llms.txt.ts    # llms.txt index for AI agents
    sitemap.md.ts  # Markdown sitemap
    rss.xml.ts     # RSS feed
  styles/          # Global CSS
public/            # Static assets
```

## Authoring Content

Blog posts are MDX files at
`src/content/blog/<slug>/index.mdx`. Required frontmatter:

```yaml
---
title: "Post title"
description: "One-line summary."
date: 2026-05-27
tags: ["design", "opinion"]
image: "./1200x630.webp"   # optional cover image
draft: false                 # optional, defaults to false
---
```

The schema is defined in `src/content.config.ts`.

## Agent-Readability Surfaces

This site implements the [Vercel Agent Readability Spec][spec].
Key endpoints:

- `/robots.txt` — allows GPTBot, ClaudeBot, CCBot, Google-Extended, and
  other AI crawlers
- `/llms.txt` — plain-text index of all pages with `.md` mirror links
- `/sitemap-index.xml` — generated by `@astrojs/sitemap`
- `/sitemap.md` — markdown sitemap with hierarchical links
- `/blog/<id>.md` — markdown mirror of each blog post with canonical
  `Link` header and YAML frontmatter
- `/AGENTS.md` — this file
- Every page emits JSON-LD structured data and a canonical `<link>`

[spec]: https://vercel.com/kb/guide/agent-readability-spec

## Conventions

- Astro components use the `.astro` extension; React islands use `.tsx`
  and are hydrated with the appropriate `client:*` directive
- Tailwind CSS v4 with `@tailwindcss/vite` — utilities are written
  directly in markup, no separate stylesheet
- Use Lucide icons (`lucide-react`) — never hardcode SVGs
- Path alias `@/` maps to `src/` (see `tsconfig.json`)
- Date handling: blog post dates are coerced via Zod (`z.coerce.date()`)

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.