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 (
AIin 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):
[env.test-sandbox2.vars]
HUB_AI_CREATION_ENABLED = "true"Then redeploy:
cd worker
npm run deploy:test-sandbox2
# or: npx wrangler deploy --env test-sandbox2Dashboard: 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)
cd worker
npm run deploy:test-sandbox2Hub dashboard (Pages — Hub setup UI)
From repo root (OAuth — unset API token):
unset CLOUDFLARE_API_TOKEN
bash scripts/deploy-cloudflare-pages-site.sh test-sandbox2This 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 scripts/deploy-sandbox-lovely-home.shOn 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:
PLATFORM_DEPLOY_ALLOW_STALE=1 bash scripts/deploy-platform-admin.shUse only when you accept manifest/registry being rebuilt from this checkout (sandbox platform admin only).
Manual UI test (preferred)
- Open the hub dashboard, e.g.
https://test-sandbox2.lovely-hub.com/. - Sign in as owner and switch to Owner Mode.
- Open Hub setup (first-run wizard or Settings → re-run setup).
- Complete steps through Guest access (property context helps the prompt).
- 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.
- 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:
node scripts/reset-hub-guide-ai-qa.mjs test-sandbox2Optional: reopen the first-run wizard (clears onboardingComplete):
node scripts/reset-hub-guide-ai-qa.mjs test-sandbox2 --reopen-wizardThen 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
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:
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.
Troubleshooting (503 and related)
| Symptom | Likely cause |
|---|---|
| AI section hidden in wizard | Free plan, flag off, guide already seeded, or aiHubGuideGeneratedAt already set |
403 PLAN_UPGRADE_REQUIRED | Hub on free plan — upgrade to Lovely Home+ or use starter guide |
403 FEATURE_DISABLED | Feature 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_AVAILABLE | Hub Worker missing [env.{site}.ai] — redeploy after adding binding = "AI" |
503 AI_UNAVAILABLE | env.AI.run failed (model/account) — check Worker Logs (wrangler tail); response may include error.detail |
409 GUIDE_ALREADY_SEEDED | Starter guide or prior import exists — run reset script or use fresh sandbox |
429 ALREADY_GENERATED | One successful AI run already recorded on this hub |
422 INVALID_AI_OUTPUT | Model JSON failed validation (retry once server-side; try shorter bullets) |
| Draft visible in editor, empty for guests | Expected until publish |
Related docs
- house-guide-cms.md
- ops-sandbox-scripts.md —
reset-hub-guide-ai-qa.mjs