docs(turbo-credits): correct pricing/fees and add ArNS-purchase-with-credits

[vilenarios]

Summary

Verified this page's claims against the live production system (turbo-bundler-1, ar-io-bundler @ develop ddfee37) rather than editing from assumption.

• Fixed an inaccurate claim. "No additional fees are applied when credits are spent" was wrong — a flat per-data-item surcharge (USD_PRICE_PER_DATA_ITEM, live default $0.00002/item = $0.02 per 1,000 items) is charged on every signed and x402 upload, on top of the byte-based storage cost. Confirmed in pricing.ts and that the env var is unset in prod (using the coded default). Corrected the bullet to disclose this rather than deny any fee exists.
• Verified accurate, left unchanged: the top-up fee table (ARIO no fee / all others 35%) — checked against the live payment_adjustment_catalog (0.65 multiplier = 35% general fee) and the code's tokensWithoutFees default list (["ario"], which covers both Solana and Base since there's only one unified "ario" token id in the system).
• Enriched for clarity: the free-tier bullet was accurate but underspecified — added the actual 10 MiB lifetime allowance figure (per-wallet + per-IP, never resets), matching the live free-tier config.
• Added ArNS coverage. This page had zero mention of ArNS, despite Turbo Credits already being the payment medium for buying/extending/upgrading ArNS names (buyArNSName/getArNSPriceForName), with a whole dedicated doc section (content/sdks/turbo-sdk/(arns-names-paid-with-turbo-credits)/) that wasn't linked from anywhere on this page. Added a short intro + working code example (verified against the existing buying-a-name.mdx/pricing-a-name.mdx docs) + link to the full guide, plus a Getting Started card.

Test plan

• npx tsc --noEmit — clean
• npm run build — succeeds, generates the new content, and confirms /sdks/turbo-sdk/purchase-lifecycle (the parenthesized route group stripped, per this repo's own routing convention documented in CLAUDE.md) is a real built page — i.e. the new internal link isn't broken
• npm run lint — clean
• npm run check-links — 0 new errors (5 pre-existing errors elsewhere in the repo, unrelated to this change)

🤖 Generated with Claude Code

[vilenarios]

Reviewed against the running services and updated this branch rather than just flagging it. Marked as draft — it should not merge until the actions API is live in production.

The pricing/fee half: verified, ship as-is

Checked against production (payment.services.ar.io), not assumed:

• $0.00002 per data item — a 1-byte item quotes 9,719,983 winc; 1 GiB quotes 12,073,560,618,222. The fixed component is ~9.72e-6 AR ≈ $0.00002. ✅
• 35% top-up fee — /v1/price/usd/1000 returns operatorMagnitude: 0.65, adjustmentAmount: -350. Exactly 35%. ✅
• Free tier 10 MiB / 105 KiB — prod /v1/info reports lifetimeBytes: 10485760, maxItemBytes: 107520, and ipBytes: 10485760. The per-wallet and per-subnet wording is right. ✅

The ArNS half was describing a surface that no longer exists

Not stale wording — inverted facts. The bundler replaced the per-operation ArNS routes with a single actions API and dropped Turbo-custodial ANTs and bring-your-own-ANT entirely:

Route	Prod today	Testnet (already upgraded)
POST /v1/arns/purchase/:intent/:name	400 (exists)	404
POST /v1/arns/transfer/:antId	400 (exists)	404
POST /v1/arns/manage/:antId/set-record	400 (exists)	404
POST /v1/arns/actions/:action	404	401 (exists)

Three things the old text got actively wrong:

1. "has Turbo spawn and own a fresh ANT for you" — inverts the security story. The customer owns the ANT from mint; Turbo is only the fee payer and never takes custody.
2. "Supplying your own processId skips this entirely" — that option no longer exists. Every buy mints an ANT, so every buy carries the surcharge. A client trusting that line under-quotes the purchase.
3. buyArNSName / transferArNSAnt / setArNSRecord / removeArNSRecord target the three removed routes.

The field names the branch introduced were correct — a live quote returns antSpawnSurchargeWinc: 2000000000000 and wincTotalWithAntSpawn — only the explanation around them was wrong.

What changed here

Rewrote the whole (arns-names-paid-with-turbo-credits) section onto the actions surface. Slugs are unchanged, so existing links (including this PR's) still resolve; every internal link was verified.

Also now documented, because the old model never had to draw these distinctions:

• Two identities — the payer (Turbo, any supported chain) vs the ANT owner (always a Solana address). They are allowed to differ, and conflating them is the easy integration bug.
• The owner needs a key, not a balance. Turbo is fee payer throughout; the owner's SOL can stay at zero for the life of the name.
• One signature, once. buy-name is the only action that always needs it. Extend/upgrade/undernames need none, and record writes need none while Turbo is a controller — which is why the server picks the shape and clients must branch on status, not on the action.
• The x-owner-* proof headers, and which fee field to quote (the bare winc / paymentAmount fields under-quote).

Two things to decide before this merges

1. Sequencing. The ArNS pages now describe a surface production does not serve yet. Merge after the bundler rollout, not before — otherwise the docs get wrong in the opposite direction.
2. The SDK gap. The ArNS helpers ship only on the alpha channel (@ardrive/turbo-sdk@1.42.0-alpha.8); latest (1.42.0) contains no ArNS code at all — I confirmed by unpacking both tarballs. There are no actions wrappers yet, so the flows are documented as HTTP requests. Worth a follow-up once the SDK catches up.