docs(pos): document Discount.amount read behavior from 2026-10

[vctrchu]

What

Adds TSDoc to Discount.amount on the POS cart types documenting the read behavior that ships with API version 2026-10: reading a manual discount from the cart returns the value that was applied (e.g. 10 for 10%), matching writes, so discounts can be echoed through bulkCartUpdate losslessly. Includes the POS app version caveat for older clients.

Why

Part of the fix for shop/issues-retail#33093: before 2026-10, reads return the calculated monetary total while writes take the applied value, so read-modify-write cycles silently corrupt percentage discounts. The behavior change is implemented in Shopify/extensibility#1657 (host, version-gated) and shop/world#997169 (POS emits the raw value).

Reported in https://community.shopify.dev/t/36265 and https://community.shopify.dev/t/36171.

Companion doc correction for the released 2026-07 branch: see the 2026-07_pos_discount_amount_doc_fix PR.

[github-actions]

We detected some changes in packages/*/package.json or packages/*/src, and there are no updates in the .changeset directory. If the changes are user-facing and should cause a version bump, run yarn changeset to track your changes and include them in the next release CHANGELOG. If you are making simple updates to repo configuration, examples, or documentation, you do not need to add a changeset.

[github-actions]

📝 POS Version Documentation Reminder

We detected changes in packages/*/src/surfaces/point-of-sale, but there are no updates to the POS versions documentation.

If these changes are user-facing and should be documented in the version changelog, please update:
packages/ui-extensions/docs/surfaces/point-of-sale/staticPages/pages/versions.doc.ts

If you are making internal changes that don't affect the public API, you can ignore this reminder.

[vctrchu]

Superseded by #4621 — the 2026-10 release now lives on the 2026-10-rc branch, so the doc change targets that instead of unstable.