fengming 0.3.10 → 0.3.12

package/docs/install/clawdock.md

@@ -1,112 +0,0 @@
----
-summary: "ClawDock shell helpers for Docker-based FengMing installs"
-read_when:
-  - You run FengMing with Docker often and want shorter day-to-day commands
-  - You want a helper layer for dashboard, logs, token setup, and pairing flows
-title: "ClawDock"
----
-
-ClawDock is a small shell-helper layer for Docker-based FengMing installs.
-
-It gives you short commands like `clawdock-start`, `clawdock-dashboard`, and `clawdock-fix-token` instead of longer `docker compose ...` invocations.
-
-If you have not set up Docker yet, start with [Docker](/install/docker).
-
-## Install
-
-Use the canonical helper path:
-
-```bash
-mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/fengming/fengming/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
-echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc
-```
-
-If you previously installed ClawDock from `scripts/shell-helpers/clawdock-helpers.sh`, reinstall from the new `scripts/clawdock/clawdock-helpers.sh` path. The old raw GitHub path was removed.
-
-## What you get
-
-### Basic operations
-
-| Command            | Description            |
-| ------------------ | ---------------------- |
-| `clawdock-start`   | Start the gateway      |
-| `clawdock-stop`    | Stop the gateway       |
-| `clawdock-restart` | Restart the gateway    |
-| `clawdock-status`  | Check container status |
-| `clawdock-logs`    | Follow gateway logs    |
-
-### Container access
-
-| Command                   | Description                                   |
-| ------------------------- | --------------------------------------------- |
-| `clawdock-shell`          | Open a shell inside the gateway container     |
-| `clawdock-cli <command>`  | Run FengMing CLI commands in Docker           |
-| `clawdock-exec <command>` | Execute an arbitrary command in the container |
-
-### Web UI and pairing
-
-| Command                 | Description                  |
-| ----------------------- | ---------------------------- |
-| `clawdock-dashboard`    | Open the Control UI URL      |
-| `clawdock-devices`      | List pending device pairings |
-| `clawdock-approve <id>` | Approve a pairing request    |
-
-### Setup and maintenance
-
-| Command              | Description                                      |
-| -------------------- | ------------------------------------------------ |
-| `clawdock-fix-token` | Configure the gateway token inside the container |
-| `clawdock-update`    | Pull, rebuild, and restart                       |
-| `clawdock-rebuild`   | Rebuild the Docker image only                    |
-| `clawdock-clean`     | Remove containers and volumes                    |
-
-### Utilities
-
-| Command                | Description                             |
-| ---------------------- | --------------------------------------- |
-| `clawdock-health`      | Run a gateway health check              |
-| `clawdock-token`       | Print the gateway token                 |
-| `clawdock-cd`          | Jump to the FengMing project directory  |
-| `clawdock-config`      | Open `~/.fengming`                      |
-| `clawdock-show-config` | Print config files with redacted values |
-| `clawdock-workspace`   | Open the workspace directory            |
-
-## First-time flow
-
-```bash
-clawdock-start
-clawdock-fix-token
-clawdock-dashboard
-```
-
-If the browser says pairing is required:
-
-```bash
-clawdock-devices
-clawdock-approve <request-id>
-```
-
-## Config and secrets
-
-ClawDock works with the same Docker config split described in [Docker](/install/docker):
-
-- `<project>/.env` for Docker-specific values like image name, ports, and the gateway token
-- `~/.fengming/.env` for env-backed provider keys and bot tokens
-- `~/.fengming/agents/<agentId>/agent/auth-profiles.json` for stored provider OAuth/API-key auth
-- `~/.fengming/fengming.json` for behavior config
-
-Use `clawdock-show-config` when you want to inspect the `.env` files and `fengming.json` quickly. It redacts `.env` values in its printed output.
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Docker" href="/install/docker" icon="docker">
-    Canonical Docker install for FengMing.
-  </Card>
-  <Card title="Docker VM runtime" href="/install/docker-vm-runtime" icon="cube">
-    Docker-managed VM runtime for hardened isolation.
-  </Card>
-  <Card title="Updating" href="/install/updating" icon="arrow-up-right-from-square">
-    Updating the FengMing package and managed services.
-  </Card>
-</CardGroup>

package/docs/install/development-channels.md

@@ -1,148 +0,0 @@
----
-summary: "Stable, beta, and dev channels: semantics, switching, pinning, and tagging"
-read_when:
-  - You want to switch between stable/beta/dev
-  - You want to pin a specific version, tag, or SHA
-  - You are tagging or publishing prereleases
-title: "Release channels"
-sidebarTitle: "Release Channels"
----
-
-FengMing ships three update channels:
-
-- **stable**: npm dist-tag `latest`. Recommended for most users.
-- **beta**: npm dist-tag `beta` when it is current; if beta is missing or older than
-  the latest stable release, the update flow falls back to `latest`.
-- **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
-  The `main` branch is for experimentation and active development. It may contain
-  incomplete features or breaking changes. Do not use it for production gateways.
-
-We usually ship stable builds to **beta** first, test them there, then run an
-explicit promotion step that moves the vetted build to `latest` without
-changing the version number. Maintainers can also publish a stable release
-directly to `latest` when needed. Dist-tags are the source of truth for npm
-installs.
-
-## Switching channels
-
-```bash
-fengming update --channel stable
-fengming update --channel beta
-fengming update --channel dev
-```
-
-`--channel` persists your choice in config (`update.channel`) and aligns the
-install method:
-
-- **`stable`** (package installs): updates via npm dist-tag `latest`.
-- **`beta`** (package installs): prefers npm dist-tag `beta`, but falls back to
-  `latest` when `beta` is missing or older than the current stable tag.
-- **`stable`** (git installs): checks out the latest stable git tag, excluding
-  semver prerelease tags such as `-alpha.N`, `-beta.N`, `-rc.N`, `-dev.N`,
-  `-next.N`, `-preview.N`, `-canary.N`, `-nightly.N`, and other prerelease
-  suffixes.
-- **`beta`** (git installs): prefers the latest beta git tag, but falls back to
-  the latest stable git tag when beta is missing or older.
-- **`dev`**: ensures a git checkout (default `~/fengming`, or
-  `$FENGMING_HOME/fengming` when `FENGMING_HOME` is set; override with
-  `FENGMING_GIT_DIR`), switches to `main`, rebases on upstream, builds, and
-  installs the global CLI from that checkout.
-
-<Tip>
-If you want stable and dev in parallel, keep two clones and point your gateway at the stable one.
-</Tip>
-
-## One-off version or tag targeting
-
-Use `--tag` to target a specific dist-tag, version, or package spec for a single
-update **without** changing your persisted channel:
-
-```bash
-# Install a specific version
-fengming update --tag 2026.4.1-beta.1
-
-# Install from the beta dist-tag (one-off, does not persist)
-fengming update --tag beta
-
-# Switch to the moving GitHub main checkout
-fengming update --channel dev
-
-# Install a specific npm package spec
-fengming update --tag fengming@2026.4.1-beta.1
-
-# Install from GitHub main once without persisting the channel
-fengming update --tag main
-```
-
-Notes:
-
-- `--tag` applies to **package (npm) installs only**. Git installs ignore it.
-- The tag is not persisted. Your next `fengming update` uses your configured
-  channel as usual.
-- For package installs, FengMing pre-packs GitHub/git source specs into a
-  temporary tarball before the staged npm install. Use `--channel dev` or
-  `--install-method git --version main` when you want the moving `main`
-  checkout as your persistent install.
-- Downgrade protection: if the target version is older than your current version,
-  FengMing prompts for confirmation (skip with `--yes`).
-- `--channel beta` is different from `--tag beta`: the channel flow can fall back
-  to stable/latest when beta is missing or older, while `--tag beta` targets the
-  raw `beta` dist-tag for that one run.
-
-## Dry run
-
-Preview what `fengming update` would do without making changes:
-
-```bash
-fengming update --dry-run
-fengming update --channel beta --dry-run
-fengming update --tag 2026.4.1-beta.1 --dry-run
-fengming update --dry-run --json
-```
-
-The dry run shows the effective channel, target version, planned actions, and
-whether a downgrade confirmation would be required.
-
-## Plugins and channels
-
-When you switch channels with `fengming update`, FengMing also syncs plugin
-sources:
-
-- `dev` prefers bundled plugins from the git checkout.
-- `stable` and `beta` restore npm-installed plugin packages.
-- npm-installed plugins are updated after the core update completes.
-
-## Checking current status
-
-```bash
-fengming update status
-```
-
-Shows the active channel, install kind (git or package), current version, and
-source (config, git tag, git branch, or default).
-
-## Tagging best practices
-
-- Tag releases you want git checkouts to land on (`vYYYY.M.D` for stable,
-  `vYYYY.M.D-beta.N` for beta; named semver prerelease suffixes such as
-  `-alpha.N`, `-rc.N`, and `-next.N` are not stable targets).
-- Legacy numeric stable tags such as `vYYYY.M.D-1` and `v1.0.1-1` are still
-  recognized as stable git tags for compatibility.
-- `vYYYY.M.D.beta.N` is also recognized for compatibility, but prefer `-beta.N`.
-- Keep tags immutable: never move or reuse a tag.
-- npm dist-tags remain the source of truth for npm installs:
-  - `latest` -> stable
-  - `beta` -> candidate build or beta-first stable build
-  - `dev` -> main snapshot (optional)
-
-## macOS app availability
-
-Beta and dev builds may **not** include a macOS app release. That is OK:
-
-- The git tag and npm dist-tag can still be published.
-- Call out "no macOS build for this beta" in release notes or changelog.
-
-## Related
-
-- [Updating](/install/updating)
-- [Installer internals](/install/installer)

package/docs/install/digitalocean.md

@@ -1,174 +0,0 @@
----
-summary: "Host FengMing on a DigitalOcean Droplet"
-read_when:
-  - Setting up FengMing on DigitalOcean
-  - Looking for a simple paid VPS for FengMing
-title: "DigitalOcean"
----
-
-Run a persistent FengMing Gateway on a DigitalOcean Droplet (~$6/month for the 1 GB Basic plan).
-
-DigitalOcean is the simplest paid VPS path. If you prefer cheaper or free options:
-
-- [Hetzner](/install/hetzner) — €3.79/mo, more cores/RAM per dollar.
-- [Oracle Cloud](/install/oracle) — Always Free ARM (up to 4 OCPU, 24 GB RAM), but signup can be finicky and ARM-only.
-
-## Prerequisites
-
-- DigitalOcean account ([signup](https://cloud.digitalocean.com/registrations/new))
-- SSH key pair (or willingness to use password auth)
-- About 20 minutes
-
-## Setup
-
-<Steps>
-  <Step title="Create a Droplet">
-    <Warning>
-    Use a clean base image (Ubuntu 24.04 LTS). Avoid third-party Marketplace 1-click images unless you have reviewed their startup scripts and firewall defaults.
-    </Warning>
-
-    1. Log into [DigitalOcean](https://cloud.digitalocean.com/).
-    2. Click **Create > Droplets**.
-    3. Choose:
-       - **Region:** Closest to you
-       - **Image:** Ubuntu 24.04 LTS
-       - **Size:** Basic, Regular, 1 vCPU / 1 GB RAM / 25 GB SSD
-       - **Authentication:** SSH key (recommended) or password
-    4. Click **Create Droplet** and note the IP address.
-
-  </Step>
-
-  <Step title="Connect and install">
-    ```bash
-    ssh root@YOUR_DROPLET_IP
-
-    apt update && apt upgrade -y
-
-    # Install Node.js 24
-    curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
-    apt install -y nodejs
-
-    # Install FengMing
-    curl -fsSL https://fengming.ai/install.sh | bash
-
-    # Create the non-root user that will own FengMing state and services.
-    adduser fengming
-    usermod -aG sudo fengming
-    loginctl enable-linger fengming
-
-    su - fengming
-    fengming --version
-    ```
-
-    Use the root shell only for system bootstrap. Run FengMing commands as the non-root `fengming` user so state lives under `/home/fengming/.fengming/` and the Gateway installs as that user's systemd service.
-
-  </Step>
-
-  <Step title="Run onboarding">
-    ```bash
-    fengming onboard --install-daemon
-    ```
-
-    The wizard walks you through model auth, channel setup, gateway token generation, and daemon installation (systemd).
-
-  </Step>
-
-  <Step title="Add swap (recommended for 1 GB Droplets)">
-    ```bash
-    fallocate -l 2G /swapfile
-    chmod 600 /swapfile
-    mkswap /swapfile
-    swapon /swapfile
-    echo '/swapfile none swap sw 0 0' >> /etc/fstab
-    ```
-  </Step>
-
-  <Step title="Verify the gateway">
-    ```bash
-    fengming status
-    systemctl --user status fengming-gateway.service
-    journalctl --user -u fengming-gateway.service -f
-    ```
-  </Step>
-
-  <Step title="Access the Control UI">
-    The gateway binds to loopback by default. Pick one of these options.
-
-    **Option A: SSH tunnel (simplest)**
-
-    ```bash
-    # From your local machine
-    ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP
-    ```
-
-    Then open `http://localhost:18789`.
-
-    **Option B: Tailscale Serve**
-
-    ```bash
-    curl -fsSL https://tailscale.com/install.sh | sudo sh
-    sudo tailscale up
-    fengming config set gateway.tailscale.mode serve
-    fengming gateway restart
-    ```
-
-    Then open `https://<magicdns>/` from any device on your tailnet.
-
-    Tailscale Serve authenticates Control UI and WebSocket traffic via tailnet identity headers, which assumes the gateway host itself is trusted. HTTP API endpoints follow the gateway's normal auth mode (token/password) regardless. To require explicit shared-secret credentials over Serve, set `gateway.auth.allowTailscale: false` and use `gateway.auth.mode: "token"` or `"password"`.
-
-    **Option C: Tailnet bind (no Serve)**
-
-    ```bash
-    fengming config set gateway.bind tailnet
-    fengming gateway restart
-    ```
-
-    Then open `http://<tailscale-ip>:18789` (token required).
-
-  </Step>
-</Steps>
-
-## Persistence and backups
-
-FengMing state lives under:
-
-- `~/.fengming/` — `fengming.json`, per-agent `auth-profiles.json`, channel/provider state, and session data.
-- `~/.fengming/workspace/` — the agent workspace (SOUL.md, memory, artifacts).
-
-These survive Droplet reboots. To take a portable snapshot:
-
-```bash
-fengming backup create
-```
-
-DigitalOcean snapshots back the whole Droplet up; `fengming backup create` is portable across hosts.
-
-## 1 GB RAM tips
-
-The $6 Droplet only has 1 GB RAM. To keep things smooth:
-
-- Make sure the swap step above is in `/etc/fstab` so it survives reboots.
-- Prefer API-based models (Claude, GPT) over local ones — local LLM inference does not fit in 1 GB.
-- Set `agents.defaults.model.primary` to a smaller model if you hit OOMs on large prompts.
-- Monitor with `free -h` and `htop`.
-
-## Troubleshooting
-
-**Gateway will not start** -- Run `fengming doctor --non-interactive` and check logs with `journalctl --user -u fengming-gateway.service -n 50`.
-
-**Port already in use** -- Run `lsof -i :18789` to find the process, then stop it.
-
-**Out of memory** -- Verify swap is active with `free -h`. If still hitting OOM, use API-based models (Claude, GPT) rather than local models, or upgrade to a 2 GB Droplet.
-
-## Next steps
-
-- [Channels](/channels) -- connect Telegram, WhatsApp, Discord, and more
-- [Gateway configuration](/gateway/configuration) -- all config options
-- [Updating](/install/updating) -- keep FengMing up to date
-
-## Related
-
-- [Install overview](/install)
-- [Fly.io](/install/fly)
-- [Hetzner](/install/hetzner)
-- [VPS hosting](/vps)

package/docs/install/docker-vm-runtime.md

@@ -1,154 +0,0 @@
----
-summary: "Shared Docker VM runtime steps for long-lived FengMing Gateway hosts"
-read_when:
-  - You are deploying FengMing on a cloud VM with Docker
-  - You need the shared binary bake, persistence, and update flow
-title: "Docker VM runtime"
----
-
-Shared runtime steps for VM-based Docker installs such as GCP, Hetzner, and similar VPS providers.
-
-## Bake required binaries into the image
-
-Installing binaries inside a running container is a trap.
-Anything installed at runtime will be lost on restart.
-
-All external binaries required by skills must be installed at image build time.
-
-The examples below show three common binaries only:
-
-- `gog` (from `gogcli`) for Gmail access
-- `goplaces` for Google Places
-- `wacli` for WhatsApp
-
-These are examples, not a complete list.
-You may install as many binaries as needed using the same pattern.
-
-If you add new skills later that depend on additional binaries, you must:
-
-1. Update the Dockerfile
-2. Rebuild the image
-3. Restart the containers
-
-**Example Dockerfile**
-
-```dockerfile
-FROM node:24-bookworm
-
-RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
-
-# Example binary 1: Gmail CLI (gogcli — installs as `gog`)
-# Copy the current Linux asset URL from https://github.com/steipete/gogcli/releases
-RUN curl -L https://github.com/steipete/gogcli/releases/latest/download/gogcli_linux_amd64.tar.gz \
-  | tar -xzO gog > /usr/local/bin/gog; \
-  chmod +x /usr/local/bin/gog
-
-# Example binary 2: Google Places CLI
-# Copy the current Linux asset URL from https://github.com/steipete/goplaces/releases
-RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_linux_amd64.tar.gz \
-  | tar -xzO goplaces > /usr/local/bin/goplaces; \
-  chmod +x /usr/local/bin/goplaces
-
-# Example binary 3: WhatsApp CLI
-# Copy the current Linux asset URL from https://github.com/steipete/wacli/releases
-RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli-linux-amd64.tar.gz \
-  | tar -xzO wacli > /usr/local/bin/wacli; \
-  chmod +x /usr/local/bin/wacli
-
-# Add more binaries below using the same pattern
-
-WORKDIR /app
-COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
-COPY ui/package.json ./ui/package.json
-COPY scripts ./scripts
-
-RUN corepack enable
-RUN pnpm install --frozen-lockfile
-
-COPY . .
-RUN pnpm build
-RUN pnpm ui:install
-RUN pnpm ui:build
-
-ENV NODE_ENV=production
-
-CMD ["node","dist/index.js"]
-```
-
-<Note>
-The URLs above are examples. For ARM-based VMs, choose the `arm64` assets. For reproducible builds, pin versioned release URLs.
-</Note>
-
-## Build and launch
-
-```bash
-docker compose build
-docker compose up -d fengming-gateway
-```
-
-If build fails with `Killed` or `exit code 137` during `pnpm install --frozen-lockfile`, the VM is out of memory.
-Use a larger machine class before retrying.
-
-Verify binaries:
-
-```bash
-docker compose exec fengming-gateway which gog
-docker compose exec fengming-gateway which goplaces
-docker compose exec fengming-gateway which wacli
-```
-
-Expected output:
-
-```
-/usr/local/bin/gog
-/usr/local/bin/goplaces
-/usr/local/bin/wacli
-```
-
-Verify Gateway:
-
-```bash
-docker compose logs -f fengming-gateway
-```
-
-Expected output:
-
-```
-[gateway] listening on ws://0.0.0.0:18789
-```
-
-## What persists where
-
-FengMing runs in Docker, but Docker is not the source of truth.
-All long-lived state must survive restarts, rebuilds, and reboots.
-
-| Component           | Location                                               | Persistence mechanism  | Notes                                                         |
-| ------------------- | ------------------------------------------------------ | ---------------------- | ------------------------------------------------------------- |
-| Gateway config      | `/home/node/.fengming/`                                | Host volume mount      | Includes `fengming.json`, `.env`                              |
-| Model auth profiles | `/home/node/.fengming/agents/`                         | Host volume mount      | `agents/<agentId>/agent/auth-profiles.json` (OAuth, API keys) |
-| Auth profile key    | `/home/node/.config/fengming/`                         | Host volume mount      | Local encryption key for OAuth auth profile token material    |
-| Skill configs       | `/home/node/.fengming/skills/`                         | Host volume mount      | Skill-level state                                             |
-| Agent workspace     | `/home/node/.fengming/workspace/`                      | Host volume mount      | Code and agent artifacts                                      |
-| WhatsApp session    | `/home/node/.fengming/`                                | Host volume mount      | Preserves QR login                                            |
-| Gmail keyring       | `/home/node/.fengming/`                                | Host volume + password | Requires `GOG_KEYRING_PASSWORD`                               |
-| Plugin packages     | `/home/node/.fengming/npm`, `/home/node/.fengming/git` | Host volume mount      | Downloadable plugin package roots                             |
-| External binaries   | `/usr/local/bin/`                                      | Docker image           | Must be baked at build time                                   |
-| Node runtime        | Container filesystem                                   | Docker image           | Rebuilt every image build                                     |
-| OS packages         | Container filesystem                                   | Docker image           | Do not install at runtime                                     |
-| Docker container    | Ephemeral                                              | Restartable            | Safe to destroy                                               |
-
-## Updates
-
-To update FengMing on the VM:
-
-```bash
-git pull
-docker compose build
-docker compose up -d
-```
-
-## Related
-
-- [Docker](/install/docker)
-- [Podman](/install/podman)
-- [ClawDock](/install/clawdock)