@itradingai/aiwiki 0.2.18 → 0.2.20

package/docs/USAGE.md

@@ -56,14 +56,14 @@ aiwiki status
 
 ## 2. 让宿主 Agent 学会 AIWiki
 
-初始化知识库之后，先让宿主 Agent 学会 AIWiki。推荐先扫描本机支持的宿主 Agent：
+初始化知识库之后，先让宿主 Agent 学会 AIWiki。主路径推荐使用幂等同步：
 
 ```bash
-aiwiki agent list
-aiwiki agent check
+aiwiki agent sync --yes
+aiwiki agent check --json
 ```
 
-再启动安装向导：
+旧的安装向导仍然兼容，但不再作为首选路径：
 
 ```bash
 aiwiki agent install
@@ -93,7 +93,7 @@ aiwiki prompt agent
 
 把输出内容安装成宿主 Agent 的 skill，或粘贴到宿主 Agent 的项目/会话说明里。不同 Agent 的安装入口不同，所以 AIWiki 提供自动安装向导和通用协议两条路径。
 
-`aiwiki agent check` 用来确认本机检测到哪些宿主 Agent、哪些已经安装 AIWiki 对接文件、哪些还需要运行 `aiwiki agent install --agent <id> --yes`。
+`aiwiki agent check --json` 用来确认本机检测到哪些宿主 Agent、哪些已经安装 AIWiki 对接文件、哪些还需要运行 `aiwiki agent sync --agent <id> --yes`。
 
 ## 3. 日常使用
 
@@ -127,7 +127,7 @@ source_url: https://example.com/article
 summary: 这里是文章前段摘要，方便 Agent 快速告诉用户文章大意。
 run_id: 20260507-153012-abc123
 run_dir: F:\knowledge_data\aiwiki\09-runs\20260507-153012-abc123
-files: 15
+files: 8
 processing_summary: 09-runs/20260507-153012-abc123/processing-summary.md
 wiki_entry: 05-wiki/source-knowledge/article-slug.md
 wiki_entry_generation_mode: agent_enriched
@@ -138,7 +138,7 @@ grounding_needs_review: no
 grounding_markers: none
 grounding_claims_with_quotes: 1/1
 source_card: 03-sources/article-cards/article-slug.md
-draft_outline: 09-runs/20260507-153012-abc123/draft-outline.md
+draft_outline: 09-runs/20260507-153012-abc123/draft-outline.md  # 仅在生成大纲时出现
 dashboard: dashboards/AIWiki Home.md
 review_queue: dashboards/Review Queue.md
 warnings: 0
@@ -186,25 +186,26 @@ 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
+02-raw/articles/
+03-sources/article-cards/
+05-wiki/source-knowledge/
 ```
 
-同时写入长期目录：
+只有 payload 有对应内容或 `request.outputs` 明确请求时，才会出现可选增强产物：
 
 ```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/
@@ -212,6 +213,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`。
@@ -252,10 +255,10 @@ AIWiki 生成的 Markdown 按 Obsidian vault 内路径组织，文件正文会
 
 链接规则：
 - wikilink 使用 vault 相对路径，统一为 `/`，并去掉 `.md` 后缀。
-- `05-wiki/source-knowledge` 是默认知识入口；`03-sources/article-cards` 会链接到 Wiki 条目、原文、Claim 建议、素材建议、选题、大纲和本次处理记录。
-- `02-raw/articles`、`04-claims/_suggestions`、`06-assets/_suggestions`、`07-topics/ready`、`08-outputs/outlines` 会回链到资料卡，Obsidian 的 Backlinks/Graph View 可以串起同一篇资料。
+- `02-raw/articles`、`03-sources/article-cards`、`05-wiki/source-knowledge` 和 `09-runs/<run-id>` 是核心产物；`04-claims/_suggestions`、`06-assets/_suggestions`、`07-topics/ready`、`08-outputs/outlines` 只在 payload 有对应内容或 `request.outputs` 明确请求时生成。
+- `03-sources/article-cards` 只链接本次实际生成的可选增强产物，避免空目录和断链。
 - `09-runs/<run-id>/processing-summary.md` 会把本次生成的 Markdown 文件列成可点击 wikilink；`payload.json` 不是 Markdown，保留普通路径。
-- frontmatter 会写入 `aiwiki_id`、`type`、`status`、`slug`、`source_url`、`content_fingerprint`、`created_at`、`captured_at`、`run_id`、`source_card`、`raw_note`、`claims_note`、`assets_note`、`topics_note`、`outline_note`、`run_summary`、`tags` 等字段，便于后续用 Obsidian Search / Properties / Dataview 做筛选。
+- frontmatter 会写入 `aiwiki_id`、`type`、`status`、`slug`、`source_url`、`content_fingerprint`、`created_at`、`captured_at`、`run_id`、`source_card`、`raw_note`、`run_summary` 等核心字段；`claims_note`、`assets_note`、`topics_note`、`outline_note` 只在对应产物存在时出现。
 
 ### Obsidian 数据库入口
 
@@ -324,9 +327,10 @@ aiwiki lint
 aiwiki lint --severity warning
 aiwiki lint --json
 aiwiki lint --no-write
+aiwiki lint --fix-empty-dirs --json
 ```
 
-`lint` 会先输出 `lint_summary`、`top_issue` 和报告路径，再按 Errors / Warnings / Info 分组展示问题。每个问题会尽量给出建议动作，例如 `enrich`、`fix_link`、`reingest`、`archive` 或 `mark_reviewed`。`--severity` 只查看指定级别，`--json` 给宿主 Agent 使用，`--no-write` 只在终端检查而不更新 `dashboards/Lint Report.md`。
+`lint` 会先输出 `lint_summary`、`safe_fixes`、`top_issue` 和报告路径，再按 Errors / Warnings / Info 分组展示问题。每个问题会尽量给出建议动作，例如 `enrich`、`fix_link`、`reingest`、`archive`、`mark_reviewed` 或 `remove_empty_optional_dir`。`--severity` 只查看指定级别，`--json` 给宿主 Agent 使用，`--no-write` 只在终端检查而不更新 `dashboards/Lint Report.md`。`--fix-empty-dirs --json` 只会删除已知且为空的可选增强目录，并在 `safe_fixes.applied` 里报告删除了什么。
 
 查看下一步建议：
 

package/docs/development-log.md

@@ -2,6 +2,233 @@
 
 This log records queue-driven AIWiki development milestones that should remain visible to future maintainers, not only in automation chat history.
 
+## 2026-06-08 - Base contract cleanup and safe optional directory pruning
+
+Status: implemented and locally verified, committed locally, blocked before GitHub push and npm publication. Test-server verification is now required before both GitHub push and npm publication.
+
+Version target: `@itradingai/aiwiki@0.2.19`
+
+Commit: `3ae25b9` (`Stabilize AIWiki base contract before public-trial work`)
+
+### Goal
+
+Make the base AIWiki experience quieter and more reliable before public-trial work. A new workspace should show the core knowledge workflow first, not a set of empty enhancement directories or legacy command paths. Agents should also have a safe, machine-readable way to detect and remove only empty optional directories.
+
+The scoped acceptance criteria were:
+
+- keep the main help and quick-start path focused on setup, Agent sync/check, ingest, context/query, lint, status, and doctor;
+- preserve legacy command behavior without presenting legacy commands as the primary path;
+- create only core directories by default in new workspaces;
+- create optional long-term directories only when ingest actually writes related outputs;
+- treat missing optional directories as normal in doctor and directory summaries;
+- report empty optional directories as safe-fix lint issues with stable JSON metadata;
+- make `lint --fix-empty-dirs --json` delete only known empty optional directories and empty known optional parent directories;
+- keep the base CLI out of crawling, vector search, RAG-over-wiki, RBAC, RSS, scheduled collection, and browser-plugin scope.
+
+### Implemented
+
+- `src/workspace.ts`
+  - Split core directories from optional enhancement directories.
+  - Made setup/init/doctor summaries core-first.
+  - Kept optional directories valid when they already exist, but stopped requiring them for a healthy workspace.
+
+- `src/payload.ts`, `src/ingest.ts`, and `src/wiki-entry.ts`
+  - Preserved `request.outputs` as an additive request instead of normalizing every ingest into all optional artifacts.
+  - Kept core ingest artifacts stable: Source Card, Wiki Entry, and Processing Summary.
+  - Created claims, assets, topics, and outline files only when payload content or explicit outputs require them.
+  - Omitted optional frontmatter links when the corresponding files are not written.
+
+- `src/lint.ts` and `src/app.ts`
+  - Added safe-fix metadata for empty known optional directories.
+  - Added `safe_fixes.available`, `safe_fixes.applied`, and `safe_fixes.only_safe_fixes` to JSON output.
+  - Added `aiwiki lint --fix-empty-dirs --json`.
+  - Kept deletion deliberately narrow: known optional empty directories only, never core directories, unknown directories, non-empty directories, or files.
+  - Reduced main help to the core user path while preserving existing command behavior.
+
+- Documentation and packaged skill files
+  - Updated README, usage docs, FAQ, Agent handoff, lint protocol, and skill instructions for the core-first workflow.
+  - Documented the Agent flow: run `aiwiki lint --json`, apply safe fixes only when allowed, rerun lint, and report the changed directories.
+  - Tightened package file inclusion so unrelated untracked docs are not accidentally packed.
+
+- Tests
+  - Updated workspace tests for the smaller default directory contract.
+  - Added ingest coverage for minimal output behavior.
+  - Added CLI coverage for `lint --fix-empty-dirs --json` and help/setup guidance.
+
+### Verification
+
+- `npm test`: passed, 59 tests.
+- `npm run release:check`: passed, including tests and `scripts/release-check.mjs`.
+- `npm pack --dry-run`: passed for `@itradingai/aiwiki@0.2.19`, 35 files, package size 77.1 kB, shasum `3f436503bb0dc3019b188941f06f3c518bbecc0b`.
+- Verification used `D:/Program Files/nodejs/npm.cmd` with a repo-local npm cache because the PowerShell `npm` shim points to a missing `C:/Users/Max/AppData/Roaming/npm/npm-cli.js`.
+
+### Release State
+
+The implementation is committed locally, but the GitHub push failed before publication:
+
+```text
+Warning: Identity file C:/Users/Max/.ssh/id_ed25519 not accessible: Permission denied.
+git@github.com: Permission denied (publickey).
+fatal: Could not read from remote repository.
+```
+
+Because GitHub push failed, npm publication was not attempted. The task queue and human board are marked `blocked`, and the Enterprise WeChat blocked notification was delivered successfully with HTTP 200 / `errcode:0`.
+
+### Testing Server Gate
+
+Test-server verification must run before updating GitHub or npm.
+
+The release gate for `0.2.19` is now a pre-GitHub and pre-npm tarball smoke test: create the exact local npm tarball that would be published, copy that `.tgz` to a task-specific directory on `170.106.73.197`, install it into a task-local Node project, and run the same smoke commands against that installed package. This proves the package artifact before it reaches GitHub or npm.
+
+The older published-package smoke test remains useful after npm publication as a final registry sanity check, but it is no longer allowed to be the first remote test. Pushing to GitHub or publishing to npm before test-server verification would make a public delivery surface the first real deployment surface, which is the wrong order for this queue.
+
+Required prepublication smoke commands:
+
+```bash
+aiwiki setup --path <tmp-vault> --yes
+aiwiki doctor --path <tmp-vault>
+inspect that only core directories are created by default
+aiwiki ingest-agent --payload <minimal-fixture> --path <tmp-vault>
+inspect that optional output directories remain absent unless needed
+aiwiki lint --json --path <tmp-vault>
+aiwiki lint --fix-empty-dirs --json --path <tmp-vault>
+aiwiki context <topic> --path <tmp-vault>
+aiwiki query <topic> --path <tmp-vault>
+```
+
+The smoke test must use only a task-specific temporary directory on the remote server. Do not install globally, do not reuse a real user vault, and do not clean outside the task directory.
+
+### Resume Steps
+
+Remote tarball smoke must pass first. Only after that, restore SSH key access for the current runtime user or configure GitHub authentication so this succeeds:
+
+```powershell
+git push origin main
+```
+
+Then continue the release chain:
+
+```powershell
+npm publish --access public
+npm view @itradingai/aiwiki version
+```
+
+After `npm view` returns `0.2.19`, a short published-package registry sanity check can be run, but the blocking test-server gate must already have passed before both GitHub push and npm publish.
+
+### Notes For Future Changes
+
+- Keep optional directories optional. Do not reintroduce required empty claims/assets/topics/outlines directories in new workspaces.
+- Keep safe fixes narrow and auditable. Do not let `--fix-empty-dirs` delete files, core directories, unknown directories, or non-empty directories.
+- Keep main help focused on the core path. Legacy commands can remain compatible without being promoted as first-run guidance.
+- Test-server verification from the local npm tarball must happen before GitHub push and before npm publication. Local pack verification alone is not enough to update GitHub or npm.
+
+## 2026-06-07 - Agent-first skill sync
+
+Status: implemented, locally verified, pushed to GitHub, blocked on npm OTP before publication.
+
+Version target: `@itradingai/aiwiki@0.2.18`
+
+Commit: `e41d634` (`Make Agent skill upgrades safe to sync automatically`)
+
+### Goal
+
+Make AIWiki skill upgrades safe for Agent-first operation. The intended user path is that a host AI Agent can upgrade AIWiki, synchronize its local skill instructions, tell the user what changed, and preserve a rollback path without requiring the user to manually inspect Agent home directories.
+
+The scoped acceptance criteria were:
+
+- provide one idempotent command for first install and future upgrades;
+- keep npm install side-effect free and avoid automatic writes to Agent home directories;
+- detect missing, current, changed, and unsupported Agent targets;
+- back up changed installed skill files before overwrite;
+- support `--dry-run` and `--json` for Agent-driven preview and automation;
+- improve CLI help, README, and Agent handoff docs for skill upgrade behavior;
+- update the packaged AIWiki skill so Agents know how to use the new context/query/lint surfaces.
+
+### Implemented
+
+- `src/app.ts`
+  - Added `aiwiki agent sync`.
+  - Added `aiwiki agent sync --agent <id> --yes`.
+  - Added `aiwiki agent sync --dry-run`.
+  - Added `aiwiki agent sync --json --yes`.
+  - Added `aiwiki agent check --json`.
+  - Added command-specific help for `aiwiki agent help`, `aiwiki agent sync --help`, `aiwiki context --help`, and `aiwiki query --help`.
+  - Added safe copy behavior that compares source and target files, no-ops when current, and writes timestamped backups before overwrite.
+  - Updated next-action guidance from manual install toward `aiwiki agent sync --yes`.
+
+- `skill/SKILL.md`
+  - Added skill version marker `aiwiki-skill-version: 0.2.18`.
+  - Added Agent-first setup and upgrade instructions.
+  - Documented `agent sync`, `agent check`, `--dry-run`, `--json`, and backup/rollback behavior.
+  - Expanded Agent guidance for filtered/explainable context JSON.
+
+- `skill/QUERY_PROTOCOL.md` and `skill/LINT_PROTOCOL.md`
+  - Documented filters, query scope, result quality, recommended next action, match reasons, quality signals, and lint/next handling for host Agents.
+
+- `skill/UPGRADE_NOTES.md`
+  - Added packaged notes that explain the current skill changes, expected Agent behavior after sync, and user-facing summary requirements.
+
+- `README.md`, `docs/USAGE.md`, and `docs/AGENT_HANDOFF.md`
+  - Added safe skill sync and upgrade instructions for first installs, long-gap upgrades, per-agent sync, JSON status checks, and rollback from backup.
+
+- `tests/cli.test.ts`
+  - Covered agent sync dry-run, install, JSON current state, changed-file backup, and overwrite behavior.
+  - Covered new help text and `agent check --json`.
+
+### Verification
+
+- `npm test`: passed, 56 tests.
+- `npm run release:check`: passed, including 56 tests and release-check.
+- `npm pack --dry-run`: passed for `@itradingai/aiwiki@0.2.18`.
+- Clean publish clone verification from `C:\Users\Max\AppData\Local\Temp\aiwiki-publish-dc800e0934564873853c9313d670122c`: `npm ci`, `npm run release:check`, and `npm pack --dry-run` passed.
+- Isolated smoke test with temporary `CODEX_HOME` and `CLAUDE_HOME`: passed for first install, `agent check --json`, changed skill backup, overwrite, and current-state dry-run.
+
+### Release State
+
+GitHub push succeeded:
+
+```text
+ceec9a1..e41d634 main -> main
+```
+
+npm publication from a clean clone is blocked by a one-time password challenge:
+
+```text
+npm error code EOTP
+npm error This operation requires a one-time password from your authenticator.
+```
+
+Current registry version remains `0.2.16`, so remote smoke tests for `0.2.18` have not run yet.
+
+### Resume Steps
+
+After npm OTP is available, publish from a clean committed tree or a fresh clean clone:
+
+```powershell
+npm publish --otp=<code>
+npm view @itradingai/aiwiki version
+```
+
+After `npm view` returns `0.2.18`, run remote smoke tests for:
+
+```bash
+aiwiki agent sync --dry-run
+aiwiki agent sync --json --yes
+aiwiki agent check --json
+aiwiki context --help
+aiwiki query --help
+```
+
+Use a task-specific temporary Agent home and vault on the remote server. Do not write to real user Agent homes during remote verification.
+
+### Notes For Future Changes
+
+- Keep `agent sync` explicit. Do not add npm lifecycle hooks that write into `CODEX_HOME`, `CLAUDE_HOME`, or other Agent home directories.
+- Preserve backup-before-overwrite behavior for any future Agent target.
+- Keep `agent install` compatible, but prefer `agent sync` in user-facing guidance because it handles both first install and upgrade.
+- Do not make the skill upgrade workflow depend on crawling, vector search, RAG-over-wiki, RBAC, RSS, scheduled collection, or browser plugins.
+- Package publication should use a clean clone or clean committed tree because unrelated untracked files can otherwise be included by broad package `files` rules.
+
 ## 2026-06-05 - AIWIKI-004 lint workbench
 
 Status: implemented, locally verified, pushed to GitHub, blocked on npm OTP before publication.

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.