From a965b2b2deb1e2cf2e831e7872b89012978835ed Mon Sep 17 00:00:00 2001
From: Xuepoo Foter <144407384+Xuepoo@users.noreply.github.com>
Date: Mon, 5 Oct 2026 17:45:45 +0800
Subject: [PATCH] [CTX-0279] docs(website-sync): update pin-advance CLI to
 schema-2 form

Replace the pre-schema-2 pin-advance commands with the canonical just docs-sync --source <id> --pin <sha|tag> form (bitty-website#98), define <id> as the pin entry source id, and note the single-source --pin exception plus the rejected PIN= form. Closes #382.
---
 docs/development/website-sync.md | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/docs/development/website-sync.md b/docs/development/website-sync.md
index 339fe65..c91c10f 100644
--- a/docs/development/website-sync.md
+++ b/docs/development/website-sync.md
@@ -65,9 +65,15 @@ resolves to a single SHA. The file has no extra keys and is committed.
 Synchronization is the single command defined by SY-2:
 
 ```sh
-bun run sync:docs --pin <40-char-sha-or-tag>
+just docs-sync --source <id> --pin <sha|tag>
+# equivalent: bun run sync:docs --source <id> --pin <sha|tag>
 ```
 
+`<id>` is the pin entry's source id (for example `bitty-docs`).
+`--pin` without `--source` is accepted only while exactly one source
+is pinned; once more than one source is pinned, `--pin` requires
+`--source`.
+
 Behavior, per the RFC and `bitty-website/scripts/sync-docs.mjs`:
 
 1. Reject a missing `--pin`, a short SHA, or a floating name such as
@@ -277,10 +283,14 @@ publish a docs change:
    mirror:
 
    ```sh
-   just docs-sync PIN=<merged-docs-sha>
-   # equivalent: bun run sync:docs --pin <merged-docs-sha>
+   just docs-sync --source <id> --pin <merged-docs-sha>
+   # equivalent: bun run sync:docs --source <id> --pin <merged-docs-sha>
    ```
 
+   `<id>` is the pin entry's source id (for example `bitty-docs`).
+   The `PIN=<sha>` just-variable form is rejected; pass `--source`
+   and `--pin` as arguments.
+
 3. Verify the mirror is current and reproducible:
 
    ```sh
@@ -319,8 +329,9 @@ here.
    `docs/project/redirects.json` when a published identity moves, and
    passes `just check`.
 2. The `bitty-website` change advances the pin to that exact docs SHA
-   via `bun run sync:docs --pin <sha>`, implements presentation or
-   routing changes, and passes `just check` with the new pin.
+   via `just docs-sync --source <id> --pin <sha>`, implements
+   presentation or routing changes, and passes `just check` with the
+   new pin.
 3. Each pull request links the other (`Docs-PR`, optional `Code-PR`,
    `RFC: Website Delivery RFC OQ-023`, `CarryCtx: CTX-XXXX`) and names
    ordering constraints.