# PocketPapi

PocketPapi is a centralized command center for managing connected websites, tasks, agents, support, SEO, performance, and approvals.

## Public resources

- [PocketPapi homepage](https://pocketpapi.com/): Public product overview and workspace onboarding.
- [PocketPapi POS](https://pocketpapi.com/pos-software): Point-of-sale workflow for orders, menus, kitchen flow, inventory, loyalty, and shop operations.
- [PocketPapi CRM](https://pocketpapi.com/crm): Project-scoped leads, customer history, logged activity, follow-up tasks, and review-only AI drafts.
- [Team management and time tracking](https://pocketpapi.com/team-management): Employee profiles, shifts, clock records, manager-reviewed payroll workflows, and coverage.
- [Pocket Papi mobile app](https://pocketpapi.com/pocketpapi-app): Site leads, website live chat, site tools, and PocketPapi Phone activity on mobile.
- [PocketPapi Screens](https://pocketpapi.com/screens-app): Digital menu boards, announcements, display controls, and optional phone-based games.
- [Shop](https://pocketpapi.com/shop): Public product catalog with customer-facing fitment, part, package, and inventory details.
- [Help Center](https://pocketpapi.com/help): Public setup and product guidance.
- [Effects library](https://pocketpapi.com/help/effects): Public, copyable website effects catalog.
- [MCP connection guide](https://pocketpapi.com/help/mcp): Public connection instructions.
- [MCP Studio](https://pocketpapi.com/mcp): Authenticated POS-like control room for client setup, project-scoped providers, agents, scheduled Site/Local tasks, local-runner shortcuts, and contract status.
- [Affiliate program](https://pocketpapi.com/affiliate): Public partner page for people who want to sell PocketPapi websites, share tracked referrals, and earn commissions under their configured partner rules.
- [Control-plane API guide](https://pocketpapi.com/help/api): Public API documentation.
- [Sitemap](https://pocketpapi.com/sitemap.xml): Public URL inventory for search crawlers.
- [REST discovery manifest](https://pocketpapi.com/.well-known/ai-plugin.json): Public machine-readable API discovery.

## Machine interfaces

Machine interfaces:
- REST discovery: /.well-known/ai-plugin.json
- Authenticated channel setup: `/settings/api-keys` stores typed provider setup; eBay App ID/Dev ID/Cert ID/RuName, environment, and optional ePN campaign are deployment-wide, while seller OAuth and all account credentials remain encrypted per project. `/shop/manage/channels` is the project connection hub with consistent Connect, Disconnect, and Make default controls for one or more accounts; eBay seller OAuth starts there.
- REST status: /api/control-plane/status
- REST projects: /api/control-plane/projects
- REST sites: /api/control-plane/sites
- REST business network: GET/POST /api/control-plane/business-network (site-scoped, project-wide banner settings)
- REST galleries: GET/POST /api/control-plane/galleries and GET /api/control-plane/gallery-image (site-scoped gallery metadata, approved central media, and server-side image proxy)
- REST/MCP Site Studio update handshake: GET /api/control-plane/mcp/update and sitecommander_mcp_update (returns the current generated-site feature pack and staging-only update policy)
- REST MCP contract handshake: GET /api/control-plane/mcp/version?site_id=123 (always call this before work; returns the current manifest and update requirement)
- REST MCP scheduled tasks: GET/POST /api/control-plane/mcp/tasks, POST /api/control-plane/mcp/tasks/claim, POST /api/control-plane/mcp/tasks/complete
- AI Command Center REST: GET /api/control-plane/ai/workspace?action=brief&site_id=123 for the compact first read, then GET/POST /api/control-plane/ai/workspace and /api/control-plane/marketing/workspace as needed; POST /api/control-plane/marketing/media (multipart, 50 MB max; binary uploads go to the private site-scoped Project Media Library)
- AI Command Center MCP: sitecommander_ai_workspace and sitecommander_marketing_workspace; start with the compact token-conscious `brief`, then request exact records; shared Muse/MCP/browser handoff threads, tasks, scheduled tasks, reminders, no-generation content/social drafts, reusable project media, campaign/funnel drafts, editorial dates without a provider, and confirmed social publishing when connected
- AI Command Center browser bridge: /ai/command-center surfaces the authenticated project workflows, common MCP tool names, connected remote MCP servers, and copy-ready client instructions; browser access keeps the signed-in user’s project/site permissions
- REST Pocket Papi status: /api/control-plane/easyapp (legacy path)
- REST Pocket Papi ensure: POST /api/control-plane/easyapp (legacy path; site-scoped, idempotent)
- REST synchronization health: /api/control-plane/sync-health
- REST tasks: /api/control-plane/tasks
- REST activity: /api/control-plane/activity
- REST reviews: /api/control-plane/reviews?site_id=123
- REST conversations: /api/control-plane/conversations?site_id=123
- REST messages: /api/control-plane/messages?conversation_id=123
- REST support tickets: /api/control-plane/tickets?site_id=123
- REST ticket messages: /api/control-plane/ticket-messages?ticket_id=123
- REST reply to review: POST /api/control-plane/reviews/reply
- REST reply to conversation: POST /api/control-plane/messages/reply
- REST sender profiles: GET/POST /api/control-plane/mail/profiles
- REST BIMI status/prepare/verify/record: /api/control-plane/bimi/*
- REST ingest: POST /api/control-plane/events (message, subscription, contact, or lead)
- Pocket Papi compatibility site directory: GET /api/easyapp/sites
- Pocket Papi compatibility enrollment: POST /api/easyapp/configure
- Pocket Papi compatibility site login: POST /api/easyapp/auth/login
- Pocket Papi compatibility leads: GET /api/easyapp/leads; POST /api/easyapp/leads/status
- Pocket Papi compatibility live chat: GET /api/easyapp/conversations, GET /api/easyapp/messages, POST /api/easyapp/messages/reply
- PocketPapi mobile login: POST /api/command-center/auth/login
- PocketPapi mobile data: GET /api/command-center/summary, /projects, /sites, /marketing, /tasks, /activity, /integration-logs (administrator troubleshooting permission). The marketing view is scoped to accessible projects and reports ads/campaigns, content, research, business plans, site plans, channels, leads, and customer-account inventory.
- MCP JSON-RPC: /mcp
- MCP setup tool: sitecommander_mcp_studio (returns the Studio URL plus a non-secret site-provider readiness status; if setup is required, direct the user to the provider fields in Studio and never ask for a key in chat)
- Codex MCP configuration uses `bearer_token_env_var = "POCKETPAPI_MCP_TOKEN"`; this is only the environment-variable name. Store the one-time `sc_...` bearer token separately in `POCKETPAPI_MCP_TOKEN` and never put the token itself in `bearer_token_env_var`.
- MCP version/task tools: sitecommander_mcp_version, sitecommander_agents, sitecommander_scheduled_tasks, sitecommander_task_create, sitecommander_task_claim_local, sitecommander_task_complete_local
- AI/marketing workspace MCP tools: sitecommander_ai_workspace, sitecommander_marketing_workspace (reads are bounded and site scoped; draft writes require idempotency keys; social scheduling needs explicit confirmation, a connected destination, publishing permission, and applicable platform consent)
- Site Studio MCP tools: sitecommander_site_studio_pages, sitecommander_site_studio_edit, sitecommander_site_studio_page_add, sitecommander_site_studio_page_remove, sitecommander_site_studio_page_role, sitecommander_site_studio_blocks, sitecommander_site_studio_block_add, sitecommander_site_studio_media, sitecommander_site_studio_image_replace, sitecommander_site_studio_effect_apply, sitecommander_site_studio_navigation, sitecommander_site_studio_navigation_save, sitecommander_site_studio_pagespeed, sitecommander_site_studio_publish. Site-file edits stay in staging and return a preview; publishing requires separate approval of the exact change_set_id.
- Site Studio link editing: per-link Amazon/eBay tracking IDs use the selected site's Shop connection, then PocketPapi central Shop. Links can add owner-provided HTTPS social profiles to the accessible social bar. Form/gallery saves through sitecommander_forms/sitecommander_form_save and sitecommander_galleries/sitecommander_gallery_save return an exact staged revision and preview; generated public sites read only published snapshots. Protection tools remain available through sitecommander_protection_status/sitecommander_protection_save.
- Complete API guide: /api/control-plane/guide
- Central Zernio gateway: /api/control-plane/zernio/accounts, /api/control-plane/zernio/reviews, /api/control-plane/zernio/posts
- Public effects library: /help/effects (63 recipes, including advanced native recipes and eight free MIT library starters)
- Public effects catalog: GET /api/effects, GET /api/effects/{effect_id}, POST /api/effects/compose
- MCP effects tools: sitecommander_effects_search, sitecommander_effects_fetch, sitecommander_effects_compose
- MCP mail tools: sitecommander_mail_profiles, sitecommander_mail_profile_upsert, sitecommander_bimi_status, sitecommander_bimi_prepare, sitecommander_bimi_verify, sitecommander_bimi_record
- MCP business network tools: sitecommander_business_network, sitecommander_business_network_save (theme, CTA, business names, HTTPS website/logo URLs, and site-aware highlighting)
- MCP gallery tools: sitecommander_galleries, sitecommander_gallery_save (site-scoped gallery placement, ordered central-media items, HTTPS image URLs, captions, alt text, and enabled state; writes are staged until exact-revision publish approval)
- Site service catalog: GET/POST /api/control-plane/site-services; site-scoped drafts, approved same-site media references, exact staged revisions, and published snapshots. Use sitecommander_services, sitecommander_service_save, and sitecommander_service_delete. Add the Site Studio service_catalog block to imported pages; generated public output reads only published records through pocketpapi-services.php and shows an explicit empty state.
- MCP support tools: sitecommander_conversations, sitecommander_messages, sitecommander_tickets, sitecommander_ticket_messages, sitecommander_send_message
- REST POS integration: GET/POST /api/control-plane/pos/{action} for the complete site-scoped POS suite: catalog/menu/modifiers, orders and line items, payments, register sessions/cash movements, KDS/order status, inventory events, payment attempts, loyalty, promotions/redemptions, rewards/redemptions, gift cards/transactions, giveaways/entries, broadcasts, drivers/deliveries, kiosks, self-serve stations/requests, printers, menu boards, labels/printables/presets, settings, reports, site-scoped email/text subscribers, and social/ticket/order links
- REST POS sync: POST /api/control-plane/pos/sync-config, POST /api/control-plane/pos/sync, GET /api/control-plane/pos/sync-health, GET /api/control-plane/pos/sync-export, POST /api/control-plane/pos/sync-import, and GET /cron/pos-sync?secret=CRON_SECRET
- MCP POS tools: sitecommander_pos_* mirrors every POS action, including sitecommander_pos_driver_save, sitecommander_pos_gift_card_issue, sitecommander_pos_gift_card_redeem, sitecommander_pos_sync, sitecommander_pos_social_link, and sitecommander_pos_social_reply
- MCP Pocket Papi provisioning tool: sitecommander_easyapp_ensure (legacy tool name; creates/updates the site workspace; never returns private configuration codes or signing credentials)
- REST shop contract: GET /api/control-plane/shop/status, POST /api/control-plane/shop/ensure, GET /api/control-plane/shop/distribution, POST /api/control-plane/shop/distribution, POST /api/control-plane/shop/distribution/opt-in, GET/POST /api/control-plane/shop/products, POST /api/control-plane/shop/products/enrich, GET /api/control-plane/shop/orders, GET/POST /api/control-plane/shop/channels, POST /api/control-plane/shop/publish/prepare, POST /api/control-plane/shop/publish/execute, POST /api/control-plane/shop/sync/prepare, POST /api/control-plane/shop/sync/execute, GET /api/control-plane/shop/job
- MCP shop tools: sitecommander_shop_ensure, sitecommander_shop_distribution, sitecommander_shop_distribution_save, sitecommander_shop_distribution_opt_in, sitecommander_shop_products, sitecommander_shop_product_save, sitecommander_shop_product_enrich, sitecommander_shop_orders, sitecommander_shop_channels, sitecommander_shop_channel_save, sitecommander_shop_publish_prepare, sitecommander_shop_publish_execute, sitecommander_shop_sync_prepare, sitecommander_shop_sync_execute, sitecommander_shop_job
- REST eBay contract: GET/POST /api/control-plane/ebay/{action}; read actions are status, readiness, search, item, saved_items, and job; write actions are config_save, authorization_start, external_item_save, publish_prepare, publish_execute, sync_prepare, and sync_execute. eBay seller OAuth is project-Shop scoped, and Sell API writes require explicit confirmation.
- MCP eBay tools: sitecommander_ebay_status, sitecommander_ebay_readiness, sitecommander_ebay_search, sitecommander_ebay_item, sitecommander_ebay_saved_items, sitecommander_ebay_job, sitecommander_ebay_config_save, sitecommander_ebay_authorization_start, sitecommander_ebay_external_item_save, sitecommander_ebay_publish_prepare, sitecommander_ebay_publish_execute, sitecommander_ebay_sync_prepare, sitecommander_ebay_sync_execute
- Generated Site Studio shop surfaces: pocketpapi-shop.php for staff offer selection and pocketpapi-offers.php for the branded public offer widget. Central PocketPapi products remain the source of truth; referral links create pending order-backed commission rows.
- Public shop surfaces: /shop, /shop/product/{slug}, /shop/cart, /shop/checkout, /shop/order/{order_number}, and feed endpoints under /shop/feed/ including /shop/feed/grubhub.json. Connector setup requirements remain protected Help Center content for authorized users only. PayPal Checkout is separate from the paypal_zettle POS/inventory channel.
- Public subscriptions: GET/POST /subscribe and POST /subscribe/unsubscribe collect and revoke central email/text opt-ins with explicit channel consent; staff can review them at /broadcasts.

Authentication uses `Authorization: Bearer <token>`. Broad MCP tokens are created once by an authenticated administrator from MCP Studio, are shown once, and scope project/site discovery to the token creator's accessible workspaces or selected sites. A site owner can instead use the project's MCP/API setting to create a site-scoped connection token for that site's server; it is shown once, rotates the previous site token, and cannot reach another site. MCP responses include `mcp_contract` metadata; clients should perform the version handshake before every task or tool session. Live-chat replies through `/api/control-plane/messages/reply` appear in the visitor's site widget and PocketPapi Support Inbox/action center. MCP/API requests are recorded for administrator troubleshooting without storing tokens or request bodies.

MCP Studio shows a prominent setup notice when no effective server-side Site AI provider is configured or its encrypted API key is missing. Site-mode scheduled tasks require that provider; the notice links to the authenticated provider form. Local-mode tasks remain available and use the key already configured in Codex, Claude, or another local runner. Never request, retrieve, or transmit a local AI key through MCP, and never expose the server's encrypted provider value in an MCP response.

Connected sites send `POST /api/control-plane/events` with their site-scoped token. Use `/api/control-plane/sync-health` to verify last event/API activity, and use Audit Logs in the command center to troubleshoot working and failed calls.

The POS contract is identical on PocketPapi and MyRides (`https://emmitsburgrides.com`). Configure a peer on both sites with `sync-config`, use a site-scoped token with `pos_sync`, and schedule `/cron/pos-sync` from cPanel for automatic bounded bilateral sync. Tokens, passwords, payment credentials, and social-provider secrets are never exported.

PocketPapi public sites are discoverable without a token; private sites require an owner-issued configuration code shown once from the PocketPapi setting in Project Setup. Every project receives Pocket Papi automatically, and Project Setup controls its app name and public/private enrollment in one place. Pocket Papi then uses a separate site-scoped user session for leads and live chat. Legacy EasyApp/App route names remain only for compatibility. Never place an MCP token in the PocketPapi mobile bundle.

The public `/affiliate` page is the top-of-funnel partner offer: it is aimed at web designers, marketers, consultants, and trusted community operators who want to sell PocketPapi websites with delivery support. The page explains the partner flow (introduce a business, share a tracked link, follow conversion and commission status), and its form defaults to affiliate enrollment. Personalized `/affiliate/{slug}` pages remain customer-facing referral landing pages and keep the referring partner attached to website inquiries.

The effects endpoints are read-only, public, and do not require command-center access. LLMs should search the catalog before writing new motion, prefer native recipes, pin third-party versions, and preserve keyboard, touch, and prefers-reduced-motion behavior.

Mail identity is site-scoped. Sender profiles accept public HTTPS photo URLs or base64 PNG/JPEG/WebP uploads up to 4 MB. BIMI preparation accepts validated SVG Tiny PS and optional VMC/CMC PEM assets, returns the DNS TXT record, and never changes DNS. Never claim BIMI is active unless the verification checks pass. BIMI is a brand-logo signal; Gmail/Microsoft 365 account photos and Outlook directory/contact photos are provider or recipient controlled.