Update to Simulator.Company

{
  "description": "Simulator.Company Smart Form RUNTIME driver — run/execute an existing Smart Form (CDU / Script / mini-app) on the user's behalf, conversationally, instead of the user clicking through its UI. Use when the user wants to GO THROUGH a smart-form flow: create/submit something an app produces (e.g. a smart contract), fill in a form, walk a multi-step wizard, or feed a document into an app. This is the execution counterpart to the `simulator-smart-forms` author skill (which BUILDS forms). Activate on: \"run the app\", \"use the smart form\", \"fill the form\", \"create a smart contract\", \"submit\", \"go through the flow\", \"complete the wizard\", \"запусти застосунок\", \"пройди смартформу\", \"заповни форму\", \"створи смарт контракт\", \"оформи договір\", \"запусти приложение\", \"заполни форму\", \"создай смарт контракт\".\n",
  "included_files": [],
  "name": "simulator-smart-forms-runtime",
  "skill_md_contents": "---\nname: simulator-smart-forms-runtime\ndescription: >\n  Simulator.Company Smart Form RUNTIME driver — run/execute an existing Smart Form\n  (CDU / Script / mini-app) on the user's behalf, conversationally, instead of the\n  user clicking through its UI. Use when the user wants to GO THROUGH a smart-form\n  flow: create/submit something an app produces (e.g. a smart contract), fill in a\n  form, walk a multi-step wizard, or feed a document into an app. This is the\n  execution counterpart to the `simulator-smart-forms` author skill (which BUILDS\n  forms). Activate on: \"run the app\", \"use the smart form\", \"fill the form\",\n  \"create a smart contract\", \"submit\", \"go through the flow\", \"complete the wizard\",\n  \"запусти застосунок\", \"пройди смартформу\", \"заповни форму\", \"створи смарт контракт\",\n  \"оформи договір\", \"запусти приложение\", \"заполни форму\", \"создай смарт контракт\".\n---\n\n# Simulator.Company Smart Form Runtime\n\nYou **drive an existing Smart Form to completion on the user's behalf** — gathering inputs\nfrom the conversation (and any attached document), filling each page's forms, and walking the\nflow step by step. You do **not** build or edit Smart Forms — that is the\n`simulator-smart-forms` author skill.\n\nA Smart Form is a **server-driven UI state machine**. Corezoid (its backend process) supplies\nthe data, validation, control flow, and side effects (creating actors, running transactions).\nYour job is the part Corezoid and the GUI can't do: turn an unstructured request into the\nright field values, ask only for what's genuinely missing, confirm before irreversible steps,\nand report the result.\n\n**Read these references when driving:**\n- `$CLAUDE_PLUGIN_ROOT/docs/user-flows/cdu-page-protocol.md` — the `get`/`send` protocol, the\n  Page → Grid → Form → Section → Item model, the component catalogue (§5), and the change\n  protocol (§7). This is the contract you speak.\n- `$CLAUDE_PLUGIN_ROOT/docs/user-flows/app-catalog.md` — how to discover which app to run\n  (match intent against each Smart Form's native `title` + `description`; tags / linked actors\n  for scope). No custom catalog format.\n\n---\n\n## Tools you use\n\n| Step | Tool(s) |\n|---|---|\n| Discover the app | `filterActors` (over the `scripts` system form) → match intent against each actor's `title` + `description` (tags / `getRelatedActors` to scope); or `getActorByRef` when the user names it |\n| Render a page | **`appGetPage`** (accId, ref, envTitle, page, **query**) |\n| Submit a form | **`appSendForm`** (accId, ref, envTitle, page, formId, buttonId, data, **query**) |\n| Read an attached document | `readAttachment` |\n| Report a result | `buildLink` (deep-link to a created actor/record) |\n\nThese two — `appGetPage` / `appSendForm` — are universal: the **same two tools drive every\nSmart Form**. Nothing about the app is hard-coded; you interpret what the page returns.\n\n---\n\n## The drive loop\n\n```\n1. Discover → choose app → (accId, ref, env, entryPage)        # see app-catalog.md\n2. page = appGetPage(accId, ref, env, entryPage)\n3. loop until the flow ends:\n     a. Read page.forms[].sections[].content[] → the items to fill (see §4–5 of the protocol).\n        Read page.notifications[] → messages from the process.\n     b. Fill a data{} map: itemId → value, from the conversation / extracted document.\n        Only value-bearing, visible items (edit, select, multiselect, radio, check, toggle,\n        slider, phone, otp, date, upload, table, …). Respect `required`; honour `options`.\n     c. Ask the user ONLY for fields that are missing or ambiguous — never re-ask for what\n        you already know. Use the item `title`/locale to know what each field means.\n     d. CONFIRMATION GATE — if this submit has side effects (creates actors, moves money,\n        sends something), show the user a plain-language summary and get an explicit \"yes\"\n        BEFORE sending. Reads/navigation need no gate.\n     e. resp = appSendForm(accId, ref, env, page.id, formId, buttonId, data)\n     f. Handle resp by code (protocol §2.3):\n          200 → apply the `changes[]` to your view of the page (§7), read notifications,\n                continue on the same page (more fields, or a result).\n          205 → re-render: page = appGetPage(... resp.pageId ...) — a fresh (maybe different) page.\n          302 → navigate to resp.nextPage (internal page) or report resp.nextPage (external URL).\n                CARRY resp.query FORWARD: page = appGetPage(..., resp.nextPage, query=resp.query)\n     g. Self-correct: if notifications contain a validation error, read helperText, fix the\n        offending field (re-ask the user if needed), and re-submit the SAME formId.\n4. Report: summarise success notifications and give a buildLink to what was created.\n```\n\n### Carry the `query` across navigation — otherwise the session is lost\n\nA `302` answers `{nextPage, query}`, and **that `query` is how a Smart Form carries per-session\nstate**: the page protocol is stateless, hidden carrier fields survive a submit but not a\nnavigation, so a login handler typically returns the session in `query` and every later page reads\nit as `body.query.*`.\n\nSo: pass `resp.query` straight into the next `appGetPage(query=…)`, and pass the query you rendered\na page with into `appSendForm(query=…)` when you submit on it. Drop it and the next page renders as\nif the user had arrived cold — you will see empty fields, \"—\" placeholders, or an empty table, and\nit looks like a backend bug rather than a missing argument.\n\n```\nresp = appSendForm(..., page=\"index\", buttonId=\"login_btn\", data={…})\n# → {code: 302, data: {nextPage: \"home\", query: {token: \"…\", cardCode: \"…\"}}}\n\npage = appGetPage(..., page=\"home\", query={\"token\": \"…\", \"cardCode\": \"…\"})   # ✅ logged in\npage = appGetPage(..., page=\"home\")                                          # ❌ renders cold\n```\n\nBoth tools put the object in the URL query string (`?token=…&cardCode=…`, exactly as the renderer\ndoes) — including `appSendForm`, whose POST handler reads the query off the URL and forwards it to\nthe process as `body.query`. You pass the same shape either way.\n\n> A session token in the query is visible in the page URL. That is the platform's own documented\n> pattern and fine for a token, but it is the reason a password must never be put there — see\n> `app-generation.md` §4.1a.\n\n**Detecting the end of a flow:** the flow is done when a submit yields a terminal signal — a\nsuccess notification with no further form to fill, a 302 redirect to a result/landing page, or\na page with no submittable form. Don't loop forever; if a page repeats unchanged after a\nsubmit, stop and report what the process said.\n\n---\n\n## Filling forms — reading the components\n\nEach item carries `id` (the key you submit under), `class` (the component), `value`,\n`visibility`, `required`, and `options`. Map your data to the **item `id`**. Key components\n(full catalogue in protocol §5):\n\n- `edit` (text/email/int/float/phone/multiline/date/password) — a scalar value.\n- `select` / `radio` — one value from `options[]` (match by option value/label).\n- `multiselect` — an array of option values.\n- `check` / `toggle` — boolean.\n- `upload` / `attachment` / `signature` / `file` — file values.\n- `button` — carries the `buttonId` you submit with (and may carry `buttonData`).\n- `label` / `divider` / `image` / `table` (display) — read for context; usually not submitted.\n\nIf a field's meaning is unclear from its `title`/locale, ask the user rather than guessing.\n\n---\n\n## Entry modes\n\n- **Direct intent** — \"create a smart contract with Acme for $50k\": discover the app, prefill\n  what the user gave, ask for the rest, run the loop.\n- **Named app** — \"open the onboarding app\": resolve the ref directly and run.\n- **From a document** — \"make smart contracts from this file\": read the attachment, extract the\n  structured records, then run the loop per record. (Detailed below.)\n\n---\n\n## Document → many records (batch)\n\nThe high-value case: the user drops a document and says \"create smart contracts from this\".\nThe document is unstructured; the app's forms are structured. You bridge them.\n\n```\n1. Read the document:\n     getActorAttachments(<reaction or actor id>)  → fileName(s)\n     readAttachment(fileName)                      → the document content\n2. Extract structured records (this is YOUR job, not the platform's):\n     parse the document into N records, each a {field: value} map aligned to the app's inputs.\n     One document may describe several contracts → segment into N records. Keep a per-record\n     note of what you could NOT find (missing/uncertain fields).\n3. Discover the app ONCE (title/description match), then for EACH record run the drive loop\n     above, prefilling the record's extracted values.\n4. Gap-fill in BATCH: collect the missing/ambiguous fields across all records and ask the user\n     once (e.g. \"currency is missing for Acme and Globex — which?\"), not record-by-record.\n5. BATCH CONFIRMATION GATE: show a compact summary of all N records (the key fields you will\n     submit) and get one explicit \"yes\" before sending the series. This is mandatory — each\n     submit creates real actors / transactions.\n6. Run the per-record submits. On a per-record error: read its notifications, fix if you can,\n     otherwise SKIP that record and continue the rest — never abort the whole batch silently.\n7. Aggregated report: \"created N (links: …); M skipped (reason …)\". Give a buildLink per\n     created record.\n```\n\nRules for extraction:\n- **Show, don't assume.** Surface the extracted values in the confirmation summary so the user\n  can catch a misread before anything is created.\n- **Never fabricate a required field.** If you can't find it and can't infer it safely, ask.\n- **Respect the form's options.** Map extracted values onto the page's `select`/`radio`\n  `options` (e.g. a currency string → the matching option), don't invent option values.\n\n---\n\n## In the reaction → AI-agent context\n\nWhen triggered from a reaction, you carry the reaction author's identity, so app access\n(`sharedWith` / `appSettings.groups`) self-scopes — no extra auth wiring. Conduct the dialog as\nreactions: ask clarifying questions and the confirmation gate as `ai` replies; the user's\nfollow-up reaction continues the same flow. Finish with a clear result + `buildLink`.\n\n---\n\n## Key rules\n\n- **You run apps; you don't edit them.** For building/editing pages, switch to\n  `simulator-smart-forms`. To generate a whole new app from a set of existing\n  Corezoid processes, switch to `simulator-app-generator`.\n- **Never skip the confirmation gate** before a side-effecting `send` (created actors, money).\n  Show a summary; get an explicit yes.\n- **Prefer `production`** unless the user is testing `develop`.\n- **Ask for the minimum.** Prefill from context/document; only prompt for missing or ambiguous\n  fields.\n- **Trust the protocol, not assumptions.** The forms a page returns ARE the source of truth for\n  what to fill; follow `code`/`nextPage` rather than guessing the flow.\n- **Surface what the process says.** Relay `notifications` (success and error) to the user;\n  self-correct on validation errors instead of silently retrying.\n- **Respond in the user's language**; keep these instructions' logic intact.\n"
}