BRANCH_ID: default everywhere, numeric only for branched storage

[claude]

Requested by David Esner · Slack thread

End state

BRANCH_ID is optional everywhere, and the templates now behave that way. A user running any template locally does not have to set it — the effective value is default, which resolves to the production branch. The advice is identical on the platform and locally, which was the point of the change: nothing to look up, and no value that can drift between a developer's machine and the deployed app.

A numeric BRANCH_ID is the documented exception, needed only when the app has to read a development branch's tables (branched storage).

Why the framing flipped mid-PR

The first two commits on this branch were built on the premise that the Query Service rejects the string "default" with a parse error, so local dev had to pass a numeric branch ID. Review from the domain owner: that is not true — the Query Service accepts default.

With the premise gone, the two-context split that the earlier commits worked so hard to draw (platform injects the var, local dev must supply it) collapses. The two contexts no longer differ in any way the reader has to act on, so the subsection is now a single unified explanation instead of two mirrored cases.

	Before this PR	After the first two commits	Now
Local dev	"Defaults to default. Almost always leave it that way." — then, eleven lines down, "needs a numeric ID"	Always set it, to the main branch's numeric ID	Don't set it; falls back to default
Deployed	Leave it out of the app config	Leave it out of the app config	Leave it out of the app config
Dev-branch tables	Set the branch's numeric ID	Set the branch's numeric ID	Set the branch's numeric ID

Retained from the old text: data apps only ever run in the production branch and the var controls which branch's tables are read; use mcp__keboola__get_project_info rather than hand-rolling GET /v2/storage/dev-branches; the branch_id / is_development_branch fields; the Development Branches UI lookup. The is_development_branch check now reads the other way round — it tells you whether the branch_id you got back is the development branch you actually want, instead of gating against accidentally pasting a dev-branch ID.

Documentation

plugins/dataapp-developer/skills/dataapp-development/references/

• storage-access.md §BRANCH_ID — rewritten. One unified explanation (normally unset, effective value default, same in both contexts) plus one exception (numeric ID for branched storage) with both lookup paths.
• storage-access.md — BRANCH_ID marked optional in both required-env-var lists (§Direct RO workspace queries, §Alternative: Storage API workspace-query endpoint). The Storage API line no longer says the API "happens to tolerate" default with "no reason to rely on that" — default is simply fine there too.
• storage-access.md — the SDK call-shape examples and the Storage Access wrapper (storage.py / storage.ts) now default to default (os.environ.get("BRANCH_ID", "default"), process.env.BRANCH_ID || 'default') instead of requiring the var, matching the Storage-API endpoint snippets that already did. The # numeric, not "default" comments are gone.
• storage-access.md — dropped branch_id from the values the agent pre-fills into .env.local; there is nothing to fill in.
• troubleshooting.md — the missing-env-var entry is no longer keyed on KeyError: 'BRANCH_ID' (nothing in the docs raises that any more) and now states outright that BRANCH_ID is not one of the variables to add.
• python-js-apps.md — BRANCH_ID removed from the env vars to mirror locally.

Templates — actual behaviour change

plugins/dataapp-developer/skills/dataapp-development/templates/

• streamlit/utils/data_loader.py — was: st.error("Missing BRANCH_ID. The Query Service requires a numeric branch ID — the string 'default' is rejected…") and an empty DataFrame. Now: branch_id = _get("BRANCH_ID") or "default". The WORKSPACE_ID check is untouched.
• streamlit/.streamlit/secrets.toml.example — BRANCH_ID = "510379" # numeric — Query Service rejects the string "default" moved into the commented optional block with a corrected comment. Three required keys, not four.
• nodejs-app/api/keboola-client.js — resolveKeboolaEnv() returns branch: branch.value || 'default'; runQuery() no longer pushes BRANCH_ID onto missing. The pick('KBC_BRANCH_ID', 'BRANCH_ID') alias behaviour is deliberately untouched.

python-app/, python-node-app/ and duckdb-cache/ never referenced BRANCH_ID, so there was nothing to change. All three template README.mds already listed only KBC_URL, KBC_TOKEN, WORKSPACE_ID, so they were already consistent with BRANCH_ID being optional.

Deliberately left alone

• docs/superpowers/plans/2026-05-13-dataapp-development.md — historical planning document. Its code samples already use _get("BRANCH_ID", "default") and pick('KBC_BRANCH_ID', 'BRANCH_ID'), so they happen to agree with the new guidance anyway.
• The KBC_BRANCH_ID vs BRANCH_ID alias question, and adding .env.example files to templates that don't ship one — both flagged separately, neither approved here.
• references/glossary.md's "Development Branches (find numeric branch ID)" UI pointer — still correct, that's the exception path.

Where the false claim came from

74c2020 (15 May) introduced it, in that commit message: "The Query Service rejects the string "default" for BRANCH_ID with a parse error." It landed with no repro, no captured error text, and no test. 76ee160 later the same day propagated it into the templates while migrating them off the legacy Storage API workspace endpoint; the failure that session actually recorded was 404 workspace.workspaceNotFound from the legacy endpoint, which is a different problem. The commit immediately before, 5152542, had said "leave it at default" — which is what this PR restores.

No version bumps or README changes

CLAUDE.md's four bookkeeping steps are scoped to adding commands, agents, or skills. This edits prose and template internals in an existing skill: no new skill surface, no frontmatter change, no file list change. Happy to add a patch bump if the convention is that docs/template edits ship one.

Verification

• Tier 0 static lint, from evals/: uv run --group dev pytest -q → 329 passed, 32 skipped.
• node --check templates/nodejs-app/api/keboola-client.js → clean.
• python -m py_compile templates/streamlit/utils/data_loader.py → clean.
• tomllib.load on templates/streamlit/.streamlit/secrets.toml.example → parses.
• Tier 1 activation evals not run (need ANTHROPIC_API_KEY); none of this touches skill routing.