Picture Parrot guide format 1.0 - instructions for agents
==========================================================

Picture Parrot turns one photo into an ordered, step-by-step guide that
helpers can follow, check off, and print. This file explains how an agent can
prepare a guide for a person to review.

Where this works
----------------
This is a preview feature. The /developers page of the Picture Parrot app
registers two WebMCP browser tools while that page is open in a browser that
supports WebMCP (document.modelContext). It is not a remote MCP server and not
a public REST API. Availability on the public pictureparrot.com site is not
promised; check the page itself. Tools may not be visible when the app runs
inside an embedded preview frame; open it in its own browser tab instead.

Tools
-----
1. picture_parrot_guide_format
   Read-only. Returns this format's JSON Schema and an example.
   No account or guide data is returned.

2. picture_parrot_prepare_guide
   Input: one guide object (schema below).
   Validates the guide and opens a visible review on the page.
   It does NOT save, publish, call AI, or use a guide slot.
   Returns a JSON string:
     {"status":"ready_for_review","saved":false,"guide":{...normalized...},
      "supplyTotals":[{"title","amount","multiplier","total","basis"}],
      "nextAction":"..."}
   or, when the guide cannot be used:
     {"status":"rejected","saved":false,"error":"..."}
   Only one review can be open. If one is open, the tool is rejected with
   "A review is already open. Finish or discard it before preparing another."
   Ask the person to finish or discard it first.

The person then reviews the photo and steps, can rename the guide and drag
pins, and chooses "Create editable guide". Creating requires their own
Picture Parrot sign-in and follows their plan's guide limit (Free: 3 guides,
Pro: unlimited). Every step stays editable after creation.

Guide object
------------
schemaVersion  required. Always "1.0".
title          required. 1-120 characters.
occasion       optional. Up to 60 characters.
photo          required. One of the bundled sample paths:
                 /assets/birthday-table.png
                 /assets/wedding-centerpiece.png
                 /assets/corporate-swag-station.png
                 /assets/kids-hiking-kit.png
               or a base64 data URL: data:image/png|jpeg|webp;base64,...
               Decoded maximum 8 MiB. The bytes must match the declared type.
               Remote URLs are not accepted and are never fetched.
eventPlan      optional. {"count": 1-10000 integer,
                          "singular": "table", "plural": "tables"}
               (labels 1-30 characters). Required when any pin repeats.
pins           required. 1-100 pins in display order (step 1 first).

Each pin
--------
title          required. 1-120 characters.
x, y           required. Numbers from 0 to 1: the pin's position as a
               fraction of the photo's width (x, from the left edge) and
               height (y, from the top edge). Same convention as saved pins.
instruction    optional. Up to 2000 characters.
quantity       optional. Amount per repeating unit, or once per event.
               Use a numeric string ("2", "1.5") for calculated totals.
               Leave empty when unknown; it is never guessed.
unit           optional. Up to 64 characters ("candles and holders").
supplyBasis    optional. "repeat" multiplies quantity by eventPlan.count.
               "fixed" (default) means once per event.
location       optional. Where to find the supplies. Up to 120 characters.
assignee       optional. Helper name. Up to 120 characters.
packingNote    optional. What to pack away afterwards. Up to 2000
               characters.

Unknown fields are rejected. Text is trimmed. Values over a field's limit
are rejected with a message naming the field.

Do not send
-----------
IDs, owner credentials, share links, or completion flags. Picture Parrot
creates fresh IDs, and every step starts unchecked.

Example
-------
See /developers/example.json. The wedding example uses 40 tables, so
"2 candles and holders per table" totals 80.

Schema
------
See /developers/guide.schema.json (JSON Schema 2020-12).