@itradingai/aiwiki 0.2.23 → 0.2.25

package/README.md

@@ -158,6 +158,7 @@ See:
 
 - [`examples/demo-run/`](examples/demo-run/)
 - [`examples/obsidian-vault-sample/`](examples/obsidian-vault-sample/)
+- [`examples/public-trial-scenarios/`](examples/public-trial-scenarios/)
 
 ## Why AIWiki
 
@@ -178,6 +179,8 @@ Instead of saving links and losing context, you get Markdown files that your ass
 - **Give Codex, Claude Code, or QClaw a stable local knowledge layer** it can query before answering.
 - **Keep summaries traceable** with raw records, source cards, Wiki Entries, and run records.
 
+For a guided first trial, use the [public-trial scenario pack](examples/public-trial-scenarios/). It includes article research, topic planning, and project decision memory samples, with commands, expected artifacts, query/context reuse examples, and WeChat-group-ready usage copy.
+
 ## How It Works
 
 ```text
@@ -291,6 +294,7 @@ For Chinese users, scan the QR codes below to join the WeChat group or follow th
 - [Agent Handoff](docs/AGENT_HANDOFF.md)
 - [FAQ](docs/FAQ.md)
 - [Showcase](docs/SHOWCASE.md)
+- [Public Trial Scenarios](examples/public-trial-scenarios/)
 - [Trial Feedback Template](docs/TRIAL_FEEDBACK_TEMPLATE.md)
 - [Roadmap](docs/ROADMAP.md)
 - [Release Notes](docs/RELEASE.md)

package/dist/src/app.js

@@ -316,7 +316,7 @@ function printContextHelp(stream) {
     writeLine(stream, "  --status active|to-review|ready|draft");
     writeLine(stream, "  --limit <1-50>");
     writeLine(stream, "");
-    writeLine(stream, "context JSON includes query_scope, result_quality, recommended_next_action, match_reasons, quality_signals, and related_refs.");
+    writeLine(stream, "context JSON includes query_scope, result_quality, recommended_next_action, match_reasons, quality_signals, related_refs, and reuse_guidance.");
 }
 function parseLintSeverity(value) {
     if (value === undefined) {
@@ -850,6 +850,7 @@ function contextOptions(args) {
 function renderQuery(context) {
     const lines = [`AIWiki 查询: ${context.query}`, ""];
     lines.push(`结果质量: matches=${context.result_quality.total_matches}, best_score=${context.result_quality.best_score}, has_wiki_entry=${context.result_quality.has_wiki_entry ? "yes" : "no"}`, `下一步建议: ${context.recommended_next_action}`, `查询范围: groups=${context.query_scope.searched_groups.join(",") || "none"}, limit=${context.query_scope.limit}, filters=${JSON.stringify(context.query_scope.filters)}`, "");
+    lines.push("Reuse workflows:", `- writing: ${context.reuse_guidance.writing}`, `- research: ${context.reuse_guidance.research}`, `- decision: ${context.reuse_guidance.decision}`, `- review: ${context.reuse_guidance.review}`, "");
     appendQueryGroup(lines, "Wiki 条目", context.matches.wiki_entries);
     appendQueryGroup(lines, "资料卡", context.matches.source_cards);
     appendQueryGroup(lines, "选题", context.matches.topics);

package/dist/src/context.js

@@ -42,6 +42,7 @@ export async function buildContext(rootPath, query, options = {}, now = new Date
             raw_refs: []
         },
         suggested_answer_structure: ["topic overview", "core claims", "available evidence", "reuse judgment", "next action"],
+        reuse_guidance: reuseGuidance(),
         warnings: []
     };
     if (!tokens.length) {
@@ -265,6 +266,14 @@ function qualitySignals(item) {
         signals.push("relationships:present");
     return signals;
 }
+function reuseGuidance() {
+    return {
+        writing: "Use matched Wiki Entries for angles, outlines, and source-backed points; check quality_signals before drafting.",
+        research: "Start from Wiki Entries, then inspect related_refs and Source Cards when evidence or source context matters.",
+        decision: "Use matches to recover constraints, prior judgments, and rejected alternatives before making or revising a choice.",
+        review: "Use result_quality, match_reasons, quality_signals, and warnings to decide whether the knowledge is ready or needs enrichment."
+    };
+}
 function finalizeQuality(result) {
     const all = Object.values(result.matches).flat();
     result.result_quality = {

package/docs/AGENT_HANDOFF.md

@@ -174,6 +174,8 @@ If `fetch_status` is `failed`, say that AIWiki recorded the failure reason but d
 
 ## Query Protocol
 
+Call AIWiki context before writing, researching, deciding, or reviewing when the user asks you to reuse knowledge from this workspace. This includes drafting from prior notes, comparing evidence, recovering project constraints, checking rejected alternatives, or validating whether a match is strong enough to cite.
+
 When the user asks what AIWiki knows about a topic, call:
 
 ```bash
@@ -196,6 +198,7 @@ Read these fields before responding:
 - `match_reasons`
 - `quality_signals`
 - `related_refs`
+- `reuse_guidance`
 
 Do not scan `02-raw` by default unless the Wiki result is insufficient, the user asks to verify the original text, or sources conflict.
 

package/docs/README.md

@@ -30,6 +30,7 @@ This docs folder keeps the public guides short and task-oriented. The main READM
 
 - [`../examples/demo-run/`](../examples/demo-run/) records input files, CLI commands, and outputs from a regenerated run.
 - [`../examples/obsidian-vault-sample/`](../examples/obsidian-vault-sample/) is a sample Markdown vault showing the current core-first artifact contract.
+- [`../examples/public-trial-scenarios/`](../examples/public-trial-scenarios/) contains three public-trial scenarios: article research, topic planning, and project decision memory.
 
 ## Core Workflow
 
@@ -42,6 +43,8 @@ AI assistant reads a source
 
 For public trials, keep the first loop to one source and one question: setup, ingest, inspect the run artifacts, query/context reuse, lint/doctor, and a short feedback note.
 
+The scenario pack gives users copyable sample inputs, expected generated artifacts, reuse prompts, long-term maintenance value, and WeChat-group-ready copy for each trial path.
+
 ## Important Boundaries
 
 AIWiki does not fetch webpages, call an LLM, install Obsidian plugins, run vector search, or manage multiple knowledge bases. The host assistant reads sources; AIWiki validates, writes, links, queries, and checks the local Markdown knowledge base.

package/docs/SHOWCASE.md

@@ -103,5 +103,29 @@ The assistant should use the returned JSON, including match reasons and quality
 
 - [`../examples/demo-run/`](../examples/demo-run/) records input files, commands, and CLI outputs.
 - [`../examples/obsidian-vault-sample/`](../examples/obsidian-vault-sample/) is a generated sample vault.
+- [`../examples/public-trial-scenarios/`](../examples/public-trial-scenarios/) provides three runnable public-trial examples: article research memory, topic planning memory, and project decision memory.
 
 The sample does not rely on crawling, vector search, RAG-over-wiki, or Pro automation. It shows the real base CLI file contract.
+
+## Public Trial Scenario Pack
+
+Use the scenario pack when a user asks, "What should I try first?"
+
+Each scenario includes:
+
+- sample input material
+- base CLI commands
+- expected Raw, Source Card, Wiki Entry, and run artifacts
+- a query/context reuse prompt
+- why the knowledge is worth maintaining over time
+- WeChat-group-ready usage copy
+
+Suggested order:
+
+```text
+article research memory
+  -> topic planning memory
+  -> project decision memory
+```
+
+This order starts from the most common reading workflow, moves into content reuse, and ends with team/project memory. It keeps the trial focused on local Markdown knowledge reuse instead of adding crawling, vectors, or Pro features.

package/docs/USAGE.md

@@ -120,6 +120,26 @@ aiwiki lint --json --path <workspace>
 
 When the source is a URL, the assistant reads it first and then calls `aiwiki ingest-agent`; AIWiki itself does not crawl the page.
 
+### Public-trial scenarios
+
+If you do not have a source ready, use the runnable scenario pack:
+
+```bash
+aiwiki setup --path ./aiwiki-trial --yes
+aiwiki ingest-file --file examples/public-trial-scenarios/input/article-research.md --path ./aiwiki-trial
+aiwiki query "source card" --path ./aiwiki-trial
+aiwiki context "article research" --path ./aiwiki-trial
+aiwiki lint --json --path ./aiwiki-trial
+```
+
+The pack includes:
+
+- article research memory
+- topic planning memory
+- project decision memory
+
+See [`../examples/public-trial-scenarios/`](../examples/public-trial-scenarios/) for sample inputs, expected generated artifacts, query/context reuse examples, maintenance value, and WeChat-group-ready copy for each scenario.
+
 Tell your assistant:
 
 ```text
@@ -165,6 +185,13 @@ For human-readable terminal output:
 aiwiki query "<topic>"
 ```
 
+Use query/context before the assistant writes, researches, decides, or reviews:
+
+- Writing: retrieve prior angles, outlines, source-backed points, and quality warnings before drafting.
+- Research: start from Wiki Entries, then follow `related_refs` and Source Cards when evidence matters.
+- Decisions: recover constraints, prior judgments, and rejected alternatives before changing direction.
+- Review: check `result_quality`, `match_reasons`, `quality_signals`, and warnings before treating a match as reusable knowledge.
+
 Useful filters:
 
 ```bash

package/docs/development-log.md

@@ -6,6 +6,8 @@ This log records queue-driven AIWiki development milestones that should remain v
 
 Status: implemented and locally verified. Demo GIF recording is intentionally deferred until the P0/P1 documentation and repository trust pass is complete.
 
+Version published: `@itradingai/aiwiki@0.2.23`
+
 ### Goal
 
 Close the high-priority public-facing issues identified after the README rewrite:
@@ -37,6 +39,9 @@ Close the high-priority public-facing issues identified after the README rewrite
 - Pack inspection confirmed `docs/assets`, `aiwiki-hero`, `aiwiki-logo`, `join-group`, and `wechat-official-account` are still excluded from the npm tarball.
 - GitHub About description was updated to match npm/README positioning.
 - Initial CI run exposed Node 20 incompatibility in the quoted test glob; the test helper was added, and the follow-up GitHub Actions CI run passed on Node 20, 22, and 24.
+- Prepublish remote tarball smoke passed on `170.106.73.197` in `/tmp/aiwiki-0.2.23-prepublish-20260611T150959`.
+- GitHub Actions Publish npm run `27330327862` succeeded and npm registry reported `0.2.23`.
+- Postpublish remote npm smoke passed on `170.106.73.197` in `/tmp/aiwiki-0.2.23-postpublish-20260611T151405`.
 
 ## 2026-06-11 - README hero and logo asset refresh
 
@@ -467,3 +472,19 @@ Then update the queue through `published`, `remote_verified`, and `done`.
 - Lint actions are advisory only. Do not make `archive`, `reingest`, `mark_reviewed`, or related actions mutate files without a separate explicit task.
 - Keep lint local-file-only. Do not add crawling, vector search, RAG-over-wiki, RBAC, RSS, scheduled collection, or browser plugins under this queue item.
 - The original working tree had unrelated `skill/SKILL.md` changes. Publication must use a clean commit export until that WIP is resolved.
+
+## 2026-06-12 - Public trial scenario pack
+
+### Goal
+
+Help first-time AIWiki users try three concrete workflows without inventing their own source material.
+
+### Implemented
+
+- Added `examples/public-trial-scenarios/` with article research, topic planning, and project decision memory samples.
+- Documented the base CLI commands, expected generated artifacts, query/context reuse prompt, long-term maintenance value, and WeChat-group-ready copy for each scenario.
+- Linked the scenario pack from README, docs home, Usage, and Showcase.
+
+### Boundaries
+
+- No crawler, WeChat reader, browser plugin, vector search, RAG-over-wiki, RBAC, RSS, scheduled collection, Pro command, or new dependency was added.

package/examples/public-trial-scenarios/README.md

@@ -0,0 +1,173 @@
+# Public Trial Scenario Pack
+
+This pack gives first-time AIWiki users three small, repeatable scenarios.
+Each one uses only the base CLI: `setup`, `ingest-file`, `query`, `context`,
+and `lint`.
+
+Run any scenario in a temporary knowledge base:
+
+```bash
+aiwiki setup --path ./aiwiki-trial --yes
+aiwiki ingest-file --file examples/public-trial-scenarios/input/article-research.md --path ./aiwiki-trial
+aiwiki query "source card" --path ./aiwiki-trial
+aiwiki context "source card" --path ./aiwiki-trial
+aiwiki lint --json --path ./aiwiki-trial
+```
+
+For a clean comparison, create a new temporary workspace per scenario or remove
+only your own temporary `./aiwiki-trial` folder after inspecting it.
+
+## Scenario 1: Article Research Memory
+
+Input material:
+
+- [`input/article-research.md`](input/article-research.md)
+
+Use this when you read an article and want the assistant to preserve the core
+argument, evidence boundary, and later writing angles.
+
+Commands:
+
+```bash
+aiwiki ingest-file --file examples/public-trial-scenarios/input/article-research.md --path ./aiwiki-trial
+aiwiki query "source card" --path ./aiwiki-trial
+aiwiki context "article research" --path ./aiwiki-trial
+```
+
+Expected generated artifacts:
+
+- `02-raw/articles/article-research.md`
+- `03-sources/article-cards/article-research.md`
+- `05-wiki/source-knowledge/article-research.md`
+- `09-runs/<run-id>/processing-summary.md`
+
+Reuse example:
+
+```text
+Ask: What does AIWiki remember about preserving source evidence?
+Expected: query/context should surface the article-research Wiki Entry and explain why it matched.
+```
+
+Why maintain it over time:
+
+Article notes become useful only when they are searchable and traceable months
+later. This scenario shows how a one-off reading note becomes reusable research
+memory.
+
+WeChat group copy:
+
+```text
+AIWiki can turn an article note into a traceable Source Card and Wiki Entry. Try it with one article, then ask the knowledge base what evidence and writing angles it preserved.
+```
+
+## Scenario 2: Topic Planning Memory
+
+Input material:
+
+- [`input/topic-planning.md`](input/topic-planning.md)
+
+Use this when you collect rough topic ideas and want the assistant to turn them
+into reusable planning context instead of another forgotten note.
+
+Commands:
+
+```bash
+aiwiki ingest-file --file examples/public-trial-scenarios/input/topic-planning.md --path ./aiwiki-trial
+aiwiki query "topic planning" --path ./aiwiki-trial
+aiwiki context "content calendar" --path ./aiwiki-trial
+```
+
+Expected generated artifacts:
+
+- `02-raw/articles/topic-planning.md`
+- `03-sources/article-cards/topic-planning.md`
+- `05-wiki/source-knowledge/topic-planning.md`
+- `09-runs/<run-id>/source-card.md`
+
+Reuse example:
+
+```text
+Ask: What topic directions are already captured for public trial content?
+Expected: query/context should return the topic-planning entry before the assistant drafts.
+```
+
+Why maintain it over time:
+
+A content queue is easier to improve when old reasons, audiences, and angles are
+still visible. This scenario shows how AIWiki keeps planning memory available
+for future writing.
+
+WeChat group copy:
+
+```text
+AIWiki can keep topic ideas from becoming scattered chat history. Save a planning note, then ask it which angles are already available before writing.
+```
+
+## Scenario 3: Project Decision Memory
+
+Input material:
+
+- [`input/project-decision.md`](input/project-decision.md)
+
+Use this when a project decision needs to be remembered with constraints,
+rejected alternatives, and a future check point.
+
+Commands:
+
+```bash
+aiwiki ingest-file --file examples/public-trial-scenarios/input/project-decision.md --path ./aiwiki-trial
+aiwiki query "decision memory" --path ./aiwiki-trial
+aiwiki context "constraints and rejected alternatives" --path ./aiwiki-trial
+```
+
+Expected generated artifacts:
+
+- `02-raw/articles/project-decision.md`
+- `03-sources/article-cards/project-decision.md`
+- `05-wiki/source-knowledge/project-decision.md`
+- `09-runs/<run-id>/wiki-entry.md`
+
+Reuse example:
+
+```text
+Ask: Why did the project choose a local Markdown knowledge base first?
+Expected: query/context should surface the decision note and preserve the stated constraints.
+```
+
+Why maintain it over time:
+
+Decision memory prevents the team from re-litigating the same tradeoffs. This
+scenario shows how AIWiki keeps the reason, boundary, and next review together.
+
+WeChat group copy:
+
+```text
+AIWiki is useful for more than articles: it can preserve project decisions with constraints and rejected alternatives so the next assistant starts from context.
+```
+
+## What Success Looks Like
+
+After each scenario, inspect:
+
+```text
+02-raw/articles/
+03-sources/article-cards/
+05-wiki/source-knowledge/
+09-runs/
+```
+
+Then run:
+
+```bash
+aiwiki lint --json --path ./aiwiki-trial
+```
+
+The scenario is successful when AIWiki creates a raw record, Source Card, Wiki
+Entry, run summary, and query/context can find the scenario topic again.
+
+## Boundaries
+
+These examples do not use crawling, WeChat reading, browser plugins, vector
+search, RAG-over-wiki, RBAC, RSS, scheduled collection, Pro commands, or new
+dependencies. If the source is a webpage, the host assistant reads it first and
+then passes understood content into AIWiki.

package/examples/public-trial-scenarios/input/article-research.md

@@ -0,0 +1,26 @@
+# Article Research Memory
+
+## Source
+
+A team is evaluating how to keep research notes useful after an assistant reads
+an article. The current problem is not reading speed. The problem is that useful
+claims, source context, and writing angles disappear into chat history.
+
+## Key Points
+
+- The source should be saved with enough traceability to revisit later.
+- The summary should separate what the source says from what the assistant
+  inferred.
+- The reusable entry should be easy to query before writing a future article.
+- A first trial should use one article and one question, not a large migration.
+
+## Reuse Prompt
+
+Before drafting a post about AI knowledge bases, ask:
+
+```text
+What does AIWiki remember about preserving source evidence?
+```
+
+The answer should reuse the stored Source Card and Wiki Entry instead of relying
+on memory from the current chat only.

package/examples/public-trial-scenarios/input/project-decision.md

@@ -0,0 +1,35 @@
+# Project Decision Memory
+
+## Decision
+
+Start with a local Markdown knowledge base before adding heavier retrieval
+systems.
+
+## Constraints
+
+- Users need to inspect and edit the generated files.
+- The first public trial must work without a hosted service.
+- The assistant, not AIWiki, reads webpages and understands source content.
+- Query and context should stay local and explainable.
+
+## Rejected Alternatives
+
+- Browser plugin first: too much installation and permission surface for the
+  first trial.
+- Vector database first: useful later, but it hides the file contract before
+  users trust the workflow.
+- Scheduled RSS collection first: it solves volume before the basic reuse loop
+  is proven.
+
+## Review Trigger
+
+Revisit this decision after users can reliably complete setup, ingest one
+source, query it later, and report where the workflow feels unclear.
+
+## Reuse Prompt
+
+Before proposing a new storage or retrieval feature, ask:
+
+```text
+Why did the project choose a local Markdown knowledge base first?
+```

package/examples/public-trial-scenarios/input/topic-planning.md

@@ -0,0 +1,28 @@
+# Topic Planning Memory
+
+## Planning Note
+
+The public trial needs content that helps users understand what AIWiki is for.
+The strongest topics are practical and problem-first:
+
+- "Why bookmarks are not enough for AI reading workflows"
+- "How to turn one article into reusable assistant context"
+- "What to check during a 10-minute AIWiki trial"
+
+## Audience
+
+Users who already ask AI assistants to read links, summarize documents, or
+prepare writing material, but who lose the result after the chat ends.
+
+## Success Signal
+
+A useful topic plan should explain what the user can try immediately, what files
+AIWiki creates, and how query/context helps the next writing session.
+
+## Reuse Prompt
+
+Before planning the next public-trial article, ask:
+
+```text
+What topic directions are already captured for public trial content?
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itradingai/aiwiki",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "type": "module",
   "description": "Local Markdown knowledge base for AI assistants. Save what your AI reads, ask it later, and keep everything local.",
   "license": "MIT",

package/skill/SKILL.md

@@ -3,7 +3,7 @@ name: aiwiki
 description: Local Markdown knowledge base workflow for AI assistants.
 ---
 
-<!-- aiwiki-skill-version: 0.2.22 -->
+<!-- aiwiki-skill-version: 0.2.25 -->
 
 # AIWiki Skill
 
@@ -202,6 +202,8 @@ If `fetch_status` is `failed`, say that AIWiki recorded the failure reason but d
 
 ## Query Protocol
 
+Call AIWiki context before writing, researching, deciding, or reviewing when the user asks you to reuse knowledge from this workspace. This includes drafting from prior notes, comparing evidence, recovering project constraints, checking rejected alternatives, or validating whether a match is strong enough to cite.
+
 When the user asks to understand a topic from AIWiki, call:
 
 ```bash
@@ -224,6 +226,7 @@ Use the returned JSON to answer. Prefer Wiki Entries first, but read these field
 - `match_reasons`: why each result matched
 - `quality_signals`: scaffold, enriched, grounding, status, and relationship hints
 - `related_refs`: local wikilinks and frontmatter relationships
+- `reuse_guidance`: how to apply the result to writing, research, decisions, and review
 
 Do not scan `02-raw` by default unless the Wiki result is insufficient, the user asks to verify the original text, or sources conflict.