* docs: host documentation on GitHub Pages with VitePress

Move README content into a proper documentation site built with VitePress
and deployed to https://yao-pkg.github.io/pkg/ via GitHub Actions.

- Landing page with pkg identity (amber/pink palette from logo)
- Guide split into 21 focused pages (getting started, targets, config,
  bytecode, compression, SEA mode, snapshot FS, native addons, ESM, API,
  troubleshooting, advanced)
- New SEA vs Standard page highlighting the stock-binary benefit and
  linking the pkg-fetch elimination roadmap (#231)
- DEVELOPMENT.md and docs/ARCHITECTURE.md canonical sources moved into
  docs-site/, roots replaced with stub pointers to avoid drift
- README trimmed to install + quick start + links to hosted docs
- .github/workflows/docs.yml builds and deploys on push to main

Manual follow-up: enable GitHub Pages with Source = GitHub Actions in
repo settings.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: update GitHub Actions to use latest versions of checkout, setup-node, and deploy-pages

* docs: address self-review feedback on docs site PR

- gate docs workflow on PRs (build-only) to catch VitePress breakage before merge
- switch workflow to npm ci with cache-dependency-path for reproducible installs
- read site version from package.json so nav dropdown no longer rots each release
- reconcile SEA vs Standard messaging on the guide landing page
- fix typos and stale DEVELOPMENT.md references in copilot-instructions
- mark root DEVELOPMENT.md and docs/ARCHITECTURE.md stubs as non-canonical
- replace non-standard -webkit-linear-gradient with standard linear-gradient

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: major docs site overhaul — tutorials, recipes, mermaid, migration

New pages:
- guide/migration.md — drop-in migration from archived vercel/pkg fork
- guide/recipes.md — copy-paste cookbook for common tasks
- changelog.md — CHANGELOG.md mirrored into the docs site via include

Rewritten pages:
- guide/getting-started.md — first-binary tutorial with code groups + full
  CLI table; no more raw --help dump
- guide/sea-mode.md — leads with a hello-world walkthrough
- guide/configuration.md — full schema table + production example
- guide/targets.md — code groups + tip callout + alpine/musl section
- guide/environment.md — inlined pkg-fetch vars + PKG_EXECPATH clarification
- guide/troubleshooting.md — NODE_OPTIONS dead end replaced with a full fix,
  check-this-first preface added
- guide/bytecode|compression|options|build|output|snapshot-fs|native-addons|
  esm|api|packaged-app|custom-node|detecting-assets|advanced-debug-vfs|
  advanced-windows-metadata — expanded + frontmatter + next-step links

VitePress config:
- withMermaid for mermaid flowchart support
- sitemap.hostname for SEO
- outline level raised to [2, 4]
- Collapsed singleton sidebar groups into a Cookbook section
- Added Recipes to the top nav
- Version dropdown links to migration + changelog

Landing page:
- vercel/pkg fork banner
- Social badges (npm version, downloads, stars, CI, license)
- Code groups for CLI vs package.json vs Node.js API
- Standard vs SEA side-by-side

Architecture:
- Top-level mermaid overview comparing both build paths
- Mermaid flowcharts for traditional + SEA build pipelines
- Mermaid flow for VFS provider path resolution
- ASCII diagrams kept for readers who prefer them

Development page:
- Full docs-site local dev workflow
- Structure, mermaid how-to, new-page checklist
- Canonical-source note for the root stubs

Polish:
- Responsive hero image on small viewports
- Fork-banner CSS
- .nvmrc pinning docs-site to Node 22
- Frontmatter (title + description) on every guide page for SEO
- Twitter card meta

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add hero terminal GIF and fix badge stacking on landing page

- Record a real 15s pkg session (mkdir → echo → pkg index.js → ls → run)
  with VHS as docs-site/public/hero.gif (98KB). Tape-based so it is
  reproducible in CI if we want to regenerate it later.
- Embed the GIF in the landing page as a figure under the fork banner.
- Replace the inline HTML badge anchors with Markdown image links on
  a single line so VitePress renders them inside a single <p>. The old
  setup put each anchor on its own line which the markdown processor
  wrapped in separate paragraphs, stacking the badges vertically.
- Add .landing-badges / .landing-demo / .landing-body CSS: flex layout
  for the badge row, shadow + border-radius on the demo GIF, consistent
  max-width + padding on the content block.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: re-record hero GIF with a working sandboxed pkg wrapper

The previous recording ran VHS with a PATH that did not include the nvm
node bin dir, so the /tmp/bin/pkg wrapper's `env ... node ...` invocation
failed with "env: node: No such file or directory" and the session showed
three cascading errors instead of a successful build.

Fix: hardcode the absolute node path inside the wrapper so it works under
any restricted PATH. Re-recorded — now shows the real pkg build producing
three binaries and running the linux one.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: update mermaid diagram styles for better readability and adjust SEA mode documentation

* docs: enhance dark mode visibility for mermaid diagrams and update native addon notes

* docs: trim docs-site verbosity and split architecture doc

Audience split: keep the detailed pipelines, binary layouts, VFS provider,
worker bootstrap and patch tables as docs/ARCHITECTURE.md (contributor /
agent reference), and replace docs-site/architecture.md with a lean ~110
line user overview that links back to it.

Also dedup SEA-vs-standard and walker explanations across index pages,
collapse the pkg-fetch roadmap down to a pointer to #231, share the
reference sidebar config, and add a jump TOC to the recipes page.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: clarify cross-compile support and Node 22 regression

Standard cross-compile is confirmed broken on Node 22 targets (builds
succeed but linux-arm64 crashes with UNEXPECTED-20 and win-x64 exits
silently, matching #87 and #181). Node 20 and Node 24 are fine in both
Standard and Enhanced SEA modes. Rewrite the targets.md Cross-compilation
section as a node-version-keyed support table with the regression called
out, and reference it from the landing page, getting-started, and the
sea-vs-standard feature matrix.

Verified on a Linux x86_64 host against linux-x64, linux-arm64 (via
docker + QEMU) and win-x64 (via docker + Wine) for each of Node 20, 22,
and 24 using the pkg-xcompile-test harness.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore(skills): add pkg-xcompile-test skill

Project-local skill (under .claude/skills/) that runs a full
(mode × target) cross-compile matrix for pkg and reports which
combinations work. Default modes are std, std-public
(--public-packages "*" --public) and sea; targets cover linux-x64,
linux-arm64 (via docker + QEMU), win-x64 (via docker + Wine), and
macos-* (build only — runtime verification needs a real Mac).

The run-matrix.sh script auto-switches nvm to match the target node
major, resolves PKG_BIN from its own location (<repo>/lib-es5/bin.js),
and writes binaries to $PKG_XCOMPILE_WORKDIR (default /tmp/pkg-xcompile)
so the working tree stays clean.

SKILL.md records the known results for node 20/22/24 as of 2026-04-15
and documents the wine-in-docker stdout gotcha.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: add cross-compile matrix workflow

Adds a GitHub Actions workflow that builds hello.js from every supported
host runner (linux-x64, linux-arm64, macos-x64, macos-arm64, win-x64)
for every target triple, in Standard / Standard+public / SEA modes on
Node 22. Each produced binary is then executed on its target runner,
and a per-mode matrix of the host-to-target results is posted as a
sticky PR comment.

Structured as three stages:

  1. build   — matrix of (host × mode × node); each job compiles all
               targets from that host and uploads the binaries.
  2. run     — one job per target runner; downloads all artifacts,
               filters by target, runs each binary, writes result JSON.
  3. collate — renders the markdown matrix and upserts it as a PR
               comment using a <!-- xcompile-matrix --> marker so
               re-runs update instead of spamming.

Build failures are emitted as ".failed" sentinel files so the run
stage can distinguish BUILD_FAIL from RUN_FAIL. Uses yarn (the repo's
package manager) and pins actions to the versions already used
elsewhere in the repo (checkout@v6, setup-node@v6, upload/download-
artifact@v4, github-script@v7).

Triggers on PRs touching lib/, prelude/, dictionary/, scripts/,
package.json, yarn.lock, or the workflow itself, and on
workflow_dispatch for manual runs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address deep-review findings on docs site branch

- docs: fix broken cross-page anchors in bytecode, recipes, build and
  sea-mode guides; replace raw /pkg/ prefixed link in index.md with
  VitePress-managed markdown link.
- ci(xcompile): switch cross-compile matrix to workflow_dispatch only
  (manual trigger is safer and avoids burning macOS/Windows minutes on
  every PR), wire the node-majors input via a setup job, add timeouts,
  upload per-cell build logs, short-circuit collate when no results,
  fix empty-array expansion under bash 3.2 / set -u on macOS runners,
  add spawnSync timeout, sanitise backticks in PR summary, and drop
  the dead PR-comment path.
- ci(docs): split concurrency so PR builds no longer queue behind
  production deploys, scope pages/id-token permissions to the deploy
  job, add timeout-minutes, and add an offline lychee link-check step
  to catch dead anchors before they ship.
- chore(skills): make run-matrix.sh fail fast (set -euo pipefail),
  write per-cell logs under $WORKDIR/logs so a failing cell is not
  overwritten, print log paths on stderr, add an unknown-target case,
  and document the debugging workflow in SKILL.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: drop root package-lock.json and standardize on yarn for pkg

package-lock.json was created by accident in #229 alongside the yarn
lockfile. pkg's canonical package manager is yarn (see yarn.lock); the
accidental npm lockfile drifts silently and confuses contributors.

- Remove package-lock.json and gitignore it at the repo root so it
  cannot reappear.
- Rewrite the dev-command references in CLAUDE.md, .claude/rules/*,
  .github/copilot-instructions.md and docs-site/development.md from
  "npm run <x>" to "yarn <x>", and spell out the split: pkg uses yarn,
  docs-site is the only place npm is used.

User-facing install instructions (README, guide/getting-started, guide/
migration, guide/api) are unchanged — end users still "npm install -g
@yao-pkg/pkg" and the CI recipe example still shows npm, since that
reflects how consumers package their own projects.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* ci: fix xcompile matrix false failures on macos and build-fail reporting

First run of the matrix on #234 surfaced three harness bugs (all cells
that failed under Standard mode were already matching the known Node 22
regression — those were expected). The CI-side bugs were:

1. macos-arm64 std jobs died on the first target with
   `EXTRA[@]: unbound variable`. Bash 3.2 ships on GitHub's macOS
   runners, and `set -u` + `"${EMPTY_ARRAY[@]}"` is a nounset error
   there. std-public/sea worked only because EXTRA was non-empty.
   Expand it with `${EXTRA[@]+"${EXTRA[@]}"}` instead, which degrades
   gracefully on old bash.

2. All macos-x64 build and run jobs were cancelled by the runner pool —
   GitHub has retired the Intel macOS runner (macos-13). Drop macos-x64
   as a build host entirely, and route the macos-x64 *target* runs to
   macos-14, which pre-installs Rosetta 2 and executes x86_64 Mach-O
   binaries transparently.

3. The run-stage reader iterated binaries and skipped .failed sidecars,
   so a pkg failure that left no output at all (vs. a 0-byte stub) dropped
   the combo out of the matrix as `:grey_question:` instead of showing
   `:x:&nbsp;build`. Also capture pkg's real exit code via
   `|| status=$?` so `set -e` doesn't eat it, always leave an empty
   binary on failure so the reader enumerates every combo, and pull the
   last 5 lines of the build log into the BUILD_FAIL detail so the
   collated summary surfaces the actual error without downloading
   artifacts.

Verified by parsing the workflow YAML: 4 build hosts (linux-x64,
linux-arm64, macos-arm64, win-x64), 5 run targets including
macos-x64@macos-14.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(ci): drop lychee link-checker from docs workflow

The step was a belt-and-braces defence against dead anchors, but lychee
fights VitePress's /pkg/ base-URL rewrite and extensionless URLs — it
reports ~2000 false positives for resources that are served fine on
the live site. Not worth the complexity; VitePress's own build-time
dead-link check already catches markdown link typos, and the five
broken anchors that motivated the step have been fixed and are
verified against the rendered HTML.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: proofread development.md

Address Copilot review feedback on grammar in docs-site/development.md:
fix "create release", "have build", "runned", "It install", and "Foreach"
phrases flagged by the reviewer.

* ci: skip heavy jobs on docs-only PRs

Add a `changes` job that uses dorny/paths-filter to detect whether
anything outside docs-site/ was touched. The build matrix and every
test.yml call still run so their required status check contexts are
reported, but their steps are gated on the flag — docs-only PRs get
green checks in seconds instead of burning the full OS/node matrix.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

When pkg fails to generate V8 bytecode for a file (typically during
cross-compile builds), it previously logged a warning, marked the
stripe as skipped, and shipped a zero-byte stripe. That left the
runtime VFS entry with neither STORE_BLOB nor STORE_CONTENT set, so
any require() of that file crashed with "Error: UNEXPECTED-20" (#87,
#181).

Producer now mutates the stripe to STORE_CONTENT and emits the
original source buffer instead, so the file is still readable at
runtime (as if packed with --no-bytecode for that single file). The
unused Stripe.skip field is removed.

If fabrication succeeds but the target V8 later rejects the cached
data at runtime (e.g. linuxstatic code cache vs a non-linuxstatic
target build), the prelude used to exit silently with code 4. Throw
a real Error naming the cause and the --public / --sea workarounds
so users can diagnose and decide how to proceed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- index.md: markdown link inside the fork-banner <div> was rendered as
  literal text because raw HTML blocks don't parse inline markdown
  without blank-line separation. Convert the block to use markdown
  content with surrounding blank lines so [migration guide] resolves.
- custom.css: zero the default <p> margin inside mermaid nodeLabel /
  edgeLabel / cluster-label / label. Mermaid wraps label text in <p>
  via its markdown parser; the browser's default <p> margin inflated
  the rendered label height beyond the foreignObject size mermaid had
  pre-measured, clipping the last line below the node rect.
- config.ts: set themeVariables.fontSize to 15px and add flowchart
  padding so mermaid's layout math matches the 15px rendered text.

)

* fix(sea): prevent sentinel duplication when pkg is in dependencies

When a user lists @yao-pkg/pkg in `dependencies` (instead of
`devDependencies`), the walker includes sea.js in the SEA archive.
The verbatim sentinel string ends up in the injected blob, causing
postject to find it twice and fail with "Multiple occurences of
sentinel found in the binary".

Split the sentinel via string concatenation so the literal never
appears in compiled output.

Closes https://github.com/julianpoemp/yao-pkg-nestjs-sea-example

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add /pkg-debug Claude Code skill for troubleshooting

Add a user-invocable skill that guides through build failures, runtime
crashes, missing assets, binary bloat, cross-compile regressions,
native addons, SEA issues, patches, and dictionaries.

Also add a section to the troubleshooting docs with install and usage
instructions and a cross-reference from the debug VFS page.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add --fallback-to-source flag for bytecode compilation failures

The automatic fallback to source introduced in 46a7f8e shipped plain
source whenever V8 bytecode fabrication failed, without the user
explicitly opting in. This moves that behaviour behind a new
--fallback-to-source flag.

Default (no flag): warn about the failure, mention --fallback-to-source
in the warning, and skip the file. The empty VFS key is cleaned up so
the prelude no longer hits "Error: UNEXPECTED-20" (#87, #181).

With --fallback-to-source: ship the file as plain source (previous
automatic behaviour).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: restore skip behaviour, improve UNEXPECTED-20 error

Default (no --fallback-to-source): warn, mark the stripe as skipped,
and emit a zero-byte buffer — identical to the pre-46a7f8e behaviour.
If the file is required at runtime the prelude now throws a descriptive
UNEXPECTED-20 error naming the file and suggesting --fallback-to-source,
--no-bytecode, or --sea.

test-50-extensions needs source at runtime during cross-compile so it
now passes --fallback-to-source explicitly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: revert test-50-extensions flag — --public already includes source

The walker emits both STORE_BLOB and STORE_CONTENT stripes for public
files (lib/walker.ts:987-1003), so when bytecode fabrication fails the
source is still available at runtime. No --fallback-to-source needed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>