# AGENTS.md

This file tells AI coding agents (Codex CLI, Cursor, Copilot, Windsurf, Devin, Aider, Warp, Zed, and others) how to work in the Closeread repository.

## What this repo is

Closeread is the site and operational code for a 48-hour codebase audit service for indie SaaS founders selling on Acquire. The audit work itself is performed by Free Guy, an AI agent, in a separate sandbox. This repo is the public surface (closeread.io), the audit packet template, the per-language appendices, and the intake plumbing.

## Build and test

- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`
- Tests: `pnpm test`
- Type-check: `pnpm typecheck`
- Lint: `pnpm lint`

Run `pnpm typecheck && pnpm lint && pnpm test && pnpm build` before any commit that touches `src/`. CI gates on zero errors across all four.

## Code style

- TypeScript strict mode. No `any` without an inline `// reason:` comment.
- Single quotes. No semicolons. Two-space indentation.
- One default export per file when exporting a component. Named exports otherwise.
- No em dashes anywhere (style rule, enforced by lint).

## Repository conventions

- `src/` is product code. Edit freely with the workflows above.
- `content/` is human-readable copy (homepage, packet template, appendices). Treat as load-bearing prose, not boilerplate.
- `content/machine-readable/` is the agent surface (this file, llms.txt, agent-card.json). Update in lockstep with `src/` when the site sitemap or offer changes.
- `decisions/` is the architecture decision record. Add a new ADR before any change that crosses a service boundary or introduces a new dependency.
- `.env*` files are gitignored. Real secrets live in 1Password and are injected at deploy time.

## Audit-specific rules

- When you generate or modify an audit packet, follow `content/audit-packet/template-v2.md` section ordering and the "Method / Findings / What this means for your buyer" three-part structure for every section.
- Findings rank by deal-impact, not raw CVSS. A High-CVSS dependency that's build-time-only ranks below a Medium-CVSS one that's user-input reachable.
- Every finding must cite file + line in `src/` or the audited customer repo. No findings without citations.
- Customer code never leaves the sandbox. Do not commit any file from `/tmp/audit-*/` into this repo.

## What not to touch without explicit approval

- Stripe payment link, product, or price (live commercial endpoint)
- DNS records, Cloudflare zone settings, email routing
- Anything in `secrets/` or any path matching `.env*`
- The audit registry at `/opt/brain/audits/registry.md` (append-only outside the audit-execution workflow)

## Free Guy and Jared

The founder of Closeread is Free Guy, an AI agent. Jared Fracker, Founder of Command Center Consulting, created Free Guy and reviews every customer-facing artifact before delivery. If a task touches outbound communication, billing, or third-party commitments, surface to Jared before acting.

## When you get stuck

Open an issue. Tag with `agent-blocked` and include: what you tried, what the error was, what you'd need to unblock. Free Guy reads `agent-blocked` issues daily.