# Agent instructions — Portfolio

Read this file at the **start of any task** in this repo.

## Backlog (required)

1. Read [`BACKLOG.md`](BACKLOG.md) and [`backlog/items.yaml`](backlog/items.yaml).
2. If the user named an id (e.g. `A-003`), work that item.
3. Else if doing unlisted work, check the backlog anyway — avoid duplicating ready items.
4. For **new** tasks Vincent describes, add an entry to both files (use the template in `BACKLOG.md`).
5. When you **start** an item: set `status: in_progress` in yaml and move it in `BACKLOG.md`.
6. When you **finish**: set `status: done`, move to Done, note commit in `done_note`. Run `node scripts/build-cases.mjs` if `cases/` changed.

**Pickable agent work:** `owner: agent` and `status: ready` in `backlog/items.yaml`.

**Human-owned:** `owner: human` (screenshots, client content, strategic decisions) — do not mark done without Vincent's input.

## Repo map

| Path | Role |
|------|------|
| `index.html` | Homepage (inline CSS/JS) |
| `cases/{slug}/` | Case source: `meta.json` + `body.html` |
| `scripts/build-cases.mjs` | Generates `work/*.html`, fragments, sitemap |
| `work/` | Built case pages + carousel (`cases.html`) |
| `templates/standalone.html` | Shell for standalone case pages |

## Build

```bash
node scripts/build-cases.mjs
node scripts/build-lab.mjs   # Lab cards from vkogmail/lab (see AGENTS.md)
node scripts/check-lab-links.mjs   # optional — verify lab demo URLs before deploy
```

Run before deploy and after editing `cases/`. Vercel runs this in `vercel.json` `buildCommand`.

## Case header convention

`meta.json` → `header` block. `body.html` uses `{{CASE_HEADER}}`, `{{CASE_TAGS}}` inside `.case-lead`. See any `cases/*/meta.json` for examples.

## Lab content source

The `#lab` section is **only** fed from the lab monorepo ([`vkogmail/lab`](https://github.com/vkogmail/lab), local `• Projecten/lab-monorepo`).

- **Public GitHub** shows `apps/` and root `lab-cards.json` only — inventory, `packages/brand`, and monorepo tooling stay local. Web demos vendor `public/brand/` before push.
- Each experiment owns `apps/{name}/lab.card.json`; run `npm run build:cards` locally, then push `lab-cards.json` + app changes.
- **App READMEs** (public GitHub): code-first only — [`apps/README.md`](https://github.com/vkogmail/lab/blob/main/apps/README.md) + `README.template.md`. Portfolio URLs and showcase workflow belong in `lab.card.json` / local `LAB-SHOWCASE.md`, not in app READMEs.
- **Plugin landing pages** (`index.html`, `landing.html`, `hero.jpg`): gitignored on public GitHub; generated at Vercel build from `apps/_landing/`. Plugin source is `code.js` / `ui.html` / `src/`.
- **Do not hand-edit lab cards in this repo.** Change copy, URLs, or status in the lab repo, then sync:
  - **Deploy:** Vercel runs `node scripts/build-lab.mjs`, which fetches `lab-cards.json` from GitHub.
  - **Local:** with `lab-monorepo` checked out beside this repo, `node scripts/build-lab.mjs` reads `../lab-monorepo/lab-cards.json` automatically. Or set `LAB_CARDS_PATH=…` explicitly.
- Cached copy: `./lab-cards.json` (offline fallback if fetch fails).
- **Hero images:** when a card sets `"hero": "showcase/hero.png"`, `build-lab.mjs` copies from `lab-monorepo/apps/{slug}/` into `./lab-showcase/{slug}/` for the portfolio grid.
- **Specimens:** each card can show a small animated SVG icon. Set optional `"spec"` in `lab.card.json` (see lab schema enum), or rely on slug defaults in `scripts/lab-specs.mjs`. Hero screenshots (`hero`) replace the spec when set.
- **New lab card ship checklist:** see [`.cursor/rules/lab-card-ship.mdc`](.cursor/rules/lab-card-ship.mdc) — dedicated specimen animation + tag alignment are required; do not reuse a generic `spec` or skip portfolio CSS.

**Brand styling sync:** when homepage tokens, buttons, or nav change in `index.html` (or case chrome CSS), mirror into `lab-monorepo/packages/brand/` in the same session. See `.cursor/rules/lab-brand-sync.mdc` and `packages/brand/README.md` in the lab repo.

## Constraints

- Static site — no framework on homepage.
- Do not commit unless Vincent asks.
- Minimise scope; match existing patterns.

## LLM context (published site)

- `/llms.txt` · `/llms-full.txt` — public site summary (also link backlog when deployed).