@c4a/context-cli 0.7.5 → 0.7.9

package/plugins/README.md

@@ -1,21 +1,39 @@
 # Context Agent Integration
 
+> This directory is generated; do not edit it directly. Paths below are relative to the source repository root. Edit `plugins/context/README.md` for this documentation.
+
 [简体中文](./README_CN.md)
 
-This directory is the only human-maintained source for the Context Agent
-integration. It contains the single Context entry Skill, the Code and Markdown
+`plugins/context/` is the only human-maintained source for the Context Agent
+integration in this repository. It contains the Context production and explicit-only context-inspect-search Skills, the Code, Markdown, Note and Sessions
 Indexer Provider Skills, host manifest templates, and shared assets.
 
 Run `bun run --filter @c4a/context-cli build:plugin` to regenerate the npm
-projection and the committed `repo-install/` tree. Do not edit generated files
-under `repo-install/` or `packages/context-cli/dist/plugins/`.
+projection and the committed `plugins/context/repo-install/` tree. Do not edit generated files
+under `plugins/context/repo-install/` or `packages/context-cli/dist/plugins/`.
 
-`repo-install/{claude,codex,cursor}/` contains host-specific plugin roots with
-only the public Context entry; `repo-install/skills/` is the portable Skill
+`plugins/context/repo-install/{claude,codex,cursor}/` contains host-specific plugin roots with
+the two public entries; `plugins/context/repo-install/skills/` is the portable Skill
 projection. In the same install, `context plugin install` projects Providers
 to the Codex/Cursor shared `~/.agents/skills` directory and Claude's
 `~/.claude/skills`, so Provider names do not inherit a plugin namespace.
 
+Invoke Context explicitly, or continue an already active Context conversation.
+Ordinary coding and design discussions do not automatically start this workflow.
+Installing a Provider makes it discoverable; it does not enable it for every
+workspace. The Agent selects Providers for the current sources and requirements.
+
 The conversational entry delegates workspace state and lifecycle authority to
 the local `context` CLI. Indexer Skills are activated only through the verified
 Context workflow and Indexer Provider lifecycle.
+
+
+## Query and attribute workspace knowledge
+
+Explicitly invoke `/c4a:context-inspect-search` (Cursor: `/c4a-context-inspect-search`)
+or the `context-inspect-search` Skill. It first uses a usable dist package and its query Skill. Without output, it
+tries one build only when the current workflow safely permits it; otherwise it
+queries approved `knowledge`. It traces package pages through the build inventory
+to approved originals and registered sources, without resetting production. Accepted suggestions hand off to `context`.
+Codex disables implicit invocation through Skill policy; Claude commands disable
+model invocation. Other hosts must honor the explicit-only instructions.

package/plugins/README_CN.md

@@ -1,18 +1,34 @@
 # Context Agent 接入
 
+> 本目录由构建生成，请勿直接编辑。以下说明中的路径以源码仓库根目录为准；文档真源位于 `plugins/context/README_CN.md`。
+
 [English](./README.md)
 
-本目录是 Context Agent 接入唯一的人工维护真源，包含单一 Context 入口 Skill、
-Code/Markdown Indexer Provider Skills、各宿主 manifest 模板和共享资产。
+仓库中的 `plugins/context/` 是 Context Agent 接入唯一的人工维护真源，包含 Context 生产入口和显式触发的 context-inspect-search 技能、
+Code/Markdown/Note/Sessions Indexer Provider Skills、各宿主 manifest 模板和共享资产。
 
 运行 `bun run --filter @c4a/context-cli build:plugin` 可重新生成 npm 投影及提交到
-仓库的 `repo-install/`。不要直接编辑 `repo-install/` 或
+仓库的 `plugins/context/repo-install/`。不要直接编辑 `plugins/context/repo-install/` 或
 `packages/context-cli/dist/plugins/` 下的生成文件。
 
-`repo-install/{claude,codex,cursor}/` 分别是只包含 Context 主入口的宿主插件根；
-`repo-install/skills/` 是可移植 Skill 投影。`context plugin install` 在同一次安装中
+`plugins/context/repo-install/{claude,codex,cursor}/` 分别是只包含 Context 主入口的宿主插件根；
+`plugins/context/repo-install/skills/` 是可移植 Skill 投影。`context plugin install` 在同一次安装中
 把 Provider 投影到 Codex/Cursor 共用的 `~/.agents/skills` 与 Claude 的
 `~/.claude/skills`，因此 Provider 不获得插件命名空间。
 
+显式调用 Context，或在已经启动的 Context 会话中继续工作，才进入此流程；普通编码和
+方案讨论不会自动启动它。安装 Provider 只让 Agent 能发现它，不代表所有工作区都会
+启用。Agent 根据当前来源和需求选择 Provider。
+
 对话入口把工作区状态和 workflow 生命周期权威交给本地 `context` CLI；Indexer
 Skills 只能通过完成校验的 Context Indexer Provider 生命周期激活。
+
+
+## 查询知识与来源归因
+
+主动调用 `/c4a:context-inspect-search`（Cursor：`/c4a-context-inspect-search`），
+或指定 `context-inspect-search` 技能。优先使用可用 dist 中的查询技能；没有产物时，当前流程
+允许才尝试一次构建，否则从已批准的 `knowledge` 查询。通过构建清单关联批准原稿
+并追溯登记来源，不清理工作区、不为查询推进无关生产任务。证据充分时可建议更新，用户采纳后交给
+`context` 的当前流程。Codex 配置禁止隐式调用，Claude 命令配置禁止模型自动调用；
+其他宿主依赖显式触发指引，不承诺其支持相同的自动调用控制。

package/plugins/VERSION

@@ -1 +1 @@
-0.7.5
+0.7.9

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,8 +1,19 @@
 {
   "name": "c4a",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
-  "version": "0.7.5",
-  "author": { "name": "c4a" },
+  "version": "0.7.9",
+  "author": {
+    "name": "c4a"
+  },
   "license": "MIT",
-  "keywords": ["context", "knowledge-base", "wiki", "claude-plugin", "c4a"]
+  "keywords": [
+    "context",
+    "knowledge-base",
+    "wiki",
+    "claude-plugin",
+    "c4a"
+  ],
+  "skills": [
+    "./skills/context-indexer-create"
+  ]
 }

package/plugins/claude/commands/context-inspect-search.md

@@ -0,0 +1,159 @@
+---
+description: "Use only when the user explicitly invokes context-inspect-search to query a Context workspace's approved knowledge and trace answers to its registered documents or source code. Do not auto-start for ordinary coding, planning, debugging, or an active Context production workflow."
+argument-hint: "[project-dir or user intent]"
+disable-model-invocation: true
+---
+
+# Context Inspect Search
+
+Answer questions from a selected knowledge workspace, then investigate its
+sources when the answer needs verification. This is an independent query entry,
+not an Indexer or a production Route. Use the conversation language.
+
+## Invocation and scope
+
+Start only on the user's explicit command or named Skill invocation. Continue
+related follow-up questions without repeated invocation; stop applying this
+Skill when the user changes task. An existing workspace, error message, or
+knowledge-related phrase is not an activation signal.
+
+Locate the user-selected workspace. With the CLI available, use
+`context entry [project-dir] --format json` to identify it and its installed
+instructions. This is inspection: do not execute a returned production command
+just because it is actionable. If the CLI is unavailable or state inspection
+fails, readable files can still support a bounded answer; report what could not
+be checked. Do not initialize a replacement workspace or install tools silently.
+If several workspaces could match, resolve which one the user means.
+
+Keep all paths relative to that workspace. Read its `AGENTS.md` and relevant
+configuration before investigating. The presence of a `.tmp` directory alone
+does not establish a workspace. Querying must not clear caches, reset tasks,
+change checkouts, accept Review, or start Author or close. The one permitted
+query preparation build is described below.
+
+## Choose the query material
+
+**Prefer an existing usable dist.** Locate the package output from the workspace
+configuration and inspect its index and `context-build-inventory.json`. Choose
+the package matching the question; do not silently combine unrelated packages.
+A usable package has readable delivered pages, not just an existing directory.
+Read its bundled query Skill (usually `skills/knowledge-query/SKILL.md`, but
+business templates may use another name) and use its navigation and search
+instructions within that package. If it has no query Skill, use its readable
+indexes and pages; a missing Skill alone is not a reason to rebuild. Do not
+execute unrelated scripts merely because they are bundled.
+
+Do not build first when usable output exists. It represents its last successful
+build and selected scope, not necessarily the latest approved workspace content.
+A search miss does not make the package unusable or justify a rebuild. For a
+latest-content question or an apparent gap, inspect the corresponding approved
+knowledge and distinguish it from the delivered version.
+
+**If no usable output exists, try one build when allowed.** Inspect the current
+Route/status and configured package. Only use the normal CLI build action when
+its prerequisites are already satisfied and it will not advance an unrelated
+active delivery or revision. Do not create package configuration, approve a
+template, run close, recover production state or finish pending work just to
+make this query possible. When a safe build is available, run its current
+command once in the identified workspace, wait for the same invocation's exit
+and receipt, then inspect its actual output and query Skill. Do not launch a
+second writer or treat partial output as a completed package. There is no
+unverified promise that this takes less than 20 seconds.
+
+**Otherwise query approved knowledge directly.** If the CLI is unavailable,
+state cannot be checked, build is not allowed, or the attempt fails, briefly
+explain the limitation and continue from readable approved knowledge. Do not
+loop through build repairs. Use `knowledge/structure.yaml` to locate pages,
+collections and source associations; search selected `knowledge/` paths with
+Host file tools, trying domain terms, symbol names and synonyms. Read relevant
+sections in context. A search miss proves neither absence of knowledge nor
+absence of the underlying capability. Candidates and `.tmp` reports may explain
+pending work but are not approved knowledge. If approval cannot be established,
+state that limitation rather than treating arbitrary Markdown as approved.
+
+## Trace delivered answers to workspace sources
+
+For a dist hit, find its `dist_path` in the matching package inventory's
+`approved_knowledge.files` and follow that record's `approved_path` into the
+workspace. `approved_path` is relative to the workspace's `knowledge/` root,
+not the dist directory or workspace root; do not guess the mapping from similar filenames. Read that page and its source
+associations in `knowledge/structure.yaml`, then follow the registered sources.
+If the inventory or mapping is missing, still answer from readable package
+content where possible, but do not claim verified original-source attribution.
+
+The chain is: delivered page → build inventory mapping → approved knowledge and
+structure → registered raw material at its recorded version. The current
+approved page can have changed since build; describe differences rather than
+silently replacing one version with another. Dist and knowledge are two forms
+of the same content, not independent corroborating evidence. The bundled query
+Skill owns package-local retrieval; this explicitly invoked inspection Skill
+owns the subsequent, separately scoped workspace/source investigation. Cite
+which layer supports each claim.
+
+## Prepare only the sources needed for attribution
+
+Follow the relevant page's source references and `sources/*/index.yaml` records.
+Check the selected raw body, attachments or repository module and its recorded
+version before claiming deep attribution. This readiness check concerns the
+selected materials, not completion of the active production workflow.
+
+For repositories, `context source recovery-plan --format json` provides a
+read-only recovery plan. Reuse an accessible checkout only after checking its
+remote, pinned commit and module path. Inspect local changes as well: a matching
+HEAD does not prove a dirty file is the recorded source. Do not silently use the
+latest branch or reset a user's checkout.
+
+If material is missing, report what cannot be verified and offer the smallest
+necessary recovery. With the user's recovery authorization, follow the installed
+`repository-source-recovery.md` procedure and schema in the workflow bundle
+identified by entry, using the CLI's `source restore` contract. Recover only the
+selected source groups; never run `task prepare` or the whole workspace-reset
+procedure to enable a query. If a writer is active or recovery cannot safely
+coexist, keep the answer bounded and defer the write. Do not invent recovery
+payload fields when the installed schema is unavailable.
+
+For documents, notes and sessions, read their saved source bodies or summaries
+and necessary attachments. A summary is not a full conversation transcript.
+An external link is not evidence of its unread target. Fetch missing external
+material only within the user's authorized scope; current remote content is not
+proof of an older snapshot. If historical raw material is unavailable, identify
+the gap rather than reconstructing it from generated knowledge.
+
+## Explain and verify
+
+Trace from the approved claim to the relevant source location. Expand to
+adjacent definitions or tests only as necessary and within the selected source
+scope. Distinguish declared API, implementation behavior, test assertions and
+observed runtime behavior; reading code does not prove a runtime experiment.
+Apart from the bounded package build above, do not run repository builds, tests
+or arbitrary scripts merely to answer a query. If runtime validation is needed, explain the proposed check
+and obtain the user's authorization for that scope.
+
+Lead with the answer, then cite concrete page paths and source locations,
+including the version when it affects the conclusion. Separate confirmed facts,
+inferences and unavailable evidence. If source versions differ, describe the
+difference before deciding that a knowledge page is wrong. Do not dump runtime
+ids, long raw excerpts or a mandatory audit report into every answer.
+
+## Suggest improvements and hand off
+
+When evidence supports a correction or worthwhile addition, briefly describe:
+
+- the affected page or missing topic and the reader's actual problem;
+- the supporting source location/version and what it establishes;
+- whether to revise an existing page, adjust discoverability, add a topic, or
+  obtain missing material first;
+- the bounded pages/sources involved and any uncertainty.
+
+Check the existing scope and neighboring pages before recommending new content.
+Do not create a page solely because a search missed it, and do not propose
+unsupported claims as a knowledge update. With insufficient raw evidence, give
+an actionable material request instead of forcing an update.
+
+A suggestion is not authorization to write. Only when the user accepts the
+update, hand the question, evidence, proposed change and scope to the installed
+`context` production Skill in the same workspace. Read its fresh Route; it owns
+candidate repair, approved-page revision and scheduling around active work.
+Do not clear state, reuse an earlier revision, directly edit knowledge, or build
+a second update workflow. If the production Skill/CLI is unavailable, provide
+the handoff information and state that no update has started.