suken-cite-guide 0.1.0__tar.gz

suken_cite_guide-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 suken
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

suken_cite_guide-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: suken-cite-guide
+Version: 0.1.0
+Summary: Giải thích có bằng chứng (ảnh nguồn khoanh đỏ kèm dòng dịch, tuyến truyện trên khung UI, thẻ giải thích code) và cầm tay chỉ việc trên trình duyệt; 5 chế độ bật bằng từ khoá qua hook Claude Code.
+Author: suken
+License-Expression: MIT
+Keywords: citation,screenshot,highlight,annotation,llm,claude-code
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Environment :: Console
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Dynamic: license-file
+
+# suken-cite-guide
+
+Giúp một LLM agent (như Claude Code) **giải thích có bằng chứng** và **cầm tay chỉ việc** cho người dùng.
+Mỗi khẳng định kèm ảnh chụp nguồn khoanh đỏ đoạn trích và một dòng dịch; mỗi việc cần làm trên trình duyệt
+thì agent vẽ vòng đỏ ngay trên màn hình để người dùng tự bấm. Gói có 5 chế độ, người dùng gõ từ khoá trong
+chat để bật đúng chế độ cần:
+
+| Từ khoá | Chế độ | Người đọc nhận |
+| --- | --- | --- |
+| `suken-Story` | cốt truyện giải thích | **một link** tuyến truyện vẽ trên khung UI (trục thời gian, chuỗi nhân quả, so sánh, so số liệu, mâu thuẫn, chỗ hổng…), đi từng bước bằng ◀ ▶, ô nào cũng có 📷 mở ảnh nguồn |
+| `suken-Cite` | trích dẫn đơn lẻ | câu trả lời ngắn, mỗi ý kèm một link ảnh nguồn khoanh đỏ |
+| `suken-CodeStory` | cốt truyện code | một flow qua nhiều module kể thành tuyến truyện, mỗi bước một thẻ giải thích code |
+| `suken-Code` | thẻ code | một thẻ gom vị trí trong flow, class, hàm, thư viện, biến và giá trị thật lúc chạy, bằng màu, icon, sơ đồ |
+| `suken-Guide` / `suken-non_Guide` | cầm tay chỉ việc | vòng đỏ, mũi tên, 📋 dán, ⏎, 🔗 vẽ trên chính tab của mình; tự bấm từng bước, bấm sai thì bị chặn |
+
+Nguồn có thể là trang web (kể cả email, chat phải đăng nhập), PDF, Word, Excel, PowerPoint, CSV, ảnh, file
+code và file chữ (mở trong VS Code chạy trên trình duyệt).
+
+## Dùng thế nào
+
+Cài gói, rồi cài hook một lần trong thư mục mở Claude Code:
+
+```bash
+pip install suken-cite-guide
+suken-cite-guide setup        # cài hook, 2 reviewer, code-server; kiểm chrome-devtools
+```
+
+Từ đó, gõ từ khoá kèm yêu cầu trong chat, ví dụ `suken-Story vì sao run B chậm hơn run A?`. Hook đưa
+nguyên hướng dẫn của chế độ đó cho agent ngay trong lượt chat, agent không phải tự nhớ đọc. Riêng
+`suken-Guide` giữ tới khi gõ `suken-non_Guide`: trong lúc bật, hook chặn agent tự bấm, gõ, mở, đóng tab
+trên trình duyệt, chỉ người dùng tắt được.
+
+Không dùng hook (agent khác Claude Code): bảo agent chạy `suken-cite-guide usage` để chọn chế độ và đọc
+hướng dẫn. Mỗi hướng dẫn cùng một khung: luật vàng, checklist, review; agent chỉ giao kết quả khi reviewer
+chấm **ĐẠT**.
+
+## Các lệnh
+
+| Lệnh | Làm gì |
+| --- | --- |
+| `suken-cite-guide setup [--remove]` | cài hook cho 5 từ khoá (`.claude/settings.local.json`, giữ nguyên hook khác), 2 subagent reviewer (`.claude/agents/`), code-server (~220 MB vào cache); kiểm MCP chrome-devtools và cổng Chrome DevTools rồi báo thiếu gì. `--remove` gỡ hook và reviewer |
+| `suken-cite-guide usage [story\|cite\|codestory\|code\|guide\|renderer]` | in hướng dẫn của một chế độ (không kèm: in danh sách chế độ) |
+| `suken-cite-guide init --dir ./cites` | tạo thư mục dự án trích dẫn |
+| `suken-cite-guide serve --dir ./cites` | bật server xem ảnh, xem file (mặc định cổng 8123); `render/pdf.html?file=…&page=` và `render/open.html?file=…` mở thẳng PDF, Word, Excel, PowerPoint, CSV |
+| `suken-cite-guide text --file … \| --doc …` | in chữ của nguồn (pdf, docx, xlsx, pptx) để đọc nhanh trước khi chụp |
+| `suken-cite-guide add …` | thêm trích dẫn: ảnh chụp `--image` + `--box`, hoặc thẻ code `--explain <json>` — thiếu mục nào thì từ chối và nói rõ |
+| `suken-cite-guide skeleton --file … --lines …` | thẻ code: in khung JSON điền sẵn class, hàm, biến của các dòng code (Python) |
+| `suken-cite-guide story --template timeline\|argument` | in khung truyện; điền xong thì `story --id … --json …` kiểm và lưu |
+| `suken-cite-guide editor --folder …` | mở VS Code chạy trên trình duyệt (code-server); lần đầu tự tải ~220 MB vào cache |
+| `suken-cite-guide guide template` | in khung kịch bản cầm tay chỉ việc |
+| `suken-cite-guide guide run <kịch bản\|->` | kiểm kịch bản rồi vẽ vòng đỏ trên tab người dùng; mỗi lần cần agent (xong, lạc, bấm sai, tunnel…) in một dòng JSON kèm ảnh tab và tóm tắt trang |
+| `suken-cite-guide guide reattach [địa chỉ]` | gắn bộ điều khiển đang chạy vào kết nối Chrome mới (sau khi người dùng mở lại tunnel) |
+| `suken-cite-guide register`, `snapshot`, `urls` | ghi nguồn gốc file; lưu bản sao trang web (cách cũ); in link |
+| `suken-cite-guide check` | kiểm mọi trích dẫn và mọi truyện |
+
+Ví dụ một trích dẫn:
+
+```bash
+suken-cite-guide init --dir ./cites
+suken-cite-guide serve --dir ./cites &
+# agent mở nguồn trên Chrome, chụp màn hình vào ./cites/shots/price.png, rồi chỉ vùng cần khoanh:
+suken-cite-guide add --dir ./cites --id price --image ./cites/shots/price.png --box 120,340,860,372 \
+  --quote "Pears 2.40/kg" --section "prices.pdf · trang 3" --vi "Lê giá 2,40 mỗi kg."
+# link cho người đọc : http://127.0.0.1:8123/c.html?id=price
+```
+
+## Yêu cầu
+
+- Python 3.9+ (không cần thư viện Python nào khác; phần chạy trên trình duyệt đã đóng gói sẵn).
+- Chrome, và Claude Code có MCP server **chrome-devtools**; cầm tay chỉ việc dùng chung cổng DevTools đó
+  (mặc định `http://127.0.0.1:9222`).
+- Hook và từ khoá: Claude Code.
+- Nguồn phải đăng nhập (email, chat…): đăng nhập sẵn trên chính Chrome mà chrome-devtools điều khiển.
+- Linux hoặc macOS.
+
+## Giấy phép
+
+MIT. Các thư viện trình duyệt đi kèm và giấy phép của chúng nằm trong `THIRD_PARTY_NOTICES.md`.

suken_cite_guide-0.1.0/README.md

@@ -0,0 +1,78 @@
+# suken-cite-guide
+
+Giúp một LLM agent (như Claude Code) **giải thích có bằng chứng** và **cầm tay chỉ việc** cho người dùng.
+Mỗi khẳng định kèm ảnh chụp nguồn khoanh đỏ đoạn trích và một dòng dịch; mỗi việc cần làm trên trình duyệt
+thì agent vẽ vòng đỏ ngay trên màn hình để người dùng tự bấm. Gói có 5 chế độ, người dùng gõ từ khoá trong
+chat để bật đúng chế độ cần:
+
+| Từ khoá | Chế độ | Người đọc nhận |
+| --- | --- | --- |
+| `suken-Story` | cốt truyện giải thích | **một link** tuyến truyện vẽ trên khung UI (trục thời gian, chuỗi nhân quả, so sánh, so số liệu, mâu thuẫn, chỗ hổng…), đi từng bước bằng ◀ ▶, ô nào cũng có 📷 mở ảnh nguồn |
+| `suken-Cite` | trích dẫn đơn lẻ | câu trả lời ngắn, mỗi ý kèm một link ảnh nguồn khoanh đỏ |
+| `suken-CodeStory` | cốt truyện code | một flow qua nhiều module kể thành tuyến truyện, mỗi bước một thẻ giải thích code |
+| `suken-Code` | thẻ code | một thẻ gom vị trí trong flow, class, hàm, thư viện, biến và giá trị thật lúc chạy, bằng màu, icon, sơ đồ |
+| `suken-Guide` / `suken-non_Guide` | cầm tay chỉ việc | vòng đỏ, mũi tên, 📋 dán, ⏎, 🔗 vẽ trên chính tab của mình; tự bấm từng bước, bấm sai thì bị chặn |
+
+Nguồn có thể là trang web (kể cả email, chat phải đăng nhập), PDF, Word, Excel, PowerPoint, CSV, ảnh, file
+code và file chữ (mở trong VS Code chạy trên trình duyệt).
+
+## Dùng thế nào
+
+Cài gói, rồi cài hook một lần trong thư mục mở Claude Code:
+
+```bash
+pip install suken-cite-guide
+suken-cite-guide setup        # cài hook, 2 reviewer, code-server; kiểm chrome-devtools
+```
+
+Từ đó, gõ từ khoá kèm yêu cầu trong chat, ví dụ `suken-Story vì sao run B chậm hơn run A?`. Hook đưa
+nguyên hướng dẫn của chế độ đó cho agent ngay trong lượt chat, agent không phải tự nhớ đọc. Riêng
+`suken-Guide` giữ tới khi gõ `suken-non_Guide`: trong lúc bật, hook chặn agent tự bấm, gõ, mở, đóng tab
+trên trình duyệt, chỉ người dùng tắt được.
+
+Không dùng hook (agent khác Claude Code): bảo agent chạy `suken-cite-guide usage` để chọn chế độ và đọc
+hướng dẫn. Mỗi hướng dẫn cùng một khung: luật vàng, checklist, review; agent chỉ giao kết quả khi reviewer
+chấm **ĐẠT**.
+
+## Các lệnh
+
+| Lệnh | Làm gì |
+| --- | --- |
+| `suken-cite-guide setup [--remove]` | cài hook cho 5 từ khoá (`.claude/settings.local.json`, giữ nguyên hook khác), 2 subagent reviewer (`.claude/agents/`), code-server (~220 MB vào cache); kiểm MCP chrome-devtools và cổng Chrome DevTools rồi báo thiếu gì. `--remove` gỡ hook và reviewer |
+| `suken-cite-guide usage [story\|cite\|codestory\|code\|guide\|renderer]` | in hướng dẫn của một chế độ (không kèm: in danh sách chế độ) |
+| `suken-cite-guide init --dir ./cites` | tạo thư mục dự án trích dẫn |
+| `suken-cite-guide serve --dir ./cites` | bật server xem ảnh, xem file (mặc định cổng 8123); `render/pdf.html?file=…&page=` và `render/open.html?file=…` mở thẳng PDF, Word, Excel, PowerPoint, CSV |
+| `suken-cite-guide text --file … \| --doc …` | in chữ của nguồn (pdf, docx, xlsx, pptx) để đọc nhanh trước khi chụp |
+| `suken-cite-guide add …` | thêm trích dẫn: ảnh chụp `--image` + `--box`, hoặc thẻ code `--explain <json>` — thiếu mục nào thì từ chối và nói rõ |
+| `suken-cite-guide skeleton --file … --lines …` | thẻ code: in khung JSON điền sẵn class, hàm, biến của các dòng code (Python) |
+| `suken-cite-guide story --template timeline\|argument` | in khung truyện; điền xong thì `story --id … --json …` kiểm và lưu |
+| `suken-cite-guide editor --folder …` | mở VS Code chạy trên trình duyệt (code-server); lần đầu tự tải ~220 MB vào cache |
+| `suken-cite-guide guide template` | in khung kịch bản cầm tay chỉ việc |
+| `suken-cite-guide guide run <kịch bản\|->` | kiểm kịch bản rồi vẽ vòng đỏ trên tab người dùng; mỗi lần cần agent (xong, lạc, bấm sai, tunnel…) in một dòng JSON kèm ảnh tab và tóm tắt trang |
+| `suken-cite-guide guide reattach [địa chỉ]` | gắn bộ điều khiển đang chạy vào kết nối Chrome mới (sau khi người dùng mở lại tunnel) |
+| `suken-cite-guide register`, `snapshot`, `urls` | ghi nguồn gốc file; lưu bản sao trang web (cách cũ); in link |
+| `suken-cite-guide check` | kiểm mọi trích dẫn và mọi truyện |
+
+Ví dụ một trích dẫn:
+
+```bash
+suken-cite-guide init --dir ./cites
+suken-cite-guide serve --dir ./cites &
+# agent mở nguồn trên Chrome, chụp màn hình vào ./cites/shots/price.png, rồi chỉ vùng cần khoanh:
+suken-cite-guide add --dir ./cites --id price --image ./cites/shots/price.png --box 120,340,860,372 \
+  --quote "Pears 2.40/kg" --section "prices.pdf · trang 3" --vi "Lê giá 2,40 mỗi kg."
+# link cho người đọc : http://127.0.0.1:8123/c.html?id=price
+```
+
+## Yêu cầu
+
+- Python 3.9+ (không cần thư viện Python nào khác; phần chạy trên trình duyệt đã đóng gói sẵn).
+- Chrome, và Claude Code có MCP server **chrome-devtools**; cầm tay chỉ việc dùng chung cổng DevTools đó
+  (mặc định `http://127.0.0.1:9222`).
+- Hook và từ khoá: Claude Code.
+- Nguồn phải đăng nhập (email, chat…): đăng nhập sẵn trên chính Chrome mà chrome-devtools điều khiển.
+- Linux hoặc macOS.
+
+## Giấy phép
+
+MIT. Các thư viện trình duyệt đi kèm và giấy phép của chúng nằm trong `THIRD_PARTY_NOTICES.md`.

suken_cite_guide-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,23 @@
+# Third-party notices
+
+`suken-cite-guide` ships pre-built browser bundles (`src/suken_cite_guide/static/dist/`) that include the
+following open-source libraries. License headers kept by the bundler are in `dist/*.LEGAL.txt`.
+
+| Library | Version | License | Source |
+| --- | --- | --- | --- |
+| @recogito/text-annotator | 4.3.7 | BSD-3-Clause | https://github.com/recogito/text-annotator-js |
+| pdfjs-dist (PDF.js) | 6.4.299 | Apache-2.0 | https://github.com/mozilla/pdf.js |
+| docx-preview | 0.4.1 | Apache-2.0 | https://github.com/VolodymyrBaydalka/docxjs |
+| @silurus/ooxml (xlsx, pptx viewer) | 0.88.0 | MIT | https://github.com/yukiyokotani/office-open-xml-viewer |
+| JSZip (used by docx-preview) | 3.10.2 | MIT (dual MIT / GPL-3.0; used under MIT) | https://github.com/Stuk/jszip |
+| highlight.js | 11.12.0 | BSD-3-Clause | https://github.com/highlightjs/highlight.js |
+
+## Not distributed
+
+`suken-cite-guide snapshot` downloads **SingleFile CLI** (AGPL-3.0,
+https://github.com/gildas-lormeau/single-file-cli) from its GitHub releases into your user cache the
+first time you run it. It is run as a separate program and is not included in this package.
+
+`suken-cite-guide editor` downloads **code-server** (MIT, https://github.com/coder/code-server) from its GitHub
+releases into your user cache the first time you run it, and checks its SHA-256. It is run as a separate
+program and is not included in this package.

suken_cite_guide-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "suken-cite-guide"
+version = "0.1.0"
+description = "Giải thích có bằng chứng (ảnh nguồn khoanh đỏ kèm dòng dịch, tuyến truyện trên khung UI, thẻ giải thích code) và cầm tay chỉ việc trên trình duyệt; 5 chế độ bật bằng từ khoá qua hook Claude Code."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
+authors = [{ name = "suken" }]
+keywords = ["citation", "screenshot", "highlight", "annotation", "llm", "claude-code"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Environment :: Console",
+    "Topic :: Text Processing",
+]
+dependencies = []
+
+[project.scripts]
+suken-cite-guide = "suken_cite_guide.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+suken_cite_guide = ["STORY.md", "CITE.md", "CODESTORY.md", "CODE.md", "GUIDE.md", "RENDERER.md", "agents/*.md", "static/*", "static/**/*"]

suken_cite_guide-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

suken_cite_guide-0.1.0/src/suken_cite_guide/CITE.md

@@ -0,0 +1,79 @@
+# suken-cite-guide — chế độ trích dẫn đơn lẻ (suken-Cite)
+
+**Việc của bạn:** user hỏi một câu. Bạn trả lời **ngắn bằng chữ**, mỗi ý quan trọng kèm **một link trích
+dẫn**: ảnh chụp đúng chỗ trong nguồn, đoạn trích khoanh đỏ, kèm một dòng dịch. Không dựng tuyến truyện.
+
+> ⚠️ User cần hiểu cả một chuỗi sự việc hay lập luận nhiều bước thì đó là chế độ cốt truyện:
+> `suken-cite-guide usage story`. Câu hỏi về code: `suken-cite-guide usage code`.
+
+## Luật vàng — không bao giờ được phá
+
+1. **Một khẳng định, một trích dẫn.** Câu nào nói điều nguồn khẳng định thì kèm link trích dẫn ngay sau.
+   Không có nguồn thì nói thẳng là nguồn không nói, không lấp bằng suy luận.
+2. **Khoanh đúng đoạn nói lên điều đó.** Đoạn trích phải nói đúng điều câu trả lời khẳng định, không mạnh
+   hơn.
+3. **Ít trích dẫn.** Mỗi trích dẫn chỉ khoanh đoạn user cần để tự kiểm câu trả lời.
+4. **Xong khi:** `suken-cite-guide check --dir ./cites` báo `OK` cho mọi trích dẫn bạn đưa user.
+
+## Quy trình — chép checklist này vào câu trả lời và đánh dấu dần
+
+```
+- [ ] 1. Chuẩn bị: init, serve
+- [ ] 2. Đọc nguồn, chọn những đoạn cần trích
+- [ ] 3. Mỗi đoạn: mở nguồn, chụp, thêm trích dẫn
+- [ ] 4. Chạy suken-cite-guide check --dir ./cites
+- [ ] 5. Trả lời: vài câu ngắn, mỗi ý kèm link cho người đọc
+```
+
+**1. Chuẩn bị** (đứng ở thư mục mà user mở Claude Code):
+
+```bash
+suken-cite-guide init --dir ./cites
+nohup suken-cite-guide serve --dir ./cites > ./cites/server.log 2>&1 &
+curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8123/c.html   # phải ra 200
+```
+
+Cổng 8123 đã bị dùng thì chọn cổng khác, và truyền cùng `--port` cho `serve` và `add`.
+
+**2. Đọc nguồn** (trang web: mở bằng chrome-devtools; file: `suken-cite-guide text --file <file>` đọc nhanh
+chữ của pdf, docx, xlsx, pptx).
+
+## Trích dẫn
+
+Mọi nguồn đi chung một đường: **mở → chụp màn hình → chỉ vùng khoanh**.
+
+1. **Mở nguồn** bằng chrome-devtools `new_page` (nhớ `pageId`):
+   - Trang web, email, chat (kể cả phải đăng nhập): mở link thật. Bấm mở rộng, cuộn tới khi đoạn cần
+     trích nằm trong màn hình.
+   - Code, file chữ (`.py`, `.md`, `.txt`, `.log`…): mở trong code-server
+     (`nohup suken-cite-guide editor --folder <thư mục user mở trong IDE> > ./cites/editor.log 2>&1 &`, rồi
+     `http://127.0.0.1:8125/?folder=<thư mục đó>`), cuộn tới đúng dòng. code-server dùng chung giữa các phiên: `curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8125/healthz` ra 200 thì dùng luôn, không bật thêm.
+   - File trên máy: chép vào `./cites/sources/`. PDF, ảnh mở thẳng `http://127.0.0.1:8123/sources/<file>`;
+     Word, Excel, PowerPoint, CSV mở `http://127.0.0.1:8123/render/open.html?file=sources/<file>` (thêm
+     `&slide=7`, `&sheet=Phase 1&cell=B14` hoặc `&row=9`).
+   - Luôn mở **đúng file gốc** user đưa, cấm tự đổi định dạng (xlsx → csv, pptx → pdf…). Tắt Chrome tự
+     dịch và Dark Reader nếu chúng đang đổi trang.
+2. **Chụp** `take_screenshot` (màn hình thường, không `fullPage`) với `filePath` là
+   `./cites/shots/<id>.png`, rồi `close_page` đúng `pageId` của bạn. Lấy kích thước ảnh:
+   `file ./cites/shots/<id>.png` (in ra `W x H`). Nhìn ảnh, tìm đoạn cần trích, ghi vùng bao quanh nó
+   `x0,y0,x1,y1` theo pixel của ảnh gốc, trong khoảng 0–W, 0–H. Ảnh hiển thị bị thu nhỏ thì đổi:
+   `x_gốc = x_hiển_thị × W ÷ rộng_hiển_thị`, `y_gốc = y_hiển_thị × H ÷ cao_hiển_thị`.
+3. **Thêm:**
+
+```bash
+suken-cite-guide add --dir ./cites --id <id> --image ./cites/shots/<id>.png --box x0,y0,x1,y1 \
+  --quote "<chữ trong vùng khoanh, nguyên văn>" --section "<nguồn · vị trí>" --vi "<dòng dịch>" \
+  --source-url "<link gốc, nếu có>"
+```
+
+`--vi`: 1–2 câu tiếng Việt, bản dịch, kèm lý do đoạn này quan trọng nếu cần. `add` in ra
+`link cho người đọc` — đó là link đưa user. `add` với một id đã có thì trích dẫn cũ bị thay.
+
+## Gỡ lỗi
+
+| Triệu chứng | Cách sửa |
+| --- | --- |
+| `c.html` báo trích dẫn không tồn tại | sai id, hoặc server đang phục vụ `--dir` khác |
+| `add` báo `--box` nằm ngoài ảnh | toạ độ phải trong 0–W, 0–H của ảnh gốc (`file <ảnh>` in ra `W x H`) |
+| code-server không mở được | xem `./cites/editor.log`; cổng 8125 bận thì `editor --port` khác |
+| Người đọc gặp lỗi kết nối | server đã tắt, hoặc cổng chưa được chuyển tiếp về máy người đọc |

suken_cite_guide-0.1.0/src/suken_cite_guide/CODE.md

@@ -0,0 +1,86 @@
+# suken-cite-guide — chế độ thẻ code (suken-Code)
+
+Bạn trả lời bằng **thẻ giải thích code**: một trang ảnh gom 6 mục (vị trí trong flow, class, hàm, thư
+viện, biến, giá trị thật lúc chạy) bằng màu, icon, sơ đồ. **Chi tiết nằm trong thẻ, không nằm trong chữ.**
+
+> ⚠️ Ở đây chỉ giao **1 thẻ = 1 link**. Trả lời = link thẻ + 1 câu. User hỏi **một flow qua nhiều module /
+> nhiều nút trong sơ đồ flow** thì đó là chế độ cốt truyện code: `suken-cite-guide usage codestory`.
+
+## Chọn loại thẻ
+
+| Loại thẻ | Khi nào |
+| --- | --- |
+| **Thẻ đơn** (mặc định) | Hàm được gọi vẽ thành **hộp đen** (nhận gì, làm gì, trả gì). Không có `steps`, `calls`, `defs` |
+| **Thẻ nhiều đoạn** | User chỉ ra nhiều đoạn, hoặc không mở hàm được gọi thì không hiểu được → thêm `steps`, tối đa 4 đoạn. Vẫn **1 link**, user tự tua ◀ ▶ (mục *Thẻ nhiều đoạn*) |
+
+## ⛔ CẤM
+
+1. **Cấm ảnh code thường** (kể cả ảnh chụp code-server) và **cấm trích trang web, tài liệu thư viện**. Chỉ dùng thẻ `code-explain`.
+2. **Cấm vượt phạm vi câu hỏi:** không lần sang module/backend/framework mà câu hỏi không cần.
+3. **Cấm bịa giá trị.** Không ghi `value` (giá trị thật lúc chạy) nếu chưa thấy trong log hoặc chưa chạy lại
+   bằng lệnh chỉ đọc (không ghi file, không gọi dịch vụ ngoài); không có thì để `""`. `output` là hàm trả về
+   gì, dạng chữ: luôn điền.
+
+## Quy trình
+
+Đứng ở thư mục mà user mở Claude Code.
+
+```
+- [ ] 1. Chọn loại thẻ (bảng trên)
+- [ ] 2. suken-cite-guide init --dir ./cites
+        nohup suken-cite-guide serve --dir ./cites > ./cites/server.log 2>&1 &
+- [ ] 3. suken-cite-guide skeleton --file <file> --lines <a-b> > <id>.json   ← khung điền sẵn class, hàm, tham số, biến
+        Chỉ dựng được khung cho file .py. File khác: dừng và báo user rằng thẻ code chưa hỗ trợ ngôn ngữ đó.
+- [ ] 4. Điền các ô trong <id>.json (mục Điền khung)
+- [ ] 5. suken-cite-guide add --dir ./cites --id <id> --file <file> --explain <id>.json --section "…" --vi "<1 câu>"
+        add báo thiếu gì → điền tiếp → chạy lại, tới khi lưu được
+- [ ] 6. Chụp thẻ: new_page tới dòng "trang cần chụp" mà add in ra (nhớ pageId), take_screenshot với filePath là dòng
+        "lưu ảnh vào", rồi close_page đúng pageId. Nhìn ảnh: sai vòng khoanh hay nhãn → sửa <id>.json, add lại, chụp lại
+- [ ] 7. Gọi subagent suken-guide-code-review (đưa: câu hỏi gốc, link thẻ sẽ đưa user, loại thẻ, ./cites, nguồn của giá trị lúc chạy) → sửa tới khi ĐẠT
+- [ ] 8. Đưa user đúng dòng `link cho người đọc` mà add in ra
+```
+
+Cổng 8123 bận thì dùng cổng khác, truyền cùng `--port` cho `serve` và `add`.
+
+## Điền khung
+
+**Thuật ngữ:** *vòng khoanh* là các dòng được hỏi (`focus` của thẻ đơn, `lines` của từng đoạn). `show` là các
+dòng hiện thêm quanh vòng khoanh để xem. Chữ = từ tách bởi khoảng trắng.
+**Biểu tượng trên thẻ:** 🏛 class có hàm · 📋 class dữ liệu (dataclass, NamedTuple, model DB) · 📦 hàm/class thư viện.
+
+Sau `skeleton`, điền các ô sau; ô không nhắc tới thì giữ nguyên.
+
+| Ô | Điền gì |
+| --- | --- |
+| `question` | câu người mới chắc chắn sẽ hỏi về vòng khoanh (thường là *vì sao đoạn này đúng / làm được việc đó*). **Chỉ để bạn tự biết phải trả lời gì, không hiện trên thẻ** |
+| nhãn `"answer": true` | câu trả lời cho `question`, gắn vào **chữ then chốt** trong vòng khoanh, `from` trỏ tới dòng chứa lời giải (vd `rev-parse` → `↖ main = dòng 35`). Chữ then chốt nằm trong chuỗi (lệnh git/shell, SQL) thì tự thêm nhãn, `kind: "library"` |
+| `kind: "unknown"` | đổi thành `function` (hàm của dự án — thêm hộp vào `machine`) hoặc `library` |
+| `label` của nhãn | làm gì, 2–4 chữ (tối đa 6). **Hàm/class thư viện (📦): nói rõ vai trò bằng chính tên những thứ đã có trên thẻ**, tối đa 14 chữ — vd `gói câu hỏi + câu trả lời + đáp án thành 1 ca chấm`, không phải `gói 3 thứ để chấm` |
+| `from` | tạo ra ở đâu (khung đã gợi ý) |
+| `inputs[].label` | giá trị truyền vào là một biến chưa có nhãn (vd `r`) → ghi nó là gì (vd `1 hàng CSV`) |
+| `machine[]` (hộp hàm) | `does`: làm gì, vài chữ. `output`: **bắt buộc**, hàm trả về gì, dạng chữ (vd `danh sách câu hỏi`). `value`: giá trị thật lúc chạy, không có thì `""` |
+| `machine[].owner` | khung tự điền khi hàm là hàm của một class → hộp hàm được lồng vào hộp class đó. Hàm thư viện không có hộp |
+| `machine[].then` | kết quả hàm được dùng tiếp ngay (vd `.close()`): `{name, does}` |
+| `classBox` class có hàm (🏛) | `does` + `does` của từng hàm; hàm được gọi trong vòng khoanh thì thêm `"called": true` |
+| `classBox` class dữ liệu (📋) | `does` + `does` của từng trường trong `fields` |
+| `classBox` `guess` | mục đích class là bạn suy ra, không từ docstring → `"guess": true` (thẻ hiện "≈ suy ra từ code") |
+| `map` | sơ đồ flow của dự án (README, docs, specs…): `{"label": "…", "nodes": ["…"], "here": <số thứ tự nút đang ở, từ 0>}`. Không tìm thấy → **hỏi user**; user xác nhận không có → `"map": "không có"` |
+
+Khung chỉ có các dòng được hỏi; muốn hiện thêm dòng xung quanh thì mở rộng `show` (dòng thêm chỉ để xem,
+**không gắn nhãn** — nhãn chỉ nằm trong vòng khoanh).
+
+## Thẻ nhiều đoạn
+
+Chạy `skeleton` cho từng đoạn rồi gộp vào một file. Thêm `show` gồm mọi đoạn, `defs` = các đoạn định
+nghĩa hàm được mở, `machine` lồng bằng `calls` (A gọi B), và `steps` (mỗi phần tử là một đoạn):
+
+```json
+"steps": [
+  { "label": "dòng 51–52 · trong main", "lines": [[51, 52]], "lit": ["0"], "question": "…" },
+  { "label": "dòng 17–19 · trong A", "lines": [[17, 19]], "lit": ["1", "0:head", "0:out"], "question": "…" }
+]
+```
+
+Mỗi đoạn một `question` và một nhãn `answer` trong dòng của đoạn đó. `lit` = phần sơ đồ được sáng: `"1"`
+cả hộp cấp 1; `"1:in"`, `"1:head"`, `"1:out"` từng phần (cấp 0 = hộp ngoài cùng). Muốn tự nhìn từng
+đoạn thì mở `trang cần chụp` thêm `&step=N`.

suken_cite_guide-0.1.0/src/suken_cite_guide/CODESTORY.md

@@ -0,0 +1,116 @@
+# suken-cite-guide — chế độ cốt truyện code (suken-CodeStory)
+
+Bạn trả lời một câu hỏi về **flow qua nhiều module / nhiều nút trong sơ đồ flow** bằng **tuyến truyện trên
+khung UI**. Mỗi bước truyện = 1 nút flow = 1 `headline` + 1 **thẻ giải thích code** (một trang ảnh gom 6
+mục: vị trí trong flow, class, hàm, thư viện, biến, giá trị thật lúc chạy). **Chi tiết nằm trong thẻ, không
+nằm trong chữ.** Khi chọn dòng code cho mỗi thẻ: giá trị nào được dùng cũng phải thấy nó từ đâu ra, trong cùng
+vòng khoanh hoặc ở bước trước.
+
+> ⚠️ User chỉ hỏi **vài dòng code** thì đó là chế độ thẻ code: `suken-cite-guide usage code`.
+
+## Chọn loại thẻ cho mỗi bước truyện
+
+| Loại thẻ | Khi nào |
+| --- | --- |
+| **Thẻ đơn** (mặc định) | Hàm được gọi vẽ thành **hộp đen** (nhận gì, làm gì, trả gì). Không có `steps`, `calls`, `defs` |
+| **Thẻ nhiều đoạn** | Trong bước đó cần xem nhiều đoạn, hoặc không mở hàm được gọi thì không hiểu được → thêm `steps`, tối đa 4 đoạn; người đọc tua ◀ ▶ trong thẻ (mục *Thẻ nhiều đoạn*) |
+
+## ⛔ CẤM
+
+1. **Cấm ảnh code thường** (kể cả ảnh chụp code-server) và **cấm trích trang web, tài liệu thư viện**. Chỉ dùng thẻ `code-explain`.
+2. **Cấm vượt phạm vi câu hỏi:** không lần sang module/backend/framework mà câu hỏi không cần.
+3. **Cấm bịa giá trị.** Không ghi `value` (giá trị thật lúc chạy) nếu chưa thấy trong log hoặc chưa chạy lại
+   bằng lệnh chỉ đọc (không ghi file, không gọi dịch vụ ngoài); không có thì để `""`. `output` là hàm trả về
+   gì, dạng chữ: luôn điền.
+
+## Quy trình
+
+Đứng ở thư mục mà user mở Claude Code.
+
+```
+- [ ] 1. Chọn các nút flow (mỗi nút 1 bước truyện) + loại thẻ cho mỗi bước (bảng trên)
+- [ ] 2. suken-cite-guide init --dir ./cites
+        nohup suken-cite-guide serve --dir ./cites > ./cites/server.log 2>&1 &
+- [ ] 3. Với từng thẻ, làm 3a–3d:
+   3a. suken-cite-guide skeleton --file <file> --lines <a-b> > <id>.json   ← khung điền sẵn class, hàm, tham số, biến
+       Chỉ dựng được khung cho file .py. File khác: dừng và báo user rằng thẻ code chưa hỗ trợ ngôn ngữ đó.
+   3b. Điền các ô trong <id>.json (mục Điền khung)
+   3c. suken-cite-guide add --dir ./cites --id <id> --file <file> --explain <id>.json --section "…" --vi "<1 câu>"
+       add báo thiếu gì → điền tiếp → chạy lại, tới khi lưu được
+   3d. Chụp thẻ: new_page tới dòng "trang cần chụp" mà add in ra (nhớ pageId), take_screenshot với filePath là dòng
+       "lưu ảnh vào", rồi close_page đúng pageId. Nhìn ảnh: sai vòng khoanh hay nhãn → sửa, add lại, chụp lại
+- [ ] 4. Điền khung truyện, chạy suken-cite-guide story tới khi lưu được (mục Tuyến truyện)
+- [ ] 5. Gọi subagent suken-guide-code-review (đưa: câu hỏi gốc, link của mọi thẻ, id truyện, loại thẻ, ./cites, nguồn của giá trị lúc chạy) → sửa tới khi ĐẠT
+- [ ] 6. Đưa user đúng dòng `link cho người đọc` mà story in ra
+```
+
+Cổng 8123 bận thì dùng cổng khác, truyền cùng `--port` cho `serve`, `add` và `story`.
+
+## Điền khung
+
+**Thuật ngữ:** *vòng khoanh* là các dòng được hỏi (`focus` của thẻ đơn, `lines` của từng đoạn). `show` là các
+dòng hiện thêm quanh vòng khoanh để xem. Chữ = từ tách bởi khoảng trắng.
+**Biểu tượng trên thẻ:** 🏛 class có hàm · 📋 class dữ liệu (dataclass, NamedTuple, model DB) · 📦 hàm/class thư viện.
+
+Sau `skeleton`, điền các ô sau; ô không nhắc tới thì giữ nguyên.
+
+| Ô | Điền gì |
+| --- | --- |
+| `question` | câu người mới chắc chắn sẽ hỏi về vòng khoanh (thường là *vì sao đoạn này đúng / làm được việc đó*). **Chỉ để bạn tự biết phải trả lời gì, không hiện trên thẻ** |
+| nhãn `"answer": true` | câu trả lời cho `question`, gắn vào **chữ then chốt** trong vòng khoanh, `from` trỏ tới dòng chứa lời giải (vd `rev-parse` → `↖ main = dòng 35`). Chữ then chốt nằm trong chuỗi (lệnh git/shell, SQL) thì tự thêm nhãn, `kind: "library"` |
+| `kind: "unknown"` | đổi thành `function` (hàm của dự án — thêm hộp vào `machine`) hoặc `library` |
+| `label` của nhãn | làm gì, 2–4 chữ (tối đa 6). **Hàm/class thư viện (📦): nói rõ vai trò bằng chính tên những thứ đã có trên thẻ**, tối đa 14 chữ — vd `gói câu hỏi + câu trả lời + đáp án thành 1 ca chấm`, không phải `gói 3 thứ để chấm` |
+| `from` | tạo ra ở đâu (khung đã gợi ý) |
+| `inputs[].label` | giá trị truyền vào là một biến chưa có nhãn (vd `r`) → ghi nó là gì (vd `1 hàng CSV`) |
+| `machine[]` (hộp hàm) | `does`: làm gì, vài chữ. `output`: **bắt buộc**, hàm trả về gì, dạng chữ (vd `danh sách câu hỏi`). `value`: giá trị thật lúc chạy, không có thì `""` |
+| `machine[].owner` | khung tự điền khi hàm là hàm của một class → hộp hàm được lồng vào hộp class đó. Hàm thư viện không có hộp |
+| `machine[].then` | kết quả hàm được dùng tiếp ngay (vd `.close()`): `{name, does}` |
+| `classBox` class có hàm (🏛) | `does` + `does` của từng hàm; hàm được gọi trong vòng khoanh thì thêm `"called": true` |
+| `classBox` class dữ liệu (📋) | `does` + `does` của từng trường trong `fields` |
+| `classBox` `guess` | mục đích class là bạn suy ra, không từ docstring → `"guess": true` (thẻ hiện "≈ suy ra từ code") |
+| `map` | sơ đồ flow của dự án (README, docs, specs…): `{"label": "…", "nodes": ["…"], "here": <số thứ tự nút đang ở, từ 0>}`. Không tìm thấy → **hỏi user**; user xác nhận không có → `"map": "không có"` |
+
+Khung chỉ có các dòng được hỏi; muốn hiện thêm dòng xung quanh thì mở rộng `show` (dòng thêm chỉ để xem,
+**không gắn nhãn** — nhãn chỉ nằm trong vòng khoanh).
+
+## Thẻ nhiều đoạn
+
+Chạy `skeleton` cho từng đoạn rồi gộp vào một file. Thêm `show` gồm mọi đoạn, `defs` = các đoạn định
+nghĩa hàm được mở, `machine` lồng bằng `calls` (A gọi B), và `steps` (mỗi phần tử là một đoạn):
+
+```json
+"steps": [
+  { "label": "dòng 51–52 · trong main", "lines": [[51, 52]], "lit": ["0"], "question": "…" },
+  { "label": "dòng 17–19 · trong A", "lines": [[17, 19]], "lit": ["1", "0:head", "0:out"], "question": "…" }
+]
+```
+
+Mỗi đoạn một `question` và một nhãn `answer` trong dòng của đoạn đó. `lit` = phần sơ đồ được sáng: `"1"`
+cả hộp cấp 1; `"1:in"`, `"1:head"`, `"1:out"` từng phần (cấp 0 = hộp ngoài cùng). Muốn tự nhìn từng
+đoạn thì mở `trang cần chụp` thêm `&step=N`.
+
+## Tuyến truyện
+
+**Xương sống:** `argument`, chuỗi nhân quả theo thứ tự code chạy. Mỗi `cite` trong khung truyện là id một thẻ.
+Từ bước 2, `link` là chữ nối với bước trước (nên | vì | nhưng | rồi | để | vì vậy); bước 1 không có `link`.
+
+**Mỗi bước** có `headline` (tối đa 16 chữ, một câu "vậy thì sao", không phải câu tả ảnh) và `cards`
+(`{label ≤8 chữ, cite}`), thêm tối đa 3 khối trong `blocks` khi cần:
+
+| Khối | Dùng khi | Điền |
+| --- | --- | --- |
+| `conflict` | hai nguồn nói khác | `left`/`right`: `{who ≤3 chữ, cite}`; `rows` ≥1 hàng `{left, right}`, mỗi bên ≤6 chữ |
+| `compare` | so phương án | `columns` 2–4 tên ≤4 chữ; `rows`: `{label ≤5 chữ, cells}`, mỗi ô `text` ≤6 chữ hoặc `mark` (yes/no) |
+| `bars` | so con số | `groups`: `{label ≤6 chữ, items}`; mỗi nhóm ≥2 `items`: `{label ≤4 chữ, value > 0, text ≤3 chữ, cite}` |
+| `status` | chưa chốt / đang chờ / đã chốt | `items`: `{label ≤8 chữ, state: open \| wait \| done, note ≤3 chữ (tuỳ chọn), cite}` |
+| `gap` | nguồn không nói | `text` ≤12 chữ; **khối** không có `cite`. `need` tuỳ chọn `{label ≤8 chữ, cite}`: ai cần điều đó, kèm nguồn nói vậy |
+| `ref` | nhắc lại một bước trước | `step` (số thứ tự bước trước, từ 1), `label` ≤8 chữ, `cite` |
+| `funnel` | lọc dần còn ít | `stages` ≥3 `{label ≤6 chữ, cite}`; `here` = số tầng đang ở, từ 1 |
+
+```bash
+suken-cite-guide story --template argument > story.json     # khung mẫu có sẵn đủ các khối: xoá khối không dùng
+suken-cite-guide story --dir ./cites --id <id-truyện> --json story.json
+```
+
+Lệnh chỉ rõ ô nào thiếu hoặc quá dài, và chỉ lưu khi đủ; lưu xong in `link cho người đọc` — link duy
+nhất đưa user. Truyện tối đa 20 bước.