The self-configuring advisor, in homezero.

cd ~/Projects/Zero/homezero/.claude/worktrees/advisor-flue
mkdir -p flue && cd flue
npm init -y && npm pkg set type=module
npm i @flue/runtime valibot agents hono
npm i -D @flue/cli wrangler vitest

Model on the spike's two registrations (app.ts:12-26) — a gw provider (workers-ai via the gateway) AND registerProvider('anthropic', { baseUrl: GW('anthropic'), apiKey: env.ANTHROPIC_API_KEY }) — plus the password route guard. Advisor returns { model:'anthropic/claude-opus-4-8', instructions:'You are the HomeZero advisor…' } for now (Task 8 makes it dynamic). Account id in GW() = 5a6fef07a998d84ec047ef43d0543342, gateway claudeflare-gateway.

// flue/wrangler.jsonc
{ "name": "homezero-flue", // NEVER "homezero"
  "compatibility_date": "2026-05-18",
  "compatibility_flags": ["nodejs_compat"],
  "ai": { "binding": "AI" },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["FlueRegistry", "FlueAdvisorAgent"] }] }
// Workspace binding name comes from Task 2's generator; route added in Task 12.

Put ANTHROPIC_API_KEY, GATEWAY_TOKEN, AUTH_PASSWORD in flue/.dev.vars; set them as Worker secrets with wrangler secret put.

npx flue build --target cloudflare
npx wrangler deploy --config dist/*/wrangler.json

git add flue && git commit -m "feat(flue): advisor Worker scaffold — homezero-flue, opus, gateway, gated"

cd flue && npx flue add sandbox cloudflare-shell

# NOTE: @flue/runtime types are .d.mts, not .d.ts
grep -rn "defineTool\|createAgent\|ToolDefinition" node_modules/@flue/runtime/dist/*.d.mts | head
grep -rni "readFile\|writeFile\|FlueFs\|AgentCreateContext" node_modules/@flue/runtime/dist/*.d.mts | head -30

git add flue/flue.config.ts flue/src/cloudflare.ts flue/wrangler.jsonc
git commit -m "chore(flue): add cloudflare-shell Workspace; pin tool/workspace API"

A Worker can't shell out npx convex run (the cells idiom). Confirmed path (the Convex CLI's own run.js does exactly this): ConvexHttpClient from convex/browser (Worker-safe, no Node deps) → client.setAdminAuth(CONVEX_DEPLOY_KEY) → client.mutation(makeFunctionReference('team:setAdvisorStep'), args). Pin the exact setAdminAuth + function-reference signatures against the installed convex package.

Implement callConvex. Prove it by calling an existing internalQuery that needs no setup — e.g. cellRegistry:list (public) or intakes:getById with a known id — from a temporary /debug/convex route, gated by the password.

git add flue/src/advisor/convexClient.ts flue/src/app.ts
git commit -m "feat(flue): Worker→Convex admin client (deploy-key internal calls)"

Follow the verbatim idiom from board.test.ts:1-7: convexTest(schema, modules), seed an advisor row via t.run((ctx)=>ctx.db.insert('teamMembers',{userId:'user_1',role:'advisor',label:'Your advisor',status:'birthing',order:0,createdAt:0,updatedAt:0})), call t.mutation(internal.team.setAdvisorStep,{userId:'user_1',step:'authoring'}), assert the row's step==='authoring' via t.run. Add a rejection test for an unknown step.

Add advisorStep to validators.ts (with a prose comment, house style). Import it in schema.ts (imports block lines 3-24) and add step: v.optional(advisorStep) to the teamMembers table. Implement setAdvisorStep in team.ts: find the by_user_role row (userId, 'advisor'); ctx.db.patch(row._id,{ step, updatedAt: Date.now() }).

git add convex/validators.ts convex/schema.ts convex/team.ts convex/team.test.ts
git commit -m "feat(convex): advisorStep ladder field + setAdvisorStep on teamMembers"

In the edge-safe awakening test, assert stepCopy('studying_market') contains "market" and the 5 steps each map to a distinct non-empty line. Keep lib/awakening.ts free of Convex imports (file header constraint).

Add stepCopy + a stepIndex (0-4 for a progress affordance). Extend RosterMember with step?. In home/page.tsx, when the advisor row has a step and status is pre-born, render stepCopy(step) in the awakening hero (page.tsx:180-218) and/or the roster strip subtitle (page.tsx:166-176). Reuse the existing reactive useQuery(api.team.getForUser, …) — no new query.

git add lib/awakening.ts lib/awakening.test.ts app/\(app\)/home/page.tsx app/\(app\)/shared.tsx
git commit -m "feat(web): render the granular advisor step ladder on /home"

If P1 added a new convex module, add "./<file>.ts": () => import("./<file>") to testModules.ts (convex-test won't load it otherwise). Run the whole suite.

git add convex/testModules.ts && git commit -m "test(convex): register modules; full suite green" --allow-empty

Assert setStep records the last step per userId and markBorn records (intakeId, advisorCell). (Same pattern as the spike plan's store test.)

MemoryStore = Maps. ConvexStore.setStep → callConvex('team:setAdvisorStep',{userId,step}); ConvexStore.markBorn → callConvex('intakes:markBorn',{intakeId,advisorCell}). getStore() returns ConvexStore in the Worker, MemoryStore in tests.

git add flue/src/advisor/store.ts flue/src/advisor/convexStore.ts flue/test/store.test.ts
git commit -m "feat(flue): AdvisorStore seam — MemoryStore + ConvexStore(setStep, markBorn)"

set_step('authoring') records to MemoryStore; set_step('banana') rejects. isConfigured flips false→true after writeIdentity (FakeWorkspace, Map-backed, matching Task-2 shape).

Validate step against the exact 5 literals; bind userId via closure (model never supplies it). isConfigured = IDENTITY.md exists & .trim().length>0.

git add flue/src/advisor/tools.ts flue/src/advisor/identity.ts flue/test
git commit -m "feat(flue): set_step + finish_birth tools, IDENTITY.md helpers"

FIRST_RUN_INSTRUCTIONS: "You are Zero, this household's HomeZero advisor, being born. The message carries the onboarding answers (place + person) and the resolved market. Call check_identity first to confirm you're unconfigured. Then, in order, calling the named tools: (1) set_step('waking'); (2) set_step('studying_market'), reflect on the resolved market; (3) set_step('authoring'), write IDENTITY.md via the workspace tool — your understanding of THIS user from their answers (who they are, what they want, their constraints). Your name is Zero and your yearnings ship in yearnings.md — do NOT invent either; (4) set_step('scouting'); (5) set_step('ready'); (6) finish_birth, then greet them in one warm line as Zero." CONFIGURED_INSTRUCTIONS(identityMd): "You are Zero, this household's advisor. Your understanding of them: «identity». Warm, concise 1-3 sentences. No tools unless asked."

Context is only { id, env, payload } — no Workspace. Branch on whether ctx.payload looks like a birth payload (carries intakeId) vs ordinary chat; always expose the tools incl. check_identity:

export default createAgent(async ({ id, payload }) => {
  const userId = id, store = getStore()
  const intakeId = payload?.intakeId            // present only on the birth POST
  return {
    model: 'anthropic/claude-opus-4-8',
    tools: [checkIdentityTool(userId), ...makeAdvisorTools(store, { userId, intakeId })],
    instructions: intakeId ? FIRST_RUN_INSTRUCTIONS : CONFIGURED_INSTRUCTIONS_LAZY,
  }
})

check_identity reads IDENTITY.md from the session FlueFs and tells the model whether it's already configured — so a stray birth payload can't re-author over an existing identity. CONFIGURED_INSTRUCTIONS_LAZY tells the model to call check_identity first and adopt the returned identity. (Pin the init-tool's FlueFs access against Task 2's NOTES.)

npx flue build --target cloudflare && npx wrangler deploy --config dist/*/wrangler.json
U=user_smoke_$(date +%s)
curl -s -X POST https://homezero-flue.<sub>.workers.dev/agents/advisor/$U \
  -H "Authorization: Bearer $AUTH_PASSWORD" -H 'content-type: application/json' \
  -d '{"message":"{\"name\":\"Pat\",\"where\":\"Paonia, CO 81428\",\"answers\":{\"context\":[{\"label\":\"frugal\"},{\"label\":\"workshop\"}]},\"market\":{\"marketCell\":\"zero-delta-co-market\",\"county\":\"delta-co\",\"coverage\":\"covered\"}}"}'

git add flue/src/advisor/prompts.ts flue/src/agents/advisor.ts
git commit -m "feat(flue): self-config first-run — authors IDENTITY.md, walks ladder, finish_birth"

POST a normal question to the same $U ("what should I watch on utility costs?").

POST onboarding answers to a brand-new $U2; confirm full first-run (per-instance isolation).

git add flue/src/app.ts && git commit -m "feat(flue): dev chat surface + verify configured branch"

Copy zeroCreated (doorbell.ts:317-350): read process.env.ADVISOR_WORKER_URL + AUTH_PASSWORD; skip-log if unset; load the intake via internal.intakes.getById; POST the payload to {ADVISOR_WORKER_URL}/agents/advisor/{userId}. The Worker's first-run consumes it.

At intakes.ts, move the advisor wake INTO the covered-market block (the same guard as the roster seed at :105) and schedule ringAdvisor instead of ringDoorbell: ctx.scheduler.runAfter(0, internal.doorbell.ringAdvisor, { intakeId }). Out-of-bounds/coverable → no birth (waitlist). For admin.ts:325 (the manual/synthetic-birth ring, gated on args.ring !== false, NOT coverage) just swap ringDoorbell → ringAdvisor and KEEP its args.ring guard — don't impose coverage there. Delete the old ringDoorbell internalAction once both callers are repointed.

First fix the breakage: intakes.test.ts:58-62 currently asserts a scheduled job whose name includes 'ringDoorbell' with args [{intakeId}] — change 'ringDoorbell'→'ringAdvisor' and confirm the scheduled count stays 2 (ringAdvisor + setRoster) for a covered market. Then add: vi.stubGlobal('fetch', vi.fn(...)); covered where → Worker URL POSTed with the resolved market; out-of-bounds where → NO ringAdvisor scheduled, NO POST.

git add convex/doorbell.ts convex/intakes.ts convex/admin.ts convex/intakes.test.ts
git commit -m "feat(convex): ringAdvisor — direct POST to the Flue Worker, gated to covered markets"

Add a route to flue/wrangler.jsonc (a custom domain like advisor.homezero.md, distinct from the homezero Worker's www/apex/delta). Set ADVISOR_WORKER_URL + AUTH_PASSWORD on the Convex deployment (npx convex env set).

The direct POST surfaces its own success/failure, so the bridge-era delivery bookkeeping is obsolete: ringDoorbell + DOORBELL_RETRY_BACKOFF_MS, and — if no operator wants delivery-health — markDoorbellResult + intakes.doorbell field + doorbellRecord/doorbellState. Nothing in app/ reads them. KEEP the unrelated doorbells (ringTeardown, marketEvent, zeroCreated).

git add flue/wrangler.jsonc convex/doorbell.ts
git commit -m "chore: advisor route + env; retire ringDoorbell retry machinery"

Mint U=user_smoke_$(date +%s). Seed an advisor roster row for U via convex run team:setRoster (covered market). POST the onboarding payload to the Worker. Poll team:getForUser (via convex run) until the advisor row's step==='ready' AND status==='born' (timeout 120s). Assert buyers.advisorCell got set (markBorn). POST a follow-up; assert a non-empty persona reply.

bash flue/scripts/smoke.sh

git add flue/scripts/smoke.sh && git commit -m "test: end-to-end advisor birth smoke"