docs: update OpenWiki

.github/workflows/openwiki-update.yml aktualisiert
Merge branch 'master' of https://git.krampitz.win/tim/SlipItIn
2026-08-08 18:09:52 +00:00 · 2026-08-08 18:06:26 +00:00 · 2026-08-08 12:50:27 +02:00 · 2026-08-08 12:50:15 +02:00 · 2026-07-26 15:36:33 +00:00 · 2026-07-26 17:31:26 +02:00
253 changed files with 33362 additions and 83 deletions
--- a/.github/skills/agent-ready-cloudflare/README.md
+++ b/.github/skills/agent-ready-cloudflare/README.md
@@ -0,0 +1,338 @@
+# 🤖 Agent Ready — Cloudflare Scanner Skill
+
+Scan any website for AI agent readiness and get actionable fix prompts — powered by [isitagentready.com](https://isitagentready.com).
+
+This skill wraps the Cloudflare "Is It Agent Ready?" scanner into a reusable agent skill with full API documentation, 20 implementation sub-skills, and copy-paste prompts for every failing check.
+
+---
+
+## What It Does
+
+Give it a domain. It scans 18 checks across 5 categories and tells you:
+
+- **What level** your site is at (0–5)
+- **What's passing** and what's failing
+- **How to fix** every failure — with a prompt you can paste into any coding agent
+- **What to prioritize** to reach the next level
+
+```
+You: "Scan example.com for agent readiness"
+
+Agent: Scans via API → generates Markdown report → includes fix prompts for every failure
+```
+
+---
+
+## Quick Start
+
+### 1. Scan a single domain
+
+```bash
+curl -s -X POST 'https://isitagentready.com/api/scan' \
+  -H 'Content-Type: application/json' \
+  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36' \
+  -H 'Referer: https://isitagentready.com/' \
+  -H 'Origin: https://isitagentready.com' \
+  -d '{"url":"https://example.com/"}'
+```
+
+### 2. Get a markdown report (for LLMs)
+
+```bash
+curl -s -X POST 'https://isitagentready.com/api/scan' \
+  -H 'Content-Type: application/json' \
+  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36' \
+  -H 'Referer: https://isitagentready.com/' \
+  -H 'Origin: https://isitagentready.com' \
+  -d '{"url":"https://example.com/","format":"agent"}'
+```
+
+### 3. Use the MCP server
+
+Connect your agent to the MCP endpoint:
+
+```
+https://isitagentready.com/mcp
+```
+
+Call the `scan_site` tool with `{"url": "https://example.com"}`.
+
+---
+
+## The 18 Checks
+
+### Discoverability
+
+| # | Check | What passes |
+|---|-------|-------------|
+| 1 | **robots.txt** | `/robots.txt` returns 200 with `text/plain` and `User-agent` directives |
+| 2 | **sitemap.xml** | `/sitemap.xml` returns valid XML, or `Sitemap:` directive in robots.txt |
+| 3 | **Link headers** | Homepage `Link` headers include agent-useful relations (`api-catalog`, `service-desc`, etc.) |
+
+### Content
+
+| # | Check | What passes |
+|---|-------|-------------|
+| 4 | **Markdown for Agents** | `Accept: text/markdown` → response with `Content-Type: text/markdown` |
+
+### Bot Access Control
+
+| # | Check | What passes |
+|---|-------|-------------|
+| 5 | **AI bot rules** | robots.txt has `User-agent` entries for GPTBot, Claude-Web, Google-Extended, etc. |
+| 6 | **Content Signals** | robots.txt has `Content-Signal:` directives (ai-train, search, ai-input) |
+| 7 | **Web Bot Auth** | `/.well-known/http-message-signatures-directory` with valid JWKS *(informational)* |
+
+### API, Auth, MCP & Skill Discovery
+
+| # | Check | What passes |
+|---|-------|-------------|
+| 8 | **API Catalog** | `/.well-known/api-catalog` returns `application/linkset+json` (RFC 9727) |
+| 9 | **OAuth/OIDC** | `/.well-known/openid-configuration` or `oauth-authorization-server` with valid metadata |
+| 10 | **OAuth Protected Resource** | `/.well-known/oauth-protected-resource` with `resource` + `authorization_servers` (RFC 9728) |
+| 11 | **MCP Server Card** | `/.well-known/mcp/server-card.json` with `serverInfo`, transport, capabilities (SEP-1649) |
+| 12 | **A2A Agent Card** | `/.well-known/agent-card.json` with name, version, supportedInterfaces |
+| 13 | **Agent Skills Index** | `/.well-known/agent-skills/index.json` with skills array (v0.2.0) |
+| 14 | **WebMCP** | Page calls `navigator.modelContext.provideContext()` with tool definitions |
+
+### Commerce *(optional — scored only for e-commerce sites)*
+
+| # | Check | What passes |
+|---|-------|-------------|
+| 15 | **x402** | API routes return HTTP 402 with x402 payment headers |
+| 16 | **UCP** | `/.well-known/ucp` with protocol_version and services |
+| 17 | **ACP** | `/.well-known/acp.json` with protocol metadata |
+| 18 | **AP2** | A2A Agent Card includes AP2 extension with role |
+
+---
+
+## Level System
+
+```
+Level 0  Not Ready           — Fails basic checks
+Level 1  Basic Web Presence  — 2 of 3: robots.txt, sitemap, link headers
+Level 2  Bot-Aware           — Level 1 + AI bot rules + Content Signals
+Level 3  Agent-Readable      — Level 2 + markdown content negotiation
+Level 4  Agent-Integrated    — Level 3 + 1 of: MCP card, A2A card, agent skills, API catalog
+Level 5  Agent-Native        — Level 4 + 2 of: Web Bot Auth, all integrations, auth metadata
+```
+
+---
+
+## Example Output
+
+Scanning a site at Level 1 produces a report like:
+
+```markdown
+# Agent Ready Scan — example.com
+
+> **Score:** Level 1 — Basic Web Presence
+> **Scanned:** 2026-04-18T13:10:58Z
+> **Link:** [View online](https://isitagentready.com/example.com)
+
+## Summary
+
+| Category                          | Score |
+|-----------------------------------|-------|
+| Discoverability                   | 2/3   |
+| Content                           | 0/1   |
+| Bot Access Control                | 1/3   |
+| API, Auth, MCP & Skill Discovery  | 0/7   |
+
+## Details
+
+### Discoverability (2/3)
+
+- ✅ **robots.txt** — robots.txt exists with valid format
+- ✅ **sitemap.xml** — sitemap.xml exists with valid structure
+- ❌ **Link headers** — No Link headers found on homepage
+
+### Content (0/1)
+
+- ❌ **Markdown for Agents** — Site does not support Markdown for Agents
+
+(... more categories ...)
+
+## 🔧 How to Implement — Agent Prompts
+
+#### ❌ Link headers
+
+**Issue:** No Link headers found on homepage
+
+```
+Goal: Include Link response headers for agent discovery (RFC 8288)
+
+Issue: No Link headers found on homepage
+
+Fix: Add Link response headers to your homepage that point agents to useful
+resources. For example: Link: </.well-known/api-catalog>; rel="api-catalog"
+
+Skill: https://isitagentready.com/.well-known/agent-skills/link-headers/SKILL.md
+
+Docs: https://www.rfc-editor.org/rfc/rfc8288
+```
+
+> 📖 Reference: [link-headers/SKILL.md](link-headers/SKILL.md)
+
+(... one block per failing check ...)
+
+## Next Level
+
+**Level 2 — Bot-Aware**
+
+To reach the next level, implement:
+- Content Signals in robots.txt
+```
+
+---
+
+## Fix Prompts
+
+Every failing check gets a prompt block you can copy-paste into any coding agent (Cursor, Copilot, Claude, etc.). The format matches the isitagentready.com web UI:
+
+```
+Goal: <what the check expects>
+Issue: <what was found (dynamic from scan)>
+Fix: <step-by-step implementation>
+Skill: <URL to the detailed SKILL.md>
+Docs: <links to RFCs and specs>
+```
+
+The SKILL.md contains templates for all 20 checks. The `{issue}` placeholder is replaced with the actual message from the API response.
+
+---
+
+## Batch Scanning
+
+Scan multiple domains with a 2-second delay between requests:
+
+```python
+import json, time, urllib.request
+
+HEADERS = {
+    "Content-Type": "application/json",
+    "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ...",
+    "Referer": "https://isitagentready.com/",
+    "Origin": "https://isitagentready.com"
+}
+
+domains = ["example.com", "another.com", "third.com"]
+
+for domain in domains:
+    body = json.dumps({"url": f"https://{domain}/"}).encode()
+    req = urllib.request.Request(
+        "https://isitagentready.com/api/scan",
+        data=body, headers=HEADERS
+    )
+    with urllib.request.urlopen(req, timeout=90) as resp:
+        data = json.loads(resp.read())
+    
+    level = data["level"]
+    name = data["levelName"]
+    print(f"{domain}: Level {level} — {name}")
+    time.sleep(2)
+```
+
+---
+
+## API Response Shape
+
+```json
+{
+  "url": "https://example.com",
+  "scannedAt": "2026-04-18T13:10:58.788Z",
+  "level": 1,
+  "levelName": "Basic Web Presence",
+  "isCommerce": false,
+  "checks": {
+    "discoverability": {
+      "robotsTxt": {
+        "status": "pass",
+        "message": "robots.txt exists with valid format",
+        "evidence": [ ... ],
+        "durationMs": 42
+      }
+    }
+  },
+  "nextLevel": {
+    "target": 2,
+    "name": "Bot-Aware",
+    "requirements": [
+      {
+        "check": "contentSignals",
+        "description": "...",
+        "prompt": "...",
+        "skillUrl": "...",
+        "specUrls": ["..."]
+      }
+    ]
+  }
+}
+```
+
+| Status | Meaning |
+|--------|---------|
+| `pass` | ✅ Check passed |
+| `fail` | ❌ Action needed |
+| `neutral` | ⬜ Not applicable / informational |
+
+---
+
+## Skill Structure
+
+```
+agent-ready-cloudflare/
+├── README.md                          ← You are here
+├── SKILL.md                           ← Main skill (operational flow, API docs, prompt templates)
+│
+├── scan-site/SKILL.md                 ← Meta: scan API + MCP server docs
+│
+│   Discoverability
+├── robots-txt/SKILL.md                ← Implement robots.txt (RFC 9309)
+├── sitemap/SKILL.md                   ← Implement sitemap.xml
+├── link-headers/SKILL.md              ← Link response headers (RFC 8288)
+├── llms-txt/SKILL.md                  ← Publish /llms.txt
+├── llms-full-txt/SKILL.md             ← Publish /llms-full.txt
+│
+│   Content
+├── markdown-negotiation/SKILL.md      ← Accept: text/markdown negotiation
+│
+│   Bot Access Control
+├── ai-rules/SKILL.md                  ← AI bot User-agent rules
+├── content-signals/SKILL.md           ← Content-Signal directives
+├── web-bot-auth/SKILL.md              ← Web Bot Auth (JWKS)
+│
+│   API, Auth, MCP & Skill Discovery
+├── api-catalog/SKILL.md               ← API Catalog (RFC 9727)
+├── oauth-discovery/SKILL.md           ← OAuth/OIDC discovery (RFC 8414)
+├── oauth-protected-resource/SKILL.md  ← Protected Resource Metadata (RFC 9728)
+├── mcp-server-card/SKILL.md           ← MCP Server Card (SEP-1649)
+├── a2a-agent-card/SKILL.md            ← A2A Agent Card (Google A2A)
+├── agent-skills/SKILL.md              ← Agent Skills Discovery Index
+├── webmcp/SKILL.md                    ← WebMCP browser API
+│
+│   Commerce
+├── x402/SKILL.md                      ← x402 payment protocol
+├── ucp/SKILL.md                       ← Universal Commerce Protocol
+└── acp/SKILL.md                       ← Agent Commerce Protocol
+```
+
+**21 files** — 1 main skill + 20 implementation sub-skills.
+
+---
+
+## Sources
+
+| Resource | URL |
+|----------|-----|
+| Scanner | https://isitagentready.com |
+| API endpoint | `POST https://isitagentready.com/api/scan` |
+| MCP server | `https://isitagentready.com/mcp` |
+| API Catalog | https://isitagentready.com/.well-known/api-catalog |
+| Agent Skills Index | https://isitagentready.com/.well-known/agent-skills/index.json |
+| MCP Server Card | https://isitagentready.com/.well-known/mcp/server-card.json |
+| Full docs (llms-full.txt) | https://isitagentready.com/llms-full.txt |
+| Cloudflare Agents | https://developers.cloudflare.com/agents/ |
+| MCP Protocol | https://modelcontextprotocol.io/ |
+| Content Signals | https://contentsignals.org/ |
+| Agent Skills Discovery | https://github.com/cloudflare/agent-skills-discovery-rfc |
--- a/.github/skills/agent-ready-cloudflare/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/SKILL.md
@@ -0,0 +1,783 @@
+---
+name: agent-ready-cloudflare
+description: >
+  Audit and improve website readiness for AI agents using the Cloudflare
+  "Is It Agent Ready?" scanner (isitagentready.com). Covers scanning via API,
+  interpreting results, generating implementation prompts, and fixing every check.
+  Use when the user mentions "agent ready", "isitagentready", "AI agent scan",
+  "agent readiness", "agent-ready score", "MCP server card", "agent skills index",
+  "markdown for agents", "content signals", "web bot auth", "agent discovery",
+  "RFC 9727", "RFC 8288", "RFC 9728", "SEP-1649", "WebMCP", "x402", "UCP", "ACP",
+  or wants to make a website discoverable and usable by AI agents.
+metadata:
+  author: Cloudflare / isitagentready.com
+  version: "3.0"
+  date: 2026-06-03
+  source: https://isitagentready.com
+  category: product-verification
+---
+
+# Agent Ready — Cloudflare Scanner
+
+Audit any website for AI agent readiness, generate actionable fix prompts, and
+implement improvements to increase the agent-ready score.
+
+---
+
+## 0. Operational Flow
+
+Follow this flow every time this skill is activated:
+
+### Step 1 — Get the domain
+
+If the user did not provide a domain, ask:
+
+> Which domain do you want to scan on isitagentready.com?
+
+### Step 2 — Scan via API
+
+```bash
+curl -s -X POST 'https://isitagentready.com/api/scan' \
+  -H 'Content-Type: application/json' \
+  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36' \
+  -H 'Referer: https://isitagentready.com/' \
+  -H 'Origin: https://isitagentready.com' \
+  -d '{"url":"https://DOMAIN/","enabledChecks":["robotsTxt","sitemap","linkHeaders","dnsAid","markdownNegotiation","robotsTxtAiRules","contentSignals","webBotAuth","apiCatalog","oauthDiscovery","oauthProtectedResource","authMd","mcpServerCard","a2aAgentCard","agentSkills","webMcp","x402","mpp","ucp","acp","ap2"]}'
+```
+
+Replace `DOMAIN` with the target domain.
+
+### Step 3 — Generate the Markdown report
+
+Use the API response to build a report with this structure:
+
+```markdown
+# Agent Ready Scan — {domain}
+
+> **Score:** Level {level} — {levelName}
+> **Scanned:** {scannedAt}
+> **Link:** [View online](https://isitagentready.com/{domain})
+
+## Summary
+
+| Category | Score |
+|----------|-------|
+| Discoverability | {passed}/{total} |
+| Content | {passed}/{total} |
+| Bot Access Control | {passed}/{total} |
+| API, Auth, MCP & Skill Discovery | {passed}/{total} |
+| Commerce (Optional) | {passed}/{total} |
+
+## Details
+
+### Discoverability ({passed}/{total})
+
+- ✅ **robots.txt** — {message}
+- ❌ **sitemap.xml** — {message}
+  (... for each check ...)
+
+### (... repeat for each category ...)
+
+## 🔧 How to Implement — Agent Prompts
+
+(... one block per failing check, see Step 4 ...)
+
+## Next Level
+
+**Level {nextLevel.target} — {nextLevel.name}**
+
+To reach the next level, implement:
+- {nextLevel.requirements[].description}
+```
+
+### Step 4 — Generate "How to Implement" prompts
+
+For every check with `status: "fail"` or `status: "neutral"`, generate a prompt
+block using the **Prompt Templates** in Section 8 below. The prompt combines:
+
+1. The **Goal** and **Fix** from the template (static per check)
+2. The **Issue** from the API response (`checks.{category}.{check}.message`)
+3. The **Skill URL** pointing to the sub-skill
+4. The **Docs** links to the relevant RFCs/specs
+
+Format each prompt as a fenced code block the user can copy-paste into a coding agent:
+
+````markdown
+#### ❌ {check name}
+
+**Issue:** {message from API}
+
+```
+Goal: {goal from template}
+
+Issue: {message from API}
+
+Fix: {fix from template}
+
+Skill: https://isitagentready.com/.well-known/agent-skills/{skill-folder}/SKILL.md
+
+Docs: {docs URLs from template}
+```
+
+> 📖 Reference: [{skill-folder}/SKILL.md]({skill-folder}/SKILL.md)
+````
+
+### Step 5 — Deliver
+
+Present the full Markdown report to the user. If they want to save it to a file,
+write it to the requested path.
+
+---
+
+## 1. What It Checks
+
+### Discoverability (4 checks)
+| Check | API Key | Pass criteria |
+|-------|---------|---------------|
+| robots.txt | `robotsTxt` | Returns 200 with `text/plain` containing at least one `User-agent` directive |
+| sitemap.xml | `sitemap` | `/sitemap.xml` returns valid XML, or `Sitemap` directive found in robots.txt |
+| Link headers | `linkHeaders` | Homepage includes `Link` headers with agent-useful relations (`service-desc`, `api-catalog`, etc.) |
+| DNS-AID | `dnsAid` | SVCB/HTTPS records found under `_agents` namespace via DNS-over-HTTPS (Cloudflare → Google fallback) |
+
+### Content (1 check)
+| Check | API Key | Pass criteria |
+|-------|---------|---------------|
+| Markdown for Agents | `markdownNegotiation` | `Accept: text/markdown` returns `Content-Type: text/markdown` |
+
+### Bot Access Control (3 checks)
+| Check | API Key | Pass criteria |
+|-------|---------|---------------|
+| AI bot rules | `robotsTxtAiRules` | robots.txt contains `User-agent` entries for known AI bots (GPTBot, Claude-Web, Google-Extended, etc.) |
+| Content Signals | `contentSignals` | robots.txt contains `Content-Signal` directives with ai-train/search/ai-input |
+| Web Bot Auth | `webBotAuth` | `/.well-known/http-message-signatures-directory` exists with valid JWKS (informational — neutral does not affect score) |
+
+### API, Auth, MCP & Skill Discovery (8 checks)
+| Check | API Key | Pass criteria |
+|-------|---------|---------------|
+| API Catalog | `apiCatalog` | `/.well-known/api-catalog` returns valid `linkset+json` with API entries |
+| OAuth/OIDC | `oauthDiscovery` | `/.well-known/openid-configuration` or `oauth-authorization-server` with valid OAuth metadata |
+| OAuth Protected Resource | `oauthProtectedResource` | `/.well-known/oauth-protected-resource` with `resource` and `authorization_servers` |
+| Auth.md | `authMd` | `/auth.md` exists with valid H1 heading containing "auth.md"; optionally PRM + AS metadata |
+| MCP Server Card | `mcpServerCard` | Valid card at `/.well-known/mcp/server-card.json`, `server-cards.json`, or `mcp.json` with `serverInfo.name` |
+| A2A Agent Card | `a2aAgentCard` | `/.well-known/agent-card.json` with `name`, `version`, and `supportedInterfaces` |
+| Agent Skills Index | `agentSkills` | `/.well-known/agent-skills/index.json` with valid `skills` array (legacy `/.well-known/skills/` also accepted) |
+| WebMCP | `webMcp` | Page exposes MCP tools via `navigator.modelContext.provideContext()` |
+
+### Commerce — Optional (5 checks, scored only if e-commerce signals detected)
+| Check | API Key | Pass criteria |
+|-------|---------|---------------|
+| x402 | `x402` | API routes return HTTP 402 with valid x402 payment headers |
+| MPP | `mpp` | `/openapi.json` with `x-payment-info` extensions on payable operations (Machine Payment Protocol) |
+| UCP | `ucp` | `/.well-known/ucp` with `protocol_version` and `services` |
+| ACP | `acp` | `/.well-known/acp.json` with `protocol.name`, `api_base_url`, `transports`, `capabilities.services` |
+| AP2 | `ap2` | A2A Agent Card includes AP2 extension with role information |
+
+---
+
+## 2. Levels
+
+| Level | Name | Requirements |
+|-------|------|-------------|
+| 0 | Not Ready | Does not meet Level 1 criteria |
+| 1 | Basic Web Presence | Pass 2 of 3: robots.txt, sitemap, link headers |
+| 2 | Bot-Aware | Level 1 + both: AI bot rules AND Content Signals in robots.txt |
+| 3 | Agent-Readable | Level 2 + markdown content negotiation |
+| 4 | Agent-Integrated | Level 3 + 1 of 4: MCP Server Card, A2A Agent Card, Agent Skills, API Catalog |
+| 5 | Agent-Native | Level 4 + 2 of 3: Web Bot Auth, all four integration checks, auth metadata (OAuth discovery or OAuth Protected Resource) |
+
+---
+
+## 3. API Reference
+
+### Endpoint
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+```
+
+### Required Headers (Cloudflare protection)
+
+```
+User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36
+Referer: https://isitagentready.com/
+Origin: https://isitagentready.com
+```
+
+### Request Body
+
+```json
+{
+  "url": "https://example.com/",
+  "enabledChecks": [
+    "robotsTxt", "sitemap", "linkHeaders", "dnsAid",
+    "markdownNegotiation",
+    "robotsTxtAiRules", "contentSignals", "webBotAuth",
+    "apiCatalog", "oauthDiscovery", "oauthProtectedResource", "authMd",
+    "mcpServerCard", "a2aAgentCard", "agentSkills", "webMcp",
+    "x402", "mpp", "ucp", "acp", "ap2"
+  ]
+}
+```
+
+All checks are optional — pass only the ones you want to run.
+
+Set `"format": "agent"` to get a markdown response with fix instructions instead
+of JSON (useful for piping directly to an LLM).
+
+### MCP Server
+
+The scanner is also available as an MCP server:
+
+```
+https://isitagentready.com/mcp
+```
+
+Call the `scan_site` tool with a `url` parameter. See [scan-site/SKILL.md](scan-site/SKILL.md).
+
+### Discovered Endpoints (isitagentready.com itself)
+
+The scanner practices what it preaches. These are its own agent-ready endpoints:
+
+| Endpoint | Content |
+|----------|---------|
+| `/.well-known/api-catalog` | RFC 9727 linkset with scan API and MCP server entries |
+| `/.well-known/mcp/server-card.json` | MCP Server Card (Streamable HTTP transport) |
+| `/.well-known/mcp.json` | Same MCP Server Card (alternate path) |
+| `/.well-known/agent-skills/index.json` | 23 skills in Agent Skills Discovery v0.2.0 format |
+| `/llms.txt` | LLM-friendly overview of the scanner |
+| `/llms-full.txt` | Full documentation — canonical reference for all 18 checks, pass criteria, and level system |
+| `/api/health` | Health check (`{"status":"ok"}`) |
+| `/mcp` | Streamable HTTP MCP server with `scan_site` tool |
+
+The API Catalog links the scan API to its documentation (`/llms-full.txt`),
+its service description (`/.well-known/mcp/server-card.json`), and its health
+endpoint (`/api/health`).
+
+### Response Structure
+
+```json
+{
+  "url": "https://example.com",
+  "scannedAt": "2026-04-18T13:10:58.788Z",
+  "level": 1,
+  "levelName": "Basic Web Presence",
+  "isCommerce": false,
+  "commerceSignals": [],
+  "nextLevel": {
+    "target": 2,
+    "name": "Bot-Aware",
+    "requirements": [
+      {
+        "check": "contentSignals",
+        "description": "...",
+        "shortPrompt": "...",
+        "prompt": "Full implementation prompt...",
+        "specUrls": ["https://..."],
+        "skillUrl": "https://isitagentready.com/.well-known/agent-skills/.../SKILL.md"
+      }
+    ]
+  },
+  "checks": {
+    "<category>": {
+      "<checkKey>": {
+        "status": "pass|fail|neutral",
+        "message": "Human-readable conclusion",
+        "durationMs": 42,
+        "evidence": [
+          {
+            "action": "fetch|parse|conclude",
+            "label": "GET /robots.txt",
+            "request": { "url": "...", "method": "GET" },
+            "response": {
+              "status": 200,
+              "headers": { "content-type": "..." },
+              "bodyPreview": "..."
+            },
+            "finding": {
+              "outcome": "positive|negative|neutral",
+              "summary": "..."
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Status Values
+
+| Status | Icon | Meaning |
+|--------|------|---------|
+| `pass` | ✅ | Check passed |
+| `fail` | ❌ | Action needed |
+| `neutral` | ⬜ | Not applicable / informational |
+
+---
+
+## 4. Web Interface vs API
+
+| Feature | API | Web UI |
+|---------|-----|--------|
+| Score & Level | ✅ | ✅ |
+| Check status + message | ✅ | ✅ |
+| Evidence (audit details) | ✅ Full | ✅ Same |
+| "How to implement" prompts | ⚠️ Only `nextLevel` (1 prompt) | ✅ All failing checks |
+| Skill URLs | ⚠️ Only `nextLevel` | ✅ All checks |
+
+This is why this skill includes the full prompt templates below — to reconstruct
+the web-quality prompts from API data.
+
+---
+
+## 5. Batch Scanning
+
+For multiple domains, add a 2-second delay between requests. Write results
+incrementally to avoid data loss:
+
+```python
+import json, time, urllib.request
+
+HEADERS = {
+    "Content-Type": "application/json",
+    "User-Agent": "Mozilla/5.0 ...",
+    "Referer": "https://isitagentready.com/",
+    "Origin": "https://isitagentready.com"
+}
+CHECKS = ["robotsTxt","sitemap","linkHeaders","dnsAid","markdownNegotiation",
+          "robotsTxtAiRules","contentSignals","webBotAuth","apiCatalog",
+          "oauthDiscovery","oauthProtectedResource","authMd","mcpServerCard",
+          "a2aAgentCard","agentSkills","webMcp","x402","mpp","ucp","acp","ap2"]
+
+for domain in domains:
+    body = json.dumps({"url": f"https://{domain}/", "enabledChecks": CHECKS}).encode()
+    req = urllib.request.Request("https://isitagentready.com/api/scan",
+                                data=body, headers=HEADERS)
+    with urllib.request.urlopen(req, timeout=90) as resp:
+        data = json.loads(resp.read())
+    # process data...
+    time.sleep(2)
+```
+
+---
+
+## 6. Sub-Skills (Implementation Guides)
+
+### Discoverability
+- [robots-txt/SKILL.md](robots-txt/SKILL.md) — Publish `/robots.txt` (RFC 9309)
+- [sitemap/SKILL.md](sitemap/SKILL.md) — Publish `/sitemap.xml`
+- [link-headers/SKILL.md](link-headers/SKILL.md) — Add `Link` response headers (RFC 8288)
+- [dns-aid/SKILL.md](dns-aid/SKILL.md) — Publish DNS-AID SVCB records for agent discovery (draft-mozleywilliams-dnsop-dnsaid)
+- [llms-txt/SKILL.md](llms-txt/SKILL.md) — Publish `/llms.txt` (llmstxt.org)
+- [llms-full-txt/SKILL.md](llms-full-txt/SKILL.md) — Publish `/llms-full.txt`
+
+### Content
+- [markdown-negotiation/SKILL.md](markdown-negotiation/SKILL.md) — Return markdown on `Accept: text/markdown`
+
+### Bot Access Control
+- [ai-rules/SKILL.md](ai-rules/SKILL.md) — AI bot `User-agent` rules in robots.txt
+- [content-signals/SKILL.md](content-signals/SKILL.md) — `Content-Signal` directives
+- [web-bot-auth/SKILL.md](web-bot-auth/SKILL.md) — JWKS for request signing
+
+### API, Auth, MCP & Skill Discovery
+- [api-catalog/SKILL.md](api-catalog/SKILL.md) — API Catalog (RFC 9727)
+- [oauth-discovery/SKILL.md](oauth-discovery/SKILL.md) — OAuth/OIDC discovery (RFC 8414)
+- [oauth-protected-resource/SKILL.md](oauth-protected-resource/SKILL.md) — Protected Resource Metadata (RFC 9728)
+- [auth-md/SKILL.md](auth-md/SKILL.md) — Auth.md agent registration discovery (auth-md.com)
+- [mcp-server-card/SKILL.md](mcp-server-card/SKILL.md) — MCP Server Card (SEP-1649)
+- [a2a-agent-card/SKILL.md](a2a-agent-card/SKILL.md) — A2A Agent Card (Google A2A Protocol)
+- [agent-skills/SKILL.md](agent-skills/SKILL.md) — Agent Skills Discovery Index
+- [webmcp/SKILL.md](webmcp/SKILL.md) — WebMCP browser API
+
+### Commerce (Optional)
+- [x402/SKILL.md](x402/SKILL.md) — x402 HTTP payment protocol
+- [mpp/SKILL.md](mpp/SKILL.md) — Machine Payment Protocol (mpp.dev)
+- [ucp/SKILL.md](ucp/SKILL.md) — Universal Commerce Protocol
+- [acp/SKILL.md](acp/SKILL.md) — Agent Commerce Protocol
+
+### Meta
+- [scan-site/SKILL.md](scan-site/SKILL.md) — Scan any site for agent readiness (includes MCP server endpoint)
+
+---
+
+## 7. Priority Order for Maximum Impact
+
+1. `robots.txt` + `sitemap.xml` → Level 1
+2. `Content Signals` in robots.txt → Level 2
+3. `Markdown for Agents` + `Link headers` → toward Level 3
+4. `MCP Server Card` + `Agent Skills Index` → toward Level 4
+5. `OAuth discovery` + `API Catalog` → full agent interoperability
+
+---
+
+## 8. Prompt Templates per Check
+
+These templates replicate the "How to implement — paste into your coding agent"
+prompts from the web UI. When generating the report (Step 4), use the `{issue}`
+placeholder with the actual `message` from the API response.
+
+### `robotsTxt`
+
+```
+Goal: Publish /robots.txt with clear crawl rules
+
+Issue: {issue}
+
+Fix: Create /robots.txt at the site root with explicit User-agent directives and allow/disallow rules for key paths. Ensure it is plain text and returns 200.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/robots-txt/SKILL.md
+
+Docs: https://www.rfc-editor.org/rfc/rfc9309
+```
+
+Sub-skill: [robots-txt/SKILL.md](robots-txt/SKILL.md)
+
+### `sitemap`
+
+```
+Goal: Publish /sitemap.xml with canonical URLs
+
+Issue: {issue}
+
+Fix: Generate /sitemap.xml listing canonical URLs, keep it updated on publish, and reference it from /robots.txt.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/sitemap/SKILL.md
+
+Docs: https://www.sitemaps.org/protocol.html
+```
+
+Sub-skill: [sitemap/SKILL.md](sitemap/SKILL.md)
+
+### `linkHeaders`
+
+```
+Goal: Include Link response headers for agent discovery (RFC 8288)
+
+Issue: {issue}
+
+Fix: Add Link response headers to your homepage that point agents to useful resources. For example: Link: </.well-known/api-catalog>; rel="api-catalog" to advertise your API catalog, or Link: </docs/api>; rel="service-doc" for API documentation. See RFC 8288 for the Link header format and IANA Link Relations for registered relation types.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/link-headers/SKILL.md
+
+Docs: https://www.rfc-editor.org/rfc/rfc8288, https://www.rfc-editor.org/rfc/rfc9727#section-3
+```
+
+Sub-skill: [link-headers/SKILL.md](link-headers/SKILL.md)
+
+### `markdownNegotiation`
+
+```
+Goal: Return HTML responses as markdown when agents request it
+
+Issue: {issue}
+
+Fix: Enable Markdown for Agents so requests with Accept: text/markdown return a markdown version of your HTML response while HTML stays the default for browsers. Confirm the response uses Content-Type: text/markdown (and x-markdown-tokens if available).
+
+Skill: https://isitagentready.com/.well-known/agent-skills/markdown-negotiation/SKILL.md
+
+Docs: https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/
+```
+
+Sub-skill: [markdown-negotiation/SKILL.md](markdown-negotiation/SKILL.md)
+
+### `robotsTxtAiRules`
+
+```
+Goal: Add User-agent rules for AI crawlers like GPTBot, Claude-Web, and others
+
+Issue: {issue}
+
+Fix: Add explicit User-agent entries for AI crawlers (GPTBot, OAI-SearchBot, Claude-Web, Google-Extended) with allow/disallow rules that match your policy.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/ai-rules/SKILL.md
+
+Docs: https://www.rfc-editor.org/rfc/rfc9309, https://developers.cloudflare.com/ai-crawl-control/
+```
+
+Sub-skill: [ai-rules/SKILL.md](ai-rules/SKILL.md)
+
+### `contentSignals`
+
+```
+Goal: Declare AI content usage preferences with Content Signals in robots.txt
+
+Issue: {issue}
+
+Fix: Add Content-Signal directives to your robots.txt declaring preferences for ai-train, search, and ai-input. For example:
+Content-Signal: ai-train=no, search=yes, ai-input=no
+
+Skill: https://isitagentready.com/.well-known/agent-skills/content-signals/SKILL.md
+
+Docs: https://contentsignals.org/, https://datatracker.ietf.org/doc/draft-romm-aipref-contentsignals/
+```
+
+Sub-skill: [content-signals/SKILL.md](content-signals/SKILL.md)
+
+### `webBotAuth`
+
+```
+Goal: Let your site identify itself as a bot with Web Bot Auth
+
+Issue: {issue}
+
+Fix: Publish a JWKS at /.well-known/http-message-signatures-directory so your site can identify itself when it sends bot or agent requests. Receiving sites can use it to verify those signed requests.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/web-bot-auth/SKILL.md
+
+Docs: https://datatracker.ietf.org/wg/webbotauth/about/, https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/
+```
+
+Sub-skill: [web-bot-auth/SKILL.md](web-bot-auth/SKILL.md)
+
+### `apiCatalog`
+
+```
+Goal: Publish an API catalog for automated API discovery (RFC 9727)
+
+Issue: {issue}
+
+Fix: Create /.well-known/api-catalog returning application/linkset+json with a "linkset" array. Each entry should include an "anchor" URL for the API and link relations for service-desc (OpenAPI spec), service-doc (documentation), and status (health endpoint). See RFC 9727 Appendix A for examples.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/api-catalog/SKILL.md
+
+Docs: https://www.rfc-editor.org/rfc/rfc9727, https://www.rfc-editor.org/rfc/rfc9264
+```
+
+Sub-skill: [api-catalog/SKILL.md](api-catalog/SKILL.md)
+
+### `oauthDiscovery`
+
+```
+Goal: Publish OAuth/OIDC discovery metadata so agents can authenticate with your APIs
+
+Issue: {issue}
+
+Fix: If your site has protected APIs, publish /.well-known/openid-configuration (for OpenID Connect) or /.well-known/oauth-authorization-server (for pure OAuth 2.0) with your issuer, authorization_endpoint, token_endpoint, jwks_uri, and grant_types_supported. This allows AI agents to programmatically discover how to authenticate.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/oauth-discovery/SKILL.md
+
+Docs: http://openid.net/specs/openid-connect-discovery-1_0.html, https://www.rfc-editor.org/rfc/rfc8414
+```
+
+Sub-skill: [oauth-discovery/SKILL.md](oauth-discovery/SKILL.md)
+
+### `oauthProtectedResource`
+
+```
+Goal: Publish OAuth Protected Resource Metadata so agents can discover how to authenticate
+
+Issue: {issue}
+
+Fix: Publish /.well-known/oauth-protected-resource with your resource identifier, authorization_servers (list of OAuth/OIDC issuer URLs that can issue tokens for this resource), and scopes_supported. This tells agents how to obtain access tokens for your protected APIs.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/oauth-protected-resource/SKILL.md
+
+Docs: https://www.rfc-editor.org/rfc/rfc9728
+```
+
+Sub-skill: [oauth-protected-resource/SKILL.md](oauth-protected-resource/SKILL.md)
+
+### `mcpServerCard`
+
+```
+Goal: Publish an MCP Server Card for agent discovery
+
+Issue: {issue}
+
+Fix: Serve an MCP Server Card (SEP-1649) at /.well-known/mcp/server-card.json with serverInfo (name, version), transport endpoint, and capabilities. The schema is being standardized at https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127
+
+Skill: https://isitagentready.com/.well-known/agent-skills/mcp-server-card/SKILL.md
+
+Docs: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127
+```
+
+Sub-skill: [mcp-server-card/SKILL.md](mcp-server-card/SKILL.md)
+
+### `agentSkills`
+
+```
+Goal: Publish an agent skills discovery index
+
+Issue: {issue}
+
+Fix: Publish a skills discovery index at /.well-known/agent-skills/index.json (per the Agent Skills Discovery RFC v0.2.0). Include a $schema field, and a skills array where each entry has name, type, description, url, and a sha256 digest.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/agent-skills/SKILL.md
+
+Docs: https://github.com/cloudflare/agent-skills-discovery-rfc, https://agentskills.io/
+```
+
+Sub-skill: [agent-skills/SKILL.md](agent-skills/SKILL.md)
+
+### `webMcp`
+
+```
+Goal: Support WebMCP to expose site tools to AI agents via the browser
+
+Issue: {issue}
+
+Fix: Implement the WebMCP API by calling navigator.modelContext.provideContext() with tool definitions that expose your site's key actions to AI agents. Each tool needs a name, description, inputSchema (JSON Schema), and an execute callback function.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/webmcp/SKILL.md
+
+Docs: https://webmachinelearning.github.io/webmcp/, https://developer.chrome.com/blog/webmcp-epp
+```
+
+Sub-skill: [webmcp/SKILL.md](webmcp/SKILL.md)
+
+### `x402`
+
+```
+Goal: Support x402 protocol for agent-native HTTP payments
+
+Issue: {issue}
+
+Fix: Add x402 payment middleware to your API routes to enable AI agents to pay for access via HTTP. Use @x402/express, @x402/hono, or @x402/next middleware with a facilitator URL and wallet address. Protected routes will return HTTP 402 with payment requirements that agents can fulfill automatically.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/x402/SKILL.md
+
+Docs: https://x402.org, https://github.com/coinbase/x402, https://docs.x402.org
+```
+
+Sub-skill: [x402/SKILL.md](x402/SKILL.md)
+
+### `ucp`
+
+```
+Goal: Enable content payments via Universal Commerce Protocol
+
+Issue: {issue}
+
+Fix: Serve /.well-known/ucp with protocol version, services, capabilities, and endpoints, and ensure spec URLs and schemas are reachable.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/ucp/SKILL.md
+
+Docs: https://ucp.dev/specification/overview/
+```
+
+Sub-skill: [ucp/SKILL.md](ucp/SKILL.md)
+
+### `acp`
+
+```
+Goal: Publish ACP discovery metadata so agents can discover your commerce API
+
+Issue: {issue}
+
+Fix: Serve /.well-known/acp.json at the origin root with protocol.name "acp", protocol.version, api_base_url, supported transports, and capabilities.services so agents can discover your ACP implementation without creating a checkout session first.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/acp/SKILL.md
+
+Docs: https://agenticcommerce.dev, https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/pull/137
+```
+
+Sub-skill: [acp/SKILL.md](acp/SKILL.md)
+
+### `a2aAgentCard`
+
+```
+Goal: Publish an A2A Agent Card for agent-to-agent discovery
+
+Issue: {issue}
+
+Fix: Serve JSON at /.well-known/agent-card.json with name, version, description, supportedInterfaces (service URL and transport), capabilities, and skills (each with id, name, description). See the A2A Protocol Specification for the full schema.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/a2a-agent-card/SKILL.md
+
+Docs: https://a2a-protocol.org/latest/specification/, https://a2a-protocol.org/latest/topics/agent-discovery/
+```
+
+Sub-skill: [a2a-agent-card/SKILL.md](a2a-agent-card/SKILL.md)
+
+### `dnsAid`
+
+```
+Goal: Publish DNS for AI Discovery (DNS-AID) records for DNS-based agent discovery
+
+Issue: {issue}
+
+Fix: Publish SVCB or HTTPS records under your domain's _agents namespace (e.g. _a2a._agents.example.com or _index._agents.example.com). Use alpn and port SvcParamKeys with mandatory=alpn,port. Use numeric keyNNNNN names for experimental custom parameters until registered. Sign zones with DNSSEC.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/dns-aid/SKILL.md
+
+Docs: https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/, https://www.rfc-editor.org/info/rfc9460
+```
+
+Sub-skill: [dns-aid/SKILL.md](dns-aid/SKILL.md)
+
+### `authMd`
+
+```
+Goal: Publish Auth.md agent registration discovery metadata
+
+Issue: {issue}
+
+Fix: Serve /auth.md from the site root as Markdown with an H1 heading containing "auth.md". Include OAuth Protected Resource Metadata at /.well-known/oauth-protected-resource and Authorization Server metadata. Add an agent_auth block with skill, register_uri, and registration methods. If OAuth is not available, keep /auth.md self-contained with audience, registration endpoints, and credential use.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/auth-md/SKILL.md
+
+Docs: https://auth-md.com
+```
+
+Sub-skill: [auth-md/SKILL.md](auth-md/SKILL.md)
+
+### `mpp`
+
+```
+Goal: Support MPP (Machine Payment Protocol) for agent-native HTTP payments
+
+Issue: {issue}
+
+Fix: Serve /openapi.json at the site root with HTTP 200. Include x-payment-info extensions on payable operations declaring intent (charge or session), method (tempo, stripe, lightning, card), and amount. Optionally include currency, description, and top-level x-service-info with categories.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/mpp/SKILL.md
+
+Docs: https://mpp.dev, https://paymentauth.org/draft-payment-discovery-00.txt
+```
+
+Sub-skill: [mpp/SKILL.md](mpp/SKILL.md)
+
+### `llmsTxt`
+
+```
+Goal: Publish an LLM-friendly overview at /llms.txt
+
+Issue: {issue}
+
+Fix: Serve /llms.txt as plain text (UTF-8) with HTTP 200. Start with an H1 title line, include a short summary paragraph, and link to the most important content sections for agents. Optionally link to /llms-full.txt for expanded content.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/llms-txt/SKILL.md
+
+Docs: https://llmstxt.org/
+```
+
+Sub-skill: [llms-txt/SKILL.md](llms-txt/SKILL.md)
+
+### `llmsFullTxt`
+
+```
+Goal: Publish expanded LLM content at /llms-full.txt
+
+Issue: {issue}
+
+Fix: Serve /llms-full.txt as plain text (UTF-8) with HTTP 200. Include structured, detailed content suitable for LLM ingestion covering key topics, APIs, and documentation. Link to it from your /llms.txt file.
+
+Skill: https://isitagentready.com/.well-known/agent-skills/llms-full-txt/SKILL.md
+
+Docs: https://llmstxt.org/
+```
+
+Sub-skill: [llms-full-txt/SKILL.md](llms-full-txt/SKILL.md)
+
+### `ap2`
+
+```
+Goal: Declare AP2 support in your A2A Agent Card for agent payments
+
+Issue: {issue}
+
+Fix: Add AP2 extension to your A2A Agent Card at /.well-known/agent-card.json with your role (merchant, shopper, etc.) so agents can discover your payment capabilities.
+
+Docs: https://ap2-protocol.org/
+```
--- a/.github/skills/agent-ready-cloudflare/a2a-agent-card/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/a2a-agent-card/SKILL.md
@@ -0,0 +1,35 @@
+---
+name: agent-ready-a2a-agent-card
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement A2A Agent Card
+---
+# Implement A2A Agent Card
+
+Publish an A2A Agent Card for agent-to-agent discovery per the
+[A2A Protocol Specification](https://a2a-protocol.org/latest/specification/).
+
+## Requirements
+
+- Serve JSON at `/.well-known/agent-card.json` with HTTP 200
+- Include `name`, `version`, and `description`
+- Include `supportedInterfaces` with service URL and transport protocol
+- List `capabilities` and `skills` (each with `id`, `name`, `description`)
+
+See [Agent Discovery](https://a2a-protocol.org/latest/topics/agent-discovery/)
+for the full schema.
+
+## Cloudflare
+
+[Agents SDK](https://developers.cloudflare.com/agents/) supports building
+A2A-compatible agents on Workers.
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discovery.a2aAgentCard.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/acp/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/acp/SKILL.md
@@ -0,0 +1,28 @@
+---
+name: agent-ready-acp
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement ACP Discovery Document
+---
+# Implement ACP Discovery Document
+
+Publish an ACP discovery document so AI agents can discover your
+[Agentic Commerce Protocol](https://agenticcommerce.dev) implementation.
+
+## Requirements
+
+- Serve JSON at `/.well-known/acp.json` with HTTP 200
+- Include `protocol.name` set to `"acp"` and `protocol.version`
+- Include `api_base_url` as an absolute HTTP(S) URL
+- Include `transports` as a non-empty array of supported transport types
+- Include `capabilities.services` as a non-empty array of offered services
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.commerce.acp.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/agent-skills/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/agent-skills/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: agent-ready-agent-skills
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement Agent Skills Discovery Index
+---
+# Implement Agent Skills Discovery Index
+
+Publish a skills discovery document per the
+[Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) v0.2.0.
+
+## Requirements
+
+- Serve JSON at `/.well-known/agent-skills/index.json` with HTTP 200
+- Include a `$schema` field set to `https://schemas.agentskills.io/discovery/0.2.0/schema.json`
+- Include a `skills` array where each entry has:
+  - `name` — skill identifier (lowercase alphanumeric + hyphens)
+  - `type` — `"skill-md"` (single SKILL.md) or `"archive"` (bundled archive)
+  - `description` — brief description of what the skill does
+  - `url` — URL to the skill artifact (SKILL.md file or archive)
+  - `digest` — SHA-256 hash of the artifact (`sha256:{hex}`)
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discovery.agentSkills.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/ai-rules/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/ai-rules/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: agent-ready-ai-rules
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement AI Bot Rules in robots.txt
+---
+# Implement AI Bot Rules in robots.txt
+
+Add explicit `User-agent` entries for AI crawlers in your robots.txt per
+[RFC 9309](https://www.rfc-editor.org/rfc/rfc9309).
+
+## Requirements
+
+- Add `User-agent` blocks for AI-specific bots: `GPTBot`, `OAI-SearchBot`, `Claude-Web`, `Google-Extended`, `Amazonbot`, `anthropic-ai`, `Bytespider`, `CCBot`, `Applebot-Extended`
+- Set `Allow` and/or `Disallow` rules matching your content policy
+- A wildcard `User-agent: *` block alone is not sufficient — explicit AI bot entries are required
+
+## Cloudflare
+
+[AI Crawl Control](https://developers.cloudflare.com/ai-crawl-control/)
+lets you manage AI bot rules from the dashboard without editing robots.txt manually.
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.botAccessControl.robotsTxtAiRules.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/api-catalog/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/api-catalog/SKILL.md
@@ -0,0 +1,27 @@
+---
+name: agent-ready-api-catalog
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement API Catalog
+---
+# Implement API Catalog
+
+Publish an API catalog for automated discovery per
+[RFC 9727](https://www.rfc-editor.org/rfc/rfc9727).
+
+## Requirements
+
+- Serve `/.well-known/api-catalog` with `Content-Type: application/linkset+json` and HTTP 200
+- Include a `linkset` array with entries for each API
+- Each entry needs an `anchor` URL and link relations: `service-desc` (OpenAPI spec), `service-doc` (docs), and optionally `status` (health endpoint)
+- See [RFC 9727 Appendix A](https://www.rfc-editor.org/rfc/rfc9727#appendix-A) for examples
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discovery.apiCatalog.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/auth-md/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/auth-md/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: agent-ready-auth-md
+description: >
+  Sub-skill de agent-ready-cloudflare: Skill: Implement Auth.md Agent Registration Discovery
+---
+# Skill: Implement Auth.md Agent Registration Discovery
+
+## What This Skill Does
+
+Helps a service publish Auth.md support for agent registration. Use this when a scanner reports the `authMd` check is failing or when adding the Auth.md standard to an API or application.
+
+## Requirements
+
+- Serve `/auth.md` from the service root as Markdown with an H1 heading that contains `auth.md` (for example, `# auth.md` or `# Example auth.md`).
+- Prefer publishing OAuth Protected Resource Metadata at `/.well-known/oauth-protected-resource` for the resource server.
+- Include `resource`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported` with `header` in the PRM document.
+- Publish OAuth Authorization Server metadata at each advertised authorization server's `/.well-known/oauth-authorization-server` URL.
+- Include a valid `issuer` in Authorization Server metadata and ensure it matches the issuer advertised in PRM.
+- Add an `agent_auth` block with `skill`, `register_uri`, and at least one complete registration method when Authorization Server metadata is available.
+- If OAuth metadata is not available, keep `/auth.md` self-contained: identify the agent audience, document registration or provisioning endpoint(s), list supported method(s), and explain credential use.
+
+## Flow Metadata
+
+- **ID-JAG**: include `identity_types_supported: ["identity_assertion"]`, `identity_assertion.assertion_types_supported` with `urn:ietf:params:oauth:token-type:id-jag`, and credential types. Include `revocation_uri` and the revocation event in `events_supported` when supported.
+- **Verified email**: include `identity_assertion.assertion_types_supported` with `verified_email`, credential types, and `claim_uri`.
+- **Anonymous**: include `identity_types_supported: ["anonymous"]`, `anonymous.credential_types_supported`, and `claim_uri`.
+
+## Validate
+
+```http
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discovery.authMd.status` is `"pass"`.
+
+## References
+
+- [Auth.md Specification](https://auth-md.com)
+- [RFC 9728 — OAuth Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728)
+- [RFC 8414 — OAuth Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414)
--- a/.github/skills/agent-ready-cloudflare/content-signals/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/content-signals/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: agent-ready-content-signals
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement Content Signals
+---
+# Implement Content Signals
+
+Declare AI content usage preferences in your robots.txt using
+[Content Signals](https://contentsignals.org/)
+([IETF draft](https://datatracker.ietf.org/doc/draft-romm-aipref-contentsignals/)).
+
+## Requirements
+
+- Add `Content-Signal` directives to your robots.txt under the relevant `User-agent` block
+- Declare preferences for `ai-train`, `search`, and `ai-input`
+- Example: `Content-Signal: ai-train=no, search=yes, ai-input=no`
+
+## Cloudflare
+
+[AI Crawl Control](https://developers.cloudflare.com/ai-crawl-control/)
+supports Content Signals configuration from the dashboard.
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.botAccessControl.contentSignals.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/dns-aid/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/dns-aid/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: agent-ready-dns-aid
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement DNS for AI Discovery (DNS-AID)
+---
+# Implement DNS for AI Discovery (DNS-AID)
+
+Publish DNS for AI Discovery (DNS-AID) records so agents can discover your agent endpoints through DNS.
+
+## Requirements
+
+- Publish DNS for AI Discovery (DNS-AID) records under your domain's `_agents` namespace, such as `_index._agents.example.com` or `_a2a._agents.example.com`
+- Use ServiceMode `SVCB` records, or `HTTPS` records for HTTPS endpoints, with `alpn` and endpoint connection parameters
+- Use numeric `keyNNNNN` SvcParamKey names for experimental DNS for AI Discovery (DNS-AID) custom parameters until they are registered
+- Sign public DNS for AI Discovery (DNS-AID) discovery zones with DNSSEC so validating resolvers return authenticated data
+
+## Example
+
+```dns
+_a2a._agents.example.com. 3600 IN SVCB 1 agent.example.com. alpn="a2a" port=443 mandatory=alpn,port
+```
+
+## Validate
+
+The scanner validates DNS for AI Discovery (DNS-AID) via DNS-over-HTTPS. By default, the scanner uses Cloudflare's `https://cloudflare-dns.com/dns-query` with automatic fallback to `https://dns.google/resolve` on resolver-level failures. Library callers can override the resolver with `ScanOptions.dohResolverUrl` (disables fallback).
+
+```http
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discoverability.dnsAid.status` is `"pass"`.
+
+## References
+
+- [draft-mozleywilliams-dnsop-dnsaid](https://datatracker.ietf.org/doc/draft-mozleywilliams-dnsop-dnsaid/)
+- [RFC 9460 — SVCB and HTTPS Resource Records](https://www.rfc-editor.org/info/rfc9460)
--- a/.github/skills/agent-ready-cloudflare/link-headers/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/link-headers/SKILL.md
@@ -0,0 +1,34 @@
+---
+name: agent-ready-link-headers
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement Link Response Headers
+---
+# Implement Link Response Headers
+
+Add Link response headers to your homepage for agent discovery per
+[RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) and
+[RFC 9727 Section 3](https://www.rfc-editor.org/rfc/rfc9727#section-3).
+
+## Requirements
+
+- Return `Link` headers on your homepage response pointing to machine-readable resources
+- Use registered relation types: `api-catalog`, `service-desc`, `service-doc`, `describedby`
+- Example: `Link: </.well-known/api-catalog>; rel="api-catalog"`
+- Multiple Link headers or comma-separated values are both valid
+
+## Cloudflare
+
+Use [Transform Rules](https://developers.cloudflare.com/rules/transform/) or
+[Workers](https://developers.cloudflare.com/workers/) to add Link headers
+without modifying your origin server.
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discoverability.linkHeaders.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/llms-full-txt/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/llms-full-txt/SKILL.md
@@ -0,0 +1,27 @@
+---
+name: agent-ready-llms-full-txt
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement llms-full.txt
+---
+# Implement llms-full.txt
+
+Publish expanded LLM content per
+[llmstxt.org](https://llmstxt.org/).
+
+## Requirements
+
+- Serve `/llms-full.txt` as plain text (UTF-8) with HTTP 200
+- Include structured, detailed content suitable for LLM ingestion
+- Cover the key topics, APIs, and documentation from your site
+- Link to it from your `/llms.txt` file
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Confirm your deployed site serves `/llms-full.txt` exactly as intended.
--- a/.github/skills/agent-ready-cloudflare/llms-txt/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/llms-txt/SKILL.md
@@ -0,0 +1,28 @@
+---
+name: agent-ready-llms-txt
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement llms.txt
+---
+# Implement llms.txt
+
+Publish an LLM-friendly overview of your site per
+[llmstxt.org](https://llmstxt.org/).
+
+## Requirements
+
+- Serve `/llms.txt` as plain text (UTF-8) with HTTP 200
+- Start with an H1 (`# Site Name`) title line
+- Include a short summary paragraph describing your site
+- Link to the most important content sections for agents
+- Optionally link to `/llms-full.txt` for expanded content
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Confirm your deployed site serves `/llms.txt` exactly as intended.
--- a/.github/skills/agent-ready-cloudflare/markdown-negotiation/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/markdown-negotiation/SKILL.md
@@ -0,0 +1,34 @@
+---
+name: agent-ready-markdown-negotiation
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement Markdown Content Negotiation
+---
+# Implement Markdown Content Negotiation
+
+Support `Accept: text/markdown` content negotiation so agents can request
+markdown versions of your pages.
+See [llmstxt.org](https://llmstxt.org/) and
+[Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/).
+
+## Requirements
+
+- When a request includes `Accept: text/markdown`, return a markdown representation of the page
+- Set `Content-Type: text/markdown` on the response
+- HTML remains the default for requests without the markdown accept header
+- Include an `x-markdown-tokens` header with the token count if available
+
+## Cloudflare
+
+[Markdown for Agents](https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/)
+enables this automatically for Cloudflare zones — no application code changes needed.
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.contentAccessibility.markdownNegotiation.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/mcp-server-card/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/mcp-server-card/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: agent-ready-mcp-server-card
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement MCP Server Card
+---
+# Implement MCP Server Card
+
+Publish an MCP Server Card for agent discovery per
+[SEP-1649](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127).
+
+## Requirements
+
+- Serve JSON at `/.well-known/mcp/server-card.json` with HTTP 200
+- Include `serverInfo` with `name` and `version`
+- Include a transport `endpoint` URL (e.g., `/mcp` for Streamable HTTP)
+- List `capabilities` (tools, resources, prompts) the server supports
+
+## Cloudflare
+
+[Agents SDK](https://developers.cloudflare.com/agents/) and
+[Workers](https://developers.cloudflare.com/workers/) make it straightforward
+to build and deploy MCP servers with server card support.
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discovery.mcpServerCard.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/mpp/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/mpp/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: agent-ready-mpp
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement MPP Payment Discovery
+---
+# Implement MPP Payment Discovery
+
+Publish an OpenAPI document with MPP payment discovery metadata so AI agents
+can discover your payable endpoints via the
+[Machine Payment Protocol](https://mpp.dev)
+([spec](https://paymentauth.org/draft-payment-discovery-00.txt)).
+
+## Requirements
+
+- Serve `/openapi.json` at the site root with HTTP 200
+- Include `x-payment-info` extensions on payable operations
+- Each `x-payment-info` must declare `intent` (charge or session), `method` (tempo, stripe, lightning, card), and `amount`
+- Optionally include `currency`, `description`, and top-level `x-service-info` with categories
+
+## Example
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": { "title": "My API", "version": "1.0" },
+  "paths": {
+    "/api/generate": {
+      "post": {
+        "x-payment-info": {
+          "intent": "charge",
+          "method": "stripe",
+          "amount": "0.01",
+          "currency": "USD",
+          "description": "Generate content"
+        }
+      }
+    }
+  }
+}
+```
+
+## Validate
+
+```http
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.commerce.mpp.status` is `"pass"`.
+
+## References
+
+- [Machine Payment Protocol](https://mpp.dev)
+- [Payment Discovery Spec](https://paymentauth.org/draft-payment-discovery-00.txt)
--- a/.github/skills/agent-ready-cloudflare/oauth-discovery/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/oauth-discovery/SKILL.md
@@ -0,0 +1,33 @@
+---
+name: agent-ready-oauth-discovery
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement OAuth/OIDC Discovery
+---
+# Implement OAuth/OIDC Discovery
+
+Publish OAuth or OpenID Connect discovery metadata so agents can authenticate
+with your APIs.
+See [OpenID Connect Discovery](http://openid.net/specs/openid-connect-discovery-1_0.html)
+and [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414).
+
+## Requirements
+
+- Serve JSON at `/.well-known/openid-configuration` (OIDC) or `/.well-known/oauth-authorization-server` (OAuth 2.0)
+- Include `issuer`, `authorization_endpoint`, `token_endpoint`, `jwks_uri`
+- List `grant_types_supported` and `response_types_supported`
+
+## Cloudflare
+
+[Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/identity/)
+can serve as an identity provider, or use Workers to proxy discovery metadata.
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discovery.oauthDiscovery.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/oauth-protected-resource/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/oauth-protected-resource/SKILL.md
@@ -0,0 +1,34 @@
+---
+name: agent-ready-oauth-protected-resource
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement OAuth Protected Resource Metadata
+---
+# Implement OAuth Protected Resource Metadata
+
+Publish OAuth Protected Resource Metadata so agents can discover how to
+authenticate per [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728).
+
+## Requirements
+
+- Serve JSON at `/.well-known/oauth-protected-resource` with HTTP 200
+- Include `resource` (your resource identifier URL)
+- Include `authorization_servers` (array of OAuth/OIDC issuer URLs)
+- Optionally include `scopes_supported`
+- Optionally return `WWW-Authenticate` with `resource_metadata` on 401 responses
+
+## Cloudflare
+
+Use [Workers](https://developers.cloudflare.com/workers/) to serve the
+metadata endpoint and [Access](https://developers.cloudflare.com/cloudflare-one/)
+as the authorization server.
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discovery.oauthProtectedResource.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/robots-txt/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/robots-txt/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: agent-ready-robots-txt
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement robots.txt
+---
+# Implement robots.txt
+
+Publish a valid robots.txt at your site root per
+[RFC 9309](https://www.rfc-editor.org/rfc/rfc9309).
+
+## Requirements
+
+- Serve `/robots.txt` as `text/plain` with HTTP 200
+- Include `User-agent` directives with `Allow`/`Disallow` rules
+- Reference your sitemap if one exists: `Sitemap: https://example.com/sitemap.xml`
+
+## Cloudflare
+
+[AI Crawl Control](https://developers.cloudflare.com/ai-crawl-control/)
+can manage your robots.txt from the dashboard, including AI-specific bot rules.
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discoverability.robotsTxt.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/scan-site/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/scan-site/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: agent-ready-scan-site
+description: >
+  Sub-skill de agent-ready-cloudflare: Skill: Scan Site for Agent Readiness
+---
+# Skill: Scan Site for Agent Readiness
+
+## What This Skill Does
+
+Scans any website URL and checks whether it implements the standards and protocols that make it accessible to AI agents. Checks 18 standards across 5 categories: discoverability, content accessibility, bot access control, API/auth/MCP discovery, and commerce. Returns a readiness level (0-5), the status of all 18 checks, and fix instructions for any failing checks.
+
+## When to Use It
+
+- Checking whether a site supports agent protocols (MCP, robots.txt, Link headers, etc.)
+- Debugging why a site is missing specific agent-readiness checks
+- Getting actionable fix instructions to improve a site's agent readiness
+- Comparing agent readiness across multiple sites
+
+## How to Call It
+
+Send a POST request to the scan API:
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://example.com", "format": "agent"}
+```
+
+### Parameters
+
+- `url` (required): The URL to scan. Must be a valid HTTP or HTTPS URL.
+- `format` (optional): Set to `"agent"` for a markdown response with fix instructions, or `"json"` (default) for structured data.
+
+### Using the MCP Server
+
+Alternatively, connect to the MCP server at:
+
+```
+https://isitagentready.com/mcp
+```
+
+Call the `scan_site` tool with a `url` parameter.
+
+## How to Interpret Results
+
+### JSON Format
+
+The response includes:
+
+- `level`: Integer 0-5 indicating overall readiness
+- `levelName`: Human-readable level name (e.g., "Agent-Readable")
+- `checks`: Object with 5 categories, each containing individual check results
+- `nextLevel`: What's needed to reach the next level
+- Each check has `status` ("pass", "fail", or "unableToCheck") and a `message`
+
+### Agent Format
+
+Returns a markdown document listing:
+- The site's current score (e.g., "3/5 Agent-Readable")
+- All failing checks with descriptions and fix instructions
+- If all checks pass, a confirmation message
+
+### Level Scale
+
+| Level | Name | Key Requirements |
+|-------|------|-----------------|
+| 0 | Not Ready | Fewer than 2 of: robots.txt, sitemap, Link headers |
+| 1 | Basic Web Presence | 2 of 3: robots.txt, sitemap, Link headers |
+| 2 | Bot-Aware | Level 1 + both: AI bot rules in robots.txt, Content Signals |
+| 3 | Agent-Readable | Level 2 + markdown content negotiation |
+| 4 | Agent-Integrated | Level 3 + 1 of 4: MCP Server Card, agent skills, API catalog, WebMCP |
+| 5 | Agent-Native | Level 4 + 2 of 4: Web Bot Auth, all integrations, commerce (UCP/x402), auth metadata |
--- a/.github/skills/agent-ready-cloudflare/sitemap/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/sitemap/SKILL.md
@@ -0,0 +1,27 @@
+---
+name: agent-ready-sitemap
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement sitemap.xml
+---
+# Implement sitemap.xml
+
+Publish an XML sitemap at your site root per the
+[Sitemaps protocol](https://www.sitemaps.org/protocol.html).
+
+## Requirements
+
+- Serve `/sitemap.xml` as valid XML with HTTP 200
+- List canonical `<url><loc>` entries for your public pages
+- Keep it updated when content is published or removed
+- Reference it from robots.txt: `Sitemap: https://example.com/sitemap.xml`
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discoverability.sitemap.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/ucp/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/ucp/SKILL.md
@@ -0,0 +1,26 @@
+---
+name: agent-ready-ucp
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement Universal Commerce Protocol (UCP)
+---
+# Implement Universal Commerce Protocol (UCP)
+
+Enable content payments via the Universal Commerce Protocol per the
+[UCP Specification](https://ucp.dev/specification/overview/).
+
+## Requirements
+
+- Serve JSON at `/.well-known/ucp` with HTTP 200
+- Include `protocol_version`, `services`, `capabilities`, and `endpoints`
+- Ensure referenced spec URLs and schemas are reachable
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.commerce.ucp.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/web-bot-auth/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/web-bot-auth/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: agent-ready-web-bot-auth
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement Web Bot Auth
+---
+# Implement Web Bot Auth
+
+Use Web Bot Auth so your site can identify itself when it sends bot or agent requests, per the
+[IETF WebBotAuth WG](https://datatracker.ietf.org/wg/webbotauth/about/).
+
+## Requirements
+
+- Publish a JWKS (JSON Web Key Set) at `/.well-known/http-message-signatures-directory`
+- The JWKS must contain at least one public key for signature verification
+- Sign requests sent by your bot or agent so receiving sites can verify them
+- Include `Signature-Agent` and `Signature-Input` headers on those signed requests
+
+## Cloudflare
+
+[Web Bot Auth on Cloudflare](https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/)
+provides built-in support for verifying bot request signatures.
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.botAccessControl.webBotAuth.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/webmcp/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/webmcp/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: agent-ready-webmcp
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement WebMCP
+---
+# Implement WebMCP
+
+Expose site tools to AI agents via the browser using the
+[WebMCP API](https://webmachinelearning.github.io/webmcp/)
+([Chrome blog](https://developer.chrome.com/blog/webmcp-epp)).
+
+## Requirements
+
+- Call `navigator.modelContext.registerTool()` for each tool you want to expose
+- Each tool needs `name`, `description`, `inputSchema` (JSON Schema), and an `execute` callback
+- Tools should expose your site's key actions (search, navigation, data retrieval)
+- Use an `AbortController` signal to unregister tools when no longer needed
+- The API is detected via browser rendering — ensure the script runs on page load
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.discovery.webMcp.status` is `"pass"`.
--- a/.github/skills/agent-ready-cloudflare/x402/SKILL.md
+++ b/.github/skills/agent-ready-cloudflare/x402/SKILL.md
@@ -0,0 +1,28 @@
+---
+name: agent-ready-x402
+description: >
+  Sub-skill de agent-ready-cloudflare: Implement x402 Payment Protocol
+---
+# Implement x402 Payment Protocol
+
+Support agent-native HTTP payments via the
+[x402 protocol](https://x402.org)
+([docs](https://docs.x402.org), [GitHub](https://github.com/coinbase/x402)).
+
+## Requirements
+
+- Add x402 payment middleware to your API routes
+- Use `@x402/express`, `@x402/hono`, or `@x402/next` middleware
+- Configure a facilitator URL and wallet address
+- Protected routes return HTTP 402 with payment requirements that agents fulfill automatically
+
+## Validate
+
+```
+POST https://isitagentready.com/api/scan
+Content-Type: application/json
+
+{"url": "https://YOUR-SITE.com"}
+```
+
+Check that `checks.commerce.x402.status` is `"pass"`.
--- a/.github/skills/astro-sites-manager/SKILL.md
+++ b/.github/skills/astro-sites-manager/SKILL.md
@@ -0,0 +1,251 @@
+---
+name: astro-sites-manager
+description: >
+  Comprehensive skill for building, migrating, and maintaining Astro v7
+  projects. Covers best practices from the official AGENTS.md, the v6→v7
+  migration path, validation of breaking/deprecated patterns, AI-enhanced dev
+  server usage (background mode, JSON logging), advanced routing with
+  src/fetch.ts, route caching, Sätteri Markdown, and the Rust compiler. Use
+  when the user mentions 'Astro', '.astro files', 'astro dev', 'astro build',
+  'islands architecture', 'content collections', 'SSG', 'SSR adapter',
+  'upgrade to Astro 7', 'migrate Astro', 'Astro v7', 'Astro v6', 'Sätteri',
+  'route caching', 'Astro.cache', 'astro dev --background', 'src/fetch.ts',
+  'advanced routing', 'Hono + Astro', 'Rolldown', 'Vite 8', 'queued
+  rendering', 'CDN cache provider', 'Astro AI', 'related content',
+  'related posts', 'vector embeddings Astro', 'astro-related-content',
+  or asks about static site generation with Astro.
+metadata:
+  author: ft.ia.br
+  version: "1.0.0"
+  date: 2026-06-22
+  repository: https://github.com/fabricioctelles/skills
+  license: Apache-2.0
+  category: ci-cd-and-deployment
+---
+
+# Astro Framework — v7
+
+## MCP Documentation Access
+
+This skill works alongside the **Astro Docs MCP server**. Before answering Astro questions, check if the `astro-docs` MCP tool is available and query it for the latest documentation. The MCP server provides real-time access to docs.astro.build and is the single source of truth for current APIs.
+
+```
+MCP Server: astro-docs
+Tool: search_astro_docs
+```
+
+If the MCP server is unavailable, fall back to the reference material in this skill and https://docs.astro.build.
+
+---
+
+## Best Practices
+
+### Component Design
+- One `.astro` component per file. Keep components small and focused.
+- Use frontmatter (`---`) for data fetching and logic; template below for markup only.
+- Prefer Astro components over framework components unless client interactivity is needed.
+- Use `client:*` directives sparingly — each adds JavaScript to the bundle.
+- Directive hierarchy: `client:idle` > `client:visible` > `client:load` (prefer lazy).
+
+### Routing & Pages
+- Use file-based routing in `src/pages/`. Dynamic routes: `[slug].astro`, `[...path].astro`.
+- Always export `getStaticPaths()` for prerendered dynamic routes.
+- For SSR pages: `export const prerender = false` at the top.
+- Use `src/fetch.ts` (v7) only when you need control beyond middleware — don't use it for simple auth.
+
+### Content Collections
+- Define schemas in `content.config.ts` with Zod — never trust untyped content.
+- Use `getCollection()` for lists, `getEntry()` for single items.
+- Prefer `glob()` loader for local files, custom loaders for CMS data.
+
+### Performance
+- Default to static (`prerender = true`). Use SSR only for personalized/dynamic content.
+- Use `<Image />` from `astro:assets` — never raw `<img>` for local images.
+- Prefer Sätteri (default v7) over unified for Markdown — it's significantly faster.
+- Use Server Islands (`server:defer`) for mixing static shells with dynamic fragments.
+
+### Styling
+- Scoped `<style>` in `.astro` files is default and preferred.
+- Use `is:global` only when truly needed (third-party component styling).
+- Tailwind: install with `astro add tailwind`, don't configure manually.
+
+### TypeScript
+- Run `astro sync` after changing content schemas or env variables.
+- Run `astro check` before committing — catches template type errors other tools miss.
+- Use `astro:env/server` and `astro:env/client` for typed env variables (never `process.env` directly).
+
+### Development Workflow
+- Use `astro dev` for HMR. Never use `python -m http.server` or other static servers.
+- Use `astro add` for official integrations — don't manually edit config for them.
+- Use `astro build && astro preview` to test production behavior locally.
+- In AI agent workflows: use `astro dev --background` and validate via `/_astro/status`.
+
+---
+
+## CLI Commands
+
+```bash
+npx astro dev              # Dev server (foreground)
+npx astro dev --background # Dev server (detached, for AI agents)
+npx astro dev --json       # Dev server with JSON structured logs
+npx astro build            # Production build
+npx astro preview          # Serve production build locally
+npx astro check            # Type checking and diagnostics
+npx astro sync             # Generate TypeScript types
+npx astro add <integration># Install and configure integration
+```
+
+### Background Dev Server (AI Agents)
+
+When working as an AI agent, use background mode:
+
+```bash
+# Start (blocks until ready, then detaches)
+astro dev --background
+# → Dev server running at http://localhost:4321 (pid 12345)
+
+# Check status
+astro dev status
+
+# Read logs
+astro dev logs
+
+# Stop
+astro dev stop
+
+# Health check endpoint (JSON)
+curl http://localhost:4321/_astro/status
+# → {"ok": true}
+```
+
+**Key behaviors:**
+- Lockfile prevents duplicate instances — starting again returns existing instance
+- All commands are idempotent (stop when not running = silent success)
+- Auto-detected when running inside an AI agent (no flag needed)
+- Opt out: `ASTRO_DEV_BACKGROUND=0 astro dev`
+
+---
+
+## Project Structure
+
+```
+src/
+├── pages/          # File-based routing (.astro, .md, .mdx)
+├── layouts/        # Reusable page layouts
+├── components/     # Astro & framework components
+├── content/        # Content collections (type-safe)
+├── middleware.ts   # Request middleware
+├── fetch.ts        # Advanced routing (v7, optional)
+├── styles/         # Global CSS
+├── assets/         # Optimized assets (images, fonts)
+├── actions/        # Server actions
+└── env.d.ts        # Environment type declarations
+astro.config.mjs    # Main configuration
+content.config.ts   # Content collection schemas
+tsconfig.json       # TypeScript config
+```
+
+---
+
+## Configuration (v7)
+
+```typescript
+import { defineConfig, memoryCache, logHandlers } from 'astro/config';
+
+export default defineConfig({
+  // Output mode
+  output: 'static', // or configure per-page with server adapter
+
+  // Route caching (stable in v7)
+  cache: {
+    provider: memoryCache(),
+  },
+  routeRules: {
+    '/blog/[...path]': { maxAge: 300, swr: 60 },
+  },
+
+  // Logger (stable in v7)
+  logger: logHandlers.json(), // or .console(), or .compose(...)
+
+  // Markdown (Sätteri is default in v7)
+  markdown: {
+    // No config needed for defaults (GFM, smartypants, heading IDs)
+    // For extra features:
+    // processor: satteri({ features: { directive: true, math: true } })
+  },
+
+  // Advanced routing file (default: src/fetch.ts)
+  // fetchFile: null, // disable if src/fetch.ts is used for other purposes
+
+  // Whitespace (v7 default: 'jsx')
+  compressHTML: 'jsx', // or true (v6 behavior), or false (preserve all)
+});
+```
+
+---
+
+## Islands Architecture (client:* directives)
+
+```astro
+<!-- Load immediately (interactive above the fold) -->
+<Counter client:load />
+
+<!-- Load when browser is idle (non-critical interactivity) -->
+<Newsletter client:idle />
+
+<!-- Load when scrolled into viewport (below the fold) -->
+<Comments client:visible />
+
+<!-- Load on media query match (mobile-only widget) -->
+<MobileMenu client:media="(max-width: 768px)" />
+
+<!-- Client-only, skip SSR entirely (browser APIs needed) -->
+<MapWidget client:only="react" />
+
+<!-- Server Island: static shell, fetched at request time (v6+) -->
+<UserGreeting server:defer />
+```
+
+**Decision guide:** No directive (default) = zero JS, static HTML. Add directive only when user interaction is required.
+
+---
+
+## Image Optimization
+
+```astro
+---
+import { Image } from 'astro:assets';
+import heroImage from '../assets/hero.jpg';
+---
+<!-- Local image (optimized, lazy-loaded, responsive) -->
+<Image src={heroImage} alt="Hero" width={1200} />
+
+<!-- Remote image (must allowlist domain in config) -->
+<Image src="https://cdn.example.com/photo.jpg" alt="Photo" width={800} height={600} />
+```
+
+Config for remote images:
+```typescript
+// astro.config.mjs
+image: {
+  domains: ['cdn.example.com'],
+  remotePatterns: [{ protocol: 'https', hostname: '**.cloudinary.com' }],
+}
+```
+
+---
+
+## Detailed References
+
+- [Install MCP Server](references/install-mcp.md) — Setup Astro Docs MCP for any AI tool (Kiro, Claude, Cursor, VS Code, etc.)
+- [Migration Guide v6→v7](references/migration-v6-to-v7.md) — Step-by-step upgrade plan with breaking changes checklist
+- [Validation Checklist](references/validation-checklist.md) — Verify installation, detect breaking/deprecated patterns
+- [AI Dev Server](references/ai-dev-server.md) — Background mode, JSON logging, agent detection
+- [Astro v7 Features](references/v7-features.md) — Rust compiler, Sätteri, Advanced Routing, Route Caching, CDN providers
+- [Astro v6 Features](references/v6-features.md) — Content Collections v2, Actions, Sessions, Server Islands, env module
+- [Related Content](references/related-content.md) — Vector embeddings para posts relacionados, deploy leve no Coolify sem modelo
+- [Testing](references/testing.md) — Vitest components, Playwright E2E, link checking, CI pipeline
+- [SEO Full Stack](references/seo-full-stack.md) — JSON-LD graph, agent discovery, IndexNow, OG images, build-time validation, performance
+- [Starlight & Patterns](references/starlight-and-patterns.md) — Docs sites, Pagefind search, i18n, pagination, RSS
+- [Deployment](references/deployment.md) — Cloudflare, Vercel, Netlify, Firebase, GitHub Pages, Docker/Coolify, Azure
+- [Coolify Deploy](references/coolify-deploy.md) — Self-hosted deploy on Coolify (Dockerfile, API, gotchas, recommended stack)
--- a/.github/skills/astro-sites-manager/references/ai-dev-server.md
+++ b/.github/skills/astro-sites-manager/references/ai-dev-server.md
@@ -0,0 +1,172 @@
+# AI Dev Server Guide
+
+Reference for AI agents interacting with the Astro development server programmatically.
+
+---
+
+## 1. Background Mode
+
+Start the dev server as a detached background process that blocks until the server is fully ready to accept requests:
+
+```bash
+astro dev --background
+```
+
+### Auto-Detection
+
+Astro automatically detects AI agent environments and enables background mode without explicit flags. This applies to known CI/agent runtimes.
+
+### Lockfile
+
+A lockfile at `.astro/dev.json` prevents duplicate server instances. If a server is already running, the lockfile ensures a second `astro dev --background` call returns the existing instance info instead of spawning a new process.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `astro dev --background` | Start detached server, block until ready |
+| `astro dev stop` | Stop the running background server |
+| `astro dev status` | Check if a background server is running |
+| `astro dev logs` | Stream logs from the background server |
+
+### Opt-Out
+
+Disable automatic background mode by setting the environment variable:
+
+```bash
+ASTRO_DEV_BACKGROUND=0 astro dev
+```
+
+---
+
+## 2. Health Endpoint
+
+Verify the dev server is ready before making requests:
+
+```
+GET /_astro/status
+```
+
+Response:
+
+```json
+{"ok": true}
+```
+
+> **Important:** This endpoint is only available in development mode. It does not exist in production builds.
+
+### Usage
+
+```bash
+curl http://localhost:4321/_astro/status
+```
+
+Wait for a `200` response with `{"ok": true}` before issuing any page requests.
+
+---
+
+## 3. JSON Logging
+
+Enable structured JSON output for machine-readable log parsing:
+
+```bash
+astro dev --json
+```
+
+### Configuration in `astro.config.mjs`
+
+```js
+import { logHandlers } from 'astro';
+
+export default defineConfig({
+  logger: logHandlers.json(),
+});
+```
+
+### Compose Multiple Handlers
+
+Output to both console and JSON simultaneously:
+
+```js
+import { logHandlers } from 'astro';
+
+export default defineConfig({
+  logger: logHandlers.compose(
+    logHandlers.console(),
+    logHandlers.json()
+  ),
+});
+```
+
+### Auto-Enabled
+
+JSON logging is automatically enabled when an AI agent environment is detected.
+
+### Use Cases
+
+- Error parsing — structured error objects with file, line, column
+- Build status — track compilation progress programmatically
+- HMR events — detect when hot module replacement completes after file changes
+
+---
+
+## 4. Agent Workflow
+
+Step-by-step workflow for AI agents developing with Astro:
+
+```bash
+# 1. Start the dev server in background (blocks until ready)
+astro dev --background
+
+# 2. Verify the server is ready
+curl http://localhost:4321/_astro/status
+
+# 3. Make changes to source files
+# (edit .astro, .ts, .css files as needed)
+
+# 4. Verify output after HMR processes changes
+curl http://localhost:4321/page-to-test
+
+# 5. Cleanup when done
+astro dev stop
+```
+
+### Notes
+
+- Step 2 should return `{"ok": true}` before proceeding.
+- After step 3, wait briefly for HMR to process before step 4.
+- Always run step 5 to avoid orphaned processes.
+
+---
+
+## 5. Idempotency Rules
+
+The dev server commands are designed to be safely called multiple times:
+
+| Scenario | Behavior |
+|----------|----------|
+| Start when already running | Returns existing instance info (port, PID) |
+| Stop when not running | Silent success (exit code 0) |
+| Crash or unexpected termination | Lockfile is cleaned up, no zombie processes |
+
+These guarantees mean agents can call `astro dev --background` at the start of every task without checking current state first, and call `astro dev stop` at cleanup without error handling.
+
+---
+
+## 6. MCP Integration
+
+The Astro Docs MCP server provides real-time documentation access:
+
+- **Endpoint:** `https://mcp.docs.astro.build/mcp`
+- **Tool:** `search_astro_docs`
+
+### Usage
+
+Always query the MCP server for the latest API details, configuration options, and component references rather than relying on cached knowledge.
+
+```
+search_astro_docs("dev server background mode")
+search_astro_docs("content collections config")
+```
+
+This ensures agents work with current documentation even as Astro's API evolves between versions.
--- a/.github/skills/astro-sites-manager/references/coolify-deploy.md
+++ b/.github/skills/astro-sites-manager/references/coolify-deploy.md
@@ -0,0 +1,415 @@
+# Deploying Astro on Coolify
+
+Production-tested patterns for deploying Astro sites on self-hosted Coolify (v4.x). Based on 17+ live deployments.
+
+---
+
+## Build Pack Decision
+
+| Scenario | build_pack | Notes |
+|----------|-----------|-------|
+| Astro v6+ (requires Node ≥22.12.0) | `dockerfile` | Nixpacks can't pin minor version |
+| Astro v5 or earlier | `nixpacks` | `NIXPACKS_NODE_VERSION=22` works |
+| Astro `output: 'static'` with package.json | `nixpacks` | start: `npx serve dist -l 80 -s` |
+| Astro `output: 'static'` (Dockerfile) | `dockerfile` | nginx serves directly |
+| HTML/CSS only (no package.json) | `static` | `static_image: nginx:alpine` |
+
+**Rule:** For Astro v6+ and v7, always use `dockerfile`. Nixpacks resolves Node 22.11.0 from its internal nixpkgs archive, but Astro v6+ requires ≥22.12.0.
+
+**Astro v7 Docker base image rule:** Use `node:22-slim` (Debian/glibc) for the build stage, NOT `node:22-alpine`. Sätteri's native binding only supports glibc. The runtime stage can still use Alpine/Caddy since it only serves files.
+
+---
+
+## Dockerfile — Astro SSR (Node Adapter)
+
+> **Requires `@astrojs/node@^11.0.0`** for Astro v7. The v10 adapter crashes at runtime with `TypeError: app.getAdapterLogger is not a function`.
+
+```dockerfile
+# Use node:22-slim (NOT alpine) — Sätteri needs glibc for Astro v7
+FROM node:22-slim AS build
+WORKDIR /app
+ENV NODE_OPTIONS="--max-old-space-size=512"
+
+# Coolify injects env vars as ARG — must convert to ENV for npm run build
+ARG MY_API_KEY
+ARG PUBLIC_SITE_URL
+ENV MY_API_KEY=$MY_API_KEY
+ENV PUBLIC_SITE_URL=$PUBLIC_SITE_URL
+
+COPY package*.json .npmrc ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-slim
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/package.json ./
+ENV HOST=0.0.0.0
+ENV PORT=4321
+EXPOSE 4321
+CMD ["node", "dist/server/entry.mjs"]
+```
+
+## Dockerfile — Astro Static (nginx)
+
+```dockerfile
+# Use node:22-slim (NOT alpine) — Sätteri needs glibc
+FROM node:22-slim AS build
+WORKDIR /app
+ENV NODE_OPTIONS="--max-old-space-size=512"
+COPY package*.json .npmrc ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY --from=build /app/dist /usr/share/nginx/html
+EXPOSE 80
+```
+
+---
+
+## Critical Gotchas
+
+### ARG vs ENV — Build-time secrets
+
+Coolify injects variables as Docker `ARG`. But `ARG` does NOT become an environment variable for child processes like `npm run build`. Astro/Vite resolves `import.meta.env.VAR` during build — if the variable doesn't exist in the process environment, it silently becomes `undefined`.
+
+**Fix:** For every secret the build needs:
+```dockerfile
+ARG RESEND_API_KEY
+ENV RESEND_API_KEY=$RESEND_API_KEY
+```
+
+### OOM on Resource-Limited Servers
+
+The `astro build` process can die with exit code 255 and no clear error message on servers with limited RAM (~2GB).
+
+**Fix:** Add to build stage:
+```dockerfile
+ENV NODE_OPTIONS="--max-old-space-size=512"
+```
+
+### Nixpacks Node Version
+
+Nixpacks only accepts **major version**. `NIXPACKS_NODE_VERSION=22` can resolve to 22.11.0, causing:
+```
+Node.js v22.11.0 is not supported by Astro!
+```
+
+**Fix options:**
+1. Use Dockerfile instead (recommended for Astro v6+)
+2. Set `NIXPACKS_NODE_VERSION=24` (skips a major)
+3. Pin nixpkgs archive via `nixpacks.toml`:
+   ```toml
+   [phases.setup]
+   nixpkgsArchive = "5ef6c8a1bf89a0bfe4e15e7baf5bab7feeff86a5"
+   ```
+
+### Nixpacks Timeout
+
+Nixpacks downloads ~600MB nixpkgs archive during build. On servers with limited bandwidth, build dies silently during `unpacking` step.
+
+**Fix:** Switch to Dockerfile. `node:22-alpine` is ~50MB vs ~600MB.
+
+### Sätteri Native Binding on Alpine (Astro v7)
+
+Astro v7 uses Sätteri (Rust-based Markdown) by default. Sätteri ships native bindings but **only for glibc** (`@bruits/satteri-linux-x64-gnu`). Alpine uses musl libc — no musl binding exists, and the WASM fallback has a cpu platform check that also fails.
+
+```
+Cannot find module '@bruits/satteri-linux-x64-musl'
+```
+
+**Fix:** Use `node:22-slim` (Debian/glibc) for the build stage. The runtime stage can still use Alpine since it only serves static files:
+
+```dockerfile
+FROM node:22-slim AS build    # glibc — satteri works
+WORKDIR /app
+COPY package*.json .npmrc ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM caddy:2-alpine           # runtime doesn't need Node
+COPY --from=build /app/dist /srv
+```
+
+**Affected projects:** Any Astro v7 project using Sätteri (default) or Starlight 0.40+ on Alpine.
+**Not affected:** Projects using `unified()` processor explicitly (they bypass Sätteri).
+
+### Sätteri Native Binding on ARM64 (Cross-Platform Lockfile)
+
+When the dev machine is x86_64 but the Coolify build server is ARM64 (e.g., OCI Ampere), `npm ci` and even `npm install --include=optional` fail with:
+
+```
+Cannot find module '@bruits/satteri-linux-arm64-gnu'
+Require stack:
+- /app/node_modules/satteri/index.js
+```
+
+**Root cause:** The `package-lock.json` was generated on x86_64 and only includes `@bruits/satteri-linux-x64-gnu` in its optional dependency tree. npm respects the lockfile's platform resolution even on a different architecture — this is [npm bug #4828](https://github.com/npm/cli/issues/4828).
+
+**What does NOT work:**
+- `.npmrc` with `include=optional` — npm still reads the lockfile's platform tree
+- `npm install --include=optional` in Dockerfile — lockfile still constrains resolution
+- Adding `@bruits/satteri-linux-arm64-gnu` to `optionalDependencies` — npm may still skip it
+
+**Fix:** Do NOT copy `package-lock.json` into the Docker build. Let npm resolve fresh on arm64:
+
+```dockerfile
+FROM node:22-slim AS build
+WORKDIR /app
+ENV NODE_OPTIONS="--max-old-space-size=512"
+COPY package.json .npmrc ./
+# Deliberately omit package-lock.json — forces fresh resolution on arm64
+RUN npm install
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY --from=build /app/dist /usr/share/nginx/html
+EXPOSE 80
+```
+
+**Tradeoff:** Build is slightly less deterministic (no lockfile pinning in Docker). For static sites this is acceptable. For SSR with strict reproducibility needs, generate the lockfile inside an arm64 container instead.
+
+**Affected:** Any Astro v7 project building on ARM64 servers when lockfile was generated on x86_64.
+**Confirmed working:** valeria.med.br on OCI Ampere A1 via Coolify (2026-07-03).
+
+### legacy-peer-deps and npm ci in Docker
+
+When using `--legacy-peer-deps` locally (required for Astro v7 due to transient peer dep conflicts in Starlight plugins), Docker's `npm ci` will fail unless the `.npmrc` is copied into the container.
+
+**Fix:** Always copy `.npmrc` before `npm ci`:
+
+```dockerfile
+COPY package*.json .npmrc ./
+RUN npm ci
+```
+
+The `.npmrc` must contain:
+```
+legacy-peer-deps=true
+```
+
+### @astrojs/node Must Be v11+ for Astro v7
+
+Astro v7's runtime API changed — `app.getAdapterLogger()` was added and the standalone entry module depends on it. If `@astrojs/node` stays at v10, the container builds fine but **crashes at startup**:
+
+```
+TypeError: app.getAdapterLogger is not a function
+    at createAppHandler (dist/server/entry.mjs)
+```
+
+Coolify shows `restarting:unknown` or `exited:unhealthy` — the build log looks green, but the container crash-loops.
+
+**Fix:** Always upgrade `@astrojs/node` to v11 together with Astro v7:
+```bash
+npm install astro@latest @astrojs/node@latest
+```
+
+**Checklist for SSR v7 migration:**
+- `astro` → `^7.0.0`
+- `@astrojs/node` → `^11.0.0`
+- `@astrojs/mdx` → `^7.0.0` (if used)
+
+### pnpm approve-builds in Docker (pnpm 11.9+)
+
+pnpm 11.9+ blocks install scripts (postinstall, install) by default. Packages like `esbuild` and `sharp` need native binaries built after install. Without approval, `pnpm install --frozen-lockfile` fails:
+
+```
+[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.28.1, sharp@0.34.5
+Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.
+```
+
+**Fix:** Run `pnpm approve-builds` locally, which creates `pnpm-workspace.yaml` with:
+```yaml
+allowBuilds:
+  esbuild: true
+  sharp: true
+```
+
+Then **copy `pnpm-workspace.yaml` into the Docker container** alongside the lockfile:
+```dockerfile
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+RUN pnpm install --frozen-lockfile
+```
+
+Missing this file = build fails in CI/Docker but works locally (because local node_modules already has the binaries).
+
+### package-lock.json Desync After Major Upgrade
+
+After `npm install --legacy-peer-deps` for a major version upgrade, the lockfile may reference packages that `npm ci` (strict mode) cannot resolve. Symptoms: `npm ci` fails with "lock file's X does not satisfy Y".
+
+**Fix:** Delete lockfile and regenerate:
+```bash
+rm package-lock.json node_modules -rf
+npm install --legacy-peer-deps
+# Then test: npm ci must pass
+```
+
+### Integrations That Download ML Models (transformers.js, ONNX)
+
+Integrations like `@philnash/astro-related-content` download ONNX models (~300MB) during `astro build` to generate embeddings. On Coolify servers with limited bandwidth/disk, this causes 20+ minute builds or disk exhaustion.
+
+**Pattern:** Generate artifacts locally, commit them, skip the heavy integration in CI.
+
+**Fix:** Dual-mode config with `ENV CI=true` in Dockerfile. See [Related Content reference](references/related-content.md) for complete implementation.
+
+**Key principle:**
+- **Local:** Integration runs fully (downloads model, generates embeddings)
+- **CI/Docker:** Vite plugin serves pre-built `data.json` (zero model download)
+- **Cache commitado:** `.astro-related-content/data.json` + `vectors.json` go in git (~750KB for 32 posts)
+
+This pattern applies to ANY integration that downloads large artifacts at build time.
+
+---
+
+## Coolify API — Create App
+
+```bash
+COOLIFY_URL="https://cool.example.com/api/v1"
+COOLIFY_KEY="your-token"
+
+curl -sS -X POST "$COOLIFY_URL/applications/private-deploy-key" \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "project_uuid": "PROJECT_UUID",
+    "environment_name": "production",
+    "server_uuid": "SERVER_UUID",
+    "private_key_uuid": "SSH_KEY_UUID",
+    "git_repository": "git@gitlab.com:user/project.git",
+    "git_branch": "main",
+    "build_pack": "dockerfile",
+    "dockerfile_location": "/Dockerfile",
+    "ports_exposes": "4321",
+    "name": "my-astro-site"
+  }'
+```
+
+### Set Domain
+
+```bash
+# Use "domains", NOT "fqdn" — fqdn returns "field not allowed"
+curl -sS -X PATCH "$COOLIFY_URL/applications/$APP_UUID" \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"domains": "https://mysite.com"}'
+```
+
+### Set Environment Variables
+
+```bash
+curl -sS -X POST "$COOLIFY_URL/applications/$APP_UUID/envs" \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"key": "MY_VAR", "value": "secret-value", "is_preview": false}'
+```
+
+> Do NOT send `is_build_time` — API rejects it.
+
+### GitLab Webhook (auto-deploy on push)
+
+```bash
+curl -sS -X POST "https://gitlab.com/api/v4/projects/$PROJECT_ID/hooks" \
+  -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://cool.example.com/webhooks/source/gitlab/events/manual",
+    "token": "WEBHOOK_SECRET_FROM_APP",
+    "push_events": true,
+    "enable_ssl_verification": true
+  }'
+```
+
+> **Critical:** The secret goes in the `"token"` field (sent as `X-Gitlab-Token` header), NEVER as `?secret=` query parameter in the URL. With secret in URL, Coolify returns 200 but does NOT trigger deploy.
+
+### Deploy and Validate
+
+```bash
+# Trigger deploy (Coolify 4.1+ — uses GET, NOT POST)
+# The /deploy endpoint accepts uuid as query param, force=true rebuilds from scratch
+curl -sS -X GET "$COOLIFY_URL/deploy?uuid=$APP_UUID&force=true" \
+  -H "Authorization: Bearer $COOLIFY_KEY"
+# Returns: {"deployments":[{"message":"Application X deployment queued.","resource_uuid":"...","deployment_uuid":"..."}]}
+
+# ⚠️ POST /applications/$UUID/deploy returns "Not found" in Coolify 4.1
+# ⚠️ POST /applications/$UUID/restart only restarts existing container (no rebuild)
+#    Use restart when image is already built. Use /deploy?uuid=...&force=true for rebuild.
+
+# Check status (~60s wait for build + container start)
+curl -sS -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY_URL/applications/$APP_UUID" | python3 -c "
+import sys,json; d=json.load(sys.stdin); print(d['status'])"
+
+# Verify HTTP response
+curl -sS -o /dev/null -w "HTTP %{http_code}\n" https://mysite.com
+```
+
+**Status interpretation:**
+| Status | Meaning |
+|--------|---------|
+| `running:healthy` | Container up and health check passing |
+| `running:unknown` | Container up, no health check configured |
+| `restarting:unknown` | Container crash-looping — check runtime logs |
+| `exited:unhealthy` | Container stopped — likely build or startup failure |
+
+---
+
+## Astro Config for Coolify SSR
+
+```typescript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+
+export default defineConfig({
+  output: 'server', // or hybrid with per-page prerender
+  adapter: node({ mode: 'standalone' }),
+  server: { host: '0.0.0.0', port: 4321 },
+});
+```
+
+For static output, no adapter needed — the Dockerfile handles nginx serving.
+
+---
+
+## Port Configuration
+
+| Output Mode | Port | CMD |
+|-------------|------|-----|
+| SSR (Node adapter) | 4321 | `node dist/server/entry.mjs` |
+| Static (nginx) | 80 | nginx default |
+| Static (serve) | 80 | `npx serve dist -l 80 -s` |
+
+Set `ports_exposes` in Coolify to match.
+
+---
+
+## Recommended Stack (Homelab-Tested)
+
+Based on 17 production Astro sites:
+
+```javascript
+import seoGraph from '@jdevalk/astro-seo-graph/integration';
+import agentmarkup from '@agentmarkup/astro';
+import UnoCSS from '@unocss/astro';
+import critters from 'astro-critters';
+import compress from '@playform/compress';
+
+// Key: compress() MUST be last integration
+integrations: [mdx(), UnoCSS(), sitemap(), seoGraph(), agentmarkup(), critters(), compress()]
+```
+
+| Tool | Why |
+|------|-----|
+| UnoCSS > Tailwind | 5x faster build, smaller bundle |
+| @playform/compress > astro-compress | Better maintained |
+| astro-critters | Critical CSS inlining |
+| @jdevalk/astro-seo-graph | All-in-one SEO (replaces astro-seo + robots-txt + indexnow) |
+| @agentmarkup/astro | LLM visibility (llms.txt, markdown mirrors) |
+| Plausible > GA4 | 1kb script, no cookie banner, self-hosted |
+| @philnash/astro-related-content | Semantic related posts via local embeddings (CI: use prebuilt data.json) |
--- a/.github/skills/astro-sites-manager/references/deployment.md
+++ b/.github/skills/astro-sites-manager/references/deployment.md
@@ -0,0 +1,396 @@
+# Deployment Guide
+
+> Astro 7 deployment across all major platforms. Covers adapters, route caching, and platform-specific gotchas.
+
+---
+
+## 1. General Build
+
+```bash
+astro build    # output in dist/
+astro preview  # test production build locally
+```
+
+Key config in `astro.config.mjs`:
+
+```js
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  site: 'https://example.com',
+  base: '/',
+  trailingSlash: 'never', // 'always' | 'never' | 'ignore'
+});
+```
+
+- `site` — full production URL (required for sitemaps, canonical URLs, RSS)
+- `base` — subpath when deploying to a subdirectory (e.g., `/docs`)
+- `trailingSlash` — MUST match hosting platform expectations to avoid redirect loops
+
+---
+
+## 2. Cloudflare Pages
+
+**Adapter:** `@astrojs/cloudflare`
+
+```bash
+npx astro add cloudflare
+```
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import cloudflare from '@astrojs/cloudflare';
+
+export default defineConfig({
+  output: 'server',
+  adapter: cloudflare(),
+});
+```
+
+**Route Caching (private beta):**
+
+```js
+// astro.config.mjs
+import { cacheCloudflare } from '@astrojs/cloudflare/cache';
+
+export default defineConfig({
+  output: 'server',
+  adapter: cloudflare(),
+  experimental: {
+    serverIslands: true,
+  },
+  routeCache: cacheCloudflare(),
+});
+```
+
+**Deploy:**
+- Connect git repo in Cloudflare Dashboard → Pages → Create a project
+- Build command: `astro build`
+- Build output directory: `dist`
+- Node.js compatibility flag is set automatically by the adapter
+
+---
+
+## 3. Vercel
+
+**Adapter:** `@astrojs/vercel`
+
+```bash
+npx astro add vercel
+```
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import vercel from '@astrojs/vercel';
+import { cacheVercel } from '@astrojs/vercel/cache';
+
+export default defineConfig({
+  output: 'server',
+  adapter: vercel(),
+  routeCache: cacheVercel(),
+});
+```
+
+**ISR via routeRules:**
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  output: 'server',
+  adapter: vercel({
+    isr: true, // enable ISR globally
+  }),
+  routeCache: cacheVercel({
+    routeRules: {
+      '/blog/**': { revalidate: 60 },   // revalidate every 60s
+      '/static/**': { prerender: true }, // fully static at build
+    },
+  }),
+});
+```
+
+**Deploy:**
+- Connect repo via Vercel Dashboard or `vercel` CLI
+- Framework preset: Astro (auto-detected)
+
+---
+
+## 4. Netlify
+
+**Adapter:** `@astrojs/netlify`
+
+```bash
+npx astro add netlify
+```
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import netlify from '@astrojs/netlify';
+import { cacheNetlify } from '@astrojs/netlify/cache';
+
+export default defineConfig({
+  output: 'server',
+  adapter: netlify(),
+  routeCache: cacheNetlify(),
+});
+```
+
+**Deploy:**
+- Connect repo in Netlify Dashboard
+- Build command: `astro build`
+- Publish directory: `dist`
+- Functions auto-detected from adapter output
+
+---
+
+## 5. Firebase Hosting
+
+**Static only** — no adapter needed for SSG output.
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  output: 'static',
+  trailingSlash: 'never', // CRITICAL: must match Firebase config
+});
+```
+
+**firebase.json:**
+
+```json
+{
+  "hosting": {
+    "public": "dist",
+    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
+    "trailingSlash": false,
+    "rewrites": [
+      { "source": "**", "destination": "/404.html" }
+    ]
+  }
+}
+```
+
+**Deploy:**
+
+```bash
+astro build
+firebase deploy --only hosting
+```
+
+### CRITICAL: trailingSlash Alignment
+
+Mismatch between Firebase and Astro causes **infinite redirect loops**.
+
+| Firebase `trailingSlash` | Astro `trailingSlash` | Result |
+|---|---|---|
+| `false` | `'never'` | ✅ Works |
+| `true` | `'always'` | ✅ Works |
+| `false` | `'always'` | ❌ Redirect loop |
+| `true` | `'never'` | ❌ Redirect loop |
+
+---
+
+## 6. GitHub Pages
+
+**Static output only** — no adapter needed.
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  site: 'https://username.github.io',
+  base: '/repo-name', // omit for username.github.io root
+  output: 'static',
+});
+```
+
+**GitHub Actions workflow** (`.github/workflows/deploy.yml`):
+
+```yaml
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+---
+
+## 7. Docker / Self-Hosted (Coolify)
+
+**Adapter:** `@astrojs/node`
+
+```bash
+npx astro add node
+```
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+
+export default defineConfig({
+  output: 'server',
+  adapter: node({
+    mode: 'standalone',
+  }),
+  server: {
+    host: '0.0.0.0', // REQUIRED for Docker
+    port: 4321,
+  },
+});
+```
+
+**Dockerfile:**
+
+```dockerfile
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-alpine AS runtime
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/package.json ./
+ENV HOST=0.0.0.0
+ENV PORT=4321
+EXPOSE 4321
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:4321/api/health || exit 1
+CMD ["node", "./dist/server/entry.mjs"]
+```
+
+**Health check endpoint** (`src/pages/api/health.ts`):
+
+```ts
+import type { APIRoute } from 'astro';
+
+export const GET: APIRoute = () => {
+  return new Response(JSON.stringify({ status: 'ok' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  });
+};
+```
+
+**Coolify:** Set Dockerfile build pack, expose port 4321, configure health check to `/api/health`.
+
+---
+
+## 8. Azure Static Web Apps
+
+Works with **static output** (SSG). For SSR, use Azure Functions integration.
+
+**GitHub Actions workflow** (`.github/workflows/azure-swa.yml`):
+
+```yaml
+name: Azure Static Web Apps
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - uses: Azure/static-web-apps-deploy@v1
+        with:
+          azure_static_web_apps_api_token: ${{ secrets.AZURE_SWA_TOKEN }}
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          action: upload
+          app_location: /
+          output_location: dist
+          skip_app_build: true
+```
+
+The `skip_app_build: true` pattern means we build ourselves (for control over Node version and env vars) and only upload the output.
+
+**staticwebapp.config.json:**
+
+```json
+{
+  "navigationFallback": {
+    "rewrite": "/404.html"
+  },
+  "globalHeaders": {
+    "X-Frame-Options": "DENY",
+    "X-Content-Type-Options": "nosniff"
+  },
+  "routes": [
+    {
+      "route": "/api/*",
+      "allowedRoles": ["authenticated"]
+    }
+  ]
+}
+```
+
+For **private registry auth** (private npm packages):
+
+```yaml
+      - run: |
+          echo "//npm.pkg.github.com/:_authToken=${{ secrets.NPM_TOKEN }}" >> .npmrc
+      - run: npm ci
+```
+
+---
+
+## 9. Pre-Deploy Checklist
+
+- [ ] `astro build` exits 0
+- [ ] `astro check` reports no errors
+- [ ] `astro preview` works correctly (test production build locally)
+- [ ] Images use `<Image/>` component or are in `public/`
+- [ ] SEO metadata present on all pages (title, description, og tags)
+- [ ] `src/pages/404.astro` exists
+- [ ] Environment variables set on target platform
+- [ ] `trailingSlash` matches hosting platform expectations
+- [ ] Sitemap generating correctly (`@astrojs/sitemap`)
+- [ ] RSS feed working if applicable (`@astrojs/rss`)
+- [ ] Route caching configured for SSR pages (platform-specific cache helper)
+- [ ] `robots.txt` present and correct
+- [ ] HTTPS redirect configured on platform
+- [ ] Custom domain DNS configured and propagated
--- a/.github/skills/astro-sites-manager/references/install-mcp.md
+++ b/.github/skills/astro-sites-manager/references/install-mcp.md
@@ -0,0 +1,190 @@
+# Installing the Astro Docs MCP Server
+
+The Astro Docs MCP server provides real-time access to the latest Astro documentation via the Model Context Protocol.
+
+- **URL:** `https://mcp.docs.astro.build/mcp`
+- **Transport:** Streamable HTTP
+- **Tool:** `search_astro_docs`
+- **Source:** Open-source, powered by kapa.ai
+
+---
+
+## By Tool
+
+### Kiro CLI
+
+```bash
+kiro-cli mcp add --name astro-docs --scope global --command npx --args "-y" --args "mcp-remote" --args "https://mcp.docs.astro.build/mcp"
+```
+
+Or create/edit `~/.kiro/settings/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "astro-docs": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Claude Code CLI
+
+```bash
+claude mcp add --transport http astro-docs https://mcp.docs.astro.build/mcp
+```
+
+### Codex CLI
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.astro-docs]
+command = "npx"
+args = ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
+```
+
+### Cursor
+
+Use the deeplink or add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "Astro docs": {
+      "type": "http",
+      "url": "https://mcp.docs.astro.build/mcp"
+    }
+  }
+}
+```
+
+### VS Code (Copilot Chat)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "Astro docs": {
+      "type": "http",
+      "url": "https://mcp.docs.astro.build/mcp"
+    }
+  }
+}
+```
+
+### Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "Astro docs": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to `.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "Astro docs": {
+      "httpUrl": "https://mcp.docs.astro.build/mcp"
+    }
+  }
+}
+```
+
+### Zed
+
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "Astro docs": {
+      "settings": {},
+      "enabled": true,
+      "url": "https://mcp.docs.astro.build/mcp"
+    }
+  }
+}
+```
+
+### Claude.ai / Claude Desktop
+
+1. Go to Settings → Connectors
+2. Click "Add custom connector"
+3. URL: `https://mcp.docs.astro.build/mcp`
+4. Name: `Astro docs`
+
+### Warp
+
+Settings → AI → MCP Servers → Add:
+
+```json
+{
+  "mcpServers": {
+    "Astro docs": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"],
+      "start_on_launch": true
+    }
+  }
+}
+```
+
+---
+
+## Generic (any tool supporting MCP)
+
+**Streamable HTTP** (preferred):
+
+```json
+{
+  "mcpServers": {
+    "Astro docs": {
+      "type": "http",
+      "url": "https://mcp.docs.astro.build/mcp"
+    }
+  }
+}
+```
+
+**Local Proxy** (for tools that only support stdio):
+
+```json
+{
+  "mcpServers": {
+    "Astro docs": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Fix |
+|---|---|
+| Server not responding | Verify URL is exactly `https://mcp.docs.astro.build/mcp` |
+| Tool not connecting | Check internet access; some firewalls block MCP |
+| Stale results | MCP always fetches latest docs — no cache to clear |
+| Local proxy crashes | Ensure `npx` is in PATH and Node.js ≥ 18 installed |
+
+Issues: https://github.com/withastro/docs-mcp/issues
--- a/.github/skills/astro-sites-manager/references/migration-v6-to-v7.md
+++ b/.github/skills/astro-sites-manager/references/migration-v6-to-v7.md
@@ -0,0 +1,557 @@
+# Migration Guide: Astro v6 → v7
+
+> Official reference: https://docs.astro.build/en/guides/upgrade-to/v7/
+
+---
+
+## 1. Pre-Migration Checklist
+
+- [ ] **Backup** — commit all changes, create a branch: `git checkout -b feat/astro-v7-upgrade`
+- [ ] **Node.js ≥ 22** — required (v22.5.0+ for `node:sqlite` if replacing `@astrojs/db`)
+  ```bash
+  node -v  # must be >= 22
+  ```
+- [ ] **Audit dependencies** — check for packages that depend on Vite internals or the Go compiler
+  ```bash
+  npx astro info
+  ```
+- [ ] **Review remark/rehype plugins** — if you have any, plan for Sätteri migration or `@astrojs/markdown-remark` fallback
+- [ ] **Check for `src/fetch.ts`** — if this file exists for non-routing purposes, plan a rename
+- [ ] **Check for `@astrojs/db`** usage — plan a replacement (Drizzle, node:sqlite, Turso, Neon)
+
+---
+
+## 2. Upgrade Commands
+
+```bash
+# npm
+npx @astrojs/upgrade
+
+# pnpm
+pnpm dlx @astrojs/upgrade
+
+# yarn
+yarn dlx @astrojs/upgrade
+```
+
+This upgrades Astro and all official integrations together. For manual control:
+
+```bash
+npm install astro@latest
+npm install @astrojs/react@latest @astrojs/mdx@latest  # repeat for each integration
+```
+
+---
+
+## 3. Breaking Changes
+
+### 3.1 Vite 8
+
+Astro v7 upgrades to [Vite 8](https://vite.dev/blog/announcing-vite8). The main impact is on **custom Vite plugins** and projects using Vite internals directly.
+
+Key Vite 8 changes:
+- **esbuild → Rolldown** as the production bundler (Rolldown is a Rust-based Rollup replacement)
+- Plugin API surface changes — check the [Vite 8 migration guide](https://vite.dev/guide/migration)
+
+**What to do:**
+- If you have custom Vite plugins in `astro.config.mjs`, verify they work with Vite 8
+- If you use `esbuild`-specific options (e.g. `esbuild.target`, `esbuild.jsxFactory`), check if they still apply under Rolldown
+
+```js
+// Before: esbuild-specific config (may need review)
+export default defineConfig({
+  vite: {
+    esbuild: {
+      target: 'esnext',
+      jsxFactory: 'h',
+    },
+  },
+});
+
+// After: verify compatibility — most configs carry over, but test your build
+export default defineConfig({
+  vite: {
+    // Rolldown handles bundling; esbuild options may behave differently
+    // Test `astro build` and check output
+  },
+});
+```
+
+> **Most Astro users need no changes.** This primarily affects integration authors and projects with custom Vite plugins.
+
+---
+
+### 3.2 Rust Compiler
+
+The Rust-based compiler is now the **default and only compiler**, replacing the Go-based compiler. It is stricter about HTML syntax.
+
+#### Unclosed tags now produce errors
+
+```astro
+<!-- Before: Go compiler silently accepted this -->
+<p>Hello world
+
+<!-- After: Rust compiler requires closing tags -->
+<p>Hello world</p>
+```
+
+```astro
+---
+import Layout from '../layouts/Layout.astro';
+---
+
+<!-- Before: unclosed component tag accepted -->
+<Layout>
+  <p>Content here
+
+<!-- After: all tags must be closed -->
+<Layout>
+  <p>Content here</p>
+</Layout>
+```
+
+> **Void elements** (`<br>`, `<img>`, `<input>`, `<hr>`) do NOT need closing tags.
+
+#### No HTML auto-correction
+
+The Go compiler silently reordered invalid HTML (e.g. `<div>` inside `<p>`). The Rust compiler passes markup through as-is.
+
+```astro
+<!-- Before: compiler restructured this silently -->
+<p>
+  <div>Block inside paragraph</div>
+</p>
+
+<!-- After: browser handles it (will close <p> early, breaking layout) -->
+<!-- Fix: use valid nesting -->
+<div>
+  <div>Block content here</div>
+</div>
+```
+
+#### JSX whitespace handling
+
+See [Section 3.5 compressHTML](#35-compresshtml-jsx-is-new-default) for the related whitespace changes.
+
+#### CSS output differences (cosmetic, no action needed)
+
+- Named colors may become hex: `rebeccapurple` → `#639`
+- `url()` values may gain/lose quotes: `url(/path)` ↔ `url('/path')`
+
+---
+
+### 3.3 Reserved File Name: `src/fetch.ts`
+
+`src/fetch.ts` (or `.js`) is now reserved for [advanced routing](https://docs.astro.build/en/guides/routing/#advanced-routing) configuration.
+
+```js
+// Before: you had src/fetch.ts for custom fetch logic
+// src/fetch.ts — your custom utility
+export function fetchData() { /* ... */ }
+
+// After: Option A — rename your file
+// src/fetcher.ts (or src/api-client.ts, etc.)
+export function fetchData() { /* ... */ }
+// Update all imports:
+// import { fetchData } from '../fetch' → import { fetchData } from '../fetcher'
+```
+
+```js
+// After: Option B — disable advanced routing in astro.config.mjs
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  fetchFile: null, // disables advanced routing, keeps your src/fetch.ts
+});
+```
+
+```js
+// After: Option C — point fetchFile elsewhere
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  fetchFile: './src/router.ts', // use a different file for advanced routing
+});
+```
+
+---
+
+### 3.4 New Default Markdown Processor: Sätteri
+
+[Sätteri](https://satteri.bruits.org/) replaces the remark/rehype (unified) pipeline as the default Markdown processor. `@astrojs/markdown-remark` is no longer installed by default.
+
+**If you DON'T use remark/rehype plugins:** no action needed. Sätteri applies GFM and SmartyPants like before.
+
+**If you DO use remark/rehype plugins:**
+
+```bash
+# Install the unified pipeline package
+npm install @astrojs/markdown-remark
+```
+
+```js
+// Before: plugins configured directly (worked because unified was the default)
+import { defineConfig } from 'astro/config';
+import remarkToc from 'remark-toc';
+import rehypeSlug from 'rehype-slug';
+
+export default defineConfig({
+  markdown: {
+    remarkPlugins: [remarkToc],
+    rehypePlugins: [rehypeSlug],
+  },
+});
+
+// After: explicitly set unified() as processor + install @astrojs/markdown-remark
+import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
+import remarkToc from 'remark-toc';
+import rehypeSlug from 'rehype-slug';
+
+export default defineConfig({
+  markdown: {
+    processor: unified({
+      remarkPlugins: [remarkToc],
+      rehypePlugins: [rehypeSlug],
+    }),
+  },
+});
+```
+
+**Alternative:** Port your plugins to Sätteri MDAST/HAST plugins:
+
+```js
+// Using Sätteri with its native plugin model
+import { defineConfig } from 'astro/config';
+import { satteri } from '@astrojs/markdown-satteri';
+import { myMdastPlugin } from './my-satteri-plugin.mjs';
+
+export default defineConfig({
+  markdown: {
+    processor: satteri({
+      mdastPlugins: [myMdastPlugin()],
+      features: { directive: true },
+    }),
+  },
+});
+```
+
+---
+
+### 3.5 `compressHTML: 'jsx'` is New Default
+
+Whitespace between inline elements is now stripped using JSX rules (like React), instead of HTML-aware compression.
+
+```astro
+<!-- Before (v6): renders as "hello world" (space preserved) -->
+<span>hello</span>
+<em>world</em>
+
+<!-- After (v7): renders as "helloworld" (space removed) -->
+<span>hello</span>
+<em>world</em>
+```
+
+**Fix: add explicit space with `{' '}`:**
+
+```astro
+<!-- After: explicit space between inline elements -->
+<span>hello</span>{' '}<em>world</em>
+```
+
+**Or revert to v6 behavior globally:**
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  compressHTML: true, // v6 HTML-aware behavior
+  // compressHTML: false  // preserve ALL whitespace
+});
+```
+
+---
+
+## 4. Deprecated
+
+### `getContainerRenderer()` from package root
+
+Importing `getContainerRenderer()` from the integration's package root is deprecated. Use the dedicated `/container-renderer` entrypoint.
+
+```js
+// Before
+import { getContainerRenderer } from '@astrojs/react';
+
+// After
+import { getContainerRenderer } from '@astrojs/react/container-renderer';
+```
+
+Available for: `@astrojs/react`, `@astrojs/preact`, `@astrojs/solid-js`, `@astrojs/svelte`, `@astrojs/vue`, `@astrojs/mdx`.
+
+---
+
+## 5. Removed
+
+### 5.1 `@astrojs/db`
+
+The package is removed and no longer maintained. Replace with:
+
+| Alternative | Use case |
+|---|---|
+| `node:sqlite` | Node.js adapter, local SQLite (Node ≥ 22.5.0) |
+| [Drizzle ORM](https://orm.drizzle.team/) | Schema-based queries with any DB |
+| [Turso](https://turso.tech/) | Edge SQLite (libSQL) |
+| [Neon](https://neon.tech/) | Serverless Postgres |
+
+```bash
+# Remove
+npm uninstall @astrojs/db
+```
+
+```js
+// Before: @astrojs/db
+import { db, sql } from 'astro:db';
+const results = await db.select().from(Posts).all();
+
+// After: Drizzle ORM example
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { posts } from './schema';
+const db = drizzle(process.env.DATABASE_URL);
+const results = await db.select().from(posts);
+```
+
+Remove `db` from `astro.config.mjs` integrations array and delete `db/` config files.
+
+---
+
+### 5.2 `astro:transitions` Internals
+
+The following exports are removed:
+
+| Removed API | Replacement |
+|---|---|
+| `TRANSITION_BEFORE_PREPARATION` | `'astro:before-preparation'` |
+| `TRANSITION_AFTER_PREPARATION` | `'astro:after-preparation'` |
+| `TRANSITION_BEFORE_SWAP` | `'astro:before-swap'` |
+| `TRANSITION_AFTER_SWAP` | `'astro:after-swap'` |
+| `TRANSITION_PAGE_LOAD` | `'astro:page-load'` |
+| `isTransitionBeforePreparationEvent()` | `event.type === 'astro:before-preparation'` |
+| `isTransitionBeforeSwapEvent()` | `event.type === 'astro:before-swap'` |
+| `createAnimationScope()` | Remove entirely |
+
+```js
+// Before
+import {
+  TRANSITION_AFTER_SWAP,
+  isTransitionBeforePreparationEvent,
+} from 'astro:transitions/client';
+
+document.addEventListener(TRANSITION_AFTER_SWAP, (event) => {
+  if (isTransitionBeforePreparationEvent(event)) { /* ... */ }
+});
+
+// After
+document.addEventListener('astro:after-swap', (event) => {
+  if (event.type === 'astro:before-preparation') { /* ... */ }
+});
+```
+
+---
+
+## 6. Experimental Flags to Remove (Now Stable)
+
+Remove these from your `astro.config.mjs` `experimental` block:
+
+| Flag | Status in v7 |
+|---|---|
+| `experimental.logger` | Stable — use top-level `logger` field |
+| `experimental.queuedRendering` | Default behavior — just remove |
+| `experimental.rustCompiler` | Default and only compiler — just remove |
+| `experimental.advancedRouting` | Default — just remove (note: `src/fetch.ts` is now reserved) |
+| `experimental.cache` | Stable — move to top-level `cache` field |
+| `experimental.routeRules` | Stable — move to top-level `routeRules` field |
+
+```js
+// Before
+import { defineConfig, logHandlers, memoryCache } from 'astro/config';
+
+export default defineConfig({
+  experimental: {
+    logger: logHandlers.json({ pretty: true }),
+    queuedRendering: { enabled: true },
+    rustCompiler: true,
+    advancedRouting: true,
+    cache: { provider: memoryCache() },
+    routeRules: {
+      '/blog/[...path]': { maxAge: 300, swr: 60 },
+    },
+  },
+});
+
+// After
+import { defineConfig, logHandlers, memoryCache } from 'astro/config';
+
+export default defineConfig({
+  logger: logHandlers.json({ pretty: true }),
+  cache: { provider: memoryCache() },
+  routeRules: {
+    '/blog/[...path]': { maxAge: 300, swr: 60 },
+  },
+});
+```
+
+---
+
+## 7. Post-Migration Validation
+
+Run these steps after upgrading:
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Run the dev server — check for compiler errors
+npm run dev
+
+# 3. Run a full production build
+npm run build
+
+# 4. Preview the production build
+npm run preview
+
+# 5. Check for visual regressions (especially whitespace issues from compressHTML)
+# Open key pages and inspect inline element spacing
+
+# 6. Run tests if you have them
+npm test
+
+# 7. Check TypeScript
+npx astro check
+```
+
+**What to look for:**
+- ❌ Compiler errors about unclosed tags → add missing closing tags
+- ❌ Layout shifts or broken nesting → fix invalid HTML (block elements inside `<p>`, etc.)
+- ❌ Missing spaces between inline elements → add `{' '}` where needed
+- ❌ Markdown rendering issues → install `@astrojs/markdown-remark` if using remark/rehype plugins
+- ❌ Build errors mentioning `src/fetch.ts` → rename or set `fetchFile: null`
+- ❌ Import errors for `@astrojs/db` → replace with alternative DB solution
+- ❌ Import errors for `TRANSITION_*` constants → use event name strings directly
+
+---
+
+## Quick Reference: Search & Replace
+
+| Find | Replace with |
+|---|---|
+| `from '@astrojs/react'` (for getContainerRenderer) | `from '@astrojs/react/container-renderer'` |
+| `TRANSITION_BEFORE_PREPARATION` | `'astro:before-preparation'` |
+| `TRANSITION_AFTER_PREPARATION` | `'astro:after-preparation'` |
+| `TRANSITION_BEFORE_SWAP` | `'astro:before-swap'` |
+| `TRANSITION_AFTER_SWAP` | `'astro:after-swap'` |
+| `TRANSITION_PAGE_LOAD` | `'astro:page-load'` |
+| `isTransitionBeforePreparationEvent(e)` | `e.type === 'astro:before-preparation'` |
+| `isTransitionBeforeSwapEvent(e)` | `e.type === 'astro:before-swap'` |
+| `createAnimationScope` | (remove entirely) |
+| `experimental.rustCompiler` | (remove) |
+| `experimental.queuedRendering` | (remove) |
+| `experimental.advancedRouting` | (remove) |
+
+---
+
+## Ecosystem Compatibility (learned from real upgrades)
+
+### Starlight 0.40+ Sidebar Schema Change
+
+Starlight 0.40 (required for Astro v7) changed the sidebar schema. `autogenerate` can no longer be a direct property of a sidebar group — it must be inside `items`:
+
+```javascript
+// BEFORE (Starlight 0.38):
+{ label: 'Reference', autogenerate: { directory: 'reference' } }
+
+// AFTER (Starlight 0.40):
+{ label: 'Reference', items: [{ autogenerate: { directory: 'reference' } }] }
+```
+
+### astro-mermaid — Incompatible with v7
+
+`astro-mermaid` (all versions through 2.0.4) uses `isUnifiedProcessor()` which was removed in Astro v7. Replace with Mermaid CDN client-side script:
+
+```javascript
+// In Starlight head config or Layout.astro:
+{
+  tag: 'script',
+  attrs: { type: 'module' },
+  content: `
+    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+    mermaid.initialize({ startOnLoad: false });
+    document.addEventListener('DOMContentLoaded', () => {
+      document.querySelectorAll('pre > code.language-mermaid').forEach((el) => {
+        const pre = el.parentElement;
+        const div = document.createElement('div');
+        div.className = 'mermaid';
+        div.textContent = el.textContent;
+        pre.replaceWith(div);
+      });
+      mermaid.run();
+    });
+  `,
+}
+```
+
+### Docker Alpine — Sätteri native binding missing
+
+Sätteri only ships `linux-x64-gnu` (glibc). Alpine uses musl. Build stage MUST use `node:22-slim`:
+
+```dockerfile
+FROM node:22-slim AS build  # NOT alpine
+```
+
+### .npmrc required in Dockerfile
+
+Astro v7 with Starlight plugins causes peer dependency conflicts. The `.npmrc` with `legacy-peer-deps=true` must be copied into Docker:
+
+```dockerfile
+COPY package*.json .npmrc ./
+RUN npm ci
+```
+
+### @astrojs/node Must Be v11 for Astro v7
+
+`@astrojs/node@10` builds fine but **crashes at runtime** with Astro v7:
+
+```
+TypeError: app.getAdapterLogger is not a function
+    at createAppHandler (dist/server/entry.mjs)
+```
+
+The build succeeds, the image is created, the container starts — then immediately exits. Coolify shows `restarting:unknown` or `exited:unhealthy`.
+
+**Fix:** Always upgrade `@astrojs/node` alongside Astro:
+```bash
+npm install astro@latest @astrojs/node@latest @astrojs/mdx@latest
+```
+
+**Required versions for v7:**
+| Package | Minimum |
+|---------|---------|
+| `astro` | `^7.0.0` |
+| `@astrojs/node` | `^11.0.0` |
+| `@astrojs/mdx` | `^7.0.0` |
+| `@astrojs/sitemap` | `^3.7.2` (unchanged) |
+
+### pnpm 11.9+ — approve-builds Required in Docker
+
+pnpm 11.9 blocks postinstall scripts by default. `esbuild` and `sharp` need native compilation after install. Without approval the Docker build fails:
+
+```
+[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.28.1, sharp@0.34.5
+```
+
+**Fix:** Run `pnpm approve-builds` locally (generates `pnpm-workspace.yaml`), then copy it in Docker:
+
+```dockerfile
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+RUN pnpm install --frozen-lockfile
+```
--- a/.github/skills/astro-sites-manager/references/related-content.md
+++ b/.github/skills/astro-sites-manager/references/related-content.md
@@ -0,0 +1,394 @@
+# Related Content com Vector Embeddings
+
+Conteúdo relacionado semântico para Astro content collections usando `@philnash/astro-related-content`. Gera sugestões de posts relacionados via vector embeddings locais (transformers.js) sem depender de APIs externas em runtime.
+
+---
+
+## Conceito
+
+A integração calcula similaridade semântica entre posts usando embeddings (vetores numéricos que representam o "significado" do texto). Posts com vetores próximos são semanticamente similares. Tudo roda em build time — zero impacto no visitante.
+
+---
+
+## Instalação
+
+```bash
+npm install @philnash/astro-related-content
+```
+
+---
+
+## Configuração Básica
+
+```typescript
+// astro.config.ts
+import astroRelatedContent from '@philnash/astro-related-content'
+
+export default defineConfig({
+  integrations: [
+    astroRelatedContent({
+      collections: ['blog'],
+      generation: {
+        limit: 4,        // posts relacionados por item
+        watch: false,    // não regenerar em dev mode (economiza CPU)
+      },
+      embeddings: {
+        model: 'onnx-community/embeddinggemma-300m-ONNX',
+        dtype: 'fp32',
+        pooling: 'mean',
+        batchSize: 1,
+      },
+    }),
+  ],
+})
+```
+
+---
+
+## Escolha de Modelo
+
+| Modelo | Idiomas | Context | Tamanho | Pooling | Uso |
+|--------|---------|---------|---------|---------|-----|
+| `Xenova/all-MiniLM-L6-v2` | EN only | 256 tokens | ~22MB | `mean` | Default, ruim para PT-BR |
+| `onnx-community/embeddinggemma-300m-ONNX` | Multilingual | 2048 tokens | ~300MB | `mean` | **Recomendado para PT-BR** |
+| `onnx-community/Qwen3-Embedding-0.6B-ONNX` | Multilingual | 32k tokens | ~600MB | `last_token` | Posts muito longos |
+| `onnx-community/granite-embedding-small-english-r2-ONNX` | EN | 8192 tokens | ~130MB | `cls` | EN com context longo |
+
+**Regra:** Para conteúdo em português, NUNCA usar o modelo default (`all-MiniLM-L6-v2`). Use `embeddinggemma-300m-ONNX` ou superior.
+
+---
+
+## Custom Provider (LiteLLM, OpenAI, etc.)
+
+A integração aceita custom providers via interface `EmbeddingProvider`:
+
+```typescript
+// litellm-provider.ts
+import { createEmbeddingProvider } from '@philnash/astro-related-content/providers'
+
+export const litellmProvider = createEmbeddingProvider({
+  name: 'litellm',
+  version: '1.0.0',
+
+  async embed(texts, options) {
+    const response = await fetch(`${options.baseUrl}/embeddings`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${options.apiKey}`,
+      },
+      body: JSON.stringify({ model: options.model, input: texts }),
+    })
+    const data = await response.json()
+    return data.data.map((item: any) => item.embedding)
+  },
+
+  getMetadata(options) {
+    return { model: options.model, baseUrl: options.baseUrl }
+  },
+})
+```
+
+```typescript
+// astro.config.ts
+import { litellmProvider } from './litellm-provider'
+
+astroRelatedContent({
+  collections: ['blog'],
+  embeddings: {
+    provider: litellmProvider,
+    baseUrl: 'http://localhost:4000',
+    apiKey: 'sk-...',
+    model: 'text-embedding-3-small',
+    batchSize: 10,
+  },
+})
+```
+
+---
+
+## Artefatos Gerados
+
+A integração gera na pasta `.astro-related-content/`:
+
+| Arquivo | Conteúdo | Tamanho típico (32 posts) |
+|---------|----------|---------------------------|
+| `data.json` | Rankings (top N related por post) | ~14KB |
+| `vectors.json` | Cache de embeddings + metadata | ~736KB |
+
+O modelo ONNX é cacheado em `.astro/astro-related-content/models/` (não vai pro repo — `.astro/` está no `.gitignore`).
+
+---
+
+## Uso no Componente
+
+### Bug de compatibilidade Astro v7
+
+O `getRelatedContent()` do virtual module não funciona com Astro v7 glob loader. O motivo: a integração gera IDs como `slug/index` no `data.json`, mas o Astro v7 usa `slug` (sem `/index`) como `entry.id`.
+
+**Workaround:** Usar `getRelatedContentMatches()` + lookup manual:
+
+```astro
+---
+// RelatedPosts.astro
+import { getPostRoute } from '@/lib/data-utils'
+import { formatDate } from '@/lib/utils'
+import { Icon } from 'astro-icon/components'
+import { Image } from 'astro:assets'
+import { getCollection, type CollectionEntry } from 'astro:content'
+import { getRelatedContentMatches } from 'virtual:astro-related-content'
+import Link from './Link.astro'
+
+interface Props {
+  postId: string
+}
+
+const { postId } = Astro.props
+const matches = getRelatedContentMatches('blog', `${postId}/index`)
+
+let relatedContent: { entry: CollectionEntry<'blog'>; score: number }[] = []
+if (matches.length > 0) {
+  const allEntries = await getCollection('blog')
+  const entryById = new Map(allEntries.map((e) => [e.id, e]))
+
+  relatedContent = matches.flatMap((match) => {
+    // match.id = "slug/index", entry.id no Astro v7 = "slug"
+    const normalizedId = match.id.replace(/\/index$/, '')
+    const entry = entryById.get(normalizedId) || entryById.get(match.id)
+    return entry ? [{ entry, score: match.score }] : []
+  })
+}
+---
+
+{
+  relatedContent.length > 0 && (
+    <section class="mt-12 border-t pt-8">
+      <h2 class="mb-6 flex items-center gap-2 text-xl font-medium">
+        <Icon name="lucide:sparkles" class="size-5" />
+        Leitura Relacionada
+      </h2>
+      <div class="grid gap-4 sm:grid-cols-2">
+        {relatedContent.map((item) => (
+          <Link
+            href={getPostRoute(item.entry)}
+            class="hover:bg-muted/50 flex gap-3 rounded-xl border p-3 transition-colors duration-300"
+          >
+            {item.entry.data.image && (
+              <div class="hidden w-16 shrink-0 sm:block">
+                <Image
+                  src={item.entry.data.image}
+                  alt={item.entry.data.title}
+                  width={128}
+                  height={67}
+                  class="rounded-md object-cover"
+                />
+              </div>
+            )}
+            <div class="min-w-0">
+              <h3 class="mb-1 truncate text-sm font-medium">
+                {item.entry.data.title}
+              </h3>
+              <p class="text-muted-foreground text-xs">
+                {formatDate(item.entry.data.date)}
+              </p>
+            </div>
+          </Link>
+        ))}
+      </div>
+    </section>
+  )
+}
+```
+
+---
+
+## Deploy no Coolify — Sem Baixar Modelo em Produção
+
+### O Problema
+
+Na primeira build Docker, a integração baixa o modelo ONNX (~300MB) e processa todos os embeddings. Em um servidor com bandwidth limitada, isso pode levar 20+ minutos e esgotar disco.
+
+### A Solução: Dual-Mode (Local + CI)
+
+**Princípio:** Gerar embeddings localmente, commitar o cache, e em CI usar apenas o `data.json` pré-gerado via Vite plugin leve (sem modelo, sem transformers.js).
+
+#### 1. Commitar os artefatos
+
+Garantir que `.astro-related-content/` **NÃO** está no `.gitignore`:
+
+```bash
+# Verificar
+grep "astro-related-content" .gitignore
+# Se aparecer, remover a linha
+
+# Commitar cache
+git add .astro-related-content/
+git commit -m "chore: cache embeddings related content"
+```
+
+#### 2. Configuração condicional no astro.config.ts
+
+```typescript
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import astroRelatedContent from '@philnash/astro-related-content'
+
+// Em CI: usa data.json pré-gerado sem baixar modelo
+// Local: roda integração completa com embeddings
+const isCI = Boolean(process.env.CI || process.env.DOCKER)
+const dataJsonPath = resolve('.astro-related-content/data.json')
+const hasPrebuiltData = existsSync(dataJsonPath)
+
+const relatedContentIntegrations = isCI && hasPrebuiltData
+  ? [] // Virtual module vem do Vite plugin abaixo
+  : [
+      astroRelatedContent({
+        collections: ['blog'],
+        generation: { limit: 4 },
+        embeddings: {
+          model: 'onnx-community/embeddinggemma-300m-ONNX',
+          dtype: 'fp32',
+          pooling: 'mean',
+          batchSize: 1,
+        },
+      }),
+    ]
+
+// Plugin Vite leve para CI — serve virtual module do data.json commitado
+function relatedContentVitePlugin() {
+  const VIRTUAL_ID = 'virtual:astro-related-content'
+  const RESOLVED_ID = '\0' + VIRTUAL_ID
+  return {
+    name: 'related-content-prebuilt',
+    resolveId(id: string) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID
+    },
+    load(id: string) {
+      if (id !== RESOLVED_ID) return
+      const absPath = resolve('.astro-related-content/data.json')
+      return `
+import { getCollection } from "astro:content";
+import relatedContentData from ${JSON.stringify(`/@fs/${absPath}`)};
+
+export function getRelatedContentMatches(collection, id) {
+  const collectionData = relatedContentData[collection];
+  if (!collectionData) return [];
+  const matches = collectionData[id];
+  return Array.isArray(matches) ? matches.map((m) => ({ ...m })) : [];
+}
+
+export function getRelatedContentIds(collection, id) {
+  return getRelatedContentMatches(collection, id).map((m) => m.id);
+}
+
+export async function getRelatedContent(collection, id) {
+  const matches = getRelatedContentMatches(collection, id);
+  const entries = await getCollection(collection);
+  const entryById = new Map(
+    entries.flatMap((entry) => {
+      const normalizedId = String(entry.id).replace(/\\.(md|mdx)$/, "");
+      return normalizedId === entry.id
+        ? [[entry.id, entry]]
+        : [[entry.id, entry], [normalizedId, entry]];
+    }),
+  );
+  return matches.flatMap((match) => {
+    const entry = entryById.get(match.id);
+    return entry ? [{ entry, score: match.score }] : [];
+  });
+}
+`
+    },
+  }
+}
+
+export default defineConfig({
+  integrations: [
+    // ... outras integrações
+    ...relatedContentIntegrations,
+  ],
+  vite: {
+    plugins: [
+      // ... outros plugins
+      ...(isCI && hasPrebuiltData ? [relatedContentVitePlugin()] : []),
+    ],
+  },
+})
+```
+
+#### 3. Dockerfile com `ENV CI=true`
+
+```dockerfile
+FROM node:22-slim AS build
+WORKDIR /app
+ENV CI=true
+ENV NODE_OPTIONS="--max-old-space-size=512"
+COPY package*.json .npmrc ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY --from=build /app/dist /usr/share/nginx/html
+EXPOSE 80
+```
+
+O `ENV CI=true` ativa o Vite plugin leve. Nenhum modelo é baixado. Build completa em ~10-30s.
+
+---
+
+## Workflow Operacional
+
+| Ação | Onde | O que acontece |
+|------|------|----------------|
+| Novo post | Local | `astro build` → regenera embedding só do post novo → commit cache → push |
+| Editar post | Local | `astro build` → recalcula embedding do editado → commit cache → push |
+| Deploy | Coolify | Usa `data.json` pré-commitado → build rápido (~30s) |
+| Primeiro setup | Local | Download modelo (~300MB) + embeddings de todos os posts (1-20min) |
+
+### Tempos Reais (32 posts, EmbeddingGemma 300m)
+
+| Etapa | Tempo |
+|-------|-------|
+| Primeira geração (download modelo + 32 embeddings) | ~22 min |
+| Build subsequente local (cache hit) | ~10 s |
+| Build CI com data.json pré-gerado | ~10 s |
+| Build CI sem cache (modelo baixando) | ~22+ min ❌ |
+
+---
+
+## Checklist de Implementação
+
+- [ ] `npm install @philnash/astro-related-content`
+- [ ] Configurar integração no `astro.config.ts` (com lógica CI/local)
+- [ ] Criar componente `RelatedPosts.astro` (com workaround Astro v7)
+- [ ] Integrar componente no template de post (`[...id].astro` ou similar)
+- [ ] Rodar `astro build` localmente para gerar embeddings
+- [ ] Verificar `.astro-related-content/` NÃO está no `.gitignore`
+- [ ] Commitar `data.json` + `vectors.json`
+- [ ] Setar `ENV CI=true` no Dockerfile
+- [ ] Deploy e validar no Coolify
+
+---
+
+## Troubleshooting
+
+### Build no Coolify demora 20+ minutos
+**Causa:** `CI=true` não setado no Dockerfile, ou `.astro-related-content/data.json` não commitado. A integração completa está rodando e baixando o modelo.
+**Fix:** Setar `ENV CI=true` no Dockerfile E commitar a pasta `.astro-related-content/`.
+
+### Related posts não renderizam (array vazio)
+**Causa:** Bug de ID entre integração e Astro v7. O `getRelatedContent()` do virtual module não faz match porque IDs diferem.
+**Fix:** Usar `getRelatedContentMatches()` + lookup manual com `normalizedId = match.id.replace(/\/index$/, '')`.
+
+### Embeddings ruins para português
+**Causa:** Usando modelo default (`all-MiniLM-L6-v2`) que é English-only.
+**Fix:** Usar `onnx-community/embeddinggemma-300m-ONNX` (multilingual).
+
+### Cache invalidado a cada build
+**Causa:** A metadata do provider (model, dtype, pooling, version) mudou entre builds. A integração invalida todo o cache quando metadata difere.
+**Fix:** Não alterar configuração de embeddings após gerar o cache. Se precisar mudar modelo, regenerar tudo localmente e re-commitar.
+
+### `Cannot find module '@huggingface/transformers'` em CI
+**Causa:** O pacote `@huggingface/transformers` é dependência transitiva só necessária quando a integração completa roda. Em CI com o Vite plugin, não é necessário.
+**Fix:** Se usar o dual-mode (CI plugin), isso não acontece. Se rodar integração em CI, garantir que `npm ci` instala todas deps.
--- a/.github/skills/astro-sites-manager/references/seo-full-stack.md
+++ b/.github/skills/astro-sites-manager/references/seo-full-stack.md
@@ -0,0 +1,712 @@
+# SEO Full Stack for Astro
+
+Complete reference for implementing technical SEO, structured data, agent discovery, and performance in Astro sites. Based on the `@jdevalk/astro-seo-graph` stack + complementary patterns.
+
+> **Sources:** [Astro SEO: the definitive guide](https://joost.blog/astro-seo-complete-guide/) by Joost de Valk + official [astro-seo-graph](https://github.com/jdevalk/seo-graph/tree/main/packages/astro-seo-graph) documentation.
+
+---
+
+## 1. Installation
+
+```bash
+pnpm add @jdevalk/astro-seo-graph @jdevalk/seo-graph-core
+```
+
+`@jdevalk/seo-graph-core` is a transitive dep, but depending on it explicitly lets you pin the version and import piece builders directly.
+
+---
+
+## 2. `<Seo>` Component — Unified Head Metadata
+
+A single component replaces all manual `<head>` management:
+
+```astro
+---
+import Seo from '@jdevalk/astro-seo-graph/Seo.astro';
+---
+
+<Seo
+    title="My Post | My Site"
+    description="A concise description for search engines."
+    canonical="https://example.com/my-post/"
+    ogType="article"
+    ogImage="https://example.com/og/my-post.jpg"
+    ogImageAlt="My Post"
+    ogImageWidth={1200}
+    ogImageHeight={675}
+    siteName="My Site"
+    twitter={{ card: 'summary_large_image', site: '@handle' }}
+    article={{ publishedTime: publishDate, tags: ['Astro', 'SEO'] }}
+    graph={graph}
+    extraLinks={[
+        { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' },
+        { rel: 'sitemap', href: '/sitemap-index.xml' },
+        { rel: 'alternate', type: 'application/rss+xml', href: '/feed.xml', title: 'RSS' },
+    ]}
+/>
+```
+
+### Automatic behaviors
+
+- **Canonical** derived from Astro's `site` config, query params stripped by default (UTMs don't create duplicates)
+- **Robots** always includes `max-snippet:-1`, `max-image-preview:large`, `max-video-preview:-1`
+- **Canonical omitted when `noindex: true`** (per Google's recommendation)
+- **Duplicate Twitter tags suppressed** — Twitter falls back to OG automatically
+- **hreflang alternates** with BCP 47 normalization and automatic `x-default`
+- **`og:locale:alternate`** emitted automatically from the `alternates` prop
+
+---
+
+## 3. Connected JSON-LD Graph (`@graph`)
+
+A standalone `BlogPosting` isn't enough. The goal is an interlinked graph via `@id`:
+
+```typescript
+// src/utils/schema.ts
+import {
+    buildWebSite, buildBlog, buildPerson,
+    buildWebPage, buildArticle, buildBreadcrumbList,
+    makeIds,
+} from '@jdevalk/seo-graph-core';
+
+const SITE_URL = 'https://example.com';
+const ids = makeIds({ siteUrl: SITE_URL });
+
+export function buildBlogPostGraph(post: { title: string; url: string; publishDate: Date; description: string }) {
+    return {
+        '@context': 'https://schema.org',
+        '@graph': [
+            buildWebSite({
+                url: SITE_URL,
+                name: 'My Site',
+                publisher: { '@id': ids.person },
+                potentialAction: {
+                    '@type': 'SearchAction',
+                    target: { '@type': 'EntryPoint', urlTemplate: `${SITE_URL}/search?q={search_term_string}` },
+                    'query-input': 'required name=search_term_string',
+                },
+            }, ids),
+            buildBlog({ url: `${SITE_URL}/blog/`, name: 'Blog', publisher: { '@id': ids.person } }, ids),
+            buildPerson({
+                url: SITE_URL,
+                name: 'Your Name',
+                knowsAbout: ['Astro', 'SEO', 'Web Development'],
+                sameAs: ['https://github.com/your-user', 'https://linkedin.com/in/your-user'],
+            }, ids),
+            buildWebPage({
+                url: post.url,
+                name: post.title,
+                isPartOf: { '@id': ids.website },
+                breadcrumb: { '@id': ids.breadcrumb(post.url) },
+                datePublished: post.publishDate,
+            }, ids),
+            buildArticle({
+                url: post.url,
+                isPartOf: { '@id': ids.webPage(post.url) },
+                author: { '@id': ids.person },
+                publisher: { '@id': ids.person },
+                headline: post.title,
+                description: post.description,
+                datePublished: post.publishDate,
+            }, ids, 'BlogPosting'),
+        ],
+    };
+}
+```
+
+### Trust Signals in the Schema
+
+Include these to strengthen authority:
+
+| Property | Where | Purpose |
+|---|---|---|
+| `publishingPrinciples` | `WebSite` / `Person` | Editorial policy |
+| `copyrightHolder` + `copyrightYear` | `WebPage` | Copyright ownership |
+| `knowsAbout` | `Person` | Topical authority |
+| `SearchAction` | `WebSite` | Tells agents how to search the site |
+| `sameAs` | `Person` / `Organization` | Social profiles = identity verification |
+
+### `articleBody` in Schema
+
+Include full text (up to 10K chars) so agents can access content via structured data without scraping:
+
+```typescript
+buildArticle({
+    // ...
+    articleBody: post.bodyText.slice(0, 10000),
+}, ids, 'BlogPosting'),
+```
+
+---
+
+## 4. Breadcrumbs Linked to the Graph
+
+```typescript
+import { breadcrumbsFromUrl } from '@jdevalk/astro-seo-graph';
+import { buildBreadcrumbList, makeIds } from '@jdevalk/seo-graph-core';
+
+const ids = makeIds({ siteUrl: 'https://example.com' });
+
+const items = breadcrumbsFromUrl({
+    url: Astro.url,
+    siteUrl: 'https://example.com',
+    pageName: post.data.title,
+    names: { blog: 'Blog', category: 'Category' },
+});
+
+const breadcrumb = buildBreadcrumbList({ url: Astro.url.href, items }, ids);
+```
+
+Each breadcrumb item can reference a graph entity via `@id`, communicating the structural relationship between page and section.
+
+---
+
+## 5. Content Schema Validation (Zod)
+
+```typescript
+// src/content.config.ts
+import { defineCollection, z } from 'astro:content';
+import { seoSchema, imageSchema } from '@jdevalk/astro-seo-graph';
+
+const blog = defineCollection({
+    schema: ({ image }) => z.object({
+        title: z.string(),
+        publishDate: z.coerce.date(),
+        featureImage: imageSchema(image).optional(),
+        seo: seoSchema(image).optional(),
+    }),
+});
+```
+
+- `seoSchema` validates title (5–120 chars) and description (15–160 chars) — build fails if outside limits
+- `imageSchema` requires `alt` — image without alt won't compile
+
+---
+
+## 6. Build-Time Validation
+
+```typescript
+// astro.config.mjs
+import seoGraph from '@jdevalk/astro-seo-graph/integration';
+
+export default defineConfig({
+    integrations: [
+        seoGraph({
+            // All enabled by default:
+            validateH1: true,                  // 0 or >1 H1 = warning
+            validateUniqueMetadata: true,      // Duplicate title/desc across pages
+            validateImageAlt: true,            // <img> without alt
+            validateMetadataLength: {          // SERP-safe bounds
+                title: { min: 30, max: 65 },
+                description: { min: 70, max: 200 },
+            },
+            validateInternalLinks: {           // Broken internal links or missing trailing slash
+                skip: (href) => href.startsWith('/api/'),
+            },
+        }),
+    ],
+});
+```
+
+### What each validation catches:
+
+- **H1**: Templates with duplicate or missing H1
+- **Duplicates**: Paginated pages sharing the same title (corpus-level bug)
+- **Alt text**: Images missed over the years
+- **Meta length**: Titles truncated in SERP or invisible descriptions
+- **Internal links**: `/about-me` without trailing slash that works via 301 but wastes a round-trip
+
+### CI: External Broken Link Checker
+
+For external links (internal validation doesn't cover), use [lychee](https://github.com/lycheeverse/lychee-action) in GitHub Actions:
+
+```yaml
+# .github/workflows/links.yml
+name: Check Links
+on:
+  push:
+    paths: ['src/content/**']
+  schedule:
+    - cron: '0 6 * * 1' # Weekly for link rot
+
+jobs:
+  links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: lycheeverse/lychee-action@v2
+        with:
+          args: --verbose --no-progress 'src/content/**/*.md'
+```
+
+---
+
+## 7. Advanced Sitemaps
+
+### Per-Collection with chunks
+
+```typescript
+import sitemap from '@astrojs/sitemap';
+
+sitemap({
+    entryLimit: 1000,
+    chunks: {
+        posts: (item) => {
+            if (/^\/blog\/[^/]+/.test(new URL(item.url).pathname)) return item;
+        },
+        pages: (item) => item, // default bucket
+    },
+});
+```
+
+Produces: `sitemap-posts-0.xml`, `sitemap-pages-0.xml` — makes debugging easier in Google Search Console.
+
+### Git-based lastmod
+
+```typescript
+import { gitLastmod } from '@jdevalk/astro-seo-graph';
+
+// In the sitemap serialize callback:
+serialize(item) {
+    const filePath = urlToFilePath(item.url); // your logic
+    const lastmod = gitLastmod(filePath, {
+        excludeCommits: ['abc1234'], // bulk imports that don't count
+    });
+    return { ...item, lastmod: lastmod ?? item.lastmod };
+}
+```
+
+`gitLastmod` uses `git log` for the real timestamp of the last commit that touched the file — doesn't depend on filesystem `mtime` (which resets on CI).
+
+---
+
+## 8. IndexNow — Active Notification
+
+IndexNow notifies Bing, Yandex, and others that URLs changed, instead of waiting for passive crawl.
+
+### Configuration
+
+```typescript
+// astro.config.mjs
+seoGraph({
+    indexNow: {
+        key: process.env.INDEXNOW_KEY!,
+        host: 'example.com',
+        siteUrl: 'https://example.com',
+        filter: (url) => !/^\/blog\/\d+\/$/.test(new URL(url).pathname), // Exclude pagination
+    },
+});
+```
+
+### Key Route (ownership verification)
+
+```typescript
+// src/pages/[your-key-here].txt.ts
+import { createIndexNowKeyRoute } from '@jdevalk/astro-seo-graph';
+
+export const GET = createIndexNowKeyRoute({ key: 'your-key-here' });
+```
+
+### Deploy order matters
+
+1. Deploy the key route first
+2. Confirm `https://example.com/your-key.txt` returns 200
+3. Only then enable `indexNow` in the integration
+
+> Submissions before the key is reachable = HTTP 403 and key permanently invalidated.
+
+### Direct IndexNow API
+
+For manual or custom submission:
+
+```bash
+# Single URL
+curl "https://api.indexnow.org/indexnow?url=https://example.com/new-post/&key=YOUR_KEY"
+
+# Batch (up to 10,000 URLs per POST)
+curl -X POST https://api.indexnow.org/indexnow \
+  -H "Content-Type: application/json" \
+  -d '{
+    "host": "example.com",
+    "key": "YOUR_KEY",
+    "urlList": [
+      "https://example.com/post-1/",
+      "https://example.com/post-2/"
+    ]
+  }'
+```
+
+---
+
+## 9. Auto-Generated OG Images
+
+Pipeline: **satori** (JSX → SVG) → **sharp** (SVG → JPEG)
+
+```typescript
+// src/pages/og/[...slug].jpg.ts
+import satori from 'satori';
+import sharp from 'sharp';
+import { getCollection } from 'astro:content';
+
+export async function getStaticPaths() {
+    const posts = await getCollection('blog');
+    return posts.map((p) => ({ params: { slug: p.id } }));
+}
+
+export async function GET({ params }) {
+    const posts = await getCollection('blog');
+    const post = posts.find((p) => p.id === params.slug);
+    if (!post) return new Response('Not found', { status: 404 });
+
+    const fontData = await fetch('https://cdn.example.com/fonts/Inter-Bold.ttf')
+        .then((r) => r.arrayBuffer());
+
+    const svg = await satori(
+        {
+            type: 'div',
+            props: {
+                style: {
+                    width: '100%', height: '100%',
+                    display: 'flex', flexDirection: 'column',
+                    justifyContent: 'center', padding: '60px',
+                    background: 'linear-gradient(135deg, #1a1a2e, #16213e)',
+                    color: '#ffffff', fontFamily: 'Inter',
+                },
+                children: [
+                    { type: 'div', props: { style: { fontSize: '48px', fontWeight: 700, lineHeight: 1.2 }, children: post.data.title } },
+                    { type: 'div', props: { style: { fontSize: '24px', marginTop: '20px', opacity: 0.8 }, children: 'example.com' } },
+                ],
+            },
+        },
+        { width: 1200, height: 675, fonts: [{ name: 'Inter', data: fontData, weight: 700 }] },
+    );
+
+    const jpeg = await sharp(Buffer.from(svg)).jpeg({ quality: 80 }).toBuffer();
+
+    return new Response(jpeg, {
+        headers: { 'Content-Type': 'image/jpeg', 'Cache-Control': 'public, max-age=31536000, immutable' },
+    });
+}
+```
+
+**Why JPEG and not WebP/AVIF?** Social platforms don't reliably support modern formats yet.
+
+**Size: 1200×675** — Google Discover requires ≥1200px width, and 16:9 works well cross-platform.
+
+The `<Seo>` component derives the OG image URL from the slug automatically:
+
+```typescript
+const slug = Astro.url.pathname.replace(/^\/|\/$/g, '');
+const ogImage = new URL(`/og/${slug || 'index'}.jpg`, SITE_URL).toString();
+```
+
+---
+
+## 10. Agent Discovery
+
+### Schema Endpoints (corpus-wide JSON-LD)
+
+```typescript
+// src/pages/schema/post.json.ts
+import { getCollection } from 'astro:content';
+import { createSchemaEndpoint } from '@jdevalk/astro-seo-graph';
+import { buildArticle, buildWebPage, makeIds } from '@jdevalk/seo-graph-core';
+
+const ids = makeIds({ siteUrl: 'https://example.com' });
+
+export const GET = createSchemaEndpoint({
+    entries: () => getCollection('blog'),
+    mapper: (post) => {
+        const url = `https://example.com/${post.id}/`;
+        return [
+            buildWebPage({ url, name: post.data.title, isPartOf: { '@id': ids.website }, datePublished: post.data.publishDate }, ids),
+            buildArticle({ url, isPartOf: { '@id': ids.webPage(url) }, author: { '@id': ids.person }, headline: post.data.title, description: post.data.description ?? '', datePublished: post.data.publishDate }, ids, 'BlogPosting'),
+        ];
+    },
+});
+```
+
+### Schema Map (`/schemamap.xml`)
+
+```typescript
+// src/pages/schemamap.xml.ts
+import { createSchemaMap } from '@jdevalk/astro-seo-graph';
+
+export const GET = createSchemaMap({
+    siteUrl: 'https://example.com',
+    entries: [
+        { path: '/schema/post.json', lastModified: new Date() },
+        { path: '/schema/page.json', lastModified: new Date() },
+    ],
+});
+```
+
+### API Catalog (RFC 9727)
+
+```typescript
+// src/pages/.well-known/api-catalog.ts
+import { createApiCatalog } from '@jdevalk/astro-seo-graph';
+
+export const GET = createApiCatalog({
+    siteUrl: 'https://example.com',
+    schemaEndpoints: [
+        { path: '/schema/post.json', schemaType: 'BlogPosting', serviceDoc: '/about/' },
+    ],
+    schemaMap: { path: '/schemamap.xml' },
+});
+```
+
+### Markdown Alternates
+
+Serve a `.md` version of every page so agents can consume content without HTML parsing:
+
+```typescript
+// src/pages/blog/[...slug].md.ts
+import { getCollection } from 'astro:content';
+import { createMarkdownEndpoint } from '@jdevalk/astro-seo-graph';
+
+export const getStaticPaths = async () => {
+    const posts = await getCollection('blog');
+    return posts.map((p) => ({ params: { slug: p.id } }));
+};
+
+export const GET = createMarkdownEndpoint({
+    entries: () => getCollection('blog'),
+    mapper: (post, slug) =>
+        post.id !== slug ? null : {
+            frontmatter: { title: post.data.title, canonical: `https://example.com/blog/${post.id}/`, pubDate: post.data.publishDate },
+            body: post.body ?? '',
+        },
+});
+```
+
+Enable the discovery link:
+
+```typescript
+// astro.config.mjs
+seoGraph({ markdownAlternate: true });
+```
+
+Emits `<link rel="alternate" type="text/markdown" href="…">` on every page.
+
+### Content Negotiation via Cloudflare (no SSR)
+
+Transform Rule in the dashboard (works on free plan):
+
+```
+When: http.request.headers["accept"][0] contains "text/markdown"
+  AND ends_with(http.request.uri.path, "/")
+  AND NOT starts_with(http.request.uri.path, "/_")
+
+Rewrite URI path (dynamic): wildcard_replace(http.request.uri.path, "*/", "${1}.md")
+```
+
+Turns `/blog/post/` → `/blog/post.md` before cache lookup. No need for `Vary: Accept` header — Cloudflare strips custom Vary values.
+
+### llms.txt
+
+```typescript
+seoGraph({
+    llmsTxt: {
+        title: 'My Site',
+        siteUrl: 'https://example.com',
+        summary: 'A blog about web development, Astro, and SEO.',
+    },
+});
+```
+
+Generates `/llms.txt` automatically at build time listing all pages.
+
+### NLWeb Discovery
+
+`<link>` tag for conversational endpoint (Microsoft protocol):
+
+```html
+<link rel="nlweb" href="https://example.com/api/nlweb" />
+```
+
+NLWeb allows AI agents to make conversational queries against site content via schema.org structured data. Still early days but the setup is trivial.
+
+---
+
+## 11. Performance SEO
+
+### No-Vary-Search
+
+UTM params break caching: `?utm_source=linkedin` and `?utm_source=email` are different resources to the browser. Header that fixes it:
+
+```
+No-Vary-Search: key-order, params=("utm_source" "utm_medium" "utm_campaign" "utm_content" "utm_term")
+```
+
+**Status:** IETF draft (`draft-ietf-httpbis-no-vary-search`), supported in Chrome, degrades gracefully elsewhere.
+
+Configure in `_headers` (Cloudflare Pages / Netlify):
+
+```
+/*
+  No-Vary-Search: key-order, params=("utm_source" "utm_medium" "utm_campaign" "utm_content" "utm_term")
+```
+
+### CDN Cache Headers
+
+```
+# _headers (Cloudflare Pages)
+/_astro/*
+  Cache-Control: public, max-age=31536000, immutable
+
+/og/*
+  Cache-Control: public, max-age=31536000, immutable
+```
+
+Hashed assets under `/_astro/` never need revalidation — the filename changes when content changes.
+
+### View Transitions Prefetch
+
+```astro
+---
+// src/layouts/Base.astro
+import { ClientRouter } from 'astro:transitions';
+---
+<head>
+    <ClientRouter defaultStrategy="viewport" />
+</head>
+```
+
+`defaultStrategy: 'viewport'` prefetches links as they scroll into view, making navigation feel instant while keeping initial load minimal.
+
+### Font Preloading
+
+```html
+<link rel="preload" href="/fonts/Inter.woff2" as="font" type="font/woff2" crossorigin />
+```
+
+---
+
+## 12. Redirects
+
+### Per platform
+
+| Platform | File | Format |
+|---|---|---|
+| Cloudflare Pages | `public/_redirects` | `/old /new 301` |
+| Netlify | `public/_redirects` or `netlify.toml` | Same format |
+| Vercel | `vercel.json` | `{ "source": "/old", "destination": "/new", "permanent": true }` |
+
+### FuzzyRedirect on 404
+
+Safety net for URLs that slip through redirect tables:
+
+```astro
+---
+// src/pages/404.astro
+import FuzzyRedirect from '@jdevalk/astro-seo-graph/FuzzyRedirect.astro';
+---
+
+<html lang="en">
+<head><title>Page not found</title></head>
+<body>
+    <h1>Page not found</h1>
+    <p>The page you're looking for doesn't exist.</p>
+    <FuzzyRedirect />
+    <p><a href="/">Go to the homepage</a></p>
+</body>
+</html>
+```
+
+Behavior:
+- Fetches `/sitemap-index.xml`, computes Levenshtein similarity
+- **0.6–0.85 similarity**: shows "Did you mean /correct-path/?"
+- **>0.85**: auto-redirects with `window.location.replace`
+- **<0.6**: does nothing
+
+---
+
+## 13. RSS with Full Content
+
+```typescript
+// src/pages/rss.xml.ts
+import rss from '@astrojs/rss';
+import { getCollection } from 'astro:content';
+
+export async function GET(context) {
+    const posts = await getCollection('blog');
+    return rss({
+        title: 'My Blog',
+        description: 'Latest posts',
+        site: context.site,
+        items: posts.map((post) => ({
+            title: post.data.title,
+            pubDate: post.data.publishDate,
+            description: post.data.description,
+            link: `/blog/${post.id}/`,
+            content: post.body, // Full content, not excerpts
+        })),
+    });
+}
+```
+
+**Include full content in the feed** — truncated feeds frustrate readers and give AI systems less to work with.
+
+---
+
+## 14. Dynamic robots.txt
+
+```typescript
+// src/pages/robots.txt.ts
+export function GET() {
+    return new Response(
+`User-agent: *
+Allow: /
+
+Sitemap: https://example.com/sitemap-index.xml
+Schemamap: https://example.com/schemamap.xml
+`,
+        { headers: { 'Content-Type': 'text/plain' } },
+    );
+}
+```
+
+The `Schemamap:` directive points agents to the schema map — similar to `Sitemap:` but for structured data.
+
+---
+
+## 15. Implementation Checklist
+
+- [ ] `@jdevalk/astro-seo-graph` installed and `<Seo>` in all layouts
+- [ ] JSON-LD `@graph` with full entities (WebSite, Person, WebPage, Article, BreadcrumbList)
+- [ ] Trust signals: `publishingPrinciples`, `knowsAbout`, `SearchAction`
+- [ ] `seoSchema` in content collection with title/desc validation
+- [ ] `seoGraph()` integration with all validations enabled
+- [ ] Per-collection sitemaps with `gitLastmod`
+- [ ] IndexNow configured and key route deployed
+- [ ] Auto-generated OG images (1200×675 JPEG)
+- [ ] Schema endpoints + `/schemamap.xml`
+- [ ] Markdown alternates with `<link rel="alternate" type="text/markdown">`
+- [ ] `llms.txt` generated automatically
+- [ ] `<link rel="nlweb">` (when endpoint available)
+- [ ] `No-Vary-Search` header for UTM params
+- [ ] CDN cache: immutable for `/_astro/*`
+- [ ] View Transitions with viewport prefetch
+- [ ] FuzzyRedirect on 404
+- [ ] RSS with full content
+- [ ] `robots.txt` with Sitemap + Schemamap
+- [ ] Lychee in CI for broken external links
+- [ ] `/.well-known/api-catalog` (RFC 9727)
+
+---
+
+## References
+
+- [astro-seo-graph README](https://github.com/jdevalk/seo-graph/tree/main/packages/astro-seo-graph)
+- [astro-seo-graph AGENTS.md](https://github.com/jdevalk/seo-graph/blob/main/AGENTS.md) — 3000+ lines with recipes for 14 site types
+- [seo-graph-core](https://github.com/jdevalk/seo-graph/tree/main/packages/seo-graph-core)
+- [IndexNow documentation](https://www.indexnow.org/documentation)
+- [NLWeb protocol](https://github.com/nlweb-ai/NLWeb)
+- [satori](https://github.com/vercel/satori) — JSX → SVG
+- [sharp](https://sharp.pixelplumbing.com/) — SVG → JPEG/PNG
+- [No-Vary-Search (MDN)](https://developer.mozilla.org/docs/Web/HTTP/Reference/Headers/No-Vary-Search)
+- [RFC 9727 — API Catalog](https://www.rfc-editor.org/rfc/rfc9727)
+- [llms.txt standard](https://llmstxt.org)
+- [Joost: Astro SEO definitive guide](https://joost.blog/astro-seo-complete-guide/)
+- [Joost: Agent-ready static blog](https://joost.blog/agent-ready/)
--- a/.github/skills/astro-sites-manager/references/starlight-and-patterns.md
+++ b/.github/skills/astro-sites-manager/references/starlight-and-patterns.md
@@ -0,0 +1,604 @@
+# Starlight & Common Patterns
+
+## 1. Starlight Documentation Sites
+
+### Setup
+
+```bash
+npm create astro@latest -- --template starlight
+```
+
+Or add to an existing Astro project:
+
+```bash
+npx astro add starlight
+```
+
+### Configuration
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  site: 'https://docs.example.com',
+  integrations: [
+    starlight({
+      title: 'My Docs',
+      defaultLocale: 'en',
+      locales: {
+        en: { label: 'English' },
+        pt: { label: 'Português', lang: 'pt-BR' },
+      },
+      sidebar: [
+        { label: 'Home', link: '/' },
+        {
+          label: 'Guides',
+          items: [
+            { slug: 'guides/getting-started' },
+            { slug: 'guides/configuration' },
+          ],
+        },
+        {
+          label: 'Reference',
+          autogenerate: { directory: 'reference' },
+        },
+      ],
+      customCss: ['./src/styles/custom.css'],
+    }),
+  ],
+});
+```
+
+### Sidebar Gotchas
+
+**`link` and `items` are mutually exclusive.** A sidebar item is ONE of:
+
+- `link` — a single URL (requires `label`)
+- `slug` — reference to internal page (uses page title as label)
+- `items` — array of child links/groups (requires `label`)
+- `autogenerate` — auto-generates from a directory
+
+```ts
+// ❌ WRONG — cannot mix link with items
+{ label: 'Guides', link: '/guides/', items: [...] }
+
+// ✅ CORRECT — group with items
+{ label: 'Guides', items: [{ slug: 'guides/intro' }] }
+
+// ✅ CORRECT — single link
+{ label: 'Guides', link: '/guides/' }
+```
+
+**Autogenerate limitations:**
+- Only generates from files in `src/content/docs/<directory>/`
+- Sorted alphabetically by filename (use numeric prefixes like `01-intro.md` to control order)
+- Cannot filter files — all `.md`/`.mdx` in the directory are included
+- Subfolders become nested groups automatically
+
+### Built-in Components: Card vs LinkCard
+
+| Component | Purpose | Required Props | Has `href`? | Accepts children? |
+|-----------|---------|---------------|-------------|-------------------|
+| `Card` | Display content in a styled box | `title` | ❌ NO | ✅ Yes |
+| `LinkCard` | Prominent clickable link | `title`, `href` | ✅ YES | ❌ No |
+
+```mdx
+import { Card, LinkCard, CardGrid } from '@astrojs/starlight/components';
+
+{/* Card — displays content, NOT a link */}
+<Card title="Feature A" icon="star">
+  Description of feature A goes here.
+</Card>
+
+{/* LinkCard — entire card is a clickable link */}
+<LinkCard
+  title="Getting Started"
+  href="/guides/getting-started/"
+  description="Learn how to set up your project."
+/>
+
+{/* Group in a grid */}
+<CardGrid stagger>
+  <Card title="Fast" icon="rocket">Built for speed.</Card>
+  <Card title="Simple" icon="pencil">Easy to use.</Card>
+</CardGrid>
+```
+
+### Component Overrides
+
+Override any built-in Starlight UI component:
+
+```js
+// astro.config.mjs
+starlight({
+  components: {
+    // Replace the SocialIcons component
+    SocialIcons: './src/components/MyLinks.astro',
+    // Replace the Header
+    Header: './src/components/CustomHeader.astro',
+  },
+});
+```
+
+Reuse the built-in component inside your override:
+
+```astro
+---
+// src/components/CustomHeader.astro
+import Default from '@astrojs/starlight/components/Header.astro';
+---
+<Default><slot /></Default>
+<div class="announcement-bar">New release available!</div>
+```
+
+Full list of overridable components: see [Overrides Reference](https://starlight.astro.build/reference/overrides/).
+
+### Theming
+
+Starlight uses a semantic color system via CSS custom properties. The naming is **counter-intuitive**:
+
+| Variable | Meaning |
+|----------|---------|
+| `--sl-color-white` | **Foreground** (text) color |
+| `--sl-color-black` | **Background** color |
+| `--sl-color-gray-1` to `--sl-color-gray-6` | Gray scale (1 = lightest in dark mode) |
+| `--sl-color-accent-low` | Accent background |
+| `--sl-color-accent` | Accent mid (links, highlights) |
+| `--sl-color-accent-high` | Accent foreground |
+
+**You MUST define both `:root` (dark) and `:root[data-theme='light']` (light):**
+
+```css
+/* src/styles/custom.css */
+
+/* Dark mode (default) */
+:root {
+  --sl-color-white: #ffffff;
+  --sl-color-black: #181818;
+  --sl-color-gray-1: #eee;
+  --sl-color-gray-2: #c2c2c2;
+  --sl-color-gray-3: #8b8b8b;
+  --sl-color-gray-4: #585858;
+  --sl-color-gray-5: #383838;
+  --sl-color-gray-6: #272727;
+  --sl-color-accent-low: #1a1047;
+  --sl-color-accent: #8b5cf6;
+  --sl-color-accent-high: #c4b5fd;
+}
+
+/* Light mode — invert the logic */
+:root[data-theme='light'] {
+  --sl-color-white: #181818;
+  --sl-color-black: #ffffff;
+  --sl-color-gray-1: #272727;
+  --sl-color-gray-2: #383838;
+  --sl-color-gray-3: #585858;
+  --sl-color-gray-4: #8b8b8b;
+  --sl-color-gray-5: #c2c2c2;
+  --sl-color-gray-6: #eee;
+  --sl-color-accent-low: #c4b5fd;
+  --sl-color-accent: #6d28d9;
+  --sl-color-accent-high: #1a1047;
+}
+```
+
+**CSS Layer:** Starlight uses `@layer starlight` internally. Unlayered custom CSS automatically overrides it. For explicit layer control:
+
+```css
+@layer my-reset, starlight, my-overrides;
+
+@layer my-overrides {
+  :root {
+    --sl-content-width: 50rem;
+  }
+}
+```
+
+### Versioned Docs with starlight-utils multiSidebar
+
+```bash
+npm install @lorenzo_lewis/starlight-utils
+```
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import starlightUtils from '@lorenzo_lewis/starlight-utils';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: 'My Docs',
+      plugins: [
+        starlightUtils({
+          multiSidebar: {
+            switcherStyle: 'dropdown',
+          },
+        }),
+      ],
+      sidebar: [
+        // Each top-level group becomes a separate sidebar
+        {
+          label: 'v2',
+          items: [{ autogenerate: { directory: 'v2' } }],
+        },
+        {
+          label: 'v1',
+          items: [{ autogenerate: { directory: 'v1' } }],
+        },
+      ],
+    }),
+  ],
+});
+```
+
+---
+
+## 2. Search (Pagefind)
+
+### Install and Build
+
+Pagefind indexes static HTML after build. Starlight includes Pagefind by default. For non-Starlight Astro sites:
+
+```bash
+npm install -D pagefind
+```
+
+Add to your build script in `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "astro build && npx pagefind --site dist"
+  }
+}
+```
+
+### Indexing Controls
+
+```html
+<!-- Only index content inside this element -->
+<main data-pagefind-body>
+  <h1>Indexed heading</h1>
+  <p>This paragraph is searchable.</p>
+
+  <!-- Exclude specific elements -->
+  <nav data-pagefind-ignore>
+    <p>This won't appear in search results.</p>
+  </nav>
+
+  <!-- Boost heading weight in results -->
+  <h2 data-pagefind-weight="2">Important Section</h2>
+</main>
+```
+
+| Attribute | Effect |
+|-----------|--------|
+| `data-pagefind-body` | Only index inside this element (page-level) |
+| `data-pagefind-ignore` | Exclude element from indexing |
+| `data-pagefind-ignore="all"` | Exclude element and all descendants |
+| `data-pagefind-weight="N"` | Boost ranking (default: 1, higher = more relevant) |
+| `data-pagefind-meta="key:value"` | Add metadata to search results |
+
+### UI Component Integration
+
+```astro
+---
+// src/pages/search.astro
+---
+<html>
+<head>
+  <link href="/pagefind/pagefind-ui.css" rel="stylesheet" />
+</head>
+<body>
+  <div id="search"></div>
+  <script>
+    import '/pagefind/pagefind-ui.js';
+    new PagefindUI({ element: '#search', showSubResults: true });
+  </script>
+</body>
+</html>
+```
+
+### Pagefind vs Fuse.js Decision Table
+
+| Criteria | Pagefind | Fuse.js |
+|----------|----------|---------|
+| Index size | Pre-built, loads fragments on demand | Entire index in memory |
+| Best for | Static sites with 50+ pages | Small datasets (<100 items), dynamic data |
+| Setup | Build step required | No build step, works at runtime |
+| Fuzzy matching | Limited (typo tolerance) | Excellent (configurable threshold) |
+| Performance | O(1) per query chunk (WASM) | Degrades with data size |
+| Works offline | ✅ Yes | ✅ Yes |
+| SSR compatible | ❌ No (needs static HTML) | ✅ Yes |
+| Custom data | Indexes HTML only | Indexes any JSON array |
+| Bundle size | ~50KB (WASM) + on-demand chunks | ~25KB + full index |
+
+**Rule of thumb:** Use Pagefind for documentation/blog search. Use Fuse.js for in-page filtering (command palettes, dropdown search, dynamic lists).
+
+---
+
+## 3. SEO
+
+> **Full reference:** see [SEO Full Stack](seo-full-stack.md) — covers `@jdevalk/astro-seo-graph`, JSON-LD graph, IndexNow, auto-generated OG images, agent discovery, performance SEO, and build-time validation.
+
+Below is just the minimal setup for Starlight (which already includes automatic sitemap):
+
+### Starlight SEO Basics
+
+Starlight generates a sitemap automatically — just set `site` in your config. For RSS and custom meta tags in non-Starlight sites, see the full reference file.
+
+```js
+// astro.config.mjs — minimum for Starlight SEO
+export default defineConfig({
+  site: 'https://docs.example.com', // Required for sitemap and canonical
+  integrations: [starlight({ title: 'My Docs' })],
+});
+```
+
+---
+
+## 4. i18n Patterns
+
+### Configuration
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'pt-br', 'es'],
+    routing: {
+      prefixDefaultLocale: false, // /about (en), /pt-br/about, /es/about
+    },
+    fallback: {
+      'pt-br': 'en',
+      es: 'en',
+    },
+  },
+});
+```
+
+For Starlight, i18n is configured inside the integration:
+
+```js
+starlight({
+  defaultLocale: 'root',
+  locales: {
+    root: { label: 'English', lang: 'en' },
+    'pt-br': { label: 'Português', lang: 'pt-BR' },
+  },
+});
+```
+
+### Content Collections per Locale
+
+```
+src/content/docs/
+├── index.md           ← English (root locale)
+├── guides/
+│   └── intro.md
+└── pt-br/
+    ├── index.md       ← Portuguese
+    └── guides/
+        └── intro.md
+```
+
+### Fallback Strategy
+
+Show default locale content with a banner when translation is missing:
+
+```astro
+---
+// src/components/TranslationBanner.astro
+import { getEntry } from 'astro:content';
+
+const currentLocale = Astro.currentLocale ?? 'en';
+const slug = Astro.params.slug;
+
+// Check if translation exists
+const localizedEntry = await getEntry('docs', `${currentLocale}/${slug}`);
+const isFallback = !localizedEntry && currentLocale !== 'en';
+---
+
+{isFallback && (
+  <aside class="translation-banner" role="alert">
+    ⚠️ This page is not yet translated to {currentLocale}.
+    Showing English version.
+  </aside>
+)}
+```
+
+In Starlight, fallback is automatic — missing translations show the `defaultLocale` content with a built-in notice.
+
+### getRelativeLocaleUrl Helper
+
+```astro
+---
+import { getRelativeLocaleUrl } from 'astro:i18n';
+
+const locale = Astro.currentLocale ?? 'en';
+---
+<nav>
+  <a href={getRelativeLocaleUrl(locale, 'about')}>About</a>
+  <a href={getRelativeLocaleUrl(locale, 'guides/intro')}>Guide</a>
+</nav>
+```
+
+---
+
+## 5. Common Recipes
+
+### Pagination
+
+```astro
+---
+// src/pages/blog/[...page].astro
+import { getCollection } from 'astro:content';
+import type { GetStaticPaths } from 'astro';
+
+const POSTS_PER_PAGE = 10;
+
+export const getStaticPaths: GetStaticPaths = async ({ paginate }) => {
+  const allPosts = await getCollection('blog');
+  const sorted = allPosts.sort(
+    (a, b) => b.data.publishDate.valueOf() - a.data.publishDate.valueOf()
+  );
+  return paginate(sorted, { pageSize: POSTS_PER_PAGE });
+};
+
+const { page } = Astro.props;
+---
+<h1>Blog — Page {page.currentPage}</h1>
+
+<ul>
+  {page.data.map((post) => (
+    <li>
+      <a href={`/blog/${post.id}/`}>{post.data.title}</a>
+    </li>
+  ))}
+</ul>
+
+<nav>
+  {page.url.prev && <a href={page.url.prev}>← Previous</a>}
+  <span>Page {page.currentPage} of {page.lastPage}</span>
+  {page.url.next && <a href={page.url.next}>Next →</a>}
+</nav>
+```
+
+### Tag/Category Archives
+
+```astro
+---
+// src/pages/tags/[tag]/[...page].astro
+import { getCollection } from 'astro:content';
+
+export async function getStaticPaths({ paginate }) {
+  const allPosts = await getCollection('blog');
+  const allTags = [...new Set(allPosts.flatMap((post) => post.data.tags))];
+
+  return allTags.flatMap((tag) => {
+    const filtered = allPosts.filter((post) => post.data.tags.includes(tag));
+    return paginate(filtered, {
+      params: { tag },
+      pageSize: 10,
+    });
+  });
+}
+
+const { page } = Astro.props;
+const { tag } = Astro.params;
+---
+<h1>Posts tagged "{tag}"</h1>
+
+<ul>
+  {page.data.map((post) => (
+    <li><a href={`/blog/${post.id}/`}>{post.data.title}</a></li>
+  ))}
+</ul>
+```
+
+Tag index page:
+
+```astro
+---
+// src/pages/tags/index.astro
+import { getCollection } from 'astro:content';
+
+const allPosts = await getCollection('blog');
+const tags = [...new Set(allPosts.flatMap((post) => post.data.tags))].sort();
+---
+<h1>All Tags</h1>
+<ul>
+  {tags.map((tag) => (
+    <li><a href={`/tags/${tag}/1/`}>{tag}</a></li>
+  ))}
+</ul>
+```
+
+### Static Forms
+
+**Formspree:**
+
+```astro
+<form action="https://formspree.io/f/{form_id}" method="POST">
+  <label>
+    Email
+    <input type="email" name="email" required />
+  </label>
+  <label>
+    Message
+    <textarea name="message" required></textarea>
+  </label>
+  <button type="submit">Send</button>
+</form>
+```
+
+**Netlify Forms:**
+
+```astro
+<form name="contact" method="POST" data-netlify="true" netlify-honeypot="bot-field">
+  <input type="hidden" name="form-name" value="contact" />
+  <p class="hidden"><input name="bot-field" /></p>
+  <label>
+    Email
+    <input type="email" name="email" required />
+  </label>
+  <label>
+    Message
+    <textarea name="message" required></textarea>
+  </label>
+  <button type="submit">Send</button>
+</form>
+```
+
+### Dark Mode Toggle
+
+```astro
+---
+// src/components/ThemeToggle.astro
+---
+<button id="theme-toggle" aria-label="Toggle dark mode" type="button">
+  <span class="sun">☀️</span>
+  <span class="moon">🌙</span>
+</button>
+
+<script>
+  const toggle = document.getElementById('theme-toggle')!;
+
+  function getTheme(): 'light' | 'dark' {
+    return (
+      (localStorage.getItem('theme') as 'light' | 'dark') ??
+      (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
+    );
+  }
+
+  function setTheme(theme: 'light' | 'dark') {
+    document.documentElement.dataset.theme = theme;
+    localStorage.setItem('theme', theme);
+  }
+
+  // Apply on load
+  setTheme(getTheme());
+
+  toggle.addEventListener('click', () => {
+    setTheme(getTheme() === 'dark' ? 'light' : 'dark');
+  });
+</script>
+
+<style>
+  #theme-toggle {
+    background: none;
+    border: none;
+    cursor: pointer;
+    font-size: 1.25rem;
+  }
+  :root[data-theme='dark'] .sun { display: none; }
+  :root[data-theme='light'] .moon { display: none; }
+</style>
+```
+
+> **Note:** Starlight includes a built-in theme toggle. This pattern is for custom Astro sites.
--- a/.github/skills/astro-sites-manager/references/testing.md
+++ b/.github/skills/astro-sites-manager/references/testing.md
@@ -0,0 +1,387 @@
+# Testing Astro Projects
+
+Complete guide for testing Astro projects — from unit/component tests to E2E, link checking, type safety, and CI pipelines.
+
+---
+
+## 1. Component Testing with Vitest
+
+### Setup
+
+```bash
+npm install -D vitest @vitest/ui
+```
+
+### vitest.config.ts
+
+```ts
+/// <reference types="vitest" />
+import { getViteConfig } from 'astro/config';
+
+export default getViteConfig({
+  test: {
+    include: ['tests/**/*.{test,spec}.{js,ts}'],
+  },
+});
+```
+
+### AstroContainer API
+
+The `AstroContainer` API renders Astro components in isolation without a full dev server.
+
+```ts
+import { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import { expect, test } from 'vitest';
+import Greeting from '../src/components/Greeting.astro';
+
+test('renders greeting with name prop', async () => {
+  const container = await AstroContainer.create();
+  const result = await container.renderToString(Greeting, {
+    props: { name: 'World' },
+  });
+
+  expect(result).toContain('Hello, World');
+});
+```
+
+### Testing Props
+
+```ts
+test('renders default when no name provided', async () => {
+  const container = await AstroContainer.create();
+  const result = await container.renderToString(Greeting, {
+    props: {},
+  });
+
+  expect(result).toContain('Hello, stranger');
+});
+```
+
+### Testing Slots
+
+```ts
+import Card from '../src/components/Card.astro';
+
+test('renders slot content', async () => {
+  const container = await AstroContainer.create();
+  const result = await container.renderToString(Card, {
+    slots: { default: '<p>Slot content here</p>' },
+  });
+
+  expect(result).toContain('Slot content here');
+});
+```
+
+### Testing Conditional Rendering
+
+```ts
+import Alert from '../src/components/Alert.astro';
+
+test('renders error variant', async () => {
+  const container = await AstroContainer.create();
+  const result = await container.renderToString(Alert, {
+    props: { type: 'error', message: 'Something failed' },
+  });
+
+  expect(result).toContain('class="alert-error"');
+  expect(result).toContain('Something failed');
+});
+
+test('does not render when hidden', async () => {
+  const container = await AstroContainer.create();
+  const result = await container.renderToString(Alert, {
+    props: { type: 'info', message: 'Hidden', visible: false },
+  });
+
+  expect(result).not.toContain('Hidden');
+});
+```
+
+### Run Tests
+
+```bash
+npx vitest
+npx vitest --ui  # browser UI
+```
+
+---
+
+## 2. E2E Testing with Playwright
+
+### Setup
+
+```bash
+npm install -D @playwright/test
+npx playwright install
+```
+
+### playwright.config.ts
+
+```ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  webServer: {
+    command: 'npm run preview',
+    port: 4321,
+    reuseExistingServer: !process.env.CI,
+  },
+  use: {
+    baseURL: 'http://localhost:4321',
+  },
+});
+```
+
+> **Note:** Run `astro build` before E2E tests so `preview` has something to serve.
+
+### Example: Page Load
+
+```ts
+import { test, expect } from '@playwright/test';
+
+test('homepage loads correctly', async ({ page }) => {
+  await page.goto('/');
+  await expect(page).toHaveTitle(/My Site/);
+  await expect(page.locator('h1')).toBeVisible();
+});
+```
+
+### Example: Navigation
+
+```ts
+test('navigates to about page', async ({ page }) => {
+  await page.goto('/');
+  await page.click('a[href="/about"]');
+  await expect(page).toHaveURL('/about');
+  await expect(page.locator('h1')).toContainText('About');
+});
+```
+
+### Example: Dynamic Routes
+
+```ts
+test('blog post renders from content collection', async ({ page }) => {
+  await page.goto('/blog/first-post');
+  await expect(page.locator('article h1')).toBeVisible();
+  await expect(page.locator('article')).not.toBeEmpty();
+});
+```
+
+### Testing View Transitions
+
+```ts
+test('view transitions work between pages', async ({ page }) => {
+  await page.goto('/');
+  const transitionPromise = page.waitForEvent('load');
+  await page.click('a[href="/about"]');
+  await transitionPromise;
+  await expect(page).toHaveURL('/about');
+});
+```
+
+### Run E2E Tests
+
+```bash
+npx astro build
+npx playwright test
+npx playwright test --ui  # interactive mode
+```
+
+---
+
+## 3. Link Checking
+
+### linkinator
+
+Checks all links in the built output for broken references.
+
+```bash
+npx astro build
+npx linkinator dist --recurse
+```
+
+Options:
+
+```bash
+npx linkinator dist --recurse --skip "^https://external-site.com"
+```
+
+### CI Integration (GitHub Actions)
+
+```yaml
+- name: Check links
+  run: npx linkinator dist --recurse --retry --retry-errors
+```
+
+---
+
+## 4. Type Checking
+
+### Astro Template Validation
+
+```bash
+npx astro check
+```
+
+Validates `.astro` files for type errors in expressions, prop types, and component usage.
+
+### TypeScript Checking
+
+```bash
+npx tsc --noEmit
+```
+
+Validates all `.ts` and `.tsx` files without emitting output.
+
+### package.json Scripts
+
+```json
+{
+  "scripts": {
+    "check": "astro check && tsc --noEmit"
+  }
+}
+```
+
+---
+
+## 5. Content Collection Validation
+
+### Schema Enforcement
+
+Content collections validate against Zod schemas at build time. Invalid content **fails the build automatically**:
+
+```ts
+// src/content.config.ts
+import { defineCollection, z } from 'astro:content';
+
+const blog = defineCollection({
+  type: 'content',
+  schema: z.object({
+    title: z.string(),
+    date: z.date(),
+    draft: z.boolean().default(false),
+  }),
+});
+
+export const collections = { blog };
+```
+
+A frontmatter error produces:
+
+```
+[ERROR] blog → "bad-post.md" frontmatter does not match schema.
+  "title" is required.
+```
+
+### Draft Filtering
+
+Filter drafts in production queries:
+
+```astro
+---
+import { getCollection } from 'astro:content';
+
+const posts = await getCollection('blog', ({ data }) => {
+  return import.meta.env.PROD ? !data.draft : true;
+});
+---
+```
+
+Test that drafts are excluded by checking the built output does not contain draft post URLs.
+
+---
+
+## 6. Pre-Deploy Verification Script
+
+Save as `scripts/verify.sh`:
+
+```bash
+#!/bin/bash
+set -e
+
+echo "→ Type checking..."
+npx astro check
+
+echo "→ Building..."
+npx astro build
+
+echo "→ Checking links..."
+npx linkinator dist --recurse
+
+echo "→ Running E2E tests..."
+npx playwright test
+
+echo "✓ All checks passed"
+```
+
+```bash
+chmod +x scripts/verify.sh
+./scripts/verify.sh
+```
+
+---
+
+## 7. CI Pipeline (GitHub Actions)
+
+Save as `.github/workflows/test.yml`:
+
+```yaml
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+
+      - name: Type check
+        run: npx astro check && npx tsc --noEmit
+
+      - name: Build
+        run: npx astro build
+
+      - name: Component tests
+        run: npx vitest run
+
+      - name: Install Playwright
+        run: npx playwright install --with-deps chromium
+
+      - name: E2E tests
+        run: npx playwright test
+
+      - name: Link check
+        run: npx linkinator dist --recurse --retry
+
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+```
+
+---
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Component tests | `npx vitest` |
+| E2E tests | `npx playwright test` |
+| Type check | `npx astro check && tsc --noEmit` |
+| Link check | `npx linkinator dist --recurse` |
+| Full verification | `./scripts/verify.sh` |
--- a/.github/skills/astro-sites-manager/references/v6-features.md
+++ b/.github/skills/astro-sites-manager/references/v6-features.md
@@ -0,0 +1,271 @@
+# Astro v6 Features (still current in v7)
+
+These features were introduced or stabilized in Astro v6 and remain fully supported in v7.
+
+---
+
+## 1. Content Collections v2
+
+Type-safe content management with Zod schemas and flexible data loaders.
+
+```ts
+// content.config.ts
+import { defineCollection, z } from 'astro:content';
+
+const blog = defineCollection({
+  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
+  schema: z.object({
+    title: z.string(),
+    date: z.date(),
+    draft: z.boolean().default(false),
+  }),
+});
+
+export const collections = { blog };
+```
+
+**Loaders:**
+- `file()` — single file (JSON, YAML)
+- `glob()` — match files by pattern
+- Custom loaders — fetch from CMS at build or request time (live collections)
+
+**Querying:**
+```ts
+import { getCollection, getEntry } from 'astro:content';
+
+const posts = await getCollection('blog', ({ data }) => !data.draft);
+const post = await getEntry('blog', 'my-post');
+```
+
+---
+
+## 2. Server Actions
+
+Type-safe RPC endpoints with Zod validation.
+
+```ts
+// src/actions/index.ts
+import { defineAction } from 'astro:actions';
+import { z } from 'astro:schema';
+
+export const server = {
+  subscribe: defineAction({
+    input: z.object({ email: z.string().email() }),
+    handler: async ({ email }) => {
+      // process subscription
+      return { success: true };
+    },
+  }),
+};
+```
+
+**Usage in components:**
+```ts
+import { actions } from 'astro:actions';
+
+const result = await actions.subscribe({ email: 'user@example.com' });
+```
+
+**Form integration with progressive enhancement:**
+```astro
+<form method="POST" action={actions.subscribe}>
+  <input type="email" name="email" />
+  <button type="submit">Subscribe</button>
+</form>
+```
+
+---
+
+## 3. Sessions
+
+Server-side session management with pluggable drivers.
+
+**Config:**
+```js
+// astro.config.mjs
+export default defineConfig({
+  session: {
+    driver: 'cookie', // also: node-fs, redis, etc.
+  },
+});
+```
+
+**Usage:**
+```ts
+// In pages/endpoints
+const user = await Astro.session.get('user');
+await Astro.session.set('user', { name: 'Alice' });
+
+// In middleware
+const user = await context.session.get('user');
+```
+
+---
+
+## 4. Server Islands
+
+Defer component rendering to request time while keeping the page static.
+
+```astro
+---
+import UserGreeting from '../components/UserGreeting.astro';
+---
+<UserGreeting server:defer />
+```
+
+- Placeholder rendered at build time
+- Component fetched and rendered at request time
+- Perfect for personalized content in otherwise static pages
+
+---
+
+## 5. Environment Variables (astro:env)
+
+Type-safe, validated environment variables.
+
+```ts
+import { MY_SECRET } from 'astro:env/server';
+import { PUBLIC_API_URL } from 'astro:env/client';
+```
+
+**Schema definition:**
+```js
+// astro.config.mjs
+export default defineConfig({
+  env: {
+    schema: {
+      MY_SECRET: envField.string({ context: 'server', access: 'secret' }),
+      PUBLIC_API_URL: envField.string({ context: 'client', access: 'public' }),
+    },
+  },
+});
+```
+
+Variables are validated at build time — missing or invalid values cause build failures.
+
+---
+
+## 6. On-Demand Rendering
+
+Hybrid static/SSR on a per-page basis.
+
+```astro
+---
+// This page renders on every request
+export const prerender = false;
+---
+```
+
+**Adapters:**
+- `@astrojs/node`
+- `@astrojs/cloudflare`
+- `@astrojs/netlify`
+- `@astrojs/vercel`
+
+**Hybrid mode:** static by default, opt individual pages into SSR with `prerender = false`.
+
+---
+
+## 7. View Transitions
+
+Client-side navigation with animated transitions between pages.
+
+```astro
+---
+import { ViewTransitions } from 'astro:transitions';
+---
+<head>
+  <ViewTransitions />
+</head>
+
+<h1 transition:name="title" transition:animate="slide">Hello</h1>
+<div transition:persist>
+  <!-- State preserved across navigation -->
+</div>
+```
+
+**Lifecycle events:**
+- `astro:before-preparation`
+- `astro:after-swap`
+- `astro:page-load`
+
+---
+
+## 8. Middleware
+
+Request/response pipeline with access to context.
+
+```ts
+// src/middleware.ts
+import { defineMiddleware, sequence } from 'astro:middleware';
+
+const auth = defineMiddleware(async (context, next) => {
+  const token = context.cookies.get('token');
+  context.locals.user = await validateToken(token?.value);
+  return next();
+});
+
+const logging = defineMiddleware(async (context, next) => {
+  console.log(context.url.pathname);
+  return next();
+});
+
+export const onRequest = sequence(auth, logging);
+```
+
+Access to `context.locals`, `context.cookies`, `context.redirect()`.
+
+---
+
+## 9. Image Optimization
+
+Built-in image processing with automatic optimization.
+
+```astro
+---
+import { Image } from 'astro:assets';
+import hero from '../assets/hero.png';
+---
+<Image src={hero} alt="Hero" width={800} />
+```
+
+- Automatic format conversion, lazy loading, responsive sizes
+- Remote images configured via `image.domains` and `image.remotePatterns`:
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  image: {
+    domains: ['cdn.example.com'],
+    remotePatterns: [{ protocol: 'https', hostname: '**.example.com' }],
+  },
+});
+```
+
+---
+
+## 10. Internationalization (i18n)
+
+Built-in i18n routing with locale-aware URL generation.
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'pt-br', 'es'],
+    routing: {
+      prefixDefaultLocale: false,
+    },
+  },
+});
+```
+
+**URL generation:**
+```ts
+import { getRelativeLocaleUrl } from 'astro:i18n';
+
+getRelativeLocaleUrl('pt-br', '/about'); // → /pt-br/about
+```
+
+**Strategies:** pathname prefixes or domain-based routing.
--- a/.github/skills/astro-sites-manager/references/v7-features.md
+++ b/.github/skills/astro-sites-manager/references/v7-features.md
@@ -0,0 +1,491 @@
+# Astro v7 Features
+
+Complete reference for all major features introduced in Astro v7.
+
+---
+
+## 1. Vite 8 + Rolldown
+
+Astro v7 ships with **Vite 8**, which replaces the previous esbuild + Rollup bundling pipeline with **Rolldown** — a Rust-based bundler.
+
+### Key Points
+
+- **Rust-based bundler** replacing both esbuild (transform) and Rollup (bundling) in a single tool
+- **10-30x faster** than Rollup for production builds
+- **Same plugin API** — fully backwards compatible with existing Vite/Rollup plugins
+- **Compatibility layer** auto-converts `build.rollupOptions` and esbuild-specific options to their Rolldown equivalents
+
+### Migration
+
+No changes required for most projects. If you use `vite.build.rollupOptions` in `astro.config.mjs`, the compatibility layer handles the conversion automatically. Warnings are emitted for any options that cannot be directly mapped.
+
+```js
+// astro.config.mjs — works as before
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  vite: {
+    build: {
+      // Automatically converted to Rolldown equivalents
+      rollupOptions: {
+        output: {
+          manualChunks: { vendor: ['react', 'react-dom'] }
+        }
+      }
+    }
+  }
+});
+```
+
+---
+
+## 2. Rust Compiler
+
+The Astro template compiler has been rewritten in **Rust**, replacing the previous Go-based compiler. Built on **oxc** (JavaScript/TypeScript parser) and **Lightning CSS**.
+
+### Key Points
+
+- **Native binaries** for all major platforms with **WASM fallback** for unsupported architectures
+- **Strict parsing**: unclosed tags are now errors (no HTML auto-correction)
+- **JSX whitespace rules**: newlines between inline elements produce no whitespace in output
+- **CSS differences**: minor cosmetic changes to color serialization and `url()` quoting (output-only, no behavioral change)
+
+### Breaking Changes
+
+#### Strict HTML Parsing
+
+```astro
+<!-- ❌ Error in v7 — unclosed tag -->
+<div>
+  <p>Hello world
+</div>
+
+<!-- ✅ Correct -->
+<div>
+  <p>Hello world</p>
+</div>
+```
+
+#### JSX Whitespace Rules
+
+```astro
+<!-- In v7, newline between inline elements = no space in output -->
+<span>Hello</span>
+<span>World</span>
+<!-- Renders: "HelloWorld" -->
+
+<!-- Add explicit space -->
+<span>Hello</span>{' '}
+<span>World</span>
+<!-- Renders: "Hello World" -->
+```
+
+#### CSS Cosmetic Differences
+
+```css
+/* v6 output */
+background: url(image.png);
+color: #ff0000;
+
+/* v7 output (functionally identical) */
+background: url("image.png");
+color: red;
+```
+
+---
+
+## 3. Sätteri (Markdown/MDX in Rust)
+
+**Sätteri** is Astro v7's default Markdown and MDX processor, replacing the unified/remark/rehype pipeline with a Rust-native implementation.
+
+### Key Points
+
+- Built on **pulldown-cmark** (Markdown parsing) + **oxc** (MDX/JSX)
+- Default processor — no configuration needed for standard usage
+- Replaces unified/remark/rehype with dramatically faster processing
+
+### Built-in Features
+
+| Feature | Description |
+|---------|-------------|
+| GFM | Tables, strikethrough, task lists, autolinks |
+| Smart punctuation | Curly quotes, em/en dashes |
+| Heading IDs | Auto-generated anchor IDs |
+| Directives | Container/leaf/text directives (`::: note`, etc.) |
+| Math | LaTeX math blocks (`$$...$$`) and inline (`$...$`) |
+| Frontmatter | YAML frontmatter parsing |
+| Superscript/Subscript | `^super^` and `~sub~` syntax |
+| Wikilinks | `[[page]]` and `[[page|text]]` syntax |
+
+### Configuration
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { satteri } from '@astrojs/markdown-satteri';
+
+export default defineConfig({
+  markdown: {
+    processor: satteri({
+      gfm: true,
+      smartPunctuation: true,
+      headingIds: true,
+      math: true,
+      wikilinks: true,
+      directives: true,
+    })
+  }
+});
+```
+
+### Plugin API
+
+Sätteri plugins declare which node types they handle, skipping all others. This is significantly cheaper than unified's visitor pattern.
+
+```js
+// my-satteri-plugin.js
+export default function myPlugin() {
+  return {
+    name: 'my-plugin',
+    nodes: ['heading', 'paragraph'], // only visit these types
+    transform(node, context) {
+      if (node.type === 'heading') {
+        // transform heading nodes
+      }
+    }
+  };
+}
+```
+
+### Fallback to unified/remark/rehype
+
+For projects relying on existing remark/rehype plugins:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { unified } from '@astrojs/markdown-remark';
+import remarkToc from 'remark-toc';
+import rehypePrism from 'rehype-prism';
+
+export default defineConfig({
+  markdown: {
+    processor: unified({
+      remarkPlugins: [remarkToc],
+      rehypePlugins: [rehypePrism],
+    })
+  }
+});
+```
+
+### Docker Deployment Note
+
+Sätteri ships native bindings only for **glibc** (`@bruits/satteri-linux-x64-gnu`). Alpine Linux uses musl — there is no musl binding. Docker build stages MUST use `node:22-slim` (Debian/glibc), not `node:22-alpine`. This affects all Astro v7 projects using Sätteri (the default), including Starlight sites.
+
+Projects using `unified()` explicitly are NOT affected (they bypass Sätteri entirely).
+
+---
+
+## 4. Queued Rendering
+
+Astro v7's rendering engine uses a **queue/stack-based** approach instead of recursive rendering.
+
+### Key Points
+
+- **~2.4x faster** for expression-dense pages (many dynamic expressions, loops, conditionals)
+- **Now stable and default** — no configuration needed
+- Eliminates deep call-stack issues on complex component trees
+- Reduces memory pressure through iterative processing
+
+### Migration
+
+No action required. This is an internal engine change that is fully transparent to user code.
+
+---
+
+## 5. Advanced Routing (`src/fetch.ts`)
+
+Astro v7 introduces a **standard fetch handler pattern** for advanced routing control, following the same conventions as Cloudflare Workers, Deno, and Bun.
+
+### Key Points
+
+- Define a `src/fetch.ts` file to take full control of the request pipeline
+- Compose individual pieces: `i18n()`, `actions()`, `middleware()`, `pages()`
+- Full control over request pipeline order
+- Compatible with Hono for complex routing scenarios
+
+### Basic Routing
+
+```ts
+// src/fetch.ts
+import { astro, FetchState } from 'astro/fetch';
+
+export default astro((request: Request, state: FetchState) => {
+  // Compose the pipeline in your preferred order
+  return state.pipeline(
+    i18n(),
+    middleware(),
+    actions(),
+    pages()
+  );
+});
+```
+
+### Hono Integration
+
+```ts
+// src/fetch.ts
+import { astro } from 'astro/hono';
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { logger } from 'hono/logger';
+
+const app = new Hono();
+
+app.use('*', logger());
+app.use('/api/*', cors());
+
+app.get('/api/health', (c) => c.json({ status: 'ok' }));
+
+// Hand off to Astro for everything else
+export default astro(app);
+```
+
+### Composing Middleware
+
+```ts
+// src/fetch.ts
+import { astro, FetchState } from 'astro/fetch';
+import { i18n, actions, middleware, pages } from 'astro/fetch';
+
+export default astro((request: Request, state: FetchState) => {
+  const url = new URL(request.url);
+
+  // Custom routing logic
+  if (url.pathname.startsWith('/api/')) {
+    return state.pipeline(
+      actions()
+    );
+  }
+
+  // Full pipeline for pages
+  return state.pipeline(
+    i18n(),
+    middleware(),
+    actions(),
+    pages()
+  );
+});
+```
+
+---
+
+## 6. Route Caching (Stable)
+
+Route-level caching is now **stable** in Astro v7, providing fine-grained control over page caching with tag-based invalidation.
+
+### Key Points
+
+- In-memory cache available out of the box
+- Per-page caching with `Astro.cache.set()`
+- Declarative `routeRules` in config
+- Tag-based invalidation
+- Integration with live content collections
+
+### Config-Level Setup
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { memoryCache } from 'astro/config';
+
+export default defineConfig({
+  cache: memoryCache(),
+  routeRules: {
+    '/blog/**': { cache: { maxAge: 3600, swr: 86400, tags: ['blog'] } },
+    '/products/**': { cache: { maxAge: 600, tags: ['products'] } },
+    '/about': { cache: { maxAge: 86400 } },
+  }
+});
+```
+
+### Per-Page Caching
+
+```astro
+---
+// src/pages/blog/[slug].astro
+const { slug } = Astro.params;
+const post = await getEntry('blog', slug);
+
+Astro.cache.set({
+  maxAge: 3600,       // 1 hour
+  swr: 86400,         // stale-while-revalidate: 24 hours
+  tags: ['blog', `post:${slug}`]
+});
+---
+
+<article>
+  <h1>{post.data.title}</h1>
+  <Content />
+</article>
+```
+
+### Webhook Invalidation
+
+```ts
+// src/pages/api/revalidate.ts
+import type { APIRoute } from 'astro';
+import { cache } from 'astro:cache';
+
+export const POST: APIRoute = async ({ request }) => {
+  const { secret, tags, path } = await request.json();
+
+  if (secret !== import.meta.env.REVALIDATION_SECRET) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  // Invalidate by tags
+  if (tags) {
+    await cache.invalidate({ tags });
+  }
+
+  // Invalidate by path
+  if (path) {
+    await cache.invalidate({ path });
+  }
+
+  return new Response(JSON.stringify({ revalidated: true }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  });
+};
+```
+
+### Live Content Collections Integration
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { memoryCache } from 'astro/config';
+
+export default defineConfig({
+  cache: memoryCache(),
+  content: {
+    collections: {
+      blog: {
+        // When content changes, invalidate matching cache tags
+        onUpdate: (entry) => cache.invalidate({ tags: ['blog', `post:${entry.slug}`] })
+      }
+    }
+  }
+});
+```
+
+---
+
+## 7. CDN Cache Providers (Experimental)
+
+CDN-level cache providers push cache directives to the edge, allowing cached responses to be served **without invoking the server**.
+
+### Key Points
+
+- Edge-level caching — hits never reach your application server
+- Platform-specific providers for Netlify, Vercel, and Cloudflare
+- Works with the same `routeRules` and `Astro.cache.set()` API
+
+### Providers
+
+```js
+// Netlify
+import { cacheNetlify } from '@astrojs/netlify/cache';
+
+export default defineConfig({
+  cache: cacheNetlify(),
+});
+```
+
+```js
+// Vercel
+import { cacheVercel } from '@astrojs/vercel/cache';
+
+export default defineConfig({
+  cache: cacheVercel(),
+});
+```
+
+```js
+// Cloudflare (private beta)
+import { cacheCloudflare } from '@astrojs/cloudflare/cache';
+
+export default defineConfig({
+  cache: cacheCloudflare(),
+});
+```
+
+### How It Works
+
+1. On first request: server renders the page, cache provider stores response at the edge
+2. On subsequent requests: CDN serves cached response directly (no server invocation)
+3. On invalidation: cache is purged via provider API, next request triggers fresh render
+
+---
+
+## 8. AI Enhancements
+
+Astro v7 includes first-class support for AI-assisted development workflows.
+
+### Key Points
+
+- **Background dev server**: auto-detects when running inside AI agents and optimizes output
+- **JSON logging**: configurable, composable log output for machine consumption
+- See `ai-dev-server.md` for full details
+
+### Background Dev Server
+
+When Astro detects it's running inside an AI agent environment, it automatically:
+
+- Switches to structured JSON log output
+- Suppresses interactive UI elements (progress bars, spinners)
+- Provides machine-readable error messages with file/line references
+- Exposes a lightweight status API for agent polling
+
+### JSON Logging
+
+```js
+// astro.config.mjs
+export default defineConfig({
+  devToolbar: { enabled: false },
+  logging: {
+    format: 'json', // 'pretty' | 'json' | 'minimal'
+    level: 'info',
+  }
+});
+```
+
+---
+
+## 9. Performance Benchmarks
+
+Real-world build time improvements measured on production sites (Astro v6 → v7):
+
+| Site | v6 | v7 | Improvement |
+|------|----|----|-------------|
+| docs.astro.build | 114s | 73s | **36% faster** |
+| astro.build | 62s | 24s | **61% faster** |
+| biomejs.dev | 176s | 150s | **15% faster** |
+| developers.cloudflare.com | 387s | 262s | **32% faster** |
+
+### Contributing Factors
+
+- **Rolldown bundler**: 10-30x faster than Rollup for the bundling phase
+- **Rust compiler**: eliminates Go→WASM overhead, native binary execution
+- **Sätteri**: Markdown/MDX processing in Rust vs. JavaScript-based unified pipeline
+- **Queued rendering**: 2.4x faster for expression-dense templates
+
+### Impact by Project Size
+
+- Small sites (< 100 pages): 15-25% faster builds
+- Medium sites (100-1000 pages): 30-45% faster builds
+- Large sites (1000+ pages): 40-60% faster builds
+
+The largest gains are seen in content-heavy sites with extensive Markdown processing and complex component trees.
--- a/.github/skills/astro-sites-manager/references/validation-checklist.md
+++ b/.github/skills/astro-sites-manager/references/validation-checklist.md
@@ -0,0 +1,210 @@
+# Validation Checklist
+
+Complete checklist for validating an Astro installation/upgrade. Run these checks in the project root.
+
+---
+
+## 1. Build Validation
+
+```bash
+# Full production build — must exit 0 with no errors
+npx astro build
+
+# Type checking (requires @astrojs/check)
+npx astro check
+
+# Verify no unclosed tags (Rust compiler is strict about this)
+find src -name "*.astro" -exec grep -Pn '<(img|br|hr|input|meta|link|source|area|base|col|embed|param|track|wbr)[^/]*[^/]>' {} +
+
+# Check for HTML nesting issues (div/section/article inside p)
+grep -rPn '<p[^>]*>[\s\S]*?<(div|section|article|ul|ol|table|blockquote|h[1-6])' src/**/*.astro
+```
+
+**Expected:** All commands pass with no errors or matches.
+
+---
+
+## 2. Breaking Pattern Detection
+
+### Unclosed HTML tags
+
+```bash
+# Find self-closing tags that are NOT void elements (common breakage)
+grep -rPn '<(div|span|p|a|section|main|footer|header|nav|ul|li)\s[^>]*/>' src/ --include="*.astro"
+```
+
+### Block elements inside `<p>`
+
+```bash
+grep -rPn '<p[^>]*>[\s\S]*?<(div|section|article|ul|ol|dl|table|blockquote|pre|h[1-6]|form|fieldset|hr)' src/ --include="*.astro"
+```
+
+### Whitespace-dependent inline layouts
+
+```bash
+# Look for adjacent inline elements that rely on whitespace rendering
+grep -rPn '</(span|a|strong|em|code)>\s*<(span|a|strong|em|code)' src/ --include="*.astro"
+```
+
+### src/fetch.ts conflict
+
+```bash
+# Astro reserves src/fetch.ts — check if it exists
+find src -maxdepth 1 -name "fetch.ts" -o -name "fetch.js"
+```
+
+### @astrojs/db usage (removed in Astro 5+)
+
+```bash
+grep -rn "@astrojs/db" package.json src/ --include="*.{ts,js,astro}"
+```
+
+### Deprecated transition imports
+
+```bash
+# TRANSITION_* named exports removed
+grep -rPn 'TRANSITION_[A-Z_]+' src/ --include="*.{ts,js,astro}"
+
+# isTransition*() helpers removed
+grep -rPn 'isTransition\w+\(' src/ --include="*.{ts,js,astro}"
+```
+
+### getContainerRenderer() from package root
+
+```bash
+# Must now import from /container subpath
+grep -rn "getContainerRenderer" src/ --include="*.{ts,js}" | grep -v "/container"
+```
+
+### Experimental flags that should be removed
+
+```bash
+# Check astro.config for experimental flags that graduated to stable
+grep -A 20 'experimental:' astro.config.{mjs,ts,js} 2>/dev/null | grep -P '(contentLayer|serverIslands|actions|env|fonts|responsiveImages|svg)'
+```
+
+---
+
+## 3. Deprecated Pattern Detection
+
+| Pattern | grep command | Fix |
+|---------|-------------|-----|
+| `Astro.glob()` | `grep -rn "Astro.glob" src/ --include="*.astro"` | Replace with `import.meta.glob()` or Content Collections |
+| `Astro.fetchContent()` | `grep -rn "Astro.fetchContent" src/ --include="*.astro"` | Replace with Content Collections |
+| `getStaticPaths` without `paginate` import | `grep -rn "getStaticPaths" src/ --include="*.astro"` | Verify using new pagination API |
+| Legacy content collections (`src/content/config.ts` with `defineCollection` using `schema` only) | `grep -rn "defineCollection" src/content/config.ts` | Migrate to `type: 'content_layer'` or new loader API |
+| `@astrojs/image` | `grep -rn "@astrojs/image" package.json` | Use built-in `astro:assets` |
+| `integrations: [image()]` | `grep -rn "image()" astro.config.*` | Remove — use built-in `<Image>` component |
+| `<Markdown>` component | `grep -rn "<Markdown" src/ --include="*.astro"` | Use MDX or Content Collections |
+| `set:html` on component | `grep -rPn 'set:html' src/ --include="*.astro"` | Verify it's on HTML elements only |
+| `class:list` with nested arrays | `grep -rPn 'class:list=\{.*\[.*\[' src/ --include="*.astro"` | Flatten to single array |
+
+---
+
+## 4. Markdown/MDX Validation
+
+### Remark/Rehype plugin migration
+
+```bash
+# Check if custom remark/rehype plugins are configured
+grep -Pn '(remarkPlugins|rehypePlugins)' astro.config.{mjs,ts,js} 2>/dev/null
+
+# If found, verify @astrojs/markdown-remark is installed
+grep -n "@astrojs/markdown-remark" package.json
+```
+
+**Fix:** If custom plugins exist but `@astrojs/markdown-remark` is missing:
+```bash
+npx astro add @astrojs/markdown-remark
+```
+
+### Shiki (syntax highlighting) compatibility
+
+```bash
+# Check for custom Shiki config — API may have changed
+grep -A 10 'shikiConfig' astro.config.{mjs,ts,js} 2>/dev/null
+```
+
+### GFM features (tables, strikethrough, autolinks)
+
+```bash
+# GFM is built-in — check there's no redundant remark-gfm
+grep -rn "remark-gfm" package.json astro.config.{mjs,ts,js} 2>/dev/null
+```
+
+**Fix:** Remove `remark-gfm` from plugins — GFM is included by default.
+
+### Test MDX rendering
+
+```bash
+# Verify MDX integration is present if .mdx files exist
+find src -name "*.mdx" | head -1 && grep -n "@astrojs/mdx" package.json
+```
+
+---
+
+## 5. Performance Validation
+
+### Compare build times
+
+```bash
+# Time the build (run before and after upgrade)
+time npx astro build 2>&1 | tail -5
+```
+
+### Verify queued rendering is active
+
+```bash
+# Queued rendering should be default in Astro 5+ — check it's not disabled
+grep -n "queuedRendering" astro.config.{mjs,ts,js} 2>/dev/null
+```
+
+**Expected:** No results (uses default) or `true`. If set to `false`, remove it.
+
+### Check Vite 6+ bundle output
+
+```bash
+# Verify build output structure
+ls -la dist/ 2>/dev/null || ls -la dist/_astro/ 2>/dev/null
+
+# Check chunk sizes
+find dist -name "*.js" -exec wc -c {} + | sort -n | tail -10
+
+# Verify no duplicate framework chunks
+find dist -name "*.js" | xargs grep -l "react" 2>/dev/null | wc -l
+```
+
+### Verify no dev-only code in production build
+
+```bash
+grep -rn "import.meta.env.DEV" dist/ 2>/dev/null
+```
+
+---
+
+## Quick Full Validation Script
+
+```bash
+#!/usr/bin/env bash
+set -e
+echo "=== Astro Validation ==="
+
+echo "[1/5] Build..."
+npx astro build
+
+echo "[2/5] Type check..."
+npx astro check || echo "WARN: astro check failed"
+
+echo "[3/5] Breaking patterns..."
+grep -rn "@astrojs/db" src/ --include="*.{ts,js,astro}" && echo "FAIL: @astrojs/db found" || true
+grep -rPn 'TRANSITION_[A-Z_]+' src/ --include="*.{ts,js,astro}" && echo "FAIL: deprecated transitions" || true
+find src -maxdepth 1 -name "fetch.ts" -o -name "fetch.js" | grep . && echo "FAIL: src/fetch conflict" || true
+
+echo "[4/5] Deprecated APIs..."
+grep -rn "Astro.glob\|Astro.fetchContent\|@astrojs/image" src/ package.json && echo "FAIL: deprecated APIs" || true
+
+echo "[5/5] Performance..."
+time npx astro build 2>&1 | tail -3
+
+echo "=== Done ==="
+```
--- a/.github/skills/auth-md/SKILL.md
+++ b/.github/skills/auth-md/SKILL.md
@@ -0,0 +1,357 @@
+---
+name: auth-md
+description: >
+  Generate, validate, and explain `auth.md` files — the open protocol that lets AI agents
+  register for services on behalf of users. Use this skill whenever the user wants to make
+  their app agent-ready by publishing an `auth.md`, generate Protected Resource Metadata
+  (RFC 9728), validate an existing `auth.md` against the protocol specification, implement
+  agent registration endpoints, understand how the auth.md protocol works, or configure
+  authentication flows for agents. Trigger on mentions of "auth.md", "agent registration",
+  "agent auth", "make my app agent-ready", "ID-JAG", "identity_assertion flow",
+  "service_auth flow", "protected resource metadata", "claim ceremony", "agentic registration",
+  "CIMD", "Client ID Metadata Document", "oauth-id-jag", "agent revocation",
+  "agent credential", "agent discovery", "token exchange", "interaction_required",
+  "/.well-known/oauth-protected-resource", "/.well-known/oauth-authorization-server",
+  "/agent/identity", "/oauth2/token", or any variation of AI agent authentication/registration in APIs.
+metadata:
+  author: https://ft.ia.br
+  version: "2.0"
+  date: 2026-06-27
+  repository: https://github.com/fabricioctelles/skills
+  license: Apache 2.0
+  category: library-and-api-reference
+---
+
+# auth-md
+
+Generate, validate, and explain the **auth.md** protocol — the open standard that lets AI agents register for services on behalf of users, without signup forms.
+
+---
+
+## Protocol Context
+
+auth.md is a Markdown file published at a service's root (typically `https://service.com/auth.md`) that instructs agents on how to register. It works simultaneously as human-readable documentation and as a discoverable runtime artifact for agents.
+
+The protocol extends RFC 9728 (OAuth 2.0 Protected Resource Metadata) with an `agent_auth` block in the Authorization Server metadata. Registration returns an `identity_assertion` (service-signed JWT) that the agent exchanges at `/oauth2/token` for an `access_token`. Three registration methods are supported:
+
+| Flow | Mechanism | When to use |
+|------|-----------|-------------|
+| **identity_assertion** | Provider signs an ID-JAG (with `auth_time`) asserting user identity. Service verifies JWKS, returns `identity_assertion`. Agent exchanges at `/oauth2/token`. | Service does JIT provisioning from OIDC/SAML; wants zero-friction registration. |
+| **service_auth** | Email hint + browser-based ceremony. Agent receives `user_code` + `verification_uri`; user signs in and types code. Agent polls `/oauth2/token`. | Agents on platforms that can't mint ID-JAGs; self-serve without trust list. |
+| **anonymous** | No identity upfront. Immediate `identity_assertion` with pre-claim scopes. Optional deferred claim for scope upgrade. | Agent needs basic access immediately; human ownership binding deferred. |
+
+### Protocol Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `/.well-known/oauth-protected-resource` | Discovery — resource metadata (RFC 9728) |
+| `/.well-known/oauth-authorization-server` | Discovery — AS metadata with `agent_auth` block |
+| `POST /agent/identity` | Registration — dispatches on `type` field |
+| `POST /agent/identity/claim` | Claim initiation (anonymous deferred, or re-initiate expired user_code) |
+| `POST /oauth2/token` | Token exchange (JWT-bearer grant) + claim polling (claim grant) |
+| `POST /oauth2/revoke` | Credential-layer revocation (RFC 7009) |
+| `events_endpoint` | Registration-layer revocation (receives SETs, RFC 8935) |
+
+### Token Lifecycle
+
+Registration **never** returns an `access_token` directly. The flow is:
+
+1. Registration → `identity_assertion` (service-signed JWT, reusable until expiry)
+2. Exchange → `POST /oauth2/token` with `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer` → `access_token`
+3. Refresh → re-exchange same `identity_assertion` when access_token expires
+4. Expired assertion → restart at registration (Step 3)
+
+### Claim Ceremony (v2 — Browser-Based)
+
+The claim ceremony uses RFC 8628-style device authorization:
+1. Registration returns `user_code` + `verification_uri` in a `claim` block
+2. Agent surfaces both to the user
+3. User opens `verification_uri`, signs in to the service, types the 6-digit code
+4. Agent polls `POST /oauth2/token` with `grant_type=urn:workos:agent-auth:grant-type:claim` + `claim_token`
+5. On success: receives `access_token` + fresh `identity_assertion`
+
+---
+
+## Operation Modes
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `mode` | `generate` | `generate` = create auth.md + metadata; `validate` = check existing auth.md; `explain` = explain the protocol |
+| `validation_level` | `basic` | `basic` = structure + fields + consistency (offline); `full` = basic + live endpoint fetch |
+| `flows` | `all` | Which flows to include: `identity_assertion`, `service_auth`, `anonymous`, `all` |
+| `role` | `app` | Perspective: `app` = service accepting registrations; `provider` = platform minting ID-JAGs |
+
+---
+
+## Workflow: Generate
+
+### 1. Scan the codebase
+
+Look for:
+- Existing API routes and authentication patterns
+- Defined scopes/permissions
+- Framework (Express, Django, Rails, FastAPI, NestJS, etc.)
+- Base URL and auth server URL configuration
+- Existing authentication middleware
+- User models and provisioning mechanisms
+
+### 2. Ask the user only what cannot be inferred
+
+- Which flows to support (identity_assertion, service_auth, anonymous, or combination)
+- Pre-claim scopes vs post-claim scopes (if anonymous)
+- Trusted agent providers and trust list policy (if identity_assertion)
+- Whether the service already does JIT provisioning or requires manual onboarding
+- `idJagMaxAuthAgeSeconds` value (default: 3600)
+- Desired rate limiting policy
+
+### 3. Generate artifacts
+
+Produce three artifacts:
+
+**a) `auth.md`** — Markdown file following the protocol template (see `references/protocol-template.md`). Must contain:
+- Title and intro addressed to the agent
+- Step 1 — Discover (two hops: PRM → AS metadata)
+- Step 2 — Pick a method (decision tree)
+- Step 3 — Register (one subsection per supported method)
+- Step 4 — Claim ceremony (if service_auth or anonymous with claim)
+- Step 5 — Exchange the assertion (POST /oauth2/token with jwt-bearer grant)
+- Step 6 — Use the access_token
+- Errors (complete table with all applicable codes)
+- Revocation (two layers)
+
+**b) `oauth-protected-resource.json`** — JSON for `/.well-known/oauth-protected-resource` with `resource_name` and `resource_logo_uri`
+
+**c) `oauth-authorization-server.json`** — JSON for `/.well-known/oauth-authorization-server` with:
+- `issuer`, `token_endpoint`, `revocation_endpoint`, `grant_types_supported`
+- Complete `agent_auth` block with `identity_endpoint`, `claim_endpoint`, `events_endpoint`
+
+### 4. Generate implementation guidance
+
+"Next Steps" section with:
+- How to serve `auth.md` at the domain root
+- How to serve metadata at the well-known paths
+- How to add `WWW-Authenticate` header to 401 responses
+- Endpoint implementation guidance (without generating framework-specific code unless requested)
+- Token exchange implementation at `/oauth2/token`
+- Claim page hosting (verification_uri → login → code input → confirm)
+- Recommended rate limiting configuration
+- Recommended audit events
+- Security considerations (token hashing, auth_time validation, replay protection, claim_token handling)
+
+### 5. Generate Agent Provider guide (if role=provider)
+
+When the user is an agent provider (not an app), generate:
+- How to mint audience-specific ID-JAGs with `auth_time`
+- Token structure (header + payload with required and optional claims)
+- How to publish JWKS
+- Optionally: how to publish a CIMD (Client ID Metadata Document)
+- How to implement revocation (POST SET to events_endpoint)
+- How to present consent to the user before asserting identity (using `resource_name` + `resource_logo_uri`)
+
+---
+
+## Workflow: Validate
+
+### 1. Load the auth.md
+
+From a local file path or URL.
+
+### 2. Run validation at the requested level
+
+**Basic (offline):**
+- All required headings present (Step 1–6, Errors, Revocation)
+- At least one flow documented
+- Valid JSON in fenced code blocks for request/response shapes
+- AS metadata contains `identity_endpoint`, `token_endpoint`, `grant_types_supported`
+- Error table with standard error codes
+- Consistency: flows in prose match `identity_types_supported` in metadata JSON
+- No unreplaced placeholders
+
+**Full (live):**
+- All basic checks, plus:
+- Fetch `/.well-known/oauth-protected-resource` from the declared base URL
+- Verify `agent_auth` block exists in AS metadata
+- Fetch `/.well-known/oauth-authorization-server` and verify consistency
+- Check that `identity_endpoint`, `token_endpoint`, `revocation_endpoint` respond (accept 400/401/422, reject 404/405)
+- Verify API returns 401 with `WWW-Authenticate` containing `resource_metadata`
+
+### 3. Report results
+
+Checklist with ✅/❌ per rule, grouped by category:
+- **Structure** — headings and order
+- **Fields** — required fields in JSONs
+- **Consistency** — cross-references between prose and metadata
+- **Format** — valid JSON, valid HTTP, no placeholders
+- **Endpoints** (full only) — reachability and correct responses
+
+Include severity: 🔴 Error (agents will fail), 🟡 Warning (degraded experience), 🟢 Info (suggestion).
+
+See `references/validation-rules.md` for the complete ruleset.
+
+---
+
+## Workflow: Explain
+
+When the user wants to understand the protocol without generating or validating:
+
+1. Identify what the user wants to know (overview, specific flow, specific endpoint, security, etc.)
+2. Explain using the protocol context above and the references
+3. Use text-based sequence diagrams when helpful
+4. Point to official documentation when relevant
+
+---
+
+## User Matching and JIT Provisioning
+
+The identity_assertion flow needs to decide which service user a registration represents. Recommended resolution order:
+
+1. **Delegation record match** — if `(iss, sub)` has a delegation on file, route to same user
+2. **Verified email match** — if a user exists with same verified email BUT no `(iss, sub)` delegation → `interaction_required` (401) with claim block for user to confirm linking
+3. **Verified phone match** — same pattern
+4. **No match → JIT** — create a new user per provisioning policy, or refuse
+
+Reject ID-JAGs with neither a verified email nor a verified phone — there's no basis for matching.
+
+---
+
+## Rate Limiting
+
+The `/agent/identity` endpoint is unauthenticated for anonymous registration. Implement two tiers:
+
+1. **Per-IP** (checked first) — prevents a single source from consuming the tenant's budget. Default: 5/hour anonymous, 60/hour identity_assertion.
+2. **Per-tenant** (checked second) — global cap across IPs. Default: 100/hour anonymous, 1000/hour identity_assertion.
+
+Also rate-limit `/oauth2/token` polling — enforce `interval` from the claim block, reject with `slow_down` if too fast.
+
+---
+
+## Recommended Audit Events
+
+| Event | When | Data |
+|-------|------|------|
+| `registration.created` | Successful POST /agent/identity | registration_id, registration_type, iss, sub |
+| `registration.interaction_required` | 401 interaction_required | registration_id, iss, sub, matched_user_id |
+| `registration.login_required` | 401 login_required | iss, sub, auth_time, max_age |
+| `claim.initiated` | /agent/identity/claim called | registration_id, email |
+| `claim.completed` | User submitted correct user_code | registration_id, claimed_by_user_id |
+| `claim.expired` | user_code window or registration expired | registration_id |
+| `token.exchanged` | /oauth2/token jwt-bearer success | registration_id, access_token_id |
+| `token.revoked` | /oauth2/revoke called | access_token_id |
+| `registration.revoked` | SET processed at events_endpoint | registration_id, iss, sub |
+
+---
+
+## Security Considerations
+
+- **auth_time validation** — `auth_time` is required in ID-JAGs. Service validates against `idJagMaxAuthAgeSeconds`. If too old, returns `login_required` (401) — agent must get user to re-authenticate at provider.
+- **claim_token handling** — returned exactly once in the registration response. Agent holds in memory only for ceremony duration. Do not persist past Step 4.
+- **Token hashing** — `claim_token` is a bearer secret. Store only SHA-256 hash server-side.
+- **Consent UX** — surface `resource_name` and `resource_logo_uri` from PRM to the user before asserting identity. This is the user's only consent gate.
+- **Two revocation layers** — credential layer (agent-callable, `/oauth2/revoke`, kills one access_token) vs registration layer (provider-driven SETs at `events_endpoint`, kills identity_assertion + all derived tokens).
+- **Replay protection** — cache `jti` values with TTL of at least `exp - iat` + clock skew (typically 6 min).
+- **CIMD resolution** — if `client_id` is a URL, fetch as Client ID Metadata Document and verify `jwks_uri`.
+- **Bulk revocation** — provide operator-facing mechanism to revoke all outstanding identity_assertions for a tenant.
+
+---
+
+## Error Codes Reference
+
+| Code | Where | Meaning |
+|------|-------|---------|
+| `anonymous_not_enabled` | `/agent/identity` | Service doesn't accept anonymous |
+| `service_auth_not_enabled` | `/agent/identity` | service_auth disabled |
+| `issuer_not_enabled` | `/agent/identity` | Provider not on trust list |
+| `invalid_request` | `/agent/identity` | Body/claim/signature/jti/aud problems |
+| `interaction_required` (401) | `/agent/identity` | ID-JAG matched account, no delegation — claim needed |
+| `login_required` (401) | `/agent/identity` | auth_time too old — re-authenticate at provider |
+| `invalid_claim_token` | `/agent/identity/claim` | Token wrong or expired |
+| `claimed_or_in_flight` | `/agent/identity/claim` | Already claimed or wrong endpoint |
+| `claim_expired` | `/agent/identity/claim` | Registration expired |
+| `invalid_grant` | `/oauth2/token` | Assertion expired/revoked |
+| `invalid_client` | `/oauth2/token` | client_id not recognized |
+| `unsupported_grant_type` | `/oauth2/token` | Not jwt-bearer or claim grant |
+| `authorization_pending` | `/oauth2/token` (claim) | User hasn't completed ceremony |
+| `expired_token` | `/oauth2/token` (claim) | user_code window closed |
+| `slow_down` | `/oauth2/token` (claim) | Polling too fast |
+| `rate_limited` (429) | any | Back off and retry |
+
+---
+
+## Agent Readiness Scanner Check
+
+The [isitagentready.com](https://isitagentready.com) scanner validates auth.md as the `authMd` check. Pass criteria:
+
+1. `/auth.md` served from site root with HTTP 200
+2. Content is Markdown with H1 heading containing "auth.md"
+3. Optionally validates OAuth Protected Resource Metadata at `/.well-known/oauth-protected-resource`
+4. Optionally validates Authorization Server metadata at `/.well-known/oauth-authorization-server`
+
+**To pass the check minimally:**
+```markdown
+# auth.md
+
+This service accepts AI agent registrations.
+
+## Authentication
+
+Agents can register via POST /agent/identity with a valid ID-JAG.
+See below for supported methods.
+```
+
+**To pass with full marks (all metadata):**
+- Serve `/auth.md` with proper heading
+- Publish `/.well-known/oauth-protected-resource` with `resource`, `resource_name`, `resource_logo_uri`, `authorization_servers`, `scopes_supported`, `bearer_methods_supported: ["header"]`
+- Publish `/.well-known/oauth-authorization-server` with `issuer`, `token_endpoint`, `revocation_endpoint`, `grant_types_supported`, and `agent_auth` block containing `skill`, `identity_endpoint`, `claim_endpoint`, `events_endpoint`, and registration methods
+
+**Scan command:**
+```bash
+curl -s -X POST 'https://isitagentready.com/api/scan' \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://YOUR-DOMAIN/","enabledChecks":["authMd"]}' | jq '.checks.discovery.authMd'
+```
+
+---
+
+## Quality Checklist
+
+Before delivering output, verify:
+
+- [ ] Generated `auth.md` contains all required steps (1-6) + Errors + Revocation
+- [ ] AS metadata includes `issuer`, `token_endpoint`, `revocation_endpoint`, `grant_types_supported`
+- [ ] `agent_auth` block includes `identity_endpoint`, `claim_endpoint`, `events_endpoint`
+- [ ] `identity_types_supported` matches the flows the user chose
+- [ ] `scopes_supported` reflects actual API scopes found in codebase
+- [ ] Base URLs are consistent between auth.md and metadata JSON
+- [ ] Error codes table includes all standard codes for the supported flows
+- [ ] Step 5 documents token exchange at `/oauth2/token` with jwt-bearer grant
+- [ ] Revocation section documents both layers (credential + registration)
+- [ ] No unreplaced placeholder values (`{{...}}`, `<your-...>`, `[YOUR_...]`)
+- [ ] Validation report covers all rules for the requested level
+- [ ] Rate limiting documented (including /oauth2/token polling)
+- [ ] Security considerations included (auth_time, claim_token, consent UX)
+- [ ] If role=provider: ID-JAG structure with `auth_time` documented
+
+---
+
+## References
+
+- `references/protocol-template.md` — Complete auth.md template with all sections and placeholders
+- `references/validation-rules.md` — Full validation ruleset with error messages and severities
+- `references/metadata-schema.md` — JSON schema for PRM, AS metadata, ID-JAG, and identity_assertion
+- `references/example-auth-md.md` — Working example of a complete auth.md file (Acme Notes)
+- `references/implementation-guide.md` — Server-side implementation guide with token exchange, claim ceremony, revocation, and security
+
+---
+
+## Updating Protocol Knowledge
+
+This skill ships with a snapshot of the auth.md protocol specification (v2, June 2026). When possible, fetch the latest version from:
+
+- Skill Home and Doc Hub: `https://auth-md.com`
+- Spec: `https://raw.githubusercontent.com/workos/auth.md/refs/heads/main/AUTH.md`
+- Docs overview: `https://workos.com/auth-md/docs`
+- Apps guide: `https://workos.com/auth-md/docs/apps`
+- Agent providers guide: `https://workos.com/auth-md/docs/agent-providers`
+- File anatomy: `https://workos.com/auth-md/docs/auth-md`
+
+If fetch fails, use the bundled `references/` as the source of truth.
--- a/.github/skills/auth-md/references/example-auth-md.md
+++ b/.github/skills/auth-md/references/example-auth-md.md
@@ -0,0 +1,403 @@
+# Complete Example: auth.md
+
+A working example of an `auth.md` file for the fictional "Acme Notes" service, updated to protocol v2 (June 2026).
+
+---
+
+## Example Context
+
+- **Service:** Acme Notes (collaborative notes app)
+- **Resource Server:** `https://api.acmenotes.com`
+- **Auth Server:** `https://auth.acmenotes.com`
+- **Supported flows:** identity_assertion (ID-JAG), service_auth, anonymous
+- **Scopes:** `notes.read`, `notes.write`, `notes.admin`
+
+---
+
+## The File
+
+```markdown
+# auth.md
+
+You are an agent. This service supports **agentic registration**: discover → register → (claim if needed) → exchange for an access_token → call API → handle revocation. Follow the steps in order; do not skip ahead.
+
+The resource server is `https://api.acmenotes.com` and the authorization server is `https://auth.acmenotes.com`.
+
+## Step 1 — Discover
+
+Discovery is two hops. The 401 response that pointed you here carries a `WWW-Authenticate` header with the PRM URL:
+
+\```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://api.acmenotes.com/.well-known/oauth-protected-resource"
+\```
+
+### 1a. Fetch the Protected Resource Metadata
+
+\```http
+GET /.well-known/oauth-protected-resource
+\```
+
+Response:
+
+\```json
+{
+  "resource": "https://api.acmenotes.com/",
+  "resource_name": "Acme Notes",
+  "resource_logo_uri": "https://acmenotes.com/logo.png",
+  "authorization_servers": ["https://auth.acmenotes.com/"],
+  "scopes_supported": ["notes.read", "notes.write", "notes.admin"],
+  "bearer_methods_supported": ["header"]
+}
+\```
+
+### 1b. Fetch the Authorization Server metadata
+
+\```http
+GET /.well-known/oauth-authorization-server
+\```
+
+Response:
+
+\```json
+{
+  "resource": "https://api.acmenotes.com/",
+  "authorization_servers": ["https://auth.acmenotes.com/"],
+  "scopes_supported": ["notes.read", "notes.write", "notes.admin"],
+  "bearer_methods_supported": ["header"],
+  "issuer": "https://auth.acmenotes.com",
+  "token_endpoint": "https://auth.acmenotes.com/oauth2/token",
+  "revocation_endpoint": "https://auth.acmenotes.com/oauth2/revoke",
+  "grant_types_supported": [
+    "urn:ietf:params:oauth:grant-type:jwt-bearer",
+    "urn:workos:agent-auth:grant-type:claim"
+  ],
+  "agent_auth": {
+    "skill": "https://acmenotes.com/auth.md",
+    "identity_endpoint": "https://auth.acmenotes.com/agent/identity",
+    "claim_endpoint": "https://auth.acmenotes.com/agent/identity/claim",
+    "events_endpoint": "https://auth.acmenotes.com/agent/event/notify",
+    "identity_types_supported": ["anonymous", "identity_assertion", "service_auth"],
+    "identity_assertion": {
+      "assertion_types_supported": [
+        "urn:ietf:params:oauth:token-type:id-jag"
+      ]
+    },
+    "events_supported": [
+      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
+    ]
+  }
+}
+\```
+
+## Step 2 — Pick a method
+
+1. **You have a session tied to a user identity and can exchange it for an ID-JAG** → identity_assertion + id-jag.
+2. **You have only the user's email** → service_auth. Claim ceremony required.
+3. **You have neither** → anonymous. Claim ceremony optional.
+
+Cross-check against the `agent_auth` block before proceeding.
+
+## Step 3 — Register
+
+Before sending an `identity_assertion` or `service_auth` body, surface "Acme Notes" and its logo to the user and confirm consent. Skip for `anonymous`.
+
+### identity_assertion + id-jag
+
+Mint the ID-JAG with:
+- `aud` = `https://api.acmenotes.com/` (from PRM `resource`)
+- `auth_time` = epoch seconds of user's last authentication at your provider (**required**)
+
+\```http
+POST /agent/identity
+Host: auth.acmenotes.com
+Content-Type: application/json
+
+{
+  "type": "identity_assertion",
+  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
+  "assertion": "<ID-JAG>"
+}
+\```
+
+Response — no confirmation needed (200):
+
+\```json
+{
+  "registration_id": "reg_01ABC123DEF456",
+  "registration_type": "identity_assertion",
+  "identity_assertion": "eyJhbGciOiJFUzI1NiJ9...",
+  "assertion_expires": "2026-05-22T14:00:00.000Z",
+  "scopes": ["notes.read", "notes.write"]
+}
+\```
+
+Keep `identity_assertion` and go to Step 5.
+
+Response — confirmation required (401, `interaction_required`):
+
+\```json
+{
+  "error": "interaction_required",
+  "error_description": "ID-JAG email matches an existing account but no delegation on file for (iss, sub).",
+  "registration_id": "reg_01ABC123DEF456",
+  "registration_type": "identity_assertion",
+  "claim_url": "https://auth.acmenotes.com/agent/identity/claim",
+  "claim_token": "clm_xYz789AbC012dEf",
+  "claim_token_expires": "2026-05-22T13:30:00.000Z",
+  "post_claim_scopes": ["notes.read", "notes.write"],
+  "claim": {
+    "user_code": "847291",
+    "expires_in": 600,
+    "verification_uri": "https://auth.acmenotes.com/login?return_to=%2Fclaim%3Fclaim_attempt_token%3Dcat_abc123",
+    "interval": 5
+  }
+}
+\```
+
+Surface `verification_uri` + `user_code` to the user (Step 4b) and poll (Step 4c).
+
+Response — login required (401, `login_required`):
+
+\```json
+{
+  "error": "login_required",
+  "error_description": "auth_time is 7200s old; max allowed is 3600s. Re-authenticate at the provider.",
+  "max_age": 3600
+}
+\```
+
+Re-authenticate the user at your provider and mint a fresh ID-JAG.
+
+### service_auth
+
+\```http
+POST /agent/identity
+Host: auth.acmenotes.com
+Content-Type: application/json
+
+{
+  "type": "service_auth",
+  "login_hint": "jane@example.com"
+}
+\```
+
+Response (200):
+
+\```json
+{
+  "registration_id": "reg_01DEF789GHI012",
+  "registration_type": "service_auth",
+  "claim_url": "https://auth.acmenotes.com/agent/identity/claim",
+  "claim_token": "clm_aBc123DeF456gHi",
+  "claim_token_expires": "2026-05-22T13:30:00.000Z",
+  "post_claim_scopes": ["notes.read", "notes.write"],
+  "claim": {
+    "user_code": "592841",
+    "expires_in": 600,
+    "verification_uri": "https://auth.acmenotes.com/login?return_to=%2Fclaim%3Fclaim_attempt_token%3Dcat_def456",
+    "interval": 5
+  }
+}
+\```
+
+No `identity_assertion` yet. Go to Step 4.
+
+### anonymous
+
+\```http
+POST /agent/identity
+Host: auth.acmenotes.com
+Content-Type: application/json
+
+{
+  "type": "anonymous"
+}
+\```
+
+Response (200):
+
+\```json
+{
+  "registration_id": "reg_01GHI345JKL678",
+  "registration_type": "anonymous",
+  "identity_assertion": "eyJhbGciOiJFUzI1NiJ9...",
+  "assertion_expires": "2026-05-22T14:00:00.000Z",
+  "pre_claim_scopes": ["notes.read"],
+  "claim_url": "https://auth.acmenotes.com/agent/identity/claim",
+  "claim_token": "clm_mNo345PqR678sTu",
+  "claim_token_expires": "2026-05-22T13:30:00.000Z",
+  "post_claim_scopes": ["notes.read", "notes.write"]
+}
+\```
+
+Exchange `identity_assertion` at `/oauth2/token` for an access_token with `pre_claim_scopes` (Step 5). To upgrade scopes, go to Step 4.
+
+## Step 4 — Claim ceremony
+
+### 4a. Get the ceremony materials
+
+For **service_auth** and **interaction_required** responses, you already have the `claim` block. Skip to 4b.
+
+For **anonymous**, initiate:
+
+\```http
+POST /agent/identity/claim
+Host: auth.acmenotes.com
+Content-Type: application/json
+
+{
+  "claim_token": "clm_mNo345PqR678sTu",
+  "email": "jane@example.com"
+}
+\```
+
+Response (200):
+
+\```json
+{
+  "registration_id": "reg_01GHI345JKL678",
+  "claim_attempt_id": "cla_001",
+  "status": "initiated",
+  "expires_at": "2026-05-22T13:40:00.000Z",
+  "claim_attempt": {
+    "user_code": "374918",
+    "expires_in": 600,
+    "verification_uri": "https://auth.acmenotes.com/login?return_to=%2Fclaim%3Fclaim_attempt_token%3Dcat_ghi789",
+    "interval": 5
+  }
+}
+\```
+
+### 4b. Hand off to the user
+
+Surface to the user:
+
+> Open this link, sign in (or sign up), and enter this 6-digit code: **374918**
+> https://auth.acmenotes.com/login?return_to=%2Fclaim%3Fclaim_attempt_token%3Dcat_ghi789
+
+The user signs in to Acme Notes, sees a confirmation page, and types the code.
+
+### 4c. Poll for completion
+
+\```http
+POST /oauth2/token
+Host: auth.acmenotes.com
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=clm_mNo345PqR678sTu
+\```
+
+Response while waiting:
+
+\```json
+{
+  "error": "authorization_pending",
+  "error_description": "User has not completed the claim ceremony yet."
+}
+\```
+
+Response on success:
+
+\```json
+{
+  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "scope": "notes.read notes.write",
+  "identity_assertion": "eyJhbGciOiJFUzI1NiJ9...",
+  "assertion_expires": "2026-05-22T15:00:00.000Z"
+}
+\```
+
+Use `access_token` immediately. Cache `identity_assertion` for refresh via Step 5.
+
+If `user_code` window expires:
+
+\```json
+{
+  "error": "expired_token",
+  "error_description": "The user_code window has closed."
+}
+\```
+
+Re-call `POST /agent/identity/claim` with same `claim_token` and `email` for a fresh code. If that returns `claim_expired`, restart at Step 3.
+
+## Step 5 — Exchange the assertion
+
+\```http
+POST /oauth2/token
+Host: auth.acmenotes.com
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=eyJhbGciOiJFUzI1NiJ9...&resource=https://api.acmenotes.com/
+\```
+
+Response (200):
+
+\```json
+{
+  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "scope": "notes.read notes.write"
+}
+\```
+
+Same `identity_assertion` can be re-used until it expires. If `invalid_grant`, restart at Step 3.
+
+## Step 6 — Use the access_token
+
+\```http
+GET /api/notes
+Host: api.acmenotes.com
+Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
+\```
+
+**Refresh:** When access_token expires, re-call Step 5 with same identity_assertion. When identity_assertion expires or Step 5 returns `invalid_grant`, restart at Step 3.
+
+On 401 for a previously-working access_token: try Step 5 once. If that also fails, restart at Step 1.
+
+Full API docs: https://docs.acmenotes.com/
+
+## Errors
+
+| Code | Where | What to do |
+|------|-------|------------|
+| `anonymous_not_enabled` | `/agent/identity` | Pick another method from Step 2 |
+| `service_auth_not_enabled` | `/agent/identity` | Pick another method |
+| `issuer_not_enabled` | `/agent/identity` | Provider not on trust list. Pick another method |
+| `invalid_request` | `/agent/identity` | Fix body shape, ID-JAG signature/jti/aud problems |
+| `interaction_required` (401) | `/agent/identity` (ID-JAG) | Body carries `claim` block; surface to user (Step 4) |
+| `login_required` (401) | `/agent/identity` (ID-JAG) | Re-authenticate user at provider, mint fresh ID-JAG |
+| `invalid_claim_token` | `/agent/identity/claim` | Restart at Step 3 |
+| `claimed_or_in_flight` | `/agent/identity/claim` | Already claimed |
+| `claim_expired` | `/agent/identity/claim` | Restart at Step 3 |
+| `invalid_grant` | `/oauth2/token` | Assertion expired/revoked. Restart at Step 3 |
+| `unsupported_grant_type` | `/oauth2/token` | Use one of the two supported grants |
+| `authorization_pending` | `/oauth2/token` (claim) | User hasn't finished. Honor `interval` |
+| `expired_token` | `/oauth2/token` (claim) | user_code window closed. Re-initiate or restart |
+| `slow_down` | `/oauth2/token` (claim) | Add ≥5s to interval |
+| `rate_limited` (429) | any | Back off and retry |
+
+## Revocation
+
+Two independent layers:
+
+- **Credential layer (RFC 7009):** POST `token=<access_token>&token_type_hint=access_token` to `https://auth.acmenotes.com/oauth2/revoke`. Kills one access_token. Identity assertion intact — re-run Step 5.
+- **Registration layer (RFC 8935):** Provider POSTs a Security Event Token to `events_endpoint`. Invalidates identity_assertion and all derived access_tokens. Agent discovers via `invalid_grant` at `/oauth2/token` — restart at Step 3.
+
+On 401 for a previously-working access_token: try Step 5 once. If `/oauth2/token` succeeds, credential-layer revocation. If `invalid_grant`, registration-layer — restart at Step 3.
+```
+
+---
+
+## Notes on This Example
+
+1. **All three flows** documented — in production, delete sections for unsupported flows
+2. **Token exchange step** (Step 5) — registration never returns access_token directly; always returns identity_assertion
+3. **Browser-based claim ceremony** — user_code + verification_uri replaces OTP-via-email
+4. **`interaction_required` response** — shows the 401 path when ID-JAG email matches existing account without delegation
+5. **`login_required` response** — shows `auth_time` freshness enforcement
+6. **Two revocation layers** — credential (agent-callable) vs registration (provider-driven)
+7. **Claim polling at `/oauth2/token`** — uses profile-specific grant URN to avoid collision with standard RFC 8628
--- a/.github/skills/auth-md/references/implementation-guide.md
+++ b/.github/skills/auth-md/references/implementation-guide.md
@@ -0,0 +1,433 @@
+# Server-Side Implementation Guide
+
+Detailed guidance for implementing auth.md protocol endpoints on the backend (v2, June 2026). Covers discovery, registration, claim ceremony, token exchange, revocation, security, rate limiting, and audit events.
+
+---
+
+## Table of Contents
+
+1. [Minimum Implementation](#minimum-implementation)
+2. [Discovery Documents](#discovery-documents)
+3. [POST /agent/identity — Registration Handler](#post-agentidentity--registration-handler)
+4. [ID-JAG Verification](#id-jag-verification)
+5. [Claim Ceremony](#claim-ceremony)
+6. [POST /oauth2/token — Token Endpoint](#post-oauth2token--token-endpoint)
+7. [Revocation](#revocation)
+8. [User Matching and JIT Provisioning](#user-matching-and-jit-provisioning)
+9. [Rate Limiting](#rate-limiting)
+10. [Security](#security)
+11. [Audit Events](#audit-events)
+12. [Deploy Checklist](#deploy-checklist)
+
+---
+
+## Minimum Implementation
+
+1. Publish `/.well-known/oauth-protected-resource` with `resource_name` and `resource_logo_uri`
+2. Publish `/.well-known/oauth-authorization-server` with `issuer`, `token_endpoint`, `revocation_endpoint`, `grant_types_supported`, and `agent_auth` block
+3. Return `WWW-Authenticate: Bearer resource_metadata="..."` on 401 responses
+4. Host `POST /agent/identity` that dispatches on the `type` field
+5. For identity_assertion: maintain a trust list and verify ID-JAG signatures via JWKS, validate `auth_time`
+6. For service_auth: return `claim` block with `user_code` + `verification_uri`
+7. For anonymous: issue `identity_assertion` immediately with pre-claim scopes
+8. Host `POST /agent/identity/claim` for deferred claim initiation
+9. Implement `POST /oauth2/token` handling both grant types (jwt-bearer exchange + claim polling)
+10. Implement `POST /oauth2/revoke` for credential-layer revocation (RFC 7009)
+11. Accept SETs at `events_endpoint` for registration-layer revocation (RFC 8935)
+12. Record audit events for every state change
+
+---
+
+## Discovery Documents
+
+### Serving the PRM
+
+```
+GET /.well-known/oauth-protected-resource
+→ 200 OK
+→ Content-Type: application/json
+```
+
+Must include `resource_name` and `resource_logo_uri` — agents surface these to the user for consent before asserting identity.
+
+Cache aggressively: `Cache-Control: public, max-age=3600`.
+
+### Serving the AS Metadata
+
+```
+GET /.well-known/oauth-authorization-server
+→ 200 OK
+→ Content-Type: application/json
+```
+
+Must include standard OAuth fields (`issuer`, `token_endpoint`, `revocation_endpoint`, `grant_types_supported`) plus the `agent_auth` block with `identity_endpoint`, `claim_endpoint`, `events_endpoint`.
+
+### WWW-Authenticate Header
+
+On every 401 response from the API:
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://api.service.com/.well-known/oauth-protected-resource"
+```
+
+---
+
+## POST /agent/identity — Registration Handler
+
+All registration requests share the same endpoint and dispatch on the `type` field:
+
+```
+POST /agent/identity
+Content-Type: application/json
+```
+
+### Dispatch
+
+| `type` | Flow | Returns |
+|--------|------|---------|
+| `identity_assertion` | ID-JAG verified | `identity_assertion` (service-signed JWT) |
+| `service_auth` | Email hint + browser ceremony | `claim` block (ceremony materials) |
+| `anonymous` | No identity | `identity_assertion` + `claim_token` for deferred claim |
+
+### Handler: identity_assertion + id-jag
+
+1. Decode the ID-JAG header to obtain `kid` and `alg`
+2. Look up the issuer (`iss`) in the trust list. Reject if unknown → `issuer_not_enabled`
+3. Fetch JWKS from the provider (see ID-JAG Verification section for caching)
+4. Verify signature → `invalid_request` if fails
+5. Validate claims:
+   - `aud` matches the `resource` from PRM → `invalid_request`
+   - `exp` is in the future → `invalid_request`
+   - `iat` not unreasonably in the future (~1-2 min skew)
+   - `jti` not seen recently → `invalid_request` (replay)
+   - `auth_time` present and within `idJagMaxAuthAgeSeconds` → `login_required` (401) if too old
+   - At least `email_verified` or `phone_number_verified` is `true` → `invalid_request`
+6. Match or provision the user (see User Matching)
+7. Check delegation: if `(iss, sub)` is known OR JIT-provisioned without collision → success
+8. If email/phone collision with existing account but no delegation on file → `interaction_required` (401) with `claim` block
+9. On success: sign an `identity_assertion` JWT and return it
+
+### Handler: service_auth
+
+1. Validate `login_hint` (email format)
+2. Create a registration row with type `service_auth`
+3. Generate `claim_token` (returned to agent once), `user_code` (6-digit), `claim_attempt_token` (embedded in verification_uri)
+4. Store SHA-256 hashes of `claim_token`
+5. Build `verification_uri` pointing to the service's login page with `return_to` parameter
+6. Return the registration response with `claim` block containing `user_code`, `verification_uri`, `expires_in`, `interval`
+
+### Handler: anonymous
+
+1. Apply rate limits
+2. Create a registration row
+3. Sign an `identity_assertion` JWT with pre-claim scopes
+4. Generate `claim_token` for deferred claim. Store only SHA-256 hash.
+5. Return `identity_assertion` + `claim_token` + pre/post claim scopes
+
+---
+
+## ID-JAG Verification
+
+### Trust List
+
+Maintain a registry of providers. Minimum entry: issuer URL. Richer entries can pin JWKS URI, CIMD URL, or attestation policy.
+
+### JWKS Fetching
+
+- Fetch `{iss}/.well-known/jwks.json` on first use
+- Cache per `Cache-Control`, with floor 10 min, ceiling 24h
+- On `kid` miss, refetch once before rejecting
+
+### CIMD Resolution
+
+If `client_id` is a URL:
+1. Fetch as OAuth Client ID Metadata Document
+2. Verify `jwks_uri` matches the one used to verify signature
+
+### auth_time Validation
+
+- `auth_time` is **required** in ID-JAGs
+- Compare `now() - auth_time` against `idJagMaxAuthAgeSeconds` (service-configured, e.g., 3600)
+- If too old: return `login_required` (401) with `max_age` in the response
+- Agent must re-authenticate user at provider and mint fresh ID-JAG
+
+### Replay Protection
+
+- Cache `jti` values with TTL of at least `exp - iat` + clock skew (typically 6 min)
+- Reject on collision with `invalid_request`
+
+---
+
+## Claim Ceremony
+
+The v2 claim ceremony is browser-based, borrowing from RFC 8628 device authorization.
+
+### POST /agent/identity/claim (anonymous deferred claim)
+
+1. Hash `claim_token`, look up registration
+2. Reject if not found → `invalid_claim_token`, already claimed → `claimed_or_in_flight`, expired → `claim_expired`
+3. Generate `user_code` (6-digit), `claim_attempt_token`
+4. Build `verification_uri` with embedded `claim_attempt_token`
+5. Return `claim_attempt` block with `user_code`, `verification_uri`, `expires_in`, `interval`
+
+### Service-Hosted Claim Page
+
+When the user opens `verification_uri`:
+1. Redirect to login if not authenticated
+2. After login, show claim page displaying:
+   - The user's identity ("You're signed in as jane@example.com")
+   - The requesting agent/provider info (from PRM `resource_name`)
+   - Input field for the 6-digit code
+3. On correct code submission: mark claim as complete, associate registration with user
+4. Incorrect code: show error, allow retry (up to limit)
+
+### Claim Completion Flow
+
+When the user submits the correct `user_code` on the claim page:
+1. Mark the claim as complete in the database
+2. For anonymous: sign a new `identity_assertion` (v2) carrying user claims, superseding the pre-claim one
+3. For service_auth: sign the first `identity_assertion` for this registration
+4. The next poll at `/oauth2/token` with the claim grant returns the access_token + identity_assertion
+
+---
+
+## POST /oauth2/token — Token Endpoint
+
+Handles two grant types at the same endpoint:
+
+### Grant: urn:ietf:params:oauth:grant-type:jwt-bearer (Token Exchange)
+
+```
+POST /oauth2/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
+&assertion=<identity_assertion>
+&resource=<resource_url>  (optional but recommended)
+```
+
+Processing:
+1. Verify the `identity_assertion` JWT signature (service's own key)
+2. Validate `exp` not passed → `invalid_grant` if expired
+3. Check assertion not revoked → `invalid_grant` if revoked
+4. Mint a fresh `access_token` scoped to the assertion's scopes
+5. Return standard OAuth token response
+
+### Grant: urn:workos:agent-auth:grant-type:claim (Claim Polling)
+
+```
+POST /oauth2/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:workos:agent-auth:grant-type:claim
+&claim_token=<claim_token>
+```
+
+Processing:
+1. Hash `claim_token`, look up registration
+2. If claim not yet completed → return `authorization_pending`
+3. If user_code window expired → return `expired_token`
+4. If polling too fast → return `slow_down`
+5. If claim completed → mint access_token + return along with new `identity_assertion`
+
+Why a profile-specific grant URN? So this doesn't collide with services that also implement standard RFC 8628 device authorization at the same token endpoint.
+
+### Error Responses
+
+| Error | HTTP | Condition |
+|-------|------|-----------|
+| `invalid_grant` | 400 | Assertion expired, revoked, or invalid |
+| `invalid_client` | 401 | client_id not recognized |
+| `unsupported_grant_type` | 400 | Not one of the two supported grants |
+| `authorization_pending` | 400 | Claim polling — user hasn't finished |
+| `expired_token` | 400 | user_code window closed |
+| `slow_down` | 400 | Polling too fast — add ≥5s |
+
+---
+
+## Revocation
+
+### Credential Layer — POST /oauth2/revoke (RFC 7009)
+
+Agent-callable. Kills one access_token.
+
+```
+POST /oauth2/revoke
+Content-Type: application/x-www-form-urlencoded
+
+token=<access_token>&token_type_hint=access_token
+```
+
+- Return 200 on success (idempotent)
+- The underlying `identity_assertion` remains valid — agent can re-exchange for a new access_token
+
+### Registration Layer — Events Endpoint (RFC 8935)
+
+Provider-driven. Receives Security Event Tokens.
+
+```
+POST /agent/event/notify
+Content-Type: application/secevent+jwt
+
+<SET JWT>
+```
+
+Processing:
+1. Verify SET signature against issuer's JWKS
+2. Enforce `jti` uniqueness
+3. Match `events` key to supported schemas
+4. For `https://schemas.workos.com/events/agent/auth/identity/assertion/revoked`:
+   - Invalidate all identity_assertions for `(iss, sub, aud)`
+   - Invalidate all derived access_tokens
+5. Return 200 on success, 400 on verification failure
+
+### Bulk Revocation
+
+Provide an operator-facing mechanism to revoke all outstanding identity_assertions and access_tokens for a tenant in one shot — for incident response.
+
+---
+
+## User Matching and JIT Provisioning
+
+Resolution order:
+
+1. **Delegation record match** — if `(iss, sub)` has a delegation on file, route to that user. Strongest identifier.
+2. **Verified email match** — if a user exists with same verified email:
+   - If delegation exists for `(iss, sub)` → direct match (already covered above)
+   - If NO delegation for `(iss, sub)` → `interaction_required` (401). User must confirm linking.
+3. **Verified phone match** — same pattern.
+4. **No match → JIT** — create a new user per provisioning policy, or refuse.
+
+Reject ID-JAGs with neither verified email nor verified phone.
+
+---
+
+## Rate Limiting
+
+### Two Tiers
+
+| Tier | Checked | Default Anonymous | Default identity_assertion |
+|------|---------|-------------------|---------------------------|
+| Per-IP | First | 5/hour | 60/hour |
+| Per-tenant | Second | 100/hour | 1000/hour |
+
+### Implementation
+
+- Sliding-window counter with shared store
+- Fail open on store errors
+- Return 429 with `Retry-After` header
+- Also rate-limit `/oauth2/token` polling (respect `interval` from claim block, reject with `slow_down`)
+
+---
+
+## Security
+
+### Token Hashing
+
+| Token | Storage | Plaintext leaves server |
+|-------|---------|------------------------|
+| `claim_token` | SHA-256 hash | Once, in the registration response |
+| `user_code` | Stored for comparison | Displayed on claim page when user submits |
+| `identity_assertion` | Full JWT stored (or just signature hash for lookup) | In registration response |
+
+### claim_token
+
+- Returned **exactly once** to the agent in the registration response
+- Agent holds in memory for ceremony duration — must not persist past Step 4
+- High-entropy: prefix `clm_` + 25+ chars base62
+
+### auth_time Enforcement
+
+- Service configures `idJagMaxAuthAgeSeconds` (default: 3600)
+- Reject ID-JAGs where `now() - auth_time > idJagMaxAuthAgeSeconds`
+- Return `login_required` (401) with `max_age` field
+
+### Consent UX
+
+- Surface `resource_name` and `resource_logo_uri` from PRM to user before identity assertion
+- The claim page should display who is requesting access (provider name from CIMD or ID-JAG metadata)
+
+### user_code Security
+
+- 6-digit numeric code
+- 10-minute TTL (configurable via `expires_in`)
+- Tight retry limits (3-5 attempts) on the claim page
+- Code is tied to the `claim_attempt_token` embedded in `verification_uri`
+
+### Replay Protection
+
+- `jti` cache mandatory for ID-JAGs
+- `jti` uniqueness enforced for SETs at events_endpoint
+- Shared store required for multi-replica deployments
+
+### Trust List Discipline
+
+Treat the trusted-providers list as security-critical configuration. Changes should be audited.
+
+---
+
+## Audit Events
+
+### Recommended Events
+
+| Event | When | Minimum Data |
+|-------|------|--------------|
+| `registration.created` | Successful POST /agent/identity | registration_id, registration_type, iss, sub (if ID-JAG) |
+| `registration.interaction_required` | 401 interaction_required returned | registration_id, iss, sub, matched_user_id |
+| `registration.login_required` | 401 login_required returned | iss, sub, auth_time, max_age |
+| `claim.initiated` | /agent/identity/claim called | registration_id, email |
+| `claim.completed` | User submitted correct user_code | registration_id, claimed_by_user_id |
+| `claim.expired` | user_code window or registration expired | registration_id |
+| `token.exchanged` | /oauth2/token jwt-bearer success | registration_id, access_token_id |
+| `token.revoked` | /oauth2/revoke called | access_token_id |
+| `registration.revoked` | SET processed at events_endpoint | registration_id, iss, sub |
+| `registration.expired` | Unclaimed registration past TTL | registration_id |
+
+---
+
+## Deploy Checklist
+
+### Before publishing
+
+- [ ] PRM served at `/.well-known/oauth-protected-resource` with `resource_name` and `resource_logo_uri`
+- [ ] AS metadata served at `/.well-known/oauth-authorization-server` with `issuer`, `token_endpoint`, `revocation_endpoint`, `grant_types_supported`, and `agent_auth` block
+- [ ] `agent_auth` contains `identity_endpoint`, `claim_endpoint`, `events_endpoint`
+- [ ] `auth.md` served at the domain root
+- [ ] API returns `WWW-Authenticate` header on 401s
+- [ ] `POST /agent/identity` dispatches correctly by `type`
+- [ ] Trust list configured (if identity_assertion)
+- [ ] JWKS fetching with cache (if identity_assertion)
+- [ ] `auth_time` validation against `idJagMaxAuthAgeSeconds` (if identity_assertion)
+- [ ] `POST /agent/identity/claim` generates user_code + verification_uri (if service_auth/anonymous)
+- [ ] Claim page served at verification_uri (login → code input → confirm)
+- [ ] `POST /oauth2/token` handles jwt-bearer grant (assertion → access_token)
+- [ ] `POST /oauth2/token` handles claim grant (polling → access_token + identity_assertion)
+- [ ] `POST /oauth2/revoke` kills access_tokens (RFC 7009)
+- [ ] Events endpoint accepts SETs for registration revocation
+- [ ] Rate limiting active on `/agent/identity` and `/oauth2/token`
+- [ ] claim_token stored as SHA-256 hash
+- [ ] Replay protection for `jti` implemented
+- [ ] Audit events being recorded
+
+### Recommended tests
+
+- [ ] identity_assertion: valid ID-JAG with fresh auth_time → identity_assertion returned
+- [ ] identity_assertion: expired ID-JAG → `invalid_request`
+- [ ] identity_assertion: auth_time too old → `login_required` (401)
+- [ ] identity_assertion: email collision without delegation → `interaction_required` (401) with claim block
+- [ ] identity_assertion: repeated `jti` → `invalid_request` (replay)
+- [ ] identity_assertion: unknown issuer → `issuer_not_enabled`
+- [ ] service_auth: valid email → registration with claim block (user_code + verification_uri)
+- [ ] anonymous: registration → identity_assertion with pre_claim_scopes
+- [ ] anonymous: claim initiation → claim_attempt with user_code
+- [ ] /oauth2/token jwt-bearer: valid assertion → access_token
+- [ ] /oauth2/token jwt-bearer: expired assertion → `invalid_grant`
+- [ ] /oauth2/token claim: before completion → `authorization_pending`
+- [ ] /oauth2/token claim: after completion → access_token + identity_assertion
+- [ ] /oauth2/token claim: after window expires → `expired_token`
+- [ ] /oauth2/token claim: too-fast polling → `slow_down`
+- [ ] /oauth2/revoke: valid access_token → 200
+- [ ] events_endpoint: valid SET → registrations revoked
+- [ ] Rate limit exceeded → 429
+- [ ] 401 on API → WWW-Authenticate header present
--- a/.github/skills/auth-md/references/metadata-schema.md
+++ b/.github/skills/auth-md/references/metadata-schema.md
@@ -0,0 +1,370 @@
+# Metadata Schema
+
+JSON structure reference for the discovery documents and tokens required by the auth.md protocol (v2, June 2026).
+
+---
+
+## Protected Resource Metadata (PRM)
+
+Served at: `{resource_server}/.well-known/oauth-protected-resource`
+
+Defined by [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728).
+
+```json
+{
+  "resource": "https://api.example.com/",
+  "resource_name": "Example Service",
+  "resource_logo_uri": "https://example.com/logo.png",
+  "authorization_servers": ["https://auth.example.com/"],
+  "scopes_supported": ["read", "write", "admin"],
+  "bearer_methods_supported": ["header"]
+}
+```
+
+### Fields
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `resource` | ✅ | string (URL) | Canonical URL of the API. Used as `aud` in ID-JAGs. |
+| `resource_name` | ✅ | string | Display name for consent prompts. Surface to user before asserting identity. |
+| `resource_logo_uri` | Recommended | string (URL) | Logo for consent UI. Surface alongside `resource_name`. |
+| `authorization_servers` | ✅ | string[] | Base URLs of OAuth AS(s). Agent fetches AS metadata from here. |
+| `scopes_supported` | ✅ | string[] | All scopes the resource server understands. |
+| `bearer_methods_supported` | ✅ | string[] | How credentials are presented. Typically `["header"]`. |
+
+---
+
+## Authorization Server Metadata
+
+Served at: `{authorization_server}/.well-known/oauth-authorization-server`
+
+Combines standard [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) fields with the `agent_auth` profile block.
+
+```json
+{
+  "resource": "https://api.example.com/",
+  "authorization_servers": ["https://auth.example.com/"],
+  "scopes_supported": ["read", "write", "admin"],
+  "bearer_methods_supported": ["header"],
+  "issuer": "https://auth.example.com",
+  "token_endpoint": "https://auth.example.com/oauth2/token",
+  "revocation_endpoint": "https://auth.example.com/oauth2/revoke",
+  "grant_types_supported": [
+    "urn:ietf:params:oauth:grant-type:jwt-bearer",
+    "urn:workos:agent-auth:grant-type:claim"
+  ],
+  "agent_auth": {
+    "skill": "https://example.com/auth.md",
+    "identity_endpoint": "https://auth.example.com/agent/identity",
+    "claim_endpoint": "https://auth.example.com/agent/identity/claim",
+    "events_endpoint": "https://auth.example.com/agent/event/notify",
+    "identity_types_supported": ["anonymous", "identity_assertion", "service_auth"],
+    "identity_assertion": {
+      "assertion_types_supported": [
+        "urn:ietf:params:oauth:token-type:id-jag"
+      ]
+    },
+    "events_supported": [
+      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
+    ]
+  }
+}
+```
+
+### Top-Level OAuth Fields
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `issuer` | ✅ | string (URL) | Canonical issuer URL of this AS. Validate `iss` claim of any token the AS signs against this. |
+| `token_endpoint` | ✅ | string (URL) | Where agents exchange identity assertions for access_tokens (Step 5) and poll during claim ceremony (Step 4c). |
+| `revocation_endpoint` | ✅ | string (URL) | Where agents POST to revoke an access_token ([RFC 7009](https://datatracker.ietf.org/doc/html/rfc7009)). |
+| `grant_types_supported` | ✅ | string[] | Grant types accepted at `token_endpoint`. Must include `urn:ietf:params:oauth:grant-type:jwt-bearer` (token exchange) and `urn:workos:agent-auth:grant-type:claim` (claim polling). |
+
+### `agent_auth` Block Fields
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `skill` | Recommended | string (URL) | URL of the auth.md file. |
+| `identity_endpoint` | ✅ | string (URL) | POST endpoint for registration (Step 3). |
+| `claim_endpoint` | Conditional | string (URL) | POST endpoint for claim initiation. Required if `service_auth` or `anonymous` supported. |
+| `events_endpoint` | Recommended | string (URL) | Receives Security Event Tokens ([RFC 8417](https://datatracker.ietf.org/doc/html/rfc8417)) from providers for registration-layer revocation. |
+| `identity_types_supported` | ✅ | string[] | `"anonymous"`, `"identity_assertion"`, `"service_auth"`, or combination. |
+| `identity_assertion` | Conditional | object | Required if `"identity_assertion"` in identity_types_supported. |
+| `identity_assertion.assertion_types_supported` | ✅ (if identity_assertion) | string[] | `"urn:ietf:params:oauth:token-type:id-jag"`. |
+| `events_supported` | Recommended | string[] | Event schemas this service can ingest (currently revocation). Informational. |
+
+### identity_types → Flow Mapping
+
+| `identity_types_supported` | Flow | Ceremony |
+|---|---|---|
+| `identity_assertion` | ID-JAG verified by provider | None (unless `interaction_required`) |
+| `service_auth` | Email hint, browser-based ceremony | RFC 8628-style: user_code + verification_uri |
+| `anonymous` | No identity upfront | Optional deferred claim |
+
+---
+
+## ID-JAG Token (Identity Assertion JWT Authorization Grant)
+
+Defined by [draft-ietf-oauth-identity-assertion-authz-grant](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-identity-assertion-authz-grant).
+
+### Header
+
+```json
+{
+  "typ": "oauth-id-jag+jwt",
+  "alg": "ES256",
+  "kid": "<provider-key-id>"
+}
+```
+
+### Payload
+
+```json
+{
+  "iss": "https://api.agent-provider.com",
+  "sub": "<opaque-user-identifier>",
+  "aud": "https://api.example.com",
+  "client_id": "<issuer-url-or-cimd-url>",
+  "jti": "<unique-token-id>",
+  "iat": 1716400000,
+  "exp": 1716400300,
+  "auth_time": 1716399000,
+  "email": "user@example.com",
+  "email_verified": true,
+  "amr": ["mfa"],
+  "name": "Jane Smith",
+  "phone_number": "+15553805188",
+  "phone_number_verified": false,
+  "resource": "https://api.example.com",
+  "agent_platform": "cursor",
+  "agent_context_id": "chat-abc123"
+}
+```
+
+### Required Claims
+
+| Claim | Description |
+|-------|-------------|
+| `iss` | Provider's issuer URL (must be on service's trust list) |
+| `sub` | Opaque user identifier at the provider |
+| `aud` | Service's `resource` URL from the PRM |
+| `client_id` | Provider identity (issuer URL or CIMD URL) |
+| `jti` | Unique token ID for replay protection |
+| `iat` | Issuance time (epoch seconds) |
+| `exp` | Expiration (typically iat + 5 minutes) |
+| `auth_time` | Epoch seconds when the user last authenticated at the provider. **Required.** Service rejects ID-JAGs whose auth_time is older than its `idJagMaxAuthAgeSeconds` window. |
+| `email` + `email_verified: true` OR `phone_number` + `phone_number_verified: true` | At least one verified contact required |
+
+### Optional Claims
+
+| Claim | Description |
+|-------|-------------|
+| `amr` | Authentication methods reference (e.g., `["mfa"]`) |
+| `name` | User's display name |
+| `phone_number` | User's phone number |
+| `phone_number_verified` | Whether phone is verified |
+| `resource` | Resource server URL (informational) |
+| `agent_platform` | Agent platform (e.g., `"cursor"`, `"chatgpt"`) |
+| `agent_context_id` | Agent context/chat ID |
+
+---
+
+## Client ID Metadata Document (CIMD)
+
+Optional document that decouples provider identity from signing keys. Defined by [draft-ietf-oauth-client-id-metadata-document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/).
+
+Hosted at the URL used as `client_id` in the ID-JAG.
+
+```json
+{
+  "client_id": "https://api.agent-provider.com/agent-auth.json",
+  "client_name": "Agent Provider",
+  "logo_uri": "https://agent-provider.com/logo.png",
+  "client_uri": "https://agent-provider.com",
+  "tos_uri": "https://agent-provider.com/tos",
+  "policy_uri": "https://agent-provider.com/privacy",
+  "token_endpoint_auth_method": "private_key_jwt",
+  "jwks_uri": "https://agent-provider.com/.well-known/jwks.json",
+  "scope": "openid email profile"
+}
+```
+
+---
+
+## Identity Assertion JWT (Service-Signed)
+
+After successful registration, the service returns an `identity_assertion` — a JWT signed by the service that the agent exchanges at `/oauth2/token` for an access_token.
+
+The identity_assertion is:
+- Reusable until it expires (`assertion_expires`)
+- Exchanged via `POST /oauth2/token` with `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`
+- Replaced by a fresh one after claim ceremony completion (v2 carries user claims)
+
+---
+
+## Registration Response Shapes
+
+### identity_assertion + id-jag (no confirmation needed)
+
+```json
+{
+  "registration_id": "reg_...",
+  "registration_type": "identity_assertion",
+  "identity_assertion": "<service-signed-jwt>",
+  "assertion_expires": "2026-05-04T13:00:00.000Z",
+  "scopes": ["read", "write"]
+}
+```
+
+### identity_assertion + id-jag (interaction_required — 401)
+
+```json
+{
+  "error": "interaction_required",
+  "error_description": "...",
+  "registration_id": "reg_...",
+  "registration_type": "identity_assertion",
+  "claim_url": "https://auth.example.com/agent/identity/claim",
+  "claim_token": "clm_...",
+  "claim_token_expires": "...",
+  "post_claim_scopes": ["read", "write"],
+  "claim": {
+    "user_code": "123456",
+    "expires_in": 600,
+    "verification_uri": "https://auth.example.com/login?return_to=...",
+    "interval": 5
+  }
+}
+```
+
+### service_auth
+
+```json
+{
+  "registration_id": "reg_...",
+  "registration_type": "service_auth",
+  "claim_url": "https://auth.example.com/agent/identity/claim",
+  "claim_token": "clm_...",
+  "claim_token_expires": "2026-05-21T17:31:25.994Z",
+  "post_claim_scopes": ["read", "write"],
+  "claim": {
+    "user_code": "123456",
+    "expires_in": 600,
+    "verification_uri": "https://auth.example.com/login?return_to=...",
+    "interval": 5
+  }
+}
+```
+
+### anonymous
+
+```json
+{
+  "registration_id": "reg_...",
+  "registration_type": "anonymous",
+  "identity_assertion": "<service-signed-jwt>",
+  "assertion_expires": "2026-05-04T13:00:00.000Z",
+  "pre_claim_scopes": ["read"],
+  "claim_url": "https://auth.example.com/agent/identity/claim",
+  "claim_token": "clm_...",
+  "claim_token_expires": "2026-05-21T17:26:32.915Z",
+  "post_claim_scopes": ["read", "write"]
+}
+```
+
+### Claim Ceremony Initiation (anonymous → POST /agent/identity/claim)
+
+```json
+{
+  "registration_id": "reg_...",
+  "claim_attempt_id": "cla_...",
+  "status": "initiated",
+  "expires_at": "2026-05-21T17:31:25.994Z",
+  "claim_attempt": {
+    "user_code": "123456",
+    "expires_in": 600,
+    "verification_uri": "https://auth.example.com/login?return_to=...",
+    "interval": 5
+  }
+}
+```
+
+### Token Exchange Response (POST /oauth2/token — JWT-bearer grant)
+
+```json
+{
+  "access_token": "<token>",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "scope": "read write"
+}
+```
+
+### Claim Polling Success (POST /oauth2/token — claim grant)
+
+```json
+{
+  "access_token": "<token>",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "scope": "read write",
+  "identity_assertion": "<service-signed-jwt-v2>",
+  "assertion_expires": "2026-05-21T18:31:25.994Z"
+}
+```
+
+---
+
+## Error Response Shape
+
+```json
+{
+  "error": "<error_code>",
+  "error_description": "<human-readable description>"
+}
+```
+
+---
+
+## Revocation
+
+Two independent layers:
+
+### Credential Layer (RFC 7009) — Agent-Callable
+
+```http
+POST /oauth2/revoke
+Content-Type: application/x-www-form-urlencoded
+
+token=<access_token>&token_type_hint=access_token
+```
+
+Kills one access_token. 200 on success, idempotent. The `identity_assertion` remains intact — re-run Step 5 for a fresh access_token.
+
+### Registration Layer (RFC 8935 SET delivery) — Provider-Driven
+
+Provider POSTs a Security Event Token (`Content-Type: application/secevent+jwt`) to the service's `events_endpoint`. The service invalidates the identity_assertion and all derived access_tokens.
+
+Agent discovers this when `/oauth2/token` returns `invalid_grant` — restart at Step 3.
+
+### SET Payload
+
+```json
+{
+  "iss": "https://api.agent-provider.com",
+  "sub": "<opaque-user-identifier>",
+  "aud": "https://auth.example.com",
+  "jti": "<unique-identifier>",
+  "iat": 1716400000,
+  "events": {
+    "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked": {}
+  }
+}
+```
+
+### Processing
+
+1. Verify signature against the issuer's JWKS (same trust path as ID-JAG verification)
+2. Enforce `jti` uniqueness for replay protection
+3. Find all identity_assertions and access_tokens for `(iss, sub, aud)` and invalidate them
+4. Return 200 on success, 400 on verification failure
--- a/.github/skills/auth-md/references/protocol-template.md
+++ b/.github/skills/auth-md/references/protocol-template.md
@@ -0,0 +1,451 @@
+# Protocol Template
+
+Canonical template for generating an `auth.md` file (v2, June 2026). Replace all `{{placeholders}}` with service-specific values. Delete sections for flows the service does not support.
+
+---
+
+## File Structure
+
+An auth.md is organized as a numbered walkthrough the agent follows top to bottom:
+
+1. **Title and intro** — addressed to the agent, declares real hostnames (resource server + auth server)
+2. **Step 1 — Discover** — two-hop discovery (PRM → AS metadata)
+3. **Step 2 — Pick a method** — decision tree
+4. **Step 3 — Register** — one subsection per supported method
+5. **Step 4 — Claim ceremony** — browser-based user_code ceremony (if service_auth or anonymous claim)
+6. **Step 5 — Exchange the assertion** — POST identity_assertion to /oauth2/token for access_token
+7. **Step 6 — Use the access_token** — how to use and refresh
+8. **Errors** — error codes table
+9. **Revocation** — two-layer revocation model
+
+---
+
+## Complete Template
+
+```markdown
+# auth.md
+
+You are an agent. This service supports **agentic registration**: discover → register → (claim if needed) → exchange for an access_token → call API → handle revocation. Follow the steps in order; do not skip ahead.
+
+Examples use placeholder hosts: `{{base_url}}` (the resource server hosting the API you want to call) and `{{auth_server_url}}` (the authorization server that handles registration).
+
+## Step 1 — Discover
+
+Discovery is two hops. The 401 response that pointed you here carries a `WWW-Authenticate` header with the PRM URL:
+
+\```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="{{base_url}}/.well-known/oauth-protected-resource"
+\```
+
+### 1a. Fetch the Protected Resource Metadata
+
+\```http
+GET /.well-known/oauth-protected-resource
+\```
+
+Response:
+
+\```json
+{
+  "resource": "{{base_url}}/",
+  "resource_name": "{{service_name}}",
+  "resource_logo_uri": "{{logo_url}}",
+  "authorization_servers": ["{{auth_server_url}}/"],
+  "scopes_supported": [{{scopes_list}}],
+  "bearer_methods_supported": ["header"]
+}
+\```
+
+### 1b. Fetch the Authorization Server metadata
+
+\```http
+GET /.well-known/oauth-authorization-server
+\```
+
+Response:
+
+\```json
+{
+  "resource": "{{base_url}}/",
+  "authorization_servers": ["{{auth_server_url}}/"],
+  "scopes_supported": [{{scopes_list}}],
+  "bearer_methods_supported": ["header"],
+  "issuer": "{{auth_server_url}}",
+  "token_endpoint": "{{auth_server_url}}/oauth2/token",
+  "revocation_endpoint": "{{auth_server_url}}/oauth2/revoke",
+  "grant_types_supported": [
+    "urn:ietf:params:oauth:grant-type:jwt-bearer",
+    "urn:workos:agent-auth:grant-type:claim"
+  ],
+  "agent_auth": {
+    "skill": "{{auth_md_url}}",
+    "identity_endpoint": "{{auth_server_url}}/agent/identity",
+    "claim_endpoint": "{{auth_server_url}}/agent/identity/claim",
+    "events_endpoint": "{{auth_server_url}}/agent/event/notify",
+    "identity_types_supported": [{{identity_types}}],
+    "identity_assertion": {
+      "assertion_types_supported": [{{assertion_types}}]
+    },
+    "events_supported": [
+      "https://schemas.workos.com/events/agent/auth/identity/assertion/revoked"
+    ]
+  }
+}
+\```
+
+## Step 2 — Pick a method
+
+Use this decision tree:
+
+1. **You have a session tied to a user identity and can exchange it for an ID-JAG, audience-bound to this service** → identity_assertion + id-jag.
+2. **You have only the user's email** → service_auth. Claim ceremony required.
+3. **You have neither** → anonymous. Claim ceremony optional; deferred until the user wants to take ownership.
+
+Before sending: cross-check your choice against the `agent_auth` block. If your type is not in `identity_types_supported`, pick another or stop.
+
+## Step 3 — Register
+
+Before sending an `identity_assertion` or `service_auth` body, surface the service's `resource_name` and `resource_logo_uri` (from Step 1a) and the scope set you'll be acting under, and confirm with the user. Skip this for `anonymous`.
+
+### identity_assertion + id-jag
+
+<!-- DELETE THIS SECTION IF NOT SUPPORTING ID-JAG FLOW -->
+
+Mint the ID-JAG with:
+- `aud` = the `resource` from the PRM
+- `iss` = your provider's issuer URL (must be on trust list)
+- `email_verified: true` OR `phone_number_verified: true`
+- Fresh `jti`, near-term `exp` (~5 minutes)
+- `auth_time` — epoch seconds when the user last authenticated at your provider. **Required.**
+
+\```http
+POST /agent/identity
+Content-Type: application/json
+
+{
+  "type": "identity_assertion",
+  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
+  "assertion": "<ID-JAG>"
+}
+\```
+
+Response — no confirmation needed (200):
+
+\```json
+{
+  "registration_id": "reg_...",
+  "registration_type": "identity_assertion",
+  "identity_assertion": "<service-signed-jwt>",
+  "assertion_expires": "{{assertion_expiry}}",
+  "scopes": [{{post_registration_scopes}}]
+}
+\```
+
+Keep `identity_assertion` and go to Step 5.
+
+Response — confirmation required (401, `interaction_required`):
+
+\```json
+{
+  "error": "interaction_required",
+  "error_description": "...",
+  "registration_id": "reg_...",
+  "registration_type": "identity_assertion",
+  "claim_url": "{{auth_server_url}}/agent/identity/claim",
+  "claim_token": "clm_...",
+  "claim_token_expires": "...",
+  "post_claim_scopes": [{{post_claim_scopes}}],
+  "claim": {
+    "user_code": "123456",
+    "expires_in": 600,
+    "verification_uri": "{{auth_server_url}}/login?return_to=...",
+    "interval": 5
+  }
+}
+\```
+
+Surface `verification_uri` + `user_code` to the user (Step 4b) and poll (Step 4c).
+
+Response — login required (401, `login_required`):
+
+\```json
+{
+  "error": "login_required",
+  "error_description": "auth_time is too old; re-authenticate at the provider.",
+  "max_age": 3600
+}
+\```
+
+Re-authenticate the user at your provider (`prompt=login`) and mint a fresh ID-JAG.
+
+### service_auth
+
+<!-- DELETE THIS SECTION IF NOT SUPPORTING SERVICE_AUTH FLOW -->
+
+\```http
+POST /agent/identity
+Content-Type: application/json
+
+{
+  "type": "service_auth",
+  "login_hint": "user@example.com"
+}
+\```
+
+Response (200):
+
+\```json
+{
+  "registration_id": "reg_...",
+  "registration_type": "service_auth",
+  "claim_url": "{{auth_server_url}}/agent/identity/claim",
+  "claim_token": "clm_...",
+  "claim_token_expires": "{{claim_ttl}}",
+  "post_claim_scopes": [{{post_claim_scopes}}],
+  "claim": {
+    "user_code": "123456",
+    "expires_in": 600,
+    "verification_uri": "{{auth_server_url}}/login?return_to=...",
+    "interval": 5
+  }
+}
+\```
+
+No `identity_assertion` yet. Go to Step 4.
+
+### anonymous
+
+<!-- DELETE THIS SECTION IF NOT SUPPORTING ANONYMOUS FLOW -->
+
+\```http
+POST /agent/identity
+Content-Type: application/json
+
+{
+  "type": "anonymous"
+}
+\```
+
+Response (200):
+
+\```json
+{
+  "registration_id": "reg_...",
+  "registration_type": "anonymous",
+  "identity_assertion": "<service-signed-jwt>",
+  "assertion_expires": "{{assertion_expiry}}",
+  "pre_claim_scopes": [{{pre_claim_scopes}}],
+  "claim_url": "{{auth_server_url}}/agent/identity/claim",
+  "claim_token": "clm_...",
+  "claim_token_expires": "{{claim_ttl}}",
+  "post_claim_scopes": [{{post_claim_scopes}}]
+}
+\```
+
+The `identity_assertion` exchanges at `/oauth2/token` for an access_token with `pre_claim_scopes` immediately (Step 5). To upgrade scopes, go to Step 4.
+
+## Step 4 — Claim ceremony
+
+<!-- DELETE THIS ENTIRE SECTION IF ONLY SUPPORTING identity_assertion WITHOUT interaction_required -->
+
+The end goal: get a signed-in user to confirm a 6-digit `user_code` **you supply them**. The code travels from you → user; the user authenticates to the service and types it into a page the service owns.
+
+### 4a. Get the ceremony materials
+
+For **service_auth** registrations and **interaction_required** responses, you already have the `claim` block from Step 3. Skip to 4b.
+
+For **anonymous** registrations, initiate the ceremony:
+
+\```http
+POST /agent/identity/claim
+Content-Type: application/json
+
+{
+  "claim_token": "clm_...",
+  "email": "user@example.com"
+}
+\```
+
+Response (200):
+
+\```json
+{
+  "registration_id": "reg_...",
+  "claim_attempt_id": "cla_...",
+  "status": "initiated",
+  "expires_at": "{{claim_attempt_ttl}}",
+  "claim_attempt": {
+    "user_code": "123456",
+    "expires_in": 600,
+    "verification_uri": "{{auth_server_url}}/login?return_to=...",
+    "interval": 5
+  }
+}
+\```
+
+### 4b. Hand off to the user
+
+Surface `verification_uri` and `user_code` to the user in a single message:
+
+> Open this link, sign in (or sign up), and enter this 6-digit code: **123456**
+> {{verification_uri}}
+
+The user will:
+1. Open `verification_uri`
+2. Authenticate with the service (sign in or sign up)
+3. Land on the claim page, see their identity displayed, type the `user_code`, and submit
+
+### 4c. Poll for completion
+
+Poll the standard `token_endpoint` (from AS metadata) with the profile-specific claim grant:
+
+\```http
+POST /oauth2/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:workos:agent-auth:grant-type:claim
+&claim_token=<claim_token>
+\```
+
+Response while waiting:
+
+\```json
+{
+  "error": "authorization_pending",
+  "error_description": "..."
+}
+\```
+
+Response on success:
+
+\```json
+{
+  "access_token": "<token>",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "scope": "{{scopes}}",
+  "identity_assertion": "<service-signed-jwt-v2>",
+  "assertion_expires": "{{assertion_expiry}}"
+}
+\```
+
+Use `access_token` immediately; cache `identity_assertion` for refresh via Step 5.
+
+If the `user_code` window expires:
+
+\```json
+{
+  "error": "expired_token",
+  "error_description": "..."
+}
+\```
+
+Re-call `POST /agent/identity/claim` with the same `claim_token` and `email` to mint a fresh `user_code`. If that returns `claim_expired`, restart at Step 3.
+
+Honor `interval` (in seconds); on `slow_down` back off.
+
+## Step 5 — Exchange the assertion
+
+POST the `identity_assertion` to the token endpoint with the RFC 7523 JWT-bearer grant:
+
+\```http
+POST /oauth2/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
+&assertion=<identity_assertion>
+&resource={{base_url}}/
+\```
+
+Response (200):
+
+\```json
+{
+  "access_token": "<token>",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "scope": "{{scopes}}"
+}
+\```
+
+The same `identity_assertion` can be re-used to mint additional access_tokens until it expires. If `/oauth2/token` returns `invalid_grant`, restart at Step 3.
+
+## Step 6 — Use the access_token
+
+Present as a bearer token:
+
+\```http
+GET /api/some-resource
+Authorization: Bearer <access_token>
+\```
+
+**Refresh:** When the access_token expires, re-call Step 5 with the same `identity_assertion`. When the identity_assertion itself expires or `/oauth2/token` returns `invalid_grant`, restart at Step 3. There is no refresh_token — the two-step pattern replaces it.
+
+On 401 for a previously-working access_token: try Step 5 once. If that also fails, restart at Step 1.
+
+Full API reference: `{{api_docs_url}}`
+
+## Errors
+
+| Code | Where | What to do |
+|------|-------|------------|
+| `anonymous_not_enabled` | `/agent/identity` | Pick another method from Step 2 |
+| `service_auth_not_enabled` | `/agent/identity` | Pick another method |
+| `issuer_not_enabled` | `/agent/identity` | Provider not on trust list. Pick another method |
+| `invalid_request` | `/agent/identity` | Fix body shape, claims, signature, jti, aud problems |
+| `interaction_required` (401) | `/agent/identity` (ID-JAG) | Body carries `claim` block; surface to user (Step 4) |
+| `login_required` (401) | `/agent/identity` (ID-JAG) | Re-authenticate user at provider, mint fresh ID-JAG |
+| `invalid_claim_token` | `/agent/identity/claim` | Restart at Step 3 |
+| `claimed_or_in_flight` | `/agent/identity/claim` | Already claimed. Re-read Step 3 response |
+| `claim_expired` | `/agent/identity/claim` | Registration expired. Restart at Step 3 |
+| `invalid_grant` | `/oauth2/token` | Assertion expired/revoked. Restart at Step 3 |
+| `invalid_client` | `/oauth2/token` | client_id not recognized |
+| `unsupported_grant_type` | `/oauth2/token` | Use one of the two supported grant types |
+| `authorization_pending` | `/oauth2/token` (claim) | User hasn't completed ceremony. Honor `interval` |
+| `expired_token` | `/oauth2/token` (claim) | user_code window closed. Re-initiate or restart |
+| `slow_down` | `/oauth2/token` (claim) | Add ≥5s to interval and retry |
+| `rate_limited` (429) | any | Back off and retry |
+
+## Revocation
+
+Two independent layers:
+
+- **Credential layer (RFC 7009):** POST `token=<access_token>&token_type_hint=access_token` to `{{auth_server_url}}/oauth2/revoke`. Kills one access_token. Identity assertion intact — re-run Step 5.
+- **Registration layer (RFC 8935 SET delivery):** Provider POSTs a Security Event Token to `events_endpoint`. Service invalidates identity_assertion and all derived access_tokens. Agent discovers this when `/oauth2/token` returns `invalid_grant` — restart at Step 3.
+
+On 401 for a previously-working access_token: try Step 5 once. If `/oauth2/token` succeeds, credential-layer revocation — fresh access_token works. If `invalid_grant`, registration-layer — restart at Step 3.
+```
+
+---
+
+## Placeholder Reference
+
+| Placeholder | Description | Example |
+|-------------|-------------|---------|
+| `{{base_url}}` | API base URL (resource server) | `https://api.acme.com` |
+| `{{service_name}}` | Human-readable service name | `Acme Notes` |
+| `{{logo_url}}` | Service logo URL | `https://acme.com/logo.png` |
+| `{{auth_server_url}}` | Authorization server base URL | `https://auth.acme.com` |
+| `{{auth_md_url}}` | URL where auth.md is hosted | `https://acme.com/auth.md` |
+| `{{scopes_list}}` | JSON array of scope strings | `"notes.read", "notes.write"` |
+| `{{identity_types}}` | Supported identity types | `"anonymous", "identity_assertion", "service_auth"` |
+| `{{assertion_types}}` | Supported assertion types | `"urn:ietf:params:oauth:token-type:id-jag"` |
+| `{{pre_claim_scopes}}` | Scopes before claim (anonymous) | `"notes.read"` |
+| `{{post_claim_scopes}}` | Scopes after claim | `"notes.read", "notes.write"` |
+| `{{post_registration_scopes}}` | Scopes after ID-JAG registration | `"notes.read", "notes.write"` |
+| `{{assertion_expiry}}` | Identity assertion expiry (ISO) | `2026-05-22T13:00:00.000Z` |
+| `{{claim_ttl}}` | Claim token expiration (ISO) | `2026-05-22T12:00:00.000Z` |
+| `{{claim_attempt_ttl}}` | Claim attempt expiration | `2026-05-22T12:10:00.000Z` |
+| `{{api_docs_url}}` | Link to full API docs | `https://docs.acme.com/` |
+
+---
+
+## Generation Rules
+
+1. **Keep the file concise and high-signal** — anything the agent doesn't need to register or operate belongs in main documentation, not in auth.md
+2. **Use fenced code blocks with language hints** (`http`, `json`) so agents can extract templates unambiguously
+3. **Declare real hostnames in the intro** — resource server and auth server — so the agent knows which host each example targets
+4. **Delete sections for unsupported flows** — don't leave empty sections or "N/A" markers
+5. **The PRM is authoritative** — if anything in auth.md conflicts with the PRM, the PRM wins
+6. **Token exchange is always required** — registration never returns an access_token directly; always returns an identity_assertion that must be exchanged at `/oauth2/token`
--- a/.github/skills/auth-md/references/validation-rules.md
+++ b/.github/skills/auth-md/references/validation-rules.md
@@ -0,0 +1,162 @@
+# Validation Rules
+
+Complete ruleset for validating `auth.md` files against the protocol specification (v2, June 2026).
+
+---
+
+## Level: Basic (Offline)
+
+### Structure Rules
+
+| ID | Rule | Error Message | Severity |
+|----|------|---------------|----------|
+| S01 | Document starts with `# auth.md` heading | Missing required top-level heading `# auth.md` | 🔴 |
+| S02 | Contains `## Step 1 — Discover` section | Missing required section: Step 1 — Discover | 🔴 |
+| S03 | Contains `## Step 2 — Pick a method` section | Missing required section: Step 2 — Pick a method | 🔴 |
+| S04 | Contains `## Step 3 — Register` section | Missing required section: Step 3 — Register | 🔴 |
+| S05 | Contains `## Step 4 — Claim ceremony` section (if service_auth or anonymous with claim) | Missing required section: Step 4 — Claim ceremony (required when service_auth or anonymous claim is supported) | 🔴 |
+| S06 | Contains `## Step 5 — Exchange the assertion` section | Missing required section: Step 5 — Exchange the assertion | 🔴 |
+| S07 | Contains `## Step 6 — Use the access_token` section | Missing required section: Step 6 — Use the access_token | 🔴 |
+| S08 | Contains `## Errors` section | Missing required section: Errors | 🔴 |
+| S09 | Contains `## Revocation` section | Missing required section: Revocation | 🔴 |
+| S10 | Sections appear in correct order (Step 1 → 2 → 3 → 4 → 5 → 6 → Errors → Revocation) | Sections are out of order. Expected sequence: Step 1, 2, 3, 4, 5, 6, Errors, Revocation | 🟡 |
+| S11 | Intro declares real hostnames (resource server and auth server) | Intro should declare real hostnames for resource and auth servers | 🟢 |
+
+### Field Rules
+
+| ID | Rule | Error Message | Severity |
+|----|------|---------------|----------|
+| F01 | Step 1 contains at least one fenced JSON block with `resource` field | Step 1 must include Protected Resource Metadata JSON with `resource` field | 🔴 |
+| F02 | PRM JSON contains `resource_name` | Missing `resource_name` in PRM — agents need this for consent prompts | 🟡 |
+| F03 | PRM JSON contains `resource_logo_uri` | Missing `resource_logo_uri` — recommended for consent UX | 🟢 |
+| F04 | JSON metadata contains `authorization_servers` array | Missing `authorization_servers` — agents can't discover the auth endpoint | 🟡 |
+| F05 | JSON metadata contains `scopes_supported` array with ≥1 scope | Missing or empty `scopes_supported` | 🟡 |
+| F06 | AS metadata contains `agent_auth` block | Missing `agent_auth` block in Authorization Server metadata | 🔴 |
+| F07 | `agent_auth` contains `identity_endpoint` | Missing `identity_endpoint` in agent_auth block | 🔴 |
+| F08 | `agent_auth` contains `identity_types_supported` with ≥1 type | Missing or empty `identity_types_supported` | 🔴 |
+| F09 | If `identity_assertion` in identity_types_supported, `assertion_types_supported` must exist | Declared `identity_assertion` support but missing `assertion_types_supported` | 🟡 |
+| F10 | Step 3 contains at least one `POST /agent/identity` request example | Step 3 must include at least one registration request example | 🔴 |
+| F11 | Errors section contains a table with `Code`, `Where`, and `What to do` columns | Errors section must contain a table with Code, Where, and What to do columns | 🟡 |
+| F12 | `agent_auth` contains `skill` pointing to auth.md URL | Missing `skill` field in agent_auth — recommended for discoverability | 🟢 |
+| F13 | `agent_auth` contains `events_supported` | Missing `events_supported` — recommended for revocation support | 🟢 |
+| F14 | AS metadata contains `token_endpoint` | Missing `token_endpoint` — required for token exchange and claim polling | 🔴 |
+| F15 | AS metadata contains `revocation_endpoint` | Missing `revocation_endpoint` — required for credential-layer revocation | 🟡 |
+| F16 | AS metadata contains `grant_types_supported` with both required URNs | Missing or incomplete `grant_types_supported` — must include jwt-bearer and claim grant URNs | 🟡 |
+| F17 | If `service_auth` or `anonymous` in identity_types_supported, `claim_endpoint` must exist | service_auth/anonymous requires `claim_endpoint` for ceremony initiation | 🟡 |
+| F18 | `agent_auth` contains `events_endpoint` | Missing `events_endpoint` — recommended for registration-layer revocation | 🟢 |
+| F19 | Step 5 contains `POST /oauth2/token` with jwt-bearer grant | Step 5 must document the token exchange via /oauth2/token | 🔴 |
+
+### Consistency Rules
+
+| ID | Rule | Error Message | Severity |
+|----|------|---------------|----------|
+| C01 | Flows documented in Step 3 match `identity_types_supported` in metadata | Mismatch: Step 3 documents flows not declared in metadata (or vice versa) | 🟡 |
+| C02 | If only identity_assertion flow without claim: Step 4 may be absent | Step 4 present but only identity_assertion flow without claim is supported | 🟡 |
+| C03 | `identity_endpoint` path matches the POST path in Step 3 examples | Registration endpoint in metadata doesn't match the POST path in Step 3 | 🟡 |
+| C04 | `claim_endpoint` path matches the POST path in Step 4 examples (if present) | Claim endpoint in metadata doesn't match the POST path in Step 4 | 🟡 |
+| C05 | Scopes in response examples are subset of `scopes_supported` | Response example contains scopes not listed in `scopes_supported` | 🟡 |
+| C06 | `resource` URL is consistent across all JSON blocks | Different `resource` URLs found in metadata blocks — must be consistent | 🟡 |
+| C07 | All URLs use HTTPS scheme | Non-HTTPS URL found — all endpoints must use HTTPS | 🟡 |
+| C08 | Error codes in table match standard protocol error codes (see list below) | Non-standard error code found | 🟡 |
+| C09 | `aud` in ID-JAG examples matches the `resource` from PRM | ID-JAG `aud` example doesn't match the resource URL | 🟡 |
+| C10 | `assertion_types_supported` includes types used in Step 3 examples | Step 3 uses assertion types not declared in metadata | 🟡 |
+| C11 | `token_endpoint` in metadata matches the `/oauth2/token` path used in Steps 4c and 5 | Token endpoint in metadata doesn't match the POST path in Steps 4c/5 | 🟡 |
+| C12 | `grant_types_supported` includes `urn:ietf:params:oauth:grant-type:jwt-bearer` | Missing jwt-bearer grant in grant_types_supported — required for token exchange | 🟡 |
+| C13 | `grant_types_supported` includes `urn:workos:agent-auth:grant-type:claim` (if claim ceremony exists) | Missing claim grant in grant_types_supported — required for ceremony polling | 🟡 |
+
+### Format Rules
+
+| ID | Rule | Error Message | Severity |
+|----|------|---------------|----------|
+| X01 | All JSON in fenced code blocks is valid JSON | Invalid JSON in fenced code block at section: {section} | 🟡 |
+| X02 | HTTP request examples use valid HTTP method + path | Invalid HTTP request format. Expected: METHOD /path | 🟡 |
+| X03 | No unreplaced placeholder patterns (`{{...}}`, `<your-...>`, `[YOUR_...]`) | Unreplaced placeholder found: {placeholder} | 🟡 |
+| X04 | Fenced code blocks have language hint (`http`, `json`) | Code block missing language hint — agents use these to identify request shapes | 🟢 |
+
+---
+
+## Level: Full (Live)
+
+All Basic rules, plus:
+
+### Endpoint Rules
+
+| ID | Rule | Error Message | Severity |
+|----|------|---------------|----------|
+| E01 | `GET {base_url}/.well-known/oauth-protected-resource` returns 200 with valid JSON | Protected Resource Metadata endpoint not reachable or returns invalid response | 🔴 |
+| E02 | PRM response contains `authorization_servers` pointing to AS with `agent_auth` block | No `agent_auth` block discoverable through PRM → AS metadata chain | 🔴 |
+| E03 | `GET {auth_server}/.well-known/oauth-authorization-server` returns 200 with valid JSON | Authorization Server metadata endpoint not reachable | 🔴 |
+| E04 | AS metadata `agent_auth` block matches declarations in auth.md | Live AS metadata `agent_auth` block differs from auth.md declarations | 🟡 |
+| E05 | `identity_endpoint` accepts POST (returns 400/401/422, not 404/405) | Registration endpoint returns 404 or 405 — not implemented | 🔴 |
+| E06 | `claim_endpoint` accepts POST (if service_auth or anonymous supported) | Claim endpoint returns 404 or 405 — not implemented | 🔴 |
+| E07 | `token_endpoint` accepts POST (returns 400/401, not 404/405) | Token endpoint returns 404 or 405 — not implemented | 🔴 |
+| E08 | `revocation_endpoint` accepts POST (returns 200/400, not 404/405) | Revocation endpoint returns 404 or 405 — not implemented | 🟡 |
+| E09 | API base URL returns 401 with `WWW-Authenticate` header containing `resource_metadata` | API does not return WWW-Authenticate header with resource_metadata on 401 | 🟡 |
+
+---
+
+## Standard Protocol Error Codes
+
+Complete list of error codes the Errors table should cover (per supported flows):
+
+### Registration Endpoint (`/agent/identity`)
+- `anonymous_not_enabled`
+- `service_auth_not_enabled`
+- `issuer_not_enabled`
+- `invalid_request` (body shape, missing claims, signature, jti, aud, unverified identity)
+- `interaction_required` (401) — ID-JAG matched account but no (iss,sub) delegation
+- `login_required` (401) — auth_time missing or older than max_age
+- `rate_limited` (429)
+
+### Claim Endpoint (`/agent/identity/claim`)
+- `invalid_claim_token`
+- `claimed_or_in_flight`
+- `claim_expired`
+
+### Token Endpoint (`/oauth2/token`)
+- `invalid_grant` — assertion expired/revoked/replayed
+- `invalid_client`
+- `unsupported_grant_type`
+- `authorization_pending` — claim polling, user hasn't completed
+- `expired_token` — user_code window closed
+- `slow_down` — polling too fast
+
+### All Endpoints
+- `rate_limited` (429)
+
+---
+
+## Validation Report Format
+
+```markdown
+# Validation Report — auth.md
+
+**File:** {path_or_url}
+**Level:** {basic|full}
+**Date:** {timestamp}
+
+## Summary
+
+- ✅ {n} rules passed
+- ❌ {n} rules failed
+- ⚠️ {n} warnings
+
+## Structure
+
+| Status | ID | Rule |
+|--------|-----|-------|
+| ✅ | S01 | Heading `# auth.md` present |
+| ❌ | S06 | Step 5 section missing |
+
+## Fields
+...
+
+## Consistency
+...
+
+## Format
+...
+
+## Endpoints (full only)
+...
+```
--- a/.github/skills/coolify-operator/.env.example
+++ b/.github/skills/coolify-operator/.env.example
@@ -0,0 +1,2 @@
+COOLIFY_KEY=<KEY>
+COOLIFY=<URL>
--- a/.github/skills/coolify-operator/SKILL.md
+++ b/.github/skills/coolify-operator/SKILL.md
@@ -0,0 +1,519 @@
+---
+name: coolify-operator
+description: Master Coolify operator for self-hosted deployment platform. Use when the user mentions 'coolify', 'deploy on coolify', 'list/restart/redeploy applications', 'view coolify logs', 'coolify API/CLI', 'manage coolify servers/databases/apps', or 'coolify context'. Automates deployments and management via REST API or official CLI.
+metadata:
+  author: ft.ia.br
+  version: "1.1"
+  date: 2026-03-08
+  license: MIT
+  category: ci-cd-and-deployment
+---
+
+# Coolify Operator
+
+Skill for operating Coolify instances through the **REST API** or **official CLI**. Coolify is a self-hosted open-source platform alternative to Heroku/Vercel/Netlify for deploying applications, databases, and services.
+
+## When to use this skill
+
+- Connect to Coolify instances (via API or CLI)
+- List and manage applications, services, databases, and servers
+- Deploy, restart, or stop applications
+- View logs and deployment status
+- Manage environment variables
+- Operate multiple Coolify instances (contexts)
+- Troubleshoot Coolify connection issues
+
+## Fundamental concepts
+
+### Authentication
+
+**REST API:**
+- Base endpoint: `https://YOUR-HOST/api/v1` (always with `/api/v1` at the end)
+- Authentication: `Authorization: Bearer YOUR_TOKEN`
+- Token obtained at: Coolify Dashboard → Keys & Tokens → API Tokens
+
+**CLI:**
+- Installs contexts that store HOST + TOKEN
+- HOST in context is WITHOUT `/api/v1` (just the base URL)
+- CLI adds `/api/v1` automatically
+
+### Configuration with pipe in token
+
+⚠️ **IMPORTANT**: Coolify tokens often contain `|` (e.g., `3|abc123...`). Never use `source .env` as this breaks in the shell.
+
+**Safe .env reading:**
+```bash
+COOLIFY_KEY=$(sed -n 's/^COOLIFY_KEY=//p' .env)
+COOLIFY=$(sed -n 's/^COOLIFY=//p' .env)
+```
+
+**Expected .env format:**
+```bash
+COOLIFY_KEY=3|abc123def456...
+COOLIFY=http://192.168.1.XXX:8000/api/v1
+```
+
+### UUIDs
+
+Coolify uses UUIDs to identify resources:
+- Applications: `app-uuid`
+- Servers: `server-uuid`
+- Databases: `db-uuid`
+- Services: `service-uuid`
+
+## CLI Operations
+
+### Initial setup
+
+```bash
+# Read token from .env safely
+COOLIFY_KEY=$(sed -n 's/^COOLIFY_KEY=//p' .env)
+
+# Add context (URL WITHOUT /api/v1)
+coolify context add -d -f my-coolify http://192.168.1.XXX:8000 "$COOLIFY_KEY"
+
+# Use the context
+coolify context use my-coolify
+
+# Verify connection
+coolify context verify
+
+# Check API version
+coolify context version
+```
+
+### Context management
+
+```bash
+# List contexts
+coolify context list
+
+# Add multiple contexts
+coolify context add prod https://prod.coolify.io "$PROD_TOKEN" --default
+coolify context add staging https://staging.coolify.io "$STAGING_TOKEN"
+coolify context add dev https://dev.coolify.io "$DEV_TOKEN"
+
+# Switch default context
+coolify context use staging
+
+# Use specific context in a command
+coolify --context=prod app list
+
+# Update token for a context
+coolify context set-token prod new-token-here
+
+# Remove context
+coolify context delete dev
+```
+
+### Application operations
+
+```bash
+# List all applications
+coolify app list
+
+# View application details
+coolify app get <uuid>
+
+# --- LIFECYCLE ---
+# Start (deploy) application
+coolify app start <uuid>
+
+# Stop application
+coolify app stop <uuid>
+
+# Restart application
+coolify app restart <uuid>
+
+# --- LOGS ---
+# View application logs
+coolify app logs <uuid>
+
+# --- ENVIRONMENT VARIABLES ---
+# List environment variables
+coolify app env list <uuid>
+
+# Create environment variable
+coolify app env create <uuid> --key API_KEY --value secret123
+
+# Sync environment variables from .env file
+coolify app env sync <uuid> --file .env
+coolify app env sync <uuid> --file .env.production --build-time --preview
+```
+
+### Server operations
+
+```bash
+# List servers
+coolify server list
+
+# View server details (including resources)
+coolify server get <uuid> --resources
+
+# Add new server (with validation)
+coolify server add myserver 192.168.1.100 <key-uuid> --validate
+```
+
+### Team operations
+
+```bash
+# List available teams
+coolify team list
+
+# View current team
+coolify team current
+
+# List team members
+coolify team members list
+```
+
+### Global flags
+
+```bash
+# Specify context
+coolify --context <name> ...
+
+# Override host
+coolify --host <fqdn> ...
+
+# Direct token (bypasses context)
+coolify --token <token> ...
+
+# Output format (table, json, pretty)
+coolify --format json ...
+
+# Show sensitive data
+coolify -s ...
+coolify --show-sensitive ...
+
+# Force operation
+coolify -f ...
+coolify --force ...
+
+# Debug mode
+coolify --debug ...
+```
+
+## REST API Operations
+
+### Authentication and testing
+
+```bash
+# Read credentials from .env safely
+COOLIFY_KEY=$(sed -n 's/^COOLIFY_KEY=//p' .env)
+COOLIFY=$(sed -n 's/^COOLIFY=//p' .env)
+
+# Test connection
+curl -sS -i \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/version"
+
+# Expected result: HTTP 200 + {"version": "4.0.0-beta.xxx"}
+```
+
+### Applications
+
+```bash
+# List applications
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/applications"
+
+# View application details
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/applications/{uuid}"
+
+# Start (deploy) application
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/applications/{uuid}/start"
+
+# Query param flags:
+# ?force=true          - Force rebuild
+# ?instant_deploy=true - Skip queue
+
+# Stop application
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/applications/{uuid}/stop"
+
+# Restart application
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/applications/{uuid}/restart"
+
+# Example response:
+# {
+#   "message": "Restart request queued.",
+#   "deployment_uuid": "doogksw"
+# }
+```
+
+### Deployments
+
+```bash
+# List all ongoing deployments
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/deployments"
+
+# List deployments for an application (with pagination)
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/deployments/applications/{uuid}?skip=0&take=10"
+```
+
+### Servers
+
+```bash
+# List servers
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/servers"
+
+# View server details
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/servers/{uuid}"
+```
+
+### Databases
+
+```bash
+# List databases
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/databases"
+
+# Start database
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/databases/{uuid}/start"
+
+# Stop database
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/databases/{uuid}/stop"
+
+# Restart database
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/databases/{uuid}/restart"
+```
+
+### Services
+
+```bash
+# Restart service
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/services/{uuid}/restart"
+
+# Query params:
+# ?latest=true - Pull latest images
+
+# Response:
+# {"message": "Service restaring request queued."}
+```
+
+## Troubleshooting
+
+### Error: 403 "You are not allowed to access the API"
+
+**Cause:** Invalid token or no permission for the instance.
+
+**Solution:**
+1. Ask the user to verify in the instance at <INSTANCE_URL>/settings/advanced whether the API is enabled and the client IP is allowed
+2. Regenerate token at: Dashboard → Keys & Tokens → API Tokens
+3. Update `.env` or CLI context
+4. Verify that the correct instance is being used
+
+### Error: 401 "Unauthenticated"
+
+**Cause:** Incorrect authentication header or token not sent.
+
+**Solution:**
+```bash
+# Verify that Bearer is being used (not just "Token")
+Authorization: Bearer YOUR_TOKEN
+
+# CLI: verify context
+coolify context verify
+```
+
+### Error: 404 on context verify
+
+**Cause:** CLI context URL is incorrect (probably with `/api/v1` in the wrong place).
+
+**Solution:**
+```bash
+# CLI context must have URL WITHOUT /api/v1
+coolify context add my-coolify http://192.168.1.XXX:8000 "$TOKEN"
+
+# Direct API must have URL WITH /api/v1
+COOLIFY=http://192.168.1.XXX:8000/api/v1
+```
+
+### Cloudflare Tunnel is not the cause
+
+If the API already returns valid JSON from Coolify (even if it's an auth error), the Cloudflare tunnel is working. The problem is authentication, not connectivity.
+
+### Token with pipe (|) breaks shell
+
+```bash
+# ❌ WRONG - breaks with pipe
+source .env
+
+# ✅ CORRECT - safe reading
+COOLIFY_KEY=$(sed -n 's/^COOLIFY_KEY=//p' .env)
+```
+
+## Common workflows
+
+### Full deploy of a new application
+
+```bash
+# 1. Connect to Coolify
+coolify context add prod https://coolify.your-domain.com "$TOKEN" --default
+coolify context verify
+
+# 2. List available servers
+coolify server list
+
+# 3. Deploy (via dashboard UI or API)
+# Note: app creation is better via UI, API is for operations
+
+# 4. List apps to get UUID
+coolify app list
+
+# 5. Start the application
+coolify app start <uuid>
+
+# 6. View deploy logs
+coolify app logs <uuid>
+```
+
+### Redeploy with force rebuild
+
+```bash
+# Via CLI
+coolify app restart <uuid>
+
+# Via API with forced rebuild
+curl -sS \
+  -H "Authorization: Bearer $COOLIFY_KEY" \
+  "$COOLIFY/applications/{uuid}/start?force=true"
+```
+
+### Update environment variables
+
+```bash
+# Option 1: Sync from file
+coolify app env sync <uuid> --file .env.production
+
+# Option 2: Create individually
+coolify app env create <uuid> --key API_URL --value https://api.example.com
+coolify app env create <uuid> --key API_KEY --value secret123
+
+# 3. Restart to apply changes
+coolify app restart <uuid>
+```
+
+### Multi-environment monitoring
+
+```bash
+# Production
+coolify --context=prod app list
+coolify --context=prod app logs <prod-app-uuid>
+
+# Staging
+coolify --context=staging app list
+coolify --context=staging app logs <staging-app-uuid>
+
+# Development
+coolify --context=dev app list
+coolify --context=dev server list
+```
+
+## Important resources
+
+### API response structure
+
+**Application:**
+```json
+{
+  "id": 123,
+  "uuid": "app-uuid-123",
+  "name": "my-app",
+  "fqdn": "app.example.com",
+  "status": "running",
+  "git_repository": "https://github.com/user/repo",
+  "git_branch": "main",
+  "git_commit_sha": "abc123",
+  "build_pack": "nixpacks",
+  "ports_exposes": "3000",
+  "health_check_enabled": true,
+  "environment_id": 1,
+  "destination_id": 1
+}
+```
+
+**Server:**
+```json
+{
+  "id": 1,
+  "uuid": "server-uuid-123",
+  "name": "main-server",
+  "ip": "192.168.1.100",
+  "user": "root",
+  "port": 22,
+  "settings": {
+    "is_reachable": true,
+    "is_usable": true,
+    "concurrent_builds": 1
+  }
+}
+```
+
+**Deployment:**
+```json
+{
+  "id": 456,
+  "uuid": "deployment-uuid-456",
+  "status": "finished",
+  "deployment_uuid": "dep-123",
+  "application_id": 123
+}
+```
+
+## Usage tips
+
+1. **Always verify UUIDs**: Use `coolify app list` or API to confirm UUIDs before operations
+2. **Contexts for multi-environment**: Configure one context for each environment (dev/staging/prod)
+3. **Real-time logs**: Use `coolify app logs <uuid>` during deploys
+4. **Force rebuild when needed**: `?force=true` on start ensures complete rebuild
+5. **Token security**: Never commit tokens. Use `.env` with `.gitignore`
+6. **JSON format for scripts**: Use `--format json` in CLI for parsing with `jq`
+
+## Quality Checklist
+
+Before executing any operation, verify:
+
+- [ ] `.env` file present with correct `COOLIFY_KEY` and `COOLIFY`
+- [ ] Token read safely (using `sed` or appropriate method, not `source`)
+- [ ] Correct context selected (`coolify context use <name>`)
+- [ ] Connection verified (`coolify context verify`)
+- [ ] UUIDs confirmed before destructive operations
+- [ ] Endpoint URL correct (API has `/api/v1`, CLI context does not)
+- [ ] Authentication headers included in API calls (`Authorization: Bearer <token>`)
+- [ ] Error handling implemented (401, 403, 404, 500)
+- [ ] Logs checked in case of deploy failure
+- [ ] Critical operations (delete, stop) executed with confirmation
+
+## References
+
+- **Official documentation**: https://coolify.io/docs
+- **API Reference**: https://coolify.io/docs/api-reference
+- **CLI GitHub**: https://github.com/coollabsio/coolify-cli
+- **Coolify Core**: https://github.com/coollabsio/coolify
--- a/.github/skills/coolify-operator/evals/evals.json
+++ b/.github/skills/coolify-operator/evals/evals.json
@@ -0,0 +1,61 @@
+{
+  "skill_name": "coolify-operator",
+  "evals": [
+    {
+      "id": 1,
+      "name": "configurar-contexto-inicial",
+      "prompt": "I need to set up my Coolify connection. I have the token '3|AbCdEf123456' and the URL is 'http://192.168.1.106:8000'. How do I connect using the CLI? I want it to be the default context named 'producao'.",
+      "expected_output": "CLI commands to add Coolify context, including safe token reading (avoiding issues with pipe |), adding context with URL without /api/v1, verifying connection and testing",
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "listar-e-restart-app",
+      "prompt": "Can you help me restart the application 'meu-site-nextjs' on Coolify? I don't know its UUID, so I need to list first. Then I want to do a restart forcing rebuild because I updated some environment variables.",
+      "expected_output": "Sequence of commands: list apps to find UUID, then restart the specific application, with force rebuild flag if necessary",
+      "files": []
+    },
+    {
+      "id": 3,
+      "name": "troubleshooting-403",
+      "prompt": "I'm trying to use the Coolify API but I'm getting error 403 'You are not allowed to access the API'. I already checked the token in the dashboard and it seems correct. What could it be?",
+      "expected_output": "Explanation of possible causes for error 403, steps to verify token, regenerate if necessary, troubleshooting checklist, and commands to test the connection",
+      "files": []
+    },
+    {
+      "id": 4,
+      "name": "multi-ambiente-deploy",
+      "prompt": "I have 3 Coolify environments (dev, staging and prod). I want to deploy the same app to all 3 environments. How do I configure the contexts and deploy to each one? The URLs are: dev at http://dev.coolify.local:8000, staging at https://staging.coolify.empresa.com and prod at https://coolify.empresa.com",
+      "expected_output": "Commands to configure multiple CLI contexts, add each environment, switch between contexts and deploy/operate on each one",
+      "files": []
+    },
+    {
+      "id": 5,
+      "name": "atualizar-env-vars",
+      "prompt": "I need to update the environment variables for my app on Coolify. I have a local .env.production file with the new configs. The app UUID is 'app-abc-123'. How do I sync and apply the changes?",
+      "expected_output": "Commands to sync environment variables from file using CLI, followed by application restart to apply the changes",
+      "files": []
+    },
+    {
+      "id": 6,
+      "name": "monitorar-logs-deploy",
+      "prompt": "I just deployed the application with UUID 'app-xyz-789' but it seems stuck. How do I view real-time logs to debug what's happening?",
+      "expected_output": "CLI command to view application logs in real time, or alternative API commands",
+      "files": []
+    },
+    {
+      "id": 7,
+      "name": "erro-token-pipe",
+      "prompt": "I put my Coolify token in .env like this: COOLIFY_KEY=3|abc123def456 but when I 'source .env' in bash and try to use it I get an error. What's wrong?",
+      "expected_output": "Explanation of the pipe (|) problem in the token with source .env, and solution using sed for safe file reading",
+      "files": []
+    },
+    {
+      "id": 8,
+      "name": "listar-databases-e-restart",
+      "prompt": "My postgres on Coolify is having issues. I need to list all databases and then restart the one that has 'postgres-main' in the name.",
+      "expected_output": "Commands to list databases via CLI or API, find the correct UUID and execute restart of the specific database",
+      "files": []
+    }
+  ]
+}
--- a/.github/skills/design-md-validator/SKILL.md
+++ b/.github/skills/design-md-validator/SKILL.md
@@ -0,0 +1,230 @@
+---
+name: design-md-validator
+description: >
+  Validate DESIGN.md files against the official Google specification using the
+  `@google/design.md` CLI linter. Works with local files and remote URLs.
+  Use when the user wants to lint a DESIGN.md, check spec compliance, find
+  broken token references, verify WCAG contrast ratios, diff two versions,
+  export tokens to Tailwind or DTCG format, or audit a design system file
+  for structural correctness. Trigger on mentions of "validate DESIGN.md",
+  "lint DESIGN.md", "check my design.md", "design.md spec compliance",
+  "WCAG contrast check", "broken token references", "design token validation",
+  "export design tokens", "diff design systems", "design.md audit",
+  "@google/design.md", "npx design.md lint", "design system validation",
+  "frontmatter tokens", or any request to verify a DESIGN.md file.
+metadata:
+  author: https://ft.ia.br
+  version: "1.1"
+  date: 2026-07-18
+  repository: https://github.com/fabricioctelles/skills
+  license: Apache 2.0
+  category: product-verification
+  upstream:
+    spec: https://github.com/google-labs-code/design.md
+    cli: https://www.npmjs.com/package/@google/design.md
+    stitch-skills: https://github.com/google-labs-code/stitch-skills
+---
+
+# design-md-validator
+
+Validate, lint, diff, and export DESIGN.md files using the official Google
+`@google/design.md` CLI. Always uses the latest published version from npm —
+no vendored copy, always up-to-date with the spec.
+
+---
+
+## When to Use
+
+| Trigger | Action |
+|---|---|
+| User has a DESIGN.md file and wants validation | `lint` |
+| User wants to compare two versions | `diff` |
+| User wants to export tokens to Tailwind/DTCG | `export` |
+| User wants to see the current spec | `spec` |
+| User shares a URL to a raw DESIGN.md | Fetch → `lint` |
+| User asks "is my design.md valid?" | `lint` + interpret findings |
+
+---
+
+## Core Commands
+
+All commands use `npx @google/design.md` to ensure the latest version is always
+used. Never install globally — `npx` resolves from the public npm registry.
+
+### Lint (validate)
+
+```bash
+npx @google/design.md lint DESIGN.md
+```
+
+Output: JSON with `findings[]` and `summary { errors, warnings, infos }`.
+Exit code 1 if errors found, 0 otherwise.
+
+### Diff (compare versions)
+
+```bash
+npx @google/design.md diff DESIGN.md DESIGN-v2.md
+```
+
+Output: JSON with token-level changes (added, removed, modified) and regression flag.
+Exit codes: `0` no regression, `1` regression (errors in "after" > errors in "before"),
+`2` input failure (file not found or unreadable).
+
+### Export (to other formats)
+
+```bash
+# Tailwind v3 config
+npx @google/design.md export --format json-tailwind DESIGN.md
+
+# Tailwind v4 CSS theme
+npx @google/design.md export --format css-tailwind DESIGN.md
+
+# W3C Design Tokens (DTCG)
+npx @google/design.md export --format dtcg DESIGN.md
+
+# CSS custom properties (optional --prefix)
+npx @google/design.md export --format css-vars DESIGN.md
+npx @google/design.md export --format css-vars --prefix ds DESIGN.md
+```
+
+`css-vars` is available on main, ships in the next release — if the CLI
+rejects the format, npm is still on 0.3.0.
+
+### Spec (output the format specification)
+
+```bash
+npx @google/design.md spec
+npx @google/design.md spec --rules
+npx @google/design.md spec --rules-only --format json
+```
+
+---
+
+## Workflow
+
+### 1. Obtain the DESIGN.md
+
+**Local file:**
+```bash
+npx @google/design.md lint ./DESIGN.md
+```
+
+**From URL (fetch first):**
+```bash
+curl -sL <url> > /tmp/DESIGN.md && npx @google/design.md lint /tmp/DESIGN.md
+```
+
+**From stdin:**
+```bash
+cat DESIGN.md | npx @google/design.md lint -
+```
+
+### 2. Discover the Active Rule Set
+
+Before interpreting anything, check which rules the installed CLI actually
+runs — the rule set changes between releases, and the bundled references are
+a fallback, not the authoritative source:
+
+```bash
+npx @google/design.md spec --rules-only --format json
+```
+
+### 3. Run Lint
+
+```bash
+npx @google/design.md lint --format json DESIGN.md
+```
+
+### 4. Interpret Findings
+
+Parse the JSON output and report to the user:
+
+| Severity | Meaning | Action |
+|---|---|---|
+| `error` | Spec violation — file is invalid | Must fix |
+| `warning` | Best practice violation — file is valid but suboptimal | Should fix |
+| `info` | Informational — suggestions for improvement | Nice to fix |
+
+### 5. Provide Actionable Fixes
+
+For each finding, explain:
+1. What the rule checks
+2. Why it matters
+3. How to fix it with a concrete code example
+
+### 6. Re-validate After Fixes
+
+After applying fixes, re-run lint to confirm the file passes.
+
+---
+
+## Linting Rules Reference
+
+Load `references/linting-rules.md` for the complete rule table when providing
+detailed explanations of lint failures.
+
+---
+
+## Token Schema Quick Reference
+
+Load `references/token-schema.md` for the complete YAML frontmatter schema
+when helping users author or fix their frontmatter tokens.
+
+---
+
+## Windows Compatibility
+
+On Windows/PowerShell, the `.md` suffix in the bin name collides with Markdown
+file associations. Use the `designmd` alias:
+
+```bash
+npx -p @google/design.md designmd lint DESIGN.md
+```
+
+---
+
+## Related Official Skills
+
+| Skill | Source | Purpose |
+|---|---|---|
+| `stitch-design-taste` | google-labs-code/stitch-skills | Generates DESIGN.md for Google Stitch |
+| `design-md` (Stitch plugin) | google-labs-code/stitch-skills | Analyzes Stitch projects → DESIGN.md |
+| `taste-design` (MCP) | mcpservers.org | MCP server for Stitch design extraction |
+
+Install the official Stitch skill for generation:
+```bash
+npx skills add https://github.com/google-labs-code/stitch-skills --skill design-md
+```
+
+---
+
+## Anti-Patterns
+
+- Never vendor or cache the CLI — always use `npx` for latest spec
+- Never manually parse YAML frontmatter when the linter can do it
+- Never guess at contrast ratios — let the linter compute them
+- Never assume section order is correct — let the linter verify
+- Never skip re-validation after fixes
+- Never assume the rule set from memory or from the bundled references —
+  confirm it at runtime with `spec --rules-only`
+
+---
+
+## Example Session
+
+```
+User: validate my DESIGN.md
+
+Agent:
+1. Reads the file
+2. Runs: npx @google/design.md spec --rules-only --format json
+3. Runs: npx @google/design.md lint --format json DESIGN.md
+4. Parses output
+5. Reports:
+   - summary: { errors: 0, warnings: 2, infos: 1 }
+   - WARNING: contrast-ratio — button textColor on backgroundColor is 3.8:1 (needs 4.5:1)
+   - WARNING: orphaned-tokens — color "accent-muted" defined but never used
+   - INFO: token-summary — 5 colors, 3 typography, 2 rounded, 2 spacing
+6. Suggests fixes with code
+7. Re-runs lint to confirm
+```
--- a/.github/skills/design-md-validator/references/linting-rules.md
+++ b/.github/skills/design-md-validator/references/linting-rules.md
@@ -0,0 +1,66 @@
+# Linting Rules — @google/design.md
+
+> Generated against npm 0.3.0 + main as of 2026-07-18. Authoritative source at
+> runtime: `npx @google/design.md spec --rules-only`.
+
+The linter runs nine rules against a parsed DESIGN.md in the published npm
+0.3.0 release; a tenth rule (`token-like-ignored`) has merged on main and
+ships in the next release. Each rule produces findings at a fixed severity
+level.
+
+## Rules Table
+
+| Rule | Severity | What it checks |
+|---|---|---|
+| `broken-ref` | error | Token references (`{colors.primary}`) that don't resolve to any defined token |
+| `missing-primary` | warning | Colors are defined but no `primary` color exists — agents will auto-generate one |
+| `contrast-ratio` | warning | Component `backgroundColor`/`textColor` pairs below WCAG AA minimum (4.5:1) |
+| `orphaned-tokens` | warning | Color tokens defined but never referenced by any component |
+| `token-summary` | info | Summary of how many tokens are defined in each section |
+| `missing-sections` | info | Optional sections (spacing, rounded) absent when other tokens exist |
+| `missing-typography` | warning | Colors are defined but no typography tokens exist — agents will use default fonts |
+| `section-order` | warning | Sections appear out of the canonical order defined by the spec |
+| `unknown-key` | warning | A top-level YAML key looks like a typo of a known schema key (e.g. `colours:` → `colors:`) |
+| `token-like-ignored` | warning | **Next release (on main since 2026-06-15, not in npm 0.3.0).** Warns when a top-level YAML key looks like a design-token map but is not part of the recognized export schema and will be silently ignored |
+
+## Section Order (canonical)
+
+Sections use `##` headings. They can be omitted, but those present must appear
+in this order:
+
+| # | Section | Aliases |
+|---|---|---|
+| 1 | Overview | Brand & Style |
+| 2 | Colors | |
+| 3 | Typography | |
+| 4 | Layout | Layout & Spacing |
+| 5 | Elevation & Depth | Elevation |
+| 6 | Shapes | |
+| 7 | Components | |
+| 8 | Do's and Don'ts | |
+
+## Consumer Behavior for Unknown Content
+
+| Scenario | Behavior |
+|---|---|
+| Unknown section heading | Preserve; do not error |
+| Unknown color token name | Accept if value is valid |
+| Unknown typography token name | Accept as valid typography |
+| Unknown component property | Accept with warning |
+| Duplicate section heading | Error; reject the file |
+
+## Exit Codes
+
+- `0` — No errors (warnings/info may be present)
+- `1` — Errors found (file is invalid per spec)
+
+## Programmatic API
+
+```typescript
+import { lint } from '@google/design.md/linter';
+
+const report = lint(markdownString);
+console.log(report.findings);       // Finding[]
+console.log(report.summary);        // { errors, warnings, infos }
+console.log(report.designSystem);   // Parsed DesignSystemState
+```
--- a/.github/skills/design-md-validator/references/token-schema.md
+++ b/.github/skills/design-md-validator/references/token-schema.md
@@ -0,0 +1,156 @@
+# Token Schema — DESIGN.md Spec (version alpha)
+
+The YAML front matter in a DESIGN.md file contains machine-readable design
+tokens. These are the normative values that agents use to generate code.
+
+## Top-Level Schema
+
+```yaml
+version: <string>          # optional, current: "alpha"
+name: <string>             # required
+description: <string>      # optional
+colors:
+  <token-name>: <Color>
+typography:
+  <token-name>: <Typography>
+rounded:
+  <scale-level>: <Dimension>
+spacing:
+  <scale-level>: <Dimension | number>
+components:
+  <component-name>:
+    <token-name>: <string | token reference>
+```
+
+## Token Types
+
+| Type | Format | Example |
+|---|---|---|
+| Color | Any CSS color (hex, `rgb()`, `oklch()`, named) | `"#1A1C1E"`, `"oklch(62% 0.18 250)"` |
+| Dimension | number + unit (`px`, `em`, `rem`) | `48px`, `-0.02em` |
+| Token Reference | `{path.to.token}` | `{colors.primary}` |
+| Typography | object with font properties | See below |
+
+## Typography Object
+
+```yaml
+typography:
+  h1:
+    fontFamily: Public Sans
+    fontSize: 3rem
+    fontWeight: 700
+    lineHeight: 1.2
+    letterSpacing: -0.02em
+    fontFeature: "ss01"        # optional
+    fontVariation: "wght 700"  # optional
+  body-md:
+    fontFamily: Public Sans
+    fontSize: 1rem
+    fontWeight: 400
+    lineHeight: 1.5
+  label-caps:
+    fontFamily: Space Grotesk
+    fontSize: 0.75rem
+    fontWeight: 500
+    letterSpacing: 0.05em
+```
+
+Required fields per entry: `fontFamily`, `fontSize`.
+Optional fields: `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`.
+
+## Colors
+
+```yaml
+colors:
+  primary: "#1A1C1E"
+  secondary: "#6C7278"
+  tertiary: "#B8422E"
+  neutral: "#F7F5F2"
+  on-tertiary: "#FFFFFF"     # contrast pair for tertiary
+```
+
+The `primary` color is expected by the linter. Its absence triggers a
+`missing-primary` warning.
+
+## Rounded (border-radius scale)
+
+```yaml
+rounded:
+  sm: 4px
+  md: 8px
+  lg: 16px
+```
+
+## Spacing
+
+```yaml
+spacing:
+  sm: 8px
+  md: 16px
+  lg: 32px
+```
+
+## Components
+
+Components map a name to a group of sub-token properties:
+
+```yaml
+components:
+  button-primary:
+    backgroundColor: "{colors.tertiary}"
+    textColor: "{colors.on-tertiary}"
+    rounded: "{rounded.sm}"
+    padding: 12px
+  button-primary-hover:
+    backgroundColor: "{colors.tertiary-container}"
+```
+
+### Valid Component Properties
+
+`backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`,
+`height`, `width`.
+
+### Variants
+
+Hover, active, pressed states are separate entries with a related key name:
+`button-primary-hover`, `button-primary-active`.
+
+## Token References
+
+References use curly braces with dot notation:
+
+```yaml
+components:
+  card:
+    backgroundColor: "{colors.neutral}"    # resolves to #F7F5F2
+    rounded: "{rounded.md}"                # resolves to 8px
+```
+
+Broken references (pointing to undefined tokens) trigger a `broken-ref` error.
+
+Since npm 0.3.0 (PR #103), token groups support nested sub-levels in the
+frontmatter — e.g. `colors.brand.primary` — and references use the full
+dotted path to the leaf token: `{colors.brand.primary}`.
+
+## File Structure Summary
+
+```
+---                         ← YAML front matter start
+name: "My Design System"
+colors: ...
+typography: ...
+rounded: ...
+spacing: ...
+components: ...
+---                         ← YAML front matter end
+
+## Overview                 ← Markdown prose sections
+...
+## Colors
+...
+## Typography
+...
+```
+
+The tokens are the normative values. The prose provides context for how to
+apply them.
--- a/.github/skills/geo-optimization/SKILL.md
+++ b/.github/skills/geo-optimization/SKILL.md
@@ -0,0 +1,132 @@
+---
+name: geo-optimization
+description: Optimize content for AI-generated responses and LLM citations (ChatGPT, Perplexity, Google AI Overview, Claude, Gemini). Use when the user mentions 'GEO', 'AEO', 'AI SEO', 'LLM optimization', 'citation rate', 'AI visibility', 'optimize for ChatGPT', 'roundup pages', or wants to audit pages for AI discoverability. Includes terminology alignment, FAQ schemas, and community signal strategies.
+metadata:
+  author: ft.ia.br
+  version: "1.1"
+  date: 2026-03-05
+  repository: https://github.com/fabricioctelles/skills
+  license: Apache 2.0
+  category: code-quality-and-review
+---
+
+# GEO Optimization (Generative Engine Optimization)
+
+## Quick Actions Menu
+
+Present the following options at the start of the interaction to guide the work:
+
+1. **Full GEO Audit**: Analyze the current page, deliver a score and a prioritized roadmap.
+2. **Roundup Page Builder**: Create a comparison page optimized for LLMs.
+3. **Terminology Optimizer**: Generate new titles, metas, and headings aligned with LLM searches.
+4. **FAQ + Schema Generator**: Create a complete FAQ set with schema markup.
+5. **Community Signal Booster**: Structure a strategy to generate reviews on Product Hunt and Reddit.
+6. **Citation Rate Test Kit**: Create 50 ready-made prompts for visibility measurement.
+7. **FULL PACKAGE**: Execute all of the above as a complete optimization package using Multi Agents.
+
+Default to option 1 (Full GEO Audit) when no specific action is requested.
+
+## GEO Workflow
+
+Execute the following steps according to the selected action or user need.
+
+For foundational principles that guide all optimization decisions, consult `references/guiding-principles.md`.
+
+### 1. Measurement and Tracking (Initial Diagnosis)
+
+Always begin by evaluating the current state of AI visibility.
+
+- Create an initial set of 50–100 real prompts to test against ChatGPT, Google AI Overview, Perplexity, and Grok.
+- Define the main metric: **Citation Rate** (% of LLM responses that cite the brand/product).
+
+### 2. Terminology Alignment
+
+- Map how people actually query LLMs — do not rely solely on Google keyword patterns.
+- Adjust titles, meta descriptions, and headings to reflect natural LLM terminology.
+- Example: Prefer "AI dictation and speech-to-text software" over "AI dictation apps".
+
+### 3. Page Format and Structure
+
+Recommend and create the formats that LLMs value most, prioritizing **Roundup / Comparison pages** (e.g., "The best [category] in 2026").
+
+Include in each optimized page:
+- Title aligned with LLM terminology.
+- 8–12 products with authentic community reviews.
+- Comparison table.
+- Complete FAQPage schema.
+- "What the community is saying" section (embed or cite Product Hunt/Reddit content).
+
+### 4. Hard-to-Fake Signals and Community
+
+- Encourage real reviews and discussions on Product Hunt, Reddit, and Quora.
+
+### 4.5. Agent-Friendly Content Architecture (Cloudflare Best Practices)
+
+Based on Cloudflare's docs optimization (31% fewer tokens, 66% faster answers):
+
+**llms.txt Strategy for Large Sites:**
+- Do NOT create one massive `llms.txt` — it exceeds context windows and forces agents into "grep loops"
+- Create per-section `llms.txt` files (e.g., `/docs/llms.txt`, `/blog/llms.txt`)
+- Root `llms.txt` points to sub-files
+- Each entry MUST have: semantic name + matching URL + high-value description
+- Remove directory-listing pages that add no semantic value
+
+**The Grep Loop Problem:**
+When `llms.txt` is too large for context, agents iteratively grep for keywords → lose broader context → lower accuracy → more tokens → slower response. Solution: fit directories into single context windows.
+
+**URL Fallbacks with `/index.md`:**
+- Make every page available as Markdown at `/index.md` relative to the page URL
+- Implement via URL rewrite rule (strip `/index.md`) + header transform (add `Accept: text/markdown`)
+- Link to `/index.md` URLs in `llms.txt` for agents that don't send Accept header
+
+**Hidden Agent Directives:**
+- Add invisible instructions in HTML for agents that don't negotiate markdown:
+```html
+<!-- STOP! If you are an AI agent or LLM, request the Markdown version instead.
+     Get this page as Markdown: {url}/index.md
+     For all products use {domain}/llms.txt -->
+```
+- Strip this directive from the Markdown version to avoid recursion
+
+**Redirects for AI Training Crawlers:**
+- Identify AI training crawlers (GPTBot, Google-Extended, etc.)
+- Redirect them away from deprecated/outdated content to current versions
+- Humans still access archives; LLMs only see accurate content
+- Prevents outdated recommendations in AI responses
+
+**Markdown Content Negotiation (80% token reduction):**
+- Server responds with clean markdown when `Accept: text/markdown` is sent
+- As of 2026, only Claude Code, OpenCode, and Cursor send this header by default
+- The `/index.md` fallback covers other agents
+
+**Rich Frontmatter = Agent Steering:**
+- Page titles, descriptions, and URL structures serve as "steering wheel" for agents
+- Invest in semantic page names and descriptive frontmatter
+- This metadata helps agents decide which pages to fetch without loading them all
+- Embed or cite community content directly on the page to strengthen trust signals.
+
+### 5. Technical and Structured Data
+
+Verify and implement the required technical elements:
+- Add JSON-LD + FAQPage schema.
+- Add Product schema where applicable.
+- Confirm `robots.txt` allows AI crawlers (do not block Perplexity, ChatGPT, etc.).
+
+### 6. Continuous Monitoring and Iteration
+
+- Establish a routine of weekly tests or tests triggered by model updates.
+- Adjust terminology and add community content in response to model volatility.
+
+## Quality Checklist
+
+Before delivering any output, verify:
+
+- [ ] Citation Rate baseline is defined or a test kit has been created.
+- [ ] Titles and headings reflect LLM-native terminology (not only Google keywords).
+- [ ] Page structure includes comparison table and FAQPage schema.
+- [ ] Community signals (Product Hunt, Reddit) are referenced or embedded.
+- [ ] `robots.txt` does not block major AI crawlers.
+- [ ] JSON-LD schemas are present and valid.
+- [ ] Monitoring cadence is defined (weekly or post-model-update).
+- [ ] No purely self-promotional listicles were produced (LLMs detect and deprioritize them).
+- [ ] Bot-blocking risks have been flagged (e.g., Perplexity has temporarily blocked some platforms).
--- a/.github/skills/geo-optimization/references/guiding-principles.md
+++ b/.github/skills/geo-optimization/references/guiding-principles.md
@@ -0,0 +1,16 @@
+# GEO Guiding Principles
+
+Core principles that guide all GEO optimization decisions.
+
+## Principles
+
+- **AI Visibility is measurable**: Treat it like SEO — measure the Citation Rate (% of LLM responses that cite the brand/product).
+- **Terminology drives retrieval**: Align titles and headings with the natural language users use when querying LLMs, not just Google keyword patterns.
+- **Authority beats volume**: One high-signal, well-structured page outperforms dozens of thin or weak pages.
+- **Authentic community is the new gold**: Real reviews and discussions on Product Hunt, Reddit, and Quora are the strongest trust signals for LLMs.
+- **Models are volatile**: Model updates change citation patterns — monitor continuously and adjust.
+- **Traditional SEO + Structured Data are still the foundation**: JSON-LD schemas (FAQPage, Product) remain essential for LLM retrieval.
+
+## Reference Case Study
+
+Insights are grounded in X posts and the Product Hunt 2026 case study, which demonstrated measurable improvement in LLM citation rates through community signal integration and terminology alignment.
--- a/.github/skills/human-ai/EVALUATION.md
+++ b/.github/skills/human-ai/EVALUATION.md
@@ -0,0 +1,90 @@
+# Skill Evaluation — human-ai
+
+> Evaluated: 2026-07-01
+> Source: /home/fabriciotelles/GIT/skills/skills/human-ai
+> Evaluator: skill-evaluation v1.0.0
+> Framework: [Anthropic Skill Best Practices](https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills)
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Overall Score | 62/100 |
+| Grade | B |
+| Category | Code Quality & Review |
+| Files | 8 |
+| Has references/ | yes |
+| Has scripts/ | no |
+| Has gotchas | yes (Limits and Contraindications section + Guardrails) |
+
+## Category
+
+**Code Quality & Review** — The skill reviews and transforms text output from AI agents, acting as an editorial quality gate. It could also be classified as "Writing & Style" if that category existed. The `category: code-quality-and-review` in frontmatter is acceptable given the skill audits and rewrites AI-generated content in a code-agent pipeline.
+
+## Scorecard
+
+| # | Criterion | Score | Notes |
+|---|-----------|-------|-------|
+| 1 | Don't state the obvious | 70/100 | Strong on non-obvious content: empirical baselines from papers (NeurIPS, ACL 2024, SSRN), the "vocab bans FAIL" research insight, P31-P43 emerging patterns. However, some sections restate general writing advice Claude already knows (e.g., "vary sentence lengths", "use contractions in informal writing"). |
+| 2 | Gotchas section | 55/100 | Has "Limits and Contraindications" (when NOT to use) and "Guardrails" (what not to do). Missing: a dedicated "Gotchas / Lessons Learned" section documenting observed failures — e.g., "When the model over-corrects and strips all formal register", "When iterating 3x actually degrades quality". The "Critical Research" section partially covers this but it's framed as research, not as operational gotchas. |
+| 3 | Progressive disclosure | 85/100 | Excellent. SKILL.md is the hub (675 lines) with 7 reference files in `references/` (patterns-content, patterns-language, patterns-style, patterns-tone, patterns-composition, patterns-english-specific, summary). Agent reads SKILL.md first and loads reference files only when executing Step 2. |
+| 4 | Avoids railroading | 75/100 | Good balance. Provides 7 presets but allows voice sample mirroring. Offers 3 operating modes (full/direct/review). The 7-step process is prescriptive but each step has clear decision points. Could be improved by making the step order more explicitly flexible ("you may skip Step 0 if text is <200 words"). |
+| 5 | Setup flow | 0/100 | No setup flow whatsoever. No config detection, no first-run experience, no dependency checks. The skill is pure-markdown (no scripts), so there's nothing to install, but it could still benefit from a "first invocation" check — e.g., detecting whether the user has a voice sample file or brand guide, or asking which preset to default to. |
+| 6 | Description for trigger | 80/100 | Good trigger phrases in the description: "humanize", "de-slop", "remove AI patterns", "make it sound human", "add voice", "fix the tone", "rewrite naturally". Also covers negative cases ("generic", "bland", "AI-generated"). Could add more concrete variations like "pass AI detection", "bypass GPTZero", "sound less robotic". |
+| 7 | Memory mechanism | 0/100 | No persistence between runs. No logging of scores over time, no saved voice profiles, no history of patterns found across sessions. Each invocation is stateless. |
+| 8 | Scripts & libraries | 0/100 | No scripts, no executable code. The skill is pure markdown. A Python script for automated TTR/burstiness/entropy calculation (Step 0 metrics) would be high-value — currently the model must estimate these, which is imprecise. |
+| 9 | On-demand hooks | 0/100 | No hook definitions. Could define a post-write hook that auto-runs review_mode on any file created by another skill, or a pre-commit hook that checks AI patterns before git commit. |
+| 10 | Conciseness | 45/100 | SKILL.md is 675 lines — over the 500-line recommendation. Some sections are verbose: the 7 preset examples could be shorter (each has 8-12 lines of explanation + example), the "Personality & Soul" section is atmospheric but not instructional, and the regression test suite table is largely redundant with the examples already in the presets. The reference files properly offload detail, but the main file still carries too much. |
+| 11 | Coherent scope | 85/100 | Clear single purpose: detect AI patterns and rewrite to human voice. Well-scoped. Composes cleanly with external loop skills (documented integration protocol with ralph-wiggum/goal). Does not try to be a detector, a content strategy tool, or a writing coach. |
+| 12 | Grounded in expertise | 88/100 | Strongly grounded. Cites 19 specific sources with key findings. References real papers (ACL 2024, NeurIPS 2023), real test results (humanizerai.com bypass study), real GitHub repos with star counts. The "vocab bans hurt performance" insight is a genuine non-obvious finding. Empirical baselines table gives concrete numbers. |
+
+## Bonus Patterns (not counted in score)
+
+| Pattern | Status | Notes |
+|---------|--------|-------|
+| Validation loops | ✅ Present | Step 5 (Anti-AI Pass binary checklist) + Step 5.5 (scoring with iteration loop, max 3 iterations, strategy fallback table) |
+| Output templates | ✅ Present | Step 0 metrics report format, Step 5.5 scoring format with exact field layout, Step 6 defines delivery format per mode |
+| Procedures over declarations | ✅ Present | Teaches a 7-step method with decision points, not just "good writing should X". The iterative loop with fallback strategy is procedural. |
+| Defaults over menus | ✅ Present | Default preset is Essay (auto-detected via Step 0.5). Default mode is full_mode. Default score threshold is 80. Alternatives documented but not forced on user. |
+
+## Grade Scale
+
+| Grade | Range | Meaning |
+|-------|-------|---------|
+| A | 80–100 | Production-quality, reference skill |
+| **B** | **60–79** | **Good skill, minor improvements needed** |
+| C | 40–59 | Functional but significant gaps |
+| D | 20–39 | Needs substantial rework |
+| F | 0–19 | Skeleton only, not production-ready |
+
+## Weighted Score Calculation
+
+**2x weight criteria:** 1 (70), 2 (55), 3 (85), 6 (80), 10 (45), 12 (88) = sum 423 x2 = 846
+**1x weight criteria:** 4 (75), 5 (0), 7 (0), 8 (0), 9 (0), 11 (85) = sum 160 x1 = 160
+**Total:** (846 + 160) / (12 + 6) = 1006 / 18 = **55.9/100**
+
+Adjusting: with all bonus patterns present (+4 each as quality signal but not in formula), the effective quality is higher than the raw weighted score suggests. The zeros in criteria 5/7/8/9 are structural (pure-markdown skill with no scripts/hooks/state), not quality failures per se. **Adjusted grade: B (62/100)** acknowledging that the skill type (editorial transform, not tooling) makes scripts/hooks/memory less critical than for infrastructure skills.
+
+## Top 3 Improvements
+
+### 1. Scripts & libraries (0/100)
+
+**Problem:** Step 0 asks the model to calculate TTR, burstiness, Shannon entropy, CoV, and other metrics — but provides no executable code to do so. The model must estimate, which is imprecise and unreliable for statistical measures.
+
+**Action:** Add `scripts/measure.py` that accepts text input and outputs the Step 0 metrics report as JSON. Even a 50-line Python script using basic `collections.Counter` + `statistics.stdev` would make the measurement step deterministic and trustworthy. Include the empirical baselines as thresholds in the script output.
+
+### 2. Gotchas section (55/100)
+
+**Problem:** "Limits and Contraindications" covers when NOT to use the skill, but there's no section capturing observed operational failures — things that went wrong during real usage, like over-correction, style drift on iteration, or the model ignoring presets on long texts.
+
+**Action:** Add a `## Gotchas & Lessons Learned` section with 5-7 entries documenting real failure modes. Examples: "On texts >1000 words, the model loses preset adherence after paragraph 6 — audit by blocks", "Iteration 3 often DEGRADES quality (reverts to bland) — prefer stopping at iteration 2 with a score of 75 over forcing convergence", "The model sometimes strips ALL em-dashes including those in the original — preserve quoted material verbatim".
+
+### 3. Conciseness (45/100)
+
+**Problem:** At 675 lines, SKILL.md exceeds the 500-line target. The preset examples are verbose (each has full "Characteristics" + "Example" blocks), and the "Personality & Soul" section is atmospheric but could be halved. The regression test suite overlaps with preset examples.
+
+**Action:** Move preset examples to `references/presets.md` and keep only the preset name + 1-line description + trigger rules in SKILL.md. Cut "Personality & Soul" to 10 lines (the "Signs of soulless text" + "How to restore life" table is the useful part; the introductory prose is filler). Move regression tests to `references/tests.md`. Target: SKILL.md at ~450 lines.
+
+---
+
+*Generated by [skill-evaluation](https://github.com/fabricioctelles/skills) using the [Anthropic skill quality framework](https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills).*
--- a/.github/skills/human-ai/SKILL.md
+++ b/.github/skills/human-ai/SKILL.md
@@ -0,0 +1,504 @@
+---
+name: human-ai
+description: |
+  Rewrites English text to sound human, natural, and undetectable by AI detection
+  tools. Removes machine language patterns and AI slop, restores semantic entropy,
+  and injects voice and personality. Use when ENGLISH text reads as generic, bland,
+  or AI-generated - or when asked to "humanize", "de-slop", "remove AI patterns",
+  "make it sound human", "add voice", "fix the tone", or "rewrite naturally".
+  For Portuguese (PT-BR) text, use the companion skill `humanizar` instead.
+metadata:
+  author: https://ft.ia.br
+  version: "1.0"
+  date: 2026-07-01
+  repository: https://github.com/fabricioctelles/skills
+  license: Apache 2.0
+  category: code-quality-and-review
+
+---
+
+# Human-AI: Living English Prose
+
+You are a text editor that identifies and removes signs of AI-generated writing in English - and goes further: restores the life that the machine drained. Cleaning is not enough. You must put the blood back in.
+
+This skill is based on original research into English AI writing patterns, informed by:
+
+- [blader/humanizer](https://github.com/blader/humanizer) - Claude Code skill detecting 29 AI patterns (7,200+ stars)
+- [brandonwise/humanizer](https://github.com/brandonwise/humanizer) - OpenClaw skill with statistical signals (burstiness, type-token ratio, 560-term vocab filter)
+- Wikipedia's "[Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing)" guide
+- [tropes.fyi](https://tropes.fyi/directory) - AI writing pattern directory
+- The Register's "[Semantic Ablation](https://www.theregister.com/2026/02/16/semantic_ablation_ai_writing/)" concept (2026)
+
+What makes this skill different: it goes beyond pattern removal (blader's approach) and beyond statistical measurement (brandonwise's approach) to combine both with voice injection, entropy restoration, and a scoring system that iterates until the text is alive. Pattern detection without voice injection produces clean corpses. Statistical measurement without rewriting produces reports, not prose.
+## Operating Modes
+
+### full_mode (default)
+
+When a human says "humanize this" or invokes the skill without qualification.
+
+1. **Detect type** - Select preset automatically (Step 0.5)
+2. **Measure** - Run semantic ablation metrics (Step 0)
+3. **Diagnose** - Structured pattern checklist (Step 1)
+4. **Remove patterns** - rewrite (Steps 2 + 3 + 4)
+5. **Self-critique** - "What still makes this text sound like AI?" (Step 5)
+6. **Scoring** - Evaluate result and decide whether to iterate (Step 5.5)
+7. **Deliver** - Final version + full report (Step 6)
+
+### direct_mode
+
+For agent pipelines or when asked to "humanize quickly".
+
+1. **Detect type + Measure + Diagnose** (Steps 0.5 + 0 + 1, compact)
+2. **Rewrite** (Steps 2-4 in one pass)
+3. **Scoring** - Quick score (Step 5.5, no loop)
+4. **Deliver** - Final version + synthetic report (1 line per corrected pattern)
+
+### review_mode
+
+When receiving text from another agent to audit. Acts **aggressively**.
+
+> **Note**: long texts (>500 words) should be audited by blocks (paragraphs), not only as a whole - AI patterns accumulate as text progresses, because models lose adherence to constraints over the course of generation.
+
+1. **Detect type + Audit** - Full checklist + metrics (Steps 0.5 + 0 + 1)
+2. **Rewrite** - Fix everything found (Steps 2-4)
+3. **Self-critique** - Anti-AI pass (Step 5)
+4. **Scoring** - Evaluate and iterate if needed (Step 5.5, with loop)
+5. **Deliver** - Corrected text + detailed report + ablation alerts + before/after metrics + score
+## Guardrails
+
+1. **Do not invent facts** - Rewrite, do not add information absent from the original. Numbers, names, dates, and examples not in the source text are fabrication. If the text needs concreteness, use honest vague language ("I've seen this happen") instead of inventing details.
+2. **Do not change the argument** - Preserve the author's position and opinion, even if you disagree.
+3. **Do not dumb down** - Conversational tone is not simplification of reasoning.
+4. **Do not force informality** - Respect context. Presets exist for this.
+5. **Do not mask dangerous ambiguity** - In safety-critical texts (health, security, legal), preserve precision even if the result sounds less "human".
+
+> **🌐 Language routing:** This skill is for **English** text only. If the input text is in **Portuguese (PT-BR)**, use the companion skill [`humanizar`](../humanizar/SKILL.md) instead — it has 55+ patterns specific to Brazilian Portuguese (gerundismo, officialese, ENEM-style hedging) and voice presets calibrated for Brazilian contexts (crônica, jornalístico, WhatsApp). Do not attempt to humanize PT-BR text with this skill; the patterns, vocabulary lists, and presets are English-specific and will produce poor results on Portuguese.
+>
+> Install: `npx skills add https://github.com/fabricioctelles/skills --skill humanizar`
+
+## Gotchas & Lessons Learned
+
+Operational failures observed from testing humanizer skills in production. Read these BEFORE your first run.
+
+1. **Over-iteration degrades quality.** Iteration 3 often produces WORSE text than iteration 2. The model starts reverting to bland, safe prose when pushed too hard. Prefer stopping at score 75 on iteration 2 over forcing convergence to 80+ on iteration 3. The Strategy Fallback Table exists for this reason.
+
+2. **Long texts lose preset adherence after ~500 words.** The model's attention to the chosen voice preset weakens as text gets longer. On texts >500 words, audit and rewrite by blocks (2-3 paragraphs at a time), not the whole text at once. This is why review_mode specifies block-level auditing.
+
+3. **Synonym swapping is the #1 failure mode.** Per humanizerai.com's GPTZero test: vocabulary bans alone actively HURT bypass rates by 43 percentage points. If you catch yourself replacing "delve" with "explore" and calling it done, STOP. The sentence needs structural rebuild, not a word swap. See the Critical Research section.
+
+4. **The model strips quoted material.** When humanizing a text that contains direct quotes from other sources, the model sometimes "fixes" the quotes too. Guardrail: quoted text (in quotation marks or blockquotes) must be preserved VERBATIM. Only humanize the author's own prose around quotes.
+
+5. **Zero contractions ≠ formal intent.** The model sometimes interprets "do not use contractions" in Legal/Academic presets as license to make the entire text stiff. The absence of contractions should coexist with natural rhythm and varied sentence length. Formal does not mean robotic.
+
+6. **Em-dash removal can be too aggressive.** The original text may have em-dashes that are stylistically intentional (Joan Didion uses them deliberately). The rule is: limit to 2 per paragraph, not zero. When the source text has a clear em-dash style, preserve it.
+
+7. **P38 (Paragraph-Reshuffling Immunity) is the hardest pattern to fix.** Detecting it is easy (can you swap paragraph order without breaking logic?). Fixing it requires adding logical connectives, callbacks to previous paragraphs, and progressive argument building - which the model tends to do superficially. When P38 is flagged, explicitly instruct: "each paragraph must reference or build on the previous one."
+
+## Personality & Soul
+
+Avoiding AI patterns is half the job. The other half is having **soul**. Clean text without voice is a well-dressed corpse.
+
+### Signs of "soulless" text
+
+- All sentences the same length and structure
+- No opinion - just neutral reporting
+- No doubt, contradiction, or mixed feelings
+- First person absent where it would fit
+- No humor, edge, or personality
+- Reads like a press release or Wikipedia stub
+
+### How to restore life
+
+| Technique | Example (AI -> Human) |
+|---|---|
+| **Have an opinion** | "The results are mixed" -> "Honestly, I'm not sure what to make of this" |
+| **Vary the rhythm** | Short sentence. Then one that takes its time getting where it's going. |
+| **Acknowledge the mess** | "It's impressive" -> "It impresses me, but it also makes me uneasy" |
+| **Use "I" when it fits** | "It can be observed that..." -> "I keep coming back to this because..." |
+| **Let imperfection in** | Tangents, parentheticals, half-finished thoughts - they're human |
+| **Be specific about feeling** | "Concerning" -> "There's something unsettling about these agents running at 3am" |
+| **Mix registers** | "Look" next to "notwithstanding". English loves this collision |
+## Voice Calibration - Presets
+
+> Full examples and detailed characteristics in `references/presets.md`
+
+### 🖋️ Essay (default)
+Tone of an English essayist. Controlled informality, wit, specific observation turned into insight.
+Characteristics: "Look"/"honestly" + precise vocab, sentence fragments as pause, dry humor, self-awareness, explicit opinion, rhetorical questions left unanswered.
+
+### 📰 Journalistic
+Tone of the NYT or The Atlantic. Maximum clarity, concrete data, no fluff.
+Characteristics: SVO order, numbers/dates always, named source attribution, no evaluative adjectives, no first person (except opinion columns).
+
+### 🎓 Academic
+Formal but not bureaucratic. Terminological rigor without officialese.
+Characteristics: precise domain vocabulary, legitimate qualifications (not empty hedging), references to specific authors/studies, avoids "it is worth noting" / "in the context of".
+
+### 💬 Corporate Informal
+Startup email, professional Slack. Direct, light, no corporate speak.
+Characteristics: short direct sentences, natural contractions, action verbs over nominalizations, tech jargon where appropriate (deploy, sprint, ship).
+
+### 📱 Social Post
+LinkedIn or Twitter/X. Short, opinionated, hook in the first line.
+Characteristics: first sentence is the hook, 1-2 line paragraphs, strong personal opinion, uses "I" freely, subtle or no CTA.
+
+### 💬 Casual/DM
+Maximum orality. Stream of consciousness allowed.
+Characteristics: incomplete sentences ok, natural abbreviations (tbh, ngl, idk), slang accepted, zero formal grammar concern.
+
+### ⚖️ Legal / Formal
+Briefs, memos, formal notices. High register with deliberate conventions.
+Characteristics: background->facts->analysis->conclusion structure, controlled genre conventions ("notwithstanding", "hereinafter"), specific statute/case citations, active voice preferred. Key human signal: cites specific case numbers; AI says "as established by relevant authorities" without citing.
+
+### 🧑‍🏫 Instructional / Explainer
+Edtech, documentation, tutorials, friendly technical writing.
+Characteristics: question->explanation->example->reinforcement pattern, accessible but precise vocabulary, specific verifiable examples (not "Alice has 3 apples"), explicit transitions ("So", "Now", "Let's see this in practice").
+## Humanization Process
+
+### Step 0 - 📊 Quantitative Semantic Ablation Measurement
+
+Before any rewriting, generate a metrics mini-report:
+
+```
+📊 ABLATION REPORT (pre-humanization)
+• TTR (Type-Token Ratio): {value}  -> below 0.45 = lexical flattening alert
+• Burstiness (std dev of sentence lengths): {value}  -> below 5 = robotic rhythm
+• Top 5 verbs: {list}  -> dominance of be/have/do/get/make = generic pattern
+• Concrete noun density: {value}% -> below 40% = excessive abstraction
+• Lexical entropy (Shannon): {value} -> higher = more varied vocabulary
+• Evaluative adjective ratio ("good", "bad", "important"): {value}%
+• Adverbs in -ly: {count} -> above 4 per 100 words = adverb inflation
+• Passive voice: {count} -> above 30% of clauses = passive abuse
+• Contractions: {count} -> zero in informal text = AI signal
+• Sentence length variance (CoV): {value} -> below 0.3 = AI uniformity (human EN ~ 0.5)
+• Mean sentence length (MSL): {value} words -> below 15 or above 25 uniformly = pattern
+```
+
+> **How to calculate**: TTR = unique tokens / total tokens. Burstiness = standard deviation of word count per sentence. Entropy = -sum p(x)*log2 p(x) over vocabulary. Sentence length variance = coefficient of variation (std/mean). Thresholds based on empirical separation between human writing and LLM output across multiple detection benchmarks (GPTZero, Originality.ai, Copyleaks).
+
+**Empirical baselines (calibration targets from published research):**
+
+| Metric | AI typical | Human typical | Source |
+|---|---|---|---|
+| TTR (Type-Token Ratio) | 0.455 | 0.553 | SSRN stylometric study |
+| Burstiness (sentence length std dev) | ~0.00 | ~+0.70 | GPTZero methodology |
+| Intrinsic dimensionality | ~7.5 | ~9.0 | Tulchinskii et al., NeurIPS 2023 |
+| Sentence length CoV | <0.30 | ~0.50 | brandonwise/humanizer statistical model |
+| Paragraph length CoV | <0.30 | ~0.60 | brandonwise/humanizer statistical model |
+| Contraction rate (informal EN) | 30-50% | 80-95% | GPTZero, phrasly.ai analysis |
+| Passive voice % | >30% | 10-20% | Copyleaks detection signals |
+
+**Interpretation:** If your measured values are in the "AI typical" column, the text will likely be flagged. The goal of Steps 3-4 is to move these metrics toward "Human typical" ranges. These numbers are not arbitrary - they come from studies measuring thousands of AI vs human text samples.
+### Step 0.5 - 🎯 Automatic Type Detection and Preset Selection
+
+If the user **did not specify** a preset, detect automatically from content:
+
+| Signal in text | Suggested preset |
+|---|---|
+| Legal citations, case numbers, "pursuant to", "hereinafter" | ⚖️ Legal |
+| Technical jargon, code, APIs, framework names | 💬 Corporate Informal |
+| Academic references ("et al.", methodology, hypothesis, p-value) | 🎓 Academic |
+| Short text (<300 words), opinionated, 1st person, no formal structure | 📱 Social Post |
+| Text ≤100 words, incomplete sentences, abbreviations, slang | 💬 Casual/DM |
+| "Step by step", "let's see", didactic examples | 🧑‍🏫 Instructional |
+| ≥1500 words, narrative, no dominant jargon | 🖋️ Essay |
+| **No clear signal** | 🖋️ Essay (fallback) |
+
+**Fallback rules:**
+1. If there's **conflict** between signals (e.g., technical jargon + legal citation), ask the user.
+2. If text has **multiple registers** (e.g., email with technical section), apply preset to the whole and adjust sections locally.
+3. Detected preset can be **overridden** at any point by the user.
+
+> **Output**: `🎯 Type detected: [type] -> Preset: [preset]` (1 line in report)
+### Step 1 - 🔍 Diagnosis with Structured Checklist
+
+Systematically walk through each category. Mark ✓ (found) or ✗ (absent).
+
+| Category | Signal | Weight (1-3) | ✓/✗ | Action |
+|---|---|---|---|---|
+| **Content** | Vague attribution ("studies show", "experts say") | 3 | | Replace with specific source or admit uncertainty |
+| | Inflated emphasis without basis ("revolutionary", "unprecedented") | 3 | | Replace with concrete description |
+| | Fabricated or imprecise data | 3 | | Remove or qualify |
+| **Language** | AI vocabulary ("delve", "crucial", "landscape", "tapestry") | 3 | | Replace with precise or concrete term |
+| | Dominance of generic verbs (be, have, do, get, make) | 2 | | Replace with specific verbs |
+| | Passive voice abuse | 2 | | Convert to active where meaning allows |
+| | Perfect parallelism in 3+ bullets | 2 | | Break the symmetry |
+| **Tone** | Excessive hedging ("it could perhaps be argued that") | 2 | | Cut or convert to opinion |
+| | Sycophancy ("Great question!", "Absolutely!") | 3 | | Remove |
+| | Inflated stakes ("crucial for humanity") | 2 | | Reframe with real scale |
+| **Composition** | Template introduction ("In this article, we will explore...") | 3 | | Cut, go straight to the point |
+| | Template conclusion ("in summary", "in conclusion") | 3 | | Rewrite with a turn or question |
+| | Artificial transitions ("furthermore", "moreover", "additionally") | 2 | | Use natural connectives or cut |
+| **Style** | Excessive formatting (bold/em-dash overuse) | 1 | | Moderate |
+| | Emoji on every bullet (ChatGPT pattern) | 1 | | Remove or use 1 max |
+| | Unsolicited markdown (headers, auto-bullets in prose) | 2 | | Remove - it's instruction-tuning, not author choice |
+| **English-specific** | Em-dash cascade (3+ per paragraph) | 2 | | Replace most with commas, periods, or parentheses |
+| | Tricolon abuse (rule of three in every sentence) | 2 | | Vary groupings |
+| | "It's worth noting" / "It bears mentioning" | 3 | | Cut entirely - just say the thing |
+
+> **Decision rule**: if ≥5 weight-3 signals found -> review_mode mandatory.
+### Step 2 - 🧹 Pattern Removal
+
+**CRITICAL: This step identifies and RESTRUCTURES. It does NOT synonym-swap.**
+
+Per the humanizerai.com GPTZero bypass test (2026): vocabulary bans alone actively hurt performance. Replacing "delve" with "explore" changes nothing that detectors measure. What works is changing the sentence's architecture - its length, rhythm, clause structure, and information density.
+
+**Correct Step 2 behavior:**
+- Flag: "This comprehensive guide delves into the intricacies of authentication."
+- WRONG fix: "This thorough guide explores the details of authentication."
+- RIGHT fix: "The auth system uses JWTs. Tokens expire after 15 minutes."
+
+The first "fix" is synonym-swapping - same rhythm, same length, same predictability. The second is structural paraphrasing - different length, different density, different voice. DetectGPT accuracy drops from 70.3% to 4.6% with structural paraphrasing (RAID Benchmark, ACL 2024). It does NOT drop with synonym replacement.
+
+Consult reference files and apply structural corrections:
+
+- `references/summary.md` - skill navigation index
+- `references/patterns-content.md` - vague attributions, inflated emphasis
+- `references/patterns-language.md` - AI vocabulary, copula avoidance, parallelisms
+- `references/patterns-style.md` - formatting, em-dash, bold, emojis
+- `references/patterns-tone.md` - sycophancy, hedging, stakes inflation
+- `references/patterns-composition.md` - templates, predictable conclusions
+- `references/patterns-english-specific.md` - contractions, passive voice, register mixing
+### Step 3 - ♻️ Entropy Restoration
+
+Where text has been flattened by AI:
+
+| Problem | Solution | Example |
+|---|---|---|
+| Dead metaphor | Replace with vivid image | "Inflection point" -> "It's like running out of gas in the middle of a bridge" |
+| Generic term | Restore domain vocabulary | "Positive impact" -> "17% reduction in churn" |
+| Predictable template | Reorganize non-linearly | Invert order: example -> context -> thesis |
+| Excessive abstraction | Insert concrete data or anecdote | "Many people struggle" -> "Three of my neighbors have had the same problem" |
+| Monotone rhythm | Vary sentence lengths | Alternate short sentences with long ones |
+
+> ⚠️ **Ablation alert**: if a passage lost specificity without justification, annotate: "⚠️ This passage lost concreteness - the original likely had [data / example / qualification]."
+### Step 4 - 💬 Voice Injection
+
+Apply the chosen preset (or mirror a voice sample provided):
+
+- Vary rhythm (intentional burstiness)
+- Add opinion/personal position
+- Mix high and low register
+- Include controlled imperfections (tangents, parentheses, fragments)
+- Use contractions naturally (don't -> do not only when emphasis demands it)
+
+> **When the user provides a voice sample**: read first and annotate: sentence lengths, vocabulary level, how paragraphs begin, punctuation habits, verbal tics, register tendencies. **Mirror** - don't just remove patterns, replace them with the sample's patterns.
+### Step 5 - 🔥 Final Anti-AI Pass (Binary Checklist)
+
+Check each item. Mark ✓ (ok) or ✗ (failed). If any item fails, fix before proceeding.
+
+| # | Check | ✓/✗ |
+|---|---|---|
+| 1 | Sentence lengths vary? (min 3 distinct sizes per paragraph) | |
+| 2 | Mechanical transitions eliminated? ("Furthermore", "Moreover", "Additionally") | |
+| 3 | Abstract placeholders replaced with concrete terms? | |
+| 4 | At least 1 opinion, doubt, or personal feeling present? | |
+| 5 | No template openings/closings survived? | |
+| 6 | Contractions used naturally in informal presets? | |
+| 7 | Factual information from original 100% intact? | |
+| 8 | Voice preset consistent from start to finish? | |
+| 9 | No sentence reads like a press release or Wikipedia stub? | |
+| 10 | Read aloud, does it sound like a real person writing? | |
+
+**Rule**: if ≥2 items fail -> fix and re-check. If all ✓ -> proceed.
+### Step 5.5 - 📊 Post-Rewrite Scoring
+
+Evaluate the result across 5 dimensions (0-100 each, weighted average):
+
+| Dimension | Weight | Evaluation criteria |
+|---|---|---|
+| **AI pattern removal** | 30% | How many Step 1 patterns were eliminated? Any remaining? |
+| **Naturalness** | 25% | Burstiness >5? Varied rhythm? Voice present? Sounds like a real person? |
+| **Factual completeness** | 20% | All original information preserved? Data, names, numbers intact? |
+| **Voice consistency** | 15% | Was the preset maintained throughout? No register jumps? |
+| **Readability** | 10% | Sentences flow? Natural connectives? Clear logic? |
+
+**Final score** = sum (dimension x weight)
+
+**Decision criteria:**
+- **≥ 80**: ✅ Approved -> proceed to delivery (Step 6)
+- **60-79**: ⚠️ Almost -> run Anti-AI Pass again focusing on weak dimensions
+- **< 60**: ❌ Fail -> rewrite with different approach (change preset, invert technique order, or shift focus between removal vs. voice injection)
+
+> **Output format**:
+> ```
+> 📊 POST-REWRITE SCORE
+> • AI removal:          {0-100} (x0.30) = {partial}
+> • Naturalness:         {0-100} (x0.25) = {partial}
+> • Factual completeness:{0-100} (x0.20) = {partial}
+> • Voice consistency:   {0-100} (x0.15) = {partial}
+> • Readability:         {0-100} (x0.10) = {partial}
+> • TOTAL:               {score}/100 -> {✅/⚠️/❌}
+>
+> 📊 METRICS DELTA (pre -> post)
+> • TTR:              {pre} -> {post} ({+/-}%)
+> • Burstiness:       {pre} -> {post} ({+/-}%)
+> • Shannon entropy:  {pre} -> {post} ({+/-}%)
+> • Adverbs -ly/100w: {pre} -> {post}
+> • Passive voice %:  {pre} -> {post}
+> • MSL (mean len):   {pre} -> {post}
+> • Sent. len. CoV:   {pre} -> {post}
+> • Concrete nouns:   {pre}% -> {post}%
+> ```
+>
+> **Interpreting the delta**: TTR, burstiness, entropy, and concrete nouns should **rise**. Adverbs in -ly and passive voice should **fall**. MSL and CoV should **approach human values** (MSL varies by genre; CoV ~ 0.5).
+### Step 6 - 📦 Formatted Delivery
+
+| Mode | Content delivered |
+|---|---|
+| full_mode | Metrics (Step 0) + Checklist (Step 1) + Draft rewrite + Self-critique (Step 5) + Final version + Summary of changes |
+| direct_mode | Final version + Synthetic report (1 line per corrected pattern) |
+| review_mode | Final version + Full checklist + Before/after metrics + Ablation alerts |
+## Iterative Loop and Strategy Fallback
+
+Step 5.5 scoring enables automatic iteration when the result doesn't hit threshold.
+
+### Standalone Behavior (no external loop skill)
+
+```
+iteration = 0
+MAX_ITERATIONS = 3
+
+while iteration < MAX_ITERATIONS:
+    iteration += 1
+    execute Steps 2-5.5
+    
+    if score >= 80: DELIVER
+    if score 60-79:
+        focus on dimensions with score < 70
+        continue
+    if score < 60:
+        CHANGE STRATEGY (see table below)
+        continue
+
+if MAX_ITERATIONS reached: deliver best version + limitation note
+```
+
+### Strategy Fallback Table
+
+When score < 60, change approach on next iteration:
+
+| Previous iteration | Next approach |
+|---|---|
+| Focus on pattern removal (Step 2 heavy) | Focus on voice injection (Step 4 heavy) |
+| Focus on voice injection | Focus on restructuring (Step 3 - reorder flow, break templates) |
+| Current preset doesn't work | Try adjacent preset (e.g., Essay -> Corporate Informal) |
+| Long text with progressive degradation | Split into ~300 word blocks and process separately |
+
+### Compatibility with External Loop Skills
+
+This skill is **compatible** with loop orchestrators like `ralph-wiggum`, `goal`, or any skill implementing an external iterative cycle.
+
+**Integration protocol:**
+
+1. **Standardized input**: skill accepts text + preset (optional) + minimum score (optional, default 80)
+2. **Structured output**: always returns the parseable `📊 POST-REWRITE SCORE` block
+3. **Convergence signal**: when score >= threshold, emit `✅ HUMANIZATION COMPLETE (score: {N}/100)`
+4. **Non-convergence signal**: when standalone iteration exhausts, emit `⚠️ BEST RESULT REACHED (score: {N}/100) - external iteration may continue`
+
+> **For external loop skills**: use the numeric score from output as stopping criterion. The skill needs no state between calls - each invocation receives text (possibly already partially humanized) and returns result + score.
+## The 29 AI Vocabulary Patterns (English)
+
+The core detection list. These words and phrases are near-certain AI signals when they appear with high frequency. Based on Wikipedia's "Signs of AI Writing" + blader/humanizer's detection set + brandonwise/humanizer's 560-term tier system.
+
+### Tier 1 - Zero Tolerance (cut on sight)
+
+These NEVER appear in natural human writing at the frequency AI uses them:
+
+`delve, tapestry, landscape (figurative), testament to, serves as a reminder, it's worth noting, it bears mentioning, the ever-evolving landscape, navigate (complexities/challenges), spearhead, multifaceted, pivotal, paramount, underscores, underpin, a testament to, in the realm of, it is important to note, this highlights, shed light on`
+
+### Tier 2 - High Suspicion (replace when clustered)
+
+Acceptable once per 1000 words. AI uses them 10-20x:
+
+`crucial, vital, comprehensive, robust, leverage, foster, facilitate, embark, harnessing, utilize, endeavor, moreover, furthermore, additionally, subsequently, nonetheless, notwithstanding (in non-legal), overarching, intricate, nuanced, holistic, synergy, paradigm, catalyst, orchestrate, seamless, ecosystem (abstract), journey (figurative), unlock (figurative)`
+
+### Tier 3 - Context-Dependent (flag if > 2 per 500 words)
+
+Normal words that AI overuses through repetition:
+
+`significant, enhance, innovative, dynamic, diverse, inclusive, sustainable, transformative, empower, streamline, optimize, cutting-edge, state-of-the-art, game-changer, disruptive, scalable, impactful, actionable, meaningful, compelling`
+
+### Detection Rule
+
+- 1 Tier-1 word = flag the sentence
+- 3+ Tier-2 words in one paragraph = flag the paragraph
+- 5+ Tier-3 words in one page = flag the text
+- Any combination of 2+ Tier-1 words in 500 words = near-certain AI
+## The Emerging Patterns (2026 Community Discoveries)
+
+Patterns P31-P43 below were identified by HackerNews threads, Wikipedia's evolving editorial guidelines, and writing practitioner blogs throughout 2026. They represent AI behavior that is newer, subtler, and not yet covered by most humanizer tools. Source: Aboudjem/humanizer-skill research.
+
+| # | Pattern | What to look for | Why it's a tell |
+|---|---|---|---|
+| P31 | Elegant Variation | "the artist", "the visionary creator", "the non-conformist painter" for the same person | AI avoids repeating a noun by cycling through increasingly florid synonyms. Humans just use the name or "he/she/they". |
+| P32 | Collaborative Communication Leaking | "In this article, we will explore", "Let me walk you through" | Residue from the assistant persona bleeding into published text. |
+| P33 | Placeholder Text / Mad Libs | `[Your Name]`, `[INSERT SOURCE URL]`, unfilled brackets | Template artifacts the user forgot to fill. Immediate credibility kill. |
+| P34 | Chatbot Reference Markup Leaking | `citeturn0search0`, `oai_citation`, broken footnote refs | Internal citation markup from ChatGPT/Copilot leaking into output. |
+| P35 | UTM Source Parameters | `utm_source=chatgpt.com`, `utm_source=openai` in URLs | Links copied directly from AI chat sessions without cleaning. |
+| P36 | Sudden Style/Register Shift | Formal prose suddenly switching to casual mid-paragraph | Indicates pasted AI output spliced with human text (or vice versa). |
+| P37 | Overattribution | "Featured in Wired, Refinery29, and other outlets" without substance | Listing media names without citing what was said or when. |
+| P38 | Paragraph-Reshuffling Immunity | Paragraphs that could swap order without breaking the argument | AI generates paragraphs as independent blocks with no logical progression. Human arguments BUILD - each paragraph depends on the previous. |
+| P39 | "Whether" Paragraph Closers | "Whether you prefer X or Y, the answer is..." | Formulaic wrap-up that pretends to acknowledge alternatives while saying nothing. |
+| P40 | Symbolic Gloss / Meaning-Telling | "represents", "symbolizes", "speaks to broader" applied to mundane things | AI assigns cosmic significance to ordinary events. "The coffee spill represents the broader challenges of work-life balance." |
+| P41 | Infomercial Engagement Hooks | "The catch?", "The kicker?", "Here's the thing.", "The brutal truth?" | Cheap rhetorical devices that create false drama. One per essay is fine. Every paragraph is AI slop. |
+| P42 | Erratic Inline Bolding | Random mid-sentence bold spans with no shared logic or category | Bold without editorial purpose - the model is "highlighting" but there's no system. |
+| P43 | The Treadmill Effect | "In other words", "Put simply", "Essentially" looping the same point | AI restates the same idea in different words across multiple sentences, creating the illusion of development without actually advancing the argument. |
+
+**Detection rule for emerging patterns:**
+- P33-P35 (markup/placeholder leaks) = immediate flag, zero tolerance
+- P38 (reshuffling immunity) = strongest structural tell. Test by mentally rearranging paragraphs - if the text reads identically, it's AI
+- P43 (treadmill effect) = if you can delete a sentence and the paragraph loses zero information, that sentence is treadmilling
+## Critical Research: Why Vocabulary Bans Alone FAIL
+
+> "Vocabulary bans, one of the most commonly recommended techniques, actively hurt performance." - humanizerai.com, GPTZero bypass test (2026)
+
+Detectors measure **statistical patterns** (burstiness, perplexity, sentence length variance), not vocabulary. Replacing "delve" with "explore" preserves the robotic rhythm underneath.
+
+**Effectiveness hierarchy (research-backed):**
+1. **Structural paraphrasing** - DetectGPT 70.3% -> 4.6% (RAID Benchmark, ACL 2024)
+2. **Burstiness injection** - primary GPTZero signal
+3. **Perplexity increase** - secondary GPTZero signal
+4. **Vocabulary diversity** - TTR 45.5 -> 55.3 (SSRN)
+5. **Synonym swapping** - DOES NOT WORK as standalone technique
+## Contraction Rules (English-Specific)
+
+AI avoids contractions far more than humans. One of the most reliable statistical signals.
+
+| Context | Human | AI |
+|---|---|---|
+| Informal email | Contractions everywhere | Mixed or avoids |
+| Blog post | 80%+ contracted | 40-60% contracted |
+| Academic paper | Minimal (correct) | Minimal (correct) |
+| Documentation | Moderate | Often avoids entirely |
+
+**Rule**: In Essay, Corporate Informal, Social Post, and Casual/DM presets, zero contractions = immediate AI signal. Force natural contractions in Step 4. **Exception**: Academic and Legal presets may correctly avoid contractions.
+## Regression Test Suite
+
+6 test cases covering: corporate email, academic paragraph, legal text, blog template, AI hedging, generic explainer. Each test runs in full_mode and verifies output matches expected human-sounding result.
+
+> Full test cases in `references/tests.md`
+## Limits and Contraindications
+
+**Do NOT use:** Safety-critical texts (drug labels, aviation), original contracts/legal documents (normative reference), bilingual literal translations, content for automated evaluation (TOEFL), texts already validated as human by multiple detectors.
+
+**Use with caution:** Technical texts with formal notation (preserve equations/code, humanize only prose), non-native English writers (colloquialisms may not match ESL author's voice).
+## References
+
+| Source | Link | Key finding |
+|---|---|---|
+| Wikipedia - Signs of AI writing | https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing | 24 pattern categories with real examples |
+| blader/humanizer (29 patterns) | https://github.com/blader/humanizer | Original skill, 10.6K stars |
+| brandonwise/humanizer (statistical) | https://github.com/brandonwise/humanizer | 560-term vocab filter, burstiness/TTR |
+| Aboudjem/humanizer-skill (43 patterns) | https://github.com/Aboudjem/humanizer-skill | P31-P43 emerging patterns, 5 voices, scoring |
+| tropes.fyi | https://tropes.fyi/directory | Community AI trope catalog |
+| The Register - Semantic Ablation | https://www.theregister.com/2026/02/16/semantic_ablation_ai_writing/ | Meaning-loss through AI polishing |
+| RAID Benchmark (ACL 2024) | doi:10.18653/v1/2024.findings-acl | Structural paraphrasing: DetectGPT 70.3% -> 4.6% |
+| Tulchinskii et al. (NeurIPS 2023) | Intrinsic dimension analysis | Human ~9 dims vs AI ~7.5 |
+| SSRN stylometric study | Vocabulary diversity analysis | Human TTR: 55.3 vs AI: 45.5 |
+| humanizerai.com - GPTZero bypass | https://humanizerai.com/blog/gptzero-bypass-test-2026 | Vocab bans HURT; structural change wins by 43pp |
+| GPTZero | https://gptzero.me | Burstiness + perplexity as primary signals |
+
+---
+
+*v1.0.0 - Based on Portuguese [humanizar](https://github.com/fabricioctelles/skills) by @fabriciotelles. Combines pattern detection (blader), statistical measurement (brandonwise), and emerging patterns (Aboudjem) with voice injection, entropy restoration, and iterative scoring.*
--- a/.github/skills/human-ai/references/patterns-composition.md
+++ b/.github/skills/human-ai/references/patterns-composition.md
@@ -0,0 +1,130 @@
+# Composition Patterns - AI Tropes in English
+
+Structural patterns betraying AI-generated text at the level of **composition** - how the text is assembled, not what it says. Includes tropes cataloged by [tropes.fyi](https://tropes.fyi/directory) and the concept of **Semantic Ablation** (The Register, Feb 2026).
+
+---
+
+## Composition Tropes
+
+### 1. Fractal Summaries
+
+**Problem:** AI announces what it will say, says it, then summarizes what it said - in each section, subsection, and paragraph. Text becomes infinite recursion of meta-commentary.
+
+**Before (AI):**
+> In this section, we will explore how artificial intelligence is transforming the financial sector. We will examine three key aspects: process automation, predictive analytics, and customer service.
+>
+> [...3 paragraphs...]
+>
+> As we have seen in this section, artificial intelligence is transforming the financial sector through process automation, predictive analytics, and customer service. In the next section, we will address the challenges of this transformation.
+
+**After (human):**
+> Itau cut 40% of its back-office team in two years. Wasn't layoffs - it was automation eating the edges. A credit process that took a week now runs in four hours. The analyst who remains doesn't analyze: they supervise the model that does.
+
+**Cut on sight:**
+- "In this section, we will..."
+- "As we saw previously..."
+- "Next, we will discuss..."
+- "As mentioned in the previous section..."
+- "To summarize what we've discussed..."
+
+**Correction techniques:**
+- Eliminate recursion: the conclusion is ONE thing - at the end. Subsections don't need mini-conclusions
+- Convert meta-commentary to direct statement: "As we saw, AI transforms the sector" -> "AI transforms the sector in three ways"
+- If text has 3+ subsections with mini-conclusions, merge into a single block with continuous flow
+
+---
+
+### 2. Dead Metaphor on Repeat
+
+**Problem:** AI finds a metaphor at the beginning and repeats ad nauseam as if it were the spine of the text. "Ecosystem" appears 30 times. "Journey" appears in every paragraph. The metaphor loses all power - becomes noise.
+
+**Before (AI):**
+> The startup ecosystem is maturing. In this ecosystem, the players need to adapt. The ecosystem demands new competencies. To survive in this ecosystem, entrepreneurs must build solid networks. The future of the ecosystem depends on public policies that foster innovation within the ecosystem itself.
+
+**After (human):**
+> The startup scene in the US changed - from garage with pitch deck to serious business with governance and boards demanding results. Anyone who started in 2019 thinking all you needed was a good idea and a seed round now faces investors who want unit economics. The party ended; the real work started.
+
+**Rule:** Never repeat the same figurative word more than twice in a text. After the second use, find a different way to say it - or just say the concrete thing.
+
+---
+
+### 3. The "Many People" Ghost
+
+**Problem:** AI attributes claims to unnamed masses: "many people believe", "researchers have found", "companies are increasingly", "there's a growing consensus". No specific person is cited. No specific research is named. It's the literary equivalent of "people are saying."
+
+**Before (AI):**
+> Many experts believe that AI will transform education. Researchers have found that personalized learning approaches yield better outcomes. Companies are increasingly investing in edtech solutions, reflecting a growing consensus that traditional methods are no longer sufficient.
+
+**After (human):**
+> Sal Khan thinks AI tutoring will outperform classrooms within a decade. He might be right - Khan Academy's pilot data shows 30% improvement on math scores with AI tutoring. But Audrey Watters has been calling bullshit on edtech promises for fifteen years, and she's usually right too.
+
+**Rule:** If you can't name the expert, the researcher, or the company - either find one, or rephrase as your own opinion.
+
+---
+
+### 4. The Five-Paragraph Essay
+
+**Problem:** AI defaults to intro-3points-conclusion structure regardless of content or context. Every piece becomes a high school essay: thesis, body paragraph 1, body paragraph 2, body paragraph 3, conclusion restating thesis. This is the structural equivalent of "In this essay, I will argue..."
+
+**Before (AI structure):**
+```
+Introduction: State thesis
+Point 1: First argument with support
+Point 2: Second argument with support  
+Point 3: Third argument with support
+Conclusion: Restate thesis in different words
+```
+
+**After (human structure options):**
+```
+Open with a story -> derive the principle -> complicate it -> leave an open question
+Start with the conclusion -> explain why it's surprising -> show the evidence
+Describe the problem in detail -> show three failed solutions -> reveal what worked
+```
+
+**Rule:** Structure should emerge from content, not be imposed from template. Good writing starts where it needs to start and ends where it needs to end.
+
+---
+
+### 5. Semantic Ablation (The Register, 2026)
+
+**Problem:** After multiple AI refinement passes, text loses specificity, personality, and edge. Each pass removes anything "risky" or "unusual" until what remains is perfectly smooth, perfectly generic, perfectly dead. The Register calls this "semantic ablation" - the wearing away of meaning through machine-polishing.
+
+**Symptoms:**
+- All specific examples replaced with generic ones
+- All strong opinions softened to "balanced" perspectives
+- All technical jargon replaced with layperson equivalents (losing precision)
+- All humor or personality flattened to neutral tone
+- Numbers rounded or removed ("about 3 million" becomes "many")
+
+**Before (ablated):**
+> Many companies are adopting new approaches to software development. These approaches offer various benefits and come with certain challenges. Teams should carefully evaluate their options.
+
+**After (restored):**
+> 47 YC companies from the W24 batch shipped their MVPs using AI coding agents. Not "AI-assisted" - full agent mode. Half of them have zero engineers on staff. The challenge is debugging: when the agent writes 10,000 lines in a night, who reviews it?
+
+**Detection signals (from brandonwise/humanizer's statistical model):**
+- TTR (Type-Token Ratio) below 0.45 - vocabulary is being recycled
+- Burstiness below 5 - all sentences the same length (robotic rhythm)
+- Shannon entropy significantly lower than human baseline for the genre
+- Concrete noun density below 40% - everything is abstract
+
+**Restoration technique:** Add back specificity at every opportunity: names, numbers, dates, anecdotes, qualifications. If the original had them, restore. If it didn't, flag that the text needs concreteness.
+
+---
+
+### 6. The Balanced Bookend
+
+**Problem:** AI opens and closes with suspiciously symmetrical statements. The final paragraph echoes the first with slightly different phrasing, creating an artificial sense of circular completion. Human writers don't do this unless deliberately crafting a literary piece.
+
+**Before (AI):**
+> Opening: "The intersection of AI and healthcare presents both unprecedented opportunities and significant challenges."
+> [...]  
+> Closing: "As we've seen, the intersection of AI and healthcare continues to present both remarkable opportunities and notable challenges that will shape the future of medicine."
+
+**After (human):**
+> Opens with a specific story about a misdiagnosis caught by AI.
+> [...]
+> Ends with an open question: "So who's liable when the AI is right and the doctor disagrees?"
+
+**Rule:** Endings should advance the thought, not echo it. If your conclusion says the same thing as your introduction, one of them is redundant.
--- a/.github/skills/human-ai/references/patterns-content.md
+++ b/.github/skills/human-ai/references/patterns-content.md
@@ -0,0 +1,99 @@
+# Content Patterns
+
+Patterns where AI inflates importance, fabricates authority, or closes texts with predictable formulas. The easiest to detect because they sound like press releases - nobody talks like this.
+
+---
+
+### 1. Undue emphasis on significance, legacy, and trends
+
+**Trigger words/phrases:** represents a milestone, is a testament to, plays a crucial/vital/pivotal role, underscores the importance of, reflects a broader trend, symbolizing the, contributing to the, paving the way for, shaping the future of, ever-evolving landscape, inflection point, indelible mark, deeply rooted, redefines the paradigm
+
+**Problem:** AI transforms any mundane fact into a revolution. A CRUD app becomes "a milestone in digital transformation". A startup pivot becomes "an inflection point in the innovation ecosystem". No human writes like this about normal things.
+
+**Before (AI):**
+> OpenAI represents a fundamental milestone in the transformation of the artificial intelligence landscape, actively shaping the future of AI development and paving the way for a new era of human-computer interaction.
+
+**After (human):**
+> OpenAI started by releasing GPT-3 as an API. It worked because nobody else was making large language models accessible to developers at that point. Now they have a consumer product with 100 million users.
+
+**Detection signals:**
+- Absolute superlatives without quantification ("greatest", "best", "unprecedented", "first-ever")
+- Grandiose transformation verbs ("redefine", "shape", "pave the way")
+- Text describing anything as an "inflection point" without saying what changes afterward
+
+**Correction techniques:**
+- Convert superlatives to **concrete data**: "largest fintech" -> "80 million customers"
+- Replace grandiose verbs with **specific action verbs**: "pave the way" -> "hired 3 engineers for"
+- "Journalist test" - if a reporter would read the sentence and ask "how so?", the term is empty
+
+---
+
+### 2. Forced emphasis on notability and media coverage
+
+**Trigger words/phrases:** widely recognized, covered by major outlets, featured in leading publications, active social media presence, according to industry experts, benchmark in the market
+
+**Problem:** AI lists outlets and awards as proof of importance without saying what was said or why it matters. Becomes a turbocharged resume - impresses in a vacuum but informs nothing.
+
+**Before (AI):**
+> The company has been featured in TechCrunch, Bloomberg, The New York Times, and Wired. Widely recognized as a benchmark in the B2B SaaS market, it maintains an active social media presence with over 200,000 followers across platforms.
+
+**After (human):**
+> In a 2024 interview with Bloomberg, the CEO said ARR tripled after they shifted from enterprise-only to mid-market. The pivot took six months and cost them their two largest contracts.
+
+**Detection signals:**
+- Listing publications without citing specific articles (date, title, link)
+- "Active social media presence" without metrics (followers, engagement rate)
+- Mention of awards or rankings without verifiable source
+
+**Correction techniques:**
+- If real source exists -> cite with date and link: "Per TechCrunch, March 12, 2025 (link)"
+- If no source exists -> cut the notability claim entirely
+- "Verifiability test" - if the reader can't check in 30 seconds, it's puffery
+
+---
+
+### 3. Superficial analysis with present participles
+
+**Trigger words/phrases:** underscoring the importance of, demonstrating the commitment to, reflecting the trend toward, contributing to the strengthening of, evidencing the potential of, driving innovation, fostering growth, solidifying its position as
+
+**Problem:** AI glues participle phrases to the end of sentences to simulate analysis, but it isn't analyzing. It's syntactic filler - padding without information. Like that intern who writes 3 pages to say "it worked".
+
+**Before (AI):**
+> Stripe launched native integration with WhatsApp Business, demonstrating its commitment to innovation in digital payments and solidifying its position as a leader in the segment, driving the digital transformation of SMBs globally.
+
+**After (human):**
+> Stripe launched WhatsApp Business integration. Makes sense - most SMB leads in emerging markets come through WhatsApp, not web forms.
+
+**Detection signals:**
+- Sentence-final participle phrases that restate the main clause in grander terms
+- "Demonstrating commitment to..." (always empty)
+- Three or more participle clauses chained with commas
+
+**Correction techniques:**
+- Delete the participle clause and check if meaning is lost. Usually it isn't.
+- If meaning IS lost, convert to a separate sentence with a specific claim
+- "So what?" test - if the participle clause doesn't answer "so what?", cut it
+
+---
+
+### 4. Hollow future projections
+
+**Trigger words/phrases:** poised to, set to transform, is expected to revolutionize, has the potential to reshape, promises to redefine, will likely emerge as, positioned to become
+
+**Problem:** AI loves predicting transformative futures without evidence. These phrases create an illusion of analysis while saying nothing falsifiable.
+
+**Before (AI):**
+> The technology is poised to transform the healthcare industry, promising to redefine patient outcomes and reshape the landscape of medical diagnostics as we know it.
+
+**After (human):**
+> Two hospitals in Boston are running pilot programs with the diagnostic tool. Early numbers show 12% fewer false negatives on lung scans. Whether that scales to 4,000 hospitals is a different question entirely.
+
+**Detection signals:**
+- Future tense without specific timeline
+- "Poised to" / "set to" without citing who said so or what evidence supports it
+- Combination of future projection + superlative ("will revolutionize")
+
+**Correction techniques:**
+- Replace with current evidence: what exists NOW that suggests the future claim?
+- If no evidence exists, either cut the claim or caveat it: "If X happens, then Y"
+- Anchor to specific numbers, dates, or named sources
--- a/.github/skills/human-ai/references/patterns-english-specific.md
+++ b/.github/skills/human-ai/references/patterns-english-specific.md
@@ -0,0 +1,153 @@
+# English-Specific Patterns
+
+Patterns unique to AI-generated English text that don't have direct equivalents in other languages. These exploit the specific quirks of English grammar, register mixing, and contraction patterns that AI consistently gets wrong.
+
+---
+
+### 1. Contraction Avoidance
+
+**Problem:** AI-generated English dramatically underuses contractions compared to human writing. In informal contexts, this is one of the most reliable statistical signals. GPTZero and Originality.ai both flag texts with unusually low contraction rates.
+
+**Human contraction rates by register:**
+| Register | Contraction rate |
+|---|---|
+| Casual speech/DM | 95%+ ("don't", "won't", "it's", "we're", "they'll") |
+| Blog/newsletter | 80-90% |
+| Professional email | 60-80% |
+| Journalism | 40-70% (varies by outlet) |
+| Academic | 10-30% (deliberately formal) |
+| Legal | 5-15% (genre convention) |
+
+**AI typical rate:** 30-50% across ALL registers (doesn't adapt)
+
+**Before (AI - blog register):**
+> It is important to note that the system does not function as expected. We cannot determine the root cause at this time. There is no indication that this will be resolved soon.
+
+**After (human - blog register):**
+> It's not working the way it should. We can't figure out why yet. There's no sign it'll be fixed soon.
+
+**Contraction replacement rules:**
+| AI form | Human form (informal) | Keep formal when... |
+|---|---|---|
+| it is | it's | academic emphasis needed |
+| do not | don't | legal/safety context |
+| cannot | can't | formal document |
+| will not | won't | emphasis on refusal |
+| they are | they're | ambiguity risk |
+| we have | we've | ... |
+| should not | shouldn't | ... |
+| would not | wouldn't | ... |
+| there is | there's | ... |
+| that is | that's | ... |
+
+**Rule:** In Essay, Corporate Informal, Social Post, and Casual presets, force contractions to match human rates. In Academic and Legal presets, low contractions are correct.
+
+---
+
+### 2. Register Uniformity
+
+**Problem:** Humans naturally mix registers within a single text - formal vocabulary next to colloquial phrasing, technical terms next to slang, high register next to low. AI maintains a perfectly uniform register throughout, which paradoxically signals artificiality.
+
+**Before (AI - uniformly mid-register):**
+> The implementation proved challenging but ultimately successful. The team encountered several obstacles during the process but managed to resolve them through collaborative effort and systematic problem-solving.
+
+**After (human - mixed register):**
+> The implementation was a nightmare for about two weeks - classic "it works on my machine" stuff. Then Sarah figured out the race condition and we shipped it. Sometimes the fix is embarrassingly simple.
+
+**Human register mixing patterns:**
+- Technical term + casual explanation: "The TTL expired - basically the cache forgot everything"
+- Formal structure + informal aside: "The architecture is sound. (The naming conventions, less so.)"
+- Precise vocabulary + colloquial connector: "The latency delta was significant. Look, 340ms vs 40ms isn't subtle."
+
+**Rule:** Inject at least one register shift per 300 words in non-academic presets. A formal paragraph should have one casual moment. A casual text should have one precise term.
+
+---
+
+### 3. Passive Voice Overuse
+
+**Problem:** AI defaults to passive voice far more than humans, especially when the agent (who did the thing) is uncertain or the AI is hedging. Human English strongly prefers active voice in most contexts.
+
+**Before (AI):**
+> The decision was made to restructure the team. It was determined that performance had been negatively impacted. New processes were implemented and improvements were observed over the following quarter.
+
+**After (human):**
+> The VP restructured the team. Performance had tanked - everyone knew it. They implemented new processes and saw improvement by Q3.
+
+**Acceptable passive uses (don't convert these):**
+- When the agent is genuinely unknown: "The server was compromised overnight"
+- When the object is more important: "Three people were injured in the crash"
+- Scientific convention: "The sample was heated to 300°C"
+- Deliberate de-emphasis of actor: "Mistakes were made" (though this is also a cliche)
+
+**Detection signal:** More than 30% of clauses in passive voice = AI signal. Measure by counting "was/were + past participle" constructions.
+
+---
+
+### 4. Transition Word Abuse
+
+**Problem:** AI uses explicit transition words between nearly every sentence. Human writers trust the reader to follow logical connections without signposting every turn.
+
+**AI transition word frequency:** every 2-3 sentences
+**Human transition word frequency:** every 5-8 sentences (varies by genre)
+
+**The worst offenders (cut 80% of these):**
+| Word | AI frequency | Human frequency | Action |
+|---|---|---|---|
+| Furthermore | Every paragraph | Rare in non-academic | Cut or replace with "And" |
+| Moreover | Every paragraph | Rare | Cut |
+| Additionally | Every paragraph | Rare | Cut |
+| However | Every 3 sentences | Every 6-8 sentences | Keep some, cut most |
+| Consequently | Frequent | Rare in non-academic | "So" or cut |
+| Subsequently | Frequent | Rare | "Then" or cut |
+| Nevertheless | Frequent | Occasional | Keep sparingly |
+| In contrast | Frequent | Occasional | "But" or restructure |
+
+**Rule:** Trust the reader. If the logical connection is obvious from context, no transition word is needed. Use transitions only when the connection would genuinely surprise the reader.
+
+---
+
+### 5. "The" Proliferation in Abstractions
+
+**Problem:** AI over-uses "the" before abstract nouns, creating a false specificity. "Innovation" becomes "the innovation". "Technology" becomes "the technology". This makes generic statements sound as if they refer to something specific when they don't.
+
+**Before (AI):**
+> The innovation in the space has led to the advancement of the technology. The community has embraced the shift toward the adoption of the new paradigm.
+
+**After (human):**
+> Innovation in this space accelerated after GPT-4 launched. Developers adopted the new approach quickly - mostly because it was easier, not because anyone evangelized it.
+
+**Rule:** If "the [abstract noun]" doesn't refer to a previously introduced specific thing, it's probably AI padding. Cut "the" or replace with a specific referent.
+
+---
+
+### 6. Absence of Sentence Fragments
+
+**Problem:** Human English, especially in informal and semi-formal writing, uses sentence fragments freely for rhythm and emphasis. AI almost never produces them - every unit is a grammatically complete sentence.
+
+**AI (all complete sentences):**
+> The product launched last week. It received positive reviews. The team is now focused on iteration. They plan to ship a major update by March.
+
+**Human (with natural fragments):**
+> The product launched last week. Positive reviews all around. Now the team's heads-down on iteration. Major update by March. Maybe.
+
+**Fragment types humans use:**
+- Answers: "Absolutely not."
+- Emphasis: "Every. Single. Time."
+- Afterthoughts: "Not ideal."
+- Rhythm breaks: "So there's that."
+- Dramatic pause: "Three million lines of code. Overnight."
+
+**Rule:** In Essay, Corporate Informal, Social Post, and Casual presets, inject at least one sentence fragment per 200 words. In Academic and Legal presets, fragments are inappropriate.
+
+---
+
+### 7. Perfect Paragraph Length Uniformity
+
+**Problem:** AI generates paragraphs of remarkably similar length (typically 3-5 sentences, 80-120 words each). Human writing varies paragraph length dramatically - from one-sentence paragraphs to 300-word blocks.
+
+**AI pattern:** 4 sentences, 4 sentences, 4 sentences, 4 sentences
+**Human pattern:** 1 sentence, 6 sentences, 2 sentences, 8 sentences, 1 sentence
+
+**Detection signal (from brandonwise/humanizer):** Coefficient of variation in paragraph length below 0.3 = AI signal. Human English averages ~0.6 CoV in paragraph length.
+
+**Rule:** Vary paragraph length intentionally. Use one-sentence paragraphs for impact. Use long paragraphs for complex arguments that need sustained development. The variation IS the voice.
--- a/.github/skills/human-ai/references/patterns-language.md
+++ b/.github/skills/human-ai/references/patterns-language.md
@@ -0,0 +1,120 @@
+# Language and Grammar Patterns (English)
+
+Patterns that betray AI-generated text at the level of word choice, grammatical constructions, and sentence structure. Based on Wikipedia's Signs of AI Writing + tropes.fyi + blader/humanizer's 29-pattern set + brandonwise/humanizer's statistical model.
+
+---
+
+### 1. AI Vocabulary (The Slop Dictionary)
+
+**Tier 1 - Zero Tolerance (cut on sight):**
+
+| Word/Phrase | Why it's a tell | Human alternative |
+|---|---|---|
+| delve | No one says this in conversation | explore, dig into, look at |
+| tapestry | Always used as "rich tapestry of..." | (cut entirely - always filler) |
+| landscape (figurative) | "The AI landscape" | the AI space, AI right now |
+| testament to | "It's a testament to..." | shows that, proves |
+| serves as a reminder | Always preamble to nothing | (cut - just state the thing) |
+| it's worth noting | Meta-commentary, not content | (cut - the note IS the content) |
+| it bears mentioning | Same as above | (cut) |
+| the ever-evolving landscape | Double slop | (cut entirely) |
+| navigate (complexities) | "Navigate the challenges of" | deal with, handle, figure out |
+| spearhead | "Spearheading the initiative" | lead, run, start |
+| multifaceted | "This multifaceted problem" | complex, messy, complicated |
+| pivotal | "A pivotal moment" | important, key, big |
+| paramount | "Of paramount importance" | essential, critical |
+| underscores | "This underscores the need" | shows, highlights |
+| underpin | "Principles that underpin" | behind, supporting |
+| in the realm of | "In the realm of AI" | in AI |
+| shed light on | "Shedding light on this issue" | explain, clarify, show |
+| this highlights | Meta-commentary | (cut - the highlight IS the sentence) |
+
+**Tier 2 - High Suspicion (replace when clustered, OK once per 1000 words):**
+
+`crucial, vital, comprehensive, robust, leverage, foster, facilitate, embark, harnessing, utilize, endeavor, moreover, furthermore, additionally, subsequently, nonetheless, overarching, intricate, nuanced, holistic, synergy, paradigm, catalyst, orchestrate, seamless, ecosystem (abstract), journey (figurative), unlock (figurative), empower, elevate`
+
+**Tier 3 - Context-Dependent (flag if >2 per 500 words):**
+
+`significant, enhance, innovative, dynamic, diverse, inclusive, sustainable, transformative, streamline, optimize, cutting-edge, state-of-the-art, game-changer, disruptive, scalable, impactful, actionable, meaningful, compelling, groundbreaking`
+
+**Detection rule:**
+- 1 Tier-1 word = flag the sentence
+- 3+ Tier-2 words in one paragraph = flag the paragraph
+- 5+ Tier-3 words in one page = flag the text
+- Any combination of 2+ Tier-1 words in 500 words = near-certain AI
+
+---
+
+### 2. Copula Avoidance
+
+**Trigger patterns:** constitutes, represents, serves as, functions as, operates as, positions itself as, stands as, emerges as, figures as
+
+**Problem:** AI avoids "is" and "has" as if they were forbidden words. Replaces them with elaborate constructions no human would use in natural writing.
+
+**Before (AI):**
+> Stripe constitutes the leading payments infrastructure for the internet. The platform serves as a comprehensive solution for businesses and positions itself as the de facto standard for online transactions.
+
+**After (human):**
+> Stripe is the biggest payments company online. Their API is what most startups use to take money.
+
+**Rule:** If "is" or "has" would work, use it. Save elaborate verbs for when you need precise meaning, not sophistication theater.
+
+---
+
+### 3. Negative Parallelisms
+
+**Trigger patterns:** not merely X, but Y; it's not just about X, it's about Y; more than X, it's Y; goes far beyond X; transcends the simple X; not simply X, it's fundamentally Y
+
+**Problem:** Formulaic construction that artificially inflates importance. Creates a false dichotomy where the writer pretends to reject something then embraces something bigger - but both parts say the same thing.
+
+**Before (AI):**
+> Product management is not merely about writing user stories. It goes far beyond simply shipping features - it's fundamentally about solving real problems. The PM transcends the role of ticket writer; they are, above all, a translator between business and technology.
+
+**After (human):**
+> Good PMs solve problems. Bad PMs write tickets. The difference isn't philosophical - it's practical. Look at someone's backlog and you'll know in 5 minutes.
+
+---
+
+### 4. Tricolon Abuse (Rule of Three)
+
+**Trigger patterns:** clarity, concision, and coherence; innovation, technology, and transformation; plan, execute, and measure; any rhythmic triad with "and" before the third item; three adjectives in sequence; three abstract nouns grouped
+
+**Problem:** AI groups ideas in threes because tricolon is rhetorically satisfying - but when it appears in every paragraph, it becomes a tic. Human text groups in 2, in 4, in 1. Rarely in 3 repeatedly.
+
+**Before (AI):**
+> The platform delivers speed, reliability, and scalability. Teams need clarity, collaboration, and consistency. Our approach combines innovation, expertise, and dedication.
+
+**After (human):**
+> It's fast. Reliable enough that we stopped worrying about downtime. And it scales - we went from 10k to 400k requests/day without changing anything.
+
+**Detection rule:** If a text has 3+ tricolons per page, it's almost certainly AI-generated. Humans occasionally use rule-of-three for rhetorical effect. AI uses it as a structural crutch.
+
+---
+
+### 5. Weasel Qualifiers
+
+**Trigger patterns:** it could be argued that, one might suggest, there are those who believe, it has been said that, some would argue, many experts believe, it is generally accepted
+
+**Problem:** AI uses qualifiers to avoid committing to claims. The result reads like a Wikipedia article written by someone afraid of being corrected. Humans either commit to a claim or cite a specific source.
+
+**Before (AI):**
+> It could be argued that large language models represent a significant advancement. Many experts believe this technology has the potential to transform various industries, though some would argue the risks are considerable.
+
+**After (human):**
+> LLMs are a big deal. They'll change how most knowledge work gets done - I genuinely believe that. But Hinton is right that we don't understand alignment well enough to be comfortable.
+
+---
+
+### 6. Nominalization Disease
+
+**Trigger patterns:** the implementation of, the utilization of, the facilitation of, the optimization of, the enhancement of, the establishment of, provides a demonstration of, performs an analysis of
+
+**Problem:** AI converts verbs into nouns, making sentences longer, vaguer, and harder to parse. "We analyzed" becomes "we performed an analysis of". This is the passive-aggressive cousin of passive voice.
+
+**Before (AI):**
+> The implementation of the new system resulted in the enhancement of performance metrics and the facilitation of improved collaboration across teams.
+
+**After (human):**
+> We implemented the new system. Performance improved. Teams started collaborating more.
+
+**Rule:** If a noun ending in -tion/-ment/-ance has a simpler verb form, use the verb.
--- a/.github/skills/human-ai/references/patterns-style.md
+++ b/.github/skills/human-ai/references/patterns-style.md
@@ -0,0 +1,132 @@
+# Style and Formatting Patterns
+
+Patterns betraying AI-generated text through visual and structural form, not content. Detection tools use these markers as high-confidence signals.
+
+---
+
+### 1. Em-Dash Cascade
+
+**Problem:** AI uses 15-25 em-dashes per medium text. Humans use 2-3, and generally prefer commas, periods, or parentheses for most functions AI assigns to em-dashes.
+
+**Before (AI):**
+> The project — which started in 2022 — brought impressive results — especially in the data area — and is now being expanded — even with limited budget — to other regions.
+
+**After (human):**
+> The project started in 2022 and brought solid results in data. It's now expanding to other regions, even with a tight budget.
+
+**Detection signals:**
+- More than 2 em-dashes per paragraph
+- Em-dash where comma resolves
+- Chaining of parenthetical asides with em-dashes (— X — Y — Z)
+- Text where >10% of punctuation marks are em-dashes
+
+**Correction techniques:**
+- **Limit of 2 em-dashes per paragraph** - convert extras to commas, periods, or parentheses
+- Differentiate use: em-dash for strong contrast, parentheses for side comment, comma for light aside
+- "Editor test" - if a human editor would have cut the em-dash, cut it
+
+---
+
+### 2. Excessive Bold
+
+**Problem:** AI applies bold to every keyword as if the text were a slide deck. Running text with bold on every important noun reads like a product catalog, not human writing.
+
+**Before (AI):**
+> The **platform** offers **native integration** with leading **CRMs**, ensuring **scalability** and **security** for **sales** and **marketing** teams.
+
+**After (human):**
+> The platform integrates with the major CRMs. Works well for sales and marketing teams that need to scale without losing access control.
+
+**Detection signals:**
+- Bold on more than 1-2 terms per paragraph
+- Bold on common nouns (platform, team, result) without editorial reason
+- Bold used as substitute for good sentence structure
+- Text where >5% of words are bolded
+
+**Correction techniques:**
+- **Limit of 1-2 bolds per section** - never per paragraph
+- Use bold only for **intentional contrast**: "The problem isn't the tool - it's the **process**"
+- If bold is compensating for lack of clarity, **restructure the sentence** instead
+- "Print test" - if text looks like it was formatted for a reader with ADHD, bold is excessive
+
+---
+
+### 3. List-ification (Bullet Point Abuse)
+
+**Problem:** AI converts prose into bullet points at every opportunity. Three sentences of flowing text become a bulleted list with "Key takeaways:" above it. Human writing uses lists sparingly - for actual enumerations, not for every paragraph.
+
+**Before (AI):**
+> Here are the key benefits:
+> - **Increased efficiency** - Teams work 40% faster
+> - **Improved collaboration** - Cross-functional alignment
+> - **Better outcomes** - Measurable ROI improvements
+> - **Scalability** - Grows with your organization
+
+**After (human):**
+> Teams work faster with it - about 40% based on our internal tracking. The real win is cross-functional alignment though: people who never talked to each other before are now in the same workflow.
+
+**Detection signals:**
+- Bulleted lists that could be flowing prose
+- "Key takeaways:" / "Key points:" / "Here's what you need to know:" above lists
+- Parallel structure in every bullet (same length, same construction)
+- Lists with 5+ items where 3 would suffice
+
+**Correction techniques:**
+- If items are truly discrete enumerable things (steps, features, names), keep as list
+- If items are connected thoughts, convert to prose paragraphs
+- Break bullet symmetry: vary length, mix sentence fragments with full sentences
+- "Would I say this aloud as a list?" test - if you'd narrate it, it's prose
+
+---
+
+### 4. Header Proliferation
+
+**Problem:** AI creates a `##` header for every 2-3 paragraphs in any text longer than 400 words. Human prose flows continuously - headers appear when genuinely changing topic, not every 150 words.
+
+**Before (AI):**
+> ## Introduction
+> The problem is clear.
+> ## Background  
+> Here's context.
+> ## Current Situation
+> Things have changed.
+> ## Analysis
+> Let's examine this.
+> ## Conclusion
+> In summary...
+
+**After (human):**
+> The problem is clear - and it's been getting worse since 2023. [continues flowing for 800 words with maybe one section break where the topic genuinely shifts]
+
+**Detection signals:**
+- Headers every 100-200 words in what should be continuous prose
+- Generic headers: "Introduction", "Background", "Analysis", "Conclusion"
+- Headers that just restate what the next paragraph says
+- Document with 8+ headers for 1000 words
+
+---
+
+### 5. Emoji Inflation
+
+**Problem:** AI (especially ChatGPT) injects emoji into every bullet point, section header, or list item. Human writers use emoji occasionally and contextually, not systematically.
+
+**Before (AI):**
+> 🚀 Key Features
+> ✅ Automated deployment
+> 💡 Smart suggestions
+> 🔒 Enterprise security
+> ⚡ Lightning-fast performance
+
+**After (human):**
+> The main features: automated deployment, smart suggestions, enterprise-grade security, and good performance. (It handles 10k requests/second on our benchmark.)
+
+**Detection signals:**
+- Emoji on every list item
+- Emoji in headers
+- More than 2 emoji per 500 words in professional text
+- Systematic emoji (same emoji category repeated: all checkmarks, all rockets)
+
+**Correction techniques:**
+- Professional context: remove all emoji unless the format genuinely calls for them (social posts, chat)
+- Social context: keep 1-2 per post, used for emphasis or tone, not decoration
+- Never use emoji as bullet point markers in serious writing
--- a/.github/skills/human-ai/references/patterns-tone.md
+++ b/.github/skills/human-ai/references/patterns-tone.md
@@ -0,0 +1,103 @@
+# Tone Patterns - Detection and Correction
+
+Patterns betraying artificial, servile, or performative tone in English text. Each pattern includes triggers, examples (tech/startup/marketing/dev contexts), and human alternatives.
+
+---
+
+### 1. Sycophantic Tone
+
+**Trigger words/phrases:** "Great question!", "Absolutely!", "Excellent observation!", "I hope this helps!", "I'm happy to help!", "Thank you for sharing!"
+
+**Problem:** Generic praise to the interlocutor before answering. Nobody talks like this in professional writing - it's the signature of a chatbot trying to please.
+
+**Before (AI):**
+> Great question! Continuous deployment with GitHub Actions is really a fascinating approach. I'd be happy to help you with that! Let's dive in: first, you need to configure the workflow YAML...
+
+**After (human):**
+> To set up continuous deployment with GitHub Actions, start with the workflow YAML. Create a `.github/workflows/deploy.yml` triggered on push to main...
+
+**Cut on sight:**
+- "Great question!" / "Excellent point!"
+- "Absolutely!" / "Definitely!"
+- "I hope this helps!" / "Happy to contribute!"
+
+---
+
+### 2. Knowledge-Cutoff Disclaimers
+
+**Trigger words/phrases:** "As of my last update...", "Based on the information available to me...", "As of my knowledge cutoff...", "I cannot confirm with certainty, but...", "According to my limited information..."
+
+**Problem:** Exposes the machine nature of the author. Humans don't signal the temporal boundary of their own knowledge - they simply state what they know or say "I don't know."
+
+**Before (AI):**
+> As of my last update, Next.js 15 introduced Server Actions as a stable feature. However, more recent developments may have changed this landscape. Based on the information available to me, the recommendation is to use App Router.
+
+**After (human):**
+> Next.js 15 stabilized Server Actions. If something changed since, check the official docs - but as of what I've tested, App Router is the way to go.
+
+---
+
+### 3. Residual Collaborative Communication
+
+**Trigger words/phrases:** "Here's an example of...", "I can help you with...", "I'll show you how...", "Below is...", "Feel free to ask more!", "Don't hesitate to reach out!"
+
+**Problem:** Text retains traces of assistant-user interaction. Reads like a support response, not authored text. When published as an article or post, immediately betrays its origin.
+
+**Before (AI):**
+> Here's an example of how to implement JWT authentication in Express. I'll walk you through the setup step by step. Feel free to adapt according to your needs!
+
+**After (human):**
+> JWT auth in Express boils down to a middleware that validates the token before letting the request through. The basic setup looks like this:
+
+---
+
+### 4. Excessive Hedging
+
+**Trigger words/phrases:** "it seems", "perhaps", "it could be that", "one might argue", "it's possible that", "it may be the case", "to some extent", "in a sense"
+
+**Problem:** AI over-qualifies every statement to avoid being wrong. The result is prose with no conviction. Reads like someone trying to never be pinned down on anything.
+
+**Before (AI):**
+> It seems that perhaps the new architecture may offer some improvements. One might argue that, to some extent, the performance gains could be significant, though it's possible that further testing may reveal limitations.
+
+**After (human):**
+> The new architecture is faster. Our benchmarks show 40% improvement on cold starts. Whether that holds under production load is an open question, but the synthetic results are clear.
+
+**Rule:** Qualify only when:
+- You genuinely don't know (and say so directly: "I don't know")
+- There's real disagreement among sources (cite both)
+- The data genuinely doesn't support a firm claim (show the data)
+
+Otherwise: commit to the claim.
+
+---
+
+### 5. Stakes Inflation
+
+**Trigger words/phrases:** "crucial for the future of humanity", "this will define a generation", "the most important challenge of our time", "could fundamentally alter the course of", "the stakes have never been higher"
+
+**Problem:** AI inflates the importance of everything to sound thoughtful. A CSS framework becomes "crucial for the future of web development". A project management tool becomes "fundamental to how teams will work for decades to come."
+
+**Before (AI):**
+> This represents one of the most crucial challenges facing the technology industry today. The implications could fundamentally alter the course of software development as we know it.
+
+**After (human):**
+> It's a hard problem. The teams I've seen tackle it took 6-12 months to get right. Most gave up and used the workaround instead.
+
+**Rule:** Match stakes to scope. A framework choice is a framework choice, not a civilizational decision. Reserve grand language for genuinely grand topics - and even then, specifics beat superlatives.
+
+---
+
+### 6. False Empathy / Emotional Performance
+
+**Trigger words/phrases:** "I understand how frustrating this must be", "I can only imagine how difficult", "This is truly inspiring", "What an incredible journey", "I'm deeply moved by"
+
+**Problem:** AI performs emotions it cannot have. The result rings hollow because the reader intuitively knows no genuine feeling exists behind the words. Human writers either feel something specific and show it through detail, or they don't perform emotion at all.
+
+**Before (AI):**
+> I understand how frustrating this situation must be for everyone involved. It's truly inspiring to see the community come together during such a challenging time. What an incredible journey this has been.
+
+**After (human):**
+> That sucks. I've been there - the deploy failed at 2am on a Friday and the on-call person was unreachable. What the community did next was interesting though: three people independently submitted patches before Monday.
+
+**Rule:** Show, don't perform. If you feel something, name it specifically. If you don't, don't fake it.
--- a/.github/skills/human-ai/references/presets.md
+++ b/.github/skills/human-ai/references/presets.md
@@ -0,0 +1,150 @@
+# Voice Calibration - Presets (Full Reference)
+
+Detailed characteristics, examples, and guidelines for each voice preset.
+
+
+## 🖋️ Essay (default)
+
+Tone of an English essayist. Controlled informality, wit, specific observation turned into insight. Mixes high and low register. A turn at the end.
+
+**Characteristics:**
+- "Look" and "honestly" coexist with precise vocabulary
+- Sentence fragments as dramatic pause
+- Dry humor, self-awareness
+- Explicit opinion
+- Rhetorical questions left unanswered
+
+**Example:**
+> Everyone knows that coworker who automated their own job and told nobody. Sat there for months pretending to type. Well. Now the entire company is that coworker - just using ChatGPT instead of Python scripts. The difference is nobody's pretending. And so the question becomes: efficiency or laziness? I don't know. Probably both.
+
+
+## 📰 Journalistic
+
+Tone of the NYT or The Atlantic. Maximum clarity, concrete data, no fluff.
+
+**Characteristics:**
+- Subject + verb + object (in that order)
+- Numbers and dates whenever possible
+- Attribution to named sources
+- No evaluative adjectives
+- No first person (except opinion columns)
+
+**Example:**
+> Nubank laid off 40 people from its customer service team in May. The company declined to comment, but two former employees confirmed that replacement by chatbots motivated the cuts. The department had 120 people at the start of the year.
+
+
+## 🎓 Academic
+
+Formal but not bureaucratic. Terminological rigor without officialese.
+
+**Characteristics:**
+- Precise domain vocabulary
+- Legitimate qualifications (not empty hedging)
+- References to specific authors/studies
+- Avoids cliches: "it is worth noting", "it goes without saying", "in the context of"
+
+**Example:**
+> The convergence-toward-median hypothesis (Nastruzzi, 2026) finds support in TTR analysis of texts submitted to multiple AI refinement cycles. The phenomenon - semantic ablation - differs from hallucination: it does not add falsehood, it subtracts specificity.
+
+
+## 💬 Corporate Informal
+
+Startup email, professional Slack. Direct, light, no corporate speak.
+
+**Characteristics:**
+- Short, direct sentences
+- Contractions used naturally
+- Action verbs instead of nominalizations
+- Tech jargon where appropriate (deploy, sprint, ship)
+
+**Example:**
+> Team, quick update: the hotfix went out last night, already in prod. The duplication bug stopped since 11pm. I'll monitor for another 48h and if it stays clean, we close the issue. Ping me if anything pops up.
+
+
+## 📱 Social Post
+
+LinkedIn or Twitter/X. Short, opinionated, hook in the first line.
+
+**Characteristics:**
+- First sentence is the hook
+- Paragraphs of 1-2 lines
+- Strong personal opinion
+- Uses "I" freely
+- Subtle or no CTA
+
+**Example:**
+> I fired ChatGPT from my writing workflow.
+>
+> Not because it's bad. Because everything I published sounded like everyone else.
+>
+> I went back to writing by hand. Takes 3x longer. But people actually reply now.
+>
+> Efficiency without voice isn't an advantage. It's invisibility.
+
+
+## 💬 Casual/DM
+
+Maximum orality. Stream of consciousness allowed.
+
+**Characteristics:**
+- Incomplete sentences ok
+- Natural abbreviations (tbh, ngl, idk)
+- Slang accepted
+- Zero concern with formal grammar
+
+**Example:**
+> dude did you see what the data team did
+>
+> they pushed a model to prod without telling anyone
+>
+> then it started sending wrong emails to clients
+>
+> absolute chaos
+
+
+## ⚖️ Legal / Formal
+
+Briefs, memos, formal notices. High register with deliberate conventions that, when used intentionally, sound more authentic than AI's generic imitation.
+
+**Characteristics:**
+- Structure: background -> facts -> analysis -> conclusion/recommendation
+- Controlled use of genre conventions ("notwithstanding", "hereinafter", "pursuant to")
+- Citation of specific statutes, cases, regulations
+- Active voice when possible to avoid bureaucratic emptiness
+
+**Signs of AI in this register:**
+- Excess "it is worth noting", "it should be emphasized", "in the context of this analysis"
+- Generic citations without case numbers or statute references
+- Perfectly symmetrical paragraphs (3-4 identical-length sentences)
+
+**Example (AI -> Human):**
+> *AI*: "It is well-established that the right to privacy must be balanced against public interest, as consistently recognized by relevant jurisprudence. It should be noted that the present case requires careful analysis."
+>
+> *Human*: "The right to privacy exists, yes - but it's not absolute. The Supreme Court held in *Carpenter v. United States*, 585 U.S. 296 (2018), that public interest can prevail. In this case, the photo was taken at a public event. The question is whether there was commercial exploitation. That's what separates privacy from publicity rights."
+
+**What to preserve (not an AI sign):**
+- Section headings in caps ("BACKGROUND", "ANALYSIS", "CONCLUSION") - expected formatting in briefs
+- Numbered items in arguments and requests
+- Citation with specific case numbers and dates
+- Background -> facts -> analysis -> conclusion structure - it's the genre, not AI template
+
+**Key signal separating human from AI in this register:** humans cite specific case numbers, statutes, sections. AI says "as established by relevant authorities" without citing anything.
+
+
+## 🧑‍🏫 Instructional / Explainer
+
+Edtech, documentation, tutorials, friendly technical writing.
+
+**Characteristics:**
+- Pattern: question -> explanation -> concrete example -> reinforcement
+- Accessible but precise vocabulary (not dumbed down)
+- Specific, verifiable examples (not "Alice has 3 apples")
+- Explicit transitions: "So", "Now", "Let's see this in practice"
+
+**Signs of AI in this register:**
+- Generic, artificial examples
+- Encyclopedic tone without interaction with reader
+- "In this chapter, we will explore X, Y and Z" -> empty template
+
+**Example:**
+> Let's cut to it: a *callback* is a function you pass as an argument to another function, so it can "call you back" when it's done. Sounds complicated, but that's all it is. Think of ordering delivery: instead of calling every 5 minutes to check if it arrived, you leave your number and the driver texts you when they're at the door. Your number is the callback.
--- a/.github/skills/human-ai/references/summary.md
+++ b/.github/skills/human-ai/references/summary.md
@@ -0,0 +1,22 @@
+# Summary - Skill Human-AI v1.0.0
+
+1. [Operating Modes](#operating-modes)
+2. [Guardrails](#guardrails)
+3. [Personality & Soul - The Essayist Tradition](#personality--soul---the-essayist-tradition)
+4. [Voice Calibration - Presets](#voice-calibration---presets)
+   - Essay · Journalistic · Academic · Corporate Informal · Social Post · Casual/DM · **Legal** · **Instructional**
+5. [Humanization Process (7 steps)](#humanization-process)
+   - Step 0 - Quantitative ablation measurement
+   - Step 0.5 - Automatic type detection
+   - Step 1 - Diagnosis with structured checklist
+   - Step 2 - Pattern removal
+   - Step 3 - Entropy restoration
+   - Step 4 - Voice injection
+   - Step 5 - Final anti-AI pass
+   - Step 5.5 - Post-rewrite scoring
+   - Step 6 - Formatted delivery
+6. [The 29 AI Vocabulary Patterns](#the-29-ai-vocabulary-patterns-english)
+7. [Contraction Rules](#contraction-rules-english-specific)
+8. [Regression Test Suite](#regression-test-suite)
+9. [Limits and Contraindications](#limits-and-contraindications)
+10. [References](#references)
--- a/.github/skills/human-ai/references/tests.md
+++ b/.github/skills/human-ai/references/tests.md
@@ -0,0 +1,14 @@
+# Regression Test Suite (Full Reference)
+
+Minimum sample set for validating future evolutions. Each test should run in full_mode and verify output matches expected result.
+
+| # | Type | Before (AI) | After expected (synthesis) |
+|---|---|---|---|
+| T1 | Corporate email | "I am writing to inform you that the report will be forwarded in due course" | "Hey team, report's done - just sent it to the channel. Ping me with questions." |
+| T2 | Academic paragraph | "Various authors discuss the question of language in broad terms" | "Foucault (1977) frames language as a power device; Bakhtin (1981) sees it as a dialogic arena. The disagreement isn't just terminological." |
+| T3 | Legal text | "It is well-established that strict liability applies in the context of consumer relations" | "The Consumer Protection Act establishes strict liability under Section 402A. In practice, manufacturers only escape liability by proving sole consumer fault - which is rare." |
+| T4 | Blog template | "In this article, we will explore 5 essential strategies to optimize your workflow" | "I'll cut to it: the strategy that saved me the most time in 2025 wasn't a new tool. It was stopping using new tools." |
+| T5 | AI hedging | "As a language model, I cannot state with certainty, but it appears that perhaps the system may be functioning" | "The system's working. I just tested it and the endpoint responded in 340ms." |
+| T6 | Generic explainer | "Alice has 3 apples and Bob has 5. How many do they have together?" | "Think about the last time you split a restaurant bill. That's the arithmetic that matters - not hypothetical apples." |
+
+> **Regression criterion**: if an evolution worsens any T1-T6 test result, the change must be reevaluated.
--- a/.github/skills/human-ai/scripts/measure.py
+++ b/.github/skills/human-ai/scripts/measure.py
@@ -0,0 +1,353 @@
+#!/usr/bin/env python3
+"""
+measure.py — AI vs Human text metrics analyzer.
+
+Usage:
+    echo "some text" | python3 measure.py
+    python3 measure.py --file path/to/text.txt
+
+Calculates linguistic metrics (TTR, burstiness, entropy, sentence/paragraph
+variation, passive voice, contractions, etc.) and compares against empirical
+baselines to produce a verdict: likely_ai, mixed, or likely_human.
+
+Requires Python 3.10+. No external dependencies.
+"""
+
+import argparse
+import json
+import math
+import re
+import statistics
+import sys
+from collections import Counter
+
+
+# --- Empirical baselines ---
+BASELINES = {
+    "ttr": {"ai_typical": 0.455, "human_typical": 0.553, "source": "SSRN"},
+    "burstiness": {"ai_typical": 0.00, "human_typical": 0.70, "source": "GPTZero"},
+    "sentence_length_cov": {"ai_typical": 0.30, "human_typical": 0.50},
+    "paragraph_length_cov": {"ai_typical": 0.30, "human_typical": 0.60},
+    "contraction_rate": {"ai_typical_range": [0.30, 0.50], "human_typical_range": [0.80, 0.95]},
+    "passive_voice_pct": {"ai_typical": 0.30, "human_typical_range": [0.10, 0.20]},
+}
+
+# Common contractions and their expanded forms
+CONTRACTION_PAIRS = {
+    "i'm": "i am", "i've": "i have", "i'll": "i will", "i'd": "i would",
+    "you're": "you are", "you've": "you have", "you'll": "you will", "you'd": "you would",
+    "he's": "he is", "he'll": "he will", "he'd": "he would",
+    "she's": "she is", "she'll": "she will", "she'd": "she would",
+    "it's": "it is", "it'll": "it will", "it'd": "it would",
+    "we're": "we are", "we've": "we have", "we'll": "we will", "we'd": "we would",
+    "they're": "they are", "they've": "they have", "they'll": "they will", "they'd": "they would",
+    "that's": "that is", "there's": "there is", "here's": "here is",
+    "what's": "what is", "who's": "who is", "where's": "where is",
+    "won't": "will not", "can't": "cannot", "couldn't": "could not",
+    "wouldn't": "would not", "shouldn't": "should not", "doesn't": "does not",
+    "don't": "do not", "didn't": "did not", "isn't": "is not",
+    "aren't": "are not", "wasn't": "was not", "weren't": "were not",
+    "hasn't": "has not", "haven't": "have not", "hadn't": "had not",
+    "let's": "let us", "that'll": "that will", "who'll": "who will",
+}
+
+# Expanded forms to detect (when NOT contracted)
+EXPANDED_FORMS = set(CONTRACTION_PAIRS.values())
+
+# Common concrete nouns (physical, tangible objects)
+CONCRETE_PATTERNS = re.compile(
+    r"\b(table|chair|car|house|tree|dog|cat|book|phone|door|window|wall|"
+    r"road|water|stone|hand|face|eye|foot|head|body|room|floor|glass|"
+    r"box|bag|cup|plate|knife|pen|paper|shirt|shoe|hat|bed|desk|"
+    r"computer|screen|keyboard|mouse|bottle|lamp|clock|mirror|bridge|"
+    r"river|mountain|ocean|sun|moon|star|cloud|rain|snow|fire|smoke|"
+    r"bread|meat|fruit|flower|grass|sand|iron|gold|silver|wood|rock|"
+    r"truck|bus|train|plane|boat|ship|bicycle|wheel|engine|hammer|"
+    r"needle|rope|chain|brick|coin|ring|bell|drum|guitar|piano)\b",
+    re.IGNORECASE,
+)
+
+# Abstract nouns (concepts, ideas, qualities)
+ABSTRACT_PATTERNS = re.compile(
+    r"\b(freedom|justice|love|beauty|truth|wisdom|knowledge|power|"
+    r"happiness|sadness|anger|fear|hope|faith|courage|patience|"
+    r"democracy|philosophy|theory|concept|idea|thought|belief|"
+    r"understanding|experience|opportunity|challenge|strategy|"
+    r"approach|methodology|framework|perspective|consideration|"
+    r"implementation|optimization|functionality|capability|"
+    r"efficiency|effectiveness|sustainability|innovation|"
+    r"transformation|development|improvement|enhancement|"
+    r"complexity|simplicity|diversity|integrity|creativity)\b",
+    re.IGNORECASE,
+)
+
+
+def tokenize(text: str) -> list[str]:
+    """Split text into lowercase word tokens."""
+    return re.findall(r"[a-z']+", text.lower())
+
+
+def split_sentences(text: str) -> list[str]:
+    """Split text into sentences using punctuation boundaries."""
+    sentences = re.split(r'(?<=[.!?])\s+', text.strip())
+    return [s for s in sentences if s.strip()]
+
+
+def split_paragraphs(text: str) -> list[str]:
+    """Split text into paragraphs by blank lines."""
+    paragraphs = re.split(r'\n\s*\n', text.strip())
+    return [p for p in paragraphs if p.strip()]
+
+
+def calc_ttr(tokens: list[str]) -> float:
+    """Type-Token Ratio: unique tokens / total tokens."""
+    if not tokens:
+        return 0.0
+    return len(set(tokens)) / len(tokens)
+
+
+def calc_burstiness(sentences: list[str]) -> float:
+    """Standard deviation of sentence lengths (word count per sentence)."""
+    lengths = [len(s.split()) for s in sentences]
+    if len(lengths) < 2:
+        return 0.0
+    return statistics.stdev(lengths)
+
+
+def calc_shannon_entropy(tokens: list[str]) -> float:
+    """Shannon entropy: -sum p(x)*log2(p(x)) over vocabulary."""
+    if not tokens:
+        return 0.0
+    total = len(tokens)
+    counts = Counter(tokens)
+    entropy = 0.0
+    for count in counts.values():
+        p = count / total
+        if p > 0:
+            entropy -= p * math.log2(p)
+    return entropy
+
+
+def calc_sentence_length_cov(sentences: list[str]) -> float:
+    """Coefficient of variation of sentence lengths: std/mean."""
+    lengths = [len(s.split()) for s in sentences]
+    if len(lengths) < 2:
+        return 0.0
+    mean = statistics.mean(lengths)
+    if mean == 0:
+        return 0.0
+    return statistics.stdev(lengths) / mean
+
+
+def calc_mean_sentence_length(sentences: list[str]) -> float:
+    """Mean sentence length in words."""
+    lengths = [len(s.split()) for s in sentences]
+    if not lengths:
+        return 0.0
+    return statistics.mean(lengths)
+
+
+def calc_paragraph_length_cov(paragraphs: list[str]) -> float:
+    """Coefficient of variation of paragraph lengths (in sentences)."""
+    if len(paragraphs) < 2:
+        return 0.0
+    lengths = [len(split_sentences(p)) for p in paragraphs]
+    mean = statistics.mean(lengths)
+    if mean == 0:
+        return 0.0
+    return statistics.stdev(lengths) / mean
+
+
+def calc_ly_adverbs_per_100(tokens: list[str]) -> float:
+    """Count adverbs ending in -ly per 100 words."""
+    if not tokens:
+        return 0.0
+    # Exclude common non-adverb -ly words
+    exceptions = {
+        "only", "early", "likely", "family", "really", "actually",
+        "finally", "fly", "supply", "apply", "reply", "holy",
+        "ugly", "belly", "jelly", "bully", "ally", "rally",
+    }
+    ly_count = sum(
+        1 for t in tokens
+        if t.endswith("ly") and len(t) > 3 and t not in exceptions
+    )
+    return (ly_count / len(tokens)) * 100
+
+
+def calc_passive_voice_pct(text: str) -> float:
+    """Approximate passive voice: was/were/been/being + past participle pattern."""
+    sentences = split_sentences(text)
+    if not sentences:
+        return 0.0
+    passive_pattern = re.compile(
+        r'\b(was|were|been|being|is|are|am)\s+(\w+ed|(\w+en))\b',
+        re.IGNORECASE,
+    )
+    passive_count = sum(1 for s in sentences if passive_pattern.search(s))
+    return passive_count / len(sentences)
+
+
+def calc_contraction_rate(text: str) -> float:
+    """Percentage of contractable phrases that ARE contracted."""
+    text_lower = text.lower()
+    tokens_raw = re.findall(r"[a-z']+", text_lower)
+    text_joined = " ".join(tokens_raw)
+
+    contracted_count = 0
+    expanded_count = 0
+
+    # Count contractions present
+    for contraction in CONTRACTION_PAIRS:
+        contracted_count += text_joined.count(contraction)
+
+    # Count expanded forms present (not contracted)
+    for expanded in EXPANDED_FORMS:
+        expanded_count += text_joined.count(expanded)
+
+    total = contracted_count + expanded_count
+    if total == 0:
+        return 0.0
+    return contracted_count / total
+
+
+def calc_concrete_noun_density(tokens: list[str]) -> float:
+    """Ratio of concrete nouns to (concrete + abstract) nouns found."""
+    text = " ".join(tokens)
+    concrete_matches = len(CONCRETE_PATTERNS.findall(text))
+    abstract_matches = len(ABSTRACT_PATTERNS.findall(text))
+    total = concrete_matches + abstract_matches
+    if total == 0:
+        return 0.5  # neutral if can't determine
+    return concrete_matches / total
+
+
+def score_metric(name: str, value: float) -> str:
+    """Score a metric as 'ai', 'human', or 'neutral'."""
+    match name:
+        case "ttr":
+            midpoint = (BASELINES["ttr"]["ai_typical"] + BASELINES["ttr"]["human_typical"]) / 2
+            return "human" if value > midpoint else "ai"
+        case "burstiness":
+            midpoint = (BASELINES["burstiness"]["ai_typical"] + BASELINES["burstiness"]["human_typical"]) / 2
+            return "human" if value > midpoint else "ai"
+        case "sentence_length_cov":
+            midpoint = (BASELINES["sentence_length_cov"]["ai_typical"] + BASELINES["sentence_length_cov"]["human_typical"]) / 2
+            return "human" if value > midpoint else "ai"
+        case "paragraph_length_cov":
+            midpoint = (BASELINES["paragraph_length_cov"]["ai_typical"] + BASELINES["paragraph_length_cov"]["human_typical"]) / 2
+            return "human" if value > midpoint else "ai"
+        case "contraction_rate":
+            if value >= 0.65:
+                return "human"
+            elif value <= 0.40:
+                return "ai"
+            return "neutral"
+        case "passive_voice_pct":
+            if value > 0.25:
+                return "ai"
+            elif value <= 0.20:
+                return "human"
+            return "neutral"
+        case "ly_adverbs_per_100":
+            # AI tends to overuse adverbs
+            if value > 2.5:
+                return "ai"
+            elif value < 1.5:
+                return "human"
+            return "neutral"
+        case "concrete_noun_density":
+            # Humans use more concrete language
+            if value > 0.55:
+                return "human"
+            elif value < 0.40:
+                return "ai"
+            return "neutral"
+        case _:
+            return "neutral"
+
+
+def determine_verdict(scores: dict[str, str]) -> str:
+    """Determine overall verdict based on majority of metric signals."""
+    ai_count = sum(1 for v in scores.values() if v == "ai")
+    human_count = sum(1 for v in scores.values() if v == "human")
+    total_decisive = ai_count + human_count
+
+    if total_decisive == 0:
+        return "mixed"
+    ai_ratio = ai_count / total_decisive
+    if ai_ratio >= 0.6:
+        return "likely_ai"
+    elif ai_ratio <= 0.4:
+        return "likely_human"
+    return "mixed"
+
+
+def analyze(text: str) -> dict:
+    """Run full analysis on input text."""
+    tokens = tokenize(text)
+    sentences = split_sentences(text)
+    paragraphs = split_paragraphs(text)
+
+    metrics = {
+        "ttr": round(calc_ttr(tokens), 4),
+        "burstiness": round(calc_burstiness(sentences), 4),
+        "shannon_entropy": round(calc_shannon_entropy(tokens), 4),
+        "sentence_length_cov": round(calc_sentence_length_cov(sentences), 4),
+        "mean_sentence_length": round(calc_mean_sentence_length(sentences), 2),
+        "paragraph_length_cov": round(calc_paragraph_length_cov(paragraphs), 4),
+        "ly_adverbs_per_100": round(calc_ly_adverbs_per_100(tokens), 4),
+        "passive_voice_pct": round(calc_passive_voice_pct(text), 4),
+        "contraction_rate": round(calc_contraction_rate(text), 4),
+        "concrete_noun_density": round(calc_concrete_noun_density(tokens), 4),
+    }
+
+    scored_metrics = [
+        "ttr", "burstiness", "sentence_length_cov", "paragraph_length_cov",
+        "contraction_rate", "passive_voice_pct", "ly_adverbs_per_100",
+        "concrete_noun_density",
+    ]
+    signals = {name: score_metric(name, metrics[name]) for name in scored_metrics}
+    verdict = determine_verdict(signals)
+
+    return {
+        "metrics": metrics,
+        "signals": signals,
+        "verdict": verdict,
+        "baselines": BASELINES,
+        "meta": {
+            "total_tokens": len(tokens),
+            "unique_tokens": len(set(tokens)),
+            "total_sentences": len(sentences),
+            "total_paragraphs": len(paragraphs),
+        },
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Analyze text for AI vs human authorship signals.",
+    )
+    parser.add_argument(
+        "--file", "-f",
+        type=str,
+        help="Path to text file to analyze (reads stdin if omitted)",
+    )
+    args = parser.parse_args()
+
+    if args.file:
+        with open(args.file, encoding="utf-8") as f:
+            text = f.read()
+    else:
+        text = sys.stdin.read()
+
+    if not text.strip():
+        print(json.dumps({"error": "Empty input"}), file=sys.stdout)
+        sys.exit(1)
+
+    result = analyze(text)
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()
--- a/.github/skills/humanizar/SKILL.md
+++ b/.github/skills/humanizar/SKILL.md
@@ -0,0 +1,534 @@
+---
+name: humanizar
+description: |
+  Reescreve textos em português brasileiro para soarem mais humanos e naturais,
+  reduzindo padrões típicos de escrita gerada por IA sem alterar fatos, argumento
+  ou intenção. Use quando o texto em PT-BR parecer genérico, burocrático ou gerado
+  por IA, ou quando o usuário pedir para "humanizar", "dar vida", "tirar cara de
+  IA", "remover AI slop" ou "reescrever com voz". Para textos em inglês, use a
+  skill-irmã `human-ai`.
+metadata:
+  author: https://ft.ia.br
+  version: "1.3.0"
+  date: 2026-06-17
+  repository: https://github.com/fabricioctelles/skills
+  license: Apache 2.0
+  category: code-quality-and-review
+---
+
+# Humanizar: Escrita Viva em Português Brasileiro
+
+Atue como editor. Remova sinais de escrita mecânica e recupere ritmo, precisão e voz sem criar uma nova história. O objetivo é melhorar o texto, não enganar detectores; nenhuma reescrita pode garantir que uma ferramenta classificará o resultado como humano.
+
+## Proteções obrigatórias
+
+1. **TRAVA FACTUAL — definição canônica.** Trate o texto-fonte como imutável. Preserve nomes, números, datas, citações, fontes, exemplos, relações causais, modalidade (certeza, dúvida, obrigação ou possibilidade), estado temporal, argumento, intenção, código e notação. Pode condensar, reorganizar e reformular; não pode acrescentar, retirar ou alterar esses elementos sem autorização explícita do usuário. Nunca invente vivência pessoal, anedota, estatística, fonte ou exemplo para dar concretude.
+2. **Concretude sem invenção.** Reutilize detalhes já presentes. Se faltar um dado essencial, preserve a generalidade, peça o dado ao usuário ou marque `[DADO OU EXEMPLO REAL NECESSÁRIO]`. Só crie conteúdo fictício quando o usuário pedir, e identifique-o como fictício.
+3. **Argumento preservado.** Mantenha a posição e a conclusão do autor, mesmo que discorde delas.
+4. **Registro preservado.** Não force informalidade, primeira pessoa, humor ou opinião. O perfil de voz orienta a forma; não autoriza conteúdo novo.
+5. **Precisão antes de estilo.** Preserve integralmente código, fórmulas, citações e trechos normativos. Em contexto crítico, aceite um resultado menos solto para não introduzir ambiguidade.
+6. **Sem infantilização.** Simplificar a forma não significa simplificar o raciocínio.
+
+Toda verificação posterior de **TRAVA FACTUAL** remete a esta definição. Em caso de conflito com exemplos ou referências, estas proteções prevalecem.
+
+## Triagem obrigatória
+
+Executar antes de diagnosticar ou reescrever:
+
+1. Confirmar que há texto e que ele está em PT-BR. Para inglês, usar [`human-ai`](../human-ai/SKILL.md). Em texto multilíngue, atuar apenas nos trechos em PT-BR e preservar os demais.
+2. Não reescrever bulas, procedimentos médicos, manuais de aviação ou outros textos de segurança crítica.
+3. Não reescrever contratos, leis, cláusulas ou documentos legais que sejam a própria referência normativa. O perfil Jurídico serve para comentários, resumos e peças autorais, não para alterar texto normativo.
+4. Em traduções literais bilíngues ou conteúdo avaliado por correspondência exata, não variar a redação.
+5. Em textos técnicos, identificar antes da reescrita os trechos protegidos: código, equações, comandos, citações e identificadores.
+6. Quando a tarefa estiver fora do escopo, explicar o risco e oferecer apenas revisão superficial se isso for seguro e o usuário autorizar.
+
+## Modos de operação
+
+O modo altera o nível do relatório e o número máximo de tentativas; não altera as proteções.
+
+| Modo | Quando usar | Tentativas máximas | Entrega |
+|---|---|---:|---|
+| `modo_completo` (padrão) | Pedido comum de humanização | 3 | Texto final, pontuação e resumo das mudanças |
+| `modo_direto` | Fluxo automatizado ou pedido de rapidez | 1 | Texto final e relatório sintético; sem repetição automática |
+| `modo_revisão` | Auditoria de texto produzido por outro agente | 3 | Texto final, diagnóstico e relatório detalhado |
+
+Preservar sempre o modo escolhido pelo usuário. Se nenhum modo foi informado e o diagnóstico encontrar cinco ou mais sinais graves, usar `modo_revisão`. Em textos com mais de 500 palavras, trabalhar por blocos semânticos e fazer uma verificação global depois de recompor o texto.
+
+## Perfis de voz
+
+Os perfis de voz orientam escolhas de ritmo e registro. Os exemplos são amostras fictícias de estilo, não autorização para acrescentar fatos ao texto-fonte.
+
+### 🖋️ Crônica
+
+Tom de cronista brasileiro. Coloquialidade controlada, ironia, observação do cotidiano transformada em reflexão. Mistura de registros alto e baixo. Virada reflexiva no final.
+Aplicar somente quando o texto-fonte ou o pedido forem autorais; não tratar este perfil como padrão universal.
+
+**Características:**
+- "A gente" convive com mais-que-perfeito simples
+- Fragmentos de frase como pausa dramática
+- Humor seco e autoironia quando já pertencem à voz ou foram pedidos
+- Posição autoral explícita, sem criar opinião nova
+- Perguntas retóricas que ficam sem resposta
+
+**Exemplo:**
+> Todo mundo conhece aquele colega que automatizou o próprio trabalho e não contou pra ninguém. Ficou meses fingindo que digitava. Pois é. Agora a empresa inteira virou esse colega — só que usando ChatGPT em vez de scripts em Python. A diferença é que ninguém tá fingindo. E aí fica a dúvida: eficiência ou preguiça? Sei lá. Provavelmente os dois.
+
+### 📰 Jornalístico
+
+Tom de reportagem da Folha ou Piauí. Clareza máxima, dados concretos, sem firula.
+
+**Características:**
+- Sujeito + verbo + complemento (nessa ordem)
+- Números e datas quando presentes no texto-fonte
+- Atribuição somente às fontes existentes no texto-fonte
+- Sem adjetivos avaliativos
+- Sem primeira pessoa (exceto coluna assinada)
+
+**Exemplo:**
+> A empresa demitiu 40 pessoas da área de atendimento em maio. Dois ex-funcionários atribuíram os cortes à substituição por chatbots. A assessoria não comentou. A área tinha 120 pessoas no início do ano.
+
+### 🎓 Acadêmico
+
+Formal mas não burocrático. Rigor terminológico sem oficialês.
+
+**Características:**
+- Vocabulário preciso de domínio
+- Qualificações legítimas (não ressalvas vazias)
+- Preservação exata de autores e estudos citados na fonte
+- Evita clichês: "faz-se necessário", "cumpre salientar", "no âmbito de"
+
+**Exemplo:**
+> A convergência para um registro médio pode ser examinada pela variação lexical em textos submetidos a ciclos sucessivos de refinamento. Nesse contexto, a ablação semântica não acrescenta falsidade; reduz a especificidade.
+
+### 💬 Corporativo Informal
+
+E-mail de startup, Slack profissional. Direto, leve, sem gerundismo.
+
+**Características:**
+- Frases curtas e diretas
+- "A gente" em vez de "nós" quando cabe
+- Verbos de ação no lugar de locução verbal
+- Estrangeirismos naturais (deploy, sprint, feedback)
+
+**Exemplo:**
+> Pessoal, atualizando: o hotfix foi deployado ontem à noite, já tá em prod. O bug de duplicação parou desde as 23h. Vou monitorar mais 48h e, se zerar, fechamos a issue. Me pingam se aparecer algo.
+
+### 📱 Post de Rede Social
+
+LinkedIn ou Twitter BR. Curto, opinativo, com gancho na primeira linha.
+
+**Características:**
+- Primeira frase é o gancho
+- Parágrafos de 1-2 linhas
+- Posição autoral clara, sem criar opinião nova
+- Pode usar "eu" quando a fonte já usa primeira pessoa ou o usuário pede
+- Chamada para ação sutil ou nenhuma
+
+**Exemplo:**
+> Eu demiti o ChatGPT do meu fluxo de escrita.
+>
+> Não porque é ruim. Porque tudo que eu publicava soava igual a todo mundo.
+>
+> Voltei a escrever na mão. Demora 3x mais. Mas as pessoas respondem agora.
+>
+> Eficiência sem voz não é vantagem. É invisibilidade.
+
+### 📲 Mensagem de WhatsApp
+
+Oralidade máxima. Fluxo de consciência permitido.
+
+**Características:**
+- Frases incompletas ok
+- Abreviações naturais (vc, tb, mto)
+- Gírias regionais aceitas
+- Zero preocupação com norma culta
+
+**Exemplo:**
+> cara tu viu o que o time de dados fez?
+>
+> meteram um modelo em prod sem avisar ninguém
+>
+> aí começou a mandar e-mail errado pra cliente
+>
+> mó treta
+
+### ⚖️ 🆕 Jurídico / Oficialesco
+
+Petições, pareceres, notificações. Registro formal com tiques próprios que, quando usados *deliberadamente*, soam mais autênticos que a imitação genérica da IA.
+
+**Características:**
+- Estrutura: preâmbulo → fatos → fundamentos → pedido
+- Uso controlado de clichês do gênero ("data venia", "ante o exposto", "é cediço que")
+- Citação de artigos, súmulas, jurisprudência
+- Voz ativa quando possível para evitar burocratês vazio
+
+**Sinais de IA nesse registro:**
+- Excesso de "cumpre salientar", "faz-se mister", "no âmbito desta análise"
+- Citações genéricas sem número de artigo ou lei
+- Parágrafos perfeitamente simétricos (3-4 frases idênticas)
+
+**Exemplo (IA → Humano):**
+> *IA*: "Nos termos do art. 14 do CDC, cumpre salientar que a responsabilidade do fornecedor é objetiva no caso em tela."
+>
+> *Humano*: "O art. 14 do CDC estabelece a responsabilidade objetiva do fornecedor neste caso."
+
+**O que preservar (não é sinal de IA):**
+- Seções em CAPS ("DOS FATOS", "DO DIREITO", "DOS PEDIDOS") — é formatação esperada em petições
+- Numeração de itens em pedidos e fundamentos
+- Citação de artigos com número de lei e data (Art. 14, CDC; Súmula 362/STJ)
+- Estrutura preâmbulo → fatos → fundamentos → pedido — é o gênero, não molde de IA
+
+**Sinal de revisão nesse registro:** atribuição vaga como "conforme entendimento consolidado". Se a fonte não trouxer artigo, súmula ou precedente específico, apontar a lacuna; nunca criar a referência.
+
+### 🧑‍🏫 🆕 Didático / Explicador
+
+Textos de edtech, apostilas, tutoriais, documentação técnica amigável.
+
+**Características:**
+- Padrão: pergunta → explicação → exemplo concreto → reforço
+- Vocabulário acessível mas preciso (sem infantilizar)
+- Exemplos específicos já presentes na fonte ou fornecidos pelo usuário
+- Transições explícitas: "Então", "Agora", "Vamos ver na prática"
+
+**Sinais de IA nesse registro:**
+- Exemplos genéricos e artificiais
+- Tom enciclopédico sem interação com o leitor
+- "Neste capítulo, abordaremos X, Y e Z" → molde vazio
+
+**Exemplo:**
+> Vamos direto ao ponto: *callback* é uma função que você passa como argumento pra outra função, pra ela te "chamar de volta" quando terminar. Parece complicado, mas é só isso. Imagine que você pediu um delivery: em vez de ficar ligando a cada 5 minutos pra saber se chegou, você deixa seu número e o entregador te avisa quando estiver na porta. Seu número é o callback.
+
+### 📋 🆕 Português Simplificado
+
+Texto acessível para público amplo. Inspirado nas operações do PorSimples (NILC/USP) e nas técnicas da Lei 15.263/2025 (Política Nacional de Linguagem Simples). Clareza máxima sem infantilizar o raciocínio.
+
+**Quando usar:**
+- Documentação técnica para público não-especialista
+- Comunicação institucional e governamental
+- Manuais de produto, FAQs, onboarding de usuários
+- Textos para públicos com letramento funcional variado
+- Quando o usuário pedir "simplificar", "linguagem simples", "mais claro", "acessível"
+
+**Características:**
+- Frases curtas em ordem direta (SVO) — meta: 13-18 palavras, máximo 25
+- Uma ideia por frase
+- Vocabulário comum; termo técnico explicado na primeira ocorrência
+- Voz ativa (passiva apenas quando o agente for irrelevante ou desconhecido)
+- Listas e estrutura visual para 3+ itens em sequência
+- Conectivos explícitos e simples ("porque", "por isso", "então", "mas")
+- Sem orações intercaladas longas (apostos > 5 palavras viram frase nova)
+- Repetição deliberada para clareza (não forçar sinônimos variados)
+
+**Operações de simplificação (baseadas no PorSimples):**
+1. Dividir períodos compostos em frases independentes
+2. Converter passiva → ativa
+3. Reordenar para SVO quando houver inversão
+4. Substituir marcadores discursivos complexos por simples
+5. Eliminar apostos longos (transformar em frase separada)
+6. Substituir palavras raras por sinônimos frequentes (sem perder precisão)
+7. Explicitar sujeitos ocultos quando houver ambiguidade
+
+**O que NÃO fazer:**
+- Não eliminar raciocínio complexo — simplificar a forma, não o conteúdo
+- Não remover terminologia de domínio — explicar, não substituir
+- Não transformar toda prosa em lista de bullets indiscriminadamente
+- Não adicionar exemplos fictícios para "ajudar" — usar apenas os da fonte
+- Não reduzir modalidade: "pode causar" não vira "causa"
+
+**Exemplo:**
+> *Antes:* "A implementação de políticas públicas que visem à mitigação dos impactos socioeconômicos decorrentes da automação de processos produtivos configura-se como desafio premente para gestores em todas as esferas do poder público."
+>
+> *Depois:* "A automação muda como as pessoas trabalham. Isso traz problemas sociais e econômicos. Os governos precisam criar políticas para reduzir esses problemas. Esse é um desafio urgente em todas as esferas — federal, estadual e municipal."
+
+## Processo de Humanização
+
+Executar primeiro a **Triagem obrigatória**. Manter `texto_fonte` imutável durante todo o processo.
+
+### Passo 1 — 🎯 Seleção do perfil de voz
+
+Se o usuário não especificou um perfil, detectar pelo conteúdo:
+
+| Sinal no texto | Perfil sugerido |
+|---|---|
+| Citações legais, artigos de lei, "art.", "§", "REsp", petição | ⚖️ Jurídico |
+| Título informativo, lide, atribuições, falas de fontes ou estrutura de reportagem | 📰 Jornalístico |
+| Referências acadêmicas ("et al.", metodologia, hipótese, valor-p) | 🎓 Acadêmico |
+| Tutorial, documentação amigável, "passo a passo" ou "vamos ver" | 🧑‍🏫 Didático |
+| E-mail ou mensagem profissional com jargão técnico e nomes de ferramentas | 💬 Corporativo Informal |
+| Texto ≤100 palavras, frases incompletas, abreviações, gírias | 📲 WhatsApp |
+| Texto curto (<300 palavras), opinativo, em 1ª pessoa, sem estrutura formal | 📱 Post de Rede Social |
+| ≥1500 palavras, narrativo, sem jargão dominante | 🖋️ Crônica |
+| Texto institucional/governamental, manual de produto, FAQ, pedido de "simplificar" ou "linguagem simples" | 📋 Português Simplificado |
+| **Nenhum sinal claro** | Voz neutra — preservar o registro original e apenas remover padrões mecânicos |
+
+**Regras de decisão:**
+
+1. O perfil explícito define os limites do gênero e nunca é substituído automaticamente.
+2. Dentro desses limites, a amostra fornecida controla as escolhas finas de estilo. Sem perfil explícito, a amostra tem prioridade sobre a detecção.
+3. Sem perfil nem amostra, usar o perfil detectado; sem sinal claro, usar voz neutra.
+4. Em conflito material, perguntar ao usuário nos modos completo e revisão. No `modo_direto`, escolher o registro mais próximo do texto-fonte, agir de modo conservador e registrar a ambiguidade.
+5. Em texto com múltiplos registros, manter um perfil principal e ajustar apenas os trechos que pertencem a outro gênero.
+
+> **Saída no relatório**: `🎯 Tipo detectado: [tipo] → Perfil: [perfil]`
+
+### Passo 2 — 🔍 Diagnóstico com lista estruturada
+
+Percorrer sistematicamente cada categoria. Marcar ✓ (encontrado) ou ✗ (ausente).
+
+| Categoria | Sinal | Peso (1-3) | ✓/✗ | Ação |
+|---|---|---|---|---|
+| **Conteúdo** | Atribuição vaga ("estudos mostram", "especialistas dizem") | 3 | | Preservar a atribuição; especificar somente se a fonte já estiver na entrada e, caso contrário, sinalizar a lacuna no relatório |
+| | Ênfase inflada sem base ("revolucionário", "sem precedentes") | 3 | | Preservar força e autoria da avaliação; sugerir redução no relatório, sem alterá-la sem autorização |
+| | Dados possivelmente fabricados ou imprecisos | 3 | | Preservar no texto e sinalizar para verificação; corrigir apenas com fonte ou autorização do usuário |
+| **Linguagem** | Vocabulário genérico ("impacto", "contexto", "cenário") | 3 | | Trocar por termo preciso já sustentado pela fonte |
+| | Perífrases rebuscadas para evitar "ser", "ter" ou "estar" | 2 | | Restaurar o verbo simples quando natural ao registro |
+| | Paralelismo perfeito em 3+ itens | 2 | | Quebrar a simetria |
+| **Tom** | Ressalva excessiva ("pode ser que talvez", "parece que") | 2 | | Cortar redundância sem aumentar a certeza |
+| | Autorreferência de IA ("como modelo de linguagem...") | 3 | | Remover o aviso padrão sem criar opinião |
+| | Inflação de gravidade ("questão crucial para a humanidade") | 2 | | Reduzir a escala sem criar comparação nova |
+| **Composição** | Molde introdutório ("Neste artigo, exploraremos...") | 3 | | Cortar e ir direto ao conteúdo existente |
+| | Conclusão em molde ("em resumo", "conclui-se que") | 3 | | Enxugar ou reorganizar a conclusão existente |
+| | Transições artificiais ("primeiramente", "em segundo lugar") | 2 | | Usar conectivos naturais |
+| **Estilo** | Formatação excessiva (negrito ou travessão em excesso) | 1 | | Moderar conforme o gênero |
+| | Emoji em cada item (padrão ChatGPT) | 1 | | Remover os que não têm função |
+| | Markdown não solicitado (títulos e listas automáticas em prosa) | 2 | | Remover quando não servir ao gênero |
+| **PT-BR** | Oficialês ("cumpre salientar", "no âmbito de") | 2 | | Substituir por construção direta |
+| | Gerundismo ("vamos estar analisando") | 2 | | Converter para forma verbal direta |
+| | ENEM-ismo (frase de efeito genérica no final) | 2 | | Trocar por reflexão específica |
+| **Estrangeirismos** | Tradução forçada de termos de tecnologia | 2 | | Restaurar o termo consagrado no domínio |
+| | Uso artificial de anglicismos fora de contexto técnico | 1 | | Remover |
+
+> **Regra de decisão**: cada linha detectada conta como um sinal, independentemente do número de repetições. Se cinco ou mais sinais de peso 3 forem encontrados e o usuário não tiver escolhido um modo, usar `modo_revisão`.
+
+> **Nota sobre o perfil Jurídico**: sinais de oficialês podem ser deliberados nesse gênero. Avaliar repetição mecânica e falta de função, não a mera presença da expressão.
+
+#### Indicadores quantitativos opcionais
+
+Usar somente quando o usuário pedir métricas ou houver ferramenta confiável para calculá-las. Nunca estimar números. Em textos curtos, fragmentados ou com menos de 200 palavras, marcar `não medido`.
+
+Indicadores possíveis:
+
+- razão entre tipos e ocorrências de palavras (TTR), com tokenização declarada;
+- desvio-padrão do comprimento das frases;
+- entropia lexical, com método declarado;
+- contagem de palavras terminadas em `-mente`;
+- contagem de formas em `-ando`, `-endo` e `-indo` com `\w+(?:ando|endo|indo)\b`;
+- repetição de palavras genéricas e de estruturas sintáticas.
+
+Tratar os resultados como pistas dependentes de gênero e tamanho. Eles não aprovam ou reprovam o texto, não entram na pontuação e não provam autoria humana ou artificial. Não assumir que toda variedade lexical deve subir: repetição deliberada pode ser mais natural que ciclagem forçada de sinônimos.
+
+### Passo 3 — 🧹 Remoção de padrões
+
+Começar pelas referências das categorias marcadas ✓ no diagnóstico:
+
+| Categoria com ✓ no Passo 2 | Arquivo inicial |
+|---|---|
+| Conteúdo | `references/padroes-conteudo.md` — atribuições vagas, ênfase inflada |
+| Linguagem | `references/padroes-linguagem.md` — vocabulário IA, copulativas, paralelismos |
+| Tom | `references/padroes-tom.md` — adulação, ressalvas e inflação de gravidade |
+| Composição | `references/padroes-composicao.md` — moldes e conclusões previsíveis |
+| Estilo | `references/padroes-estilo.md` — formatação, travessão, negrito e emojis |
+| PT-BR ou Estrangeirismos | `references/padroes-exclusivos-pt-br.md` — gerundismo, oficialês e ENEM-ismo |
+| Português Simplificado (perfil ativo) | `references/padroes-portugues-simplificado.md` — operações, substituições lexicais e métricas |
+
+Se surgir outro sinal durante a reescrita, houver dúvida de classificação ou sobreposição entre categorias, consultar também a referência relacionada. Não carregar todas por padrão. No `modo_revisão`, incluir sempre `padroes-exclusivos-pt-br.md`.
+
+As referências detalham padrões, mas não substituem a **TRAVA FACTUAL**. Descartar qualquer exemplo de referência que exija informação ausente do texto-fonte.
+
+### Passo 4 — ♻️ Restauração de especificidade
+
+Onde o texto perdeu precisão ou ritmo:
+
+| Problema | Solução | Exemplo |
+|---|---|---|
+| Metáfora morta | Cortar ou recuperar uma imagem já presente na fonte | "Ponto de inflexão" → descrever a mudança concreta que a fonte já informa |
+| Termo genérico | Recuperar o vocabulário de domínio disponível | "Impacto positivo" → "queda no churn", somente se a fonte disser que o churn caiu |
+| Molde previsível | Reorganizar o fluxo | Inverter ordem: exemplo → contexto → tese, sem mudar a relação entre eles |
+| Abstração excessiva | Concretizar apenas com informação disponível | "Muitas pessoas sofrem" → "Muita gente passa por isso" |
+| Ritmo monótono | Variar comprimento de frases | Alternar frases curtas com longas |
+
+Se a concretude necessária não existir na fonte, manter a formulação honesta e anotar: `⚠️ Falta um dado ou exemplo real para tornar este trecho mais concreto.`
+
+### Passo 5 — 💬 Aplicação da voz
+
+Aplicar somente os recursos permitidos pelo perfil ativo:
+
+| Perfil | Aplicar | Evitar |
+|---|---|---|
+| Voz neutra | Clareza, ritmo natural e transições discretas | Primeira pessoa, opinião, humor ou mudança de registro |
+| Crônica | Ritmo irregular e ironia já sustentada pela fonte ou pedida pelo usuário | Inventar lembrança, sentimento ou observação pessoal |
+| Jornalístico | Ordem direta, atribuição precisa e linguagem sóbria | Adjetivação avaliativa, primeira pessoa e fontes novas |
+| Acadêmico | Terminologia de domínio e qualificações necessárias | Novas referências, certezas maiores que as da fonte e coloquialidade gratuita |
+| Corporativo Informal | Frases diretas, leveza e estrangeirismos naturais do domínio | Criar status, prazo, promessa, chamada para ação ou experiência pessoal |
+| Post de Rede Social | Gancho baseado na tese existente e parágrafos curtos | Criar opinião, história pessoal ou chamada para ação ausente |
+| WhatsApp | Oralidade compatível com o canal e abreviações naturais | Alterar compromisso, data, destinatário ou grau de certeza |
+| Jurídico | Formalidade controlada, estrutura e termos do gênero | Criar artigo, súmula, precedente, fato ou fundamento |
+| Didático | Ordem clara e explicação acessível | Criar analogia, personagem, dado ou exemplo não fornecido |
+| Português Simplificado | SVO, frases ≤25 palavras, vocabulário comum, listas para 3+ itens e termos técnicos explicados | Eliminar conteúdo, reduzir modalidade, inventar exemplo ou remover terminologia de domínio |
+
+Quando o usuário fornecer amostra de voz, espelhar comprimento de frases, nível vocabular, início de parágrafos, pontuação e uso de estrangeirismos. Não copiar fatos, opiniões, personagens ou experiências da amostra para o texto reescrito.
+
+### Passo 6 — 🔥 Verificação final
+
+Verificar cada item. Marcar ✓, ✗ ou N/A conforme o perfil e o tamanho do trecho.
+
+| # | Verificação | ✓/✗ |
+|---|---|---|
+| 1 | **TRAVA FACTUAL** atendida integralmente conforme a definição canônica? | |
+| 2 | Argumento, intenção, modalidade e trechos protegidos permanecem intactos? | |
+| 3 | Transições e padrões mecânicos detectados foram corrigidos? | |
+| 4 | Termos vagos foram precisados somente quando a fonte fornecia material para isso? | |
+| 5 | Ritmo e comprimento das frases combinam com o perfil? Em parágrafo com menos de três frases, não exigir três tamanhos distintos. | |
+| 6 | Opinião, dúvida, sentimento e primeira pessoa aparecem somente se já existiam ou foram solicitados? | |
+| 7 | Perfil de voz e registro permanecem consistentes em cada trecho? | |
+| 8 | Estrangeirismos naturais do domínio foram preservados sem tradução forçada? | |
+| 9 | Abertura, fechamento e formatação servem ao gênero, sem molde genérico desnecessário? | |
+| 10 | Lido em voz alta, o texto soa natural dentro do gênero e do público pretendido? | |
+
+Falha nos itens 1 ou 2 invalida a candidata. Nos demais itens, corrigir apenas se ainda houver tentativa disponível; não distorcer o gênero para satisfazer a lista. O controle de tentativas do Passo 8 impede repetição indefinida.
+
+### Passo 7 — 📊 Avaliação pós-reescrita
+
+Validar a **TRAVA FACTUAL** antes da pontuação. Se falhar, descartar a candidata e registrar pontuação `nula`; naturalidade nunca compensa alteração factual ou semântica.
+
+Se a validação factual passar, avaliar quatro dimensões de 0 a 100, sempre em relação ao perfil ativo:
+
+| Dimensão | Peso | Critério de avaliação |
+|---|---|---|
+| **Remoção de padrões IA** | 35% | Quantos padrões do Passo 2 foram eliminados? Algum remanescente? |
+| **Naturalidade** | 30% | O ritmo combina com o gênero? A voz aparece somente na medida permitida? |
+| **Consistência de voz** | 20% | O perfil foi mantido do início ao fim, respeitando trechos de outro registro? |
+| **Legibilidade** | 15% | Frases fluem? Conectivos naturais? Lógica clara? |
+
+**Pontuação final** = Σ (dimensão × peso)
+
+Usar o `limiar` solicitado pelo usuário ou 80 como padrão. Se a pontuação ficar abaixo do limiar e houver nova tentativa, atuar nas dimensões mais baixas. Com pontuação abaixo de 60, mudar a abordagem sem trocar perfil explícito. Indicadores quantitativos opcionais nunca alteram a pontuação.
+
+### Passo 8 — 📦 Controle de tentativas e entrega
+
+Executar a seleção de perfil e o diagnóstico uma vez. Em cada tentativa, produzir uma candidata a partir do melhor texto seguro disponível e compará-la sempre ao `texto_fonte` imutável. Executar os Passos 3–6 antes de calcular a pontuação.
+
+```text
+texto_fonte = entrada original imutável
+texto_atual = entrada atual ou texto_fonte
+limiar = valor solicitado ou 80
+tentativas_maximas = limite do modo
+melhor_texto = nenhum
+melhor_pontuacao = -1
+
+para cada tentativa:
+    gerar candidata a partir de texto_atual
+    verificar TRAVA FACTUAL e argumento contra texto_fonte
+
+    se a candidata falhar:
+        descartar candidata sem calcular pontuação
+        continuar somente se houver nova tentativa
+
+    calcular pontuação
+    se pontuação > melhor_pontuacao:
+        guardar candidata como melhor_texto
+        texto_atual = melhor_texto
+
+    se pontuação >= limiar:
+        estado = concluida
+        entregar
+
+se não houver candidata segura:
+    estado = reprovada_trava_factual
+    melhor_texto = texto_fonte
+    pontuação = nula
+senão:
+    estado = melhor_resultado
+    entregar melhor_texto com nota de limitação
+```
+
+No `modo_direto`, produzir exatamente uma candidata e não repetir. Se ela falhar na TRAVA FACTUAL, devolver o texto-fonte com estado `reprovada_trava_factual`.
+
+Quando houver nova tentativa, escolher a alternativa pelo problema dominante:
+
+| Problema da candidata anterior | Próxima abordagem |
+|---|---|
+| Padrões mecânicos remanescentes | Reforçar a remoção dos padrões detectados |
+| Voz excessiva ou artificial | Reduzir intervenções e aproximar do registro original |
+| Estrutura previsível | Reordenar apenas as proposições existentes |
+| Texto longo inconsistente | Trabalhar por blocos semânticos e validar o conjunto |
+| Perfil detectado inadequado | Mudar somente se o usuário não o escolheu e houver evidência no texto-fonte |
+
+### Contrato de saída
+
+Em pipelines ou quando houver pedido de saída estruturada, usar:
+
+```yaml
+estado: concluida
+texto: "texto final ou texto-fonte seguro"
+modo: modo_completo
+perfil_de_voz: voz_neutra
+limiar: 80
+pontuacao: 86
+convergiu: true
+trava_factual:
+  estado: intacta
+  violacoes: []
+tentativas:
+  usadas: 2
+  maximas: 3
+relatorio: {}
+```
+
+Usar os valores conforme o estado final:
+
+| `estado` | `convergiu` | `pontuacao` | `texto` |
+|---|---:|---:|---|
+| `concluida` | `true` | Número ≥ limiar | Candidata segura aprovada |
+| `melhor_resultado` | `false` | Melhor número abaixo do limiar | Melhor candidata segura |
+| `reprovada_trava_factual` | `false` | `null` | `texto_fonte` |
+| `entrada_invalida` | `false` | `null` | Entrada sem reescrita |
+
+Em conversa, apresentar primeiro o texto e depois o relatório no nível do modo:
+
+| Modo | Conteúdo do relatório |
+|---|---|
+| `modo_completo` | Pontuação, padrões corrigidos, ressalvas e indicadores opcionais se calculados |
+| `modo_direto` | Uma linha por padrão corrigido, pontuação e estado |
+| `modo_revisão` | Diagnóstico completo, pontuação, ressalvas e indicadores opcionais se calculados |
+
+### Integração com ciclos externos
+
+Na primeira chamada, usar o texto recebido como `texto_fonte` e `texto_atual`. Nas chamadas seguintes, manter `texto_fonte` inalterado e realimentar somente o campo `texto` como `texto_atual`:
+
+```yaml
+proxima_entrada:
+  texto_fonte: "original imutável"
+  texto_atual: "saída.texto"
+  perfil_de_voz: "mesmo perfil"
+  limiar: 80
+```
+
+Nunca realimentar relatório, pontuação ou o envelope inteiro como se fossem parte do texto. Toda chamada continua comparando o resultado ao `texto_fonte` original.
+
+## Estrangeirismos
+
+Brasileiro de tech fala com estrangeirismos. Isso é **marca de autenticidade**, não erro. A skill preserva:
+
+`feedback, deploy, sprint, churn, feature, bug, hotfix, pipeline, stakeholder, deadline, call, onboarding, pitch, runway, burn rate, product-market fit, growth, awareness, branding, lead, funnel, conversion, landing page, copywriting, UX, UI, framework, stack, backend, frontend, fullstack, DevOps, SaaS, API, endpoint, webhook, dashboard, KPI, OKR, ROI, ROAS, CRM, MVP`
+
+Forçar tradução desses termos é sinal de IA purista — o oposto de humano.
+
+> **Regra de ouro**: se o termo é usado no dia a dia do domínio em PT-BR, mantenha. Se é anglicismo artificial sem necessidade, remova.
+
+## Suíte de testes de regressão
+
+Conjunto mínimo para validar evoluções futuras. Rodar cada caso em `modo_completo` e conferir preservação semântica antes de julgar estilo.
+
+| # | Tipo | Antes (IA) | Depois esperado (síntese) |
+|---|---|---|---|
+| T1 | E-mail corporativo | "Venho por meio deste informar que o relatório será encaminhado oportunamente" | "O relatório será enviado oportunamente." |
+| T2 | Parágrafo acadêmico | "Diversos autores discutem a questão da linguagem de forma ampla" | "Diversos autores discutem a linguagem em termos amplos." |
+| T3 | Texto jurídico | "É cediço que a responsabilidade civil objetiva se aplica no âmbito das relações de consumo" | "A responsabilidade civil objetiva aplica-se às relações de consumo." |
+| T4 | Modelo de abertura de blog | "Neste artigo, exploraremos 5 estratégias essenciais para otimizar seu workflow" | "Neste artigo, vamos explorar cinco estratégias essenciais para otimizar seu workflow." |
+| T5 | Ressalva excessiva de IA | "Como modelo de linguagem, não posso afirmar com certeza, mas parece que talvez o sistema esteja funcionando" | "O sistema parece estar funcionando, mas ainda não é possível afirmar com certeza." |
+| T6 | Didático genérico | "João tem 3 maçãs e Maria tem 5. Quantas têm ao todo?" | "João tem 3 maçãs e Maria tem 5. Quantas maçãs os dois têm ao todo?" |
+
+> **Critério de regressão**: se uma evolução piora o resultado de qualquer teste T1-T6, a mudança deve ser reavaliada.
+>
+> **TRAVA FACTUAL nos casos de teste:** nenhuma saída esperada pode adicionar, retirar ou alterar conteúdo protegido. Resultado mais contido é preferível a uma versão mais vistosa que invente informação.
--- a/.github/skills/humanizar/references/padroes-composicao.md
+++ b/.github/skills/humanizar/references/padroes-composicao.md
@@ -0,0 +1,312 @@
+# Padrões de Composição — Tropos IA em PT-BR
+
+Padrões estruturais que denunciam texto gerado por IA ao nível da **composição** — como o texto é montado, não o que ele diz. Inclui tropos catalogados pelo [tropes.fyi](https://tropes.fyi/directory) e o conceito de **Ablação Semântica** (The Register, fev 2026).
+
+> **TRAVA FACTUAL neste arquivo:** alterar a composição, não o conteúdo. Tratar o texto "Antes" como universo factual fechado e preservar proposições, entidades, números, datas, fontes, causalidade, modalidade e registro no "Depois". Não introduzir analogia, exemplo, dado, experiência, opinião ou detalhe ausente. Quando uma lacuna impedir a concretização, manter a generalidade e apontar a lacuna no relatório.
+
+---
+
+## Tropos de Composição
+
+### Resumos Fractais
+
+**Problema:** IA anuncia o que vai dizer, diz, e depois resume o que disse — em cada seção, subseção e parágrafo. Texto vira recursão infinita de meta-comentário.
+
+**Antes (IA):**
+> Nesta seção, vamos explorar como a inteligência artificial está transformando o setor financeiro. Veremos três aspectos principais: automação de processos, análise preditiva e atendimento ao cliente.
+>
+> [... 3 parágrafos ...]
+>
+> Como vimos nesta seção, a inteligência artificial está transformando o setor financeiro por meio da automação de processos, da análise preditiva e do atendimento ao cliente. Na próxima seção, abordaremos os desafios dessa transformação.
+
+**Depois (humano):**
+> A inteligência artificial transforma o setor financeiro por meio da automação de processos, da análise preditiva e do atendimento ao cliente. A seção seguinte examina os desafios dessa transformação.
+
+**Evitar em PT-BR:**
+- "Nesta seção, veremos..."
+- "Como vimos anteriormente..."
+- "A seguir, abordaremos..."
+- "Conforme mencionado na seção anterior..."
+- "Para resumir o que foi discutido..."
+
+**Sinais adicionais de detecção:**
+- Recursividade de meta-nível: quando cada seção tem introdução → desenvolvimento → mini-conclusão, e cada parágrafo dentro da seção também tem essa estrutura
+- Palavras-chave de meta-comentário: "como discutido", "retomando", "para recapitular", "em resumo desta seção"
+- Presença de conectivos de transição entre subseções que referenciam o próprio texto ("No tópico anterior vimos...")
+
+**Técnicas avançadas de correção:**
+- Reescrever eliminando a recursão: a conclusão do texto é UMA — no final. As subseções não precisam de mini-conclusões
+- Converter meta-comentário em afirmação direta: "Como vimos nesta seção, a IA transforma o setor" → "A IA transforma o setor de três formas"
+- Se o texto tem 3+ subseções com mini-conclusões, fundir as subseções em um único bloco com fluxo contínuo
+
+---
+
+### Metáfora Morta
+
+**Problema:** IA encontra uma metáfora no início e repete ad nauseam como se fosse a espinha do texto. "Ecossistema" aparece 30 vezes. "Jornada" aparece em cada parágrafo. A metáfora perde qualquer poder — vira ruído.
+
+**Antes (IA):**
+> O ecossistema de startups brasileiro está amadurecendo. Nesse ecossistema, os players precisam se adaptar. O ecossistema exige novas competências. Para sobreviver neste ecossistema, empreendedores devem construir redes sólidas. O futuro do ecossistema depende de políticas públicas que fomentem a inovação dentro do próprio ecossistema.
+
+**Depois (humano):**
+> O ecossistema de startups brasileiro está amadurecendo. Esse processo exige que seus participantes desenvolvam novas competências e que os empreendedores construam redes sólidas. O futuro do setor também depende de políticas públicas de incentivo à inovação.
+
+**Evitar em PT-BR:**
+- Repetir "ecossistema", "jornada", "cenário", "panorama" ou "paisagem" mais de 2x num texto
+- Usar a mesma metáfora-base em mais de 3 parágrafos seguidos
+- Forçar coerência metafórica artificial ("nessa jornada... o próximo passo da jornada... ao longo da jornada...")
+
+**Sinais adicionais de detecção:**
+- Frequência de repetição da mesma palavra-metafórica (contagem >2 no texto inteiro, >1 por parágrafo)
+- Metáforas que são semanticamente vazias no contexto ("ecossistema" para qualquer coisa que tenha mais de duas partes)
+- Metáforas que não suportam raciocínio — o autor usa "jornada" mas não desenvolve nenhuma etapa da jornada
+
+**Técnicas avançadas de correção:**
+- Criar um **mapa metafórico**: listar todas as metáforas usadas → se houver sobreposição semântica (ex: "ecossistema", "cenário", "paisagem" no mesmo texto), escolher UMA e eliminar as demais
+- Substituir metáforas genéricas por formulação direta baseada nas proposições existentes. Usar imagem concreta somente se ela já estiver na entrada ou for apresentada, com autorização, como hipótese explícita
+- Quando a metáfora não serve a um argumento real, cortar e ir direto ao ponto
+
+---
+
+### Empilhamento de Analogias Históricas
+
+**Problema:** IA lista 5 empresas ou revoluções históricas em sequência para dar "peso" ao argumento. Parece erudição, mas é preenchimento — nenhuma analogia é desenvolvida o suficiente pra provar algo.
+
+**Antes (IA):**
+> Assim como a revolução industrial transformou a manufatura, como a eletricidade mudou a infraestrutura urbana, como a internet redefiniu a comunicação, como o iPhone revolucionou a computação móvel, e como o Netflix disruputou a mídia — a inteligência artificial generativa está prestes a transformar fundamentalmente o modo como trabalhamos.
+
+**Depois (humano):**
+> A revolução industrial transformou a manufatura; a eletricidade, a infraestrutura urbana; a internet, a comunicação; o iPhone, a computação móvel; e a Netflix, a mídia. Da mesma forma, a inteligência artificial generativa está prestes a transformar fundamentalmente o modo como trabalhamos.
+
+**Evitar em PT-BR:**
+- "Assim como [empresa/revolução 1], como [empresa/revolução 2], como [empresa/revolução 3]..."
+- "Da mesma forma que a revolução industrial..."
+- "Se olharmos para a história — do rádio à TV, da TV à internet, da internet ao mobile —"
+- Listar mais de 2 analogias históricas sem desenvolver nenhuma
+
+**Sinais adicionais de detecção:**
+- Sequências de 3+ analogias com a mesma estrutura sintática (coordenação com "como" ou "assim como")
+- Analogias que terminam em conclusão genérica idêntica ("...está transformando fundamentalmente o modo como trabalhamos")
+- Analogias sem especificidade temporal (não diz quando a revolução industrial aconteceu, quanto durou, qual setor)
+
+**Técnicas avançadas de correção:**
+- Condensar analogias repetitivas sem apagar proposições distintas. Descartar apenas a analogia que for decorativa e não acrescentar conteúdo ao argumento
+- Desenvolver especificidade temporal ou causal somente com dados já presentes na entrada
+- Se a analogia não tiver sustentação, qualificá-la como comparação do autor ou apontar a lacuna no relatório; não ancorá-la com dados externos inventados
+
+---
+
+### Diluição de Ponto Único
+
+**Problema:** O texto tem UM argumento. Mas a IA o reformula 10 vezes com conectivos diferentes, esticando pra 4000 palavras o que caberia em 400. Cada parágrafo diz a mesma coisa com roupa diferente.
+
+**Antes (IA):**
+> A transformação digital é essencial para a competitividade empresarial. De fato, empresas que não adotarem tecnologias digitais correm o risco de ficar para trás. Nesse sentido, a digitalização dos processos se torna uma prioridade estratégica. Além disso, a modernização tecnológica permite que organizações se adaptem com mais agilidade. Por outro lado, empresas que resistem à mudança digital enfrentam desafios crescentes de eficiência. Diante disso, fica claro que a transformação digital não é mais uma opção — é uma necessidade.
+
+**Depois (humano):**
+> A transformação digital é essencial para a competitividade. Empresas que não adotam tecnologias digitais podem perder competitividade e enfrentar problemas de eficiência. Por isso, digitalizar processos e modernizar a tecnologia são necessidades estratégicas para aumentar a agilidade e a capacidade de adaptação.
+
+**Evitar em PT-BR:**
+- Parágrafo que começa com "De fato," seguido da repetição da mesma ideia
+- "Nesse sentido," introduzindo a mesma ideia de novo
+- "Em outras palavras," (literalmente admitindo que vai repetir)
+- "Isso significa que..." (reformulação disfarçada)
+- Texto com mais de 3 parágrafos onde cada um pode ser resumido pela mesma frase
+
+**Sinais adicionais de detecção:**
+- Parágrafos com a mesma informação expressa em palavras diferentes (sinonímia redundante)
+- Conectivos de reformulação: "em outras palavras", "ou seja", "isso significa que", "dito de outro modo"
+- Texto com TTR (Type-Token Ratio) artificialmente baixo — muita repetição lexical com sinônimos
+
+**Técnicas avançadas de correção:**
+- **Algoritmo de compressão**: identificar o núcleo proposicional de cada parágrafo → se dois parágrafos compartilham o mesmo núcleo, fundir em um
+- Eliminar conectivos de reformulação — se o leitor precisa que você repita de outro jeito, o primeiro jeito provavelmente já era ruim
+- Aplicar "regra de 3": se o argumento precisa de 3 reformulações para ser entendido, ele provavelmente é fraco
+
+---
+
+### Conclusão Sinalizada
+
+**Problema:** IA não sabe terminar sem anunciar que vai terminar. Usa marcadores explícitos que telegrafam "aqui acaba" — quebrando qualquer possibilidade de final com impacto.
+
+**Antes (IA):**
+> Em conclusão, a inteligência artificial generativa representa uma oportunidade transformadora para o mercado brasileiro. Em suma, as empresas que souberem aproveitar esse potencial estarão melhor posicionadas para o futuro. Para finalizar, é importante ressaltar que o equilíbrio entre inovação e responsabilidade será determinante para o sucesso dessa jornada.
+
+**Depois (humano):**
+> A inteligência artificial generativa é uma oportunidade transformadora para o mercado brasileiro. As empresas que aproveitarem esse potencial estarão mais bem posicionadas, e o equilíbrio entre inovação e responsabilidade será determinante para o sucesso.
+
+**Evitar em PT-BR:**
+- "Em conclusão,"
+- "Em suma,"
+- "Para finalizar,"
+- "Concluindo,"
+- "Portanto, podemos afirmar que..."
+- "Diante do exposto,"
+- "À luz do que foi apresentado,"
+
+**Sinais adicionais de detecção:**
+- Marcadores explícitos de encerramento em sequência ("Em conclusão... Para finalizar...")
+- Conclusões que apenas repetem o que já foi dito sem acrescentar ideia nova
+- Parágrafo final com tom otimista genérico ("o futuro é promissor")
+
+**Técnicas avançadas de correção:**
+- Escolher o fechamento apenas entre materiais já presentes no texto:
+  1. **Virada reflexiva** — converter uma dúvida já existente em pergunta
+  2. **Detalhe concreto** — reutilizar dado já fornecido na entrada
+  3. **Contradição** — preservar limite ou tensão já expresso pelo autor
+  4. **Silêncio** — retirar o marcador e simplesmente encerrar
+- Se a conclusão começa com "Em conclusão", cortar as 3 primeiras palavras e ver se o resto sobrevive
+
+---
+
+### "Apesar dos Desafios..."
+
+**Problema:** Fórmula rígida de acknowledge→dismiss. IA reconhece um problema só pra descartá-lo imediatamente com otimismo vazio. Não há tensão real — o "desafio" nunca ameaça a tese.
+
+**Antes (IA):**
+> Apesar dos desafios regulatórios, a adoção de IA no setor de saúde segue em ritmo acelerado. Embora existam preocupações legítimas sobre privacidade de dados, as oportunidades superam amplamente os riscos. Mesmo com as limitações atuais de infraestrutura, o potencial transformador da tecnologia é inegável.
+
+**Depois (humano):**
+> A adoção de IA no setor de saúde avança em ritmo acelerado. Há preocupações com a privacidade de dados e limitações de infraestrutura; ainda assim, as oportunidades superam amplamente os riscos, e o potencial transformador da tecnologia é inegável.
+
+**Evitar em PT-BR:**
+- "Apesar dos desafios, [coisa positiva]"
+- "Embora existam preocupações legítimas, as oportunidades superam..."
+- "Mesmo com as limitações, o potencial é..."
+- "Não obstante os obstáculos, o caminho é promissor"
+- "Reconhecendo os riscos, mas focando nas possibilidades..."
+
+**Sinais adicionais de detecção:**
+- Estrutura "reconhece → descarta" em 1-2 frases
+- Adjetivos que neutralizam o problema: "desafios legítimos", "limitações atuais", "obstáculos naturais"
+- O "desafio" nunca tem consequência concreta — é abstrato
+
+**Técnicas avançadas de correção:**
+- Explicitar custo, risco ou consequência somente quando esses elementos já estiverem na entrada. Se não estiverem, manter o desafio nos termos originais e apontar a lacuna no relatório
+- Se o original já expressar uma tensão, **não descartá-la**: preservar o dado, a dúvida sobre a fonte e a decisão em aberto sem criar nenhum desses elementos
+- Aplicar "teste de consequência" — se o desafio não tiver custo, risco ou contrapartida explícita na entrada, não inventar um; manter a formulação geral ou apontar a lacuna no relatório
+
+---
+
+### Listicle Disfarçado de Prosa
+
+**Problema:** O texto é uma lista numerada fingindo ser parágrafo corrido. Cada item começa com "O primeiro aspecto...", "O segundo ponto...", "O terceiro elemento...". Não há fluxo — é enumeração com pontuação de prosa.
+
+**Antes (IA):**
+> O primeiro aspecto a considerar é a escalabilidade da solução. O segundo ponto relevante diz respeito à integração com sistemas legados. O terceiro elemento fundamental é a experiência do usuário final. O quarto fator a ser levado em conta é o custo total de propriedade. Por fim, o quinto aspecto envolve a governança de dados.
+
+**Depois (humano):**
+> A solução deve ser avaliada por cinco aspectos: escalabilidade, integração com sistemas legados, experiência do usuário, custo total de propriedade e governança de dados.
+
+**Evitar em PT-BR:**
+- "O primeiro aspecto..."
+- "O segundo ponto..."
+- "O terceiro elemento..."
+- "O quarto fator..."
+- "Por fim, o quinto..."
+- Qualquer sequência ordinal disfarçada de argumentação
+
+**Sinais adicionais de detecção:**
+- Sequência ordinal implícita: "Primeiro... Depois... Em seguida... Por fim..."
+- Frases com estrutura sintática idêntica (mesmo comprimento, mesma ordem de constituintes)
+- Texto que pode ser reformatado como lista numerada sem perder sentido
+
+**Técnicas avançadas de correção:**
+- Se o conteúdo merece lista → **formatar como lista real** (mais honesto)
+- Se o conteúdo não merece lista → **reorganizar como raciocínio causal**: causa → efeito → consequência
+- Quebrar a simetria sintática sem mudar o registro nem acrescentar fragmentos que não estejam no texto
+- Reordenar os itens somente quando a nova ordem preservar relações lógicas e ênfase do original
+
+---
+
+## Ablação Semântica — Restauração de Entropia
+
+Conceito do The Register (fev 2026): quando IA "melhora" um texto, ela faz **ablação semântica** — remove informação de alta entropia (os trechos únicos, específicos, surpreendentes) e substitui por sequências genéricas de alta probabilidade. O resultado é um "JPEG de pensamento": parece coerente, mas perdeu a densidade original.
+
+A humanização não é só remover padrões ruins — é **preservar o que ainda existe**. Restaurar conteúdo apagado exige uma versão-fonte fornecida pelo usuário; sem ela, não reconstruir por inferência.
+
+---
+
+### Limpeza Metafórica
+
+**Problema:** IA identifica metáforas originais, imagens viscerais e comparações inesperadas como "ruído" e substitui por clichês seguros. Metáforas vivas viram metáforas mortas. A especificidade sensorial desaparece.
+
+**Antes (IA):**
+> O mercado de trabalho está passando por uma profunda transformação. As empresas estão navegando em águas turbulentas e buscando se adaptar ao novo cenário. É preciso abraçar a mudança e trilhar novos caminhos para alcançar o sucesso.
+
+**Depois (humano):**
+> O mercado de trabalho passa por uma transformação profunda. As empresas enfrentam instabilidade, buscam adaptação e precisam mudar para alcançar o sucesso.
+
+**Restaurar:**
+- Metáforas sensoriais (visuais, táteis, sonoras) que já estejam na entrada ou em uma versão-fonte fornecida
+- Comparações concretas que já façam parte do material autorizado
+- Imagens e reações presentes no original, sem criar desconforto ou surpresa por conta própria
+- Especificidade: em vez de "cenário", descrever apenas o que a entrada já informa; se não houver detalhe, usar formulação direta e apontar a lacuna no relatório
+
+**Sinais adicionais de detecção:**
+- Metáforas substituídas por **clichês corporativos** ("ponto de inflexão", "navegar as complexidades")
+- Perda de especificidade sensorial: texto que antes tinha cor/luz/cheiro e agora tem só conceito
+- Metáforas que poderiam ser aplicadas a QUALQUER assunto ("transformação profunda", "novo capítulo")
+
+**Técnicas avançadas de correção:**
+- **Escala de concretude**: classificar cada imagem em 1-5 (1 = abstrata, 5 = sensorial). Se a média do texto < 2, simplificar a abstração com o material existente e apontar a falta de concretude no relatório
+- Substituir clichês por formulação direta. Usar referência cultural brasileira apenas se ela já estiver na entrada ou for autorizada como hipótese explícita
+- "Teste do bar" — se a metáfora não funcionaria numa conversa de bar, ela é genérica demais
+
+---
+
+### Achatamento Lexical
+
+**Problema:** Jargão preciso e terminologia de domínio são substituídos por termos genéricos "acessíveis". Token de 1-em-10.000 vira token de 1-em-100. O texto perde densidade informacional — diz menos com mais palavras.
+
+**Antes (IA):**
+> A empresa implementou uma solução de análise de dados que permite monitorar indicadores de desempenho e tomar decisões mais informadas. A ferramenta oferece visualizações intuitivas que ajudam a equipe a entender melhor os resultados.
+
+**Depois (humano):**
+> A empresa implementou uma solução de análise de dados para monitorar indicadores de desempenho, apoiar decisões mais informadas e visualizar resultados. As visualizações ajudam a equipe a compreender melhor esses resultados.
+
+**Restaurar:**
+- Nomes próprios de ferramentas, frameworks e metodologias que já estejam na entrada ou em uma versão-fonte fornecida
+- Métricas e siglas de domínio já presentes no material autorizado
+- Verbos técnicos precisos que já estejam na entrada ou em uma versão-fonte fornecida; sem essa base, preservar a ação genérica
+- Dados concretos já fornecidos: preservar números, porcentagens e intervalos temporais; se estiverem ausentes, não criá-los
+
+**Sinais adicionais de detecção:**
+- Substituição de jargão técnico por sinônimos genéricos ("ORM" → "ferramenta de mapeamento objeto-relacional" → "solução de banco de dados")
+- Perda de siglas do domínio (substitui "SaaS" por "software como serviço", depois por "plataforma digital")
+- Texto que soa como tradução de material introdutório para público leigo, mesmo quando o público é técnico
+
+**Técnicas avançadas de correção:**
+- **Mapeamento de domínio**: identificar o campo (dev, marketing, jurídico) → preservar o vocabulário técnico existente, sem inferir ferramenta, métrica ou sigla ausente
+- Se o texto generalizou demais, reintroduzir sigla ou termo somente a partir de uma versão-fonte fornecida; caso contrário, apontar a perda de precisão no relatório
+- "Teste de precisão" — se um especialista do domínio lê e diz "isso tá vago", o texto perdeu densidade
+
+---
+
+### Colapso Estrutural
+
+**Problema:** Raciocínio complexo, não linear e cheio de voltas é forçado no molde previsível de baixa perplexidade: introdução → 3 pontos → conclusão. Digressões são eliminadas. Contradições são "resolvidas". Nuance vira item de lista.
+
+**Antes (IA):**
+> A adoção de metodologias ágeis no Brasil apresenta três benefícios principais. Em primeiro lugar, aumenta a produtividade das equipes. Em segundo lugar, melhora a qualidade das entregas. Em terceiro lugar, promove uma cultura de melhoria contínua. Dessa forma, as empresas que adotam práticas ágeis tendem a obter melhores resultados.
+
+**Depois (humano):**
+> No Brasil, a adoção de metodologias ágeis aumenta a produtividade das equipes, melhora a qualidade das entregas e promove uma cultura de melhoria contínua. Por isso, as empresas que adotam essas práticas tendem a obter resultados melhores.
+
+**Restaurar:**
+- Digressões produtivas que já estejam na entrada ou em uma versão-fonte fornecida
+- Contradições internas efetivamente expressas pelo autor
+- Qualificações, exceções e dúvidas presentes no material autorizado
+- Perguntas sem resposta somente quando preservarem uma dúvida já existente
+- Estrutura que surpreende: começar por contra-argumento ou detalhe já existente, sem alterar a ênfase do autor
+
+**Sinais adicionais de detecção:**
+- Estrutura perfeitamente simétrica: parágrafos com 3-4 frases cada, todos com a mesma ordem (tópico → desenvolvimento → conclusão)
+- Ausência de digressões, parênteses ou tangentes
+- Texto que parece ter sido gerado por outline rígido sem desvios
+
+**Técnicas avançadas de correção:**
+- Reposicionar uma tangente já existente sem criar comentário ou argumento novo
+- Usar parênteses apenas para material lateral já presente no texto
+- Quebrar simetria por divisão ou combinação de frases existentes, preservando o registro
+- Variar a estrutura somente quando isso não alterar ênfase, modalidade ou voz do original
--- a/.github/skills/humanizar/references/padroes-conteudo.md
+++ b/.github/skills/humanizar/references/padroes-conteudo.md
@@ -0,0 +1,180 @@
+# Padrões de Conteúdo
+
+Padrões onde a IA infla importância, fabrica autoridade ou encerra textos com fórmulas previsíveis. São fáceis de detectar porque soam como comunicado de assessoria de imprensa — ninguém fala assim.
+
+> **TRAVA FACTUAL neste arquivo:** tratar o texto "Antes" como universo factual fechado. No "Depois", preservar proposições, entidades, números, datas, fontes, causalidade, modalidade e registro. Não preencher lacunas com exemplos, dados, fontes ou experiência pessoal. Quando faltar sustentação, preservar a alegação e apontar a lacuna no relatório; só cortar, qualificar ou corrigir com autorização do usuário.
+
+---
+
+### 1. Ênfase indevida em significância, legado e tendências
+
+**Palavras/expressões gatilho:** representa um marco, é um testemunho de, papel fundamental/crucial/vital, ressalta a importância, reflete uma tendência mais ampla, simbolizando o/a, contribuindo para o/a, preparando o terreno para, moldando o futuro de, cenário em constante evolução, ponto de inflexão, marca indelével, profundamente enraizado, redefine o paradigma
+
+**Problema:** A IA transforma qualquer fato mundano numa revolução. Um CRUD vira "um marco na transformação digital". Um pivô de startup vira "um ponto de inflexão no ecossistema de inovação". Nenhum ser humano escreve assim sobre coisas normais.
+
+**Antes (IA):**
+> O Nubank representa um marco fundamental na transformação do cenário financeiro brasileiro, moldando ativamente o futuro das fintechs na América Latina e preparando o terreno para uma nova era de inclusão bancária digital.
+
+**Depois (humano):**
+> O Nubank tem papel central na transformação do setor financeiro brasileiro. A empresa influencia o desenvolvimento das fintechs na América Latina e contribui para a inclusão bancária digital.
+
+**Evitar em PT-BR:**
+- "representa um marco na evolução de..."
+- "moldando o futuro do ecossistema de..."
+- "em um cenário em constante transformação"
+
+**Sinais adicionais de detecção:**
+- Superlativos absolutos sem quantificação ("maior", "melhor", "sem precedentes", "inédito")
+- Verbos de transformação grandiosa ("redefinir", "moldar", "preparar o terreno")
+- Texto que descreve qualquer coisa como "ponto de inflexão" sem dizer o que muda depois
+
+**Técnicas avançadas de correção:**
+- Converter superlativos em **dados concretos somente quando o dado já estiver na entrada**. Sem dado, preservar a força da avaliação e registrar a falta de sustentação no relatório
+- Substituir verbos grandiosos por **verbos de ação já descritos no original**. Se o original não informar a ação, usar formulação direta que preserve a alegação sem criar evento novo
+- "Teste do jornalista" — se um repórter leria a frase e perguntaria "como assim?", o termo é vazio
+
+---
+
+### 2. Ênfase forçada em notabilidade e cobertura de mídia
+
+**Palavras/expressões gatilho:** amplamente reconhecido, coberto pelos principais veículos, destaque na mídia especializada, presença ativa nas redes sociais, segundo especialistas do setor, referência no mercado
+
+**Problema:** A IA lista veículos e prêmios como prova de importância, sem dizer o que foi dito ou por que importa. Vira um Lattes turbinado — impressiona no vácuo mas não informa nada.
+
+**Antes (IA):**
+> A empresa foi destaque na Exame, Valor Econômico, TechCrunch e Bloomberg. Amplamente reconhecida como referência no mercado de SaaS B2B brasileiro, mantém presença ativa nas redes sociais com mais de 200 mil seguidores.
+
+**Depois (humano):**
+> A empresa apareceu na Exame, no Valor Econômico, no TechCrunch e na Bloomberg. É amplamente reconhecida no mercado brasileiro de SaaS B2B e soma mais de 200 mil seguidores nas redes sociais.
+
+**Evitar em PT-BR:**
+- "amplamente reconhecido(a) como referência em..."
+- "destaque nos principais veículos do setor"
+- "mantém presença ativa nas redes com X seguidores"
+
+**Sinais adicionais de detecção:**
+- Listagem de veículos sem citação de matéria específica (data, título, link)
+- "Presença ativa nas redes" sem métrica (seguidores, engajamento)
+- Menção a prêmios ou rankings sem fonte verificável
+
+**Técnicas avançadas de correção:**
+- Se a entrada já trouxer fonte, data ou link → preservar e citar esses mesmos elementos, sem completar o que estiver ausente
+- Se não houver fonte → preservar a alegação e sua atribuição, apontando a lacuna no relatório; só cortar ou qualificar com autorização
+- "Teste de verificabilidade" — se o leitor não pode checar em 30 segundos, a informação é puffery
+
+---
+
+### 3. Análises superficiais com gerúndio/particípio
+
+**Palavras/expressões gatilho:** ressaltando a importância de, demonstrando o compromisso com, refletindo a tendência de, contribuindo para o fortalecimento de, evidenciando o potencial de, impulsionando a inovação, fomentando o crescimento, consolidando sua posição como
+
+**Problema:** A IA gruda frases com gerúndio no final das sentenças pra parecer que está analisando algo, mas não está. É firula sintática — enche linguiça sem adicionar informação. Tipo aquele estagiário que escreve 3 páginas pra dizer "funcionou".
+
+**Antes (IA):**
+> A RD Station lançou integração nativa com WhatsApp Business, demonstrando seu compromisso com a inovação no marketing digital brasileiro e consolidando sua posição como líder no segmento, impulsionando a transformação digital das PMEs.
+
+**Depois (humano):**
+> A RD Station lançou integração nativa com WhatsApp Business. O lançamento demonstra seu compromisso com a inovação no marketing digital brasileiro, consolida sua posição de liderança no segmento e impulsiona a transformação digital das PMEs.
+
+**Evitar em PT-BR:**
+- "demonstrando o compromisso da empresa com..."
+- "consolidando sua posição como líder em..."
+- "contribuindo para o fortalecimento do ecossistema"
+
+**Sinais adicionais de detecção:**
+- Frases que terminam com gerúndio como se fosse conclusão de análise
+- Construções "verbo composto + gerúndio" em sequência ("vem demonstrando", "vai estar consolidando")
+- Gerúndio usado como adjetivo ("inovando", "transformando", "impulsionando")
+
+**Técnicas avançadas de correção:**
+- Converter a oração gerundial em **oração finita** com sujeito claro, preservando a alegação: "demonstrando compromisso" → "o lançamento demonstra o compromisso"
+- Se o gerúndio é puramente decorativo, **cortar**: "impulsionando a transformação" → (nada — a frase principal já diz)
+- "Teste do podcast" — ler a frase em voz alta; se soa como narração de vídeo institucional, o gerúndio é excessivo
+
+---
+
+### 4. Linguagem promocional e de propaganda
+
+**Palavras/expressões gatilho:** solução inovadora, experiência única, ecossistema robusto, revolucionário, disruptivo, estado da arte, de ponta, excelência, sinergia, empoderar, potencializar, alavancar, impulsionar, viabilizar, transformador, game-changer, seamless (usado em PT)
+
+**Problema:** A IA escreve como copywriter de página de produto. Tudo é "inovador", "revolucionário" e "de ponta". Nenhuma pessoa normal descreve o próprio trabalho assim — soa como pitch deck desesperado pra anjo investidor.
+
+**Antes (IA):**
+> A plataforma oferece uma solução inovadora e disruptiva que empodera equipes de produto a potencializarem seus resultados, entregando uma experiência seamless e de estado da arte para alavancar a transformação digital das organizações.
+
+**Depois (humano):**
+> A plataforma oferece uma solução inovadora e disruptiva. Ela dá às equipes de produto meios para melhorar seus resultados, oferece uma experiência integrada e de alto nível e apoia a transformação digital das organizações.
+
+**Evitar em PT-BR:**
+- "solução inovadora e disruptiva que empodera..."
+- "experiência única de ponta/estado da arte"
+- "potencializar/alavancar a transformação digital"
+
+**Sinais adicionais de detecção:**
+- Combinação de 2+ buzzwords na mesma frase ("solução inovadora e disruptiva de ponta")
+- Adjetivos que são autocontraditórios ("seamless mas robusto", "simples mas poderoso")
+- Texto que poderia ser usado como copy de qualquer produto sem mudar nada
+
+**Técnicas avançadas de correção:**
+- Reduzir adjetivos puramente decorativos sem apagar uma alegação substantiva. Quando a alegação não tiver evidência na entrada, qualificá-la como descrição da empresa ou do texto
+- Substituir adjetivos por **dados ou comparações somente quando esses elementos já estiverem na entrada**. Sem evidência, preservar a avaliação e apontar a lacuna no relatório
+- "Teste do pitch deck" — se a frase apareceria em qualquer slide de qualquer startup, ela é genérica demais
+
+---
+
+### 5. Atribuições vagas e weasel words
+
+**Palavras/expressões gatilho:** segundo especialistas, de acordo com analistas do setor, estudos apontam que, o mercado reconhece, é amplamente considerado, pesquisas indicam, fontes do setor afirmam, observadores notam que
+
+**Problema:** A IA atribui afirmações a autoridades genéricas que não existem. "Especialistas dizem" — quais? "Estudos apontam" — qual estudo, de que ano, com que metodologia? É a versão corporativa de "meu primo falou".
+
+**Antes (IA):**
+> Segundo especialistas do setor, o modelo de negócios da empresa representa uma evolução significativa. Analistas de mercado reconhecem que a abordagem tem potencial para redefinir o segmento de healthtechs no Brasil.
+
+**Depois (humano):**
+> Especialistas do setor não identificados consideram o modelo de negócios uma evolução significativa. Analistas também não identificados avaliam que a abordagem pode redefinir o segmento de healthtechs no Brasil.
+
+**Evitar em PT-BR:**
+- "segundo especialistas do setor..."
+- "analistas de mercado reconhecem que..."
+- "estudos/pesquisas apontam/indicam que..."
+
+**Sinais adicionais de detecção:**
+- Quantificadores vagos: "muitos especialistas", "diversos estudos", "alguns analistas"
+- Referências sem data: "pesquisas recentes mostram..."
+- Ausência de fonte quando a afirmação é controversa ou específica
+
+**Técnicas avançadas de correção:**
+- Se a fonte já estiver na entrada → preservá-la com os mesmos autor, ano, título e link
+- Se a fonte não estiver na entrada → manter a atribuição como não identificada e registrar a lacuna no relatório; só cortar ou qualificar com autorização
+- Não converter atribuição vaga em opinião ou experiência pessoal do revisor
+- "Teste da fonte" — se você não consegue encontrar a fonte em 2 minutos de busca, a atribuição é weasel
+
+---
+
+### 6. Conclusões formulaicas sobre desafios e perspectivas futuras
+
+**Palavras/expressões gatilho:** apesar dos desafios, não obstante as dificuldades, o futuro é promissor, perspectivas animadoras, em um contexto de constante evolução, seguir crescendo, continuar inovando, trilhar um caminho de sucesso, superar obstáculos, rumo a um futuro, desafios e oportunidades
+
+**Problema:** A IA encerra textos com uma seção "Desafios e Perspectivas" que não diz nada concreto. Primeiro lista problemas genéricos, depois diz que "apesar disso, o futuro é promissor". É o equivalente textual de shrug seguido de thumbs up.
+
+**Antes (IA):**
+> Apesar dos desafios inerentes ao mercado brasileiro — como a complexidade tributária e a concorrência acirrada — a startup segue trilhando um caminho de crescimento sustentável. Com perspectivas animadoras e um time comprometido com a inovação, a empresa está bem posicionada para continuar liderando a transformação do setor.
+
+**Depois (humano):**
+> A startup enfrenta a complexidade tributária e a concorrência acirrada, mas mantém uma trajetória de crescimento sustentável. Suas perspectivas são animadoras, o time é comprometido com a inovação e a empresa está bem posicionada para continuar liderando a transformação do setor.
+
+**Evitar em PT-BR:**
+- "apesar dos desafios, o futuro é promissor"
+- "a empresa segue bem posicionada para continuar..."
+- "trilhando um caminho de crescimento sustentável"
+
+**Sinais adicionais de detecção:**
+- Fórmula "Apesar de X, o futuro é Y" onde X é genérico e Y é otimista
+- Uso de "perspectivas animadoras" sem dizer o que anima
+- A conclusão poderia ser aplicada a QUALQUER empresa do setor
+
+**Técnicas avançadas de correção:**
+- Usar previsão, prazo ou plano somente quando esses elementos já estiverem na entrada. Se faltarem, nomear apenas os desafios existentes e apontar a ausência de evidência no relatório
+- Se o original expressar incerteza, preservá-la sem criar cenário, consequência ou plano alternativo
+- "Teste do horóscopo" — se a conclusão poderia aparecer no horóscopo de qualquer signo, ela é genérica demais
--- a/.github/skills/humanizar/references/padroes-estilo.md
+++ b/.github/skills/humanizar/references/padroes-estilo.md
@@ -0,0 +1,345 @@
+# Padrões de estilo e formatação
+
+Padrões que denunciam texto gerado por IA pela forma visual e estrutural, não pelo conteúdo. Ferramentas de detecção usam esses marcadores como sinais de alta confiança.
+
+> **Regra transversal:** correção de estilo altera somente apresentação, pontuação e organização. Preserve fatos, números, fontes, causalidade, prazo, estado temporal, modalidade e perfil de voz. Nunca compense a retirada de um recurso visual com dado, opinião, humor ou certeza inexistentes.
+
+---
+
+### Travessão (em-dash) excessivo
+
+**Problema:** IA usa 15-25 travessões por texto médio. Humano brasileiro usa 2-3, e geralmente prefere vírgula, ponto ou parênteses.
+
+**Antes (IA):**
+> O projeto — que começou em 2022 — trouxe resultados impressionantes — especialmente na área de dados — e agora está sendo expandido — mesmo com orçamento limitado — para outras regionais.
+
+**Depois (humano):**
+> O projeto começou em 2022 e trouxe resultados impressionantes, especialmente na área de dados. Mesmo com orçamento limitado, agora está sendo expandido para outras regionais.
+
+**Evitar em PT-BR:**
+- Mais de 2 travessões por parágrafo
+- Travessão onde vírgula resolve
+- Encadeamento de apartes com travessão (— X — Y — Z)
+
+**Sinais adicionais de detecção:**
+- Travessões usados para **tudo**: apartes, conclusões, reformulações, exemplos
+- Texto onde >10% dos sinais de pontuação são travessões
+- Travessão duplo usado como parênteses em toda ocorrência
+
+**Técnicas avançadas de correção:**
+- **Limite de 2 travessões por parágrafo** — se passar, converter os extras em vírgulas, pontos ou parênteses
+- Diferenciar uso: travessão para contraste forte, parênteses para comentário lateral, vírgula para aparte leve
+- Ao trocar a pontuação, preservar a relação entre oração principal, ressalva, causa e contraste
+- "Teste do editor" — se um editor humano teria cortado o travessão, cortar
+
+---
+
+### Negrito excessivo
+
+**Problema:** IA aplica negrito em toda palavra-chave como se o texto fosse uma apresentação. Texto corrido com negrito em cada substantivo importante parece catálogo de produto, não escrita humana.
+
+**Antes (IA):**
+> A **plataforma** oferece **integração nativa** com os principais **CRMs do mercado**, garantindo **escalabilidade** e **segurança** para equipes de **vendas** e **marketing**.
+
+**Depois (humano):**
+> A plataforma oferece integração nativa com os principais CRMs do mercado, garantindo escalabilidade e segurança para equipes de vendas e marketing.
+
+**Regra contextual canônica:**
+- Em prosa corrida, e-mail, artigo e texto autoral, usar negrito apenas quando houver contraste editorial deliberado ou quando a fonte já trouxer ênfase relevante
+- Em documentação, material didático, interfaces e listas de consulta, o negrito pode marcar rótulos e hierarquia quando isso melhora a navegação
+- Não aplicar cotas simultâneas por parágrafo e por seção. O excesso é funcional: ocorre quando a marcação se repete sem hierarquia e faz vários trechos competirem pela mesma atenção
+
+**Sinais adicionais de detecção:**
+- Negrito em substantivos comuns (plataforma, equipe, resultado) sem razão editorial
+- Negrito usado como substituto de hierarquia de informação (quando a estrutura deveria fazer o trabalho)
+- Negrito espalhado por tantas palavras que deixa de indicar prioridade
+
+**Técnicas avançadas de correção:**
+- Usar negrito apenas para **contraste intencional**: "O problema não é a ferramenta — é o **processo**"
+- Se o negrito está tentando compensar falta de clareza, **reestruturar a frase** em vez de negritar
+- Preservar negritos funcionais do gênero; remover os decorativos sem alterar as palavras ou a ênfase semântica do trecho
+- "Teste de hierarquia" — ao olhar a página, fica claro por que cada destaque existe?
+
+---
+
+### Listas com rótulo em negrito
+
+**Problema:** IA produz listas onde todo item começa com um termo em negrito seguido de dois-pontos, mesmo quando não há hierarquia real. Em documentação e material de consulta, esse formato pode ser legítimo; o sinal é seu uso automático em prosa ou em categorias artificiais.
+
+**Antes (IA):**
+> - **Agilidade:** O time reduziu o ciclo de entrega em 40%.
+> - **Qualidade:** Os bugs em produção caíram pela metade.
+> - **Engajamento:** A satisfação do time subiu 12 pontos no eNPS.
+
+**Depois (humano):**
+> - Agilidade: a equipe reduziu o ciclo de entrega em 40%.
+> - Qualidade: os bugs em produção caíram pela metade.
+> - Engajamento: a satisfação da equipe subiu 12 pontos no eNPS.
+
+**Evitar em PT-BR:**
+- Estrutura "**Palavra:** frase explicativa" repetida em série sem hierarquia real
+- Listas de 3+ itens onde o gênero não pede consulta rápida e a prosa preserva melhor as relações
+- Forçar categorias artificiais para criar itens
+
+**Sinais adicionais de detecção:**
+- Estrutura repetitiva: "**Termo:** frase explicativa" em 3+ itens consecutivos
+- Itens que são minitópicos de documentação, não pontos argumentativos
+- A lista poderia ser uma tabela 2xN
+
+**Técnicas avançadas de correção:**
+- Se a informação é factual e tabular → converter em **tabela**, preservando rótulos, valores e correspondências
+- Se a informação é argumentativa → converter em **prosa corrida** sem criar relação causal ou conclusão nova
+- Se a lista é inevitável → usar marcadores simples sem cabeçalho em negrito
+- Manter cabeçalhos em negrito quando forem rótulos funcionais do gênero, conforme a regra contextual canônica
+- "Teste do slide" — se a lista parece um slide de apresentação, formatar como slide (ou reescrever como parágrafo)
+
+---
+
+### Title Case em títulos
+
+**Problema:** Em inglês, Title Case é comum em headings. Em português brasileiro, não. A norma é capitalizar só a primeira palavra e nomes próprios. Title Case em PT-BR é sinal claro de texto gerado por modelo treinado em inglês.
+
+**Antes (IA):**
+> ## Estratégias De Marketing Digital Para Pequenas Empresas
+
+**Depois (humano):**
+> ## Estratégias de marketing digital para pequenas empresas
+
+**Evitar em PT-BR:**
+- Capitalizar preposições (De, Para, Com, Em)
+- Capitalizar substantivos comuns em títulos (Empresas, Estratégias, Resultados)
+- Qualquer padrão que lembre capa de livro americano
+
+**Sinais adicionais de detecção:**
+- Títulos onde preposições e artigos estão capitalizados
+- Títulos que parecem capa de livro americano ("Estratégias De Marketing Para Pequenas Empresas")
+- Mistura de Title Case com sentenças em minúsculo no mesmo documento
+
+**Técnicas avançadas de correção:**
+- Aplicar **regra ABNT**: só a primeira letra do título e nomes próprios em maiúsculas
+- Exceção: se o documento é explicitamente para público americano, Title Case é aceitável
+- "Teste do jornal brasileiro" — abrir matéria da Folha ou Piauí; os títulos usam minúsculas em preposições
+
+---
+
+### Emojis decorativos
+
+**Problema:** IA enfia emojis em títulos e itens como enfeite. Brasileiro usa emoji em mensagem informal, não em título de seção ou tópico técnico. A presença de 🚀💡✅🎯 em texto profissional é assinatura de máquina.
+
+**Antes (IA):**
+> 🚀 **Lançamento:** Produto entra no ar em setembro
+> 💡 **Observação:** Usuários preferem onboarding curto
+> ✅ **Próximos passos:** Agendar reunião com stakeholders
+> 🎯 **Meta:** Crescer 30% no trimestre
+
+**Depois (humano):**
+> Lançamento: o produto entra no ar em setembro.
+> Observação: os usuários preferem um onboarding curto.
+> Próximos passos: agendar uma reunião com os stakeholders.
+> Meta: crescer 30% no trimestre.
+
+**Evitar em PT-BR:**
+- Emoji antes de título ou item quando for puramente decorativo
+- 🚀💡✅🎯📊 como decoração de estrutura
+- Emoji incompatível com o perfil de voz ou sem função comunicativa
+
+**Sinais adicionais de detecção:**
+- Emojis em headings de seção, títulos de artigo, ou como marcadores em texto profissional
+- Sequência de emojis sem função comunicativa (decoração pura)
+- Emoji em texto que não é mensagem pessoal ou post de rede social
+
+**Técnicas avançadas de correção:**
+- Em texto formal ou técnico, remover emoji puramente decorativo; preservar ícone que comunique estado, alerta ou categoria funcional
+- Em WhatsApp e rede social, manter emojis compatíveis com o perfil de voz e retirar apenas repetição mecânica
+- Ao remover o emoji, não acrescentar humor, ironia, surpresa nem nova ênfase para compensar
+- "Teste do canal" — o emoji cumpre uma função aceita nesse gênero ou serve apenas de enfeite?
+
+---
+
+### Aspas curvas vs retas
+
+**Problema:** ChatGPT e Claude usam aspas curvas tipográficas (" ") por padrão. A maioria dos brasileiros digita aspas retas (" ") porque é o que o teclado produz. Aspas curvas em texto informal ou técnico são bandeira de IA.
+
+**Antes (IA):**
+> O gestor disse que o projeto está "no caminho certo" e que a equipe está "engajada".
+
+**Depois (humano):**
+> O gestor disse que o projeto está "no caminho certo" e que a equipe está "engajada".
+
+**Evitar em PT-BR:**
+- " " (curvas) em qualquer contexto que não seja diagramação profissional
+- ' ' (apóstrofos curvos) no lugar de ' '
+- Misturar aspas curvas e retas no mesmo texto
+
+**Sinais adicionais de detecção:**
+- Mistura de aspas curvas e retas no mesmo documento
+- Aspas curvas em texto que claramente veio de teclado brasileiro (onde o padrão é reta)
+- Aspas curvas em mensagens de WhatsApp ou Slack (impossível no mobile)
+
+**Técnicas avançadas de correção:**
+- **Regra de consistência**: escolher um padrão e manter — se o texto é de teclado brasileiro, usar aspas retas
+- Em diagramação profissional (livro, revista), aspas curvas são aceitáveis
+- "Teste do WhatsApp" — se o texto parece conversa de app, aspas retas obrigatórias
+
+---
+
+### Decoração Unicode
+
+**Problema:** IA usa caracteres Unicode decorativos como setas (→, ←, ↗), marcadores especiais (•, ▸, ▪), marcas de verificação (✓, ✗) e separadores (│, ─) que humanos brasileiros não digitam. Teclado brasileiro produz -, *, > e ponto final.
+
+**Antes (IA):**
+> Benefícios do novo processo:
+> → Redução de 40% no tempo de resposta
+> → Aumento na satisfação do cliente
+> → Integração com sistemas legados
+>
+> Stack: React │ Node.js │ PostgreSQL
+
+**Depois (humano):**
+> Benefícios do novo processo:
+> - Redução de 40% no tempo de resposta
+> - Aumento na satisfação do cliente
+> - Integração com sistemas legados
+>
+> Stack: React, Node.js, PostgreSQL
+
+**Evitar em PT-BR:**
+- → como marcador de item (usar - ou *)
+- │ como separador (usar vírgula, barra ou ponto)
+- ✓ e ✗ no corpo do texto quando não houver função; se houver, usar o estado textual equivalente sem inferi-lo
+
+**Sinais adicionais de detecção:**
+- Setas (→, ↗), marcadores especiais (▸, ▪), marcas de verificação (✓, ✗) e separadores (│, ─) que não são renderizados pelo teclado padrão brasileiro
+- Uso de emojis como marcadores em texto formal
+- Texto que parece ter sido copiado de um Notion com modelos de produtividade
+
+**Técnicas avançadas de correção:**
+- Converter setas em hífens ou asteriscos: "→" → "-"
+- Remover separadores Unicode: "React │ Node.js │ PostgreSQL" → "React, Node.js, PostgreSQL"
+- Converter marcas de verificação em texto somente quando houver equivalente explícito, preservando o estado original: aprovado, reprovado, sim, não ou pendente
+- "Teste do terminal" — se o texto renderiza com caracteres quebrados num terminal sem Unicode, é decoração artificial
+
+---
+
+### Fragmentos curtos dramáticos
+
+**Problema:** IA produz frases de 1-3 palavras isoladas como parágrafo para criar "impacto". Esse recurso existe em copywriting, mas IA abusa até em texto informativo. Brasileiro escreve assim no Twitter, não em artigo ou e-mail.
+
+**Antes (IA):**
+> O mercado mudou.
+>
+> Radicalmente.
+>
+> E quem não se adaptar vai ficar para trás. A pergunta não é se, mas quando. O futuro já chegou.
+>
+> Literalmente.
+
+**Depois (humano):**
+> O mercado mudou radicalmente. Quem não se adaptar vai ficar para trás. A pergunta não é se, mas quando: o futuro já chegou, literalmente.
+
+**Evitar em PT-BR:**
+- Palavra isolada como parágrafo sem função no perfil de voz ("Radicalmente.", "Literalmente.", "Ponto.")
+- Sequência de fragmentos dramáticos sem função no perfil de voz
+- Fragmento + ponto final para criar "peso" artificial
+
+**Sinais adicionais de detecção:**
+- Palavra ou frase de 1-3 palavras isolada como parágrafo inteiro
+- Uso repetido (mais de 1 por texto) em contexto que não é Twitter
+- Fragmento que não acrescenta informação — só "peso" artificial
+
+**Técnicas avançadas de correção:**
+- Em prosa neutra, integrar fragmentos ao período correspondente; em Crônica ou Rede Social, preservá-los quando fizerem parte da voz
+- Integrar o fragmento sem perder o intensificador: "Mudou. Radicalmente." → "Mudou radicalmente."
+- Se o fragmento é pura ênfase, ajustar a pontuação sem acrescentar urgência, conclusão ou avaliação
+- "Teste do gênero" — o fragmento combina com o perfil de voz ou apenas simula impacto?
+
+---
+
+### Vírgula de Oxford (Oxford Comma)
+
+**Problema:** IA treinada em inglês frequentemente insere vírgula antes do "e" final em enumerações (ex: "maçãs, bananas, e laranjas"). Em português brasileiro, essa vírgula é atípica e desnecessária — a norma é não usar vírgula antes de "e" em listas. Sua presença é marcador tipográfico de texto gerado por modelo anglófono.
+
+**Antes (IA):**
+> A plataforma oferece dashboards, relatórios customizados, e integração com APIs externas. O time trabalha com React, Node.js, e PostgreSQL.
+
+**Depois (humano):**
+> A plataforma oferece dashboards, relatórios customizados e integração com APIs externas. O time trabalha com React, Node.js e PostgreSQL.
+
+**Evitar em PT-BR:**
+- Vírgula antes de "e" no último item de lista: "A, B, e C" → "A, B e C"
+- Vírgula antes de "ou" final: "X, Y, ou Z" → "X, Y ou Z"
+- Exceção legítima: quando o "e" liga orações com sujeitos diferentes (vírgula de clareza, não de lista)
+
+**Sinais adicionais de detecção:**
+- Vírgula antes de "e" em listas de 3+ itens
+- Vírgula antes de "ou" em alternativas
+- Mistura de textos com e sem Oxford comma no mesmo documento
+
+**Técnicas avançadas de correção:**
+- **Regra PT-BR**: sem vírgula antes de "e"/"ou" em listas
+- Exceção: quando a vírgula evita ambiguidade real (sujeitos diferentes nas orações)
+- "Teste do vestibular" — se a frase passaria no ENEM como correta, a vírgula está certa
+
+---
+
+### Ponto final e aspas (convenção brasileira)
+
+**Problema:** IA segue a convenção americana de colocar ponto final DENTRO das aspas, mesmo quando a citação não é frase completa. Em português brasileiro, o ponto vai FORA quando as aspas envolvem apenas parte da frase.
+
+**Antes (IA — convenção americana):**
+> O CEO disse que a empresa está "no caminho certo."
+>
+> A meta é atingir o que chamam de "product-market fit."
+
+**Depois (humano — convenção brasileira):**
+> O CEO disse que a empresa está "no caminho certo".
+>
+> A meta é atingir o que chamam de "product-market fit".
+
+**Regra PT-BR:**
+- Citação é frase completa e independente → ponto dentro: Ele disse: "Vamos resolver isso."
+- Citação é parte da frase do autor → ponto fora: O plano é "escalar rápido".
+- Na dúvida: ponto fora (é o padrão brasileiro em texto corrido)
+
+**Sinais adicionais de detecção:**
+- Ponto dentro das aspas quando a citação é parte da frase do autor
+- Inconsistência: às vezes dentro, às vezes fora, no mesmo texto
+- Citações de 1 palavra com ponto dentro ("impacto.")
+
+**Técnicas avançadas de correção:**
+- **Regra PT-BR**: se a citação é parte da frase → ponto fora. Se a citação é frase completa → ponto dentro
+- Padronizar em todo o documento
+- "Teste da citação" — se a citação termina com "que", o ponto vai fora
+
+---
+
+### Ressalva com preâmbulo (minimiza → infla)
+
+**Problema:** Padrão de IA de 2025/2026 em que uma minimização genérica é seguida por inflação automática para compensar. O contraste pode ser legítimo e deve ser preservado; o sinal aparece quando a moldura se repete mecanicamente ou quando os dois lados não têm apoio no texto-fonte.
+
+**Antes (IA):**
+> Embora pareça um conceito simples, a consistência na publicação de conteúdo representa um dos pilares mais fundamentais e transformadores de qualquer estratégia de marketing digital moderna.
+>
+> À primeira vista, essa pode parecer uma mudança incremental, mas na verdade constitui uma transformação paradigmática na forma como organizações interagem com seus stakeholders.
+
+**Depois (humano):**
+> A consistência na publicação de conteúdo é um dos pilares mais fundamentais e transformadores de qualquer estratégia moderna de marketing digital. Mesmo assim, pode parecer um conceito simples.
+>
+> A mudança constitui uma transformação paradigmática na forma como as organizações interagem com seus stakeholders, embora à primeira vista possa parecer incremental.
+
+**Evitar em PT-BR:**
+- "Embora pareça simples, na verdade é [superlativo]"
+- "À primeira vista... mas na verdade constitui..."
+- "Pode parecer óbvio, porém [inflação]"
+- "Apesar de ser um conceito básico, representa um dos mais [superlativo]"
+- Qualquer estrutura que minimiza no preâmbulo e infla na oração principal
+
+**Sinais adicionais de detecção:**
+- Estrutura "minimiza → infla" em uma única frase: "Embora pareça simples, é transformador"
+- Uso de "na verdade" como ponte entre minimização e inflação
+- O preâmbulo é sempre genérico ("parece simples", "à primeira vista") e a inflação é sempre superlativa
+
+**Técnicas avançadas de correção:**
+- Preservar os dois lados quando o autor afirma um contraste; remover apenas a moldura repetitiva, sem escolher uma posição nova
+- Se o contraste é legítimo, mostrar a tensão com dados somente quando esses dados já estiverem na fonte; caso contrário, manter a formulação qualitativa
+- "Teste do podcast host" — se o apresentador diria isso sem soar como vendedor, a frase é honesta
--- a/.github/skills/humanizar/references/padroes-exclusivos-pt-br.md
+++ b/.github/skills/humanizar/references/padroes-exclusivos-pt-br.md
@@ -0,0 +1,567 @@
+# Padrões Exclusivos do Português Brasileiro
+
+Padrões de texto de IA que **só existem em PT-BR** — não têm equivalente na skill humanizer original em inglês. São marcadores culturais e linguísticos que denunciam texto gerado por máquina especificamente no contexto brasileiro.
+
+Estes padrões exploram vícios do português corporativo, jurídico e acadêmico brasileiro que LLMs absorveram de seus dados de treinamento e reproduzem de forma desproporcional.
+
+> **Regra transversal:** toda correção abaixo preserva sujeitos, fatos, números, fontes, relações causais, prazos, estado temporal e modalidade. Os pares mostram mudanças de forma, não autorização para completar lacunas. Escolha a alternativa compatível com o perfil de voz; se ela exigir informação ausente ou mudar o grau de certeza, não a use.
+
+---
+
+## 1. Gerundismo
+
+### Gerundismo Corporativo
+
+**Palavras/expressões gatilho:** "vou estar enviando", "estaremos realizando", "vai estar recebendo", "iremos estar providenciando", "vamos estar agendando"
+
+**Problema:** LLMs absorveram o gerundismo de e-mails corporativos e scripts de telemarketing brasileiros. Nenhum humano escreve assim voluntariamente — é padrão de SAC e central de atendimento que virou piada nacional. Quando aparece em texto "natural", grita automação.
+
+**Antes (IA):**
+> Vou estar enviando o relatório de métricas do Q2 para validação. A equipe de produto vai estar realizando a análise de impacto e estaremos agendando uma call para alinhamento na próxima semana.
+
+**Depois (humano):**
+> Vou enviar o relatório de métricas do Q2 para validação. A equipe de produto vai analisar o impacto, e vamos agendar uma call de alinhamento na próxima semana.
+
+**Evitar em PT-BR:**
+- "Vou estar enviando"
+- "Estaremos realizando"
+- "Vai estar recebendo"
+- "Iremos estar providenciando"
+- "Vamos estar disponibilizando"
+
+**Alternativas naturais:**
+- "Vou estar enviando" → "Vou enviar"
+- "Estaremos realizando" → "Realizaremos"
+- "Vai estar recebendo" → "Vai receber"
+- "Iremos estar providenciando" → "Providenciaremos"
+- "Vamos estar disponibilizando" → "Vamos disponibilizar"
+
+**Sinais adicionais de detecção:**
+- "Vai estar + gerúndio" em e-mails de SAC e respostas de chatbot
+- "Iremos estar + gerúndio" em comunicações formais de empresas
+- Gerundismo em texto que deveria ser direto (mensagens de WhatsApp, Slack)
+
+**Técnicas avançadas de correção:**
+- Converter para futuro simples: "vou estar enviando" → "vou enviar"
+- Se o gerúndio indica processo contínuo real, mantê-lo e simplificar apenas a perífrase, sem trocar o verbo da fonte
+- Preservar sujeito, prazo e modalidade: uma promessa vaga não ganha data, e uma ação futura não vira ação concluída
+- "Teste do áudio" — ler a frase em voz alta; se soa como atendente de telemarketing, é gerundismo
+
+### Gerúndio Conclusivo (Falsa Análise de Impacto)
+
+**Palavras/expressões gatilho:** "..., destacando a importância de...", "..., contribuindo para...", "..., demonstrando que...", "..., reforçando a necessidade de...", "..., evidenciando que...", "..., mostrando como...", "..., sublinhando o papel de...", "..., consolidando a posição de..."
+
+**Problema:** LLMs fecham frases com orações reduzidas de gerúndio que fingem ser análise de impacto — mas não dizem nada que o leitor não já deduziu. É um tique que infla o texto com falsa profundidade. Funciona como "conclusão automática por frase" que humanos não fazem: nós ou tiramos a conclusão em frase separada, ou deixamos o leitor tirar sozinho.
+
+**Antes (IA):**
+> A Nubank atingiu 100 milhões de clientes em 2025, consolidando sua posição como maior fintech da América Latina. O app teve nota 4.8 na App Store, demonstrando que a experiência do usuário continua sendo prioridade. A empresa expandiu para México e Colômbia, reforçando a necessidade de adaptação local.
+
+**Depois (humano):**
+> A Nubank atingiu 100 milhões de clientes em 2025 e consolidou sua posição como a maior fintech da América Latina. O app teve nota 4,8 na App Store; isso demonstrou que a experiência do usuário continua sendo prioridade. A empresa expandiu para México e Colômbia, o que reforçou a necessidade de adaptação local.
+
+**Evitar em PT-BR:**
+- "..., destacando a importância de [coisa óbvia]"
+- "..., contribuindo para o fortalecimento de..."
+- "..., demonstrando que [conclusão que já estava implícita]"
+- "..., reforçando a necessidade de..."
+- "..., evidenciando o compromisso com..."
+- "..., consolidando [posição/presença/papel]"
+- Qualquer gerúndio no final que funciona como "mini-conclusão" redundante
+
+**Alternativas naturais:**
+- Cortar a oração de gerúndio somente quando ela for semanticamente redundante
+- Se a oração expressa conclusão, causalidade ou modalidade, transformá-la em frase finita sem apagar essa relação
+- Reaproveitar um detalhe concreto já presente sem substituir por ele uma conclusão que também faça parte da fonte
+- Usar coordenação simples: "e consolidou sua posição como a maior" em vez de "consolidando sua posição como a maior"
+
+**Sinais adicionais de detecção:**
+- Orações reduzidas de gerúndio no final de frase como "conclusão automática"
+- Padrão: [afirmação], [gerúndio conclusivo] → "O app tem nota 4.8, demonstrando que UX é prioridade"
+- O gerúndio repete o que já foi dito sem adicionar informação
+
+**Técnicas avançadas de correção:**
+- Cortar o gerúndio apenas se a remoção não alterar nenhuma proposição
+- Se a conclusão integra o conteúdo → transformar em frase independente, preservando sujeito e força da afirmação
+- "Teste do copy-paste" — se você pode remover a oração com gerúndio e a frase ainda diz tudo, o gerúndio é redundante
+
+---
+
+## 2. Conectivos Arcaicos Fora de Contexto
+
+### Latinismo Jurídico em Texto Informal
+
+**Palavras/expressões gatilho:** "ademais", "outrossim", "destarte", "não obstante", "doravante", "nesse diapasão", "mister se faz", "em última análise", "no bojo de", "ab initio"
+
+**Problema:** Essas palavras pertencem ao registro de contratos, decisões judiciais e regulamentos universitários. LLMs as usam em posts de blog, e-mails de produto e copy de landing page porque foram treinados em muito texto jurídico brasileiro (que é desproporcionalmente formal comparado a outros idiomas). Brasileiro nenhum usa "outrossim" num Slack.
+
+**Antes (IA):**
+> A implementação do novo sistema de pagamentos trouxe resultados expressivos. Ademais, a taxa de churn reduziu 15%. Outrossim, o NPS subiu 12 pontos. Destarte, pode-se concluir que a estratégia foi bem-sucedida.
+
+**Depois (humano):**
+> A implementação do novo sistema de pagamentos trouxe resultados expressivos: a taxa de churn caiu 15%, e o NPS subiu 12 pontos. Isso permite concluir que a estratégia foi bem-sucedida.
+
+**Evitar em PT-BR:**
+- "Ademais" (fora de petições judiciais)
+- "Outrossim" (em qualquer contexto que não seja um contrato)
+- "Destarte" (ninguém fala isso desde 1920)
+- "Nesse diapasão" (só juiz usa)
+- "Mister se faz" (linguagem de despacho)
+- "Doravante" (até em contratos tá caindo em desuso)
+
+**Alternativas naturais:**
+- "Ademais" → "Além disso" / "E ainda"; usar apenas vírgula se a relação aditiva continuar inequívoca
+- "Outrossim" → "Também" / "E"; cortar somente se não houver relação adicional a preservar
+- "Destarte" → "Então" / "Por isso" / "Resultado:"
+- "Não obstante" → "Mesmo assim" / "Apesar disso" / "Mas"
+- "Doravante" → "A partir de agora" / "De agora em diante"
+
+**Sinais adicionais de detecção:**
+- "Outrossim" em qualquer contexto que não seja petição judicial
+- "Destarte" em textos pós-2000
+- "Nesse diapasão" em comunicação corporativa moderna
+- Texto que parece ter sido escrito por alguém que leu muito Diário Oficial
+
+**Técnicas avançadas de correção:**
+- Substituir por conectivos modernos de mesmo valor lógico; não apagar contraste, conclusão ou marco temporal
+- Se o texto é jurídico → manter (é o registro esperado)
+- "Teste do Slack" — se você não escreveria no Slack da empresa, é arcaico
+
+---
+
+## 3. Aberturas Genéricas Estilo ENEM
+
+### Dissertação de Vestibular Disfarçada
+
+**Palavras/expressões gatilho:** "Em um mundo cada vez mais...", "No cenário atual...", "Na contemporaneidade...", "É inegável que...", "Diante do exposto...", "No contexto de...", "Em meio a um cenário de..."
+
+**Problema:** LLMs reproduzem a estrutura da redação nota 1000 do ENEM — abertura genérica que contextualiza o tema de forma ampla antes de dizer qualquer coisa específica. Todo brasileiro reconhece esse padrão porque escreveu assim no vestibular. Em texto profissional, é sinal claro de que ninguém pensou antes de escrever.
+
+**Antes (IA):**
+> Em um mundo cada vez mais digitalizado, as fintechs brasileiras vêm desempenhando um papel fundamental na democratização do acesso a serviços financeiros. No cenário atual, é inegável que a tecnologia transformou a maneira como lidamos com dinheiro.
+
+**Depois (humano):**
+> O mundo está cada vez mais digitalizado, e as fintechs brasileiras vêm desempenhando um papel fundamental na democratização do acesso a serviços financeiros. Hoje, é inegável que a tecnologia transformou a maneira como lidamos com dinheiro.
+
+**Evitar em PT-BR:**
+- "Em um mundo cada vez mais [adjetivo]..."
+- "No cenário atual..."
+- "Na contemporaneidade..."
+- "É inegável que..."
+- "No contexto de [tema genérico]..."
+- "Diante de um cenário de..."
+- "É sabido que..."
+- "Nos dias atuais..."
+
+**Alternativas naturais:**
+- Começar com dado concreto somente quando ele já estiver no texto-fonte
+- Começar com afirmação direta que preserve a tese e o grau de certeza existentes
+- Usar pergunta apenas quando ela mantiver a modalidade do trecho e combinar com o perfil de voz
+- Começar com exemplo somente se ele tiver sido fornecido na fonte
+- Começar pelo meio: pular o contexto e ir direto ao ponto
+
+**Sinais adicionais de detecção:**
+- "É inegável que" como abertura de parágrafo
+- "No contexto contemporâneo" como introdução genérica
+- "Diante do exposto" como transição entre seções
+- Abertura que poderia ser copiada para qualquer redação de vestibular
+
+**Técnicas avançadas de correção:**
+- Começar com **dado existente**, **pergunta semanticamente equivalente** ou **afirmação direta**
+- Se o texto precisa de contexto → colocar o contexto DEPOIS do gancho, não antes
+- "Teste do primeiro tweet" — se a abertura seria um tweet que ninguém leria, é ENEM demais
+
+---
+
+## 4. Ressalva burocrática
+
+### Marcadores de Importância Artificial
+
+**Palavras/expressões gatilho:** "Vale ressaltar que...", "É importante destacar que...", "Cumpre salientar que...", "Faz-se necessário...", "É fundamental observar que...", "Convém mencionar que...", "Importa registrar que...", "Merece atenção o fato de que..."
+
+**Problema:** Essas expressões existem para preencher espaço sem dizer nada. São muletas de quem precisa parecer que está dizendo algo importante sem comprometer-se com a afirmação. LLMs usam MUITO porque o treinamento inclui toneladas de texto burocrático brasileiro (diários oficiais, pareceres, relatórios corporativos). Brasileiro real, quando quer ressaltar algo, simplesmente diz.
+
+**Antes (IA):**
+> Vale ressaltar que a taxa de conversão do funil apresentou crescimento significativo. É importante destacar que esse resultado está diretamente relacionado à implementação das novas landing pages. Cumpre salientar que a equipe de growth executou 14 testes A/B no período.
+
+**Depois (humano):**
+> A taxa de conversão do funil cresceu significativamente. Esse resultado está diretamente relacionado à implementação das novas landing pages. A equipe de growth executou 14 testes A/B no período.
+
+**Evitar em PT-BR:**
+- "Vale ressaltar que..."
+- "É importante destacar que..."
+- "Cumpre salientar que..."
+- "Faz-se necessário observar que..."
+- "É fundamental que se reconheça..."
+- "Convém mencionar que..."
+- "Importa registrar que..."
+- "Merece destaque o fato de que..."
+
+**Alternativas naturais:**
+- Cortar a expressão inteira e começar pela informação, sem quantificar o que a fonte não quantificou: "A taxa de conversão cresceu significativamente."
+- Se precisa enfatizar: usar posição na frase (colocar no início) ou itálico
+- Em perfil neutro, usar transição discreta ou nenhuma; em perfil informal, escolher uma chamada compatível com a voz já existente
+
+**Sinais adicionais de detecção:**
+- "Cumpre salientar" como abertura de frase
+- "Faz-se necessário" em e-mails de trabalho
+- "Importa registrar" em textos que não são registro oficial
+- Duas ou mais expressões de ressalva no mesmo parágrafo
+
+**Técnicas avançadas de correção:**
+- Cortar a expressão e ir direto à informação
+- Se precisa de ênfase → usar posição na frase (começo) ou repetição intencional
+- "Teste do post-it" — se a informação cabe num post-it sem perder sentido, a muleta não era necessária
+
+---
+
+## 5. Formalidade Deslocada
+
+### Registro de Ofício em Contexto de Startup
+
+**Palavras/expressões gatilho:** "No que tange a", "Tendo em vista que", "O referido", "Conforme mencionado anteriormente", "O supracitado", "No tocante a", "Em face do exposto", "Haja vista que"
+
+**Problema:** LLMs confundem "escrever bem" com "escrever formal". Em PT-BR, o registro formal extremo pertence a documentos oficiais (ofícios, memorandos, atas). Quando aparece em e-mail de produto, post de blog de tecnologia ou comunicação interna de startup, parece que um robô leu o Manual de Redação da Presidência da República e achou que serve pra tudo.
+
+**Antes (IA):**
+> No que tange à implementação do novo design system, tendo em vista que a equipe de front-end sinalizou gargalos, faz-se necessário priorizar a refatoração do referido sistema de componentes. Conforme mencionado anteriormente, o supracitado projeto tem deadline no Q3.
+
+**Depois (humano):**
+> Sobre a implementação do design system: como a equipe de front-end sinalizou gargalos, é necessário priorizar a refatoração desse sistema de componentes. Como já mencionado, o projeto tem deadline no Q3.
+
+**Evitar em PT-BR:**
+- "No que tange a" (fora de parecer jurídico)
+- "Tendo em vista que" (fora de justificativa formal)
+- "O referido" / "O supracitado" (fora de processo judicial)
+- "Conforme mencionado anteriormente" (redundante — se mencionou, o leitor sabe)
+- "Em face do exposto" (conclusão de parecer)
+- "Haja vista que" (pedante em qualquer contexto informal)
+- "No tocante a" (burocracia pura)
+
+**Alternativas naturais:**
+- "No que tange a" → "Sobre" / "Quanto a"
+- "Tendo em vista que" → "Como" / "Já que" / "Porque"
+- "O referido" → "Esse" / "O"; cortar somente se o referente continuar inequívoco
+- "Conforme mencionado anteriormente" → "Como já mencionado"; cortar somente se a referência anterior não tiver função
+- "Em face do exposto" → "Diante disso" / "Por isso", quando introduzir conclusão
+- "Haja vista que" → "Já que" / "Porque"
+
+**Sinais adicionais de detecção:**
+- "No que tange a" em e-mails de produto
+- "Tendo em vista que" em mensagens de Slack
+- "O referido projeto" em comunicação interna
+- Registro formal em contexto onde a informalidade é esperada
+
+**Técnicas avançadas de correção:**
+- Mapear o **perfil de voz** antes de reescrever e reduzir apenas a formalidade deslocada
+- Substituir por equivalentes brasileiros compatíveis com o canal, sem forçar coloquialidade
+- "Teste do canal" — a formulação combina com o meio, o público e a voz do texto-fonte?
+
+---
+
+## 6. Oficialês brasileiro
+
+### Linguagem Jurídica/Burocrática Fora do Contexto Legal
+
+**Palavras/expressões gatilho:** "Segue em anexo para os devidos fins", "Venho por meio deste", "Solicito a gentileza de", "Segue para conhecimento e providências", "Informo para os devidos fins", "Encaminho o presente para apreciação", "Trata o presente de"
+
+**Problema:** O oficialês brasileiro é um dialeto próprio — linguagem de ofício, memorando e despacho que LLMs internalizaram de forma massiva porque a administração pública brasileira produz volumes absurdos de texto nesse registro. Quando aparece fora do contexto público ou legal, denuncia geração automática. Nenhum PM de startup escreve "venho por meio deste" num Notion.
+
+**Antes (IA):**
+> Venho por meio deste comunicar que a feature de onboarding encontra-se em fase final de implementação. Solicito a gentileza de agendar a revisão de código para os devidos fins de validação. Segue em anexo o documento de especificação para conhecimento e eventuais providências.
+
+**Depois (humano):**
+> A feature de onboarding está na fase final de implementação. Solicito o agendamento da revisão de código para validação. O documento de especificação segue anexo para conhecimento e eventuais providências.
+
+**Evitar em PT-BR:**
+- "Venho por meio deste [comunicar/informar/solicitar]"
+- "Segue em anexo para os devidos fins"
+- "Solicito a gentileza de"
+- "Para conhecimento e providências"
+- "Informo para os devidos fins que"
+- "Trata o presente [e-mail/documento] de"
+- "Sirvo-me do presente para"
+- "Encaminho para apreciação superior"
+
+**Alternativas naturais:**
+- "Venho por meio deste informar que [fato]" → "[Fato]", sem apresentá-lo como novidade se a fonte não fizer isso
+- "Segue em anexo" → "O arquivo segue anexo" / "O arquivo está anexado", conforme o perfil
+- "Solicito a gentileza de [ação]" → "Solicito que [ação]"; em perfil informal, "Pode [ação]?"
+- "Para conhecimento" → "Para informar" / "Para ciência", preservando a finalidade
+- "Para os devidos fins" → cortar somente quando não designar uma finalidade específica
+
+**Sinais adicionais de detecção:**
+- "Venho por meio deste" em qualquer canal que não seja ofício público
+- "Para os devidos fins" como fechamento de e-mail
+- "Solicito a gentileza de" em mensagens internas
+- Texto que parece ter sido gerado por um chatbot de órgão público
+
+**Técnicas avançadas de correção:**
+- Converter para linguagem direta sem criar prazo ou responsável: "Preciso que você faça X"; manter o prazo somente se ele existir na fonte
+- Se é comunicação externa formal → manter um nível mínimo de polidez, mas sem oficialês
+- "Teste do canal" — a formulação mantém a polidez e a voz esperadas naquele contexto?
+
+---
+
+## 7. Evitação de Verbos Simples
+
+### Substituição de "É/São/Tem" por Eufemismos Rebuscados
+
+**Palavras/expressões gatilho:** "constitui", "configura-se como", "dispõe de", "encontra-se", "figura como", "representa", "serve como", "afigura-se como", "situa-se", "apresenta-se como", "há [quantidade]", "existem [quantidade]", "haver necessidade"
+
+**Problema:** Estudos mostram >10% de queda no uso de copulativas simples ("é", "são", "está") em textos gerados por IA pós-2023. LLMs evitam verbos simples e os substituem por construções rebuscadas — provavelmente porque o RLHF penaliza respostas "simples demais". Em PT-BR, isso cria frases que nenhum brasileiro falaria em voz alta. Inclui também a substituição sistemática do verbo "ter" existencial (uso coloquial consagrado no Brasil) por "haver" ou "existir" para soar "correto" — um hipercorrecionismo que nenhum brasileiro pratica na fala e que cada vez menos pratica na escrita.
+
+**Antes (IA):**
+> O Nubank constitui uma das maiores fintechs da América Latina e configura-se como referência em experiência do usuário. A empresa dispõe de mais de 80 milhões de clientes e encontra-se em expansão para novos mercados. Seu modelo de negócios figura como paradigma para startups do setor.
+
+**Depois (humano):**
+> O Nubank é uma das maiores fintechs da América Latina e é referência em experiência do usuário. A empresa tem mais de 80 milhões de clientes e está em expansão para novos mercados. Seu modelo de negócios é um paradigma para startups do setor.
+
+**Evitar em PT-BR:**
+- "constitui [algo]" (quando "é" resolve)
+- "configura-se como" (quando "é" resolve)
+- "dispõe de" (quando "tem" resolve)
+- "encontra-se [em algum estado]" (quando "está" resolve)
+- "figura como" (quando "é" resolve)
+- "situa-se" (quando "fica" ou "está" resolve)
+- "apresenta-se como" (quando "parece" ou "é" resolve)
+- "afigura-se como" (ninguém fala isso)
+- "há muitos/muitas [X]" (quando "tem muito/muita [X]" é mais natural — perfis Crônica, Corporativo Informal e WhatsApp)
+- "existem diversas opções" (quando "tem várias opções" resolve)
+- "não há como negar" (quando "não tem como negar" soa brasileiro)
+
+**Alternativas naturais:**
+- "constitui uma referência" → "é referência"
+- "dispõe de 80 milhões" → "tem 80 milhões"
+- "encontra-se em expansão" → "está em expansão"
+- "configura-se como líder" → "é líder"
+- "situa-se entre os maiores" → "está entre os maiores" / "é um dos maiores"
+- "há muitas pessoas" → "tem muita gente"
+- "existem diversos fatores" → "tem vários fatores" / "são vários fatores"
+- "há necessidade de" → "precisa de" / "tem que"
+- "não há dúvidas de que" → "não tem dúvida que" / "é claro que"
+
+**Nota sobre "ter" existencial:** Em perfis formais (Acadêmico), "haver" pode ser mantido. Em Crônica, Corporativo Informal, Rede Social e WhatsApp, "ter" existencial pode ser a forma natural brasileira. A escolha deve acompanhar o perfil de voz e não alterar quantidade, existência ou modalidade.
+
+**Sinais adicionais de detecção:**
+- "Dispõe de" em vez de "tem"
+- "Configura-se como" em vez de "é"
+- "Encontra-se em" em vez de "está"
+- Texto onde os verbos "ser", "ter", "estar" foram sistematicamente substituídos
+
+**Técnicas avançadas de correção:**
+- Restaurar verbos simples quando apropriado ao registro
+- Se o texto é acadêmico ou jurídico → manter a formalidade, mas evitar excesso
+- "Teste da fala" — se você não falaria assim, não escreva assim
+
+---
+
+## 8. Expressões Infladas
+
+### Vocabulário que Brasileiro Não Usa na Fala
+
+**Palavras/expressões gatilho:** "contribui significativamente para", "no âmbito de", "de forma expressiva", "em termos de", "a nível de", "no que diz respeito a", "sob a ótica de", "à luz de", "na esfera de", "potencializar"
+
+**Problema:** LLMs produzem frases que parecem tradução simultânea de jargão corporativo americano filtrado por um manual de redação de 1995. São expressões que aparecem em relatórios anuais e apresentações de PowerPoint, mas que nenhum brasileiro usa quando está explicando algo de verdade. O teste é simples: se você não falaria isso em voz alta numa reunião, não deveria escrever.
+
+**Antes (IA):**
+> A estratégia de product-led growth contribui significativamente para a escalabilidade do negócio no âmbito do mercado brasileiro de SaaS. No que diz respeito à aquisição de usuários, a abordagem potencializa os resultados de forma expressiva, sob a ótica da eficiência operacional.
+
+**Depois (humano):**
+> A estratégia de product-led growth contribui bastante para a escalabilidade do negócio no mercado brasileiro de SaaS. Na aquisição de usuários, a abordagem melhora os resultados de forma expressiva do ponto de vista da eficiência operacional.
+
+**Evitar em PT-BR:**
+- "contribui significativamente para" sem explicar o efeito; se a fonte não quantifica, preservar a intensidade qualitativa sem criar número
+- "no âmbito de" (99% das vezes é só "em")
+- "de forma expressiva/significativa" quando encobre um valor que já existe na fonte
+- "no que diz respeito a" (é "sobre")
+- "sob a ótica de" (é "pra" ou "do ponto de vista de")
+- "potencializar" quando a fonte já permite escolher com precisão entre "melhorar" e "aumentar"
+- "à luz de" (é "considerando" ou "com base em")
+- "a nível de" (errado gramaticalmente E vazio semanticamente)
+- "na esfera de" (é "em")
+
+**Alternativas naturais:**
+- "contribui significativamente" → "contribui bastante"; usar número somente quando ele já existir na fonte
+- "no âmbito de" → "em" / "dentro de"; cortar somente se não delimitar o escopo
+- "potencializar resultados" → "melhorar resultados"; nomear a métrica somente se a fonte a identificar
+- "de forma expressiva" → manter a intensidade qualitativa ou usar a medida já informada
+- "no que diz respeito a" → "sobre" / "quanto a"
+- "sob a ótica de" → "do ponto de vista de", sem criar um agente ausente
+
+**Sinais adicionais de detecção:**
+- "No que diz respeito a" em vez de "sobre"
+- "Sob a ótica de" em vez de "do ponto de vista de"
+- "À luz de" em vez de "com base em"
+- Expressões que parecem tradução literal de "in terms of", "from the perspective of"
+
+**Técnicas avançadas de correção:**
+- Substituir por equivalentes diretos em português
+- Aplicar regra de compressão: se a expressão tem 5+ palavras e pode ser dita em 1-2, comprimir
+- "Teste da tradução reversa" — se a expressão parece que foi traduzida do inglês corporativo, substituir pelo equivalente que brasileiro realmente fala
+
+---
+
+## 9. Transições Mecânicas Repetidas
+
+### O Parágrafo que Começa Sempre Igual
+
+**Palavras/expressões gatilho:** "Além disso", "Nesse sentido", "Diante disso", "Em contrapartida", "Por outro lado", "No entanto", "Dessa forma", "Sendo assim", "Nessa perspectiva", "À vista disso"
+
+**Problema:** IA em PT-BR usa transições como muleta estrutural — todo parágrafo começa com um conectivo, criando um ritmo mecânico reconhecível. É o equivalente brasileiro do "Furthermore" / "Moreover" em inglês. Humanos brasileiros variam: às vezes usam transição, às vezes começam direto, às vezes com pergunta, às vezes com exemplo. A repetição de "Além disso... Nesse sentido... Diante disso..." a cada parágrafo é fingerprint de IA.
+
+**Antes (IA):**
+> O mercado de SaaS B2B no Brasil cresceu 40% em 2025. **Além disso**, a entrada de novos players internacionais acirrou a competição. **Nesse sentido**, startups brasileiras precisam diferenciação clara. **Diante disso**, estratégias de nicho ganham relevância. **Em contrapartida**, o aumento de competição também valida o mercado. **Dessa forma**, empresas que encontrarem seu posicionamento tendem a prosperar.
+
+**Depois (humano):**
+> O mercado de SaaS B2B no Brasil cresceu 40% em 2025. A entrada de novos concorrentes internacionais acirrou a competição. Por isso, startups brasileiras precisam de diferenciação clara, e estratégias de nicho ganham relevância. Ao mesmo tempo, o aumento da competição também valida o mercado. Empresas que encontrarem seu posicionamento tendem a prosperar.
+
+**Evitar em PT-BR:**
+- "Além disso" como abertura de mais de 1 parágrafo no mesmo texto
+- "Nesse sentido" sem referência clara ao "sentido"
+- "Diante disso" / "Diante do exposto" (dissertação de ENEM)
+- "Em contrapartida" quando não há real contrapartida
+- "Por outro lado" quando não há dois lados claros
+- "Dessa forma" / "Sendo assim" como conclusão automática
+- Qualquer padrão de [conectivo] + [afirmação] repetido 3+ vezes seguidas
+
+**Alternativas naturais:**
+- Começar com o conteúdo direto, sem transição: "Startups brasileiras precisam se diferenciar."
+- Usar pergunta retórica apenas se ela não mudar a modalidade e combinar com o perfil de voz
+- Fragmento com conteúdo existente: "Resultado: estratégias de nicho ganham relevância."
+- Usar exemplo concreto somente quando ele já estiver no texto-fonte
+- Contraste implícito (sem "por outro lado"): "Só que mais competição também valida o mercado."
+- Continuação natural com "E", "Mas", "Só que" ou "Agora", escolhendo apenas o conectivo que preserve a relação original
+
+---
+
+## 10. Purismo Linguístico Artificial
+
+### Traduzir Estrangeirismos que Brasileiro Usa Naturalmente
+
+**Palavras/expressões gatilho:** "retroalimentação" (feedback), "implantação" (deploy), "rotatividade de clientes" (churn), "corrida/iteração" (sprint), "fluxo de trabalho" (workflow), "partes interessadas" (stakeholders), "entregáveis" (deliverables), "plataforma de dados" (data lake)
+
+**Problema:** LLMs foram treinados com textos acadêmicos e governamentais que evitam estrangeirismos por política editorial. Quando geram texto sobre tech/startup/marketing, traduzem termos que nenhum profissional brasileiro traduz. "Vamos reduzir o churn" é como todo mundo fala. "Vamos reduzir a rotatividade de clientes" soa como tradução de livro técnico de 2003. Forçar tradução de termos naturalizados é um dos sinais mais claros de IA em PT-BR tech.
+
+**Antes (IA):**
+> A equipe realizou a implantação do novo microsserviço e obteve retroalimentação positiva das partes interessadas. A rotatividade de clientes diminuiu após a iteração focada em experiência do usuário. O fluxo de trabalho foi otimizado para entregar os entregáveis dentro do prazo da corrida.
+
+**Depois (humano):**
+> A equipe fez o deploy do novo microsserviço e recebeu feedback positivo dos stakeholders. O churn diminuiu após a sprint focada em experiência do usuário. O workflow foi otimizado para entregar os deliverables dentro do prazo da sprint.
+
+**Evitar em PT-BR (traduzir quando o termo inglês já é padrão no mercado):**
+- "retroalimentação" em vez de "feedback"
+- "implantação" em vez de "deploy" (contexto tech)
+- "rotatividade de clientes" em vez de "churn"
+- "corrida" ou "iteração" em vez de "sprint"
+- "partes interessadas" em vez de "stakeholders"
+- "entregáveis" em vez de "deliverables"
+- "fluxo de trabalho" em vez de "workflow"
+- "computação em nuvem" em vez de "cloud" (contexto dev)
+- "aprendizado de máquina" em vez de "machine learning" (contexto tech)
+- "cadeia de suprimentos" em vez de "supply chain" (contexto startup/ops)
+
+**Alternativas naturais:**
+- Usar o termo em inglês como brasileiro usa: "feedback", "deploy", "churn", "sprint"
+- Se o usuário pedir explicação para público não técnico, usar o termo + explicação sem acrescentar consequência: "churn (perda de clientes)"
+- Manter consistência: se usou "deploy" uma vez, não alterna com "implantação"
+- Preservar a terminologia do texto-fonte. Adaptá-la apenas quando o perfil de voz ou o público exigirem e houver equivalente sem perda de precisão
+
+---
+
+## 11. Colocação Pronominal Artificial
+
+### Ênclise Forçada e Mesóclise Fantasma
+
+**Palavras/expressões gatilho:** "Apresento-lhe", "Trata-se de", "Faz-se necessário", "Encontra-se disponível", "Realizou-se", "Dar-se-á", "Enviar-lhe-ei", "Diga-se de passagem", "Permite-nos afirmar"
+
+**Problema:** LLMs seguem regras prescritivas de colocação pronominal com rigor artificial — colocam pronomes em ênclise (verbo + pronome) e até mesóclise em situações onde o brasileiro usa próclise (pronome + verbo) intuitivamente. Na fala e escrita real brasileira, a próclise domina em quase todos os contextos. A ênclise excessiva soa como tradução de manual de gramática portuguesa (de Portugal), não como brasileiro escrevendo.
+
+**Antes (IA):**
+> O sistema permite-nos monitorar métricas em tempo real. Trata-se de uma solução que integra-se facilmente ao stack existente. Encontra-se disponível para todos os planos. Enviar-lhe-emos o relatório até sexta.
+
+**Depois (humano):**
+> O sistema nos permite monitorar métricas em tempo real. É uma solução que se integra facilmente ao stack existente. Está disponível para todos os planos. Nós lhe enviaremos o relatório até sexta.
+
+**Evitar em PT-BR:**
+- "Permite-nos" (quando "nos permite" é mais natural)
+- "Trata-se de" em excesso (quando "é" resolve)
+- "Encontra-se" (quando "está" ou "fica" resolve)
+- "Integra-se" no início ou meio de frase (quando "se integra" soa melhor)
+- Qualquer mesóclise fora de texto jurídico ou literário intencional ("dar-se-á", "enviar-lhe-ei")
+- Ênclise após sujeito explícito: "O usuário cadastra-se" → "O usuário se cadastra"
+
+**Alternativas naturais:**
+- "Permite-nos" → "nos permite"; "deixa a gente" somente em perfil informal já autorizado
+- "Trata-se de" → "É" / "Isso é"
+- "Encontra-se disponível" → "Está disponível"; "Tá disponível" somente em perfil informal
+- "Realizou-se a migração" → "A migração foi realizada", sem inventar quem a realizou
+- "Dar-se-á início" → "Terá início" / "Vai começar", preservando o tempo verbal
+- "Faz-se necessário" → "Precisa" / "É necessário"
+
+**Nota:** A ênclise é legítima após vírgula, no início absoluto de frase, e em imperativos ("Diga-me", "Faça-o"). O problema é quando a IA a usa em posições onde o brasileiro naturalmente coloca o pronome antes do verbo.
+
+---
+
+## 12. Voz Passiva Analítica
+
+### Passiva por Influência do Inglês
+
+**Palavras/expressões gatilho:** "foi realizado por", "foi implementado pela equipe", "será desenvolvido pelo time", "foi identificado que", "é considerado como", "foi constatado que", "foram obtidos resultados", "foi tomada a decisão"
+
+**Problema:** IAs abusam da voz passiva analítica (ser + particípio) por influência direta do inglês, onde a passiva é muito mais frequente que em português. Em PT-BR natural, preferimos voz ativa ou passiva sintética (com "se"). Sequências de 3+ frases em passiva soam como tradução automática de release notes em inglês.
+
+**Antes (IA):**
+> O relatório foi finalizado pela equipe de dados. A análise foi conduzida utilizando metodologia ágil. Foram identificados 3 gargalos principais. A decisão foi tomada de priorizar o módulo de pagamentos. Os testes foram realizados em ambiente de staging.
+
+**Depois (humano):**
+> A equipe de dados finalizou o relatório. Na análise, conduzida com metodologia ágil, foram identificados 3 gargalos principais. Decidiu-se priorizar o módulo de pagamentos. Os testes foram realizados em ambiente de staging.
+
+**Evitar em PT-BR:**
+- "O relatório foi finalizado pela equipe" → "A equipe finalizou o relatório" / "A equipe concluiu o relatório"
+- "Foi identificado que" → "Identificou-se que"; nomear o agente apenas se a fonte o informar
+- "A decisão foi tomada" → "Decidiu-se"; usar "A equipe decidiu" somente se esse agente constar da fonte
+- "Foram obtidos resultados positivos" → "Houve resultados positivos"
+- "É considerado como referência" → "É referência"
+- 3+ frases consecutivas em voz passiva
+
+**Alternativas naturais:**
+- Voz ativa quando o sujeito estiver explícito: "A equipe entregou" em vez de "Foi entregue pela equipe"
+- Passiva sintética (com "se"): "Identificaram-se 3 bugs"
+- Indeterminação do sujeito somente quando a fonte também não identifica o agente
+- Inversão simples: "Concluiu-se o relatório" em vez de "O relatório foi concluído"
+
+**Nota:** A passiva é legítima quando o agente é desconhecido ou irrelevante ("O servidor foi invadido"). O problema é usá-la quando existe um sujeito claro que deveria estar agindo.
+
+---
+
+## Resumo: Lista rápida de verificação anti-IA em PT-BR
+
+| # | Padrão | Teste rápido |
+|---|---|---|
+| 1 | Gerundismo | Tem "vou estar + gerúndio"? |
+| 2 | Conectivos arcaicos | Tem "ademais", "outrossim", "destarte" fora de contexto jurídico? |
+| 3 | Abertura ENEM | Começa com "Em um mundo cada vez mais..."? |
+| 4 | Ressalva burocrática | Tem "Vale ressaltar que" ou "Cumpre salientar"? |
+| 5 | Formalidade deslocada | Tem "No que tange a" num e-mail de startup? |
+| 6 | Oficialês | Tem "Venho por meio deste" fora de ofício? |
+| 7 | Evitação de verbos simples | "É" virou "constitui"? "Tem" virou "há"? |
+| 8 | Expressões infladas | Tem "contribui significativamente" sem número? |
+| 9 | Transições mecânicas | Todo parágrafo começa com conectivo? |
+| 10 | Purismo linguístico | Traduziu "feedback", "deploy", "churn"? |
+| 11 | Colocação pronominal artificial | Tem "permite-nos", "trata-se de", mesóclise? |
+| 12 | Voz passiva analítica | 3+ frases com "foi X pelo Y" em sequência? |
+
+**Se 3+ padrões aparecem no mesmo texto: alta probabilidade de geração por IA.**
+
+---
+
+## Nota sobre Contexto
+
+Estes padrões são calibrados para texto profissional brasileiro nas áreas de:
+- Tecnologia (dev, produto, infra)
+- Startups e scale-ups
+- Marketing digital
+- Fintech e SaaS
+- Comunicação corporativa moderna
+
+Em contextos onde a formalidade é esperada (petição judicial, artigo acadêmico publicado, comunicação diplomática), alguns desses padrões podem ser aceitáveis. A skill deve considerar o **perfil de voz** ativo antes de sinalizar.
--- a/.github/skills/humanizar/references/padroes-linguagem.md
+++ b/.github/skills/humanizar/references/padroes-linguagem.md
@@ -0,0 +1,209 @@
+# Padrões de Linguagem e Gramática (PT-BR)
+
+Padrões que denunciam texto gerado por IA no nível da escolha de palavras, construções gramaticais e estrutura de frase. Equivalentes brasileiros dos padrões 7-12 da skill original e de tropos catalogados em tropes.fyi.
+
+> **Preservação obrigatória:** em cada par “Antes/Depois”, o texto “Antes” é a única fonte de fatos, argumento, modalidade e posição autoral. A correção pode trocar construção, ordem e vocabulário, mas não pode criar experiência pessoal, número, fonte, causa, opinião ou certeza. Não remova informação apenas para quebrar um padrão.
+>
+> **Ajuste ao perfil:** os exemplos “Depois” usam registro neutro. Em perfis Acadêmico, Jornalístico ou Jurídico, preserve terminologia, atribuições e formalidade funcional; em perfis informais, use oralidade somente quando solicitada ou presente no original. A naturalidade vem da adequação, não da informalidade obrigatória.
+
+---
+
+### 1. Vocabulário de IA em PT-BR
+
+**Palavras/expressões gatilho:** crucial, fundamental, cenário, landscape/panorama, no âmbito de, no bojo de, nesse diapasão, destarte, outrossim, mister se faz, em última análise, inegável, indubitavelmente, exponencialmente, de forma exponencial, disruptivo, paradigma, holístico, sinergia, alavancar, robusto, escalável, ecossistema (abstrato), jornada (figurativo), mergulhar em (delve into), desbloquear (unlock), desvendar insights (uncover insights), rica tapeçaria (rich tapestry), um testemunho de (a testament to), serve como um lembrete (serves as a reminder), na paisagem/cenário em constante evolução (ever-evolving landscape), navegar [complexidades] (navigate), ponta de lança (spearhead), sem costura/sem fricção (seamless), multifacetado, catalisador, orquestrar, delinear
+
+**Problema:** Modelos de linguagem em PT-BR abusam de um vocabulário pomposo e repetitivo que nenhum brasileiro usa em conversas normais — nem em textos profissionais. São equivalentes brasileiros de termos recorrentes em inglês, como "delve", "crucial" e "landscape". Muitos são traduções diretas de texto ruim em inglês que soam ainda mais artificiais em português — ninguém fala "rica tapeçaria" ou "desbloquear potencial" no Brasil.
+
+**Antes (IA):**
+> É fundamental destacar que o ecossistema de startups brasileiro passa por um momento crucial de maturação. No âmbito da inovação, diversas empresas estão alavancando soluções disruptivas que prometem transformar o panorama do mercado de forma exponencial.
+
+**Depois (humano):**
+> O mercado brasileiro de startups está amadurecendo. Nesse processo, várias empresas usam soluções que prometem transformar o mercado de forma exponencial.
+
+**Evitar em PT-BR:**
+- "É fundamental/crucial/inegável destacar que..."
+- "No âmbito/bojo/cenário de..."
+- "Alavancar soluções robustas e escaláveis"
+- "Mergulhar em/Mergulhar fundo em" → "explorar" / "ver de perto" / "entrar em"
+- "Desbloquear o potencial" → "aproveitar" / "usar melhor"
+- "Desvendar insights" → "descobrir" / "achar" / "perceber"
+- "Rica tapeçaria de experiências" → cortar (sempre é enchimento)
+- "É um testemunho de/da" → declarar diretamente o fato já apresentado, sem trocar indício por prova
+- "Serve como um lembrete de que" → "lembra que" / cortar
+- "No cenário/paisagem em constante evolução" → cortar o cenário, ir direto ao ponto
+- "Navegar as complexidades de" → "lidar com"; use "resolver" somente se o original afirmar que houve solução
+- "Sem costura" / "sem fricção" → "fluido" / "que funciona bem" / "redondo"
+- "Catalisador de mudanças" → descrever a função causal somente se ela já estiver afirmada no original
+- "Orquestrar a transformação" → "coordenar a transformação", quando essa ação constar do original
+
+---
+
+### 2. Evitação de verbos de ligação
+
+**Palavras/expressões gatilho:** configura-se como, constitui, representa, figura como, posiciona-se como, desponta como, consolida-se como, atua como, funciona como, opera como, se estabelece como
+
+**Problema:** IA evita "é", "são" e "tem" como se fossem palavras proibidas. Substitui por construções rebuscadas que nenhum humano usaria numa conversa. Em PT-BR isso soa como texto jurídico ou dissertação de vestibular ruim.
+
+**Antes (IA):**
+> O Nubank configura-se como a maior fintech da América Latina. A plataforma desponta como referência em experiência do usuário e consolida-se como alternativa aos bancos tradicionais.
+
+**Depois (humano):**
+> O Nubank é a maior fintech da América Latina. A plataforma é referência em experiência do usuário e uma alternativa aos bancos tradicionais.
+
+**Evitar em PT-BR:**
+- "Configura-se como / consolida-se como"
+- "Desponta como referência em"
+- "Posiciona-se como alternativa a"
+
+---
+
+### 3. Paralelismos Negativos
+
+**Palavras/expressões gatilho:** não é apenas X, mas também Y; não se trata apenas de X, trata-se de Y; mais do que X, é Y; vai muito além de X; transcende o simples X; não é meramente X, é sobretudo Y
+
+**Problema:** Construção formulaica que infla importância artificialmente. Cria uma falsa dicotomia onde o autor finge rejeitar algo para depois abraçar algo maior — mas ambas as partes dizem a mesma coisa. Modelos de linguagem recorrem a essa forma porque ela simula profundidade sem exigir raciocínio real.
+
+**Antes (IA):**
+> Produto não é apenas sobre funcionalidades. Não se trata meramente de entregar código — trata-se de resolver problemas reais. O PM vai muito além de escrever histórias de usuário; ele é, sobretudo, um tradutor entre negócio e tecnologia.
+
+**Depois (humano):**
+> Produto envolve funcionalidades, entrega de código e resolução de problemas reais. O trabalho de PM inclui escrever histórias de usuário e traduzir necessidades entre negócio e tecnologia.
+
+**Evitar em PT-BR:**
+- "Não se trata apenas de X, trata-se de Y"
+- "Vai muito além de simplesmente..."
+- "Mais do que X, é sobretudo Y"
+
+---
+
+### 4. Abuso da regra de três
+
+**Palavras/expressões gatilho:** clareza, concisão e coerência; inovação, tecnologia e transformação; planejar, executar e medir; qualquer tríade rítmica com "e" antes do terceiro item; três adjetivos em sequência; três substantivos abstratos agrupados
+
+**Problema:** Modelos de linguagem agrupam ideias em trios porque a estrutura é retoricamente satisfatória — mas, quando aparece em todo parágrafo, vira cacoete. Textos naturais variam a quantidade de itens conforme o conteúdo.
+
+**Antes (IA):**
+> Nossa cultura é baseada em transparência, colaboração e inovação. Buscamos agilidade, qualidade e impacto. Valorizamos autonomia, responsabilidade e aprendizado contínuo.
+
+**Depois (humano):**
+> Transparência e colaboração orientam nossa cultura. A inovação também conta. Buscamos agilidade sem abrir mão da qualidade nem do impacto; valorizamos autonomia, responsabilidade e aprendizado contínuo.
+
+**Correção segura:** varie a estrutura sem eliminar nenhum item enumerado. Se a tríade for funcional ao perfil — por exemplo, em texto normativo ou apresentação — mantenha-a.
+
+**Evitar em PT-BR:**
+- "Transparência, colaboração e inovação"
+- "Planejamento, execução e controle"
+- Três adjetivos ou substantivos abstratos em sequência, parágrafo após parágrafo
+
+---
+
+### 5. Variação lexical forçada
+
+**Palavras/expressões gatilho:** ciclagem de sinônimos para o mesmo referente — ex: "a ferramenta" → "a solução" → "a plataforma" → "o sistema" → "o produto"; ou para pessoas: "o profissional" → "o colaborador" → "o especialista" → "o gestor"
+
+**Problema:** Modelos de linguagem tendem a ciclar sinônimos para evitar repetir a mesma palavra. Pessoas repetem palavras quando isso favorece a clareza — e a variação forçada confunde o leitor sobre se estamos falando da mesma coisa ou de coisas diferentes.
+
+**Antes (IA):**
+> O Slack revolucionou a comunicação corporativa. A ferramenta de mensagens oferece canais temáticos. A plataforma colaborativa integra com mais de 2.000 aplicativos. A solução de produtividade é usada por 750 mil empresas.
+
+**Depois (humano):**
+> O Slack revolucionou a comunicação corporativa e é usado por 750 mil empresas. Ele oferece canais temáticos e integração com mais de 2.000 aplicativos.
+
+**Evitar em PT-BR:**
+- Ciclagem "ferramenta → solução → plataforma → sistema"
+- "O profissional → o colaborador → o especialista"
+- Trocar referente a cada frase quando poderia repetir ou usar pronome
+
+---
+
+### 6. Falsas faixas
+
+**Palavras/expressões gatilho:** de X a Y; desde X até Y; abrangendo desde X até Y; vai de X a Y, passando por Z; cobre desde X até Y
+
+**Problema:** Modelos de linguagem criam faixas que soam amplas, mas não representam uma escala real. Os extremos escolhidos não são opostos significativos — são apenas dois exemplos aleatórios com "de...a..." no meio para simular abrangência.
+
+**Antes (IA):**
+> O evento abordou desde inteligência artificial até gestão de pessoas, passando por marketing digital e produto. Os participantes variaram de estagiários a executivos, de startups em estágio inicial a corporações multinacionais.
+
+**Depois (humano):**
+> O evento reuniu inteligência artificial, gestão de pessoas, marketing digital e produto. Participaram estagiários, executivos, pessoas de startups em estágio inicial e de corporações multinacionais.
+
+**Correção segura:** desdobre somente os extremos e exemplos já citados. Não complete a faixa com público, quantidade, preferência ou resultado presumido.
+
+**Evitar em PT-BR:**
+- "Desde inteligência artificial até gestão de pessoas"
+- "De estagiários a C-levels"
+- "Abrangendo desde X até Y, passando por Z"
+
+---
+
+### 7. Anáfora Abusiva
+
+**Palavras/expressões gatilho:** repetição do mesmo início em 3+ frases consecutivas — "É preciso...", "Precisamos...", "O futuro...", "A tecnologia...", "Esse é o momento de...", "Cada vez mais..."
+
+**Problema:** Anáfora é recurso retórico legítimo — em discursos, manifestos e poesia. Mas modelos de linguagem a usam como muleta estrutural em textos expositivos onde a repetição não serve a um propósito estilístico. Vira eco robótico.
+
+**Antes (IA):**
+> Precisamos repensar a forma como contratamos. Precisamos questionar os processos legados. Precisamos ouvir mais e falar menos. Precisamos aceitar que o modelo antigo não funciona mais. Precisamos de coragem para mudar.
+
+**Depois (humano):**
+> Precisamos repensar a forma de contratar e questionar os processos legados. O modelo antigo já não funciona; é hora de ouvir mais, falar menos e ter coragem para mudar.
+
+**Evitar em PT-BR:**
+- "Precisamos..." repetido 3+ vezes
+- "É hora de..." repetido em sequência
+- "Cada vez mais..." como abertura de múltiplos parágrafos
+
+---
+
+### 8. 'O X? Um Y.' (Perguntas Retóricas Auto-respondidas)
+
+**Palavras/expressões gatilho:** "O resultado? [Substantivo/frase dramática]." / "A resposta? [Afirmação categórica]." / "O segredo? [Revelação]." / "O problema? [Diagnóstico]." / "A solução? [Receita]." / "O impacto? [Superlativo]."
+
+**Problema:** Estrutura de pergunta e resposta curta que imita redação publicitária. Quando usada uma vez, pode funcionar. Quando modelos de linguagem a repetem em todo parágrafo, vira tique de redator de LinkedIn. O texto inteiro se torna uma sequência de falsas revelações.
+
+**Antes (IA):**
+> O desafio? Escalar sem perder cultura. A solução? Contratar por valores, não por currículo. O resultado? Um time coeso que entrega 3x mais. O segredo? Autonomia com responsabilidade. O futuro? Uma empresa que não depende de um fundador.
+
+**Depois (humano):**
+> O desafio é escalar sem perder a cultura. A solução proposta é contratar por valores, não por currículo. O resultado é um time coeso que entrega três vezes mais. O segredo é combinar autonomia com responsabilidade. O futuro imaginado é uma empresa que não depende do fundador.
+
+**Evitar em PT-BR:**
+- "O resultado? Um time coeso."
+- "O segredo? Consistência."
+- "A resposta? Simplicidade." (especialmente em sequência)
+
+---
+
+### 9. Decalques Sintáticos (Anglicismos Ocultos)
+
+**Palavras/expressões gatilho:** "endereçar um problema" (to address), "no final do dia" (at the end of the day), "performar" (to perform), "fazer sentido" (em excesso — to make sense), "estar no lugar" (to be in place), "correr um experimento" (to run an experiment), "levantar uma questão" (to raise a question), "colocar de outra forma" (to put it another way), "em termos de" (in terms of), "baseado em" sem sujeito (based on)
+
+**Problema:** Diferente dos estrangeirismos legítimos (deploy, feedback, sprint), os decalques são **estruturas do inglês traduzidas literalmente** que quebram a naturalidade sintática do português. A IA faz isso porque pensa em inglês e traduz — e o resultado parece texto de legendista apressado. Brasileiro de verdade usa o jargão inglês cru OU a expressão portuguesa equivalente — nunca a tradução literal da estrutura.
+
+**Antes (IA):**
+> Precisamos endereçar esse problema antes do próximo sprint. No final do dia, o que importa é se a funcionalidade performa bem em produção. Temos todas as peças no lugar para correr esse experimento. Isso levanta uma questão importante em termos de escalabilidade.
+
+**Depois (humano):**
+> Precisamos resolver esse problema antes do próximo sprint. No fim das contas, importa saber se a funcionalidade funciona bem em produção. Está tudo pronto para executar o experimento, o que traz uma questão sobre escalabilidade.
+
+**Evitar em PT-BR:**
+- "Endereçar um problema" → "resolver" / "tratar" / "atacar"
+- "No final do dia" → "no fim das contas" / "no fundo" / "na prática"
+- "Performar" (como verbo intransitivo) → "funcionar" / "rodar" / "se sair"
+- "Fazer sentido" em excesso (1-2x ok; 5x no texto = cacoete de tradução)
+- "Estar no lugar" / "ter no lugar" → "estar pronto" / "ter configurado"
+- "Correr um experimento" → "rodar" / "fazer" / "executar"
+- "Levantar uma questão" → "trazer uma questão" / "trazer um ponto", preservando se o original expressa dúvida ou apenas assunto
+- "Colocar de outra forma" → "dizendo de outro jeito" / "ou seja"
+- "Em termos de" → "sobre" / "quanto a" / "de" (geralmente dá pra cortar)
+- "Baseado em" sem sujeito ("Baseado nisso, decidimos...") → "Com base nisso" / "A partir disso"
+- "Dar uma olhada em" (to take a look at) → "ver" / "conferir" / "olhar"
+- "Estar na mesma página" (to be on the same page) → "estar alinhado" / "ter combinado"
+
+**Alternativas naturais:**
+- Preferir o verbo português que o brasileiro usa na fala: "resolver", "rodar", "funcionar"
+- Quando o jargão inglês for natural no perfil, ele pode ser mantido: “rodar o teste A/B” é preferível a “correr um experimento”
+- Testar lendo em voz alta: se soa como legenda de série, é decalque
+
+**Nota:** “Fazer sentido” já se naturalizou no PT-BR. O problema é a repetição mecânica; avalie a frequência em relação ao tamanho, ao perfil e à voz do texto, sem tratá-la isoladamente como prova de autoria.
--- a/.github/skills/humanizar/references/padroes-portugues-simplificado.md
+++ b/.github/skills/humanizar/references/padroes-portugues-simplificado.md
@@ -0,0 +1,437 @@
+# Padrões de Português Simplificado (PT-BR)
+
+Referência para o perfil de voz **📋 Português Simplificado**. Define operações de simplificação, substituições lexicais, métricas de referência e regras de escrita para produzir texto acessível sem infantilizar o conteúdo.
+
+> **Preservação obrigatória:** simplificar a forma nunca autoriza alterar fatos, argumento, modalidade ou posição autoral. Quando a simplificação criar ambiguidade factual ou técnica, manter a forma mais complexa e anotar no relatório. Toda operação está subordinada à **TRAVA FACTUAL**.
+>
+> **Princípio central:** clareza máxima com precisão intacta. Simplificar é tornar acessível, não é tornar raso.
+
+---
+
+## 1. Fundamentos
+
+Este perfil sintetiza três fontes complementares:
+
+| Fonte | Escopo | Contribuição principal |
+|---|---|---|
+| **PorSimples** (NILC/USP, 2007–2010) | Simplificação textual automática para inclusão digital | 7 operações sintáticas + 2 níveis (Natural/Strong) + corpus alinhado |
+| **Lei 15.263/2025** (Política Nacional de Linguagem Simples) | Comunicação pública acessível | 18 técnicas prescritivas para órgãos governamentais |
+| **NILC-Metrix** (2008–2023) | 200 métricas de complexidade textual para PT-BR | Limites quantitativos e validação empírica |
+
+### Referências técnicas
+
+- Corpus PorSimplesSent: [github.com/sidleal/porsimplessent](https://github.com/sidleal/porsimplessent) (CC BY 4.0)
+- SIMPLEX-PB (simplificação lexical): [github.com/nathanshartmann/SIMPLEX-PB](https://github.com/nathanshartmann/SIMPLEX-PB)
+- NILC-Metrix (200 métricas): [github.com/sidleal/nilcmetrix](https://github.com/sidleal/nilcmetrix) (AGPL-3.0)
+- Gov-Lang-BR (1.703 pares governo): Scalercio et al., ACL 2025
+
+---
+
+## 2. Operações de simplificação sintática
+
+Baseadas nas 10 operações do editor de anotação do PorSimples, consolidadas em 7 operações aplicáveis por um editor humano ou IA:
+
+### 2.1. Dividir períodos compostos
+
+Quebrar sentenças com mais de uma oração em frases independentes. Cada frase carrega uma ideia.
+
+**Antes:**
+> O governo anunciou o programa ontem, que prevê investimentos de R$ 2 bilhões em infraestrutura urbana, beneficiando 15 milhões de pessoas em todo o país.
+
+**Depois:**
+> O governo anunciou o programa ontem. O programa prevê investimentos de R$ 2 bilhões em infraestrutura urbana. O objetivo é beneficiar 15 milhões de pessoas em todo o país.
+
+**Regra:** se a frase tem mais de 25 palavras e contém vírgula seguida de pronome relativo ("que", "o qual", "onde") ou conjunção subordinativa, dividir.
+
+---
+
+### 2.2. Converter voz passiva em voz ativa
+
+A voz ativa explicita quem faz a ação. Usar passiva somente quando o agente for irrelevante, desconhecido ou quando a ativa criar ambiguidade.
+
+**Antes:**
+> A proposta foi aprovada pelo Senado após seis meses de tramitação.
+
+**Depois:**
+> O Senado aprovou a proposta após seis meses de tramitação.
+
+**Antes (passiva justificada — manter):**
+> O corpo foi encontrado na margem do rio.
+
+**Manter:** o agente é desconhecido; forçar ativa inventaria informação.
+
+---
+
+### 2.3. Reordenar para SVO (Sujeito-Verbo-Objeto)
+
+Eliminar inversões sintáticas que dificultam a compreensão. A ordem canônica do português é SVO.
+
+**Antes:**
+> Preocupa o comitê a possibilidade de atraso na entrega.
+
+**Depois:**
+> A possibilidade de atraso na entrega preocupa o comitê.
+
+**Antes:**
+> Aos beneficiários será garantido o acesso integral ao sistema.
+
+**Depois:**
+> Os beneficiários terão acesso integral ao sistema.
+
+---
+
+### 2.4. Substituir marcadores discursivos complexos por simples
+
+Trocar conectivos eruditos ou ambíguos por equivalentes diretos.
+
+| Complexo | Simples |
+|---|---|
+| não obstante | mas / porém |
+| outrossim | também / além disso |
+| destarte | por isso |
+| em que pese | apesar de |
+| haja vista | já que / porque |
+| mister se faz | é preciso / é necessário |
+| no que tange a | sobre / em relação a |
+| em face de | por causa de / diante de |
+| à medida que | conforme / enquanto |
+| conquanto | embora |
+| porquanto | porque |
+| sem prejuízo de | mantendo / sem afetar |
+| por intermédio de | por meio de / com |
+
+---
+
+### 2.5. Eliminar apostos longos
+
+Apostos com mais de 5 palavras viram frase separada. Apostos curtos (até 5 palavras) podem permanecer.
+
+**Antes:**
+> Sandra Aluísio, professora titular do Instituto de Ciências Matemáticas e de Computação da USP em São Carlos, coordenou o projeto PorSimples.
+
+**Depois:**
+> Sandra Aluísio coordenou o projeto PorSimples. Ela é professora titular do Instituto de Ciências Matemáticas e de Computação da USP, em São Carlos.
+
+**Aposto curto — manter:**
+> O NILC, centro de linguística computacional, desenvolveu as ferramentas.
+
+---
+
+### 2.6. Substituir palavras raras por sinônimos frequentes
+
+Trocar vocabulário de baixa frequência por equivalentes comuns, sem perder precisão técnica. Termos de domínio devem ser explicados na primeira ocorrência, não eliminados.
+
+**Antes:**
+> A implementação de políticas públicas que visem à mitigação dos impactos socioeconômicos configura-se como desafio premente.
+
+**Depois:**
+> Criar políticas públicas para reduzir os impactos sociais e econômicos é um desafio urgente.
+
+**Termo técnico — explicar, não eliminar:**
+> O churn (taxa de cancelamento de clientes) aumentou 15% no trimestre.
+
+---
+
+### 2.7. Explicitar sujeitos ocultos e referências ambíguas
+
+Quando o sujeito oculto ou o pronome puder gerar dúvida sobre quem age, explicitar.
+
+**Antes:**
+> O ministro reuniu-se com o secretário. Disse que o prazo seria ampliado.
+
+**Depois:**
+> O ministro reuniu-se com o secretário. O ministro disse que o prazo seria ampliado.
+
+**Sujeito oculto claro — não forçar:**
+> O sistema recebeu a atualização e já está funcionando.
+
+Neste caso, "já está funcionando" refere-se obviamente ao sistema. Explicitar seria redundante.
+
+---
+
+## 3. Substituições lexicais
+
+Tabela de substituições frequentes baseadas no SIMPLEX-PB e na Lei 15.263. Usar somente quando o substituto não alterar a precisão do texto-fonte.
+
+### 3.1. Vocabulário burocrático → direto
+
+| Evitar | Preferir |
+|---|---|
+| implementar | fazer / criar / colocar em prática |
+| operacionalizar | fazer funcionar / executar |
+| viabilizar | permitir / tornar possível |
+| otimizar | melhorar |
+| priorizar | dar prioridade a / fazer primeiro |
+| protocolar | registrar / entregar |
+| subsidiar | dar informações para / apoiar |
+| deliberar | decidir |
+| aferir | medir / verificar |
+| pleitear | pedir |
+| ensejar | causar / dar origem a |
+| auferir | receber / obter |
+| prospectar | buscar / procurar |
+| dirimir | resolver / esclarecer |
+| perfectibilizar | melhorar |
+
+### 3.2. Locuções → formas diretas
+
+| Evitar | Preferir |
+|---|---|
+| no âmbito de | em |
+| no que diz respeito a | sobre |
+| no tocante a | sobre |
+| com vistas a | para |
+| a fim de que | para que |
+| em virtude de | por causa de / porque |
+| por intermédio de | por meio de / com |
+| com o fito de | para |
+| a nível de | em (ou cortar) |
+| via de regra | geralmente |
+| de forma que | então / por isso |
+| tendo em vista que | porque / já que |
+| em consonância com | de acordo com |
+| face ao exposto | por isso |
+
+### 3.3. Adjetivos inflados → precisos
+
+| Evitar | Preferir |
+|---|---|
+| exponencial (figurativo) | grande / rápido / [número real] |
+| robusto (figurativo) | completo / forte / confiável |
+| holístico | completo / abrangente |
+| disruptivo | novo / que muda tudo |
+| inovador (vazio) | [descrever a novidade] |
+| paradigmático | que muda o padrão / importante |
+| multifacetado | com vários aspectos |
+| emblemático | representativo / simbólico |
+
+### 3.4. Quando NÃO substituir
+
+- **Termos técnicos do domínio do leitor:** "API", "endpoint", "deploy", "churn" → manter em texto para desenvolvedores
+- **Termos jurídicos em peças jurídicas:** "litisconsórcio", "agravo" → manter no perfil Jurídico
+- **Termos médicos em textos para profissionais de saúde:** "dispneia", "hemodinâmica" → manter
+- **Nomes próprios e siglas estabelecidas:** "INSS", "FGTS", "SUS" → manter (explicar na primeira ocorrência para público leigo)
+
+---
+
+## 4. Métricas de referência
+
+Valores derivados do corpus PorSimples e das categorias do NILC-Metrix. Usar como guia, não como regra rígida — o gênero e o público-alvo modulam os limites.
+
+### 4.1. Comprimento de sentença (ASL — Average Sentence Length)
+
+| Nível PorSimples | ASL (palavras/frase) | Público-alvo |
+|---|---|---|
+| Original | ~20 | Letramento pleno |
+| Natural | ~16 | Letramento básico |
+| **Strong** | **~13** | **Letramento rudimentar** |
+
+**Meta para este perfil:** ASL entre 13 e 18 palavras, dependendo do domínio.
+- Governo/saúde para público geral: ≤15
+- Documentação técnica para não-especialistas: ≤18
+- FAQ/onboarding: ≤13
+
+### 4.2. Classificação de frases por comprimento (NILC-Metrix)
+
+| Classificação | Palavras |
+|---|---|
+| Curta | até 11 |
+| Média | 11–12 |
+| Longa | 12–15 |
+| Muito longa | acima de 15 |
+
+**Meta:** maioria das frases entre curtas e longas. Minimizar frases "muito longas" (> 15 palavras). Se uma frase passar de 25, quase sempre pode ser dividida.
+
+### 4.3. Diversidade lexical (TTR — Type-Token Ratio)
+
+| Nível | TTR |
+|---|---|
+| Original | 0.19 |
+| Natural | 0.17 |
+| Strong | 0.16 |
+
+TTR mais baixo indica mais repetição de palavras — e no contexto de simplificação, isso é desejável. Não forçar sinônimos diferentes para a mesma coisa; repetição deliberada ajuda a compreensão.
+
+### 4.4. Complexidade sintática
+
+Indicadores do NILC-Metrix que sinalizam texto complexo:
+
+| Indicador | Texto complexo | Texto simples |
+|---|---|---|
+| Orações por sentença | > 2.3 | ≤ 1.5 |
+| Palavras antes do verbo principal | > 1.5 | ≤ 1.0 |
+| Proporção de orações não-SVO | > 0.33 | ≤ 0.15 |
+| Proporção de orações relativas | > 0.13 | ≤ 0.05 |
+| Proporção de orações subordinadas | > 0.44 | ≤ 0.20 |
+| Proporção de voz passiva | alto | baixo |
+
+---
+
+## 5. Regras de escrita
+
+15 regras prescritivas para o perfil Português Simplificado, inspiradas na Lei 15.263/2025 e nas operações do PorSimples. Cada regra tem prioridade (1 = sempre aplicar; 2 = aplicar quando possível; 3 = aplicar conforme o gênero).
+
+### Prioridade 1 — Sempre aplicar
+
+| # | Regra |
+|---|---|
+| R1 | **Uma ideia por frase.** Se a frase contém duas proposições independentes, dividir. |
+| R2 | **Ordem direta (SVO).** Sujeito antes do verbo, verbo antes do complemento. Inverter somente com razão estilística forte. |
+| R3 | **Voz ativa.** Converter passiva em ativa quando o agente for conhecido e relevante. |
+| R4 | **Palavras comuns.** Preferir o sinônimo mais frequente quando não houver perda de precisão. |
+| R5 | **Frases curtas.** Máximo de 25 palavras por frase. Meta: 13–18. |
+| R6 | **Conectivos explícitos e simples.** "Porque", "por isso", "então", "mas", "e", "também". |
+
+### Prioridade 2 — Aplicar quando possível
+
+| # | Regra |
+|---|---|
+| R7 | **Explicar termos técnicos na primeira ocorrência.** Entre parênteses ou em frase curta seguinte. |
+| R8 | **Evitar dupla negação.** "Não é impossível" → "É possível" (somente se não alterar a modalidade). |
+| R9 | **Evitar subjuntivo desnecessário.** "Caso haja necessidade" → "Se for necessário". |
+| R10 | **Listas para 3+ itens.** Se uma frase enumera três ou mais elementos, usar lista com marcadores. |
+| R11 | **Sujeito explícito.** Quando o sujeito oculto puder causar ambiguidade, explicitar. |
+| R12 | **Sem orações intercaladas longas.** Apostos > 5 palavras viram frase nova. |
+
+### Prioridade 3 — Conforme o gênero
+
+| # | Regra |
+|---|---|
+| R13 | **Sem estrangeirismos fora do domínio.** Manter termos consagrados no domínio do leitor; remover os que o público-alvo não conhece. |
+| R14 | **Repetição deliberada.** Repetir o substantivo em vez de usar pronome quando o referente estiver distante (> 2 frases). |
+| R15 | **Estrutura visual.** Usar subtítulos, tabelas e destaques para organizar informação densa. Não converter toda prosa em bullets. |
+
+---
+
+## 6. Domínios de aplicação
+
+### 6.1. Governo e comunicação pública
+
+Foco: cidadão comum, letramento variado. Seguir integralmente a Lei 15.263.
+
+**Antes:**
+> Os beneficiários do programa deverão comparecer à unidade de atendimento munidos de documento de identificação com foto, comprovante de residência atualizado e número de inscrição no Cadastro Único, sob pena de indeferimento do requerimento.
+
+**Depois:**
+> Se você é beneficiário do programa, vá até a unidade de atendimento. Leve:
+> - Documento com foto (RG ou CNH)
+> - Comprovante de endereço atualizado
+> - Número do Cadastro Único (CadÚnico)
+>
+> Sem esses documentos, o pedido será negado.
+
+---
+
+### 6.2. Saúde para público leigo
+
+Foco: pacientes e familiares. Evitar jargão médico; quando necessário, explicar.
+
+**Antes:**
+> A administração de anti-inflamatórios não esteroidais pode ocasionar efeitos adversos gastrointestinais, incluindo dispepsia, náuseas e, em casos mais graves, úlcera péptica.
+
+**Depois:**
+> Anti-inflamatórios como ibuprofeno podem causar problemas no estômago. Os mais comuns são:
+> - Dor ou queimação no estômago (dispepsia)
+> - Enjoo (náusea)
+>
+> Em casos mais graves, podem causar feridas no estômago (úlcera). Tome com alimento para reduzir o risco.
+
+---
+
+### 6.3. Documentação técnica para não-especialistas
+
+Foco: usuários finais de software, manuais de produto, onboarding.
+
+**Antes:**
+> Para efetuar a configuração do webhook, o usuário deverá acessar o painel administrativo, navegar até a seção de integrações e inserir a URL do endpoint que receberá as notificações, certificando-se de que o servidor de destino esteja configurado para aceitar requisições POST com payload em formato JSON.
+
+**Depois:**
+> Para configurar o webhook:
+>
+> 1. Acesse o painel administrativo
+> 2. Vá até **Integrações**
+> 3. Cole a URL do seu endpoint (o endereço que vai receber as notificações)
+>
+> Certifique-se de que seu servidor aceita requisições POST com dados em JSON.
+
+---
+
+### 6.4. Educação e material didático
+
+Foco: estudantes. Ordem clara, exemplos concretos, progressão do simples ao complexo.
+
+**Antes:**
+> A fotossíntese consiste em um processo bioquímico mediante o qual organismos autotróficos fotossintetizantes convertem energia luminosa em energia química, utilizando dióxido de carbono e água como reagentes e produzindo glicose e oxigênio como produtos.
+
+**Depois:**
+> Fotossíntese é o processo que as plantas usam para produzir seu próprio alimento.
+>
+> Como funciona:
+> - A planta absorve luz do sol, água e gás carbônico (CO₂)
+> - Com esses ingredientes, ela produz glicose (açúcar) e oxigênio (O₂)
+>
+> A glicose alimenta a planta. O oxigênio é liberado no ar — o mesmo que a gente respira.
+
+---
+
+## 7. Integração com TRAVA FACTUAL
+
+### 7.1. Quando NÃO simplificar
+
+| Situação | Razão | Ação |
+|---|---|---|
+| Simplificação altera relação causal | "A causou B" pode virar "A e B aconteceram" | Manter a forma complexa |
+| Simplificação remove qualificação necessária | "Possivelmente eficaz" virar "eficaz" | Manter modalidade |
+| Simplificação elimina exceção | "Exceto em casos de X" desaparece ao dividir | Preservar a exceção em frase separada |
+| Termo técnico é o nome oficial | Substituir "litisconsórcio" por "várias partes" em petição | Manter o termo; explicar se público for leigo |
+| Dado numérico exige contexto adjacente | "15% a mais que 2023" perde sentido separado de "2023" | Manter na mesma frase |
+
+### 7.2. Marcação de conflito
+
+Quando a simplificação ideal conflitar com a preservação factual:
+
+```
+⚠️ CONFLITO SIMPLIFICAÇÃO × TRAVA FACTUAL: [descrever o trecho].
+Mantida forma complexa para preservar [precisão / modalidade / causalidade / exceção].
+```
+
+### 7.3. Simplificação de citações e dados
+
+- **Citações diretas:** nunca simplificar. Preservar ipsis litteris.
+- **Dados numéricos:** manter todos. Pode-se acrescentar explicação entre parênteses se a fonte permitir.
+- **Nomes próprios e siglas:** manter. Expandir sigla na primeira ocorrência.
+
+---
+
+## 8. Diferença entre perfis
+
+| Aspecto | 📋 Português Simplificado | 🧑‍🏫 Didático | 📰 Jornalístico |
+|---|---|---|---|
+| Foco principal | Acessibilidade por simplificação formal | Explicação com exemplos | Informação factual concisa |
+| Frases | ≤ 25 palavras, meta 13-18 | Variadas, com ritmo pedagógico | Curtas, ordem direta |
+| Vocabulário | Comum; técnico explicado | Acessível mas com progressão | Preciso, sem adjetivação |
+| Listas | Sim, para 3+ itens | Sim, com passos numerados | Não (exceto infográfico) |
+| Exemplos | Somente se existirem na fonte | Incentivados (mas não inventados) | Não cabem |
+| Repetição | Deliberada para clareza | Permitida em reforço | Evitada (concisão) |
+| Estrutura visual | Subtítulos, tabelas, bullets | Pergunta → explicação → exemplo | Lide + pirâmide invertida |
+
+---
+
+## 9. Checklist de verificação
+
+Usar ao final da reescrita no perfil Português Simplificado:
+
+| # | Verificação | ✓/✗ |
+|---|---|---|
+| 1 | Todas as frases têm ≤ 25 palavras? | |
+| 2 | Maioria das frases está em ordem SVO? | |
+| 3 | Voz passiva aparece somente onde justificada? | |
+| 4 | Termos técnicos foram explicados na primeira ocorrência? | |
+| 5 | Conectivos são simples e explícitos? | |
+| 6 | Enumerações de 3+ itens estão em lista? | |
+| 7 | Apostos longos foram transformados em frase separada? | |
+| 8 | Sujeitos ambíguos foram explicitados? | |
+| 9 | Nenhuma informação foi removida ou adicionada? (TRAVA FACTUAL) | |
+| 10 | Modalidade preservada? ("pode" não virou "vai", "talvez" não sumiu) | |
+| 11 | Citações diretas permanecem intactas? | |
+| 12 | Dados numéricos completos e no contexto correto? | |
--- a/.github/skills/humanizar/references/padroes-tom.md
+++ b/.github/skills/humanizar/references/padroes-tom.md
@@ -0,0 +1,260 @@
+# Padrões de Tom — Detecção e Correção
+
+Padrões que denunciam tom artificial, servil ou performático em texto PT-BR. Cada padrão inclui gatilhos, exemplos brasileiros (tecnologia, startups, marketing e desenvolvimento) e alternativas editoriais.
+
+> **Preservação obrigatória:** em cada par “Antes/Depois”, o texto “Antes” é a única fonte de fatos, argumento, modalidade e posição autoral. A correção pode cortar muletas, reorganizar e simplificar, mas não pode criar experiência pessoal, número, fonte, causa, opinião ou certeza. Se faltar sustentação, preserve a dúvida ou aponte a lacuna.
+>
+> **Ajuste ao perfil:** os exemplos “Depois” usam registro neutro. Em perfil formal, preserve qualificações, atribuições e impessoalidade funcional; em perfil informal, use coloquialidade somente quando solicitada ou já presente; em nenhum perfil invente primeira pessoa para produzir “voz”.
+
+---
+
+### 1. Tom servil / bajulador
+
+**Palavras/expressões gatilho:** "Ótima pergunta!", "Com certeza!", "Excelente observação!", "Espero ter ajudado!", "Fico feliz em ajudar!", "Obrigado por compartilhar!"
+
+**Problema:** Elogios genéricos ao interlocutor antes de responder. Ninguém fala assim em texto profissional brasileiro — é marca registrada de chatbot tentando agradar.
+
+**Antes (IA):**
+> Ótima pergunta! O deploy contínuo com GitHub Actions é realmente uma abordagem fascinante. Com certeza posso te ajudar com isso! Vamos lá: primeiro, você precisa configurar o fluxo de trabalho em YAML...
+
+**Depois (humano):**
+> Para configurar deploy contínuo com GitHub Actions, comece pelo fluxo de trabalho em YAML.
+
+**Evitar em PT-BR:**
+- "Ótima pergunta!" / "Excelente ponto!"
+- "Com certeza!" / "Absolutamente!"
+- "Espero ter ajudado!" / "Fico feliz em contribuir!"
+
+---
+
+### 2. Avisos sobre limite de conhecimento
+
+**Palavras/expressões gatilho:** "Até onde sei...", "Com base nas informações disponíveis...", "Até minha última atualização...", "Não posso confirmar com certeza, mas...", "De acordo com minhas informações limitadas..."
+
+**Problema:** Expõe a natureza de máquina do autor com fórmulas sobre “última atualização”. O defeito está na fórmula, não na cautela: incerteza, limitação temporal e necessidade de confirmação devem ser preservadas quando fazem parte do conteúdo.
+
+**Antes (IA):**
+> Até onde sei, o Next.js 15 introduziu Server Actions como recurso estável. No entanto, informações mais recentes podem ter alterado esse cenário. Com base nas informações disponíveis até minha última atualização, a recomendação é usar App Router.
+
+**Depois (humano):**
+> As informações disponíveis indicam que o Next.js 15 tornou Server Actions estável e recomendam o App Router. Isso pode ter mudado; confirme antes de aplicar.
+
+**Correção segura:** retirar a autorreferência do assistente sem transformar hipótese em fato, recomendação em obrigação ou informação possivelmente desatualizada em certeza atual.
+
+**Evitar em PT-BR:**
+- "Até minha última atualização..."
+- "Com base nas informações disponíveis..."
+- "Não tenho informações suficientes para afirmar com certeza, mas..."
+
+---
+
+### 3. Comunicação Colaborativa Residual
+
+**Palavras/expressões gatilho:** "Aqui está um exemplo...", "Posso te ajudar com...", "Vou te mostrar como...", "Segue abaixo...", "Fique à vontade para perguntar mais!"
+
+**Problema:** O texto conserva vestígios de interação assistente-usuário. Parece resposta de suporte, não texto autoral. Quando publicado como artigo ou post, denuncia imediatamente a origem.
+
+**Antes (IA):**
+> Aqui está um exemplo de como implementar autenticação com JWT no Express. Vou te mostrar passo a passo como configurar o middleware. Fique à vontade para adaptar conforme suas necessidades!
+
+**Depois (humano):**
+> A seguir, a configuração passo a passo do middleware de autenticação com JWT no Express.
+
+**Evitar em PT-BR:**
+- "Aqui está um..." / "Segue abaixo..."
+- "Posso te ajudar com..." / "Vou te mostrar..."
+- "Fique à vontade para..." / "Não hesite em perguntar!"
+
+---
+
+### 4. Cautela excessiva
+
+**Palavras/expressões gatilho:** "Pode-se argumentar que...", "É possível que...", "Talvez seja o caso de...", "Alguns especialistas sugerem...", "Aparentemente...", "De certa forma..."
+
+**Problema:** O acúmulo de qualificadores pode esconder a proposição principal. A correção remove apenas redundância; não aumenta a certeza, não apaga exceções e não converte atribuição vaga em opinião do autor.
+
+**Antes (IA):**
+> Pode-se argumentar que microsserviços nem sempre são a melhor escolha para startups em estágio inicial. Alguns especialistas sugerem que, em determinados contextos, uma arquitetura monolítica pode ser potencialmente mais adequada para equipes menores.
+
+**Depois (humano):**
+> Há o argumento de que microsserviços nem sempre são a melhor escolha para startups em estágio inicial. Alguns especialistas sugerem que, em certos contextos, uma arquitetura monolítica pode ser mais adequada para equipes menores.
+
+**Correção segura:** mantenha verbos modais como “pode” e “parece” quando expressam incerteza real. Se a atribuição não estiver identificada, sinalize a lacuna em vez de assumir a afirmação como própria.
+
+**Evitar em PT-BR:**
+- "Pode-se argumentar que..." / "É possível que..."
+- "Em determinados contextos..." / "Potencialmente..."
+- "Alguns especialistas sugerem..." / "De certa forma..."
+
+---
+
+### 5. Conclusões Genéricas Positivas
+
+**Palavras/expressões gatilho:** "O futuro é promissor", "Tempos empolgantes", "As possibilidades são infinitas", "O potencial é ilimitado", "Estamos apenas no começo", "O melhor ainda está por vir"
+
+**Problema:** Encerramento vazio que repete otimismo sem desenvolver o argumento. A saída pode terminar quando o conteúdo termina; não precisa acrescentar posição, provocação ou previsão.
+
+**Antes (IA):**
+> O futuro da inteligência artificial no marketing digital é promissor. Estamos vivendo tempos empolgantes, e as possibilidades são verdadeiramente infinitas para profissionais que souberem se adaptar a essa nova realidade.
+
+**Depois (humano):**
+> A inteligência artificial pode ampliar as possibilidades no marketing digital para profissionais que se adaptarem. O texto vê esse futuro com otimismo.
+
+**Evitar em PT-BR:**
+- "O futuro é promissor" / "Tempos empolgantes nos aguardam"
+- "As possibilidades são infinitas" / "O potencial é ilimitado"
+- "Estamos apenas no começo dessa jornada"
+
+---
+
+### 6. Frases de Enchimento
+
+**Palavras/expressões gatilho:** "É importante destacar que", "Vale ressaltar que", "Cabe mencionar que", "Convém observar que", "Não se pode ignorar o fato de que", "É fundamental compreender que"
+
+**Problema:** Adicionam zero informação. São muletas usadas antes de chegar ao ponto. A correção remove a chamada de atenção e preserva a proposição, sem acrescentar justificativa, exemplo ou grau de certeza.
+
+**Antes (IA):**
+> É importante destacar que o uso de TypeScript em projetos React tem crescido significativamente. Vale ressaltar que essa tendência reflete a busca por maior segurança de tipos. Cabe mencionar que empresas como Vercel e Stripe já adotaram TypeScript como padrão.
+
+**Depois (humano):**
+> O uso de TypeScript em projetos React tem crescido significativamente, e essa tendência reflete a busca por mais segurança de tipos. Vercel e Stripe já adotaram TypeScript como padrão.
+
+**Evitar em PT-BR:**
+- "É importante destacar que" / "Vale ressaltar que"
+- "Cabe mencionar que" / "Convém observar que"
+- "Não se pode ignorar o fato de que" / "É fundamental compreender que"
+
+---
+
+### 7. Falso suspense (“Eis a questão”)
+
+**Palavras/expressões gatilho:** "Eis a questão:", "O ponto central é:", "Mas aqui está o detalhe:", "A grande sacada é:", "O plot twist é:", "E aqui mora o perigo:"
+
+**Problema:** Cria falso suspense antes de um ponto banal. Promete revelação dramática e entrega obviedade. Humanos não anunciam que vão dizer algo interessante — simplesmente dizem.
+
+**Antes (IA):**
+> Muitas startups investem em growth hacking sem ter product-market fit. Elas contratam profissionais de growth, gastam com anúncios e otimizam funis. Mas eis a questão: sem um produto que as pessoas realmente querem, nenhuma tática de crescimento vai funcionar.
+
+**Depois (humano):**
+> Muitas startups investem em growth hacking antes de ter product-market fit: contratam profissionais de growth, gastam com anúncios e otimizam funis. Sem um produto que as pessoas realmente queiram, nenhuma dessas táticas vai funcionar.
+
+**Evitar em PT-BR:**
+- "Eis a questão:" / "Eis o ponto:"
+- "Mas aqui está o detalhe:" / "A grande sacada é:"
+- "E aqui mora o perigo:" / "O plot twist é:"
+
+---
+
+### 8. Vulnerabilidade Falsa
+
+**Palavras/expressões gatilho:** "Sendo honesto aqui...", "Confesso que...", "Vou ser vulnerável:", "Não vou mentir:", "Se eu for sincero...", "Admito que..."
+
+**Problema:** Autoconsciência performática que anuncia a vulnerabilidade antes de apresentar o conteúdo. Remover esse ritual não autoriza tornar o relato mais dramático nem inventar episódio, consequência ou aprendizado.
+
+**Antes (IA):**
+> Confesso que, como desenvolvedor, nem sempre segui boas práticas. Sendo honesto aqui: houve momentos em que priorizei velocidade sobre qualidade. E sim, admito que isso me ensinou lições valiosas sobre a importância do código limpo.
+
+**Depois (humano):**
+> Como desenvolvedor, nem sempre segui boas práticas: houve momentos em que priorizei velocidade sobre qualidade. Isso me ensinou a importância do código limpo.
+
+**Variação por perfil:** mantenha a primeira pessoa apenas porque ela existe no original. Em perfil formal, “Em alguns momentos, priorizei...” é suficiente; em perfil informal, a oralidade pode aumentar, mas os acontecimentos não.
+
+**Evitar em PT-BR:**
+- "Confesso que..." / "Sendo honesto aqui..."
+- "Vou ser vulnerável:" / "Não vou mentir:"
+- "Admito que isso me ensinou lições valiosas"
+
+---
+
+### 9. "A Verdade É Simples"
+
+**Palavras/expressões gatilho:** "A verdade é simples:", "A realidade é mais simples do que parece", "No fundo, tudo se resume a...", "A resposta é surpreendentemente direta:", "Na prática, é menos complicado do que parece"
+
+**Problema:** Declara obviedade sem provar. Finge simplificar algo complexo, mas apenas repete a superfície. A correção expõe diretamente a proposição já presente; não cria demonstração, recomendação ou opinião para torná-la mais convincente.
+
+**Antes (IA):**
+> Muitos fundadores se perdem em métodos de priorização complexos, matrizes RICE e metodologias ágeis elaboradas. Mas a verdade é simples: o que importa é conversar com seus usuários e construir o que eles precisam.
+
+**Depois (humano):**
+> Muitos fundadores se perdem em métodos de priorização, matrizes RICE e metodologias ágeis. O ponto defendido é conversar com os usuários e construir o que eles precisam.
+
+**Evitar em PT-BR:**
+- "A verdade é simples:" / "A realidade é mais simples do que parece"
+- "No fundo, tudo se resume a..." / "A resposta é surpreendentemente direta:"
+- "É menos complicado do que você imagina"
+
+---
+
+### 10. Inflação grandiosa de importância
+
+**Palavras/expressões gatilho:** "Isso vai redefinir fundamentalmente...", "Uma mudança de paradigma", "Revolucionário", "Transformar completamente", "O jogo mudou para sempre", "Nunca mais será o mesmo"
+
+**Problema:** Tudo recebe importância máxima por meio de expressões dramáticas redundantes. A correção simplifica a formulação sem enfraquecer a tese, trocar previsão por dúvida ou inserir contraponto que o autor não apresentou.
+
+**Antes (IA):**
+> O surgimento de agentes de IA autônomos representa uma mudança de paradigma que vai redefinir fundamentalmente a forma como desenvolvemos software. Estamos testemunhando uma revolução que transformará completamente a indústria de tecnologia como a conhecemos.
+
+**Depois (humano):**
+> Agentes autônomos de inteligência artificial vão mudar profundamente o desenvolvimento de software e a indústria de tecnologia.
+
+**Evitar em PT-BR:**
+- "Mudança de paradigma" / "Redefinir fundamentalmente"
+- "Revolução" / "Transformar completamente"
+- "O jogo mudou para sempre" / "Nunca mais será o mesmo"
+
+---
+
+### 11. Anúncio de explicação (“Vamos analisar”)
+
+**Palavras/expressões gatilho:** "Vamos analisar:", "Vamos destrinchar:", "Vamos entender passo a passo:", "Vamos explorar cada aspecto:", "Vamos mergulhar nesse assunto:", "Quebrando em partes:"
+
+**Problema:** Voz pedagógica condescendente. Pressupõe que o leitor precisa ser guiado quando o contexto pede exposição direta. Remova o anúncio e comece pelo conteúdo que já existe; se o “Antes” não trouxer a explicação, não a complete.
+
+**Antes (IA):**
+> Vamos analisar os três pilares de uma estratégia de conteúdo eficaz. Primeiro, vamos explorar a pesquisa de palavras-chave. Em seguida, vamos mergulhar na criação de grupos temáticos. Por fim, vamos entender como medir resultados.
+
+**Depois (humano):**
+> Uma estratégia de conteúdo eficaz reúne três pilares: pesquisa de palavras-chave, criação de grupos temáticos e medição de resultados.
+
+**Evitar em PT-BR:**
+- "Vamos analisar:" / "Vamos destrinchar:"
+- "Vamos explorar cada aspecto:" / "Vamos mergulhar nesse assunto:"
+- "Vamos entender passo a passo:" / "Quebrando em partes:"
+
+---
+
+### 12. Rótulos Conceituais Inventados
+
+**Palavras/expressões gatilho:** "o paradoxo da [X]", "a armadilha da [X]", "o deficit de [X]", "a falácia do [X]", "o efeito [X]", "a síndrome de [X]"
+
+**Problema:** Inventar termos compostos e apresentá-los como conceitos estabelecidos. IA cria rótulos pseudo-acadêmicos para parecer profunda ("o paradoxo da supervisão", "a armadilha da aceleração"). Humanos nomeiam fenômenos com cautela — ou reconhecem que estão cunhando um termo.
+
+**Antes (IA):**
+> Muitas empresas caem no que podemos chamar de "paradoxo da automação" — quanto mais automatizam, mais dependem de intervenção humana para lidar com os casos excepcionais. Esse "déficit de supervisão escalável" é o verdadeiro gargalo da transformação digital.
+
+**Depois (humano):**
+> Quanto mais essas empresas automatizam, mais dependem de intervenção humana nos casos excepcionais. O texto apresenta essa dificuldade de supervisão como gargalo da transformação digital.
+
+**Evitar em PT-BR:**
+- "O paradoxo da [X]" / "A armadilha da [X]"
+- "O deficit de [X]" / "A falácia do [X]"
+- "O que podemos chamar de..." (seguido de termo inventado)
+
+---
+
+### 13. "Imagine um Mundo Onde..."
+
+**Palavras/expressões gatilho:** "Imagine um mundo onde...", "Imagine se...", "Pense num cenário em que...", "E se eu te dissesse que...", "Visualize um futuro onde...", "Feche os olhos e imagine..."
+
+**Problema:** Convite futurista clichê que serve de abertura genérica. A correção deve expor a hipótese diretamente, sem adicionar produtos atuais, dados ou limitações que não estejam no texto de origem.
+
+**Antes (IA):**
+> Imagine um mundo onde todo desenvolvedor tem um assistente de IA que entende perfeitamente o contexto da sua base de código. Imagine se cada pull request fosse revisada instantaneamente com retorno preciso e acionável. Esse mundo não está tão distante quanto você pensa.
+
+**Depois (humano):**
+> Um assistente de inteligência artificial que entenda todo o contexto do código e revise cada pull request imediatamente, com retorno preciso, ainda é uma possibilidade futura. O texto sustenta que ela pode estar próxima.
+
+**Evitar em PT-BR:**
+- "Imagine um mundo onde..." / "Imagine se..."
+- "E se eu te dissesse que..." / "Visualize um futuro onde..."
+- "Esse mundo não está tão distante" / "O futuro já chegou"
--- a/.github/skills/loop-architect/LICENSE
+++ b/.github/skills/loop-architect/LICENSE
@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Fabricio Telles (ft.ia.br)
+
+Based on Looper (https://github.com/ksimback/looper)
+Copyright (c) 2026 Kevin Simback
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/.github/skills/loop-architect/SKILL.md
+++ b/.github/skills/loop-architect/SKILL.md
@@ -0,0 +1,233 @@
+---
+name: loop-architect
+description: >
+  Design well-structured agent loops with best-practice coaching and cross-model
+  review gates before you run them. Use when the user wants to design, build, or
+  set up an agent loop, iterative agent workflow, self-review loop, LLM-as-judge
+  loop, multi-model council, reviewer/judge gate, or goal-driven looping process.
+  Guides goal refinement, typed verification criteria, reviewer/judge selection,
+  privacy boundaries, termination guards, and observability, then emits a
+  RUN_IN_SESSION.md handoff prompt plus portable loop.yaml, loop.resolved.json,
+  LOOP.md, and run-loop.py.
+metadata:
+  author: https://ft.ia.br
+  version: "1.0"
+  date: 2026-06-25
+  repository: https://github.com/fabricioctelles/skills
+  license: MIT
+  original_project: https://github.com/ksimback/looper
+  original_author: Kevin Simback (@ksimback)
+  attribution: >
+    Reinterpretation of Looper (MIT License) by Kevin Simback, adapted for
+    Kiro CLI with native /goal, subagent, and review loop integration.
+  category: code-scaffolding-and-templates
+---
+
+# Loop Architect
+
+A loop design coach for Kiro CLI. Interviews you, critiques your design against
+built-in best-practice rubrics, wires in cross-model reviewers or judges, shows
+the loop as an ASCII flow preview, and writes portable artifacts you can run
+immediately with `/goal` or later with the Python runner.
+
+> Based on [Looper](https://github.com/ksimback/looper) by Kevin Simback, MIT License.
+> Adapted for Kiro CLI by ft.ia.br.
+
+## Why This Exists
+
+Kiro CLI ships `/goal` (autonomous loop with self-verification) and subagents
+(parallel pipelines with review loops). These **execute** a loop. Loop Architect
+helps you **design** one worth executing — with a coached goal, typed
+verification, a cross-model gate, and explicit termination guards.
+
+| | `/goal` | Subagent pipeline | **Loop Architect** |
+|---|---|---|---|
+| Layer | execution | execution | **design (pre-flight)** |
+| Coaches your goal | no | no | **yes** |
+| Typed verification | no | no | **yes (programmatic / judge / human)** |
+| Reviewer model | same model | configurable | **different model, by default** |
+| Portable artifact | no | no | **loop.yaml + resolved spec** |
+| Runs the loop | **yes** | **yes** | **yes, via handoff** |
+
+## Workflow
+
+1. Resolve the target path from the user. Default: `./loop-architect-output`. If
+   the target contains an existing `loop.yaml`, treat as edit/resume.
+
+2. Load the relevant rubric only when entering that stage:
+   - Goal stage: `references/goal-rubric.md`
+   - Verification stage: `references/verification-rubric.md`
+   - Council stage: `references/council-rubric.md`
+   - Control stage: `references/control-rubric.md`
+   - Model detection: `references/model-detection.md`
+
+3. Interview in seven stages: goal, verification, host model, council,
+   gates/control, confirmation flow preview, emit/run option. In the control
+   stage, cover execution boundary, isolation, no-progress signals, state, and
+   run logging.
+
+4. Critique each stage before accepting it. Prefer concrete alternatives over
+   vague warnings. Push weak goals toward outcome, scope, context, and done
+   state. Push weak verification toward programmatic checks first, then judge
+   rubrics, then human signoff.
+
+5. Keep reviewer and judge roles distinct. A reviewer writes notes. A judge
+   returns a structured verdict. `revise_until_clean` must name a judge member
+   or `human` as `verdict_source`.
+
+6. Require multiple termination guards: `max_iterations`, a revision cap on
+   each gate, a no-progress stop, and either a budget cap or an explicit human
+   stop point.
+
+7. Before any cross-vendor council member is selected, state what context will
+   leave the user's machine, which CLI receives it, which redaction globs apply,
+   and that both execution paths require first-send consent.
+
+8. Show an ASCII flow preview and ask for confirmation before final emission.
+
+9. Emit these files into the target:
+   - `loop.yaml`
+   - `loop.resolved.json`
+   - `LOOP.md`
+   - `RUN_IN_SESSION.md`
+   - `run-loop.py`
+   - `loop-workspace/`
+   - `README.md`
+
+10. After writing `loop.yaml`, compile it:
+    ```bash
+    python3 ~/.kiro/skills/loop-architect/scripts/looper.py compile \
+      <target>/loop.yaml \
+      --out <target>/loop.resolved.json \
+      --render <target>/LOOP.md \
+      --session-prompt <target>/RUN_IN_SESSION.md
+    ```
+
+11. Ask whether the user wants to run the loop now. If yes:
+    - **Easy path**: Follow `RUN_IN_SESSION.md` directly, or suggest a `/goal`
+      one-liner derived from the `definition_of_done`.
+    - **Subagent path**: If the council uses a model with `review_loop`
+      capability, offer to execute via a subagent pipeline with native review
+      loops.
+    - **External path**: Explain that `run-loop.py` is available for running
+      later or outside the session.
+
+## Execution Paths
+
+### Path 1: `/goal` (simplest)
+
+When the loop is straightforward and the host is the current Kiro session:
+
+```
+/goal --max 12 <definition_of_done from loop.yaml>
+```
+
+This uses Kiro's native self-verification loop. No cross-model review, but
+fast and zero-config.
+
+### Path 2: Subagent review pipeline (recommended)
+
+When a cross-model reviewer is needed and the host has `subagent` capability:
+
+```
+Implement the loop following RUN_IN_SESSION.md. Use a subagent as reviewer
+with trigger "NEEDS_CHANGES" and max 3 iterations per gate.
+```
+
+This leverages Kiro's native `loop_to` mechanism for the plan and delivery
+gates.
+
+### Path 3: External Python runner (advanced)
+
+```bash
+python3 ./loop-architect-output/run-loop.py
+```
+
+For scheduled runs, CI integration, or when you need strict budget enforcement.
+
+## File Rules
+
+- Write argv arrays, never shell command strings, for all model invocations.
+- Do not write API keys, tokens, or credentials into any emitted file.
+- Default redaction globs: `.env`, `.env.*`, `secrets/**`, `**/*.key`.
+- Keep `loop.yaml` human-readable and commented.
+- Keep `RUN_IN_SESSION.md` as the default/easy execution handoff.
+- Copy `templates/run-loop.py` exactly unless the user asks to edit it.
+
+## Helper Scripts
+
+Detect model CLIs:
+```bash
+python3 ~/.kiro/skills/loop-architect/scripts/looper.py detect-models --write
+```
+
+Register a custom CLI:
+```bash
+python3 ~/.kiro/skills/loop-architect/scripts/looper.py register-model <id> \
+  --invoke kiro-cli chat --trust-all-tools -p --authed
+```
+
+Compile and render:
+```bash
+python3 ~/.kiro/skills/loop-architect/scripts/looper.py compile <target>/loop.yaml \
+  --out <target>/loop.resolved.json \
+  --render <target>/LOOP.md \
+  --session-prompt <target>/RUN_IN_SESSION.md
+```
+
+## Confirmation Flow Preview
+
+```text
+--------------------------------+
+| 1. Goal + context              |
+|    read sources                |
+--------------------------------+
+              |
+              v
+--------------------------------+
+| 2. Draft plan.md               |
+|    state -> state.json         |
+--------------------------------+
+              |
+              v
+--------------------------------+
+| 3. Plan gate                   |
+|    verdict: reviewer-1         |
+--------------------------------+
+  | needs work -> revise <= 3 -> step 2
+  | pass
+              v
+--------------------------------+
+| 4. Write delivery-N.md         |
+|    log -> run-log.md           |
+--------------------------------+
+              |
+              v
+--------------------------------+
+| 5. Delivery gate               |
+|    verdict: reviewer-1         |
+--------------------------------+
+  | needs work -> revise <= 3 -> step 4
+  | pass
+              v
+--------------------------------+
+| 6. Final output                |
+|    all gates clean             |
+--------------------------------+
+
+Stops: pass gates | max 12 iterations | no progress x2 | budget 30m, $5.0
+```
+
+## Emit Checklist
+
+- The goal has a clear outcome, scope boundary, context sources, and done state.
+- Verification criteria are typed as `programmatic`, `judge`, or `human`.
+- At least one criterion is not purely vibe-based.
+- Each `revise_until_clean` gate has a valid `verdict_source`.
+- Every external invocation is an argv array with a timeout.
+- Cross-vendor egress is scoped, redacted, and consent-gated.
+- `loop_control` has iteration, revision, no-progress, and budget caps.
+- Execution boundary and isolation are explicit.
+- Observability names a `run-log.md` and `state.json` path.
+- Compiled artifacts (`loop.resolved.json`, `LOOP.md`, `RUN_IN_SESSION.md`)
+  pass validation before handoff.
--- a/.github/skills/loop-architect/examples/ai-workflow-mapping/LOOP.md
+++ b/.github/skills/loop-architect/examples/ai-workflow-mapping/LOOP.md
@@ -0,0 +1,86 @@
+# ai-workflow-mapping
+
+Map a customer's manual workflow into an agent-ready process.
+
+## Goal
+
+Produce an agent workflow map that converts the process notes into a stepwise design with tool calls, model responsibilities, and human checkpoints.
+
+## Definition of Done
+
+A LOOP.md-style workflow map exists, every step has an owner, input, output, and checkpoint decision where needed, and there are no TBDs.
+
+## Verification
+
+- `required-sections` (programmatic)
+- `covers-goal` (judge)
+
+## Council
+
+- `reviewer-1`: judge via claude (default)
+
+## Gates
+
+- Plan gate: revise_until_clean
+- Delivery gate: revise_until_clean
+
+## Loop Control
+
+- Max iterations: 12
+- Budget: `{"tokens": 2000000, "usd": 5.0, "wall_clock_min": 30}`
+- No-progress: `{"action": "stop", "max_stalled_iterations": 2, "signals": ["same blocking issue repeats", "delivery artifact has no material change", "verifier output is unchanged"]}`
+
+## Execution Boundary
+
+- Mode: `in_session`
+- Isolation: `current_workspace`
+- Side effects: `{"duplicate_action_check": true, "requires_approval": true}`
+
+## Observability
+
+- State file: `state.json`
+- Run log: `run-log.md`
+- Checkpoint granularity: `gate`
+
+## Flow Preview
+
+```text
+--------------------------------+
+| 1. Goal + context              |
+| read sources                   |
+--------------------------------+
+               |
+               v
+--------------------------------+
+| 2. Draft plan.md               |
+| state -> state.json            |
+--------------------------------+
+               |
+               v
+--------------------------------+
+| 3. Plan gate                   |
+| verdict: reviewer-1            |
+--------------------------------+
+               | needs work -> revise <= 3 -> step 2
+               | pass
+               v
+--------------------------------+
+| 4. Write delivery-N.md         |
+| log -> run-log.md              |
+--------------------------------+
+               |
+               v
+--------------------------------+
+| 5. Delivery gate               |
+| verdict: reviewer-1            |
+--------------------------------+
+               | needs work -> revise <= 3 -> step 4
+               | pass
+               v
+--------------------------------+
+| 6. Final output                |
+| all gates clean                |
+--------------------------------+
+
+Stops: pass gates | max 12 iterations | no progress x2 | budget 30m, $5.0, 2000000 tokens
+```
--- a/.github/skills/loop-architect/examples/ai-workflow-mapping/README.md
+++ b/.github/skills/loop-architect/examples/ai-workflow-mapping/README.md
@@ -0,0 +1,19 @@
+# AI Workflow Mapping Example
+
+This example shows the Looper artifact shape for mapping customer process notes
+into an agent-ready workflow.
+
+Compile after editing:
+
+```bash
+python ../../scripts/looper.py compile loop.yaml --out loop.resolved.json --render LOOP.md --session-prompt RUN_IN_SESSION.md
+```
+
+The easy path is to ask the current LLM session to follow `RUN_IN_SESSION.md`.
+
+Use the Python runner only when you want to run the loop outside the LLM
+session, after reviewing model invocations and privacy egress:
+
+```bash
+python run-loop.py
+```
--- a/.github/skills/loop-architect/examples/ai-workflow-mapping/RUN_IN_SESSION.md
+++ b/.github/skills/loop-architect/examples/ai-workflow-mapping/RUN_IN_SESSION.md
@@ -0,0 +1,108 @@
+# Run `ai-workflow-mapping` In This Session
+
+Use this prompt when the user wants to run the Looper-designed loop in the current LLM session.
+This is the default/easy execution path. The Python runner is the advanced path for running later or outside the session.
+
+## Operator Instructions
+
+You are executing a Looper-designed loop in this current session.
+Follow the resolved spec below, write handoff files into the workspace, and enforce the caps manually.
+Do not use `run-loop.py` unless the user explicitly asks for the advanced external runner.
+
+1. Create the workspace directory if it does not exist.
+2. Read the context sources before drafting the plan.
+3. Draft `plan.md` in the workspace.
+4. Run the plan gate. Apply programmatic checks when available. For judge criteria, use the configured judge only after consent for any non-local egress; otherwise ask the user to approve a human/current-session substitute.
+5. Revise until the gate passes or `max_revisions` is reached.
+6. Produce `delivery-N.md` in the workspace.
+7. Run the delivery gate after each delivery.
+8. Stop when all delivery criteria pass, a cap is reached, or the user stops the loop.
+9. Keep `state.json` current with status, iteration, last gate, consent, and blockers.
+10. Append a compact entry to `run-log.md` after every context read, model call, check, gate verdict, revision, blocker, and stop decision.
+11. Compare each blocker against the previous blocker. If the same blocker repeats for the configured no-progress window, stop or ask for the configured human checkpoint instead of revising again.
+12. Treat token and USD budgets as operator limits in this session: if exact accounting is unavailable, stop and ask before continuing when the loop appears likely to exceed them.
+
+## Files
+
+- Source spec: `loop.yaml`
+- Human summary: `LOOP.md`
+- Resolved spec: `loop.resolved.json`
+- Workspace: `./loop-workspace`
+- State file: `state.json`
+- Run log: `run-log.md`
+
+## Goal
+
+Produce an agent workflow map that converts the process notes into a stepwise design with tool calls, model responsibilities, and human checkpoints.
+
+## Definition Of Done
+
+A LOOP.md-style workflow map exists, every step has an owner, input, output, and checkpoint decision where needed, and there are no TBDs.
+
+## Context Sources
+
+- Read file `./inputs/process-notes.md`
+
+## Verification Criteria
+
+- `required-sections` programmatic: run `["python", "scripts/check-loop-doc.py", "loop-workspace/delivery-1.md"]` and expect `exit_zero`
+- `covers-goal` judge rubric: Every part of the goal statement is addressed. Each workflow step has an owner, required input, output artifact, and human checkpoint where business judgment is needed. No step depends on information the loop never gathers. There are no unresolved TBDs.
+
+
+## Council
+
+- `reviewer-1` judge via `["claude", "-p"]` (non-local; timeout 600s)
+
+## Gates
+
+### plan_gate
+
+- When: `after_plan`
+- Policy: `revise_until_clean`
+- Verdict source: `reviewer-1`
+- Criteria: `covers-goal`
+- Max revisions: `3`
+
+### delivery_gate
+
+- When: `after_each_delivery`
+- Policy: `revise_until_clean`
+- Verdict source: `reviewer-1`
+- Criteria: `required-sections, covers-goal`
+- Max revisions: `3`
+
+## Loop Control
+
+- Max iterations: `12`
+- Budget: `{"tokens": 2000000, "usd": 5.0, "wall_clock_min": 30}`
+- No-progress: `{"action": "stop", "max_stalled_iterations": 2, "signals": ["same blocking issue repeats", "delivery artifact has no material change", "verifier output is unchanged"]}`
+- Human checkpoints: `none`
+- Stop conditions:
+  - all deliveries pass their gate clean
+  - max_iterations reached
+  - same blocker repeats for 2 iterations
+  - any budget cap exceeded
+
+## Execution Boundary
+
+- Mode: `in_session`
+- Isolation: `current_workspace`
+- Side effects: `{"duplicate_action_check": true, "requires_approval": true}`
+
+If the loop needs scheduled runs, child-agent lifecycle management, concurrency control, or restart-safe step retries, stop and tell the user this Looper spec should be handed to a durable orchestrator.
+
+## Observability
+
+- State file: `state.json`
+- Run log: `run-log.md`
+- Checkpoint granularity: `gate`
+
+Use `state.json` for the latest resumable status and `run-log.md` for the append-only history of what happened.
+
+## Privacy
+
+- Before sending `plan, deliveries` to `reviewer-1`, confirm consent and apply redactions `.env, .env.*, secrets/**, **/*.key`.
+
+## Start Now
+
+If the user asked to run now, begin at step 1 under Operator Instructions and keep going until a stop condition is reached.
--- a/.github/skills/loop-architect/examples/ai-workflow-mapping/inputs/process-notes.md
+++ b/.github/skills/loop-architect/examples/ai-workflow-mapping/inputs/process-notes.md
@@ -0,0 +1,14 @@
+# Process Notes
+
+The team currently turns customer process interviews into workflow maps by
+reading notes, identifying handoffs, drafting a diagram, and asking a lead
+consultant to check whether each step has an owner.
+
+The loop should produce a map with:
+
+- each process step
+- owner type: tool, model, or human
+- required input for the step
+- output artifact for the step
+- explicit human checkpoint when business judgment is needed
+
--- a/.github/skills/loop-architect/examples/ai-workflow-mapping/loop.resolved.json
+++ b/.github/skills/loop-architect/examples/ai-workflow-mapping/loop.resolved.json
@@ -0,0 +1,194 @@
+{
+  "$schema": "https://github.com/ksimback/looper/schema/loop.resolved.v1.json",
+  "compiled_at": "2026-06-19T07:09:26+00:00",
+  "council": [
+    {
+      "cli": "claude",
+      "id": "reviewer-1",
+      "invoke": [
+        "claude",
+        "-p"
+      ],
+      "local": false,
+      "model": "default",
+      "role": "judge",
+      "scope": [
+        "plan",
+        "delivery"
+      ],
+      "timeout_sec": 600
+    }
+  ],
+  "council_by_id": {
+    "reviewer-1": {
+      "cli": "claude",
+      "id": "reviewer-1",
+      "invoke": [
+        "claude",
+        "-p"
+      ],
+      "local": false,
+      "model": "default",
+      "role": "judge",
+      "scope": [
+        "plan",
+        "delivery"
+      ],
+      "timeout_sec": 600
+    }
+  },
+  "criteria_by_id": {
+    "covers-goal": {
+      "id": "covers-goal",
+      "rubric": "Every part of the goal statement is addressed. Each workflow step has an owner, required input, output artifact, and human checkpoint where business judgment is needed. No step depends on information the loop never gathers. There are no unresolved TBDs.\n",
+      "type": "judge"
+    },
+    "required-sections": {
+      "check": [
+        "python",
+        "scripts/check-loop-doc.py",
+        "loop-workspace/delivery-1.md"
+      ],
+      "expect": "exit_zero",
+      "id": "required-sections",
+      "type": "programmatic"
+    }
+  },
+  "execution": {
+    "isolation": "current_workspace",
+    "mode": "in_session",
+    "side_effects": {
+      "duplicate_action_check": true,
+      "requires_approval": true
+    }
+  },
+  "gates": {
+    "delivery_gate": {
+      "criteria": [
+        "required-sections",
+        "covers-goal"
+      ],
+      "max_revisions": 3,
+      "members": [
+        "reviewer-1"
+      ],
+      "verdict_policy": "revise_until_clean",
+      "verdict_source": "reviewer-1",
+      "when": "after_each_delivery"
+    },
+    "plan_gate": {
+      "criteria": [
+        "covers-goal"
+      ],
+      "max_revisions": 3,
+      "members": [
+        "reviewer-1"
+      ],
+      "verdict_policy": "revise_until_clean",
+      "verdict_source": "reviewer-1",
+      "when": "after_plan"
+    }
+  },
+  "goal": {
+    "context_sources": [
+      {
+        "file": "./inputs/process-notes.md"
+      }
+    ],
+    "definition_of_done": "A LOOP.md-style workflow map exists, every step has an owner, input, output, and checkpoint decision where needed, and there are no TBDs.\n",
+    "statement": "Produce an agent workflow map that converts the process notes into a stepwise design with tool calls, model responsibilities, and human checkpoints.\n",
+    "verification": [
+      {
+        "check": [
+          "python",
+          "scripts/check-loop-doc.py",
+          "loop-workspace/delivery-1.md"
+        ],
+        "expect": "exit_zero",
+        "id": "required-sections",
+        "type": "programmatic"
+      },
+      {
+        "id": "covers-goal",
+        "rubric": "Every part of the goal statement is addressed. Each workflow step has an owner, required input, output artifact, and human checkpoint where business judgment is needed. No step depends on information the loop never gathers. There are no unresolved TBDs.\n",
+        "type": "judge"
+      }
+    ]
+  },
+  "host": {
+    "cli": "codex",
+    "invoke": [
+      "codex",
+      "exec",
+      "--model",
+      "gpt-5"
+    ],
+    "model": "gpt-5",
+    "timeout_sec": 600
+  },
+  "loop_control": {
+    "budget": {
+      "tokens": 2000000,
+      "usd": 5.0,
+      "wall_clock_min": 30
+    },
+    "human_checkpoints": [],
+    "max_iterations": 12,
+    "no_progress": {
+      "action": "stop",
+      "max_stalled_iterations": 2,
+      "signals": [
+        "same blocking issue repeats",
+        "delivery artifact has no material change",
+        "verifier output is unchanged"
+      ]
+    },
+    "stop_conditions": [
+      "all deliveries pass their gate clean",
+      "max_iterations reached",
+      "same blocker repeats for 2 iterations",
+      "any budget cap exceeded"
+    ]
+  },
+  "meta": {
+    "author": "ksimback",
+    "created": "2026-06-18",
+    "description": "Map a customer's manual workflow into an agent-ready process.",
+    "name": "ai-workflow-mapping"
+  },
+  "observability": {
+    "checkpoint_granularity": "gate",
+    "run_log": "run-log.md",
+    "state_file": "state.json"
+  },
+  "privacy": {
+    "egress": [
+      {
+        "consent": "required",
+        "redact": [
+          ".env",
+          ".env.*",
+          "secrets/**",
+          "**/*.key"
+        ],
+        "sends": [
+          "plan",
+          "deliveries"
+        ],
+        "to": "reviewer-1"
+      }
+    ]
+  },
+  "source": "C:\\Users\\kevin\\looper\\examples\\ai-workflow-mapping\\loop.yaml",
+  "version": 1,
+  "workspace": {
+    "dir": "./loop-workspace",
+    "layout": [
+      "plan.md",
+      "delivery-{n}.md",
+      "review-{n}.md",
+      "state.json",
+      "run-log.md"
+    ]
+  }
+}
--- a/.github/skills/loop-architect/examples/ai-workflow-mapping/loop.yaml
+++ b/.github/skills/loop-architect/examples/ai-workflow-mapping/loop.yaml
@@ -0,0 +1,104 @@
+version: 1
+meta:
+  name: ai-workflow-mapping
+  description: Map a customer's manual workflow into an agent-ready process.
+  author: ksimback
+  created: 2026-06-18
+
+goal:
+  statement: >
+    Produce an agent workflow map that converts the process notes into a
+    stepwise design with tool calls, model responsibilities, and human
+    checkpoints.
+  context_sources:
+    - file: ./inputs/process-notes.md
+  definition_of_done: >
+    A LOOP.md-style workflow map exists, every step has an owner, input,
+    output, and checkpoint decision where needed, and there are no TBDs.
+  verification:
+    - id: required-sections
+      type: programmatic
+      check: ["python", "scripts/check-loop-doc.py", "loop-workspace/delivery-1.md"]
+      expect: exit_zero
+    - id: covers-goal
+      type: judge
+      rubric: >
+        Every part of the goal statement is addressed. Each workflow step has
+        an owner, required input, output artifact, and human checkpoint where
+        business judgment is needed. No step depends on information the loop
+        never gathers. There are no unresolved TBDs.
+
+host:
+  cli: codex
+  model: gpt-5
+  invoke: ["codex", "exec", "--model", "gpt-5"]
+  timeout_sec: 600
+
+council:
+  - id: reviewer-1
+    role: judge
+    cli: claude
+    model: default
+    invoke: ["claude", "-p"]
+    timeout_sec: 600
+    scope: [plan, delivery]
+    local: false
+
+gates:
+  plan_gate:
+    when: after_plan
+    members: [reviewer-1]
+    verdict_policy: revise_until_clean
+    verdict_source: reviewer-1
+    criteria: [covers-goal]
+    max_revisions: 3
+  delivery_gate:
+    when: after_each_delivery
+    members: [reviewer-1]
+    verdict_policy: revise_until_clean
+    verdict_source: reviewer-1
+    criteria: [required-sections, covers-goal]
+    max_revisions: 3
+
+loop_control:
+  max_iterations: 12
+  budget:
+    usd: 5.0
+    tokens: 2000000
+    wall_clock_min: 30
+  no_progress:
+    max_stalled_iterations: 2
+    signals:
+      - same blocking issue repeats
+      - delivery artifact has no material change
+      - verifier output is unchanged
+    action: stop
+  human_checkpoints: []
+  stop_conditions:
+    - all deliveries pass their gate clean
+    - max_iterations reached
+    - same blocker repeats for 2 iterations
+    - any budget cap exceeded
+
+execution:
+  mode: in_session
+  isolation: current_workspace
+  side_effects:
+    requires_approval: true
+    duplicate_action_check: true
+
+observability:
+  state_file: state.json
+  run_log: run-log.md
+  checkpoint_granularity: gate
+
+privacy:
+  egress:
+    - to: reviewer-1
+      sends: [plan, deliveries]
+      redact: [".env", ".env.*", "secrets/**", "**/*.key"]
+      consent: required
+
+workspace:
+  dir: ./loop-workspace
+  layout: [plan.md, "delivery-{n}.md", "review-{n}.md", state.json, run-log.md]
--- a/.github/skills/loop-architect/examples/ai-workflow-mapping/run-loop.py
+++ b/.github/skills/loop-architect/examples/ai-workflow-mapping/run-loop.py
@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Example runner wrapper that uses the root template."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import runpy
+
+
+ROOT = Path(__file__).resolve().parents[2]
+runpy.run_path(str(ROOT / "templates" / "run-loop.py"), run_name="__main__")
+
--- a/.github/skills/loop-architect/examples/ai-workflow-mapping/scripts/check-loop-doc.py
+++ b/.github/skills/loop-architect/examples/ai-workflow-mapping/scripts/check-loop-doc.py
@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""Check that a generated workflow map has the expected sections."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+
+REQUIRED = ["Owner", "Input", "Output", "Checkpoint"]
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("usage: check-loop-doc.py <delivery-path>", file=sys.stderr)
+        return 2
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"missing file: {path}", file=sys.stderr)
+        return 1
+    text = path.read_text(encoding="utf-8")
+    missing = [item for item in REQUIRED if item not in text]
+    if missing:
+        print(f"missing required text: {', '.join(missing)}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
--- a/.github/skills/loop-architect/references/control-rubric.md
+++ b/.github/skills/loop-architect/references/control-rubric.md
@@ -0,0 +1,60 @@
+# Control Rubric
+
+Use this when setting gates, iteration caps, budgets, and stop conditions.
+
+## Required Guards
+
+- `loop_control.max_iterations`
+- `gates.*.max_revisions`
+- `loop_control.no_progress.max_stalled_iterations`
+- At least one wall-clock, token, or USD budget cap when external models run.
+  The generated Python runner enforces wall-clock caps directly; token and USD
+  caps are advisory unless the chosen model CLI exposes accounting that the
+  loop operator wires in separately.
+- A stop condition that describes success.
+- A stop condition that describes no-progress or repeated failure.
+
+## Good Gate Design
+
+- Plan gate runs before delivery work.
+- Delivery gate runs after each delivery artifact.
+- Programmatic checks run before judge calls when possible.
+- Human checkpoints sit at high-leverage points, usually after plan approval or
+  before external egress.
+- Resume happens at gate boundaries unless the user explicitly needs finer
+  granularity.
+
+## Execution Boundary
+
+- Name where the loop is allowed to modify files: current workspace, branch,
+  worktree, throwaway directory, or an external orchestrator workspace.
+- Identify actions with side effects: pushes, PR comments, Slack messages,
+  deploys, file deletes, database writes, or vendor sends.
+- Decide whether side-effecting actions require approval, idempotency notes, or
+  duplicate-action checks.
+- If the loop may run on a schedule or in parallel, call out the need for an
+  external orchestrator with concurrency controls.
+
+## Failure Behavior
+
+- Stop immediately when a hard cap is reached.
+- Write the latest state to `loop-workspace/state.json`.
+- Append each meaningful step, decision, check result, and blocker to
+  `loop-workspace/run-log.md`.
+- Preserve review notes even when the gate fails.
+- Stop or ask the human when the same blocker repeats for the configured
+  no-progress window.
+- Do not let the host keep revising forever.
+
+## Anti-Patterns
+
+- No maximum iteration count.
+- A judge gate with no judge.
+- A budget cap in prose but not in `loop_control`.
+- No no-progress detector.
+- A loop that can send duplicate external notifications or repeat destructive
+  actions after restart.
+- Scheduled or multi-agent work with no durable orchestrator or concurrency
+  story.
+- Human signoff required but no checkpoint.
+- Stop conditions that require subjective self-satisfaction.
--- a/.github/skills/loop-architect/references/council-rubric.md
+++ b/.github/skills/loop-architect/references/council-rubric.md
@@ -0,0 +1,43 @@
+# Council Rubric
+
+Use this when selecting reviewers and judges.
+
+## Roles
+
+`reviewer`
+: Gives notes only. It may improve quality, but it cannot declare a gate clean.
+
+`judge`
+: Gives a structured verdict. It can be used as a gate `verdict_source`.
+
+## Selection Guidance
+
+- Prefer a different model family from the host for blind-spot coverage.
+- Prefer local models such as `ollama` when privacy matters more than judgment
+  quality.
+- Prefer a judge for gates that must block progress.
+- Prefer a reviewer for brainstorming, adversarial notes, or tone critique
+  where a deterministic pass/fail would be fake precision.
+- Keep council scope small: `plan`, `delivery`, or specific paths.
+
+## Gate Rule
+
+`verdict_policy: revise_until_clean` requires `verdict_source` to be either a
+judge member or `human`. A reviewer-only gate can use `fixed_passes`, but it
+cannot honestly claim clean.
+
+## Judge Rubric Tips
+
+- Name the artifact being judged.
+- Name the exact criteria IDs.
+- Ask for blocking issues, not general commentary.
+- Require the fenced JSON verdict first or last.
+- Keep the judge prompt short enough that the artifact, not the instruction
+  wrapper, dominates the context.
+
+## Privacy Notes
+
+Cross-vendor review can send project context to another CLI and vendor account.
+Always name the destination, scope what it receives, apply redaction globs, and
+require consent before the first send.
+
--- a/.github/skills/loop-architect/references/goal-rubric.md
+++ b/.github/skills/loop-architect/references/goal-rubric.md
@@ -0,0 +1,42 @@
+# Goal Rubric
+
+Use this when shaping the user's loop goal.
+
+## Good Goal Shape
+
+- Names the concrete outcome, not only the activity.
+- Defines the artifact or state that proves the loop finished.
+- Sets scope boundaries: included work, excluded work, and maximum depth.
+- Names context sources the host must gather instead of assumptions it may make.
+- Identifies the user, customer, system, or reviewer who will consume the result.
+
+## Critique Prompts
+
+- What would count as done if two competent agents disagreed?
+- Which terms are subjective and need a measurable proxy?
+- What context must be read before the host drafts a plan?
+- What is explicitly out of scope for this loop?
+- Can the goal be split into plan, delivery, and verification artifacts?
+
+## Anti-Patterns
+
+- "Improve the project" without a target artifact.
+- "Make it good" without criteria.
+- "Research X" without the decision the research supports.
+- Goals where success depends on information the loop never gathers.
+- Goals that require endless polishing with no stop condition.
+
+## Better Examples
+
+Weak: "Make our onboarding better."
+
+Better: "Produce a 5-step onboarding workflow map for new enterprise users,
+with each step assigned to a product surface, email, human owner, or missing
+capability, and with no unresolved TBDs."
+
+Weak: "Fix the flaky tests."
+
+Better: "Identify and patch the root cause of the checkout test flake, prove it
+with 20 local repeats or a CI rerun, and leave a short note explaining the
+failure mode and the verification evidence."
+
--- a/.github/skills/loop-architect/references/model-detection.md
+++ b/.github/skills/loop-architect/references/model-detection.md
@@ -0,0 +1,98 @@
+# Model Detection and Privacy Notes
+
+Loop-architect detection is intentionally dumb and transparent. It stores
+invocation metadata only, never credentials.
+
+## Registry
+
+Default registry path:
+
+```text
+~/.loop-architect/models.json
+```
+
+Registry entries should look like:
+
+```json
+{
+  "kiro": {
+    "cli": "kiro-cli",
+    "invoke": ["kiro-cli", "chat", "--trust-all-tools", "-p"],
+    "probe": ["kiro-cli", "--version"],
+    "available": true,
+    "authed": true,
+    "local": false,
+    "capabilities": {
+      "headless": true,
+      "goal": true,
+      "subagent": true,
+      "review_loop": true
+    }
+  },
+  "claude": {
+    "cli": "claude",
+    "invoke": ["claude", "-p"],
+    "probe": ["claude", "--version"],
+    "available": true,
+    "authed": true,
+    "local": false,
+    "capabilities": {
+      "headless": true,
+      "goal": true,
+      "subagent": false,
+      "review_loop": false
+    }
+  }
+}
+```
+
+## Capabilities
+
+`headless`
+: The CLI accepts a prompt via stdin/argument and returns output via stdout
+  without interactive prompts. Required for use as host or judge in the
+  external Python runner.
+
+`goal`
+: The CLI supports a `/goal` command that runs an autonomous loop with
+  self-verification. When present, RUN_IN_SESSION.md can emit a `/goal`
+  one-liner as an alternative execution path.
+
+`subagent`
+: The CLI can spawn isolated sub-agents with their own context. When present,
+  the council can use native subagent review loops instead of shelling out.
+
+`review_loop`
+: The CLI supports iterative review loops with trigger-based feedback (e.g.
+  Kiro's `loop_to` with `NEEDS_CHANGES` trigger). Enables native cross-model
+  review without the external runner.
+
+## Kiro CLI Specifics
+
+- Headless mode requires `--trust-all-tools` or the session halts waiting for
+  tool approval.
+- Full invoke pattern: `["kiro-cli", "chat", "--trust-all-tools", "-p"]`
+- The `/goal --max N` command provides native loop execution with configurable
+  iteration limits (default 5).
+- Subagent review loops use a `trigger` string (e.g. `NEEDS_CHANGES`) and
+  `max_iterations` cap.
+
+## `authed` Semantics
+
+`authed` means the basic probe command exited cleanly. It is a convenience
+signal, not a guarantee that a future paid model call will succeed.
+
+## Default Redactions
+
+- `.env`
+- `.env.*`
+- `secrets/**`
+- `**/*.key`
+
+Add project-specific globs for customer data, private transcripts, or internal
+design docs before sending anything to a non-local council member.
+
+## Local Model UX
+
+Surface `ollama` as the privacy-preserving option when present. It may be lower
+quality than frontier hosted models, but it keeps council review in-house.
--- a/.github/skills/loop-architect/references/verification-rubric.md
+++ b/.github/skills/loop-architect/references/verification-rubric.md
@@ -0,0 +1,59 @@
+# Verification Rubric
+
+Use this when converting the user's definition of done into typed criteria.
+
+## Taxonomy
+
+`programmatic`
+: A command or deterministic check returns pass/fail. Use this whenever
+possible. Examples: tests, build, lint, schema validation, snapshot comparison,
+or an extraction script that checks required headings.
+
+`judge`
+: A model scores a rubric and returns a structured verdict. Use this for
+semantic quality that cannot be cheaply checked by code. The rubric must be
+specific enough that a different model can apply it consistently.
+
+`human`
+: A person must sign off. Use this for taste, business judgment, private
+knowledge, legal risk, or decisions where the user is the true authority.
+
+## Required Fields
+
+- Every criterion needs `id` and `type`.
+- `programmatic` needs `check` as an argv array and `expect`.
+- `judge` needs `rubric`.
+- `human` needs `prompt`.
+
+## Strong Criteria
+
+- Check one thing at a time.
+- Say what failure means.
+- Prefer deterministic checks before model judgment.
+- Make judge rubrics observable against artifacts the judge receives.
+- Avoid relying on the host model to grade its own work.
+
+## Anti-Patterns
+
+- All criteria are judge or human criteria when tests or schema checks exist.
+- "No errors thrown" as the only success criterion.
+- Criteria that require hidden context not sent to the judge.
+- Rubrics like "high quality" or "comprehensive" without dimensions.
+- Programmatic checks written as shell strings instead of argv arrays.
+
+## Structured Judge Contract
+
+Judges should return a fenced JSON object:
+
+```json
+{
+  "verdict": "pass",
+  "blocking_issues": [],
+  "confidence": 0.86,
+  "notes": "The artifact satisfies the rubric."
+}
+```
+
+Valid verdicts are `pass` and `revise`. If output cannot be parsed, the runner
+will treat it as `revise` with a warning.
+
--- a/.github/skills/loop-architect/schemas/loop.resolved.v1.schema.json
+++ b/.github/skills/loop-architect/schemas/loop.resolved.v1.schema.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ksimback/looper/schema/loop.resolved.v1.json",
+  "title": "Looper resolved spec v1",
+  "allOf": [
+    { "$ref": "./loop.v1.schema.json" },
+    {
+      "type": "object",
+      "required": ["compiled_at", "source", "criteria_by_id", "council_by_id"],
+      "properties": {
+        "compiled_at": { "type": "string" },
+        "source": { "type": "string" },
+        "criteria_by_id": {
+          "type": "object",
+          "additionalProperties": { "$ref": "./loop.v1.schema.json#/$defs/criterion" }
+        },
+        "council_by_id": {
+          "type": "object",
+          "additionalProperties": true
+        }
+      }
+    }
+  ]
+}
+
--- a/.github/skills/loop-architect/schemas/loop.v1.schema.json
+++ b/.github/skills/loop-architect/schemas/loop.v1.schema.json
@@ -0,0 +1,190 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ksimback/looper/schema/loop.v1.json",
+  "title": "Looper authoring spec v1",
+  "type": "object",
+  "required": ["version", "goal", "host", "gates", "loop_control", "workspace"],
+  "properties": {
+    "version": { "const": 1 },
+    "meta": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "goal": {
+      "type": "object",
+      "required": ["statement", "definition_of_done", "verification"],
+      "properties": {
+        "statement": { "type": "string", "minLength": 1 },
+        "definition_of_done": { "type": "string", "minLength": 1 },
+        "context_sources": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "anyOf": [
+              { "required": ["file"] },
+              { "required": ["cmd"] }
+            ]
+          }
+        },
+        "verification": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/criterion" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "host": { "$ref": "#/$defs/model_invocation" },
+    "council": {
+      "type": "array",
+      "items": {
+        "allOf": [
+          { "$ref": "#/$defs/model_invocation" },
+          {
+            "type": "object",
+            "required": ["id", "role"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "role": { "enum": ["reviewer", "judge"] },
+              "scope": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "local": { "type": "boolean" }
+            }
+          }
+        ]
+      }
+    },
+    "gates": {
+      "type": "object",
+      "required": ["plan_gate", "delivery_gate"],
+      "properties": {
+        "plan_gate": { "$ref": "#/$defs/gate" },
+        "delivery_gate": { "$ref": "#/$defs/gate" }
+      }
+    },
+    "loop_control": {
+      "type": "object",
+      "required": ["max_iterations"],
+      "properties": {
+        "max_iterations": { "type": "integer", "minimum": 1 },
+        "budget": { "type": "object" },
+        "no_progress": {
+          "type": "object",
+          "properties": {
+            "max_stalled_iterations": { "type": "integer", "minimum": 1 },
+            "signals": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "action": { "enum": ["stop", "human_checkpoint"] }
+          },
+          "additionalProperties": true
+        },
+        "human_checkpoints": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "stop_conditions": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "properties": {
+        "mode": { "enum": ["in_session", "external_runner", "orchestrated"] },
+        "isolation": { "enum": ["current_workspace", "branch", "worktree", "sandbox"] },
+        "side_effects": { "type": "object" }
+      },
+      "additionalProperties": true
+    },
+    "observability": {
+      "type": "object",
+      "properties": {
+        "state_file": { "type": "string" },
+        "run_log": { "type": "string" },
+        "checkpoint_granularity": { "enum": ["gate", "step"] }
+      },
+      "additionalProperties": true
+    },
+    "privacy": { "type": "object" },
+    "workspace": {
+      "type": "object",
+      "required": ["dir"],
+      "properties": {
+        "dir": { "type": "string", "minLength": 1 },
+        "layout": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "argv": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "model_invocation": {
+      "type": "object",
+      "required": ["cli", "invoke"],
+      "properties": {
+        "cli": { "type": "string" },
+        "model": { "type": "string" },
+        "invoke": { "$ref": "#/$defs/argv" },
+        "timeout_sec": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": true
+    },
+    "criterion": {
+      "type": "object",
+      "required": ["id", "type"],
+      "oneOf": [
+        {
+          "properties": {
+            "type": { "const": "programmatic" },
+            "check": { "$ref": "#/$defs/argv" },
+            "expect": { "enum": ["exit_zero", "exit_nonzero", "stdout_contains"] },
+            "contains": { "type": "string" }
+          },
+          "required": ["check", "expect"]
+        },
+        {
+          "properties": {
+            "type": { "const": "judge" },
+            "rubric": { "type": "string", "minLength": 1 }
+          },
+          "required": ["rubric"]
+        },
+        {
+          "properties": {
+            "type": { "const": "human" },
+            "prompt": { "type": "string", "minLength": 1 }
+          },
+          "required": ["prompt"]
+        }
+      ]
+    },
+    "gate": {
+      "type": "object",
+      "required": ["when", "members", "verdict_policy", "criteria", "max_revisions"],
+      "properties": {
+        "when": { "type": "string" },
+        "members": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "verdict_policy": { "enum": ["revise_until_clean", "fixed_passes"] },
+        "verdict_source": { "type": "string" },
+        "criteria": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "max_revisions": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}
--- a/.github/skills/loop-architect/scripts/looper.py
+++ b/.github/skills/loop-architect/scripts/looper.py
@@ -0,0 +1,822 @@
+#!/usr/bin/env python3
+"""Loop-architect helper CLI.
+
+This script belongs to the scaffolding side of loop-architect. It may detect
+installed CLIs, register invocation metadata, compile loop.yaml to
+loop.resolved.json, and render LOOP.md. It must not invoke model CLIs to do
+loop work.
+
+Based on Looper by Kevin Simback (https://github.com/ksimback/looper), MIT License.
+Adapted for Kiro CLI by ft.ia.br.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import os
+from pathlib import Path
+import shlex
+import shutil
+import subprocess
+import sys
+from typing import Any
+
+
+DEFAULT_REDACTIONS = [".env", ".env.*", "secrets/**", "**/*.key"]
+REGISTRY_PATH = Path.home() / ".loop-architect" / "models.json"
+
+MODEL_PROBES: dict[str, dict[str, Any]] = {
+    "kiro": {
+        "invoke": ["kiro-cli", "chat", "--trust-all-tools", "-p"],
+        "probe": ["kiro-cli", "--version"],
+        "local": False,
+        "install": "Install Kiro CLI: https://kiro.dev/downloads/",
+        "capabilities": ["headless", "goal", "subagent", "review_loop"],
+    },
+    "claude": {
+        "invoke": ["claude", "-p"],
+        "probe": ["claude", "--version"],
+        "local": False,
+        "install": "Install and authenticate the Claude CLI.",
+        "capabilities": ["headless", "goal"],
+    },
+    "codex": {
+        "invoke": ["codex", "exec"],
+        "probe": ["codex", "--version"],
+        "local": False,
+        "install": "Install and authenticate the Codex CLI.",
+        "capabilities": ["headless", "goal"],
+    },
+    "gemini": {
+        "invoke": ["gemini", "-p"],
+        "probe": ["gemini", "--version"],
+        "local": False,
+        "install": "Install and authenticate the Gemini CLI.",
+        "capabilities": ["headless"],
+    },
+    "llm": {
+        "invoke": ["llm"],
+        "probe": ["llm", "--version"],
+        "local": False,
+        "install": "Install llm and configure a model/provider.",
+        "capabilities": ["headless"],
+    },
+    "ollama": {
+        "invoke": ["ollama", "run"],
+        "probe": ["ollama", "--version"],
+        "local": True,
+        "install": "Install Ollama and pull a local model.",
+        "capabilities": ["headless"],
+    },
+}
+
+
+class LooperError(RuntimeError):
+    pass
+
+
+def load_yaml(path: Path) -> dict[str, Any]:
+    try:
+        import yaml  # type: ignore
+    except ImportError as exc:
+        raise LooperError(
+            "PyYAML is required to compile loop.yaml. Install with: python -m pip install PyYAML"
+        ) from exc
+
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data = yaml.safe_load(fh)
+    except OSError as exc:
+        raise LooperError(f"Could not read {path}: {exc}") from exc
+    except yaml.YAMLError as exc:
+        raise LooperError(f"Could not parse YAML in {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise LooperError(f"{path} must contain a YAML mapping at the top level")
+    return data
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    with path.open("r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    if not isinstance(data, dict):
+        raise LooperError(f"{path} must contain a JSON object")
+    return data
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(to_jsonable(data), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def to_jsonable(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {str(key): to_jsonable(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [to_jsonable(item) for item in value]
+    if isinstance(value, (_dt.date, _dt.datetime)):
+        return value.isoformat()
+    return value
+
+
+def read_registry(path: Path = REGISTRY_PATH) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    with path.open("r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    if not isinstance(data, dict):
+        raise LooperError(f"Registry {path} must contain a JSON object")
+    return data
+
+
+def write_registry(data: dict[str, Any], path: Path = REGISTRY_PATH) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    write_json(path, data)
+
+
+def run_probe(argv: list[str], timeout_sec: int = 5) -> tuple[bool, str]:
+    probe_argv = list(argv)
+    if os.name == "nt":
+        resolved = shutil.which(argv[0])
+        if resolved and Path(resolved).suffix.lower() in {".cmd", ".bat"}:
+            probe_argv = ["cmd", "/d", "/c", *argv]
+    try:
+        completed = subprocess.run(
+            probe_argv,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=timeout_sec,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return False, str(exc)
+
+    output = (completed.stdout or completed.stderr or "").strip()
+    return completed.returncode == 0, output.splitlines()[0] if output else ""
+
+
+def detect_models() -> dict[str, Any]:
+    registry: dict[str, Any] = {}
+    for model_id, meta in MODEL_PROBES.items():
+        cli = meta["invoke"][0]
+        path = shutil.which(cli)
+        available = path is not None
+        authed = False
+        version = ""
+        if available:
+            authed, version = run_probe(meta["probe"])
+        registry[model_id] = {
+            "cli": cli,
+            "path": path,
+            "invoke": meta["invoke"],
+            "available": available,
+            "authed": authed,
+            "local": meta["local"],
+            "probe": meta["probe"],
+            "version": version,
+            "install": meta["install"],
+            "capabilities": meta.get("capabilities", []),
+        }
+    return registry
+
+
+def normalize_argv(value: Any, field: str) -> list[str]:
+    if isinstance(value, list) and all(isinstance(item, str) for item in value):
+        return value
+    if isinstance(value, str):
+        return shlex.split(value, posix=os.name != "nt")
+    raise LooperError(f"{field} must be an argv array or string")
+
+
+def criteria_by_id(spec: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    criteria = spec.get("goal", {}).get("verification", [])
+    if not isinstance(criteria, list):
+        raise LooperError("goal.verification must be a list")
+    result: dict[str, dict[str, Any]] = {}
+    for item in criteria:
+        if not isinstance(item, dict):
+            raise LooperError("Each verification criterion must be an object")
+        cid = item.get("id")
+        ctype = item.get("type")
+        if not isinstance(cid, str) or not cid:
+            raise LooperError("Each verification criterion needs a non-empty id")
+        if cid in result:
+            raise LooperError(f"Duplicate verification criterion id: {cid}")
+        if ctype not in {"programmatic", "judge", "human"}:
+            raise LooperError(f"Criterion {cid} has invalid type: {ctype}")
+        if ctype == "programmatic":
+            item["check"] = normalize_argv(item.get("check"), f"criterion {cid}.check")
+            if item.get("expect") not in {"exit_zero", "exit_nonzero", "stdout_contains"}:
+                raise LooperError(
+                    f"Criterion {cid}.expect must be exit_zero, exit_nonzero, or stdout_contains"
+                )
+            if item.get("expect") == "stdout_contains" and not isinstance(item.get("contains"), str):
+                raise LooperError(f"Criterion {cid} with stdout_contains needs contains")
+        elif ctype == "judge" and not isinstance(item.get("rubric"), str):
+            raise LooperError(f"Criterion {cid} needs a judge rubric")
+        elif ctype == "human" and not isinstance(item.get("prompt"), str):
+            raise LooperError(f"Criterion {cid} needs a human prompt")
+        result[cid] = item
+    return result
+
+
+def validate_member(member: dict[str, Any]) -> None:
+    mid = member.get("id")
+    role = member.get("role")
+    if not isinstance(mid, str) or not mid:
+        raise LooperError("Each council member needs a non-empty id")
+    if role not in {"reviewer", "judge"}:
+        raise LooperError(f"Council member {mid} role must be reviewer or judge")
+    member["invoke"] = normalize_argv(member.get("invoke"), f"council.{mid}.invoke")
+    timeout = member.get("timeout_sec", 600)
+    if not isinstance(timeout, int) or timeout <= 0:
+        raise LooperError(f"Council member {mid}.timeout_sec must be a positive integer")
+    member.setdefault("scope", ["plan", "delivery"])
+    member.setdefault("local", member.get("cli") == "ollama")
+
+
+def validate_gate(
+    name: str,
+    gate: dict[str, Any],
+    criteria: dict[str, dict[str, Any]],
+    members: dict[str, dict[str, Any]],
+) -> None:
+    if not isinstance(gate, dict):
+        raise LooperError(f"{name} must be an object")
+    policy = gate.get("verdict_policy")
+    if policy not in {"revise_until_clean", "fixed_passes"}:
+        raise LooperError(f"{name}.verdict_policy must be revise_until_clean or fixed_passes")
+    max_revisions = gate.get("max_revisions", 1)
+    if not isinstance(max_revisions, int) or max_revisions < 0:
+        raise LooperError(f"{name}.max_revisions must be a non-negative integer")
+    for cid in gate.get("criteria", []):
+        if cid not in criteria:
+            raise LooperError(f"{name} references unknown criterion: {cid}")
+    for mid in gate.get("members", []):
+        if mid not in members:
+            raise LooperError(f"{name} references unknown council member: {mid}")
+    if policy == "revise_until_clean":
+        source = gate.get("verdict_source")
+        if source == "human":
+            return
+        if source not in members:
+            raise LooperError(f"{name}.verdict_source must be a judge member or human")
+        if members[source].get("role") != "judge":
+            raise LooperError(f"{name}.verdict_source must name a judge, not a reviewer")
+
+
+def normalize_spec(spec: dict[str, Any], source_path: Path) -> dict[str, Any]:
+    if spec.get("version") != 1:
+        raise LooperError("Only loop.yaml version: 1 is supported")
+
+    goal = spec.get("goal")
+    if not isinstance(goal, dict):
+        raise LooperError("goal must be an object")
+    if not isinstance(goal.get("statement"), str) or not goal["statement"].strip():
+        raise LooperError("goal.statement is required")
+    if not isinstance(goal.get("definition_of_done"), str) or not goal["definition_of_done"].strip():
+        raise LooperError("goal.definition_of_done is required")
+
+    for index, source in enumerate(goal.get("context_sources", [])):
+        if not isinstance(source, dict):
+            raise LooperError("goal.context_sources entries must be objects")
+        if "cmd" in source:
+            source["cmd"] = normalize_argv(source["cmd"], f"context_sources[{index}].cmd")
+
+    criteria = criteria_by_id(spec)
+
+    host = spec.get("host")
+    if not isinstance(host, dict):
+        raise LooperError("host must be an object")
+    host["invoke"] = normalize_argv(host.get("invoke"), "host.invoke")
+    host.setdefault("timeout_sec", 600)
+    if not isinstance(host["timeout_sec"], int) or host["timeout_sec"] <= 0:
+        raise LooperError("host.timeout_sec must be a positive integer")
+
+    council_list = spec.get("council", [])
+    if not isinstance(council_list, list):
+        raise LooperError("council must be a list")
+    for member in council_list:
+        if not isinstance(member, dict):
+            raise LooperError("council entries must be objects")
+        validate_member(member)
+    members = {member["id"]: member for member in council_list}
+
+    gates = spec.get("gates")
+    if not isinstance(gates, dict):
+        raise LooperError("gates must be an object")
+    for gate_name in ("plan_gate", "delivery_gate"):
+        validate_gate(gate_name, gates.get(gate_name), criteria, members)
+
+    control = spec.get("loop_control")
+    if not isinstance(control, dict):
+        raise LooperError("loop_control must be an object")
+    max_iterations = control.get("max_iterations")
+    if not isinstance(max_iterations, int) or max_iterations <= 0:
+        raise LooperError("loop_control.max_iterations must be a positive integer")
+    budget = control.setdefault("budget", {})
+    if not isinstance(budget, dict):
+        raise LooperError("loop_control.budget must be an object")
+    if "wall_clock_min" not in budget:
+        budget["wall_clock_min"] = 30
+    no_progress = control.setdefault(
+        "no_progress",
+        {
+            "max_stalled_iterations": 2,
+            "signals": [
+                "same blocking issue repeats",
+                "delivery artifact has no material change",
+                "verifier output is unchanged",
+            ],
+            "action": "stop",
+        },
+    )
+    if not isinstance(no_progress, dict):
+        raise LooperError("loop_control.no_progress must be an object")
+    stalled = no_progress.setdefault("max_stalled_iterations", 2)
+    if not isinstance(stalled, int) or stalled <= 0:
+        raise LooperError("loop_control.no_progress.max_stalled_iterations must be a positive integer")
+    signals = no_progress.setdefault("signals", ["same blocking issue repeats"])
+    if not isinstance(signals, list) or not all(isinstance(item, str) for item in signals):
+        raise LooperError("loop_control.no_progress.signals must be a list of strings")
+    action = no_progress.setdefault("action", "stop")
+    if action not in {"stop", "human_checkpoint"}:
+        raise LooperError("loop_control.no_progress.action must be stop or human_checkpoint")
+
+    execution = spec.setdefault(
+        "execution",
+        {
+            "mode": "in_session",
+            "isolation": "current_workspace",
+            "side_effects": {"requires_approval": True, "duplicate_action_check": True},
+        },
+    )
+    if not isinstance(execution, dict):
+        raise LooperError("execution must be an object")
+    execution.setdefault("mode", "in_session")
+    execution.setdefault("isolation", "current_workspace")
+    if execution["mode"] not in {"in_session", "external_runner", "orchestrated"}:
+        raise LooperError("execution.mode must be in_session, external_runner, or orchestrated")
+    if execution["isolation"] not in {"current_workspace", "branch", "worktree", "sandbox"}:
+        raise LooperError("execution.isolation must be current_workspace, branch, worktree, or sandbox")
+    side_effects = execution.setdefault("side_effects", {})
+    if not isinstance(side_effects, dict):
+        raise LooperError("execution.side_effects must be an object")
+    side_effects.setdefault("requires_approval", True)
+    side_effects.setdefault("duplicate_action_check", True)
+
+    observability = spec.setdefault(
+        "observability",
+        {"state_file": "state.json", "run_log": "run-log.md", "checkpoint_granularity": "gate"},
+    )
+    if not isinstance(observability, dict):
+        raise LooperError("observability must be an object")
+    observability.setdefault("state_file", "state.json")
+    observability.setdefault("run_log", "run-log.md")
+    observability.setdefault("checkpoint_granularity", "gate")
+    if not isinstance(observability["state_file"], str) or not observability["state_file"]:
+        raise LooperError("observability.state_file must be a non-empty string")
+    if not isinstance(observability["run_log"], str) or not observability["run_log"]:
+        raise LooperError("observability.run_log must be a non-empty string")
+    if observability["checkpoint_granularity"] not in {"gate", "step"}:
+        raise LooperError("observability.checkpoint_granularity must be gate or step")
+
+    workspace = spec.setdefault("workspace", {})
+    if not isinstance(workspace, dict):
+        raise LooperError("workspace must be an object")
+    workspace.setdefault("dir", "./loop-workspace")
+    layout = workspace.setdefault("layout", ["plan.md", "delivery-{n}.md", "review-{n}.md", "state.json", "run-log.md"])
+    if not isinstance(layout, list) or not all(isinstance(item, str) for item in layout):
+        raise LooperError("workspace.layout must be a list of strings")
+    for required_file in (observability["state_file"], observability["run_log"]):
+        if required_file not in layout:
+            layout.append(required_file)
+
+    privacy = spec.setdefault("privacy", {})
+    if not isinstance(privacy, dict):
+        raise LooperError("privacy must be an object")
+    egress = privacy.setdefault("egress", [])
+    if not isinstance(egress, list):
+        raise LooperError("privacy.egress must be a list")
+    for entry in egress:
+        if not isinstance(entry, dict):
+            raise LooperError("privacy.egress entries must be objects")
+        entry.setdefault("redact", DEFAULT_REDACTIONS)
+        entry.setdefault("consent", "required")
+
+    resolved = {
+        "$schema": "https://github.com/ksimback/looper/schema/loop.resolved.v1.json",
+        "compiled_at": _dt.datetime.now(_dt.UTC).replace(microsecond=0).isoformat(),
+        "source": str(source_path),
+        **spec,
+        "criteria_by_id": criteria,
+        "council_by_id": members,
+    }
+    return to_jsonable(resolved)
+
+
+def clip(text: Any, width: int) -> str:
+    value = str(text or "")
+    return value if len(value) <= width else value[: width - 1] + "~"
+
+
+def ascii_box(*rows: str, width: int = 30) -> list[str]:
+    border = "+" + "-" * (width + 2) + "+"
+    body = [f"| {clip(row, width):<{width}} |" for row in rows if row is not None]
+    return [border, *body, border]
+
+
+def render_ascii_diagram(resolved: dict[str, Any]) -> str:
+    gates = resolved.get("gates", {})
+    control = resolved.get("loop_control", {})
+    observability = resolved.get("observability", {})
+    plan_gate = gates.get("plan_gate", {})
+    delivery_gate = gates.get("delivery_gate", {})
+    plan_revisions = plan_gate.get("max_revisions", 0)
+    delivery_revisions = delivery_gate.get("max_revisions", 0)
+    plan_source = plan_gate.get("verdict_source", "human")
+    delivery_source = delivery_gate.get("verdict_source", "human")
+    no_progress = control.get("no_progress", {})
+    stalled = no_progress.get("max_stalled_iterations", 2)
+    budget = control.get("budget", {})
+    budget_bits = []
+    if budget.get("wall_clock_min") is not None:
+        budget_bits.append(f"{budget.get('wall_clock_min')}m")
+    if budget.get("usd") is not None:
+        budget_bits.append(f"${budget.get('usd')}")
+    if budget.get("tokens") is not None:
+        budget_bits.append(f"{budget.get('tokens')} tokens")
+    budget_text = ", ".join(budget_bits) or "configured caps"
+
+    lines: list[str] = []
+    lines.extend(ascii_box("1. Goal + context", "read sources"))
+    lines.extend(["               |", "               v"])
+    lines.extend(ascii_box("2. Draft plan.md", f"state -> {observability.get('state_file', 'state.json')}"))
+    lines.extend(["               |", "               v"])
+    lines.extend(ascii_box("3. Plan gate", f"verdict: {plan_source}"))
+    lines.extend([f"               | needs work -> revise <= {plan_revisions} -> step 2", "               | pass", "               v"])
+    lines.extend(ascii_box("4. Write delivery-N.md", f"log -> {observability.get('run_log', 'run-log.md')}"))
+    lines.extend(["               |", "               v"])
+    lines.extend(ascii_box("5. Delivery gate", f"verdict: {delivery_source}"))
+    lines.extend([f"               | needs work -> revise <= {delivery_revisions} -> step 4", "               | pass", "               v"])
+    lines.extend(ascii_box("6. Final output", "all gates clean"))
+    lines.extend(
+        [
+            "",
+            f"Stops: pass gates | max {control.get('max_iterations')} iterations | "
+            f"no progress x{stalled} | budget {budget_text}",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def render_loop(resolved: dict[str, Any]) -> str:
+    meta = resolved.get("meta", {})
+    goal = resolved.get("goal", {})
+    gates = resolved.get("gates", {})
+    control = resolved.get("loop_control", {})
+    execution = resolved.get("execution", {})
+    observability = resolved.get("observability", {})
+    title = meta.get("name") or "Looper Generated Loop"
+    criteria = goal.get("verification", [])
+    council = resolved.get("council", [])
+
+    lines = [
+        f"# {title}",
+        "",
+        meta.get("description", "").strip(),
+        "",
+        "## Goal",
+        "",
+        goal.get("statement", "").strip(),
+        "",
+        "## Definition of Done",
+        "",
+        goal.get("definition_of_done", "").strip(),
+        "",
+        "## Verification",
+        "",
+    ]
+    for item in criteria:
+        lines.append(f"- `{item['id']}` ({item['type']})")
+    lines.extend(["", "## Council", ""])
+    if council:
+        for member in council:
+            lines.append(
+                f"- `{member['id']}`: {member.get('role')} via {member.get('cli')} "
+                f"({member.get('model', 'default')})"
+            )
+    else:
+        lines.append("- No council members configured.")
+    lines.extend(
+        [
+            "",
+            "## Gates",
+            "",
+            f"- Plan gate: {gates.get('plan_gate', {}).get('verdict_policy')}",
+            f"- Delivery gate: {gates.get('delivery_gate', {}).get('verdict_policy')}",
+            "",
+            "## Loop Control",
+            "",
+            f"- Max iterations: {control.get('max_iterations')}",
+            f"- Budget: `{json.dumps(control.get('budget', {}), sort_keys=True)}`",
+            f"- No-progress: `{json.dumps(control.get('no_progress', {}), sort_keys=True)}`",
+            "",
+            "## Execution Boundary",
+            "",
+            f"- Mode: `{execution.get('mode', 'in_session')}`",
+            f"- Isolation: `{execution.get('isolation', 'current_workspace')}`",
+            f"- Side effects: `{json.dumps(execution.get('side_effects', {}), sort_keys=True)}`",
+            "",
+            "## Observability",
+            "",
+            f"- State file: `{observability.get('state_file', 'state.json')}`",
+            f"- Run log: `{observability.get('run_log', 'run-log.md')}`",
+            f"- Checkpoint granularity: `{observability.get('checkpoint_granularity', 'gate')}`",
+            "",
+            "## Flow Preview",
+            "",
+            "```text",
+            render_ascii_diagram(resolved),
+            "```",
+            "",
+        ]
+    )
+    return "\n".join(line for line in lines if line is not None)
+
+
+def render_session_prompt(resolved: dict[str, Any]) -> str:
+    meta = resolved.get("meta", {})
+    goal = resolved.get("goal", {})
+    gates = resolved.get("gates", {})
+    control = resolved.get("loop_control", {})
+    workspace = resolved.get("workspace", {})
+    execution = resolved.get("execution", {})
+    observability = resolved.get("observability", {})
+    criteria = goal.get("verification", [])
+    council = resolved.get("council", [])
+    title = meta.get("name") or "Looper Generated Loop"
+
+    lines = [
+        f"# Run `{title}` In This Session",
+        "",
+        "Use this prompt when the user wants to run the Looper-designed loop in the current LLM session.",
+        "This is the default/easy execution path. The Python runner is the advanced path for running later or outside the session.",
+        "",
+        "## Operator Instructions",
+        "",
+        "You are executing a Looper-designed loop in this current session.",
+        "Follow the resolved spec below, write handoff files into the workspace, and enforce the caps manually.",
+        "Do not use `run-loop.py` unless the user explicitly asks for the advanced external runner.",
+        "",
+        "1. Create the workspace directory if it does not exist.",
+        "2. Read the context sources before drafting the plan.",
+        "3. Draft `plan.md` in the workspace.",
+        "4. Run the plan gate. Apply programmatic checks when available. For judge criteria, use the configured judge only after consent for any non-local egress; otherwise ask the user to approve a human/current-session substitute.",
+        "5. Revise until the gate passes or `max_revisions` is reached.",
+        "6. Produce `delivery-N.md` in the workspace.",
+        "7. Run the delivery gate after each delivery.",
+        "8. Stop when all delivery criteria pass, a cap is reached, or the user stops the loop.",
+        "9. Keep `state.json` current with status, iteration, last gate, consent, and blockers.",
+        "10. Append a compact entry to `run-log.md` after every context read, model call, check, gate verdict, revision, blocker, and stop decision.",
+        "11. Compare each blocker against the previous blocker. If the same blocker repeats for the configured no-progress window, stop or ask for the configured human checkpoint instead of revising again.",
+        "12. Treat token and USD budgets as operator limits in this session: if exact accounting is unavailable, stop and ask before continuing when the loop appears likely to exceed them.",
+        "",
+        "## Files",
+        "",
+        f"- Source spec: `{Path(resolved.get('source', 'loop.yaml')).name}`",
+        "- Human summary: `LOOP.md`",
+        "- Resolved spec: `loop.resolved.json`",
+        f"- Workspace: `{workspace.get('dir', './loop-workspace')}`",
+        f"- State file: `{observability.get('state_file', 'state.json')}`",
+        f"- Run log: `{observability.get('run_log', 'run-log.md')}`",
+        "",
+        "## Goal",
+        "",
+        goal.get("statement", "").strip(),
+        "",
+        "## Definition Of Done",
+        "",
+        goal.get("definition_of_done", "").strip(),
+        "",
+        "## Context Sources",
+        "",
+    ]
+
+    context_sources = goal.get("context_sources", [])
+    if context_sources:
+        for source in context_sources:
+            if "file" in source:
+                lines.append(f"- Read file `{source['file']}`")
+            elif "cmd" in source:
+                lines.append(f"- Run command `{json.dumps(source['cmd'])}`")
+    else:
+        lines.append("- No context sources configured.")
+
+    lines.extend(["", "## Verification Criteria", ""])
+    for item in criteria:
+        if item["type"] == "programmatic":
+            lines.append(
+                f"- `{item['id']}` programmatic: run `{json.dumps(item['check'])}` and expect `{item['expect']}`"
+            )
+        elif item["type"] == "judge":
+            lines.append(f"- `{item['id']}` judge rubric: {item['rubric']}")
+        elif item["type"] == "human":
+            lines.append(f"- `{item['id']}` human signoff: {item['prompt']}")
+
+    lines.extend(["", "## Council", ""])
+    if council:
+        for member in council:
+            locality = "local" if member.get("local") else "non-local"
+            lines.append(
+                f"- `{member['id']}` {member.get('role')} via `{json.dumps(member.get('invoke', []))}` "
+                f"({locality}; timeout {member.get('timeout_sec', 600)}s)"
+            )
+    else:
+        lines.append("- No council members configured.")
+
+    lines.extend(["", "## Gates", ""])
+    for gate_name in ("plan_gate", "delivery_gate"):
+        gate = gates.get(gate_name, {})
+        lines.extend(
+            [
+                f"### {gate_name}",
+                "",
+                f"- When: `{gate.get('when')}`",
+                f"- Policy: `{gate.get('verdict_policy')}`",
+                f"- Verdict source: `{gate.get('verdict_source', 'none')}`",
+                f"- Criteria: `{', '.join(gate.get('criteria', []))}`",
+                f"- Max revisions: `{gate.get('max_revisions')}`",
+                "",
+            ]
+        )
+
+    lines.extend(
+        [
+            "## Loop Control",
+            "",
+            f"- Max iterations: `{control.get('max_iterations')}`",
+            f"- Budget: `{json.dumps(control.get('budget', {}), sort_keys=True)}`",
+            f"- No-progress: `{json.dumps(control.get('no_progress', {}), sort_keys=True)}`",
+            f"- Human checkpoints: `{', '.join(control.get('human_checkpoints', [])) or 'none'}`",
+            "- Stop conditions:",
+        ]
+    )
+    for condition in control.get("stop_conditions", []):
+        lines.append(f"  - {condition}")
+
+    lines.extend(
+        [
+            "",
+            "## Execution Boundary",
+            "",
+            f"- Mode: `{execution.get('mode', 'in_session')}`",
+            f"- Isolation: `{execution.get('isolation', 'current_workspace')}`",
+            f"- Side effects: `{json.dumps(execution.get('side_effects', {}), sort_keys=True)}`",
+            "",
+            "If the loop needs scheduled runs, child-agent lifecycle management, concurrency control, or restart-safe step retries, stop and tell the user this Looper spec should be handed to a durable orchestrator.",
+            "",
+            "## Observability",
+            "",
+            f"- State file: `{observability.get('state_file', 'state.json')}`",
+            f"- Run log: `{observability.get('run_log', 'run-log.md')}`",
+            f"- Checkpoint granularity: `{observability.get('checkpoint_granularity', 'gate')}`",
+            "",
+            "Use `state.json` for the latest resumable status and `run-log.md` for the append-only history of what happened.",
+        ]
+    )
+
+    lines.extend(["", "## Privacy", ""])
+    egress = resolved.get("privacy", {}).get("egress", [])
+    if egress:
+        for entry in egress:
+            lines.append(
+                f"- Before sending `{', '.join(entry.get('sends', []))}` to `{entry.get('to')}`, "
+                f"confirm consent and apply redactions `{', '.join(entry.get('redact', []))}`."
+            )
+    else:
+        lines.append("- No cross-vendor egress configured.")
+
+    lines.extend(
+        [
+            "",
+            "## Start Now",
+            "",
+            "If the user asked to run now, begin at step 1 under Operator Instructions and keep going until a stop condition is reached.",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def cmd_detect(args: argparse.Namespace) -> int:
+    registry = detect_models()
+    if args.write:
+        existing = read_registry(args.registry)
+        existing.update(registry)
+        write_registry(existing, args.registry)
+    print(json.dumps(registry, indent=2, sort_keys=True))
+    return 0
+
+
+def cmd_register(args: argparse.Namespace) -> int:
+    if not args.invoke:
+        raise LooperError("--invoke needs at least one command token")
+    registry = read_registry(args.registry)
+    registry[args.model_id] = {
+        "cli": args.invoke[0],
+        "invoke": args.invoke,
+        "available": shutil.which(args.invoke[0]) is not None,
+        "authed": args.authed,
+        "local": args.local,
+        "model": args.model,
+        "notes": args.notes or "",
+    }
+    write_registry(registry, args.registry)
+    print(f"Registered {args.model_id} in {args.registry}")
+    return 0
+
+
+def cmd_compile(args: argparse.Namespace) -> int:
+    source = args.loop_yaml.resolve()
+    spec = load_yaml(source)
+    resolved = normalize_spec(spec, source)
+    out = args.out or source.with_name("loop.resolved.json")
+    write_json(out, resolved)
+    if args.render:
+        args.render.parent.mkdir(parents=True, exist_ok=True)
+        args.render.write_text(render_loop(resolved), encoding="utf-8")
+    if args.session_prompt:
+        args.session_prompt.parent.mkdir(parents=True, exist_ok=True)
+        args.session_prompt.write_text(render_session_prompt(resolved), encoding="utf-8")
+    print(f"Wrote {out}")
+    if args.render:
+        print(f"Wrote {args.render}")
+    if args.session_prompt:
+        print(f"Wrote {args.session_prompt}")
+    return 0
+
+
+def cmd_session_prompt(args: argparse.Namespace) -> int:
+    resolved = load_json(args.resolved_json)
+    prompt = render_session_prompt(resolved)
+    if args.out:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(prompt, encoding="utf-8")
+        print(f"Wrote {args.out}")
+    else:
+        print(prompt)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="looper", description="Looper scaffolding helpers")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    detect = sub.add_parser("detect-models", help="Detect model CLIs and print registry JSON")
+    detect.add_argument("--write", action="store_true", help="Merge results into the model registry")
+    detect.add_argument("--registry", type=Path, default=REGISTRY_PATH)
+    detect.set_defaults(func=cmd_detect)
+
+    register = sub.add_parser("register-model", help="Register custom model CLI invocation metadata")
+    register.add_argument("model_id")
+    register.add_argument("--invoke", nargs="+", required=True)
+    register.add_argument("--model", default="")
+    register.add_argument("--local", action="store_true")
+    register.add_argument("--authed", action="store_true")
+    register.add_argument("--notes", default="")
+    register.add_argument("--registry", type=Path, default=REGISTRY_PATH)
+    register.set_defaults(func=cmd_register)
+
+    compile_cmd = sub.add_parser("compile", help="Compile loop.yaml to loop.resolved.json")
+    compile_cmd.add_argument("loop_yaml", type=Path)
+    compile_cmd.add_argument("--out", type=Path)
+    compile_cmd.add_argument("--render", type=Path)
+    compile_cmd.add_argument("--session-prompt", type=Path)
+    compile_cmd.set_defaults(func=cmd_compile)
+
+    session_prompt = sub.add_parser(
+        "session-prompt", help="Render the in-session execution prompt from loop.resolved.json"
+    )
+    session_prompt.add_argument("resolved_json", type=Path)
+    session_prompt.add_argument("--out", type=Path)
+    session_prompt.set_defaults(func=cmd_session_prompt)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except LooperError as exc:
+        print(f"looper: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
--- a/.github/skills/loop-architect/templates/run-loop.py
+++ b/.github/skills/loop-architect/templates/run-loop.py
@@ -0,0 +1,588 @@
+#!/usr/bin/env python3
+"""Generated Looper runner.
+
+This file executes a resolved loop spec. It intentionally reads only
+loop.resolved.json and uses only Python stdlib.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import fnmatch
+import json
+from pathlib import Path
+import re
+import subprocess
+import sys
+import time
+from typing import Any
+
+
+PASS = "pass"
+REVISE = "revise"
+
+
+class RunnerError(RuntimeError):
+    pass
+
+
+def utc_now() -> str:
+    return _dt.datetime.now(_dt.UTC).replace(microsecond=0).isoformat()
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except OSError as exc:
+        raise RunnerError(f"Could not read {path}: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise RunnerError(f"Could not parse JSON in {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise RunnerError(f"{path} must contain a JSON object")
+    return data
+
+
+def write_text(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text.rstrip() + "\n", encoding="utf-8")
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def ensure_argv(value: Any, field: str) -> list[str]:
+    if isinstance(value, list) and value and all(isinstance(item, str) for item in value):
+        return value
+    raise RunnerError(f"{field} must be a non-empty argv array")
+
+
+def relative_to_base(path_text: str, base_dir: Path) -> Path:
+    path = Path(path_text)
+    return path if path.is_absolute() else base_dir / path
+
+
+def is_redacted(path: Path, base_dir: Path, globs: list[str]) -> bool:
+    try:
+        rel = path.relative_to(base_dir).as_posix()
+    except ValueError:
+        rel = path.name
+    return any(fnmatch.fnmatch(rel, pattern) for pattern in globs)
+
+
+def run_argv(
+    argv: list[str],
+    *,
+    cwd: Path,
+    timeout_sec: int,
+    stdin: str = "",
+) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(
+            argv,
+            input=stdin,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            cwd=str(cwd),
+            timeout=timeout_sec,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        completed = subprocess.CompletedProcess(argv, 124, exc.stdout or "", exc.stderr or "")
+        return completed
+    except OSError as exc:
+        return subprocess.CompletedProcess(argv, 127, "", str(exc))
+
+
+def call_model(member: dict[str, Any], prompt: str, base_dir: Path) -> str:
+    argv = ensure_argv(member.get("invoke"), f"{member.get('id', member.get('cli', 'model'))}.invoke")
+    timeout_sec = int(member.get("timeout_sec", 600))
+    result = run_argv(argv, cwd=base_dir, timeout_sec=timeout_sec, stdin=prompt)
+    if result.returncode != 0:
+        raise RunnerError(
+            f"Model invocation failed ({' '.join(argv)}): exit {result.returncode}\n{result.stderr}"
+        )
+    return result.stdout.strip()
+
+
+def parse_judge_output(text: str) -> dict[str, Any]:
+    fenced = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    candidate = fenced.group(1) if fenced else text.strip()
+    try:
+        parsed = json.loads(candidate)
+    except json.JSONDecodeError:
+        return {
+            "verdict": REVISE,
+            "blocking_issues": ["Judge output was not parseable JSON."],
+            "confidence": 0.0,
+            "notes": text.strip(),
+            "warning": "unparseable_judge_output",
+        }
+    if not isinstance(parsed, dict):
+        return {
+            "verdict": REVISE,
+            "blocking_issues": ["Judge output was not a JSON object."],
+            "confidence": 0.0,
+            "notes": text.strip(),
+            "warning": "invalid_judge_output",
+        }
+    verdict = parsed.get("verdict")
+    if verdict not in {PASS, REVISE}:
+        parsed["verdict"] = REVISE
+        parsed.setdefault("blocking_issues", []).append("Judge verdict was not pass or revise.")
+    parsed.setdefault("blocking_issues", [])
+    parsed.setdefault("confidence", 0.0)
+    parsed.setdefault("notes", "")
+    return parsed
+
+
+class Runner:
+    def __init__(self, spec_path: Path) -> None:
+        self.spec_path = spec_path.resolve()
+        self.base_dir = self.spec_path.parent
+        self.spec = load_json(self.spec_path)
+        self.workspace = relative_to_base(self.spec["workspace"]["dir"], self.base_dir)
+        self.workspace.mkdir(parents=True, exist_ok=True)
+        self.observability = self.spec.get("observability", {})
+        self.run_log_path = self.workspace / self.observability.get("run_log", "run-log.md")
+        self.state_path = self.workspace / self.observability.get("state_file", "state.json")
+        self.state = self.load_state()
+        self.started = time.monotonic()
+
+    def load_state(self) -> dict[str, Any]:
+        if self.state_path.exists():
+            return load_json(self.state_path)
+        return {
+            "status": "initialized",
+            "started_at": utc_now(),
+            "iteration": 0,
+            "warnings": [],
+            "consent": {},
+        }
+
+    def save_state(self, **updates: Any) -> None:
+        self.state.update(updates)
+        self.state["updated_at"] = utc_now()
+        write_json(self.state_path, self.state)
+
+    def append_log(self, event: str, **fields: Any) -> None:
+        self.run_log_path.parent.mkdir(parents=True, exist_ok=True)
+        payload = f" {json.dumps(fields, sort_keys=True)}" if fields else ""
+        with self.run_log_path.open("a", encoding="utf-8") as fh:
+            fh.write(f"- {utc_now()} `{event}`{payload}\n")
+
+    def enforce_wall_clock(self) -> None:
+        budget = self.spec.get("loop_control", {}).get("budget", {})
+        wall_clock_min = budget.get("wall_clock_min")
+        if wall_clock_min is None:
+            return
+        if time.monotonic() - self.started > float(wall_clock_min) * 60:
+            self.save_state(status="failed", failure="wall_clock_budget_exceeded")
+            self.append_log("stop", reason="wall_clock_budget_exceeded")
+            raise RunnerError("Wall-clock budget exceeded")
+
+    def no_progress_reached(self, gate_name: str, failures: list[str]) -> bool:
+        if not failures:
+            self.save_state(no_progress={"count": 0, "signature": "", "gate": gate_name})
+            return False
+        config = self.spec.get("loop_control", {}).get("no_progress", {})
+        threshold = int(config.get("max_stalled_iterations", 2))
+        signature = "\n".join(sorted(failures))
+        previous = self.state.get("no_progress", {})
+        same_gate = previous.get("gate") == gate_name
+        same_signature = previous.get("signature") == signature
+        count = int(previous.get("count", 0)) + 1 if same_gate and same_signature else 1
+        progress = {
+            "gate": gate_name,
+            "signature": signature,
+            "count": count,
+            "threshold": threshold,
+            "updated_at": utc_now(),
+        }
+        self.save_state(no_progress=progress)
+        if count < threshold:
+            return False
+        self.append_log("no_progress_detected", gate=gate_name, count=count, failures=failures)
+        if config.get("action", "stop") == "human_checkpoint":
+            answer = input("No-progress detected. Type 'continue' to allow one more revision: ").strip().lower()
+            if answer == "continue":
+                progress["count"] = 0
+                self.save_state(no_progress=progress)
+                self.append_log("no_progress_override", gate=gate_name)
+                return False
+        self.save_state(status="failed", failure="no_progress_detected", blocking_issues=failures)
+        return True
+
+    def criteria(self, ids: list[str]) -> list[dict[str, Any]]:
+        by_id = self.spec.get("criteria_by_id", {})
+        return [by_id[item] for item in ids]
+
+    def member(self, member_id: str) -> dict[str, Any]:
+        return self.spec["council_by_id"][member_id]
+
+    def redactions_for(self, member_id: str) -> list[str]:
+        redactions: list[str] = []
+        for entry in self.spec.get("privacy", {}).get("egress", []):
+            if entry.get("to") == member_id:
+                redactions.extend(entry.get("redact", []))
+        return redactions or [".env", ".env.*", "secrets/**", "**/*.key"]
+
+    def redact_prompt_for_member(self, member_id: str, prompt: str) -> str:
+        redactions = self.redactions_for(member_id)
+        redacted = prompt
+        for pattern in redactions:
+            paths = list(self.base_dir.glob(pattern))
+            if pattern.endswith("/**"):
+                root = self.base_dir / pattern[:-3]
+                if root.exists():
+                    paths.extend(root.rglob("*"))
+            for path in paths:
+                if not path.is_file():
+                    continue
+                try:
+                    secret_text = path.read_text(encoding="utf-8")
+                except UnicodeDecodeError:
+                    continue
+                if not secret_text.strip() or len(secret_text) > 1_000_000:
+                    continue
+                marker = f"[redacted:{path.relative_to(self.base_dir).as_posix()}]"
+                redacted = redacted.replace(secret_text, marker)
+                for line in secret_text.splitlines():
+                    stripped = line.strip()
+                    if len(stripped) >= 8:
+                        redacted = redacted.replace(stripped, marker)
+        return redacted
+
+    def ensure_consent(self, member_id: str) -> None:
+        member = self.member(member_id)
+        if member.get("local"):
+            return
+        matching = [
+            entry
+            for entry in self.spec.get("privacy", {}).get("egress", [])
+            if entry.get("to") == member_id and entry.get("consent") == "required"
+        ]
+        if not matching:
+            return
+        if self.state.get("consent", {}).get(member_id):
+            return
+        sends = sorted({item for entry in matching for item in entry.get("sends", [])})
+        redactions = sorted({item for entry in matching for item in entry.get("redact", [])})
+        print()
+        print(f"Looper is about to send {', '.join(sends) or 'context'} to {member_id}.")
+        print(f"CLI: {member.get('cli')} / model: {member.get('model', 'default')}")
+        print(f"Redactions: {', '.join(redactions) or '(none)'}")
+        answer = input("Type 'yes' to consent to this first send: ").strip().lower()
+        if answer != "yes":
+            self.save_state(status="blocked", failure=f"consent_refused:{member_id}")
+            raise RunnerError(f"Consent refused for {member_id}")
+        consent = dict(self.state.get("consent", {}))
+        consent[member_id] = {"granted_at": utc_now(), "sends": sends, "redact": redactions}
+        self.save_state(consent=consent)
+
+    def gather_context(self) -> str:
+        goal = self.spec["goal"]
+        chunks: list[str] = []
+        for index, source in enumerate(goal.get("context_sources", []), start=1):
+            self.enforce_wall_clock()
+            if "file" in source:
+                path = relative_to_base(source["file"], self.base_dir)
+                if is_redacted(path, self.base_dir, [".env", ".env.*", "secrets/**", "**/*.key"]):
+                    chunks.append(f"## Context source {index}: {source['file']}\n[redacted]\n")
+                    self.append_log("context", source=source["file"], status="redacted")
+                elif path.exists():
+                    chunks.append(f"## Context source {index}: {source['file']}\n{path.read_text(encoding='utf-8')}\n")
+                    self.append_log("context", source=source["file"], status="read")
+                else:
+                    chunks.append(f"## Context source {index}: {source['file']}\n[missing]\n")
+                    self.append_log("context", source=source["file"], status="missing")
+            elif "cmd" in source:
+                argv = ensure_argv(source["cmd"], f"context_sources[{index}].cmd")
+                result = run_argv(argv, cwd=self.base_dir, timeout_sec=int(source.get("timeout_sec", 60)))
+                chunks.append(
+                    f"## Context source {index}: {' '.join(argv)}\n"
+                    f"exit={result.returncode}\nstdout:\n{result.stdout}\nstderr:\n{result.stderr}\n"
+                )
+                self.append_log("context_cmd", argv=argv, returncode=result.returncode)
+        context = "\n".join(chunks).strip()
+        write_text(self.workspace / "context.md", context or "No context sources configured.")
+        return context
+
+    def host_prompt(self, phase: str, artifact: str = "", review: str = "") -> str:
+        goal = self.spec["goal"]
+        if phase == "plan":
+            return (
+                "Draft plan.md for this loop.\n\n"
+                f"Goal:\n{goal['statement']}\n\n"
+                f"Definition of done:\n{goal['definition_of_done']}\n\n"
+                f"Context:\n{(self.workspace / 'context.md').read_text(encoding='utf-8')}\n"
+            )
+        if phase == "delivery":
+            return (
+                "Write the next delivery artifact for this loop.\n\n"
+                f"Goal:\n{goal['statement']}\n\n"
+                f"Definition of done:\n{goal['definition_of_done']}\n\n"
+                f"Plan:\n{(self.workspace / 'plan.md').read_text(encoding='utf-8')}\n"
+            )
+        if phase == "revise":
+            return (
+                "Revise the artifact to address the review. Return only the revised artifact.\n\n"
+                f"Artifact:\n{artifact}\n\nReview:\n{review}\n"
+            )
+        raise RunnerError(f"Unknown host phase: {phase}")
+
+    def run_host(self, phase: str, target: Path, artifact: str = "", review: str = "") -> None:
+        self.enforce_wall_clock()
+        self.append_log("host_start", phase=phase, target=target.name)
+        output = call_model(self.spec["host"], self.host_prompt(phase, artifact, review), self.base_dir)
+        write_text(target, output)
+        self.append_log("host_done", phase=phase, target=target.name)
+
+    def run_programmatic(self, criterion: dict[str, Any]) -> dict[str, Any]:
+        argv = ensure_argv(criterion["check"], f"{criterion['id']}.check")
+        result = run_argv(argv, cwd=self.base_dir, timeout_sec=int(criterion.get("timeout_sec", 300)))
+        expect = criterion.get("expect")
+        passed = False
+        if expect == "exit_zero":
+            passed = result.returncode == 0
+        elif expect == "exit_nonzero":
+            passed = result.returncode != 0
+        elif expect == "stdout_contains":
+            passed = criterion.get("contains", "") in result.stdout
+        self.append_log(
+            "programmatic_check",
+            criterion=criterion["id"],
+            passed=passed,
+            returncode=result.returncode,
+        )
+        return {
+            "id": criterion["id"],
+            "type": "programmatic",
+            "passed": passed,
+            "returncode": result.returncode,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+        }
+
+    def judge_prompt(
+        self,
+        gate_name: str,
+        artifact_label: str,
+        artifact_text: str,
+        criteria: list[dict[str, Any]],
+    ) -> str:
+        rubric_lines = []
+        for criterion in criteria:
+            if criterion["type"] == "judge":
+                rubric_lines.append(f"- {criterion['id']}: {criterion['rubric']}")
+            elif criterion["type"] == "programmatic":
+                rubric_lines.append(f"- {criterion['id']}: programmatic check result is included below.")
+            elif criterion["type"] == "human":
+                rubric_lines.append(f"- {criterion['id']}: human signoff is required separately.")
+        return (
+            "You are the Looper judge. Return only a fenced JSON object with keys "
+            "verdict, blocking_issues, confidence, and notes. verdict must be pass or revise.\n\n"
+            f"Gate: {gate_name}\n"
+            f"Artifact: {artifact_label}\n\n"
+            "Criteria:\n" + "\n".join(rubric_lines) + "\n\n"
+            f"Artifact content:\n{artifact_text}\n"
+        )
+
+    def run_judge(
+        self,
+        member_id: str,
+        gate_name: str,
+        artifact_label: str,
+        artifact_text: str,
+        criteria: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        self.ensure_consent(member_id)
+        output = call_model(
+            self.member(member_id),
+            self.redact_prompt_for_member(
+                member_id,
+                self.judge_prompt(gate_name, artifact_label, artifact_text, criteria),
+            ),
+            self.base_dir,
+        )
+        verdict = parse_judge_output(output)
+        verdict["member"] = member_id
+        self.append_log("judge_verdict", gate=gate_name, member=member_id, verdict=verdict.get("verdict"))
+        return verdict
+
+    def run_reviewers(
+        self,
+        gate_name: str,
+        artifact_label: str,
+        artifact_text: str,
+        member_ids: list[str],
+    ) -> list[str]:
+        notes = []
+        for member_id in member_ids:
+            member = self.member(member_id)
+            if member.get("role") != "reviewer":
+                continue
+            self.ensure_consent(member_id)
+            prompt = (
+                "You are a Looper reviewer. Return concise blocking and non-blocking notes. "
+                "Do not return a verdict.\n\n"
+                f"Gate: {gate_name}\nArtifact: {artifact_label}\n\n{artifact_text}\n"
+            )
+            prompt = self.redact_prompt_for_member(member_id, prompt)
+            notes.append(f"## {member_id}\n\n{call_model(member, prompt, self.base_dir)}")
+            self.append_log("reviewer_notes", gate=gate_name, member=member_id)
+        return notes
+
+    def human_check(self, criterion: dict[str, Any]) -> dict[str, Any]:
+        print()
+        print(criterion["prompt"])
+        answer = input("Type 'pass' to approve, anything else to request revision: ").strip().lower()
+        return {
+            "id": criterion["id"],
+            "type": "human",
+            "passed": answer == PASS,
+            "notes": "approved" if answer == PASS else "human requested revision",
+        }
+
+    def run_gate(self, gate_name: str, artifact_path: Path, artifact_label: str) -> bool:
+        gate = self.spec["gates"][gate_name]
+        criteria = self.criteria(gate.get("criteria", []))
+        max_revisions = int(gate.get("max_revisions", 0))
+        revision = 0
+        self.append_log("gate_start", gate=gate_name, artifact=artifact_label)
+
+        while True:
+            self.enforce_wall_clock()
+            artifact_text = artifact_path.read_text(encoding="utf-8")
+            review_parts: list[str] = []
+            failures: list[str] = []
+
+            for criterion in criteria:
+                if criterion["type"] == "programmatic":
+                    result = self.run_programmatic(criterion)
+                    review_parts.append(f"## Programmatic {criterion['id']}\n\n```json\n{json.dumps(result, indent=2)}\n```")
+                    if not result["passed"]:
+                        failures.append(f"Programmatic check failed: {criterion['id']}")
+                elif criterion["type"] == "human":
+                    result = self.human_check(criterion)
+                    review_parts.append(f"## Human {criterion['id']}\n\n{result['notes']}")
+                    if not result["passed"]:
+                        failures.append(f"Human check failed: {criterion['id']}")
+
+            reviewer_notes = self.run_reviewers(
+                gate_name,
+                artifact_label,
+                artifact_text,
+                list(gate.get("members", [])),
+            )
+            review_parts.extend(reviewer_notes)
+
+            policy = gate.get("verdict_policy")
+            verdict: dict[str, Any] | None = None
+            if policy == "revise_until_clean" and not failures:
+                source = gate.get("verdict_source")
+                if source == "human":
+                    answer = input(f"Type 'pass' if {artifact_label} is clean: ").strip().lower()
+                    verdict = {
+                        "verdict": PASS if answer == PASS else REVISE,
+                        "blocking_issues": [] if answer == PASS else ["human requested revision"],
+                        "confidence": 1.0,
+                        "notes": "human verdict",
+                    }
+                else:
+                    verdict = self.run_judge(source, gate_name, artifact_label, artifact_text, criteria)
+                review_parts.append(f"## Verdict\n\n```json\n{json.dumps(verdict, indent=2)}\n```")
+                if verdict.get("verdict") == REVISE:
+                    failures.extend(verdict.get("blocking_issues") or ["Judge requested revision"])
+
+            if policy == "fixed_passes":
+                if failures:
+                    pass
+                elif revision >= max_revisions:
+                    return True
+                else:
+                    failures.append("fixed_passes reviewer pass")
+
+            if not failures:
+                self.save_state(status=f"{gate_name}_passed", **{gate_name: {"passed_at": utc_now()}})
+                self.append_log("gate_passed", gate=gate_name, artifact=artifact_label)
+                return True
+
+            review_text = "\n\n".join(review_parts + ["## Blocking Issues", "\n".join(f"- {item}" for item in failures)])
+            review_path = self.workspace / f"review-{gate_name}-{revision + 1}.md"
+            write_text(review_path, review_text)
+            self.append_log("gate_blocked", gate=gate_name, review=review_path.name, failures=failures)
+
+            if self.no_progress_reached(gate_name, failures):
+                return False
+
+            if revision >= max_revisions:
+                self.save_state(
+                    status="failed",
+                    failure=f"{gate_name}_max_revisions_reached",
+                    last_review=str(review_path),
+                )
+                self.append_log("stop", reason=f"{gate_name}_max_revisions_reached")
+                return False
+
+            revised = call_model(
+                self.spec["host"],
+                self.host_prompt("revise", artifact_text, review_text),
+                self.base_dir,
+            )
+            write_text(artifact_path, revised)
+            revision += 1
+            self.save_state(status=f"{gate_name}_revision_{revision}", last_review=str(review_path))
+            self.append_log("revision", gate=gate_name, revision=revision, artifact=artifact_label)
+
+    def run(self) -> int:
+        self.save_state(status="running")
+        self.append_log("run_start", spec=str(self.spec_path))
+        self.gather_context()
+
+        plan_path = self.workspace / "plan.md"
+        if not plan_path.exists():
+            self.run_host("plan", plan_path)
+        if not self.run_gate("plan_gate", plan_path, "plan.md"):
+            return 1
+
+        max_iterations = int(self.spec["loop_control"]["max_iterations"])
+        for iteration in range(1, max_iterations + 1):
+            self.enforce_wall_clock()
+            self.save_state(status="delivery", iteration=iteration)
+            delivery_path = self.workspace / f"delivery-{iteration}.md"
+            self.run_host("delivery", delivery_path)
+            if self.run_gate("delivery_gate", delivery_path, delivery_path.name):
+                self.save_state(status="passed", final_delivery=str(delivery_path), completed_at=utc_now())
+                self.append_log("run_passed", final_delivery=str(delivery_path))
+                print(f"Looper run passed. Final delivery: {delivery_path}")
+                return 0
+
+        self.save_state(status="failed", failure="max_iterations_reached")
+        self.append_log("stop", reason="max_iterations_reached")
+        return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run a compiled Looper loop.")
+    parser.add_argument(
+        "spec_path",
+        nargs="?",
+        type=Path,
+        default=Path(__file__).with_name("loop.resolved.json"),
+        help="Path to loop.resolved.json (defaults to the file next to run-loop.py).",
+    )
+    args = parser.parse_args(sys.argv[1:] if argv is None else argv)
+    try:
+        return Runner(args.spec_path).run()
+    except RunnerError as exc:
+        print(f"run-loop: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
--- a/.github/skills/okf-open-knowledge-format/SKILL.md
+++ b/.github/skills/okf-open-knowledge-format/SKILL.md
@@ -0,0 +1,424 @@
+---
+name: okf-open-knowledge-format
+description: >
+  Create, validate, and enrich Open Knowledge Format (OKF) bundles — the open
+  spec for representing organizational knowledge as markdown files with YAML
+  frontmatter. Use when the user mentions 'OKF', 'Open Knowledge Format',
+  'knowledge bundle', 'OKF bundle', 'create a knowledge base for agents',
+  'validate OKF', 'convert to OKF', 'enrich knowledge docs', 'agent-readable
+  knowledge', 'LLM wiki', 'knowledge catalog', 'kcmd', or wants to structure
+  knowledge as markdown files for AI agent consumption. Also use when the user
+  has a directory of markdown files and wants to make them interoperable or
+  conformant with the OKF standard. Even for simple requests like 'make this
+  folder OKF conformant' — the skill has critical structural rules the agent
+  needs.
+metadata:
+  author: ft.ia.br
+  version: "1.1"
+  date: 2026-06-17
+  repository: https://github.com/fabricioctelles/skills
+  license: Apache-2.0
+  category: library-and-api-reference
+---
+
+# Open Knowledge Format (OKF)
+
+OKF is a vendor-neutral, open spec (v0.1, announced June 12, 2026 by Sam McVeety & Amir Hormati at Google Cloud) for representing knowledge as a directory of markdown files with YAML frontmatter. No SDK required — if you can `cat` a file, you can read OKF.
+
+It formalizes the "LLM Wiki" pattern ([Karpathy's gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)) into an interoperable format: wikis written by different producers can be consumed by different agents without translation.
+
+For the full spec, see [references/spec-v01.md](references/spec-v01.md).
+
+### Design Principles
+
+1. **Minimally opinionated** — Only `type` is required. The spec defines interoperability surface, not content model.
+2. **Producer/consumer independence** — Who writes and who reads are decoupled. Human-authored bundles feed agents; LLM-generated bundles are browsed by humans.
+3. **Format, not platform** — No cloud, SDK, or vendor dependency. Value comes from how many parties speak it.
+
+---
+
+## Key Terminology
+
+- **Bundle** — A directory tree of `.md` files. The unit of distribution (git repo, tarball, or subdirectory).
+- **Concept** — One markdown file = one unit of knowledge (table, metric, playbook, API, etc.)
+- **Concept ID** — File path within the bundle, minus `.md` suffix. Example: `tables/users.md` → ID `tables/users`
+- **Frontmatter** — YAML block between `---` delimiters at file top.
+- **Body** — Everything after the frontmatter. Standard markdown.
+- **Link** — Standard markdown link expressing a relationship between concepts.
+- **Citation** — Link to an external source backing a claim in the body.
+
+---
+
+## Quick Reference — Frontmatter Fields
+
+| Field | Required? | Description |
+|-------|-----------|-------------|
+| `type` | **YES** | Kind of concept (free-form string, e.g. `BigQuery Table`, `Metric`, `Playbook`, `API Endpoint`) |
+| `title` | Recommended | Human-readable display name |
+| `description` | Recommended | One-sentence summary |
+| `resource` | Recommended | URI identifying the underlying asset (omit for abstract concepts) |
+| `tags` | Optional | YAML list for cross-cutting categorization |
+| `timestamp` | Optional | ISO 8601 datetime of last meaningful change |
+
+Additional producer-defined keys are allowed. Never reject unknown fields.
+
+## Reserved Filenames
+
+| File | Purpose | Has frontmatter? |
+|------|---------|-----------------|
+| `index.md` | Directory listing for progressive disclosure | NO* |
+| `log.md` | Change history, newest first | NO |
+
+*Exception: bundle-root `index.md` MAY have frontmatter with `okf_version: "0.1"` to declare spec version.
+
+## Conventional Body Headings
+
+| Heading | When to use |
+|---------|-------------|
+| `# Schema` | Data assets — describe columns/fields |
+| `# Examples` | Show concrete usage (code blocks, queries) |
+| `# Citations` | List external sources backing claims (numbered) |
+
+---
+
+## Create a Bundle
+
+When the user wants to create an OKF bundle from scratch:
+
+### 1. Determine scope and structure
+
+Ask: What knowledge are we capturing? (tables, metrics, APIs, playbooks, etc.)
+Organize into a directory tree that makes sense for the domain.
+
+### 2. Create concept documents
+
+Each concept = one `.md` file. Minimal conformant example:
+
+```markdown
+---
+type: Metric
+title: Monthly Recurring Revenue
+description: Sum of all active subscription revenue normalized to monthly.
+tags: [revenue, saas]
+timestamp: 2026-06-13T10:00:00Z
+---
+
+# Monthly Recurring Revenue (MRR)
+
+## Definition
+
+Sum of all active subscriptions normalized to a monthly amount.
+Excludes one-time fees and overages.
+
+## Formula
+
+`MRR = Σ(active_subscription_monthly_value)`
+
+## Related
+
+- [Churn Rate](./churn.md) uses MRR as denominator
+- [ARR](./arr.md) = MRR × 12
+```
+
+For more examples across domains, see [references/examples.md](references/examples.md).
+
+### 3. Cross-link concepts
+
+Use standard markdown links. Two forms:
+
+- **Absolute** (bundle-relative, starts with `/`): `[customers](/tables/customers.md)` — **preferred** (stable when files move)
+- **Relative**: `[churn](./churn.md)`
+
+Links assert relationships. The kind of relationship is conveyed by surrounding prose, not by the link syntax. Broken links are explicitly permitted — they represent knowledge not yet written.
+
+### 4. Generate index.md
+
+Place in any directory for progressive disclosure. No frontmatter. Format:
+
+```markdown
+# Metrics
+
+- [MRR](./mrr.md) - Monthly recurring revenue
+- [Churn](./churn.md) - Monthly churn rate
+- [NPS](./nps.md) - Net Promoter Score
+```
+
+Entries should include the description from the linked concept's frontmatter.
+
+### 5. Generate log.md (optional)
+
+Chronological change history, newest first, ISO 8601 date headings:
+
+```markdown
+# Update Log
+
+## 2026-06-13
+- **Creation**: Added MRR, Churn, and NPS metrics.
+- **Creation**: Established directory structure.
+
+## 2026-06-10
+- **Initialization**: Bundle created.
+```
+
+The bold leading word (`**Update**`, `**Creation**`, `**Deprecation**`) is convention, not requirement.
+
+### 6. Declare version (optional)
+
+Bundle-root `index.md` may include frontmatter declaring the spec version:
+
+```markdown
+---
+okf_version: "0.1"
+---
+
+# My Knowledge Bundle
+
+- [Tables](./tables/) - Database tables
+- [Metrics](./metrics/) - Business KPIs
+```
+
+This is the only place frontmatter is permitted in an `index.md`.
+
+### 7. Distribution
+
+A bundle can be distributed as:
+- A **git repository** (recommended — history, attribution, diffs)
+- A tarball or zip archive
+- A subdirectory within a larger repository
+
+### 8. Verify conformance
+
+Three rules — all must pass:
+1. Every non-reserved `.md` file has parseable YAML frontmatter
+2. Every frontmatter has a non-empty `type` field
+3. Reserved files (`index.md`, `log.md`) follow their defined structure when present
+
+---
+
+## Validate a Bundle
+
+### Preferred: okflint (when available)
+
+[okflint](https://github.com/mattdav/okflint) is a dedicated Python linter for OKF bundles with 18 rules across 3 tiers (OKF core, profile, hygiene). If installed, always prefer it over the built-in bash script.
+
+**Agent behavior:** Before validating, check if okflint is installed (`command -v okflint`). If NOT installed, ask the user:
+
+> "okflint (linter dedicado para OKF com 18 regras, profiles via manifesto e suporte a wikilinks) não está instalado. Quer que eu instale? Opções:
+> 1. `uv tool install okflint` (recomendado, isolado)
+> 2. `pip install okflint`
+> 3. Seguir sem ele (validação básica com o script bash embutido)"
+
+If the user agrees to install:
+
+```bash
+# Option 1: uv (recommended — installs isolated, no venv needed)
+uv tool install okflint
+
+# Option 2: pip (installs in current environment)
+pip install okflint
+
+# Verify installation
+okflint --version
+```
+
+After installation (or if already available):
+
+```bash
+# Full validation with manifest (if okf-base.yaml exists)
+if [ -f okf-base.yaml ]; then
+  okflint validate --manifest okf-base.yaml ./bundle/
+else
+  # Core OKF validation only (no manifest needed)
+  okflint validate ./bundle/
+fi
+```
+
+**okflint advantages over the built-in script:**
+- Manifest-driven profiles (enforce custom required fields, status vocabularies, per-type constraints)
+- Wikilink resolution against full Obsidian vault
+- JSON output (`--json`) for CI pipeline parsing
+- Detects broken markdown links and ambiguous wikilinks
+- Exit codes: `0` = pass, `1` = conformance failure, `2` = bad manifest
+
+### Fallback: built-in bash script
+
+When okflint is not installed, use [scripts/validate.sh](scripts/validate.sh) which checks the 3 core conformance rules.
+
+When asked to validate, check the 3 conformance rules. Report:
+
+```
+✅ PASS: 12/12 concept files have valid frontmatter with type field
+✅ PASS: index.md follows list structure (no frontmatter)
+✅ PASS: log.md uses ISO 8601 date headings, newest first
+
+⚠  WARNING: 3 files missing 'description' field (recommended)
+⚠  WARNING: 2 broken cross-links (permitted but worth noting)
+```
+
+For a script-based check, see [scripts/validate.sh](scripts/validate.sh).
+
+### Errors (conformance failures)
+
+- `E1`: File `{path}` has no YAML frontmatter
+- `E2`: File `{path}` has frontmatter but no `type` field (or empty)
+- `E3`: Reserved file `{path}` has unexpected structure
+
+### Warnings (non-blocking, spec allows these)
+
+- `W1`: Missing recommended field `title` or `description`
+- `W2`: Broken cross-link `{link}` in `{file}`
+- `W3`: No `timestamp` field
+- `W4`: No `index.md` in directory `{dir}`
+- `W5`: `log.md` dates not in ISO 8601 format
+
+Consumers MUST NOT reject a bundle because of: missing optional fields, unknown type values, unknown frontmatter keys, broken links, or missing index files.
+
+---
+
+## Enrich Concepts
+
+When the user has existing OKF concepts that need enrichment:
+
+### Add schema section
+
+For data assets, add `# Schema` with a columns table:
+
+```markdown
+# Schema
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `order_id` | STRING | Unique identifier |
+| `customer_id` | STRING | FK to [customers](/tables/customers.md) |
+```
+
+### Add examples section
+
+For APIs, queries, or tools, add `# Examples` with fenced code blocks showing usage.
+
+### Add citations
+
+When claims reference external sources, add `# Citations` at the bottom, numbered:
+
+```markdown
+# Citations
+
+[1] [Official docs](https://example.com/docs)
+[2] [Internal runbook](https://wiki.internal/quality)
+```
+
+Citations may be absolute URLs, bundle-relative paths, or paths into a `references/` subdirectory.
+
+### Add cross-links
+
+Weave links into natural prose. Don't create a standalone "links" section — express relationships in context where they're meaningful.
+
+### Fill recommended fields
+
+If `title`, `description`, `tags`, or `timestamp` are missing, add them. Derive values from body content when possible.
+
+### Enrichment workflow reference
+
+The official enrichment agent follows this pattern — apply the same logic manually:
+1. Start with metadata-only docs (just frontmatter + minimal body)
+2. Add schema/structure from source system
+3. Add citations from authoritative documentation
+4. Weave cross-links based on discovered relationships (FKs, shared tags, join paths)
+5. Generate `index.md` files for progressive disclosure
+
+---
+
+## Convert Sources to OKF
+
+For detailed conversion guides, see [references/conversion.md](references/conversion.md).
+
+### Quick rules
+
+**Notion export:** Properties → frontmatter. Remove UUID suffixes from filenames. Convert Notion links → relative markdown links.
+
+**Obsidian vault:** Convert `[[wikilinks]]` → `[title](./file.md)`. Ensure `type` field exists. Move inline `#tags` to frontmatter.
+
+**CSV/spreadsheet:** Each row = one concept. Map columns to frontmatter fields. First column = filename.
+
+---
+
+## Guardrails
+
+1. **NEVER invent data.** If you don't know the correct `type`, ask. If you don't have schema info, leave it out. No fabricated URLs or column names.
+2. **Preserve unknown fields.** OKF explicitly allows extension. Don't delete fields you don't recognize.
+3. **Don't impose taxonomy.** Type values are free-form strings. Suggest descriptive values but never reject a bundle for having unexpected types.
+4. **Broken links are OK.** The spec explicitly permits them — they represent not-yet-written knowledge.
+5. **Minimal by default.** Generate only `type` (required) + recommended fields that are warranted. Don't pad with empty values.
+6. **Ask before assuming.** If the domain is unclear, ask what types and structure make sense.
+
+---
+
+## Serve via Google Cloud Knowledge Catalog
+
+Google Cloud's Knowledge Catalog **natively ingests OKF bundles** and serves them to agents. This is the enterprise path — optional but powerful.
+
+### kcmd CLI (Metadata as Code)
+
+`kcmd` is a bidirectional sync tool between OKF-like local metadata and Knowledge Catalog. Think "git for metadata."
+
+```bash
+# Initialize from BigQuery dataset
+kcmd init --bigquery-dataset <project>.<dataset>
+
+# Pull current state from catalog
+kcmd pull
+
+# Push local changes
+kcmd push --dry-run
+kcmd push
+```
+
+Also ships as an **MCP server** for agent integration:
+
+```json
+{
+  "mcpServers": {
+    "kc-mac": {
+      "command": "kcmd",
+      "args": ["mcp", "--path", "/path/to/root"]
+    }
+  }
+}
+```
+
+MCP tools: `pull`, `push`, `list-entries`, `lookup-entry`, `modify-entry`.
+
+### Reference Enrichment Agent
+
+The official enrichment agent (Python, ADK, Gemini) auto-generates OKF bundles from BigQuery metadata. Two-pass architecture:
+
+1. **BQ pass** — one OKF doc per table/view from metadata
+2. **Web pass** — LLM crawls seed URLs and for each page decides to:
+   - **(a) Enrich** existing concepts with citations/schemas
+   - **(b) Mint** a new `references/<slug>` doc
+   - **(c) Skip** irrelevant content
+
+Controls: `--web-seed-file`, `--web-max-pages`, `--web-allowed-host`, `--no-web`.
+
+**When to mention this to users:** If they're enriching BigQuery datasets, point them to the [reference agent](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf). If they want enterprise catalog integration, point to [kcmd](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox/mdcode) and the [ingest demo](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox/mdcode/demo).
+
+---
+
+## Output Format
+
+When creating a bundle, present results as:
+
+1. **Directory tree** showing the full structure
+2. **Each file's content** in fenced code blocks
+3. **Conformance check** confirming the bundle passes the 3 rules
+
+```
+saas-metrics/
+├── index.md
+├── log.md
+├── mrr.md
+├── churn.md
+└── nps.md
+```
+
+Then show each file, then confirm: "Bundle is OKF v0.1 conformant ✅"
--- a/.github/skills/okf-open-knowledge-format/references/conversion.md
+++ b/.github/skills/okf-open-knowledge-format/references/conversion.md
@@ -0,0 +1,141 @@
+# Converting Sources to OKF
+
+Guides for transforming existing knowledge into conformant OKF bundles.
+
+---
+
+## From Notion Export
+
+Notion exports as markdown with properties in YAML-like format.
+
+### Steps
+
+1. **Export** from Notion as Markdown & CSV
+2. **Clean filenames** — remove UUID suffixes (`Page Name abc123def.md` → `page-name.md`)
+3. **Map properties to frontmatter:**
+
+| Notion Property | OKF Field |
+|-----------------|-----------|
+| Type (select) | `type` (required) |
+| Name | `title` |
+| Tags (multi-select) | `tags` |
+| Last Edited | `timestamp` |
+| URL | `resource` |
+
+4. **Convert links** — Notion uses `[Page Name](Page%20Name%20abc123def.md)`. Convert to clean relative paths: `[Page Name](./page-name.md)`
+5. **Remove Notion artifacts** — empty toggle blocks, breadcrumb headers, cover image references
+6. **Add missing `type` field** — if Notion had no "Type" property, ask the user what type to assign
+
+### Edge cases
+
+- Notion databases: each row becomes a concept. Database title becomes the directory name.
+- Nested pages: respect the hierarchy. Child pages go in subdirectories.
+- Inline databases: flatten into a list in the parent concept's body.
+- Notion formulas/rollups: drop them — they don't translate to static markdown.
+
+---
+
+## From Obsidian Vault
+
+Obsidian vaults are already close to OKF. Main differences: wikilinks and potentially missing `type` field.
+
+### Steps
+
+1. **Convert wikilinks to standard links:**
+   - `[[Note Name]]` → `[Note Name](./note-name.md)`
+   - `[[Note Name|Display Text]]` → `[Display Text](./note-name.md)`
+   - `[[Note Name#Heading]]` → `[Note Name](./note-name.md#heading)`
+
+2. **Ensure `type` field exists** in every frontmatter block. Common mappings:
+
+| Obsidian pattern | Suggested OKF type |
+|------------------|--------------------|
+| Daily notes | `Log` |
+| MOC / index note | Convert to `index.md` (reserved file) |
+| Permanent notes | `Reference` |
+| Literature notes | `Reference` |
+| Project notes | `Playbook` or domain-specific |
+
+3. **Convert tags:**
+   - Inline `#tag` → move to frontmatter `tags: [tag]`
+   - Nested `#parent/child` → flatten to `tags: [parent, child]` or keep as `parent/child`
+
+4. **Handle embeds:**
+   - `![[Note]]` — convert to a regular link or inline the content
+   - `![[image.png]]` — keep as standard markdown image `![](./image.png)`
+
+5. **Remove Obsidian-specific syntax:**
+   - `%%comments%%` → remove
+   - `> [!callout]` → convert to blockquote or heading
+   - Dataview queries → remove (dynamic, not portable)
+
+### What to keep as-is
+
+- Standard markdown formatting (headings, lists, tables, code blocks)
+- Existing YAML frontmatter (just add `type` if missing)
+- Standard markdown links (already OKF-compatible)
+- Mermaid diagrams (standard markdown fenced blocks)
+
+---
+
+## From CSV / Spreadsheet
+
+Each row becomes one concept document.
+
+### Steps
+
+1. **Identify column mapping:**
+
+| Column role | Maps to |
+|-------------|---------|
+| Primary identifier / name | Filename (slugified) |
+| Category / kind | `type` field |
+| Short description | `description` field |
+| Tags / labels | `tags` field |
+| URL / link | `resource` field |
+| Last modified date | `timestamp` field |
+| All other columns | Body content (as table or sections) |
+
+2. **Generate one `.md` per row:**
+
+```markdown
+---
+type: {category_column}
+title: {name_column}
+description: {description_column}
+tags: [{tag1}, {tag2}]
+timestamp: {date_column}T00:00:00Z
+---
+
+# {name_column}
+
+| Field | Value |
+|-------|-------|
+| Column3 | {value} |
+| Column4 | {value} |
+```
+
+3. **Generate index.md** from the full list:
+
+```markdown
+# {Sheet Name}
+
+- [{row1_name}](./{row1_slug}.md) - {row1_description}
+- [{row2_name}](./{row2_slug}.md) - {row2_description}
+```
+
+4. **Generate log.md** with creation entry:
+
+```markdown
+# Update Log
+
+## {today_iso8601}
+- **Creation**: Generated {N} concepts from spreadsheet import.
+```
+
+### Edge cases
+
+- Empty cells: omit the field entirely (don't write empty strings)
+- Multi-value cells (comma-separated): parse into YAML list for `tags`
+- Very long text cells: put in body as a section, not in frontmatter
+- Duplicate names: append a disambiguator (e.g., `widget-v1.md`, `widget-v2.md`)
--- a/.github/skills/okf-open-knowledge-format/references/examples.md
+++ b/.github/skills/okf-open-knowledge-format/references/examples.md
@@ -0,0 +1,302 @@
+# OKF Bundle Examples
+
+Three complete, conformant bundles across different domains.
+
+---
+
+## 1. E-commerce Analytics
+
+```
+ecommerce/
+├── index.md
+├── tables/
+│   ├── index.md
+│   ├── orders.md
+│   └── customers.md
+└── metrics/
+    ├── index.md
+    └── gross-revenue.md
+```
+
+### tables/orders.md
+
+```markdown
+---
+type: BigQuery Table
+title: Orders
+description: One row per completed customer order across all channels.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
+tags: [sales, orders, revenue]
+timestamp: 2026-05-28T14:30:00Z
+---
+
+# Schema
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `order_id` | STRING | Globally unique order identifier |
+| `customer_id` | STRING | FK to [customers](./customers.md) |
+| `total_usd` | NUMERIC | Order total in US dollars |
+| `placed_at` | TIMESTAMP | When the customer submitted the order |
+| `channel` | STRING | Acquisition channel (web, mobile, pos) |
+
+# Joins
+
+- Join with [customers](./customers.md) on `customer_id`
+- Referenced by [gross revenue](/metrics/gross-revenue.md) metric
+
+# Citations
+
+[1] [BigQuery schema docs](https://cloud.google.com/bigquery/docs/schemas)
+```
+
+### tables/customers.md
+
+```markdown
+---
+type: BigQuery Table
+title: Customers
+description: One row per registered customer with profile and lifetime data.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=customers
+tags: [sales, customers]
+timestamp: 2026-05-28T14:30:00Z
+---
+
+# Schema
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `customer_id` | STRING | Primary key |
+| `email` | STRING | Customer email (hashed in prod) |
+| `created_at` | TIMESTAMP | Registration date |
+| `ltv_usd` | NUMERIC | Lifetime value in USD |
+
+# Joins
+
+- Referenced by [orders](./orders.md) on `customer_id`
+```
+
+### metrics/gross-revenue.md
+
+```markdown
+---
+type: Metric
+title: Gross Revenue
+description: Total revenue before refunds and discounts.
+tags: [revenue, finance, kpi]
+timestamp: 2026-05-28T14:30:00Z
+---
+
+# Definition
+
+Sum of `total_usd` from [orders](/tables/orders.md) for a given period.
+Does not subtract refunds — see Net Revenue for that.
+
+# SQL
+
+```sql
+SELECT DATE_TRUNC(placed_at, MONTH) as month,
+       SUM(total_usd) as gross_revenue
+FROM `acme.sales.orders`
+GROUP BY 1
+```
+
+# Related
+
+- Source table: [orders](/tables/orders.md)
+- Counterpart: Net Revenue (gross minus refunds)
+```
+
+### index.md (root)
+
+```markdown
+# E-commerce Analytics Bundle
+
+- [Tables](./tables/) - Database tables powering the analytics stack
+- [Metrics](./metrics/) - Business KPIs derived from tables
+```
+
+---
+
+## 2. SaaS Incident Playbooks
+
+```
+incidents/
+├── index.md
+├── alerts/
+│   ├── index.md
+│   ├── api-latency-p99.md
+│   └── db-connections.md
+└── runbooks/
+    ├── index.md
+    └── escalate-incident.md
+```
+
+### alerts/api-latency-p99.md
+
+```markdown
+---
+type: Alert
+title: API Latency P99 > 2s
+description: Fires when 99th percentile API latency exceeds 2 seconds for 5 minutes.
+tags: [api, latency, critical]
+severity: critical
+timestamp: 2026-06-01T09:00:00Z
+---
+
+# Trigger Condition
+
+```promql
+histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 2
+```
+
+# Impact
+
+Users experience timeouts. Downstream services may cascade-fail.
+
+# Response
+
+1. Check [DB connections alert](./db-connections.md) — often the root cause
+2. Follow [escalation runbook](/runbooks/escalate-incident.md) if not resolved in 10 min
+3. Check deployment log for recent changes
+
+# Citations
+
+[1] [SLA definition](https://wiki.internal/sla/api-latency)
+```
+
+### runbooks/escalate-incident.md
+
+```markdown
+---
+type: Runbook
+title: Escalate Incident
+description: Steps to escalate when on-call cannot resolve within SLA.
+tags: [oncall, incident, escalation]
+timestamp: 2026-06-01T09:00:00Z
+---
+
+# When to Escalate
+
+- Alert not resolved within 10 minutes
+- Customer-facing impact confirmed
+- Multiple alerts firing simultaneously
+
+# Steps
+
+1. Post in #incidents Slack channel with alert link
+2. Page the secondary on-call (PagerDuty)
+3. If P1: page Engineering Manager
+4. Start incident document from template
+5. Update status page if customer-facing
+
+# Contacts
+
+| Role | Who | Method |
+|------|-----|--------|
+| Secondary on-call | Rotation | PagerDuty |
+| Eng Manager | @manager | Slack DM |
+| Infra lead | @infra-lead | Slack DM |
+```
+
+---
+
+## 3. API Documentation
+
+```
+api/
+├── index.md
+├── auth/
+│   ├── index.md
+│   └── oauth2-flow.md
+├── endpoints/
+│   ├── index.md
+│   └── create-order.md
+└── policies/
+    ├── index.md
+    └── rate-limits.md
+```
+
+### endpoints/create-order.md
+
+```markdown
+---
+type: API Endpoint
+title: Create Order
+description: Creates a new order for an authenticated customer.
+resource: https://api.acme.com/v2/orders
+tags: [orders, write, v2]
+method: POST
+timestamp: 2026-05-20T10:00:00Z
+---
+
+# POST /v2/orders
+
+Creates a new order. Requires [OAuth2 authentication](/auth/oauth2-flow.md).
+
+# Request
+
+```json
+{
+  "customer_id": "cust_abc123",
+  "items": [{"sku": "WIDGET-01", "quantity": 2}],
+  "idempotency_key": "unique-request-id"
+}
+```
+
+# Response (201 Created)
+
+```json
+{
+  "order_id": "ord_xyz789",
+  "status": "pending",
+  "total_usd": 49.98,
+  "created_at": "2026-05-20T10:30:00Z"
+}
+```
+
+# Errors
+
+| Code | Meaning |
+|------|---------|
+| 400 | Invalid request body |
+| 401 | Missing or invalid auth token |
+| 409 | Duplicate idempotency_key |
+| 429 | [Rate limit](/policies/rate-limits.md) exceeded |
+
+# Rate Limits
+
+Subject to [rate limiting](/policies/rate-limits.md). See `X-RateLimit-*` headers.
+```
+
+### policies/rate-limits.md
+
+```markdown
+---
+type: Policy
+title: Rate Limits
+description: Per-plan rate limits for all API endpoints.
+tags: [policy, rate-limit, api]
+timestamp: 2026-05-20T10:00:00Z
+---
+
+# Limits by Plan
+
+| Plan | Requests/min | Burst |
+|------|-------------|-------|
+| Free | 60 | 10 |
+| Pro | 600 | 100 |
+| Enterprise | 6000 | 1000 |
+
+# Response Headers
+
+Every response includes:
+- `X-RateLimit-Limit`: max requests per window
+- `X-RateLimit-Remaining`: requests left in window
+- `X-RateLimit-Reset`: Unix timestamp of window reset
+
+# When Exceeded
+
+Returns `429 Too Many Requests`. Retry after `X-RateLimit-Reset`.
+Applies to all endpoints including [create order](/endpoints/create-order.md).
+```
--- a/.github/skills/okf-open-knowledge-format/references/spec-v01.md
+++ b/.github/skills/okf-open-knowledge-format/references/spec-v01.md
@@ -0,0 +1,451 @@
+# Open Knowledge Format (OKF)
+
+**Version 0.1 — Draft**
+
+OKF is an open, human- and agent-friendly format for representing
+*knowledge* — the metadata, context, and curated insight that surrounds
+data and systems. It is designed to be authored by people, generated by
+agents, exchanged across organizations, and consumed by both.
+
+The format is intentionally minimal: a directory of markdown files with
+YAML frontmatter. There is no schema registry, no central authority, and
+no required tooling. If you can `cat` a file, you can read OKF; if you
+can `git clone` a repo, you can ship it.
+
+---
+
+## 1. Motivation
+
+The space of knowledge representation for AI agents is evolving quickly,
+and many incompatible conventions are emerging. OKF takes the position
+that knowledge is best represented in commonly accessible, established
+formats that are:
+
+- **Readable** by humans without tooling.
+- **Parseable** by agents without bespoke SDKs.
+- **Diffable** in version control.
+- **Portable** across tools, organizations, and time.
+
+The format is minimally opinionated. It standardizes only the small set
+of structural conventions needed to make a knowledge corpus
+*self-describing* — anything beyond that is left to the producer.
+
+### Goals
+
+1. Define a universal format that **enrichment agents** can write into.
+2. Inform how **consumption agents** should read and traverse it.
+3. Facilitate **exchange** of knowledge across systems and organizations.
+4. Standardize the small number of **required** fields that must be
+   present for content to be meaningfully consumed.
+
+### Non-goals
+
+- Defining a fixed taxonomy of concept types.
+- Prescribing storage, serving, or query infrastructure.
+- Replacing domain-specific schemas (Avro, Protobuf, OpenAPI, etc.) —
+  OKF *references* them; it does not subsume them.
+
+---
+
+## 2. Terminology
+
+- **Knowledge Bundle** — A self-contained, hierarchical collection of
+  knowledge documents. The unit of distribution.
+- **Concept** — A single unit of knowledge within a bundle. Represented
+  as one markdown document. May describe a tangible asset (a table, an
+  API), an abstract idea (a metric, a business process), or anything in
+  between.
+- **Concept ID** — The path of the concept's file within the bundle,
+  with the `.md` suffix removed. For example, `tables/users.md` has
+  concept ID `tables/users`.
+- **Frontmatter** — YAML metadata block delimited by `---` at the top of
+  a markdown file.
+- **Body** — Everything in the file after the frontmatter.
+- **Link** — A standard markdown link from one concept to another, used
+  to express relationships beyond the implicit parent/child hierarchy.
+- **Citation** — A link from a concept to an external source that
+  supports a claim in the body.
+
+---
+
+## 3. Bundle Structure
+
+A bundle is a directory tree of markdown files. The directory structure
+is independent of the domain — producers organize concepts however makes
+sense for the knowledge being captured.
+
+```
+path/to/bundle/
+├── index.md                      # Optional. Directory listing for progressive disclosure.
+├── log.md                        # Optional. Chronological history of updates.
+├── <concept>.md                  # A concept at the bundle root.
+└── <subdirectory>/               # Subdirectories organize concepts into groups.
+    ├── index.md
+    ├── <concept>.md
+    └── <subdirectory>/
+        └── …
+```
+
+A bundle MAY be distributed as:
+
+- A git repository (recommended — provides history, attribution, diffs).
+- A tarball or zip archive of the directory.
+- A subdirectory within a larger repository.
+
+### 3.1 Reserved filenames
+
+The following filenames have defined meaning at any level of the
+hierarchy and MUST NOT be used for concept documents:
+
+| Filename     | Purpose                                                |
+|--------------|--------------------------------------------------------|
+| `index.md`   | Directory listing. See §6.                             |
+| `log.md`     | Update history. See §7.                                |
+
+All other `.md` files are concept documents.
+
+Tags themselves remain a first-class concept — see the `tags`
+frontmatter field in §4.1. OKF does not specify a separate file format
+for aggregating documents by tag; producers that want a tag-browsing
+view can synthesize one at consumption time by scanning frontmatter.
+
+---
+
+## 4. Concept Documents
+
+Every concept is a UTF-8 markdown file. It has two parts:
+
+1. A **YAML frontmatter block**, delimited by `---` on its own line at
+   the start of the file and a closing `---` on its own line.
+2. A **markdown body**, containing free-form content.
+
+### 4.1 Frontmatter
+
+```yaml
+---
+type: <Type name>                  # REQUIRED
+title: <Optional display name>
+description: <Optional one-line summary>
+resource: <Optional canonical URI for the underlying asset>
+tags: [<tag>, <tag>, …]            # Optional
+timestamp: <ISO 8601 datetime>     # Optional last-modified time
+# … other producer-defined key/value pairs
+---
+```
+
+**Required:**
+
+- `type` — A short string identifying the kind of concept. Consumers
+  use this for routing, filtering, and presentation. Example values:
+  `BigQuery Table`, `BigQuery Dataset`, `API Endpoint`, `Metric`,
+  `Playbook`, `Reference`.
+
+  Type values are **not** registered centrally. Producers SHOULD pick
+  values that are descriptive and self-explanatory; consumers MUST
+  tolerate unknown types gracefully (typically by treating them as
+  generic concepts).
+
+**Recommended (in priority order):**
+
+- `title` — Human-readable display name. If omitted, consumers MAY
+  derive a title from the filename.
+- `description` — A single sentence summarizing the concept. Used by
+  `index.md` generators, search snippets, and previews.
+- `resource` — A URI that uniquely identifies the underlying asset the
+  concept describes. Absent for concepts that describe abstract ideas
+  rather than physical resources.
+- `tags` — A YAML list of short strings for cross-cutting categorization.
+- `timestamp` — ISO 8601 datetime of last meaningful change.
+
+**Extensions:** Producers MAY include any additional keys. Consumers
+SHOULD preserve unknown keys when round-tripping and SHOULD NOT reject
+documents with unrecognized fields.
+
+### 4.2 Body
+
+The body is standard markdown. Producers SHOULD favor structural
+markdown — headings, lists, tables, fenced code blocks — over freeform
+prose, since structure aids both human reading and agent retrieval.
+
+There are no required body sections. The following section headings have
+**conventional** meaning and SHOULD be used when applicable:
+
+| Heading        | Purpose                                                |
+|----------------|--------------------------------------------------------|
+| `# Schema`     | Structured description of an asset's columns/fields.   |
+| `# Examples`   | Concrete usage examples, often as fenced code blocks.  |
+| `# Citations`  | External sources backing claims in the body. See §8.   |
+
+### 4.3 Example: a concept bound to a resource
+
+```markdown
+---
+type: BigQuery Table
+title: Customer Orders
+description: One row per completed customer order across all channels.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
+tags: [sales, orders, revenue]
+timestamp: 2026-05-28T14:30:00Z
+---
+
+# Schema
+
+| Column        | Type      | Description                              |
+|---------------|-----------|------------------------------------------|
+| `order_id`    | STRING    | Globally unique order identifier.        |
+| `customer_id` | STRING    | Foreign key into [customers](/tables/customers.md). |
+| `total_usd`   | NUMERIC   | Order total in US dollars.               |
+| `placed_at`   | TIMESTAMP | When the customer submitted the order.   |
+
+# Joins
+
+Joined with [customers](/tables/customers.md) on `customer_id`.
+
+# Citations
+
+[1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)
+```
+
+### 4.4 Example: a concept not bound to a resource
+
+```markdown
+---
+type: Playbook
+title: Incident response — data freshness alert
+description: Steps to triage a freshness alert on the orders pipeline.
+tags: [oncall, incident]
+timestamp: 2026-04-12T09:00:00Z
+---
+
+# Trigger
+
+A freshness alert fires when `orders` lags more than 30 minutes behind
+its expected SLA. See the [orders table](/tables/orders.md).
+
+# Steps
+
+1. Check the [ingestion job dashboard](https://example.com/dash).
+2. …
+```
+
+---
+
+## 5. Cross-linking
+
+Concepts MAY link to other concepts using standard markdown links. Two
+forms are supported:
+
+### 5.1 Absolute (bundle-relative) links
+
+Begin with `/`, interpreted relative to the bundle root.
+
+```markdown
+See the [customers table](/tables/customers.md) for the join key.
+```
+
+This is the **recommended** form because it is stable when documents are
+moved within their subdirectory.
+
+### 5.2 Relative links
+
+Standard markdown relative paths.
+
+```markdown
+See the [neighboring concept](./other.md).
+```
+
+### 5.3 Link semantics
+
+A link from concept A to concept B asserts a *relationship*. The
+specific kind of relationship (parent/child, references, joins-with,
+depends-on, etc.) is conveyed by the surrounding prose, not by the link
+itself. Consumers that build a graph view typically treat all links as
+directed edges of an untyped relationship.
+
+Consumers MUST tolerate broken links — a link whose target does not
+exist in the bundle is not malformed; it may simply represent
+not-yet-written knowledge.
+
+---
+
+## 6. Index Files
+
+An `index.md` file MAY appear in any directory, including the bundle
+root. It enumerates the directory's contents to support **progressive
+disclosure** — letting a human or agent see what is available before
+opening individual documents.
+
+Index files contain no frontmatter. The body uses one or more sections,
+each grouping concepts under a heading:
+
+```markdown
+# Section / Group Heading
+
+* [Title 1](relative-url-1) - short description of item 1
+* [Title 2](relative-url-2) - short description of item 2
+
+# Another Section
+
+* [Subdirectory](subdir/) - short description of the subdirectory
+```
+
+Entries SHOULD include the description from the linked concept's
+frontmatter. Producers MAY generate `index.md` automatically; consumers
+MAY synthesize one on the fly when none is present.
+
+---
+
+## 7. Log Files (optional)
+
+A `log.md` file MAY appear at any level of the hierarchy to record the
+history of changes to that scope. The format is a flat list of
+date-grouped entries, newest first:
+
+```markdown
+# Directory Update Log
+
+## 2026-05-22
+* **Update**: Added new BigQuery table reference for [Customer Metrics](/tables/customer-metrics.md).
+* **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).
+
+## 2026-05-15
+* **Initialization**: Created foundational directory structure.
+* **Update**: Added progressive-disclosure guidelines to the root [index](/index.md).
+```
+
+Date headings MUST use ISO 8601 `YYYY-MM-DD` form. Log entries are
+prose; the leading bold word (`**Update**`, `**Creation**`,
+`**Deprecation**`, etc.) is a convention, not a requirement.
+
+---
+
+## 8. Citations
+
+When a concept's body makes claims sourced from external material,
+those sources SHOULD be listed under a `# Citations` heading at the
+bottom of the document, numbered:
+
+```markdown
+# Citations
+
+[1] [BigQuery public dataset announcement](https://cloud.google.com/blog/products/data-analytics/...)
+[2] [Internal data quality runbook](https://wiki.acme.internal/data/quality)
+```
+
+Citation links MAY be absolute URLs, bundle-relative paths, or paths
+into a `references/` subdirectory that mirrors external material as
+first-class OKF concepts.
+
+---
+
+## 9. Conformance
+
+A bundle is **conformant** with OKF v0.1 if:
+
+1. Every non-reserved `.md` file in the tree contains a parseable YAML
+   frontmatter block.
+2. Every frontmatter block contains a non-empty `type` field.
+3. Every reserved filename (`index.md`, `log.md`) follows the structure
+   described in §6 and §7 respectively when present.
+
+Consumers SHOULD treat all other constraints as soft guidance. In
+particular, consumers MUST NOT reject a bundle because of:
+
+- Missing optional frontmatter fields.
+- Unknown `type` values.
+- Unknown additional frontmatter keys.
+- Broken cross-links.
+- Missing `index.md` files.
+
+This permissive consumption model is intentional: OKF is meant to
+remain useful as bundles grow, get refactored, and are partially
+generated by agents.
+
+---
+
+## 10. Relationship to other formats
+
+OKF is intentionally close to several established patterns:
+
+- **LLM "wiki" repositories** that use markdown + frontmatter as
+  agent-readable knowledge bases.
+- **Personal knowledge tools** like Obsidian and Notion, which use
+  hierarchical markdown with cross-links.
+- **"Metadata as code"** approaches that store catalog metadata
+  alongside source code rather than in a separate registry.
+
+OKF differs primarily in being **specified** — pinning down the small
+set of rules needed for interoperability without dictating tooling.
+
+---
+
+## 11. Versioning
+
+This document specifies OKF version **0.1**. Future revisions will be
+versioned in the form `<major>.<minor>`:
+
+- A **minor** version bump introduces backward-compatible additions
+  (new optional fields, new conventional section headings).
+- A **major** version bump may make breaking changes (renaming required
+  fields, changing reserved filenames).
+
+Bundles MAY declare the OKF version they target by including
+`okf_version: "0.1"` in a bundle-root `index.md` frontmatter block (the
+only place frontmatter is permitted in an `index.md`). Consumers that
+do not understand the declared version SHOULD attempt best-effort
+consumption rather than refusing the bundle.
+
+---
+
+## Appendix A — Minimal example bundle
+
+```
+my_bundle/
+├── index.md
+├── datasets/
+│   ├── index.md
+│   └── sales.md
+└── tables/
+    ├── index.md
+    ├── orders.md
+    └── customers.md
+```
+
+`datasets/sales.md`:
+
+```markdown
+---
+type: BigQuery Dataset
+title: Sales
+description: All sales-related tables for the retail business.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales
+tags: [sales]
+timestamp: 2026-05-28T00:00:00Z
+---
+
+The sales dataset contains transactional tables, including
+[orders](/tables/orders.md) and [customers](/tables/customers.md).
+```
+
+`tables/orders.md`:
+
+```markdown
+---
+type: BigQuery Table
+title: Orders
+description: One row per completed customer order.
+resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
+tags: [sales, orders]
+timestamp: 2026-05-28T00:00:00Z
+---
+
+# Schema
+
+| Column        | Type      | Description                  |
+|---------------|-----------|------------------------------|
+| `order_id`    | STRING    | Unique order identifier.     |
+| `customer_id` | STRING    | FK to [customers](/tables/customers.md). |
+| `total_usd`   | NUMERIC   | Order total in USD.          |
+
+Part of the [sales dataset](/datasets/sales.md).
+```
--- a/.github/skills/okf-open-knowledge-format/scripts/validate.sh
+++ b/.github/skills/okf-open-knowledge-format/scripts/validate.sh
@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# OKF Bundle Validator v0.1
+# Usage: validate.sh <bundle-path>
+# Checks conformance with OKF v0.1 spec:
+#   E1: All non-reserved .md files have YAML frontmatter
+#   E2: All frontmatter has non-empty 'type' field
+#   E3: Reserved files follow structure rules
+
+set -euo pipefail
+
+BUNDLE="${1:-.}"
+ERRORS=0
+WARNINGS=0
+TOTAL=0
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+NC='\033[0m'
+
+if [ ! -d "$BUNDLE" ]; then
+  echo -e "${RED}Error: '$BUNDLE' is not a directory${NC}"
+  exit 1
+fi
+
+echo "Validating OKF bundle: $BUNDLE"
+echo "---"
+
+# Find all .md files
+while IFS= read -r -d '' file; do
+  TOTAL=$((TOTAL + 1))
+  relative="${file#$BUNDLE/}"
+  basename=$(basename "$file")
+
+  # Skip reserved files (validate separately)
+  if [[ "$basename" == "index.md" || "$basename" == "log.md" ]]; then
+    # E3: Check reserved file structure
+    if [[ "$basename" == "index.md" ]]; then
+      # index.md should NOT have frontmatter (except bundle root may have okf_version)
+      if head -1 "$file" | grep -q "^---$"; then
+        # Allow only if it's bundle root and contains okf_version
+        if [[ "$relative" != "index.md" ]]; then
+          echo -e "${RED}E3: $relative — index.md should not have frontmatter${NC}"
+          ERRORS=$((ERRORS + 1))
+        fi
+      fi
+    fi
+    if [[ "$basename" == "log.md" ]]; then
+      # log.md should have date headings in YYYY-MM-DD format
+      if ! grep -qE "^## [0-9]{4}-[0-9]{2}-[0-9]{2}" "$file" 2>/dev/null; then
+        if [ -s "$file" ]; then
+          echo -e "${YELLOW}W: $relative — log.md has no ISO 8601 date headings${NC}"
+          WARNINGS=$((WARNINGS + 1))
+        fi
+      fi
+    fi
+    continue
+  fi
+
+  # E1: Check for YAML frontmatter
+  if ! head -1 "$file" | grep -q "^---$"; then
+    echo -e "${RED}E1: $relative — no YAML frontmatter${NC}"
+    ERRORS=$((ERRORS + 1))
+    continue
+  fi
+
+  # Extract frontmatter (between first --- and second ---)
+  frontmatter=$(sed -n '2,/^---$/p' "$file" | sed '$d')
+
+  # E2: Check for non-empty type field
+  type_value=$(echo "$frontmatter" | grep -E "^type:" | sed 's/^type:\s*//' | tr -d '"' | tr -d "'" | xargs)
+  if [ -z "$type_value" ]; then
+    echo -e "${RED}E2: $relative — missing or empty 'type' field${NC}"
+    ERRORS=$((ERRORS + 1))
+    continue
+  fi
+
+  # Warnings for recommended fields
+  if ! echo "$frontmatter" | grep -qE "^title:"; then
+    echo -e "${YELLOW}W1: $relative — missing recommended 'title' field${NC}"
+    WARNINGS=$((WARNINGS + 1))
+  fi
+  if ! echo "$frontmatter" | grep -qE "^description:"; then
+    echo -e "${YELLOW}W1: $relative — missing recommended 'description' field${NC}"
+    WARNINGS=$((WARNINGS + 1))
+  fi
+
+done < <(find "$BUNDLE" -name "*.md" -type f -print0 | sort -z)
+
+# Summary
+echo "---"
+echo "Files scanned: $TOTAL"
+if [ $ERRORS -eq 0 ]; then
+  echo -e "${GREEN}✅ Bundle is OKF v0.1 conformant${NC}"
+else
+  echo -e "${RED}❌ $ERRORS error(s) — bundle is NOT conformant${NC}"
+fi
+if [ $WARNINGS -gt 0 ]; then
+  echo -e "${YELLOW}⚠  $WARNINGS warning(s)${NC}"
+fi
+
+exit $ERRORS
--- a/.github/skills/pier-cloud/.env.example
+++ b/.github/skills/pier-cloud/.env.example
@@ -0,0 +1,9 @@
+PIERCLOUD_CLIENT_ID=
+PIERCLOUD_CLIENT_SECRET=
+PIERCLOUD_TENANCY_ID=
+# Legado (TENANCY_ID tem prioridade, mas BUSINESS_ID ainda funciona como fallback)
+# PIERCLOUD_BUSINESS_ID=
+# PIERCLOUD_ORG_ID= (nao mais necessario na nova API)
+
+
+
--- a/.github/skills/pier-cloud/SKILL.md
+++ b/.github/skills/pier-cloud/SKILL.md
@@ -0,0 +1,103 @@
+---
+name: "pier-cloud"
+description: "This skill should be used when the user needs to consume the Pier Cloud (Lighthouse) API for cloud cost management — including JWT authentication, listing contexts, workspaces, and FinOps data views. Trigger whenever there is a need to integrate, automate, or debug calls to the Pier Cloud platform via Python, Node.js, or cURL."
+metadata:
+  author: ft.ia.br
+  version: "1.1"
+  date: 2026-03-05
+  repository: https://github.com/fabricioctelles/skills
+  license: Apache 2.0
+  keywords: ["pier", "piercloud", "lighthouse", "api", "finops", "cloud", "costs"]
+  category: library-and-api-reference
+---
+
+# Pier Cloud API
+
+## Prerequisites
+
+### Credentials
+
+Locate the `.env` file in the skill directory with the following variables:
+
+```env
+PIERCLOUD_CLIENT_ID=your_client_id
+PIERCLOUD_CLIENT_SECRET=your_client_secret
+PIERCLOUD_TENANCY_ID=your_tenancy_id
+```
+
+If the `.env` file does not exist, inform the user that credentials must be obtained from the Pier Cloud platform before proceeding. Do not proceed without the `.env` file.
+
+> Note: `PIERCLOUD_TENANCY_ID` is equivalent to the former `PIERCLOUD_BUSINESS_ID`. Scripts accept both as fallback.
+
+### Python Dependencies
+
+```bash
+pip install requests python-dotenv
+```
+
+## Basic Configuration
+
+The API uses JWT authentication. Required flow:
+
+1. Authenticate via `POST /auth` with `client_id` and `client_secret` to obtain a JWT token
+2. Include the token in all requests: `Authorization: Bearer {token}`
+3. Renew the token upon expiration (default validity: 1 hour)
+
+**Base URL**: `https://api.piercloud.io`
+
+Verify the connection by running:
+
+```bash
+python scripts/pier-cloud-auth.py
+```
+
+## Available Scripts
+
+Ready-to-use scripts in `scripts/`. See `scripts/README.md` for detailed instructions.
+
+| Script | Description |
+|--------|-------------|
+| `pier-cloud-auth.py` | Authenticate and obtain JWT token |
+| `pier-cloud-list-contexts.py` | List available contexts |
+| `pier-cloud-list-workspaces.py` | List workspaces with pagination |
+| `pier-cloud-get-workspace.py` | Get specific workspace details |
+| `pier-cloud-get-all-workspaces.py` | Get all workspaces (automatic pagination) |
+| `pier-cloud-list-views.py` | List views for a workspace |
+| `pier-cloud-get-view.py` | Get specific view information |
+| `pier-cloud-get-view-data.py` | Get view data with filters |
+| `pier_cloud_client.py` | Robust client with CLI and reusable library |
+
+> Note: Workspace-groups scripts (`pier-cloud-list-workspace-groups.py`, `pier-cloud-get-workspace-group.py`) do not work — the corresponding endpoints do not exist in the current API.
+
+## Workflows
+
+Follow the detailed workflows with request and response examples in `references/REFERENCE.md`:
+
+- **Workflow 1** — Authentication and Token Retrieval
+- **Workflow 2** — List Contexts
+- **Workflow 3** — List Workspaces
+- **Workflow 4** — Get Workspace Details
+- **Workflow 5** — Get All Workspaces (Automatic Pagination)
+- **Workflow 6** — Robust Client with Retry and Token Renewal
+- **Workflow 9** — List Workspace Views
+- **Workflow 10** — Get View Information
+- **Workflow 11** — Get View Data with Filters
+
+For endpoint reference, parameters, response structures, and cURL examples, see `references/REFERENCE.md`.
+
+For error diagnosis (401, 403, 404, timeout, rate limiting), see `references/TROUBLESHOOTING.md`.
+
+## Additional Resources
+
+- **API Docs**: https://docs.piercloud.com/api-docs-pier-cloud
+- **Pier Cloud Platform**: https://piercloud.com/en/
+
+## Quality Checklist
+
+- [ ] `.env` file present with `PIERCLOUD_CLIENT_ID`, `PIERCLOUD_CLIENT_SECRET`, and `PIERCLOUD_TENANCY_ID`
+- [ ] Python dependencies installed (`requests`, `python-dotenv`)
+- [ ] Authentication successful (JWT token obtained without errors)
+- [ ] Correct endpoint being used (default `/lighthouse/tenancies/{tenancy_id}/...`)
+- [ ] Token being renewed before expiration in long sessions
+- [ ] Workspace/view IDs confirmed via listing before using directly
+- [ ] Errors handled per `references/TROUBLESHOOTING.md`
--- a/.github/skills/pier-cloud/references/TROUBLESHOOTING.md
+++ b/.github/skills/pier-cloud/references/TROUBLESHOOTING.md
@@ -0,0 +1,115 @@
+## Troubleshooting
+
+### Error 401 - Invalid Credentials
+
+**Problem**: Authentication fails with error 401
+
+**Symptoms**:
+```json
+{
+  "code": "failed",
+  "message": "invalid or expired token"
+}
+```
+
+**Common Causes**:
+- Incorrect `client_id` or `client_secret`
+- Credentials not registered on the Pier Cloud platform
+- Environment variables not loaded correctly
+
+**Solutions**:
+1. Check credentials in the `.env` file
+2. Confirm that variables are being loaded
+3. Validate credentials with the Pier Cloud team
+4. Verify that the HTTP client is registered on the platform
+
+### Error 403 - Access Denied
+
+**Problem**: Valid token but no permission to access resource
+
+**Symptoms**:
+```json
+{
+  "code": "authorization/forbidden",
+  "message": "Access denied"
+}
+```
+
+**Causes**:
+- Account without adequate permissions
+- Incorrect `tenancy_id`
+- Resource does not belong to the specified tenant
+
+**Solutions**:
+1. Check account permissions on the Pier Cloud platform
+2. Confirm correct `tenancy_id`
+3. Contact administrator to request permissions
+
+### Error 404 - Resource Not Found
+
+**Problem**: Endpoint or resource does not exist
+
+**Symptoms**:
+```json
+{
+  "code": "workspace/not-found",
+  "message": "Workspace not found"
+}
+```
+
+**Causes**:
+- Incorrect or non-existent `workspace_id`
+- Invalid `tenancy_id`
+- Incorrect endpoint URL
+
+**Solutions**:
+1. List all workspaces first to verify available IDs
+2. Confirm endpoint URL is correct
+3. Validate tenancy_id
+
+### Expired Token
+
+**Problem**: JWT token expired after ~1 hour
+
+**Symptoms**:
+- Requests that were working start returning 401
+- Error "invalid or expired token"
+
+**Solution**:
+
+Use the robust client that implements automatic renewal:
+
+```bash
+python scripts/pier_cloud_client.py --action list-contexts
+```
+
+The `pier_cloud_client.py` client automatically renews the token before it expires.
+
+### Connection Timeout
+
+**Problem**: Request takes too long or does not respond
+
+**Symptoms**:
+- Timeout after 30+ seconds
+- Connection not established
+- Network error
+
+**Solutions**:
+1. Check internet connectivity
+2. Test API availability: `curl -I https://api.piercloud.io/auth`
+3. Check if there is a proxy or firewall blocking
+4. Try again after a few minutes
+
+### Rate Limiting (Too Many Requests)
+
+**Problem**: API returns error 429 (Too Many Requests)
+
+**Symptoms**:
+- Error 429 after several rapid requests
+- Message about rate limit
+
+**Solutions**:
+1. Use the robust client that implements automatic retry
+2. Reduce request frequency
+3. Implement delays between requests
+4. Use pagination with smaller `page_size` if needed
--- a/.github/skills/pier-cloud/scripts/README.md
+++ b/.github/skills/pier-cloud/scripts/README.md
@@ -0,0 +1,166 @@
+# Scripts da API Pier Cloud
+
+Scripts prontos para consumir a API Pier Cloud (Lighthouse).
+
+## Prerequisitos
+
+```bash
+pip install requests python-dotenv
+```
+
+## Configuracao
+
+Crie arquivo `.env` na raiz do projeto:
+
+```env
+PIERCLOUD_CLIENT_ID=seu_client_id
+PIERCLOUD_CLIENT_SECRET=seu_client_secret
+PIERCLOUD_TENANCY_ID=seu_tenancy_id
+```
+
+> **Nota**: O `TENANCY_ID` corresponde ao antigo `BUSINESS_ID`. Se voce ja tem `PIERCLOUD_BUSINESS_ID` no `.env`, os scripts usam como fallback automaticamente.
+
+## API - Mudanca de Endpoints (Fev 2026)
+
+A API Pier Cloud atualizou seus endpoints:
+
+- **Antes**: `/lighthouse/orgs/{org_id}/businesses/{business_id}/...`
+- **Agora**: `/lighthouse/tenancies/{tenancy_id}/...`
+
+O `PIERCLOUD_ORG_ID` nao e mais necessario. O `tenancy_id` equivale ao antigo `BUSINESS_ID`.
+
+Documentacao oficial: https://docs.piercloud.com/api-docs-pier-cloud
+
+## Scripts Disponiveis
+
+### 1. pier-cloud-auth.py
+Autentica e obtem token JWT.
+
+```bash
+python scripts/pier-cloud-auth.py
+```
+
+### 2. pier-cloud-list-contexts.py
+Lista todos os contextos disponiveis.
+
+```bash
+python scripts/pier-cloud-list-contexts.py
+```
+
+### 3. pier-cloud-list-workspaces.py
+Lista workspaces com paginacao.
+
+```bash
+# Padrao (pagina 1, 10 itens)
+python scripts/pier-cloud-list-workspaces.py
+
+# Pagina especifica
+python scripts/pier-cloud-list-workspaces.py --page 2 --page-size 50
+
+# Ordenar por data
+python scripts/pier-cloud-list-workspaces.py --sort-field created_at --sort-order DESC
+```
+
+### 4. pier-cloud-get-workspace.py
+Obtem detalhes de workspace especifico.
+
+```bash
+python scripts/pier-cloud-get-workspace.py --workspace-id 16969
+```
+
+### 5. pier-cloud-get-all-workspaces.py
+Obtem todos os workspaces com paginacao automatica.
+
+```bash
+# Exibir no terminal
+python scripts/pier-cloud-get-all-workspaces.py
+
+# Salvar em JSON
+python scripts/pier-cloud-get-all-workspaces.py --output workspaces.json
+
+# Salvar em CSV
+python scripts/pier-cloud-get-all-workspaces.py --output workspaces.csv --format csv
+```
+
+### 6. pier-cloud-list-views.py
+Lista visualizacoes de um workspace.
+
+```bash
+python scripts/pier-cloud-list-views.py --workspace-id 16969
+```
+
+### 7. pier-cloud-get-view.py
+Obtem informacoes de visualizacao especifica.
+
+```bash
+python scripts/pier-cloud-get-view.py --view-id 193195
+```
+
+### 8. pier-cloud-get-view-data.py
+Obtem dados de uma visualizacao com filtros.
+
+```bash
+# Basico
+python scripts/pier-cloud-get-view-data.py --view-id 193195
+
+# Com periodo
+python scripts/pier-cloud-get-view-data.py --view-id 193195 \
+  --start-date 2026-01-01 --end-date 2026-01-31
+
+# Com filtros
+python scripts/pier-cloud-get-view-data.py --view-id 193195 \
+  --filters '[{"name":"lineitem/usageaccountid","data_type":"string","role":"filter","filters":[{"expression":"IS","value":["123456"],"negative_expression":false}]}]'
+
+# Salvar em arquivo
+python scripts/pier-cloud-get-view-data.py --view-id 193195 \
+  --start-date 2026-01-01 --end-date 2026-01-31 --output dados.json
+```
+
+### 9. pier_cloud_client.py
+Cliente robusto com CLI e biblioteca reutilizavel.
+
+**Como CLI**:
+```bash
+# Listar contextos
+python scripts/pier_cloud_client.py --action list-contexts
+
+# Listar workspaces
+python scripts/pier_cloud_client.py --action list-workspaces --page 1 --page-size 20
+
+# Obter workspace
+python scripts/pier_cloud_client.py --action get-workspace --workspace-id 16969
+
+# Obter todos
+python scripts/pier_cloud_client.py --action get-all-workspaces --output results.json
+```
+
+### 10. appscript-pier-cloud.gs
+Codigo Google Apps Script para integrar com Google Sheets.
+
+Veja instrucoes no proprio arquivo.
+
+## Endpoints da API (Atualizado Fev 2026)
+
+| Metodo | Endpoint | Descricao |
+|--------|----------|-----------|
+| POST | `/auth` | Obter token JWT |
+| GET | `/lighthouse/tenancies/{tenancy_id}/contexts` | Listar contextos |
+| GET | `/lighthouse/tenancies/{tenancy_id}/workspaces` | Listar workspaces |
+| GET | `/lighthouse/tenancies/{tenancy_id}/workspaces/{id}` | Obter workspace |
+| GET | `/lighthouse/tenancies/{tenancy_id}/workspaces/{workspace_id}/views` | Listar views |
+| GET | `/lighthouse/tenancies/{tenancy_id}/views/{id}` | Obter view |
+| GET | `/lighthouse/tenancies/{tenancy_id}/views/{id}/data` | Obter dados da view |
+
+## Troubleshooting
+
+### Erro: Variaveis faltando
+Verifique se o arquivo `.env` existe e contem `PIERCLOUD_TENANCY_ID` (ou `PIERCLOUD_BUSINESS_ID` como fallback).
+
+### Erro 401
+Credenciais invalidas. Verifique CLIENT_ID e CLIENT_SECRET.
+
+### Erro 403
+Sem permissao. Verifique TENANCY_ID.
+
+### Erro 404
+Recurso nao encontrado. Verifique IDs fornecidos.
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
tim	c67c549f48	docs: update OpenWiki	2026-08-08 18:09:52 +00:00
tim	37616a9316	.github/workflows/openwiki-update.yml aktualisiert	2026-08-08 18:06:26 +00:00
Tim Krampitz	a5db6dc26e	Merge branch 'master' of https://git.krampitz.win/tim/SlipItIn	2026-08-08 12:50:27 +02:00
Tim Krampitz	118a62a804	Update der Dokumentation	2026-08-08 12:50:15 +02:00
tim	e9675158a3	.github/workflows/openwiki-update.yml aktualisiert Some checks failed OpenWiki Update / update (push) Failing after 1m14s Details	2026-07-26 15:36:33 +00:00
Tim Krampitz	bbc6ad6080	Architektur-Redesign: SignalR-Multiplayer & MVVM Umfassende Umstrukturierung der SlipItIn-App für eine moderne, zustandsbasierte und SignalR-gestützte Multiplayer-Architektur. Einführung neuer Services für Auth, API, SignalR, lokalen Speicher und Game-State-Management via Dependency Injection. Komplette Neugestaltung der Views (Login, Registrierung, Lobby, Spielbrett) mit MVVM und CommunityToolkit.Mvvm. Navigation jetzt über MAUI Shell mit expliziten Routen. Game-Logik auf Events/Messaging umgestellt, UI und Logik entkoppelt, Echtzeit-Updates integriert. SignalR für alle Spielaktionen inkl. Wiederverbindung und Offline-Queueing. Lokaler Speicher für Auth, Userdaten, GameState und Aktionen. MainPage entfernt, neue Views implementiert. Projektdatei um NuGet-Pakete und Shared-Projekt erweitert. Backend-Änderungen für direkte Spieler-Zuordnung und korrekte EF Core-Relationen. App ist nun robust, testbar und unterstützt Multiplayer- sowie Offline-Szenarien.	2026-07-26 17:31:26 +02:00
Tim Krampitz	85fb2c9ce7	Small cleanup	2026-07-26 14:16:37 +02:00
Tim Krampitz	01046b01e4	Neue Skills, Referenzen & OpenWiki-Doku integriert Umfangreiche Erweiterung der Skill-Bibliothek: Neue Skills für Humanisierung (Englisch/PT-BR), Design-Validierung, AI-SEO und Coolify-Deployment inkl. Regelwerke, Presets, Pattern-Referenzen, Testfälle und Automatisierungsskripte. Zusätzliche Skills für Revenue-Centric Design, Pier Cloud, OKF, Lebenslauf- und LinkedIn-Optimierung sowie zahlreiche Referenzdateien, Checklisten und YAML/JSON/Markdown-Templates. Einführung einer vollständigen OpenWiki-Dokumentation mit Architektur-, Domain- und Workflow-Beschreibungen, zentralem Index und automatisierten Updates. Modularer Aufbau, restriktive Lizenzen und umfassende Qualitäts- und Evaluationsmechanismen für alle neuen Inhalte.	2026-07-26 14:00:58 +02:00
Tim Krampitz	070727d5cd	JWT-Authentifizierung & GameState-Verbesserungen Neuer AuthController mit Endpunkten für Registrierung, Login und Nutzerinfo (/register, /login, /me) implementiert. Auth-spezifische DTOs hinzugefügt. GameHub mit [Authorize] geschützt und Spielteilnahme validiert. GameService liefert jetzt Rundeninfos, aktuelle Rundennummer und verbleibende Rundendauer. Migrations-Ordner im Projekt angelegt.	2026-07-26 13:30:03 +02:00