docs: publish VitePress documentation on GitHub Pages

2026-10-12 02:19:24 +00:00 · 2026-10-07 16:58:04 +08:00
parent eab34a9d8c
commit c78fe6990b
17 changed files with 2817 additions and 21 deletions
@@ -0,0 +1,63 @@
+name: Documentation site
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".nvmrc"
+      - ".github/workflows/pages.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".nvmrc"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  HUSKY: "0"
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - run: npm ci
+      - run: npm run docs:build
+      - uses: actions/upload-pages-artifact@v4
+        if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    name: Publish documentation
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v5
+      - uses: actions/deploy-pages@v4
+        id: deployment
@@ -37,6 +37,7 @@ coverage/
 test-results.xml
 .turbo/
 .cache/
+docs/.vitepress/cache/

 # OS
 .DS_Store
@@ -26,6 +26,22 @@ worktrees. After a package, lockfile, or managed-skill version change, run

 Keep dependencies flowing inward through the existing domain, contracts, provider, application, server, and adapter layers. Parse unknown values at process and protocol boundaries, model expected failures with `Result`, and preserve the canonical tool inventory defined by `TOOL_CONTRACTS` unless a deliberate contract change updates every verifier, generated catalog artifact, and snapshot. Keep tool discovery complete and report capability- and session-scoped availability through `binary_session`.

+## Documentation website
+
+The VitePress site uses the Markdown files in `docs/` and deploys to
+<https://morluto.github.io/rea/>. Run `npm run docs:dev` for live editing,
+`npm run docs:build` to check the production build and links, and
+`npm run docs:preview` to preview that build at `/rea/`.
+
+Site navigation lives in `docs/.vitepress/config.ts`. Keep links to guides
+relative so they work on GitHub and the website; link to repository files
+outside `docs/` using their full GitHub URLs. Generated reference documents
+still use `npm run docs:generate`; `docs:build` only builds the website.
+
+The documentation workflow builds pull requests and deploys changes on `main`.
+The repository's **Settings → Pages → Build and deployment → Source** must be
+set to **GitHub Actions** before the first deployment.
+
 ## Development feedback and PR verification

 For an ordinary edit, run the relevant regression and cached static checks:
@@ -17,7 +17,7 @@

 <a href="https://trendshift.io/repositories/82054?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-82054" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/82054" alt="morluto%2Frea | Trendshift" width="250" height="55"/></a>

-[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [Tool catalog](#tool-catalog-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
+[Documentation](https://morluto.github.io/rea/) · [Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [Tool catalog](#tool-catalog-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)

 <code>npx rea-agents setup</code>

@@ -0,0 +1,83 @@
+import { defineConfig } from "vitepress";
+
+export default defineConfig({
+  title: "REA",
+  description:
+    "Reverse engineer binaries, applications, and runtime behavior with one CLI and MCP server.",
+  lang: "en-US",
+  base: "/rea/",
+  themeConfig: {
+    nav: [
+      { text: "Get started", link: "/installation" },
+      { text: "Reference", link: "/mcp-contracts" },
+      { text: "Roadmap", link: "/roadmap" },
+    ],
+    sidebar: [
+      {
+        text: "Getting started",
+        items: [
+          { text: "Installation and setup", link: "/installation" },
+          { text: "Agent prompts", link: "/mcp-prompts" },
+          { text: "Roadmap", link: "/roadmap" },
+        ],
+      },
+      {
+        text: "Investigation guides",
+        items: [
+          { text: "Native binaries", link: "/native-investigation" },
+          {
+            text: "JavaScript and Electron",
+            link: "/javascript-artifact-reconstruction",
+          },
+          {
+            text: "JavaScript workflows",
+            link: "/javascript-application-workflows",
+          },
+          { text: "Browser observation", link: "/browser-observation" },
+          { text: "Electron observation", link: "/electron-observation" },
+          { text: "Process capture", link: "/process-capture" },
+          { text: ".NET assemblies", link: "/managed-code-analysis" },
+          { text: "Android applications", link: "/android-analysis" },
+          { text: "Apple applications", link: "/apple-application-analysis" },
+          { text: "Firmware", link: "/firmware-analysis" },
+          {
+            text: "Reconstruction readiness",
+            link: "/reconstruction-readiness",
+          },
+        ],
+      },
+      {
+        text: "Provider guides",
+        collapsed: true,
+        items: [
+          { text: "IDA", link: "/ida-provider" },
+          { text: "Ghidra on Windows", link: "/windows-ghidra-p0" },
+          { text: "Ghidra DOS analysis", link: "/ghidra-dos" },
+          { text: "Ghidra NativeAOT", link: "/ghidra-nativeaot" },
+          { text: "Provider evaluation", link: "/provider-evaluation" },
+        ],
+      },
+      {
+        text: "Reference and development",
+        collapsed: true,
+        items: [
+          { text: "MCP contracts", link: "/mcp-contracts" },
+          { text: "Tool design", link: "/tool-design" },
+          { text: "Testing", link: "/testing" },
+          { text: "Architecture decisions", link: "/adr/README" },
+        ],
+      },
+    ],
+    search: { provider: "local" },
+    socialLinks: [
+      { icon: "github", link: "https://github.com/morluto/rea" },
+      { icon: "discord", link: "https://discord.gg/GkcryMnJDM" },
+    ],
+    editLink: {
+      pattern: "https://github.com/morluto/rea/edit/main/docs/:path",
+    },
+    footer: {
+      message: "Released under the MIT License.",
+    },
+  },
+});
@@ -29,12 +29,12 @@ same bytes could therefore disagree because of language, compiler, loader,
 analyzer, or provider-version differences while appearing target-compatible.

 The decision addressed the earlier representations of
-[`CompositeProvider`](../../src/application/binary/CompositeProvider.ts),
-[runtime composition](../../src/application/runtime.ts),
-[`BinarySession`](../../src/application/binary/BinarySession.ts),
-[`BinaryTarget`](../../src/domain/binaryTarget.ts),
-[analysis snapshot](../../src/domain/analysisSnapshot.ts), and
-[session lifecycle inputs](../../src/contracts/sessionLifecycleInputs.ts).
+[`CompositeProvider`](https://github.com/morluto/rea/blob/main/src/application/binary/CompositeProvider.ts),
+[runtime composition](https://github.com/morluto/rea/blob/main/src/application/runtime.ts),
+[`BinarySession`](https://github.com/morluto/rea/blob/main/src/application/binary/BinarySession.ts),
+[`BinaryTarget`](https://github.com/morluto/rea/blob/main/src/domain/binaryTarget.ts),
+[analysis snapshot](https://github.com/morluto/rea/blob/main/src/domain/analysisSnapshot.ts), and
+[session lifecycle inputs](https://github.com/morluto/rea/blob/main/src/contracts/sessionLifecycleInputs.ts).

 The next deep provider must not weaken the existing product invariants:

@@ -2,7 +2,7 @@

 REA wraps an existing headless JADX engine through `src/android/`. Its source is
 kept as an unmodified, commit-pinned Git submodule; see
-[upstream provenance](../third_party/README.md). CLI and MCP use the same
+[upstream provenance](https://github.com/morluto/rea/blob/main/third_party/README.md). CLI and MCP use the same
 application workflow and return artifact-bound Evidence inline.

 This family is present on repository main and in npm 4.1.0. Check the
@@ -38,7 +38,7 @@ git submodule update --init third_party/binwalk third_party/unblob
 ```

 Normal REA builds and npm packages do not include or build these sources or
-engine binaries. See [upstream provenance](../third_party/README.md).
+engine binaries. See [upstream provenance](https://github.com/morluto/rea/blob/main/third_party/README.md).

 ## CLI and MCP

@@ -0,0 +1,46 @@
+---
+layout: home
+
+hero:
+  name: REA
+  text: Reverse Engineer Anything
+  tagline: Understand binaries, applications, and runtime behavior with one CLI and MCP server.
+  actions:
+    - theme: brand
+      text: Get started
+      link: /installation
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/morluto/rea
+
+features:
+  - title: Investigate with your agent
+    details: Connect REA to your coding agent, describe the app or feature you want to understand, and follow the evidence.
+    link: /mcp-prompts
+  - title: Inspect across formats
+    details: Explore native binaries, JavaScript and Electron apps, .NET assemblies, Android packages, firmware, and websites.
+    link: /installation
+  - title: Keep the evidence
+    details: Analysis runs locally and returns observations, limitations, and unknowns through the CLI and MCP.
+    link: /mcp-contracts
+---
+
+## Start with one command
+
+```bash
+npx rea-agents setup
+```
+
+Choose your agent, review the planned changes, and approve setup. Native binary
+analysis can use an existing Hopper, Ghidra, or IDA installation; static
+JavaScript analysis needs no native analysis engine.
+
+For a first result from an extracted JavaScript application or ASAR:
+
+```bash
+npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --json
+```
+
+See [installation and setup](./installation.md) for requirements and configuration.
+
+![REA inspecting a native binary in Hopper](./assets/rea-hopper-analysis.png)
@@ -90,7 +90,7 @@ npx skills add morluto/rea --skill reverse-engineer-anything

 This installs agent instructions and bundled references, not REA MCP
 registration or analysis engines. Follow the skill's
-[conditional connection guide](../skills/reverse-engineer-anything/SKILL.md#connect-only-when-needed).
+[conditional connection guide](https://github.com/morluto/rea/blob/main/skills/reverse-engineer-anything/SKILL.md#connect-only-when-needed).
 Working tools can be used immediately. If tools are missing, inspect the current
 client's registration with `doctor --client codex --json` (substitute its client
 ID), then plan repairs with `setup --client codex --dry-run --json`. Show and
@@ -110,7 +110,7 @@ npx -y rea-agents@latest analyze-javascript-application /absolute/path/to/app --
 It returns the complete Evidence record directly and requires no native engine.
 Provider failures in doctor do not prevent unrelated target-free tools. To check
 readiness for one task instead of auditing every integration, see
-[Check readiness for the task at hand](../README.md#check-readiness-for-the-task-at-hand).
+[Check readiness for the task at hand](https://github.com/morluto/rea/blob/main/README.md#check-readiness-for-the-task-at-hand).

 ## Supported agents

@@ -25,7 +25,7 @@ part of the current tool set.

 This guide describes the implementation and verification of
 [ADR-0003](adr/0003-managed-code-evidence-and-provider-boundary.md). The canonical
-tool inventory is [`product-catalog.json`](product-catalog.json).
+tool inventory is [`product-catalog.json`](https://github.com/morluto/rea/blob/main/docs/product-catalog.json).

 ## Shipped scope

@@ -30,8 +30,8 @@ explicit limitation; architecture inventory locations remain available.
  connections and controller/class names. `verify:interface-builder` compiles
  a source-owned AppKit XIB with `ibtool`. Storyboards require an installed
  iOS platform; unsupported archive forms remain explicit.
- `inspect_native_dispatch_metadata` / `rea inspect-native-dispatch-metadata
-  <app-or-binary>` prefers a validated macOS Mach-O byte reader. It decodes
+- `inspect_native_dispatch_metadata` /
+  `rea inspect-native-dispatch-metadata <app-or-binary>` prefers a validated macOS Mach-O byte reader. It decodes
  64-bit little-endian Objective-C class/metaclass records, superclass pointers,
  absolute/relative method entries, ivar offsets/sizes/alignment and protocol
  declarations. It also decodes simple Swift conformances, static synchronous
@@ -148,7 +148,7 @@ private runtime files; crash-time transactional deletion is not claimed.

 ## Verification

-See [native controls](../native/windows/README.md) for the separate artifact
+See [native controls](https://github.com/morluto/rea/blob/main/native/windows/README.md) for the separate artifact
 build lane and native boundary checks. Development tarballs without the built
 artifact report native controls unavailable; publishing requires the verified
 artifact and manifest.
@@ -2,6 +2,9 @@
  "$schema": "./node_modules/knip/schema.json",
  "entry": ["src/main.ts", "src/cli.ts", "src/contracts/errorSchemas.ts"],
  "project": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.mjs"],
+  "vitepress": {
+    "entry": ["docs/.vitepress/config.ts"]
+  },
  "ignoreDependencies": ["electron", "esbuild", "webpack"],
  "ignoreExportsUsedInFile": true,
  "rules": {
@@ -159,6 +159,9 @@
    "config:print": "node scripts/print-mcp-config.mjs",
    "evidence:generate": "npm run build:cached && node scripts/generate-completion-ledger.mjs",
    "evidence:check": "npm run build:cached && node scripts/generate-completion-ledger.mjs --check",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
    "docs:generate": "node scripts/run-exclusive.mjs docs npm run docs:generate:unlocked",
    "docs:generate:unlocked": "npm run metadata:generate && npm run build:cached && node scripts/generate-mcp-tool-catalog.mjs && node scripts/generate-skill-metadata.mjs && node scripts/generate-product-catalog.mjs && node scripts/generate-completion-ledger.mjs && node scripts/generate-error-schema.mjs",
    "docs:check": "node scripts/run-exclusive.mjs docs turbo run docs:check:built",
@@ -219,6 +222,11 @@
    "ws": "8.21.0",
    "zod": "4.4.3"
  },
+  "overrides": {
+    "vitepress": {
+      "vite": "6.4.4"
+    }
+  },
  "devDependencies": {
    "@fast-check/vitest": "0.5.0",
    "@types/cross-spawn": "6.0.6",
@@ -236,6 +244,7 @@
    "oxlint": "1.87.0",
    "turbo": "2.11.7",
    "typescript": "7.0.2",
+    "vitepress": "1.6.4",
    "vitest": "5.0.3",
    "yaml": "2.9.0"
  }
@@ -21,6 +21,11 @@
    "types": ["node"],
    "verbatimModuleSyntax": true
  },
-  "include": ["src/**/*.ts", "tests/**/*.ts", "vitest.config.ts"],
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts",
+    "vitest.config.ts",
+    "docs/.vitepress/config.ts"
+  ],
  "exclude": ["dist", "node_modules"]
 }