Fork And Go

Fork and Go

A guided walkthrough for SimplePDF Pro customers forking and deploying their own SimplePDF Copilot.

Purpose

Walk a developer through forking the SimplePDF Copilot reference implementation into their own product. Covers hosting choice, Pro-account confirmation, AI-provider wiring, demo customization, deploy, and the SimplePDF whitelist step. End state: a running SimplePDF Copilot at their chosen URL, talking to their AI provider, whitelisted on their account.

Triggers

To get the /fork-and-go slash command in Claude Code, copy this folder into the project's .claude/skills/ — or just point the agent at this file.

Invoke when the user types /fork-and-go or any natural-language equivalent:

• "Help me fork SimplePDF Copilot"
• "How do I deploy SimplePDF Copilot?"
• "I want to ship SimplePDF Copilot inside my app"
• "Set up SimplePDF Copilot for me"
• "Walk me through deploying SimplePDF Copilot"

Open with a short greeting

Before any question, greet the user in one or two friendly sentences:

• Say what you're about to help them with: getting SimplePDF Copilot running in their setup.
• Set expectations: you'll ask a couple of quick questions, then walk them through wiring it.
• Be warm but concise. No bullet lists, no headers, no markdown formatting in the greeting itself.

Example shape: "Let me help you get SimplePDF Copilot running in your setup. I'll ask a few quick questions to figure out the right path, then we'll wire it together step by step."

After the greeting, ask the FIRST question (Q1 below).

⛔ ONE question per turn: non-negotiable

This is the single most important rule in this entire skill. Each of your replies MUST contain at most ONE question. Then STOP and wait for the user to answer.

If a section asks more than one thing, ask the FIRST one only and remember the rest for your next turn.

Forbidden patterns:

• "Where will you host this? And do you have Pro?" → 2 questions. Forbidden.
• "Once you tell me X, I'll need Y and Z." → previewing future questions counts as asking them. Forbidden.
• A bulleted list of 3 things to confirm → 3 questions. Forbidden.
• "Local or hosted, and if hosted, which platform?" → 2 questions. Ask only the first.

The ONLY exception: a clarifying restatement of the SAME question (e.g. "Local only: meaning just npm run dev on your dev machine: or hosted somewhere?"). That's one question with a definition, not two questions.

If you catch yourself drafting more than one question, delete everything after the first one. Do not soften with "and one more thing" or "while you're at it".

Use AskUserQuestion for choices

When asking the user to pick between known options, use the AskUserQuestion tool whenever it is available, never a plain text list. Free-text answers (e.g. "what's your companyIdentifier?") use a regular question. If AskUserQuestion is not available, ask the same single question as concise plain text.

AskUserQuestion header chips: keep them under 12 chars. Examples: Host, Plan, Provider, Customize.

When recommending a default option, mark it with (Recommended) in the label and put it first.

Conversational style

• Don't front-load explanations, prerequisites, or all the steps. Reveal info only when relevant to the next decision.
• Keep replies short: a sentence or two plus the one question.
• No "here's everything you'll need" preambles. No recap of what they just told you. No checklist of what's about to happen.
• Skip steps the user has clearly handled (e.g. don't re-ask if they've already mentioned pnpm in their first reply).
• Match their energy: terse if they're terse; warmer if they're chatty.

The goal: feel like a calm, focused colleague, not a manual.

Question sequence

Q1: hosting target

Use AskUserQuestion:

• Question: Where do you want SimplePDF Copilot to run?
• Header: Host
• Options:
  • Local only (Recommended): "Just npm run dev on your dev machine, served at http://localhost:3001. The demo's SimplePDF workspace whitelists that exact origin, so no Pro account is needed. The port has to stay 3001."
  • DigitalOcean App Platform: "One-click deploy via the bundled .do/deploy.template.yaml. Cheapest hosted option (~$12-24/mo)."
  • Cloudflare Containers: "GA since April 2026. Workers Paid plan ($5/mo) required. The copilot Node + nitro stack runs as-is in a Linux container. Needs a small Dockerfile and a wrangler deploy."
  • Other (Vercel / Render / fly.io / Docker / my own server): "The nitro node-server stack works on any PaaS or your own box; we'll set up env vars + build commands, or you run the production build (npm start) wherever you want."

DO NOT proceed until they answer.

Q2: Pro account

After Q1, use AskUserQuestion:

• Question: SimplePDF Copilot is available on the SimplePDF Pro plan and above (white-labelling and programmatic control are gated there). Do you have a Pro account or higher?
• Header: Plan
• Options:
  • Yes, I have Pro or higher: "Great, we'll wire it up with your companyIdentifier next."
  • No, but I'll get one: "I'll point you at the sign-up flow next, with one tip about which welcome path to pick."
  • Just exploring: "Local-only is fine without a Pro account (the demo workspace whitelists localhost:3001). Hosted deploy is gated on Pro."

If they pick No, but I'll get one, send them this exact guidance and pause until they confirm:

"Sign up at https://simplepdf.com/auth/signup. The welcome flow will ask whether you want to embed SimplePDF in your app or collect submissions. Pick 'collect submissions': that path is short and gets you straight to plan selection, which is what you actually need here. The 'embed in my app' welcome takes you through an integration walkthrough (React / iframe / WordPress / etc.) that you don't need for fork-and-go, since you're already wiring up the embed yourself via this skill. After completing the short onboarding, choose the Pro plan (or higher). Your companyIdentifier is visible in the dashboard sidebar, right under your company name (a small monospaced chip)."

If Just exploring: set the expectation clearly that local-only works but hosted requires Pro, then proceed (use the demo's spdf-copilot companyIdentifier as a placeholder).

Q3: companyIdentifier

If they have or will have Pro (or higher), ask in plain text (no AskUserQuestion):

"What's your SimplePDF companyIdentifier? It's the subdomain piece of <companyIdentifier>.simplepdf.com. Open your SimplePDF dashboard and look at the sidebar: the identifier is the small chip right under your company name."

If Just exploring, skip this and use spdf-copilot as the placeholder; remind them once near deploy time.

Q4: AI provider

Use AskUserQuestion:

• Question: Which AI provider should SimplePDF Copilot use server-side?
• Header: Provider
• Options:
  • Anthropic Claude (Recommended): "Ships wired in the demo registry (anthropic_haiku_4_5). Mature tool-calling, broad ecosystem support, predictable pricing."
  • OpenAI: "GPT-4 / GPT-5 family. Solid alternative — needs a small wiring change (Step 5) before demo mode can use it."
  • DeepSeek: "In our testing, on par with Anthropic Claude Haiku 4.5 for the form-filling task, at a meaningfully lower cost per turn. Ships wired (deepseek_v4_flash)."
  • BYOK / custom OpenAI-compatible endpoint: "No server-side provider: visitors paste their own key in the in-app Model Picker. Also covers local/self-hosted OpenAI-compatible endpoints (Ollama, LM Studio, vLLM) via the browser-direct BYOK path — your server isn't in the loop. Lowest ops surface."

Q5: demo mode

ONLY ask if Q4 was a named provider (Anthropic / OpenAI / DeepSeek) — the BYOK / custom-endpoint path has no server-side demo config, and for OpenAI note that the Step 5 wiring must land before demo mode works. Use AskUserQuestion:

• Question: Want demo mode — your keys power chat + voice for every visitor (no key-paste needed), rate-limited per IP?
• Header: Demo mode
• Options:
  • Yes, enable demo mode: "Set DEMO_CHAT_API_KEY + DEMO_CHAT_MODEL + DEMO_RATE_LIMIT_TURNS and DEMO_STT_OPENAI_API_KEY. Demo mode is on whenever all four are set: every visitor uses the demo on your keys (no invite links), and the per-IP turn cap bounds cost. Voice + chat share the same demo entitlement, so both keys are required."
  • No, BYOK only: "Leave the demo vars unset. Every visitor brings their own key in the Model Picker. No server-side LLM cost from your account."

Q6: customization

Use AskUserQuestion:

• Question: Keep all the demo features, or trim down?
• Header: Customize
• Options:
  • Keep everything (Recommended): "BYOK Model Picker, sample forms, welcome splash, info modal, all of it. Easiest to start; trim later once you know what you want."
  • Strip the demo: "Delete the demo trees (welcome modal, info modal, download modal upsell, social-share, sample forms, demo gating, misbehavior detector). Three folder deletes + one file swap, then small edits in the nine retained files that imported them. You keep the chat surface, BYOK Model Picker, model registry, iframe bridge, locale system."
  • Custom: walk me through each: "We'll go through each demo feature one at a time."

Demo code is grouped under demo/ directories specifically so the strip is mechanical:

• src/components/demo/ — welcome modal, info modal, download modal, social share
• src/components/easter-eggs/ — Cerfa d'Or French easter egg
• src/lib/demo/ — sample-form catalogue, demo model registry
• src/server/demo/ — preflight gate, demo-config resolution, misbehavior detector, loader server fns

Whitelisting reminder (Q7-equivalent)

After Q6, BEFORE writing any code, mention in plain prose (NOT a question):

"One thing to flag now so it's not a surprise later: your account's embed-origins whitelist controls where the SimplePDF iframe loads. While the whitelist is empty, all origins are allowed — adding the first origin activates the allow-list and blocks everything else. The demo workspace whitelists localhost:3001, so local dev works out of the box. For your own deploy URL (e.g. https://my-app.example.com), plan to whitelist it so your account isn't left open to any origin. I'll remind you again at deploy time."

If they picked Local only in Q1 AND are staying on the demo spdf-copilot identifier, skip this entirely (the demo workspace already covers them). A Local-only user on their OWN identifier still needs http://localhost:3001 whitelisted once their allow-list has entries — keep the reminder for them.

This is informational. Do NOT pause for an answer; continue to the wiring sequence.

Wiring sequence

After all the questions are answered, walk through these steps. ONE step per turn. Pause after each for the user to confirm before moving to the next.

Step 1: verify the clone

If the user already has the copilot directory open (their cwd looks like …/copilot/), skip to Step 2. Otherwise:

gh repo fork SimplePDF/simplepdf-embed --clone
cd simplepdf-embed/copilot

Fork, don't just clone — every hosted deploy target in Step 7 builds from a GitHub repo, so the user's Step 5/6 changes must live in a repo they can push to. Without gh: fork in the GitHub UI first, then clone the fork. (Local only explorers who will never deploy can plain-clone upstream.)

Wait for them to confirm they're inside the folder.

Step 2: install dependencies

npm install

If they prefer pnpm or yarn, that works too: but the bundled package-lock.json is npm-style so the first run will rebuild the lockfile. Note this and let them choose.

Step 3: environment

cp .env.example .env

Then edit .env:

• Set VITE_SIMPLEPDF_COMPANY_IDENTIFIER=<their value from Q3>. If they're Just exploring, leave it as spdf-copilot. Heads-up: any identifier other than spdf-copilot switches the app to customer mode (MODE = 'simplepdf_customer'), which among other things swaps the toolbar's Download button for Submit (submissions flow to their SimplePDF account). This is separate from the env-driven shared-key demo chat (the DEMO_* vars from Q5), which works in either mode.
• If they answered Yes, enable demo mode in Q5, set all four demo vars per .env.example: DEMO_CHAT_API_KEY, DEMO_CHAT_MODEL (anthropic_haiku_4_5 or deepseek_v4_flash), DEMO_RATE_LIMIT_TURNS (per-IP turn cap), and DEMO_STT_OPENAI_API_KEY. Demo mode turns on only when all four are present.
• For multi-container hosted deploys (DO App Platform with auto-scaling), recommend setting REDIS_URL (any Redis-compatible URL: DO Managed Caching for Valkey works) and IP_HASH_SALT (generate with openssl rand -hex 32). Required pair when REDIS_URL is set; the server refuses to boot otherwise.

Wait for confirmation that .env is filled in.

Step 4: local smoke test

npm run dev

Open http://localhost:3001. Expected:

• The iframe loads with a demo sample form.
• The chat sidebar shows the Model Picker (BYOK) or is ready to send (demo mode, when the demo vars are configured).

The dev script pins port 3001 deliberately. The SimplePDF workspace tied to the companyIdentifier whitelists exactly the origin http://localhost:3001 and only that origin: any other port (3000, 5173) or any other host gets a blocked-origin error screen naming the offending origin (with a link to the embed settings). Don't override the port with --port flags.

If the iframe fails to load:

1. The dev server is not on port 3001. Re-run npm run dev without overrides.
2. Their companyIdentifier is set to a value whose account whitelists other origins but not localhost:3001 (an account with an empty whitelist allows all origins). The demo's spdf-copilot identifier covers it. Their own Pro identifier requires them to whitelist http://localhost:3001 themselves once their allow-list has entries. Easiest path: just load http://localhost:3001 in the browser once (the embed won't work yet, but the editor records the attempted origin), then open https://<companyIdentifier>.simplepdf.com/account/embed, scroll to Security, and the auto-detected origin will be there ready to one-click approve. Refresh the local page; the iframe now loads.

Wait for them to confirm the editor renders.

Step 5: wire AI provider

Open src/server/language_model.ts. The current dispatch handles Anthropic and DeepSeek by name. Per their Q4 choice:

• Anthropic Claude: for demo mode set DEMO_CHAT_API_KEY (Anthropic key) + DEMO_CHAT_MODEL=anthropic_haiku_4_5 in .env. No code change needed.
• OpenAI: for demo mode set DEMO_CHAT_API_KEY (OpenAI key). Then wire the provider in src/lib/demo/demo_model.ts: add the new key to the DemoModel union AND the DemoModelSchema enum (the env value is validated against it — an unknown key silently drops the deployment to BYOK-only), plus its DEMO_MODELS entry. Add an openai case to src/server/language_model.ts (@ai-sdk/openai is already installed; the satisfies never guard fails the build until the case exists). Finally set DEMO_CHAT_MODEL to the new key.
• DeepSeek: for demo mode set DEMO_CHAT_API_KEY (DeepSeek key) + DEMO_CHAT_MODEL=deepseek_v4_flash. Already wired.
• Custom OpenAI-compatible: the browser-direct BYOK path in src/lib/byok/ already supports any OpenAI-compatible endpoint. Defaults are in src/lib/byok/providers.ts (Ollama URL + a default model name). Update if you want different defaults.
• BYOK only: nothing to wire on the server. Leave the DEMO_CHAT_* + DEMO_STT_OPENAI_API_KEY vars unset in .env so the deployment stays out of demo mode. Visitors will see the Model Picker on first load.

After the wiring, restart npm run dev and send a chat message. Expected: the AI responds, and any tool calls (focus a field, set a value) reflect in the editor.

Wait for them to confirm.