infra: add sync:ii-spec script, port II spec commits, and sync vc-spec

.github/workflows/sync-ii-spec.yml

@@ -0,0 +1,160 @@
+name: Sync II spec
+
+on:
+  schedule:
+    - cron: '0 9 * * 2' # Weekly on Tuesday (II releases are typically Monday/Tuesday)
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 0
+
+      - name: Create GitHub App Token
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        id: app-token
+        with:
+          client-id: ${{ vars.PR_AUTOMATION_BOT_PUBLIC_CLIENT_ID }}
+          private-key: ${{ secrets.PR_AUTOMATION_BOT_PUBLIC_PRIVATE_KEY }}
+
+      - name: Initialize internetidentity submodule at current pin
+        run: |
+          git config --global url."https://github.com/".insteadOf "git@github.com:"
+          git submodule update --init --depth 1 .sources/internetidentity
+
+      - name: Get current pinned hash
+        id: current
+        run: |
+          HASH=$(git -C .sources/internetidentity rev-parse HEAD)
+          echo "hash=$HASH" >> $GITHUB_OUTPUT
+          echo "short=$(git -C .sources/internetidentity rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+
+      - name: Fetch latest release tag and resolve hash
+        id: latest
+        run: |
+          git -C .sources/internetidentity fetch --tags --depth 100 origin
+          TAG=$(git -C .sources/internetidentity tag --sort=-version:refname \
+            | grep '^release-[0-9][0-9][0-9][0-9]-' | head -1)
+          echo "Latest release tag: $TAG"
+          HASH=$(git -C .sources/internetidentity rev-parse "$TAG")
+          SHORT=$(git -C .sources/internetidentity rev-parse --short "$TAG")
+          echo "tag=$TAG" >> $GITHUB_OUTPUT
+          echo "hash=$HASH" >> $GITHUB_OUTPUT
+          echo "short=$SHORT" >> $GITHUB_OUTPUT
+
+      - name: Check if relevant files changed
+        id: check
+        run: |
+          CURRENT="${{ steps.current.outputs.hash }}"
+          LATEST="${{ steps.latest.outputs.hash }}"
+          BRANCH="infra/sync-ii-spec-${{ steps.latest.outputs.tag }}"
+
+          if [ "$CURRENT" = "$LATEST" ]; then
+            echo "Already at latest release ${{ steps.latest.outputs.tag }}. No update needed."
+            echo "needed=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          if git ls-remote --exit-code origin "refs/heads/${BRANCH}" > /dev/null 2>&1; then
+            echo "Branch $BRANCH already exists — PR likely open, skipping."
+            echo "needed=false" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Only proceed if the spec files themselves changed
+          CHANGED=$(git -C .sources/internetidentity diff --name-only "${CURRENT}..${LATEST}" -- \
+            docs/ii-spec.mdx \
+            docs/vc-spec.md \
+            src/internet_identity/internet_identity.did)
+
+          if [ -z "$CHANGED" ]; then
+            echo "No changes to ii-spec.mdx, vc-spec.md, or internet_identity.did. Skipping."
+            echo "needed=false" >> $GITHUB_OUTPUT
+          else
+            echo "Spec files changed:"
+            echo "$CHANGED"
+            echo "needed=true" >> $GITHUB_OUTPUT
+            echo "changed_files<<EOF" >> $GITHUB_OUTPUT
+            echo "$CHANGED" >> $GITHUB_OUTPUT
+            echo "EOF" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Bump submodule to latest main
+        if: steps.check.outputs.needed == 'true'
+        run: git -C .sources/internetidentity checkout ${{ steps.latest.outputs.hash }}
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        if: steps.check.outputs.needed == 'true'
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        if: steps.check.outputs.needed == 'true'
+        run: npm ci
+
+      - name: Initialize examples submodule (required for build)
+        if: steps.check.outputs.needed == 'true'
+        run: git submodule update --init --depth 1 .sources/examples
+
+      - name: Run II spec sync
+        if: steps.check.outputs.needed == 'true'
+        run: npm run sync:ii-spec
+
+      - name: Build check
+        if: steps.check.outputs.needed == 'true'
+        run: npm run build
+
+      - name: Update VERSIONS
+        if: steps.check.outputs.needed == 'true'
+        run: |
+          sed -i "s|^internetidentity.*|internetidentity      ${{ steps.latest.outputs.tag }}                                         ${{ steps.latest.outputs.short }}|" .sources/VERSIONS
+
+      - name: Create PR
+        if: steps.check.outputs.needed == 'true'
+        run: |
+          git config user.name "pr-automation-bot-public[bot]"
+          git config user.email "pr-automation-bot-public[bot]@users.noreply.github.com"
+
+          BRANCH="infra/sync-ii-spec-${{ steps.latest.outputs.tag }}"
+          git checkout -b "$BRANCH"
+          git add .sources/internetidentity docs/references/internet-identity-spec.md docs/references/verifiable-credentials-spec.md public/references/internet-identity.did .sources/VERSIONS
+          git commit -m "chore: sync II spec to dfinity/internet-identity ${{ steps.latest.outputs.tag }}"
+          git push -u origin "$BRANCH"
+
+          CHANGED="${{ steps.check.outputs.changed_files }}"
+          {
+            echo "## Summary"
+            echo ""
+            echo "Automated sync of the Internet Identity specification from \`dfinity/internet-identity\`."
+            echo ""
+            echo "**Release:** \`${{ steps.latest.outputs.tag }}\`  (pinned from \`${{ steps.current.outputs.short }}\` → \`${{ steps.latest.outputs.short }}\`)"
+            echo ""
+            echo "**Changed upstream files:**"
+            while IFS= read -r f; do
+              [ -n "$f" ] && echo "- \`$f\`"
+            done <<< "$CHANGED"
+            echo ""
+            echo "- Ran \`npm run sync:ii-spec\` — regenerated \`docs/references/internet-identity-spec.md\` and \`docs/references/verifiable-credentials-spec.md\`"
+            echo "- Build passed ✓"
+            echo ""
+            echo "## Checklist"
+            echo ""
+            echo "- [ ] Review the diff to \`docs/references/internet-identity-spec.md\` for content changes"
+            echo "- [ ] Review the diff to \`docs/references/verifiable-credentials-spec.md\` for content changes"
+            echo "- [ ] Check for new absolute \`internetcomputer.org\` link patterns (script exits non-zero if any were missed)"
+            echo "- [ ] Verify any renamed or restructured sections are reflected correctly"
+            echo ""
+            echo "## Sync recommendation"
+            echo ""
+            echo "\`sync from dfinity/internet-identity — docs/ii-spec.mdx, docs/vc-spec.md, src/internet_identity/internet_identity.did\`"
+          } > /tmp/pr-body.md
+
+          gh pr create \
+            --title "chore: sync II spec to dfinity/internet-identity ${{ steps.latest.outputs.tag }}" \
+            --body-file /tmp/pr-body.md
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}

.sources/VERSIONS

@@ -4,6 +4,13 @@
 # version. Those repos are: portal, examples, icskills, dotskills,
 # icp-cli-recipes, icp-cli-templates, icp-js-sdk-docs.
 #
+# internetidentity — uses date-based release tags (release-YYYY-MM-DD).
+#   Only ii-spec.mdx, vc-spec.md, and internet_identity.did are synced.
+#   Pin to the latest release tag, not the tip of main — spec changes are
+#   only live once the canister is deployed at that release.
+#   The automated workflow (.github/workflows/sync-ii-spec.yml) finds the
+#   latest release-YYYY-MM-DD tag and only opens a PR if those files changed.
+#
 # FORMAT: <submodule>   <version label>   <7-char hash>
 #
 # The hash is the authoritative ref — it is what .gitmodules pins and what
@@ -55,3 +62,4 @@ motoko-core           v2.4.0
 cdk-rs                ic-cdk v0.20.1 / ic-cdk-timers v1.0.0 / ic-cdk-executor v2.0.0  317f55c
 candid                2025-12-18  # candid v0.10.20, didc v0.5.4                2e4a2cf
 response-verification v3.1.0                                                    18c5a37
+internetidentity      release-2026-05-08                                         f6cf858

AGENTS.md

@@ -192,7 +192,7 @@ docs/                       # All documentation (.md only) — src/content/docs/
 All upstream source repos are pinned as **git submodules** under `.sources/`. This ensures every agent reads the exact same content, regardless of when they run.
 
 **Two pinning strategies:**
-- **Track latest release** — repos that publish versioned releases users install. Pin to the latest release tag.
+- **Track latest release** — repos where the release represents the live/deployed state. Pin to the latest release tag. Spec changes are only accurate once released.
 - **Track main/master** — content repos where the default branch *is* the canonical source.
 
 For current release hashes, see `.sources/VERSIONS`.
@@ -217,7 +217,7 @@ For current release hashes, see `.sources/VERSIONS`.
 | `.sources/dotskills` | `vincentkoc/dotskills` | `main` | Technical documentation skill (AGPL-3.0 — kept as submodule to avoid license mixing) |
 | `.agents/skills/icp-brand-voice` | n/a — lives directly in this repo | n/a | ICP / DFINITY brand voice: positioning, vocabulary, banned terms, voice attributes |
 | `.agents/skills/icp-brand-design` | n/a — lives directly in this repo | n/a | ICP / DFINITY brand design: color tokens, typography, layout, components, accessibility |
-| `.sources/internetidentity` | `dfinity/internet-identity` | `main` | Internet Identity spec (`docs/ii-spec.mdx`), Candid interface (`src/internet_identity/internet_identity.did`) |
+| `.sources/internetidentity` | `dfinity/internet-identity` | latest release | Internet Identity spec (`docs/ii-spec.mdx`), VC spec (`docs/vc-spec.md`), Candid interface (`src/internet_identity/internet_identity.did`) |
 
 ### Submodule initialization
 
@@ -292,7 +292,7 @@ EOF
 | `candid` | Check for spec changes affecting the Candid reference or type-mapping examples |
 | `response-verification` | Check for API changes affecting certified variables patterns |
 | `dotskills` | Check if the `technical-documentation` skill changed in ways that affect review criteria |
-| `internetidentity` | Check for spec changes in `docs/ii-spec.mdx`; re-sync `internet-identity-spec.md` (see link adaptation note below). Re-copy Candid interface from `src/internet_identity/internet_identity.did` if changed |
+| `internetidentity` | Run `npm run sync:ii-spec` — the script syncs both `ii-spec.mdx` → `docs/references/internet-identity-spec.md` and `vc-spec.md` → `docs/references/verifiable-credentials-spec.md`, handling all link rewrites, Candid inlining, and frontmatter in one pass. If the script exits with a warning about unhandled links, add the new pattern to `linkMap` (ii-spec) or `vcLinkMap` (vc-spec) in `scripts/sync-ii-spec.mjs`. Pin to the latest `release-YYYY-MM-DD` tag — spec changes are only live once the canister is deployed at that release. The **Sync II spec** workflow (`.github/workflows/sync-ii-spec.yml`) checks the latest release tag and only opens a PR when `docs/ii-spec.mdx`, `docs/vc-spec.md`, or `internet_identity.did` actually changed. Trigger manually for early sync. |
 | `chain-fusion-signer` | Check for changed canister IDs, API methods, or key derivation patterns |
 | `papi` | Check for changed payment interface or cycle cost model |
 | `ic-pub-key` | Check for changed CLI flags or commands |
@@ -317,14 +317,7 @@ EOF
    ```
 4. Run `npm run build` to confirm no broken links.
 
-**Link adaptation for `internet-identity-spec.md`:** The upstream source (`docs/ii-spec.mdx`) uses absolute `internetcomputer.org` URLs pointing to the IC interface spec. Our file uses relative paths into the split `ic-interface-spec/` directory. After every re-sync, run:
-```bash
-grep -n "ic-interface-spec" docs/references/internet-identity-spec.md
-```
-Any link of the form `internetcomputer.org/.../ic-interface-spec#<anchor>` or `./ic-interface-spec.md#<anchor>` must be converted. Use the anchor-to-file mapping at the bottom of `docs/references/internet-identity-spec.md` as the authoritative guide. If a new anchor appears that is not in the comment, find its file with:
-```bash
-grep -r "{#<anchor>}" docs/references/ic-interface-spec/
-```
+**Link adaptation for `internet-identity-spec.md` and `verifiable-credentials-spec.md`:** Both are handled automatically by `npm run sync:ii-spec`. The script rewrites stale `internetcomputer.org` links to internal relative paths using `linkMap` (ii-spec) and `vcLinkMap` (vc-spec) in `scripts/sync-ii-spec.mjs`. If a new unhandled link pattern appears, the script exits with a warning — add it to the appropriate map with the correct relative path (use `grep -r "{#<anchor>}" docs/references/ic-interface-spec/` to find which file owns a given anchor), then re-run. Stale links in `vc-spec.md` are tracked upstream in `dfinity/internet-identity#3889`; once fixed, the rewrites become harmless no-ops (old URL simply no longer appears in the source).
 
 ### Synced files from submodules
 

docs/guides/authentication/verifiable-credentials.md

@@ -395,7 +395,7 @@ The VC protocol provides the following privacy guarantees:
 
 ## Next steps
 
-- Read the [VC specification](https://github.com/dfinity/internet-identity/blob/main/docs/vc-spec.md) for the full protocol details.
+- Read the [VC specification](../../references/verifiable-credentials-spec.md) for the full protocol details.
 - Explore the [verifiable credentials playground](https://github.com/dfinity/vc-playground) for issuer and relying party reference implementations.
 - Review [Internet Identity integration](internet-identity.md) for authentication setup.
 - See the [Internet Identity specification](../../references/internet-identity-spec.md) for alternative derivation origins and canister signature details.

docs/references/index.md

@@ -36,6 +36,7 @@ Technical reference material for ICP development. These pages cover exact specif
 - **[HTTP Gateway Specification](http-gateway-protocol-spec.md)**: How boundary nodes serve canister HTTP responses with certification verification.
 - **[Candid Specification](candid-spec.md)**: The Candid interface description language: type system, encoding, and subtyping rules.
 - **[Internet Identity Specification](internet-identity-spec.md)**: Delegation chains, passkey management, and canister signatures.
+- **[Verifiable Credentials Specification](verifiable-credentials-spec.md)**: Normative protocol for issuing and verifying credentials on ICP.
 
 ## Governance