| name | peek-app-builder |
| description | Entry point and guided workflow for building an app on this Peek Pro starter kit (a Next.js app that embeds inside Peek Pro's back-office iframe). Use when the user wants to build a Peek Pro app or add a feature to one — waitlist, abandoned-booking recovery, dynamic pricing, custom checkout, reseller/channel sync, reporting, webhook handling, or anything Peek Pro lacks natively. Owns the discover → mock → plan → sign-off → build → validate flow and delegates the specifics to the peek-embed-and-auth, peek-backoffice-api, peek-webhooks, peek-mcp-endpoint, odyssey-ui, peek-app-manifest-and-deploy, and testing-peek-apps skills. Triggers on "Peek Pro app", "PeekPro", "Peek app", "Peek booking", "Peek integration", "build on the starter kit". |
Build a Peek Pro app (on this starter kit)
You are helping the user build an app that extends Peek Pro — a tours & activities booking
platform — using this repository, an opinionated Next.js starter kit that already ships the
hard parts (iframe embed, the auth pipeline, the Peek SDK client, Odyssey UI, tests, CI). Your
job is to extend what's here, not rebuild it from scratch.
Peek Pro is sparsely documented, so do not rely on model memory for Peek specifics. These
skills carry the canonical knowledge and tell you when to look things up live.
The core stack is already decided — don't re-litigate it
Unlike a greenfield build, you do not choose the language, framework, or SDK. This kit is
Next.js 16 + React 19 + Tailwind 4 + TypeScript (App Router), tests with Vitest, and
talks to Peek through the @peektravel/app-utilities package (PeekAccessService,
Node-only — the first-class SDK). Take these as given.
Host and database are still your choice (the "moving layer" — see below). The recommended
default is Vercel for hosting and Neon (serverless Postgres) for data when you need it,
accessed server-side only (a DATABASE_URL), with live UI via polling/SSE from your own API
routes — offer it as a recommendation, not a mandate. Phase 0 ships no database (persistence
is deliberately deferred), so most first apps don't need one yet. See
peek-app-manifest-and-deploy for the deploy/secrets specifics — including why Supabase is a
poor fit here (its auth/RLS model doesn't match Peek's token).
⚠️ The repo currently includes Fly.io / Docker files (Dockerfile, fly.toml,
fly-deploy.yml) — these are placeholder scaffolding scheduled for removal, not the
recommended target. Don't steer the user to Fly; recommend Vercel.
Read AGENTS.md first. This Next.js version has breaking changes vs. training data, and
the iframe/SPA architecture has hard constraints (no cookies, no SSR data fetching,
library-owned auth). Everything below assumes those rules.
This skill reconciles three layers of knowledge
Your real job is synthesis. Three sources of truth meet at build time:
-
Fixed layer — the sibling skills. How Peek apps work: the embed/auth handshake, data
scoping, webhooks, the SDK, Odyssey, deploy. Stable; trust these skills.
-
Moving layer — live web search. Current best practices for Next.js 16 / React 19 / your
host (Vercel by default) — this ages fast, so research it fresh (and read
node_modules/next/dist/docs/ for the framework APIs, per AGENTS.md).
-
Peek specifics — the installed @peektravel/app-utilities package. For Peek's concrete
facts — the SDK surface, webhook parsers, Odyssey components, install/settings contract —
read the package itself. It's the authoritative, version-matched source:
node_modules/@peektravel/app-utilities/dist/index.d.ts — every public method/type,
fully typed with TSDoc and exact return shapes (the SDK surface; see peek-backoffice-api).node_modules/@peektravel/app-utilities/docs/ — the shipped guides, e.g. docs/ui.md
(Odyssey), docs/webhooks.md (webhook config + parsers). (Same files are mirrored on
jsdelivr if you need them without installing.)
This is the primary research step for anything Peek-specific — inspect the package first.
If a fact genuinely isn't in the types or docs/, mark it TODO(verify), check the live
web doc, and/or ask the user — never silently fill the gap with a guess.
The app you're building serves its own MCP endpoint by default — a runtime surface so the
App Store's AI orchestrator can operate it without the UI (see peek-mcp-endpoint). That's the
app exposing itself; Peek's own facts still come from the installed package (above).
How to interact (every step)
- Always ask when something is unclear — never guess or assume the goal, scope, a Peek
detail, or the right approach.
- Ask one question at a time. Pose a single question with your recommendation, let the
user chat it through, and only then move on. Don't batch questions.
The workflow
Kickoff: give the user a short bulleted overview of these steps and ask if they want to do
anything differently (skip, reorder, re-emphasize). Then begin.
| Step | What it covers | Lean on |
|---|
| 1. Discover purpose | What gap in Peek Pro does this fill? Who uses it (account staff / guests / app admin)? What triggers it (a webhook, a schedule, a user action)? What Peek data does it read/change? Tight v1 scope. Explicitly raise the MCP endpoint here (built by default): tell the user, recommend a concrete tool list derived from the app's jobs, and let them confirm/trim/opt out. Also flag any stack risk that could break the endpoint. | peek-backoffice-api, peek-webhooks for what's possible; peek-mcp-endpoint for what to expose |
| 2. Mock the UI | Build an interactive single-file index.html Odyssey mockup, iterate until the user is happy. | odyssey-ui |
| 3. Plan | Map the data flow as rigorously as the UI (source → when → storage → verified available?), pick which webhooks vs. SDK calls, note installDataId scoping if persistence is added. Write it up using plan-template.md. | all platform skills + the installed package (types + docs/) + web |
| 4. Sign-off (hard gate) | Present the plan; get an explicit "yes, build this." Call out anything you couldn't verify in the package/docs (TODO(verify)). Do not build before this. | — |
| 5. Build | Implement per the plan: new authenticated routes + client fetches, webhook endpoints, the MCP endpoint (by default), Odyssey UI, tests as you go. | peek-embed-and-auth, peek-backoffice-api, peek-webhooks, peek-mcp-endpoint, odyssey-ui, testing-peek-apps |
| 6. Validate & ship | Run lint/typecheck/tests + coverage; have the user run the app under the Peek framework (local tunnel or deploy — see below) so the embed actually loads; confirm secrets/PII handling; hand the user their production env-var checklist (see below); register in the Development Hub and deploy. |
Don't skip discovery/mockup, and don't build before sign-off (step 4).
Running the app — next dev won't work; it needs the Peek framework
This app cannot be run or exercised with the standard Next.js toolchain — next dev, a
plain localhost:3000, a preview server, or any generic emulator. Those load the app outside
Peek, where it has no iframe host, no parent frame to postMessage a token from, and no App
Store registration — so the token gate never resolves and every authenticated route 401s. A
green next dev proves nothing here; don't rely on it to validate behavior, and don't tell
the user the app "works" because a dev server started.
You (the agent) also can't run the real thing yourself — it requires the user's Peek
credentials and an App-Store-registered tunnel. So when it's time to see the app actually run,
stop and hand off to the user with one of two paths:
What you can do without the framework: lint, typecheck, and the Vitest suite (auth logic,
webhook derivation, ID normalization, tool dispatch — see testing-peek-apps). Drive those
yourself, but for "does it actually run in the embed," notify the user to run
npx @peektravel/app-cli dev or deploy — that's their step, not yours.
Before deploy: hand the user their production env-var checklist
Ending a build must include an explicit, copy-pasteable list of the environment variables
the app needs in production — the single most common "the app 401s / won't boot after deploy"
cause is a var that's set locally but never added to the host. Don't assume the user knows which
ones; lib/env.ts fails loud at runtime if any required var is missing (see the misconfig
→ 500 guidance in peek-embed-and-auth), so a forgotten var is a broken deploy, not a warning.
The list is dynamic — don't just parrot the base four. Derive it at the end of this build:
- Start with the kit's required runtime vars:
PEEK_APP_SECRET, PEEK_APP_ID,
PEEK_APP_URL, and PEEK_API_URL (only if you overrode the default).
- Add every var this build introduced — grep the code you wrote for
process.env. and read
lib/env.ts. Anything you added there (a DATABASE_URL for Neon, a third-party API key, a
webhook signing secret, an SSE/queue URL) belongs on the list. Any new runtime var must be
registered in lib/env.ts's Zod schema so it's validated on boot — if it's read from
process.env but not in the schema, add it, then include it here.
- Mark each as secret (host secret store only, never committed —
PEEK_APP_SECRET,
DATABASE_URL, API keys) or non-secret config (PEEK_APP_ID, PEEK_APP_URL).
Then present it verbatim, e.g.:
Before you deploy, set these in your host (Vercel → Settings → Environment Variables):
PEEK_APP_SECRET — secret (from the Development Hub)PEEK_APP_ID — config (from the Development Hub)PEEK_APP_URL — config (your deployed base URL; must match app.json base_url)PEEK_API_URL — config (only if overriding the default)DATABASE_URL — secret (Neon; server-only) (only if this build added persistence)- …any other var this build introduced
The app validates these on boot and will 500 on the first request if any required one is
missing — so set them before you flip traffic to the deploy.
See peek-app-manifest-and-deploy §3 for the canonical var table and the first-time-deploy
checklist; this step makes sure the actual set for the app you just built reaches the user.
Hard rules (do not violate)
- Never build your own login for the embedded surface. Identity comes from Peek via the
peek-auth token. See
peek-embed-and-auth. (A separate developer/admin surface may have
its own auth.)
- In any Node/server-side code, reach the Peek Pro API only through
@peektravel/app-utilities
(PeekAccessService) — never a raw HTTP/GraphQL call, and never hand-write GraphQL. See
peek-backoffice-api.
- Expose the app's key functionality as an MCP endpoint by default so the App Store AI
orchestrator can drive it without the UI. At first build, raise it explicitly and recommend a
concrete tool list (don't build or skip it silently); reuse the same auth as the UI; curate
with the user (reads by default, gate writes); flag stack risks that could break it (Node vs
Edge runtime, streaming vs serverless limits, stateless sessions). See
peek-mcp-endpoint. Skip
only if the user says the app shouldn't be AI-addressable. When you later add a feature, keep
the MCP tools in sync (also in AGENTS.md).
- Treat Peek data as sensitive PII. Security-first storage/logging/transit; no PII or
tokens in logs.
- Scope persisted data to an
installDataId if/when you add a database (the install ID is
stable across reinstalls). See peek-backoffice-api.
- Don't invent Peek endpoint/schema/event details. Resolve them from the installed
@peektravel/app-utilities package (types in dist/index.d.ts + docs/); if a fact isn't
there, mark TODO(verify), check the live doc, and/or ask the user — never guess.
- Plan the data flow, not just the UI — and verify each field actually exists before
building. An app built on absent data won't work.
- Ship with tests. Keep the Vitest suite green and meaningful (see
testing-peek-apps).
- End every build with the production env-var checklist. List the exact vars this app needs
(base four + anything the build added), flag secret vs config, and tell the user to set them in
the host before deploying. Register any new var in
lib/env.ts. See "Before deploy" above.
- Never run/validate the app with
next dev or a generic emulator. It needs the Peek
framework (iframe host + parent-frame token + App Store registration). To see it actually run,
(local tunnel registered with the App
Store) — you can't run the real embed yourself. See "Running the app" above.
Artifacts in this folder
plan-template.md — the structure for the step-3 plan. Copy it into the user's project (e.g.
PLAN.md) and fill it in.
Related skills
peek-embed-and-auth · peek-backoffice-api · peek-webhooks · peek-mcp-endpoint ·
odyssey-ui · peek-app-manifest-and-deploy · testing-peek-apps
