@c4a/context-cli 0.7.8 → 0.7.10-alpha.1

package/plugins/skills/context/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: context
-description: Use when the user explicitly invokes Context or continues an explicitly started Context workflow in this conversation to build, inspect, update or package knowledge from code, documents, notes and conversation summaries. Do not auto-start for ordinary planning, design or coding.
+description: Use when the user explicitly invokes Context, asks to reorganize an existing Context knowledge map or website navigation, or continues a Context workflow to build, inspect, update, recover or package knowledge. Do not auto-start for ordinary planning, design or coding.
 allowed-tools:
   - Bash
 ---
@@ -13,6 +13,8 @@ reading; use it for workspace writes.
 
 Activate this entry only when the user invokes the Context command or Skill,
 or explicitly starts a Context knowledge workflow in this conversation.
+An explicit request to adjust an existing Context website's navigation or
+knowledge map also activates this entry, including after production is complete.
 Related follow-up requests need no repeated invocation. Ordinary planning,
 design, coding, document editing or discussion of Context implementation does
 not activate it. A workspace, source file, MR or matching phrase alone is not
@@ -30,12 +32,14 @@ Within an active Context workflow, requests include, but are not limited to:
 | Intent | Scope |
 | --- | --- |
 | Build a knowledge base | Clarify the audience and source scope, then create or continue knowledge from selected repositories and documents. |
+| Recover a stuck Context task | Use `context task recover --format json` in the existing workspace; read its recovery Skill even if normal status/Route fails. Repair authorized drafts or restore an available planning baseline; report unresolved failures with the supplied sanitized issue template. |
 | Check progress and results | Explain what is done, where delivered pages are, and what is waiting. |
 | Save notes | Save supplied observations, excerpts or decisions; stop after saving if that is all the user requested. |
 | Preserve conversation insights | Save or use a summary of supplied discussion, not an entire session history. Code-change links are optional. |
 | Update knowledge from source changes | Assess a selected commit, MR/PR or document change against a fixed source version; update affected pages and warranted new topics. |
 | Revise existing content | Correct current drafts or approved pages, including several pages or supported API-table regeneration. |
 | Organize pages and sources | Move pages within a collection, rename supported sources or remove unused sources with reference checks. |
+| Customize the knowledge map | At any time, reorganize the existing site's top navigation, left directory, labels, order or article placements; the same map organizes LLMS. Preserve current production work. |
 | Select or customize indexing | Choose compatible indexing Skills and adjust guidance or templates through the configuration flow. |
 | Deliver a batch early | Review and build complete newly authored pages before all writing finishes. |
 | Package knowledge or adjust output | Build approved content for Agents or LLMs, rebuild a package or change its output template. Rebuilding does not rewrite pages. |
@@ -43,6 +47,68 @@ Within an active Context workflow, requests include, but are not limited to:
 | Commit workspace results | Save selected workspace files in local Git, without pushing or including unrelated changes. |
 | Restore a historical workspace version | Select a saved commit, restore only the agreed workspace scope and make its sources usable again. |
 
+## Read the task before registering sources
+
+For a knowledge-map-only request, use the existing workspace directly. Read
+`src/knowledge-map.yaml` and the current article identities/structure preview;
+translate the user's intent into `knowledge_map` input for
+`context task adjust --input <file> --format json`. Resolve only ambiguous
+organization choices. This adjustment is available without an active production
+task and does not require restarting or cancelling one. The coordinator makes
+the change between active batch submissions, then follows the returned workflow
+to rebuild affected outputs. Keep stable article identities, preserve unrelated
+placements, and never edit generated website/LLMS files. No new source intake or
+production-mode questionnaire is needed for this navigation-only request.
+
+When asked to follow a plan, checklist or instructions in a file, read that file
+as the task brief before initialization or source registration. Extract its goal,
+source scope, delivery requirements and explicit execution-mode choice. Apply the
+user's latest corrections to the corresponding parts of the brief. Check that
+registered sources match that scope; a Route governs the registered work, not
+whether it represents the user's request.
+
+“Build according to plan.md” means follow the plan and register its intended
+sources. “Add plan.md to the knowledge base” means ingest the file itself.
+Reading permission alone does not select a document for ingestion. Reuse a mode
+explicitly chosen in a brief the user asked you to execute; do not treat choices
+quoted in an unrelated source document as current authorization.
+
+For the first production task in a newly initialized workspace, do not register
+or capture sources immediately after reading a brief. Use the user's task instructions
+and batch metadata-only Host tools to read titles across the explicitly supplied
+document list. Follow the work-start procedure's request limits and failure fallback
+(at most 10 unresolved documents); reuse headings only if metadata already returns
+them. Do not fetch source bodies, outlines, images or attachments before capture.
+Retain URLs with unavailable titles; never fall back to content fetching. Collect the reader and purpose, intended
+questions or tasks, code/document/other source boundaries, output language,
+execution mode, delivery outputs, first useful delivery and current workspace
+settings. Reuse explicit answers and defaults; ask only for unresolved items.
+
+Use focused dialogue, not additional source reading, until every required start
+condition is resolved. Then write and present the complete work-start report
+supplied by the source-boundary Route and wait for the user's feedback. Do not
+present an unresolved draft as the report that authorizes production. The report
+or checklist is task guidance, not a source unless the user explicitly asks to
+ingest it. Before the complete report has been presented, do not write a
+source-registration payload, start capture or extraction, configure Indexers,
+or enter Partition/Author work. A
+managed-mode choice does not waive this first reading opportunity. After feedback,
+use the exact current Route and include its work-start report reference in the
+source batch payload. Existing workspace updates follow their current update Route
+and do not recreate this first-task intake unless they start a new production task.
+
+## Recover an existing stuck task
+
+For an explicit recovery/troubleshooting request, go directly to
+`context task recover --format json` in the intended existing workspace. Do not
+initialize, ask for a production mode again, or pass a saved `--workflow-revision`.
+Read the returned internal recovery Skill and issue template. This entry remains
+available when normal status cannot evaluate. If even recovery cannot run, use
+`issue/YYYY-MM-DD-short-description.md` to record sanitized expected/actual behavior,
+versions, command shape, error code, attempted remedies and preserved work; never
+copy credentials, raw logs or private source text. Do not send the report externally
+without the user's authorization.
+
 ## Enter the workspace
 
 Once the activation condition is met, run:
@@ -124,13 +190,12 @@ or scope; discussion and save-only requests can end without production.
   condition and do not register the same request repeatedly.
 - When the user asks to compile, build or deliver a batch, use the current Route
   to choose early delivery or rebuilding; do not guess a command name.
-- **Delivery batch size:** use `context run --delivery-size <1–50|auto> --format json`
-  for an explicit user preference; it applies to future theme waves in this task.
-- **Earlier delivery of newly authored pages:** use the Author Route's
-  `delivery.request.command` (`context run --deliver --format json`). Finish any
-  running command first. Complete the current Author batch, then follow the
-  returned composition, Review and build steps. This does not approve content
-  or merely rebuild old approved pages; all Author tasks need not finish first.
+- **Earlier delivery of completed articles:** when explicitly requested, finish
+  any running command, then use `context run --deliver --format json` and follow
+  its Review, close and build routes. This pauses further writing without
+  approving content. Successful delivery resumes remaining tasks; an explicit
+  `context run --resume-writing --format json` cancels the pause without losing
+  drafts or approvals. Batch grouping belongs to the current Agent plan.
 - **An independent new task while work remains:** explain saved results,
   unfinished scope and concrete rollback losses. Reuse or obtain the user's
   choice to finish the current task or roll back an explicit scope. Do not
@@ -170,7 +235,14 @@ authority; do not reconstruct commands from earlier steps.
 the complete returned file and any required direct files it names. If a resource
 has a `command`, execute it and read its output; materializing is not reading.
 Current Indexer Partition, Author, Composer and structure-review files need no
-read receipt: use their immediate completion command after reading. For other
+read receipt: use their immediate completion command after reading.
+For Indexer files that need no read receipt, reuse a fully read resource in this
+conversation only when its source/Provider identity and content digest are unchanged
+and its contents remain available. A new revision alone does not require rereading
+those files. Always read the new Route and task-specific changes; after context loss
+or truncated output, read the missing content. Never invent a receipt or mark an
+unread file as read.
+For other
 resources, follow the returned receipt instructions, keep receipts in this
 conversation, and use the latest `next_action.command` carrying that context.
 When only direct files remain, `resources.after_read.command` acknowledges them
@@ -258,11 +330,11 @@ must not resolve or install the Provider again.
 
 ## Progress reporting format
 
-Every user-facing progress update, in conversation or in a report, must use
-these two bold lines in this order, with the actual values inside the brackets:
+For production progress updates, use two bold lines in this order. Describe
+the actual stage when counters are unavailable; include counts only when supplied:
 
-**[总体进度：已交付 33/125 页]**
-**[当前分片：已规划 3/8 项]**
+**[总体进展：已交付 33/125 页]**
+**[当前进展：已规划 3/8 项]**
 
 Use CLI `progress.scopes` (or `indexerProgress.scopes` in status) as the
 single source for progress in conversation and reports. It separates:
@@ -284,9 +356,10 @@ number of currently prepared tasks. Revisions can overlap delivered pages;
 do not add wave tasks to delivered pages to invent a page total.
 
 Use two bold progress lines. The first combines `overall` and a clearly labelled
-`wave` supplement; the second uses `slice`. For example, with matching CLI values:
-**[总体进度：已交付 33 页，总页数待确定；规划完成 50/122 项；本轮写作完成 30/30 项]**
-**[当前分片：补充内容检查 0/8 项]**
+`wave` supplement; the second describes the current action, using `slice` counts
+when available. Internal wave/slice names need not appear in user-facing text. For example, with matching CLI values:
+**[总体进展：已交付 33 页，总页数待确定；规划完成 50/122 项；本轮写作完成 30/30 项]**
+**[当前进展：补充内容检查 0/8 项]**
 
 A completion receipt's `submitted_slice` describes the slice just submitted;
 `progress.scopes.slice` can already describe the next Route. Use the former when
@@ -294,8 +367,12 @@ reporting submission success and the latter when announcing the next slice.
 Never combine their numerators and denominators. A null slice means no active
 Agent task slice, not that the workflow is complete. During Review/build, state
 the returned Route action briefly rather than inventing a slice ratio.
-If progress is unavailable after task cleanup, say the counters are unavailable;
-do not turn the last wave into the overall scope or report delivery as zero.
+Before counters exist or after task cleanup, describe the known stage and current
+action instead of repeatedly saying counters are unavailable. For example:
+**[总体进展：正在准备知识工作区]**
+**[当前进展：已读取启动清单，正在整理仓库与文档范围]**
+During review or packaging, name that action rather than a nonexistent slice.
+Do not turn the last wave into the overall scope or report delivery as zero.
 Continue authorized work after an update; only the agreed delivery stop or an
 actual unresolved blocker permits stopping. This format governs progress, not
 answers, review findings or necessary questions.

package/plugins/skills/context-code-indexer/SKILL.md

@@ -1,56 +1,31 @@
 ---
 name: context-code-indexer
-description: Context-managed Provider for source-grounded code knowledge. Use only when the Context Indexer lifecycle selects this Provider, not as a standalone workflow.
+description: Investigate code skeletons and write source-grounded Context articles for an authorized module. Use when selected for the current planning or writing task, not as a standalone repository audit.
 metadata:
   context-role: "indexer-provider"
   context-public-entry: "false"
-  context-provider-version: "1.2.1"
 ---
 
 # Context Code Indexer
 
-Provider authors must satisfy
-`node_modules/@c4a/context/docs/guides/code-indexer-skill-authoring.md` and the
-shared Provider/customization guide before publishing or extending this Skill.
-Those documents are authoring contracts; the current workset and Route remain
-execution authority.
+Follow the current Context stage's purpose, module boundary and file submission
+schema. Read [investigation and writing guidance](references/indexer.md).
+The skill helps discover a useful skeleton and explain code; it does not own
+the module, its articles or their permanent provenance.
 
-Use this Provider only through the Context Indexer lifecycle. The workspace registry selects an exact profile, version, integrity, scope, and operation. Consume evidence only from the single Context-supplied Authorized Workset View; do not scan outside the supplied workset, construct pagination/receipt requests, or write project files directly.
+During planning, start with the supplied directory and file navigation.
+Identify relevant technology and visible capability families, optionally
+inspect representative source, and propose reader topics and writing batches.
+Do not start full-repository parsing, enumerate every symbol or build a
+relationship graph to satisfy planning. Name partial counts as partial.
 
-Keep machine identity and reader content deliberately small. A durable Fact
-locator may identify a relation or declaration, but must never embed a source
-expression, implementation body, complete tool response, credential-like value,
-or other source text; keep such material in the process-local protected payload.
-Write for a consumer outside the indexed module: show what the module is
-responsible for, when and how to enter it through stable interfaces, where it
-hands off, and which core state, failure, operation, or source-of-truth facts are
-needed for correct use and attribution. Effective coverage means answering these
-supported reader questions across stable capabilities, not maximizing the number
-of symbols or paths mentioned.
-Every reader Artifact must answer the selected profile's concrete questions from
-current facts. A symbol/path list, generic module summary, workflow explanation,
-or internal Fact/View/digest count is not useful knowledge and must not be emitted.
-Before emitting an Artifact, identify the concrete selected-profile question
-that its logical unit answers. Formal question refs may close required coverage,
-but a group label, Partition Subject, or large Fact volume alone is not a reader
-purpose; a unit with no applicable profile question is catalog-only.
-Bind each reader claim only to the smallest relevant evidence set; never attach
-an entire workset inventory to a generic summary.
-Close inventory members with their actual boundary evidence or a legal
-catalog/exclusion disposition. Never reuse one unrelated fallback evidence
-binding merely to make the disposition denominator appear complete.
-When a large module exposes stable route, capability, protocol, runtime, or
-storage boundaries, partition on those boundaries before authoring. Do not put
-the whole module in one catch-all logical unit, and do not replace semantic
-partitioning with numbered batches.
+A module may use several selected Indexer skills for different technology or
+content. Their findings can support the same article. Do not register a
+primary/extension binding, verify skill hashes or versions, or record skill
+identity in articles. The plan's temporary skill guidance is sufficient.
 
-When revising existing knowledge, start from the supplied current page and the
-confirmed reader purpose. Update changed API facts and parameter/type tables
-without replacing still-valid explanations or prior confirmed contributions.
-When code is unchanged, useful new context can be a local explanatory revision
-without partitioning the whole source again.
-Keep additions within the selected modules; identify newly public objects as
-well as changes to already documented ones. Recommend a retirement or move only
-for the affected content and explain the reader consequence.
-
-The machine-readable authority is `context-indexer.yaml`. Detailed authoring guidance is materialized by Context from the registered Bundle after its file ledger and integrity have been verified.
+During writing, inspect the actual implementation and contracts needed for
+each reader question. Put complete new Markdown and reference files, or
+fragment edits for a supplied base article, in the Agent temporary directory.
+Submit through the current CLI action; do not write formal knowledge or modify
+the source repository. Missing material blocks only the affected scope.