qgraphflow 0.0.6

package/docs/readme/README.ja.md

@@ -0,0 +1,262 @@
+<div align="center">
+
+# QGraphFlow
+
+### 複雑なコードを、探索できる図へ。
+
+経路をたどり、根拠を確認し、ひとつのオフラインファイルで共有。
+
+<sub>💡 <a href="https://github.com/Cocoon-AI/architecture-diagram-generator">Cocoon-AI/architecture-diagram-generator</a> に着想を得ました。原作者に感謝します。</sub>
+
+[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)
+
+</div>
+
+![agent-desk サンプルのアーキテクチャ図・シーケンス図・ER 図を 1.5 秒ずつ](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ja.hero.gif)
+
+*9種類の図に対応：アーキテクチャ、フローチャート、シーケンス、ER、配置、クラス、状態、ユースケース、データフロー。*
+
+QGraphFlow はソースコード、データ構造、設定、要件から対話型のソフトウェア図を生成します。関係の根拠を確認し、共有可能なオフライン HTML として届けます。
+
+**ここが違う：** 1 つのスキルで 9 種類の図、すべての関係に出典、自動レイアウト、ページ上での編集。プラグインのスクリプトと Viewer 自体はネットワーク通信を一切行いません。
+
+```bash
+npx skills add supermax92/qgraphflow
+```
+
+1 つのコマンドで Claude Code、Codex、Cursor、Qoder にスキルを導入できます。プラグインとしての導入やほかのクライアントは[インストールガイド](#インストールガイド)を参照してください。
+
+- **探索：** 検索・拡大縮小・パンで、責務と上流・下流の関係を確認。
+
+  ![探索：refund を検索して注文ツールへジャンプし、上流のエージェントオーケストレーターと下流の注文データベース・配送追跡サービスが見えるまで縮小してからパンする](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ja.explore.gif)
+
+- **検証：** ノードや接続線からファイル、行番号、シンボル、明示された不確実性を確認。
+
+  ![検証：src/gateway/chat-gateway.js:5-19 を示すカード、シンボルと根拠事実を示す詳細パネル、そして inference と記された POST /chat の接続線](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ja.verify.gif)
+
+- **編集：** ロック解除後に文字や位置を変更。必要に応じてリセット。
+
+  ![編集：ロックを解除し、LLM プロバイダーを LLM ゲートウェイに改名し、接続線ごとドラッグしてからリセットする](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ja.edit.gif)
+
+- **共有：** オフライン HTML を開くか、図全体を SVG / PNG に出力。
+
+  ![共有：オフライン HTML を開き、「その他」から PNG を書き出し、書き出されたファイルそのものを表示する](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ja.share.gif)
+
+上部のアニメーションはアーキテクチャ図・シーケンス図・ER 図を 1.5 秒ずつ（1 ループ 4.5 秒）表示し、4 つの機能アニメーションは 6.5〜8.5 秒です。すべてソースからビルドした Viewer で [agent-desk サンプル](../../examples/showcase/agent-desk)（架空の業務、実在のコード）を日本語の図と UI で録画しています。[showcase-v2 Release のアセット](https://github.com/supermax92/qgraphflow/releases/tag/showcase-v2)として配置し、Git 履歴やプラグインパッケージには含めないため閲覧にはネットワークが必要です。生成された図の HTML 自体はオフラインで動作します。
+
+## インストールガイド
+
+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) ではマーケットプレイスから直接インストールできるため、手順 1 は不要です。
+
+### 1. プラグインをダウンロード
+
+[qgraphflow-0.0.6.zip](https://github.com/supermax92/qgraphflow/releases/download/v0.0.6/qgraphflow-0.0.6.zip) をダウンロードし、隠しファイルを保持したまま専用のディレクトリに展開します。
+
+以下のコマンドはすべて、**展開後の `skills/` を含むプラグインのルートディレクトリ**で実行してください。
+
+### 2. クライアントにインストール
+
+#### Codex App / CLI
+
+ターミナルで Codex CLI を使用できるよう、あらかじめインストールしてください。
+
+```bash
+codex plugin marketplace add .
+codex plugin add qgraphflow@supermax92
+```
+
+新しいセッションを開始し、`$` を入力して `qgraphflow:q-flow` を選択します。
+
+#### Claude Code
+
+ZIP をダウンロードせず、GitHub から直接インストールします：
+
+```bash
+claude plugin marketplace add supermax92/qgraphflow
+claude plugin install qgraphflow@supermax92 --scope user
+```
+
+または、展開したプラグインのルートで実行します：
+
+```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` を選択します。ZIP のダウンロードやソースのビルドは不要です。
+
+ローカルインストールの場合は手順 1 を完了し、**Settings → Plugins → Custom → Import** を開いて、展開したプラグインのルートディレクトリ全体をインポートします。新しいセッションで `q-flow` を選択します。
+
+#### Cursor
+
+プラグインのルートディレクトリ内のすべてのファイル（隠しファイルを含む）を、次の場所にコピーします。
+
+```text
+~/.cursor/plugins/local/qgraphflow/
+```
+
+その中に `.cursor-plugin/plugin.json` があることを確認し、ウィンドウを再読み込みして **Customize** で `q-flow` を探します。旧バージョンがある場合は先にバックアップし、新旧のファイルを混在させないでください。
+
+### 3. 使い始める
+
+クライアントで対象のプロジェクトを開き、新しいセッションでスキルを選択します。下の[すぐに使う](#すぐに使う)の例を参考に依頼し、生成された HTML をブラウザで開いてください。
+
+<details>
+<summary>別のインストール方法：npm</summary>
+
+ZIP の代わりに npmjs.com からプラグインを取得することもできます。アカウント、ログイン、トークンは不要です。業務プロジェクトの外に専用ディレクトリを作成します。
+
+```bash
+mkdir qgraphflow-install
+cd qgraphflow-install
+npm install qgraphflow --ignore-scripts
+cd node_modules/qgraphflow
+```
+
+これでプラグインのルートディレクトリに移動できました。上記のクライアント別インストール手順に進んでください。**npm でダウンロードしても、クライアントへのインストールは自動では行われません。** このパッケージには `qgraphflow` コマンドも含まれ、[図とコードを同期させる](#図とコードを同期させる)で使います。
+
+</details>
+
+自分でビルドする場合は、[ソースからのビルド手順](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally)を参照してください。
+
+## すぐに使う
+
+以下は Codex の `$qgraphflow:q-flow` を使う例です。クライアントに `$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-<n>-<type>.svg`）としても書き出され、README、プルリクエスト、Wiki に画像として埋め込めます。
+
+ページで編集したあと、Chrome または Edge で「その他 → 変更を保存」を実行し、図のフォルダーを一度選ぶと、ページ、`graph.json`、SVG がその場で書き換わります。ほかのブラウザーは `graph.json` だけを保存します。そのフォルダーに置いてから `npx -y qgraphflow generate docs/qgraphflow/<name>/graph.json docs/qgraphflow/<name> --layout preserve --force` でページと SVG を再生成してください。
+
+<details>
+<summary>EC の9種類のサンプルを手動で実行</summary>
+
+次のコマンドはリポジトリ内のサンプル用です。導入済みプラグインの使用には、このリポジトリの複製は不要です。Node.js 22 以降を用意して実行します。
+
+```bash
+git clone https://github.com/supermax92/qgraphflow.git
+cd qgraphflow
+node skills/q-flow/scripts/validate-graph.mjs examples/showcase/ecommerce.ja.graph.json
+node skills/q-flow/scripts/generate-viewer.mjs examples/showcase/ecommerce.ja.graph.json output/ecommerce-ja
+```
+
+ブラウザーで `output/ecommerce-ja/index.html` を開きます。9 つの SVG も同じディレクトリにあります。上部の「図の種類」から切り替えます。各図で保存した文字と位置は切り替えても保持されます。「その他 → 変更を保存」で、上で説明したとおり全ビューを保存します。同じページは[オンラインデモ](https://supermax92.github.io/qgraphflow/)でも見られます。
+
+ビルド済み Viewer からのページ生成には、依存関係のインストール、API キー、バックエンドは不要です。AI による根拠収集と図の作成には、選んだクライアントのモデルサービスを使います。
+
+</details>
+
+## 図とコードを同期させる
+
+リポジトリのルートを指定して生成した図には、各コンポーネントの定義位置が記録されます。`--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 の図が古いと出ました。更新してください。
+```
+
+スキルは、ファイル内で 1 か所だけ見つかったシンボルのアンカーを移し、なお失敗するアンカーだけを修正し、編集した位置と文字を保ったままページと SVG を再生成します。図を描き直すことはしません。
+
+## 9種類の図が答えること
+
+| 図 · PNG | 主な問い | サンプルの範囲 |
+| --- | --- | --- |
+| アーキテクチャ | どの責務が協調するか？ | チャネル、決済、価格、リスク、在庫、支払い、注文、イベント、出荷 |
+| フローチャート | 判断はどこで分岐・合流するか？ | 欠品、リスク拒否、支払い補償、正常コミット |
+| シーケンス | 呼び出しと戻りの順序は？ | 決済成功経路と非同期 OrderPaid |
+| ER | 主要データはどう関連するか？ | カート、注文、明細、支払い、引当、荷物 |
+| 配置 | 実行単位をどこに置き、どう接続するか？ | エッジ、Kubernetes、データサービス、支払い、倉庫配送ネットワーク |
+| クラス | ドメインオブジェクトと契約はどう依存するか？ | 決済サービス、Order、4つのポート |
+| 状態 | どのイベントとガードが注文を進めるか？ | 支払い、出荷、取消、返金、終了 |
+| ユースケース | 各利用者に何ができるか？ | 購入者、店舗、倉庫、サポート |
+| データフロー | データをどう変換・保存するか？ | カート、取引判断、注文イベント、倉庫、配送受領記録 |
+
+これは QGraphFlow の機能を示す概念モデルで、特定の EC リポジトリに対応しません。サンプルの `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 ライセンスの独立プロジェクトです。本文のシナリオは概念例で、実在する企業の本番構成を表しません。提携、後援、推奨を意味するものでもありません。

package/docs/readme/README.pt.md

@@ -0,0 +1,262 @@
+<div align="center">
+
+# QGraphFlow
+
+### Transforme código complexo em diagramas que você pode explorar.
+
+Siga o caminho. Confira as evidências. Compartilhe um arquivo offline.
+
+<sub>💡 Inspirado em <a href="https://github.com/Cocoon-AI/architecture-diagram-generator">Cocoon-AI/architecture-diagram-generator</a> — agradecemos pela ideia.</sub>
+
+[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/) · [Instalação por cliente](#guia-de-instalação) · [Relatar problema](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
+
+</div>
+
+![Arquitetura, sequência e ER do exemplo agent-desk, 1,5 segundo por vista](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.pt.hero.gif)
+
+*Nove tipos: arquitetura, 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:** nove tipos de diagrama em uma só habilidade, a origem de cada relação, 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.
+
+```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.
+
+  ![Explorar: pesquisar refund, saltar para Ferramentas de pedidos, afastar até o orquestrador acima e o banco de pedidos e o rastreamento logístico abaixo, depois deslocar a tela](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.pt.explore.gif)
+
+- **Verificar:** inspecionar nós e conexões para conferir arquivos, linhas, símbolos e incertezas explícitas.
+
+  ![Verificar: cartão com src/gateway/chat-gateway.js:5-19, painel de detalhes com o símbolo e os fatos de evidência, depois a conexão POST /chat marcada como inference](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.pt.verify.gif)
+
+- **Editar:** desbloquear o layout, alterar textos e mover elementos; redefinir quando necessário.
+
+  ![Editar: desbloquear o layout, renomear Provedor LLM para Gateway LLM, arrastá-lo com suas conexões, depois redefinir](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.pt.edit.gif)
+
+- **Compartilhar:** abrir o HTML offline ou exportar o diagrama completo em SVG / PNG.
+
+  ![Compartilhar: abrir o HTML offline, exportar PNG em Mais, depois o próprio arquivo exportado](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.pt.share.gif)
+
+A animação do topo mostra arquitetura, sequência e ER por 1,5 segundo cada (4,5 segundos por ciclo); as quatro animações de recursos duram de 6,5 a 8,5 segundos. Todas foram gravadas no Viewer construído a partir do código-fonte sobre o [exemplo agent-desk](../../examples/showcase/agent-desk) — negócio fictício, código real — com diagramas e interface em português. Estão hospedadas como [assets da Release showcase-v2](https://github.com/supermax92/qgraphflow/releases/tag/showcase-v2), fora do histórico Git e do pacote do plugin, portanto vê-las exige rede; o HTML gerado do diagrama funciona offline.
+
+## 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
+
+Baixe [qgraphflow-0.0.6.zip](https://github.com/supermax92/qgraphflow/releases/download/v0.0.6/qgraphflow-0.0.6.zip) e extraia em um diretório separado, preservando os arquivos ocultos.
+
+Execute os comandos abaixo na **raiz do plugin extraído, 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
+
+Instale diretamente do GitHub sem baixar o ZIP:
+
+```bash
+claude plugin marketplace add supermax92/qgraphflow
+claude plugin install qgraphflow@supermax92 --scope user
+```
+
+Ou, a partir da raiz do plugin extraído:
+
+```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 **代码图谱可视化** ou **qgraphflow** e instale o plugin. Inicie uma nova sessão e selecione `q-flow`. Não é necessário baixar um ZIP nem compilar o código-fonte.
+
+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 extraído. 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 no cliente, inicie uma nova sessão e selecione a habilidade. Descreva a tarefa seguindo os exemplos de [Início rápido](#início-rápido) abaixo. Abra o HTML gerado no navegador.
+
+<details>
+<summary>Outra forma de instalação: npm</summary>
+
+Você também pode obter o plugin no npmjs.com em vez do ZIP, 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. Continue com as etapas de instalação no cliente acima. **Baixar pelo npm não instala automaticamente o plugin no cliente.** 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).
+
+</details>
+
+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).
+
+## Início 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 portuguê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 portuguê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 portuguê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-<n>-<type>.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/<name>/graph.json docs/qgraphflow/<name> --layout preserve --force`.
+
+<details>
+<summary>Executar manualmente o exemplo de comércio com nove vistas</summary>
+
+Os comandos abaixo executam o exemplo do repositório. Usar um plugin já instalado não exige clonar este repositório. Com Node.js 22 ou posterior:
+
+```bash
+git clone https://github.com/supermax92/qgraphflow.git
+cd qgraphflow
+node skills/q-flow/scripts/validate-graph.mjs examples/showcase/ecommerce.pt.graph.json
+node skills/q-flow/scripts/generate-viewer.mjs examples/showcase/ecommerce.pt.graph.json output/ecommerce-pt
+```
+
+Abra `output/ecommerce-pt/index.html` no navegador; os nove SVG ficam ao lado. Alterne em **Tipos de diagrama** na barra superior; cada vista mantém seus textos e posições salvos. **Mais → Salvar alterações** salva todas as vistas como descrito acima. As mesmas páginas estão na [demonstração online](https://supermax92.github.io/qgraphflow/).
+
+O Viewer pré-compilado não exige instalar dependências, chave de API ou backend. A coleta de evidências e a criação de diagramas por IA usam o serviço de modelos do cliente escolhido.
+
+</details>
+
+## Mantenha os diagramas em sincronia com o código
+
+Um diagrama gerado com a raiz do repositório registra onde cada componente é definido. 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 uma das nove vistas responde
+
+| Vista · PNG | Pergunta principal | Escopo do exemplo |
+| --- | --- | --- |
+| Arquitetura | Quais responsabilidades colaboram? | Canais, compra, preços, risco, estoque, pagamento, pedidos, eventos e entrega |
+| Fluxograma | Onde o processo se ramifica e converge? | Falta de estoque, recusa de risco, compensação de pagamento e confirmação bem-sucedida |
+| Sequência | Em que ordem ocorrem chamadas e retornos? | Compra bem-sucedida e OrderPaid assíncrono |
+| ER | Como os dados centrais se relacionam? | Carrinho, pedidos, itens, pagamentos, reservas e pacotes |
+| Implantação | Onde as unidades executam e se conectam? | Borda, Kubernetes, serviços de dados, pagamentos e redes logísticas |
+| Classes | Como objetos de domínio e contratos dependem entre si? | Serviço de compra, Order e quatro portas |
+| Estados | Quais eventos e condições avançam um pedido? | Pagamento, entrega, cancelamento, reembolso e encerramento |
+| Casos de uso | O que cada ator pode fazer? | Comprador, lojista, depósito e atendimento |
+| Fluxo de dados | Como os dados são transformados e armazenados? | Carrinho, decisões, eventos, depósito 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 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 conceituais e não representam a arquitetura de produção de nenhuma empresa; não implica afiliação, patrocínio ou endosso.