Project-specific Rust + Tauri rules: .claude/rules/rust.md. Release runbook: .claude/skills/release/SKILL.md (run /release).

Pake - Turn any webpage into a lightweight desktop app with one command.

• Purpose: Package any website into a ~5MB desktop app (20x smaller than Electron)
• Stack: Tauri v2 (Rust) + TypeScript CLI
• Platforms: macOS, Windows, Linux
• Mechanism: Uses system webview (WebKit on macOS/Linux, WebView2 on Windows)

Pake/
├── bin/                   # CLI source code (TypeScript)
│   └── cli.ts            # Main CLI entry (Commander.js)
├── src-tauri/             # Tauri Rust application
│   ├── src/              # Rust source code
│   ├── src/app/          # window creation, setup, menu, config, and invokes
│   ├── src/inject/       # injected JS/CSS behavior
│   ├── Cargo.toml        # Rust dependencies and version
│   ├── tauri.conf.json   # Tauri configuration and version
│   └── .cargo/           # Cargo configuration (gitignored)
├── dist/                 # Compiled CLI output
├── docs/                 # Documentation
│   ├── cli-usage.md      # CLI parameters
│   ├── advanced-usage.md # Customization guide
│   └── faq.md           # Troubleshooting
├── scripts/              # Utility scripts
├── tests/                # Unit, integration, and release-flow tests
├── .github/workflows/     # quality/test and release automation
├── default_app_list.json # Popular apps config for release builds
├── package.json          # Node.js dependencies and version
└── rollup.config.js      # CLI build configuration

Keep shared project facts in this file so Codex, Claude Code, and other agents use the same source of truth. CLAUDE.md is a symlink to this file, so edit AGENTS.md only. Local-only overrides (CLAUDE.local.md, AGENTS.override.md, .claude/settings.local.json) stay ignored.

• No Chinese comments in any source (Rust / TypeScript / any file). Comments and identifiers in English; follow the existing language of surrounding prose.

Prefer requests with:

• Goal: exact bug, feature, refactor, or review target
• Scope: files, directories, or subsystem boundaries to inspect first
• Repro: command, input, fixture, or failing test
• Expected: expected behavior
• Actual: current behavior, error text, or regression note
• Constraints: what must not change
• Verify: minimum command or test that proves the result

When task scope is incomplete, inspect in this order:

1. CLI entry and option parsing under bin/cli.ts, bin/options/, and bin/helpers/
2. Target TypeScript module under bin/
3. Tauri runtime or packaging files under src-tauri/src/ and src-tauri/tauri*.conf.json
4. Narrow tests under tests/unit/ or tests/integration/
5. Release workflow files under .github/workflows/ only for CI or release issues
6. Docs only if behavior, ownership, or expected usage is still unclear

Execution rules:

• Start with the smallest plausible file set
• Prefer targeted search (rg <symbol|string> <paths>) over repository-wide scans
• Ignore generated or output-heavy areas unless the task directly targets them, especially dist/, node_modules/, src-tauri/target/, .app/, src-tauri/icons/, and src-tauri/png/. Exception: dist/cli.js is the shipped CLI build artifact (see package.json files); when you change anything under bin/, rebuild it via pnpm run cli:build and commit the regenerated dist/cli.js alongside the source change
• Keep changes local to one subsystem when possible
• Run the narrowest relevant verification first, expand only if needed
• If key context is missing, make one reasonable assumption and proceed

• CLI options are user-facing and must stay synchronized across bin/helpers/cli-program.ts, bin/types.ts, bin/defaults.ts, bin/helpers/merge.ts, generated dist/cli.js, and docs/cli-usage*.md.
• Recent window/runtime options include --incognito, --new-window, --min-width, --min-height, --maximize, multi-window behavior, notification click handling, and Linux/Wayland WebKit compositing defaults.
• --incognito intentionally trades persistence for clean private sessions; be careful around login, cookies, local storage, and WeChat-style WebView detection.
• --new-window and --multi-window do not bypass every provider policy. Google OAuth and similar embedded-WebView restrictions may still require a normal browser or native client.
• Notification flows cross injected JS, Tauri invokes, capabilities, and native notification plugins. Verify the Rust capability and JS caller together.
• WebKit compositing behavior is platform-sensitive on Linux/Wayland. Do not change defaults without testing the affected platform path or documenting the risk.

• Universal builds via --multi-arch (Intel + Apple Silicon).
• Icons: .icns.
• Title bar can be customized via Tauri window options.

• Requires Visual Studio Build Tools to compile.
• Icons: .ico.
• MSI installer supported via Tauri bundler.

• Multiple package formats: .deb, .AppImage, .rpm.
• Runtime depends on libwebkit2gtk and its companion libraries.
• Icons: .png.
• WebKit compositing is platform-sensitive on Wayland; see Current Risk Areas before changing defaults.

• main - Only branch. All development and releases happen here directly.

Four files must be updated in sync for every release:

Tag format: V0.x.x (uppercase V). Current version: check package.json.

Pushing a V* tag triggers .github/workflows/release.yml:

1. release-apps - reads default_app_list.json for app list
2. create-release - creates the GitHub Release placeholder
3. build-cli - builds and uploads the dist/ CLI artifact
4. build-popular-apps - builds all apps in parallel across macOS/Windows/Linux
5. publish-docker - builds and pushes Docker image to GHCR

The workflow can also be triggered manually via workflow_dispatch with options to build popular apps or publish Docker independently.

Pushing the same V* tag also triggers .github/workflows/npm-publish.yml, which publishes pake-cli to npm through Trusted Publishing. Configure the npm package's Trusted Publisher as GitHub Actions, tw93/Pake, workflow file npm-publish.yml, with no environment. Local npm publish is only a fallback when CI or npm registry state blocks the trusted path.

Before treating an npm release as shipped, verify both gh workflow list --all | grep "Publish npm Package" and npm view pake-cli@X.Y.Z version. Do not reply to or close GitHub issues as released until the public registry returns the expected version.

.github/workflows/quality-and-test.yml runs auto-format on push, Rust quality checks, and CLI/build validation across Linux, Windows, and macOS.

Pake uses official npm and Rust sources by default. CN mirrors are explicit opt-in only:

• Set PAKE_USE_CN_MIRROR=1 only when the user or CI environment intentionally wants npmmirror/rsProxy.
• Do not reintroduce automatic China-domain mirror switching.
• If an install fails against a CN mirror, retry the same install command to separate network availability from a product regression.
• bin/utils/mirror.ts and bin/builders/BaseBuilder.ts own this behavior; keep docs and tests aligned when changing it.

# Install CLI
pnpm install -g pake-cli

# Basic usage
pake https://github.com --name GitHub

# Advanced usage
pake https://weekly.tw93.fun --name Weekly --width 1200 --height 800

See docs/faq.md for common issues and solutions.

If compilation errors occur (e.g. on macOS beta), create src-tauri/.cargo/config.toml:

[env]
MACOSX_DEPLOYMENT_TARGET = "15.0"
SDKROOT = "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"

This file is already in .gitignore.

Symptom: tests or release builds use stale CLI behavior after a bin/ edit. Fix with pnpm run cli:build and commit the regenerated dist/cli.js.

The first cargo build on a fresh clone takes 10+ minutes as Cargo compiles every Tauri dependency from source. Subsequent builds reuse the src-tauri/target/ cache. This is expected, not a bug.

• Main README: keep only common, frequently-used parameters to avoid clutter.
• CLI Documentation (docs/cli-usage.md and locale variants): include all CLI parameters with detailed usage examples.
• Rare or advanced parameters: should have full documentation in docs/cli-usage*.md but minimal or no mention in the main README. Examples: --title, --incognito, --system-tray-icon, --multi-window, --min-width, --min-height.
• Key configuration files:
  • pake.json - default app configuration.
  • src-tauri/tauri.conf.json - shared Tauri settings.
  • src-tauri/tauri.{macos,windows,linux}.conf.json - per-platform overrides.