@itradingai/aiwiki 0.2.19 → 0.2.21

package/README.md

@@ -43,6 +43,15 @@ aiwiki lint
 
 `lint` 会检查缺失链接、重复来源、fallback Wiki 条目、enriched 条目缺字段等问题，并写入 `dashboards/Lint Report.md`。
 
+## 示例
+
+仓库内置了一个由当前 CLI 重新生成的样例：
+
+- `examples/demo-run/`：输入材料、执行命令和关键 CLI 输出。
+- `examples/obsidian-vault-sample/`：可直接查看的样例知识库。
+
+样例展示了核心产物优先的约定：Raw、Source Card、Wiki Entry、Run Summary、Processing Summary 总是最先检查；Claim、Asset、Topic、Outline 只在 payload 有对应内容或明确请求时出现。
+
 ## 快速开始
 
 ### 第一步：安装 AIWiki CLI
@@ -55,7 +64,9 @@ aiwiki lint
 我的知识库路径：F:\knowledges
 
 请检查 Node.js >=20，执行 aiwiki setup --path "我的知识库路径" --yes，
-然后运行 aiwiki agent sync --yes 和 aiwiki agent check --json 完成宿主 Agent 对接。
+然后运行 aiwiki agent sync --yes、aiwiki agent check --json、
+aiwiki agent sync --path "我的知识库路径" --yes 和 aiwiki agent check --path "我的知识库路径" --json，
+完成宿主 Agent 与知识库根指导对接。
 最后执行 aiwiki doctor 和 aiwiki status，告诉我实际执行了哪些命令和还差什么手动步骤。
 ```
 
@@ -72,6 +83,8 @@ aiwiki agent check --json
 ```bash
 aiwiki agent sync --yes
 aiwiki agent check --json
+aiwiki agent sync --path "F:\knowledges" --yes
+aiwiki agent check --path "F:\knowledges" --json
 ```
 
 也可以直接输出通用协议：

package/dist/src/app.js

@@ -65,6 +65,7 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
         if (command === "agent" && subcommand === "sync") {
             const result = await syncAgentSkills({
                 agentId: flagString(args, "agent"),
+                workspaceRoot: flagString(args, "path"),
                 yes: flagBool(args, "yes"),
                 dryRun: flagBool(args, "dry-run"),
                 json: flagBool(args, "json"),
@@ -79,7 +80,7 @@ export async function runCli(argv, streams = { stdout: process.stdout, stderr: p
             return 0;
         }
         if (command === "agent" && subcommand === "check") {
-            await printAgentCheckDetailed(streams.stdout, await discoverAgentTargets(), flagBool(args, "json"));
+            await printAgentCheckDetailed(streams.stdout, await discoverAgentTargets(flagString(args, "path")), flagBool(args, "json"));
             return 0;
         }
         if (command === "agent" && (subcommand === "list" || !subcommand)) {
@@ -287,10 +288,12 @@ function printAgentHelp(stream) {
     writeLine(stream, "  aiwiki agent sync --yes");
     writeLine(stream, "  aiwiki agent sync --agent codex --yes");
     writeLine(stream, "  aiwiki agent sync --agent codex --dry-run");
+    writeLine(stream, "  aiwiki agent sync --path <workspace> --yes");
     writeLine(stream, "  aiwiki agent sync --json --yes");
     writeLine(stream, "");
     writeLine(stream, "Status:");
     writeLine(stream, "  aiwiki agent check");
+    writeLine(stream, "  aiwiki agent check --path <workspace> --json");
     writeLine(stream, "  aiwiki agent check --json");
     writeLine(stream, "");
     writeLine(stream, "Compatibility:");
@@ -324,7 +327,21 @@ function parseLintSeverity(value) {
     }
     throw new CliError("lint --severity must be error, warning, or info");
 }
-async function discoverAgentTargets() {
+const AIWIKI_AGENT_GUIDANCE_START = "<!-- AIWIKI:AGENT-GUIDANCE:START -->";
+const AIWIKI_AGENT_GUIDANCE_END = "<!-- AIWIKI:AGENT-GUIDANCE:END -->";
+const REQUIRED_AGENT_GUIDANCE_TERMS = [
+    "aiwiki setup",
+    "aiwiki agent sync",
+    "aiwiki agent check",
+    "aiwiki lint --json",
+    "aiwiki lint --fix-empty-dirs --json",
+    "aiwiki ingest-file",
+    "aiwiki ingest-agent",
+    "aiwiki status",
+    "aiwiki query",
+    "aiwiki context"
+];
+async function discoverAgentTargets(workspaceRoot) {
     const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
     const skillSource = path.join(packageRoot, "skill", "SKILL.md");
     const promptSource = path.join(packageRoot, "docs", "AGENT_HANDOFF.md");
@@ -334,7 +351,8 @@ async function discoverAgentTargets() {
     const claudeHome = process.env.CLAUDE_HOME ? path.resolve(process.env.CLAUDE_HOME) : path.join(os.homedir(), ".claude");
     const opencodeHome = process.env.OPENCODE_HOME ? path.resolve(process.env.OPENCODE_HOME) : path.join(os.homedir(), ".opencode");
     const hermesHome = process.env.HERMES_HOME ? path.resolve(process.env.HERMES_HOME) : path.join(process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local"), "hermes");
-    return [
+    const workspace = workspaceRoot ? path.resolve(workspaceRoot) : undefined;
+    const targets = [
         {
             id: "codex",
             name: "Codex",
@@ -392,6 +410,18 @@ async function discoverAgentTargets() {
             note: "已检测到，但暂未确认稳定的 skill 目录。请先使用 aiwiki prompt agent。"
         }
     ];
+    if (workspace) {
+        targets.unshift({
+            id: "workspace",
+            name: "Workspace AGENTS.md",
+            detected: await exists(workspace),
+            installable: true,
+            kind: "root_guidance",
+            target: path.join(workspace, "AGENTS.md"),
+            note: "安装 marker-bounded 根指导，要求宿主 Agent 在整理、检查、入库、查询、复用时优先调用 aiwiki CLI。"
+        });
+    }
+    return targets;
 }
 function printAgentList(stream, targets) {
     writeLine(stream, "AIWiki 宿主 Agent 目标");
@@ -432,6 +462,7 @@ async function printAgentCheckDetailed(stream, targets, json = false) {
                 installable: target.installable,
                 installed: target.installed,
                 state: target.state,
+                suggested_action: suggestedAgentAction(target),
                 source: target.source,
                 target: target.target
             }))
@@ -441,14 +472,21 @@ async function printAgentCheckDetailed(stream, targets, json = false) {
     writeLine(stream, "AIWiki Agent check");
     for (const target of checked) {
         writeLine(stream, `${target.id}: ${target.name} | detected=${target.detected ? "yes" : "no"} | installed=${target.installed ? "yes" : "no"} | installable=${target.installable ? "yes" : "no"} | state=${target.state}`);
-        if (target.detected && target.installable && (target.state === "missing" || target.state === "different")) {
-            writeLine(stream, `  suggested: aiwiki agent sync --agent ${target.id} --yes`);
-        }
-        else if (target.detected && !target.installable) {
-            writeLine(stream, "  suggested: aiwiki prompt agent");
+        const suggested = suggestedAgentAction(target);
+        if (suggested) {
+            writeLine(stream, `  suggested: ${suggested}`);
         }
     }
 }
+function suggestedAgentAction(target) {
+    if (target.detected && target.installable && (target.state === "missing" || target.state === "different")) {
+        return target.id === "workspace" ? `aiwiki agent sync --path "${path.dirname(target.target ?? ".")}" --yes` : `aiwiki agent sync --agent ${target.id} --yes`;
+    }
+    if (target.detected && !target.installable) {
+        return "aiwiki prompt agent";
+    }
+    return undefined;
+}
 async function installAgentSkill(options) {
     const targets = await discoverAgentTargets();
     const installable = targets.filter((target) => target.detected && target.installable);
@@ -503,7 +541,7 @@ async function askQuestion(streams, question) {
     }
 }
 async function syncAgentSkills(options) {
-    const targets = await discoverAgentTargets();
+    const targets = await discoverAgentTargets(options.workspaceRoot);
     const selected = options.agentId ? targets.find((target) => target.id === options.agentId) : undefined;
     if (!selected && options.agentId) {
         throw new CliError(`未知宿主 Agent: ${options.agentId}`);
@@ -546,6 +584,9 @@ async function copyInstallFileSafe(source, target, force) {
     return { action: targetExists ? "updated" : "installed", backupPath };
 }
 async function inspectAgentTarget(target) {
+    if (target.kind === "root_guidance") {
+        return inspectWorkspaceGuidanceTarget(target);
+    }
     if (!target.installable || !target.source || !target.target) {
         return "unsupported";
     }
@@ -567,7 +608,7 @@ async function syncAgentTarget(target, dryRun) {
         changed: false,
         dryRun
     };
-    if (state === "unsupported" || !target.source || !target.target) {
+    if (state === "unsupported" || !target.target || (!target.source && target.kind !== "root_guidance")) {
         return { ...base, action: "unsupported", note: target.note };
     }
     if (state === "current") {
@@ -576,9 +617,78 @@ async function syncAgentTarget(target, dryRun) {
     if (dryRun) {
         return { ...base, action: state === "missing" ? "would_install" : "would_update", changed: true };
     }
+    if (target.kind === "root_guidance") {
+        const result = await syncWorkspaceGuidanceTarget(target);
+        return { ...base, action: result.action, backupPath: result.backupPath, changed: result.action !== "current" };
+    }
     const result = await copyInstallFileSafe(target.source, target.target, true);
     return { ...base, action: result.action, backupPath: result.backupPath, changed: result.action !== "current" };
 }
+async function inspectWorkspaceGuidanceTarget(target) {
+    if (!target.target || !target.detected) {
+        return "missing";
+    }
+    if (!(await exists(target.target))) {
+        return "missing";
+    }
+    const content = await fs.readFile(target.target, "utf8");
+    const block = extractWorkspaceGuidanceBlock(content);
+    if (!block) {
+        return "different";
+    }
+    return block.trim() === workspaceGuidanceBlock().trim() && REQUIRED_AGENT_GUIDANCE_TERMS.every((term) => block.includes(term)) ? "current" : "different";
+}
+async function syncWorkspaceGuidanceTarget(target) {
+    if (!target.target) {
+        return { action: "unsupported" };
+    }
+    const targetExists = await exists(target.target);
+    const existing = targetExists ? await fs.readFile(target.target, "utf8") : "";
+    const next = mergeWorkspaceGuidance(existing);
+    if (targetExists && existing === next) {
+        return { action: "current" };
+    }
+    const backupPath = targetExists ? await backupFile(target.target) : undefined;
+    await fs.mkdir(path.dirname(target.target), { recursive: true });
+    await fs.writeFile(target.target, next, "utf8");
+    return { action: targetExists ? "updated" : "installed", backupPath };
+}
+function extractWorkspaceGuidanceBlock(content) {
+    const start = content.indexOf(AIWIKI_AGENT_GUIDANCE_START);
+    const end = content.indexOf(AIWIKI_AGENT_GUIDANCE_END);
+    if (start === -1 || end === -1 || end < start) {
+        return undefined;
+    }
+    return content.slice(start, end + AIWIKI_AGENT_GUIDANCE_END.length);
+}
+function mergeWorkspaceGuidance(existing) {
+    const block = workspaceGuidanceBlock();
+    const start = existing.indexOf(AIWIKI_AGENT_GUIDANCE_START);
+    const end = existing.indexOf(AIWIKI_AGENT_GUIDANCE_END);
+    if (start !== -1 && end !== -1 && end > start) {
+        return `${existing.slice(0, start)}${block}${existing.slice(end + AIWIKI_AGENT_GUIDANCE_END.length)}`;
+    }
+    const trimmed = existing.trimEnd();
+    return `${trimmed}${trimmed ? "\n\n" : ""}${block}\n`;
+}
+function workspaceGuidanceBlock() {
+    return `${AIWIKI_AGENT_GUIDANCE_START}
+# AIWiki Agent Command Contract
+
+When a user asks to organize, inspect, ingest, query, reuse, or maintain this AIWiki workspace, call the AIWiki CLI first. Do not start with generic file search, grep/find scans, or ad hoc note edits unless the AIWiki command cannot answer the request.
+
+Required command-first loop:
+
+1. Ensure the workspace exists with \`aiwiki setup --path <workspace> --yes\`.
+2. Keep host-Agent guidance current with \`aiwiki agent sync --path <workspace> --yes\` and verify with \`aiwiki agent check --path <workspace> --json\`.
+3. Inspect structure with \`aiwiki lint --json --path <workspace>\`; apply only safe fixes with \`aiwiki lint --fix-empty-dirs --json --path <workspace>\` when allowed, then rerun \`aiwiki lint --json --path <workspace>\`.
+4. Ingest local material with \`aiwiki ingest-file --file <file> --path <workspace>\` or structured Agent material with \`aiwiki ingest-agent --stdin --path <workspace>\`.
+5. Check progress with \`aiwiki status --path <workspace>\`.
+6. Retrieve reusable knowledge with \`aiwiki query <topic> --path <workspace>\` for human-readable output or \`aiwiki context <topic> --path <workspace>\` for Agent JSON.
+
+Use fallback shell/file search only after the relevant AIWiki command has been tried or when the command is unavailable. If you fall back, say which AIWiki command was insufficient and why.
+${AIWIKI_AGENT_GUIDANCE_END}`;
+}
 async function sameFileContent(source, target) {
     try {
         const [sourceText, targetText] = await Promise.all([fs.readFile(source, "utf8"), fs.readFile(target, "utf8")]);

package/docs/AGENT_HANDOFF.md

@@ -24,6 +24,32 @@ AIWiki CLI 不做通用网页抓取，也不调用 LLM。网页读取失败时
 
 证据和疑似风险要分开：`source_quote` 等能回到原文的字段是宿主提供的 evidence/provenance；`coverage_suspected_incomplete`、`unsupported_claims`、`needs_review` 是 AIWiki 的复核提示，不代表已经证明遗漏或错误。
 
+## 命令优先契约
+
+宿主 Agent 处理 AIWiki 任务时，必须先调用 AIWiki 自带命令，再考虑通用文件搜索或临时脚本。否则只是绕过了知识库能力，用户看不到 lint、status、query/context 和入库记录的价值。
+
+项目或知识库根目录先同步根指导：
+
+```bash
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
+```
+
+日常闭环按这个顺序执行：
+
+```bash
+aiwiki setup --path <workspace> --yes
+aiwiki lint --json --path <workspace>
+aiwiki lint --fix-empty-dirs --json --path <workspace>
+aiwiki ingest-file --file <file> --path <workspace>
+aiwiki ingest-agent --stdin --path <workspace>
+aiwiki status --path <workspace>
+aiwiki query <topic> --path <workspace>
+aiwiki context <topic> --path <workspace>
+```
+
+只有当对应 AIWiki 命令无法回答问题时，才退回到 `rg`、`find`、`grep` 或手工读取文件；退回时要说明哪个 AIWiki 命令不够用。
+
 ## 标准流程
 
 1. 读取用户给的 URL、正文、附件或消息。
@@ -45,6 +71,7 @@ aiwiki ingest-agent --payload <utf8-json-file>
 ```
 
 9. 读取 CLI 输出，向用户回复入库状态、摘要、Wiki 条目、质量模式、资料卡和处理记录。
+10. 汇报产物时先说核心产物：Raw、Source Card、Wiki Entry、Run Summary、Processing Summary。Claim、Asset、Topic、Outline 只在本次 CLI 输出或文件中真实存在时再提。
 
 ## 编码要求
 

package/docs/FAQ.md

@@ -55,6 +55,8 @@ AIWiki 是一个开源的 Agent-first 本地 LLM-wiki CLI。宿主 Agent 负责
 npx @itradingai/aiwiki@latest setup
 aiwiki agent sync --yes
 aiwiki agent check --json
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
 ```
 
 然后去看：
@@ -63,6 +65,10 @@ aiwiki agent check --json
 - [SHOWCASE.md](SHOWCASE.md)
 - [AGENT_HANDOFF.md](AGENT_HANDOFF.md)
 
+## 有没有可以直接看的样例？
+
+有。`examples/demo-run/` 记录输入、命令和 CLI 输出；`examples/obsidian-vault-sample/` 是已经生成好的样例知识库。它展示了核心产物优先，以及可选增强目录只在有内容时出现。
+
 ## 怎么从知识库里查询？
 
 让宿主 Agent 调用：
@@ -80,3 +86,15 @@ aiwiki lint
 ```
 
 如果只是清理旧版本留下的空可选增强目录，可以让 Agent 先运行 `aiwiki lint --json`，确认只有 safe fix 后再运行 `aiwiki lint --fix-empty-dirs --json`。
+
+## 为什么我的 Agent 还是在直接翻文件？
+
+通常是它没有加载 AIWiki skill，或者知识库根目录缺少 AIWiki 的 `AGENTS.md` 指导。先运行：
+
+```bash
+aiwiki agent sync --yes
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
+```
+
+之后再让 Agent 处理 AIWiki 任务。它应该优先调用 `aiwiki lint --json`、`aiwiki status`、`aiwiki query`、`aiwiki context`、`aiwiki ingest-file` 或 `aiwiki ingest-agent`。只有这些命令不够用时，才退回到通用文件搜索。

package/docs/README.md

@@ -11,6 +11,11 @@ AIWiki 是一个 Agent-first 的本地知识库工具，用来把宿主 Agent
 - 路线图：[ROADMAP.md](ROADMAP.md)
 - 开发记录：[development-log.md](development-log.md)
 
+## Examples
+
+- `../examples/demo-run/` records the input files, commands, and CLI outputs from a regenerated demo.
+- `../examples/obsidian-vault-sample/` is a sample vault showing the current core-first artifact contract.
+
 ## Quick Start
 
 ```bash

package/docs/RELEASE.md

@@ -21,28 +21,21 @@ npm version patch --no-git-tag-version
 
 ## npm 发布
 
-发布前确认 npm 登录账号：
+发布前必须先让同一个本地 tarball 在测试服务器通过 smoke test。顺序是：本地验证、版本号、提交、本地 `npm pack`、测试服务器安装 tarball 并跑 CLI smoke，然后才能 `git push` 和 `npm publish`。
 
-```bash
-npm whoami
-```
+AIWiki 使用 npm Trusted Publishing。npm 发布应由 GitHub Actions 的 `.github/workflows/publish.yml` 完成，不依赖本机 `npm login`、OTP 或长期 `NPM_TOKEN`。
 
-正式发布：
+远程测试和 GitHub push 都通过后，触发发布 workflow：
 
 ```bash
-npm publish --access public
+gh workflow run publish.yml --repo iTradingAI/aiwiki
+gh run watch --repo iTradingAI/aiwiki
 ```
 
-如果账号开启了 publish 2FA，普通 token 可能只能 `whoami`，但发布时仍会要求 OTP。此时有两种方式：
+如需查看最近一次发布任务：
 
 ```bash
-npm publish --access public --otp <OTP>
-```
-
-或使用 npm Automation token 写入用户级 `.npmrc`：
-
-```bash
-npm config set //registry.npmjs.org/:_authToken "<NPM_AUTOMATION_TOKEN>"
+gh run list --workflow publish.yml --repo iTradingAI/aiwiki --limit 5
 ```
 
 发布后验证：
@@ -52,6 +45,8 @@ npm view @itradingai/aiwiki version
 npm view @itradingai/aiwiki versions --json
 ```
 
+如果 workflow 提示 Trusted Publishing / OIDC 权限问题，检查 npm 包设置里的 Trusted Publisher 是否指向 `iTradingAI/aiwiki` 和 workflow 文件名 `publish.yml`，并确认 workflow 顶层包含 `permissions: id-token: write`。
+
 ## 包体积
 
 npm 包只应包含 CLI 运行和用户文档所需文件。README 中的图片使用 GitHub raw 链接展示，`docs/assets/` 不进入 npm 包。

package/docs/ROADMAP.md

@@ -13,6 +13,7 @@ AIWiki 对外只有一个项目，所以这里写的是能力路线，不是版
 - 更稳定的 Agent handoff
 - 更完整的 Obsidian 审阅入口
 - 更容易追查失败原因
+- 更稳定的公开样例，让新用户先看到真实生成的核心产物
 
 ## 2. 更完整的内容处理能力
 

package/docs/SHOWCASE.md

@@ -19,35 +19,38 @@
 
 ### AIWiki 会写什么
 
+核心产物优先看这些：
+
 ```text
 09-runs/<run-id>/payload.json
 09-runs/<run-id>/raw.md
 09-runs/<run-id>/source-card.md
 09-runs/<run-id>/wiki-entry.md
-09-runs/<run-id>/creative-assets.md
-09-runs/<run-id>/topics.md
-09-runs/<run-id>/draft-outline.md
 09-runs/<run-id>/processing-summary.md
+02-raw/articles/<slug>.md
+03-sources/article-cards/<slug>.md
+05-wiki/source-knowledge/<slug>.md
 ```
 
-### 长期目录会出现什么
+只有在宿主 Agent 提供了对应内容，或 payload 明确请求时，才会出现可选增强产物：
 
 ```text
-02-raw/articles/
-03-sources/article-cards/
+09-runs/<run-id>/creative-assets.md
+09-runs/<run-id>/topics.md
+09-runs/<run-id>/draft-outline.md
 04-claims/_suggestions/
-05-wiki/source-knowledge/
 06-assets/_suggestions/
 07-topics/ready/
 08-outputs/outlines/
-dashboards/
 ```
 
+仓库里的 `examples/obsidian-vault-sample/` 同时包含一个普通本地文件入库和一个 enriched Agent payload 入库。前者只生成核心产物，后者因为包含 claims、topic candidates、creative assets 和 outline 请求，所以生成可选增强目录。
+
 ### 用户在 Obsidian 里怎么看
 
 - 打开 `dashboards/AIWiki Home.md`
 - 查看 `05-wiki/source-knowledge/<slug>.md`
-- 从 Wiki 条目回到资料卡、原文、选题、大纲和处理记录
+- 从 Wiki 条目回到资料卡、原文和处理记录；如果这次入库生成了选题、大纲或 Claim，再继续查看对应可选产物
 - 需要结构检查时运行 `aiwiki lint`
 
 ## 示例 2：网页没读到正文
@@ -81,3 +84,10 @@ dashboards/
 - AIWiki 负责稳定写入本地知识库
 - AIWiki 会创建 Wiki Entry；没有 Agent 分析字段时只生成可追溯脚手架
 - 结果始终可追踪、可复盘、可继续写作
+
+## 本仓库样例
+
+- `examples/demo-run/`：输入、命令和 CLI 输出。
+- `examples/obsidian-vault-sample/`：已经生成好的样例知识库。
+
+这个样例不依赖爬虫、向量库、RAG 或 Pro 自动化；它只展示基础 CLI 的真实落盘结果。

package/docs/USAGE.md

@@ -61,8 +61,12 @@ aiwiki status
 ```bash
 aiwiki agent sync --yes
 aiwiki agent check --json
+aiwiki agent sync --path <workspace> --yes
+aiwiki agent check --path <workspace> --json
 ```
 
+前两条同步本机宿主 Agent 的 skill/command，后两条在知识库根目录写入或刷新 marker-bounded `AGENTS.md` 指导。这样新的宿主 Agent 进入项目时，会先看到“必须调用 aiwiki CLI”的约束，而不是直接走默认文件搜索流程。
+
 旧的安装向导仍然兼容，但不再作为首选路径：
 
 ```bash
@@ -93,7 +97,9 @@ aiwiki prompt agent
 
 把输出内容安装成宿主 Agent 的 skill，或粘贴到宿主 Agent 的项目/会话说明里。不同 Agent 的安装入口不同，所以 AIWiki 提供自动安装向导和通用协议两条路径。
 
-`aiwiki agent check --json` 用来确认本机检测到哪些宿主 Agent、哪些已经安装 AIWiki 对接文件、哪些还需要运行 `aiwiki agent sync --agent <id> --yes`。
+`aiwiki agent check --json` 用来确认本机检测到哪些宿主 Agent、哪些已经安装 AIWiki 对接文件、哪些还需要运行 `aiwiki agent sync --agent <id> --yes`。`aiwiki agent check --path <workspace> --json` 会同时检查知识库根目录的 `AGENTS.md` 是否包含当前 AIWiki 命令优先指导，缺失或过期时会提示运行 `aiwiki agent sync --path <workspace> --yes`。
+
+如果宿主 Agent 只用 `rg`、`find`、`grep` 或手工读文件来回答 AIWiki 问题，而没有先运行 `aiwiki lint --json`、`aiwiki status`、`aiwiki query` 或 `aiwiki context`，就说明它没有真正使用 AIWiki 的知识库闭环。
 
 ## 3. 日常使用
 
@@ -186,29 +192,25 @@ Obsidian 入口：dashboards/AIWiki Home.md
 
 ## 5. 成功后会生成什么
 
-每次 run 会写入：
+每次成功 run 先看核心产物：
 
 ```text
 09-runs/<run-id>/payload.json
 09-runs/<run-id>/raw.md
 09-runs/<run-id>/source-card.md
-09-runs/<run-id>/creative-assets.md
-09-runs/<run-id>/topics.md
-09-runs/<run-id>/draft-outline.md
+09-runs/<run-id>/wiki-entry.md
 09-runs/<run-id>/processing-summary.md
-```
-
-同时写入长期目录：
-
-```text
 02-raw/articles/
 03-sources/article-cards/
 05-wiki/source-knowledge/
 ```
 
-可选增强目录只在有对应内容或 `request.outputs` 明确请求时生成：
+只有 payload 有对应内容或 `request.outputs` 明确请求时，才会出现可选增强产物：
 
 ```text
+09-runs/<run-id>/creative-assets.md
+09-runs/<run-id>/topics.md
+09-runs/<run-id>/draft-outline.md
 04-claims/_suggestions/
 06-assets/_suggestions/
 07-topics/ready/
@@ -217,6 +219,8 @@ Obsidian 入口：dashboards/AIWiki Home.md
 
 `05-wiki/source-knowledge` 是默认知识层；`09-runs` 用于追溯每次处理。
 
+可以直接查看仓库里的 `examples/demo-run/` 和 `examples/obsidian-vault-sample/`，它们由当前 CLI 生成，展示普通本地文件只生成核心产物、enriched Agent payload 才生成可选增强产物。
+
 Wiki Entry 有两种质量模式：
 
 - `agent_enriched` / `enriched`：宿主 Agent 提供了 `analysis` 或 `wiki_entry`。

package/examples/demo-run/README.md

@@ -0,0 +1,28 @@
+# AIWiki Demo Run
+
+This folder records one generated run from the current CLI contract.
+
+## Inputs
+
+- `input/local-article.md`: local Markdown input for `aiwiki ingest-file`.
+- `input/agent-enriched-payload.json`: host-Agent payload with `analysis`, claims, topics, assets, and outline requests.
+
+## Commands
+
+```bash
+aiwiki setup --path ../obsidian-vault-sample --yes
+aiwiki ingest-file --file input/local-article.md --path ../obsidian-vault-sample
+aiwiki ingest-agent --payload input/agent-enriched-payload.json --path ../obsidian-vault-sample
+aiwiki status --path ../obsidian-vault-sample
+aiwiki query "LLM Wiki" --path ../obsidian-vault-sample
+aiwiki context "LLM Wiki" --path ../obsidian-vault-sample
+aiwiki lint --json --path ../obsidian-vault-sample
+```
+
+The captured `*-output.*` files replace machine-specific paths with `<sample-vault>` and `<aiwiki-home>`.
+
+## What To Inspect
+
+- Core artifacts appear for both examples: Raw, Source Card, Wiki Entry, Run Summary, and Processing Summary.
+- Optional directories are absent for the plain local-file ingest.
+- Optional claims, assets, topics, and outline appear only for the enriched Agent payload that requested or supplied them.