docs: reposition loopforge as personal ai engineer

rexleimo · rexleimo · commit af3dc5e4f4d1 · 2026-03-05T23:34:24.000+08:00
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-LoopForge (formerly RexOS) is a long-running agent operating system: persistent memory, tool sandboxing, and model routing, plus an Anthropic-style harness for multi-session work.
+LoopForge (formerly RexOS) is a **personal AI engineer** for software delivery: long-running workflows, persistent memory, tool sandboxing, and model routing with harness checkpoints.
 
 ## Brand update
 
@@ -14,6 +14,8 @@ LoopForge (formerly RexOS) is a long-running agent operating system: persistent
 
 - Docs site: https://os.rexai.top
 - (If the custom domain isn’t configured yet) GitHub Pages: https://rexleimo.github.io/rexos/
+- 5-minute outcomes: `docs-site/tutorials/five-minute-outcomes.md`
+- Positioning: `docs-site/explanation/why-loopforge.md`
 
 ## Status
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-LoopForge（原 RexOS）是一个长任务的 Agent OS：持久化记忆、工具沙盒、模型路由，以及一个 Anthropic 风格的 Harness，用于跨多次会话持续推进任务。
+LoopForge（原 RexOS）是一个面向软件交付的 **个人研发助理（Personal AI Engineer）**：长任务流程、持久化记忆、工具沙盒、模型路由与 Harness checkpoint。
 
 ## 品牌更新
 
@@ -14,6 +14,8 @@ LoopForge（原 RexOS）是一个长任务的 Agent OS：持久化记忆、工
 
 - 文档站点：https://os.rexai.top
 - （如自定义域名未配置）GitHub Pages：https://rexleimo.github.io/rexos/
+- 5 分钟可见结果：`docs-site/tutorials/five-minute-outcomes.md`
+- 产品定位说明：`docs-site/explanation/why-loopforge.md`
 
 ## 状态
 
diff --git a/docs-site/blog/index.md b/docs-site/blog/index.md
@@ -4,11 +4,13 @@ Practical notes for builders choosing an Agent OS and scaling from local prototy
 
 ## Latest posts
 
+- [LoopForge: Personal AI Engineer, Not Just Another Assistant](personal-ai-engineer.md)
 - [What Is LoopForge?](what-is-loopforge.md)
 - [LoopForge vs OpenFang/OpenClaw](rexos-vs-openfang-openclaw.md)
 
 ## Suggested reading order
 
-1. Brand + product fit: [What Is LoopForge?](what-is-loopforge.md)
-2. First successful run: [Quickstart](../tutorials/quickstart-ollama.md)
-3. Positioning and alternatives: [LoopForge vs OpenFang/OpenClaw](rexos-vs-openfang-openclaw.md)
+1. Positioning narrative: [LoopForge: Personal AI Engineer, Not Just Another Assistant](personal-ai-engineer.md)
+2. Brand + product fit: [What Is LoopForge?](what-is-loopforge.md)
+3. First successful run: [5-Minute Outcomes](../tutorials/five-minute-outcomes.md)
+4. Positioning and alternatives: [LoopForge vs OpenFang/OpenClaw](rexos-vs-openfang-openclaw.md)
diff --git a/docs-site/blog/personal-ai-engineer.md b/docs-site/blog/personal-ai-engineer.md
@@ -0,0 +1,40 @@
+# LoopForge: Personal AI Engineer, Not Just Another Assistant
+
+If users ask "what can this do for me right now?", answer with outcomes:
+
+- fix report for one failing test
+- release readiness memo
+- provider routing plan with cost/performance trade-offs
+
+That is LoopForge's core angle.
+
+## The narrative gap
+
+Many products lead with "assistant" language.
+LoopForge should lead with "shipping work":
+
+1. You give a concrete engineering goal
+2. LoopForge executes in a workspace
+3. You get persistent artifacts you can review and commit
+
+## Position in one sentence
+
+LoopForge is your **personal AI engineer** for reproducible software delivery.
+
+## 3 examples to show in demos
+
+1. "Fix one failing test and write `notes/fix-report.md`"
+2. "Audit release readiness and write `notes/release-readiness.md`"
+3. "Plan provider routing and write `notes/provider-plan.md`"
+
+## Why this framing works
+
+- It matches developer pain
+- It differentiates from consumer assistant products
+- It makes value visible in minutes
+
+## Next links
+
+- [5-minute outcomes](../tutorials/five-minute-outcomes.md)
+- [Why LoopForge](../explanation/why-loopforge.md)
+- [Case tasks](../examples/case-tasks/index.md)
diff --git a/docs-site/explanation/why-loopforge.md b/docs-site/explanation/why-loopforge.md
@@ -0,0 +1,32 @@
+# Why LoopForge
+
+LoopForge is not trying to be a generic life assistant.
+It is built as a **personal AI engineer** for software delivery.
+
+## Positioning
+
+| Product style | Primary value |
+|---|---|
+| Personal life assistant | Daily chat, lifestyle help, broad consumer tasks |
+| Channel-heavy operations platform | Multi-channel operations and adapter breadth |
+| LoopForge | Reproducible engineering workflows and shipping artifacts |
+
+## What LoopForge optimizes for
+
+1. Reproducible execution (`change -> verify -> checkpoint`)
+2. Local-first bring-up (Ollama first, cloud routing optional)
+3. Durable artifacts (reports, checklists, summaries in workspace)
+4. Audit-friendly traces (session + memory + outputs)
+
+## What this means for teams
+
+- Easier handoff between engineers
+- Easier rollback because checkpoints are explicit
+- Easier review because outputs are files, not only chat logs
+
+## If you evaluate us in 10 minutes
+
+Run these:
+1. [5-minute outcomes](../tutorials/five-minute-outcomes.md)
+2. [Fix one failing test task](../examples/case-tasks/fix-one-failing-test.md)
+3. [Release readiness audit task](../examples/case-tasks/release-readiness-audit.md)
diff --git a/docs-site/index.md b/docs-site/index.md
@@ -2,14 +2,18 @@
 
 # LoopForge
 
-**Long-running Agent OS**: harness + SQLite memory + sandboxed tools + multi-provider routing.
+**Your Personal AI Engineer for real shipping work.**
 
-[Get started](tutorials/quickstart-ollama.md){ .md-button .md-button--primary }
+From prompt to deliverable artifacts: fix report, release checklist, research memo, and reproducible checkpoints.
+
+[Start in 5 minutes](tutorials/five-minute-outcomes.md){ .md-button .md-button--primary }
+[What it can do](examples/case-tasks/index.md){ .md-button }
+[Why LoopForge](explanation/why-loopforge.md){ .md-button }
 [Quick intro](blog/what-is-loopforge.md){ .md-button }
-[Providers](how-to/providers.md){ .md-button }
+[Personal AI Engineer](blog/personal-ai-engineer.md){ .md-button }
 
 <p class="rexos-muted">
-Start local with Ollama. Switch to GLM / MiniMax / DeepSeek / Kimi / Qwen / NVIDIA NIM when you need more power.
+OpenClaw is known as a personal assistant. LoopForge is positioned as a personal AI engineer for builders: local-first, reproducible, and audit-friendly.
 </p>
 
 </div>
@@ -18,69 +22,55 @@ Start local with Ollama. Switch to GLM / MiniMax / DeepSeek / Kimi / Qwen / NVID
 
 <div class="grid cards" markdown>
 
-- :material-checklist: **Harness for long tasks**
-  Run "change → verify → checkpoint" repeatedly.
-  [Learn more](tutorials/harness-long-task.md)
+- :material-hammer-wrench: **Fix One Failing Test**
+  Ask LoopForge to run tests, repair one failure, and write `notes/fix-report.md`.
+  [Copy/paste prompt](examples/case-tasks/fix-one-failing-test.md)
 
-- :material-database: **SQLite memory**
-  Sessions and messages live in `~/.rexos/rexos.db`.
-  [Concepts](explanation/concepts.md)
+- :material-clipboard-check: **Release Readiness Audit**
+  Generate a practical release go/no-go checklist from commits, tests, and changelog.
+  [Copy/paste prompt](examples/case-tasks/release-readiness-audit.md)
 
-- :material-shield-lock: **Sandboxed tools**
-  File IO and shell stay in workspace; web_fetch has SSRF protection.
-  [Security](explanation/security.md)
+- :material-file-document-edit: **Routing Plan + Cost Notes**
+  Produce provider/model routing guidance with trade-offs and rollback notes.
+  [Copy/paste prompt](examples/case-tasks/provider-routing-plan.md)
 
-- :material-router: **Multi-provider routing**
-  Route planning/coding/summary to different models.
-  [Providers](how-to/providers.md)
+- :material-history: **Reproducible Progress**
+  Keep a clear trail: change -> verify -> checkpoint.
+  [Harness workflow](tutorials/harness-long-task.md)
 
 </div>
 
-## Quickstart
+## 3 Fast Outcomes
 
-=== "macOS/Linux"
+=== "1) First successful run"
     ```bash
-    # 1) Start Ollama
     ollama serve
-
-    # 2) Init LoopForge
     loopforge init
-
-    # 3) Run a session
     mkdir -p my-work
-    loopforge agent run --workspace my-work --prompt "Create hello.txt with: Hello LoopForge"
+    loopforge agent run --workspace my-work --prompt "Create notes/hello.md with a short project intro."
     ```
 
-=== "Windows (PowerShell)"
-    ```powershell
-    # 1) Start Ollama
-    ollama serve
-
-    # 2) Init LoopForge
-    loopforge init
+=== "2) Fix one failing test"
+    ```bash
+    loopforge agent run --workspace . --prompt "Run tests. Fix one failing test. Re-run that test. Write notes/fix-report.md with root cause and patch summary."
+    ```
 
-    # 3) Run a session
-    mkdir my-work
-    loopforge agent run --workspace my-work --prompt "Create hello.txt with: Hello LoopForge"
+=== "3) Release audit memo"
+    ```bash
+    loopforge agent run --workspace . --prompt "Read CHANGELOG.md and recent commits. Create notes/release-readiness.md with: risks, blockers, go/no-go, and next actions."
     ```
 
-## How It Works
-
-```mermaid
-flowchart LR
-  U[You] -->|prompt| R[LoopForge CLI]
-  R --> M[(SQLite)]
-  R --> W[(Workspace)]
-  R --> G[(Git checkpoints)]
-  R --> T[Tools]
-  R --> X{Router}
-  X -->|planning| P[Small model]
-  X -->|coding| C[Stronger model]
-  X -->|summary| S[Cheap model]
-```
+## Where We Fit
+
+- Choose **LoopForge** when your primary need is engineering delivery and reproducible execution.
+- Choose assistant-style products when your primary need is daily life/chat experience.
+- Choose broad operation platforms when your primary need is channel coverage first.
+
+See detailed positioning: [Why LoopForge](explanation/why-loopforge.md).
 
 ## Next Steps
 
-- [Harness tutorial](tutorials/harness-long-task.md)
+- [5-minute outcomes](tutorials/five-minute-outcomes.md)
+- [Personal AI Engineer narrative](blog/personal-ai-engineer.md)
+- [Case task library](examples/case-tasks/index.md)
 - [Providers & routing](how-to/providers.md)
-- [FAQ](how-to/faq.md)
diff --git a/docs-site/tutorials/five-minute-outcomes.md b/docs-site/tutorials/five-minute-outcomes.md
@@ -0,0 +1,47 @@
+# 5-Minute Outcomes
+
+This page answers one question fast:
+what can LoopForge actually produce for me today?
+
+## Prerequisites
+
+```bash
+ollama serve
+loopforge init
+```
+
+## Outcome 1: First artifact in a new workspace
+
+```bash
+mkdir -p demo-work
+loopforge agent run --workspace demo-work --prompt "Create notes/hello.md with a short intro to this workspace and 3 next actions."
+```
+
+Expected artifact:
+- `demo-work/notes/hello.md`
+
+## Outcome 2: Fix one failing test with a report
+
+```bash
+loopforge agent run --workspace . --prompt "Run tests. Fix one failing test. Re-run that test. Write notes/fix-report.md with root cause and patch summary."
+```
+
+Expected artifact:
+- `notes/fix-report.md`
+
+## Outcome 3: Release readiness memo
+
+```bash
+loopforge agent run --workspace . --prompt "Read CHANGELOG.md and recent commits. Create notes/release-readiness.md with: risks, blockers, go/no-go recommendation, and next actions."
+```
+
+Expected artifact:
+- `notes/release-readiness.md`
+
+## Why this matters
+
+These are not chat replies only. They are persistent outputs you can review, commit, and hand over.
+
+Next:
+- [Case task library](../examples/case-tasks/index.md)
+- [Why LoopForge](../explanation/why-loopforge.md)
diff --git a/docs-site/zh-CN/blog/index.md b/docs-site/zh-CN/blog/index.md
@@ -4,11 +4,13 @@
 
 ## 最新文章
 
+- [LoopForge：不是泛助手，而是个人研发助理](personal-ai-engineer.md)
 - [什么是 LoopForge？](what-is-loopforge.md)
 - [LoopForge 与 OpenFang/OpenClaw](rexos-vs-openfang-openclaw.md)
 
 ## 建议阅读顺序
 
-1. 先看品牌与定位：[什么是 LoopForge？](what-is-loopforge.md)
-2. 再跑通首条链路：[快速开始](../tutorials/quickstart-ollama.md)
-3. 对比竞品场景：[LoopForge 与 OpenFang/OpenClaw](rexos-vs-openfang-openclaw.md)
+1. 先看定位叙事：[LoopForge：不是泛助手，而是个人研发助理](personal-ai-engineer.md)
+2. 再看品牌定位：[什么是 LoopForge？](what-is-loopforge.md)
+3. 再跑通首条链路：[5 分钟可见结果](../tutorials/five-minute-outcomes.md)
+4. 对比竞品场景：[LoopForge 与 OpenFang/OpenClaw](rexos-vs-openfang-openclaw.md)
diff --git a/docs-site/zh-CN/blog/personal-ai-engineer.md b/docs-site/zh-CN/blog/personal-ai-engineer.md
@@ -0,0 +1,40 @@
+# LoopForge：不是泛助手，而是个人研发助理
+
+当用户问“你到底能帮我做什么”，先回答可见结果：
+
+- 修复一个失败测试并产出报告
+- 输出发布就绪评估
+- 输出 provider 路由与成本/性能方案
+
+这就是 LoopForge 的核心叙事。
+
+## 我们现在的叙事缺口
+
+很多产品先讲“assistant”。
+LoopForge 应该先讲“交付结果”：
+
+1. 你给出具体工程目标
+2. LoopForge 在 workspace 内执行
+3. 你得到可评审、可提交、可交接的文件产物
+
+## 一句话定位
+
+LoopForge 是你的 **个人研发助理（Personal AI Engineer）**，专注可复现的软件交付。
+
+## 演示时最该展示的 3 件事
+
+1. “修一个失败测试，写 `notes/fix-report.md`”
+2. “做发布就绪审计，写 `notes/release-readiness.md`”
+3. “做路由方案，写 `notes/provider-plan.md`”
+
+## 为什么这种叙事更有效
+
+- 直接命中开发者痛点
+- 和泛消费助手形成差异
+- 价值可在几分钟内被看见
+
+## 下一步阅读
+
+- [5 分钟可见结果](../tutorials/five-minute-outcomes.md)
+- [为什么是 LoopForge](../explanation/why-loopforge.md)
+- [案例任务库](../examples/case-tasks/index.md)
diff --git a/docs-site/zh-CN/explanation/why-loopforge.md b/docs-site/zh-CN/explanation/why-loopforge.md
@@ -0,0 +1,32 @@
+# 为什么是 LoopForge
+
+LoopForge 的目标不是做“泛生活助手”。
+它的定位是 **个人研发助理（Personal AI Engineer）**，聚焦软件交付。
+
+## 定位对比
+
+| 产品形态 | 核心价值 |
+|---|---|
+| 个人生活助理 | 日常聊天与生活类任务 |
+| 渠道运营平台 | 多渠道运营与适配器广度 |
+| LoopForge | 可复现工程流程与可交付产物 |
+
+## LoopForge 优先优化什么
+
+1. 可复现执行（`修改 -> 验证 -> checkpoint`）
+2. 本地优先起步（先 Ollama，按需切云端）
+3. 持久化产物（报告、检查单、总结文档进入 workspace）
+4. 可审计轨迹（session + memory + 文件产物）
+
+## 对团队意味着什么
+
+- 工程交接更容易
+- 回滚更稳，因为 checkpoint 明确
+- 评审更直接，因为输出是文件，不只是对话
+
+## 10 分钟评估方式
+
+依次跑这三条：
+1. [5 分钟可见结果](../tutorials/five-minute-outcomes.md)
+2. [修复一个失败测试](../examples/case-tasks/fix-one-failing-test.md)
+3. [发布就绪审计](../examples/case-tasks/release-readiness-audit.md)
diff --git a/docs-site/zh-CN/index.md b/docs-site/zh-CN/index.md
diff --git a/docs-site/zh-CN/tutorials/five-minute-outcomes.md b/docs-site/zh-CN/tutorials/five-minute-outcomes.md
diff --git a/mkdocs.yml b/mkdocs.yml
