Update to YCloud Developer Kit

{
  "description": "Design, implement locally, or evaluate YCloud WhatsApp business phone-number inventory, registration, profile, display-name, Business Username, contact-book, Calling/capture settings, and commerce settings operations. Use for phone-number management; exclude WABA management, message sending, template lifecycle, WhatsApp Calling sessions, and real API mutations.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 293
    },
    {
      "relative_path": "references/openapi.md",
      "size_in_bytes": 55382
    },
    {
      "relative_path": "references/runtime.md",
      "size_in_bytes": 15187
    },
    {
      "relative_path": "references/shared/integration-boundaries.md",
      "size_in_bytes": 8401
    },
    {
      "relative_path": "references/shared/pagination-contract.md",
      "size_in_bytes": 3494
    }
  ],
  "name": "ycloud-whatsapp-phone-numbers",
  "skill_md_contents": "---\nname: ycloud-whatsapp-phone-numbers\ndescription: Design, implement locally, or evaluate YCloud WhatsApp business phone-number inventory, registration, profile, display-name, Business Username, contact-book, Calling/capture settings, and commerce settings operations. Use for phone-number management; exclude WABA management, message sending, template lifecycle, WhatsApp Calling sessions, and real API mutations.\n---\n\n# YCloud WhatsApp Phone Numbers\n\nDesign or implement contract-aware support for the fifteen phone-number\noperations in the generated reference. Never call YCloud or Meta, read\ncredentials or customer data, or mutate a real phone-number resource.\n\n## Execution boundary\n\nThese restrictions govern Skill execution: do not call a YCloud Provider API, access real credentials, or read real business data. The Skill may generate server-side adapter code for an application's runtime, but must not start it or make a live request. Reading public official documentation as contract evidence is allowed and is not a Provider API call or business-data access. A live smoke test is outside the default workflow and requires separate, explicit authorization naming the target/environment, allowed operations, credential boundary, and required result evidence.\n\nHonor Architect handoffs for `scope`, `deliverable`, `mutation`, capability IDs,\nproject seams, and expected evidence. Without one, default to focused,\nread-only guidance unless the user explicitly requests local implementation.\nLocal-write authorization permits request models/builders, adapters, handlers,\nservice bindings, mocks, synthetic fixtures, and no-network tests in the\nscoped project. Register, PATCH, settings save, and both DELETE operations are\nmock-only. Reuse the project's existing interface stack and preserve concurrent\nwork.\n\nLoad [the generated OpenAPI reference](references/openapi.md) and\n[the reviewed runtime reference](references/runtime.md) only after this skill is\nselected. If retry, idempotency, queueing, or error translation is requested,\nalso read `references/shared/integration-boundaries.md`. Exact paths, schemas,\nresponses, and descriptions come from `openapi.md`; cross-cutting pagination,\nerror, request-ID, rate-limit, and compatibility behavior comes from\n`runtime.md`. If either generated reference is missing, stale, or inconsistent\nwith its recorded source hash and operation count, report drift and stop rather\nthan reconstructing the contract from memory.\nFor phone-number list work, also read\n[`references/shared/pagination-contract.md`](references/shared/pagination-contract.md).\n\n## Exact operation scope\n\n| Intent | Method and path | operationId |\n| --- | --- | --- |\n| List phone numbers | `GET /whatsapp/phoneNumbers` | `whatsapp_phone_number-list` |\n| Retrieve phone number | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}` | `whatsapp_phone_number-retrieve` |\n| Retrieve Business Username | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername` | `whatsapp_phone_number-retrieve-business-username` |\n| Update Business Username | `PATCH /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername` | `whatsapp_phone_number-update-business-username` |\n| Delete active Business Username | `DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername` | `whatsapp_phone_number-delete-business-username` |\n| Retrieve username suggestions | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/businessUsername/suggestions` | `whatsapp_phone_number-retrieve-business-username-suggestions` |\n| Delete Meta contact-book entry | `DELETE /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/contactBook/{bsuid}` | `whatsapp_phone_number-delete-contact-book-entry` |\n| Update display name | `PATCH /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/displayName` | `whatsapp_phone_number-update-displayName` |\n| Retrieve profile | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/profile` | `whatsapp_phone_number-retrieve-profile` |\n| Update profile | `PATCH /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/profile` | `whatsapp_phone_number-update-profile` |\n| Register phone number | `POST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/register` | `whatsapp_phone_number-register` |\n| Retrieve Calling/capture settings | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings` | `whatsapp_phone_number-retrieve-settings` |\n| Save Calling/capture settings | `POST /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings` | `whatsapp_phone_number-save-settings` |\n| Retrieve commerce settings | `GET /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/whatsappCommerceSettings` | `whatsapp_phone_number-retrieve-commerce-settings` |\n| Update commerce settings | `PATCH /whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/whatsappCommerceSettings` | `whatsapp_phone_number-update-commerce-settings` |\n\nWABA discovery belongs to `ycloud-whatsapp-business-accounts`. Message\nsubmission/retrieval belongs to `ycloud-whatsapp-messages`; template lifecycle\nand analytics belongs to `ycloud-whatsapp-templates`; authentication-only work\nbelongs to `ycloud-api-authentication`; broad multi-domain planning belongs to\n`ycloud-integration-architect`. Readiness, repository maintenance, issue\ntracking, WhatsApp Calling sessions, and contact CRUD are out of scope.\n\n## Contract-first workflow\n\n1. Match only allowlisted operations and report exact methods, paths,\n   operationIds, parameters, request/response schemas, and documented responses.\n   Treat `operationId` and `x-*` fields as identifiers or codegen hints, not SDK\n   methods or business rules. Use an SDK-specific method only when its artifact,\n   version, and documentation are confirmed in the project.\n2. Preserve `wabaId`, YCloud phone-number IDs, and BSUIDs as opaque,\n   case-sensitive strings; do not parse prefixes or coerce numeric-looking IDs.\n   Preserve `phoneNumber` as an E.164 string, never a number. Encode path\n   segments correctly; the contact-book contract explicitly requires the\n   leading `+` to be encoded as `%2B` when constructing that path manually.\n   Never infer that a phone belongs to a WABA: use only confirmed input or a\n   WABA/phone lookup result.\n3. For list, use 1-based `page`, `limit` from 1 through 100, and documented\n   defaults. Request `includeTotal=true` only when a count is needed. Preserve\n   `filter.wabaId` exactly; the contract says it is required when the account has\n   more than 100 WABAs. Parse the response as the merged Page envelope with\n   required `offset`, `limit`, `length`, phone-number `items`, and optional\n   `total`; response `offset` is not a query parameter. Preserve unknown\n   response fields and enum/status values.\n4. Keep contract behavior distinct across operation families:\n\n   - **Business Username:** PATCH sends a required plain username without `@`.\n     Apply all generated length, character, letter, dot, prefix, and suffix\n     constraints after the documented trim/lowercase normalization. A successful\n     request may remain `reserved`; `pending_review` is a legacy response value,\n     and an existing active username may coexist with the requested one. DELETE\n     removes only the active username and does not cancel a reserved request.\n     Suggestions flatten to `data: string[]`; no suggestions is an empty array.\n   - **Meta contact book:** require a standard BSUID matching the generated\n     shape; parent `.ENT.` BSUIDs are unsupported. The WABA, phone binding, and\n     Meta business portfolio must match. This endpoint requires an account API\n     key, not a Developer App key, but credential selection/storage remains an\n     Authentication handoff. HTTP 200 always has `success=true`;\n     `deleted=false` is a successful no-match, not a 404. The operation does not\n     delete YCloud Contact/message/BSUID records, bypass Meta's 30-day cache, or\n     prevent later recreation after another WhatsApp interaction.\n   - **Profile and display name:** preserve requiredness and every generated\n     field constraint exactly. Do not make `newName` required merely because the\n     display-name endpoint's purpose suggests it if the schema does not. For\n     profile updates, enforce field length, website count/item length, URL\n     scheme, vertical values, and description-only `about` constraints without\n     inventing replacement semantics for omitted fields.\n   - **Registration:** preserve the no-body POST contract. Do not interpret a\n     200 registration response as message readiness, template approval, or\n     authorization to send.\n   - **Calling/capture settings:** GET accepts optional `type=capture|calling`;\n     omitted `type` follows the documented Calling response behavior. Save\n     `calling`, `capture`, or both. When both are sent, each branch is attempted\n     independently after shared authorization/phone validation; an error can\n     mean the other branch was already saved. Enabling either capture switch\n     requires the documented announcement language and purpose. Model combined\n     failures as partial/ambiguous outcomes, not atomic rollback.\n   - **Commerce settings:** preserve the two optional booleans and exact PATCH\n     response shape. Do not add an undocumented catalog/cart dependency or infer\n     omitted-field behavior.\n5. Keep contract facts separate from local policy. Validation, confirmation UX,\n   audit records, idempotency ledgers, retry budgets, and rollback controls are\n   application-owned unless the references say otherwise. Both DELETEs are\n   high-risk and all mutations are mock-only. Treat mutating timeouts and the\n   combined-settings failure as ambiguous; never replay a mutation\n   automatically. Honor documented `Retry-After` before later traffic without\n   treating it as proof that replay is safe.\n6. Use placeholders such as `<YCLOUD_API_KEY>`, `<WABA_ID>`,\n   `<E164_PHONE_NUMBER>`, and `<STANDARD_BSUID>` plus synthetic payloads. Keep\n   authentication server-side and hand credential storage to\n   `ycloud-api-authentication`; do not inspect `.env`, secret stores, logs, live\n   resources, profiles, usernames, or contact data.\n\n## Validation and evidence\n\nFor local implementation, add no-network tests for all selected operation\nroutes, exact path/query/body construction, opaque IDs, E.164 string handling\nand path encoding, pagination boundaries/defaults/optional totals, the\nmore-than-100-WABA filter condition, standard errors/request IDs, and unknown\nresponse properties or statuses. Add family-specific tests for username\nnormalization and validation, active-versus-reserved state, empty suggestions,\ncontact-book account-key gating and `deleted` semantics, profile/display-name\nconstraints, no-body registration, settings `type`, capture prerequisites,\ncombined-settings partial failure, commerce booleans, delete confirmation stops,\nambiguous timeouts, and no mutation replay. Mocks must prove no network client is\ninvoked.\n\nReturn these sections, adapted to the requested deliverable:\n\n1. **Matched contract** — source hash, selected operations, exact request and\n   response shapes, and description-only constraints.\n2. **Construction or implementation** — placeholder HTTP/project-local design,\n   changed artifacts, and project facts still needed.\n3. **Contract versus policy** — identify YCloud guarantees separately from local\n   validation, approvals, persistence, retries, and rollback choices.\n4. **Tests and evidence** — synthetic cases and actual no-network results.\n5. **CANNOT** — real YCloud/Meta calls, credentials/customer data, guessed SDK\n   methods, unsupported operations, unconfirmed retry/idempotency/atomicity, and\n   missing facts. Do not put confirmed pagination, error-envelope, request-ID,\n   status, or partial-success behavior in `CANNOT`.\n6. **Handoff** — receive a confirmed opaque WABA ID from\n   `ycloud-whatsapp-business-accounts`; once the WABA/phone pair is confirmed,\n   hand message submission/retrieval to `ycloud-whatsapp-messages` and template\n   lifecycle/analytics to `ycloud-whatsapp-templates`. Do not imply that phone\n   registration or configuration authorizes either downstream mutation. Return\n   to Architect with capability status, artifacts, tests, unknowns, and outgoing\n   handoffs.\n\n## Safety stop\n\nYCloud Provider API calls are prohibited during Skill execution, including\nnominally read-only GETs. All mutations are mock-only. Stop before any request\nthat would use a real API key, WABA/phone/BSUID/customer identifier, or live\nYCloud/Meta resource.\n"
}