@c4a/context-cli 0.7.50 → 0.7.60

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

@@ -0,0 +1,78 @@
+---
+id: context.sdk.site-translation
+kind: procedure
+mediaType: text/markdown
+---
+
+# Site translation
+
+A knowledge package website can publish translated copies of approved
+knowledge for each language tag declared in `site.locales`. Approved knowledge
+in the primary language remains the only source of truth; translations are a
+reader projection and never change Review, Verify or the KB output.
+
+## Storage
+
+| Path | Content |
+| --- | --- |
+| `translations/<tag>/<approved-path>.md` | Translated article. Frontmatter holds `title`, optional `description` and a `translation` record with `locale`, `artifact_ref`, `source_digest` and `translated_at`. |
+| `translations/<tag>/knowledge-map.yaml` | Translated navigation titles keyed by knowledge map entry `key`. |
+
+`<approved-path>` is the path below `knowledge/`. Translations are formal
+workspace content: they are included in workspace versions and package
+fingerprints, so changing one rebuilds the website.
+
+## Freshness
+
+Each translation records the digest of the approved title, description and
+body it was written from. A translation is `current` when the digest matches,
+`stale` when the approved article changed, and `missing` when no file exists.
+Runtime metadata changes do not make a translation stale. Files whose approved
+article no longer exists are reported as orphans and removed by the next
+submission.
+
+When a package declares locales and any item is not current, the workspace Route
+selects `translate-site-locales` after package template approval and before the
+workspace version is recorded.
+
+## Commands
+
+```bash
+context translate status --format json
+context translate prepare --format json
+context translate submit --input <file> --format json
+context translate skip --digest <expected_digest> --format json
+```
+
+`prepare` lists each pending article and navigation title with
+`expected_digest`. `submit` accepts:
+
+```yaml
+expected_digest: <from prepare>
+articles:
+  - locale: zh-CN
+    approved_path: knowledge/codeindex/app/start.md
+    file: .tmp/agent-payloads/translations/zh-CN/codeindex/app/start.md
+map_entries:
+  - locale: zh-CN
+    key: getting-started
+    title: 入门
+```
+
+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
+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
+language. Use it only when the user declines translation for this iteration;
+the next approved change asks again.
+
+## Website
+
+Each page is published once and contains every language; the reader's language
+selects what is shown at the same URL. A stale page shows the translation with
+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.

package/providers/context/resources/manuals/reference/project-api.md

@@ -189,7 +189,8 @@ may be rebuilt; it is not an authoring source.
 `kbPackage.site` optionally adds a VitePress website at `dist/<base>-site/` in
 the same build, beside the KB directory. `<base>` removes one trailing `-kb`
 from the package name, if present. Omit it for KB-only output. It accepts `title`, `description`,
-`lang`, a deployment `base` path, and an optional `home` presentation. `home`
+`lang`, a deployment `base` path, an optional top-bar `titleLink`, and an
+optional `home` presentation. `home`
 accepts `title`, `slogan`, `description`, hero `actions`, and `resources` shown
 below the generated site map. Each resource needs an `href`, a copyable
 `command`, or both. Omit unknown resources; the builder never invents service

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

@@ -35,6 +35,19 @@ empty diff. Inspect/edit does not advance references; delivery or an explicit
 no-impact outcome settles the selected scope. Historical locators always store
 the real repository path at the cited commit, not today's registration path.
 
+External associations in `imports.yaml` are entrances, not recorded evidence:
+they create no `references[]` and no review hints, and the CLI never checks
+their versions. When the user asks to update or check external associations,
+use existing authorized Host tools (for example `git ls-remote`, a package
+manager or a web read) to observe each selected entry's current version and
+compare it with its optional `version`. If it differs, read only what the
+linked articles rely on, report whether they need revision and update
+`version` once settled. Unreachable, unauthorized or failed checks are
+"version unknown": report them, keep `version` unchanged, and never treat them
+as changed. When an article's conclusion must trace or track external content,
+register the needed part as a source and capture it; do not cite the
+association itself as evidence.
+
 Before starting production, compare the proposed content with the workspace's
 reader purpose. For clearly unrelated anecdotes or personal rankings, briefly
 recommend leaving them out of the formal manual or saving them separately because

package/providers/context/skills/record-workspace-version/SKILL.md

@@ -9,7 +9,8 @@ checks real changes and an increasing SemVer; you decide the wording and impact.
 Do not summarize temporary execution progress as knowledge changes.
 
 This action is selected at completed-scope delivery, after Review, Close and
-package configuration/template approval, before the final package build.
+package configuration/template approval and website translation, before the final
+package build.
 Record one version for the completed scope, then follow the returned workspace
 Route to build outputs with that version. A failed build alone does not require
 another version; retry through the Route using the recorded version. Do not
@@ -26,7 +27,7 @@ Use the returned digest in `context version record --input <file> --format json`
 Input fields: `expected_digest`, `version`, `title`, `changes` (nonempty list),
 `triggers` (nonempty list of `{kind, description}`), and optional
 `actor: {name, kind}`. Trigger kinds are initial, note, sessions, mr, module,
-document, navigation, repair, dist, other. Describe what actually triggered the
+document, navigation, repair, dist, translation, other. Describe what actually triggered the
 iteration, not merely the CLI command. Never include raw private transcripts,
 credentials, local absolute paths or private account IDs in public history.
 

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

@@ -0,0 +1,36 @@
+---
+name: translate-site-locales
+description: Translate approved knowledge for the website locales declared in site.locales when the workspace Route selects this action.
+---
+
+Run `context translate prepare --format json`. The task lists every article and
+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:
+
+- 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 link target unchanged; translate link labels only;
+- keep product names, commands, file paths, identifiers and API names as written.
+
+Translate knowledge map titles as short navigation labels. Submit with
+`context translate submit --input <file> --format json`. Input fields:
+`expected_digest`, `articles` (list of `{locale, approved_path, file}`) and
+`map_entries` (list of `{locale, key, title}`). Validation is all-or-nothing:
+fix each reported item and submit again. A large task may be submitted in
+several batches with the same digest; untranslated pages show the original with
+a notice.
+
+When the user declines translation for this iteration, run
+`context translate skip --digest <expected_digest> --format json`. The website
+then publishes the pending pages in the primary language with a notice. Do not
+skip on your own judgment.
+
+Consume the returned `workflow.current` directly. In managed mode resume
+`context run --managed --until blocked-or-complete --format json`. Translating
+does not authorize a commit, upload or deployment.