fix(docs): unblock Pages build by excluding 5 workspace-only symlinks

[hoainho]

Problem

The pages build and deployment workflow has been failing on every push to main for 5+ days (9 consecutive failures since 2026-06-01, run IDs 26739555993 → 27065617557). The CI log shows:

Error: No such file or directory @ rb_check_realpath_internal -
       /github/workspace/docs/HARNESS_BACKLOG.md

Root cause

5 symlinks in docs/ point OUTSIDE the cloned repo (they're workspace-only artifacts that resolve to /Users/nhonh/Documents/personal/docs/ on local dev):

Path	Target	Status
docs/HARNESS.md	../../docs/HARNESS.md	broken on CI
docs/HARNESS_BACKLOG.md	../../docs/HARNESS_BACKLOG.md	broken on CI
docs/FEATURE_INTAKE.md	../../docs/FEATURE_INTAKE.md	broken on CI
docs/evidence/README.md	../../../docs/evidence/README.md	broken on CI
docs/templates/story.md	../../../docs/templates/story.md	broken on CI

They were intentionally added in commit d39c598 docs: wire harness via workspace symlinks so the Sisyphus harness scaffolding is available locally. The symlinks resolve fine on dev but are dangling on the CI runner (which only has the cloned repo, not the workspace).

Fix

Surgical Jekyll _config.yml with an exclude: rule for the 5 workspace paths. This:

• ✅ Preserves the local dev workflow (the symlinks remain tracked in git)
• ✅ Unblocks the Pages build (Jekyll skips the broken symlinks)
• ✅ Does not pollute the public docs site with internal Sisyphus planning content (which would happen if we instead replaced the symlinks with the real 22 KB target files)
• ✅ Does not require deleting the symlinks (which would break the user's local harness wiring)

Verification

After merge, the next push to main will trigger the pages build and deployment workflow. Expected outcome: conclusion: success. The Pages site (https://hoainho.github.io/react-debugger-extension/) will be live.

Files changed

• docs/_config.yml (new, 9 lines)

That's it. One file, 9 lines.

Risk

Tiny. Adding a Jekyll _config.yml with a single exclude: directive is the most surgical possible fix. Jekyll will use all other defaults unchanged. If the _config.yml itself somehow breaks the build, git revert is one click.

[gemini-code-assist]

Code Review

This pull request attempts to prevent Jekyll build failures on the CI runner by adding workspace-only symlinks to the exclude list in docs/_config.yml. However, feedback indicates this approach will not work because Jekyll validates symlinks in safe mode before applying exclusion rules, causing the build to still crash. The reviewer suggests deleting these symlinks during the CI workflow instead.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

While adding these paths to the exclude list in _config.yml seems like a logical fix, it unfortunately will not prevent the Jekyll build from failing on GitHub Pages.

Why this happens:

1. Security Checks in Safe Mode: GitHub Pages runs Jekyll in safe mode. To prevent directory traversal vulnerabilities, Jekyll validates all symlinks in the source directory to ensure they do not resolve to paths outside the source directory.
2. Realpath Resolution: To perform this validation, Jekyll (or its path resolution dependencies) calls File.realpath on every symlink it encounters during the initial directory scan.
3. The Crash: Because these symlinks are broken on the CI runner, File.realpath throws Errno::ENOENT (No such file or directory @ rb_check_realpath_internal). This security check and directory scanning happen before the exclude rules are applied, meaning Jekyll will still crash with the exact same error.

Recommended Solution:

To preserve your local development workflow while unblocking the Pages build, you should delete these broken symlinks during the CI workflow before Jekyll runs.

Since the default GitHub Pages builder doesn't allow running custom commands, you can switch to a custom GitHub Actions workflow for deployment (which is now the standard recommendation by GitHub).

Here is an example of how you can structure the workflow step in .github/workflows/pages.yml to clean up the symlinks before building:

- name: Clean up workspace-only symlinks
  run: |
    rm -f docs/HARNESS.md docs/HARNESS_BACKLOG.md docs/FEATURE_INTAKE.md
    rm -rf docs/evidence docs/templates

This ensures the symlinks are tracked in Git for your local dev environment, but are safely removed on the CI runner before Jekyll scans the directory.