Skip to content

Sandbox QA — AI hub creation (house guide) ​

Runbook for Workers AI draft house guide generation on a disposable sandbox hub (recommended: test-sandbox2).

Platform stack setup: sandbox-hub-quickstart.md. Per-hub deploy scripts: ops-sandbox-scripts.md.

Prerequisites ​

  • A sandbox hub with Workers AI bound (AI in hub Worker wrangler config).
  • Hub Worker deployed for that site (feature branch or main).
  • Dashboard (hub Pages) deployed so Owner Mode → Hub setup wizard is available.
  • Owner login on the hub (Cloudflare Access email code or test Access JWT in dev).
  • House guide not yet imported (AI path is blocked once D1 guide content exists).

Enable AI guide creation (hub Worker) ​

On customer hub Workers (HUB_ENVIRONMENT set in [env.{site-id}.vars]), AI guide creation is on by default when the Worker has a Workers AI binding ([env.{site-id}.ai] with binding = "AI"). In production, the wizard only offers AI generation on Lovely Home+ (paid) hubs — free plans hide the AI button and the API returns 403 PLAN_UPGRADE_REQUIRED / status unavailableReason: plan_free. Plus (and account-included plus on multi-home) may generate up to 8 categories per run.

Opt out: set HUB_AI_CREATION_ENABLED to false, 0, or no on that hub Worker.

Legacy top-level hub Worker (no HUB_ENVIRONMENT) stays off unless you set HUB_AI_CREATION_ENABLED=true explicitly.

Wrangler 4 has no vars put CLI. Use wrangler.toml (recommended) or the Cloudflare dashboard.

Sandbox explicit flag (optional):

toml
[env.test-sandbox2.vars]
HUB_AI_CREATION_ENABLED = "true"

Then redeploy:

bash
cd worker
npm run deploy:test-sandbox2
# or: npx wrangler deploy --env test-sandbox2

Dashboard: Workers & Pages → lovely-home-hub-api-{site-id} → Settings → Variables → add or change HUB_AI_CREATION_ENABLED → deploy a new version if prompted.

Confirm bindings include [env.{site-id}.ai] (binding = "AI"). Customer envs such as multi and erin need this block if it was missing — redeploy the hub Worker after adding it.

Wrangler vs dashboard: wrangler deploy replaces the remote Worker config with your local wrangler.toml. Dashboard-only variables or bindings disappear on the next deploy unless they are also in git. Pull latest main (includes [env.multi.ai] and customer HUB_AI_CREATION_ENABLED vars) before deploying production hub envs.

Deploy feature branch to sandbox ​

Hub Worker (API + AI) ​

bash
cd worker
npm run deploy:test-sandbox2

Hub dashboard (Pages — Hub setup UI) ​

From repo root (OAuth — unset API token):

bash
unset CLOUDFLARE_API_TOKEN
bash scripts/deploy-cloudflare-pages-site.sh test-sandbox2

This builds and deploys home-dashboard-test-sandbox2 from your current branch. This deploy is required for AI hub creation QA in the wizard.

Marketing / platform sandbox (optional) ​

bash
bash scripts/deploy-sandbox-lovely-home.sh

On a feature branch, the script may stop at platform admin with:

Refusing to deploy: your registry does not match origin/main — worker/wrangler.toml

That guard prevents stale registry/manifest from resurrecting torn-down hubs. Your branch legitimately differs from main (sandbox AI vars). You do not need platform-sandbox deploy to test AI on test-sandbox2.

If you still need platform-sandbox from this branch:

bash
PLATFORM_DEPLOY_ALLOW_STALE=1 bash scripts/deploy-platform-admin.sh

Use only when you accept manifest/registry being rebuilt from this checkout (sandbox platform admin only).

Manual UI test (preferred) ​

  1. Open the hub dashboard, e.g. https://test-sandbox2.lovely-hub.com/.
  2. Sign in as owner and switch to Owner Mode.
  3. Open Hub setup (first-run wizard or Settings → re-run setup).
  4. Complete steps through Guest access (property context helps the prompt).
  5. On House Guide (Step 6):
    • Confirm Generate a draft with AI appears on a plus hub (hidden on free plan, when the flag is off, guide already seeded, or AI already used).
    • Fill structured intake (at least one field): access, Wi‑Fi, anything unusual, optional pets / sitter notes / guest types.
    • Click Generate draft guide, or use Import starter guide.
  6. Open Guide Editor → verify draft topics (unpublished). Guests should not see guide categories until you publish.

Reset the same hub for another AI run ​

You do not need a new sandbox site for each test. Clear guide D1 + the one-time AI flag on test-sandbox2:

bash
node scripts/reset-hub-guide-ai-qa.mjs test-sandbox2

Optional: reopen the first-run wizard (clears onboardingComplete):

bash
node scripts/reset-hub-guide-ai-qa.mjs test-sandbox2 --reopen-wizard

Then hard refresh the hub → Hub setup → Step 6 → generate again.

In the UI (full factory reset): Settings → Utilities → Factory reset hub — wipes guide, secrets, stays, and profile (heavier than the script above).

Optional D1 checks ​

bash
cd worker
npx wrangler d1 execute lovely-home-appliance-manuals-test-sandbox2 --env test-sandbox2 \
  --command "SELECT published, has_draft FROM guide_topics LIMIT 5;"

Expect draft import: published = 0, has_draft = 1.

Site profile rate limit:

bash
npx wrangler d1 execute lovely-home-appliance-manuals-test-sandbox2 --env test-sandbox2 \
  --command "SELECT payload FROM site_profile WHERE id='default';"

Look for "aiHubGuideGeneratedAt":"…" after a successful run.

SymptomLikely cause
AI section hidden in wizardFree plan, flag off, guide already seeded, or aiHubGuideGeneratedAt already set
403 PLAN_UPGRADE_REQUIREDHub on free plan — upgrade to Lovely Home+ or use starter guide
403 FEATURE_DISABLEDFeature opted out (HUB_AI_CREATION_ENABLED false/0/no), legacy Worker without HUB_ENVIRONMENT, or hub env without Workers AI binding (default-on requires both HUB_ENVIRONMENT and env.AI.run)
503 AI_NOT_AVAILABLEHub Worker missing [env.{site}.ai] — redeploy after adding binding = "AI"
503 AI_UNAVAILABLEenv.AI.run failed (model/account) — check Worker Logs (wrangler tail); response may include error.detail
409 GUIDE_ALREADY_SEEDEDStarter guide or prior import exists — run reset script or use fresh sandbox
429 ALREADY_GENERATEDOne successful AI run already recorded on this hub
422 INVALID_AI_OUTPUTModel JSON failed validation (retry once server-side; try shorter bullets)
Draft visible in editor, empty for guestsExpected until publish