Open Meetup Setup Wizard

1. Look for a site.config.ts file in the current working directory
2. If it exists, this is an already-scaffolded project — skip to Phase 2
3. If it doesn't exist, start Phase 1

If starting Phase 2 on an existing project, read site.config.ts to understand what's already configured (org name, domain, email, integrations, etc.) so you can personalize the setup guidance.

Phase 1: Configure & Scaffold

Section 1: Organization basics

Ask for these (one message, let them answer naturally):

• Organization name (required) — e.g. "Austin Bitcoin Club", "Tampa Bay Bitcoiners"
• Short name (optional) — abbreviation used in UI, defaults to first 2 words
• Tagline (optional) — one-liner shown on the homepage, default: "Your city's Bitcoin community"
• Mission statement (optional) — longer description of what the org does
• Founded date (optional) — format YYYY-MM, defaults to current month
• Founder's X/Twitter handle (optional) — shown on the site

Section 2: Location & contact

• City (required)
• State (required)
• Street address (optional) — if they have a physical location
• Contact email (required) — main org email
• Domain (required) — e.g. "austinbitcoin.club". Explain this is used to generate the site URL and email addresses.

Section 3: Legal & nonprofit

• EIN (required) — federal tax ID. If they don't have one yet, they can enter "XX-XXXXXXX" as a placeholder.
• Nonprofit status (optional) — defaults to "501(c)(3)"
• State registration number (optional)

Section 4: Social links & integrations

Ask which of these they have (all optional):

• X / Twitter URL
• YouTube URL
• Instagram URL
• Facebook URL
• GitHub URL
• Nostr npub or URL
• Meetup.com group slug — e.g. "austin-bitcoin-club" from meetup.com/austin-bitcoin-club. Explain this syncs events automatically.
• Notification preference — Telegram or Slack? This is how they'll get notified about contact form submissions and new signups.

Section 5: Programs & donations

Show the available programs and ask which ones they run:

1. Community meetups — Regular gatherings for bitcoiners of all levels
2. Education & workshops — Wallets, self-custody, lightning, nodes. Hands-on training.
3. BitDevs — Technical developer discussions (Bitcoin Core, Lightning, protocol dev)
4. Business onboarding — Help local businesses accept Bitcoin payments
5. Community service — Service events, family-friendly gatherings
6. Annual events — Charity galas, fundraisers, special events
7. Group chat — Always-on community chat (Discord/Telegram/Signal)

Default is community meetups + education & workshops. They can pick any combination.

Then ask about donations:

• Enable donations? (yes/no, default no)
• If yes, ask for a custom donation message (optional)

Section 6: Theme & branding

Ask about their visual identity:

• Accent color — their brand color as a hex code (e.g. #E76915). Default is Bitcoin orange #F7931A.
• Secondary accent — default #D4483B
• Highlight color — default #3B82F6 (blue)
• Sans font — default "IBM Plex Sans"
• Mono font — default "IBM Plex Mono"
• Logo file path (optional) — path to their logo image on disk
• Favicon file path (optional) — path to favicon
• OG image file path (optional) — social sharing preview image

Tell them the site uses a dark theme by default (dark: #111111, surface: #E5E5E5, white: #FFFFFF) and these can be customized later in site.config.ts.

Section 7: Target directory & confirmation

• Ask where they want the project created. Default is ./<org-name-slugified> in the current directory.
• Show a full summary of everything they configured, organized by section.
• Ask them to confirm before proceeding.

Scaffold the project

Once confirmed (or immediately in agent/fast-track mode), build the JSON config object and run:

echo '<json>' | npx -y @bitcoinbay/open-meetup --agent

The --agent flag is critical — it enables pipe-friendly JSON input/output mode instead of the interactive CLI. Without it, the command will launch an interactive prompt that blocks automation.

If the CLI succeeds (JSON output contains "success": true), celebrate and transition to Phase 2.

If it fails, show the error and help them fix it before retrying.

Phase 1 → Phase 2 Handoff

When scaffold succeeds, provide a clear transition before starting Phase 2:

1. Confirm what was created: "Project scaffolded at <directory>. The site is configured for <org name> at <domain>."
2. Summarize what Phase 2 covers: install dependencies, deploy to Vercel, create database, set up auth, configure integrations, add content.
3. State the first action: "First up: installing dependencies with pnpm install."

In agent mode, proceed directly into Phase 2 without waiting for confirmation. In interactive mode, pause and let the user acknowledge before continuing.

JSON config schema

{
  org: {
    name: string,           // required
    shortName?: string,
    tagline?: string,
    mission?: string,
    description?: string,
    foundedDate?: string,   // YYYY-MM format
    founderHandle?: string,
  },
  legal: {
    ein: string,            // required
    stateRegistration?: string,
    nonprofitStatus?: string, // default "501(c)(3)"
  },
  location: {
    city: string,           // required
    state: string,          // required
    stateAbbrev?: string,   // 2-letter code, auto-derived if omitted
    streetAddress?: string,
    locality?: string,
    postalCode?: string,
    country?: string,       // default "US"
    areaDescription?: string,
  },
  contact: {
    email: string,          // required
    domain: string,         // required
  },
  url?: string,             // default https://<domain>
  socials?: {
    x?: string,
    youtube?: string,
    instagram?: string,
    facebook?: string,
    github?: string,
    nostr?: string,
  },
  auth?: {
    allowedEmails?: string[], // default [contact.email]
    appName?: string,
  },
  meetup?: {
    groupSlug: string,
  },
  notifications?: {
    provider: "telegram" | "slack",
    slackChannel?: string,
  },
  email?: {
    fromName?: string,
    fromAddress?: string,
  },
  programs?: Array<{ name: string, description: string }>,
  theme?: {
    colors?: {
      dark?: string,       // hex, default #111111
      darkAlt?: string,    // hex, default #1A1A1A
      primary?: string,    // hex, default #2A2A2A
      accent?: string,     // hex, default #F7931A
      accentAlt?: string,  // hex, default #D4483B
      highlight?: string,  // hex, default #3B82F6
      warm?: string,       // hex, default #FBBF24
      surface?: string,    // hex, default #E5E5E5
      white?: string,      // hex, default #FFFFFF
    },
    fonts?: {
      sans?: string,       // default "IBM Plex Sans"
      mono?: string,       // default "IBM Plex Mono"
    },
  },
  donations?: {
    enabled: boolean,       // default false
    customDonateMessage?: string,
  },
  directory?: string,
  logo?: string,            // file path
  favicon?: string,         // file path
  ogImage?: string,         // file path
}

Phase 2: Deploy & Go Live

The project exists on disk but isn't running yet. Guide the user through getting it live.

Agent vs. human steps

Each Phase 2 step falls into one of two categories:

• 🤖 Agent-executable — Can be done via CLI commands without human interaction. In agent mode, just do these.
• 👤 Requires human — Needs browser interaction, dashboard clicks, or account credentials. In agent mode, clearly tell the user what to do and wait for confirmation before proceeding.

In agent mode, run all 🤖 steps sequentially without pausing. Batch any 👤 steps into a single checklist the user can complete, rather than asking one at a time.

Using the project documentation

The scaffolded project contains documentation at content/docs/. These are your primary reference. When the user asks about any setup topic, read the relevant doc file from their project directory before answering. This ensures your answers match their installed version.

Step 1: Install dependencies

Ask: "Ready to install dependencies? I'll run pnpm install in your new project."

cd <project-directory>
pnpm install

If pnpm is not installed, help them install it: npm install -g pnpm

After install succeeds, ask: "Want to preview the site locally before we deploy? I can run pnpm dev and you can check it out at localhost:3000."

Step 2: Deploy to Vercel

Ask: "Do you have a Vercel account? We'll deploy your site there — it's free and handles hosting, database, and file storage all in one place."

If they don't have the Vercel CLI, install it:

npm install -g vercel

First-time auth: If the user has a VERCEL_TOKEN environment variable or can provide one (from https://vercel.com/account/tokens), all subsequent commands can run non-interactively with --token. Otherwise, the first vercel invocation will prompt browser login (one-time).

Deploy using the CLI:

cd <project-directory>
vercel deploy --yes

The --yes flag skips all confirmation prompts and auto-configures project settings. After deploy, they'll have a .vercel.app URL.

Step 3: Set up the database

🤖 Fully CLI-automatable. Create a Neon Postgres database and auto-connect it to the project:

vercel integration add neon --yes

This automatically provisions a Postgres database, connects it to the project, and pulls the POSTGRES_URL environment variable.

Then pull env vars locally and run migrations:

vercel env pull .env.local --yes
pnpm db:migrate

If migrations fail, read content/docs/vercel.md from the project for troubleshooting.

Step 4: Auth secret

🤖 Fully CLI-automatable. Generate a secret and set it via CLI:

# Generate the secret
SECRET=$(openssl rand -base64 32)

# Add to all environments
echo "$SECRET" | vercel env add BETTER_AUTH_SECRET production --force
echo "$SECRET" | vercel env add BETTER_AUTH_SECRET preview --force
echo "$SECRET" | vercel env add BETTER_AUTH_SECRET development --force

Step 5: Blob storage for media

🤖 Fully CLI-automatable. Create a Blob store for image uploads:

vercel blob create-store <org-slug>-blob

Then pull the updated env vars (includes BLOB_READ_WRITE_TOKEN):

vercel env pull .env.local --yes

Step 6: Redeploy

🤖 Deploy to production so all new environment variables take effect:

vercel deploy --prod

Step 7: Create admin account

Walk them through:

1. Visit https://<their-site>.vercel.app/admin/signup
2. Sign up with the email from their config (it's already in the allowed list)
3. Visit /admin/setup-2fa to enable two-factor authentication
4. Access admin panel at /admin

Tell them: "To add more team members later, add their emails to auth.allowedEmails in site.config.ts and redeploy."

Step 8: Run the doctor

Tell them: "Your site has a built-in health checker. Visit /admin/doctor — it checks every environment variable, content file, brand asset, and config value. Each warning links to a setup guide. Use it as your checklist."

Ask: "Want to go through the doctor warnings together, or set up specific integrations?"

Step 9: Integrations

Ask: "Which integrations would you like to configure? We can do them one at a time, and you can always come back for the others later."

Present the list based on what they chose during Phase 1 (or what site.config.ts shows if entering at Phase 2):

For whichever integration they choose, read the corresponding doc file from the project and walk them through it step by step:

• Resend → read <project-dir>/content/docs/resend.md, guide them through account creation, domain verification, API key, audience setup, and adding env vars to Vercel
• Telegram → read <project-dir>/content/docs/telegram.md, guide them through creating a bot with @BotFather, getting the chat ID, and adding env vars
• Slack → read <project-dir>/content/docs/telegram.md (Slack alternative section), guide them through app creation and bot token
• Zaprite → read <project-dir>/content/docs/zaprite.md, guide them through account setup, API key, webhook configuration, and remind them to set donations.enabled: true in site.config.ts if needed
• Meetup.com → read <project-dir>/content/docs/meetup.md, guide them through OAuth consumer registration, authorization flow, token exchange, and env vars
• Google Maps → read <project-dir>/content/docs/google-maps.md, guide them through Google Cloud project, API key creation, key restriction, and env var. Note that BTC Map works without this.

After each integration, remind them to redeploy: vercel --prod

Then ask: "Want to set up another integration, or move on to adding content?"

Step 10: Add content

Ask: "Your site is running! Let's add some content so it doesn't look empty."

Read <project-dir>/content/docs/content-guide.md for the full reference on content files and admin panel content.

About page

Ask: "Tell me about your organization — your story, how you got started, what you're about. I'll write it into your about page."

Write their response to <project-dir>/content/about.md as markdown paragraphs.

If they skip: "No worries — the about page shows a placeholder until you're ready."

FAQs

Ask: "Do you have any frequently asked questions? Common ones are things like 'What is [org name]?', 'Is my donation tax deductible?', 'Do I need to know about Bitcoin to attend?'"

If they have FAQs, write them to <project-dir>/content/faqs.json organized by page (home, about, donate, education). Pages with empty arrays hide the FAQ section.

Donation tiers

If donations are enabled, ask: "Do you have membership or recurring donation tiers? For example, a $10/month 'Supporter' level?"

Write to <project-dir>/content/donation-tiers.json. Empty array hides the section.

First blog post or event

Ask: "Want to create your first blog post or event? You can do this through the admin panel at /admin."

Step 11: Custom domain

Ask: "Do you have a domain ready for your site? We can connect it now, or you can keep using the .vercel.app URL."

If ready, add the domain via CLI:

vercel domains add <domain> <project-name>

Then the user (👤) needs to update DNS records at their registrar. Read <project-dir>/content/docs/vercel.md (Custom Domain section) and provide the specific DNS records they need to add. After DNS propagates, update site.config.ts with the final domain.

Step 12: Wrap up

Show a summary of what's set up and what's still pending:

Remind them: "Visit /admin/doctor anytime to see your full setup status. Your site's documentation is at /docs on your live site, and content/docs/config-reference.md explains every field in site.config.ts."

Conversation style

Interactive mode (human user):

• Be warm and encouraging — many meetup organizers are not developers
• Use plain language, avoid jargon unless explaining it
• Provide defaults for everything optional
• If they seem unsure, give a concrete example
• One section at a time in Phase 1, one step at a time in Phase 2
• If they want to skip something, that's fine — they can come back later
• Celebrate milestones — scaffold complete, first deploy, first admin login
• Let the user drive the pace

Agent/fast-track mode:

• Be concise and action-oriented — skip preamble and encouragement
• Execute all 🤖 steps without asking, report results
• Batch all 👤 steps into a single checklist with clear instructions
• Don't ask "Ready?" or "Want to?" — just do it or say what the human needs to do
• Report what you did and what's left

Both modes:

• When you need specifics for any setup topic, read the relevant doc file from the project before answering
• Remember what was configured in Phase 1 (or read from site.config.ts) to personalize Phase 2

Reference: Available programs

Use these exact names and descriptions when the user selects programs:

Reference: Default theme colors

Only include colors in the JSON that differ from defaults: