poster-grid-inspector: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository. Read this before modifying code.

What this repo is

A model-agnostic poster grid analysis tool. The installable skill uses the host model's native vision capability by default. Its optional web/CLI mode sends a poster image to a vision model (OpenAI or any OpenAI-compatible provider), gets back the layout's grid system, parameters, detected elements, keylines, and analysis — then renders the grid overlaid on the image and can export it as SVG guides or CSS Grid / Tailwind code.

It ships as an installable agent skill (SKILL.md) plus a runnable web app / CLI.

Commands

npm run setup        # install deps + copy .env.example → .env (never edit .env.example with real keys)
npm start            # run the web server (http://localhost:8787)
npm run dev          # tsx watch (auto-reload)
npm run analyze -- <image> [--summary]   # CLI analysis, no server needed
npm run typecheck    # tsc --noEmit

TypeScript is run directly with tsx (no build step). .js in import paths maps to .ts.

Architecture

• server.ts — Express entry: express.json({limit:'25mb'}), static public/, analyzeGridRouter, GET /health.
• server/routes/analyzeGrid.ts — POST /api/analyze-grid route (validates imageBase64, calls analyzePoster, maps AiError → HTTP).
• server/ai/analyzePoster.ts — orchestration: cache → provider call (timeout + 1 retry) → normalize → validate → return { data, meta }.
• server/ai/providers/openai.ts — Responses API (/responses, input_image, strict json_schema). openaiCompatible.ts — Chat Completions (/chat/completions, image_url, json_object/json_schema, optional enable_thinking). http.ts — fetch wrapper.
• server/ai/config.ts — .env → AiConfig. Remote analysis is blocked unless AI_REMOTE_ANALYSIS=1; getAiConfig() then throws if AI_API_KEY is missing.
• server/ai/schema.ts — POSTER_ANALYSIS_JSON_SCHEMA + runtime validatePosterAnalysis.
• server/ai/normalize.ts — strip JSON fences, clean coordinates, migrate systemNameKo → systemName.
• server/ai/cache.ts — in-memory Map; key = sha256(image + provider + model + promptVersion + schemaVersion).
• public/index.html — self-contained frontend (no bundler): upload → analyze → overlay → export.
• src/ — shared types (posterVision.ts), client helpers (visionImage.ts, analyzeGridApi.ts, gridScoring.ts).