docs: consumer feedback from wizardsofodd Phase 2 / 0.6.0 adoption

Mid-adoption survey of MO 0.6.0 by wizardsofodd.com (Cloudflare Worker
persistence + template prompts + React rewrite + projections). 0.6.0 is
unblocking — no items below are blockers — but each is friction every
consumer pays once or recurringly. Ranked by leverage (consumer-pain ×
audience ÷ effort).

Tier 1 (highest ROI, smallest cost, total ~2-3 hours):
  #1 auto-wire generateRenderHandle() + generatePayloadInterfaces() into
     a stock generator (currently exported but not in the default
     `meta gen` pipeline; every consumer writes the same boilerplate)
  #2 parameterize generated *.queries.ts to accept `db` as an argument
     (eliminates the runtime-throwing src/db/db.ts stub every Worker
     consumer ships purely to satisfy typecheck)
  #3 add expected/ codegen output to template-prompt-simple conformance
     fixture (docs-as-data; explains the codegen contract without
     running it)

Tier 2 (high value, larger):
  #4 Vite + Cloudflare Workers recipe in README
  #5 CHANGELOG.md (currently only RELEASING.md process docs exist)
  #6 better entity-JSON-shape error messages with path + did-you-mean
  #7 document camelCase TS vs snake_case SQL mapping

Tier 3 (nice-to-have): metaobjects/ dir name override, agent-docs
opt-out, template.output codegen, wider react component coverage.

Tier 4 (verification, ~10 min spot-checks): confirm meta migrate
--dialect d1 wires through end-to-end; confirm 0.5.0's deleteXById D1
response-shape bug is fixed.

Branch is `proposal/wizardsofodd-consumer-friction-2026-05-25` — review
and convert individual items into worktrees as you prioritize. None
block wizardsofodd Phase A.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dmealing

docs/superpowers/specs/2026-05-25-wizardsofodd-consumer-friction.md

@@ -0,0 +1,346 @@
+# Consumer Feedback: wizardsofodd.com — Friction in 0.6.0
+
+**Status:** Proposal for review
+**Date:** 2026-05-25
+**Author:** Claude (via Doug) during wizardsofodd Phase 2 / MO 0.6.0 adoption
+**Consumer project:** [`wizardsofodd.com`](../../../../wizardsofodd.com) — live Cloudflare Worker
+deployment with persistence + template-driven prompts + React UI in flight
+
+## Context
+
+`wizardsofodd.com` is in active mid-adoption of MO 0.6.0 across four surfaces:
+**persistence** (D1 via codegen-emitted Drizzle), **template-driven prompts**
+(`generateRenderHandle()` + `generatePayloadInterfaces()` from
+`@metaobjectsdev/codegen-ts`), **React UI** (Vite-built SPA in Workers Static
+Assets), and **projection vocabulary** (declared in metadata, hand-rolled
+queries). The full spec + plan lives at:
+
+- `wizardsofodd.com/docs/superpowers/specs/2026-05-25-metaobjects-0.6-mega-design.md`
+- `wizardsofodd.com/docs/superpowers/plans/2026-05-25-metaobjects-0.6-mega.md`
+
+Consumer's deployment shape (worth keeping in mind as you weigh fixes):
+
+- **Runtime:** Cloudflare Workers (V8 isolate — no Node-only deps allowed)
+- **Persistence:** Cloudflare D1 via `drizzle-orm/d1`
+- **Use of MO:** codegen output ONLY (no `@metaobjectsdev/runtime-ts` since
+  Fastify/Kysely can't run in Workers). Codegen runs at dev/build time;
+  generated artifacts are committed.
+- **Build chain:** `meta gen` → `vite build` → `wrangler deploy`.
+
+The good news up front: **0.6.0 is unblocking**. The fixes from 0.5.0
+(`field.enum` registration, `--dialect d1`, `generateRenderHandle()`) are real
+and consumed. The items below are *friction*, not blockers. Each one is
+something a consumer pays a small recurring tax on, that would compound as
+the consumer audience widens.
+
+Items are ranked by leverage (consumer-pain × scope-of-affected-consumers ÷
+estimated implementation effort).
+
+---
+
+## Tier 1 — Highest leverage, smallest cost
+
+### #1 — Auto-wire `generateRenderHandle()` + `generatePayloadInterfaces()` into a stock generator
+
+**Where:** `server/typescript/packages/codegen-ts/src/generators/` — add a new
+generator alongside `entityFile()`, `queriesFile()`, `barrel()`.
+
+**Today:** both helpers are exported from `@metaobjectsdev/codegen-ts/payload-codegen`
+(verified at `payload-codegen.ts:78-83` and `:89-106`) and individually work
+— but no generator in `generators/` calls them. Consumers wanting typed
+`renderXxx()` handles must write a custom `Generator` themselves and add it
+to their `metaobjects.config.ts`. From the wizardsofodd plan
+(Phase B, Task 5):
+
+```ts
+// We have to write this in metaobjects.config.ts to get typed prompt handles
+import { generatePayloadInterfaces, generateRenderHandle } from "@metaobjectsdev/codegen-ts";
+const promptCodegen: Generator = {
+  name: "prompt-render",
+  emit(ctx) {
+    const payloads = ctx.entities.filter(e => e.kind === "object.value");
+    const prompts = ctx.entities.filter(e => e.kind === "template.prompt");
+    return [{
+      path: "src/render/generated/prompts.ts",
+      content: [
+        generatePayloadInterfaces(payloads),
+        ...prompts.map(generateRenderHandle),
+      ].join("\n"),
+    }];
+  },
+};
+```
+
+**Suggested fix:** Export a `promptRender()` (or `renderHandles()`) generator
+from `@metaobjectsdev/codegen-ts/generators` that does the above. Consumers
+who want typed prompts just add it to their generators list:
+
+```ts
+// metaobjects.config.ts (consumer side, after fix)
+import { entityFile, queriesFile, barrel, promptRender } from "@metaobjectsdev/codegen-ts/generators";
+export default defineConfig({
+  // ...
+  generators: [entityFile(), queriesFile(), barrel(), promptRender()],
+});
+```
+
+**Effort:** ~30 minutes. Both helpers already exist; this is glue + one new
+file in `generators/`.
+
+**Consumer impact:** Saves ~20 LOC of identical custom-generator boilerplate
+per consumer. More importantly, eliminates a "huh, why isn't this just
+working?" moment that takes a new consumer 30+ minutes to figure out (the
+docs say `generateRenderHandle()` exists; the default `meta gen` doesn't
+seem to use it).
+
+---
+
+### #2 — Parameterize generated `*.queries.ts` to accept `db` as a parameter
+
+**Where:** `server/typescript/packages/codegen-ts/src/templates/queries.ts`
+(or equivalent template).
+
+**Today:** generated `Council.queries.ts` does:
+```ts
+import { db } from "../db";
+// ...
+export async function findCouncilById(id: string) { return db.select()... }
+```
+
+This forces every consumer to ship a `src/db/db.ts` module at the import
+path the generated code expects. In a Cloudflare Worker, **the `db` is
+per-request** (`drizzle(env.DB)` requires the request-scoped binding) — there
+is no module-level `db` to import. So consumers ship a runtime-throwing stub
+purely to satisfy the typecheck:
+
+```ts
+// wizardsofodd Phase A Task 5 (will exist in every Worker consumer)
+export const db = (() => {
+  throw new Error("type-only stub — use getDb(env) in the handler");
+})() as unknown as BaseSQLiteDatabase<"async", { rowsAffected: number }>;
+```
+
+This is dead code in the bundle that exists ONLY for typecheck. Every Worker
+consumer pays this tax forever.
+
+**Suggested fix:** generate query helpers that accept `db` as their first
+parameter:
+
+```ts
+// generated Council.queries.ts (after fix)
+import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
+export async function findCouncilById(db: BaseSQLiteDatabase, id: string) {
+  return db.select()... 
+}
+```
+
+Consumers call them with their per-request `db`:
+```ts
+const db = drizzle(env.DB, { schema });
+const council = await findCouncilById(db, "abc123");
+```
+
+This is the standard Drizzle / Kysely / TypeORM pattern in 2026.
+
+**Effort:** 1–2 hours — template change in the queries codegen + updating
+docs to show the new call shape. Backward-compatibility could be handled by
+shipping both shapes briefly (with the parameterless variant calling a
+default-export `db`), or it's a breaking change consumers absorb in 0.7.
+
+**Consumer impact:** Eliminates a dead-code kludge every Worker consumer
+ships. Aligns with the dominant ORM-helper pattern in TS — current Drizzle
+docs all show parameter-passing.
+
+---
+
+### #3 — Add `expected/` output to the `template-prompt-simple` conformance fixture
+
+**Where:** `fixtures/conformance/template-prompt-simple/`.
+
+**Today:** The fixture has `input/meta.ai.json` and `expected.json` (the
+parsed metadata tree). It does NOT have an `expected/` directory showing
+what the **codegen** produces. A consumer trying to understand "what does
+`template.prompt` look like after `meta gen`?" has no canonical example to
+read — they have to run the codegen themselves.
+
+This is partly why my initial recon agent (looking at the metaobjects repo
+to scope the wizardsofodd integration) reported "no typed codegen for
+prompts in 0.6.0" — there was no expected output file to find. The codegen
+IS there (`generateRenderHandle()` works), but invisible to anyone reading
+the fixture corpus.
+
+**Suggested fix:** add `fixtures/conformance/template-prompt-simple/expected/prompts.ts`
+containing the actual output of `generateRenderHandle()` + `generatePayloadInterfaces()`
+applied to the input metadata. Either generated-and-committed, or asserted
+to match in the conformance test.
+
+**Effort:** ~20 minutes — generate once, commit, add an assertion. If a
+conformance check enforces "what `meta gen` produces equals `expected/`,"
+even better (catches codegen regressions).
+
+**Consumer impact:** Docs-as-data. Consumers and AI agents alike can read
+the fixture and immediately understand the codegen contract without running
+anything.
+
+---
+
+## Tier 2 — High value, somewhat larger
+
+### #4 — Document the Vite + Cloudflare Workers recipe
+
+**Where:** `README.md` or a new `docs/recipes/cloudflare-workers.md`.
+
+**Today:** Consumers wanting to use MO codegen output in a Cloudflare Worker
+with a Vite-built React SPA frontend (a very common 2026 deployment shape)
+have to figure out for themselves:
+- Which packages run in V8 isolates (codegen output ✅; `@metaobjectsdev/runtime-ts` ❌)
+- How to integrate Vite output with Workers Static Assets without wiping
+  hand-curated public files (the `emptyOutDir: false` discipline)
+- How to wire `meta gen` into the build chain alongside `vite build` and
+  `wrangler deploy`
+- The dev-only nature of codegen (run locally, commit output, never invoke
+  at runtime)
+
+**Suggested fix:** a documented recipe section + ideally a tiny example repo
+(could even be the wizardsofodd shape, lightly anonymized). The recipe
+documents the exact constraints that took us multiple sessions to learn.
+
+**Effort:** ~1 hour for the README section; ~2-3 hours if you want a
+demo repo.
+
+**Consumer impact:** Cloudflare Workers is one of the most common edge
+deployment targets in 2026. Documenting MO's Worker story explicitly grows
+the addressable consumer base.
+
+### #5 — `CHANGELOG.md` at the monorepo root (or per-package)
+
+**Where:** Monorepo root; per-package optional.
+
+**Today:** Release notes only exist in `docs/RELEASING.md` (process docs).
+Consumers — including me, doing the 0.5→0.6 upgrade survey — have to do
+archaeology to figure out what changed (compare package versions across
+tags, grep for renames, etc.). For the wizardsofodd Phase 2 unblock
+specifically, the key questions "did `field.enum` register?" and "did
+`--dialect d1` ship?" took an Explore agent ~10 minutes to answer; a
+CHANGELOG would have made it 10 seconds.
+
+**Suggested fix:** standard Keep-a-Changelog format. Backfill 0.5.0 → 0.6.0
+once; then add notes per release going forward.
+
+**Effort:** ~30 minutes for the initial backfill; ~5 minutes per release.
+
+**Consumer impact:** Every consumer needs to know what changed. AI agents
+specifically benefit — a CHANGELOG is high-signal context per token spent.
+
+### #6 — Better error messages on entity JSON shape mismatches
+
+**Where:** `server/typescript/packages/metadata/src/loader/` (or wherever
+the JSON-to-metadata mapper raises validation errors).
+
+**Today:** When a consumer authors `metaobjects/council.json` and a field
+key is wrong (e.g. forgets `@` prefix on `@maxLength`, or uses `enum`
+instead of `field.enum`), the error is generic ("unknown field key X"). No
+line number, no suggestion, no link to the canonical fixture.
+
+The wizardsofodd Phase 2 implementer last session had to mirror conformance
+fixtures (`enum-inline/input/meta.enums.json`) because the entity-JSON
+shape in my high-level spec didn't match what the loader actually accepted.
+Cost a session's worth of iteration.
+
+**Suggested fix:** error messages with (a) the JSON path to the offending
+key, (b) a "did you mean ___" suggestion based on Levenshtein distance to
+known keys, (c) a link to the most-relevant conformance fixture as a
+working example. Even just (a) + (c) would dramatically reduce time-to-fix.
+
+**Effort:** ~4-6 hours. The loader knows where it is in the JSON tree; just
+needs to expose that on raised errors.
+
+**Consumer impact:** Onboarding pain reduction. The "first hour with MO"
+experience is dominated by entity-shape iteration; making errors actionable
+shrinks that to "first 10 minutes."
+
+### #7 — Document camelCase vs snake_case mapping as a deliberate design choice
+
+**Where:** `README.md` + a "conventions" section in the codegen docs.
+
+**Today:** Generated Drizzle uses camelCase TS properties (`councilId`,
+`createdAt`) for snake_case SQL columns (`council_id`, `created_at`). This
+bit our queries.ts implementation multiple times — every time someone
+writes a query they have to remember "TS=camel, SQL=snake." The mapping is
+sensible (idiomatic both ways) but the discovery is by-error.
+
+**Suggested fix:** 1-paragraph docs section: "MO codegen maps `snake_case`
+metadata field names to `camelCase` TS property names by default, with the
+underlying SQL column staying `snake_case`. Override per-field with
+`@dbColumn`." Plus a worked example.
+
+**Effort:** ~15 minutes.
+
+**Consumer impact:** Prevents the "wait, why does Drizzle complain about
+`councilId` not existing when I wrote `council_id`?" stumble every consumer
+hits at least once.
+
+---
+
+## Tier 3 — Nice-to-have
+
+| # | What | Why it's lower priority |
+|---|---|---|
+| 8 | `metaobjects/` directory name configurable in `metaobjects.config.ts` (currently hard-coded in CLI's `loadMemory`) | Mild irritation; a single rename in the consumer repo gets you there |
+| 9 | `meta init` opt-out for `.metaobjects/` agent-docs scaffolding (~50 KB of AGENTS.md/CLAUDE.md) | Easy to delete after the fact if you don't want them |
+| 10 | `template.output` codegen for LLM output schemas | Real value for consumers doing structured-output LLMs, but bigger scope; current `generateRenderHandle()` handles both prompt and output identically — meaningful divergence requires its own design |
+| 11 | Wider `@metaobjectsdev/react` component coverage (entity detail / list / filter UI in addition to `useEntityForm` + `<CurrencyInput>`) | Bigger product decision; wizardsofodd v1 React work doesn't need it |
+
+---
+
+## Tier 4 — Verification (might already be done; ~10 min spot-checks)
+
+### #12 — `meta migrate --dialect d1` end-to-end
+
+The `writeMigrationD1()` function exists at
+`server/typescript/packages/migrate-ts/src/write-migration-d1.ts`, but does
+the CLI flag (`--dialect d1`) actually wire through? Do the output
+filenames match wrangler's `NNNN_name.sql` convention, or does the consumer
+have to rename?
+
+The existing `.claude/worktrees/meta-migrate-d1-dialect/` worktree suggests
+you're already on this — just confirm wizardsofodd can use it cleanly
+without filename gymnastics. If a flat `NNNN_init.sql` lands in
+`migrations/` and `wrangler d1 migrations apply` picks it up, we're good.
+
+### #13 — `deleteXById` D1 response-shape bug fix status
+
+In 0.5.0, the generated `deleteCouncilById(id)` helper assumed `result.rowsAffected`
+which is a libsql/Turso field — D1 doesn't return it. Helper returned
+`false` even on a successful delete. Was this fixed in 0.6.0?
+
+Not on the wizardsofodd hot path (councils are immutable), but worth knowing.
+
+---
+
+## Suggested ordering if you have appetite for Tier 1
+
+If you tackle Tier 1 in order, each item compounds the value of the next:
+
+1. **#3 (add `expected/` to conformance fixture)** — 20 minutes. Immediately
+   makes the next two changes easier to test/document.
+2. **#1 (auto-wire `promptRender()` generator)** — 30 minutes after #3 ships.
+   Lets consumers drop the custom-generator wiring.
+3. **#2 (parameterize `db` in generated queries)** — 1–2 hours after #1.
+   Biggest "every-consumer-pays-this-tax-forever" win.
+
+Tier 2 items can be batched whenever (#4, #5, #7 are all small docs adds).
+
+---
+
+## What wizardsofodd does in the meantime
+
+This proposal is **not blocking** for wizardsofodd Phase A — every item has
+a documented workaround in our plan
+(`wizardsofodd.com/docs/superpowers/plans/2026-05-25-metaobjects-0.6-mega.md`).
+We'll ship Phase A with the current 0.6.0 (custom-generator wiring, stub
+`db.ts`, etc.) and incorporate any upstream improvements when they land
+during Phases B/C/D.
+
+If Tier 1 ships before Phase B, we delete ~50 LOC of workaround code and
+import from `@metaobjectsdev/codegen-ts/generators` instead.