diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index ed7646b..e9f97f9 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -8,7 +8,7 @@
"skills": "./skills/",
"interface": {
"displayName": "QGraphFlow",
- "shortDescription": "Architecture and flow diagrams: eleven kinds of interactive software diagrams from source, configuration and documents",
+ "shortDescription": "Architecture and flow diagrams: nine kinds of interactive software diagrams from source, configuration and documents",
"longDescription": "Generate flow, architecture, sequence, ER, deployment, class, state, use-case and data-flow diagrams from CodeGraph or raw repository evidence; deliver an offline HTML viewer and an auditable graph.json with in-page SVG and PNG download.",
"developerName": "Max Zheng",
"category": "Productivity",
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 118d206..187f0c9 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -11,6 +11,7 @@ on:
- 'skills/q-flow/scripts/**'
- 'skills/q-flow/assets/**'
- 'docs/pages/**'
+ - 'scripts/showcase-changes.mjs'
- '.github/workflows/pages.yml'
pull_request:
paths:
@@ -19,6 +20,7 @@ on:
- 'skills/q-flow/scripts/**'
- 'skills/q-flow/assets/**'
- 'docs/pages/**'
+ - 'scripts/showcase-changes.mjs'
- '.github/workflows/pages.yml'
workflow_dispatch:
@@ -42,6 +44,13 @@ jobs:
node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json site/jeepay/zh-CN --repo-root output/jeepay-source
node skills/q-flow/scripts/validate-graph.mjs site/jeepay/zh-CN/graph.json --repo-root output/jeepay-source
cp docs/pages/index.html site/index.html
+ - name: Generate the update comparison shown in the README clip
+ run: |
+ for locale in zh-CN en; do
+ node scripts/showcase-changes.mjs "$locale" "output/changes-$locale"
+ node skills/q-flow/scripts/generate-viewer.mjs "output/changes-$locale/current.graph.json" "site/jeepay/changes/$locale" --compare "output/changes-$locale/earlier.graph.json" --repo-root output/jeepay-source
+ node skills/q-flow/scripts/validate-graph.mjs "site/jeepay/changes/$locale/graph.json" --repo-root output/jeepay-source
+ done
- uses: actions/upload-pages-artifact@v5
with:
path: site
diff --git a/.github/workflows/publish-github-npm.yml b/.github/workflows/publish-github-npm.yml
index 8d20fef..726a417 100644
--- a/.github/workflows/publish-github-npm.yml
+++ b/.github/workflows/publish-github-npm.yml
@@ -52,7 +52,7 @@ jobs:
node verified/node_modules/@supermax92/qgraphflow/skills/q-flow/scripts/validate-graph.mjs examples/jeepay/flowchart.graph.json --input-only
node verified/node_modules/@supermax92/qgraphflow/skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/flowchart.graph.json output/order
# Generate the complete real-source Jeepay collection with the installed package.
- node verified/node_modules/@supermax92/qgraphflow/skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/eleven
+ node verified/node_modules/@supermax92/qgraphflow/skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay
- uses: actions/setup-node@v7
with:
node-version: '22'
diff --git a/README.en.md b/README.en.md
new file mode 100644
index 0000000..a9b8a5b
--- /dev/null
+++ b/README.en.md
@@ -0,0 +1,301 @@
+
+
+
+
+### Turn complex code into diagrams you can explore.
+
+Follow the path. Inspect the evidence. Share one offline file.
+
+💡 Inspired by Cocoon-AI/architecture-diagram-generator — thanks to the original author for the idea.
+
+[中文](README.md) · [English](README.en.md)
+
+[Live demo](https://supermax92.github.io/qgraphflow/) · [Getting started](#getting-started) · [Client installation](#installation-guide) · [Report an issue](https://github.com/supermax92/qgraphflow/issues) · [MIT](LICENSE)
+
+
+
+
+
+Real Jeepay source: component names stay readable with the whole diagram on screen, each card opens on its source line, and one file switches between component relationship architecture, sequence and ER diagrams. [Watch the MP4](https://github.com/supermax92/qgraphflow/releases/download/showcase-v3/jeepay.en.hero.mp4)
+
+*Nine diagram types: component relationship architecture, flowchart, sequence, ER, deployment, class, state, use case and data flow.*
+
+QGraphFlow turns source code, schemas, configuration and requirements into interactive software diagrams, with evidence you can inspect and an offline HTML file you can share.
+
+**What sets it apart:** nine diagram types from one skill, an evidence kind on every relationship and the source line behind each code-backed one, automatic layout, editing in the page, and no network requests from the plugin scripts or the Viewer itself.
+
+
+
+When the code changes, the diagram shows what changed: `generate --compare` checks against the previous version, marks added, changed and removed elements on the diagram and lists them under "This update", each with its source. The earlier version in this demo is fictional, made to show all three marks. [Try it online](https://supermax92.github.io/qgraphflow/jeepay/changes/en/) · [Watch the MP4](https://github.com/supermax92/qgraphflow/releases/download/showcase-v3/jeepay.en.changes.mp4)
+
+```bash
+npx skills add supermax92/qgraphflow
+```
+
+One command installs the skill for Claude Code, Codex, Cursor and Qoder; the [installation guide](#installation-guide) covers the plugin installations and the other clients.
+
+- **Explore:** search, zoom and pan; inspect responsibilities and upstream/downstream relationships.
+
+- **Verify:** inspect nodes and edges for source files, lines, symbols and explicitly marked uncertainty.
+
+- **Edit:** unlock the layout, change text and move elements; reset when needed.
+
+- **Share:** open offline HTML or export the complete diagram as SVG / PNG.
+
+The real-source [Jeepay corpus](examples/jeepay) contains all nine views used by CI and the live demo.
+
+## Getting started
+
+After installation, open your application project in the client and select the `q-flow` skill. These examples use Claude Code's `/q-flow`; in Codex, use the `$q-flow` or `$qgraphflow:q-flow` entry actually provided by your client. Not installed yet? Read the [installation guide](#installation-guide) first.
+
+### 1. Empty input: Not sure where to start
+
+Invoke the skill without adding a request:
+
+```text
+/q-flow
+```
+
+The skill guides you to choose the part to analyze and the question the diagram should answer. Drawing starts once the necessary information is clear.
+
+### 2. Ask about capabilities: Learn what it can draw
+
+```text
+/q-flow What types of diagrams can you draw? What questions does each type answer? I have just taken over a project; introduce your capabilities and suggest a starting point.
+```
+
+Learn what the nine diagram types are for, then decide whether to explore project structure, call order, data relationships or something else.
+
+### 3. Vague input: Only a general goal
+
+```text
+/q-flow Help me draw this project. I want to understand it as quickly as possible.
+```
+
+You do not need to specify a diagram type first. The skill selects a suitable view based on the project and your goal, and asks follow-up questions when necessary information is missing.
+
+### 4. Precise input: Define the scope and request drawing details
+
+Replace the business names and steps below with flows that actually exist in your project:
+
+```text
+/q-flow Analyze the order creation flow in the current project and generate a sequence diagram in Chinese.
+Cover the request entry point, pricing, stock reservation, payment authorization and order persistence.
+Retain the synchronous calls, asynchronous messages, paired returns, activation bars, conditional branches, retries and failure compensation that actually exist in the source. Do not omit details for brevity.
+Mark the source files and line numbers for components and calls, and save the result to docs/qgraphflow/order-sequence/.
+```
+
+State the subject, question, level of detail and output location clearly to start directly. The diagram retains only facts supported by evidence.
+
+### 5. Refine further: Expand part of the previous diagram
+
+After the result is generated, continue in the same conversation:
+
+```text
+/q-flow Expand the stock reservation step in the previous sequence diagram into a separate flowchart in Chinese.
+Show all branches for stock validation, successful reservation, retryable failures, the retry limit and stock release. Follow the source code and add no steps absent from it.
+```
+
+Start with the overall picture, then explore one step in depth. You can also request more detail in an existing diagram or verify its relationships.
+
+## Installation guide
+
+You need Node.js 22 or later and a plugin-capable client with model access configured.
+
+### Quick install
+
+```bash
+npx skills add supermax92/qgraphflow
+```
+
+Tested with `skills` 1.7.0 for Claude Code, Codex, Cursor and Qoder. It asks which clients to install to; `-a claude-code` names one, and `-g` installs for your user instead of the current project. The skill installs as `q-flow`, without the `qgraphflow:` prefix of the plugin installations below.
+
+To install it as a plugin instead, follow the steps below. [Qoder Desktop](#qoder-desktop) users can install from the marketplace and skip step 1.
+
+### 1. Download the plugin
+
+Get the plugin from npmjs.com; no account, login or token is needed. Create a separate directory outside your application project:
+
+```bash
+mkdir qgraphflow-install
+cd qgraphflow-install
+npm install qgraphflow --ignore-scripts
+cd node_modules/qgraphflow
+```
+
+You are now in the plugin root. **Downloading through npm does not automatically install the plugin in your client;** continue with step 2. The package also provides the `qgraphflow` command used in [Keep diagrams in sync with code](#keep-diagrams-in-sync-with-code).
+
+Run the following terminal commands from **the plugin root containing `skills/`**.
+
+### 2. Install in your client
+
+#### Codex App / CLI
+
+Codex CLI must be installed and available in your terminal:
+
+```bash
+codex plugin marketplace add .
+codex plugin add qgraphflow@supermax92
+```
+
+Start a new session, type `$`, and select `qgraphflow:q-flow`.
+
+#### Claude Code
+
+```bash
+claude plugin marketplace add ./
+claude plugin install qgraphflow@supermax92 --scope user
+```
+
+Start a new session and enter `/q-flow` (or the fully qualified `/qgraphflow:q-flow`).
+
+#### Qoder CLI
+
+```bash
+qodercli plugins install .
+```
+
+Start a new session and select `q-flow`.
+
+#### Qoder Desktop
+
+**Recommended:** Open **Settings → Plugins → Marketplace**, search for **QGraphFlow** or **代码图谱可视化**, and install the plugin. Start a new session and select `q-flow`.
+
+For local installation, complete step 1, then open **Settings → Plugins → Custom → Import** and import the complete plugin root directory. Start a new session and select `q-flow`.
+
+#### Cursor
+
+Copy everything in the plugin root, including hidden files, into:
+
+```text
+~/.cursor/plugins/local/qgraphflow/
+```
+
+Confirm that `.cursor-plugin/plugin.json` exists there, reload the window, and find `q-flow` in **Customize**. Back up any previous version first; do not mix old and new files.
+
+### 3. Start using it
+
+Open your application project in the client, start a new session and select the skill. Describe your request using the [Getting started](#getting-started) examples. Open the generated HTML in your browser.
+
+Building it yourself? See the [source build instructions](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
+
+## Quick usage
+
+These examples use `$qgraphflow:q-flow` in Codex. If your client shows `$q-flow`, select that entry instead. For other clients, use the skill entry described above.
+
+**Not sure where to begin?** Invoke the skill and choose the subject and question when prompted.
+
+```text
+$qgraphflow:q-flow
+```
+
+**Already have a goal?** Say which part to draw and what you want to understand. You do not need to choose a diagram type first.
+
+### Example 1: Understand the architecture
+
+```text
+$qgraphflow:q-flow Analyze the current project and generate an architecture diagram in Chinese, showing the responsibilities of the main modules, dependencies and system boundaries.
+```
+
+Useful when joining a project and learning its overall structure.
+
+### Example 2: Trace a business flow
+
+```text
+$qgraphflow:q-flow Analyze order creation and generate a sequence diagram in Chinese, showing the call order for pricing, stock reservation, payment and order persistence, and mark failure branches.
+```
+
+Replace order creation and its steps with your project's actual flow. Continue in the same conversation:
+
+```text
+$qgraphflow:q-flow Expand the stock reservation step in the previous diagram into a separate flowchart in Chinese, showing success and failure handling.
+```
+
+Results go under `docs/qgraphflow/` by default. Open `index.html` to explore, edit and export; `graph.json` retains the graph data. Each view is also written as an SVG (`diagram.svg`, or `diagram--.svg` for several views) that you can embed as an image in a README, pull request or wiki.
+
+After editing in the page, **More → Save changes** in Chrome or Edge rewrites the page, `graph.json` and the SVGs in place once you pick the diagram's folder. Other browsers save `graph.json` only: put it in the folder and regenerate the page and SVGs with `npx -y qgraphflow generate docs/qgraphflow//graph.json docs/qgraphflow/ --layout preserve --force`.
+
+
+Run the nine-view Jeepay source example
+
+Select your Jeepay source checkout to verify the evidence:
+
+```bash
+export JEEPAY_REPO_ROOT=""
+node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.json --input-only --repo-root "$JEEPAY_REPO_ROOT"
+node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"
+```
+
+Open `output/jeepay/index.html`; its nine SVGs are in the same directory. See the [corpus README](examples/jeepay) for the source revision and refresh procedure.
+
+
+
+## Keep diagrams in sync with code
+
+A diagram generated with a repository root records where each component is defined, the line behind each code-backed relationship (a call, a foreign key) and a fingerprint of every file it points into. Validating it with `--repo-root` lets lines that only moved pass and fails when the code behind the diagram changed: a recorded line was rewritten, a call was removed, new code touches a drawn component that no relationship covers, or a name the diagram uses is gone. The error shows the old and new code and names the elements and text to update. Add this job to your CI; it needs no build, login or token, and full history (`fetch-depth: 0`) lets it compare against those fingerprints:
+
+```yaml
+name: Diagrams
+on: [push, pull_request]
+jobs:
+ diagrams:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ fetch-depth: 0
+ - uses: actions/setup-node@v7
+ with:
+ node-version: '22'
+ - run: |
+ for graph in docs/qgraphflow/*/graph.json; do
+ npx -y qgraphflow validate "$graph" --input-only --repo-root . || { echo "::error file=$graph::$graph failed validation"; failed=1; }
+ done
+ exit ${failed:-0}
+```
+
+To see the impact on the pull request, add `--changes changes.md` to the validate line and post the file when it fails, for example `gh pr comment "$PR" --body-file changes.md` (needs `pull-requests: write`). It lists, per view, the elements each change touches, the file and line, and the old and new code. The page regenerated after `--fix` also marks those elements and lists the changes beside the key points.
+
+When it fails, ask the skill to refresh that diagram:
+
+```text
+$qgraphflow:q-flow CI says docs/qgraphflow/order-sequence is out of date. Refresh it.
+```
+
+The skill realigns every anchor, lists each change in the graph's `meta.sourceDrift`, updates only the elements those items name and regenerates the page and SVGs with your edited positions and text kept. It does not redraw the diagram.
+
+Add `--compare HEAD` when regenerating to see what a refresh changed: the page colors added and changed elements, lists removed ones beside the key points, and leaves `graph.json` untouched.
+
+## What each of the nine diagram types answers
+
+| View · PNG | Main question | Example scope |
+| --- | --- | --- |
+| Component relationship architecture | Which responsibility boundaries collaborate in the system? | Channels, transaction orchestration, pricing, risk, stock, payment, orders, events and fulfillment |
+| Flowchart | How does each decision point branch and converge? | Stock shortage, risk rejection, compensation for payment failure and successful commit |
+| Sequence | In what order does a request make calls and receive returns? | Successful checkout main flow and asynchronous OrderPaid |
+| ER | How does core data relate? | Cart, orders, items, payments, stock reservations and parcels |
+| Deployment | Where are runtime units placed and how are they connected? | Edge, Kubernetes, data services, payment and warehouse/logistics networks |
+| Class | How do domain objects and code contracts depend on each other? | Checkout application service, Order and four ports |
+| State | Which events and guards advance an order? | Payment, fulfillment, cancellation, refund and closure |
+| Use case | What capabilities does each actor have? | Buyer, merchant, warehouse and customer support |
+| Data flow | What transformations and stores do data assets pass through? | Cart, transaction decisions, order events, warehouse/logistics and delivery receipts |
+
+This is a concept model demonstrating QGraphFlow, not a particular e-commerce repository. The example `graph.json` invents no source paths and marks relationship evidence as `inference`. Real project diagrams need traceable source, DDL, configuration, tests and accepted requirements.
+
+## Develop and contribute
+
+```bash
+npm ci --prefix skills/q-flow/assets/viewer
+npm run build --prefix skills/q-flow/assets/viewer
+node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs
+```
+
+Development needs Node.js 22 or later, npm, tar, zip and unzip. Include a minimal redacted graph, client/browser versions and reproduction steps in issue reports.
+
+Reference documentation (English): [Evidence sources](skills/q-flow/references/evidence-sources.md) · [Graph data format](skills/q-flow/references/graph-schema.md) · [Guided intake](skills/q-flow/references/guided-intake.md) · [Viewer development and acceptance](skills/q-flow/references/viewer-development.md) · [Visual conventions](skills/q-flow/references/visual-contract.md)
+
+## License and attribution
+
+[MIT](LICENSE) · [Third-party notices](THIRD_PARTY_NOTICES.md)
+
+QGraphFlow is an independent MIT-licensed project. The scenarios in this document are conceptual examples and do not represent any real company's production architecture.
diff --git a/README.md b/README.md
index 9ba5579..cf170ed 100644
--- a/README.md
+++ b/README.md
@@ -2,121 +2,119 @@
-### Turn complex code into diagrams you can explore.
+### 把复杂代码,变成可以探索的图。
-Follow the path. Inspect the evidence. Share one offline file.
+跟随路径,查看证据,用一个离线文件分享。
-💡 Inspired by Cocoon-AI/architecture-diagram-generator — thanks to the original author for the idea.
+💡 灵感来自 Cocoon-AI/architecture-diagram-generator,感谢原作者的启发。
-[English](README.md) · [中文](docs/readme/README.zh-CN.md) · [Русский](docs/readme/README.ru.md) · [Português](docs/readme/README.pt.md) · [日本語](docs/readme/README.ja.md) · [Deutsch](docs/readme/README.de.md) · [Español](docs/readme/README.es.md)
+[中文](README.md) · [English](README.en.md)
-[Live demo](https://supermax92.github.io/qgraphflow/) · [Getting started](#getting-started) · [Client installation](#installation-guide) · [Report an issue](https://github.com/supermax92/qgraphflow/issues) · [MIT](LICENSE)
+[在线演示](https://supermax92.github.io/qgraphflow/) · [快速入门](#快速入门) · [客户端安装](#安装指南) · [反馈问题](https://github.com/supermax92/qgraphflow/issues) · [MIT](LICENSE)
-*Eleven diagram types: platform capability architecture, engineering layer architecture, component relationship architecture, flowchart, sequence, ER, deployment, class, state, use case and data flow.*
+
-QGraphFlow turns source code, schemas, configuration and requirements into interactive software diagrams, with evidence you can inspect and an offline HTML file you can share.
+以 Jeepay 真实源码为例:整图缩小后仍能读出组件名,点开卡片就是对应的源码行,同一个文件里切换组件关系、时序与 ER 图。[观看 MP4](https://github.com/supermax92/qgraphflow/releases/download/showcase-v3/jeepay.zh-CN.hero.mp4)
-**What sets it apart:** eleven diagram types from one skill, an evidence kind on every relationship and the source line behind each code-backed one, automatic layout, editing in the page, and no network requests from the plugin scripts or the Viewer itself.
+*支持九类图:【组件关系架构图、流程图、时序图、ER 图、部署图、类图、状态图、用例图、数据流图】*
-
+QGraphFlow 从源码、数据结构、配置和需求生成交互式软件图,让关系有据可查,并将结果交付为可分享的离线 HTML。
-Using real Jeepay source code, switch between component relationship architecture, sequence and ER diagrams to explore components and call relationships. [View full-size GIF](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.en.hero.gif)
+**差异在哪:** 一个技能覆盖九类图,每条关系都标明证据类别,有代码支撑的关系还记录对应的源码行,自动布局,能直接在页面里编辑,插件脚本和 Viewer 本身不发任何网络请求。
-**Complex sequence diagram showcase**
+
-
-
-A fictional e-commerce scenario contains 9 participants, 29 messages and 6 combined fragments, covering stock retries, nested branches, parallel processing, failure compensation and asynchronous callbacks. The animation progressively reveals the generated diagram to show its structure and details. [View full-size GIF](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.en.sequence-drawing.gif)
+代码变了,图上直接标出变了什么:`generate --compare` 对比上一版,把新增、改动和删除的元素标在图上,并列在右侧"本次更新"里,每一项都能点开看源码出处。演示里的上一版是虚构的,用来展示三种标记。[在线体验](https://supermax92.github.io/qgraphflow/jeepay/changes/zh-CN/) · [观看 MP4](https://github.com/supermax92/qgraphflow/releases/download/showcase-v3/jeepay.zh-CN.changes.mp4)
```bash
npx skills add supermax92/qgraphflow
```
-One command installs the skill for Claude Code, Codex, Cursor and Qoder; the [installation guide](#installation-guide) covers the plugin installations and the other clients.
+一条命令即可为 Claude Code、Codex、Cursor 和 Qoder 装好技能;以插件方式安装和其他客户端见[安装指南](#安装指南)。
-- **Explore:** search, zoom and pan; inspect responsibilities and upstream/downstream relationships.
+- **探索:** 搜索定位、缩放和平移画布,查看组件职责与上下游关系。
-- **Verify:** inspect nodes and edges for source files, lines, symbols and explicitly marked uncertainty.
+- **核验:** 从节点或连线查看详情,核对源码文件、行号、符号和明确标注的不确定性。
-- **Edit:** unlock the layout, change text and move elements; reset when needed.
+- **编辑:** 解锁后修改文字、移动元素;不满意时一键重置。
-- **Share:** open offline HTML or export the complete diagram as SVG / PNG.
+- **分享:** 打开离线 HTML,或将完整图导出为 SVG / PNG。
-The real-source [Jeepay corpus](examples/jeepay) contains all eleven views used by CI and the live demo.
+基于真实源码的 [Jeepay 语料](examples/jeepay)包含 CI 和在线演示用到的全部九个视图。
-## Getting started
+## 快速入门
-After installation, open your application project in the client and select the `q-flow` skill. These examples use Claude Code's `/q-flow`; in Codex, use the `$q-flow` or `$qgraphflow:q-flow` entry actually provided by your client. Not installed yet? Read the [installation guide](#installation-guide) first.
+安装后,在客户端打开你的业务项目,选择 `q-flow` 技能。以下以 Claude Code 的 `/q-flow` 为例;Codex 中使用客户端实际提供的 `$q-flow` 或 `$qgraphflow:q-flow` 入口。还未安装?先看[安装指南](#安装指南)。
-### 1. Empty input: Not sure where to start
+### 1. 空白输入:不知道从哪里开始
-Invoke the skill without adding a request:
+只调用技能,不附加需求:
```text
/q-flow
```
-The skill guides you to choose the part to analyze and the question the diagram should answer. Drawing starts once the necessary information is clear.
+技能会引导你选择要分析的部分,以及希望图回答的问题;必要信息明确后开始绘图。
-### 2. Ask about capabilities: Learn what it can draw
+### 2. 询问能力:先了解能画什么
```text
-/q-flow What types of diagrams can you draw? What questions does each type answer? I have just taken over a project; introduce your capabilities and suggest a starting point.
+/q-flow 你能绘制哪些类型的图?每类图适合回答什么问题?我刚接手一个项目,请先介绍能力并建议一个起点。
```
-Learn what the eleven diagram types are for, then decide whether to explore project structure, call order, data relationships or something else.
+先了解九类图的用途,再决定看项目结构、调用顺序、数据关系还是其他内容。
-### 3. Vague input: Only a general goal
+### 3. 模糊输入:只有一个大致目标
```text
-/q-flow Help me draw this project. I want to understand it as quickly as possible.
+/q-flow 帮我画一下这个项目,我想尽快看懂它。
```
-You do not need to specify a diagram type first. The skill selects a suitable view based on the project and your goal, and asks follow-up questions when necessary information is missing.
+不用先指定图类型。技能会根据项目和你的目标确定合适的视图,缺少必要信息时再追问。
-### 4. Precise input: Define the scope and request drawing details
+### 4. 精准输入:明确范围并要求绘制细节
-Replace the business names and steps below with flows that actually exist in your project:
+将下面的业务名称和步骤替换成项目中实际存在的流程:
```text
-/q-flow Analyze the order creation flow in the current project and generate a sequence diagram in Chinese.
-Cover the request entry point, pricing, stock reservation, payment authorization and order persistence.
-Retain the synchronous calls, asynchronous messages, paired returns, activation bars, conditional branches, retries and failure compensation that actually exist in the source. Do not omit details for brevity.
-Mark the source files and line numbers for components and calls, and save the result to docs/qgraphflow/order-sequence/.
+/q-flow 分析当前项目的订单创建流程,生成中文时序图。
+覆盖请求入口、价格计算、库存预占、支付授权和订单落库。
+保留源码中实际存在的同步调用、异步消息、成对返回、激活条、条件分支、重试和失败补偿,不要为了简洁省略细节。
+标明组件与调用的源码文件和行号,将结果保存到 docs/qgraphflow/order-sequence/。
```
-State the subject, question, level of detail and output location clearly to start directly. The diagram retains only facts supported by evidence.
+把对象、问题、详细程度和输出位置说清楚,就能直接开始;图中只保留有证据支持的事实。
-### 5. Refine further: Expand part of the previous diagram
+### 5. 继续细化:展开上一张图的局部
-After the result is generated, continue in the same conversation:
+在生成结果后,于同一对话中继续:
```text
-/q-flow Expand the stock reservation step in the previous sequence diagram into a separate flowchart in Chinese.
-Show all branches for stock validation, successful reservation, retryable failures, the retry limit and stock release. Follow the source code and add no steps absent from it.
+/q-flow 展开上一张时序图中的库存预占步骤,单独生成中文流程图。
+完整展示库存校验、预占成功、可重试失败、重试上限和释放库存的分支,以源码为准,不添加代码中没有的步骤。
```
-Start with the overall picture, then explore one step in depth. You can also request more detail in an existing diagram or verify its relationships.
+先看整体,再深入一个步骤;也可以继续要求补充已有图的细节或核验其中的关系。
-## Installation guide
+## 安装指南
-You need Node.js 22 or later and a plugin-capable client with model access configured.
+准备 Node.js 22 及以上版本,以及已配置好模型访问、支持插件功能的客户端。
-### Quick install
+### 快速安装
```bash
npx skills add supermax92/qgraphflow
```
-Tested with `skills` 1.7.0 for Claude Code, Codex, Cursor and Qoder. It asks which clients to install to; `-a claude-code` names one, and `-g` installs for your user instead of the current project. The skill installs as `q-flow`, without the `qgraphflow:` prefix of the plugin installations below.
+已用 `skills` 1.7.0 在 Claude Code、Codex、Cursor 和 Qoder 上实测。命令会询问装到哪些客户端;`-a claude-code` 可直接指定,`-g` 改为装到当前用户而不是当前项目。这样装上的技能名是 `q-flow`,不带下文插件安装方式里的 `qgraphflow:` 前缀。
-To install it as a plugin instead, follow the steps below. [Qoder Desktop](#qoder-desktop) users can install from the marketplace and skip step 1.
+如需以插件方式安装,按以下步骤操作。[Qoder Desktop](#qoder-desktop) 可直接从插件商城安装,跳过第 1 步。
-### 1. Download the plugin
+### 1. 下载插件
-Get the plugin from npmjs.com; no account, login or token is needed. Create a separate directory outside your application project:
+从 npmjs.com 获取插件,无需账号、登录或令牌。在业务项目之外创建独立目录:
```bash
mkdir qgraphflow-install
@@ -125,22 +123,22 @@ npm install qgraphflow --ignore-scripts
cd node_modules/qgraphflow
```
-You are now in the plugin root. **Downloading through npm does not automatically install the plugin in your client;** continue with step 2. The package also provides the `qgraphflow` command used in [Keep diagrams in sync with code](#keep-diagrams-in-sync-with-code).
+此时已进入插件根目录。**npm 下载不会自动完成客户端安装**,请继续第 2 步。这个包还提供 `qgraphflow` 命令,[让图和代码保持同步](#让图和代码保持同步)一节会用到。
-Run the following terminal commands from **the plugin root containing `skills/`**.
+以下终端命令均在**包含 `skills/` 的插件根目录**执行。
-### 2. Install in your client
+### 2. 选择客户端安装
#### Codex App / CLI
-Codex CLI must be installed and available in your terminal:
+终端需已安装 Codex CLI:
```bash
codex plugin marketplace add .
codex plugin add qgraphflow@supermax92
```
-Start a new session, type `$`, and select `qgraphflow:q-flow`.
+新建会话,输入 `$`,选择 `qgraphflow:q-flow`。
#### Claude Code
@@ -149,7 +147,7 @@ claude plugin marketplace add ./
claude plugin install qgraphflow@supermax92 --scope user
```
-Start a new session and enter `/q-flow` (or the fully qualified `/qgraphflow:q-flow`).
+新建会话,输入 `/q-flow`(或完整名称 `/qgraphflow:q-flow`)。
#### Qoder CLI
@@ -157,70 +155,70 @@ Start a new session and enter `/q-flow` (or the fully qualified `/qgraphflow:q-f
qodercli plugins install .
```
-Start a new session and select `q-flow`.
+新建会话,选择 `q-flow`。
#### Qoder Desktop
-**Recommended:** Open **Settings → Plugins → Marketplace**, search for **QGraphFlow** or **代码图谱可视化**, and install the plugin. Start a new session and select `q-flow`.
+**推荐:**打开 **Settings → Plugins → Marketplace**,搜索 **QGraphFlow** 或 **代码图谱可视化**,安装插件。新建会话,选择 `q-flow`。
-For local installation, complete step 1, then open **Settings → Plugins → Custom → Import** and import the complete plugin root directory. Start a new session and select `q-flow`.
+如需本地安装,先完成第 1 步,再打开 **Settings → Plugins → Custom → Import**,导入完整的插件根目录。新建会话,选择 `q-flow`。
#### Cursor
-Copy everything in the plugin root, including hidden files, into:
+将插件根目录中的全部内容(含隐藏文件)复制到:
```text
~/.cursor/plugins/local/qgraphflow/
```
-Confirm that `.cursor-plugin/plugin.json` exists there, reload the window, and find `q-flow` in **Customize**. Back up any previous version first; do not mix old and new files.
+确认其中存在 `.cursor-plugin/plugin.json`,重新加载窗口,在 **Customize** 中找到 `q-flow`。若已有旧版本,先备份,勿混合新旧文件。
-### 3. Start using it
+### 3. 开始使用
-Open your application project in the client, start a new session and select the skill. Describe your request using the [Getting started](#getting-started) examples. Open the generated HTML in your browser.
+在客户端打开你的业务项目,新建会话并选择技能,按[快速入门](#快速入门)中的示例描述需求。生成后,用浏览器打开输出的 HTML。
-Building it yourself? See the [source build instructions](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
+需要自行构建?参见[源码构建说明](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally)。
-## Quick usage
+## 快速使用
-These examples use `$qgraphflow:q-flow` in Codex. If your client shows `$q-flow`, select that entry instead. For other clients, use the skill entry described above.
+以下以 Codex 的 `$qgraphflow:q-flow` 入口为例;如果客户端显示 `$q-flow`,请选择它实际提供的入口。其他客户端使用上方对应的技能入口。
-**Not sure where to begin?** Invoke the skill and choose the subject and question when prompted.
+**不知道从哪里开始?** 直接调用,按提示选择要分析的部分和想了解的问题。
```text
$qgraphflow:q-flow
```
-**Already have a goal?** Say which part to draw and what you want to understand. You do not need to choose a diagram type first.
+**目标已经明确?** 一句话说明“画哪个部分+想看什么”,无需先选择图类型。
-### Example 1: Understand the architecture
+### 示例一:看懂项目架构
```text
-$qgraphflow:q-flow Analyze the current project and generate an architecture diagram in Chinese, showing the responsibilities of the main modules, dependencies and system boundaries.
+$qgraphflow:q-flow 分析当前项目,生成中文架构图,展示主要模块的职责、依赖关系和系统边界。
```
-Useful when joining a project and learning its overall structure.
+适合初次接触项目,先了解整体结构。
-### Example 2: Trace a business flow
+### 示例二:追踪业务调用
```text
-$qgraphflow:q-flow Analyze order creation and generate a sequence diagram in Chinese, showing the call order for pricing, stock reservation, payment and order persistence, and mark failure branches.
+$qgraphflow:q-flow 分析订单创建流程,生成中文时序图,展示价格计算、库存预占、支付和订单落库的调用顺序,并标明失败分支。
```
-Replace order creation and its steps with your project's actual flow. Continue in the same conversation:
+将“订单创建”及相关步骤替换成项目中的实际业务流程。看完后,在同一对话中继续追问:
```text
-$qgraphflow:q-flow Expand the stock reservation step in the previous diagram into a separate flowchart in Chinese, showing success and failure handling.
+$qgraphflow:q-flow 展开上一张图中的库存预占步骤,单独生成中文流程图,展示成功与失败的处理流程。
```
-Results go under `docs/qgraphflow/` by default. Open `index.html` to explore, edit and export; `graph.json` retains the graph data. Each view is also written as an SVG (`diagram.svg`, or `diagram--.svg` for several views) that you can embed as an image in a README, pull request or wiki.
+结果默认保存在 `docs/qgraphflow/` 下:打开 `index.html` 即可交互查看、编辑和导出,`graph.json` 保留图数据。每个视图还会写出一份 SVG(`diagram.svg`,多视图时为 `diagram--.svg`),可以直接作为图片嵌进 README、PR 或 Wiki。
-After editing in the page, **More → Save changes** in Chrome or Edge rewrites the page, `graph.json` and the SVGs in place once you pick the diagram's folder. Other browsers save `graph.json` only: put it in the folder and regenerate the page and SVGs with `npx -y qgraphflow generate docs/qgraphflow//graph.json docs/qgraphflow/ --layout preserve --force`.
+在页面里编辑后,用 Chrome 或 Edge 执行「更多 → 保存修改」并选一次图所在的文件夹,即可原地重写页面、`graph.json` 和 SVG。其他浏览器只能保存 `graph.json`:把它放回该文件夹,再用 `npx -y qgraphflow generate docs/qgraphflow//graph.json docs/qgraphflow/ --layout preserve --force` 重新生成页面和 SVG。
-Run the eleven-view Jeepay source example
+运行基于 Jeepay 源码的九视图示例
-Select your Jeepay source checkout to verify the evidence:
+指定本机的 Jeepay 源码目录来核验证据:
```bash
export JEEPAY_REPO_ROOT=""
@@ -228,13 +226,13 @@ node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.j
node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"
```
-Open `output/jeepay/index.html`; its eleven SVGs are in the same directory. See the [corpus README](examples/jeepay) for the source revision and refresh procedure.
+打开 `output/jeepay/index.html`,九个 SVG 在同一目录。源码版本和刷新步骤见[语料 README](examples/jeepay)。
-## Keep diagrams in sync with code
+## 让图和代码保持同步
-A diagram generated with a repository root records where each component is defined and the line behind each code-backed relationship (a call, a foreign key). Validating it with `--repo-root` fails when a recorded file is gone, a line range no longer fits, or a recorded symbol has left its lines, and the error names the lines where the symbol is now. Add this job to your CI; it needs no build, login or token:
+带仓库根目录生成的图会记下每个组件定义在哪里、每条有代码支撑的关系所在的那一行(调用、外键等),以及它指向的每个文件的内容指纹。用 `--repo-root` 校验时,只是挪了位置的行会自动对上、照常通过;只有图背后的代码真的变了才会失败:记录的那一行被改写、某个调用被删掉、新代码碰到了图里画的组件却没有对应的关系,或者图里用到的名字已经不存在。错误里会给出改动前后的代码,并指出要更新的元素和文字。把下面这个任务加进 CI,不需要构建、登录或令牌;拉取完整历史(`fetch-depth: 0`)才能和这些指纹比对:
```yaml
name: Diagrams
@@ -244,6 +242,8 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
+ with:
+ fetch-depth: 0
- uses: actions/setup-node@v7
with:
node-version: '22'
@@ -254,33 +254,35 @@ jobs:
exit ${failed:-0}
```
-When it fails, ask the skill to refresh that diagram:
+想在 PR 里直接看到受影响的地方,就在 validate 那一行加上 `--changes changes.md`,失败时把这个文件贴成评论,例如 `gh pr comment "$PR" --body-file changes.md`(需要 `pull-requests: write` 权限)。它按视图列出每处改动碰到的元素、文件和行号,以及改动前后的代码。执行 `--fix` 后重新生成的页面也会标出这些元素,并在要点旁列出这些改动。
+
+失败后,让技能刷新这张图:
```text
-$qgraphflow:q-flow CI says docs/qgraphflow/order-sequence is out of date. Refresh it.
+$qgraphflow:q-flow CI 提示 docs/qgraphflow/order-sequence 的图过时了,刷新一下。
```
-The skill moves anchors whose symbol it finds once, corrects only the anchors still reported, and regenerates the page and SVGs with your edited positions and text kept. It does not redraw the diagram.
+技能会把所有锚点对齐到当前代码,把每处改动列进图的 `meta.sourceDrift`,只更新这些条目指出的元素,再保留你调整过的位置和文字,重新生成页面和 SVG;不会重画整张图。
-## What each of the eleven diagram types answers
+重新生成时加上 `--compare HEAD`,就能看出这次刷新改了什么:页面把新增和改动的元素着色,在要点旁列出删掉的元素,`graph.json` 不受影响。
-| View · PNG | Main question | Example scope |
+## 九类图各自回答什么
+
+| 视图 · PNG | 主要问题 | 本示例范围 |
| --- | --- | --- |
-| Platform capability architecture | What capabilities does the platform provide? | Capability zones and matrices |
-| Engineering layer architecture | How is the engineering code organized? | Engineering layers and shared support |
-| Component relationship architecture | Which responsibility boundaries collaborate in the system? | Channels, transaction orchestration, pricing, risk, stock, payment, orders, events and fulfillment |
-| Flowchart | How does each decision point branch and converge? | Stock shortage, risk rejection, compensation for payment failure and successful commit |
-| Sequence | In what order does a request make calls and receive returns? | Successful checkout main flow and asynchronous OrderPaid |
-| ER | How does core data relate? | Cart, orders, items, payments, stock reservations and parcels |
-| Deployment | Where are runtime units placed and how are they connected? | Edge, Kubernetes, data services, payment and warehouse/logistics networks |
-| Class | How do domain objects and code contracts depend on each other? | Checkout application service, Order and four ports |
-| State | Which events and guards advance an order? | Payment, fulfillment, cancellation, refund and closure |
-| Use case | What capabilities does each actor have? | Buyer, merchant, warehouse and customer support |
-| Data flow | What transformations and stores do data assets pass through? | Cart, transaction decisions, order events, warehouse/logistics and delivery receipts |
-
-This is a concept model demonstrating QGraphFlow, not a particular e-commerce repository. The example `graph.json` invents no source paths and marks relationship evidence as `inference`. Real project diagrams need traceable source, DDL, configuration, tests and accepted requirements.
-
-## Develop and contribute
+| 组件关系架构图 | 系统由哪些责任边界协作? | 渠道、交易编排、价格、风控、库存、支付、订单、事件与履约 |
+| 流程图 | 每个决策点如何分支和收敛? | 缺货、风控拒绝、支付失败补偿与成功提交 |
+| 时序图 | 一次请求按什么顺序调用和返回? | 成功结算主链及异步 OrderPaid |
+| ER 图 | 核心数据如何关联? | 购物车、订单、明细、支付、库存预占和包裹 |
+| 部署图 | 运行单元放在哪里、怎样连接? | 边缘、Kubernetes、数据服务、支付和仓配网络 |
+| 类图 | 领域对象和代码契约怎样依赖? | Checkout 应用服务、Order 与四个端口 |
+| 状态图 | 订单受哪些事件和守卫条件推进? | 支付、履约、取消、退款和关闭 |
+| 用例图 | 每类参与者拥有哪些能力? | 买家、商家、仓库与客服 |
+| 数据流图 | 数据资产经过哪些变换和存储? | 购物车、交易决策、订单事件、仓配和物流回执 |
+
+这是用于展示 QGraphFlow 能力的概念模型,不对应某个电商仓库。`graph.json` 不伪造源码路径,关系证据统一标记为 `inference`;对真实项目绘图时,应改用源码、DDL、配置、测试和已接受需求中的可追溯证据。
+
+## 开发与参与
```bash
npm ci --prefix skills/q-flow/assets/viewer
@@ -288,24 +290,12 @@ npm run build --prefix skills/q-flow/assets/viewer
node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs
```
-Development needs Node.js 22 or later, npm, tar, zip and unzip. Include a minimal redacted graph, client/browser versions and reproduction steps in issue reports.
+开发需要 Node.js 22 及以上版本、npm、tar、zip 和 unzip。反馈问题时,请附最小脱敏图数据、客户端和浏览器版本,以及复现步骤。
-Reference documentation (English): [Evidence sources](skills/q-flow/references/evidence-sources.md) · [Graph data format](skills/q-flow/references/graph-schema.md) · [Guided intake](skills/q-flow/references/guided-intake.md) · [Viewer development and acceptance](skills/q-flow/references/viewer-development.md) · [Visual conventions](skills/q-flow/references/visual-contract.md)
+参考文档(英文):[证据来源](skills/q-flow/references/evidence-sources.md) · [图数据格式](skills/q-flow/references/graph-schema.md) · [需求引导](skills/q-flow/references/guided-intake.md) · [Viewer 开发与验收](skills/q-flow/references/viewer-development.md) · [图形表达约定](skills/q-flow/references/visual-contract.md)
-## License and attribution
+## 许可证与归属
-[MIT](LICENSE) · [Third-party notices](THIRD_PARTY_NOTICES.md)
-
-QGraphFlow is an independent MIT-licensed project. The scenarios in this document are conceptual examples and do not represent any real company's production architecture.
-
-## Architecture overviews
-
-Architecture now includes component relations, platform capabilities and engineering layers. Describe the subject and question; the skill chooses the template. Requested collections can contain multiple architecture views with independent edits.
-
-```text
-$qgraphflow:q-flow Analyze this project's platform capabilities and business integration methods, and generate a platform capability overview in Chinese.
-$qgraphflow:q-flow Analyze the organization and component layers of the current project, and generate Chinese overviews of the whole project and a cross-section of one component.
-$qgraphflow:q-flow Generate an English platform capability overview of this project and show how application modules integrate.
-```
+[MIT](LICENSE) · [第三方声明](THIRD_PARTY_NOTICES.md)
-See [examples/jeepay](examples/jeepay) for real-source platform, engineering and component relationship architecture views. Unlock an overview to reorder cards within a layer or edit text. Save keeps all views; reset restores only the current one.
+QGraphFlow 是采用 MIT 许可证的独立项目。本文场景为概念示例,不代表任何真实公司的生产架构。
diff --git a/docs/clients.de.md b/docs/clients.de.md
deleted file mode 100644
index 8524f03..0000000
--- a/docs/clients.de.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# Installationsanleitung
-
-[English](clients.md) · [中文](clients.zh-CN.md) · [Русский](clients.ru.md) · [Português](clients.pt.md) · [日本語](clients.ja.md) · [Deutsch](clients.de.md) · [Español](clients.es.md)
-
-[Zurück zur README](readme/README.de.md)
-
-Qoder Desktop kann das Plugin aus dem Marketplace installieren; dann entfällt Schritt 1 (siehe den Abschnitt unten). Die übrigen Clients installieren das Plugin-Paket von npmjs.com.
-
-Du benötigst Node.js 22 oder neuer (mit npm) und einen Client mit eingerichtetem Modellzugriff.
-
-## Schnellinstallation
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Installiert den Skill `q-flow` für Claude Code, Codex, Cursor und Qoder (getestet mit `skills` 1.7.0) und fragt, in welche Clients installiert werden soll. Für die Installation als Plugin den folgenden Schritten folgen.
-
-## 1. Plugin über npm herunterladen
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-Lege das Verzeichnis außerhalb deines Anwendungsprojekts an; Konto, Anmeldung oder Token sind nicht nötig. Danach befindest du dich im Plugin-Stammverzeichnis. Der Download über npm installiert das Plugin nicht im Client; fahre mit Schritt 2 fort. Um noch nicht veröffentlichten Code zu installieren, siehe die [Anleitung zum Bauen aus dem Quellcode](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
-
-## 2. Im Client installieren
-
-Führe die folgenden Befehle im Plugin-Stammverzeichnis aus Schritt 1 (`qgraphflow-install/node_modules/qgraphflow`) aus, nicht im Verzeichnis deines eigenen Anwendungsprojekts.
-
-### Codex App / CLI
-
-```bash
-codex plugin marketplace add .
-codex plugin add qgraphflow@supermax92
-```
-
-Hier registriert `marketplace add` nur eine lokale Installationsquelle; eine Veröffentlichung im öffentlichen Marktplatz ist nicht erforderlich. Siehe die [offizielle OpenAI-Dokumentation](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli).
-
-Starte eine neue Sitzung, gib `$` ein und wähle `qgraphflow:q-flow` aus (verwende den tatsächlich im Client angezeigten Namen).
-
-### Claude Code
-
-```bash
-claude plugin marketplace add ./
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Starte eine neue Sitzung und gib `/q-flow` (oder den vollständigen Namen `/qgraphflow:q-flow`) ein.
-
-### Qoder CLI
-
-```bash
-qodercli plugins install .
-```
-
-Starte eine neue Sitzung und wähle `q-flow` aus.
-
-### Qoder Desktop
-
-**Empfohlen:** Öffne **Settings → Plugins → Marketplace**, suche nach **QGraphFlow** oder **代码图谱可视化** und installiere das Plugin. Starte eine neue Sitzung und wähle `q-flow`.
-
-Für eine lokale Installation führe zuerst Schritt 1 aus. Öffne dann **Settings → Plugins → Custom → Import** und importiere das vollständige Plugin-Stammverzeichnis. Lade den Client neu und wähle `q-flow`.
-
-### Cursor
-
-Kopiere den gesamten Inhalt des Plugin-Stammverzeichnisses, einschließlich versteckter Dateien, nach `~/.cursor/plugins/local/qgraphflow/`. Sichere ein vorhandenes Verzeichnis zuerst; vermische keine alten und neuen Dateien.
-
-Prüfe, ob das Manifest unter `~/.cursor/plugins/local/qgraphflow/.cursor-plugin/plugin.json` liegt. Lade das Fenster neu und wähle unter Customize → Plugins / Skills den Skill `q-flow` aus.
-
-Diese lokale Methode wurde mit Cursor 3.19.13 getestet. Prüfe bei anderen Versionen, ob Plugin und Skill angezeigt werden.
diff --git a/docs/clients.es.md b/docs/clients.es.md
deleted file mode 100644
index a537a04..0000000
--- a/docs/clients.es.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# Guía de instalación
-
-[English](clients.md) · [中文](clients.zh-CN.md) · [Русский](clients.ru.md) · [Português](clients.pt.md) · [日本語](clients.ja.md) · [Deutsch](clients.de.md) · [Español](clients.es.md)
-
-[Volver al README](readme/README.es.md)
-
-Qoder Desktop permite instalar el complemento desde su Marketplace y omitir el paso 1 (consulta su sección más abajo). Los demás clientes instalan el paquete del complemento obtenido de npmjs.com.
-
-Necesitas Node.js 22 o posterior (con npm) y un cliente con acceso al modelo configurado.
-
-## Instalación rápida
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Instala la habilidad `q-flow` en Claude Code, Codex, Cursor y Qoder (probado con `skills` 1.7.0) y pregunta en qué clientes instalar. Para instalar el complemento, sigue los pasos siguientes.
-
-## 1. Descargar el complemento con npm
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-Crea el directorio fuera del proyecto de tu aplicación; no se necesita cuenta, inicio de sesión ni token. Ahora estás en la raíz del complemento. La descarga mediante npm no instala el complemento en el cliente; continúa con el paso 2. Para instalar código aún no publicado, consulta las [instrucciones de compilación desde el código fuente](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
-
-## 2. Instalar en el cliente
-
-Ejecuta los siguientes comandos desde la raíz del complemento a la que entraste en el paso 1 (`qgraphflow-install/node_modules/qgraphflow`), no desde el directorio de tu propio proyecto.
-
-### Codex App / CLI
-
-```bash
-codex plugin marketplace add .
-codex plugin add qgraphflow@supermax92
-```
-
-Aquí, `marketplace add` solo registra una fuente de instalación local; no requiere publicar el complemento en un marketplace público. Consulta la [documentación oficial de OpenAI](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli).
-
-Inicia una sesión nueva, escribe `$` y selecciona `qgraphflow:q-flow` (usa el nombre que muestre tu cliente).
-
-### Claude Code
-
-```bash
-claude plugin marketplace add ./
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Inicia una sesión nueva y escribe `/q-flow` (o el nombre completo `/qgraphflow:q-flow`).
-
-### Qoder CLI
-
-```bash
-qodercli plugins install .
-```
-
-Inicia una sesión nueva y selecciona `q-flow`.
-
-### Qoder Desktop
-
-**Recomendado:** Abre **Settings → Plugins → Marketplace**, busca **QGraphFlow** o **代码图谱可视化** e instala el complemento. Inicia una sesión nueva y selecciona `q-flow`.
-
-Para una instalación local, completa primero el paso 1. Después abre **Settings → Plugins → Custom → Import** e importa el directorio raíz completo del complemento. Recarga el cliente y selecciona `q-flow`.
-
-### Cursor
-
-Copia todo el contenido de la raíz del complemento, incluidos los archivos ocultos, a `~/.cursor/plugins/local/qgraphflow/`. Si el directorio ya existe, haz una copia de seguridad antes; no mezcles archivos antiguos y nuevos.
-
-Comprueba que el manifiesto esté en `~/.cursor/plugins/local/qgraphflow/.cursor-plugin/plugin.json`. Recarga la ventana y selecciona `q-flow` en Customize → Plugins / Skills.
-
-Este método local se probó en Cursor 3.19.13. En otras versiones, comprueba que aparezcan tanto el complemento como la habilidad.
diff --git a/docs/clients.ja.md b/docs/clients.ja.md
deleted file mode 100644
index cff8b35..0000000
--- a/docs/clients.ja.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# インストールガイド
-
-[English](clients.md) · [中文](clients.zh-CN.md) · [Русский](clients.ru.md) · [Português](clients.pt.md) · [日本語](clients.ja.md) · [Deutsch](clients.de.md) · [Español](clients.es.md)
-
-[README に戻る](readme/README.ja.md)
-
-Qoder Desktop ではマーケットプレイスからインストールでき、手順 1 は不要です(下記の該当項を参照)。その他のクライアントでは、npmjs.com から取得したプラグインパッケージをインストールします。
-
-Node.js 22 以降(npm を含む)と、モデルへのアクセスを設定済みのクライアントが必要です。
-
-## クイックインストール
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Claude Code、Codex、Cursor、Qoder にスキル `q-flow` を導入します(`skills` 1.7.0 で実測済み)。導入先のクライアントを尋ねられます。プラグインとして導入する場合は、次の手順に従ってください。
-
-## 1. npm からプラグインをダウンロード
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-ディレクトリは業務プロジェクトの外に作成します。アカウント、ログイン、トークンは不要です。これでプラグインのルートディレクトリに移動できました。npm でダウンロードしてもクライアントへのインストールは自動では行われないため、手順 2 に進んでください。未リリースのコードをインストールする場合は、[ソースからのビルド手順](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally)を参照してください。
-
-## 2. クライアントにインストール
-
-以下のコマンドは、自分の業務プロジェクトではなく、手順 1 で移動したプラグインのルートディレクトリ(`qgraphflow-install/node_modules/qgraphflow`)で実行します。
-
-### Codex App / CLI
-
-```bash
-codex plugin marketplace add .
-codex plugin add qgraphflow@supermax92
-```
-
-ここでの `marketplace add` はローカルのインストール元を登録するだけで、公開マーケットプレイスへの掲載は不要です。[OpenAI 公式ドキュメント](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli)を参照してください。
-
-新しいセッションを開始し、`$` を入力して `qgraphflow:q-flow` を選択します(クライアントに実際に表示される名前を使用してください)。
-
-### Claude Code
-
-```bash
-claude plugin marketplace add ./
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-新しいセッションを開始し、`/q-flow`(または完全名 `/qgraphflow:q-flow`)を入力します。
-
-### Qoder CLI
-
-```bash
-qodercli plugins install .
-```
-
-新しいセッションを開始し、`q-flow` を選択します。
-
-### Qoder Desktop
-
-**推奨:** **Settings → Plugins → Marketplace** を開き、**QGraphFlow** または **代码图谱可视化** を検索してインストールします。新しいセッションを開始し、`q-flow` を選択します。
-
-ローカルインストールの場合は手順 1 を完了し、**Settings → Plugins → Custom → Import** を開いて、プラグインのルートディレクトリ全体をインポートします。再読み込み後、`q-flow` を選択します。
-
-### Cursor
-
-プラグインのルートディレクトリの内容を隠しファイルも含めてすべて `~/.cursor/plugins/local/qgraphflow/` にコピーします。既存のディレクトリがある場合は先にバックアップし、新旧のファイルを混在させないでください。
-
-マニフェストが `~/.cursor/plugins/local/qgraphflow/.cursor-plugin/plugin.json` にあることを確認します。ウィンドウを再読み込みし、Customize → Plugins / Skills で `q-flow` を選択します。
-
-このローカル方式は Cursor 3.19.13 で検証済みです。他のバージョンでは、プラグインとスキルが表示されることを確認してください。
diff --git a/docs/clients.md b/docs/clients.md
index 4308b01..3bee4ab 100644
--- a/docs/clients.md
+++ b/docs/clients.md
@@ -1,8 +1,8 @@
# Installation guide
-[English](clients.md) · [中文](clients.zh-CN.md) · [Русский](clients.ru.md) · [Português](clients.pt.md) · [日本語](clients.ja.md) · [Deutsch](clients.de.md) · [Español](clients.es.md)
+[English](clients.md) · [中文](clients.zh-CN.md)
-[Back to README](../README.md)
+[Back to README](../README.en.md)
Qoder Desktop can install the plugin from its marketplace and skip step 1 (see its section below). The other clients install the plugin package from npmjs.com.
diff --git a/docs/clients.pt.md b/docs/clients.pt.md
deleted file mode 100644
index be22326..0000000
--- a/docs/clients.pt.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# Guia de instalação
-
-[English](clients.md) · [中文](clients.zh-CN.md) · [Русский](clients.ru.md) · [Português](clients.pt.md) · [日本語](clients.ja.md) · [Deutsch](clients.de.md) · [Español](clients.es.md)
-
-[Voltar ao README](readme/README.pt.md)
-
-O Qoder Desktop pode instalar o plugin pelo Marketplace e pular a etapa 1 (veja a seção correspondente abaixo). Os demais clientes instalam o pacote do plugin obtido no npmjs.com.
-
-Você precisa de Node.js 22 ou posterior (com npm) e de um cliente com acesso ao modelo configurado.
-
-## Instalação rápida
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Instala a habilidade `q-flow` no Claude Code, Codex, Cursor e Qoder (testado com `skills` 1.7.0) e pergunta em quais clientes instalar. Para instalar o plugin, siga as etapas abaixo.
-
-## 1. Baixar o plugin pelo npm
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-Crie o diretório fora do projeto da sua aplicação; não é preciso conta, login nem token. Agora você está na raiz do plugin. Baixar pelo npm não instala o plugin no cliente; continue na etapa 2. Para instalar código ainda não lançado, consulte as [instruções de compilação a partir do código-fonte](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
-
-## 2. Instalar no cliente
-
-Execute os comandos abaixo na raiz do plugin aberta na etapa 1 (`qgraphflow-install/node_modules/qgraphflow`), não no diretório do seu próprio projeto.
-
-### Codex App / CLI
-
-```bash
-codex plugin marketplace add .
-codex plugin add qgraphflow@supermax92
-```
-
-Aqui, `marketplace add` apenas registra uma fonte de instalação local; não exige publicação em um marketplace público. Consulte a [documentação oficial da OpenAI](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli).
-
-Inicie uma nova sessão, digite `$` e selecione `qgraphflow:q-flow` (use o nome exibido pelo seu cliente).
-
-### Claude Code
-
-```bash
-claude plugin marketplace add ./
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Inicie uma nova sessão e digite `/q-flow` (ou o nome completo `/qgraphflow:q-flow`).
-
-### Qoder CLI
-
-```bash
-qodercli plugins install .
-```
-
-Inicie uma nova sessão e selecione `q-flow`.
-
-### Qoder Desktop
-
-**Recomendado:** Abra **Settings → Plugins → Marketplace**, pesquise **QGraphFlow** ou **代码图谱可视化** e instale o plugin. Inicie uma nova sessão e selecione `q-flow`.
-
-Para uma instalação local, conclua primeiro a etapa 1. Depois, abra **Settings → Plugins → Custom → Import** e importe o diretório raiz completo do plugin. Recarregue o cliente e selecione `q-flow`.
-
-### Cursor
-
-Copie todo o conteúdo da raiz do plugin, incluindo arquivos ocultos, para `~/.cursor/plugins/local/qgraphflow/`. Se o diretório já existir, faça um backup antes; não misture arquivos antigos e novos.
-
-Confirme que o manifesto está em `~/.cursor/plugins/local/qgraphflow/.cursor-plugin/plugin.json`. Recarregue a janela e selecione `q-flow` em Customize → Plugins / Skills.
-
-Esse método local foi testado no Cursor 3.19.13. Em outras versões, confirme que o plugin e a habilidade aparecem.
diff --git a/docs/clients.ru.md b/docs/clients.ru.md
deleted file mode 100644
index ade4691..0000000
--- a/docs/clients.ru.md
+++ /dev/null
@@ -1,74 +0,0 @@
-# Руководство по установке
-
-[English](clients.md) · [中文](clients.zh-CN.md) · [Русский](clients.ru.md) · [Português](clients.pt.md) · [日本語](clients.ja.md) · [Deutsch](clients.de.md) · [Español](clients.es.md)
-
-[Вернуться к README](readme/README.ru.md)
-
-В Qoder Desktop плагин можно установить из Marketplace и пропустить шаг 1 (см. соответствующий раздел ниже). Остальные клиенты устанавливают пакет плагина с npmjs.com.
-
-Нужны Node.js 22 или новее (с npm) и клиент с настроенным доступом к модели.
-
-## Быстрая установка
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Устанавливает навык `q-flow` для Claude Code, Codex, Cursor и Qoder (проверено с `skills` 1.7.0) и спрашивает, в какие клиенты устанавливать. Чтобы установить плагин, выполните шаги ниже.
-
-## 1. Скачать плагин из npm
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-Создайте каталог вне своего рабочего проекта; учётная запись, вход и токен не нужны. Теперь вы в корневом каталоге плагина. Загрузка через npm не устанавливает плагин в клиент — перейдите к шагу 2. Чтобы установить ещё не выпущенный код, см. [инструкции по сборке из исходников](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
-
-## 2. Установить в клиент
-
-Выполняйте команды ниже из корневого каталога плагина, в который вы перешли на шаге 1 (`qgraphflow-install/node_modules/qgraphflow`), а не из каталога вашего приложения.
-
-### Codex App / CLI
-
-```bash
-codex plugin marketplace add .
-codex plugin add qgraphflow@supermax92
-```
-
-Здесь `marketplace add` только регистрирует локальный источник установки; публикация в маркетплейсе не требуется. См. [официальную документацию OpenAI](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli).
-
-Начните новый сеанс, введите `$` и выберите `qgraphflow:q-flow` (используйте имя, которое показывает ваш клиент).
-
-### Claude Code
-
-```bash
-claude plugin marketplace add ./
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Начните новый сеанс и введите `/q-flow` (или полное имя `/qgraphflow:q-flow`).
-
-### Qoder CLI
-
-```bash
-qodercli plugins install .
-```
-
-Начните новый сеанс и выберите `q-flow`.
-
-### Qoder Desktop
-
-**Рекомендуется:** Откройте **Settings → Plugins → Marketplace**, найдите **QGraphFlow** или **代码图谱可视化** и установите плагин. Начните новый сеанс и выберите `q-flow`.
-
-Для локальной установки выполните шаг 1, затем откройте **Settings → Plugins → Custom → Import** и импортируйте весь корневой каталог плагина. Перезагрузите клиент и выберите `q-flow`.
-
-### Cursor
-
-Скопируйте всё содержимое корневого каталога плагина, включая скрытые файлы, в `~/.cursor/plugins/local/qgraphflow/`. Если каталог уже существует, сначала сделайте резервную копию; не смешивайте старые и новые файлы.
-
-Убедитесь, что манифест находится по адресу `~/.cursor/plugins/local/qgraphflow/.cursor-plugin/plugin.json`. Перезагрузите окно и выберите `q-flow` в Customize → Plugins / Skills.
-
-Этот способ локальной установки проверялся в Cursor 3.19.13. В других версиях убедитесь, что плагин и навык отображаются.
diff --git a/docs/clients.zh-CN.md b/docs/clients.zh-CN.md
index 5f2290e..607e648 100644
--- a/docs/clients.zh-CN.md
+++ b/docs/clients.zh-CN.md
@@ -1,8 +1,8 @@
# 安装指南
-[English](clients.md) · [中文](clients.zh-CN.md) · [Русский](clients.ru.md) · [Português](clients.pt.md) · [日本語](clients.ja.md) · [Deutsch](clients.de.md) · [Español](clients.es.md)
+[English](clients.md) · [中文](clients.zh-CN.md)
-[返回 README](readme/README.zh-CN.md)
+[返回 README](../README.md)
Qoder Desktop 可从插件商城安装,跳过第 1 步(见下方对应小节)。其他客户端安装从 npmjs.com 下载的插件包。
diff --git a/docs/distribution.md b/docs/distribution.md
index 9773e8a..0dc793e 100644
--- a/docs/distribution.md
+++ b/docs/distribution.md
@@ -27,7 +27,7 @@ Use new output directories. Packaging refuses to overwrite existing outputs. `np
## Publish only after confirmation
1. Confirm the GitHub repository URL, commit author name/email, commit message, and the changes to include. `main` accepts changes only through a pull request (ruleset `main-pr-required-no-bypass`); commit on a branch, open the pull request and merge it once CI is green.
-2. Keep the media Releases `showcase-v1` (historical) and `showcase-v2` (current README recordings) separate from software `v0.0.7`. Their attachments stay on GitHub until their removal is confirmed separately; do not move old tags or mark a media-only Release as the latest software release.
+2. Keep the media Releases `showcase-v1`, `showcase-v2` (historical) and `showcase-v3` (current README recordings, made with `scripts/record-showcase.mjs`) separate from software `v0.0.7`. Their attachments stay on GitHub until their removal is confirmed separately; do not move old tags or mark a media-only Release as the latest software release.
3. The READMEs link the real-source Jeepay corpus. Public examples and smoke tests use this corpus; historical sample recordings are no longer linked.
4. Re-run checks, commit the confirmed source changes, and merge them into `main` through the pull request. Do not force-push or mirror-push. Media must not enter the commit; Codex's private `refs/codex/` snapshots are not release refs.
5. Build runtime archives from the confirmed commit, record their SHA-256 checksums, verify the extracted package, and attach them to software Release `v0.0.7`. GitHub's automatic **Source code** archives are full source snapshots, not the slim plugin installer.
@@ -42,7 +42,7 @@ Track marketplace releases separately from GitHub Releases and npm packages. For
## Online demo
-`.github/workflows/pages.yml` checks out the Jeepay revision recorded in `examples/jeepay/source.json`, builds all eleven coordinate-free views with the committed prebuilt Viewer and verifies their source anchors with `--repo-root`. It serves `site/jeepay/zh-CN/` and uses `docs/pages/index.html` as the home page. The page folder also serves its `graph.json` and SVGs.
+`.github/workflows/pages.yml` checks out the Jeepay revision recorded in `examples/jeepay/source.json`, builds all nine coordinate-free views with the committed prebuilt Viewer and verifies their source anchors with `--repo-root`. It serves `site/jeepay/zh-CN/` and uses `docs/pages/index.html` as the home page. `scripts/showcase-changes.mjs` derives an earlier version of the component relations view, and `generate-viewer.mjs --compare` marks what changed in `site/jeepay/changes/zh-CN/` and `site/jeepay/changes/en/`; the README `changes` clip records the same comparison. The page folder also serves its `graph.json` and SVGs.
Pull requests that touch the examples, the generator, the prebuilt Viewer, `docs/pages/` or the workflow run the build as a smoke test; pushes to `main` also deploy it. The site is uploaded as a Pages artifact and never enters a branch, and a failed build leaves the previous deployment online. Before the first deployment, set **Settings → Pages → Build and deployment → Source** to **GitHub Actions**.
diff --git a/docs/pages/index.html b/docs/pages/index.html
index d68d15d..60b934b 100644
--- a/docs/pages/index.html
+++ b/docs/pages/index.html
@@ -14,8 +14,10 @@
-
-### Aus komplexem Code werden Diagramme zum Erkunden.
-
-Pfade verfolgen. Belege prüfen. Eine Offline-Datei teilen.
-
-💡 Inspiriert von Cocoon-AI/architecture-diagram-generator – vielen Dank für die Anregung.
-
-[English](../../README.md) · [中文](../../docs/readme/README.zh-CN.md) · [Русский](../../docs/readme/README.ru.md) · [Português](../../docs/readme/README.pt.md) · [日本語](../../docs/readme/README.ja.md) · [Deutsch](../../docs/readme/README.de.md) · [Español](../../docs/readme/README.es.md)
-
-[Online-Demo](https://supermax92.github.io/qgraphflow/) · [Erste Schritte](#erste-schritte) · [Client-Installation](#installationsanleitung) · [Problem melden](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
-
-
-
-*Elf Diagrammarten: Plattformfähigkeitsarchitektur, Architektur der Engineering-Schichten, Komponentenbeziehungsarchitektur, Flussdiagramm, Sequenz, ER, Bereitstellung, Klasse, Zustand, Anwendungsfall und Datenfluss.*
-
-QGraphFlow erzeugt interaktive Softwarediagramme aus Quellcode, Datenstrukturen, Konfiguration und Anforderungen. Beziehungen bleiben überprüfbar; das Ergebnis lässt sich als Offline-HTML teilen.
-
-**Was es auszeichnet:** elf Diagrammarten in einem Skill, eine Belegart für jede Beziehung und die Quellzeile hinter jeder durch Code gestützten, automatisches Layout, Bearbeiten direkt auf der Seite und keine Netzwerkanfragen von den Plugin-Skripten oder dem Viewer selbst.
-
-
-
-Wechsle anhand des echten Jeepay-Quellcodes zwischen Komponentenbeziehungsarchitektur, Sequenz- und ER-Diagrammen, um Komponenten und Aufrufbeziehungen zu erkunden. [GIF in Originalgröße ansehen](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.en.hero.gif)
-
-**Präsentation eines komplexen Sequenzdiagramms**
-
-
-
-Ein fiktives E-Commerce-Szenario enthält 9 Teilnehmer, 29 Nachrichten und 6 kombinierte Fragmente mit Bestandswiederholungen, verschachtelten Zweigen, paralleler Verarbeitung, Fehlerkompensation und asynchronen Rückrufen. Die Animation zeigt das erzeugte Diagramm schrittweise und macht seine Struktur und Details sichtbar. [GIF in Originalgröße ansehen](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.en.sequence-drawing.gif)
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Ein Befehl installiert den Skill für Claude Code, Codex, Cursor und Qoder; die Installation als Plugin und weitere Clients beschreibt die [Installationsanleitung](#installationsanleitung).
-
-- **Erkunden:** suchen, zoomen und verschieben; Verantwortlichkeiten sowie ein- und ausgehende Beziehungen verstehen.
-
-- **Prüfen:** Dateien, Zeilen, Symbole und ausdrücklich gekennzeichnete Unsicherheiten an Knoten und Kanten untersuchen.
-
-- **Bearbeiten:** Layout entsperren, Texte ändern und Elemente verschieben; bei Bedarf zurücksetzen.
-
-- **Teilen:** Offline-HTML öffnen oder das vollständige Diagramm als SVG / PNG exportieren.
-
-Der auf echtem Quellcode beruhende [Jeepay-Korpus](../../examples/jeepay) enthält alle elf Ansichten, die CI und die Online-Demo verwenden.
-
-## Erste Schritte
-
-Öffne nach der Installation dein Geschäftsprojekt im Client und wähle den Skill `q-flow`. Die Beispiele verwenden `/q-flow` in Claude Code; in Codex verwendest du den Eintrag `$q-flow` oder `$qgraphflow:q-flow`, den dein Client tatsächlich anbietet. Noch nicht installiert? Lies zuerst die [Installationsanleitung](#installationsanleitung).
-
-### 1. Leere Eingabe: Du weißt nicht, wo du anfangen sollst
-
-Rufe den Skill ohne zusätzliche Anforderungen auf:
-
-```text
-/q-flow
-```
-
-Der Skill hilft dir, den zu analysierenden Teil und die Frage auszuwählen, die das Diagramm beantworten soll. Sobald die nötigen Informationen geklärt sind, beginnt das Zeichnen.
-
-### 2. Nach Fähigkeiten fragen: Erfahren, was er zeichnen kann
-
-```text
-/q-flow Welche Diagrammarten kannst du zeichnen? Welche Fragen beantwortet jede Art? Ich habe gerade ein Projekt übernommen; stelle deine Fähigkeiten vor und schlage einen Einstieg vor.
-```
-
-Lerne zuerst die Einsatzgebiete der elf Diagrammarten kennen. Entscheide dann, ob du Projektstruktur, Aufrufreihenfolge, Datenbeziehungen oder etwas anderes betrachten möchtest.
-
-### 3. Vage Eingabe: Nur ein grobes Ziel
-
-```text
-/q-flow Hilf mir, dieses Projekt zu zeichnen. Ich möchte es möglichst schnell verstehen.
-```
-
-Du musst vorher keine Diagrammart angeben. Der Skill bestimmt anhand des Projekts und deines Ziels eine passende Ansicht und fragt nach, wenn notwendige Informationen fehlen.
-
-### 4. Präzise Eingabe: Umfang festlegen und Zeichnungsdetails anfordern
-
-Ersetze die folgenden Geschäftsbegriffe und Schritte durch Abläufe, die tatsächlich in deinem Projekt vorkommen:
-
-```text
-/q-flow Analysiere die Bestellerstellung im aktuellen Projekt und erzeuge ein Sequenzdiagramm auf Chinesisch.
-Berücksichtige den Anfrageeingang, die Preisberechnung, Bestandsreservierung, Zahlungsautorisierung und Speicherung der Bestellung.
-Erhalte die synchronen Aufrufe, asynchronen Nachrichten, gepaarten Rückgaben, Aktivierungsbalken, bedingten Zweige, Wiederholungen und Fehlerkompensationen, die tatsächlich im Quellcode vorkommen. Lasse keine Details zugunsten der Kürze weg.
-Kennzeichne Quelldateien und Zeilennummern der Komponenten und Aufrufe und speichere das Ergebnis unter docs/qgraphflow/order-sequence/.
-```
-
-Benenne Gegenstand, Frage, Detailgrad und Ausgabeort klar, damit es direkt losgehen kann. Das Diagramm enthält nur durch Belege gestützte Fakten.
-
-### 5. Weiter verfeinern: Einen Teil des letzten Diagramms vertiefen
-
-Fahre nach der Erzeugung des Ergebnisses im selben Gespräch fort:
-
-```text
-/q-flow Vertiefe die Bestandsreservierung aus dem letzten Sequenzdiagramm als separates Flussdiagramm auf Chinesisch.
-Zeige sämtliche Zweige für Bestandsprüfung, erfolgreiche Reservierung, wiederholbare Fehler, Wiederholungslimit und Bestandsfreigabe. Halte dich an den Quellcode und füge keine dort fehlenden Schritte hinzu.
-```
-
-Betrachte zuerst das Ganze und vertiefe dann einen Schritt. Du kannst auch weitere Details für ein vorhandenes Diagramm anfordern oder seine Beziehungen prüfen.
-
-## Installationsanleitung
-
-Benötigt werden Node.js 22 oder neuer und ein Client mit Plugin-Unterstützung und eingerichtetem Modellzugriff.
-
-### Schnellinstallation
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Getestet mit `skills` 1.7.0 für Claude Code, Codex, Cursor und Qoder. Der Befehl fragt, in welche Clients installiert werden soll; `-a claude-code` gibt einen direkt an, `-g` installiert für den eigenen Benutzer statt für das aktuelle Projekt. Der Skill heißt danach `q-flow`, ohne das Präfix `qgraphflow:` der Plugin-Installationen unten.
-
-Für die Installation als Plugin den folgenden Schritten folgen. [Qoder Desktop](#qoder-desktop) kann das Plugin direkt aus dem Marketplace installieren; Schritt 1 entfällt.
-
-### 1. Plugin herunterladen
-
-Das Plugin von npmjs.com beziehen, ohne Konto, Anmeldung oder Token. Ein eigenes Verzeichnis außerhalb des Anwendungsprojekts erstellen:
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-Nun befindet man sich im Plugin-Stammverzeichnis. **Der Download über npm installiert das Plugin nicht automatisch im Client;** mit Schritt 2 fortfahren. Das Paket stellt außerdem den Befehl `qgraphflow` bereit, den [Diagramme mit dem Code synchron halten](#diagramme-mit-dem-code-synchron-halten) verwendet.
-
-Alle folgenden Terminalbefehle im **Plugin-Stammverzeichnis mit `skills/`** ausführen.
-
-### 2. Im gewünschten Client installieren
-
-#### Codex App / CLI
-
-Codex CLI muss installiert und im Terminal verfügbar sein:
-
-```bash
-codex plugin marketplace add .
-codex plugin add qgraphflow@supermax92
-```
-
-Eine neue Sitzung starten, `$` eingeben und `qgraphflow:q-flow` auswählen.
-
-#### Claude Code
-
-```bash
-claude plugin marketplace add ./
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Eine neue Sitzung starten und `/q-flow` (oder den vollständigen Namen `/qgraphflow:q-flow`) eingeben.
-
-#### Qoder CLI
-
-```bash
-qodercli plugins install .
-```
-
-Eine neue Sitzung starten und `q-flow` auswählen.
-
-#### Qoder Desktop
-
-**Empfohlen:** Öffne **Settings → Plugins → Marketplace**, suche nach **QGraphFlow** oder **代码图谱可视化** und installiere das Plugin. Starte eine neue Sitzung und wähle `q-flow`.
-
-Für eine lokale Installation führe zuerst Schritt 1 aus. Öffne dann **Settings → Plugins → Custom → Import** und importiere das vollständige Plugin-Stammverzeichnis. Starte eine neue Sitzung und wähle `q-flow`.
-
-#### Cursor
-
-Den gesamten Inhalt des Plugin-Stammverzeichnisses einschließlich versteckter Dateien hierhin kopieren:
-
-```text
-~/.cursor/plugins/local/qgraphflow/
-```
-
-Prüfen, ob dort `.cursor-plugin/plugin.json` vorhanden ist, das Fenster neu laden und `q-flow` unter **Customize** suchen. Eine vorhandene ältere Version zuerst sichern; alte und neue Dateien nicht vermischen.
-
-### 3. Loslegen
-
-Öffne dein Geschäftsprojekt im Client, starte eine neue Sitzung und wähle den Skill. Beschreibe deine Anforderungen anhand der Beispiele unter [Erste Schritte](#erste-schritte). Öffne das erzeugte HTML im Browser.
-
-Selbst bauen? Siehe [Anleitung zum Bauen aus dem Quellcode](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
-
-## Schnell verwenden
-
-Die Beispiele verwenden `$qgraphflow:q-flow` in Codex. Zeigt der Client `$q-flow`, diesen Eintrag wählen. In anderen Clients den oben beschriebenen Skill-Aufruf verwenden.
-
-**Noch kein Ausgangspunkt?** Den Skill aufrufen und auf Nachfrage Gegenstand und Fragestellung auswählen.
-
-```text
-$qgraphflow:q-flow
-```
-
-**Das Ziel steht fest?** Beschreiben, welchen Teil das Diagramm zeigen und welche Frage es beantworten soll. Die Diagrammart muss nicht vorab gewählt werden.
-
-### Beispiel 1: Projektarchitektur verstehen
-
-```text
-$qgraphflow:q-flow Analysiere dieses Projekt und erstelle ein chinesisches Architekturdiagramm mit Verantwortlichkeiten der Module, Abhängigkeiten und Systemgrenzen.
-```
-
-Geeignet, um sich erstmals einen Überblick über ein Projekt zu verschaffen.
-
-### Beispiel 2: Einen Geschäftsablauf verfolgen
-
-```text
-$qgraphflow:q-flow Analysiere die Bestellerstellung und erstelle ein chinesisches Sequenzdiagramm für Preisberechnung, Bestandsreservierung, Zahlung und Speicherung der Bestellung, einschließlich Fehlerzweigen.
-```
-
-Bestellerstellung und Schritte durch den tatsächlichen Projektablauf ersetzen. Im selben Gespräch weiterfragen:
-
-```text
-$qgraphflow:q-flow Vertiefe die Bestandsreservierung aus dem letzten Diagramm als separates chinesisches Flussdiagramm mit Erfolgs- und Fehlerbehandlung.
-```
-
-Ergebnisse landen standardmäßig unter `docs/qgraphflow/`. `index.html` zum Erkunden, Bearbeiten und Exportieren öffnen; `graph.json` enthält die Diagrammdaten. Jede Ansicht wird außerdem als SVG geschrieben (`diagram.svg`, bei mehreren Ansichten `diagram--.svg`), das sich als Bild in eine README, einen Pull Request oder ein Wiki einbinden lässt.
-
-Nach Änderungen auf der Seite schreibt **Mehr → Änderungen speichern** in Chrome oder Edge Seite, `graph.json` und SVGs direkt zurück, sobald der Diagrammordner einmal gewählt ist. Andere Browser speichern nur `graph.json`: die Datei in den Ordner legen und Seite und SVGs mit `npx -y qgraphflow generate docs/qgraphflow//graph.json docs/qgraphflow/ --layout preserve --force` neu erzeugen.
-
-
-Das Jeepay-Quellcodebeispiel mit elf Ansichten ausführen
-
-Wähle deine lokale Jeepay-Quellcodekopie, um die Belege zu prüfen:
-
-```bash
-export JEEPAY_REPO_ROOT=""
-node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.json --input-only --repo-root "$JEEPAY_REPO_ROOT"
-node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"
-```
-
-Öffne `output/jeepay/index.html`; die elf SVGs liegen im selben Verzeichnis. Die Quellcoderevision und das Aktualisierungsverfahren stehen in der [Korpus-README](../../examples/jeepay).
-
-
-
-## Diagramme mit dem Code synchron halten
-
-Ein mit Repository-Wurzel erzeugtes Diagramm hält fest, wo jede Komponente definiert ist, und die Zeile hinter jeder durch Code gestützten Beziehung (ein Aufruf, ein Fremdschlüssel). Die Prüfung mit `--repo-root` schlägt fehl, wenn eine erfasste Datei fehlt, ein Zeilenbereich nicht mehr in die Datei passt oder ein erfasstes Symbol seine Zeilen verlassen hat; die Meldung nennt die Zeilen, in denen das Symbol jetzt steht. Diesen Job in die CI aufnehmen; er braucht keinen Build, keine Anmeldung und kein Token:
-
-```yaml
-name: Diagrams
-on: [push, pull_request]
-jobs:
- diagrams:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v7
- - uses: actions/setup-node@v7
- with:
- node-version: '22'
- - run: |
- for graph in docs/qgraphflow/*/graph.json; do
- npx -y qgraphflow validate "$graph" --input-only --repo-root . || { echo "::error file=$graph::$graph failed validation"; failed=1; }
- done
- exit ${failed:-0}
-```
-
-Schlägt er fehl, den Skill bitten, dieses Diagramm zu aktualisieren:
-
-```text
-$qgraphflow:q-flow Laut CI ist docs/qgraphflow/order-sequence veraltet. Bitte aktualisieren.
-```
-
-Der Skill verschiebt Anker, deren Symbol er genau einmal in der Datei findet, korrigiert nur die weiterhin gemeldeten Anker und erzeugt Seite und SVGs neu, wobei bearbeitete Positionen und Texte erhalten bleiben. Er zeichnet das Diagramm nicht neu.
-
-## Welche Fragen die elf Diagrammarten beantworten
-
-| Ansicht · PNG | Hauptfrage | Umfang des Beispiels |
-| --- | --- | --- |
-| Plattformfähigkeitsarchitektur | Welche Fähigkeiten bietet die Plattform? | Fähigkeitsbereiche und Matrizen |
-| Architektur der Engineering-Schichten | Wie ist der Projektcode organisiert? | Engineering-Schichten und gemeinsame Unterstützung |
-| Komponentenbeziehungsarchitektur | Welche Verantwortungsgrenzen arbeiten im System zusammen? | Kanäle, Transaktionsorchestrierung, Preise, Risiko, Bestand, Zahlung, Bestellungen, Ereignisse und Auftragsabwicklung |
-| Flussdiagramm | Wie verzweigt und vereinigt sich jeder Entscheidungspunkt? | Fehlbestand, Risikoablehnung, Kompensation bei Zahlungsfehlern und erfolgreicher Commit |
-| Sequenz | In welcher Reihenfolge führt eine Anfrage Aufrufe aus und erhält Rückgaben? | Hauptpfad eines erfolgreichen Kaufabschlusses und asynchrones OrderPaid |
-| ER | Wie hängen die Kerndaten zusammen? | Warenkorb, Bestellungen, Positionen, Zahlungen, Bestandsreservierungen und Pakete |
-| Bereitstellung | Wo werden Laufzeiteinheiten platziert und wie sind sie verbunden? | Randnetz, Kubernetes, Datendienste, Zahlung und Lager-/Logistiknetze |
-| Klasse | Wie hängen Domänenobjekte und Codeverträge voneinander ab? | Checkout-Anwendungsdienst, Order und vier Ports |
-| Zustand | Welche Ereignisse und Wächterbedingungen treiben eine Bestellung voran? | Zahlung, Auftragsabwicklung, Stornierung, Erstattung und Abschluss |
-| Anwendungsfall | Welche Fähigkeiten besitzt jeder Akteur? | Käufer, Händler, Lager und Kundendienst |
-| Datenfluss | Welche Transformationen und Speicher durchlaufen Datenbestände? | Warenkorb, Transaktionsentscheidungen, Bestellereignisse, Lager/Logistik und Lieferbelege |
-
-Dies ist ein Konzeptmodell zur Demonstration von QGraphFlow, kein konkretes E-Commerce-Repository. Die Beispieldatei `graph.json` erfindet keine Quellpfade und kennzeichnet Beziehungen mit `inference`. Echte Projektdiagramme benötigen nachvollziehbaren Quellcode, DDL, Konfiguration, Tests und akzeptierte Anforderungen.
-
-## Entwickeln und beitragen
-
-```bash
-npm ci --prefix skills/q-flow/assets/viewer
-npm run build --prefix skills/q-flow/assets/viewer
-node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs
-```
-
-Erforderlich sind Node.js 22 oder neuer, npm, tar, zip und unzip. Fehlerberichte sollten ein minimales anonymisiertes Diagramm, Client- und Browserversion sowie Reproduktionsschritte enthalten.
-
-Referenzdokumentation (Englisch): [Belegquellen](../../skills/q-flow/references/evidence-sources.md) · [Diagrammformat](../../skills/q-flow/references/graph-schema.md) · [Geführte Bedarfsklärung](../../skills/q-flow/references/guided-intake.md) · [Viewer-Entwicklung und Abnahme](../../skills/q-flow/references/viewer-development.md) · [Diagrammgestaltung](../../skills/q-flow/references/visual-contract.md)
-
-## Lizenz und Zuordnung
-
-[MIT](../../LICENSE) · [Drittanbieterhinweise](../../THIRD_PARTY_NOTICES.md)
-
-QGraphFlow ist ein unabhängiges Projekt unter MIT-Lizenz. Die Szenarien in diesem Dokument sind konzeptionelle Beispiele und stellen keine Produktionsarchitektur eines realen Unternehmens dar.
-
-## Architekturübersichten
-
-Architektur umfasst jetzt Komponentenbeziehungen, Plattformfähigkeiten und Engineering-Schichten. Beschreibe den Gegenstand und die Frage; der Skill wählt die Vorlage. Angeforderte Sammlungen können mehrere Architekturansichten mit unabhängigen Bearbeitungen enthalten.
-
-```text
-$qgraphflow:q-flow Analysiere die Plattformfähigkeiten und die geschäftlichen Integrationswege des aktuellen Projekts und erzeuge eine Übersicht der Plattformfähigkeiten auf Chinesisch.
-$qgraphflow:q-flow Analysiere die Organisation des aktuellen Projekts und seine Komponentenschichten und erzeuge chinesische Übersichten des Gesamtprojekts und eines Komponentenquerschnitts.
-$qgraphflow:q-flow Erzeuge eine englische Übersicht der Plattformfähigkeiten dieses Projekts und zeige, wie sich Anwendungsmodule integrieren.
-```
-
-Siehe [examples/jeepay](../../examples/jeepay) für quellenbasierte Architekturansichten zu Plattform, Engineering und Komponentenbeziehungen. Entsperre eine Übersicht, um Karten innerhalb einer Schicht neu anzuordnen oder Texte zu bearbeiten. Speichern erhält alle Ansichten; Zurücksetzen stellt nur die aktuelle wieder her.
diff --git a/docs/readme/README.es.md b/docs/readme/README.es.md
deleted file mode 100644
index 0ee215c..0000000
--- a/docs/readme/README.es.md
+++ /dev/null
@@ -1,311 +0,0 @@
-
-
-
-
-### Convierte código complejo en diagramas que puedes explorar.
-
-Sigue el recorrido. Comprueba las evidencias. Comparte un archivo sin conexión.
-
-💡 Inspirado en Cocoon-AI/architecture-diagram-generator; gracias por la idea.
-
-[English](../../README.md) · [中文](../../docs/readme/README.zh-CN.md) · [Русский](../../docs/readme/README.ru.md) · [Português](../../docs/readme/README.pt.md) · [日本語](../../docs/readme/README.ja.md) · [Deutsch](../../docs/readme/README.de.md) · [Español](../../docs/readme/README.es.md)
-
-[Demo en línea](https://supermax92.github.io/qgraphflow/) · [Primeros pasos](#primeros-pasos) · [Instalación por cliente](#guía-de-instalación) · [Informar de un problema](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
-
-
-
-*Once tipos de diagramas: arquitectura de capacidades de la plataforma, arquitectura por capas de ingeniería, arquitectura de relaciones entre componentes, diagrama de flujo, secuencia, ER, despliegue, clases, estados, casos de uso y flujo de datos.*
-
-QGraphFlow genera diagramas de software interactivos a partir del código, los esquemas, la configuración y los requisitos. Permite comprobar las relaciones y compartir el resultado como HTML sin conexión.
-
-**Qué lo distingue:** once tipos de diagrama en una sola habilidad, un tipo de evidencia en cada relación y la línea de código detrás de cada una respaldada por código, diseño automático, edición en la propia página y ninguna solicitud de red de los scripts del complemento ni del propio Viewer.
-
-
-
-Con el código fuente real de Jeepay, alterna entre diagramas de arquitectura de relaciones entre componentes, secuencia y ER para explorar componentes y relaciones de llamadas. [Ver GIF a tamaño original](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.en.hero.gif)
-
-**Presentación de un diagrama de secuencia complejo**
-
-
-
-Un escenario ficticio de comercio electrónico contiene 9 participantes, 29 mensajes y 6 fragmentos combinados, con reintentos de inventario, ramas anidadas, procesamiento paralelo, compensación de fallos y callbacks asíncronos. La animación muestra gradualmente el diagrama generado para presentar su estructura y sus detalles. [Ver GIF a tamaño original](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.en.sequence-drawing.gif)
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Un solo comando instala la habilidad para Claude Code, Codex, Cursor y Qoder; la instalación como complemento y los demás clientes están en la [guía de instalación](#guía-de-instalación).
-
-- **Explorar:** buscar, ampliar y desplazar el lienzo; consultar responsabilidades y relaciones entrantes y salientes.
-
-- **Verificar:** inspeccionar nodos y conexiones para revisar archivos, líneas, símbolos e incertidumbres explícitas.
-
-- **Editar:** desbloquear el diseño, cambiar textos y mover elementos; restablecer cuando sea necesario.
-
-- **Compartir:** abrir el HTML sin conexión o exportar el diagrama completo a SVG / PNG.
-
-El [corpus de Jeepay](../../examples/jeepay), basado en código fuente real, contiene las once vistas utilizadas por CI y la demostración online.
-
-## Primeros pasos
-
-Tras la instalación, abre tu proyecto de negocio en el cliente y selecciona la habilidad `q-flow`. Los ejemplos usan `/q-flow` de Claude Code; en Codex, usa la entrada `$q-flow` o `$qgraphflow:q-flow` que ofrezca tu cliente. ¿Todavía no lo has instalado? Consulta primero la [guía de instalación](#guía-de-instalación).
-
-### 1. Entrada vacía: No sabes por dónde empezar
-
-Invoca la habilidad sin añadir una petición:
-
-```text
-/q-flow
-```
-
-La habilidad te guía para elegir la parte que analizar y la pregunta que debe responder el diagrama. Empieza a dibujar cuando la información necesaria está clara.
-
-### 2. Preguntar por las capacidades: Saber qué puede dibujar
-
-```text
-/q-flow ¿Qué tipos de diagramas puedes dibujar? ¿Qué preguntas responde cada tipo? Acabo de hacerme cargo de un proyecto; presenta tus capacidades y sugiere un punto de partida.
-```
-
-Conoce primero los usos de los once tipos de diagramas y decide después si quieres ver la estructura del proyecto, el orden de llamadas, las relaciones de datos u otro contenido.
-
-### 3. Entrada vaga: Solo tienes un objetivo general
-
-```text
-/q-flow Ayúdame a dibujar este proyecto. Quiero entenderlo lo antes posible.
-```
-
-No necesitas indicar primero el tipo de diagrama. La habilidad determina una vista adecuada según el proyecto y tu objetivo, y pregunta cuando falta información necesaria.
-
-### 4. Entrada precisa: Definir el alcance y pedir detalles del dibujo
-
-Sustituye los nombres de negocio y los pasos siguientes por procesos que existan realmente en tu proyecto:
-
-```text
-/q-flow Analiza el proceso de creación de pedidos del proyecto actual y genera un diagrama de secuencia en chino.
-Incluye la entrada de solicitudes, el cálculo de precios, la reserva de inventario, la autorización de pago y la persistencia del pedido.
-Conserva las llamadas síncronas, mensajes asíncronos, retornos emparejados, barras de activación, ramas condicionales, reintentos y compensaciones de fallos que existan realmente en el código. No omitas detalles por brevedad.
-Indica los archivos y números de línea del código de los componentes y llamadas, y guarda el resultado en docs/qgraphflow/order-sequence/.
-```
-
-Define claramente el objeto, la pregunta, el nivel de detalle y la ubicación de salida para empezar directamente. El diagrama conserva solo hechos respaldados por evidencia.
-
-### 5. Seguir refinando: Ampliar una parte del diagrama anterior
-
-Una vez generado el resultado, continúa en la misma conversación:
-
-```text
-/q-flow Amplía el paso de reserva de inventario del diagrama de secuencia anterior en un diagrama de flujo independiente en chino.
-Muestra todas las ramas de validación de inventario, reserva exitosa, fallos reintentables, límite de reintentos y liberación de inventario. Sigue el código fuente y no añadas pasos que no existan en él.
-```
-
-Mira primero el conjunto y profundiza después en un paso. También puedes pedir más detalles de un diagrama existente o verificar sus relaciones.
-
-## Guía de instalación
-
-Se necesitan Node.js 22 o posterior y un cliente compatible con complementos que tenga configurado el acceso al modelo.
-
-### Instalación rápida
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Probado con `skills` 1.7.0 en Claude Code, Codex, Cursor y Qoder. El comando pregunta en qué clientes instalar; `-a claude-code` indica uno directamente y `-g` instala para el usuario en lugar del proyecto actual. La habilidad queda instalada como `q-flow`, sin el prefijo `qgraphflow:` de las instalaciones como complemento de más abajo.
-
-Para instalarla como complemento, seguir los pasos siguientes. En [Qoder Desktop](#qoder-desktop), puedes instalar desde el Marketplace y omitir el paso 1.
-
-### 1. Descargar el complemento
-
-Obtener el complemento desde npmjs.com, sin cuenta, inicio de sesión ni token. Crear un directorio independiente fuera del proyecto de la aplicación:
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-Ahora se está en la raíz del complemento. **La descarga mediante npm no instala automáticamente el complemento en el cliente**; continuar con el paso 2. El paquete también ofrece el comando `qgraphflow`, que se usa en [Mantener los diagramas sincronizados con el código](#mantener-los-diagramas-sincronizados-con-el-código).
-
-Ejecutar los comandos siguientes desde **la raíz del complemento, que contiene `skills/`**.
-
-### 2. Instalar en el cliente
-
-#### Codex App / CLI
-
-Codex CLI debe estar instalado y disponible en la terminal:
-
-```bash
-codex plugin marketplace add .
-codex plugin add qgraphflow@supermax92
-```
-
-Iniciar una sesión nueva, escribir `$` y seleccionar `qgraphflow:q-flow`.
-
-#### Claude Code
-
-```bash
-claude plugin marketplace add ./
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Iniciar una sesión nueva y escribir `/q-flow` (o el nombre completo `/qgraphflow:q-flow`).
-
-#### Qoder CLI
-
-```bash
-qodercli plugins install .
-```
-
-Iniciar una sesión nueva y seleccionar `q-flow`.
-
-#### Qoder Desktop
-
-**Recomendado:** Abre **Settings → Plugins → Marketplace**, busca **QGraphFlow** o **代码图谱可视化** e instala el complemento. Inicia una sesión nueva y selecciona `q-flow`.
-
-Para una instalación local, completa primero el paso 1. Después abre **Settings → Plugins → Custom → Import** e importa el directorio raíz completo del complemento. Inicia una sesión nueva y selecciona `q-flow`.
-
-#### Cursor
-
-Copiar todo el contenido de la raíz del complemento, incluidos los archivos ocultos, a:
-
-```text
-~/.cursor/plugins/local/qgraphflow/
-```
-
-Comprobar que allí existe `.cursor-plugin/plugin.json`, recargar la ventana y buscar `q-flow` en **Customize**. Si hay una versión anterior, hacer una copia de seguridad antes; no mezclar archivos antiguos y nuevos.
-
-### 3. Empezar a usarlo
-
-Abre tu proyecto de negocio en el cliente, inicia una sesión nueva y selecciona la habilidad. Describe tu petición siguiendo los ejemplos de [Primeros pasos](#primeros-pasos). Abre el HTML generado en el navegador.
-
-¿Prefieres compilarlo? Consulta las [instrucciones de compilación desde el código fuente](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
-
-## Uso rápido
-
-Estos ejemplos usan `$qgraphflow:q-flow` en Codex. Si el cliente muestra `$q-flow`, seleccionar esa entrada. En los demás clientes, usar la forma de invocación indicada arriba.
-
-**¿No sabes por dónde empezar?** Invocar la habilidad y elegir el tema y la pregunta cuando lo solicite.
-
-```text
-$qgraphflow:q-flow
-```
-
-**¿Ya tienes un objetivo?** Indicar qué parte quieres dibujar y qué quieres entender. No hace falta elegir antes el tipo de diagrama.
-
-### Ejemplo 1: Entender la arquitectura
-
-```text
-$qgraphflow:q-flow Analiza este proyecto y crea un diagrama de arquitectura en chino que muestre responsabilidades de los módulos, dependencias y límites del sistema.
-```
-
-Útil para conocer la estructura general al llegar a un proyecto.
-
-### Ejemplo 2: Seguir un flujo de negocio
-
-```text
-$qgraphflow:q-flow Analiza la creación de pedidos y genera un diagrama de secuencia en chino con cálculo de precios, reserva de inventario, pago y persistencia del pedido, incluidas las ramas de fallo.
-```
-
-Sustituir la creación de pedidos y sus pasos por el flujo real del proyecto. Continuar en la misma conversación:
-
-```text
-$qgraphflow:q-flow Amplía la reserva de inventario del diagrama anterior en un diagrama de flujo independiente en chino, con el tratamiento de éxitos y fallos.
-```
-
-Los resultados se guardan bajo `docs/qgraphflow/` de forma predeterminada. Abrir `index.html` para explorar, editar y exportar; `graph.json` conserva los datos. Cada vista también se escribe como SVG (`diagram.svg`, o `diagram--.svg` cuando hay varias), que puede incrustarse como imagen en un README, una pull request o una wiki.
-
-Después de editar en la página, **Más → Guardar cambios** en Chrome o Edge reescribe en su sitio la página, `graph.json` y los SVG, tras elegir una vez la carpeta del diagrama. Otros navegadores solo guardan `graph.json`: colocarlo en la carpeta y volver a generar la página y los SVG con `npx -y qgraphflow generate docs/qgraphflow//graph.json docs/qgraphflow/ --layout preserve --force`.
-
-
-Ejecutar el ejemplo de Jeepay con once vistas basado en código fuente
-
-Selecciona tu copia local del código fuente de Jeepay para verificar la evidencia:
-
-```bash
-export JEEPAY_REPO_ROOT=""
-node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.json --input-only --repo-root "$JEEPAY_REPO_ROOT"
-node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"
-```
-
-Abre `output/jeepay/index.html`; sus once SVG están en el mismo directorio. Consulta el [README del corpus](../../examples/jeepay) para conocer la revisión del código fuente y el procedimiento de actualización.
-
-
-
-## Mantener los diagramas sincronizados con el código
-
-Un diagrama generado con la raíz del repositorio registra dónde se define cada componente y la línea detrás de cada relación respaldada por código (una llamada, una clave foránea). La validación con `--repo-root` falla cuando falta un archivo registrado, un rango de líneas ya no cabe en el archivo o un símbolo registrado salió de sus líneas, y el error indica en qué líneas está ahora el símbolo. Añadir este trabajo a la CI; no necesita compilación, inicio de sesión ni token:
-
-```yaml
-name: Diagrams
-on: [push, pull_request]
-jobs:
- diagrams:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v7
- - uses: actions/setup-node@v7
- with:
- node-version: '22'
- - run: |
- for graph in docs/qgraphflow/*/graph.json; do
- npx -y qgraphflow validate "$graph" --input-only --repo-root . || { echo "::error file=$graph::$graph failed validation"; failed=1; }
- done
- exit ${failed:-0}
-```
-
-Si falla, pedir a la habilidad que actualice ese diagrama:
-
-```text
-$qgraphflow:q-flow La CI dice que docs/qgraphflow/order-sequence está desactualizado. Actualízalo.
-```
-
-La habilidad mueve los anclajes cuyo símbolo encuentra una sola vez en el archivo, corrige solo los que siguen fallando y vuelve a generar la página y los SVG conservando las posiciones y los textos editados. No redibuja el diagrama.
-
-## Qué responde cada uno de los once tipos de diagramas
-
-| Vista · PNG | Pregunta principal | Alcance del ejemplo |
-| --- | --- | --- |
-| Arquitectura de capacidades de la plataforma | ¿Qué capacidades ofrece la plataforma? | Zonas de capacidades y matrices |
-| Arquitectura por capas de ingeniería | ¿Cómo se organiza el código del proyecto? | Capas de ingeniería y soporte compartido |
-| Arquitectura de relaciones entre componentes | ¿Qué límites de responsabilidad colaboran en el sistema? | Canales, orquestación de transacciones, precios, riesgo, inventario, pago, pedidos, eventos y ejecución de pedidos |
-| Diagrama de flujo | ¿Cómo se bifurca y converge cada decisión? | Falta de inventario, rechazo de riesgo, compensación de fallos de pago y confirmación exitosa |
-| Secuencia | ¿En qué orden hace llamadas y recibe retornos una solicitud? | Flujo principal de compra exitosa y OrderPaid asíncrono |
-| ER | ¿Cómo se relacionan los datos principales? | Carrito, pedidos, líneas, pagos, reservas de inventario y paquetes |
-| Despliegue | ¿Dónde se ubican las unidades de ejecución y cómo se conectan? | Borde, Kubernetes, servicios de datos, pago y redes de almacén y logística |
-| Clases | ¿Cómo dependen los objetos de dominio y los contratos del código? | Servicio de aplicación Checkout, Order y cuatro puertos |
-| Estados | ¿Qué eventos y condiciones de guarda hacen avanzar un pedido? | Pago, ejecución del pedido, cancelación, reembolso y cierre |
-| Casos de uso | ¿Qué capacidades tiene cada actor? | Comprador, comercio, almacén y atención al cliente |
-| Flujo de datos | ¿Por qué transformaciones y almacenes pasan los activos de datos? | Carrito, decisiones de transacción, eventos de pedidos, almacén y logística y comprobantes de entrega |
-
-Este modelo conceptual demuestra QGraphFlow y no corresponde a un repositorio de comercio concreto. El ejemplo `graph.json` no inventa rutas de código y marca las evidencias de las relaciones como `inference`. Los diagramas reales necesitan código, DDL, configuración, pruebas y requisitos aceptados que se puedan rastrear.
-
-## Desarrollo y contribuciones
-
-```bash
-npm ci --prefix skills/q-flow/assets/viewer
-npm run build --prefix skills/q-flow/assets/viewer
-node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs
-```
-
-Se necesitan Node.js 22 o posterior, npm, tar, zip y unzip. Al informar de un problema, incluir un gráfico mínimo sin datos sensibles, versiones del cliente y navegador y pasos de reproducción.
-
-Documentación de referencia (en inglés): [Fuentes de evidencia](../../skills/q-flow/references/evidence-sources.md) · [Formato de gráficos](../../skills/q-flow/references/graph-schema.md) · [Consulta guiada](../../skills/q-flow/references/guided-intake.md) · [Desarrollo y aceptación del Viewer](../../skills/q-flow/references/viewer-development.md) · [Composición de diagramas](../../skills/q-flow/references/visual-contract.md)
-
-## Licencia y atribución
-
-[MIT](../../LICENSE) · [Avisos de terceros](../../THIRD_PARTY_NOTICES.md)
-
-QGraphFlow es un proyecto independiente con licencia MIT. Los escenarios de este documento son ejemplos conceptuales y no representan la arquitectura de producción de ninguna empresa real.
-
-## Vistas generales de arquitectura
-
-La arquitectura incluye ahora relaciones entre componentes, capacidades de la plataforma y capas de ingeniería. Describe el objeto y la pregunta; la habilidad elige la plantilla. Las colecciones solicitadas pueden contener varias vistas de arquitectura con ediciones independientes.
-
-```text
-$qgraphflow:q-flow Analiza las capacidades de la plataforma y las formas de integración de negocio del proyecto actual, y genera una vista general de capacidades de la plataforma en chino.
-$qgraphflow:q-flow Analiza la organización del proyecto actual y sus capas de componentes, y genera vistas generales en chino del proyecto completo y de una sección de un componente.
-$qgraphflow:q-flow Genera una vista general en inglés de las capacidades de la plataforma de este proyecto y muestra cómo se integran los módulos de aplicación.
-```
-
-Consulta [examples/jeepay](../../examples/jeepay) para ver las vistas de arquitectura de plataforma, ingeniería y relaciones entre componentes basadas en código fuente real. Desbloquea una vista general para reordenar tarjetas dentro de una capa o editar texto. Guardar conserva todas las vistas; restablecer restaura solo la actual.
diff --git a/docs/readme/README.ja.md b/docs/readme/README.ja.md
deleted file mode 100644
index b122259..0000000
--- a/docs/readme/README.ja.md
+++ /dev/null
@@ -1,311 +0,0 @@
-
-
-### Transforme código complexo em diagramas que você pode explorar.
-
-Siga o caminho. Confira as evidências. Compartilhe um arquivo offline.
-
-💡 Inspirado em Cocoon-AI/architecture-diagram-generator — agradecemos pela ideia.
-
-[English](../../README.md) · [中文](../../docs/readme/README.zh-CN.md) · [Русский](../../docs/readme/README.ru.md) · [Português](../../docs/readme/README.pt.md) · [日本語](../../docs/readme/README.ja.md) · [Deutsch](../../docs/readme/README.de.md) · [Español](../../docs/readme/README.es.md)
-
-[Demonstração online](https://supermax92.github.io/qgraphflow/) · [Primeiros passos](#primeiros-passos) · [Instalação por cliente](#guia-de-instalação) · [Relatar problema](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
-
-
-
-*Onze tipos de diagrama: arquitetura de capacidades da plataforma, arquitetura em camadas de engenharia, arquitetura de relações entre componentes, fluxograma, sequência, ER, implantação, classes, estados, casos de uso e fluxo de dados.*
-
-QGraphFlow gera diagramas de software interativos a partir de código, esquemas, configuração e requisitos. As relações podem ser verificadas e o resultado é um HTML offline compartilhável.
-
-**O que o diferencia:** onze tipos de diagrama em uma só habilidade, o tipo de evidência de cada relação e a linha de código por trás de cada uma que o código sustenta, layout automático, edição na própria página e nenhuma requisição de rede dos scripts do plugin nem do próprio Viewer.
-
-
-
-Com o código-fonte real do Jeepay, alterne entre diagramas de arquitetura de relações entre componentes, sequência e ER para explorar componentes e relações de chamadas. [Ver GIF no tamanho original](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.en.hero.gif)
-
-**Apresentação de um diagrama de sequência complexo**
-
-
-
-Um cenário fictício de comércio eletrônico contém 9 participantes, 29 mensagens e 6 fragmentos combinados, com novas tentativas de estoque, ramos aninhados, processamento paralelo, compensação de falhas e callbacks assíncronos. A animação revela gradualmente o diagrama gerado para mostrar sua estrutura e seus detalhes. [Ver GIF no tamanho original](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.en.sequence-drawing.gif)
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Um só comando instala a habilidade para Claude Code, Codex, Cursor e Qoder; a instalação como plugin e os demais clientes estão no [guia de instalação](#guia-de-instalação).
-
-- **Explorar:** pesquisar, ampliar e deslocar a tela; entender responsabilidades e relações de entrada e saída.
-
-- **Verificar:** inspecionar nós e conexões para conferir arquivos, linhas, símbolos e incertezas explícitas.
-
-- **Editar:** desbloquear o layout, alterar textos e mover elementos; redefinir quando necessário.
-
-- **Compartilhar:** abrir o HTML offline ou exportar o diagrama completo em SVG / PNG.
-
-O [corpus do Jeepay](../../examples/jeepay), baseado em código-fonte real, contém as onze vistas usadas pelo CI e pela demonstração online.
-
-## Primeiros passos
-
-Após a instalação, abra seu projeto de negócio no cliente e selecione a habilidade `q-flow`. Os exemplos usam `/q-flow` do Claude Code; no Codex, use a entrada `$q-flow` ou `$qgraphflow:q-flow` que seu cliente realmente oferece. Ainda não instalou? Consulte primeiro o [guia de instalação](#guia-de-instalação).
-
-### 1. Entrada vazia: Não sabe por onde começar
-
-Invoque a habilidade sem acrescentar uma solicitação:
-
-```text
-/q-flow
-```
-
-A habilidade orienta você a escolher a parte a analisar e a pergunta que o diagrama deve responder. O desenho começa quando as informações necessárias estão claras.
-
-### 2. Perguntar sobre capacidades: Saber o que pode desenhar
-
-```text
-/q-flow Quais tipos de diagrama você pode desenhar? Que perguntas cada tipo responde? Acabei de assumir um projeto; apresente suas capacidades e sugira um ponto de partida.
-```
-
-Conheça primeiro os usos dos onze tipos de diagrama e depois decida se quer explorar a estrutura do projeto, a ordem das chamadas, as relações de dados ou outro conteúdo.
-
-### 3. Entrada vaga: Apenas um objetivo geral
-
-```text
-/q-flow Ajude-me a desenhar este projeto. Quero entendê-lo o mais rápido possível.
-```
-
-Não é necessário indicar primeiro o tipo de diagrama. A habilidade determina uma vista adequada com base no projeto e no seu objetivo, e pergunta quando faltam informações necessárias.
-
-### 4. Entrada precisa: Definir o escopo e pedir detalhes do desenho
-
-Substitua os nomes de negócio e os passos abaixo por fluxos que realmente existam no seu projeto:
-
-```text
-/q-flow Analise o fluxo de criação de pedidos do projeto atual e gere um diagrama de sequência em chinês.
-Inclua a entrada da solicitação, o cálculo de preços, a reserva de estoque, a autorização de pagamento e a persistência do pedido.
-Mantenha as chamadas síncronas, mensagens assíncronas, retornos emparelhados, barras de ativação, ramificações condicionais, tentativas e compensações de falha que realmente existam no código. Não omita detalhes por brevidade.
-Indique os arquivos e números de linha do código dos componentes e chamadas, e salve o resultado em docs/qgraphflow/order-sequence/.
-```
-
-Defina claramente o objeto, a pergunta, o nível de detalhe e o local de saída para começar diretamente. O diagrama mantém apenas fatos sustentados por evidências.
-
-### 5. Refinar mais: Expandir parte do diagrama anterior
-
-Após a geração do resultado, continue na mesma conversa:
-
-```text
-/q-flow Expanda a etapa de reserva de estoque do diagrama de sequência anterior em um fluxograma separado em chinês.
-Mostre todos os ramos de validação do estoque, reserva bem-sucedida, falhas que permitem nova tentativa, limite de tentativas e liberação de estoque. Siga o código-fonte e não adicione etapas ausentes dele.
-```
-
-Veja primeiro o todo e depois aprofunde uma etapa. Você também pode pedir mais detalhes de um diagrama existente ou verificar suas relações.
-
-## Guia de instalação
-
-Você precisa do Node.js 22 ou posterior e de um cliente com suporte a plugins e acesso ao modelo configurado.
-
-### Instalação rápida
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Testado com `skills` 1.7.0 no Claude Code, Codex, Cursor e Qoder. O comando pergunta em quais clientes instalar; `-a claude-code` indica um diretamente e `-g` instala para o seu usuário em vez do projeto atual. A habilidade é instalada como `q-flow`, sem o prefixo `qgraphflow:` das instalações como plugin abaixo.
-
-Para instalar como plugin, siga as etapas abaixo. No [Qoder Desktop](#qoder-desktop), você pode instalar pelo Marketplace e pular a etapa 1.
-
-### 1. Baixe o plugin
-
-Obtenha o plugin no npmjs.com, sem conta, login nem token. Crie um diretório separado, fora do projeto da sua aplicação:
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-Agora você está na raiz do plugin. **Baixar pelo npm não instala automaticamente o plugin no cliente**; continue na etapa 2. O pacote também oferece o comando `qgraphflow`, usado em [Mantenha os diagramas em sincronia com o código](#mantenha-os-diagramas-em-sincronia-com-o-código).
-
-Execute os comandos abaixo na **raiz do plugin, que contém `skills/`**.
-
-### 2. Instale no seu cliente
-
-#### Codex App / CLI
-
-O Codex CLI precisa estar instalado e disponível no terminal:
-
-```bash
-codex plugin marketplace add .
-codex plugin add qgraphflow@supermax92
-```
-
-Inicie uma nova sessão, digite `$` e selecione `qgraphflow:q-flow`.
-
-#### Claude Code
-
-```bash
-claude plugin marketplace add ./
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Inicie uma nova sessão e digite `/q-flow` (ou o nome completo `/qgraphflow:q-flow`).
-
-#### Qoder CLI
-
-```bash
-qodercli plugins install .
-```
-
-Inicie uma nova sessão e selecione `q-flow`.
-
-#### Qoder Desktop
-
-**Recomendado:** Abra **Settings → Plugins → Marketplace**, pesquise **QGraphFlow** ou **代码图谱可视化** e instale o plugin. Inicie uma nova sessão e selecione `q-flow`.
-
-Para uma instalação local, conclua primeiro a etapa 1. Depois, abra **Settings → Plugins → Custom → Import** e importe o diretório raiz completo do plugin. Inicie uma nova sessão e selecione `q-flow`.
-
-#### Cursor
-
-Copie todo o conteúdo da raiz do plugin, incluindo os arquivos ocultos, para:
-
-```text
-~/.cursor/plugins/local/qgraphflow/
-```
-
-Confirme que `.cursor-plugin/plugin.json` existe nesse local, recarregue a janela e encontre `q-flow` em **Customize**. Se houver uma versão anterior, faça backup primeiro; não misture arquivos antigos e novos.
-
-### 3. Comece a usar
-
-Abra seu projeto de negócio no cliente, inicie uma nova sessão e selecione a habilidade. Descreva sua solicitação seguindo os exemplos de [Primeiros passos](#primeiros-passos). Abra o HTML gerado no navegador.
-
-Quer compilar por conta própria? Consulte as [instruções de compilação do código-fonte](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
-
-## Uso rápido
-
-Os exemplos usam `$qgraphflow:q-flow` no Codex. Se o cliente mostrar `$q-flow`, selecione essa entrada. Nos demais clientes, use a forma de chamada da habilidade indicada acima.
-
-**Sem saber por onde começar?** Chame a habilidade e escolha o assunto e a pergunta quando solicitado.
-
-```text
-$qgraphflow:q-flow
-```
-
-**Já tem um objetivo?** Diga qual parte deseja desenhar e o que quer entender. Não é preciso escolher o tipo de diagrama antes.
-
-### Exemplo 1: Entender a arquitetura
-
-```text
-$qgraphflow:q-flow Analise este projeto e crie um diagrama de arquitetura em chinês com responsabilidades dos módulos, dependências e limites do sistema.
-```
-
-Útil para conhecer a estrutura geral ao entrar em um projeto.
-
-### Exemplo 2: Acompanhar um fluxo de negócio
-
-```text
-$qgraphflow:q-flow Analise a criação de pedidos e gere um diagrama de sequência em chinês com cálculo de preços, reserva de estoque, pagamento e persistência do pedido, incluindo os ramos de falha.
-```
-
-Substitua a criação de pedidos e suas etapas pelo fluxo real do projeto. Continue na mesma conversa:
-
-```text
-$qgraphflow:q-flow Expanda a reserva de estoque do diagrama anterior em um fluxograma separado em chinês, mostrando o tratamento de sucesso e falha.
-```
-
-Os resultados ficam em `docs/qgraphflow/` por padrão. Abra `index.html` para explorar, editar e exportar; `graph.json` mantém os dados do grafo. Cada vista também é gravada como SVG (`diagram.svg`, ou `diagram--.svg` quando há várias vistas), que pode ser incorporado como imagem em um README, pull request ou wiki.
-
-Depois de editar na página, **Mais → Salvar alterações** no Chrome ou no Edge regrava a página, o `graph.json` e os SVG no lugar, depois que você escolhe a pasta do diagrama uma vez. Outros navegadores salvam só o `graph.json`: coloque-o na pasta e gere de novo a página e os SVG com `npx -y qgraphflow generate docs/qgraphflow//graph.json docs/qgraphflow/ --layout preserve --force`.
-
-
-Executar o exemplo do Jeepay com onze vistas baseado em código-fonte
-
-Selecione sua cópia local do código-fonte do Jeepay para verificar as evidências:
-
-```bash
-export JEEPAY_REPO_ROOT=""
-node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.json --input-only --repo-root "$JEEPAY_REPO_ROOT"
-node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"
-```
-
-Abra `output/jeepay/index.html`; os onze SVG estão no mesmo diretório. Consulte o [README do corpus](../../examples/jeepay) para conhecer a revisão do código-fonte e o procedimento de atualização.
-
-
-
-## Mantenha os diagramas em sincronia com o código
-
-Um diagrama gerado com a raiz do repositório registra onde cada componente é definido e a linha por trás de cada relação sustentada pelo código (uma chamada, uma chave estrangeira). A validação com `--repo-root` falha quando um arquivo registrado sumiu, um intervalo de linhas não cabe mais no arquivo ou um símbolo registrado saiu das suas linhas, e o erro indica as linhas em que o símbolo está agora. Adicione este job ao seu CI; ele não precisa de build, login nem token:
-
-```yaml
-name: Diagrams
-on: [push, pull_request]
-jobs:
- diagrams:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v7
- - uses: actions/setup-node@v7
- with:
- node-version: '22'
- - run: |
- for graph in docs/qgraphflow/*/graph.json; do
- npx -y qgraphflow validate "$graph" --input-only --repo-root . || { echo "::error file=$graph::$graph failed validation"; failed=1; }
- done
- exit ${failed:-0}
-```
-
-Quando falhar, peça à habilidade para atualizar o diagrama:
-
-```text
-$qgraphflow:q-flow O CI diz que docs/qgraphflow/order-sequence está desatualizado. Atualize-o.
-```
-
-A habilidade move as âncoras cujo símbolo aparece uma única vez no arquivo, corrige apenas as âncoras que ainda falham e gera de novo a página e os SVG, mantendo as posições e os textos que você editou. Ela não redesenha o diagrama.
-
-## O que cada um dos onze tipos de diagrama responde
-
-| Vista · PNG | Pergunta principal | Escopo do exemplo |
-| --- | --- | --- |
-| Arquitetura de capacidades da plataforma | Quais capacidades a plataforma oferece? | Zonas de capacidades e matrizes |
-| Arquitetura em camadas de engenharia | Como o código do projeto é organizado? | Camadas de engenharia e suporte compartilhado |
-| Arquitetura de relações entre componentes | Quais limites de responsabilidade colaboram no sistema? | Canais, orquestração de transações, preços, risco, estoque, pagamento, pedidos, eventos e execução de pedidos |
-| Fluxograma | Como cada decisão se ramifica e converge? | Falta de estoque, recusa de risco, compensação de falha de pagamento e confirmação bem-sucedida |
-| Sequência | Em que ordem uma solicitação faz chamadas e recebe retornos? | Fluxo principal de compra bem-sucedida e OrderPaid assíncrono |
-| ER | Como os dados centrais se relacionam? | Carrinho, pedidos, itens, pagamentos, reservas de estoque e pacotes |
-| Implantação | Onde ficam as unidades de execução e como se conectam? | Borda, Kubernetes, serviços de dados, pagamento e redes de armazém e logística |
-| Classes | Como objetos de domínio e contratos do código dependem entre si? | Serviço de aplicação Checkout, Order e quatro portas |
-| Estados | Quais eventos e condições de guarda fazem um pedido avançar? | Pagamento, execução do pedido, cancelamento, reembolso e encerramento |
-| Casos de uso | Quais capacidades cada ator possui? | Comprador, lojista, depósito e atendimento |
-| Fluxo de dados | Por quais transformações e armazenamentos os ativos de dados passam? | Carrinho, decisões de transação, eventos de pedidos, armazém e logística e comprovantes de entrega |
-
-Este modelo conceitual demonstra o QGraphFlow e não corresponde a um repositório de comércio específico. O exemplo `graph.json` não inventa caminhos de código e marca as evidências das relações como `inference`. Diagramas reais precisam de código, DDL, configuração, testes e requisitos aceitos rastreáveis.
-
-## Desenvolvimento e contribuição
-
-```bash
-npm ci --prefix skills/q-flow/assets/viewer
-npm run build --prefix skills/q-flow/assets/viewer
-node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs
-```
-
-São necessários Node.js 22 ou posterior, npm, tar, zip e unzip. Ao relatar problemas, inclua um grafo mínimo sem informações sensíveis, versões do cliente e navegador e passos de reprodução.
-
-Documentação de referência (em inglês): [Fontes de evidência](../../skills/q-flow/references/evidence-sources.md) · [Formato dos grafos](../../skills/q-flow/references/graph-schema.md) · [Consulta guiada](../../skills/q-flow/references/guided-intake.md) · [Desenvolvimento e aceitação do Viewer](../../skills/q-flow/references/viewer-development.md) · [Composição de diagramas](../../skills/q-flow/references/visual-contract.md)
-
-## Licença e atribuição
-
-[MIT](../../LICENSE) · [Avisos de terceiros](../../THIRD_PARTY_NOTICES.md)
-
-QGraphFlow é um projeto independente sob a licença MIT. Os cenários deste documento são exemplos conceituais e não representam a arquitetura de produção de nenhuma empresa real.
-
-## Visões gerais de arquitetura
-
-A arquitetura agora inclui relações entre componentes, capacidades da plataforma e camadas de engenharia. Descreva o objeto e a pergunta; a habilidade escolhe o modelo. As coleções solicitadas podem conter várias vistas de arquitetura com edições independentes.
-
-```text
-$qgraphflow:q-flow Analise as capacidades da plataforma e as formas de integração de negócio do projeto atual e gere uma visão geral de capacidades da plataforma em chinês.
-$qgraphflow:q-flow Analise a organização do projeto atual e suas camadas de componentes e gere visões gerais em chinês do projeto inteiro e de uma seção de um componente.
-$qgraphflow:q-flow Gere uma visão geral em inglês das capacidades da plataforma deste projeto e mostre como os módulos de aplicação se integram.
-```
-
-Consulte [examples/jeepay](../../examples/jeepay) para ver as vistas de arquitetura de plataforma, engenharia e relações entre componentes baseadas em código-fonte real. Desbloqueie uma visão geral para reordenar cartões dentro de uma camada ou editar textos. Salvar mantém todas as vistas; redefinir restaura apenas a atual.
diff --git a/docs/readme/README.ru.md b/docs/readme/README.ru.md
deleted file mode 100644
index 39c7a23..0000000
--- a/docs/readme/README.ru.md
+++ /dev/null
@@ -1,311 +0,0 @@
-
-
-
-
-### Превратите сложный код в диаграммы для исследования.
-
-Проследите путь. Проверьте основания. Поделитесь одним автономным файлом.
-
-💡 Вдохновлено проектом Cocoon-AI/architecture-diagram-generator — спасибо за идею.
-
-[English](../../README.md) · [中文](../../docs/readme/README.zh-CN.md) · [Русский](../../docs/readme/README.ru.md) · [Português](../../docs/readme/README.pt.md) · [日本語](../../docs/readme/README.ja.md) · [Deutsch](../../docs/readme/README.de.md) · [Español](../../docs/readme/README.es.md)
-
-[Онлайн-демо](https://supermax92.github.io/qgraphflow/) · [Первые шаги](#первые-шаги) · [Установка для клиентов](#установка) · [Сообщить о проблеме](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
-
-
-
-*Поддерживаются одиннадцать типов диаграмм: архитектура возможностей платформы, архитектура инженерных слоёв, архитектура связей компонентов, блок-схема, последовательность, ER, развёртывание, классы, состояния, варианты использования и поток данных.*
-
-QGraphFlow создаёт интерактивные диаграммы программных систем из кода, схем данных, конфигурации и требований. Основания связей можно проверить, а результат — передать как автономный HTML.
-
-**Чем отличается:** одиннадцать типов диаграмм в одном навыке, тип доказательства для каждой связи и строка кода за каждой связью, подтверждённой кодом, автоматическая раскладка, редактирование прямо на странице и никаких сетевых запросов ни от скриптов плагина, ни от самого Viewer.
-
-
-
-На примере реального исходного кода Jeepay переключайтесь между архитектурой связей компонентов, диаграммой последовательности и ER, изучая компоненты и связи вызовов. [Посмотреть GIF в исходном размере](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.en.hero.gif)
-
-**Демонстрация сложной диаграммы последовательности**
-
-
-
-Вымышленный сценарий электронной торговли содержит 9 участников, 29 сообщений и 6 комбинированных фрагментов: повторные попытки резервирования, вложенные ветви, параллельную обработку, компенсацию сбоев и асинхронные обратные вызовы. Анимация постепенно показывает готовую диаграмму, раскрывая её структуру и детали. [Посмотреть GIF в исходном размере](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.en.sequence-drawing.gif)
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Одна команда устанавливает навык для Claude Code, Codex, Cursor и Qoder; установка в виде плагина и другие клиенты описаны в разделе [Установка](#установка).
-
-- **Исследование:** поиск, масштабирование и перемещение холста; назначение компонентов, входящие и исходящие связи.
-
-- **Проверка:** файлы, строки, символы и явно обозначенная неопределённость в узлах и связях.
-
-- **Редактирование:** разблокировка расположения, изменение текста и перемещение элементов; сброс при необходимости.
-
-- **Обмен:** автономный HTML или экспорт всей диаграммы в SVG / PNG.
-
-Основанный на реальном коде [корпус Jeepay](../../examples/jeepay) содержит все одиннадцать видов, используемых CI и онлайн-демонстрацией.
-
-## Первые шаги
-
-После установки откройте свой рабочий проект в клиенте и выберите навык `q-flow`. Примеры используют `/q-flow` в Claude Code; в Codex используйте пункт `$q-flow` или `$qgraphflow:q-flow`, который действительно предлагает ваш клиент. Ещё не установили? Сначала прочитайте раздел [Установка](#установка).
-
-### 1. Пустой ввод: Не знаете, с чего начать
-
-Вызовите навык без дополнительных требований:
-
-```text
-/q-flow
-```
-
-Навык поможет выбрать часть для анализа и вопрос, на который должна ответить диаграмма. Рисование начнётся, когда необходимая информация будет ясна.
-
-### 2. Вопрос о возможностях: Узнать, что можно нарисовать
-
-```text
-/q-flow Какие типы диаграмм ты можешь рисовать? На какие вопросы отвечает каждый тип? Я только что принял проект; сначала расскажи о своих возможностях и предложи, с чего начать.
-```
-
-Сначала узнайте назначение одиннадцати типов диаграмм, затем решите, что изучать: структуру проекта, порядок вызовов, связи данных или что-то другое.
-
-### 3. Неопределённый ввод: Есть только общая цель
-
-```text
-/q-flow Помоги нарисовать этот проект. Я хочу как можно быстрее его понять.
-```
-
-Не нужно заранее указывать тип диаграммы. Навык определит подходящий вид по проекту и вашей цели и задаст вопросы, если необходимой информации не хватает.
-
-### 4. Точный ввод: Задать границы и запросить детали рисунка
-
-Замените названия и шаги ниже процессами, которые действительно есть в вашем проекте:
-
-```text
-/q-flow Проанализируй создание заказа в текущем проекте и создай диаграмму последовательности на китайском языке.
-Включи точку входа запроса, расчёт цены, резервирование запасов, авторизацию платежа и сохранение заказа.
-Сохрани синхронные вызовы, асинхронные сообщения, парные возвраты, полосы активации, условные ветви, повторные попытки и компенсацию сбоев, которые действительно есть в исходниках. Не опускай детали ради краткости.
-Укажи исходные файлы и номера строк компонентов и вызовов и сохрани результат в docs/qgraphflow/order-sequence/.
-```
-
-Чётко задайте предмет, вопрос, уровень детализации и место вывода, чтобы начать сразу. Диаграмма сохраняет только факты, подтверждённые доказательствами.
-
-### 5. Дальнейшее уточнение: Раскрыть часть предыдущей диаграммы
-
-После получения результата продолжите в том же разговоре:
-
-```text
-/q-flow Раскрой резервирование запасов из предыдущей диаграммы последовательности отдельной блок-схемой на китайском языке.
-Покажи все ветви проверки запасов, успешного резервирования, повторяемых сбоев, предела повторных попыток и освобождения запасов. Следуй исходному коду и не добавляй отсутствующих в нём шагов.
-```
-
-Сначала рассмотрите целое, затем углубитесь в один шаг. Можно также запросить дополнительные детали существующей диаграммы или проверить её связи.
-
-## Установка
-
-Нужны Node.js 22 или новее и клиент с поддержкой плагинов и настроенным доступом к модели.
-
-### Быстрая установка
-
-```bash
-npx skills add supermax92/qgraphflow
-```
-
-Проверено с `skills` 1.7.0 для Claude Code, Codex, Cursor и Qoder. Команда спросит, в какие клиенты устанавливать; `-a claude-code` задаёт клиент сразу, а `-g` устанавливает навык для пользователя, а не для текущего проекта. Навык устанавливается как `q-flow`, без префикса `qgraphflow:`, который дают способы установки плагина ниже.
-
-Чтобы установить его как плагин, выполните шаги ниже. В [Qoder Desktop](#qoder-desktop) можно установить плагин из Marketplace и пропустить шаг 1.
-
-### 1. Скачайте плагин
-
-Получите плагин с npmjs.com — без учётной записи, входа и токена. Создайте отдельный каталог вне своего рабочего проекта:
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-Теперь вы в корневом каталоге плагина. **Загрузка через npm не устанавливает плагин в клиент автоматически** — перейдите к шагу 2. Пакет также даёт команду `qgraphflow`, которая используется в разделе [Синхронизация диаграмм с кодом](#синхронизация-диаграмм-с-кодом).
-
-Все команды ниже выполняйте из **корневого каталога плагина, содержащего `skills/`**.
-
-### 2. Установите в свой клиент
-
-#### Codex App / CLI
-
-В терминале должен быть доступен установленный Codex CLI:
-
-```bash
-codex plugin marketplace add .
-codex plugin add qgraphflow@supermax92
-```
-
-Начните новую сессию, введите `$` и выберите `qgraphflow:q-flow`.
-
-#### Claude Code
-
-```bash
-claude plugin marketplace add ./
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Начните новую сессию и введите `/q-flow` (или полное имя `/qgraphflow:q-flow`).
-
-#### Qoder CLI
-
-```bash
-qodercli plugins install .
-```
-
-Начните новую сессию и выберите `q-flow`.
-
-#### Qoder Desktop
-
-**Рекомендуется:** Откройте **Settings → Plugins → Marketplace**, найдите **QGraphFlow** или **代码图谱可视化** и установите плагин. Начните новый сеанс и выберите `q-flow`.
-
-Для локальной установки выполните шаг 1, затем откройте **Settings → Plugins → Custom → Import** и импортируйте весь корневой каталог плагина. Начните новый сеанс и выберите `q-flow`.
-
-#### Cursor
-
-Скопируйте всё содержимое корневого каталога плагина, включая скрытые файлы, в:
-
-```text
-~/.cursor/plugins/local/qgraphflow/
-```
-
-Убедитесь, что там есть `.cursor-plugin/plugin.json`, перезагрузите окно и найдите `q-flow` в **Customize**. Если уже установлена старая версия, сначала сделайте резервную копию; не смешивайте старые и новые файлы.
-
-### 3. Начните работу
-
-Откройте свой рабочий проект в клиенте, начните новую сессию и выберите навык. Опишите требования по примерам в разделе [Первые шаги](#первые-шаги). После генерации откройте выходной HTML в браузере.
-
-Хотите собрать самостоятельно? См. [инструкции по сборке из исходников](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
-
-## Быстрое использование
-
-Примеры используют `$qgraphflow:q-flow` в Codex. Если клиент показывает `$q-flow`, выберите этот пункт. Для других клиентов используйте способ вызова навыка, указанный выше.
-
-**Не знаете, с чего начать?** Вызовите навык, затем выберите предмет и вопрос по подсказке.
-
-```text
-$qgraphflow:q-flow
-```
-
-**Цель уже ясна?** Укажите, какую часть нарисовать и что требуется понять. Тип диаграммы заранее выбирать не нужно.
-
-### Пример 1: Понять архитектуру проекта
-
-```text
-$qgraphflow:q-flow Проанализируй текущий проект и создай диаграмму архитектуры на китайском языке: обязанности модулей, зависимости и границы системы.
-```
-
-Подходит для первого знакомства с общей структурой проекта.
-
-### Пример 2: Проследить бизнес-процесс
-
-```text
-$qgraphflow:q-flow Проанализируй создание заказа и создай диаграмму последовательности на китайском языке: расчёт цены, резерв запасов, оплата и сохранение заказа, включая ветки сбоев.
-```
-
-Замените создание заказа и его шаги реальным процессом проекта. Продолжите в том же разговоре:
-
-```text
-$qgraphflow:q-flow Подробно раскрой резерв запасов из предыдущей диаграммы отдельной блок-схемой на китайском языке с обработкой успеха и сбоев.
-```
-
-По умолчанию результаты находятся в `docs/qgraphflow/`. Откройте `index.html` для исследования, редактирования и экспорта; `graph.json` хранит данные графа. Каждый вид также записывается как SVG (`diagram.svg`, а для нескольких видов — `diagram--.svg`), который можно встроить как изображение в README, pull request или вики.
-
-После правок на странице команда **Ещё → Сохранить изменения** в Chrome или Edge перезаписывает страницу, `graph.json` и SVG на месте, когда вы один раз выберете каталог диаграммы. Другие браузеры сохраняют только `graph.json`: положите его в этот каталог и пересоздайте страницу и SVG командой `npx -y qgraphflow generate docs/qgraphflow//graph.json docs/qgraphflow/ --layout preserve --force`.
-
-
-Запустить пример Jeepay с одиннадцатью видами на основе исходного кода
-
-Выберите локальную копию исходников Jeepay для проверки доказательств:
-
-```bash
-export JEEPAY_REPO_ROOT=""
-node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.json --input-only --repo-root "$JEEPAY_REPO_ROOT"
-node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"
-```
-
-Откройте `output/jeepay/index.html`; одиннадцать SVG находятся в том же каталоге. Версия исходников и процедура обновления описаны в [README корпуса](../../examples/jeepay).
-
-
-
-## Синхронизация диаграмм с кодом
-
-Диаграмма, созданная с указанием корня репозитория, запоминает, где определён каждый компонент, и строку за каждой связью, подтверждённой кодом (вызов, внешний ключ). Проверка с `--repo-root` завершается ошибкой, если записанного файла больше нет, диапазон строк не помещается в файл или записанный символ ушёл из своих строк; в сообщении указано, в каких строках символ находится теперь. Добавьте эту задачу в CI — ей не нужны сборка, вход или токен:
-
-```yaml
-name: Diagrams
-on: [push, pull_request]
-jobs:
- diagrams:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v7
- - uses: actions/setup-node@v7
- with:
- node-version: '22'
- - run: |
- for graph in docs/qgraphflow/*/graph.json; do
- npx -y qgraphflow validate "$graph" --input-only --repo-root . || { echo "::error file=$graph::$graph failed validation"; failed=1; }
- done
- exit ${failed:-0}
-```
-
-Если проверка не прошла, попросите навык обновить диаграмму:
-
-```text
-$qgraphflow:q-flow CI сообщает, что диаграмма docs/qgraphflow/order-sequence устарела. Обнови её.
-```
-
-Навык переносит якоря, символ которых встречается в файле один раз, исправляет только якоря с оставшимися ошибками и пересоздаёт страницу и SVG, сохраняя ваши позиции и тексты. Заново диаграмму он не рисует.
-
-## На какие вопросы отвечает каждый из одиннадцати типов диаграмм
-
-| Вид · PNG | Главный вопрос | Область примера |
-| --- | --- | --- |
-| Архитектура возможностей платформы | Какие возможности есть у платформы? | Зоны возможностей и матрицы |
-| Архитектура инженерных слоёв | Как организован код проекта? | Инженерные слои и общая поддержка |
-| Архитектура связей компонентов | Какие границы ответственности взаимодействуют в системе? | Каналы, оркестрация транзакций, цены, риски, запасы, платежи, заказы, события и исполнение заказов |
-| Блок-схема | Как ветвится и сходится каждая точка решения? | Нехватка запасов, отказ по риску, компенсация сбоя оплаты и успешная фиксация |
-| Последовательность | В каком порядке запрос выполняет вызовы и получает возвраты? | Основной путь успешной покупки и асинхронный OrderPaid |
-| ER | Как связаны основные данные? | Корзина, заказы, позиции, платежи, резервы запасов и посылки |
-| Развёртывание | Где размещены единицы исполнения и как они соединены? | Периметр, Kubernetes, сервисы данных, платежи и складские/логистические сети |
-| Классы | Как зависят объекты домена и контракты кода? | Прикладной сервис Checkout, Order и четыре порта |
-| Состояния | Какие события и охранные условия продвигают заказ? | Оплата, исполнение, отмена, возврат денег и закрытие |
-| Варианты использования | Какие возможности есть у каждого участника? | Покупатель, продавец, склад и поддержка клиентов |
-| Поток данных | Через какие преобразования и хранилища проходят данные? | Корзина, решения по транзакциям, события заказов, склад/логистика и подтверждения доставки |
-
-Это концептуальная демонстрация QGraphFlow, а не модель конкретного торгового репозитория. Пример `graph.json` не выдумывает пути к коду и обозначает основания связей как `inference`. Диаграммы реальных проектов требуют прослеживаемых исходников, DDL, конфигурации, тестов и согласованных требований.
-
-## Разработка и участие
-
-```bash
-npm ci --prefix skills/q-flow/assets/viewer
-npm run build --prefix skills/q-flow/assets/viewer
-node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs
-```
-
-Нужны Node.js 22 или новее, npm, tar, zip и unzip. В сообщении о проблеме приложите минимальный граф без конфиденциальных данных, версии клиента и браузера и шаги воспроизведения.
-
-Справочная документация (на английском): [Источники оснований](../../skills/q-flow/references/evidence-sources.md) · [Формат графов](../../skills/q-flow/references/graph-schema.md) · [Уточнение запроса](../../skills/q-flow/references/guided-intake.md) · [Разработка и приёмка Viewer](../../skills/q-flow/references/viewer-development.md) · [Композиция диаграмм](../../skills/q-flow/references/visual-contract.md)
-
-## Лицензия и принадлежность
-
-[MIT](../../LICENSE) · [Уведомления третьих сторон](../../THIRD_PARTY_NOTICES.md)
-
-QGraphFlow — независимый проект под лицензией MIT. Сценарии в этом документе являются концептуальными примерами и не представляют производственную архитектуру какой-либо реальной компании.
-
-## Обзоры архитектуры
-
-Архитектура теперь включает связи компонентов, возможности платформы и инженерные слои. Опишите предмет и вопрос; навык выберет шаблон. Запрошенные коллекции могут содержать несколько архитектурных видов с независимыми правками.
-
-```text
-$qgraphflow:q-flow Проанализируй возможности платформы и способы бизнес-интеграции текущего проекта и создай обзор возможностей платформы на китайском языке.
-$qgraphflow:q-flow Проанализируй организацию текущего проекта и слои компонентов и создай китайские обзоры всего проекта и среза одного компонента.
-$qgraphflow:q-flow Создай обзор возможностей платформы этого проекта на английском языке и покажи, как интегрируются прикладные модули.
-```
-
-См. [examples/jeepay](../../examples/jeepay) для архитектурных видов платформы, инженерной организации и связей компонентов на основе реального кода. Разблокируйте обзор, чтобы менять порядок карточек в слое или редактировать текст. Сохранение удерживает все виды; сброс восстанавливает только текущий.
diff --git a/docs/readme/README.zh-CN.md b/docs/readme/README.zh-CN.md
deleted file mode 100644
index 4367651..0000000
--- a/docs/readme/README.zh-CN.md
+++ /dev/null
@@ -1,311 +0,0 @@
-