Wren GenBI App — Agent Workflow Guide

This guide is served by the wren CLI (wren skills get genbi), so it always matches your installed wrenai version.

Turn a Wren context layer into a shareable GenBI app — from a natural-language request to a public URL in one conversation.

Division of labor: the CLI owns the authoritative build instruction (it knows the live project facts and the pinned wren-core-wasm version) and all deterministic state (index, verify, deploy). You — the agent — author the app code by following the instruction. Never hand-write .wren/apps.yml.

Preconditions

1. A Wren project is discoverable (wren_project.yml in cwd/ancestors, or ask for the path and pass -p).
2. The context layer exists. If target/mdl.json is missing, wren genbi build compiles it implicitly — no separate step needed.
3. wren CLI ≥ the version that ships the genbi command group (wren genbi --help works).

Workflow

1. Resolve the app name and data mode

• App name: short kebab-case derived from the request (e.g. sales-overview).
• Data mode:
  • snapshot (default) — data is bundled with the app as parquet/duckdb and queried client-side. Fully serverless. Right for demos, reports, small data, and dlt-pipeline output.
  • live — the app calls back to the user's warehouse/API at view time. Right for production-scale or always-fresh data. Requires a CORS-enabled endpoint and carries strict no-credentials rules.
• Ask the user ONLY if the choice is genuinely ambiguous.

2. Get the build instruction

wren genbi build <name> --prompt "<the user's request, verbatim>" --data-mode <mode>

For long or multi-line prompts use --prompt-file <file> or pipe to --prompt -. The command prints the authoritative build instruction — wasm wiring (pinned version, CDN load), the project's model/column inventory, data-mode guidance, acceptance criteria, and the target folder. It writes no app files — the only thing it may touch is target/mdl.json, which it compiles first if missing (see Precondition 2).

3. Author the app

Follow the instruction exactly. Key conventions:

• Write everything under apps/<name>/ — never outside it.
• Copy the compiled MDL into the app as apps/<name>/mdl.json.
• Load wren-core-wasm from the CDN given in the instruction; never bundle the ~68MB binary.
• snapshot: export the data the dashboard needs into apps/<name>/data/ as parquet (verify requires at least one .parquet/.duckdb asset). See Snapshot data export below for the recipe and where the data comes from.
• live: write an endpoint-only connection config. NEVER inline credentials — verify scans for them (best-effort) and deploy gates on verify, but the rule is on you: a public static host exposes every shipped file.
• Design the dashboard to actually answer the user's request: pick the right charts/tables for the question, not a generic template.

Snapshot data export

The CLI hands you the build instruction, but the snapshot bytes still have to be exported into the app folder — that step is yours.

Where the data comes from:

• DuckDB-backed project (incl. anything loaded by the dlt-connector skill — its pipelines always land in a .duckdb file): the project's DuckDB file is your snapshot source. If the user is connecting SaaS data (HubSpot, Stripe, Salesforce, …) and has no project yet, run the SaaS→project flow first: wren skills get dlt-connector. Then come back here to ship it.
• Warehouse-backed project (Postgres, BigQuery, Snowflake, …): run the query/queries the dashboard needs through the MDL layer and write the result to parquet. Keep snapshots small — snapshot mode is for demos/reports, not full warehouse extracts; use live mode for large or always-fresh data.

Recipe (DuckDB → parquet):

# from the project root; <db> is the project's DuckDB file (see wren_project.yml)
python - <<'PY'
import duckdb
con = duckdb.connect("<db>.duckdb", read_only=True)
con.execute(
    "COPY (SELECT * FROM <table>) "
    "TO 'apps/<name>/data/<table>.parquet' (FORMAT parquet)"
)
PY

Only export the columns/rows the dashboard uses. The compiled mdl.json you copied in keeps the context layer intact regardless of how you bundle data.

4. Register and verify

wren genbi register <name> --data-mode <mode>
wren genbi verify <name>

If verify fails: fix the reported problems and re-run verify. Do NOT proceed to deploy on a failed verify. Offer wren genbi open <name> for a local preview before shipping.

5. Deploy (only if the user asked for it)

wren genbi deploy <name> --provider vercel      # or cloudflare

• Preview deployment by default. Confirm with the user before --prod.
• Tokens: the CLI discovers VERCEL_TOKEN / CLOUDFLARE_API_TOKEN from the environment or .env files. If missing, ask the user to export it or add it to the project .env. NEVER put a token on the command line.
• Cloudflare also needs CLOUDFLARE_ACCOUNT_ID (env or .env), a token scoped with Pages:Edit, and the wrangler CLI on PATH (or npx available) — the adapter shells out to wrangler pages deploy. If it's missing, ask the user to npm install -g wrangler.
• Report the returned URL to the user. Re-deploying the same app updates the same provider target.
• Verify the URL actually loads. After deploying, fetch the URL — a successful deploy can still return HTTP 401/403 to outsiders because of the provider's access protection (see below). Don't report a link as "shareable" until you've confirmed it serves.

Vercel Deployment Protection (the 401 trap)

New Vercel projects ship with Vercel Authentication turned ON by default, so every deployment — preview and production — returns 401 to anyone not logged into the owning Vercel account/team. The deploy itself succeeded; the URL is just gated.

• To make the app publicly shareable, the user disables it in the Vercel dashboard: Project → Settings → Deployment Protection → Vercel Authentication → Disabled (or scope it to production only). This setting is not controllable from wren genbi deploy; it's a one-time toggle per project in Vercel.
• If the user only needs a private link (viewable while logged into their Vercel account), leaving protection on is fine — just tell them the link won't work for logged-out visitors.

Safety boundaries

• Never inline secrets/credentials into app files — the deploy target is a public static host; anyone with the URL can read every file. verify scans for inlined credentials, but treat it as best-effort defense-in-depth, not a guarantee — never rely on it to catch a secret you shouldn't have written in the first place.
• Never pass tokens as CLI flags; they leak into shell history.
• Confirm before production deploys.
• All index state goes through wren genbi register/remove — never edit .wren/apps.yml by hand.

Quick reference