chore: add repo refresh onboarding and CI

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.3.6"
+
+      - name: Install ffmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Doctor
+        run: bun run doctor
+
+      - name: Fast tests
+        run: bun run test:fast

AGENTS.md

@@ -0,0 +1,76 @@
+# AGENTS.md
+
+## Purpose
+
+This repo is an Instagram media export lab. It provides deterministic CLI slices for recommending upload profiles, analyzing fixtures, exporting image/video media, generating overlay guides, previewing grid crops, and running validation matrices.
+
+## Prerequisites
+
+- Bun 1.3 or newer.
+- TypeScript through `bunx tsc`.
+- `ffmpeg` and `ffprobe` on `PATH`.
+- macOS `sips` only when regenerating PNG/JPEG raster fixtures with `bun run fixtures:images:raster`.
+
+Run `bun run doctor` after install to verify local tools, writable temp/output directories, and required fixture media.
+
+## Install
+
+```bash
+bun install --frozen-lockfile
+bun run doctor
+```
+
+## Quality Gates
+
+Use `bun run check` before small PRs. It runs typecheck, Biome lint, and fast tests.
+
+Use `bun run test:ci` for the same gate CI runs. Use `bun run test:slow` before changing ffmpeg-heavy export, report-export, benchmark, validate-matrix, e2e, visual, or property behavior.
+
+The full test suite is intentionally explicit about timeout with `bun run test:all`, because ffmpeg-heavy tests should not rely on Bun's default 5 second per-test timeout.
+
+## Common Commands
+
+```bash
+bun run recommend --mode reliable --surface feed --orientation portrait --json
+bun run analyze tests/fixtures/images/portrait_sample_30x40.png --mode reliable --surface feed --json
+bun run export-image tests/fixtures/images/portrait_sample_30x40.png --out tests/fixtures/exports/demo.jpg --mode reliable --surface feed --json
+bun run export-video tests/fixtures/images/portrait_video_360x640.mp4 --out tests/fixtures/exports/demo.mp4 --mode reliable --surface reel --json
+bun run validate-matrix tests/fixtures/matrix/cases_basic.json --json
+```
+
+## Test Layers
+
+- `bun run test:unit`: pure domain and helper tests.
+- `bun run test:fast`: unit tests plus lightweight CLI/overlay/grid/watch-folder integration tests.
+- `bun run test:slow`: ffmpeg-heavy integration, e2e, visual, and property suites.
+- `bun run test:all`: every Bun test with an explicit 30 second timeout.
+
+## Fixture Regeneration
+
+Only regenerate fixtures when behavior intentionally changes.
+
+```bash
+bun run fixtures:images
+bun run fixtures:images:raster
+bun run fixtures:e2e
+bun run fixtures:visual
+bun run fixtures:pixel
+```
+
+`fixtures:images:raster` uses `sips`, so it is macOS-only. Video fixtures use `ffmpeg`.
+
+## Architecture Map
+
+- `src/cli`: command entry points and argument parsing.
+- `src/domain`: deterministic policy, analysis, export, report, benchmark, and validation logic.
+- `src/types/contracts.ts`: shared public contracts.
+- `config`: versioned ruleset and export profile JSON.
+- `tests/fixtures`: source media and golden outputs.
+
+## Known Slow Areas
+
+The slowest tests are export, export-video, report-export, benchmark, validate-matrix, e2e snapshots, and pixel visual checks. They invoke ffmpeg, ffprobe, or compare generated media artifacts.
+
+## Branch Knowledge
+
+For feature branches, update the relevant file in `docs/` with the problem, decisions, commands run, and lessons learned. For this refresh stack, use `docs/repo_refresh_audit.md`.

README.md

@@ -1,99 +1,113 @@
 # instagram-upload-quality-lab
 
-Phase 1 implements a deterministic `recommend` vertical slice for Instagram profile selection.
+Deterministic Bun CLIs for experimenting with Instagram-oriented media recommendations, exports, reports, and validation matrices.
 
-Example fixture image used in tests:
+The project currently supports profile recommendations, media inspection, image/video export through ffmpeg, white-canvas variants, crop-safe overlays, profile-grid previews, watch-folder scans, report-export comparisons, and benchmark summaries.
 
-- `/Users/jonas/repos/passepartout/tests/fixtures/images/portrait_sample_30x40.ppm`
+## Prerequisites
+
+- Bun 1.3 or newer.
+- TypeScript through `bunx tsc`.
+- `ffmpeg` and `ffprobe` on `PATH`.
+- macOS `sips` only if you regenerate raster image fixtures.
 
 ## Install
 
 ```bash
-bun install
+bun install --frozen-lockfile
+bun run doctor
 ```
 
-## Run CLI
-
-```bash
-bun run recommend --mode reliable --surface feed --orientation portrait
-```
+## Run
 
-JSON output:
+Recommend an upload profile:
 
 ```bash
 bun run recommend --mode reliable --surface feed --orientation portrait --json
 ```
 
-Analyze from file:
+Analyze fixture media:
 
 ```bash
-bun run analyze tests/fixtures/images/portrait_sample_30x40.ppm --mode reliable --surface feed --json
+bun run analyze tests/fixtures/images/portrait_sample_30x40.png --mode reliable --surface feed --json
 ```
 
-Generate crop-safe overlay guide geometry:
+Export an image:
 
 ```bash
-bun run overlay --ratio 4:5 --json
+bun run export-image tests/fixtures/images/portrait_sample_30x40.png --out tests/fixtures/exports/demo.jpg --mode reliable --surface feed --json
 ```
 
-Simulate profile-grid square crop visibility:
+Export a video:
 
 ```bash
-bun run grid-preview --ratio 4:5 --json
+bun run export-video tests/fixtures/images/portrait_video_360x640.mp4 --out tests/fixtures/exports/demo.mp4 --mode reliable --surface reel --json
 ```
 
-Export image using deterministic preset:
+Generate overlay and grid-preview geometry:
 
 ```bash
-bun run export-image tests/fixtures/images/portrait_sample_30x40.png --out tests/fixtures/exports/demo.jpg --mode reliable --surface feed --json
+bun run overlay --ratio 4:5 --json
+bun run grid-preview --ratio 4:5 --json
 ```
 
-Inspect deterministic export profile fields in JSON (`export_profile_id`, `quality_used`, `crf_used`):
+Run a validation matrix:
 
 ```bash
-bun run export-video tests/fixtures/images/portrait_video_360x640.mp4 --out tests/fixtures/exports/demo.mp4 --mode reliable --surface reel --json
+bun run validate-matrix tests/fixtures/matrix/cases_basic.json --json
 ```
 
-Export image with white-canvas `polaroid_classic` style:
+## Quality Gates
 
 ```bash
-bun run export-image tests/fixtures/images/landscape_sample_48x32.jpg --out tests/fixtures/exports/demo_white_classic.jpg --mode reliable --surface feed --white-canvas --canvas-profile feed_compat --canvas-style polaroid_classic --json
+bun run typecheck
+bun run lint
+bun run check
 ```
 
-Analyze supports this slice's image fixtures:
+`bun run check` is the normal pre-PR gate: typecheck, lint, and fast tests.
 
-- `PPM` (`.ppm`)
-- `PNG` (`.png`)
-- `JPEG` (`.jpg`, `.jpeg`)
-
-## Test
-
-```bash
-bun test
-```
-
-Layered test commands:
+Test layers:
 
 ```bash
 bun run test:unit
-bun run test:integration
-bun run test:e2e
-bun run test:visual
-bun run test:visual-pixel
-bun run test:property
+bun run test:fast
+bun run test:ci
+bun run test:slow
 bun run test:all
 ```
 
-Regenerate snapshots/fixtures when needed:
+`test:slow` and `test:all` use an explicit 30 second per-test timeout for ffmpeg-heavy cases.
+
+## Fixtures
+
+Source fixtures live under `tests/fixtures/images`. Generated export outputs go to `tests/fixtures/exports`.
+
+Regenerate fixtures only when behavior intentionally changes:
 
 ```bash
 bun run fixtures:images
 bun run fixtures:images:raster
 bun run fixtures:e2e
-bun run fixtures:e2e:analyze
-bun run fixtures:e2e:overlay
-bun run fixtures:e2e:grid-preview
-bun run fixtures:e2e:export
 bun run fixtures:visual
 bun run fixtures:pixel
 ```
+
+`fixtures:images:raster` depends on macOS `sips`. Video fixture generation depends on `ffmpeg`.
+
+## Docs
+
+- `AGENTS.md`: fresh-clone setup, quality gates, architecture map, and agent workflow notes.
+- `docs/repo_refresh_audit.md`: refresh audit findings, decisions, and follow-up order.
+- `docs/phase1_knowledge.md`: previous milestone implementation notes.
+
+<!-- status:start -->
+## Status
+- State: active
+- Summary: Repo refresh stack in progress.
+- Next: Submit Graphite stack after checks pass.
+- Updated: 2026-05-01
+- Branch: `repo-refresh-onboarding-ci`
+- Working Tree: clean
+- Last Commit: chore: add repo refresh onboarding and CI
+<!-- status:end -->

biome.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.13/schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noExplicitAny": "error"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  }
+}