docs: host documentation on GitHub Pages with VitePress

.claude/rules/project.md

@@ -22,3 +22,8 @@ This is `yao-pkg/pkg` — a maintained fork of the archived `vercel/pkg`.
 - `lib/bin.js` — CLI entry point
 - `prelude/bootstrap.js` — Injected into every packaged executable
 - `dictionary/*.js` — Special handling for specific npm packages
+
+## Architecture Reference
+
+- `docs/ARCHITECTURE.md` — **detailed** contributor/agent reference. Full build pipelines, binary layout, VFS provider, worker-thread bootstrap, patch tables. Read this when working on `lib/` or `prelude/`.
+- `docs-site/architecture.md` — short user-facing overview (linked from the published docs site). Don't duplicate internals here; link back to `docs/ARCHITECTURE.md`.

.github/copilot-instructions.md

@@ -236,7 +236,7 @@ Follow conventional commits format:
 
 1. **Read existing code**: Look at similar functionality before implementing new features
 2. **Add tests**: Every new feature or bug fix should include a test
-3. **Update documentation**: Update README.md and DEVELOPMENT.md as needed
+3. **Update documentation**: Update the docs site (`docs-site/`) as needed — guides live under `docs-site/guide/`, development notes in `docs-site/development.md`, architecture in `docs-site/architecture.md`
 4. **Check CI**: Ensure all CI checks pass before requesting review
 5. **Small PRs**: Keep pull requests focused and reasonably sized
 6. **Follow patterns**: Match existing code style and patterns
@@ -275,8 +275,8 @@ The project uses GitHub Actions workflows:
 
 - **Issues**: Report bugs and feature requests on GitHub
 - **Discussions**: Use GitHub Discussions for questions
-- **Documentation**: See README.md for user documentation
-- **Development Guide**: See DEVELOPMENT.md for development details
+- **Documentation**: See the docs site at https://yao-pkg.github.io/pkg/ (sources in `docs-site/`)
+- **Development Guide**: See `docs-site/development.md` (published at https://yao-pkg.github.io/pkg/development)
 - **Related Projects**:
   - [pkg-fetch](https://github.com/yao-pkg/pkg-fetch) - Pre-compiled Node.js binaries
   - [pkg-binaries](https://github.com/yao-pkg/pkg-binaries) - Binaries for unsupported architectures

.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: Deploy docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs-site/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs-site/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs-site
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: 'npm'
+          cache-dependency-path: docs-site/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci --no-audit --no-fund
+
+      - name: Build with VitePress
+        run: npm run docs:build
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs-site/.vitepress/dist
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

DEVELOPMENT.md

@@ -1,82 +1,10 @@
-# PKG Development
-
-This document aims to help you get started with `pkg` developemnt.
-
-## Release Process
-
-In order to create release just run the command:
-
-```bash
-npm run release
-```
-
-This command will start an interactive process that will guide you through the release process using [release-it](https://github.com/release-it/release-it)
-
-## Testing
-
-Before running tests ensure you have build the project by running:
-
-```bash
-npm run build
-```
-
-> [!NOTE]
-> Remember to run again `npm run build` after changing source code (everything inside `lib` folder).
-
-Than you can use the following command to run tests:
-
-```bash
-node test/test.js <target> [no-npm | only-npm | all] [<flavor>]
-```
-
-- `<target>` is the node target the test will use when creating executables, can be `nodeXX` (like `node20`) or `host` (uses host node version as target).
-- `[no-npm | only-npm | all]` to specify which tests to run. `no-npm` will run tests that don't require npm, `only-npm` will run against some specific npm modules, and `all` will run all tests.
-- `<flavor>` to use when you want to run only tests matching a specific pattern. Example: `node test/test.js all test-99-*`. You can also set this by using `FLAVOR` environment variable.
-
-Each test is located inside `test` directory into a dedicated folder named following the pattern `test-XX-*`. The `XX` is a number that represents the order the tests will run.
+<!-- canonical-source: docs-site/development.md -->
+<!-- Do NOT edit this stub. The canonical development guide lives at docs-site/development.md and is published at https://yao-pkg.github.io/pkg/development -->
 
-When running `node test/test.js all`, based on the options, each test will be run consecutively by running `main.js` file inside the test folder.
-
-### Example test
-
-Create a directory named `test-XX-<name>` and inside it create a `main.js` file with the following content:
-
-```javascript
-#!/usr/bin/env node
-
-'use strict';
-
-const assert = require('assert');
-const utils = require('../utils.js');
-
-assert(!module.parent);
-assert(__dirname === process.cwd());
-
-const input = './test-x-index';
-
-const newcomers = [
-  'test-x-index-linux',
-  'test-x-index-macos',
-  'test-x-index-win.exe',
-];
-
-const before = utils.filesBefore(newcomers);
-
-utils.pkg.sync([input], { stdio: 'inherit' });
-
-utils.filesAfter(before, newcomers);
-```
-
-Explaining the code above:
+# PKG Development
 
-- `assert(!module.parent);` ensures the script is being run directly.
-- `assert(__dirname === process.cwd());` ensures the script is being run from the correct directory.
-- `utils.filesBefore(newcomers);` get current files in the directory.
-- `utils.pkg.sync([input], { stdio: 'inherit' });` runs `pkg` passing input file as only argument.
-- `utils.filesAfter(before, newcomers);` checks if the output files were created correctly and cleans up the directory to the original state.
+Development documentation has moved to the official docs site:
 
-### Special tests
+**→ [yao-pkg.github.io/pkg/development](https://yao-pkg.github.io/pkg/development)**
 
-- `test-79-npm`: It's the only test runned when using `only-npm`. It install and tests all node modules listed inside that dir and verifies if they are working correctly.
-- `test-42-fetch-all`: Foreach known node version verifies there is a patch existing for it using pkg-fetch.
-- `test-46-multi-arch`: Tries to cross-compile a binary for all known architectures.
+For the canonical source of this page, see [`docs-site/development.md`](docs-site/development.md).