@c4a/context-cli 0.5.41-beta.7 → 0.6.0-alpha.1

package/scripts/build-plugin.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env bun
 /**
  * build-plugin.ts — materialize installable plugin trees from the human-edited
- * plugin/ source directory directly into the nested c4a-plugins/ repo
- * (remote: github.com/context4ai/context). c4a-plugins/ is .gitignore'd by
- * c4a; it is its own git repo, the single source of marketplace distribution.
+ * plugin/ source directory.
  *
+ * The normal 0.6.x target is `dist/plugins` inside the @c4a/context-cli npm
+ * package. `context plugin install` resolves that bundled directory at runtime
+ * and installs it globally for Claude / Codex.
  * Source of truth:
  *   - plugin/commands/
  *   - plugin/skills/
@@ -12,13 +13,13 @@
  *   - plugin/.codex-plugin/plugin.json.template
  *   - plugin/.cursor-plugin/plugin.json.template
  *
- * Generated outputs under c4a-plugins/:
+ * Generated outputs under the target root:
  *   - claude/   — Claude plugin root
  *   - codex/    — Codex plugin root
  *   - cursor/   — Cursor plugin root
  *   - skills/   — Vercel-style standalone skills (no plugin manifest)
  *
- * Plus three marketplace.json files at c4a-plugins/ root pointing at the
+ * Plus three marketplace.json files at the target root pointing at the
  * respective subdirs, so a single repo serves four install paths.
  */
 
@@ -28,12 +29,7 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(__dirname, "..");
-const repoRoot = resolve(pkgRoot, "../..");
-// Integration tests stage build into a temp dir; allow override so the staged
-// run does not require a real c4a-plugins/ clone next to the staged scripts.
-const PLUGINS_ROOT = process.env.C4A_PLUGINS_ROOT
-  ? resolve(process.env.C4A_PLUGINS_ROOT)
-  : resolve(repoRoot, "c4a-plugins");
+const PLUGINS_ROOT = resolve(pkgRoot, "dist", "plugins");
 const MARKETPLACE_NAME = "c4a";
 const PLUGIN_NAME = "context";
 
@@ -47,50 +43,27 @@ interface CommandSource {
 const INTERNAL_PROCEDURES_DIR = "references/internal-procedures";
 
 /**
- * Rewrite `packaged context:skill-*` references in a command body so agents
- * without a packaged-skill registry (Codex / Cursor / Vercel-style) get
- * direct file references they can read instead of an unactionable verb.
- *
- * Claude has a packaged-skill registry and consumes the original phrasing
- * verbatim, so this transformer is only applied to non-Claude builds.
+ * Rewrite internal `skill-*` procedure references in a command body so
+ * non-Claude agent surfaces get direct file references they can read.
  */
-function rewritePackagedSkillReferences(body: string, pathFor: (skill: string) => string): string {
+function rewriteInternalProcedureReferences(body: string, pathFor: (skill: string) => string): string {
   let out = body;
 
-  // Imperative: "Use/Invoke packaged `context:skill-X` [and follow its procedure]" → read the file
-  // The optional trailer is consumed because "Read ... and follow it" already covers it.
-  out = out.replace(
-    /\b(?:Invoke|Use|invoke|use) packaged `context:(skill-[a-z-]+)`(?:\s+and follow its procedure)?/g,
-    (_match, skill: string) => `Read \`${pathFor(skill)}\` in full and follow it`,
-  );
-
-  // Imperative: "Feed/Pass <stuff> to packaged `context:skill-X`" → pass to procedure file
-  // Do not inject "do not reconstruct from memory" here; the surrounding sentence
-  // already carries that warning in its own tail and double-stating it reads redundant.
+  // Imperative: "Apply/Use/Invoke the internal `context:skill-X` procedure" -> read the file.
   out = out.replace(
-    /\b(Feed|Pass|feed|pass) ([^.`]*?) to packaged `context:(skill-[a-z-]+)`/g,
-    (_match, verb: string, mid: string, skill: string) =>
-      `${verb} ${mid} to the procedure in \`${pathFor(skill)}\` (read it in full first if you have not already)`,
+    /\b(Apply|Use|Invoke|apply|use|invoke) the internal `(?:context:)?(skill-[a-z-]+)` procedure/g,
+    (_match, verb: string, skill: string) => `${verb} the procedure in \`${pathFor(skill)}\``,
   );
 
-  // Imperative: "Apply packaged `context:skill-X` <rules>" → apply the procedure for those rules.
+  // Imperative: "invoke the internal `skill-X` procedure" in sentence middles.
   out = out.replace(
-    /\b(Apply|apply) packaged `context:(skill-[a-z-]+)`/g,
-    (_match, verb: string, skill: string) => `${verb} the procedure in \`${pathFor(skill)}\` for`,
+    /\binvoke the internal `(?:context:)?(skill-[a-z-]+)` procedure/g,
+    (_match, skill: string) => `invoke the procedure in \`${pathFor(skill)}\``,
   );
 
-  // "run `context:skill-X`" (no "packaged") → consult the procedure file
+  // Descriptive bare internal procedure references also become file paths for non-Claude builds.
   out = out.replace(
-    /\brun `context:(skill-[a-z-]+)`/g,
-    (_match, skill: string) => `consult the procedure in \`${pathFor(skill)}\``,
-  );
-
-  // Anything left is a descriptive bare reference (e.g. "stop before invoking
-  // `context:skill-X`"); substitute the file path so the agent can resolve it.
-  // The wildcard form `context:skill-*` (with literal asterisk) stays untouched
-  // because the [a-z-]+ class does not match `*`.
-  out = out.replace(
-    /`context:(skill-[a-z-]+)`/g,
+    /`(?:context:)?(skill-[a-z-]+)`/g,
     (_match, skill: string) => `\`${pathFor(skill)}\``,
   );
 
@@ -109,7 +82,7 @@ function cursorCommandSkillPath(skill: string): string {
 }
 
 function cursorCommandFileName(slug: string): string {
-  return slug === "context" ? "context.md" : `context-${slug}.md`;
+  return `context-${slug}.md`;
 }
 
 function rewriteClaudeSlashCommandsForCursor(body: string): string {
@@ -119,26 +92,26 @@ function rewriteClaudeSlashCommandsForCursor(body: string): string {
       slug === "context" ? "/context" : `/context-${slug}`
     )
     .replace(/^## Your [Tt]ask$/gm, "## Workflow")
-    .replace(/\bPackaged skill invoked by\b/g, "Internal procedure invoked by")
     .replace(/\bnot a user slash command\b/g, "not a user command");
 }
 
 /**
- * Scan a generated build root for residual packaged-skill references that
- * should have been rewritten in agent-facing entry files (Codex / Vercel
- * public skills, Cursor commands).
+ * Scan a generated build root for residual unresolved internal procedure
+ * references in agent-facing entry files (Codex / Vercel public skills,
+ * Cursor commands).
  *
- * Skips internal skill bodies — directories named `internal-procedures` (the
- * codex/vercel embed point) and any directory whose name starts with `skill-`
- * (the cursor-build internal skills tree, mirrored from `plugin/skills/`).
- * Cross-skill mentions inside those bodies are descriptive ("the next stage
- * handles X") and stay untouched.
+ * Skips internal procedure bodies — directories named `internal-procedures`
+ * (the Codex/Vercel embed point) and directories whose name starts with
+ * `skill-` (the cursor-build internal skills tree, mirrored from
+ * `plugin/skills/`). Cross-skill mentions inside those bodies are descriptive
+ * ("the next stage handles X") and stay in the source skill style.
  *
  * Throws on any leak so future commands or rewrite-pattern gaps fail the
  * build instead of silently shipping unactionable verbs.
  */
-async function verifyNoPackagedSkillLeak(root: string, label: string): Promise<void> {
+async function verifyNoInternalProcedureReferenceLeak(root: string, label: string): Promise<void> {
   const offenders: string[] = [];
+  const legacyProcedureTokenPattern = new RegExp("`context:" + "skill-[a-z-*]+`", "g");
   const stack: string[] = [root];
   while (stack.length > 0) {
     const current = stack.pop()!;
@@ -146,13 +119,16 @@ async function verifyNoPackagedSkillLeak(root: string, label: string): Promise<v
     for (const entry of entries) {
       const path = join(current, entry.name);
       if (entry.isDirectory()) {
-        if (entry.name === "internal-procedures" || entry.name.startsWith("skill-")) continue;
+        if (entry.name === INTERNAL_PROCEDURES_DIR.split("/").at(-1) || entry.name.startsWith("skill-")) continue;
         stack.push(path);
         continue;
       }
       if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
       const content = await readFile(path, "utf8");
-      const matches = content.match(/`context:skill-[a-z-]+`/g);
+      const matches = [
+        ...(content.match(/`skill-[a-z-*]+`/g) ?? []),
+        ...(content.match(legacyProcedureTokenPattern) ?? []),
+      ];
       if (matches && matches.length > 0) {
         offenders.push(`${path}: ${[...new Set(matches)].join(", ")}`);
       }
@@ -160,7 +136,7 @@ async function verifyNoPackagedSkillLeak(root: string, label: string): Promise<v
   }
   if (offenders.length > 0) {
     throw new Error(
-      `${label} build still contains unrewritten packaged skill references in agent-facing entry files — extend rewritePackagedSkillReferences() to cover the new phrasing:\n${offenders.join("\n")}`,
+      `${label} build still contains unresolved internal procedure references in agent-facing entry files — extend rewriteInternalProcedureReferences() to cover the new phrasing:\n${offenders.join("\n")}`,
     );
   }
 }
@@ -178,10 +154,14 @@ function rewriteClaudePluginRoot(content: string, levelsAboveSiblingsRoot: numbe
 }
 
 function rewriteFlattenedProcedureReferences(content: string, skill: string): string {
-  return content.replace(
+  const localReferences = content.replace(
     /(?<![\w./-])references\/([A-Za-z0-9._/-]+\.md)/g,
     `${skill}/references/$1`,
   );
+  return localReferences.replace(
+    /(?<![\w./-])((?:\.\.\/)*)(skill-[a-z-]+)\/SKILL\.md/g,
+    (_match, prefix: string, procedure: string) => `${prefix}${procedure}.md`,
+  );
 }
 
 function depthOfFileBelowSiblingsRoot(filePath: string, siblingsRoot: string): number {
@@ -307,7 +287,6 @@ function quotedFrontmatterValue(frontmatter: string, key: string, fileName: stri
 }
 
 function titleFromSlug(slug: string): string {
-  if (slug === "context") return "Router";
   return slug
     .split("-")
     .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
@@ -315,29 +294,16 @@ function titleFromSlug(slug: string): string {
 }
 
 function skillNameForCommand(slug: string): string {
-  return slug === "context" ? "context-router" : `context-${slug}`;
+  return `context-${slug}`;
 }
 
 function codexSkillNameForCommand(slug: string): string {
-  return slug === "context" ? "router" : slug;
-}
-
-function claudeCommandForSlug(slug: string): string {
-  return slug === "context" ? "/context:context" : `/context:${slug}`;
+  return slug;
 }
 
 const CURSOR_COMMAND_SUMMARIES: Record<string, string> = {
-  align: "Review raw material and confirm the Node tree before compiling knowledge.",
-  capture: "Capture documents, source code, notes, inbox files, or refreshed sources into the workspace.",
-  compile: "Turn confirmed aligned sources into source-linked knowledge through draft and semantic review.",
-  context: "Route a natural-language C4A request to the right Context command.",
-  drop: "Plan and apply source retraction with semantic decisions and archive safety.",
-  extract: "Preview extraction output for a file without writing workspace state.",
-  init: "Choose workspace layout, language, and focus, then create the C4A workspace.",
-  ops: "Run operational package tasks such as local build/export, with future publish kept under one entry.",
-  purge: "Permanently delete archived dropped-source artifacts after explicit confirmation.",
-  query: "Answer from the local knowledge workspace with citations and gap handling.",
-  status: "Show workspace state, pending work, cache health, and the next useful command.",
+  init: "Initialize a Context knowledge workspace.",
+  continue: "Continue the Context workflow from the current workspace state.",
 };
 
 function cursorCommandSummary(command: CommandSource): string {
@@ -349,10 +315,9 @@ function stripHtmlComments(markdown: string): string {
 }
 
 function publicSkillBody(command: CommandSource, publicName: string): string {
-  const claudeCommand = claudeCommandForSlug(command.slug);
-  const rewrittenBody = rewritePackagedSkillReferences(command.body, publicEntrySkillPath)
+  const rewrittenBody = rewriteInternalProcedureReferences(command.body, publicEntrySkillPath)
     .replace(/^## Your [Tt]ask$/gm, "## Workflow");
-  return `---\nname: ${publicName}\ndescription: >\n  ${command.description} Equivalent to Claude ${claudeCommand}; use the local \`context\` CLI for workspace writes.\ntools:\n  - Bash\n---\n\n# ${command.title}\n\nPublic C4A Context entry for agents that expose skills instead of Claude slash commands.\n\n- Public entry: \`${publicName}\`\n- Claude equivalent: \`${claudeCommand}\`\n- CLI primitive prefix: \`context ...\`\n- Internal procedures live under \`${INTERNAL_PROCEDURES_DIR}/\`; read each referenced file in full before following that step.\n\n---\n\n${rewrittenBody.trimEnd()}\n`;
+  return `---\nname: ${publicName}\ndescription: >\n  ${command.description} Use the local \`context\` CLI for workspace writes.\ntools:\n  - Bash\n---\n\n# ${command.title}\n\nPublic Context entry for agents that expose skills instead of slash commands.\n\n- Public entry: \`${publicName}\`\n- Host command names are installation-specific; use the command or skill surfaced by the current host instead of deriving a filesystem path from an example name.\n- CLI primitive prefix: \`context ...\`\n- Internal procedures live under \`${INTERNAL_PROCEDURES_DIR}/\`; read each referenced file in full before following that step.\n\n---\n\n${rewrittenBody.trimEnd()}\n`;
 }
 
 async function readCommands(): Promise<CommandSource[]> {
@@ -385,8 +350,8 @@ async function renderManifest(input: {
   await writeFile(input.outputPath, rendered, "utf8");
 
   const parsed = JSON.parse(rendered) as Record<string, unknown>;
-  if (parsed.name !== "context") {
-    throw new Error(`${input.label} plugin.json name must be "context", got "${String(parsed.name)}"`);
+  if (parsed.name !== PLUGIN_NAME) {
+    throw new Error(`${input.label} plugin.json name must be "${PLUGIN_NAME}", got "${String(parsed.name)}"`);
   }
   if (parsed.version !== input.version) {
     throw new Error(`${input.label} plugin.json version mismatch: ${String(parsed.version)} vs ${input.version}`);
@@ -454,7 +419,7 @@ async function writePublicSkills(
     const skillRoot = join(skillsRoot, publicName);
     await mkdir(skillRoot, { recursive: true });
     await writeFile(join(skillRoot, "SKILL.md"), publicSkillBody(command, publicName), "utf8");
-    if (command.body.includes("context:skill-")) {
+    if (/`(?:context:)?skill-[a-z-]+`/.test(command.body)) {
       const referencesRoot = join(skillRoot, INTERNAL_PROCEDURES_DIR);
       await mkdir(referencesRoot, { recursive: true });
       for (const skill of internalSkillNames) {
@@ -475,6 +440,12 @@ async function writePublicSkills(
           );
         }
       }
+      await rewriteMarkdownFiles(referencesRoot, (content) =>
+        content.replace(
+          /(?<![\w./-])((?:\.\.\/)*)(skill-[a-z-]+)\/SKILL\.md/g,
+          (_match, prefix: string, procedure: string) => `${prefix}${procedure}.md`,
+        )
+      );
     }
   }
 }
@@ -494,18 +465,18 @@ async function buildCodex(version: string, commands: readonly CommandSource[]):
   await copyAssetsIfPresent(out);
   await writePublicSkills(out, commands, codexSkillNameForCommand);
   await writeGeneratedGuards(out, "AGENTS.md", "Codex plugin build");
-  await verifyNoPackagedSkillLeak(out, "codex");
+  await verifyNoInternalProcedureReferenceLeak(out, "codex");
   await verifyNoClaudePluginRootLeak(out, "codex");
 }
 
 async function buildVercel(commands: readonly CommandSource[]): Promise<void> {
-  // Vercel-style standalone skills live directly under c4a-plugins/skills/.
-  // No plugin manifest, no per-build README; the top-level c4a-plugins/README.md
+  // Vercel-style standalone skills live directly under dist/plugins/skills/.
+  // No plugin manifest, no per-build README; the top-level dist/plugins/README.md
   // owns onboarding for this install path.
   const skillsRoot = join(PLUGINS_ROOT, "skills");
   await resetDir(skillsRoot);
   await writePublicSkills(PLUGINS_ROOT, commands, skillNameForCommand);
-  await verifyNoPackagedSkillLeak(skillsRoot, "vercel");
+  await verifyNoInternalProcedureReferenceLeak(skillsRoot, "vercel");
   await verifyNoClaudePluginRootLeak(skillsRoot, "vercel");
 }
 
@@ -518,7 +489,7 @@ async function writeCursorCommands(outRoot: string, commands: readonly CommandSo
     const raw = await readFile(sourcePath, "utf8");
     const { frontmatter } = parseFrontmatter(raw, `${command.slug}.md`);
     const rewrittenBody = rewriteClaudeSlashCommandsForCursor(
-      rewritePackagedSkillReferences(command.body, cursorCommandSkillPath),
+      rewriteInternalProcedureReferences(command.body, cursorCommandSkillPath),
     );
     const body = stripHtmlComments(rewrittenBody).trimStart();
     const file = `---\n${frontmatter}\n---\n\n${cursorCommandSummary(command)}\n\n---\n\n${body.trimEnd()}\n`;
@@ -569,35 +540,10 @@ async function buildCursor(version: string, commands: readonly CommandSource[]):
     "utf8",
   );
   await rewriteMarkdownFiles(out, rewriteClaudeSlashCommandsForCursor);
-  await verifyNoPackagedSkillLeak(out, "cursor");
+  await verifyNoInternalProcedureReferenceLeak(out, "cursor");
   await verifyNoClaudePluginRootLeak(out, "cursor");
 }
 
-async function ensurePluginsRoot(): Promise<void> {
-  try {
-    const info = await stat(PLUGINS_ROOT);
-    if (!info.isDirectory()) {
-      throw new Error(`c4a-plugins exists but is not a directory: ${PLUGINS_ROOT}`);
-    }
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    if (code !== "ENOENT") throw err;
-    throw new Error(
-      `c4a-plugins/ not found at ${PLUGINS_ROOT}. ` +
-      `Run: git clone https://github.com/context4ai/context.git c4a-plugins ` +
-      `(from the c4a repo root) before building plugins.`
-    );
-  }
-  try {
-    await stat(join(PLUGINS_ROOT, ".git"));
-  } catch {
-    throw new Error(
-      `c4a-plugins/ exists but is not a git repo. Expected remote: ` +
-      `https://github.com/context4ai/context.git`
-    );
-  }
-}
-
 async function writeMarketplaceManifests(version: string): Promise<void> {
   const claudeMarketplace = {
     name: MARKETPLACE_NAME,
@@ -605,7 +551,7 @@ async function writeMarketplaceManifests(version: string): Promise<void> {
     plugins: [{
       name: PLUGIN_NAME,
       source: "./claude",
-      description: "Context For AI — local knowledge workspace. Capture docs, extract code structure, compile into an interlinked wiki with source-traced facts.",
+      description: "Local knowledge workspace. Initialize a project and use next-step guidance to maintain it.",
     }],
   };
   const cursorMarketplace = {
@@ -615,7 +561,7 @@ async function writeMarketplaceManifests(version: string): Promise<void> {
     plugins: [{
       name: PLUGIN_NAME,
       source: "./cursor",
-      description: "Turn project sources into a local, source-linked knowledge workspace your agent can maintain and query.",
+      description: "Maintain a project-local knowledge workspace through init and continue-step guidance.",
     }],
   };
   const codexMarketplace = {
@@ -688,7 +634,8 @@ async function main(): Promise<void> {
   const version = pkg.version;
   if (!version) throw new Error("package.json is missing `version`");
 
-  await ensurePluginsRoot();
+  const targetLabel = "dist/plugins";
+  await resetDir(PLUGINS_ROOT);
 
   const commands = await readCommands();
   await buildClaude(version);
@@ -698,11 +645,11 @@ async function main(): Promise<void> {
   await writeMarketplaceManifests(version);
   await writePluginsTopLevelDocs();
 
-  process.stdout.write(`c4a-plugins/claude generated (version=${version})\n`);
-  process.stdout.write(`c4a-plugins/codex generated (version=${version}, publicSkills=${commands.length})\n`);
-  process.stdout.write(`c4a-plugins/cursor generated (version=${version}, publicSkills=${commands.length})\n`);
-  process.stdout.write(`c4a-plugins/skills generated (publicSkills=${commands.length})\n`);
-  process.stdout.write(`c4a-plugins/{marketplace.json,README.md,README_CN.md,VERSION} written\n`);
+  process.stdout.write(`${targetLabel}/claude generated (version=${version})\n`);
+  process.stdout.write(`${targetLabel}/codex generated (version=${version}, publicSkills=${commands.length})\n`);
+  process.stdout.write(`${targetLabel}/cursor generated (version=${version}, publicSkills=${commands.length})\n`);
+  process.stdout.write(`${targetLabel}/skills generated (publicSkills=${commands.length})\n`);
+  process.stdout.write(`${targetLabel}/{marketplace.json,README.md,README_CN.md,VERSION} written\n`);
 }
 
 main().catch((err) => {

package/plugin/commands/align.md

@@ -1,71 +0,0 @@
----
-description: "Align raw material into a finalized Node structure and block ownership."
-argument-hint: ""
-allowed-tools: Bash(context:*)
----
-
-## Your Task
-
-Run the CLI-guided align workflow. `/context:align` is the user entrypoint; the CLI owns route, stage, validation, workflow payload storage, and the canonical next write. The agent owns semantic Node/Section grouping and any user-facing questions.
-
-If `$ARGUMENTS` starts with `code`, run `context align code [slug]`, report the dry-run projection plan, and stop. This route is CLI-owned and does not enter the prose align workflow.
-
-### Step 1 — Scan
-
-Run `context align scan --format json`.
-
-Use the returned `workflow.next-action-envelope.v2` as the source of truth:
-
-- Follow top-level `next_action.kind` and `next_action.command` for every write.
-- Use only the returned `next_action.command` for the next required step. When it points at `read-plan`, run that one command first.
-- Treat `allowed_actions[]` as permission for read-only insertions such as `show_view`; do not choose a different write path from it.
-- Treat `agent_hints[]`, when present, as a temporary mirror or diagnostic only. If it conflicts with `next_action`, follow `next_action`.
-- Read workflow payload views only through returned `context workflow show` commands.
-- If the host truncates scan stdout but the preview includes top-level `next_action.command`, run that command. If `next_action` is not visible, rerun the scan command; do not recover host tool-result files.
-
-For protocol discovery, prefer narrow commands:
-
-- `context schema workflow.next-action-envelope.v2 --view minimal --format json`
-- `context protocol show align-compile --format json`
-- `context schema align-structure-intent --view minimal --format json` — includes required fields, enums, section kind priority/triggers, mount matrix, and a minimal authoring example; use full schema only for extended notes.
-
-### Step 2 — Read Evidence Through The Single Evidence Path
-
-If scan returns a `read-plan` command, run it and then follow the next command returned by that view. The normal path is:
-
-- `read-plan` summarizes source size, active source set, navigation/placeholder sources, and the next evidence command.
-- `source-bundle` returns the selected source text with `@c4a` block annotations. Read it, then write the requested align JSON yourself, normally `align-structure-intent`; do not pipe the bundle text into `context align validate`.
-- If `source-bundle` omits text for budget, `read_scope_complete: false`, `page.has_more: true`, or the final `source-bundle:end` annotation is missing, run its `next_action.command` before authoring.
-- If the next command contains `--read-cursor`, treat it as opaque continuation state. Do not decode it and do not replace it with hand-written `--source` / `--window` / `--range` / `--heading` selectors.
-- `blocks`, `windows`, `block-index`, `source-mapping`, and `pending-relation-refs` are detail views only. Use them when the read-plan/source-bundle next action or `how_to_explore[]` asks for a narrow follow-up.
-
-When a view returns `page.next_command`, follow that command to continue the same semantic view. Use `--source`, `--heading`, `--window`, `--range`, or `--token-budget` only as view filters; do not inspect workflow files, cache files, host tool-results, or stdout fragments with generic tools.
-
-If a detail view returns `align-blocks-read-incomplete`, `page.has_more`, or `truncated: true`, the response is a partial read. Return to the read-plan/source-bundle continuation instead of treating that partial JSON page as the complete source.
-
-### Step 3 — Produce The Semantic Payload
-
-Reuse existing knowledge before inventing new Nodes: use `context mdrive glossary match <name>` and `context mdrive node list --format json` for term/entity reuse.
-
-Apply packaged `context:skill-align-workflow` Node classification gates and align intent procedure. Keep generated payloads on stdin. Prefer heredocs for small payloads; if payload staging is needed for large or parallel writes, use the workspace AGENTS.md scratch path (`.context/.tmp/agent-payloads/<run-id>/...` in embedded workspaces, `.tmp/agent-payloads/<run-id>/...` in root-layout workspaces) and redirect stdin from it. Never reuse fixed `/tmp/c4a-*` names and never place scratch payloads under CLI-managed `.tmp/context-cli/`, `output/`, `archive/`, `knowledge/`, or `raw/` truth directories.
-
-Use CLI diagnostics instead of static prompt rules:
-
-- `diagnostics.automatic_ownership_adjustments[]` explains mechanical structural-block demotions and the explicit ownership override shape.
-- `pending-relation-refs` lists explicit Parent/Children/Related markdown links. Reuse existing target Nodes when present; keep unresolved target slug hints deferred instead of writing dangling `contains_parent` / `domain_gate.child_refs`. A relation/placeholder source may still be preserved as a no-write Node with root-level `planned_sections: []`; preserve it before default skip when an explicit retrieval need, graph need, or atomic/concrete title gives the page standalone retrieval value, even if every child ref is unresolved. Never put `planned_sections` inside `domain_gate`. If it is kept without graph support, keep supporting blocks `context_only` with `visible_to`. If you skip the source and emit no Node for it, still cover its coverable blocks with an `ownership_groups[]` rule, usually source-wide `ignored` for pure placeholders. `ignored` disposes unused material and does not support the placeholder by itself. Unresolved children stay pending rather than becoming graph edges.
-- Validation diagnostics identify contiguity, citation eligibility, ownership, and mount-matrix problems.
-- `views[]` and `diagnostics` distinguish citable evidence from supporting context; do not infer citation eligibility from raw ownership prose.
-
-### Step 4 — Validate And Submit
-
-When the envelope asks for `validate_align_decision`, submit the payload matching `next_action.input_schema`, normally the `align-structure-intent` you authored after reading evidence, to `context align validate --input - --format json` or the exact returned command. If validate returns blocking diagnostics, repair the payload and rerun validate. If validate returns a `submit_structure_decision` next_action, execute that command with the same validated payload.
-
-After a finalize command succeeds, do not submit finalize again to confirm it. Use returned `payloads.*.show_command` values, or `context workflow show --payload finalized-ownership --unwrap --format json`, for read-only confirmation; then follow `next_action.command`, normally `context compile scan --format json`.
-
-If finalize reports node reclassification hints, treat finalized ownership as the source of truth. `context status` reports finalized node types, not the originally submitted proposal.
-
-For any other write kind, execute the top-level `next_action.command` exactly. If the command rejects the payload, follow the returned `next_action` and `reason_code`; do not infer a route fallback from memory.
-
-### Final Report
-
-Report in the user's conversation language. Summarize finalized Node counts and meaningful warnings. Do not surface workflow payload digests, scope ids, block hashes, snapshot digests, or absolute paths.

package/plugin/commands/capture.md

@@ -1,113 +0,0 @@
----
-description: "Capture URLs, local Markdown, source code, stdin path lists, inbox/refresh sources, or conversation notes as Context sources."
-argument-hint: "[url | ./path.md [./more.md...] | --code [paths...] | --aspect <name...> | --stdin | --inbox | --refresh | note]"
-allowed-tools: Bash(context:*, bun:*, brew:*, curl:*, sh:*, scoop:*, choco:*, lark-cli:*), WebFetch
----
-
-<!--
-This command has no companion skill. Its protocol (argument routing +
-missing-dependency install flow) lives inline here per the slash-command
-length exemption for self-contained slash commands.
--->
-
-## Your Task
-
-Capture is entirely CLI-driven — your role is to route the right `context capture` invocation and relay its output. Never hand-write captured source snapshots: the CLI owns normalisation (NFC, BOM strip, line endings) and the `content_hash` contract, so any manual edit breaks idempotency.
-
-### Code capture diagnostics
-
-Do not run hand-written dependency preflight commands before `context capture --code`. The CLI owns TypeScript runner/plugin resolution and returns structured `agent_hints[]` when the runner is missing or misconfigured.
-
-If `context capture --code ...` fails with install or runner hints, surface the CLI's `agent_hints[]` install command exactly as printed. Ask the user once whether to run that command on their behalf; global installs touch shared state, so explicit confirmation is required before invoking `Bash`. If approved, run the exact command from `agent_hints[0].command`, then retry the original `context capture --code ...` invocation. If declined, leave the command visible so the user can run it manually. Do not inline extraction packages, do not hand-write code snapshots, and do not continue with partial capture.
-
-Invocation note: code capture does not run through `npx`. The default code aspect uses the `@c4a/extract` runner and `@c4a/extract-ts` plugin bundled into the installed `@c4a/context-cli`, then records the bundled runner identity in the user-cache manifest. Only non-default runner/plugin packages configured in `aspects/code/aspect.yaml` need to be resolvable from the same global install that provides `context`; when they are missing, the CLI returns structured install hints.
-
-### Route by argument
-
-Before choosing a local Markdown capture route, honor the surrounding task context. Driver documents such as run instructions, handbooks, READMEs, plans, feedback issues, corpus/index/manifests, and batch lists are not Context sources unless the user explicitly asks to ingest them. Capture only ingest targets that are already explicit in the user request; if they are missing, ask one clarification instead of capturing the driver document.
-
-- `$ARGUMENTS` is one or more `http://` / `https://` targets and/or local `.md` source documents to ingest → `context capture $ARGUMENTS` (Feishu docx/wiki URLs need `lark-cli`; URL and mixed batches are supported). Do not write an Agent-side URL loop.
-- User provides a long newline-separated URL list or local `.md` source document list to ingest → pass it to `context capture --stdin` with a direct heredoc. Mixed URL + local `.md` batches are supported when the user intentionally provides both.
-- `$ARGUMENTS` contains `--inbox` → `context capture --inbox`.
-- `$ARGUMENTS` contains `--refresh` → `context capture --refresh`. This refreshes active Feishu URL sources and local Markdown sources whose stored origin file still exists; code sources use `context capture --code`.
-- User asks for code capture with explicit `--module` flags → run `context capture --code $ARGUMENTS`, preserving code flags such as `--module`, `--version`, `--version-from`, and `--no-runner-cache`.
-- User asks to refresh/re-capture an already configured code source → run `context capture --code` unless the user explicitly wants to change package selection or version flags. The CLI reuses stored `capture_config`, appends a new snapshot only when code/version content changes, and never overwrites prior snapshots.
-- User asks to run a configured custom aspect capture → run `context capture --aspect <name...> --format json`. Prefer configured aspect names. If an automation script already supplies a path, it must point to an installed aspect directory in the current workspace and the CLI will treat it as that aspect name. Do not use `context capture --aspect code`; code capture remains `context capture --code` because it owns target path, `--module`, version, and runner-cache flags.
-- User provides one or more code target paths, or asks for code capture without explicit `--module` flags → run `context capture --code $ARGUMENTS --format json` directly. The CLI preflights every target first; if any target is ambiguous it returns candidates without writing, otherwise it captures all selected code targets serially.
-  - If the CLI returns candidate packages, ask the user which package paths to capture.
-  - Then run `context capture --code <original-target-if-present>` with one repeated `--module <path>` for every selected package. The CLI derives and stores path filtering silently from that selection.
-- User asks to record conversation material, a decision, a revision intent, or a temporary observation → use note capture:
-  - Classify once as `revision`, `decision`, or `brainstorm`; temporary observations are `brainstorm`. If unclear, ask one clarification.
-  - For `revision` or `decision`, require an existing target. If missing, run `context query --intent node_lookup --query "<user words>"` and ask the user to confirm a Node or Section before writing.
-  - Write the body to `context capture --note --intent <intent> --anchor <node-slug>[#<section-id>] --input -` for anchored notes, or omit `--anchor` for brainstorm.
-  - For `revision`, organize the stdin Markdown with headings: `旧上下文`, `修改意图`, `新内容`, `验证条件`.
-  - For `decision`, organize the stdin Markdown with headings: `议题`, `选项`, `决议`, `理由`.
-  - After capture, run `context status --view summary --format json` and base the user-facing next step on `next_step.command` / `workflow.next_step`.
-
-For stdin batches, use this shape:
-
-```bash
-context capture --stdin <<'EOF'
-https://example.feishu.cn/wiki/abc
-docs/a.md
-docs/b.md
-EOF
-```
-
-Do not pipe the heredoc through another command, and do not discover files with `find` / `ls` when the user already supplied the paths.
-
-### Output Handling
-
-Report the CLI output verbatim. If the CLI reports `N sources changed`, suggest the right next step:
-
-- Run `context status --view summary --format json` and use its `next_step.command` / `workflow.next_step`.
-- If JSON status reports `incremental.pending_align.status: "pending"` with `count > 0`, suggest `/context:align` even when a previous finalized align workflow or prose `workflow.next_step` says compile. Newly captured structure work must be routed through align before compile.
-- If status says aligned knowledge is missing or alignment is required → suggest `/context:align`.
-- If status says compile work is pending for Markdown / evidence-backed knowledge → suggest `/context:compile`. Mention `/context:align` only if the user wants to revise the structure.
-- If the capture was code-only and status reports pending code projection, suggest the CLI-owned code route: `context compile --aspect code <source-slug>`, followed by `context compile close` when the CLI asks for close.
-
-Never suggest prose compile or hand-built code knowledge for a code-only source. Code snapshots become active knowledge only through `context compile --aspect code`, which materializes package/category/symbol Nodes deterministically.
-
-If capture is rejected with `agent_hints[].code = "workflow-cross-family-rejected"`, do **not** run `context workflow abandon ...` automatically. First run or ask the user to run `context workflow status --format json` and explain that another workflow is active in this workspace. Continue that workflow when it is the intended task; ask the user before abandoning it when the user wants to discard that in-progress work. If the user expected a different repository/workspace, change to the confirmed workspace root before retrying capture.
-
-## Final Report
-
-Report in the user's conversation language. Translate section headings into the user's language instead of copying the English labels below verbatim. Optimize for human readability: use document titles instead of source ids, package names instead of `aspect:code:*` strings, and human-readable kind labels ("local markdown", "Feishu doc", "code package") instead of internal tokens. Do not surface content hashes, snapshot digests, workflow payload ids, or absolute file paths.
-
-Stable structure:
-
-1. Completion headline. Single line with the action verb plus core counts: how many sources were captured this round, broken down by `new` / `updated` / `unchanged`. Capture data from `context capture ... --format json` `result.summary` (or per-source statuses when no aggregate is returned).
-2. Per-source list grouped by status. Show each captured source under one of three groups (`new` / `updated` / `unchanged`); within each group list the document title (`source.title`), kind label, and a short delta indicator for updated sources (for example added/removed line counts when the CLI returns them; otherwise "content changed"). Cache-hit code packages belong in `unchanged`. Omit groups that are empty.
-3. Pending workflow signals. When `context status --view summary --format json` reports follow-up work tied to this capture (sources pending align, sources pending compile, refreshed sources pending recompile, code sources pending projection), summarize each as a single line naming the work and which sources are affected. Omit the section entirely when there is no pending follow-up.
-4. Next step. Single command suggestion driven by status: `/context:align` when structure work is pending, `/context:compile` when prose compile work is pending, `context compile --aspect code <slug>` when code projection is pending, or `context compile --aspect <name>` when a custom aspect projection is pending. If nothing is pending, say so explicitly.
-
-Do not include raw CLI diagnostics, agent_hints content, schema names, or workflow payload identifiers in the report. Those belong in earlier troubleshooting output, not in the completion summary.
-
-## Reference
-
-### Missing Dependency Recovery
-
-If the CLI returns `agent_hints[]` with `code: "capture-code-typescript-plugin-missing"`, stop and surface the hint. Ask the user once for permission to run `agent_hints[0].command` (the CLI has already picked the correct package manager — `npm install -g` or `bun install -g` — based on how `context` itself was installed). If approved, run that exact command via `Bash` and then retry the original capture; if declined, leave the command visible for manual install. Never substitute a different package manager or version.
-
-If the CLI prints a missing-dependency error like `lark-cli not installed`, walk the user through installation:
-
-1. Ask once up-front whether to proceed with install. If no → stop and tell the user to install manually from the tool's official README, then re-run.
-2. `WebFetch` the tool's official README (for `lark-cli` that's `https://github.com/larksuite/cli/blob/main/README.md#quick-start-ai-agent`).
-3. For each command the README prescribes for the user's platform, show the command then call `Bash`. The host's per-tool permission prompt is the user's confirmation surface; don't add extra y/n questions between commands.
-4. Stop on any failure; surface stderr verbatim.
-5. After success, tell the user to re-run their original `/context:*` command themselves.
-
-### Language Policy
-
-Your prose to the user follows the user's conversation language. CLI commands, flag names, URLs, env-var names, binary names, source-ids stay English.
-
-### Invariants
-
-- Captured source snapshots are immutable post-write — the CLI only ever appends new snapshots.
-- The source registry is authoritative; derived index files are not Agent workflow inputs.
-- Local `.md` source identity follows the captured file's stable origin path, not its H1/title. If the user edits the title but captures the same path again, the CLI appends a new snapshot to the same `local:*` source.
-- In `--format json`, code capture runner cache state is authoritative in `result.runner.cacheMode`: `prepared` means a workspace runner was prepared, `cached` means workspace cache hit, and `bypass` means `--no-runner-cache` used a temporary runner directory instead of the workspace runner cache.
-- Aspect snapshots default to `evidence.mode: none`. Prose-like custom aspects must opt in with `evidence: { mode: block }` in `aspects/<name>/aspect.yaml` before they generate evidence manifests. Invalid `evidence.mode` values are reported as `evidence-policy-invalid`; they are not silently treated as `none`.
-- Code aspect snapshots ship with `evidence.mode: none`; symbols/files/edges are indexed inside the code bucket. Do not ask users to inspect or repair a code `.evidence` manifest.
-- Code aspect capture writes raw code snapshots first. Materialize them with `context compile --aspect code <slug>` (or no slug for all actionable code sources) before prose align needs to attach documentation to code Nodes.
-- On duplicate capture of the same URL: identical `content_hash` → CLI skips with `unchanged`; different hash → CLI appends a new snapshot.