fix(docs): align site with bilingual source pairs

scripts/project-doc-site.spec.ts

@@ -20,6 +20,7 @@ function fixture(): { root: string; pages: DocsPage[] } {
   mkdirSync(join(root, 'packages'), { recursive: true })
   writeFileSync(join(root, 'docs/a.md'), '# A\n')
   writeFileSync(join(root, 'docs/b.md'), '# B\n')
+  writeFileSync(join(root, 'docs/x(y).md'), '# Parentheses\n')
   writeFileSync(join(root, 'packages/tool.ts'), 'one\ntwo\n')
   writeFileSync(join(root, 'packages/logo.svg'), '<svg/>\n')
   return {
@@ -88,6 +89,46 @@ describe('rewriteMarkdown', () => {
     })).toBe(source)
   })
 
+  it('replaces the destination token without changing repeated titles or escapes', () => {
+    const { root, pages } = fixture()
+    const source = '[title](b.md "b.md") [escaped](x\\(y\\).md)\n'
+    expect(rewriteMarkdown(source, {
+      locale: 'en',
+      sourcePath: 'docs/a.md',
+      route: 'en/a.md',
+      pages,
+      repoRoot: root,
+      repositoryRef: 'abc123',
+    })).toBe(
+      '[title](./reference/b.md "b.md") '
+      + '[escaped](https://github.com/deepseek-harness/deepseek-harness/blob/abc123/docs/x(y).md)\n',
+    )
+  })
+
+  it('routes a pair switcher across locales while ordinary links stay in locale', () => {
+    const { root, pages } = fixture()
+    writeFileSync(join(root, 'docs/a.zh.md'), '# A\n')
+    const paired = pages.filter(page => page.source !== 'docs/a.md')
+    paired.push(
+      {
+        locale: 'root', contentLocale: 'zh-CN', source: 'docs/a.zh.md', sourceAliases: ['docs/a.md'],
+        route: 'guide/a.md', label: 'A', sidebar: 'zh-guide', section: 'Test', order: 1,
+      },
+      {
+        locale: 'en', contentLocale: 'en-US', source: 'docs/a.md', sourceAliases: ['docs/a.zh.md'],
+        route: 'en/guide/a.md', label: 'A', sidebar: 'en-guide', section: 'Test', order: 1,
+      },
+    )
+    expect(rewriteMarkdown('[English](a.md) [B](b.md)\n', {
+      locale: 'root',
+      sourcePath: 'docs/a.zh.md',
+      route: 'guide/a.md',
+      pages: paired,
+      repoRoot: root,
+      repositoryRef: 'abc123',
+    })).toBe('[English](../en/guide/a.md) [B](../reference-root/b.md)\n')
+  })
+
   it('fails loud when a relative target is missing', () => {
     const { root, pages } = fixture()
     expect(() => rewriteMarkdown('[missing](missing.md)\n', {
@@ -102,14 +143,21 @@ describe('rewriteMarkdown', () => {
 })
 
 describe('docsPages locale routes', () => {
-  it('publishes the same canonical source at every corresponding locale route', () => {
+  it('publishes every route in both locales and selects paired user sources', () => {
     const byRoute = new Map(docsPages.map(page => [page.route, page]))
     for (const page of docsPages.filter(page => page.locale === 'root')) {
       const counterpart = byRoute.get(`en/${page.route}`)
       expect(counterpart, page.route).toBeDefined()
       expect(counterpart?.locale).toBe('en')
-      expect(counterpart?.source).toBe(page.source)
-      expect(counterpart?.contentLocale).toBe(page.contentLocale)
+      if (page.source.startsWith('docs/user/')) {
+        expect(page.source).toMatch(/\.zh\.md$/)
+        expect(page.contentLocale).toBe('zh-CN')
+        expect(counterpart?.source).toBe(page.source.replace(/\.zh\.md$/, '.md'))
+        expect(counterpart?.contentLocale).toBe('en-US')
+      } else {
+        expect(counterpart?.source).toBe(page.source)
+        expect(counterpart?.contentLocale).toBe(page.contentLocale)
+      }
     }
   })
 })