@the-bearded-bear/claude-craft 8.21.0 → 8.22.0-next.63d46da

package/Dev/i18n/base/Common/commands/aliases.md

@@ -19,6 +19,7 @@ These aliases reduce typing and improve productivity by providing short mnemonic
 | Alias | Full Command | Description |
 |-------|-------------|-------------|
 | `/ca` | `/common:audit-freshness` | Audit documentation freshness |
+| `/caa` | `/common:audit-claude-alignment` | Weekly Claude ecosystem alignment audit |
 | `/ci` | `/common:init` | Initialize Claude Craft |
 | `/cr` | `/common:release-checklist` | Pre-release verification checklist |
 | `/cs` | `/common:setup-project-context` | Setup project context for Claude |
@@ -123,6 +124,7 @@ Add to `~/.bashrc` or `~/.zshrc`:
 ```bash
 # Claude Craft Aliases
 alias ca='claude-code -p /common:audit-freshness'
+alias caa='claude-code -p /common:audit-claude-alignment'
 alias ci='claude-code -p /common:init'
 alias cr='claude-code -p /common:release-checklist'
 alias cs='claude-code -p /common:setup-project-context'
@@ -156,6 +158,7 @@ Add to `~/.config/fish/config.fish`:
 ```fish
 # Claude Craft Aliases
 alias ca 'claude-code -p /common:audit-freshness'
+alias caa 'claude-code -p /common:audit-claude-alignment'
 alias ci 'claude-code -p /common:init'
 alias cr 'claude-code -p /common:release-checklist'
 alias cs 'claude-code -p /common:setup-project-context'

package/Dev/i18n/base/Common/commands/audit-claude-alignment.md

@@ -0,0 +1,201 @@
+---
+description: "Audit hebdomadaire d'alignement sur l'écosystème Claude (CLI, modèles, best practices Anthropic, communauté) via équipe d'agents + PR de correction"
+argument-hint: "[--quick|--full] [--lens=<nom>] [--since=YYYY-MM-DD] [--dry-run] [--no-pr]"
+model: sonnet
+---
+
+# Audit d'alignement Claude — claude-craft
+
+Vérifie que claude-craft reste aligné sur l'état réel de l'écosystème Claude : version du CLI Claude Code, modèles et pricing, best practices Anthropic, features de la plateforme, avis de sécurité, et pratiques de la communauté.
+
+Complémentaire de `/common:audit-freshness`, qui couvre les stacks applicatifs (React, Symfony, Flutter…) et **jamais Claude Code lui-même**.
+
+**Résultat :** rapport `docs/audit/claude-alignment/<date>.md` + `<date>.json`, et une **PR** portant uniquement les corrections mécaniques. Tout ce qui demande un jugement part en checklist dans le corps de la PR, jamais en édition automatique.
+
+## Arguments
+
+$ARGUMENTS
+
+- `--quick` (défaut) : n'audite que les lentilles dont la source externe a bougé depuis la baseline
+- `--full` : force les 7 lentilles, effort `high` sur sécurité et modèles — cadence mensuelle
+- `--lens=<nom>` : une seule lentille (`cli-release`, `models-pricing`, `prompt-context`, `cc-features`, `security-cve`, `community`, `internal-conformance`)
+- `--since=YYYY-MM-DD` : force la date de baseline — rattrapage après un trou de cadence
+- `--dry-run` : pré-collecte + liste des agents qui seraient lancés. **Aucun agent, aucune écriture**
+- `--no-pr` : rapport seul, ni branche ni PR
+
+## MISSION
+
+### Étape 0 — Pré-vol et pré-collecte
+
+1. **Worktree propre obligatoire.** `git status --porcelain` ; si la sortie n'est pas vide, **arrêter** et le signaler. Des agents d'audit ont déjà pollué le worktree par le passé — on ne construit pas une PR par-dessus des modifications non validées.
+2. Lancer la pré-collecte déterministe (coût LLM nul) :
+   ```bash
+   node scripts/collect-claude-signals.mjs [--since=<date>] [--dry-run]
+   ```
+   Elle lit `config/claude-alignment-baseline.json`, interroge le registry npm, les avis de sécurité GitHub, le catalogue communautaire et les pages de doc suivies par empreinte, puis écrit `docs/audit/claude-alignment/signals-<date>.json`.
+3. Lire ce fichier. Le champ **`agents_to_launch`** est la liste exacte des lentilles à réveiller. Une lentille absente n'est **pas** auditée : écrire `✅ aucun changement depuis <baseline.last_run>` dans le rapport, sans lancer d'agent. C'est le principal levier de coût de cette commande.
+4. Calculer l'âge du dernier run (`baseline.last_run` → aujourd'hui). Au-delà de **10 jours**, ouvrir le rapport par un avertissement de cadence.
+5. En `--full`, ignorer `agents_to_launch` et retenir les 7 lentilles. En `--lens=<nom>`, ne retenir que celle-là. En `--dry-run`, s'arrêter ici en affichant la liste retenue et le coût estimé.
+
+### Étape 1 — Gates locaux (0 token)
+
+Lancer, et consigner le résultat de chacun dans le rapport :
+
+```bash
+npm run lint:versions   # cohérence tech-registry ↔ versions.yaml + denylist dans les fichiers vitrine
+npm run lint:includes   # liens @<path> fantômes
+npm run docs:check      # dérive des références générées
+npm run lint:i18n       # parité i18n (comptage + taille)
+```
+
+Un gate rouge est un finding **P1** au minimum. Ne pas le corriger ici : il alimente le patch-plan de l'étape 3.
+
+### Étape 2 — Équipe d'agents (un seul message, N appels Task en parallèle)
+
+Lancer **en un seul message** un agent par lentille retenue. Le routing modèle n'est pas négociable : il est ce qui rend l'audit hebdomadaire soutenable.
+
+| Lentille | `subagent_type` | `model` | `effort` |
+|---|---|---|---|
+| `cli-release` | `general-purpose` | `sonnet` | `medium` |
+| `models-pricing` | `general-purpose` | `sonnet` | `medium` (`high` en `--full`) |
+| `cc-features` | `claude-code-guide` | *(défaut de l'agent)* | — |
+| `prompt-context` | `general-purpose` | `sonnet` | `medium` |
+| `security-cve` | `general-purpose` | `sonnet` | `medium` (`high` en `--full`) |
+| `community` | `general-purpose` | `sonnet` | `medium` |
+| `internal-conformance` | `general-purpose` | `haiku` | `low` |
+
+`internal-conformance` est un scan mécanique 100 % local : son prompt lui **interdit explicitement** WebSearch et WebFetch. Les six autres reçoivent les URLs exactes issues de `signals-<date>.json` — ils font du WebFetch ciblé, pas de la découverte par WebSearch (non déterministe et multi-requêtes).
+
+**Socle commun à injecter dans chaque prompt d'agent :**
+
+```
+Tu audites la lentille "<LENTILLE>" du dépôt claude-craft (framework Claude Code, v<version de package.json>).
+
+CONTEXTE PRÉ-COLLECTÉ (ne pas re-chercher ce qui est déjà donné) :
+<coller le bloc lenses["<LENTILLE>"] de docs/audit/claude-alignment/signals-<date>.json>
+Baseline du dernier audit : <baseline.last_run>
+
+ÉTAPES :
+1. Lire les fichiers du dépôt listés ci-dessous : <PATHS>
+2. Confronter au réel via les sources fournies (WebFetch sur les URLs exactes ci-dessus).
+   Ne remonter QUE ce qui a changé depuis la baseline.
+3. Retourner EXACTEMENT ce format (< 300 mots) :
+
+## <LENTILLE>
+- **État déclaré dans le repo** : <valeur> (source: <path>:<ligne>)
+- **État réel observé** : <valeur> (source: <URL>)
+- **Écart** : aucun | mineur | majeur | critique
+- **Findings** :
+  - [<sévérité P0-P3>] <constat> — source: <URL>
+- **PATCH** : (uniquement les substitutions mécaniques sûres, une par ligne)
+  - <chemin> | <valeur actuelle> | <valeur cible> | <raison>
+- **JUGEMENT REQUIS** : (ce qui demande un arbitrage humain, jamais de PATCH)
+  - <point> — pourquoi ça ne peut pas être automatisé
+
+CONTRAINTES :
+- Citer une source pour CHAQUE affirmation. Si une info est introuvable, écrire "non trouvé".
+- Ne rien inventer, ne pas extrapoler une version depuis un numéro voisin.
+- Ne JAMAIS modifier un fichier. Tu es en lecture seule.
+- Un PATCH n'est légitime que si la substitution est littérale et sans ambiguïté
+  (numéro de version, identifiant de modèle, date). Toute reformulation de prose
+  va en JUGEMENT REQUIS.
+```
+
+**Cibles par lentille :**
+
+| Lentille | Fichiers du dépôt à confronter |
+|---|---|
+| `cli-release` | `config/versions.yaml` (`claudeCode.*`), `.claude/COMPATIBILITY.md`, `.claude/rules/12-context-management.md`, `docs/PREREQUISITES.md` |
+| `models-pricing` | `config/versions.yaml` (`claudeCode.models`, `denylist`), `.claude/rules/12-context-management.md`, `.claude/settings.json`, `.claude/settings.local.json.example` — charger le skill `claude-api` pour la référence modèles/pricing |
+| `cc-features` | `.claude/COMPATIBILITY.md`, `.claude/settings.json`, `.claude-plugin/plugin.json`, `.claude/agents/*.md`, `.claude/skills/*/SKILL.md` — identifier les features de la plateforme non encore adoptées |
+| `prompt-context` | `.claude/rules/12-context-management.md`, `.claude/rules/23-karpathy-principles.md`, `.claude/CLAUDE.md` |
+| `security-cve` | `.claude/rules/11-security.md`, `.claude/settings.json` (permissions), `.claude/COMPATIBILITY.md` (section CVE) |
+| `community` | `.claude/skills/ecosystem-tools/SKILL.md`, `docs/ECOSYSTEM.md` |
+| `internal-conformance` | Les 3 inventaires : `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `.claude/commands/**/*.md`. Vérifier : frontmatter YAML parsable et `description` non vide ; `context: fork` présent sur tout skill de plus de 60 lignes ; cohérence `model:`/`effort:` (un agent `haiku` ne doit pas être en `effort: xhigh`) ; hooks lisant leur payload sur **stdin via `jq`** et jamais via `$TOOL_INPUT` ; aucun token de `denylist` hors fichiers vitrine |
+
+### Étape 3 — Synthèse, rapport, patch-plan
+
+1. Agréger les retours. Un agent qui a échoué laisse `⚠️ audit incomplet : <raison>` — ne jamais inventer sa section.
+2. Écrire `docs/audit/claude-alignment/<date>.md` :
+
+```markdown
+# Audit d'alignement Claude — <date>
+
+**Version claude-craft** : <package.json>
+**Mode** : quick | full
+**Baseline** : <date> (<N> jours) <⚠️ si > 10 jours>
+**Lentilles auditées** : <n>/7 — <liste> (les autres inchangées depuis la baseline)
+
+## Résumé exécutif
+
+| Sévérité | Nombre |
+|----------|--------|
+| 🔴 P0 | N |
+| 🟠 P1 | N |
+| 🟡 P2 | N |
+| 🔵 P3 | N |
+
+## Gates locaux
+
+| Gate | Résultat |
+|------|----------|
+| lint:versions | ✅ / ❌ <extrait> |
+| lint:includes | … |
+| docs:check | … |
+| lint:i18n | … |
+
+## Findings par lentille
+<coller chaque rapport d'agent>
+
+## Patch-plan appliqué
+| Fichier | Avant | Après | Raison |
+|---|---|---|---|
+
+## Jugement humain requis
+- [ ] <point> — <pourquoi>
+
+## Méthodologie
+- Pré-collecte : `scripts/collect-claude-signals.mjs` (npm registry, GitHub advisories, empreintes de pages, catalogue communautaire)
+- Agents : <n> (routing sonnet/haiku documenté dans la commande)
+- Sources : toutes citées dans les sections ci-dessus
+```
+
+3. Écrire le jumeau structuré `docs/audit/claude-alignment/<date>.json` : `{ audit_date, mode, baseline, lenses{}, summary{P0..P3}, patch_plan[], human_decisions_required[], gates{} }`.
+
+### Étape 4 — Branche et PR
+
+Sauter entièrement cette étape si `--no-pr`, `--dry-run`, ou si le patch-plan est vide.
+
+1. `git checkout -b chore/claude-alignment-<date>` depuis `main` à jour.
+2. Appliquer **uniquement** les entrées du patch-plan, et **uniquement** dans l'allowlist :
+   - `config/versions.yaml` — `claudeCode.recommended|testedUpTo|models.*`, `meta.lastUpdated`, ajouts en `denylist`
+   - `.claude/COMPATIBILITY.md` — bandeau d'en-tête et ajout de lignes dans la table `Version Requirements`
+   - Substitutions de version littérales dans les fichiers de `SHOWCASE_FILES` (`scripts/verify-versions.mjs`)
+   - `Dev/i18n/<lang>/Common/templates/settings.json.template` et `Dev/i18n/<lang>/Common/rules/12-context-management.md` (les 5 langues, en une seule passe cohérente)
+   - `config/claude-alignment-baseline.json` — remplacer par `next_baseline` du fichier de signaux
+3. **Interdit, sans exception** : `.github/workflows/` (le token `gh` n'a pas le scope `workflow`, la PR deviendrait non mergeable), tout fichier hors allowlist, toute reformulation de prose, tout fichier `.md` de documentation générée (`docs/*-FULL-REFERENCE.md` : passer par `npm run docs:generate`).
+4. Rejouer les 4 gates. **Un seul rouge ⇒ pas de PR** : laisser la branche en place et l'expliquer dans le rapport.
+5. `git add` limité aux fichiers de l'allowlist effectivement modifiés, puis commit en Conventional Commits :
+   `chore(alignment): sync Claude Code <ancienne> → <nouvelle> + modèles`
+6. `gh pr create` avec, dans le corps : le résumé exécutif, le tableau du patch-plan, et la checklist « jugement humain requis ». **Jamais de merge automatique.**
+7. Revenir sur `main` et confirmer à l'utilisateur l'URL de la PR.
+
+## Règles strictes
+
+- **Worktree propre** en préalable absolu ; sinon, arrêt immédiat.
+- **Aucune édition hors allowlist**, et aucune édition du tout tant que les gates ne sont pas verts.
+- **Toute affirmation de version cite une source** (URL ou `path:ligne`).
+- **Fail-open assumé** : une source injoignable rend la lentille « à auditer », jamais « rien à signaler ».
+- **Un agent en échec** laisse `⚠️ audit incomplet : <raison>` — pas de section inventée.
+- **Parallélisme obligatoire** : un seul message contenant tous les appels Task de l'étape 2.
+- **Langue du rapport** : français, avec accents.
+
+## Exemples
+
+```
+/common:audit-claude-alignment                          # rituel hebdomadaire
+/common:audit-claude-alignment --dry-run                # quelles lentilles bougeraient ? coût nul
+/common:audit-claude-alignment --full                   # passage mensuel approfondi
+/common:audit-claude-alignment --lens=cli-release --no-pr
+/common:audit-claude-alignment --since=2026-06-30       # rattrapage après un trou de cadence
+```

package/Dev/i18n/base/Common/commands/search.md

@@ -102,7 +102,8 @@ When a user invokes `/common:search <keyword>`:
 | `architecture` | architecture skill, @database-architect |
 | `react` | /react:* commands, @react-reviewer |
 | `symfony` | /symfony:* commands, @symfony-reviewer |
-| `audit` | /team:audit, /common:audit-freshness |
+| `audit` | /team:audit, /common:audit-freshness, /common:audit-claude-alignment |
+| `claude code` | /common:audit-claude-alignment, .claude/COMPATIBILITY.md |
 | `workflow` | /workflow:* commands, workflow-analysis skill |
 
 ---

package/Dev/i18n/base/Vercel/checklists/new-feature.md

@@ -0,0 +1,75 @@
+# Vercel New Feature Checklist
+
+> Covers adding a new Serverless Function, Cron Job, or platform-level config change. For the framework running on top of Vercel (Next.js, etc.), see that stack's own new-feature checklist — this covers **only** the Vercel-platform surface.
+
+## Before Starting
+
+- [ ] **Requirements clear** - expected behavior and acceptance criteria defined
+- [ ] **Project shape identified** - static+rewrites / Serverless Functions / ISR-enabled / Cron+Scheduled (see `02-architecture-vercel.md`)
+- [ ] **Ownership checked** - if a claude-craft framework stack already owns routing/caching for this concern, defer to it rather than adding a competing `vercel.json` entry (see the decision tree in `02-architecture-vercel.md`)
+
+## Runtime Decision
+
+- [ ] **Node.js runtime (Fluid Compute) chosen by default** - no explicit `runtime` export needed
+- [ ] **Edge Runtime only chosen for an explicit, justified reason** - documented in a code comment at the top of the handler (e.g. genuine sub-Node-cold-start geo-routing need); never chosen by default or "for consistency" with older code
+- [ ] **If migrating a legacy Edge handler**, treated as a migration-audit task with its own verification pass, not copied as a template for new code
+
+## Caching Decision
+
+- [ ] **ISR/cache-header need identified** - does this route need periodic regeneration, or is a static response sufficient?
+- [ ] **If ISR is needed and a framework stack owns the route** - configured via that framework's own primitive, not hand-rolled `Cache-Control` headers in `vercel.json`
+- [ ] **If no framework owns the route** - any manual revalidation is implemented as plain HTTP caching via `vercel.json` `headers`, and documented as such (not called "ISR" — that term is reserved for the framework-level primitive)
+
+## Storage Decision
+
+- [ ] **Provider chosen deliberately**: Vercel Blob (native, for file/object storage) vs. a Marketplace integration (Neon for Postgres, Upstash for KV/Redis) - never `@vercel/kv` or `@vercel/postgres` (deprecated native packages)
+- [ ] **Connection/credentials sourced from the Marketplace integration's env vars**, not hardcoded or copied from a personal account
+
+## Cron Feature (if applicable)
+
+- [ ] **`crons` entry added to `vercel.json`** with a valid 5-field UTC schedule
+- [ ] **Plan's minimum interval and cron cap checked** before committing to a sub-hourly schedule
+- [ ] **Secret-guard implemented** in the handler (`Authorization: Bearer ${CRON_SECRET}`), see `templates/function-handler.template.ts`
+
+## Implementation
+
+- [ ] **Handler created** under `api/` (or the project's existing convention), one default export per file
+- [ ] **Env var validation guard added** at the top of the handler for any newly required variable
+- [ ] **`vercel.json` updated** with only the sections the new feature actually needs (`functions`, `crons`, `headers`) - no invented `regions`/`maxDuration`/`memory` values (YAGNI, rule 05)
+- [ ] **No secret hardcoded** - read from `process.env` only
+
+## Testing
+
+### Unit Tests
+
+- [ ] **Handler tested directly** by constructing a `Request` and asserting on the `Response` (or mocking the minimal `VercelRequest`/`VercelResponse` subset for legacy handlers)
+- [ ] **Method-not-allowed and malformed-input branches covered**
+- [ ] **Handler logic coverage >= 85%**
+
+### Cron Tests (if applicable)
+
+- [ ] **Secret-guard tested at 100%**: missing header, wrong secret, and correct secret — all three branches
+
+### Integration
+
+- [ ] **`vercel dev` smoke test** exercises the new route's `vercel.json` behavior (headers/rewrites/redirects), where applicable
+
+## Documentation
+
+- [ ] **`.env.example` updated** if a new env var was introduced
+- [ ] **`vercel.json` changes reviewed like code** - diffed and explained in the PR description, not silently regenerated
+
+## Final Checks
+
+- [ ] **Lint passes** - `npx eslint .`
+- [ ] **Types pass** - `tsc --noEmit`
+- [ ] **Tests pass** - `npx vitest run`
+- [ ] **`vercel.json` validated** - `npm run lint:vercel-config`
+- [ ] **`vercel build`** succeeds locally before pushing
+
+## Pull Request
+
+- [ ] **Descriptive title**
+- [ ] **Linked to issue/ticket**
+- [ ] **Any new deprecated-package or Edge Runtime usage explicitly justified** in the description
+- [ ] **Reviewers assigned**

package/Dev/i18n/base/Vercel/checklists/pre-commit.md

@@ -0,0 +1,59 @@
+# Vercel Pre-Commit Checklist
+
+> Covers the platform-specific surface only (`vercel.json`, `api/**`, `middleware.ts`). For the framework running on top of Vercel (Next.js, etc.), see that stack's own pre-commit checklist.
+
+## Quick Checks
+
+Run before every commit:
+
+```bash
+npx eslint . && tsc --noEmit && npx vitest run && npm run lint:vercel-config
+```
+
+## Checklist
+
+### `vercel.json`
+
+- [ ] **Validated against the platform schema** - `npx ajv validate -s schemas/vercel.schema.json -d vercel.json --strict=false`
+- [ ] **No key duplicated from a framework's own config** - check the decision tree in `02-architecture-vercel.md` before adding `headers`/`regions`/`functions`
+- [ ] **No invented `regions` or `functions.maxDuration`/`memory` value** - every non-default value has a concrete, documented reason (YAGNI, rule 05)
+- [ ] **Existing `vercel.json` never silently overwritten** - a regenerated file was diffed and confirmed against the previous version, not blindly replaced
+
+### Handler Code
+
+- [ ] **No secrets in handler code** - all secrets read from `process.env`, none hardcoded
+- [ ] **Env vars documented in `.env.example`** - every `process.env.X` referenced by a handler has a matching (empty/placeholder) entry
+- [ ] **Env var validation guard present** for any handler with a required var (see `templates/function-handler.template.ts`)
+- [ ] **No `console.log`** left in (warn/error only)
+
+### Cron Endpoints
+
+- [ ] **Secret-guard present** on every handler registered under `vercel.json`'s `crons` section - rejects requests missing or mismatching `Authorization: Bearer ${CRON_SECRET}`
+- [ ] **Guard is not the only line of defense** - path is not assumed to be secret/obscure
+
+### Deprecated Patterns
+
+- [ ] **No new `@vercel/kv` or `@vercel/postgres` import** - these native storage packages are deprecated; use Vercel Blob (native) or the Marketplace integrations (Neon for Postgres, Upstash for KV/Redis) instead
+- [ ] **No new `runtime: 'edge'` declaration** without an explicit migration comment - Edge Runtime is deprecated in favor of Fluid Compute; a legacy handler being touched must carry a comment explaining why it still targets Edge (see the migration note in `templates/function-handler.template.ts`)
+
+### Testing
+
+- [ ] **Tests pass** - `npx vitest run`
+- [ ] **New handler has tests**
+- [ ] **Coverage maintained** (>= 85% handler logic, 100% secret-guard branches)
+
+## Commands
+
+```bash
+# Full pre-commit check
+npx eslint . && tsc --noEmit && npx vitest run
+
+# Validate vercel.json against the platform schema
+npx ajv validate -s schemas/vercel.schema.json -d vercel.json --strict=false
+
+# Check for deprecated storage packages
+grep -rn "@vercel/kv\|@vercel/postgres" api/ package.json
+
+# Check for un-annotated Edge Runtime declarations
+grep -rn "runtime.*=.*['\"]edge['\"]" api/ middleware.ts 2>/dev/null
+```

package/Dev/i18n/base/Vercel/commands/check-architecture.md

@@ -0,0 +1,152 @@
+---
+description: Audit Vercel deployment configuration structure and project shape classification
+---
+
+# Vercel Architecture Audit
+
+You are an expert Vercel platform architect. Analyze the project's `vercel.json` and deployment configuration for correctness and maintainability, strictly within the deployment-platform scope of this stack.
+
+> Vercel is a **deployment platform**, not a framework. This command covers **only** `vercel.json`, Serverless Functions, ISR, Cron Jobs, Storage, and env/Preview Deployment config. For the framework's own routing/rendering/data-fetching conventions (e.g. Next.js App Router), use that framework's own `check-architecture` command instead.
+
+## MISSION
+
+Validate `vercel.json` schema correctness, classify the project's deployment shape, and flag configuration that duplicates or conflicts with a framework's native Vercel adapter.
+
+## Plan Mode
+
+> Plan mode is activated automatically when the scope spans multiple modules or requires cross-cutting investigation.
+
+## AUDIT AREAS
+
+### 1. Project Shape Detection
+
+```
+[ ] Identify shape: static+rewrites | Functions-backed | ISR-enabled | Cron+scheduled (or a combination)
+[ ] api/ directory present and mapped to Serverless Functions — Functions-backed shape
+[ ] revalidate / `Cache-Control: s-maxage` used on responses — ISR-enabled shape
+[ ] crons[] declared in vercel.json — Cron+scheduled shape
+[ ] Purely static output with rewrites/redirects only — static+rewrites shape
+```
+
+### 2. vercel.json Schema Validity
+
+```
+[ ] Valid JSON, conforms to the documented vercel.json schema (no unknown top-level keys)
+[ ] "$schema" reference present (editor validation) — optional but recommended
+[ ] No deprecated keys (e.g. legacy `routes` mixed with modern `rewrites`/`redirects`/`headers`)
+[ ] version field absent or set to 2 (legacy v1 config not used)
+```
+
+### 3. rewrites / redirects / headers Correctness
+
+```
+[ ] rewrites[] source patterns do not shadow static files unintentionally
+[ ] redirects[] use explicit `permanent: true|false` (never left implicit)
+[ ] headers[] scoped with precise `source` globs, not a blanket "/(.*)" for sensitive headers
+[ ] No conflicting rules where two rewrites/redirects match the same source with different destinations
+```
+
+### 4. regions / functions Configuration
+
+```
+[ ] functions{} block scopes memory/duration per-function-glob, not globally overbroad
+[ ] regions[] declared explicitly if data locality matters (default is auto/global)
+[ ] maxDuration set deliberately per function tier (not left at platform default for long-running jobs)
+[ ] Node.js runtime used by default; Edge Runtime only present with an explicit migration flag/comment
+```
+
+### 5. crons[] Configuration
+
+```
+[ ] Each cron entry has a valid path and schedule (standard cron syntax)
+[ ] Cron target endpoint exists under api/ and is not also publicly routable without auth (cross-check with check-security)
+[ ] No duplicate schedules pointing at the same path
+[ ] Cron frequency respects plan limits (documented, not assumed)
+```
+
+### 6. Framework Adapter Conflict Detection
+
+```
+[ ] No vercel.json rewrites duplicating a Next.js/Nuxt/SvelteKit adapter's own routing output
+[ ] No manual functions{} overrides fighting the framework's auto-detected build output
+[ ] next.config.js / nuxt.config.ts (or equivalent) is the source of truth for framework routing; vercel.json only for platform-level concerns
+```
+
+## OUTPUT FORMAT
+
+```
+══════════════════════════════════════════════════════════════
+VERCEL ARCHITECTURE AUDIT
+══════════════════════════════════════════════════════════════
+
+📊 ARCHITECTURE SCORE: XX/100
+
+🧭 PROJECT SHAPE
+──────────────────────────────────────────────────────────────
+Detected Shape: [static+rewrites | Functions-backed | ISR-enabled | Cron+scheduled | combination]
+Status: ✅ Consistent with conventions | ⚠️ Partial drift | ❌ Non-conforming
+
+Issues:
+- api/ directory present but no corresponding functions{} scoping in vercel.json
+  → Add explicit memory/duration bounds per function glob
+
+⚙️ VERCEL.JSON SCHEMA
+──────────────────────────────────────────────────────────────
+Status: ✅ Valid | ⚠️ Needs cleanup | ❌ Invalid
+
+Issues:
+- legacy `routes` array present alongside `rewrites`
+  → Migrate fully to `rewrites`/`redirects`/`headers`, remove `routes`
+
+🔀 REWRITES / REDIRECTS / HEADERS
+──────────────────────────────────────────────────────────────
+Rules found: X
+Conflicting rules: X
+
+Issues:
+- two redirects match "/blog/:slug" with different destinations
+  → Consolidate into a single unambiguous rule
+
+🌎 REGIONS / FUNCTIONS
+──────────────────────────────────────────────────────────────
+Status: ✅ Scoped deliberately | ⚠️ Overbroad | ❌ Missing
+
+Issues:
+- functions{} block sets maxDuration: 60 globally via "api/**"
+  → Scope duration per function tier; most handlers need far less
+
+⏰ CRON JOBS
+──────────────────────────────────────────────────────────────
+Crons declared: X
+Auth-guarded targets: X/X
+
+Issues:
+- crons[] target api/cleanup.ts also reachable as a public route
+  → See check-security for the CRITICAL auth-guard finding
+
+🧩 FRAMEWORK ADAPTER CONFLICTS
+──────────────────────────────────────────────────────────────
+Status: ✅ No conflicts | ⚠️ Overlap detected
+
+Issues:
+- vercel.json rewrites duplicate Next.js's own output routing
+  → Remove; let the framework's adapter own this concern
+
+📋 RECOMMENDATIONS
+──────────────────────────────────────────────────────────────
+Priority 1: [Resolve conflicting rewrite/redirect rules]
+Priority 2: [Scope functions{} bounds per handler]
+Priority 3: [Guard cron endpoints with a secret-header check]
+
+══════════════════════════════════════════════════════════════
+```
+
+## PROCESS
+
+1. Parse `vercel.json` and validate against the documented schema
+2. Detect project shape from directory layout (`api/`, cron declarations, revalidate usage)
+3. Validate rewrites/redirects/headers for conflicts and overbroad globs
+4. Review `regions`/`functions` scoping and runtime choice (Node.js default vs legacy Edge Runtime)
+5. Validate `crons[]` entries and cross-check target auth (flag for `check-security`)
+6. Detect configuration that duplicates or conflicts with a framework's native Vercel adapter
+7. Generate architecture report with a score out of 100