KLR-Pattern · allmonday · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026
diff --git a/README.md b/README.md
@@ -3,13 +3,18 @@
 [![pypi](https://img.shields.io/pypi/v/nexusx.svg)](https://pypi.python.org/pypi/nexusx)
 [![PyPI Downloads](https://static.pepy.tech/badge/nexusx/month)](https://pepy.tech/projects/nexusx)
 
-> **Declare your SQLModel entities once — GraphQL, REST, MCP, CLI, and a
-> TypeScript SDK all derive from that single model.**
-
-nexusx is a Python library for SQLModel applications. You declare entities +
-relationships, `DefineSubset` DTOs, and use-case methods; nexusx derives every
-delivery protocol from that one model — sharing one DataLoader-backed query
-graph (N+1-proof) and the same typed DTOs everywhere.
+> **A framework for building MCP-first, Agent-first applications — declare
+> your SQLModel entities once; MCP, GraphQL, REST, CLI, and a TypeScript
+> SDK all derive from that single model.**
+
+nexusx is a Python framework for building **MCP-first, Agent-first
+applications** on SQLModel. You declare entities + relationships,
+`DefineSubset` DTOs, and use-case methods; nexusx derives every delivery
+protocol from that one model — sharing one DataLoader-backed query graph
+(N+1-proof) and the same typed DTOs everywhere. Its specialty: **APIs that
+agents understand easily** — an agent can always see what data exists,
+explore the API piece by piece, and fetch only the fields it needs, so the
+context window is spent on your data, not on decoding the interface.
 
 What it removes: in a typical FastAPI + SQLModel app you re-declare the same
 data shape for each transport — response models, GraphQL types, MCP tool
@@ -23,18 +28,29 @@ schemas, CLI arguments. nexusx collapses those re-declarations into one.
 | A non-ORM async batch function | A relationship that joins the same loaders, DTOs, and ER diagrams |
 | Entity `__federation_keys__` | Cross-service federation (auto-detected + batch-fetched) |
 
+**For AI** — nexusx builds **agent-first APIs**: MCP is a first-class protocol
+with **strong typing** and **GraphQL under the hood**. Three capabilities make
+an API easy for agents to use:
+
+- **See what data exists** (field awareness) — the schema describes every
+  type, field, and relationship with exact names and types, so an agent
+  always knows what the data looks like and what it can query.
+- **Explore the API piece by piece** (progressive disclosure) — the schema is
+  revealed on demand, layer by layer (app → service → method), so an agent
+  never has to load the whole schema into its context window up front.
+- **Fetch only what is needed** (field selection) — an agent asks for the
+  exact fields it wants; one MCP call returns the whole nested result, with
+  nothing extra.
+
+In short: the agent always has enough context to understand the data, and
+only pulls back what it needs — context is spent on your business data, not
+wasted. See [MCP & context efficiency](docs/mcp-context-efficiency.md) for
+the details.
+
 **For Human** — write SQLModel entities + typed DTOs; get REST routes, GraphQL
 schema, CLI, and TS SDK without boilerplate. Change business logic once → all
 protocols update in sync.
 
-**For AI** — MCP is a first-class protocol with **strong typing** and
-**GraphQL under the hood** — the biggest win is **context efficiency**.
-Instead of dumping large, fixed-shape objects into the context window, AI agents
-**select exactly the fields they need**, with progressive disclosure on the
-schema side and DataLoader batch-loading on the data side: one MCP call returns
-a fully-nested, N+1-proof data tree — and only what was asked for. See
-[MCP & context efficiency](docs/mcp-context-efficiency.md) for the details.
-
 ## Installation
 
 ```bash
@@ -52,6 +68,51 @@ pip install "nexusx[cli]"         # Typer CLI generation
 
 nexusx requires Python 3.10 or newer.
 
+## Build an application with a single prompt
+
+The fastest start is not writing code at all. The
+[nexusx-4phase skill](skills/nexusx-4phase/) gives your coding agent a staged
+workflow over nexusx: first confirm the domain model, then build entities,
+GraphQL, and use-case APIs (REST / MCP / CLI), with an optional TypeScript
+SDK at the end. Install it with the open skills CLI (works with Claude Code,
+Codex, Cursor, and more):
+
+```bash
+npx skills add KLR-Pattern/nexusx -s nexusx-4phase -a claude-code
+```
+
+Then describe the application you want. The prompt below is the actual
+prompt that kicked off
+[MindMap X](https://github.com/allmonday/mindmap-x) (translated from the
+original Chinese):
+
+```text
+/nexusx-4phase
+
+Core requirements:
+
+- A mind map / tree editor
+- Humans can edit directly in a graphical interface
+- Agents can read and modify the same tree
+- Human and agent edits are visible to each other immediately
+- Self-hosted
+- Can be started or invoked directly from agent environments
+  like Claude Code or Codex
+
+Ideal state: start it with one command inside the agent, then let the agent
+reason about and modify the mind map while the human keeps editing in the
+browser at the same time.
+```
+
+The result is a complete, self-hosted application: a browser canvas for
+humans, an MCP server for agents — Claude Code joins the same tree with one
+command (`claude mcp add --transport http mindmap http://localhost:8740/mcp`)
+— plus CLI and REST on the same operations, all derived from one nexusx
+model. Humans and agents co-edit one tree and see each other's changes in
+real time. See the
+[MindMap X repository](https://github.com/allmonday/mindmap-x) for the full
+source.
+
 ## Why nexusx
 
 A SQLModel application usually grows through the same stages:
@@ -660,12 +721,8 @@ Start with the layer your application needs:
 | Compose engines in one process | [ComposedErManager](docs/advanced/composed_er_manager.md) |
 
 For complete runnable examples, see [`demo/`](demo/). For the progressive
-Schema-to-SDK development workflow, install the [4-phase skill](skills/nexusx-4phase/)
-with the open skills CLI (works with Claude Code, Codex, Cursor, and more):
-
-```bash
-npx skills add KLR-Pattern/nexusx -s nexusx-4phase -a claude-code
-```
+Schema-to-SDK development workflow, see
+[Build an application with a single prompt](#build-an-application-with-a-single-prompt).
 
 ## Project
 

diff --git a/docs/index.md b/docs/index.md
@@ -2,26 +2,27 @@
 template: home.html
 home:
   hero:
-    badge: "Next-Gen Business Modeling · AI-Native · SQLModel"
+    badge: "MCP-First · Agent-First · SQLModel"
     title: "Model your business once —<br>for humans and AI alike."
-    subtitle: "Model your business entities, relationships, and use cases once — GraphQL, REST, MCP, CLI, and TS SDK all derive from it. Data is a graph; tools are just its projections."
+    subtitle: "A Python framework for building MCP-first, Agent-first applications: model entities, relationships, and use cases once — MCP, GraphQL, REST, CLI, and TS SDK all derive from it. Its specialty: APIs that agents understand easily — agents always have enough context to know what the data looks like, and fetch only the fields they need."
     install: "pip install nexusx"
     primary: {label: "Get Started", ref: "guide/quick_start"}
-    secondary: {label: "GitHub", url: "https://github.com/allmonday/nexusx"}
+    secondary: {label: "GitHub", url: "https://github.com/KLR-Pattern/nexusx"}
   sections:
     # ── AI-native integration ──
     - type: cards
       muted: true
       two: true
-      title: "AI-native integration — not bolted on"
+      title: "Agent-first — not bolted on"
       subtitle: "The same typed business model serves AI agents and developers as first-class consumers."
       cards:
         - icon: "🤖"
-          title: "For AI — first-class"
-          text: "MCP is a native protocol: strongly typed, GraphQL under the hood."
+          title: "For AI — APIs agents understand"
+          text: "MCP is a first-class protocol: strongly typed, GraphQL under the hood. Three capabilities make an API agent-friendly:"
           bullets:
-            - text: "<strong>Context efficiency</strong> — agents select exactly the fields they need; one call returns a nested, N+1-proof tree with only what was asked."
-            - text: "<strong>Progressive disclosure</strong> — list_apps → describe_compose_schema → describe_compose_method → compose_query; the schema enters context piece by piece, never whole."
+            - text: "<strong>See what data exists</strong> (field awareness) — the schema describes every type, field, and relationship with exact names and types, so an agent always knows what the data looks like and what it can query"
+            - text: "<strong>Explore the API piece by piece</strong> (progressive disclosure) — list_apps → describe_compose_schema → describe_compose_method → compose_query; the schema enters context slice by slice, never as one dump"
+            - text: "<strong>Fetch only what is needed</strong> (field selection) — an agent picks the exact fields; one call returns the full nested data tree with only what was asked"
             - {label: "MCP & context efficiency →", ref: "mcp-context-efficiency"}
         - icon: "🧑‍💻"
           title: "For Human — same model"
@@ -177,13 +178,21 @@ home:
 
     # ── Build with an agent ──
     - type: cards
-      title: "Skip the API manual — build with an agent"
-      subtitle: "Install the 4-phase skill into your coding agent — Claude Code, Codex, Cursor, and more — then describe your app in plain words. The agent drives the workflow; you review the model."
+      title: "Build an application with a single prompt"
+      subtitle: "Install the 4-phase skill into your coding agent — Claude Code, Codex, Cursor, and more — then describe your app in plain words. The agent drives the staged workflow; you review the model."
       command: "npx skills add KLR-Pattern/nexusx -s nexusx-4phase -a claude-code"
       cards:
         - {icon: "🗺️", title: "Phase 0 — model the domain", text: "Confirm the domain model and persistence strategy with you before any code is written."}
         - {icon: "🏗️", title: "Phase 1–3 — build the layers", text: "Entities and relationships, GraphQL helper surface, then UseCase REST / MCP / CLI deliveries."}
         - {icon: "🚀", title: "Phase 4 — generate the SDK", text: "Optionally emit a typed TypeScript SDK from the compose schema."}
+        - icon: "🧠"
+          title: "Real case — MindMap X"
+          text: "The original prompt that built <a href='https://github.com/allmonday/mindmap-x'>MindMap X</a> was one line — <code>/nexusx-4phase</code> — plus a requirement list:"
+          bullets:
+            - text: "A mind map / tree editor"
+            - text: "Humans edit in a graphical interface; agents read and modify the same tree, with edits visible to both sides immediately"
+            - text: "Self-hosted, launchable directly from agent environments like Claude Code or Codex"
+            - text: "The result: a complete self-hosted app — browser canvas + MCP server + CLI + REST, all derived from one nexusx model"
 
     # ── Integrations ──
     - type: integrations
@@ -202,17 +211,17 @@ home:
       title: "Start from entities, not boilerplate"
       subtitle: "Declare the model once — the data graph, response DTOs, and every delivery follow."
       primary: {label: "Read the Guide", ref: "guide/quick_start"}
-      secondary: {label: "View on GitHub", url: "https://github.com/allmonday/nexusx"}
+      secondary: {label: "View on GitHub", url: "https://github.com/KLR-Pattern/nexusx"}
 ---
 
 
 # nexusx
 
-**nexusx** is a next-generation business modeling tool with deep AI integration.
-Model your business entities, relationships, and use cases once — GraphQL,
-REST, MCP, CLI, and TS SDK all derive from that single model, sharing one
-DataLoader-backed query graph (N+1-proof) and one set of typed DTOs
-(`DefineSubset`): semantic-level isomorphism, not transport-level wrapping.
+**nexusx** is a Python framework for building MCP-first, Agent-first
+applications. Model your business entities, relationships, and use cases
+once — MCP, GraphQL, REST, CLI, and TS SDK all derive from that single model,
+sharing one DataLoader-backed query graph (N+1-proof) and one set of typed
+DTOs (`DefineSubset`): semantic-level isomorphism, not transport-level wrapping.
 
 ## Run It in 60 Seconds
 

diff --git a/docs/index.zh.md b/docs/index.zh.md
@@ -2,26 +2,27 @@
 template: home.html
 home:
   hero:
-    badge: "次世代业务建模工具 · AI 原生 · SQLModel"
+    badge: "MCP 优先 · Agent 优先 · SQLModel"
     title: "一次业务建模，<br>人与 AI 共享。"
-    subtitle: "把业务实体、关系与用例建模一次，GraphQL、REST、MCP、CLI 与 TS SDK 全部派生。数据是一张图，工具只是它的投影视图。"
+    subtitle: "构建 MCP 优先、Agent 优先应用的 Python 框架：实体、关系与用例建模一次，MCP、GraphQL、REST、CLI 与 TS SDK 全部派生。特色：高效构建 Agent 容易理解的 API——Agent 有充分上下文了解数据，也只取所需字段。"
     install: "pip install nexusx"
     primary: {label: "快速开始", ref: "guide/quick_start"}
-    secondary: {label: "GitHub", url: "https://github.com/allmonday/nexusx"}
+    secondary: {label: "GitHub", url: "https://github.com/KLR-Pattern/nexusx"}
   sections:
     # ── AI 原生集成 ──
     - type: cards
       muted: true
       two: true
-      title: "AI 原生集成，而非外挂"
+      title: "Agent 优先，而非外挂"
       subtitle: "同一份类型化业务模型，AI 代理与开发者都是一级消费者。"
       cards:
         - icon: "🤖"
-          title: "面向 AI —— 一等公民"
-          text: "MCP 是原生协议：强类型，底层是 GraphQL。"
+          title: "面向 AI —— Agent 容易理解的 API"
+          text: "MCP 是一等公民协议：强类型，底层是 GraphQL。三个能力让 API 对 Agent 友好："
           bullets:
-            - text: "<strong>Context 效率</strong> —— agent 按需选字段，一次调用返回无 N+1 的嵌套数据树，且只要所求内容"
-            - text: "<strong>渐进披露</strong> —— list_apps → describe_compose_schema → describe_compose_method → compose_query，schema 按需分片进入上下文"
+            - text: "<strong>看得见有什么数据</strong>（字段信息感知）—— schema 精确描述每个类型、字段与关系，Agent 始终知道数据长什么样、能查什么"
+            - text: "<strong>一步步摸清 API</strong>（渐进披露）—— list_apps → describe_compose_schema → describe_compose_method → compose_query，schema 按需分片进入上下文，不必一次性全量加载"
+            - text: "<strong>要什么取什么</strong>（字段选择）—— Agent 指定所需字段，一次调用返回完整嵌套的数据树，且只要所求内容"
             - {label: "MCP 与 context 效率 →", ref: "mcp-context-efficiency"}
         - icon: "🧑‍💻"
           title: "面向人类 —— 同一模型"
@@ -177,13 +178,21 @@ home:
 
     # ── Agent 陪建 ──
     - type: cards
-      title: "不用啃 API 文档 —— 让 Agent 陪你建模"
-      subtitle: "把 4-phase skill 装进你的编码 Agent（Claude Code、Codex、Cursor 等），用自然语言描述你的应用。Agent 驱动流程，你只需审视模型。"
+      title: "用一句 prompt 构建应用"
+      subtitle: "把 4-phase skill 装进你的编码 Agent（Claude Code、Codex、Cursor 等），然后用自然语言描述你想要的应用。Agent 驱动分阶段工作流，你只需审视模型。"
       command: "npx skills add KLR-Pattern/nexusx -s nexusx-4phase -a claude-code"
       cards:
         - {icon: "🗺️", title: "Phase 0 —— 领域建模", text: "先和你确认领域模型与持久化策略，再动代码。"}
         - {icon: "🏗️", title: "Phase 1–3 —— 逐层实现", text: "实体与关系、GraphQL 辅助接口、UseCase 的 REST / MCP / CLI 交付。"}
         - {icon: "🚀", title: "Phase 4 —— 生成 SDK", text: "可选从 compose schema 生成类型化 TypeScript SDK。"}
+        - icon: "🧠"
+          title: "真实案例 —— MindMap X"
+          text: "构建 <a href='https://github.com/allmonday/mindmap-x'>MindMap X</a> 的原始 prompt，就是一句 <code>/nexusx-4phase</code> 加一张需求清单："
+          bullets:
+            - text: "脑图 / 树状结构编辑器"
+            - text: "人类在图形界面直接编辑；Agent 读写同一棵树，双方修改即时可见"
+            - text: "支持 self-hosted，可从 Claude Code、Codex 这类 Agent 环境直接启动唤起"
+            - text: "成果是一个完整自托管应用：浏览器画布 + MCP 服务 + CLI + REST，全部派生自同一个 nexusx 模型"
 
     # ── 技术栈 ──
     - type: integrations
@@ -202,13 +211,13 @@ home:
       title: "从实体开始，而不是样板代码"
       subtitle: "声明一次模型 —— 数据图、响应 DTO 与所有交付随之而来。"
       primary: {label: "阅读指南", ref: "guide/quick_start"}
-      secondary: {label: "查看 GitHub", url: "https://github.com/allmonday/nexusx"}
+      secondary: {label: "查看 GitHub", url: "https://github.com/KLR-Pattern/nexusx"}
 ---
 
 
 # nexusx
 
-**nexusx** 是一款深度集成 AI 的次世代业务建模工具。把业务实体、关系与用例建模一次，GraphQL、REST、MCP、CLI 与 TS SDK 全部由此派生，共享同一个 DataLoader 批量加载的查询图（无 N+1）和一套类型化 DTO（`DefineSubset`）：语义级同构，而非传输层包装。
+**nexusx** 是一个构建 MCP 优先、Agent 优先应用的 Python 框架。把业务实体、关系与用例建模一次，MCP、GraphQL、REST、CLI 与 TS SDK 全部由此派生，共享同一个 DataLoader 批量加载的查询图（无 N+1）和一套类型化 DTO（`DefineSubset`）：语义级同构，而非传输层包装。
 
 ## 60 秒运行起来