repowiki-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repowiki-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: Deterministic repo wiki build system, driven by any coding agent. Output language follows the repository (zh/en).
 Author: luomsis
 License-Expression: MIT
@@ -54,20 +54,27 @@ Wiki 产出语言自动跟随目标仓库（中文仓库 → `zh/`，英文仓
 
 ## 为什么是 repowiki
 
-给仓库生成 wiki 的现成方案主要有两条路：云端 AI wiki 服务（代码要上传、按量付费、产出是黑盒），
-或者让一个 agent 直接通读仓库现写（大仓库上下文装不下、中断即前功尽弃、难以并行）。
-repowiki 走第三条路：**读代码、写 wiki 的智能留给任意 agent，其余一切——任务规划、原子认领、
-产出校验、自动修复、断点续跑——做成确定性构建系统。**
-
-| | 云端 AI wiki 服务 | 让 agent 直接读仓库 | repowiki |
-|---|---|---|---|
-| 智能来源 | 内置 LLM（不可换） | 你的 agent（任选） | 你的 agent（任选） |
-| 代码出域 | 是 | 否 | 否 |
-| API Key / 网络 | 需要 | 视 agent 而定 | repowiki 本身零依赖 |
-| 大仓库 | 受服务方配额限制 | 上下文装不下 | 任务切分，逐页生成 |
-| 中断 / 崩溃 | — | 从头再来 | 状态落盘，断点续跑 |
-| 并行加速 | — | 难协调 | 多 worker 原子认领，天然并行 |
-| 产出质量 | 黑盒 | 靠 agent 自觉 | 模板强制 + 程序化校验 + 自动修复 |
+给仓库生成 wiki 的现成方案不少，但各有各的锁：
+DeepWiki 一类**云端 AI wiki 服务**，代码要上传出域、按服务付费、产出是黑盒；
+Qoder Repo Wiki、ZCode 仓库 Wiki 一类**IDE / 工具内置能力**，好用但锁在单一工具生态——
+生成计费（Credits / token）、wiki 或存于本机用户目录（难以进 CI、无版本历史）或依赖厂商平台、
+大仓库受限（如 Qoder 单项目上限 1 万文件）；或者让一个 agent 直接通读仓库现写
+（大仓库上下文装不下、中断即前功尽弃、难以并行）。
+repowiki 走另一条路：**读代码、写 wiki 的智能留给任意 agent，其余一切——任务规划、原子认领、
+产出校验、自动修复、断点续跑——做成确定性构建系统。**wiki 以 markdown + mermaid + 源码引用
+形态进你的仓库（wiki-as-code），可评审、可增量更新、可被 CI 门禁拦截过期。
+
+| | 云端 AI wiki 服务 | IDE / 工具内置（Qoder、ZCode 等） | 让 agent 直接读仓库 | repowiki |
+|---|---|---|---|---|
+| 智能来源 | 内置 LLM（不可换） | 工具绑定的模型服务 | 你的 agent（任选） | 你的 agent（任选） |
+| 代码出域 | 是（上传托管平台） | 上下文发给所选模型服务 | 否 | 否 |
+| 费用 | 按服务付费 | Credits / token 计费 | 视 agent 而定 | repowiki 本身零成本 |
+| wiki 归属 | 厂商平台 | 本机用户目录或 `.qoder/` 等，不入库/弱入库 | 一次性产物 | 你的仓库（wiki-as-code）+ 离线站点 |
+| CI 门禁 / 增量 | — | 工具内自动刷新为主，无独立门禁 | — | `stale --fail-if-stale` 拦截过期 PR，`update` 按 git diff 增量 |
+| 大仓库 | 受服务方配额限制 | 有上限（如 Qoder 1 万文件） | 上下文装不下 | 任务切分，逐页生成 |
+| 中断 / 崩溃 | — | 工具内闭环 | 从头再来 | 状态落盘，断点续跑 |
+| 并行加速 | — | — | 难协调 | 多 worker 原子认领，天然并行 |
+| 产出质量 | 黑盒 | 工具内闭环，无程序化校验 | 靠 agent 自觉 | 模板强制 + 程序化校验 + 自动修复 |
 
 一句话：**agent 负责聪明，repowiki 负责靠谱。**
 
@@ -79,7 +86,7 @@ repowiki 走第三条路：**读代码、写 wiki 的智能留给任意 agent，
 - **单文件离线站点 + agent 索引**：`site` 产出约 5 MB 自包含 HTML（导航、搜索、mermaid、源码弹层，双击即看），同时导出 `llms.txt` / `llms-full.txt`（[llmstxt.org](https://llmstxt.org/) 约定），任何 agent / IDE 按索引直接读，无需 MCP；
 - **强校验，自动修复**：模板强制 + 程序化校验；锚点 / 行号 / H1 / 路径分隔符自动修复，只有语义缺陷才判失败；
 - **双语产出，跨平台**：语言自动跟随目标仓库（zh / en）；macOS / Linux / Windows 原生支持（无需 WSL），CI 三平台 × Python 3.10-3.13 矩阵回归；
-- **知识卡片与页面原型**：机制卡片 / 模块文档，类别可整表自定义（`--categories`）；页面按主题选 module（结构型，默认）/ flow（流程型）两种模板。
+- **知识卡片与页面原型**：机制卡片 / 模块文档，类别可整表自定义（`--categories`）；页面按主题选六种原型模板：module 结构型（默认）/ flow 流程型 / layer 分层型 / data 数据模型型 / api 接口型 / event 事件型。
 
 ## 目录
 
@@ -138,8 +145,9 @@ repowiki skill status                   # 查看已装版本、是否过期
 - 幂等可重跑：finalize、update 或手动改了页面之后随时重新执行 `repowiki site` 重建；
 - 执行过 `repowiki clean` 也能重建（此时章节顺序退化为目录序，内容不受影响）。
 
-页面按 **module（结构型，默认）/ flow（流程型）** 两种原型撰写，模板与文风规范由校验器
-按语言强制；每节末尾「Section sources/章节来源」、每图后「Diagram sources/图表来源」，
+页面按 **module 结构型（默认）/ flow 流程型 / layer 分层型 / data 数据模型型 / api 接口型 /
+event 事件型** 六种原型撰写，规划时按页面主题选择（无法确认时回退 module），模板与文风规范由
+校验器按语言强制；每节末尾「Section sources/章节来源」、每图后「Diagram sources/图表来源」，
 引用格式 `[path:Lx-Ly](file://path#Lx-Ly)`，页间零链接（正因如此所有页面任务可完全并行）。
 完整小节结构见 [docs/zh/USAGE.md](docs/zh/USAGE.md)。
 

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/README.md

@@ -24,20 +24,27 @@ Wiki 产出语言自动跟随目标仓库（中文仓库 → `zh/`，英文仓
 
 ## 为什么是 repowiki
 
-给仓库生成 wiki 的现成方案主要有两条路：云端 AI wiki 服务（代码要上传、按量付费、产出是黑盒），
-或者让一个 agent 直接通读仓库现写（大仓库上下文装不下、中断即前功尽弃、难以并行）。
-repowiki 走第三条路：**读代码、写 wiki 的智能留给任意 agent，其余一切——任务规划、原子认领、
-产出校验、自动修复、断点续跑——做成确定性构建系统。**
-
-| | 云端 AI wiki 服务 | 让 agent 直接读仓库 | repowiki |
-|---|---|---|---|
-| 智能来源 | 内置 LLM（不可换） | 你的 agent（任选） | 你的 agent（任选） |
-| 代码出域 | 是 | 否 | 否 |
-| API Key / 网络 | 需要 | 视 agent 而定 | repowiki 本身零依赖 |
-| 大仓库 | 受服务方配额限制 | 上下文装不下 | 任务切分，逐页生成 |
-| 中断 / 崩溃 | — | 从头再来 | 状态落盘，断点续跑 |
-| 并行加速 | — | 难协调 | 多 worker 原子认领，天然并行 |
-| 产出质量 | 黑盒 | 靠 agent 自觉 | 模板强制 + 程序化校验 + 自动修复 |
+给仓库生成 wiki 的现成方案不少，但各有各的锁：
+DeepWiki 一类**云端 AI wiki 服务**，代码要上传出域、按服务付费、产出是黑盒；
+Qoder Repo Wiki、ZCode 仓库 Wiki 一类**IDE / 工具内置能力**，好用但锁在单一工具生态——
+生成计费（Credits / token）、wiki 或存于本机用户目录（难以进 CI、无版本历史）或依赖厂商平台、
+大仓库受限（如 Qoder 单项目上限 1 万文件）；或者让一个 agent 直接通读仓库现写
+（大仓库上下文装不下、中断即前功尽弃、难以并行）。
+repowiki 走另一条路：**读代码、写 wiki 的智能留给任意 agent，其余一切——任务规划、原子认领、
+产出校验、自动修复、断点续跑——做成确定性构建系统。**wiki 以 markdown + mermaid + 源码引用
+形态进你的仓库（wiki-as-code），可评审、可增量更新、可被 CI 门禁拦截过期。
+
+| | 云端 AI wiki 服务 | IDE / 工具内置（Qoder、ZCode 等） | 让 agent 直接读仓库 | repowiki |
+|---|---|---|---|---|
+| 智能来源 | 内置 LLM（不可换） | 工具绑定的模型服务 | 你的 agent（任选） | 你的 agent（任选） |
+| 代码出域 | 是（上传托管平台） | 上下文发给所选模型服务 | 否 | 否 |
+| 费用 | 按服务付费 | Credits / token 计费 | 视 agent 而定 | repowiki 本身零成本 |
+| wiki 归属 | 厂商平台 | 本机用户目录或 `.qoder/` 等，不入库/弱入库 | 一次性产物 | 你的仓库（wiki-as-code）+ 离线站点 |
+| CI 门禁 / 增量 | — | 工具内自动刷新为主，无独立门禁 | — | `stale --fail-if-stale` 拦截过期 PR，`update` 按 git diff 增量 |
+| 大仓库 | 受服务方配额限制 | 有上限（如 Qoder 1 万文件） | 上下文装不下 | 任务切分，逐页生成 |
+| 中断 / 崩溃 | — | 工具内闭环 | 从头再来 | 状态落盘，断点续跑 |
+| 并行加速 | — | — | 难协调 | 多 worker 原子认领，天然并行 |
+| 产出质量 | 黑盒 | 工具内闭环，无程序化校验 | 靠 agent 自觉 | 模板强制 + 程序化校验 + 自动修复 |
 
 一句话：**agent 负责聪明，repowiki 负责靠谱。**
 
@@ -49,7 +56,7 @@ repowiki 走第三条路：**读代码、写 wiki 的智能留给任意 agent，
 - **单文件离线站点 + agent 索引**：`site` 产出约 5 MB 自包含 HTML（导航、搜索、mermaid、源码弹层，双击即看），同时导出 `llms.txt` / `llms-full.txt`（[llmstxt.org](https://llmstxt.org/) 约定），任何 agent / IDE 按索引直接读，无需 MCP；
 - **强校验，自动修复**：模板强制 + 程序化校验；锚点 / 行号 / H1 / 路径分隔符自动修复，只有语义缺陷才判失败；
 - **双语产出，跨平台**：语言自动跟随目标仓库（zh / en）；macOS / Linux / Windows 原生支持（无需 WSL），CI 三平台 × Python 3.10-3.13 矩阵回归；
-- **知识卡片与页面原型**：机制卡片 / 模块文档，类别可整表自定义（`--categories`）；页面按主题选 module（结构型，默认）/ flow（流程型）两种模板。
+- **知识卡片与页面原型**：机制卡片 / 模块文档，类别可整表自定义（`--categories`）；页面按主题选六种原型模板：module 结构型（默认）/ flow 流程型 / layer 分层型 / data 数据模型型 / api 接口型 / event 事件型。
 
 ## 目录
 
@@ -108,8 +115,9 @@ repowiki skill status                   # 查看已装版本、是否过期
 - 幂等可重跑：finalize、update 或手动改了页面之后随时重新执行 `repowiki site` 重建；
 - 执行过 `repowiki clean` 也能重建（此时章节顺序退化为目录序，内容不受影响）。
 
-页面按 **module（结构型，默认）/ flow（流程型）** 两种原型撰写，模板与文风规范由校验器
-按语言强制；每节末尾「Section sources/章节来源」、每图后「Diagram sources/图表来源」，
+页面按 **module 结构型（默认）/ flow 流程型 / layer 分层型 / data 数据模型型 / api 接口型 /
+event 事件型** 六种原型撰写，规划时按页面主题选择（无法确认时回退 module），模板与文风规范由
+校验器按语言强制；每节末尾「Section sources/章节来源」、每图后「Diagram sources/图表来源」，
 引用格式 `[path:Lx-Ly](file://path#Lx-Ly)`，页间零链接（正因如此所有页面任务可完全并行）。
 完整小节结构见 [docs/zh/USAGE.md](docs/zh/USAGE.md)。
 

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "repowiki-cli"
-version = "0.7.0"
+version = "0.8.0"
 description = "Deterministic repo wiki build system, driven by any coding agent. Output language follows the repository (zh/en)."
 readme = "README.md"
 requires-python = ">=3.10"

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/src/repowiki/catalog.py

@@ -16,7 +16,7 @@ from .validate import PLACEHOLDER_RE
 
 SLUG_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
 MAX_DEPTH = 4  # root chapters are depth 1
-ARCHETYPES = ("module", "flow")  # page templates; default "module"
+ARCHETYPES = ("module", "flow", "layer", "data", "api", "event")  # page templates; default "module"
 
 
 @dataclass
@@ -31,7 +31,7 @@ class FlatNode:
     parent_id: str | None
     depth: int
     output: str  # relative to .repowiki/, e.g. zh/content/Overview/Overview.md
-    archetype: str = "module"  # page template shape: "module" | "flow"
+    archetype: str = "module"  # page template shape, one of ARCHETYPES
 
     def chapter_path(self, by_id: dict[str, "FlatNode"]) -> str:
         parts = [self.title]
@@ -107,7 +107,7 @@ def validate_catalog(data, known_paths: set[str]) -> tuple[list[str], list[str]]
             archetype = node.get("archetype", "module")
             if archetype not in ARCHETYPES:
                 errors.append(
-                    f"{where}（{title or nid}）: archetype 必须是 module 或 flow（可省略，默认 module），得到 {archetype!r}"
+                    f"{where}（{title or nid}）: archetype 必须是 {'/'.join(ARCHETYPES)} 之一（可省略，默认 module），得到 {archetype!r}"
                 )
                 archetype = "module"
             brief = node.get("page_brief")

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/src/repowiki/dispatch.py

@@ -11,7 +11,7 @@ import json
 import os
 import socket
 
-from .catalog import flatten, validate_catalog
+from .catalog import ARCHETYPES, flatten, validate_catalog
 from .errors import ConflictError, UsageError
 from .output import emit
 from .paths import WikiPaths
@@ -274,7 +274,7 @@ def _node_archetype(paths: WikiPaths, node_id: str) -> str:
         if not isinstance(n, dict):
             continue
         if n.get("id") == node_id:
-            return n.get("archetype") if n.get("archetype") in ("module", "flow") else "module"
+            return n.get("archetype") if n.get("archetype") in ARCHETYPES else "module"
         stack.extend(n.get("children") or [])
     return "module"
 

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/src/repowiki/i18n.py

@@ -42,8 +42,48 @@ STRINGS: dict[str, dict] = {
             ("故障", "prefix"),
             ("结论", "exact"),
         ],
+        "layer_sections": [
+            ("简介", "exact"),
+            ("分层总览", "exact"),
+            ("各层职责", "exact"),
+            ("层间依赖与调用规则", "exact"),
+            ("纵向切片", "prefix"),
+            ("横切关注点", "exact"),
+            ("故障", "prefix"),
+            ("结论", "exact"),
+        ],
+        "data_sections": [
+            ("简介", "exact"),
+            ("数据模型总览", "exact"),
+            ("核心实体分析", "exact"),
+            ("状态机", "exact"),
+            ("存储与序列化", "exact"),
+            ("数据生命周期", "exact"),
+            ("故障", "prefix"),
+            ("结论", "exact"),
+        ],
+        "api_sections": [
+            ("简介", "exact"),
+            ("接口清单与分组", "exact"),
+            ("请求处理时序", "exact"),
+            ("接口契约与错误码", "exact"),
+            ("鉴权与访问控制", "exact"),
+            ("配额", "prefix"),
+            ("故障", "prefix"),
+            ("结论", "exact"),
+        ],
+        "event_sections": [
+            ("简介", "exact"),
+            ("事件清单", "exact"),
+            ("事件流拓扑", "exact"),
+            ("事件契约", "exact"),
+            ("消费端处理", "exact"),
+            ("可靠性保障", "exact"),
+            ("故障", "prefix"),
+            ("结论", "exact"),
+        ],
         "overview_h1_suffix": "Wiki 总览",
-        "overview_sections": ("章节导航", "如何使用本 Wiki"),
+        "overview_sections": ("章节导航", "如何使用本 Wiki", "术语表"),
         "module_required_files": ["概述.md", "技术栈.md", "架构设计.md"],
         "card_sections": ["体系概览", "关键文件与包", "架构与设计约定", "开发者应遵循的规则"],
         "card_update_extra": "更新摘要",
@@ -54,6 +94,8 @@ STRINGS: dict[str, dict] = {
             "search_placeholder": "搜索 Wiki…",
             "no_results": "无匹配结果",
             "snippet_missing": "源文件不存在或已删除，无法展示片段。",
+            "copy_label": "复制片段",
+            "copied_label": "已复制",
             "theme_label": "切换深色/浅色主题",
             "menu_label": "打开/收起目录",
             "close_label": "关闭 (Esc)",
@@ -85,8 +127,48 @@ STRINGS: dict[str, dict] = {
             ("Troubleshooting", "prefix"),
             ("Conclusion", "exact"),
         ],
+        "layer_sections": [
+            ("Introduction", "exact"),
+            ("Layer Overview", "exact"),
+            ("Layer Responsibilities", "exact"),
+            ("Layer Dependencies and Call Rules", "exact"),
+            ("Vertical Slice", "prefix"),
+            ("Cross-Cutting Concerns", "exact"),
+            ("Troubleshooting", "prefix"),
+            ("Conclusion", "exact"),
+        ],
+        "data_sections": [
+            ("Introduction", "exact"),
+            ("Data Model Overview", "exact"),
+            ("Core Entity Analysis", "exact"),
+            ("State Machine", "exact"),
+            ("Storage and Serialization", "exact"),
+            ("Data Lifecycle", "exact"),
+            ("Troubleshooting", "prefix"),
+            ("Conclusion", "exact"),
+        ],
+        "api_sections": [
+            ("Introduction", "exact"),
+            ("Endpoint Inventory and Grouping", "exact"),
+            ("Request Handling Sequence", "exact"),
+            ("API Contracts and Error Codes", "exact"),
+            ("Authentication and Access Control", "exact"),
+            ("Quotas", "prefix"),
+            ("Troubleshooting", "prefix"),
+            ("Conclusion", "exact"),
+        ],
+        "event_sections": [
+            ("Introduction", "exact"),
+            ("Event Inventory", "exact"),
+            ("Event Flow Topology", "exact"),
+            ("Event Contracts", "exact"),
+            ("Consumer Handling", "exact"),
+            ("Reliability Guarantees", "exact"),
+            ("Troubleshooting", "prefix"),
+            ("Conclusion", "exact"),
+        ],
         "overview_h1_suffix": "Wiki Overview",
-        "overview_sections": ("Section Navigation", "How to Use This Wiki"),
+        "overview_sections": ("Section Navigation", "How to Use This Wiki", "Glossary"),
         "module_required_files": ["overview.md", "tech-stack.md", "architecture.md"],
         "card_sections": [
             "System Overview", "Key Files and Packages",
@@ -100,6 +182,8 @@ STRINGS: dict[str, dict] = {
             "search_placeholder": "Search wiki…",
             "no_results": "No matches",
             "snippet_missing": "Source file missing or deleted; snippet unavailable.",
+            "copy_label": "Copy snippet",
+            "copied_label": "Copied",
             "theme_label": "Toggle dark/light theme",
             "menu_label": "Toggle table of contents",
             "close_label": "Close (Esc)",

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/src/repowiki/skills/repowiki/SKILL.en.md

@@ -45,9 +45,12 @@ repowiki site <repo>          # 7. build the single-file offline site .repowiki/
 After an incremental update or any post-finalize page rewrites, re-run
 `repowiki site <repo>` anytime to rebuild the site (idempotent).
 
-Task types: `catalog` (section-tree planning, produces state/catalog.json; process- or
-mechanism-themed pages may set the optional `"archetype": "flow"` field to use the flow
-template — default `module` is structural) → `page` (one page each) → `overview`;
+Task types: `catalog` (section-tree planning, produces state/catalog.json; pages may set
+the optional `"archetype"` field to pick one of six skeleton templates: `module`
+(structural, default) / `flow` (process) / `layer` (layered) / `data` (data model) /
+`api` (interface) / `event` (event-driven) — chosen by theme, falling back to `module`
+when unsure; non-default archetypes require evidence in page_brief) → `page` (one page
+each) → `overview`;
 optional: `repowiki knowledge <repo> [--categories <file>]` (knowledge cards; the
 category list can be replaced wholesale), `repowiki update <repo> [--dirty]`
 (git-diff-based incremental update; rewrites affected pages and the overview with an

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/src/repowiki/skills/repowiki/SKILL.md

@@ -40,7 +40,7 @@ repowiki site <repo>          # 7. 生成单文件离线查看站点 .repowiki/<
 
 增量更新或 finalize 后重跑了页面，都可随时重跑 `repowiki site <repo>` 重建站点（幂等）。
 
-任务类型：`catalog`（目录树规划，产出 state/catalog.json；流程/机制主题页可设可选字段 `"archetype": "flow"` 选用流程型模板，默认 module 结构型）→ `page`（逐页撰写）→ `overview`（总览）；
+任务类型：`catalog`（目录树规划，产出 state/catalog.json；页面可用可选字段 `"archetype"` 选六种原型模板：module 结构型（默认）/ flow 流程型 / layer 分层型 / data 数据模型型 / api 接口型 / event 事件型，按主题选型、无法确认时回退 module，非默认原型须在 page_brief 给出证据）→ `page`（逐页撰写）→ `overview`（总览）；
 可选：`repowiki knowledge <repo> [--categories <file>]`（知识卡片，类别清单可整表自定义）、`repowiki update <repo> [--dirty]`（基于 git diff 的增量更新，重写受影响页与总览页并附「更新摘要/Update Summary」小节；`--dirty` 纳入未提交/未跟踪变更）、`repowiki stale <repo> [--fail-if-stale]`（只读过期报告：哪些页面/卡片/模块会过期，不创建任务——CI 门禁用）、`repowiki coverage <repo>`（只读覆盖率报告：wiki 从未引用的仓库文件）。
 产出语言由 plan 时确定（README 权重最高的自动检测，或 `--locale zh|en`），持久化于 `state/locale`，规格中的模板即对应语言。
 

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/src/repowiki/tasks.py

@@ -80,8 +80,18 @@ def build_catalog_task(paths: WikiPaths, inv: Inventory) -> dict:
 
 # --- phase 2: pages ---
 
+_PAGE_TEMPLATE_BY_ARCHETYPE = {
+    "module": "page_template.md",
+    "flow": "flow_template.md",
+    "layer": "layer_template.md",
+    "data": "data_template.md",
+    "api": "api_template.md",
+    "event": "event_template.md",
+}
+
+
 def _page_template_name(node: FlatNode) -> str:
-    return "flow_template.md" if node.archetype == "flow" else "page_template.md"
+    return _PAGE_TEMPLATE_BY_ARCHETYPE.get(node.archetype, "page_template.md")
 
 
 def build_page_tasks(paths: WikiPaths, nodes: list[FlatNode], inv: Inventory, max_pages: int | None = None) -> list[dict]:

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/src/repowiki/templates/en/STYLE.md

@@ -2,7 +2,13 @@
 
 ## Language
 - Write plain English; keep code identifiers, class names, file paths, and config keys verbatim.
-- Objective, factual tone — no marketing language. No emoji. No tables (unless a config listing truly needs one).
+- Objective, factual tone — no marketing language. No emoji. Narrative prose uses no tables; enumerated lists with multiple attributes per item (e.g. entity|type|constraint, component|key files|responsibility, dependency|min version|role, error code|meaning|trigger) should be rendered as tables, with one sentence before each table explaining how to read it.
+
+## Body density (content quality, mandatory)
+- Every body section first explains in 2~4 sentences of prose (what it is, how it works, where the boundaries are), then uses bullets only for enumerable facts; a section that is a single sentence or a single bullet fails the bar.
+- Before each mermaid diagram, one sentence states what it shows and why it is worth reading; after the diagram, one sentence interprets the takeaway — diagrams never replace prose.
+- Rewrite one-item lists as prose. Each section carries at least ~3 lines of body text (excluding diagrams and source lists).
+- Grounding discipline: when evidence runs thin, write the section honestly short with the conceptual-statement disclaimer; never invent files, line numbers, or behavior — fewer sections beats fabricated content.
 
 ## Section Sources & Diagram Sources (citation format, mandatory)
 - Every body section ends with a "Section sources" list; every mermaid diagram is followed by a "Diagram sources" list.
@@ -14,7 +20,8 @@
 - If a section has no corresponding code, write: `[This section is conceptual; no specific files are analyzed, hence no "Section sources"]`
 
 ## Mermaid diagram style
-- Structure diagrams use `graph TB`, dependency/relationship diagrams `graph LR`, interaction flows `sequenceDiagram`, type relationships `classDiagram`.
+- Structure diagrams use `graph TB`, dependency/relationship diagrams `graph LR`, interaction flows `sequenceDiagram`, type relationships `classDiagram`, entity relations `erDiagram`, state transitions `stateDiagram-v2`. Diagram types should match the page archetype (data pages favor `erDiagram`/`stateDiagram-v2`, layer pages favor a layered `graph TB`).
+- Syntax notes: node labels in `graph`/`flowchart` must be double-quoted; `stateDiagram-v2` transition labels are written `stateA --> stateB : "trigger"`, with display names via `state "Label" as id` aliases; `erDiagram` entity names use ASCII identifiers, relation labels go inside quotes.
 - Node labels must be wrapped in double quotes; wrap long labels with `<br/>` and keep the key identifier visible:
 
 ```mermaid

repowiki_cli-0.8.0/src/repowiki/templates/en/api_template.md

@@ -0,0 +1,92 @@
+# {{TITLE}}
+
+## Contents
+1. [Introduction](#introduction)
+2. [Endpoint Inventory and Grouping](#endpoint-inventory-and-grouping)
+3. [Request Handling Sequence](#request-handling-sequence)
+4. [API Contracts and Error Codes](#api-contracts-and-error-codes)
+5. [Authentication and Access Control](#authentication-and-access-control)
+6. [Quotas, Idempotency and Rate Limits](#quotas-idempotency-and-rate-limits)
+7. [Troubleshooting Guide](#troubleshooting-guide)
+8. [Conclusion](#conclusion)
+
+## Introduction
+<One paragraph: who these interfaces serve (external callers / CLI users / other processes), what problem they solve, and where they live in the repository.>
+
+## Endpoint Inventory and Grouping
+<The interface inventory grouped by functional domain (bullets: interface name → one-line purpose), with a grouping diagram.>
+
+```mermaid
+graph TB
+subgraph "Project domain"
+P1["Create project<br/>projects.py"]
+P2["Query project<br/>projects.py"]
+end
+subgraph "Task domain"
+T1["Create task<br/>tasks.py"]
+end
+```
+
+Diagram sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## Request Handling Sequence
+<Pick one representative call: the full handling path from client request to response.>
+
+```mermaid
+sequenceDiagram
+participant C as "Caller"
+participant MW as "Middleware"
+participant H as "Handler"
+participant S as "Service layer"
+C->>MW : "send request"
+MW->>H : "validate and route"
+H->>S : "invoke business logic"
+S-->>H : "result"
+H-->>C : "response"
+```
+
+Diagram sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## API Contracts and Error Codes
+First a short prose paragraph on the contract style; with ≥3 error codes use a table (| Code | Meaning | Trigger |), and attach a file:// citation to each interface in the inventory section.
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## Authentication and Access Control
+<Authentication method, where permission checks land in the code, and how anonymous vs authorized behavior differs (bullets); without auth, state the current situation and its boundary.>
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## Quotas, Idempotency and Rate Limits
+<Rate limits, idempotency keys, retry semantics (bullets); without them, state the current situation and what callers must guard themselves against.>
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## Troubleshooting Guide
+- <common error codes/symptoms → cause → how to locate → relevant code location.>
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## Conclusion
+<One paragraph: the interface surface's positioning, correct usage, and caveats.>
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+<cite>
+**Files referenced**
+- [<file name>](file://<repo-relative path>)
+- [<file name>](file://<repo-relative path>)
+</cite>

{repowiki_cli-0.7.0 → repowiki_cli-0.8.0}/src/repowiki/templates/en/catalog_task.md

@@ -58,7 +58,13 @@ Write every human-readable field (`title`, `summary`, `page_brief`) in **English
 5. `page_brief` states the concrete points the page must cover — it becomes the prompt for the page-writing task, so be specific (which modules/classes/flows/configs).
 6. Coverage expectations (mirroring wikis of comparable projects): project overview, quick start, core concepts, main features/SDK usage, configuration, deployment/operations, API reference, examples/contributing — trim to what this repository actually contains; do not force sections that do not apply.
 7. `slug` is lowercase English and hyphens (e.g. `project-overview`, `quick-start`).
-8. (Optional) page nodes may set `archetype` to pick the page template: mechanism/process-themed pages (e.g. "lifecycle of a request", "build & release pipeline", "event loop") use `"archetype": "flow"` (Flow Overview / Key Steps / Involved Components / Data and State Changes); all other structural themes default to `"archetype": "module"` (Project Structure / Core Components / Architecture Overview / Dependency Analysis). The field may be omitted (same as module); every flow page should state the flow's start and end in its page_brief.
+8. (Optional) page nodes may set `archetype` to pick the page skeleton: one of `module` / `flow` / `layer` / `data` / `api` / `event` (omitted = `module`). Choose by the page's topic; **when in doubt, use `module`**. Every non-default archetype has admission criteria, and choosing one requires corresponding evidence in page_brief, or the page will fail validation:
+   - `flow`: end-to-end process/mechanism topics (e.g. "lifecycle of a request", "build & release pipeline"). Admission: a fully traceable start and end exists. Evidence: page_brief states the flow's start and end.
+   - `layer`: layered-architecture / calling-convention topics (e.g. "layered architecture and dependency direction"). Admission: the code has a clear layering with call-direction rules. Evidence: page_brief lists the layers.
+   - `data`: data-model / entity / state-machine topics (e.g. "data model and storage", "order state machine"). Admission: explicit data structures and/or state transitions exist. Evidence: page_brief names the core entities.
+   - `api`: outward-facing interface / command-surface topics (e.g. "CLI reference", "REST API"). Admission: a stable caller-facing interface surface exists. Evidence: page_brief states the endpoint grouping / inventory source.
+   - `event`: event / message / pub-sub topics (e.g. "event bus", "message flow"). Admission: an event or message mechanism exists. Evidence: page_brief states where the event inventory comes from.
+   - `module` (structure, default): component / structure / dependency topics (Project Structure / Core Components / Architecture Overview / Dependency Analysis).
 
 ## Self-check (before writing the file)
 - [ ] JSON parses (re-read the file after writing to confirm)

repowiki_cli-0.8.0/src/repowiki/templates/en/data_template.md

@@ -0,0 +1,109 @@
+# {{TITLE}}
+
+## Contents
+1. [Introduction](#introduction)
+2. [Data Model Overview](#data-model-overview)
+3. [Core Entity Analysis](#core-entity-analysis)
+4. [State Machine](#state-machine)
+5. [Storage and Serialization](#storage-and-serialization)
+6. [Data Lifecycle](#data-lifecycle)
+7. [Troubleshooting Guide](#troubleshooting-guide)
+8. [Conclusion](#conclusion)
+
+## Introduction
+<One paragraph: which data/entities/states this page covers, why they matter, and where they live in the repository.>
+
+## Data Model Overview
+<One paragraph sketching the core entities and their relations, with an ER diagram (entity names in English).>
+
+```mermaid
+erDiagram
+USER ||--o{ ITEM : "creates"
+ITEM ||--o{ TAG : "owns"
+ITEM {
+    int id
+    string name
+    string status
+}
+```
+
+Diagram sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## Core Entity Analysis
+### <Entity 1>
+- Fields: <key fields and types; with many fields prefer a table: | Field | Type | Constraint/Notes |>
+- Constraints: <uniqueness / nullability / referential integrity>
+- Invariants: <conditions that must always hold>
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+### <Entity 2>
+- ...
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## State Machine
+<If there is a status field: list every state and its transition triggers in a stateDiagram-v2 (use `state "Label" as id` aliases for display names); without an explicit state machine, describe the implicit data-state progression.>
+
+```mermaid
+stateDiagram-v2
+state "Draft" as draft
+state "Published" as published
+state "Archived" as archived
+[*] --> draft
+draft --> published : "publish"
+published --> archived : "archive"
+archived --> [*]
+```
+
+Diagram sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## Storage and Serialization
+First a short prose paragraph on the storage landscape, then bullets: where data lives (memory / files / database), formats, and serialization/deserialization code points.
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## Data Lifecycle
+<The full path from creation through usage/update to archival/cleanup, with a lifecycle diagram.>
+
+```mermaid
+graph LR
+A["Create"] --> B["Use / Update"]
+B --> C["Archive"]
+C --> D["Cleanup"]
+```
+
+Diagram sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## Troubleshooting Guide
+- <common data problems (inconsistency / dirty data / concurrency conflicts) → cause → how to locate → relevant code location.>
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+## Conclusion
+<One paragraph: the data model's positioning, correct usage, and caveats.>
+
+Section sources
+- [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+<cite>
+**Files referenced**
+- [<file name>](file://<repo-relative path>)
+- [<file name>](file://<repo-relative path>)
+</cite>