qgraphflow 0.0.6 → 0.0.7

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "qgraphflow",
-      "version": "0.0.6",
+      "version": "0.0.7",
       "source": "./",
       "description": "Generate evidence-grounded interactive software diagrams with offline HTML, SVG and PNG export."
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "qgraphflow",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Generate evidence-grounded interactive software diagrams with offline HTML, SVG and PNG export.",
   "author": {
     "name": "Max Zheng",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "qgraphflow",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Generate evidence-grounded interactive software diagrams with offline HTML, SVG and PNG export.",
   "author": {
     "name": "Max Zheng"
@@ -8,7 +8,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "QGraphFlow",
-    "shortDescription": "Architecture and flow diagrams: nine kinds of interactive software diagrams from source, configuration and documents",
+    "shortDescription": "Architecture and flow diagrams: eleven 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",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "qgraphflow",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Generate evidence-grounded interactive software diagrams with offline HTML, SVG and PNG export.",
   "author": {
     "name": "Max Zheng"

package/.qoder-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "qgraphflow",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Generate evidence-grounded interactive software diagrams with offline HTML, SVG and PNG export.",
   "author": {
     "name": "Max Zheng"

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# QGraphFlow
+<h1><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/brand/qgraphflow-lockup-dark.svg"><img src="docs/images/brand/qgraphflow-lockup-light.svg" alt="QGraphFlow" height="64"></picture></h1>
 
 ### Turn complex code into diagrams you can explore.
 
@@ -10,17 +10,25 @@ Follow the path. Inspect the evidence. Share one offline file.
 
 [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)
 
-[Live demo](https://supermax92.github.io/qgraphflow/) · [Client installation](#installation-guide) · [Report an issue](https://github.com/supermax92/qgraphflow/issues) · [MIT](LICENSE)
+[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)
 
 </div>
 
-![Architecture, sequence and ER views of the agent-desk example, 1.5 seconds each](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.en.hero.gif)
-
-*Nine diagram types: architecture, flowchart, sequence, ER, deployment, class, state, use case and data flow.*
+*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.
 
-**What sets it apart:** nine diagram types from one skill, a source for every relationship, automatic layout, editing in the page, and no network requests from the plugin scripts or the Viewer itself.
+**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.
+
+![Jeepay multi-view interaction demo: component relationship architecture, sequence and ER diagrams](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.en.hero.gif)
+
+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)
+
+**Complex sequence diagram showcase**
+
+![Complex sequence diagram drawn step by step: participants, lifelines, messages, activation bars and nested combined fragments](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.en.sequence-drawing.gif)
+
+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)
 
 ```bash
 npx skills add supermax92/qgraphflow
@@ -30,21 +38,67 @@ One command installs the skill for Claude Code, Codex, Cursor and Qoder; the [in
 
 - **Explore:** search, zoom and pan; inspect responsibilities and upstream/downstream relationships.
 
-  ![Explore: search for refund, jump to Order tools, zoom out to the orchestrator upstream and the order database and logistics downstream, then pan](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.en.explore.gif)
-
 - **Verify:** inspect nodes and edges for source files, lines, symbols and explicitly marked uncertainty.
 
-  ![Verify: quick-look card with src/gateway/chat-gateway.js:5-19, details with the symbol and evidence facts, then the POST /chat edge marked as inference](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.en.verify.gif)
-
 - **Edit:** unlock the layout, change text and move elements; reset when needed.
 
-  ![Edit: unlock the layout, rename LLM provider to LLM gateway, drag it with its edges, then reset](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.en.edit.gif)
-
 - **Share:** open offline HTML or export the complete diagram as SVG / PNG.
 
-  ![Share: open the offline HTML, export PNG from More, then the exported file itself](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.en.share.gif)
+The real-source [Jeepay corpus](examples/jeepay) contains all eleven 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 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
+
+```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.
+```
 
-The top animation shows the architecture, sequence and ER views for 1.5 seconds each (4.5 seconds per loop); the four feature animations run 6.5–8.5 seconds. All of them are recorded from the source-built Viewer on the [agent-desk example](examples/showcase/agent-desk) — fictional business, real code — with English graph and interface text. They are hosted as [showcase-v2 Release assets](https://github.com/supermax92/qgraphflow/releases/tag/showcase-v2) and kept out of Git history and the plugin package, so viewing them needs network access; the generated diagram HTML itself works offline.
+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
 
@@ -62,9 +116,18 @@ To install it as a plugin instead, follow the steps below. [Qoder Desktop](#qode
 
 ### 1. Download the plugin
 
-Download [qgraphflow-0.0.6.zip](https://github.com/supermax92/qgraphflow/releases/download/v0.0.6/qgraphflow-0.0.6.zip) and extract it into a separate directory, keeping hidden files.
+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 extracted plugin root containing `skills/`**.
+Run the following terminal commands from **the plugin root containing `skills/`**.
 
 ### 2. Install in your client
 
@@ -81,17 +144,8 @@ Start a new session, type `$`, and select `qgraphflow:q-flow`.
 
 #### Claude Code
 
-Install directly from GitHub without downloading the ZIP:
-
 ```bash
-claude plugin marketplace add supermax92/qgraphflow
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Or, from the extracted plugin root:
-
-```bash
-claude plugin marketplace add .
+claude plugin marketplace add ./
 claude plugin install qgraphflow@supermax92 --scope user
 ```
 
@@ -107,9 +161,9 @@ Start a new session and select `q-flow`.
 
 #### Qoder Desktop
 
-**Recommended:** Open **Settings → Plugins → Marketplace**, search for **代码图谱可视化** or **qgraphflow**, and install the plugin. Start a new session and select `q-flow`. No ZIP download or source build is required.
+**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 extracted plugin root directory. 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
 
@@ -123,27 +177,11 @@ Confirm that `.cursor-plugin/plugin.json` exists there, reload the window, and f
 
 ### 3. Start using it
 
-Open your project in the client, start a new session, and select the skill. Describe your task using the [Quick start](#quick-start) examples below. Open the generated HTML in your browser.
-
-<details>
-<summary>Alternative installation: npm</summary>
-
-You can also get the plugin from npmjs.com instead of the ZIP; 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. Continue with the client installation steps above. **Downloading through npm does not automatically install the plugin in your client.** The package also provides the `qgraphflow` command used in [Keep diagrams in sync with code](#keep-diagrams-in-sync-with-code).
-
-</details>
+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 start
+## 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.
 
@@ -158,7 +196,7 @@ $qgraphflow:q-flow
 ### Example 1: Understand the architecture
 
 ```text
-$qgraphflow:q-flow Analyze this project and create an architecture diagram in English showing module responsibilities, dependencies and system boundaries.
+$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.
@@ -166,13 +204,13 @@ Useful when joining a project and learning its overall structure.
 ### Example 2: Trace a business flow
 
 ```text
-$qgraphflow:q-flow Analyze order creation and create a sequence diagram in English showing pricing, stock reservation, payment and order persistence, including failure branches.
+$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 stock reservation from the previous diagram into a separate flowchart in English, showing success and failure handling.
+$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-<n>-<type>.svg` for several views) that you can embed as an image in a README, pull request or wiki.
@@ -180,26 +218,23 @@ Results go under `docs/qgraphflow/` by default. Open `index.html` to explore, ed
 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/<name>/graph.json docs/qgraphflow/<name> --layout preserve --force`.
 
 <details>
-<summary>Run the nine-view e-commerce example manually</summary>
+<summary>Run the eleven-view Jeepay source example</summary>
 
-These commands run the repository example. An installed plugin does not require cloning this repository. With Node.js 22 or later:
+Select your Jeepay source checkout to verify the evidence:
 
 ```bash
-git clone https://github.com/supermax92/qgraphflow.git
-cd qgraphflow
-node skills/q-flow/scripts/validate-graph.mjs examples/showcase/ecommerce.en.graph.json
-node skills/q-flow/scripts/generate-viewer.mjs examples/showcase/ecommerce.en.graph.json output/ecommerce-en
+export JEEPAY_REPO_ROOT="<local Jeepay repository 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/ecommerce-en/index.html` in a browser; the nine SVGs sit next to it. Switch views with **Diagram types** in the top toolbar; saved text and positions survive switching. **More → Save changes** saves all views as described above. The same pages are online in the [live demo](https://supermax92.github.io/qgraphflow/).
-
-The prebuilt Viewer needs no dependency installation, API key or backend service. AI-assisted evidence gathering and graph authoring use your chosen client's model service.
+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.
 
 </details>
 
 ## Keep diagrams in sync with code
 
-A diagram generated with a repository root records where each component is defined. 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:
+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:
 
 ```yaml
 name: Diagrams
@@ -227,19 +262,21 @@ $qgraphflow:q-flow CI says docs/qgraphflow/order-sequence is out of date. Refres
 
 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.
 
-## What each of the nine views answers
+## What each of the eleven diagram types answers
 
 | View · PNG | Main question | Example scope |
 | --- | --- | --- |
-| Architecture | Which responsibilities collaborate? | Channels, checkout, pricing, risk, stock, payment, orders, events and fulfillment |
-| Flowchart | Where does the process branch and converge? | Stock shortage, risk rejection, payment compensation and successful commit |
-| Sequence | In what order do calls and returns occur? | Successful checkout and asynchronous OrderPaid |
-| ER | How does core data relate? | Cart, orders, items, payments, reservations and parcels |
-| Deployment | Where do runtime units run and connect? | Edge, Kubernetes, data services, payments and logistics networks |
-| Class | How do domain objects and contracts depend on each other? | Checkout service, Order and four ports |
+| 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 can each actor do? | Buyer, merchant, warehouse and support |
-| Data flow | How is data transformed and stored? | Cart, transaction decisions, events, warehouse and delivery receipts |
+| 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.
 
@@ -253,10 +290,22 @@ 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.
 
-[Evidence sources](skills/q-flow/references/evidence-sources.md) · [Graph format](skills/q-flow/references/graph-schema.md) · [Guided intake](skills/q-flow/references/guided-intake.md) · [Viewer development](skills/q-flow/references/viewer-development.md) · [Diagram composition](skills/q-flow/references/visual-contract.md)
+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 and do not represent any company's production architecture; no affiliation, sponsorship or endorsement is implied.
+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.
+```
+
+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.

package/docs/clients.de.md

@@ -4,9 +4,9 @@
 
 [Zurück zur README](readme/README.de.md)
 
-Qoder Desktop kann das Plugin aus dem Marketplace installieren, Claude Code direkt von GitHub (siehe die jeweiligen Abschnitte unten). In beiden Fällen entfällt Schritt 1. Für eine lokale Installation lade zuerst den QGraphFlow-Quellcode herunter und erstelle das Laufzeitpaket.
+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 und einen Client mit eingerichtetem Modellzugriff. Zum Bauen aus dem Quellcode werden außerdem Git, npm, `tar`, `zip` und `unzip` benötigt.
+Du benötigst Node.js 22 oder neuer (mit npm) und einen Client mit eingerichtetem Modellzugriff.
 
 ## Schnellinstallation
 
@@ -16,25 +16,25 @@ 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. Für die lokale Installation herunterladen und bauen
+## 1. Plugin über npm herunterladen
 
 ```bash
-git clone https://github.com/supermax92/qgraphflow.git
-cd qgraphflow
-npm run package
-unzip -q dist/qgraphflow-0.0.6.zip -d dist/runtime
+mkdir qgraphflow-install
+cd qgraphflow-install
+npm install qgraphflow --ignore-scripts
+cd node_modules/qgraphflow
 ```
 
-Wenn der QGraphFlow-Quellcode bereits vorliegt, überspringe das Klonen und wechsle in dessen Stammverzeichnis. Passe den ZIP-Dateinamen an die Version in der `package.json` von QGraphFlow an. Verwende neue Ausgabe- und Entpackverzeichnisse, ohne vorhandene Dateien zu überschreiben. Git lädt nur bereits gepushten Code herunter, keine lokalen Änderungen ohne Commit.
+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 Stammverzeichnis des QGraphFlow-Quellcodes aus, nicht im Verzeichnis deines eigenen Anwendungsprojekts. Sie installieren das vollständige Laufzeitpaket aus dem dortigen Unterverzeichnis `dist/runtime`.
+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 ./dist/runtime
+codex plugin marketplace add .
 codex plugin add qgraphflow@supermax92
 ```
 
@@ -44,17 +44,8 @@ Starte eine neue Sitzung, gib `$` ein und wähle `qgraphflow:q-flow` aus (verwen
 
 ### Claude Code
 
-Direkt von GitHub installieren, ohne Schritt 1:
-
-```bash
-claude plugin marketplace add supermax92/qgraphflow
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Oder aus dem in Schritt 1 erstellten Laufzeitpaket:
-
 ```bash
-claude plugin marketplace add ./dist/runtime
+claude plugin marketplace add ./
 claude plugin install qgraphflow@supermax92 --scope user
 ```
 
@@ -63,20 +54,20 @@ Starte eine neue Sitzung und gib `/q-flow` (oder den vollständigen Namen `/qgra
 ### Qoder CLI
 
 ```bash
-qodercli plugins install ./dist/runtime
+qodercli plugins install .
 ```
 
 Starte eine neue Sitzung und wähle `q-flow` aus.
 
 ### Qoder Desktop
 
-**Empfohlen:** Öffne **Settings → Plugins → Marketplace**, suche nach **代码图谱可视化** oder **qgraphflow** und installiere das Plugin. Starte eine neue Sitzung und wähle `q-flow`. Ein ZIP-Download oder ein Build aus dem Quellcode ist nicht erforderlich.
+**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 Verzeichnis `dist/runtime`. Lade den Client neu 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 von `dist/runtime`, einschließlich versteckter Dateien, nach `~/.cursor/plugins/local/qgraphflow/`. Sichere ein vorhandenes Verzeichnis zuerst; vermische keine alten und neuen Dateien.
+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.
 

package/docs/clients.es.md

@@ -4,9 +4,9 @@
 
 [Volver al README](readme/README.es.md)
 
-Qoder Desktop permite instalar el complemento desde su Marketplace, y Claude Code directamente desde GitHub (consulta sus secciones más abajo). En ambos casos puedes omitir el paso 1. Para una instalación local, primero descarga el código fuente de QGraphFlow y genera el paquete de ejecución.
+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 y un cliente con acceso al modelo configurado. Para compilar desde el código fuente también necesitas Git, npm, `tar`, `zip` y `unzip`.
+Necesitas Node.js 22 o posterior (con npm) y un cliente con acceso al modelo configurado.
 
 ## Instalación rápida
 
@@ -16,25 +16,25 @@ 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 y generar el paquete para la instalación local
+## 1. Descargar el complemento con npm
 
 ```bash
-git clone https://github.com/supermax92/qgraphflow.git
-cd qgraphflow
-npm run package
-unzip -q dist/qgraphflow-0.0.6.zip -d dist/runtime
+mkdir qgraphflow-install
+cd qgraphflow-install
+npm install qgraphflow --ignore-scripts
+cd node_modules/qgraphflow
 ```
 
-Si ya tienes el código fuente de QGraphFlow, omite la clonación y entra en su directorio raíz. Ajusta el nombre del ZIP a la versión del `package.json` de QGraphFlow. Usa directorios nuevos para generar y extraer el paquete, sin sobrescribir archivos existentes. Git solo descarga el código enviado al repositorio, no los cambios locales sin commit.
+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 código fuente de QGraphFlow, no desde el directorio de tu propio proyecto. Instalan el paquete completo de la subcarpeta `dist/runtime`.
+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 ./dist/runtime
+codex plugin marketplace add .
 codex plugin add qgraphflow@supermax92
 ```
 
@@ -44,17 +44,8 @@ Inicia una sesión nueva, escribe `$` y selecciona `qgraphflow:q-flow` (usa el n
 
 ### Claude Code
 
-Instala directamente desde GitHub, sin el paso 1:
-
-```bash
-claude plugin marketplace add supermax92/qgraphflow
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-O bien, desde el paquete de ejecución generado en el paso 1:
-
 ```bash
-claude plugin marketplace add ./dist/runtime
+claude plugin marketplace add ./
 claude plugin install qgraphflow@supermax92 --scope user
 ```
 
@@ -63,20 +54,20 @@ Inicia una sesión nueva y escribe `/q-flow` (o el nombre completo `/qgraphflow:
 ### Qoder CLI
 
 ```bash
-qodercli plugins install ./dist/runtime
+qodercli plugins install .
 ```
 
 Inicia una sesión nueva y selecciona `q-flow`.
 
 ### Qoder Desktop
 
-**Recomendado:** Abre **Settings → Plugins → Marketplace**, busca **代码图谱可视化** o **qgraphflow** e instala el complemento. Inicia una sesión nueva y selecciona `q-flow`. No necesitas descargar un ZIP ni compilar el código fuente.
+**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 completo `dist/runtime`. Recarga el cliente 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 `dist/runtime`, 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.
+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.