@mingfuyun/star-allinone 0.1.7 → 0.1.9

package/README.md

@@ -12,6 +12,117 @@ yarn add @mingfuyun/star-allinone
 pnpm add @mingfuyun/star-allinone
 ```
 
+## Skill 如何使用
+
+公共 skill 由本仓库维护，随 `@mingfuyun/star-allinone` 发布。业务项目用 CLI 同步到自己的 `.agents/skills/shared-*` 并提交。Codex / Cursor 直接从业务仓库发现 skill，不写入 `~/.codex/skills`，团队成员也不需要本仓库源码。
+
+```text
+.agents/skills/
+├── shared-*    ← npm 包同步，不能在业务项目直接改
+└── custom-*    ← 业务项目自己维护
+```
+
+完整约定见 [skills/README.md](skills/README.md)。
+
+### 命令
+
+全部在**业务项目根目录**执行：
+
+```bash
+pnpm exec star-allinone skills list
+pnpm exec star-allinone skills sync --dry-run
+pnpm exec star-allinone skills sync
+```
+
+`list` 查看包内公共 skill。`sync` 把它们写入当前项目的 `.agents/skills/shared-*`，会整体替换过期的 `shared-*`，但不会改 `custom-*`。
+
+### 维护者：改公共 skill
+
+1. 修改 `skills/shared/<name>/SKILL.md`，例如 `skills/shared/api-to-service/SKILL.md`
+2. 发布新版本 `@mingfuyun/star-allinone`
+3. 业务项目升级依赖并重新同步（见下方）
+
+不要把流水线 ID 或 OpenAPI 快照写进 `skills/shared`。流水线 ID 放在业务项目 `.star-allinone.json` 的 `publishPipelineId`。审查、提交、发布、Mock 和 Service 生成都是公共 skill。
+
+### 业务项目：首次接入
+
+1. 安装依赖：
+
+```bash
+pnpm add @mingfuyun/star-allinone
+```
+
+2. 在项目根目录添加 `.star-allinone.json`：
+
+```json
+{
+  "project": "starscope-frontend",
+  "publicSkillPrefix": "shared-",
+  "serviceDir": "src/services",
+  "openapi": ".agents/project/openapi.json",
+  "publishPipelineId": "5108336"
+}
+```
+
+StarLink 示例见 `examples/projects/`。
+
+3. 同步公共 skill：
+
+```bash
+pnpm exec star-allinone skills sync
+```
+
+4. 把真正的业务特例放到 `.agents/skills/custom-*`。审查、提交、发布、Mock 和 Service 生成不要做成 `custom-*`。
+
+5. 提交配置和 skill：
+
+```bash
+git add .star-allinone.json .agents/skills
+git commit -m "chore(skill): 接入公共 skill"
+```
+
+### 业务项目：日常调用
+
+在 Codex / Cursor 对话里用 `$skill-name` 显式调用，例如：
+
+```text
+使用 $shared-api-to-service，为 GET /api/v1/devices/ 生成类型、Service 和 JSON Mock。
+```
+
+```text
+使用 $shared-design-to-page，根据我上传的设计稿生成页面。
+缺少的 Service、类型和 Mock 一并生成。
+```
+
+```text
+使用 $shared-review-and-submit，对当前变更执行提交前审查。
+等我确认后再提交。
+```
+
+```text
+使用 $shared-publish-test，把当前分支发布到测试环境。
+```
+
+公共流程用 `shared-*`，项目专属规则用 `custom-*`。业务定制 skill 需要复用公共流程时，在 `custom-*` 的 `SKILL.md` 里写明先读取对应的 `.agents/skills/shared-*/SKILL.md`。
+
+### 业务项目：更新公共 skill
+
+```bash
+pnpm update @mingfuyun/star-allinone
+pnpm exec star-allinone skills sync
+git add package.json pnpm-lock.yaml .agents/skills/shared-*
+git commit -m "chore(skill): 更新公共 skill"
+```
+
+其他成员只需：
+
+```bash
+git pull
+pnpm install
+```
+
+不要手动修改 `shared-*`。下次 `skills sync` 会覆盖这些目录。
+
 ### 在 Umi 项目中使用
 
 如果您的项目使用 **Umi** 框架，组件库会自动从您的项目中获取 `@umijs/max` 的能力（如 `useAccess`）。
@@ -593,4 +704,3 @@ MIT License
 ---
 
 Made with ❤️ by 星系运维团队
-

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@mingfuyun/star-allinone",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "星系运维前端能力包",
   "main": "dist/index.js",
+  "bin": {
+    "star-allinone": "scripts/cli.js"
+  },
   "types": "dist/index.d.ts",
   "style": "dist/index.css",
   "exports": {
@@ -25,12 +28,16 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "scripts/cli.js",
+    "skills"
   ],
   "scripts": {
     "build": "webpack --env format=umd --mode=none && webpack --env format=esm --mode=none",
     "publish": "node scripts/publish.js",
     "publish:dev": "node scripts/publish.js --dev",
+    "skills:sync": "node scripts/cli.js skills sync",
+    "skills:list": "node scripts/cli.js skills list",
     "prepublishOnly": "npm run build",
     "test": "echo \"Error: no test specified\" && exit 1",
     "dev": "webpack --mode=none --watch",

package/scripts/cli.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const root = path.resolve(__dirname, '..');
+const skillsRoot = path.join(root, 'skills', 'shared');
+const DEFAULT_PREFIX = 'shared-';
+const CUSTOM_PREFIX = 'custom-';
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function usage() {
+  console.log(`Usage:
+  star-allinone skills list
+  star-allinone skills sync [--target <dir>] [--dry-run]
+
+Run the command from a business project containing .star-allinone.json.
+
+Sync writes package skills/shared/* to <project>/.agents/skills/shared-*.
+It never writes ~/.codex/skills and never modifies custom-* skills.`);
+  process.exitCode = 1;
+}
+
+function listSharedSkillNames() {
+  if (!fs.existsSync(skillsRoot)) return [];
+  return fs.readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function listSkills() {
+  const skills = listSharedSkillNames();
+  if (!skills.length) {
+    console.log('No shared skills found.');
+    return;
+  }
+  for (const name of skills) {
+    console.log(`${name} -> ${DEFAULT_PREFIX}${name}`);
+  }
+}
+
+function parseArgs(args) {
+  const options = { dryRun: false };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--target') options.target = args[++index];
+    else positional.push(arg);
+  }
+  return { options, positional };
+}
+
+function render(content, variables) {
+  return content.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (_, key) => {
+    const value = key.split('.').reduce((current, part) => current?.[part], variables);
+    if (value === undefined || value === null) {
+      throw new Error(`Missing template variable: ${key}`);
+    }
+    return String(value);
+  });
+}
+
+function publicSkillName(skillName, prefix) {
+  return `${prefix}${skillName}`;
+}
+
+function assertSafeDestination(destination) {
+  const normalized = path.resolve(destination);
+  const codexSkills = path.resolve(os.homedir(), '.codex', 'skills');
+  if (normalized === codexSkills || normalized.startsWith(`${codexSkills}${path.sep}`)) {
+    throw new Error('Refusing to write to ~/.codex/skills');
+  }
+}
+
+const TEMPLATE_EXT = new Set(['.md', '.json', '.yml', '.yaml', '.txt']);
+
+function copyTree(source, target, variables, options, relativeRoot) {
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      if (!options.dryRun) fs.mkdirSync(targetPath, { recursive: true });
+      copyTree(sourcePath, targetPath, variables, options, relativeRoot);
+      continue;
+    }
+    const relativePath = path.relative(relativeRoot, targetPath);
+    console.log(`${options.dryRun ? '[dry-run] ' : ''}${relativePath}`);
+    if (options.dryRun) continue;
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    const ext = path.extname(entry.name).toLowerCase();
+    if (TEMPLATE_EXT.has(ext)) {
+      fs.writeFileSync(targetPath, render(fs.readFileSync(sourcePath, 'utf8'), variables));
+    } else {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+  }
+}
+
+function copySkill(source, destination, skillName, prefix, variables, options) {
+  const publicName = publicSkillName(skillName, prefix);
+  if (publicName.startsWith(CUSTOM_PREFIX)) {
+    throw new Error(`Public skill prefix cannot be "${CUSTOM_PREFIX}"`);
+  }
+  const skillTarget = path.join(destination, publicName);
+  if (!options.dryRun) {
+    fs.rmSync(skillTarget, { recursive: true, force: true });
+    fs.mkdirSync(skillTarget, { recursive: true });
+  }
+  copyTree(source, skillTarget, { ...variables, sharedSkillName: publicName }, options, destination);
+}
+
+function pruneStaleShared(destination, prefix, syncedNames, options) {
+  if (!fs.existsSync(destination)) return;
+  for (const entry of fs.readdirSync(destination, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith(CUSTOM_PREFIX)) continue;
+    if (!entry.name.startsWith(prefix)) continue;
+    if (syncedNames.includes(entry.name)) continue;
+    const relativePath = path.relative(destination, path.join(destination, entry.name));
+    console.log(`${options.dryRun ? '[dry-run] ' : ''}remove stale ${relativePath}`);
+    if (!options.dryRun) {
+      fs.rmSync(path.join(destination, entry.name), { recursive: true, force: true });
+    }
+  }
+}
+
+function selectedSharedSkills(config) {
+  const available = listSharedSkillNames();
+  if (!config.sharedSkills) return available;
+  const missing = config.sharedSkills.filter((name) => !available.includes(name));
+  if (missing.length) {
+    throw new Error(`Unknown sharedSkills: ${missing.join(', ')}`);
+  }
+  return available.filter((name) => config.sharedSkills.includes(name));
+}
+
+function syncProject(options) {
+  const target = path.resolve(options.target || process.cwd());
+  const configFile = path.join(target, '.star-allinone.json');
+  if (!fs.existsSync(configFile)) throw new Error(`Missing project config: ${configFile}`);
+  const config = readJson(configFile);
+  const prefix = config.publicSkillPrefix || DEFAULT_PREFIX;
+  const destination = path.join(target, '.agents', 'skills');
+  assertSafeDestination(destination);
+
+  const variables = { ...config, ...config.variables, project: { ...config, ...config.variables } };
+  const skills = selectedSharedSkills(config);
+  const syncedNames = skills.map((name) => publicSkillName(name, prefix));
+
+  if (!options.dryRun) fs.mkdirSync(destination, { recursive: true });
+  for (const skillName of skills) {
+    copySkill(path.join(skillsRoot, skillName), destination, skillName, prefix, variables, options);
+  }
+  pruneStaleShared(destination, prefix, syncedNames, options);
+  console.log(`${options.dryRun ? 'Would sync' : 'Synced'} shared skills -> ${destination}`);
+}
+
+function main() {
+  const [group, command, ...rest] = process.argv.slice(2);
+  if (group !== 'skills') return usage();
+  if (command === 'list') return listSkills();
+  if (command !== 'sync') return usage();
+  const { options, positional } = parseArgs(rest);
+  if (positional.length) return usage();
+  syncProject(options);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}

package/skills/README.md

@@ -0,0 +1,297 @@
+# Skills
+
+公共 skill 和业务定制 skill 都保存在业务项目仓库中，但通过目录命名和来源规则明确区分。
+
+不使用 Codex 全局目录 `~/.codex/skills`，也不要求团队成员拥有 `star-allinone` 源码。
+
+## 推荐目录
+
+以 `starscope-frontend` 为例：
+
+```text
+starscope-frontend/
+├── .star-allinone.json
+└── .agents/
+    ├── skills/
+    │   ├── shared-api-to-service/
+    │   ├── shared-api-mock/
+    │   ├── shared-design-to-page/
+    │   ├── shared-verify/
+    │   ├── shared-review-and-submit/
+    │   ├── shared-publish-test/
+    │   └── custom-device-management/
+    └── project/
+        ├── conventions.md
+        ├── review-rules.md
+        └── openapi.json
+```
+
+StarLink：
+
+```text
+starlink-frontend/
+└── .agents/
+    └── skills/
+        ├── shared-api-to-service/
+        ├── shared-api-mock/
+        ├── shared-design-to-page/
+        ├── shared-verify/
+        ├── shared-review-and-submit/
+        ├── shared-publish-test/
+        └── custom-node-management/
+```
+
+命名约定：
+
+```text
+shared-*   公共 skill，由 star-allinone 提供，经 CLI 同步后提交到业务仓库
+custom-*   业务定制 skill，由业务项目维护
+```
+
+这样所有 skill 都在业务项目中，Codex 可以直接发现；同时通过名称可以清楚区分来源。
+
+## npm 包的职责
+
+`@mingfuyun/star-allinone` 包中保存公共 skill 源文件。每个 skill 包含可执行规则，细节放在同目录 `references/`：
+
+```text
+@mingfuyun/star-allinone/
+└── skills/
+    └── shared/
+        ├── api-to-service/
+        │   ├── SKILL.md
+        │   └── references/
+        │       ├── service-conventions.md
+        │       └── api-artifact-generation.md
+        ├── api-mock/
+        ├── design-to-page/          # page-conventions.md + overlays.md
+        ├── project-conventions/     # architecture / review-checklist / quality-checklist
+        ├── verify/
+        ├── review-and-submit/
+        ├── impact-analysis/
+        ├── ai-review/
+        ├── commit-current-changes/
+        └── publish-test/              # 流水线 ID 从 .star-allinone.json 读取
+```
+
+公共 skill 写死两边已对齐的硬规则，例如：页面走 `MFRequest`、DTO 放 namespace typings、`MFProTable` + `ProForm`、弹层用 `BaseModal` / `CustomDrawer` / `HocModal`、`await` 必须 try/catch、禁止无说明的 `any`。
+
+业务项目的 `.agents/project/` 只写差异：路径、权限体系、OpenAPI 位置、领域特例。项目文件可以补充，但不能削弱公共硬规则。
+
+CLI 只做同步：
+
+```text
+npm 包中的 skills/shared
+        ↓
+业务项目 .agents/skills/shared-*
+```
+
+不会写入：
+
+```text
+~/.codex/skills
+```
+
+也不会管理业务项目的 `custom-*` skill。
+
+## CLI 使用方式
+
+在业务项目目录执行：
+
+```bash
+pnpm exec star-allinone skills sync
+```
+
+CLI 根据当前业务项目的 `.star-allinone.json`，直接将公共 skill 写入当前项目：
+
+```text
+当前项目/.agents/skills/shared-*/
+```
+
+例如：
+
+```bash
+cd /path/to/starscope-frontend
+pnpm exec star-allinone skills sync
+```
+
+结果：
+
+```text
+.agents/skills/
+├── shared-api-to-service/
+├── shared-api-mock/
+├── shared-review-and-submit/
+├── shared-publish-test/
+└── custom-*/
+```
+
+公共 skill 的更新不会影响业务定制 skill。同步会整体替换 `shared-*` 目录，并删除包中已不存在的过期 `shared-*`，但不会改动 `custom-*`。
+
+## 新增或修改公共 skill
+
+管理者操作：
+
+```text
+修改 star-allinone/skills/shared/api-to-service/SKILL.md
+→ 发布新版本 @mingfuyun/star-allinone
+```
+
+业务项目操作：
+
+```bash
+pnpm update @mingfuyun/star-allinone
+pnpm exec star-allinone skills sync
+git add package.json pnpm-lock.yaml .agents/skills/shared-*
+git commit -m "chore(skill): 更新公共 skill"
+```
+
+团队成员只需要：
+
+```bash
+git pull
+pnpm install
+```
+
+由于公共 skill 已经提交到业务仓库，所以团队成员不需要手动安装全局 skill，也不需要拥有 `star-allinone` 源码。
+
+## 新增或修改业务定制 skill
+
+业务项目直接维护：
+
+```text
+.agents/skills/custom-device-management/SKILL.md
+```
+
+提交即可：
+
+```bash
+git add .agents/skills/custom-device-management
+git commit -m "feat(skill): 增加设备管理 skill"
+```
+
+不需要修改 `star-allinone`，也不需要重新发布 npm。
+
+审查、提交、测试环境发布、Mock 和 Service 生成都走公共 skill。只有流水线 ID 放在业务项目的 `.star-allinone.json`。`custom-*` 只用于真正的业务特例，例如设备管理或节点管理。
+
+## 公共部分和业务定制组合
+
+例如业务定制 skill 需要复用公共 API 生成流程：
+
+```text
+.agents/skills/custom-device-service/SKILL.md
+```
+
+内容中引用公共 skill：
+
+```md
+---
+name: custom-device-service
+description: Generate StarScope device service code.
+---
+
+本任务需要结合公共 skill `shared-api-to-service` 执行。
+
+先读取并遵循：
+
+`.agents/skills/shared-api-to-service/SKILL.md`
+
+再读取当前项目的：
+
+- OpenAPI 文件
+- Service 约定
+- 项目类型和权限规则
+
+只生成符合当前项目结构的设备相关 service。
+```
+
+公共 skill 负责通用流程，业务 skill 负责具体业务规则。
+
+## 项目配置
+
+项目差异配置放在业务项目中，例如：
+
+```text
+starscope-frontend/
+├── .star-allinone.json
+└── .agents/
+    ├── skills/
+    └── project/
+        ├── conventions.md
+        ├── review-rules.md
+        └── openapi.json
+```
+
+```json
+{
+  "project": "starscope-frontend",
+  "publicSkillPrefix": "shared-",
+  "serviceDir": "src/services",
+  "openapi": ".agents/project/openapi.json",
+  "publishPipelineId": "5108336"
+}
+```
+
+StarLink 使用：
+
+```json
+{
+  "project": "starlink-frontend",
+  "publicSkillPrefix": "shared-",
+  "publishPipelineId": "5245265"
+}
+```
+
+完整示例见 `examples/projects/`。
+
+可选字段 `sharedSkills` 用于只同步部分公共 skill；省略时同步 `skills/shared` 下的全部公共 skill。
+
+## 公共规则写在哪里
+
+| Skill | 规则位置 | 覆盖内容 |
+| --- | --- | --- |
+| `shared-api-to-service` | SKILL + `references/service-conventions.md`、`api-artifact-generation.md` | 指定 operation、`MFRequest` 映射、namespace 类型、snake_case、schema 闭包、禁止改 transport |
+| `shared-api-mock` | SKILL + `references/mock-conventions.md` | 对话 JSON 默认、完整响应信封、分页/空列表/错误场景、禁止 handler 和随机数 |
+| `shared-design-to-page` | SKILL + `references/page-conventions.md`、`overlays.md` | 页面分层、`MFProTable`、`ProForm`、权限、异步、`HocModal` 弹层合同 |
+| `shared-project-conventions` | SKILL + `references/architecture.md`、`review-checklist.md`、`quality-checklist.md` | 架构边界、质量禁令、审查清单；其他 skill 会引用这些文件 |
+| `shared-verify` | SKILL | 成套产物检查、await/loading/弹层、验证命令和报告格式 |
+| `shared-impact-analysis` | SKILL | 只读影响分类和回归路径 |
+| `shared-ai-review` | SKILL | Hooks、契约、权限、性能、安全的 P0–P3 审查 |
+| `shared-commit-current-changes` | SKILL | 确认门禁、中文 Conventional Commit、禁止未确认就提交 |
+| `shared-review-and-submit` | SKILL | impact → verify → commit review 编排 |
+| `shared-publish-test` | SKILL + `scripts/publish-current-branch.sh` | 云效测试流水线发布；只从配置读 `publishPipelineId`；git push 后不自动跑，需单独确认「推送流水线」 |
+
+以下内容**不**写进公共 skill 源码：
+
+- 流水线 ID：放在业务项目 `.star-allinone.json` 的 `publishPipelineId`
+- OpenAPI 快照：业务仓库数据文件，路径由 `.star-allinone.json` 的 `openapi` 指向
+- 真正的业务特例：权限常量名、Clear Cache 登记、IP 校验、设备/节点领域规则，放 `custom-*`
+
+## 最终推荐流程
+
+公共 skill：
+
+```text
+star-allinone 修改
+→ 发布 npm
+→ 业务项目升级 npm
+→ 执行 skills sync
+→ 提交 .agents/skills/shared-*
+```
+
+业务定制 skill：
+
+```text
+业务项目直接新增或修改 custom-*
+→ 提交业务项目
+```
+
+最终结构和责任边界：
+
+```text
+.agents/skills/
+├── shared-*    ← npm 包同步，不能在业务项目直接维护
+└── custom-*    ← 业务项目自己维护
+```
+
+这比全局安装更适合团队协作，也比把公共 skill 藏在 `node_modules` 中更可靠，因为公共 skill 最终会进入业务项目仓库，团队成员拉取代码后即可直接使用。

package/skills/shared/ai-review/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: {{sharedSkillName}}
+description: Review frontend changes for correctness, API and permission contracts, React lifecycle, performance, maintainability, security, accessibility, and test gaps. Use for a standalone review without commit. Do not modify files.
+---
+
+# AI Code Review
+
+This skill is fully shared. Review the current diff plus relevant callers and types. Before reviewing, read:
+
+1. `.agents/skills/shared-project-conventions/references/review-checklist.md`
+2. `.agents/skills/shared-project-conventions/references/quality-checklist.md`
+
+Do not require a project-local review-rules file. If `.agents/project/review-rules.md` exists, apply extra domain checks only; do not weaken shared hard rules.
+
+## Required checks
+
+1. React Hooks: stale closures, incomplete dependencies, request races, updates after unmount, unnecessary rerenders.
+2. API contracts: method/path/params, response unwrapping, pagination, nullability, enum drift, error handling, DTO mismatch.
+3. Permissions: route access, button visibility, mutation authorization, client-only enforcement.
+4. Forms/tables: validation, reset, duplicate submit, refresh after mutation, column-state, long text, empty/error.
+5. Performance: eager `xlsx`/editor imports, duplicate libraries, large lists without virtualization, unstable columns/handlers, avoidable requests.
+6. Security/privacy: tokens, user data, URLs, unsafe HTML, sensitive logs, environment config.
+7. Tests and accessibility: critical paths, failure states, keyboard labels, disabled/loading semantics.
+
+## Output
+
+Lead with findings ordered `[P0]`–`[P3]`, with file and line. Separate blocking issues from recommendations. Do not report style preferences as bugs.
+
+If none, write `No issues found.` Always include validation performed and gaps. Do not modify files unless the user explicitly asks for fixes.

package/skills/shared/api-mock/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: {{sharedSkillName}}
+description: Generate deterministic API mock responses matching the active frontend project's OpenAPI contract and service types. Use when the user asks for JSON fixtures, proxy-ready mock data, empty or error scenarios, or mock files for a specified endpoint.
+---
+
+# API Mock
+
+This skill is fully shared. Read [references/mock-conventions.md](references/mock-conventions.md), `.star-allinone.json`, the related service types, and the OpenAPI file from `openapi` in `.star-allinone.json` (or the document provided in this conversation).
+
+If the service contract is missing, first follow `.agents/skills/shared-api-to-service/SKILL.md`.
+
+## Hard rules
+
+- OpenAPI and existing namespace types are authoritative. Do not invent undocumented fields.
+- Default output is labeled conversation JSON. Write `mock/<api-path>/<method>.json` only when the user explicitly asks for files.
+- Keep the complete backend envelope. Service callers see unwrapped `data`; mocks must not drop `code` / `message` / `data`.
+- Preserve snake_case, required fields, enums, nullability, and pagination totals.
+- Never add runtime handlers, `defineMock`, Faker, current timestamps, or unseeded randomness without an explicit request.
+- Cover requested scenarios only. Success is the default; empty, overflow, zero, validation, and permission cases need an explicit ask or a documented contract.
+
+## Handoff
+
+For every endpoint, report HTTP method, path, scenario label, and one strict parseable JSON block. If files were written, list the paths and confirm they parse as JSON.