Agent docs

Mobile admin starts with one contract for iOS and Android.

Bumpgrade will build native publisher/admin apps from the same feature, roadmap, commerce, admin, and agent contracts used by the web app. This page defines the shared scope and the first platform smoke paths for #67 and #68 plus the issue #414 owner-session, private-row, private-row action, Director review, commerce review, action-intent, Director digest, confirmed-action, push-readiness, and distribution-readiness contract.

Mobile admin source data Live mobile dashboard source data

Status

Contract readyIssue #13 splits platform work into iOS issue #67, Android issue #68, and dashboard issue #153.

Private auth and actions

Mobile uses the same owner-session and confirmation rules.

Track issue #414

owner-session-contract-ready

Mobile private views reuse the same Better Auth cookie/session, owner allowlist, verified-email gate, and admin role mapping as web admin. The mobile app must not invent mobile-only roles or bypass the web/admin owner boundary.

owner-mobile-private-rows-ready

The endpoint returns owner-only private row notes and synthetic private payload metadata only to authenticated owners. Public mobile source-data exposes route, status, counts, public row labels, and redaction flags without owner-only notes, private payload JSON, owner email values, session IDs, cookies, tokens, or raw rows.

owner-mobile-private-row-actions-ready

The endpoint mutates only private-row workflow state after exact confirmation, idempotency, stale row revision, stale-state token, and audit-correlation checks. It creates no billing mutation, commerce mutation, publishing mutation, push notification, distribution state change, moderation action, creator-speech action, or public agent write.

owner-mobile-director-review-ready

The endpoint records low-risk production owner review state after exact confirmation, idempotency, current Director source-revision checks, stale-state token checks, and audit correlation. It changes only Director review state and creates no billing mutation, publishing mutation, push notification, distribution state change, public agent write, or private-row change.

owner-mobile-commerce-review-ready

The endpoint records low-risk owner commerce review state after exact confirmation, idempotency, current commerce source-revision checks, stale-state token checks, and audit correlation. It changes only commerce review state and creates no billing mutation, refund, subscription change, price change, fulfillment change, entitlement change, push notification, distribution state change, public agent write, or private-row change.

owner-mobile-action-intent-ready

The endpoint records redacted action intent evidence only. It creates no production admin mutation, billing mutation, push notification, distribution state change, private mobile row exposure, or direct public agent write.

Review and confirm agent work

The current /api/mobile-admin/director-reviews endpoint can record owner-confirmed Director workstream review state for this action. /api/mobile-admin/actions remains available for audit-only action intent evidence, but higher-risk production mutations still require domain-specific confirmed-write APIs.

Review commerce health

The current /api/mobile-admin/commerce-reviews endpoint can record owner-confirmed commerce-health review state for this action. It does not create checkout, refund, subscription, price, fulfillment, entitlement, push, distribution, private-row, or public agent mutations.

Confirm commerce or fulfillment changes

No mobile checkout, refund, subscription, price, fulfillment, or entitlement mutation is live until the shared confirmed-write API and platform evidence exist.

Push and distribution

Readiness is explicit, but sends and store distribution are not live.

Track issue #414

push-boundary-ready

Public mobile source-data may expose provider names, disabled send status, required evidence, blocked-by reasons, and redaction flags. It must not expose APNs/FCM credentials, device tokens, recipient identities, push payload bodies, queue rows, provider responses, or delivery receipts.

distribution-boundary-ready

Public mobile source-data may expose simulator/emulator status, required platform evidence, and current blockers. It must not expose signing credentials, provisioning profiles, keystore material, store account identifiers, private tester lists, or physical-device private rows.

Disabled until evidence exists

disabled-provider-contract-required; installable distribution claim not live.

Live dashboard

One public-safe digest for mobile clients.

Dashboard source data

Route

/mobile-admin/dashboard/source-data gives iOS, Android, web, and agents one dashboard payload.

Status

live-public-source-data-ready from issue #153.

Redaction

The dashboard exposes counts, statuses, route IDs, issue evidence, and recent public-safe work-log metadata only. It excludes private buyer rows, raw inbox bodies, owner email values, session IDs, R2 object keys, signed URLs, upload bodies, secret values, and write tokens.

Director brief

The phone view can start with workstreams instead of nested noise.

Director source data

Source

The mobile dashboard carries a redacted directorDigest sourced from /admin/director/source-data.

Shape

Mobile clients can show workstream totals, 1-day/7-day changes, executive queue counts, and compact brief signals for categories such as Marketing, Mobile Admin, and Security / Trust.

Redaction

The digest excludes raw attention bodies, raw work-log bodies, private rows, owner email values, and private evidence.

Jobs

What publishers need on a phone

Track issue #13

JobMobile admin digest

Check launch and platform status away from desktop

See whether Director workstreams such as marketing, security, mobile, funnels, checkout, products, email, analytics, agent work, and blockers are moving without opening the desktop admin app.

UserPublisher or owner monitoring Bumpgrade from a phone

Source routes/mobile-admin/dashboard/source-data, /admin/director/source-data, /features/source-data, /roadmap/source-data, /admin/source-data

BoundaryRead-only in the first mobile slice.

JobOwner-attention and work-log inbox

Review agent work and confirm safe follow-up actions

Inspect work-log entries, owner-attention items, screenshots, and required confirmations before approving public or billing-impacting work.

UserOwner receiving Codex, ChatGPT, Claude, or automation proposals

Source routes/mobile-admin/dashboard/source-data, /api/mobile-admin/private-rows, /api/mobile-admin/private-rows/actions, /admin/work-log/source-data, /admin/for-mark/source-data, /agent-docs/source-data

BoundaryConfirmed writes need actor identity, confirmation text, idempotency key, stale-state check, audit correlation, and redaction.

JobCommerce health summary

Inspect offer and checkout health

Read products, prices, sandbox/live checkout state, webhook evidence, and known Stripe blockers before taking action.

UserPublisher watching sales and fulfillment state

Source routes/mobile-admin/dashboard/source-data, /api/mobile-admin/commerce-reviews, /commerce/source-data, /api/commerce/checkout

BoundaryMobile can record owner-confirmed commerce-health review state through /api/mobile-admin/commerce-reviews, but no live checkout, refund, subscription, price, fulfillment, or entitlement mutation from mobile is live until higher-risk confirmed-write APIs ship.

Platform split

Each app gets its own issue and smoke path.

iosIssue #67

Build first iOS publisher admin app slice

Render the mobile admin digest, fetch the live dashboard route, and preserve fixture fallback in the Expo app foundation and iOS simulator smoke target.

Statussimulator-smoke-ready

ValidationRun npm run mobile:ios:validate to prove the fixture matches the shared contract and Xcode is available. Run npm run mobile:ios:smoke to build, install, launch, live-read/fallback hydrate, and screenshot the iOS simulator target.

androidIssue #68

Build first Android publisher admin app slice

Render the mobile admin digest, fetch the live dashboard route, and preserve fixture fallback in a native Android activity and emulator smoke target.

Statusemulator-smoke-ready

ValidationRun npm run mobile:android:validate to prove the fixture matches the shared contract and Android API 36 tooling is available. Run npm run mobile:android:smoke to build, install, launch, live-read/fallback hydrate, and screenshot the Android emulator target.

iOS slice

The first simulator path is source-data backed.

iOS source data

App foundation

apps/mobile-admin contains the Expo entrypoint and iOS smoke target.

Fixture

apps/mobile-admin/fixtures/mobile-admin-contract.json is generated from /mobile-admin/source-data before the iOS app renders.

Smoke

npm run mobile:ios:smoke builds, launches, and screenshots the simulator target.

Android slice

The first emulator path is source-data backed.

Android source data

App foundation

apps/mobile-admin/android contains the native Android smoke target.

Fixture

apps/mobile-admin/android/src/main/assets/mobile-admin-contract.json is generated from /mobile-admin/source-data before the Android app renders.

Smoke

npm run mobile:android:smoke builds, launches, and screenshots the emulator target.

API dependencies

Mobile reuses web and admin contracts.

Agent manifest

public-safe/mobile-admin/dashboard/source-data

mobile-api-dashboard

Live public-safe dashboard bundle for iOS and Android clients so mobile does not stitch or infer project state from hidden admin pages.

Stable IDsmobileDashboardCardId, directorWorkstreamId, directorBriefSignalId, directorBriefingControlId, featureId, roadmapItemId, workLogEntryId, markAttentionId, agentReadContractId

public-safe/admin/director/source-data

mobile-api-director-status

Public-safe CEO-style workstream brief for mobile clients, including top-level workstreams, current focus, briefing controls, due/in-flight/pending/change signals, and redacted 1-day/7-day change windows.

Stable IDsdirectorWorkstreamId, directorBriefSignalId, directorBriefingControlId, directorWindowId, workLogEntryId, roadmapItemId

public-safe/admin/source-data

mobile-api-admin-source

Public-safe roadmap, work-log, user-journey, and owner-attention digest for the first mobile admin screen.

Stable IDsworkLogEntryId, userJourneyId, markAttentionId, roadmapItemId

public-safe/features/source-data

mobile-api-feature-catalog

Feature status and issue evidence for the mobile dashboard.

Stable IDsfeatureId, issue, status

public-safe/roadmap/source-data

mobile-api-roadmap

Public roadmap lanes, blockers, next milestones, and issue links.

Stable IDsroadmapItemId, featureId, issue, status

public-safe/commerce/source-data

mobile-api-commerce

Redacted products, prices, checkout-intent, webhook, subscription, and audit architecture.

Stable IDsproductId, priceId, checkoutIntentId, auditCorrelationId

owner-session/api/auth/[...all]

mobile-api-auth

Better Auth session boundary for future private publisher/admin mobile views.

Stable IDsuserId, sessionId, role

owner-session/api/mobile-admin/private-rows

mobile-api-private-rows

Owner-session-only private row inspection for Mobile Admin clients, with public source-data limited to route, status, counts, public row labels, and redaction flags.

Stable IDsmobilePrivateRowId, sourceRoute, sourceRecordId, readState

owner-session/api/mobile-admin/private-rows/actions

mobile-api-private-row-actions

Owner-confirmed private row workflow actions for Mobile Admin clients, limited to low-risk mark-read and defer mutations with redacted audit evidence.

Stable IDsmobilePrivateRowActionId, mobilePrivateRowId, idempotencyKey, auditCorrelationId, staleStateToken

owner-confirmed-intent/api/mobile-admin/actions

mobile-api-confirmed-writes

Owner-gated mobile action-intent endpoint for redacted audit-only confirmation evidence before future domain-specific confirmed-write APIs mutate admin, publishing, commerce, or agent-proposal state.

Stable IDsagentActionId, idempotencyKey, auditCorrelationId, staleStateToken

owner-session/api/mobile-admin/director-reviews

mobile-api-director-review

Owner-confirmed Director workstream acknowledgement API for mobile clients, with exact confirmation, stale Director payload checks, idempotency, audit correlation, and redaction.

Stable IDsdirectorWorkstreamId, mobileDirectorReviewId, idempotencyKey, auditCorrelationId, staleStateToken

owner-session/api/mobile-admin/commerce-reviews

mobile-api-commerce-review

Owner-confirmed commerce-health acknowledgement API for mobile clients, with exact confirmation, stale commerce source-data checks, idempotency, audit correlation, and redaction.

Stable IDscommerceReviewTargetId, mobileCommerceReviewId, idempotencyKey, auditCorrelationId, staleStateToken

public-safe/mobile-admin/source-data

mobile-api-push-boundary

Public-safe push-notification readiness boundary for APNs/FCM provider requirements, disabled send status, blockers, and redaction flags before any Mobile Admin push sends exist.

Stable IDsmobilePushBoundaryId, provider, readinessChecklist, blockedBy

public-safe/mobile-admin/source-data

mobile-api-distribution-boundary

Public-safe distribution readiness boundary that separates simulator/emulator evidence from physical-device and App Store/Play Store claims.

Stable IDsmobileDistributionReadinessId, platform, requiredBeforeClaim, blockedBy

Stack and safety

No mobile-only product semantics.

Native direction

Start the publisher admin apps as an Expo React Native TypeScript workspace shared by iOS and Android, unless the child issue smoke tests expose a platform-specific reason to split native code. The repo has no existing native app tree, and the current web/admin state is already modeled as public-safe TypeScript/JSON contracts.

Auth boundary

Mobile auth source-data may name routes, roles, denial states, and issue evidence, but it must not expose owner email values, session IDs, cookies, tokens, raw Better Auth payloads, or private admin rows.

Confirmed writes

The first private mobile row slice is read-only through /api/mobile-admin/private-rows and cannot mutate production state. The first domain-specific Mobile Admin confirmed-write slice can acknowledge Director workstreams through /api/mobile-admin/director-reviews, but it mutates only low-risk owner review state.