+
+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
+
+
+
+
+
+> Fixture-mode walkthrough shown. The pipeline, compiler, verifier, sandbox
+> handshake, generated runtime, and persistence are real; only the model
+> responses use reviewed fixtures.
+
+
+
+
+
+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
+
+
+
+
-模型只负责生成受约束的 `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
@@ -94,11 +123,15 @@ 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=
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).
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..7728916
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,180 @@
+
+
+ 
+ 
+
+
+