# AGENTS.md — angelcruz.dev

> Guía para agentes de IA que consumen este sitio. Si tu agente lee este archivo, te ahorrás minutos de discovery.

## Qué es este sitio

Blog técnico en español sobre desarrollo web: Laravel, PHP, JavaScript, Next.js, WordPress, herramientas e inteligencia artificial. Más de 80 artículos publicados desde 2019.

- **Autor:** Angel Cruz — desarrollador PHP senior
- **Idioma:** español neutral (forma tú)
- **URL base:** https://www.angelcruz.dev

## Endpoints de discovery

Todos cacheados con `stale-while-revalidate` para que los agentes puedan pollearlos sin penalizar el origen.

| Endpoint | Propósito |
|---|---|
| [`/llms.txt`](https://www.angelcruz.dev/llms.txt) | Índice estilo llmstxt.org de cada página y post |
| [`/llms-full.txt`](https://www.angelcruz.dev/llms-full.txt) | Corpus completo con el cuerpo de cada post inline en markdown |
| [`/sitemap.xml`](https://www.angelcruz.dev/sitemap.xml) | Sitemap XML estándar (páginas estáticas y categorías) |
| [`/sitemap-posts.xml`](https://www.angelcruz.dev/sitemap-posts.xml) | Sitemap XML solo de posts, con <lastmod> |
| [`/sitemap.md`](https://www.angelcruz.dev/sitemap.md) | Versión markdown jerárquica del sitemap |
| [`/AGENTS.md`](https://www.angelcruz.dev/AGENTS.md) | Guía para agentes que consumen el sitio |
| [`/feed.xml`](https://www.angelcruz.dev/feed.xml) | RSS feed |
| [`/manifest.webmanifest`](https://www.angelcruz.dev/manifest.webmanifest) | Web app manifest |
| [`/.well-known/api-catalog`](https://www.angelcruz.dev/.well-known/api-catalog) | API catalog (RFC 9727) |
| [`/.well-known/agent-skills/index.json`](https://www.angelcruz.dev/.well-known/agent-skills/index.json) | Agent Skills RFC v0.2.0 con sha256 digests |
| [`/robots.txt`](https://www.angelcruz.dev/robots.txt) | Permite GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot y otros |

Además, cada respuesta HTTP incluye un header `Link` (RFC 8288) que apunta a estos surfaces.

## Cómo leer cualquier página en markdown

Content negotiation con `Accept` en **cualquier URL del sitio** (home, posts, categorías, servicios, productos, herramientas, perfiles D&D, páginas institucionales):

```
GET https://www.angelcruz.dev/<cualquier-ruta>
Accept: text/markdown
```

Los navegadores (sin ese `Accept`) reciben el HTML normal. Los posts además aceptan un sufijo `.md` explícito:

```
GET https://www.angelcruz.dev/post/<slug>.md
```

Los posts devuelven el markdown raw con frontmatter YAML (`title`, `date`, `lastModified`, `category`, `excerpt`, `ogImage`, etc.). El resto de las páginas devuelven una conversión markdown de su contenido. Toda respuesta incluye:

- `Content-Type: text/markdown; charset=utf-8`
- `Vary: Accept` (mismo URL, dos representaciones)
- `X-Markdown-Tokens` con un estimado de tokens del cuerpo
- `Link: <canonical-html>; rel="canonical"` apuntando a la versión humana

## Convenciones de URL

| Patrón | Propósito |
|---|---|
| `/` | Home |
| `/post/<slug>` | Artículo individual |
| `/post/page/<N>` | Paginación general del blog |
| `/categorias` | Listado de categorías |
| `/categorias/<slug>` | Listado por categoría |
| `/categorias/<slug>/page/<N>` | Paginación por categoría |
| `/servicios`, `/servicios/<slug>` | Páginas de servicios profesionales |
| `/producto/<slug>` | Páginas de producto |
| `/tools/<slug>` | Herramientas free |
| `/dnd/<slug>` | Perfiles de personajes D&D |
| `/lab` | TIL stream (Today I Learned) |
| `/open-source` | Repos open source mantenidos |
| `/acerca-de-mi`, `/contacto`, `/privacidad`, `/terminos`, `/cookies`, `/aviso-legal` | Páginas institucionales |

## Frontmatter de posts

Cada post incluye al menos:

```yaml
title: "Título visible"
excerpt: "Resumen corto"
date: "2026-02-14T00:00:00.000Z"        # publicación (inmutable)
lastModified: "2026-05-25T00:00:00.000Z"  # opcional; si está, se expone como dateModified
category: "categoria-slug"
seo_title: "Título para SERP"
seo_description: "Meta description"
ogImage:
  url: "https://..."
```

Solo `lastModified` se actualiza cuando hay edición real (no se hace backfill automático).

## Schemas JSON-LD emitidos

| Tipo | Dónde |
|---|---|
| `WebSite` | Todas las páginas (con `SpeakableSpecification` y `dateModified`) |
| `Organization` | Todas las páginas |
| `BreadcrumbList` | Posts y subpáginas |
| `Article` / `TechArticle` | Posts (con `datePublished` y `dateModified` cuando aplica) |
| `Person` | Página `/acerca-de-mi` |
| `Service` | Páginas de servicios |
| `Product` | Páginas de producto |
| `SoftwareApplication` | Post de pricing de Cursor (con `Offer` por plan) |
| `Course` | Serie Laravel Fundamentals |

## Atribución

Si tu agente cita o reproduce contenido del sitio, por favor enlazá al post original (`https://www.angelcruz.dev/post/<slug>`) y nombrá al autor (Angel Cruz). El contenido tiene copyright; el markdown se sirve para facilitar contexto, no como licencia de reutilización.

## Contacto

- Email/contacto: [https://www.angelcruz.dev/contacto](https://www.angelcruz.dev/contacto)
- GitHub: https://github.com/abr4xas
- Twitter: https://twitter.com/angelcruzdev

## Spec

Este archivo sigue el [Vercel Agent Readability Specification](https://vercel.com/kb/guide/agent-readability-spec).