docs: complete Chinese proofreading and generated reference pairing

scripts/project-doc-site.spec.ts

@@ -299,22 +299,54 @@ describe('docsPages locale routes', () => {
   })
 
   it('publishes the Cordis core API under matching locale structures', () => {
-    const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md', 'inherited.md']
+    const files = ['context.md', 'events.md', 'fiber.md', 'registry.md', 'service.md']
     for (const file of files) {
       const root = docsPages.find(page => page.route === `reference/cordis-api/${file}`)
       const english = docsPages.find(page => page.route === `en/reference/cordis-api/${file}`)
-      expect(root?.source).toBe(`docs/cordis-api/${file}`)
+      expect(root?.source).toBe(`docs/cordis-api/${file.replace(/\.md$/, '.zh.md')}`)
+      expect(root?.contentLocale).toBe('zh-CN')
       expect(root?.section).toBe('Cordis API')
-      expect(english?.source).toBe(root?.source)
+      expect(english?.source).toBe(`docs/cordis-api/${file}`)
+      expect(english?.contentLocale).toBe('en-US')
       expect(english?.section).toBe('Cordis Core API')
     }
   })
 
-  it('includes persistence event headings in both locale outlines', () => {
-    const pages = docsPages.filter(page => page.source === 'docs/persistence-catalog.md')
+  it('keeps Cordis inherited on the English fallback in both locales', () => {
+    const pages = docsPages.filter(page => page.route.endsWith('reference/cordis-api/inherited.md'))
     expect(pages).toHaveLength(2)
+    expect(pages.every(page => page.source === 'docs/cordis-api/inherited.md')).toBe(true)
+    expect(pages.every(page => page.contentLocale === 'en-US')).toBe(true)
+  })
+
+  it('includes persistence event headings in both locale outlines', () => {
+    const pages = docsPages.filter(page => page.route.endsWith('reference/persistence-catalog.md'))
+    expect(pages).toHaveLength(2)
+    expect(pages.map(page => page.source).sort()).toEqual([
+      'docs/persistence-catalog.md',
+      'docs/persistence-catalog.zh.md',
+    ])
     expect(pages.map(page => page.outline)).toEqual(['deep', 'deep'])
   })
+
+  it('projects reviewed generated counterparts into root locale routes', () => {
+    const routes = [
+      'reference/capability-seams.md',
+      'reference/agent-lifecycle.md',
+      'reference/tool-execution-pipeline.md',
+      'reference/config-catalog.md',
+      'reference/tool-catalog.md',
+      'reference/persistence-catalog.md',
+      'reference/cordis-api/context.md',
+      'reference/cordis-api/events.md',
+      'reference/cordis-api/fiber.md',
+      'reference/cordis-api/registry.md',
+      'reference/cordis-api/service.md',
+    ]
+    const pages = routes.map(route => docsPages.find(page => page.route === route))
+    expect(pages.every(page => page?.contentLocale === 'zh-CN')).toBe(true)
+    expect(pages.every(page => page?.source.endsWith('.zh.md'))).toBe(true)
+  })
 })
 
 describe('addProjectionFrontmatter', () => {

scripts/translation-pairing.manifest.json

@@ -4,18 +4,9 @@
     ".agents/notes/implemented/AGENTS.md",
     ".agents/notes/implemented/CLAUDE.md",
     "docs/AGENTS.md",
-    "docs/agent-lifecycle.md",
-    "docs/capability-seams.md",
-    "docs/config-catalog.md",
-    "docs/cordis-api/",
-    "docs/event-producer-consumer.md",
-    "docs/graph-atlas.md",
+    "docs/cordis-api/inherited.md",
     "docs/i18n/style-samples.md",
     "docs/i18n/terminology.md",
-    "docs/i18n/translation-prompt.md",
-    "docs/module-graph.md",
-    "docs/persistence-catalog.md",
-    "docs/tool-catalog.md",
-    "docs/tool-execution-pipeline.md"
+    "docs/i18n/translation-prompt.md"
   ]
 }

scripts/translation-pairing.spec.ts

@@ -19,6 +19,7 @@ import {
   parseTranslationPairingCliArgs,
   parseTranslationPairingManifest,
   partitionGeneratedRegions,
+  requiresSourceLanguageSwitcher,
   translationStructureDiff,
   translationStructureSignature,
 } from './translation-pairing.ts'
@@ -142,6 +143,16 @@ describe('translation pairing manifest', () => {
   })
 })
 
+describe('translation pairing switchers', () => {
+  it('exempts only paired generated English sources from reciprocal switchers', () => {
+    expect(requiresSourceLanguageSwitcher('docs/config-catalog.md')).toBe(false)
+    expect(requiresSourceLanguageSwitcher('docs/cordis-api/context.md')).toBe(false)
+    expect(requiresSourceLanguageSwitcher('docs/cordis-api/inherited.md')).toBe(false)
+    expect(requiresSourceLanguageSwitcher('docs/architecture.md')).toBe(true)
+    expect(requiresSourceLanguageSwitcher('packages/core/session/README.md')).toBe(true)
+  })
+})
+
 describe('translation pairing records', () => {
   const paths = translationPairPaths('docs/foo.md')
   const record = {

scripts/translation-pairing.ts

@@ -311,6 +311,27 @@ export function linksTo(tree: Nodes, target: string): boolean {
   return found
 }
 
+/** Generated English sources cannot carry a switcher without making their generator stale. */
+export function requiresSourceLanguageSwitcher(source: string): boolean {
+  return ![
+    'docs/agent-lifecycle.md',
+    'docs/capability-seams.md',
+    'docs/config-catalog.md',
+    'docs/cordis-api/context.md',
+    'docs/cordis-api/events.md',
+    'docs/cordis-api/fiber.md',
+    'docs/cordis-api/inherited.md',
+    'docs/cordis-api/registry.md',
+    'docs/cordis-api/service.md',
+    'docs/event-producer-consumer.md',
+    'docs/graph-atlas.md',
+    'docs/module-graph.md',
+    'docs/persistence-catalog.md',
+    'docs/tool-catalog.md',
+    'docs/tool-execution-pipeline.md',
+  ].includes(source)
+}
+
 /** Collect the ordered structural signature, skipping one switcher target. */
 export function translationStructureSignature(tree: Nodes, switcherTarget: string): TranslationStructureSignature {
   const sig: TranslationStructureSignature = { headings: [], code: [], tables: [], lists: [], links: [] }

scripts/verify-translation-pairing.ts

@@ -24,6 +24,7 @@ import {
   parseTranslationPairingCliArgs,
   parseTranslationPairingManifest,
   partitionGeneratedRegions,
+  requiresSourceLanguageSwitcher,
   isTranslationScopeFile,
   TRANSLATION_SCOPE_GLOB_EXCLUDES,
   translationStructureDiff,
@@ -254,7 +255,7 @@ for (const source of [...pairAnchors].sort()) {
   if (!linksTo(zhTree, basename(source))) {
     errors.push(`${zh}: missing language switcher — no link to ${basename(source)}`)
   }
-  if (!linksTo(sourceTree, basename(zh))) {
+  if (requiresSourceLanguageSwitcher(source) && !linksTo(sourceTree, basename(zh))) {
     errors.push(`${source}: missing language switcher — no link back to ${basename(zh)}`)
   }
   for (const divergence of translationStructureDiff(