@c4a/context-cli 0.7.55 → 0.7.61

package/indexers/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "protocol": "context.indexer.cli-release-manifest/v1",
   "package": "@c4a/context-cli",
-  "version": "0.7.55",
+  "version": "0.7.61",
   "issuer": "context4ai/context",
   "bundles": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/context-cli",
-  "version": "0.7.55",
+  "version": "0.7.61",
   "type": "module",
   "description": "Local runtime and Agent integration for traceable knowledge production",
   "license": "MIT",
@@ -24,17 +24,17 @@
   },
   "dependencies": {
     "@c4a/agent-graph": "0.3.0",
-    "@c4a/context": "0.7.55",
-    "@c4a/extract": "0.7.55",
-    "@c4a/extract-contract": "0.7.55",
-    "@c4a/extract-go": "0.7.55",
-    "@c4a/extract-mdx": "0.7.55",
-    "@c4a/extract-proto": "0.7.55",
-    "@c4a/extract-rush": "0.7.55",
-    "@c4a/extract-sql": "0.7.55",
-    "@c4a/extract-style": "0.7.55",
-    "@c4a/extract-thrift": "0.7.55",
-    "@c4a/extract-ts": "0.7.55",
+    "@c4a/context": "0.7.61",
+    "@c4a/extract": "0.7.61",
+    "@c4a/extract-contract": "0.7.61",
+    "@c4a/extract-go": "0.7.61",
+    "@c4a/extract-mdx": "0.7.61",
+    "@c4a/extract-proto": "0.7.61",
+    "@c4a/extract-rush": "0.7.61",
+    "@c4a/extract-sql": "0.7.61",
+    "@c4a/extract-style": "0.7.61",
+    "@c4a/extract-thrift": "0.7.61",
+    "@c4a/extract-ts": "0.7.61",
     "@mermaid-js/layout-elk": "0.2.0",
     "commander": "^11.0.0",
     "fast-xml-parser": "^5.10.1",

package/parserEntryWorker.js

@@ -4535,7 +4535,7 @@ var init_siteTheme = __esm(() => {
 });
 
 // ../context/src/packageSite.ts
-var siteHrefSchema, packageSiteHomeActionSchema, packageSiteHomeResourceSchema, packageSiteHomeSchema, packageSiteSchema;
+var siteHrefSchema, packageSiteHomeActionSchema, packageSiteHomeResourceSchema, packageSiteHomeSchema, localeTagSchema, localizedTextSchema, packageSiteLocaleSchema, packageSiteNavLinkSchema, packageSiteMoreItemSchema, packageSiteSocialLinkSchema, packageSiteSchema;
 var init_packageSite = __esm(() => {
   init_siteTheme();
   init_zod();
@@ -4562,6 +4562,32 @@ var init_packageSite = __esm(() => {
     actions: exports_external.array(packageSiteHomeActionSchema).optional(),
     resources: exports_external.array(packageSiteHomeResourceSchema).optional()
   }).strict();
+  localeTagSchema = exports_external.string().regex(/^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$/u, "Use a BCP 47 language tag, such as zh-CN");
+  localizedTextSchema = exports_external.record(localeTagSchema, exports_external.string().trim().min(1));
+  packageSiteLocaleSchema = exports_external.object({
+    label: exports_external.string().trim().min(1).optional(),
+    title: exports_external.string().trim().min(1).optional(),
+    description: exports_external.string().optional(),
+    home: packageSiteHomeSchema.optional()
+  }).strict();
+  packageSiteNavLinkSchema = exports_external.object({
+    text: exports_external.string().trim().min(1),
+    link: siteHrefSchema,
+    locales: localizedTextSchema.optional()
+  }).strict();
+  packageSiteMoreItemSchema = exports_external.object({
+    text: exports_external.string().trim().min(1),
+    link: siteHrefSchema.optional(),
+    target: exports_external.object({ artifact_ref: exports_external.string().trim().min(1) }).strict().optional(),
+    locales: localizedTextSchema.optional()
+  }).strict().refine((value) => value.link === undefined !== (value.target === undefined), {
+    message: "A More menu item requires exactly one of link or target"
+  });
+  packageSiteSocialLinkSchema = exports_external.object({
+    icon: exports_external.enum(["github", "discord", "x", "youtube", "slack", "linkedin", "mastodon", "npm"]),
+    link: exports_external.string().regex(/^https:\/\//u, "Use an https URL"),
+    ariaLabel: exports_external.string().trim().min(1).optional()
+  }).strict();
   packageSiteSchema = exports_external.object({
     theme: siteThemeSchema.optional(),
     title: exports_external.string().trim().min(1).optional(),
@@ -4569,9 +4595,16 @@ var init_packageSite = __esm(() => {
     lang: exports_external.string().min(1).default("en-US"),
     base: exports_external.string().regex(/^\/(?:[a-zA-Z0-9_-]+\/)*$/, "Use / or a slash-delimited deployment path, such as /docs/").default("/"),
     home: packageSiteHomeSchema.optional(),
+    locales: exports_external.record(localeTagSchema, packageSiteLocaleSchema).optional(),
+    titleLink: siteHrefSchema.optional(),
+    nav: exports_external.array(packageSiteNavLinkSchema).optional(),
+    more: exports_external.array(packageSiteMoreItemSchema).optional(),
+    socialLinks: exports_external.array(packageSiteSocialLinkSchema).optional(),
+    localePreferenceKey: exports_external.string().regex(/^[a-zA-Z0-9:._-]+$/u).optional(),
     extensions: exports_external.object({
       root: exports_external.string().regex(/^src\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_-]+$/).default("src/site"),
       slots: exports_external.object({
+        brand: exports_external.string().min(1).optional(),
         banner: exports_external.union([exports_external.string().min(1), exports_external.literal(false)]).optional(),
         knowledge: exports_external.union([exports_external.string().min(1), exports_external.literal(false)]).optional(),
         resources: exports_external.union([exports_external.string().min(1), exports_external.literal(false)]).optional(),
@@ -4580,7 +4613,13 @@ var init_packageSite = __esm(() => {
       }).strict().optional(),
       pages: exports_external.record(exports_external.string().regex(/^[a-zA-Z0-9_-]+$/), exports_external.string().min(1)).optional()
     }).strict().optional()
-  }).strict();
+  }).strict().superRefine((value, context) => {
+    for (const tag of Object.keys(value.locales ?? {})) {
+      if (tag.toLowerCase() === value.lang.toLowerCase()) {
+        context.addIssue({ code: exports_external.ZodIssueCode.custom, path: ["locales", tag], message: "An additional locale must differ from the primary site lang" });
+      }
+    }
+  });
 });
 
 // ../context/src/contracts.ts

package/plugins/VERSION

@@ -1 +1 @@
-0.7.55
+0.7.61

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "c4a",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
-  "version": "0.7.55",
+  "version": "0.7.61",
   "author": {
     "name": "c4a"
   },

package/plugins/claude/skills/context-plan/references/project-planning.md

@@ -205,6 +205,12 @@ rewriting. Keep unrelated changes and still-correct knowledge out of the
 revision scope. Explain additions or removals through the behavior and coverage
 they affect, including cross-repository dependencies when material.
 
+Compare cited files by the object IDs from `git ls-tree` at both refs first;
+an unchanged ID needs no content read. In a partial clone each `git show`,
+`cat-file -s`, `ls-tree --long`, `blame` or `log -p` can download objects one at
+a time, so batch-fetch the object IDs you still need in one `git fetch` before
+reading them, and do not scan or size such a checkout with those commands.
+
 For documents, classify the findings as new, changed, deleted or invalidated,
 unchanged, or currently unreadable. A permission failure is an access gap, not
 evidence of deletion. Use available revisions and saved bodies for comparison;

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "c4a",
-  "version": "0.7.55",
+  "version": "0.7.61",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
   "author": { "name": "c4a" },
   "homepage": "https://github.com/context4ai/c4a",
@@ -10,7 +10,7 @@
   "skills": "./skills/",
   "interface": {
     "displayName": "C4A Context",
-    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.7.55",
+    "shortDescription": "Initialize and advance a local, source-linked project knowledge workspace.\nv0.7.61",
     "longDescription": "Create a Context workspace and use agent-guided next steps to register sources, run extraction, review candidates, build package outputs, and verify health without silently mutating source repositories.",
     "developerName": "c4a",
     "category": "Productivity",

package/plugins/codex/skills/context-plan/references/project-planning.md

@@ -205,6 +205,12 @@ rewriting. Keep unrelated changes and still-correct knowledge out of the
 revision scope. Explain additions or removals through the behavior and coverage
 they affect, including cross-repository dependencies when material.
 
+Compare cited files by the object IDs from `git ls-tree` at both refs first;
+an unchanged ID needs no content read. In a partial clone each `git show`,
+`cat-file -s`, `ls-tree --long`, `blame` or `log -p` can download objects one at
+a time, so batch-fetch the object IDs you still need in one `git fetch` before
+reading them, and do not scan or size such a checkout with those commands.
+
 For documents, classify the findings as new, changed, deleted or invalidated,
 unchanged, or currently unreadable. A permission failure is an access gap, not
 evidence of deletion. Use available revisions and saved bodies for comparison;

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "c4a",
   "displayName": "C4A Context",
-  "version": "0.7.55",
+  "version": "0.7.61",
   "description": "Start or continue a project-local knowledge workspace through one graph-routed entry.",
   "author": {
     "name": "Context4AI",

package/plugins/cursor/skills/context-plan/references/project-planning.md

@@ -205,6 +205,12 @@ rewriting. Keep unrelated changes and still-correct knowledge out of the
 revision scope. Explain additions or removals through the behavior and coverage
 they affect, including cross-repository dependencies when material.
 
+Compare cited files by the object IDs from `git ls-tree` at both refs first;
+an unchanged ID needs no content read. In a partial clone each `git show`,
+`cat-file -s`, `ls-tree --long`, `blame` or `log -p` can download objects one at
+a time, so batch-fetch the object IDs you still need in one `git fetch` before
+reading them, and do not scan or size such a checkout with those commands.
+
 For documents, classify the findings as new, changed, deleted or invalidated,
 unchanged, or currently unreadable. A permission failure is an access gap, not
 evidence of deletion. Use available revisions and saved bodies for comparison;

package/plugins/skills/context-plan/references/project-planning.md

@@ -205,6 +205,12 @@ rewriting. Keep unrelated changes and still-correct knowledge out of the
 revision scope. Explain additions or removals through the behavior and coverage
 they affect, including cross-repository dependencies when material.
 
+Compare cited files by the object IDs from `git ls-tree` at both refs first;
+an unchanged ID needs no content read. In a partial clone each `git show`,
+`cat-file -s`, `ls-tree --long`, `blame` or `log -p` can download objects one at
+a time, so batch-fetch the object IDs you still need in one `git fetch` before
+reading them, and do not scan or size such a checkout with those commands.
+
 For documents, classify the findings as new, changed, deleted or invalidated,
 unchanged, or currently unreadable. A permission failure is an access gap, not
 evidence of deletion. Use available revisions and saved bodies for comparison;

package/providers/context/actions/translate-site-locales.yaml

@@ -0,0 +1,5 @@
+schema: agent-graph.action.v1
+id: translate-site-locales
+runner: agent
+effect: write
+skill: skills/translate-site-locales/SKILL.md

package/providers/context/codes.yaml

@@ -10,6 +10,7 @@ codes:
   - { code: route.production.prepare-required, kind: route-reason, summary: Prepare the next eligible production directories. }
   - { code: route.production.writing-required, kind: route-reason, summary: Complete the issued production tasks using stage-local files. }
   - { code: route.production.scope-incomplete, kind: route-reason, summary: Resolve remaining investigation and material gaps without discarding accepted articles. }
+  - { code: route.translation.pending, kind: route-reason, summary: Translate approved knowledge for the website locales or publish it in the primary language. }
   - { code: route.version.content-changed, kind: route-reason, summary: Record an increasing workspace version and changelog for formal content changes. }
   - { code: route.workspace.recovery, kind: route-reason, summary: Inspect a stuck task independently of normal workflow evaluation., document: resources/procedures/task-recovery.md }
   - { code: route.indexer.maintenance, kind: route-reason, summary: Advance registered knowledge maintenance at a safe boundary., document: resources/procedures/knowledge-maintenance.md }

package/providers/context/graphs/workspace.yaml

@@ -328,6 +328,18 @@ nodes:
     kind: terminal
     terminalOutcome: completed
 
+  - id: translate-site-locales
+    kind: action
+    reasonCode: route.translation.pending
+    action: actions/translate-site-locales.yaml
+    satisfiedBy:
+      - path: translation.route_satisfied
+        equals: true
+    resources:
+      recommended:
+        - resources/manuals/guides/site-translation.md
+        - resources/manuals/guides/package-outputs.md
+
   - id: record-workspace-version
     kind: action
     reasonCode: route.version.content-changed
@@ -350,7 +362,8 @@ edges:
   - { from: close-approved-knowledge, to: choose-package-output }
   - { from: choose-package-output, to: configure-package-output, kind: gatedBy }
   - { from: configure-package-output, to: review-package-template }
-  - { from: review-package-template, to: record-workspace-version, kind: gatedBy }
+  - { from: review-package-template, to: translate-site-locales, kind: gatedBy }
+  - { from: translate-site-locales, to: record-workspace-version }
   - { from: record-workspace-version, to: build-next }
   - { from: build-next, to: flush-logs-after-build }
   - { from: flush-logs-after-build, to: current-scope-complete }

package/providers/context/manifest.json

@@ -2,7 +2,7 @@
   "schema": "agent-graph.bundle.v1",
   "provider": {
     "id": "c4a/context",
-    "version": "0.7.55"
+    "version": "0.7.61"
   },
   "providerManifest": "provider.yaml",
   "graphs": [
@@ -14,7 +14,7 @@
     {
       "id": "workspace",
       "path": "graphs/workspace.yaml",
-      "digest": "sha256:ba5d93d4883c28e9dfd21829528684d8d6ad9b1523d5e1895b67dc5106b43f7c"
+      "digest": "sha256:f72cdb49e298f081c148bf2b58929a415f93890450522da8fd0ab09ec30b2f92"
     }
   ],
   "actions": [
@@ -153,6 +153,11 @@
       "path": "actions/run-indexer-lifecycle.yaml",
       "digest": "sha256:1de783b14a3558f4ef540a42515a04c37f91a66d3266233834d9d5fbf09158c3"
     },
+    {
+      "id": "translate-site-locales",
+      "path": "actions/translate-site-locales.yaml",
+      "digest": "sha256:28f5e4ef974197b2533319e019e32cb5e5b8899fb47b8cd8706a4b0c16bb4b9b"
+    },
     {
       "id": "work-production-stage",
       "path": "actions/work-production-stage.yaml",
@@ -188,7 +193,7 @@
     {
       "id": "context.sdk.package-outputs",
       "path": "resources/manuals/guides/package-outputs.md",
-      "digest": "sha256:000255fafc7794d2c82880aa2cfcab7126929850ea6b77a29cecb272c9fd1683"
+      "digest": "sha256:b148a151ab78f64b9f35eecf300931c1dfe6b593dcd170cda2e7aed103ed43ad"
     },
     {
       "id": "context.sdk.package-templates",
@@ -198,12 +203,17 @@
     {
       "id": "context.sdk.page-customization",
       "path": "resources/manuals/guides/page-customization.md",
-      "digest": "sha256:57695bbbe3223c3c695029747856baae9e230059848e8f37506f908e843f9b0e"
+      "digest": "sha256:c8ba4cfe671f68a5bd27187e6f3c4d68a4c014f1f7018baaebf088decc404755"
     },
     {
       "id": "context.sdk.project-api",
       "path": "resources/manuals/reference/project-api.md",
-      "digest": "sha256:d7af120518aa721f06ae2233a824a674b50eee5096244d1b9eb5efb659f8ea90"
+      "digest": "sha256:923f3e7f564019a77e0fdecf5226d6fe40bb8ab35daf45b9ddef89491eae0d7a"
+    },
+    {
+      "id": "context.sdk.site-translation",
+      "path": "resources/manuals/guides/site-translation.md",
+      "digest": "sha256:369ffdc81481e48843891f5e007129d38047e4077a693b3bc58fa6c8e8f86666"
     },
     {
       "id": "context.sdk.template-variables",
@@ -557,13 +567,17 @@
       "path": "actions/run-indexer-lifecycle.yaml",
       "digest": "sha256:1de783b14a3558f4ef540a42515a04c37f91a66d3266233834d9d5fbf09158c3"
     },
+    {
+      "path": "actions/translate-site-locales.yaml",
+      "digest": "sha256:28f5e4ef974197b2533319e019e32cb5e5b8899fb47b8cd8706a4b0c16bb4b9b"
+    },
     {
       "path": "actions/work-production-stage.yaml",
       "digest": "sha256:d03f6a3bc90ae2f9ab266a58c55e36b4d8af364dc701d3ea4db4696a05fdb1f8"
     },
     {
       "path": "codes.yaml",
-      "digest": "sha256:89f188064a3d1a46b4a4356a5d20edf06cc93a5d2cd89f87618324369aa3b2b8"
+      "digest": "sha256:a4d4b0dccf5d2146e91f7baa1fe16e34d8c410fd1096e9ad9a75214a9006ee22"
     },
     {
       "path": "graphs/indexer.yaml",
@@ -571,11 +585,11 @@
     },
     {
       "path": "graphs/workspace.yaml",
-      "digest": "sha256:ba5d93d4883c28e9dfd21829528684d8d6ad9b1523d5e1895b67dc5106b43f7c"
+      "digest": "sha256:f72cdb49e298f081c148bf2b58929a415f93890450522da8fd0ab09ec30b2f92"
     },
     {
       "path": "provider.yaml",
-      "digest": "sha256:728b4b7df2a248903d6108df23e5e8b2538c1ee1c50f40b5dbe2c05d4c9bdb63"
+      "digest": "sha256:c354a5a0a4ef1357fbf845f5112a0ec43b4f6f89762e6eb2ee8619a1e985c540"
     },
     {
       "path": "resources/contracts/indexer-provider-guide.yaml",
@@ -651,11 +665,11 @@
     },
     {
       "path": "resources/manuals/guides/package-outputs.md",
-      "digest": "sha256:000255fafc7794d2c82880aa2cfcab7126929850ea6b77a29cecb272c9fd1683"
+      "digest": "sha256:b148a151ab78f64b9f35eecf300931c1dfe6b593dcd170cda2e7aed103ed43ad"
     },
     {
       "path": "resources/manuals/guides/page-customization.md",
-      "digest": "sha256:57695bbbe3223c3c695029747856baae9e230059848e8f37506f908e843f9b0e"
+      "digest": "sha256:c8ba4cfe671f68a5bd27187e6f3c4d68a4c014f1f7018baaebf088decc404755"
     },
     {
       "path": "resources/manuals/guides/repo-content.md",
@@ -665,6 +679,10 @@
       "path": "resources/manuals/guides/sessions.md",
       "digest": "sha256:b1d86d1fb96f1caba5baf7859bf20ac43e4fe890a40db453727cf2627d44fac6"
     },
+    {
+      "path": "resources/manuals/guides/site-translation.md",
+      "digest": "sha256:369ffdc81481e48843891f5e007129d38047e4077a693b3bc58fa6c8e8f86666"
+    },
     {
       "path": "resources/manuals/guides/source-batches.md",
       "digest": "sha256:9e338332986deab67932e62398db0221a7be139ac056f0856a46738164df411e"
@@ -691,7 +709,7 @@
     },
     {
       "path": "resources/manuals/reference/project-api.md",
-      "digest": "sha256:d7af120518aa721f06ae2233a824a674b50eee5096244d1b9eb5efb659f8ea90"
+      "digest": "sha256:923f3e7f564019a77e0fdecf5226d6fe40bb8ab35daf45b9ddef89491eae0d7a"
     },
     {
       "path": "resources/manuals/reference/template-variables.md",
@@ -863,7 +881,7 @@
     },
     {
       "path": "skills/record-workspace-version/SKILL.md",
-      "digest": "sha256:695b6b384a94743de08451f447bc8a135b6a7446dfab8e9b52ae16de54fd2903"
+      "digest": "sha256:87cf750c65ddcf7182c58ea7f60d507cb5c2c2366815303f950faa07084341d6"
     },
     {
       "path": "skills/recover-workspace/SKILL.md",
@@ -881,6 +899,10 @@
       "path": "skills/run-indexer-lifecycle/SKILL.md",
       "digest": "sha256:e56bf044855a3a66aa75a12d16ecba730b11a1e695f1ce75f2ea0af81384a011"
     },
+    {
+      "path": "skills/translate-site-locales/SKILL.md",
+      "digest": "sha256:b5197f6568b1443022d631f661d7484291c9be512b78109f91e6b42806294e7e"
+    },
     {
       "path": "skills/work-production-stage/SKILL.md",
       "digest": "sha256:676289693df57b5887f104d751dd9c8cc73fb1c903e4df7088f110ef6147388a"
@@ -890,5 +912,5 @@
     "indexer": [],
     "workspace": []
   },
-  "digest": "sha256:53f022509a8a69dbf8e50b826083bb143997a758aa8d212614d4b72d020a7909"
+  "digest": "sha256:e0ee85edddee31b622543e6488e0f538d81d8edd03b8d353c66baec9dfb69e60"
 }

package/providers/context/provider.yaml

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

package/providers/context/resources/manuals/guides/package-outputs.md

@@ -108,10 +108,14 @@ screens the homepage content aligns with article content while preserving the
 sidebar rail; on narrow screens it uses the available width. Motion is limited
 to short card entrance and hover feedback and is disabled when the reader asks
 the operating system to reduce motion.
-The website uses a full-width VitePress theme with system fonts, compact navigation,
-a wide reading area and a smaller article outline. It starts in
-light mode regardless of the operating system; an explicit reader choice is
-remembered in browser storage. Search runs locally, without a search service.
+The website uses a VitePress theme with system fonts and compact navigation. The
+top bar, homepage and articles share a centered 1440px container with 32px
+margins (16px on phones); on wide screens the sidebar sits at its left edge and
+articles keep a wide reading area and a smaller outline. Navigation is centered
+in the top bar, which ends with icon buttons for search, theme, social links and
+reader language; search, or Cmd/Ctrl+K, opens a dialog over a blurred page. The theme follows the
+operating system until the reader switches it; that choice is remembered in
+browser storage. Search runs locally, without a search service.
 Mermaid renders in the browser using the website theme, with fit, original-size,
 zoom, full-screen and source controls. Controls appear on hover or keyboard focus
 (and remain visible on touch devices). Layout and source/copy actions are on the
@@ -141,6 +145,32 @@ reachable as linked read-only pages, but have no automatically added navigation
 section. A reader-facing usage guide can link them where appropriate.
 Section landing pages have stable URLs separate from article URLs.
 
+`site.nav` appends links after the reading directories, and `site.more` adds
+items to the More menu before LLM Docs and Changelog. A More item uses either
+`link` or `target: { artifact_ref }`; a target is an approved article kept
+outside the knowledge map (for example release notes or a contribution guide),
+so it is not reported as unplaced. A missing target blocks the build. Links that
+start with `/` are origin paths, such as a sibling application on the same
+domain, and are not prefixed with `site.base`. `locales` on a nav or More item
+translates its text per language tag. `socialLinks` adds icon links in the top
+bar; each requires an `https` URL.
+
+`site.locales` adds reader languages, for example
+`locales: { "zh-CN": { title: "项目知识" } }`. Every page keeps one URL and
+carries each language; the reader's language decides which one is shown, so
+links, navigation and custom pages need no per-language routes. Each locale may
+override `label`, `title`, `description` and `home`. Translations are stored in
+the workspace under `translations/<tag>/` and follow the
+[site translation](site-translation.md) procedure. The top bar language button
+switches the current page in place. A saved choice wins, then the browser
+languages, then `site.lang`; the choice is remembered under
+`site.localePreferenceKey` (default `context-locale:<package>:<base>`), which
+sites on one origin can share. Pages without a current translation show the
+original with a notice. LLM Docs and Changelog stay in the primary language.
+`context-site-map.json` lists translated, stale and missing counts per locale.
+Without `site.locales` the button still switches the interface between Chinese
+and English.
+
 `dist/<base>-site/context-site-map.json` records each article's approved path, KB path and
 site path, plus the projected menu and unresolved targets. URLs are derived from
 article identity; legacy pages without `artifact_ref` use their approved path,

package/providers/context/resources/manuals/guides/page-customization.md

@@ -38,11 +38,27 @@ credentials or private configuration in frontend files. Hidden files,
 | `resources` | Resource card group | Replace with a component |
 | `footer` | Existing homepage footer | Replace with a component |
 | `floating` | Empty | Client-only component fixed at the bottom right on all pages |
+| `brand` | Site title text | Component shown at the start of the top bar, for example a logo |
+
+`site.titleLink` sets where the top-bar title leads; it defaults to the site
+home. A root-relative link such as `/` addresses the site origin rather than
+the site `base`, so a documentation site under `/docs/` can return to a product
+homepage.
 
 Omit a slot to retain its default; set it to `false` to hide it. A component
 replaces only its slot, not the global navigation, language switch or article
 provenance. Components can use VitePress `useData()` and `useRoute()` for theme,
 page and route information. Import scoped CSS from components for local styling.
+Pages prerender in the light theme. For a reader who starts in the dark theme,
+slot components are mounted again after the page loads, so markup bound to
+`isDark` matches the reader's theme.
+
+Pages keep one URL for every reader language. `useData().lang` is the reader's
+language after mount and `site.lang` during static rendering;
+`theme.contextLocales` lists `primary`, `tags` and `labels`. To show the right
+language from the first paint, render each language and mark it with
+`data-context-locales="<tag>"` (a space-separated list for shared content); the
+site stylesheet hides the others.
 
 The floating component owns its button, chat/bot panel and open/close behavior.
 Keep its panel within the viewport and preserve keyboard focus and close controls.

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,11 @@ 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. Navigation and language fields are `nav`, `more`,
+`socialLinks`, `locales` and `localePreferenceKey`; see
+[Package Outputs](../guides/package-outputs.md) and
+[Site translation](../guides/site-translation.md). `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
@@ -197,8 +201,8 @@ or repository links. Knowledge map is projected from
 `src/knowledge-map.yaml` independently of KB directories; see
 [Package Outputs](../guides/package-outputs.md#optional-static-documentation-website).
 
-`site.extensions` optionally names a trusted `src/site` root, homepage and floating
-`slots`, and custom Markdown `pages`. Place custom pages in the same knowledge map
+`site.extensions` optionally names a trusted `src/site` root, homepage, footer,
+brand and floating `slots`, and custom Markdown `pages`. Place custom pages in the same knowledge map
 with `target.artifact_ref: "site:<page-key>"`. See
 [Page content customization](../guides/page-customization.md) for the configuration
 and the boundary between presentation code and approved knowledge.

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.