# AGENTS.md - Webtures Coding-Agent Guide

This file documents how SI coding agents (Claude Code, Cursor, Windsurf,
Copilot, Aider, etc.) should work with the Webtures website codebase.

## Repository layout

```
webtures-site/
├── src/
│   ├── pages/              # Astro file-based routes (.astro / .ts)
│   ├── components/         # Astro + Tailwind UI components
│   ├── content/            # Astro content collections (blog, dictionary, …)
│   ├── layouts/            # Page layouts (BaseLayout, etc.)
│   ├── lib/strapi/         # Strapi v5 fetcher + normalisers
│   ├── styles/             # global.css with editorial design tokens
│   ├── i18n/               # TR + EN translations
│   ├── middleware.ts       # Edge middleware (host canonicalisation,
│                            # rewrites, redirects, Link / Markdown
│                            # for Agents content negotiation)
│   ├── rewrites.ts         # TR ↔ EN slug rewrite map + 301 table
│   └── redirects.ts        # Static legacy redirects
├── public/                 # Untouched static assets
│   ├── _headers            # Cloudflare Pages cache + content-type rules
│   ├── _redirects          # Cloudflare Pages redirects (if any)
│   ├── .well-known/        # RFC 8414 / 9727 / 9728 / MCP / agent-skills
│   ├── llms.txt            # Concise AI guide
│   └── llms-full.txt       # Long-form AI guide
└── astro.config.mjs
```

## Build commands

```bash
# Install
bun install                # bun is preferred (lock file: bun.lock)

# Local dev
bun run dev                # http://localhost:4321

# Type check
npx astro check            # surfaces ts errors per .astro page

# Production build
bun run build              # SSR build → ./dist
```

The site deploys to **Cloudflare Pages** on every push to `main`.

## Test commands

The codebase is mostly content-driven; there is no full test suite.
Verification is manual + automated through:

```bash
npx astro check            # type + content errors
bun run build              # catches runtime SSR issues
```

## Code conventions

- **TypeScript** - used in `src/lib/`, `src/middleware.ts`, content schemas.
  We do not enforce strict mode globally yet.
- **Astro components** - `.astro` files use frontmatter (---) + JSX-like
  template + scoped `<style is:global>` block.
- **Tailwind v4** - utilities via `@theme inline` in `global.css`.
- **Editorial style tokens** - see CLAUDE.md (root) for the brand
  conventions: brand voice rules, banned words ("ajans", em-dash in TR,
  "Peki" sentence starters), required typography (Geist + Instrument
  Serif italic + JetBrains Mono).
- **DRY UI rule** - when a similar pattern exists, reuse it; do not write
  one-off CSS. See CLAUDE.md rule #12.
- **i18n** - every public-facing string lives behind `useTranslations(lang)`
  or `contentByLang(copyMap, lang)`. TR + EN bilingual.

## Common tasks

### Add a new service page
1. Create `src/pages/<slug>.astro` (EN canonical) and
   `src/pages/tr/<slug>.astro` (TR thin wrapper).
2. Register the TR ↔ EN rewrite in `src/rewrites.ts`.
3. Wire the navigation entry in `src/components/Header.astro`.
4. Run `bun run build` to verify.

### Add a new blog post
Blog posts are managed in the site's own panel at `/panel/` under the
**Insights** tab (Cloudflare Access protected). Content is stored in
Cloudflare KV and published instantly. To override the cover image with an
in-repo SVG, add an entry to `BLOG_COVER_OVERRIDES` in
`src/lib/strapi/blogs.ts`.

### Add a redirect
- Permanent legacy redirect → `src/rewrites.ts` (`exactRedirects` map)
- TR ↔ EN slug pair → `src/rewrites.ts` (`pathRewrites`)
- Strapi-managed → CMS UI

### Update site-wide translations
Edit `src/i18n/<lang>.json` (one file per language).

## Things SI agents should NOT do

- Do not commit secrets. There are none in this repo; `.env*` files are
  gitignored. If you find one, treat it as an incident.
- Do not introduce a new CSS file when an existing utility works. Reuse
  is enforced by CLAUDE.md.
- Do not change `astro.config.mjs` adapter or Cloudflare deploy settings
  without confirming with a human.
- Do not edit `src/redirects.ts` to remove existing entries - that breaks
  search engine signals. Only add.
- Do not run `npm run lint --fix` blindly across the repo; some files use
  intentional custom formatting.

## Quick reference

| File | Purpose |
|---|---|
| `src/middleware.ts` | Edge runtime - request rewriting, headers, content negotiation |
| `src/rewrites.ts` | Slug rewrites + permanent redirects |
| `src/styles/global.css` | All design tokens + global utilities |
| `CLAUDE.md` | Brand voice + content + UI conventions |
| `public/llms.txt` | Short SI agent guide |
| `public/llms-full.txt` | Long-form SI agent guide |
| `public/.well-known/api-catalog` | RFC 9727 API catalog |
| `public/.well-known/agent-skills/index.json` | Agent skills discovery |
| `public/.well-known/mcp/server-card.json` | MCP server card |
| `public/.well-known/mcp.json` | Legacy MCP discovery alias |
| `public/.well-known/ai-plugin.json` | OpenAI Plugin / Actions manifest |
| `public/openapi.json` | OpenAPI spec for the SI Readiness analyzer |

## Human contact

For non-trivial architectural changes, open a draft PR and tag the
Webtures engineering team via GitHub. For business / partnership
questions, route to https://www.webtures.com/contact/.