docs: redesign bilingual product README

README.md

@@ -1,104 +1,137 @@
-# FlowForge
-
-> 用自然语言生成一个可运行、可检查、可持续修改的轻量网页应用。
-
-FlowForge 是一个 Atoms-like AI Builder。用户描述业务需求后，系统先生成可编辑的产品计划；确认计划后，再由 Architect 生成受约束的 `AppSpec`，经过确定性编译、静态校验和沙箱握手，最终在浏览器里运行真实应用。
-
-![FlowForge Dashboard：输入需求、选择主题并查看示例](./assets/readme/dashboard.jpg)
-
-![FlowForge Studio：真实构建流水线和生成应用预览](./assets/readme/studio-preview.jpg)
-
-## 已实现
-
-- 自然语言创建项目，不依赖固定模板；
-- Planner 生成结构化计划，用户可编辑标题、目标用户、主题、字段、功能和假设；
-- Planner / Architect 与 Compiler / Verifier / Preview Handshake 明确区分；
-- 可停止的真实构建流程、不可变版本和失败保护；
-- sandbox iframe 中运行生成应用；
-- 生成应用支持新增、编辑、删除、搜索、筛选、状态变化和统计；
-- Project、Plan、Version 和生成应用业务数据均持久化到 IndexedDB；
-- Desktop / Tablet / Mobile 三档预览、刷新和只读源码；
-- 真实 Build Terminal、ArtifactVerifier 检查、Issue Report 和 Runtime Console；
-- 继续用自然语言创建新版本，失败不覆盖最后成功版本；
-- P1 延展：将当前版本重新编译为 standalone HTML 并下载，离线打开后可用 `localStorage` 保存数据；
-- Fixture 与真实 AI 结果显示不同 provenance，避免把演示数据伪装成模型输出。
-
-## 三分钟体验路径
-
-1. 在 Dashboard 点击“活动报名管理”示例；
-2. 选择一个主题偏好并创建项目；
-3. 在 Plan Review 中检查或编辑计划，然后点击“确认并构建”；
-4. 在 Preview 中新增、编辑、筛选和删除一条报名记录；
-5. 切换桌面、平板和手机宽度；
-6. 打开“问题 / Console”查看 11 项真实校验；
-7. 切到“动态”查看持久化的 BuildAttempt / RunEvent；
-8. 点击“导出 HTML”下载可离线运行的单文件应用；
-9. 刷新页面，确认项目、版本和业务记录仍在。
-
-## 工作原理
-
-```mermaid
-flowchart LR
-  A["自然语言 Prompt"] --> B["Planner<br/>AI Agent"]
-  B --> C["Plan Review<br/>人工确认"]
-  C --> D["Architect<br/>AI Agent"]
-  D --> E["App Compiler<br/>确定性程序"]
-  E --> F["ArtifactVerifier<br/>确定性程序"]
-  F --> G["Preview Handshake<br/>沙箱运行门"]
-  G --> H["Immutable Version"]
-  H --> I["App Viewer<br/>CRUD + IndexedDB"]
-  I --> J["自然语言修订"]
-  J --> D
-```
+<p align="center">
+  <strong>English</strong> · <a href="./README.zh-CN.md">简体中文</a>
+</p>
+
+<h1 align="center">
+  <img src="./assets/readme/hero.svg" width="100%" alt="FlowForge turns one prompt into a verified, runnable browser app">
+</h1>
+
+<p align="center">
+  <a href="https://github.com/Totoro-qaq/flowforge/actions/workflows/ci.yml"><img src="https://github.com/Totoro-qaq/flowforge/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
+  <a href="https://github.com/Totoro-qaq/flowforge/actions/workflows/codeql.yml"><img src="https://github.com/Totoro-qaq/flowforge/actions/workflows/codeql.yml/badge.svg?branch=main" alt="CodeQL status"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/github/license/Totoro-qaq/flowforge" alt="MIT license"></a>
+</p>
+
+FlowForge turns a natural-language product brief into a reviewable plan and a
+local-first CRUD app. The model produces typed `ProductPlan` and `AppSpec`
+data; a trusted compiler, artifact verifier, and sandbox handshake create and
+admit the executable result.
+
+## See FlowForge work
+
+<p align="center">
+  <img src="./assets/readme/studio-preview.jpg" width="100%" alt="FlowForge Studio showing the build pipeline, verifier, generated registration app, and version controls">
+</p>
+
+> Fixture-mode walkthrough shown. The pipeline, compiler, verifier, sandbox
+> handshake, generated runtime, and persistence are real; only the model
+> responses use reviewed fixtures.
+
+<p align="center">
+  <img src="./assets/readme/dashboard.jpg" width="100%" alt="FlowForge dashboard with a product brief composer, theme choices, and built-in examples">
+</p>
+
+Start from a brief, review the proposed product plan, build a version, use the
+generated app, and continue with natural-language revisions when a live AI
+provider is configured.
+
+## What you get
+
+- **A review checkpoint before compilation.** Edit and approve the title,
+  audience, fields, features, assumptions, and theme before a build begins.
+- **Constrained generation.** The AI produces structured plans and app specs;
+  FlowForge does not execute arbitrary model-generated code.
+- **A runnable data app.** Generated apps support create, edit, delete, search,
+  optional filters, and summary counts for one core entity.
+- **Failure-safe versions.** Successful builds are stored as immutable
+  versions; a failed build never replaces the current working version.
+- **Inspectable runtime behavior.** Desktop, tablet, and mobile previews sit
+  beside source, build events, artifact checks, and runtime diagnostics.
+- **Local-first persistence and export.** Projects, versions, and records stay
+  in IndexedDB. A version can also be recompiled into a standalone HTML file
+  with its own fresh `localStorage` data.
+
+## How it works
+
+<p align="center">
+  <img src="./assets/readme/workflow.svg" width="100%" alt="FlowForge workflow from prompt and plan review through trusted compilation, verification, sandbox preview, and an immutable version">
+</p>
 
-模型只负责生成受约束的 `ProductPlan` / `AppSpec`。模型输出不会作为任意代码直接执行；HTML、CSS、运行时桥接和 CRUD 代码均由可信编译器生成，并在保存版本前经过 Schema、CSP、外部资源、动态代码、字段引用、CRUD 控件和稳定节点清单等检查。
+The trust boundary is deliberate: the model proposes structured data, while
+deterministic code owns HTML, CSS, the CRUD runtime, content security policy,
+artifact checks, and preview admission.
 
-## 本地运行
+## Quick start — no API key required
 
-要求 Node.js 22 或更高版本。
+Requires Node.js 22 or newer.
 
 ```bash
-npm install
+git clone https://github.com/Totoro-qaq/flowforge.git
+cd flowforge
+npm ci
 cp .env.example .env.local
-npm run dev
 ```
 
-### 无模型密钥的开发演示
+For the keyless development path, set these values in `.env.local`:
+
+```dotenv
+AI_FIXTURE_MODE=true
+RATE_LIMIT_BACKEND=memory
+```
 
-将 `.env.local` 中的 `AI_FIXTURE_MODE` 改为 `true`。Fixture 模式只接受以下三个经过审查的精确示例：
+Then start the app:
 
-- 活动报名管理；
-- 通用任务列表；
-- 库存清单。
+```bash
+npm run dev
+```
 
-Fixture 仅用于本地开发和稳定回归，生产环境会强制拒绝开启它。
+Open [http://localhost:3000](http://localhost:3000), click one of the three
+built-in example cards, keep the semantic plan unchanged, and confirm the
+build. Theme changes are supported in this path.
 
-### 接入真实 AI
+Fixture mode is intentionally narrow:
 
-FlowForge 使用 OpenAI-compatible Chat Completions 接口，并要求模型支持 JSON Object 输出。
+- it accepts only the exact prompts inserted by the built-in example cards;
+- changing plan semantics such as fields or features breaks fixture matching;
+- natural-language revision is unavailable;
+- production rejects fixture mode and the in-memory rate limiter.
+
+## Connect a live AI provider
+
+FlowForge calls an OpenAI-compatible Chat Completions endpoint and requires a
+model that supports JSON Object responses.
 
 ```dotenv
-AI_API_KEY=your-key
+AI_API_KEY=your-server-only-key
 AI_BASE_URL=https://api.openai.com/v1
 AI_MODEL=your-json-capable-model
 AI_FIXTURE_MODE=false
 ```
 
-`AI_BASE_URL` 可以省略，默认使用 `https://api.openai.com/v1`。密钥仅在服务端读取，不使用 `NEXT_PUBLIC_` 前缀。
+`AI_BASE_URL` is optional and defaults to `https://api.openai.com/v1`. Never
+prefix the key with `NEXT_PUBLIC_`, and never commit `.env.local`.
+
+CI and fixture tests do not validate a live model. Before publishing a
+deployment, run one complete prompt, build, CRUD, and revision flow with the
+exact provider and model you configured.
 
-## 验证
+## Verify the repository
 
 ```bash
 npm run lint
 npm test
 npm run build
 ```
 
-当前自动化覆盖领域 Schema、Fixture 匹配、Agent 修订约束、可信编译器、ArtifactVerifier、持久化查询、时间线和 standalone HTML 导出。核心交互另在浏览器中验证，包括完整生成流程、预览 CRUD、刷新后数据恢复、三档设备宽度、诊断面板和 320 / 375px 窄屏布局。
+The automated suite covers domain schemas, reviewed fixtures, constrained
+revision rules, compilation, artifact verification, persistence queries,
+runtime messaging, and standalone export.
 
-## 部署到 Vercel
+## Deploy to Vercel
 
-本项目不需要自购云服务器。推荐把 public GitHub 仓库导入 Vercel，并在项目设置中配置：
+You do not need to rent a server. Import this public repository from
+[Vercel's New Project page](https://vercel.com/new), then configure the
+following Production environment variables:
 
 ```dotenv
 AI_API_KEY=...
@@ -107,45 +140,56 @@ AI_MODEL=...
 AI_FIXTURE_MODE=false
 
 APP_ORIGIN=https://your-project.vercel.app
-SESSION_SIGNING_SECRET=至少 32 个字符的随机值
+SESSION_SIGNING_SECRET=<output-of-openssl-rand-hex-32>
 
 RATE_LIMIT_BACKEND=redis
-RATE_LIMIT_STORE_URL=Upstash-compatible REST URL
+RATE_LIMIT_STORE_URL=your-upstash-compatible-rest-url
 RATE_LIMIT_STORE_TOKEN=...
 RATE_LIMIT_MAX=5
 RATE_LIMIT_WINDOW_SECONDS=600
 ```
 
-生产环境要求共享 Redis 限流，避免 serverless 实例之间各自计数。部署后先访问 `/api/health`，再用无痕窗口走一次完整主流程。
+Generate a signing secret locally with `openssl rand -hex 32`. After Vercel
+assigns the production URL, set `APP_ORIGIN` to that exact origin and redeploy.
+The Redis-backed limiter is required because serverless instances cannot share
+an in-memory counter.
+
+After deployment:
+
+1. Visit `/api/health` to confirm the application is reachable. This is a
+   liveness endpoint, not a provider or Redis readiness check.
+2. In a private browser window, run a full live-provider build and CRUD flow.
+3. Trigger one revision and confirm a new version is saved.
+
+## Data and safety boundaries
 
-## 数据与安全边界
+- Builder projects, versions, build events, and app records live in the current
+  browser's IndexedDB; there are no accounts or cross-device sync.
+- Clearing site data removes locally stored projects and records.
+- Previewed apps run in an opaque-origin iframe sandbox. Runtime messages check
+  both the active iframe source and a one-time nonce.
+- Generated artifacts deny external scripts, default network access, nested
+  frames, navigation, and dynamic code through CSP and static verification.
+- A failed build attempt never replaces the last successful version.
+- Exported HTML starts with a separate, empty local data store; it does not
+  copy records from the Builder.
 
-- 项目、版本和业务记录只保存在当前浏览器，不跨设备同步；
-- 清除站点数据会删除本地项目；
-- 已生成应用及其本地数据可离线操作，创建或修改应用仍需连接 AI 服务；
-- 预览 iframe 使用 `sandbox="allow-scripts allow-forms"`，没有同源权限；
-- Runtime Bridge 同时校验当前 iframe 的 `source` 和一次性 nonce；
-- 产物 CSP 禁止默认网络访问、外部脚本、嵌套 iframe、导航和动态代码执行；
-- 生成请求有匿名签名会话、同源检查、并发锁和共享限流；
-- 失败 Attempt 不会覆盖最后成功 Version。
+## Current scope
 
-## 关键取舍
+- Single-page, single-entity table apps with 2–6 fields.
+- Field types: text, number, date, boolean, and select.
+- Each project is limited to 20 saved versions and 200 app records.
+- No arbitrary code, third-party packages, connectors, multi-page apps,
+  collaboration, cloud database, sharing, or one-click hosting for generated
+  apps.
+- Destructive revisions that delete a field or change an existing field type
+  are rejected to protect stored records.
+- The Builder interface is currently Chinese-first.
 
-| 取舍 | 原因 |
-|---|---|
-| Next.js + TypeScript，而不是 Python Web UI | 同一工程完成交互、服务端 AI 代理、部署和浏览器持久化，减少跨语言与跨服务复杂度 |
-| 单实体、单页、表格型应用 | 把时间投入真实生成、运行、持久化、校验和失败保护 |
-| 可信编译器，而不是执行模型代码 | 输出可预测、可校验，也更容易解释安全边界 |
-| IndexedDB，而不是临时内存 | 满足刷新后仍可继续使用，同时不引入登录和云数据库 |
-| 计划确认后才构建 | 给用户一个明确的人机协作检查点 |
-| HTML Export 作为 P1 | 行为完整、易验证，且不会扩大在线发布和权限系统范围 |
+## Stack
 
-## 当前边界
+Next.js 16 · React 19 · TypeScript · Zod · Vitest · IndexedDB
 
-- 只生成单页、单核心实体、2–6 个字段的轻量数据应用；
-- 不支持多页面、任意第三方依赖、Shell、Monaco、Connector、Publish、Share 或云端同步；
-- 删除字段或改变既有字段类型的增量修改会被拒绝，以保护现有业务数据；
-- Builder 本身可以部署到公网，但生成应用的独立公网发布不在本次范围；
-- 任意 Prompt 和自然语言修订需要真实 AI Provider；Fixture 不冒充完整模型能力。
+## License
 
-公开仓库只保留与产品使用、架构和安全边界直接相关的说明；内部探索稿、时间盒计划与提交材料不属于产品文档。
+FlowForge is available under the [MIT License](./LICENSE).