Align public entry with goal-first onboarding

README.md

@@ -4,10 +4,12 @@
 
 <a href="https://trendshift.io/repositories/102379"><img src="https://trendshift.io/api/badge/repositories/102379" alt="LoopX — #1 on GitHub Trending, tracked by Trendshift" width="220" height="48"></a>
 
-**Turn long-horizon goals into verifiable results.**
+**Start with one goal. Keep long-running agent work verifiable.**
 
-A local-first [semantic control plane](https://loopx-project.github.io/loopx/blog/from-one-shot-agents-to-long-horizon-control/#control-plane) and [research workbench](#research-workbench) for long-running agent teams, across sessions and runtimes.<br>
-<sub>Keep goals, decisions, ownership and evidence durable. Work with Codex, Claude Code, DeepSeek Harness and other runtimes you already use.</sub>
+Tell the Agent you already use what you want done. LoopX keeps the goal,
+work, approvals and evidence durable behind the scenes, so the next session can
+continue without making you learn LoopX internals first.<br>
+<sub>Work with Codex, Claude Code, DeepSeek Harness and other runtimes. Advanced docs still expose the local-first semantic kernel, ownership model and research workbench.</sub>
 
 [![Release](https://img.shields.io/github/v/release/loopx-project/loopx?color=brightgreen)](https://github.com/loopx-project/loopx/releases/latest) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) [![TypeScript core](https://img.shields.io/badge/core-TypeScript-3178C6?logo=typescript&logoColor=white)](docs/architecture/rfcs/typescript-control-plane-migration-v0.md) [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
 
@@ -21,9 +23,9 @@ A local-first [semantic control plane](https://loopx-project.github.io/loopx/blo
 
 <a id="quick-start"></a>
 
-## Start in two steps
+## Start with one goal
 
-**1. Install LoopX and its Agent skills.** Requires Python 3.11+ and
+**1. Install LoopX once.** Requires Python 3.11+ and
 Node.js 22.22.3+ (24 LTS recommended).
 
 ```bash
@@ -32,15 +34,16 @@ python3 -m pip install --upgrade loopx && loopx workflow-skills --install
 
 [Install options and upgrades](docs/guides/installing-loopx.md)
 
-**2. Give your Agent a concrete task.** Restart your Agent host, open your
-project, then send this in Codex:
+**2. Tell your Agent the outcome.** Restart your Agent host, open your project,
+then send one natural-language goal:
 
 ```text
 $loopx speed up this project's slowest workflow; compare approaches and verify the gains
 ```
 
-Claude Code uses `/loopx <complex task>`; see [host setup](#start-from-your-agent)
-for other runtimes. Prefer a guided first run? [Choose a task below](#try-loopx).
+LoopX turns that into visible tasks, gates and evidence as needed. Claude Code
+uses `/loopx <complex task>`; see [host setup](#start-from-your-agent) for other
+runtimes. Prefer a guided first run? [Choose a task below](#try-loopx).
 
 ## 📰 News
 
@@ -64,6 +67,11 @@ for other runtimes. Prefer a guided first run? [Choose a task below](#try-loopx)
 
 ## Why LoopX
 
+You should not have to learn LoopX internals before the first useful action.
+The default path is goal-first: describe the outcome, let the Agent prepare the
+plan, and inspect the machinery only when a decision or debugging need calls
+for it.
+
 An agent can finish a task in one session. Long-running work is harder:
 objectives change, owner decisions appear, evidence goes stale, and agents
 hand work to peers. A timer can keep a loop running without making it useful.

README.zh-CN.md

@@ -4,10 +4,11 @@
 
 <a href="https://trendshift.io/repositories/102379"><img src="https://trendshift.io/api/badge/repositories/102379" alt="LoopX — GitHub Trending #1，由 Trendshift 记录" width="220" height="48"></a>
 
-**让 Agent 把长程目标做成可验证的成果。**
+**从一个目标开始，让长程 Agent 工作可验证。**
 
-面向长程 Agent 团队的本地优先[语义控制面](https://loopx-project.github.io/loopx/blog/zh/from-one-shot-agents-to-long-horizon-control/#control-plane)与[研究工作台](#research-workbench)，跨会话、跨运行时延续工作。<br>
-<sub>持久保留目标、决策、分工与证据，连接你已经在用的 Codex、Claude Code、DeepSeek Harness 等运行时。</sub>
+告诉你已经在用的 Agent 想完成什么。LoopX 在幕后持久保留目标、
+工作、审批与证据，让下一轮会话可以继续，而不要求你先学会 LoopX 内部机制。<br>
+<sub>连接 Codex、Claude Code、DeepSeek Harness 等运行时。高级文档仍会展开本地优先语义内核、ownership 模型与研究工作台。</sub>
 
 [![Release](https://img.shields.io/github/v/release/loopx-project/loopx?color=brightgreen)](https://github.com/loopx-project/loopx/releases/latest) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) [![TypeScript core](https://img.shields.io/badge/core-TypeScript-3178C6?logo=typescript&logoColor=white)](docs/architecture/rfcs/typescript-control-plane-migration-v0.zh-CN.md) [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
 
@@ -21,23 +22,24 @@
 
 <a id="快速开始"></a>
 
-## 两步开始
+## 从一个目标开始
 
-**1. 安装 LoopX 和 Agent 技能。** 需要 Python 3.11+、Node.js 22.22.3+（推荐 24 LTS）。
+**1. 安装一次 LoopX。** 需要 Python 3.11+、Node.js 22.22.3+（推荐 24 LTS）。
 
 ```bash
 python3 -m pip install --upgrade loopx && loopx workflow-skills --install
 ```
 
 [其他安装方式与升级说明](docs/guides/installing-loopx.md)
 
-**2. 给 Agent 一个具体任务。** 重启 Agent 宿主，打开项目，再在 Codex 对话中输入：
+**2. 告诉 Agent 你想要的结果。** 重启 Agent 宿主，打开项目，再发送一个自然语言目标：
 
 ```text
 $loopx 优化这个项目最慢的流程，对比方案并验证性能提升
 ```
 
-Claude Code 使用 `/loopx <复杂任务>`；其他运行时见[宿主接入](#从你已经在用的-agent-启动)。
+LoopX 会按需把它变成可见的任务、决策门和证据。Claude Code 使用
+`/loopx <复杂任务>`；其他运行时见[宿主接入](#从你已经在用的-agent-启动)。
 想跟着教程试一次？[选择一个入门任务](#试用-loopx)。
 
 ## 📰 最新动态
@@ -60,6 +62,9 @@ Claude Code 使用 `/loopx <复杂任务>`；其他运行时见[宿主接入](#
 
 ## 为什么需要 LoopX
 
+第一次有用动作之前，你不需要先学会 LoopX 内部机制。默认路径是目标优先：
+描述结果，让 Agent 准备计划；只有决策或调试需要时，再查看背后的机制。
+
 一个 Agent 可以在单次会话里完成任务。长程工作更难：目标会变化，用户决策会出现，
 证据会过期，多个 Agent 会交接。定时器能让任务继续运行，却不能保证仍在做有用的工作。