feat(mirror): link canonical notes to WikiDocs

Author: junghan0611

AGENTS.md

@@ -52,6 +52,7 @@ Junghan Kim = GLG (힣) = GLGMAN (힣맨) = the junghanacs gardener. Use this eq
 | Repo | Purpose |
 |------|---------|
 | [garden_v5](https://github.com/junghan0611/garden_v5) | Quartz **v5** rebuild workspace (branch `main`) — separate from this live garden; do not merge or port |
+| [garden2wikidocs](https://github.com/junghan0611/garden2wikidocs) | Read-only publication translator from this canonical garden to the Korean-language WikiDocs discovery mirror |
 | [notes.junghanacs.com](https://github.com/junghanacs/notes.junghanacs.com) | **Retired source** — read-only history on `v4`, keeps old `blob/v4/…` permalinks alive, rollback target |
 | [GLG-Mono](https://github.com/junghan0611/GLG-Mono) | The garden's single typeface (header/title/body/code). Web subsetting SSOT: `docs/WEBFONT_SUBSET.md` |
 | [doomemacs-config](https://github.com/junghan0611/doomemacs-config) | Doom Emacs config — denote-export.sh, agent-server.el |
@@ -205,11 +206,29 @@ IndexNow: `scripts/post-build.sh` appends a "Recent Updates" block to `public/ll
 `quartz/components/Head.tsx` emits a single `@graph` with stable `@id`s so crawlers and LLMs merge node properties across pages. Restricted to the homepage and Denote-ID pages (tags/folder-index/404 excluded).
 
 - **Person** (`@id …/#person`) on every page — `name`, `alternateName: [GLG, GLGMAN]`, `jobTitle`, `description`, `knowsAbout`, `knowsLanguage`, `sameAs` (GitHub, LinkedIn, Bluesky, Mastodon, homepage), `image`.
-- **WebSite** (`#website`), **ProfilePage** (homepage only, `mainEntity → #person`, `primaryImageOfPage` as `ImageObject`), **BlogPosting** (notes, `author/publisher → #person`, `isBasedOn → GitHub source`).
+- **WebSite** (`#website`), **ProfilePage** (homepage only, `mainEntity → #person`, `primaryImageOfPage` as `ImageObject`), and per-section content nodes (`author/publisher → #person`, `isBasedOn → GitHub source`).
 - Profile photo: `quartz/static/profile.jpg` (640×640 grayscale) → served at `/static/profile.jpg`. Separate channel from `og:image` (`/static/og-image.png`); the face photo never overrides link-preview cards.
 - **Standard schema.org only.** No invented properties (e.g. `temporalStatus`) — crawlers drop non-standard terms. Synthesize at build time; never mutate the org source. No content `license` field until a content licence (CC-*) is actually chosen — `LICENSE.txt` is Quartz's MIT, not a content licence.
 - Next AEO lever (not yet shipped): `#+reference:` citekeys → frontmatter `refs[]` → schema.org `citation` (org-export side) so bib notes expose what primary sources they engage — the "footprints, not facade" signal.
 
+## WikiDocs discovery mirror
+
+The complete cross-repository contract is [`docs/WIKIDOCS_MIRROR.md`](docs/WIKIDOCS_MIRROR.md).
+This garden is the canonical, latest, and authored source; WikiDocs is a Korean-language discovery and
+reading mirror, and `garden2wikidocs` is the read-only translation harness.
+
+- Never modify Org or exported content Markdown for mirror plumbing. Quartz synthesizes mapped `sameAs` data
+  and the visible mirror link from `quartz/data/wikidocs-mirror.json`.
+- `garden2wikidocs/mapping.json` owns WikiDocs `page_id`/URL facts. The garden owns the explicit import gate
+  `scripts/sync-wikidocs-map.mjs` and the committed minimal snapshot; Netlify never reads a sibling checkout
+  or fetches the mapping over the network.
+- `garden2wikidocs` never writes into this repository. It reports a recovered stable mapping, then the garden
+  owner decides when to import it.
+- An unmapped new garden note is valid and must remain deployable. Mirror lag or failure never blocks the
+  canonical publication path.
+- Content `sameAs` points to the corresponding rendering; it is not an HTML canonical directive. Preserve the
+  uppercase-`T`/no-per-page-canonical invariant below.
+
 ## Build & URL invariants
 
 Denote IDs and all built URLs use **uppercase `T`** (`20250727T094722`). The lone lowercase outlier is `sitemap.xml <loc>` (explicit `.toLowerCase()` in `quartz/plugins/emitters/contentIndex.tsx`). Netlify 301s uppercase→lowercase and serves lowercase `200`; `remark42.inline.ts` restores uppercase at runtime for comments. There is **no per-page `<link rel="canonical">`** — a deliberate decision: adding one would conflict the uppercase-HTML / lowercase-response / lowercase-sitemap signals (Quartz upstream refuses canonical for the same reason). Don't "fix" this without a canary confirming Netlify can preserve uppercase.

content/llms.txt

@@ -10,6 +10,18 @@
 - Robots: https://notes.junghanacs.com/robots.txt
 - RSS: https://notes.junghanacs.com/index.xml
 
+## Canonical garden and WikiDocs discovery mirror
+
+- Canonical and latest garden: https://notes.junghanacs.com/
+- Canonical source repository: https://github.com/junghan0611/garden
+- Korean-language discovery mirror: https://wikidocs.net/book/20676
+- Mirror translation harness: https://github.com/junghan0611/garden2wikidocs
+
+The garden is the authored, canonical, and latest source.
+WikiDocs is a generated mirror for Korean-language search discovery and reading; it may appear first in search results but does not replace the garden.
+For current content, temporal history, backlinks, tags, comments, and source provenance, prefer the corresponding `notes.junghanacs.com` page.
+Mapped garden notes expose their stable WikiDocs rendering through schema.org `sameAs`, while each mirror page links back to its exact original and latest garden note.
+
 ## About
 
 This site is the digital garden of Junghan Kim (김정한) — also identified in schema.org JSON-LD as GLG, GLGMAN, 힣, 힣맨, and 정한.
@@ -57,8 +69,10 @@ Canonical definitions live in [VOCABULARY.md](https://github.com/junghan0611/jun
 
 ## Connected Repositories
 
-- **garden**: This garden's source (Quartz 4 + Markdown content)
+- **garden**: This garden's canonical source (Quartz 4 + Markdown content)
   - https://github.com/junghan0611/garden
+- **garden2wikidocs**: Read-only translation harness for the Korean-language WikiDocs discovery mirror
+  - https://github.com/junghan0611/garden2wikidocs
 - **junghan0611**: Profile, résumé, identity-document set and vocabulary
   - https://github.com/junghan0611/junghan0611
 - **entwurf**: Garden-citizen dispatch substrate — v2 delivery, meta-bridge, ACP plugin, and pi adapter

docs/WIKIDOCS_MIRROR.md

@@ -0,0 +1,129 @@
+# WikiDocs mirror contract
+
+This document is the technical contract between
+[`junghan0611/garden`](https://github.com/junghan0611/garden) and
+[`junghan0611/garden2wikidocs`](https://github.com/junghan0611/garden2wikidocs).
+The public rationale and project timeline live in Denote note
+`20260220T201100` (`§garden2wikidocs — 원본 가든을 건드리지 않는 위키독스 미러`).
+
+## Center
+
+> The garden is the canonical, latest, and authored source.
+> WikiDocs is a Korean-language discovery and reading mirror.
+> `garden2wikidocs` is the translation harness between them.
+
+WikiDocs may appear before the garden in Korean search results. That is an intended
+property of the discovery surface, not a transfer of authorship or source authority.
+Readers arriving there must have an exact route back to the garden, where backlinks,
+tags, history, comments, source links, and the latest revision live.
+
+## Field ownership
+
+| Field | Authority |
+|---|---|
+| Body, title, description, section | garden Markdown exported from Org |
+| Denote ID, source URL | garden |
+| `date`, `lastmod` | garden frontmatter |
+| WikiDocs `page_id`, mirror URL | `garden2wikidocs/mapping.json` |
+| Mirror synchronization status | `garden2wikidocs` / WikiDocs |
+| Canonical-versus-mirror policy | this garden |
+
+The Denote ID is the join key. Source metadata copied into `mapping.json` remains a
+cache of garden facts; it does not become their authority.
+
+## Data flow
+
+```text
+Org → exported garden Markdown → independent garden deploy
+                              ↓ read-only
+                    garden2wikidocs build
+                              ↓
+                 WikiDocs page_id recovery
+                              ↓
+            garden2wikidocs/mapping.json
+                              ↓ explicit owner-run import
+           garden/quartz/data/wikidocs-mirror.json
+                              ↓
+              Quartz JSON-LD + visible mirror link
+```
+
+The garden's Netlify build never reads a sibling checkout and never fetches a remote
+mapping over the network. `scripts/sync-wikidocs-map.mjs` is an explicit import gate:
+it validates the mirror ledger and commits only the minimal Denote-ID-to-URL snapshot
+needed by Quartz.
+
+`garden2wikidocs` must not write into the garden repository. It updates its own ledger
+and reports that a new stable `page_id` is ready; the garden owner decides when to
+import the new snapshot.
+
+## Publication ordering
+
+1. Export and deploy the garden independently.
+2. Let `garden2wikidocs` read the public garden files and update the WikiDocs mirror.
+3. Recover new WikiDocs `page_id` values and audit the mirror.
+4. Explicitly import the refreshed mapping snapshot into the garden.
+5. On the next garden deploy, emit the corresponding JSON-LD and visible mirror links.
+
+A new garden note may temporarily have no WikiDocs mapping. That is normal and must
+not fail a garden build. A mirror outage or delayed `page_id` recovery must never block
+the canonical publication path.
+
+## Garden output
+
+For a mapped Denote page, Quartz adds the stable WikiDocs URL to the page's
+CreativeWork JSON-LD as `sameAs` and shows a compact `WikiDocs mirror` link in content
+metadata. Both are synthesized at build time; Org and exported content Markdown are not
+modified for mirror plumbing.
+
+`sameAs` records a relationship between two renderings of the work. It is not an HTML
+canonical directive and does not grant WikiDocs authority over source metadata.
+
+The garden's existing uppercase-`T` URL behavior deliberately has no per-page
+`<link rel="canonical">`. This mirror integration does not change that invariant.
+
+## Mirror output
+
+Each generated WikiDocs page must contain a separate `원본·최신본` provenance block.
+It is system metadata, not part of the author's `이 노트에 대하여` abstract.
+
+- If an abstract exists: abstract → provenance block → body.
+- If no abstract exists: provenance block → body.
+- The block links to the exact garden URL and identifies the garden as original/latest.
+- It directs readers to the garden for backlinks, tags, history, comments, and updates.
+- Creation and modification dates come only from garden frontmatter.
+- Journal title dates and recent-first ordering use `source_date` (the week/date represented by the journal).
+- Meta, bibliography, notes, and botlog title dates and recent-first ordering use `source_lastmod`,
+  falling back to `source_date` only when `lastmod` is absent.
+- Mirror build, Git commit, file mtime, and sync time must never masquerade as either source date.
+- WikiDocs may force its sidebar into ascending title order. Preserve stable titles and `page_id` values;
+  provide an explicit recent-first chapter index rather than renumbering every page to fight the sidebar.
+- Mirror sync time belongs at book level, not repeated as a content date on every page.
+
+## Validation contract
+
+### Garden
+
+- Denote IDs and WikiDocs URLs are well formed.
+- Every imported WikiDocs page ID and URL is unique.
+- Every snapshot entry points to an existing garden Denote page.
+- A mapped page emits the exact `sameAs` URL and visible mirror link.
+- An unmapped new garden page remains valid and deployable.
+- Netlify requires no sibling repository or network mapping fetch.
+
+### garden2wikidocs
+
+- Every mirror page has exactly one exact source URL.
+- `gid`, source URL Denote ID, and mapping entry agree.
+- Journal title dates equal garden `date`; all other title dates equal garden `lastmod` with `date` fallback.
+- The provenance block is separate from the author's abstract.
+- An existing WikiDocs `page_id` remains stable across rebuilds.
+- Mirror-internal links use recovered WikiDocs URLs where available and retain the
+  garden URL as fallback.
+
+## Change protocol
+
+This file is the cross-repository policy SSOT. A change to source authority, field
+ownership, publication ordering, or the provenance contract is agreed here first.
+The `garden2wikidocs` skill references this contract and owns implementation details of
+the mirror pipeline; the garden owns its importer, local snapshot, structured data, and
+public canonical policy.

quartz/components/ContentMeta.tsx

@@ -5,6 +5,7 @@ import { classNames } from "../util/lang"
 import { i18n } from "../i18n"
 import { JSX } from "preact"
 import style from "./styles/contentMeta.scss"
+import { wikidocsMirrorUrl } from "../util/wikidocsMirror"
 
 interface ContentMetaOptions {
   showReadingTime: boolean
@@ -61,8 +62,9 @@ export default ((opts?: Partial<ContentMetaOptions>) => {
       segments.push(<span>{displayedTime}</span>)
     }
 
-    // GitHub links
+    // Source/provenance links
     const showGitHubLinks = options.repoLink && options.branch && !isIndex
+    const mirrorUrl = isIndex ? undefined : wikidocsMirrorUrl(fileData.slug)
 
     return (
       <div class="contentmeta-container">
@@ -86,6 +88,15 @@ export default ((opts?: Partial<ContentMetaOptions>) => {
             >
               ᨒ History ↗
             </a>
+            {mirrorUrl && (
+              <a
+                class="github-link external"
+                href={mirrorUrl}
+                title="한국어 검색과 읽기를 위한 위키독스 발견 미러"
+              >
+                ᨒ WikiDocs mirror ↗
+              </a>
+            )}
           </p>
         )}
         <p

quartz/components/Head.tsx

@@ -5,6 +5,7 @@ import { googleFontHref, googleFontSubsetHref } from "../util/theme"
 import { QuartzComponent, QuartzComponentConstructor, QuartzComponentProps } from "./types"
 import { unescapeHTML } from "../util/escape"
 import { CustomOgImagesEmitterName } from "../plugins/emitters/ogImage"
+import { wikidocsMirrorUrl } from "../util/wikidocsMirror"
 export default (() => {
   const Head: QuartzComponent = ({
     cfg,
@@ -205,6 +206,7 @@ export default (() => {
             }
             const contentType = typeBySection[section] ?? "BlogPosting"
             const crumbName = section.charAt(0).toUpperCase() + section.slice(1)
+            const mirrorUrl = wikidocsMirrorUrl(slug)
 
             const article = {
               // 타입이 바뀌어도 @id suffix(#article)는 고정 — 크롤러 노드 병합 안정성(v5에서 #content로 재명명).
@@ -214,6 +216,8 @@ export default (() => {
               "name": fm?.title ?? title,
               "url": socialUrl,
               "mainEntityOfPage": socialUrl,
+              // 같은 저작물의 한국어 발견 미러. 검색엔진 canonical 지시가 아니다.
+              ...(mirrorUrl ? { "sameAs": mirrorUrl } : {}),
               "author": { "@id": `${origin}/#person` },
               "publisher": { "@id": `${origin}/#person` },
               // 가든은 blog가 아니다. 폴더별 의미는 @type이 표현하고, 모든 공개 MD 산출물은