Update to SignatureAPI

{
  "description": "Use when someone wants to add e-signatures or SignatureAPI to an app and the signing flow is not decided yet. Decides who signs, how they prove it is them, and what happens after. Also for a signing product or \"a platform like DocuSign\", even when the user knows no SignatureAPI terms. Writes a design brief or document, no code. Needs no API key.",
  "included_files": [
    {
      "relative_path": "references/coverage-checklist.md",
      "size_in_bytes": 3576
    },
    {
      "relative_path": "references/plain-language-questions.md",
      "size_in_bytes": 5631
    },
    {
      "relative_path": "references/product-shapes.md",
      "size_in_bytes": 15872
    }
  ],
  "name": "signatureapi-architecture",
  "skill_md_contents": "---\nname: signatureapi-architecture\ndescription: \"Use when someone wants to add e-signatures or SignatureAPI to an app and the signing flow is not decided yet. Decides who signs, how they prove it is them, and what happens after. Also for a signing product or \\\"a platform like DocuSign\\\", even when the user knows no SignatureAPI terms. Writes a design brief or document, no code. Needs no API key.\"\n---\n\n# Design a SignatureAPI integration\n\n## Purpose\n\nUnderstand what the user wants their people to experience. Then decide how\nSignatureAPI delivers it. Write a design brief or a design document, sized\nto the product, and get an explicit yes. This skill writes no application\ncode. The `signatureapi-integrate` skill builds from what the user approved.\n\n## When to reach for something else\n\n- **Building against an approved design** belongs to `signatureapi-integrate`.\n  It builds from the approved brief or document.\n- **Diagnosing an integration that already exists** belongs to\n  `signatureapi-diagnose`.\n- **Whether SignatureAPI supports something** is answered by\n  `signatureapi-docs`. Use it before you tell the user a capability exists\n  or does not.\n- **A different e-signature vendor** (DocuSign, Dropbox Sign, Adobe Sign, etc.)\n  needs that vendor's own docs. Map the user's needs onto SignatureAPI's\n  objects, not onto that vendor's.\n\n## Keep the user's vocabulary\n\nKeep the user's words for their product: a \"contract\", a \"client\", an\n\"onboarding step\". Their code keeps its names too. Use SignatureAPI terms\nonly at the API boundary, and record the mapping in the design.\n\nAsk every question in plain words; `references/plain-language-questions.md`\nhas the plain form of each decision. Tell the user two facts early: test\nmode sends no real email, and a signer who is not logged in to the app is\nreached by email.\n\n## Understand the experience first\n\nBefore reading code and before naming any API object, establish four things\nwith the user:\n\n- **The journey.** Who starts it, what they see, what the signer sees, and\n  what happens after everyone has signed. Ask for the story in their words.\n- **The actors.** Who sends, who signs, who approves, who only watches. Which\n  of them are the app's own users and which are outsiders.\n- **The success condition.** What must be true for the user to call this\n  done. A signed PDF in a folder, a status on a record, an email, a\n  dashboard entry.\n- **The constraints.** Deadline, legal context, existing vendor, volume,\n  budget, must-not-change parts of the app.\n\nWhen the request already says most of this, restate it in one short\nparagraph and ask only for what is missing. Ask in the user's words. Do not\nask about authentication methods, place types or routing yet.\n\nThen ask one more question: **quick or thorough?** Offer the choice in one\nline. \"I can propose one recommended design and you confirm or correct it.\nOr we explore alternatives together first.\" The answer sets the pace of the\nrest of the conversation. Quick means: one recommended design, decisions\nstated with their evidence, a short confirmation round. Thorough means:\npresent the alternatives, resolve the decisions in a few grouped rounds.\n\n## Explore the codebase\n\nNow read the code. Each signal below informs one decision and implies one\ndefault. Record what you find; you will cite it as evidence.\n\n- **Document origin.** Grep for PDF generation libraries, upload handlers,\n  object storage clients, DOCX or templating code. Informs the document input\n  path. Default: the app stores the file in its own storage and passes a\n  signed or public URL. `POST /uploads` only when the app has no storage.\n- **User authentication and a web frontend.** Grep for session or login\n  code, and for a browser UI. Informs recipient authentication and whether\n  the ceremony is emailed or embedded. Default: emailed link (`email_link`)\n  for people outside the app. Embedded (`custom` plus `embeddable_in`) only\n  for signers who are logged in to the app. Either can carry an extra\n  challenge as a later array entry without changing who delivers the URL.\n- **A native mobile app.** Look for an Xcode project, an Android Gradle\n  module, or a React Native app. Informs whether signers sign inside the\n  app. Default: a top-level WebView with `custom` authentication, created\n  by the app's server (Shape 4 in `references/product-shapes.md`).\n- **Tenancy.** Grep for organization, account, or tenant tables. Informs\n  `sender` and `topics`. Default: one sender (the account's default) and no\n  topics.\n- **Webhook routes, queues, domain events.** Grep for existing inbound\n  webhook handlers, job queues, event dispatch. Informs how events are\n  handled and where envelope creation runs. Default: reuse the existing\n  webhook route pattern and the existing background-job path.\n- **Where third-party ids are persisted.** Grep for columns or tables that\n  hold Stripe, Twilio, or similar ids. Informs where the envelope id goes.\n  Default: a column on the domain row that motivated the signature.\n- **PDF viewer or canvas components.** Grep for PDF rendering in the\n  frontend. Informs whether a place-drawing UI is feasible. Default: no\n  drawing UI. Use placeholders or `fixed_positions` set in code.\n- **Design records.** Look for an ADR directory (`docs/adr`, `adr/`), a\n  design-docs folder, or a decisions log. When one exists, the design\n  document goes there, in that convention, with a pointer at the default\n  path. An ADR directory counts even though this document is longer than\n  one ADR.\n\nThe four placement questions in\n`../signatureapi-integrate/references/brownfield-placement.md` cover the\ncall site, the inbound-HTTP path, and the persistence home. Answer them here.\nDo not repeat them in the design document; link to the answers.\n\n## Present the possibilities\n\nMatch the journey to the closest starting points in\n`references/product-shapes.md`. Four common shapes are described there:\nsend-for-signature inside an existing app, an embedded signing step, a\nself-serve platform, and signing inside a native mobile app. They are starting points, not a menu. Many products\ncombine two, or fit none. Say which shape is closest, what differs, and\nwhat that difference costs. In thorough mode, present two or three\nalternatives with their trade-offs. In quick mode, present one and say why.\n\n## Decide progressively\n\n- **Strong signal** in the code or the request: decide, and state the\n  evidence.\n- **Weak signal:** propose the default and ask for a yes.\n- **No signal:** ask.\n\nAlways ask, even when you could infer it, when a decision changes what\npeople experience, the security of the signing, its legal standing, its\ncost, or who owns the data. Decide everything else yourself and state it.\n\nAsk in rounds, grouped by dependency: the document and its fields; the\nsigners and how they authenticate; what happens on completion; tenancy and\nrollout. At most four questions per message, one decision each, with your\nproposed answer beside it. Stop when the remaining decisions have a strong\nsignal or a confirmed default.\n\n### Worked example: the first round\n\n> You described this: a customer accepts a quote in your app, then your\n> account manager and the customer both sign the order form, and the signed\n> PDF goes onto the order. I found a PDF generator and an S3 client, so I\n> propose your app generates the order form and uploads it. Two questions\n> on the document before we get to the signers:\n>\n> 1. Does your app generate the order form, or do account managers upload\n>    their own files? I propose generated.\n> 2. Where should the signature boxes go: marked inside the generated\n>    order form where they belong (my proposal), or at fixed spots you set\n>    once?\n\n## Decision matrix\n\nThe API-facing decisions, one row each. This table is for you; the user\nsees the plain form in `references/plain-language-questions.md`. Every\nidentifier below is in the published spec. Check any you are unsure of before you write it into the\ndesign:\n\n    node ../signatureapi-integrate/scripts/openapi-explore.mjs schema Envelope.EnvelopeInput\n    node ../signatureapi-integrate/scripts/openapi-explore.mjs schema Ceremony.CeremonyInput\n    node ../signatureapi-integrate/scripts/openapi-explore.mjs schema Recipient.Type\n    node ../signatureapi-integrate/scripts/openapi-explore.mjs schema Place.Type\n\n| Decision | Options | Signals that pick one | Consequences | Default |\n| --- | --- | --- | --- | --- |\n| Document input path | A signed or public URL to a file in the app's own storage on a supported host (`../signatureapi-integrate/references/documents.md`); `POST /uploads` with the file bytes; a DOCX template merged with `data` | Object storage present → store there and pass a signed URL. No storage → `POST /uploads`. DOCX templates present → `format: docx` with `data`. A field-drawing UI → `POST /uploads`, because the structure read needs an upload id | The app keeps its own copy and record of the file. Upload URLs are temporary. DOCX `data` shapes the template fields the app must fill | A signed URL to the app's own storage |\n| How places are defined | `[[place_key]]` placeholders in the file; `fixed_positions` in code; DOCX template fields plus places; a UI where users draw fields | App controls the document source → placeholders. Third-party PDF → `fixed_positions`. PDF viewer component present → drawing UI is feasible | A drawing UI needs page rendering, coordinate conversion, and reading the upload's structure (`inspect_upload`). It is the largest part of a platform | Placeholders when the app owns the file; `fixed_positions` otherwise |\n| Recipient types and `routing` | The values in the current `Recipient.Type` schema; `routing` `sequential` or `parallel` | Approval step in the domain flow → `approver`. Fields filled before signing → `preparer`. Countersignature by the app owner → `automatic_signer`. A qualified-signature requirement → inspect `qualified_signer` and its account prerequisites | `sequential` notifies one recipient at a time. `parallel` notifies all at once | One `signer`; `sequential` |\n| Authentication per recipient | An ordered array of `email_link`, `email_code`, `custom`, `identity_verification`. The first entry is the main method; later entries are extra challenges | Signer is logged in to the app → `custom`. Signer is outside the app → `email_link`. Regulated or high-value document → add a challenge to that main method, e.g. `[email_link, email_code]` for a signer outside the app, `[custom, email_code]` for one inside it | The **first** entry decides who delivers the ceremony URL: `email_link` first returns no URL and SignatureAPI emails the link and any code, so the app sends no email; `email_code` or `custom` first returns the URL for the app to deliver. `custom` is an assertion written to the audit log. `email_link` and `custom` are only valid first and cannot be combined; `email_code` appears at most once; `identity_verification` is never first and is enabled per account | `[email_link]` |\n| Ceremony delivery and return | Emailed link; embedded with `embeddable_in`; embedded in a native app's WebView; `redirect_url` after the ceremony | Web frontend and logged-in signer → embedded. iOS or Android app and logged-in signer → native WebView, no `embeddable_in` for a top-level WebView. No frontend → emailed | Embedded ceremonies ignore `redirect_url`; the app learns the outcome from events. A native app catches them in its WebView navigation handler, and its server confirms the outcome. `redirect_url` receives the outcome, the envelope id and the recipient id as query parameters; the names are in the spec's `Ceremony.RedirectUrl` description | Emailed link, no redirect |\n| On completion | Fetch deliverables and store them; notify the domain; do nothing beyond marking status | Object storage present → store the signed PDF there. Document model present → attach to it | `standard` deliverable includes the audit log; `simple` does not. `delivery_type: none` stops SignatureAPI emailing the deliverable to the recipient | Mark status on `envelope.completed`. On `deliverable.generated`, fetch `GET /envelopes/{envelopeId}/deliverables`, store the file at once (download URLs expire), mark the domain row |\n| Rollout | Test mode only; test then live; who holds the live key | Env file with a `key_test_` key present → test first. Secrets manager present → live key goes there | Test envelopes send no email and are not binding. Live mode needs an active subscription on the account. A live key must never enter this skill's scripts | Test mode first. The user names who holds the live key and confirms live mode is active |\n| Senders and multi-tenant | Account default sender; per-customer `sender` after `POST /senders` verification; `topics` per tenant | Tenant table present and customers send in their own name → per-customer sender. Tenant table present and one brand → default sender plus `topics` | A sender needs email verification before use. `topics` filter webhooks and envelope listings | Account default sender |\n| Branding logo | No logo; a permanent PNG upload in the same account | A tenant or product logo exists → upload that PNG with `POST /uploads`, then make it permanent with `POST /uploads/{uploadId}/store` and a unique `key`. Or the user uploads it in the Dashboard Library | `branding.logo` accepts only the `url` of a permanent PNG upload in the same account. A website, CDN or signed storage URL is rejected. A temporary upload is rejected. Store the upload once and reuse its `url`; per-tenant logos need one stored upload each | No logo |\n| Attestation | `none`, `mx_nom151`, `br_icp_brasil` | Mexican or Brazilian legal context in the domain → the matching value | Both paid options must be enabled at the account level | `none` |\n| Envelope email content | Product wording in `title` and `message`; account anti-phishing content capability when the wording contains URL-, phone-, or numeric-date-like text | Required product copy contains any restricted pattern → record account enablement as a prerequisite | A stricter account policy can reject content that is valid under the JSON schema. Do not silently rewrite required copy | Plain text without restricted patterns for generic fixtures |\n\n## Make scope explicit\n\nFor a design document, add a capability coverage table. Read the current\n`Recipient.Type` and `Place.Type` schemas and give each value one line:\nincluded now, or deferred with a reason. The first version's scope is not\nthe limit of SignatureAPI. Re-read the schemas when revising an old design.\n\n## Cover the whole product, not only the API\n\nFor a design document, walk `references/coverage-checklist.md` once:\nownership, drafts and templates, tenant isolation, retention, repair paths,\nvolume, accessibility, non-goals. Take what this product needs. It is a\nchecklist for you, not a questionnaire; most items resolve from the journey\nand the code.\n\n## Brief or document\n\nMatch the output to the size of the product.\n\n- **One signing flow** (a document, its signers, what happens after) → a\n  design brief in chat. Write no file. Start with the journey in one\n  sentence. Then give one plain line for each of these:\n  - where the document comes from\n  - who signs, in what order\n  - how a signer proves it is them\n  - where they sign\n  - what happens when everyone has signed\n  - trying it in test mode first\n\n  Take the wording from `references/plain-language-questions.md`.\n  Ask for an explicit yes. Then hand over to `signatureapi-integrate`.\n- **A platform-shaped product** (users send their own documents, draw\n  their own fields, or send in their own name; many tenants; \"a platform\n  like X\") → the design document below.\n- **The user asks for a document**, or the repository keeps design\n  records for features like this → the design document below.\n\n## Write the design document\n\nWrite it once the journey is confirmed, the shape is chosen, and every\ndecision that changes the data model, authentication or who receives email\nhas a yes.\n\nPut it where the repository keeps design records (an ADR directory, a\ndesign-docs folder), in that convention, with a one-line pointer at\n`docs/signatureapi-integration.md`. Otherwise write it at that path.\n\nKeep the template's headings. Delete a section only with a reason in Open\nitems. **For you** lines are the user's words, and the user approves them.\n**Technical decision** lines are yours.\n\n```markdown\n# <the user's name for this feature> — SignatureAPI integration design\n\nDate: YYYY-MM-DD\nStatus: draft | approved\nStarting point: <closest shape from references/product-shapes.md, or \"custom\">\nDepartures from it: <one line each, or \"none\">\n\n## The experience\n\n- Journey:\n- Actors:\n- Success condition:\n- Constraints:\n- Non-goals:\n\n## Vocabulary\n\n| The user's term | Means, at the API boundary |\n| --- | --- |\n| <their term> | <envelope / recipient / place / ceremony / deliverable, and how> |\n\n## Decisions\n\n### Where the document comes from\n- For you: <plain sentence, e.g. \"Ledgerly makes the letter itself\">\n- Technical decision:\n- Evidence or answer:\n- Consequence:\n\n### Where the signature and other fields go\n- For you: <plain sentence>\n- Technical decision:\n- Evidence or answer:\n- Consequence:\n\n### Who takes part, and in what order\n- For you: <plain sentence>\n- Technical decision:\n- Evidence or answer:\n- Consequence:\n\n### How a signer proves it is them\n- For you: <plain sentence, one per kind of signer>\n- Technical decision:\n- Evidence or answer:\n- Consequence:\n\n### Where they sign, and where they land afterwards\n- For you: <plain sentence>\n- Technical decision:\n- Evidence or answer:\n- Consequence:\n\n### What happens when everyone has signed\n- For you: <plain sentence: where the signed file goes, who gets a copy by email>\n- Technical decision:\n- Evidence or answer:\n- Consequence:\n\n### Trying it safely, then going live\n- For you: <plain sentence: test mode sends no real email; who holds the live key>\n- Technical decision:\n- Evidence or answer:\n- Consequence:\n\n### Whose name is on the email\n- For you: <plain sentence>\n- Technical decision:\n- Evidence or answer:\n- Consequence:\n\n### Legal timestamp for Mexico or Brazil\n- For you: <plain sentence, or \"not needed\">\n- Technical decision:\n- Evidence or answer:\n- Consequence:\n\n## Product coverage\n\n<one short entry per applicable area from references/coverage-checklist.md:\nownership and permissions; drafts and templates; tenant isolation; sensitive\ndata and retention; idempotency, reconciliation and repair; volume and\nobservability; accessibility, mobile, localization, branding>\n\n## SignatureAPI capability coverage\n\n| Area | Provider capability | Included now? | If deferred, why |\n| --- | --- | --- | --- |\n| Recipient type | <one current `Recipient.Type` value> | yes / no | <reason or n/a> |\n| Place type | <one current `Place.Type` value, or a group with one disposition> | yes / no | <reason or n/a> |\n\n## Account prerequisites\n\n- <account capability needed by an approved decision, including restricted\n  `title` or `message` content; or \"none\">\n\n## Endpoint sequence the application calls\n\n1. <method and path, and where in the codebase it is called from>\n\n## Events the application handles\n\n- <event type> — <what the handler does>\n\n## What the application persists\n\n- <field or table> — <what it holds>\n\n## Open items\n\n- <anything still unanswered>\n```\n\nPresent the document to the user. Ask for an explicit yes on The\nexperience section and the For you lines; read them out, not the technical\nlines. Set `Status: approved` only after the user says yes. The file is the contract\n`signatureapi-integrate` reads. Do not start building.\n\n## Red flags\n\n| Thought | Reality |\n| --- | --- |\n| \"I'll read the code first, then ask.\" | The code says where signing fits, not what people should experience. Ask that first. |\n| \"This is obvious, I'll skip the design.\" | Document source, field placement and completion handling are where a wrong guess costs days. A brief takes one message. |\n| \"Every flow needs the full document.\" | One signing flow needs a brief. The document is for platform-shaped products, or on request. |\n| \"They said 'like X', so I'll copy X's data model.\" | X's templates, drafts and tabs are not SignatureAPI's objects. Map the user's needs onto this API. |\n| \"I'll pick sensible defaults and note them.\" | `custom` authentication, a placeholder scheme and where the PDF is stored are product decisions. Propose them and get a yes. |\n\n## References\n\n- `references/product-shapes.md` — four common starting points: what the app calls, what you prove it with\n- `references/plain-language-questions.md` — each decision as a plain question, with the technical meaning of each answer\n- `references/coverage-checklist.md` — the product-design areas beyond API configuration\n- `../signatureapi-integrate/references/brownfield-placement.md` — where signing belongs in an existing codebase\n- `../signatureapi-integrate/references/verification-loop.md` — why `custom` authentication is only for signers the app verified\n\n## Vocabulary\n\nAn **envelope** holds **documents** and **recipients**. **Places** are\nregions on a document bound to a recipient. Each recipient signs through a\n**ceremony**. Completion produces a **deliverable**. The **design\ndocument** is `docs/signatureapi-integration.md`.\n"
}