@pieai/pro-gov 0.3.4 → 0.3.6

package/assets/public-agent-assets/skills/pie-skills/beginner-friendly-docs/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: beginner-friendly-docs
+description: >
+  用故事线 + 比喻 + mermaid 图表 + 对话示例，把复杂系统写成人能读懂的教学文档。
+  支持初级、中级、高级三种难度层级，自动根据目标读者调整写法。
+  当用户说"写个教程""写个文档""这个文档看不懂""能不能说人话""教我怎么用""写个入门指南"
+  "写个进阶指南""给小白写个说明""这文档太技术了""用人话解释一下""写个 beginner guide"
+  "写个 advanced guide""写个 walkthrough""让不懂编程的人也能看懂"
+  "写个使用手册""重写这个文档""这个怎么给人解释"时，使用本技能。
+  即使用户只是说"这个怎么讲清楚""文档太难了""重写一下""帮我改改这个文档"，也应当触发。
+  本技能的核心信念：如果读者看不懂，是作者的问题，不是读者的问题。
+---
+
+# 教学文档写作技能
+
+把复杂系统变成目标读者能读懂、愿意读、读完有收获的教学文档。
+
+## 核心信念
+
+- **如果读者看不懂，是作者的问题，不是读者的问题。**
+- 所有概念都能用比喻辅助理解。如果你觉得找不到比喻，说明你还没理解透。
+- 不要用"简单来说"来掩盖说不清楚。真正清晰的解释不需要这个前缀。
+- 图比文字有效，例子比定义有效，对话比步骤有效。
+
+## 第零步：判断难度层级
+
+在开始写之前，先明确文档面向的读者层级。
+
+| 层级 | 目标读者 | 前置知识假设 | 核心写法 |
+| --- | --- | --- | --- |
+| 🟢 初级 | 完全不懂技术的人 | 不知道 CLI、JSON、hash 是什么 | 100% 故事驱动，比喻先行，隐藏所有技术细节 |
+| 🟡 中级 | 读过初级文档，会基本操作 | 知道系统角色和核心流程 | 故事 + 真实命令/输出，打开更多底层细节 |
+| 🔴 高级 | 有实战经验，遇到过问题 | 能独立跑流程，需要理解边界和原理 | 深度原理 + 边界条件 + 故障排查 + 对比分析 |
+
+**如何判断**：
+- 用户明确说了（"给新手写""写进阶指南""高级用法"）→ 直接用
+- 文档标题/位置暗示了（`beginner-guide` vs `advanced` vs `reference`）→ 推断
+- 不确定 → 问用户
+
+**层级不同，但方法论相通。** 以下所有步骤在三个层级都适用，只是具体写法不同。
+
+## 写作流程
+
+### 第一步：深度研究目标系统
+
+在写任何一个字之前，先彻底搞清楚系统到底怎么工作。
+
+1. **读源代码和配置**——不是读文档，是读实际的代码、配置文件、命令行输出
+2. **找到真实的数据结构**——检查真实的目录结构、JSON 文件、配置项
+3. **跑一遍流程**——如果可能的话，实际执行一次系统的核心流程，看看每一步到底产生了什么
+4. **列出所有核心概念**——把系统里的每个关键概念列出来
+
+然后根据层级决定哪些概念需要展开、哪些可以简化、哪些可以先跳过。
+
+| 层级 | 研究重点 |
+| --- | --- |
+| 🟢 初级 | 核心流程 + 关键角色。省略所有实现细节。 |
+| 🟡 中级 | 完整流程 + 状态转换 + 常见场景。展示真实命令和输出。 |
+| 🔴 高级 | 边界条件 + 失败模式 + 底层原理 + 设计决策的 why。 |
+
+### 第二步：设计故事线
+
+为整套文档设计一个**贯穿的虚拟人物和场景**。
+
+设计要素：
+- **虚拟人物**：给他/她一个名字、一个具体的目标、一个清晰的动机
+- **人设约束**：人物的技术水平应该匹配目标读者
+- **目标场景**：一个具体的、可以从头走到尾的任务
+- **进阶挑战**：如果是中级/高级文档，给人物设计越来越复杂的情境
+
+| 层级 | 人物设定 | 场景复杂度 |
+| --- | --- | --- |
+| 🟢 初级 | 完全不懂技术，第一次用系统 | 一个简单任务从头到尾 |
+| 🟡 中级 | 会基本操作，遇到了新情况 | 多个场景、有状态变化、有分支 |
+| 🔴 高级 | 有经验但遇到复杂问题 | 故障排查、边界条件、多步连锁 |
+
+**故事线是骨架，不是装饰。** 所有概念都必须在故事里自然地出场。
+
+### 第三步：规划文档结构
+
+按照**读者学习的自然顺序**来组织文档，而不是按照系统的技术架构。
+
+**通用原则**（所有层级）：
+- 先讲"为什么要学这个"，再讲"怎么做"
+- 每篇有明确的学习目标和预计阅读时间
+- 篇与篇之间有自然的过渡
+- 全套文档有一个 index 做导航
+
+**篇数不固定**——根据内容复杂度决定，不要把太多东西塞进一篇，也不要把一个小概念拆成一整篇。一篇文档的最佳长度是 8-15 分钟阅读。
+
+### 第四步：逐篇撰写
+
+对每一篇文档，遵循以下写法：
+
+#### 开头
+- 用一句话说清"读完这篇你会知道什么"
+- 🟢 初级：不要用技术术语开场
+- 🟡 中级：可以引用系统术语，但附上回顾链接
+- 🔴 高级：可以直接用术语，但要精确定义
+
+#### 比喻和类比
+
+比喻在所有层级都有用，但使用方式不同：
+
+| 层级 | 比喻策略 |
+| --- | --- |
+| 🟢 初级 | 每个新概念必须先给比喻，再给解释。用日常生活场景（装修、做菜、体检）。 |
+| 🟡 中级 | 复杂概念用比喻辅助，简单概念直接解释。可以用专业但通用的比喻（版本控制、质检流水线）。 |
+| 🔴 高级 | 在解释设计决策时用比喻说明 why。可以用技术领域的类比（CAP 定理、乐观锁 vs 悲观锁）。 |
+
+比喻的通用要求：
+- **先给比喻，再给解释**，不要反过来
+- 比喻不能过度延伸——用到它能解释的那个点就停
+- 一个特别重要的概念，给两个不同角度的比喻
+
+#### 可视化
+
+**每个流程和概念关系都画 mermaid 图**，所有层级通用：
+
+- 流程 → `graph TD/LR`
+- 时间顺序 → `sequenceDiagram`
+- 状态变化 → `stateDiagram-v2`
+- 概念关系 → `mindmap`
+- 对比 → 并排的 `subgraph`
+- 分类决策 → 带 `{}` 判断节点的 `graph`
+
+层级差异：
+
+| 层级 | 图表策略 |
+| --- | --- |
+| 🟢 初级 | 图里只用人话标签，不放术语。颜色丰富，一眼就懂。 |
+| 🟡 中级 | 图里用系统术语 + 人话注释。展示真实状态和分支。 |
+| 🔴 高级 | 图里展示底层数据流、哈希依赖关系、失败路径。 |
+
+#### 操作示例
+
+| 层级 | 示例风格 |
+| --- | --- |
+| 🟢 初级 | 用"故事人物说了什么话"来展示，不列命令。表格格式：步骤 \| 你可以说的话。 |
+| 🟡 中级 | 先给自然语言对话，然后展示 AI 实际执行的命令和输出，两者对照。 |
+| 🔴 高级 | 直接给命令 + 输出 + 解读。展示异常输出和错误信息的解读方式。 |
+
+#### 结尾
+- "快速回顾"FAQ 表格：你可能会问 | 答案
+- 🟡🔴 中高级：补充"自测题"和参考答案
+- 🟡🔴 中高级：术语精确定义表（不只是人话对照，而是精确的功能边界）
+- "下一篇"的自然过渡
+
+#### 一个微型示例（初级层级长这样）
+
+光说方法不够，看一眼差别最快。同一个事实，技术写法 vs 初级写法：
+
+> ❌ 技术写法：「gate 校验通过后，hook 会触发 memory update，将 accepted-commit 写入记忆库。」
+>
+> ✅ 初级写法：「这一步你可以想成**体检合格才发证**。系统先给这一章做一次"体检"——查字数够不够、跟大纲对不对得上。只有全部过了，它才肯把这一章"记到账上"；没过就卡住，逼你先改。」
+
+配一张一眼能懂的图（标签全用人话，不出现术语）：
+
+```mermaid
+graph LR
+    A[写完这一章] --> B{体检通过?}
+    B -- 通过 --> C[记到账上 ✅]
+    B -- 没过 --> D[卡住, 先去改] --> A
+```
+
+操作示例用"人物说的话"，不列命令：
+
+| 步骤 | 小白可以对 AI 说的话 |
+| --- | --- |
+| 让它体检 | "帮我看看这章能不能过" |
+| 没过要改 | "它说哪里不行？带我一起改" |
+
+这就是初级写法的签名：**比喻先行 → 配图 → 用对话代替命令**。中高级在此基础上逐步打开真实命令和底层原理。
+
+### 第五步：深度迭代
+
+写完初稿后，至少做一轮深度迭代：
+
+1. **补图**——检查每个流程和概念是否都有对应的 mermaid 图
+2. **补比喻**——检查每个抽象概念是否都有合适层级的比喻
+3. **补示例**——检查每个操作步骤是否都有对应层级的操作示例
+4. **检查术语**——搜索文档中是否有未解释的术语，根据层级决定是替换、加注还是直接用
+5. **增加对比图**——在有 before/after、对比、分支选择的地方加可视化
+6. **检查连贯性**——故事人物的经历是否跨篇连贯
+7. **检查深度递进**——如果是系列文档，后面的篇章是否在前面的基础上递进，而不是重复
+
+### 第六步：交叉验证
+
+这一步至关重要，单独列为一个技能（见 `doc-cross-validator` 技能）。
+
+写完后必须对照真实系统验证文档内容，确保没有自己想当然地编造流程。
+
+## 红线（这些是 AI 写教学文档时反复栽的坑，记住"为什么"就不会犯）
+
+**所有层级**：
+- 别用"简单来说"开头——它八成是"我没讲清楚"的遮羞布，真清楚的解释不需要这个前缀
+- 别让一整段纯文字不带任何视觉元素（图/表/引用块）——读者的眼睛需要落脚点，文字墙会劝退人
+- 别写完不做交叉验证——读着顺但流程是错的，比"丑但对"更危险（见 `doc-cross-validator`）
+- 别在没有比喻或例子的情况下抛出复杂概念——抽象概念没有抓手，读者会假装看懂然后悄悄放弃
+
+**初级额外**：
+- 别假设读者知道 CLI、JSON、hash、config、commit 是什么——只要假设了，从那一句起读者就掉队了
+- 别在正文里直接贴命令行——初级读者看到命令会本能紧张，把操作藏进"对人说的话"里
+
+**中级额外**：
+- 别只给命令不解释为什么这样做——会用但不懂原理，遇到变化就懵
+- 别跳过"从初级概念到这个新概念"的桥接——读者是顺着上一篇爬上来的，断一节台阶就摔下去
+
+**高级额外**：
+- 别只说"怎么做"不说"为什么这样设计"——高级读者要的正是 why，怎么做他们能自己查
+- 别把边界条件和失败模式当"不重要"省掉——真正咬人的恰恰是这些，省了等于没写
+
+## 质量标准
+
+下面这张表是**自检基准，不是凑数指标**。判断每一项只有一个标准：**读者读到这里，缺了这个东西会不会卡住、会不会误解？** 会，就补；不会，硬凑反而是噪音。举个例子——一篇全是线性叙述、没有任何分叉的短文，硬塞三张图只会稀释重点，这时一张关键流程图就够了。别为达标而达标，AI 足够聪明，自己判断。
+
+| 维度 | 🟢 初级 | 🟡 中级 | 🔴 高级 |
+| --- | --- | --- | --- |
+| 比喻 | 每个核心概念配一个 | 复杂概念配 | 解释设计决策时配 |
+| 图表 | 每个流程/概念关系都该配图；多步流程却一张图都没有，是信号 | 关键流程与状态配图 | 数据流、失败路径、依赖关系配图 |
+| 操作示例 | 自然语言对话表格 | 对话 + 命令对照 | 命令 + 输出 + 解读 |
+| FAQ | 结尾配"快速回顾" | 结尾配 | 结尾配 + 自测题 |
+| 术语处理 | 全部用人话替代 | 系统术语 + 人话注释 | 精确定义 + 功能边界 |
+| 连贯性 | 虚拟人物贯穿 | 虚拟人物贯穿 | 场景贯穿 |
+| 阅读时间 | 目标 8-12 分钟，超长就拆篇 | 目标 10-15 分钟 | 目标 10-20 分钟 |

package/assets/public-agent-assets/skills/pie-skills/doc-cross-validator/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: doc-cross-validator
+description: >
+  交叉验证文档内容是否符合真实系统。对照源代码、配置文件、真实数据结构验证文档中的每一个事实性声明。
+  当用户说"验证一下文档""对照系统检查""这个文档说的对不对""确认文档准确性""交叉验证"
+  "别瞎编""写的对不对""有没有错""跟代码对得上吗""事实核查""fact check"时，使用本技能。
+  当用户要求写完文档之后，也应当自动触发本技能做最终验证。
+  即使用户只是说"检查一下""核实一下""是这样吗"——只要上下文中涉及文档与系统的对照关系，
+  也应当触发本技能。
+  本技能验证文档并产出审计报告；发现教程/创作类文档（人写的内容）有错时默认直接修正，并在报告里列清改了哪几处、依据何在；但绝不手改系统自己生成的状态文件（那类只报告、交由对应命令重新生成）。
+  与 beginner-friendly-docs 技能配合使用：那个技能写，这个技能验。
+---
+
+# 文档交叉验证技能
+
+验证文档内容是否与真实系统行为一致。杜绝"想当然"、"凭印象"、"差不多"。
+
+## 核心理念
+
+文档的最大敌人不是"写得不好看"，而是"写的不对"。
+
+一个用词优美但流程错误的文档，比一个丑但准确的文档更危险——它会误导读者建立错误的心智模型。
+
+**本技能只做一件事：确认文档说的跟系统做的是一致的。**
+
+## 验证流程
+
+### 第一步：标记所有事实性声明
+
+逐段扫描文档，把所有可以验证的事实性声明提取出来。
+
+事实性声明包括：
+- **流程描述**：说某个操作之后会发生什么（如"检查通过后系统会更新记忆"）
+- **数据结构**：说系统有哪些文件、文件夹、配置项
+- **检查项**：说系统会检查哪些东西
+- **状态描述**：说系统有哪些状态、状态之间怎么转换
+- **前置条件**：说做某件事之前需要满足什么条件
+- **术语定义**：给系统术语的解释
+
+**不需要验证的内容**：
+- 比喻和类比（它们是教学工具，不是事实描述）
+- 建议和最佳实践（主观判断）
+- 虚拟人物的对话（教学示例）
+
+### 第二步：逐项对照验证
+
+对每个事实性声明，找到系统中的对应真相来源。
+
+#### 验证的真相来源（按优先级排序）
+
+1. **源代码**——实际的实现逻辑。这是最终真相。
+2. **配置文件和 JSON 结构**——如 `book.json`、`gate-result.json`、`accepted-commit.json`
+3. **真实的目录结构**——用 `list_dir` 或 `ls` 检查实际存在的文件和文件夹
+4. **CLI 帮助信息**——用 `--help` 看命令实际支持哪些选项
+5. **系统的规范文档**——如 `AGENTS.md`、`SKILL.md` 等定义行为的文件
+6. **测试代码**——测试用例描述了系统的预期行为
+
+**不可以作为真相来源的**：
+- 之前版本的文档（可能过时）
+- AI 的"记忆"或"知识"（可能不准确）
+- 其他 AI 写的文档（可能也有错）
+
+#### 验证的方法
+
+对于每个事实性声明：
+
+1. **定位真相来源**——找到系统中能验证这个声明的具体文件或代码
+2. **读取真相**——实际打开文件，读取内容
+3. **对比**——声明 vs 真相，一致还是不一致？
+4. **分类**：
+   - ✅ **准确**：完全一致
+   - ⚠️ **简化但不误导**：声明省略了细节，但核心意思正确，不会导致误解
+   - 🔶 **简化但可能误导**：声明省略的细节可能让读者建立错误理解
+   - ❌ **错误**：声明与真相不一致
+   - 🔍 **无法验证**：找不到对应的真相来源
+
+### 第三步：判断简化的合理性
+
+对于"简化"类的声明，需要判断简化是否合理。
+
+#### 合理的简化
+
+- 省略了初学者不需要知道的高级功能
+- 用通用名称替代了具体的技术标识符（如"大纲"代替"plots.md"）
+- 合并了多个概念为一个更好理解的概念
+- 省略了边缘情况（只要不影响核心理解）
+
+#### 不合理的简化
+
+- 把可选步骤说成必须步骤，或反过来
+- 遗漏了会影响用户决策的重要概念
+- 把两个独立的概念混为一谈
+- 错误地简化了流程的先后顺序或因果关系
+- 完全省略了一个重要的系统组件
+
+### 第四步：输出审计报告
+
+生成一份结构化的审计报告。
+
+#### 报告格式
+
+```markdown
+# 文档交叉验证报告
+
+## 验证范围
+- 文档：[文档名]
+- 验证日期：[日期]
+- 对照的真相来源：[列出检查了哪些源文件]
+
+## 验证结果摘要
+
+| 分类 | 数量 |
+| --- | --- |
+| ✅ 准确 | N |
+| ⚠️ 简化但不误导 | N |
+| 🔶 简化但可能误导 | N |
+| ❌ 错误 | N |
+| 🔍 无法验证 | N |
+
+## 需要修正的问题
+
+### ❌ 错误 1：[简要描述]
+- **文档原文**："..."
+- **实际情况**："..."
+- **真相来源**：[文件路径]
+- **建议修正**："..."
+
+### 🔶 可能误导 1：[简要描述]
+- **文档原文**："..."
+- **实际情况**：完整描述是"..."
+- **误导风险**：读者可能会以为"..."
+- **建议**：补充说明"..."
+
+## ⚠️ 合理简化（不需要修正，但记录在案）
+
+- [声明]：省略了[什么]，对初学者不影响理解
+- ...
+
+## 验证通过的声明（抽样展示）
+
+- ✅ "检查通过后才能更新记忆" → 符合 AGENTS.md 第 151 行
+- ✅ "文件改了之后检查结果自动过期" → 符合 gate-result.json 的 inputHashes 机制
+- ...
+```
+
+### 第五步：修正文档（默认直接改"可改的内容"，改完报告改了什么）
+
+发现 ❌ 错误和 🔶 可能误导后，**默认直接动手修正**——但动手前先分清这块内容属于哪一类，因为不是所有东西都能手改。
+
+**可以直接改：人写的创作/教学类内容。** 教程正文、说明文档、大纲、草稿、设定等。发现错就改，改完务必在报告里附一份**改动清单**：改了哪几处、原文 →新文、依据哪个真相来源。这样用户既拿到干净的文档，又能一眼看到你动了什么、为什么动——这就是"改完报告"，不是"偷偷改"。
+
+**绝不手改：系统自己生成的硬状态文件。** 像 `gate-result.json`、`accepted-commit.json`、evidence、memory、`story_graph.json` 这类由命令或流程产出的产物，记录的是"系统算出来的事实"。手改会让数据对不上、还可能被系统的保护机制（hook）直接拦下。这类即使发现不对，也**只在报告里指出**，并说明应该去改它的源头、或用对应命令重新生成（如重跑 `gate run` / `memory update`），而不是直接编辑这个文件。
+
+> 一句话口诀：**这个文件是人写的，还是系统生成的？** 人写的——直接改 + 报告；系统生成的——只报告、不碰。
+
+修正"可改内容"时遵循：
+- **尽量在不破坏可读性的前提下修正**——不要为了准确而牺牲初学者的理解
+- **重要的细节补进正文；次要的细节用引用块（`>`）补充**
+- **改完重新走一遍验证**，确认没有引入新的错误
+- **在报告里保留改动清单**，方便用户复核
+
+> 例外：如果用户明确说"只检查别改""先别动我的文档"，那就只出报告、不动手——尊重用户当下的意图。
+
+## 常见的"想当然"陷阱
+
+以下是写文档时最容易出现的"想当然"错误，验证时要特别注意：
+
+| 陷阱 | 描述 | 怎么避免 |
+| --- | --- | --- |
+| 编造检查项 | 说系统检查 X，但实际没有 | 读 gate-result.json 的 checks 数组 |
+| 编造流程步骤 | 说操作后会自动做 Y，但实际需要手动 | 读源代码或跑一次实际命令 |
+| 张冠李戴 | 把 A 功能的特性说成 B 的 | 分别查看 A 和 B 的实现代码 |
+| 遗漏前置条件 | 说"做完 X 就可以 Y"，但实际还需要 Z | 读 CLI 代码中的校验逻辑 |
+| 简化过度 | 说"系统有两个状态"，但实际有五个 | 读枚举定义或状态机代码 |
+| 旧信息 | 引用的流程已经在新版本中改了 | 对照当前代码，而不是旧文档 |
+
+## 与其他技能的配合
+
+- **beginner-friendly-docs**：那个技能负责写，这个技能负责验。写完后调用本技能做验证。
+- 如果在 chapter-doctor 管道中使用，本技能位于写作之后、发布之前。
+
+## 适用范围
+
+本技能适用于任何"文档描述了一个系统"的场景：
+- 软件产品的用户指南
+- API 文档
+- 开发者文档
+- 教学文档
+- 系统架构说明
+
+不适用于：
+- 纯文学创作（没有"系统"可以验证）
+- 观点类文章（不存在客观的"对错"）
+- 营销文案（允许适度夸张）

package/assets/starter/.github/workflows/docs-check.yml

@@ -5,7 +5,6 @@ on:
     paths:
       - "AGENTS.md"
       - "CLAUDE.md"
-      - ".gemini/settings.json"
       - "README.md"
       - "docs/**"
       - "lefthook.yml"
@@ -18,7 +17,6 @@ on:
     paths:
       - "AGENTS.md"
       - "CLAUDE.md"
-      - ".gemini/settings.json"
       - "README.md"
       - "docs/**"
       - "lefthook.yml"
@@ -35,11 +33,11 @@ jobs:
 
       - uses: pnpm/action-setup@v4
         with:
-          version: 10.26.0
+          version: 11.9.0
 
       - uses: actions/setup-node@v4
         with:
-          node-version: "22"
+          node-version: "24"
           cache: pnpm
 
       - name: Install dependencies

package/assets/starter/docs/governance/agents-routing/doc-only-v0.9.md

@@ -79,6 +79,5 @@ unless the project explicitly opts them into doc-gov.
 ## External Workflow Boundary
 
 This route runs before external workflow systems such as Superpowers or GStack.
-Host-specific adapters such as `CLAUDE.md` or `.gemini/settings.json` may adapt
-the route for a specific AI client, but they must not replace the project
-`AGENTS.md` route.
+Host-specific adapters such as `CLAUDE.md` may adapt the route for a specific AI
+client, but they must not replace the project `AGENTS.md` route.

package/assets/starter/docs/governance/agents-routing/engineering-runtime-v0.9.md

@@ -74,6 +74,5 @@ This route runs before external workflow systems such as Superpowers or GStack.
 Those systems may provide skills, reviews, browser workflows, or shipping gates,
 but they execute **inside** the lane selected by this route.
 
-Host-specific adapters such as `CLAUDE.md` or `.gemini/settings.json` may adapt
-the route for a specific AI client, but they must not replace the project
-`AGENTS.md` route.
+Host-specific adapters such as `CLAUDE.md` may adapt the route for a specific AI
+client, but they must not replace the project `AGENTS.md` route.

package/assets/starter/docs/governance/boundary.md

@@ -5,8 +5,8 @@ type: reference
 status: stable
 canonical: true
 owner: project
-created: YYYY-MM-DD
-last_reviewed: YYYY-MM-DD
+created: 2026-05-08
+last_reviewed: 2026-05-08
 domain: doc-governance
 tags:
   - doc-gov

package/assets/starter/docs/governance/ssot-v0.9.md

@@ -71,7 +71,7 @@ Extra governed roots are allowed only when a project explicitly opts in.
 
 Before changing docs, look for project-local guidance in this order:
 
-1. `AGENTS.md`, `CLAUDE.md`, `.gemini/settings.json`, or equivalent AI router/config adapter.
+1. `AGENTS.md`, `CLAUDE.md`, or equivalent AI router/config adapter.
 2. `docs/governance/boundary.md`.
 3. `docs/governance/ssot-v0.9.md`.
 4. `docs/governance/agents-routing/` and the project's selected agents-routing file.
@@ -100,7 +100,7 @@ works for governed docs:
 
 | Need | Usually belongs in |
 | --- | --- |
-| AI entry and startup routing | `AGENTS.md` plus thin host-specific adapters such as `CLAUDE.md` and `.gemini/settings.json` |
+| AI entry and startup routing | `AGENTS.md` plus thin host-specific adapters such as `CLAUDE.md` |
 | Agents-routing rules | `docs/governance/agents-routing/` |
 | Doc-system rules, templates, and manifest | `docs/governance/` |
 | Project AI/development policy | `docs/policy/` |

package/assets/starter/lefthook.template.yml

@@ -6,10 +6,10 @@ pre-commit:
   parallel: false
   commands:
     01-doc-gov-router-check:
-      glob: "{AGENTS.md,CLAUDE.md,README.md,.gemini/settings.json,docs/**/*.{md,yml,yaml}}"
+      glob: "{AGENTS.md,CLAUDE.md,README.md,docs/**/*.{md,yml,yaml}}"
       run: pnpm doc-gov router-check
     02-doc-gov-check:
-      glob: "{docs/**/*.md,docs/governance/**/*.{md,yml,yaml},docs/policy/**/*.md,AGENTS.md,CLAUDE.md,.gemini/settings.json}"
+      glob: "{docs/**/*.md,docs/governance/**/*.{md,yml,yaml},docs/policy/**/*.md,AGENTS.md,CLAUDE.md}"
       run: pnpm doc-gov check && pnpm doc-gov scan --check && pnpm doc-gov links && pnpm doc-gov audit
 
 commit-msg:

package/cli-guide.md

@@ -16,6 +16,8 @@ Public package-safe commands:
 pro-gov assets list
 pro-gov assets discover --target .
 pro-gov assets recommend --target .
+pro-gov portfolio check --config /path/to/portfolio.json
+pro-gov portfolio plan --config /path/to/portfolio.json --target web-app --json
 pro-gov lens inspect --target .
 pro-gov lens report --target . --out .pro-gov/lens-report.md
 pro-gov init --profile engineering-runtime --dry-run
@@ -31,16 +33,29 @@ Full upstream-checkout commands:
 
 ```bash
 pro-gov assets list --json
+pro-gov portfolio check --config /path/to/control-repo/.pro-gov/portfolio.json --json
+pro-gov portfolio plan --config /path/to/control-repo/.pro-gov/portfolio.json --target web-app --json
 pro-gov assets plan --bundle base-governance --target . --out .pro-gov/asset-plan.json
+pro-gov assets plan --bundle project-lens --target /path/to/project --host codex --placement manual --out /tmp/project-lens-plan.json
 pro-gov assets apply --plan .pro-gov/asset-plan.json
 pro-gov assets check --target .
+pro-gov assets public-check --json
 pro-gov assets npx add <source> --plan
 pro-gov assets npx update --plan
 ```
 
-These commands need the private `agent-assets/` registry in a full Project
-Governance System checkout. The public npm package excludes private and
-third-party skill bodies by design.
+These commands use a maintainer-local `agent-assets/` registry when local-only
+assets are present. Publicly reviewed assets live under `public-agent-assets/`;
+the public npm package excludes unpublished asset bodies by design.
+`public-check` is the maintainer drift check for the promotion receipt recorded
+in `public-agent-assets/registry.json`.
+Skill placement normally comes from the asset registry. Use `--placement
+auto|manual` only as a migration override when deliberately moving an existing
+target.
+
+Portfolio manifests are external configuration files owned by a user or
+organization's control repository. PGS provides the format and commands; it does
+not publish a real user's private downstream project list.
 
 ## Typical Adoption Flow