@formlm/cli 0.3.0 → 0.5.1

package/README.md

@@ -20,6 +20,28 @@ With `formlm-cli`, you can control FormLM directly from your terminal or plug it
 
 ---
 
+## What's New in v0.5.0
+
+Hardening round driven by real agent field reports (batch runs of 50 apps), plus a second pass that re-checked every reported item against the code and machine-verified all documented commands.
+
+- **`share publish` now defaults to anonymous access** (`--access visitor`) and exposes `--access / --perm / --days / --no-style`; a new `share set` subcommand passes the raw server parameters through, so "anyone + permanent" no longer requires calling the internal API. Previously publish was hard-wired to `form-type all`, which **requires login** — anonymous respondents got the login page.
+- **`expert config --enable` no longer self-destructs**: the value is forwarded space-separated (`--enable true`) and the server accepts it again. Before, `--enable=true` was rejected as an unknown option, the whole command was discarded, yet the envelope still reported success.
+- **Parameter errors are no longer reported as success**: `picocli` validation failures now map to `code != 0` / `ok:false` instead of hiding the error text inside `data` with `code:0`.
+- **Uniform machine output**: `snapshot` and `auth status` now honour `--json`/`FORMLM_JSON=1` with the same `{ok,code,message,data}` envelope as everything else, and human guidance lines moved to stderr, so stdout is a single parseable line.
+- **`app remove` is a real alias of `app delete`**; `app list` gained `--all / --limit / --page / --with-urls`; `app urls` returns `shareToken`, `published`, `shareType/Perm/Day` and absolute https URLs.
+- **New `doctor` command** (and MCP `formlm_doctor` tool): one read-only call per app covering scoring coverage, dead/empty experts, styling, unexpected certificate pages, language consistency (`--expect-lang`, `--deep` scans widget text) and share access + reachability.
+- **New `snapshot --summary`** compact audit profile (counts, dimension names, report pages, expert flags, share type/perm/day + shareToken) — batch verification no longer needs to parse full module payloads.
+- **Resume after the plan cache expires**: `smart plan --save-plan <file>` + `smart execute --plan-file <file>` (the server plan cache is ~10 minutes, and the docs now say so).
+- **Retry/backoff**: read-only commands retry with exponential backoff on 408/429/5xx; writes are never auto-retried. Tunable via `FORMLM_RETRIES` / `FORMLM_TIMEOUT_MS`.
+- `report page remove --name "结业证书"` resolves page names server-side; `report page update` verifies the page exists (opt into upsert with `--upsert`); write confirmations are compact; `widget remove` now persists (it previously returned success without saving).
+
+- **`smart generate` now exists** as a resumability-preserving wrapper over `plan → execute×N → (--publish) → (--doctor)`, and the README finally matches the command surface. Earlier versions documented a `smart generate` that was never implemented (the first command every agent ran, and it failed).
+- **Generation is now pin-able**: `smart plan --dimensions "A|B|C"` fixes the scoring dimension names and count, `--app-name` fixes the app display name, `--dry-run` validates a prompt without leaving a residue app. Unpinned dimensions used to be renamed/recounted by the AI, forcing page↔app rework (batch measurement: 11/13 pages).
+- **Docs are now machine-verified against the command surface**: every `formlm-cli …` example in README/INSTALL is executed and checked for unknown/missing options (149 examples, 0 drifts), so documented commands cannot silently diverge again.
+- `smart plan` output carries structured `modules` / `missingModules`, so callers can detect coverage gaps (e.g. no `expert` for non-consultation plans) without parsing prose; the raw exec `403` now lists the whitelisted command set.
+
+---
+
 ## What's New in v0.2.1
 
 - **Field ID validation**: `field add --id` now enforces snake_case regex (`^[a-zA-Z0-9_]+$`)
@@ -46,7 +68,7 @@ The MCP architecture has been completely redesigned from the ground up:
 │         AI Agent (any MCP Client: Claude / Cursor /       │
 │           Codex CLI / Windsurf / Cline / ...)             │
 ├─────────────────────────────────────────────────────────┤
-│  Tier 0: auth_login, auth_status                         │
+│  Tier 0: auth_login, auth_email_code, auth_status      │
 │  Tier 1: formlm_generate                   ← Smart Pipeline │
 │  Tier 2: formlm_snapshot, formlm_skill ← State + Knowledge│
 │  Tier 3: formlm_exec                    ← Direct Commands │
@@ -84,43 +106,96 @@ For a detailed step-by-step guide (including MCP setup for Claude Desktop / Curs
 ### 1. Login
 
 ```bash
-formlm-cli auth login
-# or use a token directly
+# Recommended: copy your Access Token from the web app
+# (formlm.me → sign in → Workspace → top-right user menu → Account Settings → Access Token → Copy)
 formlm-cli auth login --token <your-token>
+
+# Interactive login — pick one of three methods:
+#   1) Access Token    (same as above)
+#   2) Email verification code  (no password, no browser — fully in the terminal)
+#   3) Email + password (only if your account has set a password —
+#      email-verification-code and Google accounts have none)
+formlm-cli auth login
 ```
 
 ### 2. Smart Pipeline (AI-recommended)
 
+Creation is a **two-phase pipeline** (`plan` → `execute` per module). `smart generate` is the one-shot wrapper
+of the same steps when you do not need per-module control:
+
 ```bash
-# Generate a complete assessment app from natural language
-# This includes form design, scale config, report pages, AND visual styling — all in one step.
-# Expected time: 60-120s for assessment, 180-300s for consultation. Do NOT cancel.
-formlm-cli smart generate --input "Create a workplace stress assessment with 10 questions, 3 dimensions, and detailed score interpretations"
+# One-shot: plan → execute every module → publish anonymously → quality audit
+formlm-cli smart generate \
+  --input "Create a workplace stress assessment with 10 questions, 3 dimensions (workload, autonomy, support), and detailed score interpretations" \
+  --plan-type assessment --question-count 10-15 --lang en --publish --doctor
 ```
 
-> **⚠️ Smart generate already includes visual styling.** If you skip smart generate and use Direct Commands (below) instead, you MUST run `connect style apply-all` to beautify your form — otherwise it will use the default unstyled appearance.
+Or step by step (recommended for batches — every step is resumable):
+
+```bash
+# Phase 1 — plan (~10-30s): creates the app and returns appId + task list.
+# --save-plan keeps the full plan JSON on disk so modules can still be executed
+# after the server-side plan cache (~10 min) expires.
+formlm-cli smart plan --input "Create a workplace stress assessment with 10 questions, 3 dimensions, and detailed score interpretations" \
+  --plan-type assessment --question-count 10-15 --lang en --dimensions "Workload|Autonomy|Support" --save-plan plan.json
+
+# Phase 2 — execute every module listed by the plan, in order (~30-120s each):
+formlm-cli smart execute --app <appId> --module form
+formlm-cli smart execute --app <appId> --module scale
+formlm-cli smart execute --app <appId> --module connect
+formlm-cli smart execute --app <appId> --module report
+formlm-cli smart execute --app <appId> --module share
+
+# Publish so anonymous visitors can fill it in (each respondent submits once, permanent):
+formlm-cli share publish --app <appId>            # --access visitor is the default
+
+# Verify quality in one read-only call (see Doctor below):
+formlm-cli doctor --app <appId> --expect-lang en
+```
+
+> **⚠️ Module coverage depends on planType.** Only `consultation` plans include an `expert` task;
+> `assessment / exam / report / survey / learn` do not. `smart plan` prints a warning when a module is
+> missing — add an expert explicitly with `formlm-cli expert config --app <appId> --name ... --role ... --kbText ...`.
+
+> **⚠️ Styling:** the `connect` module of the pipeline applies the visual style. If you skip the pipeline and use
+> Direct Commands instead, you MUST run `connect style apply-all`, otherwise the form keeps the plain unstyled look.
 
 ### 3. Get All App URLs (after creating)
 
 ```bash
-# Get fill-in, editor, and data management URLs in one call
+# Get fill-in, editor, data management, and Data API URLs in one call
 formlm-cli app urls --app <appId>
-# Returns: shareUrl (fill-in), builderUrl (editor), dataUrl (data management)
+# Returns: shareUrl (relative /s/<token>), shareUrlAbsolute (https, iframe-ready),
+#          shareToken, published, shareType/sharePerm/shareDay,
+#          builderUrl (editor), dataUrl (data management),
+#          apiUrl + apiHelpUrl (Data API, empty until enabled)
 ```
 
-### 4. Beautify Your Form (if using Direct Commands)
+### 4. Enable the Data API (form backend for any page)
+
+```bash
+# Turn a form into a data endpoint — static sites, local pages, and AI apps
+# can POST submissions straight to it (CORS enabled, no server needed)
+formlm-cli share api --app <appId> --submit true --query true
+# Then point your HTML form / fetch / curl at the returned endpoint.
+# Append ?help to the endpoint for its Markdown docs (readable by AI agents).
+```
+
+### 5. Beautify Your Form (if using Direct Commands)
 
 ```bash
 # Apply AI-generated visual style to all pages (takes 30-120s)
 formlm-cli connect style apply-all --app <appId> --look "职场压力评估，深蓝专业风格" --theme minimalist
 ```
 
-### 5. Direct Commands (for fine-grained control)
+### 6. Direct Commands (for fine-grained control)
 
 ```bash
 # Get a snapshot of all module states
 formlm-cli snapshot --app <appId>
 formlm-cli snapshot --app <appId> --md              # Markdown format (token-efficient for AI)
+formlm-cli snapshot --app <appId> --summary          # compact audit profile (batch verification)
+formlm-cli snapshot --app <appId> --with-values      # include report widget body text
 
 # Read a skill document before constructing commands
 formlm-cli skill form
@@ -130,25 +205,31 @@ formlm-cli skill scale
 formlm-cli scale query --app <appId>
 formlm-cli scale add --app <appId> --id stress --name "Stress Level" --format sum --kbText "..."
 formlm-cli scale keys add --app <appId> --scale stress --fields q1,q2,q3
-formlm-cli scale data add --app <appId> --scale stress --ranges "0-10:Low,11-20:Moderate,21-30:High"
+formlm-cli scale data add --app <appId> --scale stress --bands "Low:desc||Moderate:desc||High:desc"   # recommended: server auto-computes even boundaries + 999 sentinel
 
 # Report commands
 formlm-cli report query --app <appId>
-formlm-cli report page add --app <appId> --name "Summary" --layout grid
-formlm-cli report widget add --app <appId> --page <pageId> --type chart --chartType bar --name "Score Chart"
+formlm-cli report page add --app <appId> --name "Summary"                     # page type defaults to A4
+formlm-cli report widget add --app <appId> --page <pageId> --type scale-chart --format bar --scaleId <dim> --x 0 --y 0 --w 24 --h 12
+formlm-cli report widget logic add --app <appId> --page <pageId> --id <widgetId> --min 0 --max 20 --content "<p>Keep it up</p>"
 
-# Expert commands
+# Expert commands (--name and --kbText are required by the server)
 formlm-cli expert query --app <appId>
-formlm-cli expert config --app <appId> --enableChat true
+formlm-cli expert config --app <appId> --name "Career Coach" --role "资深职业规划师" --kbText "..." --theme Warm
+formlm-cli expert set --app <appId> --property enable --value true   # single-property toggle
+
+# Quality audit (read-only)
+formlm-cli doctor --app <appId>
+formlm-cli doctor --app <appId> --expect-lang en --deep
 ```
 
-### 6. Use as MCP Server
+### 7. Use as MCP Server
 
 ```bash
 formlm-cli mcp
 ```
 
-This starts the MCP Server (stdio transport) with 6 tools + 6 resources, ready for AI Agents to connect.
+This starts the MCP Server (stdio transport) with 9 tools + 6 resources, ready for AI Agents to connect.
 
 ---
 
@@ -156,11 +237,37 @@ This starts the MCP Server (stdio transport) with 6 tools + 6 resources, ready f
 
 ### Smart Pipeline (AI-recommended)
 
+There are two ways in: `smart plan` + `smart execute` (explicit, resumable — recommended for batches),
+or `smart generate`, which is a thin wrapper over exactly those steps:
+
 ```bash
-# Generate a complete app from natural language
-formlm-cli smart generate --input "..." [--plan-type assessment] [--style "温暖亲切"] [--question-count 10-15]
+# Phase 1 — plan only (creates the app, returns appId + tasks; cached server-side ~10min)
+formlm-cli smart plan --input "..." [--plan-type assessment] [--style "温暖亲切"] [--question-count 10-15] \
+  [--lang en] [--dimensions "Focus|Sleep|Load"] [--app-name "Team Focus Check"] \
+  [--save-plan plan.json] [--dry-run]
+
+# Phase 2 — execute one module at a time (form / scale / connect / report / expert / share)
+formlm-cli smart execute --app <appId> --module form
+formlm-cli smart execute --app <appId> --module scale --plan-file plan.json   # after the cache expired
+formlm-cli smart execute --app <appId> --module scale --clear-first          # re-run without duplicating dimensions
+
+# One-shot wrapper — plan → execute every module → optional publish → optional doctor
+formlm-cli smart generate --input "..." --plan-type assessment --lang en --publish --doctor
+formlm-cli smart generate --input "..." --only form,scale,report       # partial build
+formlm-cli smart generate --input "..." --skip connect                 # leave styling out
 ```
 
+> **Pinning vs. improvising.** By default the Plan AI invents dimension names/count and the app name, which
+> breaks page↔app consistency in batch runs. Use `--dimensions` to pin the dimension list (exact names + count)
+> and `--app-name` to pin the display name; verify afterwards with `snapshot --summary` (it reports `dimNames`).
+>
+> **`--dry-run`** validates a prompt/spec and deletes the probe app again (the server always creates an app when
+> planning), so experimentation leaves no residue.
+>
+> **Success is machine-readable**: `smart execute` returns `data.taskStatus` (`success` / `error`), and
+> `smart generate` returns `{appId, modules:[{module,status,error}], publish, doctor, resumeHint}` — trust those
+> fields, not the human wording. On a mid-run failure the app is kept and `resumeHint` gives the exact resume command.
+
 ### Snapshot
 
 ```bash
@@ -168,8 +275,38 @@ formlm-cli smart generate --input "..." [--plan-type assessment] [--style "温
 formlm-cli snapshot --app <appId>
 formlm-cli snapshot --app <appId> --module scale    # Only scale module
 formlm-cli snapshot --app <appId> --md             # Markdown format (token-efficient for AI)
+formlm-cli snapshot --app <appId> --summary        # Compact audit profile (counts/dim names/report pages/expert/share + shareToken)
+formlm-cli snapshot --app <appId> --with-values    # + report widget body text (per-page queries)
+formlm-cli snapshot --apps <id1,id2,...> --summary # Batch: N apps in ONE process (connection reuse, FORMLM_CONCURRENCY parallel apps, default 4)
+```
+
+Measured: 5 apps × 7 module queries = 35 requests in ~13s in a single process, versus one cold Node
+process per app before (the old serial-subprocess pattern took roughly 5× that, plus no connection reuse).
+
+`snapshot` is **client-synthesized**: it fans out to the 6 `assess <module> query` commands. There is no
+server-side `assess snapshot`, so calling that over raw `POST /api/v1/mcp/exec` returns 403 by design — loop
+the 6 queries yourself when you need HTTP-side batching. If a module fetch fails, the result carries
+`_errors` / `_degraded` (treat it as unknown, not as "empty module").
+
+### Doctor (read-only quality audit)
+
+```bash
+# One call per app: content/scoring coverage, expert sanity, styling,
+# unexpected certificate pages, share access semantics, link reachability
+formlm-cli doctor --app <appId>
+
+# Whole batch in one process (aggregate envelope; exit 1 if any app fails)
+formlm-cli doctor --apps <id1,id2,...> --expect-lang en
+
+# Add the language-consistency scan (classic batch defect: English app shipped with Chinese boilerplate)
+formlm-cli doctor --app <appId> --expect-lang en            # titles/labels
+formlm-cli doctor --app <appId> --expect-lang zh-hant --deep  # also scan report widget body text
+formlm-cli doctor --app <appId> --no-probe                  # skip the fill-in URL reachability probe
 ```
 
+Output is the standard envelope; `ok:false` + exit 1 when a `fail`-level finding exists, so batch drivers
+can gate on it. Each finding carries a ready-to-run `fix` command. Read-only — it never writes.
+
 ### Skill Documents
 
 ```bash
@@ -185,9 +322,9 @@ formlm-cli skill share      # Share/publish rules
 ### Auth
 
 ```bash
-formlm-cli auth login                 # Interactive login
-formlm-cli auth login --token <tok>   # Login with token
-formlm-cli auth status                # Check current login state
+formlm-cli auth login --token <tok>   # Login with Access Token (recommended: formlm.me → Account Settings)
+formlm-cli auth login                 # Interactive login — 1) Access Token, 2) email verification code (no password needed), 3) email + password
+formlm-cli auth status                # Check current login state (tokens expire after 7 days)
 formlm-cli auth logout                # Clear local token
 ```
 
@@ -203,11 +340,17 @@ formlm-cli --profile work app list    # Use a profile for one command
 ### App
 
 ```bash
-formlm-cli app list
+formlm-cli app list                                               # first page (latest 20)
+formlm-cli app list --all                                          # full inventory (server page size capped at 500)
+formlm-cli app list --limit 100 --page 2                           # explicit paging
+formlm-cli app list --all --with-urls                              # + published/shareType/sharePerm/shareDay/shareUrl/shareToken per app
+formlm-cli app list --name "wellness"                              # filter by app name
 formlm-cli app create --name "My Form" --description "..."
+formlm-cli app get --app <appId>
 formlm-cli app update --app <appId> --name "New Name" --theme blue
-formlm-cli app remove --app <appId>                        # Delete an app (irreversible)
-formlm-cli app urls --app <appId>                          # Get fill-in / editor / data URLs
+formlm-cli app delete --app <appId>                                # Delete an app (irreversible)
+formlm-cli app remove --app <appId>                                # alias of app delete
+formlm-cli app urls --app <appId>                                  # Get fill-in / editor / data URLs + shareToken
 ```
 
 ### Field
@@ -230,7 +373,7 @@ formlm-cli scale query --app <appId>                          # List all dimensi
 formlm-cli scale find --app <appId> --id <scaleId>            # Find a dimension
 formlm-cli scale add --app <appId> --id stress --name "Stress" --format sum --kbText "..."
 formlm-cli scale update --app <appId> --id stress --name "Stress Level"
-formlm-cli scale set --app <appId> --id stress --direction negative
+formlm-cli scale set --app <appId> --id stress --property direction --value negative
 formlm-cli scale remove --app <appId> --id stress
 formlm-cli scale clear --app <appId>
 formlm-cli scale config --app <appId> --enable-single true
@@ -242,7 +385,8 @@ formlm-cli scale keys list --app <appId> --scale stress
 formlm-cli scale keys set --app <appId> --scale stress --fields q3 --negScore true
 
 # Configure score ranges
-formlm-cli scale data add --app <appId> --scale stress --ranges "0-10:Low,11-20:High"
+formlm-cli scale data add --app <appId> --scale stress --bands "Low:desc||Moderate:desc||High:desc"   # recommended: server auto-computes even boundaries + 999 sentinel (ordered lowest→highest score)
+formlm-cli scale data add --app <appId> --scale stress --ranges "0-10:Low,11-20:High"                   # manual boundaries; only for non-even knowledge-specified thresholds
 formlm-cli scale data update --app <appId> --scale stress --id <dataId> --value "Moderate"
 formlm-cli scale data remove --app <appId> --scale stress --id <dataId>
 formlm-cli scale data list --app <appId> --scale stress
@@ -258,7 +402,7 @@ formlm-cli connect types [--category cover|main|final] --verbose
 formlm-cli connect config --category cover --format rich-text
 
 # Cover page management
-formlm-cli connect cover-page add --app <appId> --id cover_main --name "Welcome" --format text --value "<h1>Hello</h1>"
+formlm-cli connect cover-page add --app <appId> --id cover_main --name "Welcome" --format rich-text --value "<h1>Hello</h1>"
 formlm-cli connect cover-page update --app <appId> --id cover_main --name "New Title"
 formlm-cli connect cover-page find --app <appId> [--id cover_main]
 formlm-cli connect cover-page remove --app <appId> [--id cover_main]
@@ -286,50 +430,85 @@ formlm-cli connect style move --app <appId> --id <pageId> --direction up
 ```bash
 formlm-cli report query --app <appId>                           # List all report pages
 formlm-cli report find --app <appId> --filter <keyword>         # Find report widget
-formlm-cli report update --app <appId> --page <pageId> --name "New Name"
 
-# Page management
-formlm-cli report page add --app <appId> --name "Summary" --layout grid
-formlm-cli report page update --app <appId> --id <pageId> --name "Overview"
+# Note: update goes through the explicit owners — `report page update` (page name/bg/style/svg)
+# and `report widget update` (widget props). The server also accepts the merged
+# `assess report update --page <pageId> [--id <widgetId>]` form on the raw exec channel.
+
+# Page management (a page is a 48-col × 68-row grid canvas; layout comes from widget x/y/w/h, not a page flag)
+formlm-cli report page add --app <appId> --name "Summary" [--type A4]
+formlm-cli report page update --app <appId> --id <pageId> --name "Overview"      # fails if the id does not exist
+formlm-cli report page update --app <appId> --id <pageId> --name "Overview" --upsert   # opt into the server upsert (creates a blank page)
 formlm-cli report page remove --app <appId> --id <pageId>
+formlm-cli report page remove --app <appId> --name "结业证书"                       # locate by human-readable name
 
-# Widget management
+# Widget management (every widget command needs --page; set/find/update/remove also need --id)
 formlm-cli report widget list --app <appId> --page <pageId>
-formlm-cli report widget find --app <appId> --filter <keyword>
-formlm-cli report widget set --app <appId> --id <widgetId> --value "{{TotalScore}}"
-formlm-cli report widget add --app <appId> --page <pageId> --type chart --chartType bar --name "Score Chart"
-formlm-cli report widget update --app <appId> --id <widgetId> --name "Updated Chart"
-formlm-cli report widget remove --app <appId> --id <widgetId>
-formlm-cli report widget types --category chart
-formlm-cli report widget config --type chart --prop chartType
-
-# Logic rules
-formlm-cli report logic add --app <appId> --page <pageId> --condition "score>20" --action show
-formlm-cli report logic list --app <appId> --page <pageId>
-formlm-cli report logic remove --app <appId> --id <logicId>
+formlm-cli report widget find --app <appId> --page <pageId> --id <widgetId>          # full detail incl. HTML value
+formlm-cli report widget set --app <appId> --page <pageId> --id <widgetId> --property value --value "{{TotalScore}}"
+formlm-cli report widget add --app <appId> --page <pageId> --type scale-chart --format bar --scaleId <dim> --x 0 --y 0 --w 24 --h 12
+formlm-cli report widget update --app <appId> --page <pageId> --id <widgetId> --name "Updated Chart"
+formlm-cli report widget remove --app <appId> --page <pageId> --id <widgetId>
+formlm-cli report widget types --verbose                                             # all widget types (+ descriptions)
+formlm-cli report widget config --type scale-chart                                   # configurable properties of one type
+
+# Conditional display rules (logic lives UNDER widget)
+formlm-cli report widget logic add --app <appId> --page <pageId> --id <widgetId> --min 0 --max 20 --content "<p>Low band text</p>"
+formlm-cli report widget logic list --app <appId> --page <pageId> --id <widgetId>
+formlm-cli report widget logic remove --app <appId> --page <pageId> --id <widgetId> --logicId <logicId>
 ```
 
 ### Expert (AI Interpretation)
 
 ```bash
-formlm-cli expert query --app <appId>                    # Query expert config
-formlm-cli expert find --app <appId>                     # Find expert details
-formlm-cli expert config --app <appId> --enableChat true # Full configuration
-formlm-cli expert set --app <appId> --key model --value gpt-4
-formlm-cli expert avatar --app <appId> --name "Dr. AI" --avatar <url>
+formlm-cli expert query --app <appId>                    # Query expert config (--md for a compact table)
+formlm-cli expert find --app <appId>                     # Full config incl. prompt/welcome text
+formlm-cli expert config --app <appId> --name "Dr. AI" --role "Career coach" \
+  --kbText "..." [--welcome ...] [--question1 ...] [--theme Warm] [--enable true]   # create/update (name + kbText required)
+formlm-cli expert set --app <appId> --property enable --value true    # single-property toggle;
+                                                                        # properties: name/role/description/style/welcome/
+                                                                        # prompt/question1..3/kbText/enable/enableWelcome/theme
+formlm-cli expert avatar --app <appId> --url <url> --enable true      # needs an existing expert (config first)
 formlm-cli expert remove --app <appId>
-formlm-cli expert chat --app <appId> --message "Explain my score"
+formlm-cli expert chat --app <appId> --input "Explain my score"
 ```
 
-### Share
+> Boolean flags are forwarded space-separated (`--enable true`), never `--enable=true` — the server parses them
+> with picocli `arity 0..1`. `expert config` enables the agent by default; pass `--enable false` to configure it
+> while leaving it switched off.
+
+### Share (Publish & Access)
 
 ```bash
-formlm-cli share publish --app <appId>      # Publish (each respondent can submit once; unlimited respondents)
-formlm-cli share unpublish --app <appId>    # Unpublish
-formlm-cli share query --app <appId>        # Check publish status
-formlm-cli share url --app <appId>          # Get the shareable URL
+# Access types (know these — "public" is ambiguous):
+#   visitor = anonymous, no login required  → "anyone can fill" (the usual public form)
+#   all     = every LOGGED-IN FormLM user   → anonymous visitors hit the login page
+#   secret  = password-protected   |   owner = creator only   |   no = unpublish
+formlm-cli share publish --app <appId>                      # anonymous (visitor) + one submission + permanent
+formlm-cli share publish --app <appId> --access all --perm 2 --days 14    # explicit control
+formlm-cli share publish --app <appId> --no-style            # skip the automatic style fallback
+formlm-cli share set --app <appId> --type visitor --perm 1 --day 0        # raw server parameters (idempotent)
+formlm-cli share unpublish --app <appId>
+formlm-cli share query --app <appId>                        # authoritative type/perm/day triple
+formlm-cli share verify --app <appId>                       # published + anonymous + permanent + reachability in one call
+formlm-cli share url --app <appId>                          # URLs incl. shareToken
+formlm-cli share api --app <appId>                          # Configure the Data API (form backend endpoint)
+formlm-cli share api --app <appId> --submit true --query true --auto-create true
 ```
 
+> **Validity rule (server-side):** only `--days 1..30` are honoured as a finite window; `0`, `forever`, or anything
+> above 30 normalizes to permanent (sentinel `3650000`). There is no 90-day/1-year publish window on this channel.
+>
+> **Verifying "anyone can access":** `curl` returning 200 on the share URL proves nothing — the SPA shell answers 200
+> even behind the login gate. Use `share verify` (or read `share query`'s type/perm/day triple).
+>
+> **`smart execute --module share` vs `share publish`:** the pipeline's share module applies the plan's publish
+> settings; `share publish` is the explicit, idempotent CLI entry that also guarantees anonymous + permanent
+> defaults and prints the final URLs/`shareToken`. Re-running `share publish` is safe. If you never styled the
+> app, publish auto-applies a default style first (30-120s AI generation) — pass `--no-style` to skip that.
+
+The Data API turns a form into an HTTP data endpoint: `POST` JSON to the endpoint (or use the `/form` path for native HTML forms), read records back via the query endpoint, and hand the `?help` URL to an AI agent so it can discover the API on its own.
+
 ---
 
 ## MCP Integration
@@ -338,18 +517,21 @@ FormLM CLI works as a standard MCP Server over stdio and plugs into **any MCP-co
 
 > **⚠️ macOS/Linux users:** desktop AI clients often launch the MCP server without your full terminal PATH, which can cause `command not found` errors. See **[INSTALL.md → Step 4](INSTALL.md#step-4--connect-to-an-ai-agent-mcp-mode)** for the `env.PATH` fix, per-platform config file locations (including Codex CLI's TOML format), and the full setup guide.
 
-> **No token? No problem.** If you omit `FORMLM_TOKEN`, the AI will prompt you to authenticate via the `auth_login` tool — just provide your email + password (or token) directly in the chat.
+> **No token? No problem.** If you omit `FORMLM_TOKEN`, the AI will prompt you to authenticate via the `auth_login` tool — paste your Access Token (from formlm.me → Workspace → Account Settings; recommended), complete an in-chat email verification-code login via `auth_email_code` (no browser needed), or use email + password directly in the chat.
 
 ---
 
-## Available MCP Tools (6)
+## Available MCP Tools (9)
 
 | Tier | Tool | Description |
 |---|---|---|
-| 0 | `auth_login` | Login with token or email + password |
+| 0 | `auth_login` | Login with Access Token (recommended), email verification code, or email + password |
+| 0 | `auth_email_code` | Email verification-code login — fetch the captcha image & send the code (fully in-chat) |
 | 0 | `auth_status` | Check current login status |
-| 1 | `formlm_generate` | Generate a complete app from natural language (AssessAgent pipeline) |
-| 2 | `formlm_snapshot` | Get aggregated state of all modules (form/scale/connect/report/expert/share) |
+| 1 | `formlm_generate` | Generate the execution plan (Phase 1: creates the app, returns appId + tasks) |
+| 1 | `formlm_execute` | Execute plan modules one by one after `formlm_generate` |
+| 2 | `formlm_doctor` | Read-only quality audit of one app (scoring coverage, dead experts, styling, certificate pages, language consistency, share access, reachability) |
+| 2 | `formlm_snapshot` | Aggregated state of all modules; `summary: true` returns the compact audit profile |
 | 2 | `formlm_skill` | Fetch SKILL.md domain knowledge for a skill module |
 | 3 | `formlm_exec` | Execute any whitelisted CLI command directly |
 
@@ -371,7 +553,86 @@ FormLM CLI works as a standard MCP Server over stdio and plugs into **any MCP-co
 | Variable | Description |
 |---|---|
 | `FORMLM_BASE_URL` | FormLM server URL (default: `https://formlm.me`) |
-| `FORMLM_TOKEN` | Your auth token (alternative to `auth login`) |
+| `FORMLM_TOKEN` | Your auth token (alternative to `auth login`; keeps secrets out of shell history) |
+| `FORMLM_JSON=1` | Machine output: every command prints ONE parseable line `{ok,code,message,data}` on stdout (equivalent to the global `--json` flag) |
+| `FORMLM_NO_EXIT=1` | Batch safety: never `process.exit()` on failure — a bad command cannot kill your driver loop (errors surface as `ok:false` envelopes / thrown errors) |
+| `FORMLM_TIMEOUT_MS` | Default per-command request timeout (ms, default 60000) |
+| `FORMLM_TIMEOUT_PLAN` / `FORMLM_TIMEOUT_EXECUTE` / `FORMLM_TIMEOUT_STYLE` | Override the smart-plan (120s), smart-execute (300s) and style (600s) timeouts |
+| `FORMLM_RETRIES` | Max attempts for transient failures (default 3). Read-only commands retry on 408/429/5xx; writes are never auto-retried |
+| `FORMLM_CONCURRENCY` | In-process parallelism for batch commands (`snapshot --apps`, `doctor --apps`), default 4 |
+
+---
+
+## Scripting & Batch Use
+
+```bash
+# One parseable line per command; guidance/hints go to stderr, stdout stays clean:
+FORMLM_JSON=1 FORMLM_NO_EXIT=1 formlm-cli snapshot --app <appId> --summary
+FORMLM_JSON=1 formlm-cli share verify --app <appId>        # {ok, data:{type,forever,anonymous,httpStatus,shareToken}}
+FORMLM_JSON=1 formlm-cli doctor  --app <appId> --expect-lang en   # ok:false when a fail-level finding exists
+
+# Whole batch in one process (no per-app Node cold start; tunable with FORMLM_CONCURRENCY):
+FORMLM_JSON=1 formlm-cli doctor   --apps id1,id2,id3 --expect-lang en
+FORMLM_JSON=1 formlm-cli snapshot --apps id1,id2,id3 --summary
+```
+
+Envelope: `{ "ok": bool, "code": int, "message": string, "data": object|null }` — `data` is always parsed
+(no double-decoding needed), and validation/parameter errors now come back with a non-zero `code`
+instead of hiding the error text inside `data` while reporting success.
+
+### Status codes
+
+| Code | Meaning | What to do |
+|---|---|---|
+| `0` | Success | — |
+| `207` | Partial (multi-module reads where one module failed) | Result carries `_errors`/`_degraded`; re-check that module, don't assume it is empty |
+| `400` | Bad request / parameter or validation error | Read `message`; the server echoes picocli's hint (valid values, missing option) |
+| `401` | Not authenticated | `formlm-cli auth login --token-stdin` (or set `FORMLM_TOKEN`) |
+| `403` | Command not on the exec whitelist, or wrong credentials/verification code | See the whitelist below; for MCP check `auth_status` |
+| `408` | Request timed out client-side | Retry read-only; for `smart execute` re-run that module (writes are not auto-retried) |
+| `429` | Rate limited (login attempts, send-code quotas) | Wait, then retry with backoff |
+| `500` | Transport failure or server error | Retried automatically for read-only commands |
+
+### Raw `POST /api/v1/mcp/exec` whitelist
+
+The exec channel accepts 3-token command paths only (`assess <module> <action>`). Everything else returns
+`403 not allowed via MCP` **by design** — notably `assess snapshot` and `assess field …` do not exist on the
+server (they are client-side wrappers), so batch HTTP consumers must call the underlying queries:
+
+```
+assess app      list | create | use | current | update | remove | urls
+assess form     query | find | types | config | add | update | remove | move | set-property
+assess scale    query | find | add | update | set | remove | clear | config | keys | data
+assess connect  query | find | types | config | cover-page | final-page | main-page | style
+assess report   query | find | update | page | widget        (conditional logic is `report widget logic …`)
+assess expert   query | find | config | set | avatar | remove | chat
+assess share    set | query | url | api | flavor
+assess smart    plan | execute
+assess skill    form | scale | connect | report | expert | share
+```
+
+### Throughput notes
+
+- Every CLI invocation is a fresh Node process plus its own HTTP calls; for large batches, run independent
+  apps concurrently (the server tolerates moderate parallelism) rather than serially.
+- `snapshot`/`doctor` fan out their module queries in parallel; use `--module` / `--summary` to keep payloads small.
+- Slow server? Raise `FORMLM_TIMEOUT_MS` and `FORMLM_RETRIES` instead of hand-rolling retry loops.
+- Batch over many apps **inside one process**: `snapshot --apps …` / `doctor --apps …`, or import the built
+  module directly (`import { execCommand } from '@formlm/cli/dist/exec.js'`) and loop — HTTP connections are
+  reused and there is no per-app Node cold start.
+
+### Version coupling (CLI ↔ server)
+
+Some commands rely on server options added together with them; against an older server they fail with a
+visible `400 Unknown option …` (never a silent success, thanks to the false-success guard):
+
+| Needs server support | Command / flag |
+|---|---|
+| ✔ | `app list --all / --limit / --page / --with-urls` |
+| ✔ | `app urls` native `shareToken` + `published/shareType/…` (the CLI fills `shareToken` from `shareUrl` as a fallback) |
+| ✔ | `report page remove --name "…"` (name→id resolution moved server-side, so raw exec benefits too) |
+| ✔ | `expert config --enable true\|false` (fall back to `expert set --property enable` on an old server) |
+| ✔ | `smart plan --dimensions / --app-name`, `smart execute --plan-file` (`--plan-b64` transport) |
 
 ---
 
@@ -388,7 +649,7 @@ FormLM CLI works as a standard MCP Server over stdio and plugs into **any MCP-co
 
 Have questions, feedback, or need help getting started?
 
-📧 **[formlm.me@gmail.com](mailto:formlm.me@gmail.com)**
+📧 **[hello@formlm.me](mailto:hello@formlm.me)**
 
 Feel free to reach out — we're happy to help.
 

package/dist/commands/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/commands/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA8ExD"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/commands/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBpC,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAwHxD"}