diff --git a/.github/workflows/docs-site.yml b/.github/workflows/docs-site.yml
new file mode 100644
index 000000000..bd739f33c
--- /dev/null
+++ b/.github/workflows/docs-site.yml
@@ -0,0 +1,65 @@
+name: User documentation
+on:
+ pull_request:
+ paths: ['docs/site/**', 'docs/screenshots/**', '.github/workflows/docs-site.yml']
+ push:
+ branches: [main, 'docs/**']
+ paths: ['docs/site/**', 'docs/screenshots/**', '.github/workflows/docs-site.yml']
+ workflow_dispatch:
+permissions:
+ contents: read
+concurrency:
+ group: docs-${{ github.ref }}
+ cancel-in-progress: true
+jobs:
+ build:
+ permissions:
+ contents: read
+ pages: read
+ runs-on: ubuntu-24.04
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ persist-credentials: false
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.13'
+ - name: Install documentation build tools
+ run: pip install -r docs/site/requirements.txt playwright==1.57.0
+ - name: Check links, page structure and search coverage
+ run: python -m unittest discover -s docs/site -p test_site.py
+ - name: Resolve the configured Pages URL
+ if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && vars.PEBREL_DOCS_PAGES_ENABLED == 'true'
+ id: pages
+ uses: actions/configure-pages@v5
+ - name: Build portable static site
+ env:
+ DOCS_BASE_URL: ${{ vars.PEBREL_DOCS_BASE_URL || steps.pages.outputs.base_url }}
+ run: python docs/site/build.py --base-url "$DOCS_BASE_URL"
+ - name: Install browser
+ run: python -m playwright install --with-deps chromium
+ - name: Check desktop, mobile, keyboard and reduced-motion behavior
+ run: python docs/site/check_browser.py
+ - uses: actions/upload-artifact@v4
+ if: always()
+ with:
+ name: docs-browser-results
+ path: docs-browser-results/
+ if-no-files-found: ignore
+ - uses: actions/upload-pages-artifact@v4
+ with:
+ path: docs/site/dist
+ deploy:
+ if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && vars.PEBREL_DOCS_PAGES_ENABLED == 'true'
+ needs: build
+ runs-on: ubuntu-24.04
+ permissions:
+ pages: write
+ id-token: write
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ steps:
+ - uses: actions/deploy-pages@v4
+ id: deployment
diff --git a/.gitignore b/.gitignore
index 4077ca9c0..e9eae77df 100644
--- a/.gitignore
+++ b/.gitignore
@@ -152,3 +152,79 @@ dist-pack-*/
NebulaTerminal-*/
*-preview-package/
+
+# Published static user guide: exact reviewed source allowlist.
+!/docs/site/
+!/docs/site/assets/
+!/docs/site/content/
+!/docs/site/README.md
+!/docs/site/assets/site.css
+!/docs/site/assets/site.js
+!/docs/site/build.py
+!/docs/site/palettes.py
+!/docs/site/check_browser.py
+!/docs/site/content/index.md
+!/docs/site/content/installation.md
+!/docs/site/content/quickstart.md
+!/docs/site/requirements.txt
+!/docs/site/site.json
+!/docs/site/template.html
+!/docs/site/test_site.py
+
+!/docs/site/content/workspace.md
+!/docs/site/content/shells.md
+!/docs/site/content/clipboard.md
+!/docs/site/content/completions.md
+!/docs/site/content/palette.md
+!/docs/site/content/commands.md
+!/docs/site/content/navigation.md
+!/docs/site/content/keyboard.md
+!/docs/site/content/broadcast.md
+!/docs/site/content/sessions.md
+!/docs/site/content/layouts.md
+!/docs/site/content/quick-terminal.md
+!/docs/site/content/ssh.md
+!/docs/site/content/ssh-library.md
+!/docs/site/content/ssh-auth.md
+!/docs/site/content/ssh-routing.md
+!/docs/site/content/sftp.md
+!/docs/site/content/files.md
+!/docs/site/content/vcs.md
+!/docs/site/content/documents.md
+!/docs/site/content/images.md
+!/docs/site/content/remote-edit.md
+!/docs/site/content/ai-start.md
+!/docs/site/content/hooks.md
+!/docs/site/content/ai-history.md
+!/docs/site/content/agents.md
+!/docs/site/content/send-to-chat.md
+!/docs/site/content/appearance.md
+!/docs/site/content/themes.md
+!/docs/site/content/backgrounds.md
+!/docs/site/content/fonts.md
+!/docs/site/content/notifications.md
+!/docs/site/content/interaction.md
+!/docs/site/content/configuration.md
+!/docs/site/content/network.md
+!/docs/site/content/runtime.md
+!/docs/site/content/settings.md
+!/docs/site/content/updates.md
+!/docs/site/content/migration.md
+!/docs/site/content/privacy.md
+!/docs/site/content/troubleshooting.md
+!/docs/site/screenshots.json
+!/docs/site/third-party-notices.txt
+!/docs/site/content/terminal-basics.md
+!/docs/site/content/wsl.md
+!/docs/site/content/ssh-config.md
+!/docs/site/content/git-conflicts.md
+!/docs/site/content/svn.md
+!/docs/site/content/markdown-editing.md
+!/docs/site/content/config-examples.md
+!/docs/site/content/agent-worktrees.md
+
+!/docs/site/content/readme.md
+!/docs/site/content/contributing.md
+
+!/docs/site/content/backups.md
+!/docs/site/content/mobile.md
diff --git a/architecture/notes/docs/site/2026-09-24-static-user-guide.md b/architecture/notes/docs/site/2026-09-24-static-user-guide.md
new file mode 100644
index 000000000..d57f78e01
--- /dev/null
+++ b/architecture/notes/docs/site/2026-09-24-static-user-guide.md
@@ -0,0 +1,80 @@
+# Static user guide build boundary
+
+## Status
+
+Proposed with the documentation-site pull request.
+
+## Context
+
+The desktop application needs a navigable user manual that can be reviewed in a
+fork, published through repository Pages, and read without a running service.
+Desktop builds must not acquire a web-toolchain dependency.
+
+## Evidence
+
+- [Builder](../../../../docs/site/build.py) converts reviewed Markdown into HTML.
+- [Workflow](../../../../.github/workflows/docs-site.yml) builds independently of Cargo.
+- [Checks](../../../../docs/site/test_site.py) cover references and search coverage.
+- [Operations](../../../../docs/site/README.md) describes Pages activation.
+
+## Decision
+
+Keep the site under `docs/site`, with build-only pinned Markdown and highlighting
+libraries. Emit independent HTML pages, relative asset links and a local search
+index. Use system fonts and repository-owned application imagery. Production
+Pages deployment requires explicit repository opt-in and only runs from `main`.
+
+## Rejected alternatives
+
+A client-only application would make basic reading depend on JavaScript. A
+hosted search service would add a credential and network dependency. A second
+large frontend framework is unnecessary for Markdown, navigation and search.
+
+## Consequences
+
+Markdown and navigation remain separately reviewable. Rich HTML is trusted
+repository content, not an input format for arbitrary visitors. The build has no
+server-side user input and does not affect the desktop runtime. Captured app
+images require a separate native environment; browser screenshots verify only
+the guide's own interface.
+
+## Validation
+
+Local structural tests and the independent browser workflow exercise generated
+links, search, copying, theme persistence, mobile navigation and no-script reading.
+CI results, rather than the presence of workflow files, establish run status.
+
+## Supersedes
+
+None.
+
+## Revisit when
+
+Multiple maintained languages or versioned manuals make the current navigation
+manifest insufficient, or the small local search index no longer meets users'
+needs. Re-evaluate on measured behavior rather than adding services in advance.
+
+## Colour themes (2026-10-07)
+
+The guide takes its colours from the application's built-in themes instead of a
+site-specific palette, so the documentation reads as part of the product and
+readers can choose the theme they already use. `docs/site/palettes.py` parses the
+catalog from `nebula_settings/src/themes.rs` at build time; the build fails when
+that source changes shape. A hand-copied colour table was rejected because it would
+drift from the application. A fixed light/dark pair was rejected because the
+application ships sixteen themes and a toggle cannot express them. Where a theme's
+accent or muted colour is too faint for text, the site darkens or lightens it toward
+the theme foreground until it reaches 4.5:1; the application's own colours are
+unchanged. The choice is stored in browser storage only.
+
+## Release baseline (2026-10-07)
+
+The base pages were re-audited against the `v2.1.1` tag and the manifest now records
+that version and commit for every page; the earlier page-level `main` overrides were
+removed. The tag, not `main`, is the baseline because the guide describes what readers
+can install: `main` carries features that are not in any release. Pages whose behaviour
+changed between 1.9.1 and 2.1.1 were updated from the code at the tag (platform
+integrations on macOS and Linux, Windows ARM64 installer, release asset names, update
+channels, settings navigation) and from the release notes for 2.0.0, 2.1.0 and 2.1.1.
+Differences that are only translation refactors were not treated as behaviour changes.
+
diff --git a/docs/screenshots/pebrel-1.9.1-macos-arm64-ci.png b/docs/screenshots/pebrel-1.9.1-macos-arm64-ci.png
new file mode 100644
index 000000000..df72fddb5
Binary files /dev/null and b/docs/screenshots/pebrel-1.9.1-macos-arm64-ci.png differ
diff --git a/docs/site/README.md b/docs/site/README.md
new file mode 100644
index 000000000..99d29031e
--- /dev/null
+++ b/docs/site/README.md
@@ -0,0 +1,114 @@
+# Pebrel user documentation
+
+A Chinese user guide built from Markdown into standalone HTML, with local search,
+keyboard navigation, light/dark themes, copy controls and image zoom. The build
+uses existing repository screenshots; it does not redistribute font files or
+change the desktop application's dependencies.
+
+## Build and check
+
+```sh
+python -m pip install -r docs/site/requirements.txt
+python docs/site/build.py
+python -m unittest discover -s docs/site -p test_site.py
+python -m http.server --directory docs/site/dist 8000
+```
+
+For the browser smoke check, install `playwright==1.57.0`, run
+`python -m playwright install chromium`, then `python docs/site/check_browser.py`.
+The check serves the site under `/pebrel/`, exercising project-site path handling.
+`CHROMIUM_PATH` optionally selects an existing Chromium executable.
+
+The manifest currently contains 56 user-facing guides, organized by tasks rather
+than implementation modules. Source links are pinned to the documented commit.
+
+The documented baseline is the `v2.1.1` release (commit `d574856`). Pages were checked
+against that tag, not against later `main`: UI labels, platform availability and file
+names such as release assets follow what 2.1.1 shipped. When a later release changes a
+page, update that page, its evidence and `site.json` together, or record a page-level
+`version` and `source_commit` as described below.
+
+The generated `dist/` is disposable and ignored. Publish that directory's contents,
+not this source directory. Open `index.html` directly for offline reading; browser
+clipboard policies may require HTTP(S), in which case select and copy the text.
+Search loads a local JavaScript index rather than requiring a backend or CDN.
+
+## Colour themes
+
+The site uses the desktop application's own palettes. `palettes.py` parses the 16
+built-in themes from `pebrel_settings/src/themes.rs` (and their names from
+`pebrel_app/src/display/ui/theme.rs`) at build time and writes `assets/palettes.css`
+plus the syntax colours in `assets/highlight.css`. Nothing is copied by hand, so a
+theme added or retuned in the application reaches the site on the next build, and the
+build fails if the source no longer has the expected shape.
+
+Readers pick a theme from the palette button in the header. **Follow system** mirrors the
+application's default pair, Nord Light and Nord. The choice is stored in the browser
+only. Accent, muted and syntax colours are nudged toward the theme's foreground when
+they would fall below a 4.5:1 contrast ratio on the page or code surface; the tests
+check this for every theme.
+
+## GitHub Pages
+
+The `User documentation` workflow builds and checks documentation on matching
+pull requests and documentation-branch pushes. A PR never deploys the production
+site. It publishes a Pages artifact and browser screenshots for review.
+
+A repository administrator must first choose **Settings → Pages → Source → GitHub
+Actions**. Set the repository variable `PEBREL_DOCS_PAGES_ENABLED` to `true` to opt
+in to deployment from `main`. On production builds, the workflow reads the
+configured Pages URL for canonical links, the sitemap and the 404 home link.
+Optionally override `PEBREL_DOCS_BASE_URL` with the public
+site root, including the repository prefix and trailing slash, such as
+`https://kuddev.github.io/pebrel/`, for canonical links and a sitemap. For a custom
+domain, supply that domain's root instead. The workflow does not change repository
+settings, DNS or domain ownership.
+
+After the change is merged, the workflow deploys on a matching `main` push; it can
+also be run manually from `main`. Fork builds do not deploy unless their owner
+separately enables the same opt-in variable and Pages setting.
+
+## Maintain content
+
+`site.json` owns navigation, the documented version, the source commit and each
+page's evidence paths. A page may override `version` and `source_commit` when
+a newer feature has been audited; its displayed version and evidence links then
+use that snapshot without relabeling older guides. State the boundary in the page
+body too: an audited `main` feature is not a claim of release availability.
+Pages live in `content/`. Use Markdown links such as
+`[Installation](installation.md)`: the builder resolves them for nested HTML paths.
+Use `@ROOT@` for local image paths in rich HTML. Raw HTML is allowed for trusted,
+reviewed repository content only; this is not an untrusted Markdown service.
+
+The build copies images named in `site.json` from `docs/screenshots/` and the
+application icon from `extra/logo/nebula.png`. Caption old repository captures as
+such. Newly captured application images must state their platform and version;
+do not label a mockup or a documentation-page screenshot as an application capture.
+
+After verifying a feature change, update the relevant page and its evidence.
+Lead with the task, identify the actual menu or shortcut, explain the result,
+and place cautions beside the affected operation. Use visible entry points from
+the page's documented snapshot: retained implementation code is not by itself
+evidence of an available UI feature. Keep
+implementation rationale out of the user guide. Add each new public source
+file to the exact `.gitignore` allowlist rather than opening the whole `docs/`
+subtree. The build checks that evidence paths exist; existence alone is not proof
+that every sentence has been audited.
+
+## Application screenshot provenance
+
+`screenshots.json` records the original source and digest of every bundled image.
+Most figures reuse the existing repository images and do not imply a particular
+capture version. The macOS installation figure is the unchanged native application
+capture from the official 1.9.1 release run `35961098033`, artifact
+`stable-evidence-macos-aarch64` (`10792632932`). Its launch report identifies source
+commit `e9e83d83a63ca9cc885857439f7f6826c1cbabaf`, whose tree matches the documented
+main snapshot, and reports macOS 26.6.2 / aarch64. This was an existing upstream CI
+run, not a new run dispatched by the documentation task. Its test message is
+captioned as such; it is not presented as default application content.
+
+For future updates, inspect matching-version release evidence before replacing a
+figure. Review the actual image, source commit and launch report, remove unrelated
+personal content when necessary, and record any modification. Rebuild after
+updating both the image manifest and provenance. Browser captures prove only the
+documentation website's layout, not native application behavior.
diff --git a/docs/site/assets/site.css b/docs/site/assets/site.css
new file mode 100644
index 000000000..4429bc56a
--- /dev/null
+++ b/docs/site/assets/site.css
@@ -0,0 +1,1709 @@
+:root {
+ --header:60px;
+ --sidebar:248px;
+ --radius:8px;
+ --font:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;
+}
+
+[hidden] {
+ display:none!important;
+}
+
+* {
+ box-sizing:border-box;
+}
+
+html {
+ scroll-behavior:smooth;
+ scroll-padding-top:100px;
+}
+
+body {
+ margin:0;
+ background:var(--bg);
+ color:var(--text);
+ font-family:var(--font);
+ font-size:15px;
+ line-height:1.7;
+ -webkit-font-smoothing:antialiased;
+}
+
+a {
+ color:inherit;
+ text-decoration:none;
+}
+
+button,input {
+ font:inherit;
+}
+
+button {
+ cursor:pointer;
+}
+
+button,a,input,summary {
+ -webkit-tap-highlight-color:transparent;
+}
+
+button {
+ color:inherit;
+}
+
+button:disabled {
+ cursor:wait;
+ opacity:.65;
+}
+
+a,button {
+ transition:background .18s,color .18s,border-color .18s,transform .18s;
+}
+
+/* A palette change repaints everything at once; per-element fades would leave
+ rounded cards and pills in the old colours for a moment. */
+html[data-switching] *,
+html[data-switching] *::before,
+html[data-switching] *::after {
+ transition:none!important;
+}
+
+button:active {
+ transform:translateY(1px);
+}
+
+:focus-visible {
+ outline:3px solid var(--accent);
+ outline-offset:4px;
+}
+
+button svg,.search-heading svg {
+ width:19px;
+ height:19px;
+ fill:none;
+ stroke:currentColor;
+ stroke-width:1.6;
+ stroke-linecap:round;
+ stroke-linejoin:round;
+ flex:none;
+}
+
+kbd {
+ font-family:var(--font);
+ font-size:11px;
+ border:1px solid var(--line);
+ border-radius:5px;
+ padding:1px 5px;
+ white-space:nowrap;
+ background:var(--bg);
+ box-shadow:0 1px 0 var(--line);
+}
+
+.sr-only {
+ position:absolute;
+ width:1px;
+ height:1px;
+ overflow:hidden;
+ clip:rect(0,0,0,0);
+ white-space:nowrap;
+}
+
+.skip {
+ position:fixed;
+ top:-60px;
+ left:20px;
+ z-index:100;
+ padding:10px 20px;
+ border-radius:8px;
+ background:var(--text);
+ color:var(--bg);
+}
+
+.skip:focus {
+ top:10px;
+}
+
+.header {
+ height:var(--header);
+ position:fixed;
+ inset:0 0 auto;
+ z-index:40;
+ display:flex;
+ align-items:center;
+ gap:32px;
+ padding:0 24px;
+ border-bottom:1px solid var(--line);
+ background:var(--panel);
+}
+
+.brand {
+ display:flex;
+ align-items:center;
+ gap:10px;
+ flex:none;
+}
+
+.brand>span:first-of-type {
+ font-size:22px;
+ font-weight:620;
+ letter-spacing:-.8px;
+}
+
+.brand-docs {
+ color:var(--muted);
+ font-size:14px;
+}
+
+.brand img {
+ border-radius:7px;
+}
+
+.header-links {
+ display:flex;
+ align-items:center;
+ gap:26px;
+ font-size:13px;
+ height:100%;
+ color:var(--muted);
+}
+
+.header-links a {
+ height:100%;
+ display:flex;
+ align-items:center;
+ gap:5px;
+ position:relative;
+}
+
+.header-links a:hover,.header-links .selected {
+ color:var(--text);
+}
+
+.header-links .selected:after {
+ content:"";
+ position:absolute;
+ height:2px;
+ background:var(--text);
+ left:0;
+ right:0;
+ bottom:0;
+}
+
+.header-actions {
+ display:flex;
+ align-items:center;
+ gap:10px;
+ margin-left:auto;
+}
+
+.search-trigger {
+ height:38px;
+ width:230px;
+ display:flex;
+ align-items:center;
+ gap:10px;
+ border:1px solid var(--line);
+ border-radius:8px;
+ background:var(--soft);
+ color:var(--muted);
+ padding:0 11px;
+ font-size:12px;
+ text-align:left;
+}
+
+.search-trigger kbd {
+ margin-left:auto;
+}
+
+.search-trigger:hover {
+ border-color:var(--muted);
+}
+
+.icon-button {
+ border:0;
+ background:transparent;
+ display:grid;
+ place-items:center;
+ width:40px;
+ height:40px;
+ border-radius:8px;
+ color:var(--muted);
+}
+
+.icon-button:hover {
+ background:var(--soft);
+ color:var(--text);
+}
+
+.menu-toggle {
+ display:none;
+}
+
+.sidebar {
+ position:fixed;
+ top:var(--header);
+ bottom:0;
+ left:0;
+ width:var(--sidebar);
+ padding:29px 18px 20px 25px;
+ border-right:1px solid var(--line);
+ overflow:auto;
+ background:var(--panel);
+ scrollbar-width:thin;
+ scrollbar-color:var(--line) transparent;
+ z-index:30;
+ display:flex;
+ flex-direction:column;
+}
+
+.sidebar-home {
+ display:flex;
+ justify-content:space-between;
+ align-items:center;
+ padding:0 10px 21px;
+ font-size:13px;
+ font-weight:600;
+}
+
+.version {
+ font:11px ui-monospace,SFMono-Regular,monospace;
+ border-radius:20px;
+ padding:2px 7px;
+ background:var(--soft);
+ color:var(--muted);
+ font-weight:400;
+}
+
+.nav-group {
+ margin:3px 0 23px;
+}
+
+.nav-heading {
+ font-size:11px;
+ color:var(--muted);
+ font-weight:600;
+ padding:4px 11px 8px;
+}
+
+.nav-link {
+ display:block;
+ padding:7px 12px;
+ border-radius:7px;
+ font-size:13px;
+ color:var(--muted);
+ margin:2px 0;
+ line-height:1.7;
+}
+
+.nav-link:hover {
+ background:var(--soft);
+ color:var(--text);
+}
+
+.nav-link.active {
+ background:var(--tint);
+ color:var(--accent);
+ font-weight:550;
+}
+
+.sidebar-bottom {
+ border-top:1px solid var(--line);
+ margin:22px 10px 0;
+ padding-top:17px;
+ font-size:10px;
+ color:var(--muted);
+}
+
+.sidebar-bottom>a {
+ display:block;
+ margin:8px 0;
+}
+
+.status-dot {
+ display:inline-block;
+ width:5px;
+ height:5px;
+ background:var(--accent);
+ border-radius:50%;
+ margin-right:7px;
+}
+
+.workspace {
+ margin-left:var(--sidebar);
+ padding:calc(var(--header) + 38px) 36px 0 52px;
+ display:grid;
+ grid-template-columns:minmax(0,800px) 168px;
+ gap:56px;
+ justify-content:center;
+}
+
+main {
+ min-width:0;
+ outline:none;
+}
+
+main:focus {
+ outline:none;
+}
+
+.breadcrumb {
+ display:flex;
+ align-items:center;
+ justify-content:space-between;
+ gap:18px;
+ font-size:11px;
+ color:var(--muted);
+ margin:0 0 26px;
+ min-height:34px;
+}
+
+.breadcrumb-path {
+ display:flex;
+ align-items:center;
+ gap:12px;
+ min-width:0;
+}
+
+.breadcrumb a:hover {
+ color:var(--accent);
+}
+
+.page-heading {
+ margin-bottom:34px;
+}
+
+.page-heading h1 {
+ font-size:32px;
+ letter-spacing:-.8px;
+ line-height:1.3;
+ margin:0 0 12px;
+ font-weight:600;
+}
+
+.page-description {
+ font-size:15px;
+ color:var(--muted);
+ line-height:1.8;
+ max-width:650px;
+ margin:0;
+}
+
+.page-tools {
+ display:flex;
+ gap:12px;
+ align-items:center;
+ justify-content:flex-end;
+ margin:0 0 0 auto;
+ font-size:11px;
+ color:var(--muted);
+ white-space:nowrap;
+}
+
+.small-button {
+ display:inline-flex;
+ gap:7px;
+ align-items:center;
+ background:var(--bg);
+ border:1px solid var(--line);
+ padding:5px 11px;
+ border-radius:7px;
+ min-height:32px;
+ font-size:11px;
+}
+
+.small-button:hover {
+ background:var(--soft);
+ border-color:var(--muted);
+}
+
+.toc {
+ position:sticky;
+ top:calc(var(--header) + 35px);
+ align-self:start;
+ font-size:11px;
+ max-height:calc(100vh - 140px);
+ overflow:auto;
+ padding-top:5px;
+ scrollbar-width:thin;
+}
+
+.toc>span {
+ display:block;
+ font-weight:600;
+ margin:0 0 14px;
+}
+
+.toc nav {
+ border-left:1px solid var(--line);
+}
+
+.toc a {
+ display:block;
+ color:var(--muted);
+ padding:5px 0 5px 14px;
+ line-height:1.6;
+ margin-left:-1px;
+ border-left:1px solid transparent;
+}
+
+.toc a.level-3 {
+ padding-left:24px;
+ font-size:10px;
+}
+
+.toc a:hover {
+ color:var(--text);
+}
+
+.toc a.active {
+ border-color:var(--accent);
+ color:var(--accent);
+}
+
+.back-top {
+ background:none;
+ border:0;
+ color:var(--muted);
+ font-size:11px;
+ padding:18px 0;
+}
+
+.back-top:hover {
+ color:var(--text);
+}
+
+.hero {
+ margin:0 0 28px;
+}
+
+.hero h1 {
+ font-size:36px;
+ font-weight:600;
+ line-height:1.35;
+ letter-spacing:-.9px;
+ margin:0 0 22px;
+ max-width:540px;
+}
+
+.hero h1 span {
+ color:var(--accent);
+}
+
+.hero-actions {
+ display:flex;
+ align-items:center;
+ gap:17px;
+}
+
+.button-primary {
+ background:var(--accent);
+ color:var(--bg)!important;
+ display:inline-flex;
+ align-items:center;
+ gap:28px;
+ font-size:12px;
+ font-weight:500;
+ padding:10px 17px;
+ border:1px solid var(--accent);
+ border-radius:8px;
+ min-height:40px;
+ text-decoration:none!important;
+}
+
+.button-primary:hover {
+ opacity:.88;
+}
+
+.text-link {
+ font-size:12px;
+ color:var(--text)!important;
+ border:0!important;
+}
+
+.text-link:hover {
+ text-decoration:underline;
+}
+
+.platform-strip {
+ display:flex;
+ align-items:center;
+ gap:20px;
+ font-size:11px;
+ color:var(--muted);
+ margin:0 0 30px;
+}
+
+.platform-strip>span:first-child {
+ color:var(--text);
+ font-weight:500;
+}
+
+.platform-strip>a {
+ color:var(--muted);
+ text-decoration:none;
+ border-radius:6px;
+ padding:4px 2px;
+}
+
+.platform-strip>a:hover,
+.platform-strip>a:focus-visible {
+ color:var(--text);
+ text-decoration:underline;
+ text-underline-offset:4px;
+}
+
+.platform-strip small {
+ font-size:9px;
+ border:1px solid var(--line);
+ border-radius:4px;
+ padding:1px 4px;
+ margin-left:4px;
+}
+
+.readme-intro {
+ border-radius:8px;
+ padding:20px;
+ background:var(--soft);
+ margin:18px 0 24px;
+}
+
+.readme-intro strong {
+ display:block;
+ font-size:20px;
+ line-height:1.5;
+ margin-bottom:8px;
+}
+
+.readme-intro p {
+ margin:0!important;
+ color:var(--muted);
+}
+
+.readme-visual-grid {
+ display:grid;
+ grid-template-columns:repeat(2,minmax(0,1fr));
+ gap:12px;
+ margin:18px 0 28px;
+}
+
+.readme-visual-card {
+ border:1px solid var(--line);
+ border-radius:8px;
+ padding:19px;
+ background:var(--panel);
+}
+
+.readme-visual-card small {
+ display:block;
+ color:var(--accent);
+ font-size:10px;
+ font-weight:650;
+ letter-spacing:.06em;
+ margin-bottom:7px;
+}
+
+.readme-visual-card strong {
+ display:block;
+ font-size:15px;
+ margin-bottom:7px;
+}
+
+.readme-visual-card p {
+ color:var(--muted);
+ font-size:13px;
+ margin:0!important;
+}
+
+.readme-badges {
+ display:flex;
+ flex-wrap:wrap;
+ gap:8px;
+ margin:14px 0 24px;
+}
+
+.readme-badges span {
+ border:1px solid var(--line);
+ background:var(--soft);
+ border-radius:999px;
+ padding:6px 10px;
+ font-size:11px;
+ color:var(--muted);
+}
+
+.contribution-flow {
+ display:grid;
+ grid-template-columns:repeat(4,minmax(0,1fr));
+ gap:10px;
+ margin:18px 0 28px;
+ counter-reset:contrib-step;
+}
+
+.contribution-flow>div {
+ border:1px solid var(--line);
+ border-radius:8px;
+ padding:16px;
+ min-width:0;
+}
+
+.contribution-flow>div:before {
+ counter-increment:contrib-step;
+ content:counter(contrib-step,decimal-leading-zero);
+ display:block;
+ color:var(--accent);
+ font:600 10px ui-monospace,SFMono-Regular,monospace;
+ margin-bottom:8px;
+}
+
+.contribution-flow strong {
+ display:block;
+ font-size:13px;
+ margin-bottom:5px;
+}
+
+.contribution-flow span {
+ display:block;
+ color:var(--muted);
+ font-size:11px;
+ line-height:1.65;
+}
+
+.feature-grid {
+ display:grid;
+ grid-template-columns:repeat(2,minmax(0,1fr));
+ gap:12px;
+ margin:20px 0 32px;
+}
+
+.feature-card {
+ border:1px solid var(--line);
+ border-radius:8px;
+ padding:18px 20px!important;
+ display:block;
+ text-decoration:none!important;
+ background:var(--bg);
+}
+
+.feature-card:hover {
+ border-color:var(--accent);
+}
+
+.feature-card h3 {
+ margin:0 0 6px!important;
+ font-size:15px!important;
+}
+
+.feature-card p {
+ font-size:12px!important;
+ color:var(--muted);
+ line-height:1.75;
+ margin:0!important;
+ max-width:240px;
+}
+
+.prose {
+ font-size:16px;
+ line-height:1.9;
+}
+
+.prose h2 {
+ font-size:24px;
+ font-weight:560;
+ letter-spacing:-.5px;
+ margin:44px 0 16px;
+ line-height:1.5;
+ padding-top:3px;
+ scroll-margin-top:95px;
+}
+
+.prose h3 {
+ font-size:17px;
+ font-weight:570;
+ margin:28px 0 12px;
+ scroll-margin-top:95px;
+}
+
+.prose h4 {
+ font-size:15px;
+ font-weight:600;
+ margin:22px 0 10px;
+}
+
+.prose p {
+ margin:14px 0;
+}
+
+.prose a:not(.feature-card):not(.button-primary):not(.text-link):not(.heading-anchor) {
+ color:var(--accent);
+ text-decoration:underline;
+ text-decoration-color:color-mix(in srgb,var(--accent) 40%,transparent);
+ text-underline-offset:4px;
+}
+
+.prose a:hover {
+ text-decoration-color:currentColor;
+}
+
+.prose strong {
+ font-weight:620;
+}
+
+.prose ul,.prose ol {
+ padding-left:24px;
+ margin:15px 0;
+}
+
+.prose li {
+ padding-left:4px;
+ margin:8px 0;
+}
+
+.prose li::marker {
+ color:var(--muted);
+}
+
+.prose ol>li::marker {
+ color:var(--accent);
+ font-weight:600;
+}
+
+.prose hr {
+ border:0;
+ border-top:1px solid var(--line);
+ margin:36px 0;
+}
+
+.prose :not(pre)>code {
+ font:13px/1.7 ui-monospace,SFMono-Regular,Consolas,monospace;
+ color:var(--text);
+ background:var(--code);
+ padding:3px 6px;
+ border:1px solid var(--line);
+ border-radius:5px;
+ overflow-wrap:anywhere;
+}
+
+.prose pre {
+ margin:0;
+ padding:21px 22px;
+ overflow:auto;
+ line-height:1.75;
+ font-size:13px;
+ tab-size:2;
+ scrollbar-width:thin;
+}
+
+.prose pre code {
+ font-family:ui-monospace,SFMono-Regular,Consolas,monospace;
+}
+
+.code-block {
+ border:1px solid var(--line);
+ border-radius:8px;
+ background:var(--code);
+ margin:19px 0;
+ overflow:hidden;
+}
+
+.code-toolbar {
+ height:37px;
+ border-bottom:1px solid var(--line);
+ display:flex;
+ align-items:center;
+ justify-content:space-between;
+ padding:0 10px 0 18px;
+ font:10px var(--font);
+ color:var(--muted);
+ letter-spacing:.02em;
+}
+
+.copy-code {
+ background:transparent;
+ border:0;
+ border-radius:5px;
+ font-size:10px;
+ color:var(--muted);
+ padding:5px 8px;
+ min-width:66px;
+ min-height:28px;
+}
+
+.copy-code:hover {
+ color:var(--text);
+ background:var(--bg);
+}
+
+.copy-code[data-copied=true] {
+ color:var(--accent);
+}
+
+.table-wrap {
+ overflow:auto;
+ margin:20px 0;
+ border:1px solid var(--line);
+ border-radius:8px;
+ scrollbar-width:thin;
+}
+
+.prose table {
+ border-collapse:collapse;
+ width:100%;
+ font-size:13px;
+ line-height:1.75;
+ text-align:left;
+}
+
+.prose th {
+ font-weight:500;
+ color:var(--muted);
+ white-space:nowrap;
+}
+
+.prose th,.prose td {
+ padding:12px 15px;
+ border-bottom:1px solid var(--line);
+ vertical-align:top;
+}
+
+.prose tr:last-child td {
+ border-bottom:0;
+}
+
+.prose td code {
+ font-size:11px!important;
+}
+
+.prose td:first-child {
+ min-width:110px;
+}
+
+.callout,.prose blockquote {
+ padding:16px 19px;
+ margin:23px 0;
+ border-left:3px solid var(--accent);
+ background:var(--soft);
+ border-radius:0 6px 6px 0;
+ font-size:13px;
+}
+
+.callout p,.prose blockquote p {
+ margin:3px 0;
+}
+
+.callout-title {
+ display:block;
+ font-weight:600;
+ margin:0 0 5px;
+ color:var(--accent);
+}
+
+.callout.warning {
+ border-left-color:var(--yellow);
+}
+
+.callout.warning .callout-title {
+ color:var(--yellow);
+}
+
+.prose details {
+ margin:18px 0;
+ border:1px solid var(--line);
+ border-radius:8px;
+ padding:15px 18px;
+}
+
+.prose summary {
+ cursor:pointer;
+ font-size:13px;
+ font-weight:550;
+}
+
+.prose details[open] summary {
+ margin-bottom:12px;
+}
+
+.heading-anchor {
+ display:inline-block;
+ margin-left:9px;
+ font-size:.68em;
+ color:var(--muted);
+ opacity:0;
+ vertical-align:middle;
+}
+
+.prose h2:hover .heading-anchor,.prose h3:hover .heading-anchor,.heading-anchor:focus-visible {
+ opacity:1;
+}
+
+.prose figure {
+ margin:27px 0;
+}
+
+.prose figure img {
+ display:block;
+ width:100%;
+ height:auto;
+ border-radius:8px;
+ border:1px solid var(--line);
+ background:var(--soft);
+}
+
+.prose figure button {
+ display:block;
+ width:100%;
+ padding:0;
+ border:0;
+ border-radius:8px;
+ background:none;
+ cursor:zoom-in;
+}
+
+.prose figcaption {
+ font-size:10px;
+ color:var(--muted);
+ text-align:center;
+ line-height:1.7;
+ margin:10px 0;
+}
+
+.prose .narrow-figure {
+ max-width:310px;
+ margin-left:auto;
+ margin-right:auto;
+}
+
+.platform-tabs {
+ border:1px solid var(--line);
+ padding:18px 22px;
+ border-radius:8px;
+ margin:22px 0;
+}
+
+.platform-tablist {
+ display:none;
+ gap:6px;
+ border-bottom:1px solid var(--line);
+ margin:-2px 0 18px;
+ padding-bottom:12px;
+}
+
+.platform-tablist button {
+ background:none;
+ border:0;
+ border-radius:7px;
+ padding:7px 13px;
+ font-size:12px;
+}
+
+.platform-tablist button[aria-selected=true] {
+ background:var(--tint);
+ color:var(--accent);
+}
+
+.platform-tablist button:hover {
+ background:var(--soft);
+}
+
+.js .platform-tablist {
+ display:flex;
+}
+
+.platform-panel>:first-child {
+ margin-top:8px;
+}
+
+.source-details {
+ margin:40px 0 30px;
+ font-size:11px;
+ color:var(--muted);
+ border-top:1px solid var(--line);
+ padding-top:19px;
+}
+
+.source-details summary {
+ cursor:pointer;
+}
+
+.source-details ul {
+ padding-left:18px;
+}
+
+.source-details a {
+ text-decoration:underline;
+ text-underline-offset:3px;
+ overflow-wrap:anywhere;
+}
+
+.page-pagination {
+ display:grid;
+ grid-template-columns:1fr 1fr;
+ gap:15px;
+ margin:25px 0 35px;
+}
+
+.page-pagination a {
+ border:1px solid var(--line);
+ border-radius:8px;
+ padding:16px 18px;
+ display:flex;
+ flex-direction:column;
+ font-size:13px;
+}
+
+.page-pagination a:last-child {
+ text-align:right;
+}
+
+.page-pagination a:hover {
+ background:var(--soft);
+ border-color:var(--muted);
+}
+
+.page-pagination small {
+ color:var(--muted);
+ font-size:10px;
+ margin-bottom:5px;
+}
+
+.article-footer {
+ display:flex;
+ gap:20px;
+ border-top:1px solid var(--line);
+ padding:20px 0 34px;
+ font-size:10px;
+ color:var(--muted);
+}
+
+.article-footer>span {
+ margin-right:auto;
+}
+
+.article-footer a:hover {
+ color:var(--accent);
+}
+
+dialog {
+ color:var(--text);
+ border:1px solid var(--line);
+ background:var(--bg);
+ box-shadow:0 12px 40px color-mix(in srgb,#000 20%,transparent);
+ padding:0;
+}
+
+dialog::backdrop {
+ background:color-mix(in srgb,var(--text) 32%,transparent);
+}
+
+.search-dialog {
+ width:min(680px,calc(100vw - 32px));
+ border-radius:8px;
+ margin:15vh auto auto;
+ max-height:74vh;
+ overflow:hidden;
+}
+
+.search-dialog[open] {
+ display:flex;
+ flex-direction:column;
+ animation:dialog-in .2s ease-out;
+}
+
+.search-heading {
+ display:flex;
+ align-items:center;
+ gap:13px;
+ padding:18px 20px;
+ border-bottom:1px solid var(--line);
+}
+
+.search-heading svg {
+ color:var(--muted);
+}
+
+.search-heading input {
+ flex:1;
+ min-width:0;
+ border:0;
+ outline:none;
+ background:transparent;
+ color:var(--text);
+ font-size:15px;
+}
+
+.search-heading input:focus-visible {
+ outline:0;
+}
+
+.search-heading:focus-within {
+ box-shadow:inset 0 -2px var(--accent);
+}
+
+.search-status {
+ font-size:11px;
+ color:var(--muted);
+ padding:0 20px;
+ margin:12px 0 8px;
+}
+
+.search-results {
+ padding:0 9px 10px;
+ overflow:auto;
+ min-height:120px;
+ max-height:49vh;
+}
+
+.search-result {
+ display:block;
+ width:100%;
+ text-align:left;
+ border:1px solid transparent;
+ background:transparent;
+ color:var(--text);
+ padding:12px 14px;
+ border-radius:8px;
+ margin:2px 0;
+}
+
+.search-result[aria-selected=true],.search-result:hover {
+ background:var(--soft);
+ border-color:var(--line);
+}
+
+.search-result strong {
+ display:block;
+ font-size:13px;
+ font-weight:550;
+}
+
+.search-result small {
+ display:block;
+ font-size:11px;
+ color:var(--muted);
+ line-height:1.7;
+ margin-top:3px;
+ overflow:hidden;
+ text-overflow:ellipsis;
+}
+
+.search-result mark {
+ background:var(--tint);
+ color:var(--accent);
+ border-radius:2px;
+}
+
+.search-footer {
+ display:flex;
+ justify-content:space-between;
+ font-size:10px;
+ color:var(--muted);
+ border-top:1px solid var(--line);
+ padding:12px 20px;
+}
+
+.search-footer kbd {
+ font-size:9px;
+ margin-right:4px;
+}
+
+.image-dialog {
+ width:calc(100vw - 80px);
+ max-width:1500px;
+ max-height:92vh;
+ border-radius:8px;
+ padding:18px;
+ overflow:auto;
+ text-align:right;
+}
+
+.image-dialog img {
+ display:block;
+ width:100%;
+ height:auto;
+ margin:14px auto 0;
+}
+
+.image-dialog p {
+ font-size:12px;
+ text-align:center;
+ color:var(--muted);
+}
+
+.toast {
+ position:fixed;
+ left:50%;
+ bottom:28px;
+ transform:translate(-50%,12px);
+ background:var(--text);
+ color:var(--bg);
+ border:1px solid var(--line);
+ padding:10px 19px;
+ border-radius:8px;
+ font-size:12px;
+ opacity:0;
+ pointer-events:none;
+ transition:.2s;
+ z-index:100;
+ max-width:90vw;
+}
+
+.toast.show {
+ opacity:1;
+ transform:translate(-50%,0);
+}
+
+.noscript {
+ position:fixed;
+ bottom:0;
+ left:0;
+ right:0;
+ background:var(--soft);
+ padding:10px;
+ font-size:12px;
+ text-align:center;
+ z-index:50;
+}
+
+@keyframes dialog-in {
+ from {
+ opacity:0;
+ transform:translateY(-10px) scale(.985);
+ }
+ to {
+ opacity:1;
+ transform:none;
+ }
+}
+
+@media(min-width:1700px) {
+ .workspace {
+ padding-left:74px;
+ gap:72px;
+ grid-template-columns:minmax(0,840px) 190px;
+ }
+}
+
+@media(max-width:1280px) {
+ :root {
+ --sidebar:232px;
+ }
+ .header {
+ padding:0 23px;
+ gap:30px;
+ }
+ .workspace {
+ padding-left:38px;
+ padding-right:30px;
+ gap:30px;
+ grid-template-columns:minmax(0,800px) 140px;
+ }
+ .sidebar {
+ padding-left:17px;
+ }
+ .search-trigger {
+ width:195px;
+ }
+ .hero h1 {
+ font-size:35px;
+ }
+}
+
+@media(max-width:1080px) {
+ .toc {
+ display:none;
+ }
+ .workspace {
+ grid-template-columns:minmax(0,800px);
+ padding-left:38px;
+ padding-right:38px;
+ }
+ .header-links {
+ gap:20px;
+ }
+ .hero h1 {
+ font-size:37px;
+ }
+ .header {
+ gap:25px;
+ }
+ .brand-docs {
+ display:none;
+ }
+}
+
+@media(max-width:800px) {
+ :root {
+ --header:62px;
+ --sidebar:272px;
+ }
+ .header {
+ padding:0 17px;
+ gap:15px;
+ }
+ .brand>span:first-of-type {
+ font-size:20px;
+ }
+ .brand img {
+ width:28px;
+ height:28px;
+ }
+ .header-links {
+ display:none;
+ }
+ .header-actions {
+ gap:2px;
+ }
+ .search-trigger {
+ width:40px;
+ padding:0;
+ display:grid;
+ place-items:center;
+ border:0;
+ background:transparent;
+ }
+ .search-trigger span,.search-trigger kbd {
+ display:none;
+ }
+ .menu-toggle {
+ display:grid;
+ }
+ .sidebar {
+ transform:translateX(-100%);
+ transition:transform .24s ease;
+ width:var(--sidebar);
+ z-index:45;
+ padding:24px 19px 20px;
+ visibility:hidden;
+ }
+ .sidebar.open {
+ transform:translateX(0);
+ visibility:visible;
+ }
+ .drawer-backdrop {
+ position:fixed;
+ inset:var(--header) 0 0;
+ background:color-mix(in srgb,var(--text) 32%,transparent);
+ z-index:44;
+ }
+ .workspace {
+ margin-left:0;
+ padding:calc(var(--header) + 28px) 24px 0;
+ display:block;
+ }
+ .page-heading h1 {
+ font-size:31px;
+ }
+ .hero {
+ padding:29px 26px;
+ border-radius:8px;
+ }
+ .hero h1 {
+ font-size:34px;
+ }
+ .hero p {
+ font-size:13px;
+ max-width:370px;
+ }
+ .breadcrumb {
+ margin-bottom:22px;
+ }
+ .page-description {
+ font-size:14px;
+ }
+ .nav-link {
+ padding:10px 12px;
+ min-height:42px;
+ }
+ .article-footer {
+ gap:13px;
+ flex-wrap:wrap;
+ }
+ .article-footer>span {
+ width:100%;
+ }
+ .search-dialog {
+ margin-top:10vh;
+ }
+ .icon-button {
+ width:42px;
+ height:42px;
+ }
+ .small-button {
+ min-height:38px;
+ }
+ .copy-code {
+ min-height:32px;
+ }
+ .platform-tablist button {
+ min-height:40px;
+ }
+}
+
+@media(max-width:480px) {
+ .workspace {
+ padding-left:19px;
+ padding-right:19px;
+ }
+ .hero {
+ padding:26px 23px;
+ }
+ .hero h1 {
+ font-size:29px;
+ letter-spacing:-.7px;
+ }
+ .hero p {
+ font-size:12px;
+ }
+ .hero-actions {
+ gap:15px;
+ }
+ .platform-strip {
+ gap:11px;
+ font-size:10px;
+ flex-wrap:wrap;
+ }
+ .contribution-flow {
+ grid-template-columns:1fr;
+ }
+ .feature-grid {
+ gap:11px;
+ }
+ .feature-card {
+ padding:17px!important;
+ }
+ .feature-card h3 {
+ font-size:14px!important;
+ }
+ .feature-card p {
+ font-size:11px!important;
+ }
+ .prose {
+ font-size:15px;
+ }
+ .prose h2 {
+ font-size:21px;
+ }
+ .prose pre {
+ font-size:12px;
+ padding:17px;
+ }
+ .breadcrumb {
+ align-items:flex-start;
+ flex-wrap:wrap;
+ }
+ .page-tools {
+ width:100%;
+ flex-wrap:wrap;
+ justify-content:flex-start;
+ margin-left:0;
+ }
+ .readme-visual-grid {
+ grid-template-columns:1fr;
+ }
+ .contribution-flow {
+ grid-template-columns:repeat(2,minmax(0,1fr));
+ }
+ .page-pagination {
+ gap:9px;
+ }
+ .page-pagination a {
+ padding:13px;
+ font-size:12px;
+ }
+ .search-heading {
+ padding:13px;
+ }
+ .search-footer {
+ padding:11px 13px;
+ }
+ .search-footer>span:last-child {
+ display:none;
+ }
+ .image-dialog {
+ width:calc(100vw - 20px);
+ padding:10px;
+ }
+ .prose th,.prose td {
+ padding:10px;
+ }
+ .platform-tabs {
+ padding:16px;
+ }
+ .page-heading h1 {
+ font-size:29px;
+ }
+}
+
+@media(prefers-reduced-motion:reduce) {
+ html {
+ scroll-behavior:auto;
+ }
+ *,*:before,*:after {
+ animation:none!important;
+ transition:none!important;
+ view-transition-name:none!important;
+ }
+ ::view-transition-group(*),::view-transition-old(*),::view-transition-new(*) {
+ animation:none!important;
+ }
+ .feature-card:hover {
+ transform:none;
+ }
+}
+
+@media print {
+ html[data-theme] {
+ --bg:#fff;
+ --soft:#f7f7f7;
+ --panel:#fff;
+ --text:#000;
+ --muted:#444;
+ --line:#bbb;
+ --accent:#111;
+ --tint:#f7f7f7;
+ --code:#f5f5f5;
+ color-scheme:light;
+ }
+ .code-block,.code-block code,.code-block code span {
+ color:#000!important;
+ background:transparent!important;
+ }
+ .header,.sidebar,.toc,.page-tools,.page-pagination,.article-footer,.heading-anchor,dialog,.toast,.back-top,.copy-code {
+ display:none!important;
+ }
+ .workspace {
+ margin:0;
+ padding:0;
+ display:block;
+ }
+ body {
+ font-size:11pt;
+ background:#fff;
+ color:#000;
+ }
+ .prose {
+ font-size:10pt;
+ }
+ .prose h2,.prose h3 {
+ break-after:avoid;
+ }
+ .code-block,.callout,.prose figure {
+ break-inside:avoid;
+ }
+ .prose pre {
+ white-space:pre-wrap;
+ }
+ .prose a {
+ color:inherit;
+ }
+ .hero {
+ background:#f5f5f5;
+ }
+ .source-details {
+ display:none;
+ }
+ .platform-panel[hidden] {
+ display:block!important;
+ }
+ .platform-tablist {
+ display:none!important;
+ }
+ main {
+ max-width:100%;
+ }
+ .feature-grid {
+ display:block;
+ }
+ .feature-card {
+ margin-bottom:10px;
+ }
+}
+
+@media(max-width:800px) {
+ html:not(.js) .sidebar {
+ position:relative;
+ top:auto;
+ bottom:auto;
+ transform:none;
+ visibility:visible;
+ width:100%;
+ margin-top:var(--header);
+ max-height:300px;
+ border-bottom:1px solid var(--line);
+ }
+ html:not(.js) .workspace {
+ padding-top:28px;
+ }
+}
+
+.palette-picker {
+ position:relative;
+}
+
+.palette-menu {
+ position:absolute;
+ right:0;
+ top:calc(100% + 8px);
+ width:232px;
+ max-height:min(560px,calc(100vh - var(--header) - 24px));
+ overflow:auto;
+ padding:6px;
+ border:1px solid var(--line);
+ border-radius:8px;
+ background:var(--bg);
+ box-shadow:0 12px 40px color-mix(in srgb,#000 18%,transparent);
+ z-index:60;
+ scrollbar-width:thin;
+}
+
+.palette-group {
+ display:flex;
+ flex-direction:column;
+ margin-top:6px;
+ padding-top:6px;
+ border-top:1px solid var(--line);
+}
+
+.palette-group>span {
+ padding:4px 10px;
+ font-size:11px;
+ color:var(--muted);
+}
+
+.palette-menu button {
+ display:flex;
+ align-items:center;
+ gap:10px;
+ width:100%;
+ padding:7px 10px;
+ border:0;
+ border-radius:6px;
+ background:transparent;
+ font-size:13px;
+ text-align:left;
+}
+
+.palette-menu button:hover,
+.palette-menu button:focus-visible {
+ background:var(--soft);
+}
+
+.palette-menu button[aria-checked=true] {
+ color:var(--accent);
+ font-weight:550;
+}
+
+.palette-menu button[aria-checked=true]::after {
+ content:"✓";
+ margin-left:auto;
+}
+
+.swatch {
+ width:16px;
+ height:16px;
+ flex:none;
+ border:1px solid var(--line);
+ border-radius:50%;
+ background:linear-gradient(135deg,var(--a) 50%,var(--b) 50%);
+}
+
+.swatch-system {
+ --a:#eceff4;
+ --b:#2e3440;
+}
diff --git a/docs/site/assets/site.js b/docs/site/assets/site.js
new file mode 100644
index 000000000..231936085
--- /dev/null
+++ b/docs/site/assets/site.js
@@ -0,0 +1,292 @@
+(() => {
+ 'use strict';
+ document.documentElement.classList.add('js');
+ const root = document.body.dataset.root;
+ const $ = (selector) => document.querySelector(selector);
+ const $$ = (selector) => [...document.querySelectorAll(selector)];
+ const reducedMotion = matchMedia('(prefers-reduced-motion: reduce)');
+ const toast = $('.toast');
+ let toastTimer;
+ function announce(message) {
+ clearTimeout(toastTimer);
+ toast.textContent = message;
+ toast.classList.add('show');
+ toastTimer = setTimeout(() => toast.classList.remove('show'), 2600);
+ }
+
+ const copyTimers = new WeakMap();
+ async function copy(text, button) {
+ try {
+ await navigator.clipboard.writeText(text);
+ clearTimeout(copyTimers.get(button));
+ const label = button.dataset.label || button.textContent;
+ button.dataset.label = label;
+ button.dataset.copied = 'true';
+ button.textContent = '✓ 已复制';
+ announce('已复制到剪贴板');
+ copyTimers.set(button, setTimeout(() => {
+ button.textContent = label;
+ delete button.dataset.copied;
+ }, 1700));
+ } catch {
+ announce('复制未成功,请选中文本手动复制。');
+ }
+ }
+ $$('.copy-code').forEach(button => button.addEventListener('click', () => {
+ copy(button.closest('.code-block').querySelector('code').textContent, button);
+ }));
+ const copyPage = $('#copy-page');
+ copyPage?.addEventListener('click', () => copy(
+ JSON.parse($('#page-source').textContent), copyPage
+ ));
+ $$('.heading-anchor').forEach(link => link.addEventListener('click', async () => {
+ try {
+ await navigator.clipboard.writeText(link.href);
+ announce('已复制本节链接');
+ } catch {
+ announce('已定位本节;可从地址栏复制链接。');
+ }
+ }));
+
+ const html = document.documentElement;
+ const paletteButton = $('#theme-toggle');
+ const paletteMenu = $('#palette-menu');
+ const paletteOptions = $$('[data-palette-option]');
+ const darkPalettes = new Set(paletteOptions.filter(option => option.closest('[aria-label="深色"]')).map(option => option.dataset.paletteOption));
+ const systemDark = matchMedia('(prefers-color-scheme: dark)');
+ function applyPalette(choice, remember) {
+ const id = choice === 'system' ? (systemDark.matches ? 'Nord' : 'NordLight') : choice;
+ html.dataset.switching = '';
+ requestAnimationFrame(() => requestAnimationFrame(() => delete html.dataset.switching));
+ html.dataset.palette = id;
+ html.dataset.theme = darkPalettes.has(id) ? 'dark' : 'light';
+ if (choice === 'system') html.dataset.follow = 'system'; else delete html.dataset.follow;
+ paletteOptions.forEach(option => option.setAttribute('aria-checked', String(option.dataset.paletteOption === choice)));
+ $('meta[name=theme-color]')?.setAttribute('content', getComputedStyle(html).getPropertyValue('--bg').trim());
+ if (remember) { try { localStorage.setItem('pebrel-docs-palette', choice); } catch { /* Session only. */ } }
+ }
+ function currentChoice() { return html.dataset.follow === 'system' ? 'system' : html.dataset.palette; }
+ function setPaletteMenu(open) {
+ paletteMenu.hidden = !open;
+ paletteButton.setAttribute('aria-expanded', String(open));
+ if (open) (paletteMenu.querySelector('[aria-checked=true]') || paletteOptions[0]).focus();
+ }
+ applyPalette(currentChoice(), false);
+ paletteButton.addEventListener('click', () => setPaletteMenu(paletteMenu.hidden));
+ paletteOptions.forEach(option => option.addEventListener('click', () => {
+ applyPalette(option.dataset.paletteOption, true);
+ setPaletteMenu(false);
+ paletteButton.focus();
+ }));
+ paletteMenu.addEventListener('keydown', event => {
+ const index = paletteOptions.indexOf(document.activeElement);
+ if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+ event.preventDefault();
+ paletteOptions[(index + (event.key === 'ArrowDown' ? 1 : -1) + paletteOptions.length) % paletteOptions.length].focus();
+ } else if (event.key === 'Escape') {
+ setPaletteMenu(false);
+ paletteButton.focus();
+ }
+ });
+ document.addEventListener('click', event => {
+ if (!paletteMenu.hidden && !event.target.closest('.palette-picker')) setPaletteMenu(false);
+ });
+ systemDark.addEventListener('change', () => { if (currentChoice() === 'system') applyPalette('system', false); });
+
+ const sidebar = $('#sidebar');
+ const menu = $('#menu-toggle');
+ const backdrop = $('.drawer-backdrop');
+ const mobile = matchMedia('(max-width: 800px)');
+ function setMenu(open) {
+ sidebar.classList.toggle('open', open);
+ backdrop.hidden = !open;
+ menu.setAttribute('aria-expanded', String(open));
+ menu.setAttribute('aria-label', open ? '关闭文档导航' : '打开文档导航');
+ document.body.style.overflow = open ? 'hidden' : '';
+ sidebar.inert = mobile.matches && !open;
+ $('.workspace').inert = open;
+ if (open) sidebar.querySelector('.active, a').focus();
+ }
+ setMenu(false);
+ menu.addEventListener('click', () => setMenu(!sidebar.classList.contains('open')));
+ backdrop.addEventListener('click', () => { setMenu(false); menu.focus(); });
+ mobile.addEventListener('change', () => setMenu(false));
+ sidebar.querySelector('.active')?.scrollIntoView({ block: 'nearest' });
+
+ const searchDialog = $('#search-dialog');
+ const input = $('#search-input');
+ const results = $('#search-results');
+ const status = $('.search-status');
+ let indexPromise;
+ let index = [];
+ let matches = [];
+ let selected = 0;
+ let searchOpener;
+ function loadIndex() {
+ if (Array.isArray(window.PEBREL_DOCS_SEARCH)) return Promise.resolve(window.PEBREL_DOCS_SEARCH);
+ if (!indexPromise) indexPromise = new Promise((resolve, reject) => {
+ const script = document.createElement('script');
+ script.src = root + 'search-index.js';
+ script.onload = () => resolve(window.PEBREL_DOCS_SEARCH);
+ script.onerror = () => { script.remove(); indexPromise = null; reject(new Error('Search unavailable')); };
+ document.head.append(script);
+ });
+ return indexPromise;
+ }
+ function highlight(target, text, query) {
+ if (!query) { target.textContent = text; return; }
+ const position = text.toLocaleLowerCase().indexOf(query.toLocaleLowerCase());
+ if (position < 0) { target.textContent = text; return; }
+ target.append(document.createTextNode(text.slice(0, position)));
+ const mark = document.createElement('mark');
+ mark.textContent = text.slice(position, position + query.length);
+ target.append(mark, document.createTextNode(text.slice(position + query.length)));
+ }
+ function selectResult(value) {
+ selected = Math.max(0, Math.min(value, matches.length - 1));
+ [...results.children].forEach((element, position) => {
+ element.setAttribute('aria-selected', String(position === selected));
+ });
+ const active = results.children[selected];
+ if (active) {
+ input.setAttribute('aria-activedescendant', active.id);
+ active.scrollIntoView({ block: 'nearest' });
+ } else input.removeAttribute('aria-activedescendant');
+ }
+ function renderResults() {
+ const query = input.value.trim();
+ const terms = query.toLocaleLowerCase().split(/\s+/).filter(Boolean);
+ matches = index.map(item => {
+ const title = item.title.toLocaleLowerCase();
+ const text = (item.title + ' ' + item.text).toLocaleLowerCase();
+ const score = terms.every(term => text.includes(term))
+ ? terms.reduce((n, term) => n + (title.includes(term) ? 15 : 1), 0) + (title === query.toLocaleLowerCase() ? 50 : 0)
+ : -1;
+ return { ...item, score };
+ }).filter(item => item.score >= 0).sort((a, b) => b.score - a.score).slice(0, 18);
+ results.replaceChildren();
+ status.textContent = query ? (matches.length ? `找到 ${matches.length}${matches.length === 18 ? '+' : ''} 个相关章节` : '没有找到相关内容。试试“分屏”“SSH”或“字体”。') : '从常用指南开始,或输入功能、设置与操作步骤。';
+ matches.forEach((item, position) => {
+ const row = document.createElement('div');
+ row.className = 'search-result';
+ row.id = 'search-result-' + position;
+ row.setAttribute('role', 'option');
+ const title = document.createElement('strong');
+ highlight(title, item.title, query);
+ const description = document.createElement('small');
+ const matchPosition = query ? item.text.toLocaleLowerCase().indexOf(terms[0]) : 0;
+ const start = Math.max(0, matchPosition - 28);
+ highlight(description, (start ? '…' : '') + item.text.slice(start, start + 130), query);
+ row.append(title, description);
+ row.addEventListener('click', () => { location.href = root + item.url; });
+ row.addEventListener('pointermove', () => selectResult(position));
+ results.append(row);
+ });
+ selectResult(0);
+ }
+ async function openSearch() {
+ if (sidebar.classList.contains('open')) setMenu(false);
+ searchOpener = document.activeElement;
+ if (!searchDialog.open) searchDialog.showModal();
+ input.focus();
+ status.textContent = '正在准备本地搜索索引…';
+ try { index = await loadIndex(); renderResults(); }
+ catch { status.textContent = '搜索索引未能加载。请刷新重试,或使用左侧目录。'; }
+ }
+ $$('[data-search]').forEach(button => button.addEventListener('click', openSearch));
+ $$('[data-close-search]').forEach(button => button.addEventListener('click', () => searchDialog.close()));
+ searchDialog.addEventListener('close', () => searchOpener?.focus());
+ searchDialog.addEventListener('click', event => { if (event.target === searchDialog) searchDialog.close(); });
+ input.addEventListener('input', renderResults);
+ input.addEventListener('keydown', event => {
+ if (event.key === 'Escape') { event.preventDefault(); searchDialog.close(); return; }
+ if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+ event.preventDefault(); selectResult(selected + (event.key === 'ArrowDown' ? 1 : -1));
+ }
+ if (event.key === 'Enter' && matches[selected]) location.href = root + matches[selected].url;
+ });
+ if (!/Mac|iPhone|iPad/.test(navigator.platform)) $$('[data-shortcut]').forEach(kbd => kbd.textContent = 'Ctrl K');
+ document.addEventListener('keydown', event => {
+ const typing = event.target.closest('input,textarea,[contenteditable=true]');
+ if (((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') || (event.key === '/' && !typing && !event.ctrlKey && !event.metaKey)) {
+ event.preventDefault(); openSearch();
+ }
+ if (event.key === 'Escape' && sidebar.classList.contains('open')) {
+ setMenu(false); menu.focus();
+ }
+ if (event.key === 'Tab' && sidebar.classList.contains('open')) {
+ const links = [...sidebar.querySelectorAll('a')];
+ if (event.shiftKey && document.activeElement === links[0]) { event.preventDefault(); menu.focus(); }
+ else if (!event.shiftKey && document.activeElement === links.at(-1)) { event.preventDefault(); menu.focus(); }
+ else if (document.activeElement === menu) { event.preventDefault(); (event.shiftKey ? links.at(-1) : links[0]).focus(); }
+ }
+ });
+
+ const imageDialog = $('#image-dialog');
+ $$('figure img').forEach(image => {
+ const button = document.createElement('button');
+ button.type = 'button';
+ button.setAttribute('aria-label', '放大查看:' + image.alt);
+ image.replaceWith(button); button.append(image);
+ button.addEventListener('click', () => {
+ const preview = imageDialog.querySelector('img');
+ preview.src = image.currentSrc || image.src; preview.alt = image.alt;
+ imageDialog.querySelector('p').textContent = image.closest('figure').querySelector('figcaption')?.textContent || image.alt;
+ imageDialog.showModal();
+ });
+ });
+ $('#close-image').addEventListener('click', () => imageDialog.close());
+ imageDialog.addEventListener('click', event => { if (event.target === imageDialog) imageDialog.close(); });
+
+ $$('.platform-tabs').forEach((group, groupIndex) => {
+ const tabs = [...group.querySelectorAll('[data-platform]')];
+ const panels = [...group.querySelectorAll('.platform-panel')];
+ group.querySelector('.platform-tablist').setAttribute('role', 'tablist');
+ function choose(position, focus = false) {
+ tabs.forEach((tab, index) => {
+ tab.setAttribute('role', 'tab'); tab.id = `platform-${groupIndex}-${index}`;
+ tab.setAttribute('aria-selected', String(index === position)); tab.tabIndex = index === position ? 0 : -1;
+ panels[index].hidden = index !== position;
+ panels[index].id = `platform-panel-${groupIndex}-${index}`;
+ panels[index].setAttribute('role', 'tabpanel'); panels[index].tabIndex = 0;
+ panels[index].setAttribute('aria-labelledby', tab.id); tab.setAttribute('aria-controls', panels[index].id);
+ });
+ if (focus) tabs[position].focus();
+ }
+ tabs.forEach((tab, position) => {
+ tab.addEventListener('click', () => choose(position));
+ tab.addEventListener('keydown', event => {
+ let next;
+ if (event.key === 'ArrowRight') next = (position + 1) % tabs.length;
+ if (event.key === 'ArrowLeft') next = (position + tabs.length - 1) % tabs.length;
+ if (event.key === 'Home') next = 0;
+ if (event.key === 'End') next = tabs.length - 1;
+ if (next !== undefined) { event.preventDefault(); choose(next, true); }
+ });
+ });
+ choose(0);
+ });
+
+ const headings = $$('#article-content h2, #article-content h3');
+ const tocLinks = $$('.toc a');
+ let scheduled = false;
+ function onScroll() {
+ if (scheduled) return;
+ scheduled = true;
+ requestAnimationFrame(() => {
+ let active = headings[0]?.id;
+ for (const heading of headings) { if (heading.getBoundingClientRect().top <= 145) active = heading.id; }
+ tocLinks.forEach(link => link.classList.toggle('active', decodeURIComponent(link.hash.slice(1)) === active));
+ scheduled = false;
+ });
+ }
+ addEventListener('scroll', onScroll, { passive: true });
+ onScroll();
+ $('.back-top').addEventListener('click', () => { scrollTo({ top: 0, behavior: reducedMotion.matches ? 'instant' : 'smooth' }); $('#main').focus({ preventScroll: true }); });
+ if (!reducedMotion.matches) {
+ const observer = new IntersectionObserver(entries => entries.forEach(entry => {
+ if (entry.isIntersecting) { entry.target.classList.add('revealed'); observer.unobserve(entry.target); }
+ }), { threshold: 0.08 });
+ $$('.feature-card, .hero, figure').forEach(element => observer.observe(element));
+ }
+})();
diff --git a/docs/site/build.py b/docs/site/build.py
new file mode 100644
index 000000000..a298fbd88
--- /dev/null
+++ b/docs/site/build.py
@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""Build Pebrel's Markdown user guide into a portable, server-free HTML site."""
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import re
+import shutil
+from pathlib import Path
+from string import Template
+from urllib.parse import quote
+from xml.sax.saxutils import escape as xml_escape
+
+import mistune
+import palettes
+from pygments import highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import TextLexer, get_lexer_by_name
+from pygments.util import ClassNotFound
+
+HERE = Path(__file__).resolve().parent
+REPO = HERE.parent.parent
+UPSTREAM = "https://github.com/Kuddev/pebrel"
+SITE_VERSION = json.loads((Path(__file__).resolve().parent / "site.json").read_text(encoding="utf-8"))["version"]
+
+
+def plain(text: str) -> str:
+ return re.sub(r"\s+", " ", html.unescape(re.sub(r"<[^>]+>", " ", text))).strip()
+
+
+def page_url(slug: str) -> str:
+ return "index.html" if slug == "index" else f"{slug}/index.html"
+
+
+class Renderer(mistune.HTMLRenderer):
+ def __init__(self, root: str):
+ super().__init__(escape=False)
+ self.root = root
+ self.headings: list[tuple[int, str, str]] = []
+ self.ids: dict[str, int] = {}
+
+ def heading(self, text: str, level: int, **attrs) -> str:
+ label = plain(text)
+ base = re.sub(r"[^\w\-]+", "-", label.lower()).strip("-") or "section"
+ count = self.ids.get(base, 0)
+ self.ids[base] = count + 1
+ identity = f"{base}-{count}" if count else base
+ self.headings.append((level, identity, label))
+ return (f'{text}'
+ f'#\n')
+
+ def link(self, text: str, url: str, title=None) -> str:
+ if not re.match(r"^[a-z]+:|^//|^#", url):
+ name, sep, fragment = url.partition("#")
+ if name.endswith(".md"):
+ url = self.root + page_url(Path(name).stem) + (sep + fragment if sep else "")
+ return super().link(text, url, title)
+
+ def block_code(self, code: str, info=None) -> str:
+ language = (info or "text").split()[0]
+ try:
+ lexer = get_lexer_by_name(language)
+ except ClassNotFound:
+ lexer = TextLexer()
+ rendered = highlight(code, lexer, HtmlFormatter(nowrap=True))
+ return (f'
{html.escape(language)}'
+ '
'
+ f'
{rendered}
\n')
+
+ def block_quote(self, text: str) -> str:
+ match = re.match(r"\[!(NOTE|TIP|WARNING|IMPORTANT)\]\s*", text)
+ if match:
+ kind = match[1]
+ title = {"NOTE": "说明", "TIP": "使用提示", "WARNING": "注意", "IMPORTANT": "请先确认"}[kind]
+ text = "
" + text[match.end():]
+ return (f'\n')
+ return super().block_quote(text)
+
+ def table(self, text: str) -> str:
+ return '
\n'
+
+
+def render_markdown(source: str, root: str) -> tuple[str, Renderer]:
+ renderer = Renderer(root)
+ markdown = mistune.create_markdown(renderer=renderer, plugins=["table", "strikethrough", "task_lists", "footnotes"])
+ return markdown(source.replace("@ROOT@", root)), renderer
+
+
+def navigation(groups: list[dict], active: str, root: str) -> str:
+ result = []
+ for group in groups:
+ links = []
+ for page in group["pages"]:
+ current = page["slug"] == active
+ links.append(f'{html.escape(page["title"])}')
+ result.append(f'{html.escape(group["title"])}
{"".join(links)}')
+ return "\n".join(result)
+
+
+def home_header() -> str:
+ release = f"{UPSTREAM}/releases/latest"
+ return f'''
+'''
+
+
+def source_details(page: dict, commit: str) -> str:
+ commit = page.get("source_commit", commit)
+ sources = page.get("sources", [])
+ links = "".join(f'{html.escape(path)}' for path in sources)
+ return (f'版本与参考 · {commit[:7]}
'
+ f'适用版本:Pebrel {html.escape(page.get("version", SITE_VERSION))}。以下链接提供相关设置与功能的参考。
')
+
+
+def build(destination: Path, base_url: str) -> dict:
+ config = json.loads((HERE / "site.json").read_text())
+ pages = [dict(page, group=group["title"]) for group in config["groups"] for page in group["pages"]]
+ slugs = [page["slug"] for page in pages]
+ if len(slugs) != len(set(slugs)):
+ raise ValueError("Duplicate page slug")
+ template = Template((HERE / "template.html").read_text())
+ destination = destination.resolve()
+ screenshots = REPO / "docs" / "screenshots"
+ if destination != HERE / "dist" and (
+ REPO.is_relative_to(destination)
+ or any(
+ source == destination
+ or source.is_relative_to(destination)
+ or destination.is_relative_to(source)
+ for source in (HERE, screenshots)
+ )
+ ):
+ raise ValueError("Output directory overlaps repository sources")
+ if destination.exists():
+ if not destination.is_dir():
+ raise ValueError("Output path is not a directory")
+ generated_site = (
+ (destination / "build-info.json").is_file()
+ and (destination / ".nojekyll").is_file()
+ )
+ if any(destination.iterdir()) and not generated_site:
+ raise ValueError("Refusing to replace an output directory that is not a generated site")
+ shutil.rmtree(destination)
+ destination.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(REPO / "LICENSE", destination / "LICENSE")
+ shutil.copy2(HERE / "third-party-notices.txt", destination / "third-party-notices.txt")
+ assets = destination / "assets"
+ shutil.copytree(HERE / "assets", assets, dirs_exist_ok=True)
+ shutil.copy2(REPO / "extra/logo/nebula.png", assets / "pebrel.png")
+ screenshot_dir = assets / "screenshots"
+ screenshot_dir.mkdir(exist_ok=True)
+ shutil.copy2(HERE / "screenshots.json", screenshot_dir / "sources.json")
+ for filename in config["images"]:
+ shutil.copy2(REPO / "docs/screenshots" / filename, screenshot_dir / filename)
+ themes = palettes.load()
+ (assets / "palettes.css").write_text(palettes.stylesheet(themes), encoding="utf-8")
+ (assets / "highlight.css").write_text(palettes.code_stylesheet(), encoding="utf-8")
+ palette_menu, dark_palettes = palettes.menu(themes), palettes.dark_ids(themes)
+ search = []
+ total_characters = 0
+ all_markdown = []
+ for position, page in enumerate(pages):
+ slug = page["slug"]
+ root = "./" if slug == "index" else "../"
+ source = (HERE / "content" / f"{slug}.md").read_text(encoding="utf-8")
+ for path in page.get("sources", []):
+ if not (REPO / path.split("#")[0]).is_file():
+ raise ValueError(f"{slug}: unknown evidence source {path}")
+ content, renderer = render_markdown(source, root)
+ total_characters += len(plain(content))
+ if slug == "index":
+ header = home_header()
+ breadcrumb_tools = ""
+ else:
+ header = (
+ f'{html.escape(page["title"])}
'
+ f'{html.escape(page["description"])}
')
+ breadcrumb_tools = (
+ f'')
+ header += ''
+ toc = "".join(f'{html.escape(label)}' for level, identity, label in renderer.headings if level in (2, 3))
+ pagination = []
+ for offset, label, arrow in [(-1, "上一篇", "← "), (1, "下一篇", "→ ")]:
+ neighbor = position + offset
+ if 0 <= neighbor < len(pages):
+ target = pages[neighbor]
+ pagination.append(f'{label}{arrow}{html.escape(target["title"])}')
+ else:
+ pagination.append('')
+ canonical = f'' if base_url else ""
+ output = template.substitute(
+ description=html.escape(page["description"]), title=html.escape(page["title"]), canonical=canonical,
+ root=root, slug=slug, version=html.escape(page.get("version", config["version"])), group=html.escape(page["group"]),
+ navigation=navigation(config["groups"], slug, root), main_class="home" if slug == "index" else "document",
+ breadcrumb_tools=breadcrumb_tools, page_header=header, content=content, source_details=source_details(page, config["source_commit"]),
+ palette_menu=palette_menu, dark_palettes=dark_palettes,
+ pagination="".join(pagination), toc=toc, edit_url=f'{UPSTREAM}/edit/main/docs/site/content/{slug}.md')
+ target = destination / page_url(slug)
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_text(output, encoding="utf-8")
+ (destination / "markdown").mkdir(exist_ok=True)
+ (destination / "markdown" / f"{slug}.md").write_text(source, encoding="utf-8")
+ # Each section is independently searchable and links to its own anchor.
+ parts = re.split(r'(.*?)', content, flags=re.S)
+ search.append({"title": page["title"], "text": page["description"] + " " + plain(parts[0]), "url": page_url(slug)})
+ for i in range(1, len(parts), 2):
+ identity = re.search(r'id="([^"]+)"', parts[i])[1]
+ heading = plain(re.sub(r'', '', parts[i], flags=re.S))
+ search.append({"title": f'{page["title"]} · {heading}', "text": plain(parts[i + 1]), "url": page_url(slug) + "#" + quote(identity)})
+ all_markdown.append(f'# {page["title"]}\n\n{source}')
+ (destination / "search-index.js").write_text('window.PEBREL_DOCS_SEARCH=' + json.dumps(search, ensure_ascii=False).replace("<", "\\u003c") + ';\n', encoding="utf-8")
+ (destination / ".nojekyll").touch()
+ (destination / "llms.txt").write_text('# Pebrel 用户手册\n\n' + '\n'.join(f'- [{page["title"]}]({base_url}markdown/{page["slug"]}.md): {page["description"]}' for page in pages) + '\n', encoding="utf-8")
+ (destination / "llms-full.txt").write_text('\n\n---\n\n'.join(all_markdown), encoding="utf-8")
+ (destination / "404.html").write_text(f'未找到页面 · Pebrel404 / PEBREL DOCS这一页不在这里。
地址可能已变更。回到文档首页,通过目录或搜索继续查找。
返回文档首页 →', encoding="utf-8")
+ if base_url:
+ (destination / "sitemap.xml").write_text('' + ''.join(f'{xml_escape(base_url + page_url(page["slug"]))}' for page in pages) + '', encoding="utf-8")
+ stats = {"pages": len(pages), "search_sections": len(search), "text_characters": total_characters, "source_commit": config["source_commit"]}
+ (destination / "build-info.json").write_text(json.dumps(stats, indent=2) + "\n")
+ return stats
+
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--output", type=Path, default=HERE / "dist")
+ parser.add_argument("--base-url", default="", help="Canonical URL, including the repository subpath")
+ args = parser.parse_args()
+ url = args.base_url.rstrip("/") + "/" if args.base_url else ""
+ print(json.dumps(build(args.output.resolve(), url), ensure_ascii=False, indent=2))
diff --git a/docs/site/check_browser.py b/docs/site/check_browser.py
new file mode 100644
index 000000000..9387806b4
--- /dev/null
+++ b/docs/site/check_browser.py
@@ -0,0 +1,115 @@
+"""Exercise the built guide under a repository Pages prefix in a real browser."""
+import argparse
+import json
+import os
+import shutil
+import tempfile
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from threading import Thread
+
+from playwright.sync_api import sync_playwright, expect
+
+
+class QuietHandler(SimpleHTTPRequestHandler):
+ def log_message(self, *args):
+ pass
+
+
+def check(site: Path, output: Path):
+ output.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory() as temporary:
+ served = Path(temporary)
+ shutil.copytree(site, served / 'pebrel')
+ server = ThreadingHTTPServer(('127.0.0.1', 0), partial(QuietHandler, directory=temporary))
+ Thread(target=server.serve_forever, daemon=True).start()
+ base = f'http://127.0.0.1:{server.server_port}/pebrel/'
+ errors = []
+ try:
+ with sync_playwright() as playwright:
+ executable = os.environ.get('CHROMIUM_PATH')
+ browser = playwright.chromium.launch(executable_path=executable)
+ context = browser.new_context(viewport={'width': 1512, 'height': 1000}, permissions=['clipboard-read', 'clipboard-write'])
+ page = context.new_page()
+ page.on('pageerror', lambda error: errors.append(str(error)))
+ page.goto(base)
+ expect(page.locator('h1')).to_contain_text('从一个终端开始')
+ page.wait_for_timeout(650)
+ page.screenshot(path=str(output / 'docs-desktop.png'), full_page=True)
+ page.keyboard.press('Control+k')
+ page.locator('#search-input').fill('分屏')
+ expect(page.locator('.search-result').first).to_be_visible()
+ page.keyboard.press('Enter')
+ # Search may match a complete guide or a section within it.
+ expect(page).to_have_url(__import__('re').compile(r'/pebrel/[^#?]+/index\.html(?:#.*)?$'))
+ expect(page.locator('#article-content h2').first).to_be_visible()
+ page.keyboard.press('Control+k')
+ page.locator('#search-input').fill('字体')
+ page.keyboard.press('Escape')
+ expect(page.locator('#search-dialog')).not_to_be_visible()
+ page.goto(base + 'quickstart/index.html')
+ page.locator('.copy-code').first.click()
+ expect(page.locator('.copy-code').first).to_have_attribute('data-copied', 'true')
+ assert 'echo Hello, Pebrel' in page.evaluate('navigator.clipboard.readText()')
+ page.locator('#theme-toggle').click()
+ page.locator('[data-palette-option="CatppuccinMocha"]').click()
+ expect(page.locator('html')).to_have_attribute('data-theme', 'dark')
+ expect(page.locator('html')).to_have_attribute('data-palette', 'CatppuccinMocha')
+ page.reload()
+ expect(page.locator('html')).to_have_attribute('data-theme', 'dark')
+ expect(page.locator('html')).to_have_attribute('data-palette', 'CatppuccinMocha')
+ dark_background = page.locator('.code-block').first.evaluate('el => getComputedStyle(el).backgroundColor')
+ assert all(int(channel) < 128 for channel in __import__('re').findall(r'\d+', dark_background)[:3])
+ page.screenshot(path=str(output / 'docs-dark.png'), full_page=True)
+ page.locator('figure button').first.click()
+ expect(page.locator('#image-dialog')).to_be_visible()
+ page.keyboard.press('Escape')
+ expect(page.locator('#image-dialog')).not_to_be_visible()
+ page.set_viewport_size({'width': 390, 'height': 844})
+ page.goto(base)
+ page.locator('#theme-toggle').click()
+ page.locator('[data-palette-option="Nord"]').click()
+ page.wait_for_timeout(650)
+ assert not page.evaluate('document.documentElement.scrollWidth > innerWidth')
+ page.screenshot(path=str(output / 'docs-mobile.png'), full_page=True)
+ page.locator('#menu-toggle').click()
+ expect(page.locator('#menu-toggle')).to_have_attribute('aria-expanded', 'true')
+ page.keyboard.press('Escape')
+ expect(page.locator('#menu-toggle')).to_have_attribute('aria-expanded', 'false')
+ manifest = json.loads((Path(__file__).parent / 'site.json').read_text())
+ pages = {item['slug']: item for group in manifest['groups'] for item in group['pages']}
+ for slug in ('completions', 'backups', 'mobile'):
+ page.goto(base + slug + '/index.html')
+ version = pages[slug].get('version', manifest['version'])
+ commit = pages[slug].get('source_commit', manifest['source_commit'])
+ expect(page.locator('.article-footer')).to_contain_text(version)
+ page.locator('.source-details summary').click()
+ expect(page.locator('.source-details a').first).to_have_attribute(
+ 'href', __import__('re').compile(f"/blob/{commit}/"))
+ assert not page.evaluate('document.documentElement.scrollWidth > innerWidth')
+ page.screenshot(path=str(output / f'docs-{slug}-mobile.png'), full_page=True)
+ page.goto(base)
+ page.emulate_media(reduced_motion='reduce')
+ assert page.locator('.hero').evaluate("el => getComputedStyle(el).animationName") == 'none'
+ nojs = browser.new_context(java_script_enabled=False, viewport={'width': 390, 'height': 844})
+ fallback = nojs.new_page()
+ fallback.goto(base)
+ expect(fallback.locator('#sidebar')).to_be_visible()
+ fallback.get_by_role('link', name='快速开始', exact=True).first.click()
+ expect(fallback.locator('h1')).to_have_text('快速开始')
+ nojs.close()
+ browser.close()
+ finally:
+ server.shutdown()
+ server.server_close()
+ assert not errors, errors
+ (output / 'browser-result.json').write_text(json.dumps({'passed': True, 'page_errors': errors}, indent=2))
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser()
+ parser.add_argument('--site', type=Path, default=Path(__file__).parent / 'dist')
+ parser.add_argument('--output', type=Path, default=Path('docs-browser-results'))
+ args = parser.parse_args()
+ check(args.site, args.output)
diff --git a/docs/site/content/agent-worktrees.md b/docs/site/content/agent-worktrees.md
new file mode 100644
index 000000000..72b95ace1
--- /dev/null
+++ b/docs/site/content/agent-worktrees.md
@@ -0,0 +1,61 @@
+## 为并行任务使用不同目录
+
+两个 AI 工具同时修改同一目录,可能覆盖对方的文件。Git worktree 可以让它们使用同一仓库的不同工作目录与分支。
+
+开始前保存当前文件,在源项目中运行 `git status`。先提交或妥善保存未提交改动,再创建新的工作目录。
+
+## 使用 Pebrel 创建命名 Agent
+
+在本地 Pebrel 终端中运行:
+
+```sh
+pebrel pane list
+pebrel ctl describe --pretty
+```
+
+确认源窗格的 ID、所属窗口及当前运行时支持的 Agent 能力。假设窗口为 `1`、源窗格为 `17`,且 Codex 已安装:
+
+```sh
+pebrel ctl agent-fork --window 1 --source-pane 17 --name docs-review --kind codex --pretty
+```
+
+把数字换成自己的列表结果。成功后,响应会给出创建的 worktree 和 Agent 信息,终端将在新目录中启动相应工具。
+
+默认分支形如 `pebrel/docs-review`,工作目录位于主仓库旁的 `<仓库名>-worktrees/docs-review`。同名分支或目录已经存在时,改用新的任务名称,或先确认旧任务已不再使用。
+
+## 核对目录再发任务
+
+读取新 Agent:
+
+```sh
+pebrel ctl agent-get --agent docs-review --pretty
+```
+
+检查返回的目录与分支,再发送一项任务:
+
+```sh
+pebrel agent send docs-review "检查安装文档中的路径示例,列出需要修改的位置" --wait
+pebrel agent read docs-review --lines 80
+```
+
+任务完成后,进入这个 worktree 查看 `git diff`并运行相关检查。再按项目的 Git 工作流程提交和合并。
+
+## 只需要手动建立 worktree
+
+也可以使用 Git 自带命令。在源仓库目录中运行下面的示例,再新建终端进入新目录:
+
+```sh
+git worktree add ../my-project-docs -b docs/review
+```
+
+该命令会创建一个新分支和目录。检查成功后,在新终端中进入 `../my-project-docs`,启动已安装的 AI CLI。
+
+## SSH 上的项目
+
+Pebrel 的本机 Agent worktree 创建入口不替远端 SSH 会话建立工作目录。需要在服务器上隔离任务时,在服务器终端中使用它的 Git 命令,并选择服务器可写路径。
+
+## 完成后清理
+
+确认所有修改已提交或保存,并退出使用该目录的工具。先运行 `git worktree list`核对目录,再用 `git worktree remove 实际目录`移除不再使用的工作副本。
+
+不要直接删除仍有未提交改动的目录。对话分叉只复制会话上下文,需要文件隔离时仍按本页建立 worktree。
diff --git a/docs/site/content/agents.md b/docs/site/content/agents.md
new file mode 100644
index 000000000..eaf7679c3
--- /dev/null
+++ b/docs/site/content/agents.md
@@ -0,0 +1,116 @@
+> [!NOTE]
+> 本页按 Pebrel 2.1.1 核对。支持范围会随版本变化;如果你安装的版本较旧,设置 → Agents 里列出的工具可能比这里少,请以自己版本的界面为准。
+
+## Pebrel 如何对待 AI 命令行工具
+
+Claude Code、Codex 这类工具本质上是运行在终端里的程序,所以任何 CLI 或 TUI 都能在 Pebrel 里正常使用,不需要先"被支持"。Pebrel 做的是在此之上多走一步:认出你正在运行的是哪一个工具,再给它配上图标、任务状态、通知和对话接续。
+
+这些能力分三层,工具支持到哪一层,你能得到的体验就到哪一层:
+
+| 层级 | 你会得到什么 | 需要你做什么 |
+| --- | --- | --- |
+| **识别** | Pebrel 认出工具名称,可显示专属图标 | 不需要,直接运行即可 |
+| **屏幕识别** | 在识别的基础上,Pebrel 根据终端画面判断工具是在工作,还是在等你确认 | 不需要 |
+| **Agent 集成** | 工具自己把"开始、完成、需要你处理"等事件告诉 Pebrel,状态和通知最准确;还能记住会话,用于恢复与分叉 | Claude Code 和 Codex 默认已开启;其他工具在 **设置 → Agents** 里打开一次 |
+
+Agent 集成最准确,但并不是所有工具都提供可用的事件接口。没有集成的工具,依然可以靠屏幕识别获得不错的状态提示,只是在工具改了界面措辞之后,判断可能暂时不准。
+
+## 支持 Agent 集成的工具
+
+**设置 → Agents** 页面里列出的就是下面这 9 个工具,在 Windows、macOS 和 Linux 上都可以使用。Claude Code 和 Codex 默认开启,其余的需要自己打开开关;开启后要退出并重新启动对应的工具才会生效,步骤见[配置 Agent 集成](hooks.md)。
+
+服务器上的工具也可以使用:通过 Pebrel 的 SSH 连接时,会自动为服务器上的 Claude Code、Codex、OpenCode 和 Pi 配置集成。WSL 里则支持 Claude Code 和 Codex。
+
+| 工具 | 启动命令 | 专属图标 | 恢复对话 | 分叉对话 |
+| --- | --- | :---: | :---: | :---: |
+| Claude Code | `claude` | ✓ | ✓ | ✓ |
+| Codex | `codex` | ✓ | ✓ | ✓ |
+| OpenCode | `opencode` | ✓ | ✓ | ✓ |
+| Cursor Agent | `agent`、`cursor-agent` | — | ✓ | — |
+| Kimi Code | `kimi` | ✓ | ✓ | ✓ |
+| Pi | `pi` | ✓ | ✓ | ✓ |
+| Oh My Pi | `omp` | ✓ | ✓ | ✓ |
+| GitHub Copilot | `copilot` | — | ✓ | — |
+| Grok | `grok` | ✓ | ✓ | ✓ |
+
+几点说明:
+
+- Cursor Agent 的命令是 `agent`,不是 Cursor 桌面编辑器的 `cursor`。只安装了桌面编辑器时,设置里不会把 Cursor Agent 显示为已安装。
+- 没有专属图标的工具会用字体图标代替:Gemini、Cursor Agent 和 GitHub Copilot 各有自己的图案,其余工具显示通用图标。这不影响状态提示。
+- "恢复"指重新打开 Pebrel 后接回原来的对话,或在 [AI 会话历史](ai-history.md) 里重新打开某次对话。"分叉"指从已有对话的上下文开出一个新对话,原对话保持不变。两者都要求 Pebrel 已经知道这次对话的会话标识,而这正是 Agent 集成带来的。
+
+## 通过屏幕识别获得状态提示的工具
+
+下面这些工具目前没有 Agent 集成入口,但 Pebrel 能认出它们,并根据画面判断工作中或等待确认。
+
+| 工具 | 启动命令 | 专属图标 |
+| --- | --- | :---: |
+| Gemini CLI | `gemini` | — |
+| Amp | `amp` | — |
+| Antigravity | `agy`、`antigravity` | ✓ |
+| Cline | `cline` | — |
+| Devin | `devin` | — |
+| Droid | `droid` | — |
+| Hermes | `hermes` | — |
+| Kiro | `kiro`、`kiro-cli` | — |
+| Kilo Code | `kilo` | — |
+| Qoder | `qodercli` | — |
+| Maki | `maki` | — |
+| CodeBuddy Code | `codebuddy`、`cbc` | ✓ |
+
+这一档的工具不在 Pebrel 里恢复或分叉对话。需要接续时,使用工具自己的恢复命令即可,例如 `gemini --resume`。
+
+## 目前只做识别的工具
+
+下面这些工具能被认出,但暂时没有屏幕识别规则,也没有集成。任务状态提示比较有限,需要你自己回到窗格查看。
+
+| 工具 | 启动命令 | 专属图标 |
+| --- | --- | :---: |
+| Aider | `aider` | — |
+| Goose | `goose` | — |
+| Auggie | `auggie` | — |
+| Vibe | `vibe` | — |
+| Qwen Code | `qwen` | — |
+| Trae CLI | `trae-cli` | ✓ |
+
+## 通过 `npx` 等启动器运行也能识别
+
+Pebrel 不只看命令的第一个词。通过 `node`、`npx`、`bunx`、`uvx`、`pipx` 等启动器运行的工具,以及在 WSL 里运行的工具,同样会被认出。
+
+如果工具没有被认出,先在同一个终端里确认命令能直接运行,再看[配置 Agent 集成](hooks.md)中的排查步骤。
+
+## 名单之外的工具
+
+不在上面名单里的 CLI 或 TUI,仍然可以在 Pebrel 里正常运行,只是没有专属图标、任务状态和对话接续,终端本身的所有功能不受影响。
+
+## 接下来的方向
+
+下面是目前的开发方向,不是发布时间的承诺,具体以各版本的发布说明为准:
+
+- **补齐集成。** 优先为使用广泛、并且官方提供稳定事件接口的工具增加 Agent 集成,让它们从"屏幕识别"升级到最准确的一档。
+- **扩大恢复和分叉的范围。** 只在工具的官方命令经过核对之后才会加入。Pebrel 不会按名字猜测命令,以免把内容输入到错误的位置。
+- **识别更多工具。** 新工具会根据使用情况和启动方式是否稳定来评估。
+
+希望支持某个工具,可以在项目的 Issue 里说明工具名称、启动命令和官方文档链接,流程见[参与贡献](contributing.md)。
+
+## 常见问题
+
+### 状态没有更新,或图标没有出现
+
+先确认命令在同一个终端里能直接运行,再刷新 **设置 → Agents**。已经启用集成的工具,重启一次工具后再试。工具刚升级过时,重新启动 Pebrel 和工具可以清掉旧的识别状态。
+
+### 在标签上怎么看状态
+
+工作中的标签会显示转动的进度标记。工具停下来等你输入或授权时,标签会改为相应的提示。任务完成时,标签先短暂显示对勾,再变成一个小圆点,提醒你回去查看;正在查看的标签不会显示这个小圆点。详见[使用 AI 命令行工具](ai-start.md)。
+
+### 通知来自哪个窗格
+
+通知会指向发出事件的窗格。多个工具同时运行时,请按窗格上的图标和名称区分,通知方式见[通知](notifications.md)。
+
+### 设置里没有我的工具
+
+**设置 → Agents** 只列出有 Agent 集成的 9 个工具。其他工具没有开关,但仍会被识别,并显示图标和状态提示。
+
+### 恢复或分叉没有出现
+
+先看工具是否在上面"支持 Agent 集成"的表里且有 ✓,再检查集成是否已启用并重启过工具。SSH 标签和自定义 Profile 里不会显示分叉入口,详情见[恢复与分叉 AI 对话](ai-history.md)。
diff --git a/docs/site/content/ai-history.md b/docs/site/content/ai-history.md
new file mode 100644
index 000000000..1fbd8ccc9
--- /dev/null
+++ b/docs/site/content/ai-history.md
@@ -0,0 +1,54 @@
+## 找到之前的对话
+
+按 **Ctrl+Shift+O**(macOS 为 **⌘⇧O**)打开快速跳转,输入会话标题、项目目录或相关关键字。列表按工具分组,同一次对话可能列出两种操作:**恢复**会接回原对话,**分叉**(仅部分工具提供)会从原对话的上下文开出新对话。每一行会显示工具名称、位置和时间,先核对工具类型和目录,再选择。
+
+Pebrel 会尝试使用工具的会话记录打开对话。CLI 出现后,确认上下文确实属于原任务,再输入新的问题。
+
+历史列表会读取 Claude Code 和 Codex 自己保存的会话记录;其他已启用 Agent 集成的工具,会在它们上报会话之后出现在列表里。没有集成的工具,请通过工具自己的恢复入口打开。各工具是否支持恢复与分叉,见[支持的 AI 命令行工具](agents.md)。
+
+## 每次启动时自动接续
+
+在 **设置 → 高级 → 会话生命周期**开启:
+
+- **启动时恢复上次标签**;
+- **恢复时接续 AI 对话**。
+
+正常退出后重开 Pebrel,检查对应终端是否恢复了原对话。需要原会话记录、有效的身份信息,以及可用的 CLI 安装。
+
+关闭 Pebrel 时,如果还有 AI 对话没有取得身份信息,会弹出"仍有 AI 会话未能识别,继续关闭?"。选择 **保存已知状态并关闭** 会保存布局和已知的对话;没取得身份的对话,下次打开时可能需要手动选择。刚启动的工具需要一点时间取得身份,等它们启动完成后再关闭,可以避免这个提示。
+
+能否自动接回,取决于工具是否在[支持列表](agents.md)里有"恢复对话"的 ✓。
+
+## 恢复失败或需要选择会话
+
+原对话没能接上时,Pebrel 会保留原来的恢复记录,不会丢掉。右键相关终端标签,使用当前可用的 **重试会话恢复** 或 **选择要继续的对话…**。
+
+先检查项目目录是否仍存在、CLI 是否需要重新登录,以及原工具的历史记录是否还在。记录不足时,可以打开工具自己的历史选择器查找;Pebrel 列表没有显示某条记录,并不意味着工具已经删除它。
+
+## 从已有上下文分出新对话
+
+在受支持的本地会话中,右键标签选择 **分叉 AI 会话**;也可以在历史列表里,对某次旧对话选择 **分叉**。目前 Claude Code、Codex、OpenCode、Kimi Code、Pi、Oh My Pi 和 Grok 可以分叉。新会话从已有上下文开始,原对话继续保留。
+
+这个入口要求 Pebrel 已识别工具和会话身份;SSH、自定义 Profile 或身份信息不完整时可能不显示。需要分叉时,先在受支持的本地 Shell 中建立会话。
+
+对话分叉沿用上下文,但不会自动给代码建立独立工作目录。准备并行修改文件时,使用[Git worktree](agent-worktrees.md)。
+
+## 使用已知会话 ID
+
+已经从工具取得有效 ID 时,也可以在相应环境中运行它的恢复命令。将 `SESSION_ID`换成真实值:
+
+```sh
+claude --resume SESSION_ID
+```
+
+或:
+
+```sh
+codex resume SESSION_ID
+```
+
+安装的 CLI 版本需要支持相应命令。CLI 报参数错误时,先查看该版本的帮助,而不是反复尝试同一命令。
+
+## 备份对话
+
+保存 Pebrel 布局或主机列表不会同时备份所有 CLI 的对话正文。换电脑或清理历史前,按工具自己的方式备份会话记录,并保留对应项目目录。
diff --git a/docs/site/content/ai-start.md b/docs/site/content/ai-start.md
new file mode 100644
index 000000000..93194f7b8
--- /dev/null
+++ b/docs/site/content/ai-start.md
@@ -0,0 +1,43 @@
+## 在项目目录启动工具
+
+先按所用 CLI 的官方说明安装并登录。Claude Code、Codex 等工具分别管理自己的账户与网络连接,Pebrel 提供运行它们的终端。Pebrel 目前能识别的工具见[支持的 AI 命令行工具](agents.md)。
+
+1. 打开本地、WSL 或 SSH 终端。
+2. 用 `cd`进入准备处理的项目。
+3. 输入已安装的工具命令,例如 `claude`或 `codex`。
+4. 按工具提示完成登录和目录信任确认。
+5. 输入第一项任务,例如“介绍这个项目的目录结构,先不要修改文件”。
+
+命令找不到时,在同一环境中检查安装。Windows 中安装的 CLI,不会自动变成 WSL 或服务器中的 Linux 程序。
+
+
为不同任务使用独立窗格,可以同时查看各工具的输出。
+
+## 查看活动状态
+
+Pebrel 会给识别到的 AI CLI 显示工具图标和活动状态:标签和窗格标题上有工具图标,工作中的标签会转动,任务完成后先显示对勾,再变成小圆点。运行任务时可以切到其他标签,通过状态提示判断何时需要回来查看。
+
+在 **设置 → Agents** 启用支持的集成,可以获得更准确的任务事件。哪些工具能被识别、各自有哪些功能,见[支持的 AI 命令行工具](agents.md);配置方式见[Agent 集成](hooks.md)。
+
+出现需要权限、回答或确认的提示时,回到来源窗格阅读具体请求。任务回到空闲后,仍应查看工具输出和实际改动,确认结果符合需求。
+
+## 将报错或截图加入对话
+
+从终端选择报错文字,右键使用 **发送到聊天**,补充问题并选择目标工具。这样无需手动整理全部日志,见[发送到聊天](send-to-chat.md)。
+
+工具支持图片输入时,复制截图并在其窗格中粘贴。Pebrel 会保存或上传图片并插入路径,随后按 CLI 的方式提交,见[图片](images.md)。
+
+## 阅读较长的回答
+
+可以直接在 CLI 中滚动和复制回答。需要按标题阅读长结果时,将回答保存为本地 `.md`文件,再从文件树打开,使用[文档阅读器](documents.md)的目录、代码复制和公式排版。
+
+这套方式也适用于暂时没有集成事件的工具:保留原始 Markdown 内容,就能在文档标签中阅读。
+
+## 同时处理多个任务
+
+为不同任务新建窗格,先进入各自的项目目录,再启动 CLI。需要并行修改同一个 Git 仓库时,用独立 worktree 隔离文件,避免两个工具同时覆盖同一路径,见[隔离 AI 工作目录](agent-worktrees.md)。
+
+每项任务结束后,查看版本控制面板中的 diff,运行相应测试,再决定是否提交。
+
+## 退出后继续对话
+
+用工具自己的退出方式结束会话。之后从[AI 会话历史](ai-history.md)查找;希望启动 Pebrel 时自动接续,可开启 **启动时恢复上次标签**和 **恢复时接续 AI 对话**。
diff --git a/docs/site/content/appearance.md b/docs/site/content/appearance.md
new file mode 100644
index 000000000..8cb4cc5a0
--- /dev/null
+++ b/docs/site/content/appearance.md
@@ -0,0 +1,35 @@
+## 更换主题
+
+打开 **设置 → 外观**,点击 **更换主题**。浏览或搜索主题,选择喜欢的配色,回到终端查看实际效果。
+
+希望随系统切换深浅色时,开启 **跟随系统**,深色使用 Nord,浅色使用 Nord Light。希望始终使用固定配色时,关闭它,再选择主题。主题列表里的 Warm Sand、Slate Light 分别是原来的 Paper 与 Glass Light,旧配置中的名称仍然有效。
+
+
选择主题后,可继续调整终端字体、光标和背景。
+
+## 调整界面大小
+
+在 **外观 → 界面**中,**界面字号**用于设置侧栏、按钮和菜单的文字大小,**界面外观**用于选择“标准”或“紧凑”的留白,切换后标题栏、侧栏和顶部标签的间距立即改变。侧栏的分隔线默认就可以拖动调整宽度。
+
+终端输出太小时,调整 **终端字号**。希望一屏显示更多内容但仍容易阅读,可以先调整终端字号和字体间距,再决定是否缩小整个界面。
+
+## 更换应用图标
+
+点击 **更换图标**,查看并选择图标配色。图标与主题分别保存,切换终端主题不会强制改变图标。
+
+应用内已经改变,但任务栏、Dock 或系统文件管理器仍显示旧图标时,可以退出并重开应用;系统图标缓存的刷新可能较晚。
+
+## 更容易看清当前窗格
+
+在外观的界面选项中开启非活动窗格调暗,让当前输入位置更明显。使用多个本地和 SSH 窗格时,可以结合[标签颜色与重命名](workspace.md)区分环境。
+
+在 **光标**分组中选择条形、下划线、实心框或空心框。关闭 **光标闪烁**后,光标保持常亮。**平滑光标**可选 **关闭** 或 **平滑(90 ms)**,开启后输入和移动时光标会平滑滑动,大范围跳转仍立即到位,设置立即应用到已打开的终端。
+
+## 标签关闭按钮与界面语言
+
+**显示标签关闭按钮**控制标签上的关闭入口。关闭显示后,仍可使用鼠标中键、右键菜单或关闭快捷键。
+
+在 **语言**选项中选择界面语言。终端程序的输出由各自的环境设置决定;未翻译的界面文字可能使用英文。
+
+## 进一步定制
+
+需要改文字颜色、ANSI 调色板或行高,见[创建和导入主题](themes.md)。需要调整中英文字体和连字,见[字体](fonts.md)。使用壁纸、透明度或窗口材质,见[背景](backgrounds.md)。
diff --git a/docs/site/content/backgrounds.md b/docs/site/content/backgrounds.md
new file mode 100644
index 000000000..a9f580430
--- /dev/null
+++ b/docs/site/content/backgrounds.md
@@ -0,0 +1,38 @@
+## 设置一张背景图片
+
+1. 打开 **设置 → 外观 → 自定义背景**。
+2. 在 **背景图片**中选择本机图片文件。
+3. 设置 **背景图像拉伸模式**和 **背景图像对齐**。
+4. 调低 **背景图像不透明度**,让文字不被图片干扰。
+5. 回到终端检查普通输出、彩色输出和选区的清晰度。
+
+图片默认位于终端文字后方。要将图片延伸到标题栏和侧栏,开启相应的覆盖选项,并阅读确认提示。
+
+## 选择铺放方式
+
+| 模式 | 效果 | 适合的情况 |
+| --- | --- | --- |
+| **拉伸** | 铺满区域,可能改变图片比例 | 纹理或不怕变形的图案 |
+| **适应** | 保持比例,完整显示,可能留空 | 希望看见整张图片 |
+| **填充** | 保持比例铺满,可能裁剪边缘 | 壁纸铺满终端 |
+| **原始尺寸** | 不缩放图片 | 按原图尺寸放置 |
+
+主体被裁掉时,在九个对齐位置中选择顶部、左侧、居中等位置,再调整窗口大小查看结果。
+
+## 调整图片与终端透明度
+
+**背景图像不透明度**越低,图片越淡。**终端正文不透明度**控制终端背景整体的不透明程度,100% 为完全不透明。
+
+两者可以分别调整。例如,希望有一张浅淡壁纸、但不透出桌面,可以降低图片不透明度,同时把终端正文不透明度保持为 100%。设置页本身不会按终端正文透明度变化。
+
+## 选择背景模糊
+
+在 **外观 → 界面 → 背景模糊**中选择当前平台可用的窗口效果。Mica、Aero 和 Acrylic 等效果依赖 Windows 与系统环境,不同系统不会呈现完全相同的材质。
+
+出现闪烁、文字难读或窗口拖动不流畅时,先选择“无”并提高不透明度,再逐项恢复效果。
+
+## 更换或移除图片
+
+重新选择其他图片可以替换背景;需要回到纯色效果时,点击 **背景图片**行的重置按钮移除图片,再选择主题背景色。
+
+图片被移动、所在磁盘未挂载或路径失效时,重新选择可读取的文件。迁移到另一台电脑时,把图片素材单独复制过去,并更新路径。
diff --git a/docs/site/content/backups.md b/docs/site/content/backups.md
new file mode 100644
index 000000000..2aa4441f7
--- /dev/null
+++ b/docs/site/content/backups.md
@@ -0,0 +1,68 @@
+> [!NOTE]
+> 本页按 Pebrel 2.1.1 核对,**设置 → 备份** 从 2.0 起提供。没有这个入口时,先[更新](updates.md)到 2.0 之后的版本,或使用[备份与迁移](migration.md)中的手动方式。
+
+## 先做一份本地加密备份
+
+1. 准备一个已有文件夹,例如 U 盘、已挂载的 NAS 或自己的备份目录。
+2. 打开 **设置 → 备份**,在 **备份与恢复** 页面选择 **本地 / 网络目录**,点 **下一步**。
+3. 在 **目录** 中填写路径,或用 **浏览…** 选择文件夹,点 **检查连接并继续**。
+4. 设置至少 8 位的 **备份密码**,在 **再输入一次** 中确认,点 **下一步**。
+5. 勾选需要的内容,点 **完成并开始备份**。只想先保存配置时,选 **完成,稍后备份**。
+6. 等待完成提示,并确认页面出现备份记录;以后使用 **立即备份 → 开始备份** 再生成快照。
+
+连接检查只列出已有备份,不写入文件。因此“连接正常”不等于已经成功写入备份,仍需完成第 6 步。
+
+**备份密码与存储服务的登录密码是两回事。** Pebrel 只在本次运行的内存中保留备份密码,下次启动后需要重新输入。恢复时必须使用创建那份备份时的密码;忘记密码就无法解开已有备份,请单独妥善保管。
+
+## 选择要带走的内容
+
+默认推荐外观、终端设置、助手设置、SSH 主机和工作区会话。还可以按需选择同步设置、自定义字体、目录历史和命令历史;每次备份前都能调整,至少选择一项。
+
+- **工作区会话**是窗口、标签和分屏布局,不是正在运行的进程或 AI CLI 对话正文
+- **SSH 主机**包含连接配置,不包含 SSH 私钥,也不会复制系统凭据管理器中的密码或 API Key
+- **目录历史**可能包含项目路径;**命令历史**可能包含曾经粘贴的令牌,分享或上传前应检查是否真的需要
+- **自定义字体**会增加备份大小;外部项目文件和各 AI CLI 自己的数据仍需另外备份
+
+加密并不等于脱敏。自己写进配置或命令中的秘密仍需检查,不要把备份文件和它的密码一起公开。
+
+## 导出文件,迁移到另一台电脑
+
+在备份页的 **文件** 区域选择 **导出备份文件**,选择内容和保存位置,生成 `.pebrel-backup` 文件。首次配置向导也提供导出入口,因此只做一次离线备份不必配置云存储。
+
+把文件安全地复制到新电脑,并准备创建该文件时使用的备份密码。
+
+如果新电脑还停在首次配置向导,先按上面的步骤配置一个已有本地文件夹,选择 **完成,稍后备份**。当前界面的导入入口位于配置完成后的页面,不需要为导入额外开通远程存储。
+
+## 只恢复需要的部分
+
+1. 从已有快照选择恢复,或在 **文件 → 导入备份文件 → 选择文件…** 中打开 `.pebrel-backup`。
+2. 按提示输入该备份的密码并点 **解开**;如果本次运行已有可用密码,可能直接显示内容。
+3. 检查内容清单,只勾选需要恢复的项目,再确认恢复。
+4. 检查外观、主机和配置,新建终端验证 Shell 与路径;跨系统迁移还需修正旧电脑的路径。
+
+**恢复会覆盖本机对应的设置,未勾选的内容不变。** 开始前 Pebrel 会把当前相关文件加密保存为恢复点;恢复完成后可在当前设置页面使用 **撤回**。需要撤回时应先执行并确认结果,不要假设关闭设置页或重启后仍保留同一个撤回入口。
+
+SSH 私钥、系统凭据、Shell 和 CLI 安装不会由布局备份恢复,需要在新电脑另外准备。完整迁移检查见[备份与迁移](migration.md)。
+
+## 使用远程存储
+
+存储向导还支持 WebDAV、S3 兼容存储与 SFTP。准备自己的服务地址和权限,按页面要求填写,再检查连接:
+
+- **WebDAV**:使用已有目录的完整 HTTPS 地址;服务要求应用专用密码时,不要填普通登录密码
+- **S3**:填写服务提供的端点、存储桶、区域和访问凭据
+- **SFTP**:选择已经保存的 SSH 主机和已有远程目录,沿用该主机的认证配置
+- **本地 / 网络目录**:使用已经挂载的目录;选择同步盘时,文件的后续云同步由该同步客户端处理
+
+WebDAV / S3 的凭据管理器保存目前仅在 Windows 实现。macOS / Linux 需要在启动 Pebrel 的环境中提供 `PEBREL_BACKUP_WEBDAV_PASSWORD` 或 `PEBREL_BACKUP_S3_SECRET`,并将界面的存储密码输入留空。不要把实际秘密写进公开脚本或截图;不方便配置启动环境时,先使用本地文件夹或离线导出。
+
+存储位置按最近 10 份快照保留,成功上传后会尝试清理更旧的快照;清理失败会显示提示,不等于这次上传失败。需要长期保存的一份应另外导出保管。更改存储位置后,页面只列出新位置中的备份,旧位置的备份不会随切换而删除。
+
+## 常见问题
+
+| 现象 | 下一步 |
+| --- | --- |
+| 解不开备份 | 确认使用的是这份备份的加密密码,而不是网盘或 SSH 密码 |
+| 检查连接通过但备份失败 | 核对目录写权限、空间及实际错误;只读连接检查不能证明上传成功 |
+| 找不到导入按钮 | 首次向导先完成本地目录配置,再到文件区域导入 |
+| 新电脑的 SSH 仍无法登录 | 重新配置私钥和系统凭据,检查用户名和服务器授权 |
+| 恢复后程序或项目路径失效 | 修正跨电脑、跨系统路径,再新建终端验证 |
diff --git a/docs/site/content/broadcast.md b/docs/site/content/broadcast.md
new file mode 100644
index 000000000..597cefa88
--- /dev/null
+++ b/docs/site/content/broadcast.md
@@ -0,0 +1,28 @@
+## 同时向多个窗格输入
+
+广播输入适合在多个终端中执行相同的查询,例如同时检查几台测试服务器的系统版本。开启后,同一终端标签页里的多个窗格会接收相同的键盘输入。
+
+## 开启广播
+
+1. 在一个标签页中建立至少两个终端窗格。
+2. 分别连接需要的主机,或切换到准备操作的目录。
+3. 检查每个窗格都停在可以接收命令的位置。
+4. 点击窗格标题栏中的广播输入按钮。
+5. 先输入一条无副作用的测试命令,例如 `echo broadcast-test`,确认各窗格都收到了它。
+
+之后输入的字符和提交操作会同步到该标签的窗格。其他标签页不属于这次广播范围。
+
+## 只在一个窗格继续操作
+
+再次点击广播按钮,将其关闭。检查广播状态已取消后,再输入只针对一台主机的命令。
+
+切换焦点只是更换当前窗格;需要结束同步输入时,应明确关闭广播,而不是只点击另一个窗格。
+
+> [!WARNING]
+> 广播开启时,输入密码、删除命令或生产环境操作可能同时发送给多个会话。开始单独认证、使用交互式菜单或处理不同环境前,先关闭广播。
+
+## 图片粘贴
+
+图片粘贴需要为目标环境保存或上传文件,不会按普通文本广播给所有窗格。需要给某个 AI 工具提供图片时,关闭广播,聚焦该工具所在窗格后单独粘贴。
+
+广播中的某个程序已经退出或进入其他输入状态时,也先暂停广播,分别整理各窗格,再继续操作。
diff --git a/docs/site/content/clipboard.md b/docs/site/content/clipboard.md
new file mode 100644
index 000000000..6acff324a
--- /dev/null
+++ b/docs/site/content/clipboard.md
@@ -0,0 +1,42 @@
+## 选择终端输出
+
+拖动鼠标选择一段文字;双击可选择一个词,三击可选择一行。按住 **Shift** 可以扩展已有选区。
+
+Vim 等程序可能接管鼠标。需要复制它显示的文字时,按住 **Shift** 再拖动,使用终端自身的选区。
+
+## 复制和粘贴文字
+
+| 操作 | Windows / Linux | macOS |
+| --- | --- | --- |
+| 复制选区 | Ctrl+Shift+C | ⌘C |
+| 粘贴剪贴板 | Ctrl+V 或 Ctrl+Shift+V | ⌘V |
+
+Windows / Linux 中,Ctrl+C 在存在选区时也会复制文字;没有选区时,它用于中断正在运行的程序。
+
+粘贴前点击目标窗格。准备把命令发到服务器时,先确认焦点确实在对应 SSH 终端。
+
+## 选中即复制和右键粘贴
+
+打开 **设置 → 交互 → 鼠标与选区**,开启 **选中即复制**。之后鼠标选择结束时会复制选区,右键可以粘贴。需要使用常规右键菜单时,将这项设置关闭,右键会打开菜单,里面有复制、粘贴、复制工作目录、左右分屏、上下分屏和关闭此分栏;选中了文字并且有可用的 AI 窗格时,还会出现发送到聊天。无论这项设置是否开启,按住 **Ctrl** 再右键都可以打开这个菜单,同时不影响程序自己接收鼠标事件。
+
+这个选项适合频繁从日志中复制文字;如果经常需要右键选择其他动作,保留默认交互会更方便。
+
+## 粘贴多行命令
+
+在 **设置 → 交互**开启 **粘贴前确认**。在普通 Shell 中粘贴多行或高风险内容时,检查确认框里的文本,再决定是否继续。
+
+确认时留意三个位置:当前主机、当前目录,以及命令是否包含删除、提权或覆盖操作。多行文本送入 Shell 后,换行可能触发执行。
+
+全屏程序和使用 bracketed paste 的程序会按各自的粘贴方式处理输入;不要把确认框当成所有应用都必定显示的步骤。
+
+## 粘贴图片
+
+复制一张图片后,在目标终端执行粘贴。Pebrel 会将图片保存为 PNG,再插入对应文件路径。检查输入区中的路径,按正在使用的工具要求提交。
+
+在 WSL 或 SSH 中,路径需要指向该环境可访问的图片。SSH 传图依赖远端连接和传输成功;失败时先处理提示,再重试。图片是否显示为附件缩略图由接收的 CLI 决定。
+
+关于图片预览、终端内嵌图像及清理缓存,见[图片](images.md)。
+
+## 将输出交给 AI
+
+选择报错或日志,右键打开 **发送到聊天**,再选择目标 AI 窗格。这样可以直接携带选中的输出继续提问。具体示例见[发送到聊天](send-to-chat.md)。
diff --git a/docs/site/content/commands.md b/docs/site/content/commands.md
new file mode 100644
index 000000000..ea43df9eb
--- /dev/null
+++ b/docs/site/content/commands.md
@@ -0,0 +1,47 @@
+## 打开保存命令
+
+点击工作区顶栏的**闪电图标**打开命令管理器。先点击准备接收命令的终端窗格,再打开管理器;选中的条目会发送到这个终端。
+
+搜索框可以查找命令名称或命令文字。列表同时提供内置条目和你自己保存的条目。
+
+## 保存第一条命令
+
+例如,把检查 Git 工作区状态的命令保存下来:
+
+1. 点击 **新增命令**。
+2. **名称**填写“查看项目改动”。
+3. **命令**填写 `git status --short`。
+4. 暂时不勾选 **插入后立即按 Enter 执行**。
+5. 点击 **保存**。
+
+回到一个 Git 项目的终端,再次打开管理器并选择这条命令。文字会插入输入区,你可以先检查目录,再按 Enter 执行。
+
+## 插入文字,还是立即执行
+
+| 使用方式 | 适合的条目 |
+| --- | --- |
+| 不勾选立即执行 | 需要补充参数、路径或检查后再运行的命令 |
+| 勾选 **插入后立即按 Enter 执行** | 不需要补充参数的常用命令 |
+
+开启立即执行时,选择条目会同时发送回车。多行条目会将各非空行整理后用 `; ` 连接再执行;需要保留原始换行的脚本,请保存成脚本文件,或关闭立即执行后按目标程序的要求处理。
+
+> [!WARNING]
+> 开启立即执行的命令会在当前终端直接运行。对删除、部署或生产环境命令,建议保留插入后确认的方式。
+
+## 用分组整理命令
+
+点击 **新建分组**并输入名称,例如“项目开发”或“服务器维护”。打开命令条目的菜单,使用 **移到分组**选择目标分组。
+
+进入一个分组后,可以使用 **返回全部命令**查看完整列表。将条目移出分组时选择 **移出分组**。选择 **删除分组,保留其中的命令**只会移除分组,命令仍可在列表中找到。
+
+## 修改内置命令
+
+内置命令提供 Git、Docker、Python 和常见开发工具的示例。要调整其中的参数,打开条目菜单,选择 **保存副本**,然后编辑自己的副本。
+
+内置条目会根据当前终端环境筛选。使用前仍需在这个环境中安装相应工具,例如 Docker 命令需要 Docker 可用。
+
+## 编辑和删除
+
+从自己的命令条目菜单打开 **编辑命令**,修改名称、内容或执行方式后保存。删除不再使用的条目前,确认选中的是自己的那一条。
+
+密码、Token 和临时验证码应在终端或凭据提示中输入,不要长期放进命令条目。迁移命令库时,见[备份与迁移](migration.md)。
diff --git a/docs/site/content/completions.md b/docs/site/content/completions.md
new file mode 100644
index 000000000..031a1fc17
--- /dev/null
+++ b/docs/site/content/completions.md
@@ -0,0 +1,56 @@
+> [!NOTE]
+> 本页按 Pebrel 2.1.1 核对,智能补全从 2.1.0 起提供。1.9.x 的补全样式和接受键与这里不同;如果界面没有三个模式,先在设置中核对版本,不要照着新界面寻找旧版没有的选项。
+
+## 打开命令补全
+
+在 **设置 → 终端 → 补全** 开启 **启用命令补全**,再选择 **补齐模式**。回到普通 Shell 提示符,输入命令或路径的开头。切换模式会立即作用于已经打开的终端。
+
+候选既可以来自已执行的历史命令,也可以来自当前环境,例如 Git 分支、项目脚本和文件路径。第一次输入命令也可能出现建议,不必先运行一遍;这些补齐不需要请求 AI 服务或安装 Shell 补齐插件。
+
+## 选择模式与接受建议
+
+| 模式 | 显示方式 | 如何填入 |
+| --- | --- | --- |
+| **行内补齐** | 建议以灰字接在光标后 | 按 Tab 接受灰字 |
+| **列表补齐** | 随输入显示候选列表 | 上下方向键选择,Tab 填入;没有选中项时 Tab 接受第一项 |
+| **混合补齐** | 默认显示灰字;Tab 展开列表 | 右方向键接受灰字;列表中用上下方向键选择、Enter 填入 |
+
+列表打开时可按 Esc 关闭。混合模式的 Tab 用于打开列表或移动选择,不是直接执行命令。
+
+**接受建议只填入文字,不执行命令。** 检查完整命令、路径和目标主机,再按 Enter 执行。尤其在混合模式里,第一次 Enter 可能只是接受选中的候选,不要连续按键而跳过检查。
+
+当前界面由模式决定按键,不再单独提供“补全接受键”选择。需要完全使用 Shell 自己的补全时,关闭 Pebrel 的 **启用命令补全**。
+
+## 试用不依赖历史的补齐
+
+先进入已有的本地项目目录。在命令末尾保留表中的空格,再输入部分名称。下面是输入前缀,不是要求直接执行的完整命令:
+
+| 输入前缀 | 预期候选 | 没有候选时先确认 |
+| --- | --- | --- |
+| `git switch ` | 当前仓库可用的分支 | 当前目录属于 Git 仓库,且确实有可切换分支 |
+| `npm run ` | 项目 `package.json` 中的脚本名 | 最近的项目清单存在有效的 `scripts` |
+| `ssh ` | SSH config 中可用的主机别名 | 本机 `~/.ssh/config` 中配置了具体的 Host 名称 |
+| `wsl -d ` | 已注册的 WSL 发行版 | 在 Windows 本地 Shell 中输入,且已安装发行版 |
+| `cat ` | 当前目录的文件 | 文件存在,当前 Shell 支持该命令;cmd 可使用 `type ` |
+
+`ssh -F config ` 会使用指定配置文件中的别名;它与 Pebrel 主机库中保存的显示名称不是同一来源。相关设置见 [SSH config](ssh-config.md)。
+
+文件名含空格时,接受后检查引号是否覆盖完整路径。不要把候选中存在某个命令理解为已经安装了该程序;例如补齐 npm 脚本不会替你安装 Node.js,也不会运行脚本。
+
+## 历史补齐与环境边界
+
+运行一次无副作用的 `echo deployment finished`,等提示符返回后输入 `echo dep`,可以检查历史建议。历史补齐是复用已执行的命令;项目补齐则依据当前仍然存在的候选,已经删除的脚本或分支不会仅因出现过而重新成为有效项目候选。
+
+本机 Git、项目脚本、SSH 别名和 WSL 发行版发现用于本地 Shell;不要期待它们读取 SSH 服务器或 WSL 项目中的同名文件。WSL、SSH 的路径建议取决于对应会话的目录查询能力,历史也按环境区分,不应拿宿主机路径来判断远端补齐。
+
+Vim、全屏程序或正在运行的 AI CLI 有自己的按键行为。检查 Pebrel 补齐时,先回到普通 Shell 提示符。
+
+## 排查没有建议或建议不对
+
+1. 确认 **启用命令补全** 已打开,输入位置确实是 Shell 提示符。
+2. 用 `pwd`(cmd 使用 `cd`)确认当前目录;Git 和脚本候选需要对应项目上下文。
+3. 区分本地、WSL 和 SSH 窗格,按上面的环境边界检查候选来源。
+4. 用 `echo` 示例区分历史补齐问题与项目候选问题。
+5. 出现两套重复建议时,关闭 Pebrel 补齐或 Shell 插件中的一套再比较。
+
+反复使用且不适合依赖历史的长命令,可以存入[保存命令](commands.md)。
diff --git a/docs/site/content/config-examples.md b/docs/site/content/config-examples.md
new file mode 100644
index 000000000..c6a212767
--- /dev/null
+++ b/docs/site/content/config-examples.md
@@ -0,0 +1,104 @@
+## 在已有配置中加入示例
+
+以下完整示例可单独用于一份 `pebrel.lua`。已经有配置时,只复制需要的赋值,并放在已有的 `return config`之前,不要重复创建多份配置对象。
+
+修改后运行 `pebrel config check`。字段检查通过后,再新建终端验证启动相关设置。
+
+## 字体、背景与回滚历史
+
+```lua
+local pebrel = require 'pebrel'
+local config = pebrel.config_builder()
+
+config.font = {
+ normal = { family = 'Maple Mono NF CN', style = 'Regular' },
+ size = 13.0,
+}
+config.window = {
+ opacity = 0.96,
+ padding = { x = 8, y = 8 },
+}
+config.scrolling = { history = 10000 }
+
+return config
+```
+
+将字体名称改为当前电脑可用的字体。不透明度范围为 0–1,1 表示完全不透明。GUI 中已有相关偏好时,也检查 **设置 → 外观**是否覆盖了期望效果。
+
+## 不同系统选择不同 Shell
+
+```lua
+local pebrel = require 'pebrel'
+local config = pebrel.config_builder()
+
+if pebrel.platform.os == 'windows' then
+ config.terminal = {
+ shell = { program = 'pwsh.exe', args = { '-NoLogo' } },
+ }
+else
+ config.terminal = { shell = '/bin/bash' }
+end
+
+return config
+```
+
+该例要求 Windows 已安装 PowerShell 7,其他系统存在 `/bin/bash`。程序路径与参数分开填写;需要选择 WSL 或已识别 Shell 时,日常使用可以直接在 **设置 → 终端**中选择。
+
+## 为新终端设置环境变量
+
+```lua
+local pebrel = require 'pebrel'
+local config = pebrel.config_builder()
+
+config.env = {
+ EDITOR = 'nvim',
+ MY_PROJECT_ENV = 'development',
+}
+
+return config
+```
+
+新建终端后,PowerShell 使用 `$env:MY_PROJECT_ENV`,Bash / Zsh 使用 `echo "$MY_PROJECT_ENV"`检查变量。
+
+这些变量适合编辑器和项目标记,不适合写入准备公开分享的密钥或 Token。
+
+## 单独保存配色模块
+
+在主配置旁建立 `theme.lua`:
+
+```lua
+return {
+ primary = {
+ background = '#161616',
+ foreground = '#e8e8e8',
+ },
+}
+```
+
+主文件 `pebrel.lua`:
+
+```lua
+local pebrel = require 'pebrel'
+local config = pebrel.config_builder()
+
+config.colors = require 'theme'
+
+return config
+```
+
+保存任一已加载模块后,查看重载结果。模块名不写 `.lua`后缀,文件位置保持在配置可查找的目录里。
+
+## 清空 Profile 列表
+
+显式空数组使用 `pebrel.array()`:
+
+```lua
+local pebrel = require 'pebrel'
+local config = pebrel.config_builder()
+
+config.profiles = pebrel.array()
+
+return config
+```
+
+普通 `{}`表示空对象,不能在需要数组的地方替代空列表。包含条目时,使用连续的 Lua 数组,参见[自定义启动入口](shells.md)。
diff --git a/docs/site/content/configuration.md b/docs/site/content/configuration.md
new file mode 100644
index 000000000..bbc7139e4
--- /dev/null
+++ b/docs/site/content/configuration.md
@@ -0,0 +1,71 @@
+## 创建配置文件
+
+主题、通知和 SSH 等常用设置可以直接在界面中完成。需要保存可复用的终端参数、环境变量或 Profile 时,可以创建 Lua 配置。
+
+在可运行 Pebrel 命令的终端执行:
+
+```sh
+pebrel config init --language zh-CN
+pebrel config check
+```
+
+第一条生成带中文说明的配置,第二条检查语法与字段。初始化默认不会覆盖已有文件。需要英文说明时使用 `--language en-US`。
+
+## 修改一个选项
+
+打开生成的 `pebrel.lua`,保留开头的配置创建与结尾的 `return config`。例如:
+
+```lua
+local pebrel = require 'pebrel'
+local config = pebrel.config_builder()
+
+config.scrolling = { history = 10000 }
+config.env = { EDITOR = 'nvim' }
+
+return config
+```
+
+这个示例设置终端历史行数和默认编辑器环境变量。`EDITOR='nvim'`不会安装程序;使用前仍需安装相应编辑器。
+
+保存后再次运行 `pebrel config check`。检查通过,再新建终端查看需要在启动时生效的选项。
+
+## 配置文件在哪里
+
+标准数据目录为:
+
+| 系统 | 目录 |
+| --- | --- |
+| Windows | `%APPDATA%\Pebrel` |
+| macOS | `~/Library/Application Support/Pebrel` |
+| Linux | `$XDG_CONFIG_HOME/pebrel`,未设置时为 `~/.config/pebrel` |
+
+初始化时以命令输出的实际路径为准。便携配置、环境变量和显式参数也可能指定其他文件。
+
+需要检查特定文件时运行:
+
+```sh
+pebrel config check --config-file /path/to/pebrel.lua
+```
+
+将路径换成实际位置。这个检查命令不需要打开应用窗口。
+
+## 指定另一套配置
+
+启动参数 `--config-file`优先于 `PEBREL_CONFIG_FILE`环境变量,再往后才是标准位置的自动查找。使用 **PEBREL_CONFIG_DIR**可以指定独立配置与数据目录,适合隔离测试或便携使用。
+
+旧的 `NEBULA_*`变量保留兼容。新旧文件并存时,Pebrel 名称的配置优先;同名配置中,Lua 优先于 TOML,再到旧的 YAML 格式。选中的文件有错误时,修复这份文件即可,不要期待自动换到另一份。
+
+## 保存后重新加载
+
+有效配置变更会自动重载。重载失败时,正在运行的应用保留上次有效配置;修正提示的行或字段后,再保存一次。
+
+Shell、环境变量和回滚容量等启动相关设置,应在新窗格中验证。字体或颜色也可能受到界面偏好的覆盖;同时设置了两处时,先检查界面中是否已有对应覆盖项。
+
+## 将配置拆成多个文件
+
+主文件可使用 `require`读取旁边的 Lua 模块。例如,把配色放在 `theme.lua`,再在主文件中写 `config.colors = require 'theme'`。模块返回配置表即可;被加载的本地模块也参与重载。
+
+更多可复制的例子见[配置示例](config-examples.md)。完整字段与加载规则见仓库的 [Lua 配置参考](https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/lua-configuration.md)。
+
+> [!NOTE]
+> Lua 配置会执行本地代码。使用他人提供的配置前,先阅读内容;GUI 的 `pebrel_settings.txt`使用另一套偏好键,不能直接当作 Lua 配置粘贴。
diff --git a/docs/site/content/contributing.md b/docs/site/content/contributing.md
new file mode 100644
index 000000000..cc2ce29ee
--- /dev/null
+++ b/docs/site/content/contributing.md
@@ -0,0 +1,106 @@
+## 开始前先确认范围
+
+贡献不一定从写代码开始。清晰的复现步骤、文档改进、翻译、可访问性反馈和针对性的测试同样有价值。
+
+准备修改代码时,先阅读仓库的[贡献指南](https://github.com/Kuddev/pebrel/blob/main/CONTRIBUTING.md)、[架构说明](https://github.com/Kuddev/pebrel/blob/main/docs/architecture.md)和[项目约束](https://github.com/Kuddev/pebrel/blob/main/docs/project-constraints.md)。涉及 UI 文档时,还需要遵循仓库的国际化规则。
+
+
+
准备Fork 仓库,从目标分支创建独立工作分支。
+
修改一次 PR 只解决一个清晰问题,复用已有职责和状态来源。
+
验证运行与改动对应的测试、架构检查、格式检查和真实产品检查。
+
提交写清用户问题、实际改动、验证结果和仍未验证的范围。
+
+
+## 准备开发环境
+
+1. Fork `Kuddev/pebrel`,从 PR 目标分支创建自己的工作分支。
+2. 按仓库的 [INSTALL.md](https://github.com/Kuddev/pebrel/blob/main/INSTALL.md) 安装当前平台需要的依赖。
+3. 使用 `rust-toolchain.toml` 固定的 Rust 工具链,不要随意切换工具链版本。
+4. 构建实际的 GPUI 产品界面:
+
+```sh
+cargo build --locked -p pebrel --bin pebrel --features gpui-shell
+```
+
+如果只是修文档,应优先运行文档自己的构建与测试,不需要为了文字改动制造无关的产品代码变化。
+
+## 不要用于推广
+
+PR、Issue 及其评论不能用于广告、商业推广或引流,包括以功能贡献为名加入服务商推广、返利链接或注册优惠。确认属于未经授权的推广后,对应提交会被直接关闭。商业合作和赞助请发邮件到 [fickleheartedkeys@163.com](mailto:fickleheartedkeys@163.com),不要在 PR 或 Issue 里洽谈。完整规则见[贡献指南](https://github.com/Kuddev/pebrel/blob/main/CONTRIBUTING.md#commercial-promotion-policy)。
+
+## 保持改动容易审查
+
+- 一个 PR 只承担一个概念上的改动;不要顺便重构无关文件。
+- 先说明用户可观察到的问题,以及哪些既有行为必须保持。
+- 共享规则应继续由现有权威模块负责,UI 只适配,不复制第二套状态或持久化逻辑。
+- 有自然测试入口时,为问题增加最小、聚焦的回归验证。
+- 不要通过放宽预算、移除测试、增加跳过参数或扩大忽略范围来让 CI 变绿。
+- 不提交构建输出、本地探针、包含隐私/凭据的截图或临时调查文件。
+
+仓库的 PR size 检查会限制过大的源码改动;文档、锁文件和资源与源码预算的计算规则不同。需要大范围重构时,先拆分成可独立审查的步骤。
+
+## 本地快速检查
+
+架构检查需要 Python 3.11+。把 `` 替换成实际目标分支的基准提交:
+
+```sh
+python3 scripts/check_architecture.py --base
+python3 -m unittest scripts.tests.test_architecture_budgets scripts.tests.test_architecture_dependencies scripts.tests.test_architecture_governance
+cargo test --manifest-path tools/i18n-contract/Cargo.toml --locked
+cargo test -p pebrel-settings
+cargo test -p pebrel --test file_line_budget
+cargo fmt --all -- --check
+```
+
+涉及正式应用行为时,再运行:
+
+```sh
+cargo check -p pebrel --bin pebrel --features gpui-shell --tests --locked
+```
+
+还应运行与你修改区域直接相关的行为测试。无法在当前机器上验证的平台能力,需要在 PR 描述里明确写出,而不是把“能编译”描述成“UI 已验证”。
+
+## 修改文档网站
+
+文档站源文件位于 `docs/site/`。本地构建:
+
+```sh
+python -m pip install -r docs/site/requirements.txt
+python docs/site/build.py
+python -m unittest discover -s docs/site -p test_site.py
+```
+
+新增公开文档源文件时,还要把具体路径加入 `.gitignore` 中的精确 allowlist。不要直接放开整个 `docs/` 目录。
+
+文档应从用户任务出发:先告诉用户去哪里、执行什么、看到什么结果,再补限制和背景。不要把源码结构说明写成用户指南。
+
+## 提交 Pull Request
+
+PR 描述至少应包含:
+
+| 内容 | 应写什么 |
+| --- | --- |
+| 问题 | 用户实际遇到了什么,或为什么需要这个变化 |
+| 改动 | 哪些行为发生变化;哪些关键行为保持不变 |
+| 验证 | 实际运行过的命令、测试和平台结果 |
+| 缺口 | 没有运行的 UI、平台或打包验证 |
+| 风险 | 持久化格式、依赖、线程、公共接口等是否受到影响 |
+
+早期需要设计反馈时可以先开 Draft;准备合并前再切换 Ready。维护者根据实际 diff、测试结果、平台验证和代码审查决定是否可以合并。
+
+## CI 会检查什么
+
+Draft 和 Ready PR 使用相同的验证规划:CI 根据实际改动路径选择需要执行的原生平台测试;纯文档改动不运行原生测试。主分支、定时和发布验证保留五平台完整矩阵。PR 的检查页面会注明各平台是否实际执行,不能把未执行的绿色汇总当作测试覆盖。核心检查还包括架构合同、格式与矩阵规划和源码规模。
+
+来自 fork 的首次贡献可能在 GitHub Actions 中显示等待维护者批准。这是 GitHub 的安全边界,不应通过提高 token 权限或改用不安全触发方式绕过。
+
+## 提交前自检
+
+- 工作分支基于正确的目标分支。
+- Diff 只包含当前功能需要的文件。
+- 没有提交凭据、个人路径、私密日志或无关截图。
+- 相关测试真实运行过,PR 中没有夸大验证范围。
+- CI 失败时修原因,而不是关闭门禁。
+- 如果改动引入新的架构责任或跨层依赖,已经按仓库要求记录和讨论。
+
+完成这些步骤后,PR 会更容易复现、审查和维护。
diff --git a/docs/site/content/documents.md b/docs/site/content/documents.md
new file mode 100644
index 000000000..74bd8544b
--- /dev/null
+++ b/docs/site/content/documents.md
@@ -0,0 +1,43 @@
+## 打开 Markdown 文档
+
+在[文件树](files.md)中选择 `.md`文件。文档会在标签页中打开,并显示标题、段落、列表、代码和支持的公式排版。
+
+阅读视图可以选取和复制文字。需要修改文件时,打开文档工具栏的 **文档操作**(省略号),选择 **源码**。编辑步骤见[编辑 Markdown](markdown-editing.md)。
+
+
Markdown 文档中的公式排版。
+
+## 按目录跳转
+
+右侧栏的 **目录**按文档标题组织章节。点击标题可以跳到对应位置;长文档中,可折叠暂时不看的层级。
+
+侧栏没有显示时,点击 **展开或收起右侧栏**按钮。文档没有 Markdown 标题时,目录会显示相应的空状态;可以在源码中用 `#`、`##`建立章节。
+
+## 专注阅读
+
+点击文档工具栏中的 **专注阅读**,为正文留出更多空间;再次使用对应入口退出。这个功能调整阅读布局,不会修改文档内容。
+
+在普通代码文件中,类似位置可能显示系统全屏按钮,具体作用以按钮提示为准。
+
+## 复制代码
+
+将鼠标移到代码块,使用 **复制代码**。复制的是代码文本,不包含 Markdown 外层的反引号围栏。
+
+语言选择器可以调整当前代码块的语法高亮,帮助阅读没有写明语言的代码。需要把语言永久写入文档时,在源码中修改代码围栏后面的语言名称并保存。
+
+## 复制公式
+
+在公式相关菜单中选择 **复制 LaTeX 源码**,可将表达式交给其他数学工具。公式已完整渲染且菜单提供图片复制时,可以选择 **复制公式图片**。
+
+无法复制为图片时,先使用 LaTeX 源码,或简化不受支持的语法。用鼠标拖选跨过公式的文字时,版面不会跳动,被选中的公式会显示轮廓,复制得到的是它们的 LaTeX 源码。关于文档中的公式写法,见[Markdown 编辑](markdown-editing.md)。
+
+## 查看文件信息
+
+右侧栏切换到 **文件信息**,查看文件类型、大小、修改时间、字符数、行数、编码和保存状态。
+
+相关操作提供 **复制文件名**、**复制文件路径**、**在文件管理器中显示**、**用默认应用打开**与 **重新读取文件**。重新读取前先保存或复制仍需要保留的编辑内容。
+
+## 远端文档和大文件
+
+从 SFTP 打开的远端 Markdown 使用源码编辑,保存会写回原服务器,见[远端编辑](remote-edit.md)。
+
+文件超过 **8 MB**或无法完整作为 UTF-8 文本编辑时,会显示只读或截断提示。要查看大文件全部内容,可以使用系统编辑器,或在终端用 `less`等工具按需读取。
diff --git a/docs/site/content/files.md b/docs/site/content/files.md
new file mode 100644
index 000000000..ae0f6a5bc
--- /dev/null
+++ b/docs/site/content/files.md
@@ -0,0 +1,49 @@
+## 打开项目文件
+
+先在终端进入项目目录,再按 **Ctrl+Shift+F**(macOS 为 **⌘⇧F**)打开文件树。展开文件夹,选择要查看的文件。
+
+文本文件可以在编辑器中打开,Markdown 默认以排版后的阅读视图打开。聚焦内置 SSH 会话时,文件面板显示对应的[SFTP 远端文件](sftp.md)。
+
+## 跟随终端目录
+
+在终端执行 `cd`切换目录后,文件树可使用终端上报的目录。手动浏览过其他位置时,点击 **跟随当前终端并刷新**,或使用按钮提示的 **Alt+R**,回到当前终端目录。
+
+读取失败时先看面板里的路径和错误提示。旧目录可能仍显示在面板中,修复路径或权限后再刷新。
+
+## 按名称找文件
+
+在文件树搜索框输入文件或文件夹名称。按需要切换以下选项:
+
+| 选项 | 使用场景 |
+| --- | --- |
+| **区分大小写** | 区分 `README`与 `readme` |
+| **全词匹配** | 按完整词匹配,而不是任意部分字符 |
+| **使用正则表达式** | 用模式匹配文件名,例如 `\.md$` |
+
+搜索用于查找名称。要查找文件里面的文字,可以在终端使用已安装的搜索工具,例如:
+
+```sh
+rg "TODO" .
+```
+
+出现扫描限制或目录权限提示时,先缩小到相关项目目录,再搜索。
+
+## 从文件夹新建终端
+
+右键目标文件夹,选择 **在此处打开终端**,或使用面板的 **在此新建终端**入口。新终端打开后运行 `pwd`检查位置;cmd 使用 `cd`。
+
+WSL 目录会使用适合该环境的路径。需要把文件路径交给 Linux 命令时,使用菜单中的 **复制 Linux 路径**。
+
+## 复制路径或使用系统应用
+
+文件或目录菜单提供 **复制路径**、**打开**以及在系统文件管理器中显示的入口。要把路径放进命令时,粘贴后检查路径中是否有空格,并按 Shell 需要添加引号。
+
+文件不适合用内置编辑器处理时,可以在系统文件管理器中打开,或使用文件信息中的 **用默认应用打开**。
+
+## 从项目中忽略或删除文件
+
+在 Git 项目里,**加入 .gitignore**可为不需要跟踪的文件添加忽略规则。已经被 Git 跟踪的文件,仍需按 Git 的规则处理;忽略规则不会从历史提交中移除内容。
+
+选择 **删除**后,阅读 **移入回收站**确认框,核对文件名和路径。批量处理前先确认没有选错项目目录;操作失败时按系统提示检查权限或回收站支持情况。
+
+查看改动和提交文件,见[版本控制](vcs.md)。
diff --git a/docs/site/content/fonts.md b/docs/site/content/fonts.md
new file mode 100644
index 000000000..d2df367de
--- /dev/null
+++ b/docs/site/content/fonts.md
@@ -0,0 +1,43 @@
+## 放大终端文字
+
+打开 **设置 → 外观 → 终端外观**,调整 **终端字号(Ctrl+滚轮缩放)**。可以使用加减按钮,也可以直接点击数值输入新的字号,按 **Enter** 或移开焦点生效,按 **Esc** 取消;还可以在终端按 Ctrl+滚轮缩放。
+
+键盘缩放使用 **Ctrl++ / Ctrl+-**,macOS 使用 **⌘+ / ⌘-**;**Ctrl+0 / ⌘0**重置缩放。
+
+不希望滚动时误改字号,可以关闭同页的 **Ctrl+滚轮调整字号**。关闭后这个手势被完全忽略,既不改变字号,也不滚动终端;键盘快捷键不受影响。
+
+按钮或侧栏文字太小时,调整同页 **界面**分组中的 **界面字号**,它同样可以直接输入数值,不会改变终端输出大小。
+
+## 选择英文终端字体
+
+在 **英文终端字体**一行点击右侧的展开按钮,打开字体列表。列表里可以搜索已安装的字体,点击可用字体旁的 **加入字体组** 把它加入;**当前顺序**里的字体可以上移、下移或移出。字体组按顺序查找字形:标为“主”的第一项优先,缺少字符时使用后面的字体,内置的 Maple Mono 是最后的兜底。
+
+选择后查看数字、标点、代码缩进和表格边框。终端使用等宽网格,等宽字体更适合保持这些内容对齐;列表里标有“比例”的是比例字体,不适合终端。
+
+刚安装的字体没有出现时,重新打开字体列表;仍找不到则重启 Pebrel。使用系统显示的字体族名称,而不是字体文件名。
+
+## 单独设置中文字体
+
+**中文终端字体**与英文字体各自独立保存,同样可以展开带搜索的字体列表,设置自己的字体和回退顺序;也可以直接在输入框写字体名称,多个候选用逗号分隔,按 **Enter**或离开输入框后生效。留空时使用内置的 Maple Mono NF CN 回退。
+
+修改后同时检查中文、英文和全角标点。只有中文缺字时,优先检查中文字体和回退列表,不必更换整个界面主题。
+
+## 连字和字符间距
+
+**字体连字**可选择 **开启**、**关闭**或 **跟随主题**。字体支持时,`->`、`!=`等字符组合会以连字显示,选项会立即应用到已打开的终端。
+
+**字体间距**可选 **紧凑**或 **宽松**,用于调整终端字符的列宽。小字号下字符挤在一起时,可以试用宽松;需要更细的纵向调整时,在[主题编辑器](themes.md)设置行高。
+
+## 中文粗体看不清
+
+打开 **设置 → 交互**,调整 **中日韩粗体提亮**。它让相关字符通过提亮表现粗体,拉丁字符仍按自身字体处理。使用中英文混排的实际输出检查结果。
+
+## Powerline 箭头显示成方框
+
+在 **外观 → 终端外观**中开启 **Powerline 提示符**后,字体需要包含 Powerline 字形。出现方框时,改用具备这些字形的字体,或先关闭该选项。
+
+**启动欢迎信息**会在新会话通过 fastfetch 显示系统信息。不需要启动摘要时,将它关闭即可;此项与字体设置独立。
+
+## 排查错位或模糊
+
+先恢复默认字体与字号,再关闭连字、改回纯色背景,逐项恢复自己的设置。仍有问题时,反馈系统缩放比例、字体名称、字号、字体间距模式,以及能看出错位的截图。
diff --git a/docs/site/content/git-conflicts.md b/docs/site/content/git-conflicts.md
new file mode 100644
index 000000000..1deb8b7f2
--- /dev/null
+++ b/docs/site/content/git-conflicts.md
@@ -0,0 +1,47 @@
+## 打开冲突文件
+
+Git 合并、拉取或变基后出现冲突时,在版本控制面板的 **合并冲突**区域找到文件,选择 **在三栏合并器中解决**。
+
+编辑器会打开三列:左侧 **当前版本**,中间 **合并结果(可编辑)**,右侧 **传入版本**。
+
+## 合并需要保留的内容
+
+先比较左右两边,然后在中间结果栏整理最终内容。通常需要同时保留双方不同位置的修改,而不是直接选择一整边。
+
+冲突标记形如:
+
+```text
+<<<<<<< 当前版本
+这一侧的内容
+=======
+另一侧的内容
+>>>>>>> 传入版本
+```
+
+保留正确内容后,删除这些标记行。结果中仍有冲突标记时,页面会显示 **仍有冲突标记**,应用按钮不可用。
+
+## 采用一侧的完整版本
+
+确定整个文件应使用一侧内容时,可以点击该侧的箭头按钮:**用当前版本替换合并结果**,或 **用传入版本替换合并结果**。
+
+这会替换中间结果的完整内容,不是只接受光标附近的一小段。操作前留意中间已经手动整理的修改。
+
+Git 变基时,两侧版本的角色容易与直觉不同。以实际文件内容和正在执行的 Git 操作为准,不能只根据“当前”两个字决定保留哪边。
+
+## 应用并暂存
+
+1. 检查中间结果,确认冲突标记已经全部清除。
+2. 点击 **应用并暂存**。
+3. 等待状态显示 **已写回并暂存**。
+4. 返回版本控制面板,检查这个文件不再列为未解决冲突。
+5. 运行项目测试或检查命令,然后完成原来的 Git 操作。
+
+“应用并暂存”会保存文件并执行对应的暂存操作,不会自动替你完成整个合并或变基。
+
+在终端运行 `git status`查看下一步提示。如果当前正在变基,按 Git 提示执行 `git rebase --continue`;普通合并则按当前仓库状态完成提交。
+
+## 需要重新读取时
+
+文件被其他工具修改,或冲突状态发生变化时,可以点击 **重新读取冲突阶段**。先复制中间尚未保存的内容,以便比较或恢复。
+
+二进制文件和超出合并器文本大小限制的文件,需要使用相应的外部工具处理。某一侧显示“文件不存在”时,还要决定是否保留该文件;删除类冲突应结合 `git status`提示处理。
diff --git a/docs/site/content/hooks.md b/docs/site/content/hooks.md
new file mode 100644
index 000000000..9576c266c
--- /dev/null
+++ b/docs/site/content/hooks.md
@@ -0,0 +1,94 @@
+> [!NOTE]
+> 本页按 Pebrel 2.1.1 核对。设置页里的"Hook"是各工具对"事件入口"的称呼,本页统一叫"集成"。
+
+## 先了解默认行为
+
+集成让工具在开始、结束或需要你处理时主动告诉 Pebrel,Pebrel 据此更新标签和窗格上的活动提示,并发出通知。它在 Windows、macOS 和 Linux 上都可以使用。
+
+- **Claude Code 和 Codex 默认开启。** 只要它们安装在这台电脑上,Pebrel 会自行在它们的配置里写入集成入口,通常不需要你操作。
+- **其他工具默认关闭。** 需要在 **设置 → Agents** 里自己打开,包括 OpenCode、Cursor Agent、Kimi Code、Pi、Oh My Pi、GitHub Copilot 和 Grok。
+- **集成只在 Pebrel 里起作用。** 在 Pebrel 之外的终端运行同一个工具,不会发生任何变化。
+
+各工具具体支持哪些功能,见[支持的 AI 命令行工具](agents.md)。
+
+## 在设置里查看和开关
+
+打开 **设置 → Agents**,页面标题是"编程智能体"。每个工具占一行,从左到右依次是:
+
+- 工具图标和名称;
+- Pebrel 找到的程序路径,鼠标停在路径上可以看到完整内容;找不到时显示"未安装";
+- 当前状态;
+- 一个开关。
+
+1. 先在终端里启动一次要用的工具,让它完成初始配置。工具还没有创建过配置时,这一行会提示"请先运行一次此工具以创建配置,然后刷新"。
+2. 点击右上角的 **刷新**,重新检测。
+3. 打开这个工具的开关。点击整行也可以切换。
+4. 看到"Hooks 已安装,请重启 agent 使其生效"后,退出并重新启动这个工具。
+5. 提交一个简短任务,检查标签上的状态是否随任务变化。
+
+只需要打开自己用的工具。开关灰着无法点击,通常是因为 Pebrel 还没有找到这个工具,或它还没有创建过配置。
+
+### 状态的含义
+
+| 状态 | 含义 | 怎么处理 |
+| --- | --- | --- |
+| Hook 已安装 | 集成已经就绪 | 重启工具后即可使用 |
+| Hook 未安装 | 工具已找到,集成处于关闭状态 | 需要时打开开关 |
+| Hook 已安装 · 需修复 | 入口还在,但内容与当前版本不一致,例如工具更新时改写过配置 | 关闭再打开一次 |
+| 需要检查 | 读取或写入这个工具的配置时出错,原因会显示在这一行 | 看提示,检查配置文件的权限,再刷新 |
+| 处理中… | 正在写入或移除 | 稍候 |
+
+如果提示"缺少 hook 辅助程序,请修复 Pebrel 安装后再启用",说明 Pebrel 自带的辅助程序没有找到,重新安装 Pebrel 即可。
+
+## 开启后会改动什么
+
+Pebrel 只写入属于自己的条目,不会改动你已有的其他配置:
+
+| 工具 | 修改位置(均在用户目录下) |
+| --- | --- |
+| Claude Code | `.claude/settings.json`,设置了 `CLAUDE_CONFIG_DIR` 时用该目录 |
+| Codex | `.codex/` 下的 `config.toml` 和 `hooks.json` |
+| OpenCode | `.config/opencode/plugins/pebrel.js` |
+| Pi | `.pi/agent/extensions/pebrel.ts` |
+| Oh My Pi | `.omp/agent/extensions/pebrel.ts` |
+| Kimi Code | `.kimi-code/config.toml` |
+| Cursor Agent | `.cursor/hooks.json` |
+| GitHub Copilot | `.copilot/hooks/pebrel.json` |
+| Grok | `.grok/hooks/pebrel.json` |
+
+这些文件属于对应工具自己的配置。开关处于打开状态时,如果工具升级或别的程序改动了它们,Pebrel 会检测到并把自己的条目补回;你主动关闭的工具不会被补回。
+
+对于 Claude Code 和 Codex,Pebrel 还会放入一个名为 `pebrel-runtime` 的技能,让它们在对话里直接操作 Pebrel,例如分屏、打开文件或把任务交给另一个窗格里的工具,用法见[命令行控制与自动化](runtime.md)。你修改过的技能文件不会被覆盖。
+
+## 关闭集成
+
+在 **设置 → Agents** 关闭该工具的开关,再重启工具。出现"Hooks 已移除,请重启 agent 使其生效",表示已经移除。关闭后仍可在终端里正常运行这个工具,活动提示会退回到[屏幕识别](agents.md)。
+
+想一次移除所有工具的集成,在终端运行:
+
+```sh
+pebrel setup-ai --remove
+```
+
+它只移除 Pebrel 写入的条目,保留其他集成。不带 `--remove` 再运行一次,会重新为 Claude Code、Codex 以及你在设置里打开过的工具写入集成。
+
+## WSL 与 SSH
+
+**设置 → Agents** 只管理这台电脑上的工具。WSL 和服务器上的工具有各自的配置,由下面的方式处理。
+
+- **通过 Pebrel 的 SSH 连接:** 连接时会自动检查服务器,为其中已安装的 Claude Code、Codex、OpenCode 和 Pi 配置集成。这一步失败不会影响你正常使用终端。需要手动处理时运行 `pebrel setup-ai --ssh 主机别名或user@host`;加上 `--remove` 会移除,并记住这台主机不再自动配置。
+- **WSL:** 在 Windows 上打开 WSL 终端时,会为发行版里的 Claude Code 和 Codex 配置集成。手动运行 `pebrel setup-ai --wsl 发行版名称`,需要指定用户时再加 `--wsl-user 用户名`。Codex 可能会要求你在它的 `/hooks` 里确认这些入口。
+
+SSH 和 WSL 里的其他工具仍可使用,只是没有集成,状态提示依赖屏幕识别。
+
+## 工具没有被检测到
+
+先在准备使用它的终端里运行工具命令。命令找不到时,修复安装和 PATH;命令可用,再点 **刷新**。
+
+确认安装的是目标 CLI。例如,Cursor 桌面程序的 `cursor` 命令不等于 Cursor Agent CLI,后者的命令是 `agent`。工具刚升级过时,重新启动 Pebrel 和工具可以清除旧的检测与运行状态。
+
+## 收不到任务通知
+
+先确认工具已在启用集成后重启,再检查 **设置 → 终端 → 提醒** 里的通知选项。任务状态能更新但卡片没有出现时,通常应继续检查通知显示设置,而不是重新安装工具。
+
+通知时长、点击跳回来源窗格和系统通知见[通知](notifications.md)。
diff --git a/docs/site/content/images.md b/docs/site/content/images.md
new file mode 100644
index 000000000..c0deaef4e
--- /dev/null
+++ b/docs/site/content/images.md
@@ -0,0 +1,41 @@
+## 预览图片文件
+
+从文件树选择图片,可以查看支持格式的预览。常见格式包括 PNG、JPEG、WebP、GIF 和 BMP;超出大小限制或解码失败时,可使用系统默认应用打开。
+
+PDF 提供首页缩略图,适合辨认文件。需要翻页、批注或编辑时,使用 PDF 阅读器。Linux 的 PDF 缩略图依赖可用的 `pdftoppm`。
+
+## 把剪贴板图片交给命令行工具
+
+1. 复制图片本身,例如截图结果,而不是图片文件名。
+2. 点击准备接收图片的终端窗格。
+3. 按 **Ctrl+V / ⌘V**粘贴。
+4. 等待 PNG 保存或远端上传完成。
+5. 检查插入的文件路径,再按工具的要求提交。
+
+Pebrel 会生成图片文件并插入路径。AI CLI 是否把路径显示为附件缩略图,取决于它自己的图片输入功能。
+
+剪贴板同时包含非空文字时,可能优先粘贴文字。看到意外文本时,先撤回或清空输入,再重新复制图片。
+
+## 在 WSL 或 SSH 中粘贴
+
+WSL 使用转换后的 Linux 可访问路径。原生 SSH 会话需要先把图片传到远端,再插入远端路径;传输失败时先修复连接或权限。
+
+同一张本机图片需要发给不同主机时,分别聚焦对应窗格再粘贴。图片不参与[广播输入](broadcast.md)。
+
+## 在终端输出里显示图片
+
+前台程序输出 Pebrel 支持的 **OSC 1337**图像协议时,终端可以内嵌显示图片。仅打印一个 `.png`路径不会自动变成图像。
+
+需要使用这一方式时,选择能够输出相应协议的命令行工具,并按其说明配置。普通图片浏览优先使用文件预览,不必自己编写转义序列。
+
+## Markdown 中的图片
+
+本地 Markdown 可以引用可访问的图片,路径相对文档位置。比如 ``要求文档旁有 `images/example.png`。
+
+图片缺失时,先在文件树检查目标文件,不要仅修改显示文字。远端 Markdown 编辑不会自动把所有关联图片下载到本地阅读器。
+
+## 清理粘贴产生的文件
+
+图片粘贴后,可以从插入的路径找到副本。不再需要时按该位置删除;远端副本需要在服务器上清理。
+
+发送前检查截图中是否包含密码、Token 或私人信息。删除本机副本不会撤回已经交给远端服务器或 AI 服务的内容。
diff --git a/docs/site/content/index.md b/docs/site/content/index.md
new file mode 100644
index 000000000..a648c95f0
--- /dev/null
+++ b/docs/site/content/index.md
@@ -0,0 +1,31 @@
+## 开始使用
+
+
+
+## 常用操作
+
+| 想完成的操作 | 使用指南 |
+| --- | --- |
+| 安装 Pebrel,或选择适合电脑的版本 | [安装与平台支持](installation.md) |
+| 一边运行服务,一边输入其他命令 | [标签页与分屏](workspace.md) |
+| 补齐分支、脚本、主机和历史命令 | [命令补全](completions.md) |
+| 下次打开时恢复标签和目录 | [会话保存与恢复](sessions.md) |
+| 重复使用一组终端布局 | [布局配方](layouts.md) |
+| 找到并修改项目文件 | [文件浏览](files.md) · [Markdown 编辑](markdown-editing.md) |
+| 查看改动、提交代码和处理冲突 | [Git 提交](vcs.md) · [解决冲突](git-conflicts.md) · [SVN](svn.md) |
+| 将文件传到服务器 | [SFTP 文件传输](sftp.md) |
+| 从 Android 查看电脑终端或发送输入 | [Android 连接电脑](mobile.md) |
+| 查看 Pebrel 支持哪些 AI 命令行工具 | [支持的 AI 命令行工具](agents.md) |
+| 重新打开上次的 AI 对话 | [AI 会话历史](ai-history.md) |
+| 更改快捷键或通知时间 | [快捷键](keyboard.md) · [通知](notifications.md) |
+| 备份设置,或迁移到另一台电脑 | [加密备份](backups.md) · [备份与迁移](migration.md) |
+| 处理无法启动、连接或保存的问题 | [故障排查](troubleshooting.md) |
+
+
终端工作区。截图中的主题和窗口装饰可能因平台而不同。
+
+本指南适用于 **Pebrel 2.1.1**。`main` 中更新的功能不代表已发布到你安装的版本;功能随版本变化时,对应页面会在页首注明版本。macOS 和 Linux 安装包目前标为 Preview;平台差异见[安装与平台支持](installation.md)。
diff --git a/docs/site/content/installation.md b/docs/site/content/installation.md
new file mode 100644
index 000000000..fbb1f2336
--- /dev/null
+++ b/docs/site/content/installation.md
@@ -0,0 +1,90 @@
+## 选择安装包
+
+打开 [Pebrel Releases](https://github.com/Kuddev/pebrel/releases)。本指南对应 **2.1.1**,安装包名称包含版本、系统和处理器类型。更新版本的文件名只有版本号不同。
+
+| 电脑 | 选择的包 | 系统要求 |
+| --- | --- | --- |
+| Windows,Intel / AMD 64 位处理器 | `Pebrel-v2.1.1-windows-x64-setup.exe` 或 `Pebrel-v2.1.1-windows-x64.zip` | Windows 10 1809+ / Windows 11 |
+| Windows,ARM 处理器 | `Pebrel-v2.1.1-windows-arm64-setup.exe` 或 `Pebrel-v2.1.1-windows-arm64.zip` | Windows 10 1809+ / Windows 11,ARM64 |
+| Mac,Apple 芯片 | `Pebrel-v2.1.1-macos-arm64-preview.dmg` | 构建目标为 macOS 14+ |
+| Mac,Intel 处理器 | `Pebrel-v2.1.1-macos-x64-preview.dmg` | 构建目标为 macOS 14+ |
+| Linux,Intel / AMD 64 位处理器 | `Pebrel-v2.1.1-linux-x64-preview.deb`、`Pebrel-v2.1.1-linux-x64-preview.AppImage` 或 `Pebrel-v2.1.1-linux-x64-preview.tar.gz` | glibc 2.35+ |
+
+在 Mac 的 **苹果菜单 → 关于本机** 中可以查看芯片类型。`x64` 指 64 位 Intel / AMD,不是 32 位 x86。macOS 和 Linux 当前提供 Preview 包;macOS 构建目标为 14+,发布 CI 在 macOS 15 上验证。
+
+同一页面还有 `Pebrel-v2.1.1-android-universal-preview.apk`,它是手机端,不是桌面安装包,用法见[Android 连接电脑](mobile.md)。`SHA256SUMS` 用来核对下载文件。
+
+## Windows
+
+### 使用安装程序
+
+1. 下载 `Pebrel-v2.1.1-windows-x64-setup.exe`。
+2. 运行安装程序,按页面提示选择安装位置并完成安装。
+3. 从开始菜单或安装完成后的入口启动 Pebrel。
+4. 看到终端提示符后,输入 `echo Hello, Pebrel` 检查运行情况。
+
+ARM 处理器的电脑同样使用安装程序,下载 `Pebrel-v2.1.1-windows-arm64-setup.exe`。
+
+### 使用便携版
+
+1. 下载 `Pebrel-v2.1.1-windows-x64.zip` 或 `Pebrel-v2.1.1-windows-arm64.zip`。
+2. **完整解压**到一个可写目录。
+3. 进入解压后的目录,运行 `pebrel.exe`。
+
+保留与可执行文件一起提供的目录和资源;不要在压缩包预览窗口里直接启动,也不要只复制一个 EXE。需要随身携带配置时,参阅[配置文件](configuration.md)和[备份与迁移](migration.md)。
+
+## macOS
+
+1. 下载 Apple Silicon 的 `Pebrel-v2.1.1-macos-arm64-preview.dmg` 或 Intel 的 `Pebrel-v2.1.1-macos-x64-preview.dmg`。
+2. 打开 DMG,将 **Pebrel** 拖入 **Applications/应用程序**。
+3. 弹出 DMG,然后从“应用程序”启动 Pebrel。
+
+如果系统拦截首次启动,先确认安装包来自项目官方 Release,再打开 **系统设置 → 隐私与安全性 → 仍要打开**,按系统提示确认。无需为此全局关闭 Gatekeeper。
+
+
来自 1.9.1 发布 CI 的 macOS 启动截图,仅用于说明首次启动的样子;2.1.1 的界面细节以实际安装后的窗口为准。
+
+## Linux
+
+### Debian / Ubuntu 安装包
+
+在下载目录打开终端,执行:
+
+```sh
+sudo apt install ./Pebrel-v2.1.1-linux-x64-preview.deb
+```
+
+安装完成后,从应用菜单打开 Pebrel。使用 `apt install` 安装本地 DEB,可同时处理发行版提供的依赖。
+
+### AppImage
+
+```sh
+chmod +x Pebrel-v2.1.1-linux-x64-preview.AppImage
+./Pebrel-v2.1.1-linux-x64-preview.AppImage
+```
+
+如果提示缺少 FUSE,请按照你的发行版说明安装兼容组件,或改用 DEB / TAR.GZ 包。
+
+### TAR.GZ 便携包
+
+解压 `Pebrel-v2.1.1-linux-x64-preview.tar.gz`,进入其中的目录后运行 `./AppRun`。保留解压后的完整目录,启动器需要读取随包资源。
+
+## 平台功能差异
+
+| 功能 | Windows | macOS | Linux |
+| --- | --- | --- | --- |
+| 本地终端、标签页、分屏、SSH、SFTP | 支持 | 支持 | 支持 |
+| 系统通知 | 支持 | 支持 | 支持,取决于桌面环境 |
+| 系统托盘、关窗保留后台会话、登录时启动 | 支持 | 支持 | 支持,托盘需要桌面提供状态通知器 |
+| 全局快速终端热键 | 支持 | 支持 | 支持,Wayland 通过桌面门户注册,会按系统流程请求授权 |
+| 本地 AI 集成自动设置 | 支持 | 支持 | 支持 |
+| 应用内更新安装 | 安装版支持 | 支持,替换应用包 | 不提供,使用包管理器或下载新包 |
+
+macOS 和 Linux 的这些集成从 2.1 版开始提供,对应的设置项见[设置索引](settings.md)。通过 Scoop 或 Microsoft Store 等渠道安装的 Windows 版本,由原渠道负责更新,见[更新](updates.md)。
+
+Linux 保存密码依赖可用且已解锁的系统凭据服务。macOS 使用系统钥匙串。有关认证方式,见[SSH 认证](ssh-auth.md)。
+
+## 已经安装过 Nebula
+
+Pebrel 是项目更名后的名称。首次运行会尝试迁移旧版配置,保留原文件且不覆盖已有 Pebrel 数据。先备份旧配置,再安装新版本;具体数据位置与迁移步骤见[备份与迁移](migration.md)。
+
+无法出现窗口、资源报错或 Shell 启动失败时,见[故障排查](troubleshooting.md)。
diff --git a/docs/site/content/interaction.md b/docs/site/content/interaction.md
new file mode 100644
index 000000000..aa628bc69
--- /dev/null
+++ b/docs/site/content/interaction.md
@@ -0,0 +1,49 @@
+## 调整鼠标操作
+
+打开 **设置 → 交互 → 鼠标与选区**。
+
+**选中即复制**开启后,松开鼠标时自动复制,右键直接粘贴。经常使用右键“发送到聊天”时,可以关闭它,保留常规菜单。
+
+**焦点跟随鼠标**开启后,鼠标移到窗格会改变输入焦点。希望明确点击后才切换输入目标时,将它关闭。多个 SSH 窗格并排时,输入前注意焦点位置。
+
+**粘贴前确认**用于在普通 Shell 粘贴多行或高风险文本前显示确认。具体规则和快捷键见[剪贴板](clipboard.md)。
+
+## 调整侧栏宽度
+
+**拖拽调节侧栏宽度** 默认已开启,直接拖动侧栏与工作区之间的分隔线即可。需要固定宽度、防止误拖时,将此项关闭;已经明确关闭过的设置会被保留。
+
+分隔线无法拖动时,先检查这个开关。终端内的分屏分隔线与侧栏宽度分别调整。
+
+## 更改标签页布局
+
+在 **标签与窗口**分组中:
+
+| 设置 | 可选方式 |
+| --- | --- |
+| **标签栏位置** | 左侧边栏 / 顶部 |
+| **标签展开动效** | 滑动 / 立即 |
+| **新标签位置** | 当前标签之后 / 列表末尾 |
+
+需要减少移动效果时,把标签展开动效改为“立即”。新标签位置影响之后新建的标签,不会把已有标签全部重新排序。
+
+显示关闭按钮的设置在 **外观**页;关闭显示后仍可使用菜单、中键或快捷键关闭标签。
+
+## 再次启动 Pebrel 时打开哪里
+
+**新建实例行为**可选择创建新窗口、附加到最近使用的窗口,或附加到此桌面最近使用的窗口。
+
+经常从项目目录启动 Pebrel 时,选择附加到已有窗口可以集中管理标签;需要每个项目独立窗口时,选择创建新窗口。
+
+关窗后的后台运行、登录自启动和标签恢复在 **设置 → 高级**中配置,见[会话保存与恢复](sessions.md)。
+
+## 版本控制与中文粗体
+
+**侧栏版本控制**可设为自动检测、仅 Git 或仅 SVN。切换后进入相应项目目录并打开版本控制面板。
+
+**中日韩粗体提亮**控制中文等相关字符的粗体呈现方式。需要调整字体本身时,转到 **外观 → 终端外观**。
+
+## 恢复默认设置
+
+设置页底部选择 **恢复默认设置**,阅读确认范围后继续。此操作恢复设置和快捷键、备份原设置,并保留 SSH 主机、凭据和历史。
+
+只需要改回一个选项时,优先调整该项,避免重置其余个性化设置。
diff --git a/docs/site/content/keyboard.md b/docs/site/content/keyboard.md
new file mode 100644
index 000000000..791ab4cb2
--- /dev/null
+++ b/docs/site/content/keyboard.md
@@ -0,0 +1,53 @@
+## 常用操作
+
+下表列出默认按键。**⌘**是 Command,**⇧**是 Shift,**⌥**是 Option。已经自定义过快捷键时,以 **设置 → 按键映射**中显示的内容为准。
+
+| 操作 | Windows / Linux | macOS |
+| --- | --- | --- |
+| 新建标签页 | Ctrl+Shift+T | ⌘T |
+| 新建窗口 | Ctrl+Shift+E | ⌘N |
+| 关闭当前项 | Ctrl+Shift+W | ⌘W |
+| 打开设置 | Ctrl+, | ⌘, |
+| 显示或隐藏侧栏 | Ctrl+Shift+B | ⌘B |
+| 命令面板 | Ctrl+Shift+P | ⌘⇧P |
+| Shell 选择器 | Ctrl+K | ⌘K |
+| 快速跳转 | Ctrl+Shift+O | ⌘⇧O |
+| 文件树 | Ctrl+Shift+F | ⌘⇧F |
+| 版本控制面板 | Ctrl+Shift+G | ⌘⇧G |
+| 向右分屏 | Ctrl+Shift+D | ⌘D |
+| 向下分屏 | Ctrl+Shift+S | ⌘⇧D |
+| 放大或还原窗格 | Ctrl+Shift+Enter | ⌘⇧Enter |
+| 切换相邻窗格 | Ctrl+Alt+方向键 | ⌘⌥方向键 |
+| 下一个 / 上一个标签 | Ctrl+Tab / Ctrl+Shift+Tab | ⌘⇧] / ⌘⇧[ |
+| 增大 / 减小终端字号 | Ctrl++ / Ctrl+- | ⌘+ / ⌘- |
+| 重置终端字号 | Ctrl+0 | ⌘0 |
+| 全屏 | Alt+Enter | ⌘Ctrl+F |
+
+复制、粘贴和滚动见[剪贴板](clipboard.md)与[终端基础操作](terminal-basics.md)。文档编辑按键见[Markdown 编辑](markdown-editing.md)。
+
+## 更改一个快捷键
+
+1. 打开 **设置 → 按键映射**。
+2. 找到要更改的动作,进入按键录入状态。
+3. 按下新的组合键,检查界面显示的结果。
+4. 返回工作区,在相应位置测试。
+
+录入时按 **Esc**取消;使用界面提示的清除操作或 Backspace 清除当前录入。出现冲突提示时,换一个组合键,或先调整原来占用它的动作。
+
+macOS 上清除一个动作的快捷键时,它对应的 ⌘ 组合也会一并清除,**恢复默认**则两者都恢复。页面下方的只读区还列出了标签页数字切换和确认对话框的按键:确认对话框用 **Enter** 确定、**Esc** 取消。
+
+## 同一按键在不同位置的作用
+
+快捷键会受当前焦点影响。例如,编辑 Markdown 段落时 **Ctrl+B / ⌘B**用于加粗选区;搜索框里的方向键用于选择结果,而不是移动终端光标。
+
+快捷键没有按预期生效时,先点击要操作的终端或文档,再试一次。系统级快捷键也可能先被桌面环境或其他应用接收。
+
+## 全局快速终端
+
+全局热键可在 Pebrel 不处于前台时使用,在 Windows、macOS 和 Linux 上都可以设置,配置入口位于按键映射相关设置中。设置后,切换到其他应用试按一次,检查是否成功唤起窗口。
+
+热键无法注册时,改用没有被其他应用占用的组合。详细设置见[快速终端与托盘](quick-terminal.md)。
+
+## 恢复默认按键
+
+设置页底部的 **恢复默认设置**会同时恢复设置与快捷键,并备份原设置;SSH 主机、凭据和历史会保留。需要只改一个动作时,优先调整该项,避免重置其他个性化设置。
diff --git a/docs/site/content/layouts.md b/docs/site/content/layouts.md
new file mode 100644
index 000000000..4d21506b9
--- /dev/null
+++ b/docs/site/content/layouts.md
@@ -0,0 +1,38 @@
+## 保存一套常用排布
+
+布局配方适合保存“两个项目标签,每个标签各有两个窗格”这类重复使用的工作环境。
+
+1. 打开需要的终端,调整标签名称、目录和分屏大小。
+2. 打开[命令面板](palette.md),搜索“布局”。
+3. 选择 **保存当前窗口布局…**。
+4. 输入 **布局名称**,例如“前后端开发”。
+5. 确认保存范围,点击 **保存布局**。
+
+列表会显示保存后的配方,并标出包含多少个标签和分屏。
+
+## 选择保存范围
+
+**当前标签**只保存当前终端标签的排布,适合一组相关窗格。**当前窗口**保存窗口中的终端布局,适合整个项目环境。当前项不是终端时,“当前标签”范围可能不可选。
+
+终端标签的右键菜单也提供 **导出为工作区…**入口。日常重复使用的布局,可以从这里进入相应的工作区保存流程。
+
+## 恢复布局
+
+1. 打开命令面板,选择 **打开布局配方…**。
+2. 找到保存的布局,点击 **恢复**。
+3. 在新窗口中检查每个终端的目录和连接状态。
+4. 启动项目服务或其他需要的程序。
+
+恢复会建立新的终端会话。布局记住的是排布和启动信息,不会复制原来正在运行的进程;例如开发服务器需要在新会话中重新启动。
+
+## 更新已有工作安排
+
+调整当前窗口后,重新保存为一个容易区分的名称,例如“前后端开发 · 数据库”。确认新配方可以正常恢复后,再删除不用的旧配方。
+
+不同电脑上的目录、Shell 和 SSH 凭据可能不同。迁移布局后,先校正这些启动条件,再批量恢复。
+
+## 删除布局配方
+
+在配方列表选择 **删除**,并在确认框中确认。删除配方不会关闭已经打开的终端,也不会删除项目文件。
+
+需要自动恢复最近一次退出前的排布,而不是手动选配方时,开启[启动时恢复上次标签](sessions.md)。
diff --git a/docs/site/content/markdown-editing.md b/docs/site/content/markdown-editing.md
new file mode 100644
index 000000000..8c50fdd10
--- /dev/null
+++ b/docs/site/content/markdown-editing.md
@@ -0,0 +1,96 @@
+## 切换到源码并保存
+
+1. 从文件树打开本地 Markdown 文件。
+2. 点击工具栏的 **文档操作**(省略号),选择 **源码**;也可以按 `Ctrl+/`(macOS 为 `⌘/`)切换。
+3. 修改文本。文件名附近的未保存标记会反映编辑状态。
+4. 按 **Ctrl+S / ⌘S**,或点击 **保存**。
+5. 再次切换源码选项,查看排版后的结果。
+
+Pebrel 2.1.1 的阅读视图用于阅读和选择文字;修改段落、列表与表格时,请在源码中操作。切回阅读视图可以预览尚未保存的编辑,但仍需执行保存才能写入文件。
+
+## 标题、强调和链接
+
+下面这段可以作为一个简单说明文档:
+
+```markdown
+# 项目说明
+
+## 开始使用
+
+请先阅读 **安装步骤**,再运行开发服务。
+
+需要特别注意的地方可以写成 *斜体*。
+
+运行 `npm run dev` 后,打开终端显示的地址。
+
+[返回首页](README.md)
+```
+
+`#`后面保留一个空格。使用 `##`和 `###`划分子章节,右侧目录会根据这些标题更新。
+
+## 列表和任务清单
+
+```markdown
+1. 安装依赖。
+2. 启动服务。
+3. 打开浏览器。
+
+- 开发环境
+- 测试环境
+
+- [x] 准备配置
+- [ ] 运行测试
+```
+
+完成任务时,在源码中将 `[ ]`改为 `[x]`,保存后查看阅读效果。阅读视图中的任务框用于展示完成状态,不作为修改文件的复选框。
+
+## 代码块
+
+用三条反引号包围代码,在第一行反引号后注明语言。下面的围栏内层是一段完整的 Markdown 示例:
+
+````markdown
+```sh
+echo Hello, Pebrel
+```
+````
+
+阅读时会显示代码排版,并提供复制按钮。常见语言可写 `sh`、`powershell`、`python`、`rust`、`json`或 `lua`。
+
+## 表格
+
+```markdown
+| 环境 | 地址 | 状态 |
+| --- | --- | --- |
+| 开发 | localhost | 运行中 |
+| 测试 | test.example.com | 待检查 |
+```
+
+每行用 `|`分隔单元格,第二行定义表头分隔线。新增一行时,在源码中按相同列数补一行;需要在单元格显示竖线时,写成 `\|`。
+
+## 图片
+
+```markdown
+
+```
+
+括号内是相对当前 Markdown 文件的图片路径。分享文档时,把被引用的图片目录一起保留。图片无法显示时,检查路径大小写和文件是否存在。
+
+## 数学公式
+
+行内公式用 `$...$`,独立公式用 `$$`围起:
+
+```markdown
+直角三角形满足 $a^2+b^2=c^2$。
+
+$$
+\frac{1}{2}+\frac{1}{3}=\frac{5}{6}
+$$
+```
+
+切回阅读视图检查排版。复杂 LaTeX 的支持范围以实际渲染为准;不正常的表达式可先缩小成一个简单公式,再逐步添加内容。
+
+## 撤销和处理保存冲突
+
+在源码编辑状态下,**Ctrl+Z / ⌘Z**撤销,**Ctrl+Shift+Z / ⌘⇧Z**重做。保存使用 **Ctrl+S / ⌘S**。
+
+如果其他程序已经修改了文件,保存可能提示冲突。先复制当前编辑内容,再重新读取磁盘版本,比较后合并需要保留的部分。不要直接重读并丢掉尚未保存的文字。
diff --git a/docs/site/content/migration.md b/docs/site/content/migration.md
new file mode 100644
index 000000000..08b86415b
--- /dev/null
+++ b/docs/site/content/migration.md
@@ -0,0 +1,55 @@
+新版 `main` 中的 **设置 → 备份** 支持加密快照与选择性恢复,使用步骤和适用范围见[加密备份与恢复](backups.md)。本页保留手动备份与跨电脑迁移的检查步骤。
+
+## 找到个人数据目录
+
+| 系统 | 标准位置 |
+| --- | --- |
+| Windows | `%APPDATA%\Pebrel` |
+| macOS | `~/Library/Application Support/Pebrel` |
+| Linux | `$XDG_CONFIG_HOME/pebrel`,未设置时通常为 `~/.config/pebrel` |
+
+Windows 可以把路径粘贴到资源管理器地址栏;macOS 可在 Finder 的“前往文件夹”中输入路径。使用 `PEBREL_CONFIG_DIR`时,以指定目录为准。
+
+## 备份哪些内容
+
+先正常退出 Pebrel,再复制个人数据目录到安全位置。常见文件包括:
+
+| 内容 | 文件或位置 |
+| --- | --- |
+| 界面偏好和快捷键 | `pebrel_settings.txt` |
+| 保存的常用命令 | `saved_commands.json` |
+| 最近会话布局 | `session.json` |
+| SSH 配置记录 | `ssh_profiles.json`,及主机库的相关数据 |
+| Lua / TOML 终端配置 | 实际加载的 `pebrel.lua`或对应配置文件 |
+| 背景、额外字体和主题素材 | 保留使用中的素材及其路径 |
+
+整目录备份适合自己的恢复用途。需要发给别人或上传仓库时,改为挑选必要的脱敏文件,排除凭据、历史敏感信息及 `runtime.port`等运行时发现文件。
+
+## 迁移到另一台电脑
+
+1. 在旧电脑退出 Pebrel,备份数据与自定义配置。
+2. 在 SSH 主机库导出 CSV,需要分享或单独迁移的主题使用主题导出。
+3. 在新电脑安装 Pebrel、常用 Shell、字体和 AI CLI。
+4. 放回需要的个人配置,修正旧电脑上的程序和项目路径。
+5. 重新配置系统凭据、私钥位置和需要的账户登录。
+6. 新建终端、连接一台主机,再检查命令库和布局。
+
+跨系统迁移时,不要直接沿用另一系统的绝对路径。主题颜色通常可保留,字体、壁纸和 Shell 路径需要在新系统中重新确认。
+
+## SSH 密码与私钥
+
+CSV 只包含地址、名称和分类信息,不携带密码、私钥或私钥口令。系统凭据库中的内容也不会通过复制应用目录自动迁移。
+
+私钥应使用安全方式单独迁移,并保持恰当的访问权限;在新电脑上编辑主机条目,重新选择私钥并测试连接。不要把私钥放进公开仓库或普通分享压缩包。
+
+## 从 Nebula 升级
+
+Pebrel 会在新位置缺少相应文件时尝试复制旧版数据,保留旧文件,不覆盖已有 Pebrel 数据。首次启动后先检查主题、主机和命令,再清理旧环境。
+
+新旧配置同时存在时,检查实际加载的文件。使用 `pebrel config check`可以发现语法问题;配置选择规则见[Lua 配置](configuration.md)。
+
+## 还原备份
+
+先退出应用并保留当前数据副本,再恢复准备使用的文件。不要恢复旧的运行时控制端口或 Token 文件;让新进程自行建立。
+
+恢复后检查目录权限,运行配置检查,再新建终端验证。AI CLI 的对话正文需要按各工具自己的方式备份和恢复,不包含在 Pebrel 的标签布局中。
diff --git a/docs/site/content/mobile.md b/docs/site/content/mobile.md
new file mode 100644
index 000000000..394f85e2e
--- /dev/null
+++ b/docs/site/content/mobile.md
@@ -0,0 +1,67 @@
+> [!NOTE]
+> 本页按 Pebrel 2.1.1 核对,面向带有 **手机远程** 设置的桌面版本(2.0 起提供)和匹配的 Android 客户端。2.1.1 的发行版提供 `Pebrel-v2.1.1-android-universal-preview.apk`,下载见[项目发行版](https://github.com/Kuddev/pebrel/releases)。桌面和手机端的版本需要匹配,旧版本不支持这些流程。
+
+## 准备连接
+
+手机可以查看电脑上运行的任务,并在获准后发送终端输入。**命令仍在电脑上执行**:电脑需要保持运行和网络可达,手机不会在断线后接管电脑的进程。
+
+先准备已安装的 Android 客户端和电脑上的 Pebrel。下面使用 **局域网 / Tailscale** 连接:
+
+- 同一 Wi-Fi 或局域网内,两台设备需要能够互相访问
+- 使用 Tailscale 时,两端需要加入可互通的 Tailnet,并选手机可访问的电脑地址
+- 网络隔离、系统防火墙或电脑休眠可能阻止连接;不要为配对把本机运行时控制端口直接公开到互联网
+
+当前 Android 项目的最低版本为 Android 8.0(API 26)。这里描述 Android 流程,不代表提供了同样的 iOS 客户端。
+
+## 在电脑上开始配对
+
+1. 打开 **设置 → 手机远程**,点 **开启并配对手机**。
+2. 选择 **局域网 / Tailscale**。
+3. 在 **网卡** 中选手机可达的地址;**监听端口** 可留空,由程序选择。
+4. 保持配对页面打开,准备扫描二维码或复制配对信息。
+
+二维码单次使用,10 分钟后失效。过期或已经用过时,点 **换一个** 生成新的配对信息,不要反复使用旧截图。二维码和完整配对信息都应只交给自己的设备。
+
+## 在 Android 上连接电脑
+
+打开手机的 **连接电脑**,选择一种方式:
+
+| 方式 | 操作 | 适用情况 |
+| --- | --- | --- |
+| **扫码** | 允许相机,扫描电脑上的二维码 | 手机能看到电脑屏幕 |
+| **8 位配对码** | 选择同一局域网发现的电脑,输入二维码下方的 8 位数字 | 本地发现已经找到正确电脑 |
+| **粘贴** | 电脑点 **复制完整配对信息**,在手机粘贴,再点 **导入并连接** | 不方便使用相机或局域网发现 |
+
+拒绝相机权限后仍可使用配对码或粘贴。没有发现电脑时,先核对网络与网卡,再尝试扫码或粘贴;不要把 8 位码当作可以跨任意网络寻找电脑的地址,Tailscale 连接也不保证自动发现。
+
+## 核对校验码并批准
+
+手机显示 **等待电脑批准** 后,在两端核对校验码。只有内容一致、而且确实是自己刚发起的配对,才在电脑点 **批准**;不一致或不认识的请求应点 **拒绝**。
+
+8 位配对码用于发起连接,批准时的校验码用于核对这次配对,它们不是同一个用途的码。不要仅因输入过 8 位码就跳过电脑批准。
+
+## 从只看改为允许输入
+
+首次使用时,**新手机的默认权限** 为 **只看**;如果你曾修改过该默认值,配对后先核对这台手机的实际权限。先在手机查看正确的终端,确认任务和电脑对应。
+
+确实需要远程输入时,在电脑 **已配对的手机** 中,把该手机的权限改为 **允许输入**。发送前核对目标终端、当前目录和正在运行的程序;发到普通 Shell 的文字与发到 AI CLI 的文字可能产生不同结果。
+
+只看权限并不允许手机发送终端输入。需要收回操作权限时,在电脑改回 **只看**,不必重新配对。
+
+## 暂停连接或移除手机
+
+- **暂停**:停止监听并断开手机,但保留已经建立的配对
+- **移除**:撤销这台手机的授权,下次连接需要重新配对
+
+丢失手机或不再使用该设备时,应在电脑移除它。只退出手机页面不等于撤销电脑上的配对授权。
+
+## 连不上时按顺序检查
+
+1. 电脑是否正在运行、未休眠,**手机远程** 是否开启而非暂停。
+2. 所选网卡地址是否能从手机访问,网络是否隔离设备。
+3. 二维码是否超过 10 分钟或已经用过;需要时生成新的配对信息。
+4. 电脑是否仍有待批准请求;核对校验码后处理。
+5. 只有输入不可用时,检查这台手机是否仍是 **只看**。
+6. 切换 Wi-Fi 或 Tailscale 地址后,核对实际连接地址;必要时使用新的配对信息。
+
+桌面和手机版本差异较大时,先使用匹配版本再排查。与 SSH 服务器建立终端连接是另一种工作流,见[SSH 连接](ssh.md)。
diff --git a/docs/site/content/navigation.md b/docs/site/content/navigation.md
new file mode 100644
index 000000000..e3243b560
--- /dev/null
+++ b/docs/site/content/navigation.md
@@ -0,0 +1,27 @@
+## 打开快速跳转
+
+按 **Ctrl+Shift+O**(macOS 为 **⌘⇧O**)。输入名称或关键字,使用方向键选中结果,按 Enter 打开;按 Esc 返回工作区。
+
+快速跳转把已有终端、常用目录、SSH 主机和支持的 AI 会话历史集中到同一个查找入口。
+
+## 找到已经打开的终端
+
+输入标签名称或相关关键字,选择已有标签或窗格结果。Pebrel 会切换到它所在的位置,原来运行的程序继续保留。
+
+标签很多时,先为重要终端[重命名](workspace.md),例如“测试日志”和“生产只读”,之后就能按名称查找。
+
+## 从目录重新开始工作
+
+查找已经记录的常用目录,选择对应目录结果打开终端。打开后运行 `pwd` 确认位置,再执行项目命令。
+
+这里列出的是 Pebrel 已知的目录。本地终端成功启动后,它的起始目录会自动加入这个列表;SSH 连接和 WSL 里的路径不会被当作本机目录记录。第一次使用一个尚未记录的路径,可以先在终端 `cd` 进入,或从文件树使用 **在此处打开终端**。
+
+## 连接主机或继续 AI 对话
+
+选择 SSH 主机结果可打开对应连接;认证信息缺失时,按提示补充。主机名称和分组可在[SSH 主机库](ssh-library.md)中整理。
+
+选择 AI 历史结果会尝试通过相应 CLI 恢复会话。会话所属环境需要具备可用的工具和记录,具体见[AI 会话历史](ai-history.md)。
+
+## 查找文件
+
+需要在目录中定位文件时,打开[文件树](files.md)并使用它的搜索框。该搜索筛选文件名称;需要搜索文件内容时,可以在终端使用项目已有的搜索工具,例如 `rg`。
diff --git a/docs/site/content/network.md b/docs/site/content/network.md
new file mode 100644
index 000000000..904861435
--- /dev/null
+++ b/docs/site/content/network.md
@@ -0,0 +1,50 @@
+## 设置 Pebrel 的网络代理
+
+打开 **设置 → 网络**,在 **代理方式**中选择:
+
+| 方式 | 作用 |
+| --- | --- |
+| **不使用代理** | 使用直接连接 |
+| **跟随系统** | 使用检测到的系统代理配置 |
+| **自定义代理** | 使用自己填写的代理协议与地址 |
+
+选择自定义代理后,填写代理地址并选择协议。例如,本机 SOCKS5 服务监听 `127.0.0.1:1080`时,选择对应协议并填写这个地址。实际端口以自己的代理软件为准。
+
+## 测试当前配置
+
+1. 完成代理方式、协议和地址输入。
+2. 点击 **测试网络**。
+3. 查看返回的路线、耗时或错误文字。
+4. 修改后重新测试,确认使用的是新的配置。
+
+显示网络连接正常,说明本次测试路线可访问测试目标。某个 SSH 账户或 AI 服务仍有问题时,继续在对应连接或工具中测试。
+
+## 让新终端接入系统代理
+
+网络页还有独立的 **系统代理**开关,用于 Windows 的新建终端:开启后,新终端会使用当前 Windows 系统代理。如果你已经在 **代理方式** 里选了 **自定义代理** 并填写了地址,新开的终端会直接使用这个地址,不必再打开这个开关。PowerShell 5 和 7 的 HTTP 请求也会使用这个 HTTP 代理。
+
+开启后新建一个窗格,再启动需要联网的工具;已经运行的 Shell 和 CLI 不会自动得到重新创建的进程环境。
+
+这个开关与上面的网络代理方式分别控制。CLI 也可能使用自己的网络设置,出现问题时同时检查工具配置。
+
+## 为某个 SSH 主机覆盖代理
+
+编辑 SSH 主机,打开 **高级**页,选择跟随全局、不使用或自定义代理。只有某一台服务器需要直连时,修改该主机即可。
+
+带代理认证或跳板的连接,按[代理与跳板](ssh-routing.md)填写。连接规则预览可以帮助确认最终路线。
+
+## 在 WSL 或服务器中访问网络
+
+工具运行在 WSL 或 SSH 服务器时,网络请求从那个环境发出。尤其是 SSH 服务器上的 `127.0.0.1`指服务器自己,不是你的电脑。
+
+先在实际运行工具的环境中检查代理地址和可达性,再启动 CLI。不要把 Windows 上一次成功的测试当作远端服务也已配置完成。
+
+## 常见失败
+
+**连接被拒绝:**检查代理程序是否运行、协议和端口是否匹配。
+
+**超时:**检查当前网络、VPN、代理到目标的路线和防火墙。
+
+**某个工具仍无法联网:**新建终端重试,并检查工具自己的代理、证书或账户设置。
+
+反馈问题时保留协议、脱敏地址和错误文字,移除代理密码和 Token。
diff --git a/docs/site/content/notifications.md b/docs/site/content/notifications.md
new file mode 100644
index 000000000..b4821f71e
--- /dev/null
+++ b/docs/site/content/notifications.md
@@ -0,0 +1,35 @@
+## 开启 AI 消息提示
+
+打开 **设置 → 终端 → 提醒**,调整 AI 消息通知开关。任务需要关注时,可以通过通知回到对应窗格查看,而不必一直盯着输出。
+
+需要更准确的任务事件时,先完成[Agent 集成](hooks.md)。通知开关控制显示,Agent 集成负责提供支持的活动事件。
+
+## 调整通知停留时间
+
+在同一分组的通知时长选项中选择:**使用默认值**、**5 秒**、**10 秒**、**30 秒**、**90 秒**或 **直到手动关闭**。
+
+使用默认值时,短提示停留 5 秒、消息横幅停留 90 秒,更新通知保留到关闭。更改时长后,新出现或被刷新的应用内卡片使用新设置。
+
+
根据需要选择短暂提示或手动关闭。
+
+## 回到发出通知的终端
+
+点击通知中的来源操作,Pebrel 会返回对应窗格。阅读 CLI 里的原始问题,完成确认、授权或补充输入。
+
+关闭卡片只会隐藏通知;仍待处理的请求留在终端中。忽略了更新通知,也可以回到 **设置 → 应用**重新查看。
+
+## 为什么旧卡片不见了
+
+应用内最多保留最近三张卡片。新卡片出现时,较旧的卡片可能被替换,即使选择了手动关闭也一样。
+
+需要回看任务内容时,到来源终端或工具历史中查找,不依赖通知卡片作为日志。
+
+## 终端铃声
+
+**终端铃声**可以选择关闭、闪烁、声音或相应组合,用于响应程序发出的提醒。声音效果受当前平台支持情况影响;需要安静工作时,可优先选择关闭或闪烁。
+
+## 系统通知没有出现
+
+先确认应用内提示是否正常,再检查系统给 Pebrel 的通知权限、勿扰模式以及 Linux 桌面的通知服务。系统通知的停留时间由操作系统控制,不随应用内卡片时长改变。
+
+如果连工具状态都不更新,先检查 CLI 是否已在配置集成后重新启动。
diff --git a/docs/site/content/palette.md b/docs/site/content/palette.md
new file mode 100644
index 000000000..b06618c3d
--- /dev/null
+++ b/docs/site/content/palette.md
@@ -0,0 +1,30 @@
+## 按名称查找操作
+
+按 **Ctrl+Shift+P**(macOS 为 **⌘⇧P**)打开命令面板。在搜索框输入想做的操作,例如“设置”“分屏”或“布局”。
+
+使用方向键选择结果,按 **Enter**执行;按 **Esc**关闭面板。暂时不记得快捷键时,可以先从这里查找。
+
+## 打开设置或创建布局
+
+例如,要保存当前窗口布局:
+
+1. 打开命令面板,输入“布局”。
+2. 选择 **保存当前窗口布局…**。
+3. 在布局配方中输入名称并保存。
+
+下次使用时,在命令面板选择 **打开布局配方…**,再恢复已保存的布局。完整流程见[布局配方](layouts.md)。
+
+## 选择合适的查找入口
+
+| 需要找到的内容 | 使用的入口 |
+| --- | --- |
+| 打开设置、切换面板等应用动作 | 命令面板:Ctrl+Shift+P / ⌘⇧P |
+| PowerShell、WSL 等启动入口 | Shell 选择器:Ctrl+K / ⌘K |
+| 已开的标签、常用目录、SSH 主机和 AI 历史 | 快速跳转:Ctrl+Shift+O / ⌘⇧O |
+| 自己保存的命令文字 | 顶栏的闪电图标 |
+
+命令面板用于执行应用动作。要运行 `git status` 等 Shell 命令,回到终端输入,或从[保存命令](commands.md)插入。
+
+## 找不到某个动作
+
+先尝试更短的关键字,并确认当前打开的是命令面板。部分动作需要先聚焦一个终端标签;文档标签、没有分屏的标签和不同系统可用的动作可能不同。全局快速终端和托盘设置在 Windows、macOS 和 Linux 上都有,Linux 的托盘需要桌面提供状态通知器。
diff --git a/docs/site/content/privacy.md b/docs/site/content/privacy.md
new file mode 100644
index 000000000..7049ebb1f
--- /dev/null
+++ b/docs/site/content/privacy.md
@@ -0,0 +1,37 @@
+## 哪些内容保存在本机
+
+Pebrel 的界面偏好、命令条目、主机记录和会话布局存放在个人数据目录中。背景图片和本地文档仍位于各自路径;图片粘贴会额外产生 PNG 副本。
+
+SSH 密码等保存到对应的系统凭据库。具体目录与备份范围见[备份与迁移](migration.md)。
+
+## 内容什么时候会发送出去
+
+连接 SSH 时,认证与终端输入发送给目标服务器;SFTP 上传和远端图片粘贴会传输所选文件。使用 **发送到聊天**时,选区与问题会交给所选 AI 窗格。
+
+AI CLI 可能再把提示、文件或截图发送到其服务提供方。具体范围由工具的权限、配置和服务决定,发送前检查当前项目、目标主机和授权提示。
+
+## 备份与手机远程
+
+加密备份先在本机加密,再保存到你选择的位置,存储服务只能看到密文;SSH 私钥以及系统凭据库中的密码和 API Key 不会被包含。手机远程只有在你扫码并批准后才会连接,手机与电脑之间使用端到端加密,自建中转只转发密文,看不到终端内容。详见[加密备份](backups.md)和[Android 连接电脑](mobile.md)。
+
+## 分享配置或截图前
+
+移除密码、Token、私钥、带认证的代理地址以及不需要公开的服务器信息。检查保存命令里是否包含凭据,截图中的终端输出是否包含私人数据。
+
+分享 SSH 地址与分类时,使用主机库的 CSV 导出;它不包含密码和私钥。分享主题时,检查其中的本机路径是否需要清除。
+
+## 本机自动化的控制文件
+
+`runtime.port`等发现文件包含本机运行时连接信息和控制凭据。不要提交到仓库、发给其他人或将控制端口转发到公网。
+
+使用自动化脚本时,先列出窗格并核对目标,再发送命令。不要让脚本仅根据当前焦点决定修改哪个项目。
+
+## 清理不再需要的数据
+
+从对应的设置或列表删除不用的命令、主机或布局。图片粘贴产生的本机和远端副本,需要按实际保存位置分别清理。
+
+删除本机文件不会撤回已经上传到服务器或交给 AI 服务的内容。工具自己的历史与云端记录,应在该工具或服务中处理。
+
+## 文档网站的搜索
+
+本网站的全文搜索在浏览器内运行,不向外部搜索服务发送查询。点击 GitHub、下载或其他外部链接时,会进入相应站点,并适用其自身的数据处理方式。
diff --git a/docs/site/content/quick-terminal.md b/docs/site/content/quick-terminal.md
new file mode 100644
index 000000000..b9d9eaaea
--- /dev/null
+++ b/docs/site/content/quick-terminal.md
@@ -0,0 +1,31 @@
+## 设置全局热键
+
+快速终端在 Windows、macOS 和 Linux 上都可以使用。设置完成后,可以在其他应用中按组合键唤起 Pebrel。
+
+1. 打开 **设置 → 按键映射**。
+2. 找到 **快速终端**,录入准备使用的组合键。
+3. 在 **快速终端打开方式**中选择需要的模式。
+4. 切换到其他应用,按一次热键检查唤起效果,再按一次检查隐藏行为。
+
+如果提示热键注册失败,换一个没有被系统或其他应用占用的组合。Linux 的 Wayland 桌面通过系统的快捷键门户注册热键,首次可能会弹出授权提示,需要在系统弹窗中允许。只在 Pebrel 窗口内生效的普通快捷键,不能代替这个全局热键。
+
+## 选择打开方式
+
+| 模式 | 适合的使用方式 |
+| --- | --- |
+| **独立窗口** | 随时输入几条短命令,不打断主工作区 |
+| **唤起已有窗口** | 回到已经打开的项目和终端 |
+
+“唤起已有窗口”会召回已有工作区,不会每次都额外创建一个标签页。选择独立窗口后,可以按需要调整它的窗口大小。
+
+## 从托盘重新打开窗口
+
+打开 **设置 → 高级 → 会话生命周期**,开启 **常驻系统托盘图标**。之后可以从系统托盘(macOS 为菜单栏)中的 Pebrel 入口重新显示窗口。Linux 的托盘需要桌面环境提供状态通知器,没有它时托盘图标可能不显示。
+
+希望关闭窗口后仍保留运行中的任务,请同时开启 **关窗后保留后台会话**。隐藏窗口后,任务会继续输出;从托盘或热键唤回时,可以接着查看。
+
+## 完全退出
+
+需要结束 Pebrel 时,使用退出应用的操作,而不是仅关闭一个设置为后台保留的窗口。保存文档并结束需要处理的任务后再退出;应用进程结束后,全局热键也不再驻留。
+
+会话恢复设置见[会话保存与恢复](sessions.md)。
diff --git a/docs/site/content/quickstart.md b/docs/site/content/quickstart.md
new file mode 100644
index 000000000..618197c37
--- /dev/null
+++ b/docs/site/content/quickstart.md
@@ -0,0 +1,68 @@
+## 安装并打开 Pebrel
+
+从[安装与平台支持](installation.md)选择与你的系统和处理器匹配的安装包。首次打开后,Pebrel 会启动一个终端。看到提示符和闪烁的光标后,就可以输入命令。
+
+在终端中输入下面这行内容,再按 **Enter**:
+
+```sh
+echo Hello, Pebrel
+```
+
+如果下一行显示 `Hello, Pebrel`,随后出现新的提示符,终端已经可以正常使用。
+
+## 打开项目目录
+
+输入 `cd`,后面跟项目的路径。路径包含空格时,用引号包起来。下面两行任选一行,并把路径改成自己的项目位置。
+
+**Windows PowerShell:**
+
+```powershell
+cd "C:\Projects\my-project"
+```
+
+**macOS、Linux 或 WSL:**
+
+```sh
+cd ~/Projects/my-project
+```
+
+输入 `pwd` 可以查看当前目录。在 Windows 命令提示符(cmd)中,使用不带参数的 `cd` 查看目录。
+
+需要切换终端程序时,按 **Ctrl+K**(macOS 为 **⌘K**)打开 Shell 选择器,再选择已安装的 Shell。默认 Shell 和启动目录可以在 **设置 → 终端** 中调整。
+
+## 再开一个终端
+
+运行开发服务时,原终端可能一直显示日志。另开一个标签页,就能继续输入其他命令。
+
+| 操作 | Windows / Linux | macOS |
+| --- | --- | --- |
+| 新建标签页 | Ctrl+Shift+T | ⌘T |
+| 向右分屏 | Ctrl+Shift+D | ⌘D |
+| 向下分屏 | Ctrl+Shift+S | ⌘⇧D |
+| 放大当前窗格,再按一次还原 | Ctrl+Shift+Enter | ⌘⇧Enter |
+
+点击要使用的窗格后再输入。新建分屏会启动另一个 Shell,你可以在里面切换到其他目录或运行不同程序。
+
+
通过标签页切换终端;需要同时查看时,可在一个标签页内分屏。
+
+## 连接服务器
+
+打开 **设置 → SSH**,选择 **添加 SSH 主机**,填写地址、用户名和认证信息。保存后,从主机列表打开连接。
+
+首次连接会要求确认服务器指纹。与服务器管理员提供的指纹核对一致后,再继续登录。完整示例见[连接第一台 SSH 主机](ssh.md)。
+
+## 启动 AI 命令行工具
+
+已经安装并登录 Claude Code 或 Codex 时,可以直接在项目终端中运行 `claude` 或 `codex`。先试一个范围明确的任务,例如“介绍这个项目的目录结构,先不要修改文件”。
+
+Pebrel 会为识别出的工具显示图标和活动状态。如何查看回答、找回历史对话,见[使用 AI 命令行工具](ai-start.md)。
+
+## 调整字体和外观
+
+点击窗口中的设置按钮,打开 **外观**。文字太小时,先调整 **终端字号**;侧栏、菜单和按钮的文字则由 **界面字号** 控制。主题、字体和行高的详细设置见[外观](appearance.md)。
+
+## 结束工作
+
+运行中的命令通常可以按 **Ctrl+C** 停止;在 Windows / Linux 中有文字选中时,先点击终端空白处清除选区,再按 Ctrl+C。出现提示符后,输入 `exit` 退出 Shell。
+
+希望下次打开时恢复标签页和目录,可以在 **设置 → 高级 → 会话生命周期** 开启 **启动时恢复上次标签**。需要关窗后继续运行任务,请另行开启[后台会话保留](sessions.md)。
diff --git a/docs/site/content/readme.md b/docs/site/content/readme.md
new file mode 100644
index 000000000..51f1c19a3
--- /dev/null
+++ b/docs/site/content/readme.md
@@ -0,0 +1,101 @@
+
+
GPU 加速终端、SSH 工作区,以及 AI CLI 会话空间。
+
Pebrel 把本地 Shell、远程主机、文件和 AI 命令行工具集中在同一个原生桌面工作区。这个页面把仓库 README 中最常用的信息重新组织成可以快速浏览的图文说明。
+
+
+Rust 2024GPUIWindows 10 / 11macOS 14+ PreviewLinux glibc 2.35+ PreviewGPL-3.0
+
+## 一个工作区里完成什么
+
+
+
TERMINAL终端与会话用标签页和分屏组织多个 Shell;每个窗格保留自己的工作目录,并可保存常用工作区布局。
+
REMOTESSH 与文件保存远端主机,通过 SSH 连接服务器,并在终端旁使用 SFTP 上传、下载和整理文件。
+
AI CLIAI 命令行工作流在独立标签或分屏中运行受支持的 AI CLI,通过活动状态、通知和历史记录跟踪任务。
+
READER原生阅读与配置阅读 Markdown、公式和本地图片,使用主题、背景、快捷键与 Lua 配置调整工作环境。
+
+
+
用标签页组织多个终端,并在同一个窗口里保持工作上下文。
+
+
多个命令行任务可以并排运行;每个窗格保持独立输入和输出。
+
+## 平台与下载
+
+从[最新发行版](https://github.com/Kuddev/pebrel/releases/latest)选择与你的系统和架构对应的安装包。
+
+| 平台 | 当前支持 | 安装包 |
+| --- | --- | --- |
+| Windows 10 1809+ / 11 | 正式版,x64 / ARM64 | .exe 安装器或 .zip 便携包 |
+| macOS 14+ | Preview,Apple Silicon / Intel | .dmg |
+| Linux,glibc 2.35+ | Preview,x64 | .AppImage、.deb 或 .tar.gz |
+| Android 8.0+ | Preview,手机端 | .apk,用于[连接电脑](mobile.md) |
+
+Pebrel 2.1 在 Windows、macOS 和 Linux 上都提供系统托盘、全局快速终端热键、登录启动和本地 AI 集成自动配置;Windows 和 macOS 还可以在应用内安装更新,Linux 通过包管理器或新安装包升级。细节见[安装与平台支持](installation.md)。
+
+## 终端与会话
+
+- 侧栏或顶部标签管理终端,并可拖拽调整分屏。
+- 每个窗格可以拥有独立工作目录;复制部分远端或子系统标签时会保留已知目录。
+- 内置智能补全:从当前 Git 仓库、项目脚本、SSH 配置别名、文件目录获取候选(Windows 还包括已注册的 WSL 发行版),也支持历史补全,见[命令补全](completions.md)。
+- 可选择关窗后继续保留后台会话;应用真正退出后的对话恢复属于另一套机制。
+
+要实际配置这些行为,参见[标签页与分屏](workspace.md)、[保存与恢复会话](sessions.md)和[快捷键速查](keyboard.md)。
+
+## SSH 与文件
+
+Pebrel 可以保存主机、读取 SSH 配置别名,并使用代理或单级跳板。认证可使用密码、私钥及服务器支持的交互流程,首次连接时应核对主机密钥。
+
+SFTP 面板用于浏览远端目录、上传与下载文件或文件夹、查看传输进度并取消任务。本地文件浏览、Git 操作和远端文件编辑可以与终端同时进行。
+
+
终端、文件与远端连接围绕同一工作区组织。
+
+## 手机与备份
+
+2.0 起,Android 客户端可以连接电脑,查看正在运行的任务、在获准后发送输入并接收提醒,命令仍在电脑上执行,见[Android 连接电脑](mobile.md)。设置、SSH 主机和工作区布局可以先在本机加密,再备份到本地目录、WebDAV、S3 兼容存储或 SSH 主机,见[加密备份](backups.md)。
+
+## AI CLI 工作流
+
+Pebrel 会识别多种 AI CLI,并在受支持时显示活动状态与更精确的任务提示,各工具的支持范围见[支持的 AI 命令行工具](agents.md)。通知与来源窗格关联,点击后可以回到对应终端。
+
+已捕获的回答可以在阅读器中查看 Markdown、公式、原文和本地图片。向终端粘贴图片时,Pebrel 会把图片保存为文件并把路径交给当前会话;终端内联显示是否可用取决于命令行工具输出的协议和内容。
+
+
AI CLI 与普通 Shell 一样运行在终端中,同时可使用会话相关的辅助能力。
+
+## 外观、文档与配置
+
+Pebrel 提供浅色与深色主题、背景、不透明度、图标和界面语言设置。Markdown 文档可以直接在应用内阅读,数学公式由原生界面排版。
+
+
文档阅读器可以显示 Markdown 内容和数学公式。
+
+使用命令行初始化并检查 Lua 配置:
+
+~~~sh
+pebrel config init --language zh-CN
+pebrel config check
+~~~
+
+配置重载失败时会继续使用上一份有效配置。完整字段和示例参见[使用 Lua 配置](configuration.md)与[常用配置示例](config-examples.md)。
+
+## 通知
+
+在 **设置 → 终端 → 提醒** 中可以选择通知显示时长:保留默认时长、5 / 10 / 30 / 90 秒,或保持常驻。隐藏通知卡片只会关闭显示,不会自动执行确认、拒绝或其他任务操作。
+
+## 构建 Pebrel
+
+安装仓库固定的 Rust 工具链和平台依赖后,README 给出的正式产品构建命令为:
+
+~~~sh
+cargo build --release --locked -p pebrel --bin pebrel --features gpui-shell
+~~~
+
+准备参与开发时,请继续阅读[贡献与开发](contributing.md),按照仓库规定运行相应检查。
+
+## 赞助、社区与联系
+
+- **赞助**:README 当前感谢 Fluxion AI 对项目的支持。
+- **社区**:可通过项目 README 中列出的社区入口参与讨论。
+- **Discord**:[discord.gg/VFn4rcxmhn](https://discord.gg/VFn4rcxmhn)
+- **邮箱**:[fickleheartedkeys@163.com](mailto:fickleheartedkeys@163.com)
+- **许可证**:GPL-3.0;第三方版权和许可证声明以仓库内对应文件为准。
+
+> [!NOTE]
+> 本页是 README 的文档化导览,不替代仓库 README。版本、下载文件和社区入口发生变化时,以仓库当前内容和最新发行版为准。
diff --git a/docs/site/content/remote-edit.md b/docs/site/content/remote-edit.md
new file mode 100644
index 000000000..68b562e6c
--- /dev/null
+++ b/docs/site/content/remote-edit.md
@@ -0,0 +1,41 @@
+## 打开远端文本文件
+
+建立内置 SSH 连接,进入[SFTP 文件列表](sftp.md),打开要修改的文本文件。编辑器标题包含文件名和目标主机,先确认两者再编辑。
+
+远端 Markdown 以源码打开,避免把服务器上的相对资源路径当作本机文件加载。
+
+## 保存回服务器
+
+1. 修改所需内容。
+2. 点击 **保存**,或按 **Ctrl+S / ⌘S**。
+3. 等待“正在保存”结束,查看保存状态。
+4. 必要时在远端终端中读取文件,确认服务器上的结果。
+
+保存目标是打开文件时的原主机和路径。切换到其他 SSH 窗格,不会将这个文件改存到另一台服务器。
+
+## 连接断开或权限不足
+
+网络断开时,先恢复 SSH 连接;权限不足时,检查当前账户是否可以写入该文件及所在目录。编辑器不会自动提权为管理员账户。
+
+错误提示出现后,保留当前编辑内容,再处理问题并保存。重要修改可以先复制到本地文件,防止关闭应用后丢失。
+
+## 文件已经被其他人修改
+
+保存前检查到服务器文件发生变化时,Pebrel 会报告冲突。此时:
+
+1. 复制当前尚未保存的内容。
+2. 重新读取远端文件,查看最新版本。
+3. 合并双方需要保留的修改。
+4. 再次保存并检查结果。
+
+如果文件由部署程序或其他编辑器自动生成,应先暂停相关修改流程,避免不断覆盖。
+
+## 取消读取或保存
+
+远端操作进行时,工具栏提供取消入口。点击后等取消状态结束,再开始下一次操作。取消后可以重新读取远端文件,确认服务器上实际保留的版本。
+
+## 只读文件
+
+超过 **8 MB**的文件可能只预览开头,无法在此保存;非完整 UTF-8 文本也可能只读。此时可以下载后用合适的编辑器处理,或在远端终端使用服务器上的工具。
+
+关闭仍有未保存内容的标签时,按提示选择保存、放弃或取消。文件尚未成功保存前,不要只根据终端连接恢复就关闭编辑器。
diff --git a/docs/site/content/runtime.md b/docs/site/content/runtime.md
new file mode 100644
index 000000000..33618cf8b
--- /dev/null
+++ b/docs/site/content/runtime.md
@@ -0,0 +1,95 @@
+## 查看当前终端与运行状态
+
+在 Pebrel 的本地终端运行:
+
+```sh
+pebrel env --pretty
+pebrel ctl describe --pretty
+pebrel pane list
+```
+
+`env`显示调用环境,`describe`列出当前运行时支持的能力,`pane list`列出可以定位的窗格。后续命令中的窗格 ID,要使用实际列表里的值。
+
+命令找不到时,检查当前环境是否为本地 Pebrel 窗格,以及 `PEBREL_CLI`指向的程序。SSH 服务器上不会自动安装本机的 Pebrel CLI。
+
+## 读取另一个窗格的输出
+
+假设目标窗格 ID 为 `17`,读取最近 80 行:
+
+```sh
+pebrel pane read 17 --lines 80
+```
+
+多个窗口中存在相同 ID 时,补充对应的窗口参数。不要固定复用上一次启动中的 ID,关闭并重建窗格后应重新查询。
+
+## 发送一条命令
+
+确认目标停在普通 Shell 提示符,并位于正确项目目录后,发送:
+
+```sh
+pebrel pane send 17 "git status --short" --wait
+```
+
+`send`会提交文本并发送回车,`--wait`等待相应状态变化。只想插入文字供人工检查时,使用 `--no-submit`,不要同时加等待执行结束的选项。
+
+读取窗格输出确认执行结果。等待结束不等于项目测试成功,成功与否仍由实际命令输出和退出状态判断。
+
+## 发送保留换行的文本
+
+将文本写入 UTF-8 文件 `task.txt`,然后执行:
+
+```sh
+pebrel pane paste 17 --from-file task.txt --wait
+```
+
+该方式保留换行,目标需要支持 bracketed paste。文件应是普通文本,输入上限为 32 KiB;不用于发送二进制、控制序列或给远端自动转发本机文件。
+
+## 独立运行一个命令
+
+需要在目标窗格的已知目录执行非交互命令,同时不改变其 Shell 输入时,可以使用:
+
+```sh
+pebrel pane exec 17 -- git status --short
+```
+
+`exec`直接启动独立子进程。命令和参数分别传入,管道、重定向和变量展开不会自动作为 Shell 语法执行。需要交互式程序时,仍应在终端会话中运行。
+
+## 向 AI 工具分配任务
+
+先执行 `pebrel agent list`确认工具名称或稳定 ID,再发送任务。例如,列表中的目标确实名为 `codex`时:
+
+```sh
+pebrel agent send codex "检查当前项目的测试入口,先不要修改文件" --wait
+pebrel agent read codex --lines 80
+```
+
+自动化应使用列表返回的身份,而不是仅根据窗口焦点猜测目标。命名 Agent 和隔离目录的完整示例见[隔离 AI 工作目录](agent-worktrees.md)。
+
+## 管理标签页
+
+标签页的编号按窗口计算,所以必须指定窗口。编号从 0 开始,以 `pebrel ctl snapshot --pretty` 里的值为准:
+
+```sh
+pebrel tab rename 2 "API 日志" --window 1
+pebrel tab move 2 0 --window 1
+pebrel tab close 2 --window 1
+```
+
+`rename` 传入空字符串可以恢复自动标题。`close` 只关闭空闲的标签,里面还有程序在运行时会被拒绝。
+
+## 校验和运行本地插件命令
+
+2.0 起,`pebrel plugin` 可以在不启动窗口的情况下检查或调用一个本地命令插件包:
+
+```sh
+pebrel plugin check ./my-plugin --pretty
+pebrel plugin run ./my-plugin summary --args '{"label":"示例"}' --timeout-ms 3000
+```
+
+`check` 只校验插件的清单和入口路径,不执行 Lua。`run` 每次只调用一个已声明的命令,`--timeout-ms` 取值 1 到 30000,默认 3000。命令按需运行,结束后不会留下常驻的插件进程。这个版本支持命令插件,不包含常驻的插件面板。
+
+## 超时后如何处理
+
+先读取目标状态和最近输出。如果任务已经收到但仍在执行,继续查看或等待;不要立即重复发送同一条任务,以免执行两次。
+
+参数和能力相关错误,可以用 `pebrel ctl describe --pretty`检查当前版本,并参阅[运行时控制参考](https://github.com/Kuddev/pebrel/blob/d574856dae42f7a5142045e0b05f3eb43106fa3d/docs/runtime-control-api.md)。运行时发现文件包含本机控制凭据,不应公开、同步给他人或转发端口。
diff --git a/docs/site/content/send-to-chat.md b/docs/site/content/send-to-chat.md
new file mode 100644
index 000000000..357833bec
--- /dev/null
+++ b/docs/site/content/send-to-chat.md
@@ -0,0 +1,35 @@
+## 把报错交给 AI 分析
+
+先在一个窗格中启动 AI CLI,再在产生报错的终端中操作:
+
+1. 选择需要分析的报错文字。
+2. 右键选区,选择 **发送到聊天**。
+3. 在对话框中检查引用的内容。
+4. 补充问题,例如“请解释这个错误,并指出下一步要检查的文件,先不要修改代码”。
+5. 选择目标 AI 窗格,确认后发送。
+
+消息会将选中的文字作为引用,并附上你的问题。回到目标窗格可以继续查看工具的响应。
+
+## 只发送相关日志
+
+通常保留错误信息、相关命令和附近几行上下文即可。过长的日志可以先缩小选区;缺少上下文时,再补充运行目录、系统或复现步骤。
+
+发送前移除密码、访问令牌、私人路径或其他不应分享的信息。目标工具可能把内容交给它所连接的 AI 服务。
+
+## 选择正确的目标
+
+目标列表显示可接收输入的 AI 窗格,并标出相应工具。远端目标还会显示主机信息,选择之前先核对。
+
+目标需要仍在运行,并处于可接受粘贴消息的状态。工具已经退出、被替换或暂时无法接收时,先回到那个终端处理,再重新打开发送对话框。
+
+## 没有可用目标
+
+检查 AI CLI 是否已启动、是否被 Pebrel 识别,以及当前是否停在等待输入的位置。仍无法使用时,可以先复制整理后的消息,再手动粘贴到工具的输入区。
+
+开启 **选中即复制**后,右键行为可能变为粘贴。需要调出常规选区菜单时,在 **设置 → 交互**关闭该选项,见[剪贴板](clipboard.md)。
+
+## 把内容发送到远端
+
+选择 SSH 上的 AI 窗格时,这段文字会离开本机。确认引用内容允许发送到该服务器,并确认列表中的主机就是预期目标,再提交。
+
+需要发送图片而不是日志时,使用[图片粘贴](images.md)。
diff --git a/docs/site/content/sessions.md b/docs/site/content/sessions.md
new file mode 100644
index 000000000..b383d3e99
--- /dev/null
+++ b/docs/site/content/sessions.md
@@ -0,0 +1,39 @@
+## 下次打开时恢复标签和目录
+
+打开 **设置 → 高级 → 会话生命周期**,开启 **启动时恢复上次标签**。正常退出后再次启动 Pebrel,会按已保存的信息重新建立终端标签、分屏和已知目录。
+
+建议先用两个空闲终端测试:分别进入不同目录,正常退出并重开,再运行 `pwd` 检查恢复位置。SSH 标签需要重新连接服务器,缺少认证信息时会再次询问。
+
+恢复标签会启动新会话。上次终端里没有保存的屏幕内容和普通程序的内存状态,不会作为整个进程一起恢复。
+
+## 关窗后让任务继续运行
+
+1. 在 **设置 → 高级 → 会话生命周期**开启 **关窗后保留后台会话**。
+2. 建议同时开启 **常驻系统托盘图标**,方便重新打开窗口。
+3. 运行一个需要持续进行的任务,再关闭窗口。
+4. 通过托盘或快速终端重新唤起 Pebrel,查看原任务的输出。
+
+这项设置使应用在关窗后继续驻留。真正退出应用、结束进程、注销或重启电脑会终止本地进程;需要跨重启运行的任务,应使用相应系统服务或任务管理工具。
+
+## 接续 AI 对话
+
+希望恢复标签时继续之前的 Claude Code 或 Codex 对话,在开启标签恢复后,再开启 **恢复时接续 AI 对话**。
+
+恢复需要可用的会话标识、原会话记录和对应 CLI。Pebrel 会尝试用 CLI 的恢复入口接续对话;工具仍可能要求登录或确认工作目录。
+
+恢复失败时,右键相关终端标签,使用可用的 **重试会话恢复**或 **选择要继续的对话…**。也可以从[AI 会话历史](ai-history.md)手动选择。
+
+## 应该开启哪一项
+
+| 你的需要 | 设置 |
+| --- | --- |
+| 重启应用后重新打开标签、分屏与目录 | 启动时恢复上次标签 |
+| 关闭窗口但继续运行本地任务 | 关窗后保留后台会话 |
+| 重开时接续受支持的 AI 对话 | 启动时恢复上次标签 + 恢复时接续 AI 对话 |
+| 按项目保存几套可重复打开的布局 | 使用[布局配方](layouts.md) |
+
+## 远端任务需要长时间运行
+
+SSH 连接断开时,远端命令是否继续由服务器上的程序和会话管理方式决定。对必须持续运行的远端任务,建议使用服务器上已安装的会话保持工具或系统服务;重新连接后按对应工具的恢复方式继续。
+
+关闭 Pebrel 前,仍应保存打开的文档。文档编辑缓冲区的保存提示与终端会话恢复是两套操作。
diff --git a/docs/site/content/settings.md b/docs/site/content/settings.md
new file mode 100644
index 000000000..daca3fc09
--- /dev/null
+++ b/docs/site/content/settings.md
@@ -0,0 +1,51 @@
+## 打开设置并查找选项
+
+按 **Ctrl+,**(macOS 为 **⌘,**),或点击工作区的设置按钮。
+
+顶部搜索可以查找设置所属的分区。例如输入“通知”进入提醒相关设置,输入“字体”进入外观,输入“恢复”查找会话生命周期。搜索无结果时,试用更短的关键字。
+
+## 常用设置在哪里
+
+| 需要调整的内容 | 位置 |
+| --- | --- |
+| 查看版本、检查更新 | **应用 → 版本与更新** |
+| 更换主题、应用图标、跟随系统深浅色 | **外观** |
+| 中英文字体、终端字号、Ctrl+滚轮缩放、平滑光标、字符间距、回滚和滚动 | **外观 → 终端外观** |
+| 界面字号、语言、密度与透明度 | **外观 → 界面** |
+| 壁纸及图片铺放方式 | **外观 → 自定义背景** |
+| 默认 Shell、启动目录、新终端刷新环境变量(Windows) | **终端 → 启动** |
+| 命令补全(模式和按键见[补全指南](completions.md)) | **终端 → 补全** |
+| AI 通知、卡片时长、终端铃声 | **终端 → 提醒** |
+| 工具检测与集成 | **Agents** |
+| 选中即复制、鼠标焦点、粘贴确认 | **交互 → 鼠标与选区** |
+| 标签位置、新实例行为、Git / SVN 显示 | **交互 → 标签与窗口** |
+| 修改组合键、全局快速终端 | **按键映射** |
+| 保存主机、密码与密钥、代理和跳板 | **SSH** |
+| 网络代理、测试网络、新终端接入系统代理(Windows) | **网络** |
+| 备份与恢复、导出和导入备份文件 | **备份**([加密备份](backups.md)) |
+| 配对手机、管理已配对的手机、自建中转 | **手机远程**([Android 连接电脑](mobile.md)) |
+| 登录启动、托盘、后台会话、恢复标签和 AI 对话 | **高级 → 会话生命周期** |
+
+## 设置什么时候生效
+
+开关和选择项通常在操作后保存。文字输入按相应字段提示,通过 Enter、离开输入框或保存按钮提交。
+
+有些设置影响新会话:更改默认 Shell、回滚行数或终端代理环境后,新建窗格检查效果。修改 Agent 集成后,重新启动相应 CLI。
+
+出现保存失败提示时,按错误信息检查文件或目录权限,不必删除整套配置。
+
+## 更改界面语言
+
+在 **外观 → 界面 → 语言**选择需要的语言。设置改变 Pebrel 的菜单和说明文字,不改变 Shell 或远端程序输出。个别未翻译项会显示英文。
+
+## 登录时启动
+
+在 **高级 → 会话生命周期**中开启 **登录时自启动**。希望启动后先在后台待命时,再开启 **静默启动**;启用时会同时启用托盘,可从托盘重新打开窗口。
+
+显式打开目录等启动方式可能仍会显示窗口。先测试一次普通启动和托盘唤回,再决定是否保留静默模式。
+
+## 找不到平台专有选项
+
+托盘、全局快速终端、登录启动和关窗保留后台会话在 Windows、macOS 和 Linux 上都有对应选项。如果你的版本早于 2.1,macOS 和 Linux 可能没有这些选项,先在[更新](updates.md)中升级。
+
+修改配置文件、备份偏好和恢复默认设置,分别见[Lua 配置](configuration.md)、[备份迁移](migration.md)和[交互设置](interaction.md)。
diff --git a/docs/site/content/sftp.md b/docs/site/content/sftp.md
new file mode 100644
index 000000000..eba66aafc
--- /dev/null
+++ b/docs/site/content/sftp.md
@@ -0,0 +1,56 @@
+## 打开远端文件列表
+
+先建立[内置 SSH 连接](ssh.md),点击对应终端窗格,再打开文件面板。目录加载完成后,选择文件夹进入下一级,使用 **上一级**返回。
+
+列表可以跟随终端已知的远端目录。手动浏览其他目录后,点击 **重新跟随**回到终端目录;服务器文件有变化时,点击 **重新读取**刷新。
+
+## 上传文件或文件夹
+
+1. 在远端列表中进入目标目录。
+2. 点击 **上传文件**或 **上传文件夹**。
+3. 在本机文件选择窗口中选取要上传的内容。
+4. 有同名冲突时,选择处理方式。
+5. 查看传输进度,完成后确认远端列表中的结果。
+
+服务器上的目标目录需要写入权限。选择本地文件期间如果切换了目标,Pebrel 可能提示“目标已改变”;此时回到正确的远端目录,重新发起上传。
+
+## 下载到本机
+
+选中远端文件或文件夹,点击 **下载到本地**,再选择本机保存位置。下载文件夹时会传输其内容,并显示进度。
+
+完成后,在本机目标目录检查结果。磁盘空间不足、写入权限或网络断开都可能使传输中止,可以在修复原因后重新发起。
+
+## 处理同名项目
+
+| 选项 | 结果 |
+| --- | --- |
+| **覆盖** | 用传入内容替换目标同名文件 |
+| **跳过** | 保留目标已有内容,跳过冲突项 |
+| **保留两者** | 另取名称保存,让两份内容同时存在 |
+| **取消** | 取消这次操作 |
+
+选择 **覆盖**、**跳过**、**保留两者** 后对话框会关闭并开始处理;**取消** 关闭对话框,不开始传输。聚焦按钮后可按 Enter 或空格确认。文件与目录类型冲突时,覆盖可能不可选。重要文件不确定是否应替换时,先使用“保留两者”,再比较两份内容。
+
+## 跳过没有变化的文件
+
+重复传输目录时,可以勾选 **跳过未变**,减少重复复制。Pebrel 根据文件大小和修改时间判断可跳过项,不逐个计算完整内容的校验和。
+
+需要确保重新传输某个同大小、同时间戳的文件时,关闭此选项后再操作。
+
+## 远端复制与粘贴
+
+1. 在源主机的远端列表中选中文件或目录。
+2. 点击 **复制远端项目**。
+3. 浏览到目标目录;也可以切换到另一条已连接的 SSH 会话。
+4. 点击 **粘贴到当前远端目录**。
+5. 处理冲突并检查完成状态。
+
+跨主机复制需要源和目标都可连接,并具备读取、写入权限。这里复制的是所选项目,后续粘贴的目标由当前远端目录决定。
+
+## 取消传输
+
+传输过程中点击 **取消**。出现“正在取消”时,等待操作结束再开始下一次传输。取消不会撤回此前已经完成的其他文件;重新传输前检查目标目录,选择合适的同名处理方式。
+
+## 修改远端文本文件
+
+从远端列表打开支持的文本文件,编辑后按 **Ctrl+S / ⌘S**保存回服务器。保存结果与异常处理见[远端文件编辑](remote-edit.md)。
diff --git a/docs/site/content/shells.md b/docs/site/content/shells.md
new file mode 100644
index 000000000..34f09d4a6
--- /dev/null
+++ b/docs/site/content/shells.md
@@ -0,0 +1,56 @@
+## 为新终端选择 Shell
+
+按 **Ctrl+K**(macOS 为 **⌘K**)打开 Shell 选择器,选择要启动的终端程序。列表取决于当前电脑已安装的 Shell,以及你配置的启动入口。
+
+Windows 可以使用 PowerShell、命令提示符以及已安装的 WSL 发行版。macOS 和 Linux 使用系统中可用的 Shell;安装了 Zellij 时,它也会出现在选择器中,包括 Homebrew 等常见位置。选择一个入口后,Pebrel 会为它建立终端会话。
+
+## 更改默认 Shell
+
+1. 打开 **设置 → 终端**。
+2. 在 **默认 Shell**中选择常用的程序。
+3. 新建终端,检查提示符是否来自所选 Shell。
+
+已打开的 Shell 会继续运行。更改默认项不会中途替换它们。
+
+找不到刚安装的 Shell 时,先确认该程序可以独立启动,再重新打开 Pebrel。便携终端可以通过设置中的终端目录选择入口添加;应选择包含可执行文件的目录,或其上一级安装目录。
+
+## 设定启动目录
+
+1. 打开 **设置 → 终端 → 启动**,找到 **启动目录**。
+2. 点击当前路径或“继承当前目录”,在文件夹选择窗口中选取项目目录。
+3. 新建终端,检查是否进入所选目录。
+
+要取消固定启动目录,点击路径右侧的 **清除**。该项会重新显示“继承当前目录”,新会话可沿用已有终端的已知目录。
+
+在 Windows 上,同一分组还有 **新建终端时刷新系统环境变量**。开启时,打开终端会读取 Windows 当前的环境设置,刚装好的程序和新改的 PATH 不必重启 Pebrel 就能用;关闭后新终端继承启动 Pebrel 时的环境,包括临时加进去的 PATH。已经打开的终端不受影响。
+
+输入 `pwd` 查看实际目录;cmd 使用 `cd`。如果 Shell 自己的启动脚本也执行了 `cd`,最终目录会受该脚本影响。
+
+## 配置带参数的启动入口
+
+例如,你希望在选择器中直接启动一个带指定参数的外部程序,可以在 Lua 配置中添加 Profile:
+
+```lua
+local pebrel = require 'pebrel'
+local config = pebrel.config_builder()
+
+config.profiles = {
+ {
+ name = 'SSH — 开发服务器',
+ command = 'ssh',
+ args = { 'dev@example.com' },
+ },
+}
+
+return config
+```
+
+把示例地址换成自己的服务器。保存后执行 `pebrel config check` 检查配置,再从 Shell 选择器打开这个入口。
+
+该例使用外部 `ssh` 命令。需要 Pebrel 的主机管理、连接测试和 SFTP 文件面板时,使用[内置 SSH 连接](ssh.md)。
+
+## Shell 打不开时
+
+如果创建标签后立即退出,先从系统终端运行同一程序,检查路径和启动参数。自定义 Profile 中,程序路径放在 `command`,每个参数分别放进 `args`,不要把整条命令和所有参数合成程序名。
+
+WSL 发行版入口与 Windows 本地 Shell 的文件路径不同,具体见[使用 WSL](wsl.md)。
diff --git a/docs/site/content/ssh-auth.md b/docs/site/content/ssh-auth.md
new file mode 100644
index 000000000..dd4049f07
--- /dev/null
+++ b/docs/site/content/ssh-auth.md
@@ -0,0 +1,47 @@
+## 使用账户密码
+
+编辑主机,在 **基本**页选择 **密码**认证,填写用户名与密码。希望以后自动使用该密码时,勾选保存到系统凭据库的选项,然后保存主机。
+
+Windows 使用凭据管理器,macOS 使用钥匙串;Linux 需要可用且已解锁的系统凭据服务。保存失败时,仍可按连接提示临时输入密码。
+
+编辑已有连接时,密码框留空会保留已保存的密码。需要移除已存凭据时,使用界面提供的清除操作,不要把留空当成删除。
+
+## 使用私钥
+
+1. 编辑主机,将认证方式切换为 **密钥**。
+2. 点击 **选择私钥文件**,选取本机私钥。
+3. 有多个身份时,按需要添加其他私钥文件。
+4. 测试连接;出现私钥口令提示时,输入创建该密钥时设置的口令。
+
+私钥通常与同名 `.pub`公钥文件成对存在。这里选择的是私钥;公钥应预先由服务器管理员配置到对应账户。
+
+没有手动指定密钥时,连接会结合 SSH config 的 `IdentityFile`和常见默认私钥位置查找。使用 agent 的环境中,也需要确认 agent 中确实加载了所需身份。
+
+## 使用自动认证
+
+选择 **自动**,让连接先尝试可用密钥,再按需要使用密码。服务器只允许公钥认证时,仍需提供被服务器认可的密钥,密码不会代替它。
+
+存在多个身份、经常连错账户时,给这个主机显式指定用户名和私钥,比依赖多个默认身份更容易排查。
+
+## 验证码和多轮认证
+
+服务器使用动态验证码或键盘交互认证时,选择 **交互式**。启动连接后,逐项阅读服务器发来的问题,再输入密码、验证码等内容。
+
+验证码有有效期,输入新的验证码;不需要把动态验证码保存到主机库。服务器问题的内容由服务器决定,不一定每次相同。
+
+## 查看主机密钥提示
+
+账户认证前还可能出现服务器指纹确认。账户密码或私钥用于证明“你是谁”,主机指纹用于确认“连到的是哪台服务器”。首次使用或指纹变化时,都应独立核对。
+
+## 认证失败时检查什么
+
+| 提示或现象 | 优先检查 |
+| --- | --- |
+| 密码认证失败 | 用户名、密码、服务器是否允许密码登录 |
+| 私钥无法读取 | 选中的是否为私钥、文件是否存在、当前用户的读取权限 |
+| 私钥口令错误 | 是否输入了密钥口令,而不是服务器账户密码 |
+| 多个身份均被拒绝 | 为该主机显式选择正确私钥,检查服务器授权 |
+| 验证码一直失败 | 选择交互式认证,并检查验证码和设备时间 |
+| 无法保存密码 | 系统凭据服务是否可用、是否已解锁 |
+
+换电脑时,主机 CSV 可以携带连接信息,但密码和私钥需要单独配置,见[迁移](migration.md)。
diff --git a/docs/site/content/ssh-config.md b/docs/site/content/ssh-config.md
new file mode 100644
index 000000000..026f1ec8e
--- /dev/null
+++ b/docs/site/content/ssh-config.md
@@ -0,0 +1,54 @@
+## 给连接取一个别名
+
+SSH config 可以把地址、用户名、端口和密钥路径放在一个有名称的条目里。用户配置通常位于 `~/.ssh/config`;Windows 对应用户目录下的 `.ssh\config`。
+
+例如,为开发服务器添加:
+
+```sshconfig
+Host development
+ HostName example.com
+ User dev
+ Port 22
+ IdentityFile ~/.ssh/id_ed25519
+```
+
+把地址、账户和私钥路径换成自己的信息。`Host development`定义别名,`HostName`才是真正连接的服务器地址。
+
+## 在 Pebrel 中使用
+
+1. 保存 SSH config 文件。
+2. 打开 **设置 → SSH**。
+3. 使用重新读取入口刷新已发现的主机。
+4. 查找 `development`并启动连接。
+5. 首次连接时核对指纹,再处理认证提示。
+
+如果已经另外保存过同一服务器的主机条目,可以给两者设置容易区分的名称,避免误用不同账户。
+
+## 通过跳板机连接
+
+配置中可以使用一个独立别名描述跳板,例如:
+
+```sshconfig
+Host bastion
+ HostName bastion.example.com
+ User gateway
+
+Host internal-dev
+ HostName 10.0.0.20
+ User dev
+ ProxyJump bastion
+```
+
+然后在主机的 **高级**设置中,让跳板策略 **跟随 SSH config**。也可以改为 **指定主机**,为这一条连接单独设置跳板。界面中的连接规则预览可帮助确认实际路线。
+
+涉及多个跳板、复杂匹配或其他 OpenSSH 选项时,先查看 Pebrel 的连接预览并测试;并非所有外部 SSH 配置选项都具有相同支持范围。代理与跳板的具体操作见[连接路由](ssh-routing.md)。
+
+## 修改后没有生效
+
+确认修改的是当前用户的配置文件,保存后重新读取,再新建连接。已经建立的 SSH 会话不会中途切换到新地址或新密钥。
+
+在 Pebrel 中保存的主机覆盖项也可能影响连接。检查 **高级**页是否设置为跟随配置,还是显式指定了代理或跳板。
+
+## 隐藏或移除别名
+
+只是不想在 Pebrel 列表中看到某个别名时,可以隐藏它。想从 SSH 配置本身移除连接,则编辑原文件并删除相应段落,再刷新列表。修改原文件前保留备份,尤其是在其他 SSH 客户端也使用它的情况下。
diff --git a/docs/site/content/ssh-library.md b/docs/site/content/ssh-library.md
new file mode 100644
index 000000000..98d8ae6b3
--- /dev/null
+++ b/docs/site/content/ssh-library.md
@@ -0,0 +1,56 @@
+## 查找一台主机
+
+打开 **设置 → SSH**,在搜索框输入名称、地址、分组、标签或备注。列表上方可以按 **全部**、**置顶**、**最近** 切换范围,也可以按分组筛选。经常使用的主机在主机行的 **主机操作** 菜单里选择 **置顶**,之后在 **置顶** 范围里就能直接找到。
+
+每一行会显示这台主机的登录方式,例如密码、私钥文件名;通过跳板连接的主机会注明“经 某某主机”。
+
+建议用用途命名条目,例如“开发环境”或“日志服务器”;同一地址的不同账户,也可以在名称中写明账户用途。
+
+## 编辑连接和分类
+
+打开条目的编辑入口,在 **基本**页修改地址、端口、用户名或认证方式。分组、标签和备注用于整理列表,可以填写环境、项目和用途。
+
+保存前检查地址与用户名,再使用 **测试连接**确认。如果只想更改列表显示文字,修改 **主机名称**即可,不必改服务器地址。
+
+## 复制一台主机
+
+在主机行的 **主机操作** 菜单里选择 **复制**,会立即保存一台连接设置相同的新主机。之后修改副本的地址、凭据、代理或跳板、分组与标签,都不会影响原来的主机。想基于一台现有主机建立类似的连接时,先复制再修改比从头填写更省事。
+
+## 使用 SSH config 中的主机
+
+Pebrel 可以发现用户 SSH config 文件中的别名。修改配置后,使用列表的重新读取入口刷新。
+
+从配置文件发现的主机可以在 Pebrel 列表里隐藏;这不会删除原 SSH config 条目。要重新显示,使用隐藏项的恢复入口。如何编写别名和 IdentityFile,见[使用 SSH config](ssh-config.md)。
+
+## 导出主机列表
+
+在 SSH 主机库的导出入口选择 CSV 文件位置。导出的连接元数据包含以下列:
+
+```csv
+destination,label,group,tags,notes,connect_to
+dev@example.com,开发服务器,开发环境,linux;test,测试账户,
+```
+
+`connect_to` 是可选列,用来保存“实际要连接的地址”。普通主机留空即可;[复制](#复制一台主机)出来的主机会在这一列写入它真正连接的地址,导入后仍然连到同一台服务器。
+
+CSV 不包含密码、私钥内容或私钥口令。它适合备份地址与分类,或在另一台电脑上重建主机列表。
+
+## 批量导入主机
+
+1. 先从 Pebrel 导出一份 CSV,保留列名作为模板。
+2. 在副本中填写地址、显示名称及分类信息。
+3. 使用导入入口选择文件。
+4. 查看导入结果,确认新增、跳过或失败的条目。
+5. 为新增主机补充认证信息,再测试连接。
+
+已有条目不会被导入文件覆盖;重复项会按导入规则跳过。地址或端口有误时,先修正对应行再导入。文件较大时可以分批处理,并逐批查看结果。
+
+包含逗号、引号或换行的字段需要正确的 CSV 引号转义。不要把密码或私钥加进表格;非空的敏感凭据列会被拒绝。
+
+## 删除主机
+
+选择条目的删除入口,并确认删除提示。如果其他连接正在引用它作为跳板,先调整这些连接的跳板设置。
+
+删除主机记录不会删除服务器上的文件。配置文件发现的条目需要永久移除时,应编辑原 SSH config;仅在 Pebrel 隐藏时仍可恢复。
+
+换电脑后的凭据处理见[备份与迁移](migration.md)。
diff --git a/docs/site/content/ssh-routing.md b/docs/site/content/ssh-routing.md
new file mode 100644
index 000000000..b170c3146
--- /dev/null
+++ b/docs/site/content/ssh-routing.md
@@ -0,0 +1,46 @@
+## 先确认需要哪种连接方式
+
+直接能访问服务器时,保持直连即可。网络只允许通过代理访问外部地址时,设置代理;服务器位于内部网络、必须经过堡垒机时,设置跳板。
+
+编辑主机并打开 **高级**页,可以分别配置这两部分。
+
+## 使用全局代理
+
+1. 在 **设置 → 网络**填写代理类型、地址、端口及必要的认证信息。
+2. 使用网络测试入口检查代理。
+3. 编辑 SSH 主机,打开 **高级**页。
+4. 将代理策略设为 **跟随全局**,保存并测试连接。
+
+某台主机不需要代理时,把它的代理策略改为 **不使用**;不必关闭所有连接共用的全局代理。
+
+## 为单台主机指定代理
+
+在主机的 **高级**页选择自定义代理,填写 SOCKS5 或 HTTP CONNECT 代理的地址和端口。代理要求认证时,再填写用户名和密码。
+
+代理端口应在 `1–65535`范围内。填写密码时同时填写用户名;编辑后先用 **测试连接**检查,再保存为日常连接。
+
+HTTP CONNECT 代理的认证传输本身不等同于经过 TLS 保护的代理通道。使用不可信网络时,应选择管理员提供的安全接入方式。
+
+## 使用跳板机
+
+假设目标是内部主机 `10.0.0.20`,需要经过 `gateway@bastion.example.com:22`:
+
+1. 为目标主机填写它自己的地址、用户名和认证信息。
+2. 在 **高级 → 跳板**中选择 **指定主机**。
+3. 选择已有跳板条目,或填写 `gateway@bastion.example.com:22`。
+4. 查看 **连接规则预览**,确认路线经过跳板再到目标。
+5. 测试连接,按需处理跳板和目标各自的认证提示。
+
+已有 SSH config 的 `ProxyJump`设置时,可以选择 **跟随 SSH config**。需要忽略配置里的跳板时,选择 **不使用**。
+
+跳板账户和目标服务器账户可能不同,请分别填写。把目标密码填给跳板,不会让后续认证自动成功。
+
+## 同时使用代理和跳板
+
+代理作用于连接路线的第一段。例如可以先通过代理连接堡垒机,再由堡垒机访问内部服务器。使用连接规则预览检查第一跳,避免代理指向或跳板地址配置反了。
+
+## 找出失败的是哪一段
+
+先测试代理或堡垒机自身是否可达,再测试目标连接。代理拒绝通常需要检查类型、端口和代理认证;跳板认证失败检查跳板账户;到达跳板后仍超时,检查它到内部目标的网络与防火墙。
+
+服务器指纹校验仍需要按提示完成,代理和跳板不会替代身份校验。
diff --git a/docs/site/content/ssh.md b/docs/site/content/ssh.md
new file mode 100644
index 000000000..8f6c6315b
--- /dev/null
+++ b/docs/site/content/ssh.md
@@ -0,0 +1,60 @@
+## 准备连接信息
+
+向服务器管理员取得主机地址、端口、用户名,以及密码或私钥。首次连接还需要核对服务器指纹。下面以 `dev@example.com`、端口 `22`为例;操作时换成你的实际信息。
+
+## 添加主机
+
+1. 打开 **设置 → SSH**,选择 **添加 SSH 主机**。
+2. 在 **基本**页填写下列信息。
+3. 选择认证方式并补充相应字段。
+4. 点击 **测试连接**,处理认证提示和服务器身份确认。
+5. 测试成功后点击 **保存**。
+
+| 字段 | 示例 | 说明 |
+| --- | --- | --- |
+| **主机名称** | 开发服务器 | 列表中的显示名称,便于查找 |
+| **主机地址** | example.com | 域名或 IP 地址,为必填项 |
+| **端口** | 22 | 使用管理员提供的 SSH 端口 |
+| **用户名** | dev | 服务器上的账户名 |
+
+地址也可以包含连接信息,例如 `dev@example.com`或 `ssh://dev@example.com:2222`。为便于检查,首次设置时可以分别填写地址、端口和用户名。
+
+## 选择认证方式
+
+**密码**:填写账户密码。需要记住密码时,勾选保存到系统凭据库的选项;否则连接时按提示输入。
+
+**密钥**:点击 **选择私钥文件**,选择私钥,而不是扩展名为 `.pub`的公钥。私钥设置了口令时,连接过程中还会询问口令。
+
+**自动**:先尝试可用密钥,再按需要使用密码。
+
+**交互式**:适合服务器要求多轮提问、动态验证码或其他交互认证的情况。问题会在连接过程中逐项显示。
+
+完整说明见[密码、密钥与交互认证](ssh-auth.md)。
+
+## 确认服务器指纹
+
+首次连接时,Pebrel 可能显示服务器的主机密钥指纹。通过管理员、服务器控制台或其他独立可信渠道核对,确认一致后再接受。
+
+> [!WARNING]
+> 已连接过的服务器突然出现指纹变更时,先停止连接并向管理员确认原因。不要仅为了消除提示而直接接受新指纹。
+
+## 打开远端终端
+
+保存后,从 SSH 主机列表选择这个条目的连接入口。登录完成并出现远端提示符后,运行:
+
+```sh
+hostname
+pwd
+```
+
+确认显示的是目标服务器和预期目录。需要并排处理本地与远端工作时,可以使用[分屏](workspace.md)。
+
+## 浏览服务器文件
+
+聚焦这个 SSH 窗格,再打开文件面板。远端文件列表可用于浏览目录、上传、下载和编辑支持的文本文件。完整操作见[SFTP](sftp.md)。
+
+## 连接未成功
+
+超时先检查网络、VPN、地址和端口;“认证失败”先检查账户及认证方式。需要经过代理或跳板机时,编辑主机并打开 **高级**页,按[代理与跳板](ssh-routing.md)设置。
+
+“测试连接”通过后仍无法启动所需程序时,在远端终端检查程序是否已安装、当前账户是否有权限。
diff --git a/docs/site/content/svn.md b/docs/site/content/svn.md
new file mode 100644
index 000000000..ab152c183
--- /dev/null
+++ b/docs/site/content/svn.md
@@ -0,0 +1,43 @@
+## 打开工作副本
+
+先用 SVN 客户端检出项目,再在 Pebrel 终端进入这个工作副本。打开 **版本控制面板**,保持 **设置 → 交互 → 侧栏版本控制**为 **自动检测**或 **仅 SVN**。
+
+常规 SVN 操作需要可用的 `svn`命令或对应客户端。安装后,重新打开 Pebrel,并在终端运行 `svn --version`检查命令行环境。
+
+## 添加并提交文件
+
+查看变更列表,把尚未纳入版本控制的新文件添加到 SVN。检查准备提交的文件,填写提交信息后执行提交。
+
+SVN 的添加是将新文件纳入版本控制;它不等同于 Git 的暂存区。提交会联系版本库服务器,需要网络和对应账户权限。
+
+## 更新工作副本
+
+使用更新入口获取服务器上的新修订。更新前检查本地未提交的改动;出现冲突时先处理冲突文件,再继续提交。
+
+对已经手动解决的冲突,**解决**操作会保留当前文件内容并标记冲突已解决。点击前先确认文件里已经没有需要处理的冲突内容。
+
+## Windows 上使用 TortoiseSVN
+
+安装 TortoiseSVN 后,Pebrel 的 **更多 SVN 操作**菜单可以打开它的图形界面。例如:
+
+| 菜单项 | 用途 |
+| --- | --- |
+| **版本库浏览器** | 查看服务器上的目录和文件 |
+| **更新至版本…** | 将工作副本更新到指定修订 |
+| **分支 / 标记…** | 创建分支或标记 |
+| **切换…** | 切换当前工作副本对应的路径 |
+| **合并…** | 打开 SVN 合并流程 |
+| **导出…** | 导出不含工作副本管理信息的文件 |
+| **修订图** | 查看修订关系 |
+| **重定位…** | 更改版本库位置 |
+| **属性 / 清理** | 查看属性或处理工作副本维护操作 |
+
+这些操作会进入外部客户端的对话框,按对话框中的路径、修订和确认步骤完成。安装 TortoiseSVN 后若仍提示不可用,重新启动 Pebrel 再检测。
+
+## 对单个文件操作
+
+文件行的更多菜单提供 **显示日志**、**责任追溯**、**获得锁定…**、**释放锁定**、**加入忽略列表…**、**重命名…**、**删除**、**编辑冲突**和 **属性**。
+
+锁定适合需要独占编辑的文件;修改完成后按团队流程提交并释放锁。删除和重命名会改变工作副本状态,提交前再次检查变更列表。
+
+macOS 和 Linux 不提供 TortoiseSVN 的 Windows 图形入口,可以在终端使用 `svn`或系统上的 SVN 客户端完成对应操作。
diff --git a/docs/site/content/terminal-basics.md b/docs/site/content/terminal-basics.md
new file mode 100644
index 000000000..f798d7081
--- /dev/null
+++ b/docs/site/content/terminal-basics.md
@@ -0,0 +1,52 @@
+## 输入命令并查看结果
+
+终端提示符后的光标表示 Shell 正在等待输入。输入命令,按 **Enter** 执行;程序结束后,提示符会再次出现。
+
+```sh
+echo Hello, Pebrel
+```
+
+如果程序持续显示日志且没有新的提示符,它可能还在运行。可以另开一个[标签页或分屏](workspace.md)执行其他命令。
+
+## 查看和切换目录
+
+| 操作 | PowerShell / macOS / Linux / WSL | Windows cmd |
+| --- | --- | --- |
+| 查看当前目录 | `pwd` | `cd` |
+| 列出文件 | `ls` | `dir` |
+| 返回上一级 | `cd ..` | `cd ..` |
+| 进入指定目录 | `cd "路径"` | `cd /d "路径"` |
+
+命令在当前窗格的目录里运行。切换到另一个窗格后,先查看它的目录;各个 Shell 的目录可以不同。
+
+路径中的空格需要用引号包围。例如 PowerShell 中的 `cd "C:\My Projects\demo"`,或 macOS 中的 `cd "$HOME/My Projects/demo"`。
+
+## 停止运行中的命令
+
+通常按 **Ctrl+C** 可向当前程序发送中断请求。Windows / Linux 有文字选中时,Ctrl+C 会先复制选区;先清除选区再中断。macOS 复制使用 **⌘C**,中断仍使用 **Ctrl+C**。
+
+程序可能要求确认退出,或自行处理这次中断。回到提示符后,再输入下一条命令。
+
+## 查看之前的输出
+
+使用滚轮或触控板向上滚动。普通终端画面还支持:
+
+| 按键 | 作用 |
+| --- | --- |
+| Shift+PageUp / Shift+PageDown | 按页查看输出 |
+| Shift+Home | 移到保留的历史顶部 |
+| Shift+End | 返回输出底部 |
+
+进入 Vim、less 等全屏程序后,优先使用该程序自己的导航按键。程序接管鼠标时,按住 **Shift** 再用鼠标,可使用终端的选择或滚动操作。
+
+## 保留更多历史输出
+
+打开 **设置 → 外观 → 终端外观**,调整 **回滚行数**。这个数值控制每个窗格能保留的历史行数;修改后,新建终端窗格使用新设置。增加行数会增加长时间运行时的内存用量。
+
+**滚动速度**用于调整鼠标滚轮滚动的行数,修改后立即生效;触控板手势不受该倍率控制。
+
+## 当前窗格运行在哪台机器
+
+本地 Shell 使用电脑上的文件和程序;WSL 使用所选发行版的环境;SSH 使用远端服务器的环境。需要确认位置时,先查看标签、Shell 类型和当前目录,再运行 `pwd` 或 `hostname`。
+
+这一步在复制文件路径、启动 AI 工具和执行修改命令前尤其有用。进一步阅读:[WSL](wsl.md)、[SSH](ssh.md)、[复制与粘贴](clipboard.md)。
diff --git a/docs/site/content/themes.md b/docs/site/content/themes.md
new file mode 100644
index 000000000..d265dec31
--- /dev/null
+++ b/docs/site/content/themes.md
@@ -0,0 +1,49 @@
+## 从已有主题创建副本
+
+1. 打开 **设置 → 外观 → 更换主题**。
+2. 选择接近目标的主题,从 **作为模板**入口进入 **自定义主题**。
+3. 填写 **主题名称**,例如“我的深色配色”。
+4. 修改需要的颜色或字体,观察旁边的预览。
+5. 点击 **保存并应用**,回到终端检查效果。
+
+创建副本不会改动内置模板。只想先收藏这套配色时,点击 **仅保存**,稍后再从自定义主题中选择。
+
+## 调整常用设置
+
+**常用颜色**包含终端背景、文字颜色、强调色和光标颜色;**字体与显示**包含字体、字号、行高和不透明度。右侧的预览和文字与背景对比度提示会随修改更新。
+
+例如,文字拥挤时可以略微增加行高;光标不容易看清时,选择与背景有明显差异的光标颜色。预览包含终端、界面和 ANSI 色彩,修改后分别检查这几处。
+
+预览中的变化在应用前不会改动当前终端。离开编辑器时如出现未保存提示,可以选择继续编辑,或放弃草稿。
+
+## 调整调色板和界面细节
+
+展开 **高级设置**,可继续调整 **ANSI 16 色**、选区背景、选区文字、光标文字,以及主题支持的圆角、留缝、阴影和分割线。
+
+ANSI 颜色影响命令行程序输出的不同颜色;选区颜色影响鼠标选中的文字。修改后查看一段带颜色的输出和一段选区,确认文字仍清晰。
+
+颜色或数值格式不正确时,修正标出的字段再保存。需要回到当前模板的起点时,使用 **重置修改**。
+
+## 导入其他终端的配色
+
+选择 **导入**并打开主题文件。Pebrel 可以读取自身 JSON 主题,以及当前版本支持的其他静态主题格式。
+
+1. 选择文件,等待读取完成。
+2. 一个文件包含多套配色时,在候选主题中选择一项。
+3. 查看 **导入说明**,确认不支持或未映射的字段。
+4. 点击 **作为模板**,将配色载入编辑器。
+5. 检查预览后点击 **保存并应用**,或 **仅保存**。
+
+如果某种主题文件不能直接导入,可先整理为 Pebrel 支持的静态配色格式;包含脚本或动态计算的整份配置,也应先转换为纯配色数据。
+
+## 导出主题
+
+在编辑器选择 **导出**,选择目标格式,查看 **此格式不会保留的设置**,再指定保存位置。
+
+保留 Pebrel 的完整主题设置时,使用 **Pebrel**格式。导出到其他终端时,主要保留目标格式能表达的配色,Pebrel 特有的界面设置可能不会保留。
+
+## 避免丢失草稿
+
+切换模板会替换当前尚未保存的修改。想比较两个方案时,先保存第一个副本,再从另一个模板创建新副本。
+
+多个窗口同时编辑主题而出现保存冲突时,先保留当前草稿,再重新读取主题库比较,不要覆盖另一个窗口刚保存的结果。
diff --git a/docs/site/content/troubleshooting.md b/docs/site/content/troubleshooting.md
new file mode 100644
index 000000000..9db5ca9fe
--- /dev/null
+++ b/docs/site/content/troubleshooting.md
@@ -0,0 +1,82 @@
+## 应用打不开或没有窗口
+
+先确认安装包与系统、处理器匹配,并已完整解压。Windows 便携版保留整个目录;macOS 从 Applications 启动,不从 DMG 内直接运行;Linux TAR.GZ 使用包内 `AppRun`。
+
+开启过 **静默启动**或 **关窗后保留后台会话**时,窗口可能只是隐藏了,先检查系统托盘(macOS 为菜单栏)。macOS 被系统阻止时,按[首次启动说明](installation.md)处理。
+
+仍无法启动时,从系统终端运行对应程序并保留错误输出,不要先删除所有个人数据。
+
+## 新终端立即退出
+
+先从系统终端运行同一 Shell,确认它本身可以启动。再检查 **设置 → 终端 → 默认 Shell**与启动目录。
+
+自定义 Profile 的 `command`只填写程序,参数放在 `args`。WSL 先用 `wsl -d 发行版名称`检查发行版是否可启动。修改后新建标签测试。
+
+## 字体缺字、箭头变成方框或列不齐
+
+恢复默认终端字体和字号,再检查 **中文终端字体**、**字体间距**与 **字体连字**。Powerline 箭头需要字体提供相应字形。
+
+只有背景影响阅读时,先关闭图片和模糊、提高不透明度。详细步骤见[字体](fonts.md)。
+
+## SSH 连接超时
+
+检查服务器地址、端口、VPN 和本地网络。需要代理或跳板时,编辑主机的 **高级**页,查看连接规则预览。
+
+先测试第一跳,再检查跳板到目标的连通性。端口可达后仍认证失败,转到下一项,不必反复更换终端字体或 Shell。
+
+## SSH 认证失败或指纹变化
+
+核对用户名,确认选择了服务器允许的认证方式。私钥认证选择私钥而非 `.pub`文件,密钥口令与账户密码分开输入;需要验证码时选择交互式认证。
+
+指纹变化先向管理员确认,不要直接接受以跳过错误。详见[SSH 认证](ssh-auth.md)。
+
+## 文件树没有跟随当前目录
+
+先在终端运行 `pwd`(cmd 使用 `cd`)确认位置,再点击 **跟随当前终端并刷新**。手动进入其他目录后,需要通过跟随入口回到终端位置。
+
+仍不更新时,检查当前 Shell 的目录上报是否可用。SSH 文件列表使用 **重新跟随**和 **重新读取**。
+
+## SFTP 上传或下载失败
+
+查看目标路径,检查源文件读取权限、目标写入权限、磁盘空间与 SSH 连接。目标在文件选择期间发生变化时,回到正确目录重新发起传输。
+
+有同名冲突时明确选择覆盖、跳过或保留两者。取消之后检查哪些文件已完成,再重新传输,见[SFTP](sftp.md)。
+
+## 文档无法编辑或保存
+
+本地 Markdown 先使用 **文档操作 → 源码**;阅读视图不能直接编辑段落。超过 8 MB 或非完整 UTF-8 文本可能只读,需要外部编辑器。
+
+保存冲突先复制未保存内容,再重新读取并比较。远端保存失败还需检查服务器权限与网络,见[远端编辑](remote-edit.md)。
+
+## AI 图标、活动状态或历史缺失
+
+先在同一终端检查 CLI 是否可运行。启用或更改 Agent 集成后重启 CLI;工具状态异常时刷新 **设置 → Agents**并检查集成结果。
+
+历史恢复需要对应工具的会话记录和有效身份。右键标签使用重试或选择会话入口,或在 CLI 自己的历史里查找,见[AI 会话历史](ai-history.md)。
+
+## 设置改了却没有效果
+
+先确认修改的是正确设置:界面字号与终端字号分开,背景图片不透明度与终端不透明度分开,网络代理与新终端系统代理开关分开。
+
+Shell、回滚行数和进程环境需在新建窗格中验证。Lua 配置报错时运行 `pebrel config check`;存在 GUI 覆盖项时检查 **设置**中的当前值。
+
+## 更新后还是旧版本
+
+完全退出后台实例,检查快捷方式是否仍指向旧目录。便携版应从新解压目录启动,macOS 应从替换后的 Applications 应用启动,再检查 **设置 → 应用**的版本号。
+
+## 提交问题反馈
+
+打开 **设置 → 应用 → 反馈问题**,提供下面的信息:
+
+```text
+Pebrel 版本:
+系统和处理器架构:
+安装方式:安装程序 / ZIP / DMG / DEB / AppImage / TAR.GZ
+Shell 或远端环境:
+操作步骤:
+预期结果:
+实际结果和错误文字:
+是否能稳定重现:
+```
+
+附上能说明问题的截图或脱敏日志。不要附上密码、Token、私钥或运行时发现文件。涉及主题、字体或缩放时,再补充对应设置。
diff --git a/docs/site/content/updates.md b/docs/site/content/updates.md
new file mode 100644
index 000000000..9aad2b10c
--- /dev/null
+++ b/docs/site/content/updates.md
@@ -0,0 +1,57 @@
+## 检查是否有新版本
+
+打开 **设置 → 应用**,查看当前版本并点击 **检查更新**。发现新版本后,打开更新详情查看下载和安装操作。
+
+**自动检查更新**控制后台检查,预下载选项用于提前下载更新包。普通安装显示的更新通道是 **Stable**。
+
+更新前保存文档,并结束或安排好运行中的任务。下载完成后仍需按安装提示继续,重新启动后才能使用新程序。
+
+## Windows 安装版
+
+使用官方安装程序安装的版本,可以通过更新详情下载并安装,x64 和 ARM64 都会选择匹配的安装程序。按提示完成安装器流程,然后重新启动 Pebrel。
+
+完成后回到 **设置 → 应用**,检查版本号是否已更新。安装正在进行时,不要同时手动替换应用文件。
+
+## 由 Scoop 或 Microsoft Store 管理的安装
+
+通过 Scoop 或 Windows 应用包安装的 Pebrel,更新由原来的安装渠道负责。在 **设置 → 应用** 里,状态会显示 **由安装渠道管理更新**,**检查更新** 和自动检查、预下载这些选项不再提供,页面会写明该渠道:
+
+- Scoop 安装:在终端执行 `scoop update pebrel`。
+- 通过 Microsoft Store 安装:打开 Microsoft Store 检查更新。
+- 无法识别来源的安装:回到原来的安装渠道更新;这份副本已停用普通安装器更新。
+
+## Windows 便携版
+
+便携目录使用手动替换包的方式:
+
+1. 下载匹配架构的新 ZIP。
+2. 备份配置,并正常退出 Pebrel,包括后台驻留实例。
+3. 将新 ZIP 完整解压到新的目录。
+4. 迁移放在旧程序目录旁的个人配置或素材。
+5. 启动新目录中的 `pebrel.exe`,检查版本和设置。
+
+确认新版本正常后,再清理旧程序目录。只替换 EXE 可能遗漏随包资源;ARM64 与 x64 包也不要混用。
+
+## macOS
+
+从 Applications 中运行的可写 Pebrel `.app`可使用受支持的更新安装入口。按更新详情提示保存工作、退出相关运行实例并继续安装。
+
+如果提示当前安装位置不支持更新,或安装未成功:下载匹配 Apple Silicon / Intel 的官方 DMG,退出 Pebrel,再将应用拖入 Applications 替换。
+
+不要从仍挂载的 DMG 或被系统临时转移的路径直接安装更新。完成后从 Applications 重新启动并检查版本;首次启动的系统确认见[安装](installation.md)。
+
+## Linux
+
+使用与当前安装方式一致的新包。DEB 用户通过包管理器安装新版本;AppImage 用户退出旧进程后运行新的 AppImage;TAR.GZ 用户完整解压新包后使用其中的 `AppRun`。
+
+Linux 当前仍需手动完成包替换。更新检查可以帮助发现版本,不会自动代替包管理器更新系统安装。
+
+## 更新失败
+
+**下载失败:**检查网络代理、磁盘空间和 Release 资产是否可访问。
+
+**无法写入应用目录:**检查安装位置与权限,必要时改用官方安装包手动更新。
+
+**重开后还是旧版本:**检查启动的是不是旧目录中的快捷方式,以及后台是否仍有旧进程。
+
+反馈时提供版本号、系统、架构、安装方式和完整错误文字。升级前的数据保存方法见[备份与迁移](migration.md)。
diff --git a/docs/site/content/vcs.md b/docs/site/content/vcs.md
new file mode 100644
index 000000000..1153cc32a
--- /dev/null
+++ b/docs/site/content/vcs.md
@@ -0,0 +1,44 @@
+## 查看项目改动
+
+在本地终端进入 Git 仓库,按 **Ctrl+Shift+G**(macOS 为 **⌘⇧G**)打开版本控制面板。面板会显示当前仓库、分支和文件状态。
+
+如果显示的不是当前项目,使用 **回到终端当前目录**;执行外部 Git 命令后,点击刷新按钮重新读取状态。
+
+在 **设置 → 交互 → 侧栏版本控制**中,可以选择 **自动检测**、**仅 Git**或 **仅 SVN**。
+
+## 暂存准备提交的文件
+
+1. 查看 **变更**列表,打开文件检查内容。
+2. 对需要提交的文件选择 **暂存**。
+3. 在 **已暂存**列表确认本次提交范围。
+4. 放错文件时,选择 **取消暂存**将它移回未暂存区域。
+
+确定所有改动都属于同一任务时,可以使用 **全部暂存**。取消暂存只调整提交范围,不会丢失工作区里的文件修改。
+
+## 创建提交
+
+在提交信息框输入简短说明,例如“修正安装指南中的目录示例”,点击 **提交**。成功后刷新状态,已提交的改动会从待提交列表中移除,并出现在历史中。
+
+提交失败时,阅读错误消息。Git 用户身份未设置、提交钩子失败或冲突未解决,都需要先在当前仓库处理,再重试。
+
+## 拉取和推送
+
+使用 **拉取**获取远端更新,使用 **推送**发送本地提交。提交到本地仓库后,仍需推送才能让远端看到它。
+
+远端认证由当前 Git 环境处理;SSH 主机库保存的登录凭据不一定用于 Git。可以在同一终端运行 `git remote -v`检查远端地址。
+
+拉取出现冲突时,转到[解决 Git 冲突](git-conflicts.md),不要反复点击拉取或直接丢弃文件。
+
+## 阅读历史和分支线路
+
+切换到历史相关视图,查看提交信息及线路。线路显示提交之间的连接关系,便于识别分支和合并。检查某次改动时,先确认仓库路径和当前分支,再查看对应文件。
+
+## 丢弃不需要的修改
+
+对未提交的改动使用 **丢弃改动**,并在确认框核对范围。它会撤销相应文件的本地修改;需要保留的部分应先复制或提交。
+
+“取消暂存”用于暂时不提交,“丢弃改动”用于撤销修改,两者不能互换。
+
+## 使用 SVN
+
+进入 SVN 工作副本后,自动检测模式会切换到相应操作。SVN 使用添加、更新和提交,没有 Git 的暂存区与推送步骤。Windows 上的高级图形操作可交由 TortoiseSVN,见[SVN 工作副本](svn.md)。
diff --git a/docs/site/content/workspace.md b/docs/site/content/workspace.md
new file mode 100644
index 000000000..fafaf3d58
--- /dev/null
+++ b/docs/site/content/workspace.md
@@ -0,0 +1,57 @@
+## 窗口、标签页和窗格
+
+一个 Pebrel 窗口可以容纳多个标签页。终端标签页里又可以分成多个窗格,每个窗格都有自己的 Shell、当前目录和运行中的程序。
+
+例如,可以为两个项目分别建立标签页,在每个标签页里分出“运行服务”和“查看日志”两个窗格。切换项目时切换标签页;同时查看输出时使用分屏。
+
+## 创建和切换标签页
+
+点击新建终端入口,或按 **Ctrl+Shift+T**(macOS 为 **⌘T**)。需要为新终端选择不同 Shell 时,使用 **Ctrl+K / ⌘K** 打开 Shell 选择器。
+
+点击标签即可切换。也可以使用 **Ctrl+Tab** 切到下一个标签、**Ctrl+Shift+Tab** 切到上一个标签;macOS 还支持 **⌘⇧] / ⌘⇧[**。
+
+在 **设置 → 交互** 中,**标签栏位置**可选择“左侧边栏”或“顶部”,**新标签位置**可选择“当前标签之后”或“列表末尾”。
+
+## 创建分屏
+
+1. 点击准备拆分的终端窗格。
+2. 右键标签页,选择 **左右分屏**或**上下分屏**。
+3. 新窗格出现后,点击它并运行需要的命令。
+
+快捷键:Windows / Linux 使用 **Ctrl+Shift+D** 向右分屏、**Ctrl+Shift+S** 向下分屏;macOS 使用 **⌘D / ⌘⇧D**。
+
+拖动分隔线可以改变两个窗格的大小。需要暂时集中看一个窗格时,按 **Ctrl+Shift+Enter / ⌘⇧Enter** 放大当前窗格,再按一次还原布局。
+
+## 在窗格之间移动
+
+点击窗格可以将输入焦点移过去。使用键盘时,按 **Ctrl+Alt+方向键**(macOS 为 **⌘⌥方向键**)切换到相邻窗格。
+
+拖动窗格标题可以调整排布;将标题拖出终端区域,可以把该窗格拆成独立标签。拖动前先辨认窗格标题与分隔线:前者移动窗格,后者调整大小。
+
+## 重命名、排序和标色
+
+右键标签页打开菜单:
+
+| 操作 | 用途 |
+| --- | --- |
+| **重命名** | 输入项目名或用途,例如“API 日志”;也可使用 F2 |
+| **向左移动 / 向右移动** | 调整标签顺序;位于边缘时,对应方向不可用 |
+| **标签颜色** | 用颜色区分项目或环境;选择清除项可恢复默认 |
+| **移到新窗口** | 将这项工作移到单独窗口中 |
+| **复制标签** | 用同类启动入口新建会话,并尽量沿用已知工作目录 |
+
+“复制标签”适合在同一目录再开一个 Shell;原终端里正在运行的命令仍留在原标签中。
+
+## 给窗格命名
+
+双击窗格标题可以为这个窗格命名,例如“日志”或“构建”。按 **Enter** 或点到别处保存,按 **Esc** 取消;清空名称会恢复自动标题。窗格移动或恢复会话后名称仍然保留。把鼠标停在标题上,会看到这些操作提示。
+
+## 收起侧栏
+
+点击侧栏收起按钮,或按 **Ctrl+Shift+B / ⌘B**。打开文件树时使用 **Ctrl+Shift+F / ⌘⇧F**。终端区域需要更多空间时,可以收起不使用的面板。
+
+如果经常使用同一套排布,打开命令面板搜索“布局”,将当前标签或窗口保存为[布局配方](layouts.md)。
+
+## 关闭终端
+
+在 Shell 中输入 `exit`,或使用关闭入口。关闭窗格、标签页或窗口时,如果里面还有程序在运行,Pebrel 会先提示“某程序仍在运行,关闭会中止它”,确认后才会关闭。关闭前先停止仍需处理的命令,并保存文档标签中的修改。有关关窗后保留任务、重启后恢复标签的设置,见[会话保存与恢复](sessions.md)。
diff --git a/docs/site/content/wsl.md b/docs/site/content/wsl.md
new file mode 100644
index 000000000..213ad91a9
--- /dev/null
+++ b/docs/site/content/wsl.md
@@ -0,0 +1,60 @@
+## 打开已安装的发行版
+
+**此页适用于 Windows 上的 WSL。** 先在 Windows 中安装并完成 WSL 发行版的初始化,再打开 Pebrel。
+
+按 **Ctrl+K**打开 Shell 选择器,选择需要的发行版。进入后,运行:
+
+```sh
+pwd
+uname -s
+```
+
+`uname -s` 应显示 `Linux`。需要检查 Windows 已安装哪些发行版时,可以在 PowerShell 中运行:
+
+```powershell
+wsl --list --verbose
+```
+
+刚安装的发行版没有出现在选择器中时,先用 Windows 的 WSL 入口启动一次,再重新打开 Pebrel。
+
+## 进入 Linux 或 Windows 项目
+
+Linux 用户目录通常通过 `~`访问。Windows C 盘在常见 WSL 配置下映射到 `/mnt/c`:
+
+```sh
+cd ~/projects/my-project
+```
+
+或者进入 Windows 上的项目:
+
+```sh
+cd /mnt/c/Projects/my-project
+```
+
+把路径换成实际目录。项目位于 Linux 文件系统时,优先使用 Linux 路径;需要复制路径给 WSL 命令时,可以使用文件树提供的 **复制 Linux 路径**。
+
+## 将 WSL 作为默认终端
+
+打开 **设置 → 终端 → 默认 Shell**,选择相应发行版,然后新建标签。需要沿用当前 Linux 目录时,在 **启动目录**右侧点击 **清除**,让该项显示“继承当前目录”。
+
+复制已有 WSL 标签也会尽量使用已知工作目录。新标签打开后运行 `pwd`,可以确认目录是否已跟随。
+
+## 安装开发工具和 AI CLI
+
+WSL 有独立的软件环境。需要在 WSL 中运行 Node.js、Python 或 AI CLI 时,在该发行版内安装并登录。Windows 中能运行某个命令,并不代表 WSL 的 Linux PATH 中也有它。
+
+把项目文件交给 AI 之前,先在同一个 WSL 窗格中进入项目目录,再启动工具。
+
+## 复制图片与使用 Pebrel CLI
+
+在 WSL 终端粘贴图片时,Pebrel 会插入适合该环境访问的路径。提交给 CLI 前,检查生成的路径是否完整。
+
+从 Pebrel 启动的本地窗格会提供 CLI 环境信息,WSL 会转换相关路径。可以运行 `pebrel env --pretty` 检查;没有找到命令时,检查 `PEBREL_CLI` 指向的程序是否可从 WSL 执行。控制命令的使用见[终端自动化](runtime.md)。
+
+## 常见问题
+
+**打开后立刻退出:**先从 PowerShell 执行 `wsl -d 发行版名称`。如果也失败,先修复发行版本身的启动问题。
+
+**命令可以运行,但字体或颜色不同:**WSL Shell 的提示符配置与 Windows Shell 分开,终端字体则仍在 Pebrel 的 **外观**中设置。
+
+**文件树目录没有变化:**确认 Shell 能上报当前目录,再使用文件树的跟随和刷新入口。手动浏览过目录后,点击 **跟随当前终端并刷新**恢复跟随。
diff --git a/docs/site/palettes.py b/docs/site/palettes.py
new file mode 100644
index 000000000..192bf023c
--- /dev/null
+++ b/docs/site/palettes.py
@@ -0,0 +1,182 @@
+"""Derive the documentation colour themes from the desktop application's built-in themes.
+
+The palettes are parsed from the application source rather than copied, so a theme added
+or retuned in `pebrel_settings` reaches the site on the next build. The build fails when
+the source no longer has the expected shape instead of silently dropping a theme.
+"""
+import html
+import re
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]
+THEMES_RS = REPO / "pebrel_settings/src/themes.rs"
+LABELS_RS = REPO / "pebrel_app/src/display/ui/theme.rs"
+
+# Mirrors the application's factory default (Nord) and its light pair when following the system.
+DEFAULT_LIGHT = "NordLight"
+DEFAULT_DARK = "Nord"
+
+FIELDS = ("shell", "background", "foreground", "muted", "accent", "selected", "line",
+ "red", "green", "yellow", "blue", "purple", "cyan")
+
+
+def _bytes(raw: str) -> tuple[int, ...]:
+ return tuple(int(value.strip(), 0) for value in raw.split(",") if value.strip())
+
+
+def _hex(channels: tuple[int, ...]) -> str:
+ return "#" + "".join(f"{channel:02x}" for channel in channels[:3])
+
+
+def _mix(front: tuple[int, ...], back: tuple[int, ...], amount: float) -> tuple[int, ...]:
+ return tuple(round(f * amount + b * (1 - amount)) for f, b in zip(front[:3], back[:3]))
+
+
+def luminance(channels: tuple[int, ...]) -> float:
+ def linear(value: int) -> float:
+ value /= 255
+ return value / 12.92 if value <= 0.03928 else ((value + 0.055) / 1.055) ** 2.4
+ red, green, blue = (linear(value) for value in channels[:3])
+ return 0.2126 * red + 0.7152 * green + 0.0722 * blue
+
+
+def contrast(first: tuple[int, ...], second: tuple[int, ...]) -> float:
+ high, low = sorted((luminance(first), luminance(second)), reverse=True)
+ return (high + 0.05) / (low + 0.05)
+
+
+def load() -> list[dict]:
+ """Return the selectable built-in themes in the order the application lists them."""
+ source = THEMES_RS.read_text(encoding="utf-8")
+ order = re.search(r"pub const BUILTIN: \[Self; \d+\] = \[(.*?)\];", source, re.S)
+ if not order:
+ raise ValueError("themes.rs: BUILTIN catalog not found")
+ variants = re.findall(r"Self::(\w+)", order.group(1))
+ labels_source = LABELS_RS.read_text(encoding="utf-8")
+ label_block = re.search(r"pub\(crate\) fn label\(self\) -> &'static str \{(.*?)\n \}", labels_source, re.S)
+ if not label_block:
+ raise ValueError("theme.rs: label() not found")
+ labels = dict(re.findall(r'Self::(\w+) => "([^"]+)"', label_block.group(1)))
+ reviewed = re.search(r"pub const fn reviewed_palette\(self\).*?\n \}\n", source, re.S)
+ if not reviewed:
+ raise ValueError("themes.rs: reviewed_palette() not found")
+ arms = {
+ name: body
+ for name, body in re.findall(r"Self::(\w+) => ReviewedPalette \{(.*?)\n \},", reviewed.group(0), re.S)
+ }
+ themes = []
+ for variant in variants:
+ if variant not in arms or variant not in labels:
+ raise ValueError(f"theme {variant}: palette or label missing in the application source")
+ palette = {}
+ for field in FIELDS:
+ found = re.search(rf"\b{field}: \[([^\]]*)\]", arms[variant])
+ if not found:
+ raise ValueError(f"theme {variant}: field {field} missing")
+ palette[field] = _bytes(found.group(1))
+ themes.append({
+ "id": variant, "label": labels[variant], "palette": palette,
+ "light": luminance(palette["background"]) > 0.4,
+ })
+ ids = {theme["id"] for theme in themes}
+ if DEFAULT_LIGHT not in ids or DEFAULT_DARK not in ids:
+ raise ValueError("default theme pair is not selectable")
+ return themes
+
+
+def _over(front: tuple[int, ...], back: tuple[int, ...]) -> tuple[int, ...]:
+ """Composite a colour that may carry an alpha channel, as the application does."""
+ alpha = front[3] / 255 if len(front) > 3 else 1
+ return _mix(front, back, alpha)
+
+
+def readable(color: tuple[int, ...], foreground: tuple[int, ...], background: tuple[int, ...]) -> tuple[int, ...]:
+ """Keep a theme colour for text, nudged toward the foreground only when too faint to read."""
+ for step in range(21):
+ candidate = _mix(foreground, color, step / 20)
+ if contrast(candidate, background) >= 4.5:
+ return candidate
+ return foreground
+
+
+def tokens(theme: dict) -> dict[str, str]:
+ palette = theme["palette"]
+ background = palette["background"]
+ selected = _mix(_over(palette["selected"], background), background, 0.5)
+ foreground = palette["foreground"]
+ accent = readable(palette["accent"], foreground, selected)
+ muted = readable(palette["muted"], foreground, selected)
+
+ def ink(name: str) -> str:
+ return _hex(readable(palette[name], foreground, selected))
+ return {
+ "bg": _hex(background),
+ "panel": _hex(palette["shell"]),
+ "soft": _hex(selected),
+ "code": _hex(selected),
+ "tint": _hex(_mix(accent, background, 0.12)),
+ "text": _hex(palette["foreground"]),
+ "muted": _hex(muted),
+ "line": _hex(_over(palette["line"], background)),
+ "accent": _hex(accent),
+ "red": ink("red"), "green": ink("green"), "yellow": ink("yellow"),
+ "blue": ink("blue"), "purple": ink("purple"), "cyan": ink("cyan"),
+ }
+
+
+def _block(selector: str, theme: dict) -> str:
+ scheme = "light" if theme["light"] else "dark"
+ body = "".join(f"--{name}:{value};" for name, value in tokens(theme).items())
+ return f"{selector}{{color-scheme:{scheme};{body}}}\n"
+
+
+def stylesheet(themes: list[dict]) -> str:
+ by_id = {theme["id"]: theme for theme in themes}
+ css = "/* Generated by palettes.py from the application's built-in themes. */\n"
+ css += _block(":root", by_id[DEFAULT_LIGHT])
+ css += "@media (prefers-color-scheme: dark){\n" + _block(":root:not([data-palette])", by_id[DEFAULT_DARK]) + "}\n"
+ for theme in themes:
+ css += _block(f'html[data-palette="{theme["id"]}"]', theme)
+ return css
+
+
+def code_stylesheet() -> str:
+ """Syntax colours that follow the active palette instead of two fixed Pygments styles."""
+ groups = [
+ ("var(--purple)", "k kd kn kp kr kt"),
+ ("var(--green)", "s s1 s2 sa sb sc sd se sh si sx sr ss"),
+ ("var(--yellow)", "m mb mf mh mi mo il na"),
+ ("var(--blue)", "nf nc fm nd ne nt"),
+ ("var(--cyan)", "nb bp o ow"),
+ ("var(--red)", "err gd gr"),
+ ("var(--green)", "gi"),
+ ]
+ lines = []
+ for color, classes in groups:
+ selector = ",".join(f".code-block .{name}" for name in classes.split())
+ lines.append(f"{selector}{{color:{color}}}")
+ comments = ",".join(f".code-block .{name}" for name in "c c1 cm cp cs ch cpf".split())
+ lines.append(f"{comments}{{color:var(--muted);font-style:italic}}")
+ lines.append(".code-block .gh,.code-block .gu,.code-block .gs{font-weight:600}")
+ return "\n".join(lines) + "\n"
+
+
+def dark_ids(themes: list[dict]) -> str:
+ return ",".join(f"'{theme['id']}'" for theme in themes if not theme["light"])
+
+
+def menu(themes: list[dict]) -> str:
+ def item(theme: dict) -> str:
+ values = tokens(theme)
+ return (
+ f'')
+
+ def group(title: str, light: bool) -> str:
+ entries = "".join(item(theme) for theme in themes if theme["light"] is light)
+ return f'{title}{entries}
'
+
+ system = ('')
+ return system + group("浅色", True) + group("深色", False)
diff --git a/docs/site/requirements.txt b/docs/site/requirements.txt
new file mode 100644
index 000000000..9f922dfb6
--- /dev/null
+++ b/docs/site/requirements.txt
@@ -0,0 +1,2 @@
+mistune==3.2.1
+Pygments==2.20.0
diff --git a/docs/site/screenshots.json b/docs/site/screenshots.json
new file mode 100644
index 000000000..1641b5c06
--- /dev/null
+++ b/docs/site/screenshots.json
@@ -0,0 +1,86 @@
+{
+ "nebula-top-tabs.png": {
+ "kind": "existing_repository_screenshot",
+ "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/nebula-top-tabs.png",
+ "sha256": "a857a5d055fff00447e1e3ee5e36fc7b3e8618b1c7ab6c5343f26933ebd225d7",
+ "capture_version": "not established; do not infer from documentation version"
+ },
+ "split-ai-workflows.png": {
+ "kind": "existing_repository_screenshot",
+ "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/split-ai-workflows.png",
+ "sha256": "2d603eb796af45bd927c8ff9a0c3dcc74ffeb6d9df8ace1b5e7a7d5d0bb1fbfb",
+ "capture_version": "not established; do not infer from documentation version"
+ },
+ "nebula-claude-session.png": {
+ "kind": "existing_repository_screenshot",
+ "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/nebula-claude-session.png",
+ "sha256": "aac8e3e610c8d54a145ffe81a238f82415d3eefbe5a472d23b5adfc396352619",
+ "capture_version": "not established; do not infer from documentation version"
+ },
+ "native-math-rendering.png": {
+ "kind": "existing_repository_screenshot",
+ "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/native-math-rendering.png",
+ "sha256": "c1b8e356878ebf5fe368873d37f5daa0cca2de7688129f3a05ec28c8637d6e16",
+ "capture_version": "not established; do not infer from documentation version"
+ },
+ "themes.png": {
+ "kind": "existing_repository_screenshot",
+ "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/themes.png",
+ "sha256": "f8031403d4da402a8dd9388d72a7e13e3d1e31d3d7424a2a8ec0c4bbf9a04946",
+ "capture_version": "not established; do not infer from documentation version"
+ },
+ "ai-sidebar.png": {
+ "kind": "existing_repository_screenshot",
+ "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/ai-sidebar.png",
+ "sha256": "df0916d23dc254b9cbc31238c47606b27466104f800ba53f663674bca4dfc4da",
+ "capture_version": "not established; do not infer from documentation version"
+ },
+ "notification-duration.png": {
+ "kind": "existing_repository_screenshot",
+ "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/notification-duration.png",
+ "sha256": "bff479f36adf609b4fae95d79fcf751357cae133af46cdd9afeb1d6235fa4786",
+ "capture_version": "not established; do not infer from documentation version"
+ },
+ "reader-selection-opacity.png": {
+ "kind": "existing_repository_screenshot",
+ "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/reader-selection-opacity.png",
+ "sha256": "9264f5cdb5e34a9d1f101cb561cf4a8fcbdd67146199f4e99092e46ea7a9f23a",
+ "capture_version": "not established; do not infer from documentation version"
+ },
+ "hero.png": {
+ "kind": "existing_repository_screenshot",
+ "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/hero.png",
+ "sha256": "763d24c1cfe411e6624b77fcfa9dd3da82f5d0c5f4e237f52eada418312ce687",
+ "capture_version": "not established; do not infer from documentation version"
+ },
+ "pebrel-1.9.1-macos-arm64-ci.png": {
+ "kind": "official_release_ci_screenshot",
+ "version": "1.9.1",
+ "platform": "macOS",
+ "architecture": "aarch64",
+ "reported_os_version": "26.6.2",
+ "source_commit": "e9e83d83a63ca9cc885857439f7f6826c1cbabaf",
+ "source_tree": "601e9bdf8a43323337f6d768759b262b75a16da2",
+ "workflow_run": "https://github.com/Kuddev/pebrel/actions/runs/35961098033",
+ "artifact_id": 10792632932,
+ "artifact_name": "stable-evidence-macos-aarch64",
+ "artifact_created_at": "2026-09-24T05:58:38Z",
+ "artifact_sha256": "7c444586185e180881b5ee0c7b1bfadbd7cfddb72dd27ef0504fbf2973157797",
+ "original_path": "macos-aarch64-launch-artifacts/installed-app.png",
+ "sha256": "6f2b2a1b42975020ce53bc37bf85e9529dee97ca12f79f9edfc43825b2d892b9",
+ "modifications": "none",
+ "scope": "Visible native application launch with CI test text. Existing upstream run; not newly dispatched for this documentation task.",
+ "launch_report": {
+ "status": "passed",
+ "launch_method": "launchservices",
+ "commit": "e9e83d83a63ca9cc885857439f7f6826c1cbabaf",
+ "architecture": "aarch64",
+ "os_version": "26.6.2",
+ "quarantine_assessment": "not_tested",
+ "screenshot": "captured",
+ "rendered_text": true,
+ "utf8_locale": true,
+ "home_cwd": true
+ }
+ }
+}
diff --git a/docs/site/site.json b/docs/site/site.json
new file mode 100644
index 000000000..aaf856bc9
--- /dev/null
+++ b/docs/site/site.json
@@ -0,0 +1,650 @@
+{
+ "version": "2.1.1",
+ "source_commit": "d574856dae42f7a5142045e0b05f3eb43106fa3d",
+ "groups": [
+ {
+ "title": "开始使用",
+ "pages": [
+ {
+ "slug": "index",
+ "title": "概览",
+ "description": "安装 Pebrel,运行命令,连接服务器并管理项目文件。",
+ "sources": [
+ "README.md",
+ "pebrel_app/src/platform/capabilities.rs"
+ ]
+ },
+ {
+ "slug": "readme",
+ "title": "项目概览",
+ "description": "用图文方式浏览 README 中的定位、核心能力、平台下载、配置与社区信息。",
+ "sources": [
+ "README.md",
+ "README.zh-CN.md",
+ "INSTALL.md"
+ ]
+ },
+ {
+ "slug": "quickstart",
+ "title": "快速开始",
+ "description": "运行第一条命令,再创建标签页、分屏和 SSH 连接。",
+ "sources": [
+ "INSTALL.md",
+ "pebrel_app/src/gpui_shell/workspace/keyboard_bindings.rs"
+ ]
+ },
+ {
+ "slug": "installation",
+ "title": "安装与平台支持",
+ "description": "选择适合电脑的安装包,完成安装和首次启动。",
+ "sources": [
+ "INSTALL.md",
+ "pebrel_app/src/platform/capabilities.rs",
+ "pebrel_app/src/platform/update_installation.rs"
+ ]
+ },
+ {
+ "slug": "workspace",
+ "title": "标签页与分屏",
+ "description": "新建、移动和关闭标签页,调整分屏大小与焦点。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/tab_menu.rs",
+ "pebrel_app/src/gpui_shell/workspace/pane_header.rs",
+ "pebrel_app/src/gpui_shell/workspace/keyboard_bindings.rs"
+ ]
+ },
+ {
+ "slug": "terminal-basics",
+ "sources": [
+ "pebrel_app/src/gpui_shell/terminal/view.rs",
+ "pebrel_app/src/gpui_shell/workspace/keyboard_bindings.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/appearance_advanced.rs"
+ ],
+ "title": "运行命令与切换目录",
+ "description": "查看当前目录、执行命令、停止程序和查找历史输出。"
+ }
+ ]
+ },
+ {
+ "title": "日常终端",
+ "pages": [
+ {
+ "slug": "shells",
+ "title": "Shell 与启动目录",
+ "description": "选择默认 Shell,设定启动目录,添加带参数的启动入口。",
+ "sources": [
+ "pebrel_app/src/terminal_profiles.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/shell_picker.rs",
+ "docs/lua-configuration.md",
+ "pebrel_app/src/gpui_shell/settings_pane.rs"
+ ]
+ },
+ {
+ "slug": "wsl",
+ "sources": [
+ "pebrel_app/src/shell_detect.rs",
+ "pebrel_app/src/agent_env.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/shell_picker.rs"
+ ],
+ "title": "使用 WSL",
+ "description": "打开已安装的 Linux 发行版,访问项目并运行 Linux 工具。"
+ },
+ {
+ "slug": "clipboard",
+ "title": "选择、复制与粘贴",
+ "description": "复制终端输出,粘贴命令和图片,设置选中即复制。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/terminal/view/image_paste.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/setting_help.rs",
+ "pebrel_app/src/gpui_shell/workspace/send_to_chat.rs"
+ ]
+ },
+ {
+ "slug": "completions",
+ "title": "命令补全与智能候选",
+ "description": "选择三种补齐模式,补齐 Git 分支、项目脚本、SSH 别名、路径与历史命令。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane.rs",
+ "pebrel_app/i18n/zh-CN.json",
+ "pebrel_app/src/gpui_shell/terminal/view/completion.rs",
+ "pebrel_app/src/completion.rs",
+ "pebrel_app/src/completion/connections.rs",
+ "pebrel_app/src/completion/project_scripts.rs",
+ "nebula-completions/src/semantic/common.rs"
+ ]
+ },
+ {
+ "slug": "palette",
+ "title": "命令面板",
+ "description": "搜索并执行应用操作,快速打开设置或调整工作区。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/palette.rs",
+ "pebrel_app/src/gpui_shell/workspace/keyboard_bindings.rs"
+ ]
+ },
+ {
+ "slug": "commands",
+ "title": "保存常用命令",
+ "description": "保存、搜索和分组命令,选择插入文字或立即执行。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/command_manager.rs",
+ "pebrel_app/src/gpui_shell/workspace/command_manager/groups.rs",
+ "pebrel_app/src/saved_commands.rs"
+ ]
+ },
+ {
+ "slug": "navigation",
+ "title": "查找与快速跳转",
+ "description": "切换已打开的标签,跳转目录、主机和 AI 会话。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/quick_jump.rs",
+ "pebrel_app/src/ai_sessions.rs"
+ ]
+ },
+ {
+ "slug": "keyboard",
+ "title": "快捷键速查",
+ "description": "查找 Windows、macOS 和 Linux 常用快捷键,修改按键映射。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/keyboard_bindings.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/keymap.rs"
+ ]
+ }
+ ]
+ },
+ {
+ "title": "工作空间",
+ "pages": [
+ {
+ "slug": "broadcast",
+ "title": "广播输入",
+ "description": "选择同一标签中的多个窗格,同时输入命令并退出广播。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/pane_header.rs",
+ "pebrel_app/src/gpui_shell/terminal/view/image_paste.rs"
+ ]
+ },
+ {
+ "slug": "sessions",
+ "title": "保存与恢复会话",
+ "description": "设置启动时恢复标签和目录,在 Windows 中保留后台会话。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/session_persistence.rs",
+ "pebrel_app/src/gpui_shell/workspace/session_recovery.rs",
+ "pebrel_app/src/gpui_shell/session_restore.rs",
+ "pebrel_app/src/platform/capabilities.rs",
+ "pebrel_app/src/gpui_shell/settings_pane.rs"
+ ]
+ },
+ {
+ "slug": "layouts",
+ "title": "保存与打开布局",
+ "description": "把常用标签和分屏保存为布局配方,在新窗口中打开。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/recipes/mod.rs"
+ ]
+ },
+ {
+ "slug": "quick-terminal",
+ "title": "快速终端与托盘",
+ "description": "设置 Windows 全局热键,通过托盘召回终端或退出程序。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/quick_terminal.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/keymap.rs",
+ "pebrel_app/src/platform/capabilities.rs"
+ ]
+ }
+ ]
+ },
+ {
+ "title": "远程连接",
+ "pages": [
+ {
+ "slug": "ssh",
+ "title": "连接 SSH 服务器",
+ "description": "填写连接信息、测试认证并核对服务器指纹。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/ssh_settings.rs",
+ "pebrel_app/src/gpui_shell/ssh_settings/editor.rs",
+ "pebrel_app/src/gpui_shell/workspace/ssh_dialog.rs"
+ ]
+ },
+ {
+ "slug": "ssh-library",
+ "title": "管理 SSH 主机",
+ "description": "编辑连接,整理分组与标签,导入或导出主机列表。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/ssh_settings/library.rs",
+ "pebrel_app/src/gpui_shell/ssh_settings/library/exchange.rs",
+ "pebrel_app/src/ssh_profiles/exchange.rs",
+ "pebrel_app/src/ssh_profiles/organization.rs"
+ ]
+ },
+ {
+ "slug": "ssh-auth",
+ "title": "密码、密钥与认证",
+ "description": "选择认证方式,使用私钥,并管理保存的登录凭据。",
+ "sources": [
+ "pebrel_app/src/ssh_session/lifecycle.rs",
+ "pebrel_app/src/ssh_session/agent.rs",
+ "pebrel_app/src/ssh_credentials.rs",
+ "pebrel_app/src/platform/credentials.rs"
+ ]
+ },
+ {
+ "slug": "ssh-config",
+ "sources": [
+ "pebrel_app/src/ssh.rs",
+ "pebrel_app/src/ssh_session.rs",
+ "pebrel_app/src/gpui_shell/ssh_settings/library.rs",
+ "pebrel_app/src/ssh_proxy.rs"
+ ],
+ "title": "使用 SSH config",
+ "description": "通过别名连接服务器,读取配置中的用户名、密钥和跳板。"
+ },
+ {
+ "slug": "ssh-routing",
+ "title": "代理与跳板机",
+ "description": "配置直连、代理或单级跳板,检查连接路线。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/ssh_settings/advanced.rs",
+ "pebrel_app/src/ssh_profiles/connection.rs",
+ "pebrel_app/src/ssh_session/route.rs",
+ "pebrel_app/src/ssh_proxy.rs"
+ ]
+ },
+ {
+ "slug": "sftp",
+ "title": "SFTP 文件传输",
+ "description": "上传和下载文件夹,复制远端文件,处理同名文件并查看进度。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/remote_files.rs",
+ "pebrel_app/src/gpui_shell/workspace/remote_files/transfers.rs",
+ "pebrel_app/src/ssh_sftp/transfer.rs",
+ "pebrel_app/src/ssh_sftp/transaction.rs"
+ ]
+ },
+ {
+ "slug": "mobile",
+ "title": "Android 连接电脑",
+ "description": "配对自己的手机、核对校验码、选择只看或允许输入,并撤销不用的设备。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane/mobile/view.rs",
+ "pebrel_app/src/mobile_connection/preferences.rs",
+ "pebrel_app/i18n/zh-CN.json",
+ "mobile/android/app/src/main/java/io/github/kuddev/pebrel/mobile/ui/RelayForm.kt",
+ "mobile/android/app/src/main/java/io/github/kuddev/pebrel/mobile/ui/TerminalScreen.kt",
+ "mobile/android/app/src/main/res/values-zh-rCN/pairing.xml",
+ "mobile/android/app/build.gradle.kts",
+ "mobile/link/src/pairing.rs",
+ "mobile/link/src/endpoint/host.rs"
+ ]
+ }
+ ]
+ },
+ {
+ "title": "文件与阅读",
+ "pages": [
+ {
+ "slug": "files",
+ "title": "浏览与查找文件",
+ "description": "打开项目目录,筛选文件,在指定目录新建终端。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/file_tree.rs",
+ "pebrel_app/src/gpui_shell/file_preview.rs",
+ "pebrel_app/src/platform/file_preview.rs"
+ ]
+ },
+ {
+ "slug": "vcs",
+ "title": "查看与提交 Git 改动",
+ "description": "查看差异、暂存文件、提交改动并与远端同步。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/vcs_panel.rs",
+ "pebrel_app/src/gpui_shell/workspace/vcs_panel/rows.rs",
+ "pebrel_app/src/gpui_shell/workspace/vcs_panel/list_model.rs"
+ ]
+ },
+ {
+ "slug": "git-conflicts",
+ "sources": [
+ "pebrel_app/src/gpui_shell/code_tab.rs",
+ "pebrel_app/src/gpui_shell/workspace/vcs_panel/rows.rs"
+ ],
+ "title": "解决 Git 冲突",
+ "description": "使用三栏冲突视图整理结果,保存并暂存已解决的文件。"
+ },
+ {
+ "slug": "svn",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/vcs_panel.rs",
+ "pebrel_app/src/display/side_panel/vcs.rs"
+ ],
+ "title": "使用 SVN",
+ "description": "查看 SVN 工作副本的改动,执行更新和提交。"
+ },
+ {
+ "slug": "documents",
+ "title": "阅读文档",
+ "description": "打开 Markdown,使用目录、代码复制和公式预览。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/file_editor/mod.rs",
+ "pebrel_app/src/gpui_shell/file_editor/chrome.rs",
+ "pebrel_app/src/gpui_shell/file_editor/code_actions.rs",
+ "pebrel_app/src/gpui_shell/file_editor/tests.rs"
+ ]
+ },
+ {
+ "slug": "markdown-editing",
+ "sources": [
+ "pebrel_app/src/gpui_shell/file_editor/mod.rs",
+ "pebrel_app/src/gpui_shell/file_editor/chrome.rs",
+ "pebrel_app/src/gpui_shell/file_editor/tests.rs"
+ ],
+ "title": "编辑 Markdown",
+ "description": "切换到源码,编写标题、列表、表格和公式,保存后预览。"
+ },
+ {
+ "slug": "images",
+ "title": "查看与粘贴图片",
+ "description": "预览本地图片和附件,把剪贴板图片传给终端中的工具。",
+ "sources": [
+ "pebrel_app/src/platform/file_preview.rs",
+ "pebrel_app/src/gpui_shell/file_preview.rs",
+ "pebrel_app/src/gpui_shell/terminal/view/image_paste.rs",
+ "README.md"
+ ]
+ },
+ {
+ "slug": "remote-edit",
+ "title": "编辑服务器上的文件",
+ "description": "从 SFTP 面板打开文本文件,保存修改并处理冲突。",
+ "sources": [
+ "pebrel_app/src/ssh_sftp/document.rs",
+ "pebrel_app/src/gpui_shell/file_editor/mod.rs",
+ "pebrel_app/src/gpui_shell/workspace/remote_files.rs"
+ ]
+ }
+ ]
+ },
+ {
+ "title": "AI 工作流",
+ "pages": [
+ {
+ "slug": "ai-start",
+ "title": "使用 AI 命令行工具",
+ "description": "启动 Claude Code 或 Codex,用标签、分屏和状态提示管理任务。",
+ "sources": [
+ "README.md",
+ "pebrel_app/src/ai_agents.rs",
+ "pebrel_app/src/gpui_shell/workspace/agents.rs",
+ "pebrel_app/src/ai_hook/integrations.rs",
+ "pebrel_app/src/gpui_shell/terminal/view.rs",
+ "pebrel_app/src/gpui_shell/terminal/view/agent_activity.rs",
+ "pebrel_app/src/display/program_identity.rs"
+ ]
+ },
+ {
+ "slug": "agents",
+ "title": "支持的 AI 命令行工具",
+ "description": "查看 Pebrel 能识别哪些 AI CLI 和 TUI,以及每个工具有哪些状态、图标和会话功能。",
+ "sources": [
+ "pebrel_app/src/ai_agents.rs",
+ "pebrel_app/src/ai_hook/integrations.rs",
+ "pebrel_app/src/display/program_identity.rs",
+ "pebrel_app/src/agent_detection/_shared.toml",
+ "pebrel_app/src/gpui_shell/settings_pane/agents.rs"
+ ]
+ },
+ {
+ "slug": "hooks",
+ "title": "配置 Agent 集成",
+ "description": "检测已安装的工具,配置可用集成并检查状态提示。",
+ "sources": [
+ "pebrel_app/src/ai_hook/integrations.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/agents.rs",
+ "pebrel_app/src/ai_hook/local/settings.rs",
+ "pebrel_app/src/platform/capabilities.rs",
+ "pebrel_app/src/cli.rs",
+ "pebrel_app/src/ssh_session/integration.rs",
+ "pebrel_settings/src/agent_hooks.rs",
+ "pebrel_app/src/ai_hook/local/runtime_skills.rs"
+ ]
+ },
+ {
+ "slug": "ai-history",
+ "title": "恢复与分叉 AI 对话",
+ "description": "查找历史会话,恢复先前对话,或从已有上下文继续新任务。",
+ "sources": [
+ "pebrel_app/src/ai_sessions.rs",
+ "pebrel_app/src/gpui_shell/workspace/session_recovery.rs",
+ "pebrel_app/src/gpui_shell/workspace/tab_menu.rs",
+ "pebrel_app/src/ai_agents.rs",
+ "pebrel_app/src/gpui_shell/workspace/agents.rs"
+ ]
+ },
+ {
+ "slug": "send-to-chat",
+ "title": "把输出发送给 AI",
+ "description": "选中终端文字,补充问题,再选择接收内容的 Agent。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/workspace/send_to_chat.rs"
+ ]
+ },
+ {
+ "slug": "agent-worktrees",
+ "sources": [
+ "docs/runtime-control-api.md",
+ "pebrel_app/src/git_worktree.rs",
+ "pebrel_app/src/gpui_shell/workspace/residency.rs"
+ ],
+ "title": "隔离 AI 工作目录",
+ "description": "为并行任务创建独立 Git worktree,核对目录后分配任务。"
+ }
+ ]
+ },
+ {
+ "title": "个性化",
+ "pages": [
+ {
+ "slug": "appearance",
+ "title": "调整应用外观",
+ "description": "更换主题和图标,选择界面密度、语言与光标样式。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane/appearance.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/appearance_advanced.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/appearance_picker.rs"
+ ]
+ },
+ {
+ "slug": "themes",
+ "title": "创建和导入主题",
+ "description": "从模板创建配色,调整颜色,导入或导出主题文件。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane/theme_editor.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/theme_transfer.rs",
+ "pebrel_app/src/theme_library/formats.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/theme_advanced.rs"
+ ]
+ },
+ {
+ "slug": "backgrounds",
+ "title": "背景图片与透明度",
+ "description": "选择壁纸、设置铺放方式,并调整图片和终端的不透明度。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane/appearance_advanced.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/setting_help.rs",
+ "pebrel_app/src/gpui_shell/settings_pane.rs"
+ ]
+ },
+ {
+ "slug": "fonts",
+ "title": "字体、字号与间距",
+ "description": "设置中英文字体、调整字号和间距,解决对齐与缺字问题。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane/font_picker.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/appearance.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/appearance_advanced.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/scrolling.rs"
+ ]
+ },
+ {
+ "slug": "notifications",
+ "title": "通知与提醒",
+ "description": "设置 AI 消息、卡片显示时长和终端铃声。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane/notifications.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/setting_help.rs",
+ "README.md",
+ "pebrel_app/src/platform/capabilities.rs"
+ ]
+ },
+ {
+ "slug": "interaction",
+ "title": "鼠标与窗口行为",
+ "description": "调整复制粘贴、鼠标焦点、标签位置和新实例行为。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/setting_help.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/navigation.rs"
+ ]
+ },
+ {
+ "slug": "configuration",
+ "title": "使用 Lua 配置",
+ "description": "创建配置文件,检查语法和字段,修改并重载设置。",
+ "sources": [
+ "docs/lua-configuration.md",
+ "pebrel_app/src/config/mod.rs"
+ ]
+ },
+ {
+ "slug": "config-examples",
+ "sources": [
+ "docs/lua-configuration.md",
+ "pebrel_app/src/config/mod.rs"
+ ],
+ "title": "常用配置示例",
+ "description": "复制并调整字体、Shell、环境变量和模块化配色示例。"
+ },
+ {
+ "slug": "network",
+ "title": "网络与系统代理",
+ "description": "设置连接代理、测试网络,并让新终端使用系统代理环境。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/network_settings.rs",
+ "pebrel_app/src/update_proxy.rs",
+ "pebrel_app/src/ssh_proxy.rs"
+ ]
+ }
+ ]
+ },
+ {
+ "title": "参考与帮助",
+ "pages": [
+ {
+ "slug": "runtime",
+ "title": "命令行控制与自动化",
+ "description": "列出窗格、发送文本、读取输出,向指定 Agent 分配任务。",
+ "sources": [
+ "docs/runtime-control-api.md",
+ "pebrel_app/src/runtime_api/cli.rs",
+ "pebrel_app/src/agent_env.rs"
+ ]
+ },
+ {
+ "slug": "settings",
+ "title": "设置索引",
+ "description": "按需要完成的操作查找设置位置,了解何时需要新建会话。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane/navigation.rs",
+ "pebrel_app/src/gpui_shell/settings_pane.rs",
+ "pebrel_app/src/platform/capabilities.rs"
+ ]
+ },
+ {
+ "slug": "updates",
+ "title": "更新 Pebrel",
+ "description": "检查新版本,按照当前平台和安装方式完成升级。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane/about.rs",
+ "pebrel_app/src/platform/update_installation.rs",
+ "pebrel_app/src/platform/update_installation/macos.rs",
+ "pebrel_app/src/update_download.rs"
+ ]
+ },
+ {
+ "slug": "backups",
+ "title": "加密备份与恢复",
+ "description": "创建加密快照、导出迁移文件、选择恢复内容,检查密码与存储平台限制。",
+ "sources": [
+ "pebrel_app/src/gpui_shell/settings_pane/backup.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/backup/setup.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/backup/view.rs",
+ "pebrel_app/src/gpui_shell/settings_pane/backup/operations.rs",
+ "pebrel_app/src/encrypted_backup.rs",
+ "pebrel_app/src/encrypted_backup/recovery.rs",
+ "pebrel_app/src/backup_remote.rs",
+ "pebrel_app/i18n/zh-CN.json"
+ ]
+ },
+ {
+ "slug": "migration",
+ "title": "备份与迁移",
+ "description": "备份偏好、主机和命令,将工作环境迁移到另一台电脑。",
+ "sources": [
+ "pebrel_app/src/brand.rs",
+ "docs/lua-configuration.md",
+ "pebrel_app/src/ssh_profiles/exchange.rs",
+ "pebrel_app/src/platform/credentials.rs"
+ ]
+ },
+ {
+ "slug": "privacy",
+ "title": "数据与凭据",
+ "description": "查看本地数据的用途,管理凭据,检查分享或发送的内容。",
+ "sources": [
+ "pebrel_app/src/platform/credentials.rs",
+ "pebrel_app/src/gpui_shell/workspace/send_to_chat.rs",
+ "pebrel_app/src/runtime_api.rs",
+ "pebrel_app/src/ssh_profiles/exchange.rs"
+ ]
+ },
+ {
+ "slug": "troubleshooting",
+ "title": "故障排查",
+ "description": "处理启动、字体、SSH、文件保存和会话恢复中的常见问题。",
+ "sources": [
+ "INSTALL.md",
+ "pebrel_app/src/gpui_shell/settings_pane/navigation.rs",
+ "pebrel_app/src/platform/capabilities.rs",
+ "docs/runtime-control-api.md"
+ ]
+ },
+ {
+ "slug": "contributing",
+ "title": "贡献与开发",
+ "description": "准备开发环境,完成本地检查,并按仓库规则提交便于审查的改动。",
+ "sources": [
+ "CONTRIBUTING.md",
+ "docs/project-constraints.md",
+ "docs/architecture.md",
+ "INSTALL.md"
+ ]
+ }
+ ]
+ }
+ ],
+ "images": [
+ "nebula-top-tabs.png",
+ "split-ai-workflows.png",
+ "nebula-claude-session.png",
+ "native-math-rendering.png",
+ "themes.png",
+ "ai-sidebar.png",
+ "notification-duration.png",
+ "reader-selection-opacity.png",
+ "hero.png",
+ "pebrel-1.9.1-macos-arm64-ci.png"
+ ]
+}
diff --git a/docs/site/template.html b/docs/site/template.html
new file mode 100644
index 000000000..8a5e4558f
--- /dev/null
+++ b/docs/site/template.html
@@ -0,0 +1,59 @@
+
+
+
+
+
+
+
+
+ $title · Pebrel 文档
+ $canonical
+
+
+
+
+
+
+
+
+跳到正文
+
+
+
+
+
+
+ $page_header
+ $content
+ $source_details
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/site/test_site.py b/docs/site/test_site.py
new file mode 100644
index 000000000..d33e5047e
--- /dev/null
+++ b/docs/site/test_site.py
@@ -0,0 +1,184 @@
+"""Check generated navigation, rich content, and portable asset references."""
+import json
+import hashlib
+import tempfile
+import unittest
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+import palettes
+from build import build, HERE, home_header, page_url, source_details
+
+
+class Document(HTMLParser):
+ def __init__(self, source):
+ super().__init__()
+ self.ids = set()
+ self.duplicates = set()
+ self.references = []
+ self.headings = []
+ self.images_without_alt = []
+ self.remote_runtime = []
+ self.feed(source)
+
+ def handle_starttag(self, tag, attrs):
+ values = dict(attrs)
+ identity = values.get('id')
+ if identity in self.ids:
+ self.duplicates.add(identity)
+ if identity:
+ self.ids.add(identity)
+ if tag == 'h1':
+ self.headings.append(tag)
+ if tag == 'img' and 'alt' not in values:
+ self.images_without_alt.append(values)
+ for key in ('src', 'href'):
+ if key in values:
+ self.references.append(values[key])
+ resource = values.get('src') if tag == 'script' else values.get('href') if tag == 'link' and values.get('rel') == 'stylesheet' else ''
+ if resource and urlsplit(resource).scheme:
+ self.remote_runtime.append(resource)
+
+
+class SiteTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ cls.temp = tempfile.TemporaryDirectory()
+ cls.root = Path(cls.temp.name)
+ cls.stale_page = cls.root / 'obsolete' / 'index.html'
+ cls.stale_page.parent.mkdir()
+ cls.stale_page.write_text('stale output')
+ (cls.root / 'build-info.json').write_text('{}')
+ (cls.root / '.nojekyll').touch()
+ cls.report = build(cls.root, 'https://example.org/pebrel/')
+ cls.documents = {
+ path.resolve(): Document(path.read_text())
+ for path in cls.root.rglob('*.html')
+ }
+
+ @classmethod
+ def tearDownClass(cls):
+ cls.temp.cleanup()
+
+ def test_build_removes_stale_output(self):
+ self.assertFalse(self.stale_page.exists())
+
+ def test_build_preserves_unrelated_output(self):
+ with tempfile.TemporaryDirectory() as temp:
+ output = Path(temp)
+ sentinel = output / 'user-data.txt'
+ sentinel.write_text('keep')
+ with self.assertRaisesRegex(ValueError, 'not a generated site'):
+ build(output, '')
+ self.assertEqual(sentinel.read_text(), 'keep')
+
+ def test_build_does_not_remove_source_directories(self):
+ with self.assertRaisesRegex(ValueError, 'overlaps repository sources'):
+ build(HERE, '')
+
+ def test_internal_links_and_fragments(self):
+ for path, document in self.documents.items():
+ for reference in document.references:
+ url = urlsplit(reference)
+ if url.scheme or url.netloc:
+ continue
+ target = (path.parent / unquote(url.path)).resolve() if url.path else path
+ if target.is_dir():
+ target /= 'index.html'
+ with self.subTest(page=path.name, link=reference):
+ self.assertTrue(target.is_relative_to(self.root), 'Link escapes site root')
+ self.assertTrue(target.is_file(), f'Missing local destination: {target}')
+ if url.fragment and target in self.documents:
+ self.assertIn(unquote(url.fragment), self.documents[target].ids)
+
+ def test_homepage_hero_has_no_eyebrow_or_description(self):
+ header = home_header()
+ hero = header.split('', 1)[0]
+ self.assertNotIn('eyebrow', hero)
+ self.assertNotIn('