@c4a/context-cli 0.7.70 → 0.7.71

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

@@ -80,23 +80,24 @@ 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` returns section changes, title/description changes, exterior-text changes
-(including the article tail), and section order changes. It writes draft files
-and a `submission_path` template. Unchanged parts retain their translation;
-changed parts contain the current primary-language text for the Agent to translate.
-Review every pending part before submitting; generated source text is not a translation.
-
-Older current translations acquire source-part baselines without changing their
-reader text. Older stale translations report `diff: unknown` and get a full source
-draft plus a `.previous.md` translation for comparison.
-
-Repeated preparation preserves edited drafts. `draft: rebase-required` means the
-source changed while a draft was being edited; that draft is excluded from the
-submission template. Reconcile it with the current source, then explicitly add
-the returned `source_digest` to that article's submission entry. Never copy a new
-digest onto an unreconciled draft. Ordinary submissions still use `expected_digest`.
-A draft without a generation record, such as one left by an older workflow, is
-kept as `unrecorded_draft` beside a freshly generated draft.
+`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
@@ -174,10 +176,12 @@ 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 matches an exact ATX heading
-outside code fences in a Markdown source; its region ends before the next
+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 three-region limit applies after resolving and deduplicating positions.
+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,17 +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 matches an exact ATX heading
-outside code fences in a Markdown source; its region ends before the next
+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 three-region limit applies after resolving and deduplicating positions.
+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
@@ -108,10 +108,12 @@ 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 matches an exact ATX heading
-outside code fences in a Markdown source; its region ends before the next
+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 three-region limit applies after resolving and deduplicating positions.
+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/skills/translate-site-locales/SKILL.md

@@ -8,13 +8,12 @@ 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.
 
-Use the returned draft and submission paths. Preserve unchanged translated parts
-and translate the listed changes in a natural tone. For `diff: unknown`, compare
-with the previous translation. A `rebase-required` draft must be reconciled with
-the current source before explicitly confirming its `source_digest`.
-
-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;