Add iOS/Android push notification integration guides

[dadachi]

Summary

Two implementation guides for paid iOS/Android substrate clients (issue #58 PRs #3, #4):

• docs/push-ios-integration.md — APNs registration in AppDelegate, permission UX, token lifecycle, foreground/background handlers, sign-out cleanup
• docs/push-android-integration.md — Firebase setup, FirebaseMessagingService, POST_NOTIFICATIONS permission for API 33+, notification channels, token sync, sign-out cleanup

Scope split clarified in each doc

Concern	This Rails repo	Client repo (this guide)
Provider credentials (APNs .p8 / FCM service account)	✅
ItemTagNotifier payload + AASM trigger	✅
POST /api/v1/shopkeeper/devices API contract	✅ (docs/openapi.yaml)	references it
Token receipt + lifecycle (POST/DELETE)		✅
Permission UX		✅
Foreground/background presentation		✅

Each guide includes:

• API contract recap with platform: "apple" / "google" (matches Action Push Native conventions, not ios / android)
• Capabilities / project setup
• Permission UX patterns
• 4-stage token lifecycle (receive · refresh · sign-in rebind · sign-out)
• Foreground vs background presentation
• Local testing tips (including how to trigger the notifier from the Rails console)
• Out-of-scope list (notification grouping, custom actions, Notification Service Extension, etc.)

Both guides follow the substrate rename-safety contract — no article-coupled domain words, so the agent's text-only rename pipeline won't produce article disagreements.

Test plan

• Markdown renders correctly in GitHub preview
• Cross-references to docs/openapi.yaml and app/models/item_tag.rb resolve
• No article-coupled domain noun violations (substrate rename-safety contract)

🤖 Generated with Claude Code

[dadachi]

Moved to docs-private/ — these docs are paid-edition-only client integration guides and shouldn't ship in the open-source repo's docs/ tree.