# Bar-model solution agent contract (Workstream B)

You convert **one P6 past-paper** into drawn Singapore **model-method (bar) diagrams**
for the questions that genuinely suit one. You ONLY read local files and write ONE
JSON file. You do NOT touch the database, SSH, git, or the network.

## Input
A paper folder under `docs/past year questions/P6/<folder>/` containing:
- `manifest.json` — `paper.source_prefix` + `questions[]` each with `n`, `question`,
  `answer0..3`, `correct_answer`, `type_id`, `explanation`, `source`.
- `paper.pdf` — the original paper. **The printed answer key / working is usually
  in this PDF.** Use it to confirm answers and to read the intended method.

## What to select
Emit a model ONLY for questions whose structure is naturally a bar model:
- part–whole (a whole split into parts), comparison (A vs B, "more than", "times as"),
- fraction/percentage **of a quantity**, ratio sharing, before–after / transfer,
- "remainder" problems, equal-groups word problems.

SKIP: pure computation (`12 tenths as a decimal`), geometry/area/angles, measurement
conversion, data/graph reading, and anything where a bar adds no insight. Quality over
coverage — a typical P6 paper yields ~5–12 models.

**Also skip any question whose manifest `type_id` is `0`** — those are free-response /
construction items that are NOT loaded into the app, so a model for them has nowhere to
attach. Only emit models for `type_id` 1 (MCQ) or 2 (fill-in).

## Output
Write `docs/past year questions/P6/<folder>/barmodels.json`:

```json
{
  "source_prefix": "ACS 2022 P6 Prelim",
  "models": [
    {
      "n": 17,
      "answer": "$480",
      "answer_matches_key": true,
      "working": "4 units \\(= \\$640\\). 1 unit \\(= \\$160\\). Alan \\(= 3\\) units \\(= \\$480\\).",
      "spec": {
        "unit_px": 90,
        "bars": [
          {"label": "Alan", "segments": [
              {"u": 1, "fill": "#dbe9ff"}, {"u": 1, "fill": "#dbe9ff"}, {"u": 1, "fill": "#dbe9ff"}],
           "brace": {"text": "?"}},
          {"label": "Ben", "segments": [{"u": 1, "fill": "#ffe7c2"}]}
        ],
        "total": {"text": "$640", "bars": [0, 1]}
      }
    }
  ]
}
```

### Field rules
- `n` — the question number (integer), must match `manifest.questions[].n`.
- `answer` — the final answer string (use `\\(...\\)` for any fraction/math).
- `answer_matches_key` — `true` if your answer matches the paper's printed key; if the
  printed answer looks wrong or is missing, set `false` and explain in `working`.
- `working` — short model-method prose (units → value). Inline math as `\\(...\\)`
  (NOT `$...$`). This is shown above the drawn image and must stand alone if the
  image fails to load.
- `spec` — passed verbatim to the renderer. Schema:
  - `unit_px` (int, default 90) — width of ONE unit box. Pick so the widest bar is
    ≤ ~7 units; for many units use a smaller `unit_px` (e.g. 60).
  - `bars[]` — top-to-bottom. Each bar:
    - `label` (string, left of the bar; "" for none)
    - `segments[]` — left-to-right boxes. Each: `u` (unit width, integer ≥1),
      optional `text` (label INSIDE the box, e.g. a value or "?"), optional `fill`
      (hex; default white). Use the SAME fill for equal units of one quantity.
    - optional `brace` `{ "text": "?" }` — draws a brace UNDER the whole bar (use for
      the unknown total of a single bar).
  - optional `total` `{ "text": "$640", "bars": [i, j] }` — a brace to the RIGHT
    spanning the listed bar indices (0-based) with a label; use for the combined total.

### Conventions
- Represent unknowns as a `?` (either a segment `text` or a `brace`/`total` text).
- Keep ≤ 6 bars and ≤ ~8 units per bar; merge where sensible so it stays readable.
- One model per question. If a problem truly needs before/after, emit two bars labelled
  "Before"/"After" in the same spec.
- Do not invent numbers — every value must come from the question or its key.

Return a one-paragraph summary: paper, how many models emitted, how many questions
skipped, and any answer-key mismatches you flagged.