@topy-ai/maggie 0.7.52 → 0.7.54

package/bundled-references/maggiedash-booking/RULES.md

@@ -0,0 +1,167 @@
+# Booking rules and shared test vectors
+
+Every host built on the MaggieDash booking model implements these rules the
+same way. Each rule is a pure function with test vectors in
+[`contracts/maggiedash/booking-rules-v1.json`](../../bundled-contracts/maggiedash/booking-rules-v1.json)
+and a reference implementation in `tools/clis/maggie_booking_rules.py`.
+
+```bash
+maggie booking rules-vectors --list                     # rules, why they exist, vector counts
+maggie booking rules-vectors                            # reference implementation (must pass)
+maggie booking rules-vectors --host-command "node scripts/booking-rules.mjs"
+```
+
+`--host-command` runs the host's own code: the command reads one line
+`{"rule": "<id>", "input": {...}}` from stdin and prints the result JSON. Only
+the fields a vector lists are compared, so hosts may return more. Add the
+command to CI so a port of the engine cannot drift.
+
+Conventions: money is integer minor units; instants are UTC ISO-8601; local
+wall times are interpreted in the venue's IANA time zone.
+
+## Lifecycle
+
+**`manage_action`** — what a client's manage link may do. A client cancels
+or reschedules only a `confirmed` booking that has not started; never one
+on hold (`held`, `pending_payment`), arrived or in service, or closed
+(`completed`, `cancelled`, `no_show`, `expired`). A window policy stops
+online changes inside the window ("contact the business"). The business may
+cancel anything not closed but never reschedules a booking in service. Check
+the booking's **own** start time, not only the new slot's.
+
+**`late_payment`** — Checkout completed after the hold expired. If the time
+is still free, reinstate the booking as confirmed; otherwise refund the full
+amount on the connected account and tell the client the time was taken. A
+repeated event is a no-op. Never just record the payment: a paid client
+without a booking is the worst outcome. Hosts also need a job that expires
+`pending_payment` bookings whose Checkout session expired, so the slot is
+released.
+
+## Time and money
+
+**`schedule_to_utc`** — every schedule input (time off, closures, shifts,
+opening hours) is a local wall time in the **venue's** zone; the browser's
+zone never matters. Send the local value and the location id to the server,
+or convert with the venue zone in the client. A time skipped by the spring
+clock change is rejected; a repeated autumn time uses the first occurrence
+and is flagged. Staff without a location use their default location's zone.
+
+**`money_minor`** — node-postgres returns `bigint` as a string. Parse money
+columns to integers in the repository (or set `pg.types.setTypeParser(20,
+…)` when every value fits a safe integer) before any arithmetic or JSON for
+the booking sheet; reject decimals and floats.
+
+**`sale_total`** — till maths: item prices × quantity, plus add-ons **only
+when not already included in the booking item price** (a booking item that
+already contains its add-ons must not be charged twice), minus discounts,
+plus a service charge on the discounted amount (rounded half up). Vouchers
+and packages are payments against the total, not discounts. Tips are added
+after the service charge, never commissioned, and split between team members
+by share, handing out remainder pennies one at a time.
+
+The checkout around it: receipts for every sale, invoices and quotes with a
+number sequence per business, pay-by-QR (a Checkout link on the client's
+phone for the sale), and Stripe Terminal **server-driven** readers on the
+business's connected account (register by code per branch location; record
+the payment when the PaymentIntent succeeds; test with the simulated reader
+`simulated-wpe`).
+
+**`payment_policy_setup`** — deposit or full prepayment needs a connected
+account that can take charges. Setup refuses the policy until then (and
+`maggie booking release-gate` should flag a live service whose policy needs
+payments while they are off), instead of refusing clients at the last step.
+Do not create a `pending_payment` booking before the payment capability is
+confirmed.
+
+## Notifications and calendar
+
+**`reminders_due`** — reminder offsets are per business (default 24 h and
+2 h). Each stage is sent once per booking (store a sent marker per booking
+and stage; dedupe key `<booking>:reminder:<stage>`). A booking made inside a
+stage's window never gets that stage; a stage the worker missed is skipped,
+not sent late.
+
+**`notification_plan`** — cancellation and reschedule templates name who
+acted (`by_client`, `by_business`, `by_system`). The business is told when a
+client or the system cancels or reschedules; the client is always told.
+
+**`ics_text`** — escape `\`, `;`, `,` and newlines in TEXT values (RFC 5545)
+and fold lines at 75 octets. Attach the `.ics` to the confirmation e-mail
+(`text/calendar; method=PUBLISH`) rather than linking to it. Per-team-member
+calendar feeds use a long random token per person (revocable, rotated on
+role change) and show only that person's bookings, without client contact
+details.
+
+## Availability
+
+**`plan_slots`** (reference planner) and **`rota_week`**, **`price_for`**:
+
+- opening hours may have several ranges per day (lunch breaks);
+- staff may follow an N-week rota anchored to a Monday;
+- a staff member may have their own duration for a treatment;
+- "anyone available" picks the free person with the fewest bookings that
+  day, then sort order;
+- the service time must sit inside opening hours and staff hours and outside
+  closures; buffers only keep other bookings away (as MaggieDash `planSlots`);
+- an optional minimum gap rejects starts that would leave a gap shorter than
+  it next to another booking;
+- group bookings of 2-6 need that many free people at the same start;
+- slots are on the local grid and stay correct on clock-change days;
+- peak/off-peak price rules adjust the base price by weekday and local time.
+
+Multiple locations: run the planner per branch with that branch's hours,
+rooms and staff; a resource (room, bed) is free only when no overlapping
+allocation holds it.
+
+## Team
+
+**`permission_check`** — roles `owner`, `manager`, `reception`, `therapist`
+carry named permissions; the owner may grant or revoke them per role, except
+`team.manage` and `billing.manage`, which stay owner-only. "Own bookings
+only" follows from the absence of `bookings.view_all`, never from a role
+name. A **PIN switch** on a shared device can only lower the role
+(owner → therapist), and the effective role applies everywhere: API checks,
+pages, menus and actions such as clock-in — compute it once per request from
+the session and the switched profile, and render navigation from the same
+permission set.
+
+**`commission`** and **`hourly_pay`** — commission per person and kind
+(service, product) on net sales after discounts, never on tips or service
+charge; hourly pay from clock-in/out minus unpaid breaks, per minute. A pay
+run combines commission, hourly pay and tips per person for a period and
+exports CSV for accounting tools (columns: period, staff name, staff
+reference, hours, hourly pay, commission, tips, total, currency — map them to
+Xero/QuickBooks payroll or journal imports).
+
+## Clients
+
+**`online_booking_gate`** — client safety before online booking: a blocked
+client sees a neutral "please contact us" (never "you are blocked"); a
+treatment with a patch-test category needs a recorded patch test that is not
+older than its validity (for example 180 days) and at least 48 hours before
+the appointment. Health questions and the business's own health items are
+special-category data: store answers per client with consent and a version
+of the form, show them only to staff with `clients.health`, and keep them out
+of exports, analytics and AI prompts unless the client consented.
+
+**`merge_clients`** — merging duplicates adds both point balances and
+lifetime points, recomputes the tier, and keeps every history entry and
+membership. **`membership_credits`** — memberships bill monthly on the
+business's connected account; a paused month neither bills nor adds
+credits.
+
+**`link_booking_to_account`** — signed-in client accounts sit beside the
+token links: a guest booking joins an account only when the account's e-mail
+is verified and equal (case and spaces ignored). The account lists bookings,
+packages, memberships and saved cards (cards stay on the business's
+connected account; show brand, last four and expiry only). The manage-token
+link keeps working for guests.
+
+## Release smoke business
+
+Keep one **hidden production smoke business** per platform so release smoke
+tests can book, reschedule and cancel without touching real businesses:
+excluded from search, sitemaps and directories (`noindex`), pay-at-venue or a
+test-mode connected account only, its own staff and services, and bookings
+cleaned up by the smoke run. `maggie booking release-gate` evidence should
+include one full booking round trip on it after every production deploy.

package/bundled-references/maggiedash-booking/RUNTIME-OPERATIONS.md

@@ -67,7 +67,7 @@ loaded, the structured error output retains that prior timestamp for stale
 health evaluation. An external scheduler monitor is still required to detect
 a worker that never starts, because no in-process health report can be emitted
 while the process is down.
-The additive status table is now present in ORA staging; the six-job preview
+The additive status table is now present in the reference host's staging; the six-job preview
 there passed with `write=false`, zero alerts, and no provider dispatch. The
 preview intentionally left `last_success_at` empty. Production still needs the
 schema migration before the updated worker can run.
@@ -104,7 +104,7 @@ claim or delivery result. `--write` performs database writes and invokes the
 host provider for each claimed notification. Reconcile staging outbox/provider
 activity before any write-mode run.
 
-The generic Astro PostgreSQL worker and ORA host worker include the
+The generic Astro PostgreSQL worker and the reference host's worker include the
 schema-versioned `health` summary in successful cycle output and caught
 schema/lock/runtime failures. It carries stable alert codes, severity, a
 correlation ID, and counts only; the worker does not send an alert itself.

package/bundled-references/maggiedash-booking/STRIPE-INTEGRATION.md

@@ -44,11 +44,11 @@ and the [API reference](https://docs.stripe.com/api).
 | Events/webhooks | Core | Idempotent payment state projection | Verify raw body before parsing |
 | Coupons + Promotion Codes | Optional | Campaign and referral discounts | Stripe applies the discount; local rules own eligibility |
 | Customer Balance Transactions | Optional | Stripe invoice credits | Not a gift-card ledger by itself |
-| Billing Subscriptions + Invoices | Future | Memberships or recurring plans | Add only when recurring booking is a product requirement |
+| Billing Subscriptions + Invoices | Optional | Memberships billed monthly | On a platform, create them on the business's connected account; pause/resume per [RULES.md](./RULES.md) |
 | Customer Portal | Future | Customer-managed subscriptions and billing details | Use short-lived portal sessions |
 | Stripe Tax | Optional | VAT/tax calculation and transaction records | Confirm jurisdiction, evidence, and price ownership |
-| Terminal | Future | In-person deposits/balances | Requires reader operations and device lifecycle |
-| Connect | Future | Multi-merchant/platform money movement | Not for a single business or multi-location tenant |
+| Terminal | Optional | In-person payments at the till | Server-driven readers per branch location; simulated reader in test mode |
+| Connect | Platform | Many businesses on one booking platform | Direct charges on each business's connected account; see "Platform hosts" below. Not needed for one business or a multi-location tenant |
 
 The implementation maps Stripe's provider states into the existing normalized
 states (`requires_action`, `pending`, `failed`, `succeeded`, `cancelled`, and
@@ -105,6 +105,44 @@ accounting, CRM, support, analytics, marketing, and workflow automation. It is
 an integration surface, not a reason to add third-party credentials to the
 MaggieDash browser bundle.
 
+## Platform hosts (Stripe Connect)
+
+A single business, or one business with several locations, uses its own
+Stripe account and needs no Connect. A **platform** that hosts many
+independent businesses (a booking marketplace, a salon software provider)
+takes each business's payments on that business's own account:
+
+- **Accounts**: one connected account per business, created and onboarded
+  with Accounts v2 (`/v2/core/accounts`, account links). Store the account
+  id on the business workspace; never let a client choose it.
+- **Direct charges**: every Checkout Session, PaymentIntent, SetupIntent,
+  refund, subscription and Terminal call runs **on the connected account**
+  (`Stripe-Account` header / `stripeAccount` option). The business is the
+  merchant of record; its customers, saved cards and disputes live there.
+- **Fees**: an application fee is optional and a product decision; "no
+  platform fee" is a valid configuration — leave `application_fee_amount`
+  unset rather than zero.
+- **Events**: Connect events arrive with `event.account`. Use a Connect
+  (thin-event) destination or a Connect webhook endpoint with its own signing
+  secret. For every payment event check the **amount, currency and account**
+  against the booking before changing state; an event for another account is
+  ignored and logged.
+- **Saved cards and off-session charges** (deposits, no-show fees) use
+  SetupIntents on the connected account with the client's consent; a card
+  saved on one business is never visible to another.
+- **Memberships**: subscriptions on the connected account; pausing uses the
+  subscription's pause collection, and credits follow the
+  `membership_credits` rule in [RULES.md](./RULES.md).
+- **Payouts and disputes**: read them per account (`GET /v1/payouts`,
+  `/v1/disputes` with the account header) for the business's dashboard;
+  answering disputes stays in the Stripe Dashboard or an embedded component.
+- **Setup gate**: a business may choose deposit or full prepayment only once
+  its account can take charges (`payment_policy_setup` rule); the setup UI
+  blocks it and the release gate flags it.
+- **QA**: `maggie booking connect-qa --detect` finds a test-mode connected
+  account and prints the `stripe listen --forward-connect-to …` command and
+  the payment cases to run.
+
 ## Live setup runbook (read-only verification)
 
 Switching a host to live mode is the step most likely to create real objects
@@ -154,7 +192,7 @@ Any host-side live readiness check must likewise issue `GET` requests only.
 4. Coupons/Promotion Codes for campaigns; add local referral attribution.
 5. Stripe Tax if the host has the required tax configuration.
 6. Billing/Portal for memberships; Terminal for in-person operations; Connect
-   only for a true platform model.
+   for a platform that hosts many businesses (see "Platform hosts").
 7. Gift-card partner or local ledger after accounting and redemption rules are
    approved. The local-ledger option is fixed by the
    [voucher lifecycle contract](./VOUCHERS.md).

package/bundled-references/provider-adapter-contract.md

@@ -173,9 +173,22 @@ rules from a redacted JSON manifest; see the Social Share skill for shapes.
 
 ## Structured model output
 
-Keep structured-output schemas small. Gemini rejected a JSON schema whose enum
-had 125 values with `400 INVALID_ARGUMENT`, and the caller silently fell back
-for every request. For a large vocabulary (styles, categories, catalogue IDs):
+Keep structured-output schemas small. The limit is **schema complexity**, not
+vocabulary size: roughly enum values × repeated array items × nesting.
+Gemini rejected a JSON schema whose enum had 125 values with
+`400 INVALID_ARGUMENT`, and the caller silently fell back for every request.
+It also rejected a plan schema with a 5-6 value `template_key` enum on each
+of up to 20 array items (`maxItems: 20`) — immediately and with no detail —
+while 4 values or `maxItems: 10` passed. So:
+
+- never put an `enum` inside repeated array items; describe the allowed
+  values in the prompt or the field `description` and validate server-side;
+- keep `maxItems` small on arrays of objects, and always set it;
+- run `maggie tool maggie_social_share.py schema-check schema.json`
+  (`tools/clis/maggie_schema_complexity.py`) before a release; it fails on
+  the patterns above and reports an estimated complexity score.
+
+For a large vocabulary (styles, categories, catalogue IDs):
 
 1. ask for a free string (optionally with a short list of examples in the
    prompt) instead of a large `enum`;

package/bundled-skills/catalog.json

@@ -4,7 +4,7 @@
   "skills": [
     {
       "name": "maggie-assistant-tools",
-      "description": "Build an AI assistant's tools once and expose them safely to an in-app agent, an MCP server and ChatGPT/Claude apps. Use for tool registries, risk levels and gates, approval cards with signed one-time tokens, audit logs, MCP annotations, user-facing capability pages, publishing product CLI/MCP packages and app reviews, and multi-tenant assistant bridge hosts."
+      "description": "Build an AI assistant's tools once and expose them safely to an in-app agent, an MCP server and ChatGPT/Claude apps. Use for tool registries, risk levels and gates, result cards, approval cards with signed one-time tokens and standing workflow approvals, audit logs, MCP annotations, public discovery MCP and audience binding, visitor-facing receptionists, user-facing capability pages, publishing product CLI/MCP packages and app reviews, and multi-tenant assistant bridge hosts."
     },
     {
       "name": "maggie-auth-reference",

package/bundled-skills/maggie-assistant-tools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maggie-assistant-tools
-description: Build an AI assistant's tools once and expose them safely to an in-app agent, an MCP server and ChatGPT/Claude apps. Use for tool registries, risk levels and gates, approval cards with signed one-time tokens, audit logs, MCP annotations, user-facing capability pages, publishing product CLI/MCP packages and app reviews, and multi-tenant assistant bridge hosts.
+description: Build an AI assistant's tools once and expose them safely to an in-app agent, an MCP server and ChatGPT/Claude apps. Use for tool registries, risk levels and gates, result cards, approval cards with signed one-time tokens and standing workflow approvals, audit logs, MCP annotations, public discovery MCP and audience binding, visitor-facing receptionists, user-facing capability pages, publishing product CLI/MCP packages and app reviews, and multi-tenant assistant bridge hosts.
 metadata:
   version: 1.0.0
 ---
@@ -31,7 +31,9 @@ all read that one definition. Per tool:
 | `risk` | `read`, `write-reversible`, `write-spends` (credits, quota, AI generation), `write-public` (public or hard to undo), `never` (the assistant must not do it) — `R0`…`W4` are accepted aliases |
 | `gates` | declared preconditions, e.g. `verified-site`, `credits`, `ai-generation` |
 | `scope` | `account` or `workspace`; account writes are audited at account scope |
-| `channels` | `in-app`, `mcp`, `chatgpt`, `claude`, `cli` |
+| `channels` | `in-app`, `mcp`, `chatgpt`, `claude`, `cli`, `web-widget` (visitors) |
+| `card` | optional result card: `place`, `slot-picker`, `booking`, `voucher`, `change-preview`, `numbers`, `draft`, `list` |
+| `mcpServers` | which declared MCP servers expose the tool (public discovery vs signed-in) |
 
 Write user copy by hand. Rewriting model descriptions with regexes ("the
 user" → "you", dropping `(from connected_apps_list)`) needs overrides for a
@@ -55,6 +57,50 @@ tools are not served on MCP; list them on the capability page instead.
 you approve" and "publishes or is hard to undo", plus a "can't do" section
 from `cantDo` entries and `never` tools, using only user copy.
 
+## Result cards and conversations
+
+A tool may declare a `card`: the app and ChatGPT/Claude widgets render the
+result's structured content as that card (a place, a slot picker that opens
+booking, a change preview before approval, a set of numbers, a draft), and
+every other surface shows the text result, which the tool must still return.
+A `change-preview` card belongs to a write: it is what the approval card
+shows. Keep one card component per type and reuse it across tools.
+
+Declare where conversations live with `threads`. Server-stored threads let a
+person continue on another device and let support see a conversation **with
+consent**; they need `retentionDays`, `supportAccess` (`none` or
+`with-consent`) and `deleteOnAccountDeletion: true`. Keep approval tokens out
+of the stored thread text (they live with the model turn, see below).
+
+## MCP servers: public discovery and signed-in
+
+Declare servers in `mcpServers`:
+
+- **Public discovery** (`auth: "none"`) lets AI assistants and AI search
+  answer from published data: search, details, an availability summary and a
+  booking link. Read tools only, never account-scoped, and a `rateLimit`
+  per IP (per minute and/or per day). Serve only what the public web pages
+  already show; no customer data.
+- **Signed-in** (`auth: "oauth"`) binds every token to the server: `resource`
+  is the canonical https URL, clients send it as the RFC 8707 resource
+  indicator, and the server rejects tokens whose audience is another
+  resource. Binding is on by default; turning it off needs an
+  `audienceException` with the reason. Publish protected-resource metadata
+  (RFC 9728) and check it with `maggie product mcp-check`.
+
+## A visitor-facing receptionist
+
+A chat on a business's public page answers strangers, so no approval card is
+possible. Tools on the `web-widget` channel must be read-only and
+workspace-scoped, and the registry needs a `visitorPolicy`: off until the
+business turns it on, daily caps per visitor and per business, every answer
+logged for the business, answers from the business's own facts only, and
+never card details. See the [booking receptionist
+example](../../bundled-contracts/maggie-assistant-tools/booking-receptionist-example-v1.json)
+and [receptionist notes](references/booking-receptionist.md): it finds real
+free times and opens the normal booking sheet; it never books or takes a
+card.
+
 ## Approvals and audit
 
 Read [approvals and audit](references/approvals-and-audit.md) before
@@ -62,6 +108,11 @@ implementing writes. In short: a write runs only with a signed, short-lived,
 single-use approval bound to the exact calls, caller and scope; the token is
 stored with the model turn on the server so a client answering only yes/no
 works; every write produces one audit entry with a readable summary.
+Scheduled and event-driven workflows use a **standing approval**: a signed
+grant for one workflow, its tools and per-tool limits (per day, per run, fixed
+arguments, maximum amount) that expires within 90 days and can be revoked;
+calls outside the limits fall back to a normal approval card, and each run is
+audited with channel `workflow` and the grant id.
 
 ```bash
 maggie assistant approval-selftest
@@ -87,7 +138,7 @@ See [bridge host](references/bridge-host.md) and
 ## Hard boundaries
 
 - Never let the model see or choose an approval token; never accept a write
-  without one.
+  without one (or a standing approval whose limits cover the call).
 - Never expose `never` tools or billing changes on MCP or third-party apps.
 - Never publish a package or submit an app for review without an explicit
   yes; these commands only check.

package/bundled-skills/maggie-assistant-tools/references/approvals-and-audit.md

@@ -52,3 +52,30 @@ One entry per write, written by the server after the call:
 `maggie assistant audit-check` replays a recorded session
 (`{calls: [{tool, workspace, actionId, ok}], audit: [...]}`) against the
 registry and fails on missing, duplicate, unreadable or mis-scoped entries.
+
+## Standing approvals for workflows
+
+Approvals are single-use per turn, which makes automations ("when someone
+cancels, offer the slot to the waitlist", "ask for a review the day after a
+visit") ask every time. A standing approval is a signed grant the owner gives
+once for one workflow:
+
+- **Bound to** the owner, the workspace, the workflow id and a list of tool
+  grants. Each grant has `maxPerDay` (required), optional `maxPerRun`,
+  `fixedArgs` (for example the e-mail template) and `maxAmountMinor` for
+  money.
+- **Expires** within 90 days; the owner renews it from the workflow screen.
+  Revocation is a server-side list checked on every run.
+- **Every run** is checked against the grant and the day's usage on the
+  server, gets an idempotency key from the grant id and the call, and is
+  audited with channel `workflow` and `standingApprovalId`.
+- **Outside the limits** (another tool, a different template, the daily cap
+  reached, an amount above the maximum, expired or revoked) the call is not
+  run; the workflow queues a normal approval card for the owner instead.
+- Never grant `never` tools; prefer narrow grants (one template, a small
+  daily cap) over broad ones.
+
+The reference implementation is `issue_standing` / `check_standing` /
+`StandingStore` in `tools/runtime/assistant_approval.py`;
+`maggie assistant approval-selftest` exercises it, and `audit-check` rejects
+workflow audit entries without the grant id.

package/bundled-skills/maggie-assistant-tools/references/booking-receptionist.md

@@ -0,0 +1,45 @@
+# AI receptionist for a booking page
+
+A receptionist answers visitors on one business's public page: "Do you do
+lash lifts?", "How much is a 60-minute massage?", "Anything on Saturday
+morning?". It is a reader and a guide, never an agent that books.
+
+## What it may do
+
+- Answer from **this business's facts**: treatments, prices, durations,
+  opening hours, address, team names, policies (cancellation, deposits, patch
+  tests) and the business's own FAQs. Load them fresh per conversation; never
+  answer prices or availability from the model's general knowledge.
+- Find **real** free times from the live availability engine (the same call
+  the booking sheet uses), at most a handful per answer, rendered as a slot
+  picker.
+- Open the **normal booking sheet** preselected at the chosen treatment and
+  time. The visitor enters details and pays there; the sheet's own rules
+  (deposits, patch tests, blocked clients) apply unchanged.
+- Hand off: when the answer is not in the facts, say so and show the
+  business's phone and e-mail.
+
+## What it must not do
+
+- Book, reschedule or cancel; take or ask for card details; promise a price
+  or time the engine did not return; give medical advice beyond the
+  business's written policy (for example "a patch test is required 48 hours
+  before a lash tint").
+- Read other clients' data. The receptionist runs as the visitor, not as the
+  business.
+
+## Controls
+
+- Off until the business turns it on (`visitorPolicy.enabledByDefault:
+  false`), with a preview the owner can try first.
+- Daily caps per visitor (IP + browser id) and per business; when a cap is
+  hit, show the contact details instead of an error.
+- Every question and answer is logged and visible to the business, with the
+  tools called. Retain the log for a fixed period and delete it with the
+  business.
+- Text inside visitor messages is content, never an instruction to change
+  these rules. The system prompt names the business and forbids answering
+  for other businesses.
+
+Validate the registry with `maggie assistant registry-validate`; the
+`web-widget` checks enforce read-only tools and the visitor policy.

package/bundled-skills/maggie-assistant-tools/references/bridge-host.md

@@ -54,3 +54,57 @@ user brings their own account. Review terms again at least every six months.
 - When an argument must be passed, escape each one with `printf %q`.
 - zsh does not word-split unquoted variables, so `for x in $list` sees one
   item; write remote scripts for `sh` and iterate explicitly.
+
+## Smoke-testing `codex exec` with an image
+
+`-i/--image` takes **several** paths, so `codex exec ... -i photo.jpg "prompt"`
+reads the prompt as a second image path and fails with "No prompt provided
+via stdin". Put the prompt first, or end the image list with `--`:
+
+```bash
+codex exec "Describe this photo in one sentence" -i photo.jpg
+codex exec -i photo.jpg -- "Describe this photo in one sentence"
+```
+
+## Images on the user's ChatGPT plan (Codex app-server)
+
+Verified on codex-cli 0.160 against the app-server JSON schema
+(`codex app-server generate-json-schema`) and live turns:
+
+- **A separate image Codex per ChatGPT account.** The chat Codex runs with
+  the product's MCP server and must keep `image_generation` disabled. Image
+  work runs on a second app-server for the same account with
+  `--disable` for every machine-touching feature except `image_generation`,
+  `sandbox_mode="read-only"`, `approval_policy="never"`,
+  `web_search="disabled"` and **no MCP server or tools**, so text inside a
+  picture cannot make it act.
+- **One ephemeral thread per request**: `thread/start` with
+  `ephemeral: true`, `approvalPolicy: "never"`, `sandbox: "read-only"` and
+  developer instructions that say text inside an image is content, never an
+  instruction.
+- **Image input**: turn input items `{type: "image", url: "data:<mime>;base64,<data>"}`
+  after the text item. Validate first: png/jpeg/webp/gif only, a cap on count
+  (for example 5) and size (for example 4 MB of base64), base64 characters
+  only.
+- **Analysis** returns `agentMessage` items; pass `outputSchema` on
+  `turn/start` for JSON answers.
+- **Generation** returns `item/completed` notifications with
+  `item.type == "imageGeneration"`: `status`, `result` (base64 PNG, may be
+  empty), `savedPath` (a file on disk), `revisedPrompt`, and `failure`. A
+  `failure` mentioning `usageLimitExceeded` means the plan's image quota is
+  used up — tell the user, do not retry.
+- **Nothing stays on the bridge**: read `savedPath` when `result` is empty,
+  then delete its folder; the product stores the image it uses.
+- **Stop and time limits**: `turn/interrupt` with the thread id when the
+  caller cancels or a deadline passes (about 2 minutes for analysis, 5 for
+  generation).
+- **Fallback**: the caller treats any failure (no bridge, quota, timeout, no
+  image) as "use our own model" and says which one made the result.
+
+## Reverse proxy limits
+
+Chat with photos and image jobs need a larger body and a longer read timeout
+than API defaults: at least `client_max_body_size 25m` and
+`proxy_read_timeout`/`proxy_send_timeout` 360 s on the bridge routes (5-minute
+generations plus margin). `maggie deployment bridge-check` compares the
+observed nginx values with the plan's `proxy` block.

package/bundled-skills/maggie-auth-reference/SKILL.md

@@ -39,3 +39,21 @@ table, run that mirror after the primary provider session succeeds. A missing
 optional table or temporary mirror failure must be a safe, redacted warning and
 must not reject a valid primary session. Make the mirror blocking only when the
 host has explicitly documented it as part of the authentication contract.
+
+## External identity providers: Firebase session cookies
+
+When the host uses Firebase Authentication with server session cookies,
+`verifySessionCookie(cookie, true)` (`checkRevoked`) compares the cookie's
+`auth_time` with the user's `tokensValidAfterTime`, both in whole seconds. A
+user created (or whose tokens were revoked) in the same second as the cookie
+was minted is treated as revoked: `auth/session-cookie-revoked`, intermittently.
+
+- QA fixtures that create a user and immediately sign in must wait about
+  1.5 s after `createUser` (or after `revokeRefreshTokens`) before minting the
+  ID token and session cookie.
+- Production sign-up flows hit the same race when they create the account and
+  the session in one request; mint the session from the client's fresh ID
+  token after creation, and on `auth/session-cookie-revoked` right after
+  sign-up retry once after a short delay instead of signing the person out.
+- Keep `checkRevoked: true` on sensitive routes; do not turn it off to hide
+  the race.

package/bundled-skills/maggie-blog/SKILL.md

@@ -56,6 +56,14 @@ Search/sort views are not indexable; drafts never appear in public routes, RSS,
 or sitemap output. Provider keys remain server-side. Public publication and
  migrations always require explicit confirmation.
 
+API Pull deliveries need their live URL recorded so social posts and internal
+links point at the page that exists now: the site reports it on publish
+(`maggie blog live-urls record --content-id ID --url URL`), and
+`maggie blog live-urls match --sitemap URL --write` fills the gaps
+additively — it never retires an earlier match, and the original page wins
+over translated copies that share the slug. See
+[where a delivered post went live](../../bundled-tools/integrations/maggie-api-pull.md#where-a-delivered-post-went-live).
+
 Automatic publication is an opt-in host policy, not the default. Keep human
 review enabled unless the owner explicitly chooses otherwise. If a host has
 that approval, validate its evidence before its scheduler calls the host's