workspace: make Quarto PR preview robust (un-failable comment + correct URL on private repos)

Two latent bugs in the reusable Quarto deploy workflow made a freshly
scaffolded repo's first PR look broken (red deploy check, no/wrong preview
link) even when the site published fine:

1. The preview-comment gh api read was unguarded under set -e; a transient
   5xx HTML body breaks --jq and abORTS the deploy after publish. Now the
   block runs under set +e and closes on a guaranteed-success command.
2. The preview URL was hardcoded to <owner>.github.io/<repo>, dead on
   private/internal repos that serve from an obfuscated *.pages.github.io
   domain. Now resolved from the Pages API with fallback; deploy job and
   scaffold docs.yml template grant pages: read.

Supersedes #91, #92, #93.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: gas2own

.github/workflows/workspace-quarto-site.yml

@@ -87,6 +87,10 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
+      # `pages: read` lets us resolve the site's real served URL from the Pages
+      # API (private/internal repos serve from an obfuscated *.pages.github.io
+      # domain, not <owner>.github.io/<repo>). Degrades gracefully if absent.
+      pages: read
     concurrency:
       group: pages-${{ github.event.pull_request.number || github.ref }}
       cancel-in-progress: true
@@ -145,19 +149,33 @@ jobs:
 
           # For a PR, ensure exactly one preview-link comment (create or update),
           # independent of whether the content changed. Best-effort — a comment
-          # hiccup shouldn't fail an otherwise-successful publish.
+          # hiccup shouldn't fail an otherwise-successful publish, so the whole
+          # block runs with errexit disabled and closes on a guaranteed success.
           if [ "${{ github.event_name }}" = "pull_request" ]; then
-            url="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-$PR_NUMBER/"
+            set +e
+            # Resolve the site's real base URL from the Pages config. Private and
+            # internal repos serve from an obfuscated <random>.pages.github.io
+            # domain, NOT <owner>.github.io/<repo>, so hardcoding the latter
+            # yields a dead preview link there. Fall back to the canonical form
+            # if the Pages API is unavailable (e.g. token lacks `pages: read`).
+            base=$(gh api "repos/${{ github.repository }}/pages" --jq '.html_url' 2>/dev/null)
+            base="${base%/}"
+            [ -n "$base" ] || base="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
+            url="$base/pr-preview/pr-$PR_NUMBER/"
             body="📄 Preview: $url"
+            # Guard the read: it runs the same set of transient failure modes as
+            # the writes below (a 5xx returns an HTML body that --jq can't parse),
+            # so an unguarded assignment would abort the step mid-publish.
             existing=$(gh api "repos/${{ github.repository }}/issues/$PR_NUMBER/comments" \
-              --jq 'map(select(.body | startswith("📄 Preview:"))) | .[0].id // empty')
+              --jq 'map(select(.body | startswith("📄 Preview:"))) | .[0].id // empty' 2>/dev/null)
             if [ -n "$existing" ]; then
               gh api "repos/${{ github.repository }}/issues/comments/$existing" -X PATCH -f body="$body" >/dev/null \
                 || echo "::warning::could not update preview comment"
             else
               gh api "repos/${{ github.repository }}/issues/$PR_NUMBER/comments" -f body="$body" >/dev/null \
                 || echo "::warning::could not create preview comment"
             fi
+            set -e
           fi
 
   # Remove a PR's preview when the PR closes. Shares that PR's concurrency group

plugins/asta-tools/skills/workspace/assets/docs.yml

@@ -13,9 +13,12 @@ on:
 #
 # The token needs write access for gh-pages pushes and PR preview comments;
 # the called workflow's jobs individually downscope to least privilege.
+# `pages: read` lets the deploy job resolve the real served URL for the preview
+# link (private/internal repos use an obfuscated *.pages.github.io domain).
 permissions:
   contents: write
   pull-requests: write
+  pages: read
 
 jobs:
   docs: