docs(base44-cli): route dev and build through the CLI [merge after cli#580 + cli release]

[davidsu]

🚧 DRAFT — merge right after the cli release

Part of the re-scoped local-dev plan (login is out of scope; the five earlier PRs are closed).

Repo	PR	Relationship
base44/cli	#580	ships all four surfaces this documents (dev, dev --remote, build, deploy --build). #581 was folded into it. This doc must not merge before it — it names commands that PR introduces
base44-dev/vite-plugin	#102	the console messages that make "don't run npm run dev / npm run build yourself" actionable. No dependency either way — neither PR quotes the other's strings

Semantics here are verified against landed code and an independent QA pass on a clean scratch app
(base44 build bakes the id; the previously-broken deployed bundle now returns 200 where it 404'd),
not against a spec.

Why this should merge early in the train, not last

This PR does two different jobs, and the second one changes its urgency:

1. Additive — documents base44 dev --remote and base44 build. Safe to land any time after cli#580.
2. Corrective — the skill currently instructs the broken build path in four places. Every hour
   it stays unmerged, the published skill tells agents to run a bare npm run build, producing a
   bundle with no app id whose every API call fails once deployed.

Job 2 has no plugin dependency, so the cheapest safe order is cli#580 → cli release → this →
plugin#102 → plugin release (endorsed by the vite-plugin lane, which owned the earlier ordering).

The problem

An app can be run locally two ways and the skills documented one. SKILL.md offered only
npx base44 dev; nothing said a production-backed mode exists, or which mode touches live data.

Second-order problem: SKILL.md's routing block sent every existing-project case
(base44/config.jsonc exists) to base44-sdk with "this skill only handles CLI commands" — precisely
the user who wants to run their app, routed away from the guidance.

The change

One file, skills/base44-cli/SKILL.md.

Routing (§ IMMEDIATE ACTION REQUIRED). Existing-project cases still hand off to base44-sdk, with
one carve-out: running the app locally stays here, and the agent reads the mode guidance before
starting a dev server.

§ Running Local Development. A two-row table with the data consequence in it, a stated default, the
site.serveCommand / linked-project preconditions, and one line telling agents not to run npm run dev
directly (the plugin's message covers them if they do). Backend-only projects stay first-class — the
backend-only template ships no frontend at all.

Kept short deliberately. This is SKILL.md; it loads into every agent's context. Net ~+15 lines. It
orients on the decision and delegates detail to dev.md.

History

Earlier revisions of this PR documented the option-A redirectToLogin fix in skills/base44-sdk, then
a base44 dev vs bare npm run dev mode table. Both described plans that were dropped; base44-sdk is
untouched and the npm run dev → production row is gone, since the plugin fallback that made it true
never ships.

Reviewed on the investigate-login channel by the cli, plugin, sdk, apper and test-runner lanes. Two
corrections from that review survive into this version: the detection heuristic (the vite startup line
names the backend) and binding the frontend to site.serveCommand rather than to a frontend merely
existing.

Deliberately omitted to protect context: unlinked-project failure modes, base44 dev passing
unimplemented API routes to production, the local DB also clearing on schema change, and media uploads
living in a temp dir.

🤖 Generated with Claude Code