@c4a/context-cli 0.7.67 → 0.7.71

package/providers/context/provider.yaml

@@ -1,6 +1,6 @@
 schema: agent-graph.provider.v1
 id: c4a/context
-version: 0.7.67
+version: 0.7.71
 name: Context workflow
 description: Internal work contract for Context knowledge workspaces.
 graphs:

package/providers/context/resources/manuals/guides/code-indexer-skill-authoring.md

@@ -50,7 +50,8 @@ proof of runtime behavior. Preserve expressions without executing project code,
 distinguish declaration defaults from implementation defaults, and state unknowns.
 
 Use the current stage's Markdown and reference-file schemas. Each fragment cites
-at most three actual source locations; the CLI computes regional digests. Split
+actual source regions from at most three files (up to eight regions); the CLI
+computes regional digests. Split
 an explanation when it needs separate evidence, not to fill a fixed template.
 Reuse stable article and fragment identities when revising. Supporting documents,
 notes or sessions may contribute to the same article without becoming code facts.

package/providers/context/resources/manuals/guides/knowledge-updates.md

@@ -338,7 +338,7 @@ changing structure, adding a page or when a section has no unambiguous ID.
 To change a fragment's citations, include `references` alongside its `section_id`:
 each entry supplies `source_ref` and `locator` (`path`, `start_line`, `end_line`).
 Context computes the region fingerprint. This uses the same revision submission,
-with at most three source positions per fragment. Full Markdown may include a
+with at most three source files and eight regions per fragment. Full Markdown may include a
 `sections` list of reference edits; local section edits may change content,
 references, or both. Omission preserves citations; an empty list removes them.
 
@@ -703,6 +703,19 @@ Revision section edits may supply `references` as `source_ref` plus a
 `locator` containing `path`, `start_line`, and `end_line`. Context computes the
 regional digest. Omitted references preserve the current fragment's citations;
 an explicit empty list removes them, and deleting a fragment removes its
-citations. Each fragment may cite at most three source positions. Register and
+citations. Each fragment may cite at most three source files and eight regions. Register and
 authorize new material before citing it, then follow normal Review, close and
 build. Article links alone do not authorize reading new sources or prove a claim.
+
+### Locating submitted references
+
+Submission locators also accept `{path, heading}` or `{path, quote}` instead of
+line numbers. Use exactly one form. A heading is the title text of an exact ATX heading
+outside code fences in a Markdown source; a leading `##` marker is optional and,
+when present, also selects the heading level; its region ends before the next
+same-level or higher-level heading. A quote is an exact, unique, nonempty
+substring (line endings are normalized). Ambiguous matches return candidate
+line ranges. Both forms resolve against authorized captured text before hashing;
+stored references still contain only `path`, `start_line` and `end_line`.
+The per-fragment limits (three source files, eight regions) apply after
+resolving and deduplicating positions.

package/providers/context/resources/manuals/guides/markdown-indexer-skill-authoring.md

@@ -45,7 +45,7 @@ submit the short stage-relative manifest. Title and description belong to the
 article, not an internal layout-mapping tuple.
 
 Keep stable article and fragment identities when revising. Each fragment cites
-at most three actual source regions. The CLI handles source digests and safety;
+actual source regions from at most three files (up to eight regions). The CLI handles source digests and safety;
 the Agent judges whether the evidence supports the explanation. For a local
 failure, use the returned fragment identifier or position to repair the affected
 part. Completed independent tasks can be submitted without the rest of the batch.

package/providers/context/resources/manuals/guides/site-translation.md

@@ -60,8 +60,11 @@ map_entries:
 ```
 
 A translated article keeps every `context:section` marker, id and order, every
-fenced code block with its language and content (Mermaid labels may change), and
-every link target. Submission validates all items first and saves nothing when
+fenced code block and its language marker, and every link target. Prose in
+`text`, `txt`, and `plaintext` blocks may be translated; keep commands, paths,
+and placeholders such as `<repository>` unchanged. Mermaid labels may change.
+All other blocks, including blocks without a language marker, keep their content
+unchanged. Submission validates all items first and saves nothing when
 any item fails. A digest from before an approved content change is rejected.
 
 `skip` records that the current pending items are published in the primary
@@ -76,3 +79,25 @@ an outdated notice and a button that switches to the original; a missing page
 shows the original with a notice. Navigation titles without a translation use
 the translated article title, then the primary title. Site search covers every
 language; opening a result in another language switches to it.
+
+## Incremental drafts
+
+`prepare` writes a draft for each pending article and a `submission_path`
+template. A stale article's draft is its current translation; a missing
+article's draft is the approved source. When Git history contains the approved
+version the translation was made from, `source_diff` names a diff from that
+version to the current article. Without such history `source_diff` is `null`;
+compare the draft with the whole approved article. Update only what changed and
+submit the draft. History is missing, for example, when several approve and
+translate rounds ran without a commit in between: the version each translation
+was made from was never recorded. Committing approved knowledge and translations
+after a round lets the next generated draft carry a diff; it does not guarantee
+one, because a kept draft never has a diff.
+
+An existing edited draft is kept (`draft: kept`) as unfinished work, with
+`source_diff: null`; a draft whose body is still the unedited starting text is
+regenerated with its diff. A kept draft has no diff because the source may have
+changed again, even back, since it was written, so align the whole draft with
+the current approved article. Delete it
+to start again from the current translation. Successful submission removes the
+drafts and diffs it saved.

package/providers/context/resources/manuals/reference/package-templates.md

@@ -316,8 +316,8 @@ Approved Markdown under `knowledge/` and the article index in
   and fragment `sections` with their region `references`.
 - Markdown fragment markers contain only their stable ID:
   `<!-- context:section id="usage" -->` and `<!-- /context:section -->`.
-  Structure records each corresponding ID and at most three source positions
-  per fragment, not three per article.
+  Structure records each corresponding ID and its source positions: at most
+  three distinct source files and eight regions per fragment, not per article.
 - A reference contains `source_ref`, `locator: { path, start_line, end_line }`
   and the Host-computed regional `content_digest`. Do not duplicate this in
   Markdown frontmatter or comments.

package/providers/context/resources/procedures/approved-revision.md

@@ -34,6 +34,8 @@ association. Then retry the same `task adjust` without refresh and, once materia
 is available, with `refresh: true`; reread the resulting revision. Do not invent
 module references, replace an older note, delete sources or clear the task to
 satisfy this boundary. Already imported material does not need to be imported again.
+The adjusted source stays citable by the remaining pages queued in the same revision;
+repeating the adjustment for an unchanged source keeps already prepared pages.
 A managed-source `base_digest` protects file replacement from conflicts; it is not
 source-scope authorization and is not interchangeable with a snapshot hash.
 
@@ -137,7 +139,7 @@ Action schema and the same source and baseline validation.
 
 When a fragment's support changes, include `references` with its actual
 `source_ref` and `locator` (`path`, `start_line`, `end_line`). Each fragment allows
-up to three positions; Context reads the captured region and computes its digest.
+regions from up to three source files, eight regions in total; Context reads the captured region and computes its digest.
 For full Markdown, optional `sections` contains only `{ section_id, references }`
 entries; for local edits it can accompany `content` or update references alone.
 An explicit empty list removes that fragment's citations. Deleted fragments lose
@@ -170,3 +172,16 @@ If the user explicitly requires a different presentation, explain the difference
 and resolve that choice before accepting it. Do not rerun unchanged Repair to
 force a format the program deliberately omits. Check the actual resulting page;
 accepted tasks or an empty Composer result alone do not demonstrate a correction.
+
+### Locating submitted references
+
+Submission locators also accept `{path, heading}` or `{path, quote}` instead of
+line numbers. Use exactly one form. A heading is the title text of an exact ATX heading
+outside code fences in a Markdown source; a leading `##` marker is optional and,
+when present, also selects the heading level; its region ends before the next
+same-level or higher-level heading. A quote is an exact, unique, nonempty
+substring (line endings are normalized). Ambiguous matches return candidate
+line ranges. Both forms resolve against authorized captured text before hashing;
+stored references still contain only `path`, `start_line` and `end_line`.
+The per-fragment limits (three source files, eight regions) apply after
+resolving and deduplicating positions.

package/providers/context/resources/procedures/knowledge-updates.md

@@ -338,7 +338,7 @@ changing structure, adding a page or when a section has no unambiguous ID.
 To change a fragment's citations, include `references` alongside its `section_id`:
 each entry supplies `source_ref` and `locator` (`path`, `start_line`, `end_line`).
 Context computes the region fingerprint. This uses the same revision submission,
-with at most three source positions per fragment. Full Markdown may include a
+with at most three source files and eight regions per fragment. Full Markdown may include a
 `sections` list of reference edits; local section edits may change content,
 references, or both. Omission preserves citations; an empty list removes them.
 
@@ -703,6 +703,19 @@ Revision section edits may supply `references` as `source_ref` plus a
 `locator` containing `path`, `start_line`, and `end_line`. Context computes the
 regional digest. Omitted references preserve the current fragment's citations;
 an explicit empty list removes them, and deleting a fragment removes its
-citations. Each fragment may cite at most three source positions. Register and
+citations. Each fragment may cite at most three source files and eight regions. Register and
 authorize new material before citing it, then follow normal Review, close and
 build. Article links alone do not authorize reading new sources or prove a claim.
+
+### Locating submitted references
+
+Submission locators also accept `{path, heading}` or `{path, quote}` instead of
+line numbers. Use exactly one form. A heading is the title text of an exact ATX heading
+outside code fences in a Markdown source; a leading `##` marker is optional and,
+when present, also selects the heading level; its region ends before the next
+same-level or higher-level heading. A quote is an exact, unique, nonempty
+substring (line endings are normalized). Ambiguous matches return candidate
+line ranges. Both forms resolve against authorized captured text before hashing;
+stored references still contain only `path`, `start_line` and `end_line`.
+The per-fragment limits (three source files, eight regions) apply after
+resolving and deduplicating positions.

package/providers/context/resources/procedures/production-stage-files.md

@@ -70,7 +70,7 @@ complete article with stable `context:section` markers. References contain
 `sections`, each with its matching `id` and `references` list. A reference is
 `source_ref` plus `locator: {path, start_line, end_line}` from actual authorized
 text. CLI computes source digests. A fragment may cite at most three distinct
-source positions; an article may have multiple fragments.
+source files and eight regions; an article may have multiple fragments.
 
 When prose names a file, directory or Skill from a cited repository, write its
 exact repository-relative path, or the unique name of its directory such as a
@@ -104,3 +104,16 @@ build resumes the same stage; a failed build retains the pause and all tasks.
 To cancel that pause explicitly, use `context run --resume-writing --format json`.
 It preserves approved articles, candidates and existing task input handles.
 Partial delivery must include the approved articles needed by its local links.
+
+### Locating submitted references
+
+Submission locators also accept `{path, heading}` or `{path, quote}` instead of
+line numbers. Use exactly one form. A heading is the title text of an exact ATX heading
+outside code fences in a Markdown source; a leading `##` marker is optional and,
+when present, also selects the heading level; its region ends before the next
+same-level or higher-level heading. A quote is an exact, unique, nonempty
+substring (line endings are normalized). Ambiguous matches return candidate
+line ranges. Both forms resolve against authorized captured text before hashing;
+stored references still contain only `path`, `start_line` and `end_line`.
+The per-fragment limits (three source files, eight regions) apply after
+resolving and deduplicating positions.

package/providers/context/resources/procedures/source-update.md

@@ -26,6 +26,13 @@ Use an empty list only when existing pages cover the change or the additions
 are outside the confirmed purpose. New pages go through the same writing and
 review process as revisions; a new topic is not a no-change decision.
 
+A kept page's citations whose text only moved in the updated source are
+relocated when the update settles. When cited text changed or cannot be
+confirmed, the completion result lists it in `reference_warnings`; those
+citations keep their previous locations. The warning is a receipt for the
+accepted decision, not a request to resubmit it: after the current update queue
+finishes, run `context revise` on each listed page that needs a correction.
+
 The CLI keeps the previous processed version until every requested page has
 been approved, closed and built. If temporary progress is lost, inspect again
 from that version and preserve the pages already approved. A saved report or

package/providers/context/schemas/approved-revision-result.schema.json

@@ -30,26 +30,64 @@
                       "minLength": 1
                     },
                     "locator": {
-                      "type": "object",
-                      "properties": {
-                        "path": {
-                          "type": "string"
+                      "anyOf": [
+                        {
+                          "type": "object",
+                          "properties": {
+                            "path": {
+                              "type": "string"
+                            },
+                            "start_line": {
+                              "type": "integer",
+                              "minimum": 1
+                            },
+                            "end_line": {
+                              "type": "integer",
+                              "minimum": 1
+                            }
+                          },
+                          "required": [
+                            "path",
+                            "start_line",
+                            "end_line"
+                          ],
+                          "additionalProperties": false
                         },
-                        "start_line": {
-                          "type": "integer",
-                          "minimum": 1
+                        {
+                          "type": "object",
+                          "properties": {
+                            "path": {
+                              "$ref": "#/anyOf/0/properties/sections/items/properties/references/items/properties/locator/anyOf/0/properties/path"
+                            },
+                            "heading": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          },
+                          "required": [
+                            "path",
+                            "heading"
+                          ],
+                          "additionalProperties": false
                         },
-                        "end_line": {
-                          "type": "integer",
-                          "minimum": 1
+                        {
+                          "type": "object",
+                          "properties": {
+                            "path": {
+                              "$ref": "#/anyOf/0/properties/sections/items/properties/references/items/properties/locator/anyOf/0/properties/path"
+                            },
+                            "quote": {
+                              "type": "string",
+                              "minLength": 1
+                            }
+                          },
+                          "required": [
+                            "path",
+                            "quote"
+                          ],
+                          "additionalProperties": false
                         }
-                      },
-                      "required": [
-                        "path",
-                        "start_line",
-                        "end_line"
-                      ],
-                      "additionalProperties": false
+                      ]
                     }
                   },
                   "required": [
@@ -57,8 +95,7 @@
                     "locator"
                   ],
                   "additionalProperties": false
-                },
-                "maxItems": 3
+                }
               }
             },
             "required": [

package/providers/context/schemas/indexer-agent-step-result.schema.json

@@ -129,26 +129,64 @@
                           "minLength": 1
                         },
                         "locator": {
-                          "type": "object",
-                          "properties": {
-                            "path": {
-                              "type": "string"
+                          "anyOf": [
+                            {
+                              "type": "object",
+                              "properties": {
+                                "path": {
+                                  "type": "string"
+                                },
+                                "start_line": {
+                                  "type": "integer",
+                                  "minimum": 1
+                                },
+                                "end_line": {
+                                  "type": "integer",
+                                  "minimum": 1
+                                }
+                              },
+                              "required": [
+                                "path",
+                                "start_line",
+                                "end_line"
+                              ],
+                              "additionalProperties": false
                             },
-                            "start_line": {
-                              "type": "integer",
-                              "minimum": 1
+                            {
+                              "type": "object",
+                              "properties": {
+                                "path": {
+                                  "$ref": "#/$defs/approvedRevision/anyOf/0/properties/sections/items/properties/references/items/properties/locator/anyOf/0/properties/path"
+                                },
+                                "heading": {
+                                  "type": "string",
+                                  "minLength": 1
+                                }
+                              },
+                              "required": [
+                                "path",
+                                "heading"
+                              ],
+                              "additionalProperties": false
                             },
-                            "end_line": {
-                              "type": "integer",
-                              "minimum": 1
+                            {
+                              "type": "object",
+                              "properties": {
+                                "path": {
+                                  "$ref": "#/$defs/approvedRevision/anyOf/0/properties/sections/items/properties/references/items/properties/locator/anyOf/0/properties/path"
+                                },
+                                "quote": {
+                                  "type": "string",
+                                  "minLength": 1
+                                }
+                              },
+                              "required": [
+                                "path",
+                                "quote"
+                              ],
+                              "additionalProperties": false
                             }
-                          },
-                          "required": [
-                            "path",
-                            "start_line",
-                            "end_line"
-                          ],
-                          "additionalProperties": false
+                          ]
                         }
                       },
                       "required": [
@@ -156,8 +194,7 @@
                         "locator"
                       ],
                       "additionalProperties": false
-                    },
-                    "maxItems": 3
+                    }
                   }
                 },
                 "required": [

package/providers/context/skills/translate-site-locales/SKILL.md

@@ -8,13 +8,19 @@ knowledge map title that is missing or stale for each declared locale, with the
 `expected_digest` to submit. Approved knowledge in the primary language remains
 the only source of truth; translations never change it.
 
-For each article, read the approved file and write a complete translation to a
-temporary file under `.tmp/agent-payloads/`. Keep its structure exactly:
+Edit each returned draft `file` and submit the returned `submission_path`. With
+`draft: generated`, a stale article's draft is its current translation; when
+`source_diff` is a path, apply those source changes. A missing article's draft
+is the approved source to translate in a natural tone. With `draft: kept`, or
+whenever `source_diff` is `null`, align the whole draft with the current
+approved article before submitting. Keep the translation's structure exactly:
 
 - frontmatter contains only a translated `title` and optional `description`;
 - keep every `context:section` marker, id and order unchanged;
-- keep every fenced code block, language and content unchanged; only Mermaid
-  labels may be translated;
+- keep every fenced code block and language marker; translate prose in `text`,
+  `txt`, and `plaintext` blocks, preserving commands, paths and placeholders such
+  as `<repository>`. Mermaid labels may be translated. Keep content unchanged
+  in every other block, including blocks without a language marker;
 - keep every link target unchanged; translate link labels only;
 - keep product names, commands, file paths, identifiers and API names as written.