fengming 0.3.9 → 0.3.11

package/docs/install/macos-vm.md

@@ -1,281 +0,0 @@
----
-summary: "Run FengMing in a sandboxed macOS VM (local or hosted) when you need isolation or iMessage"
-read_when:
-  - You want FengMing isolated from your main macOS environment
-  - You want iMessage integration in a sandbox
-  - You want a resettable macOS environment you can clone
-  - You want to compare local vs hosted macOS VM options
-title: "macOS VMs"
----
-
-## Recommended default (most users)
-
-- **Small Linux VPS** for an always-on Gateway and low cost. See [VPS hosting](/vps).
-- **Dedicated hardware** (Mac mini or Linux box) if you want full control and a **residential IP** for browser automation. Many sites block data center IPs, so local browsing often works better.
-- **Hybrid:** keep the Gateway on a cheap VPS, and connect your Mac as a **node** when you need browser/UI automation. See [Nodes](/nodes) and [Gateway remote](/gateway/remote).
-
-Use a macOS VM when you specifically need macOS-only capabilities such as iMessage or want strict isolation from your daily Mac.
-
-## macOS VM options
-
-### Local VM on your Apple Silicon Mac (Lume)
-
-Run FengMing in a sandboxed macOS VM on your existing Apple Silicon Mac using [Lume](https://cua.ai/docs/lume).
-
-This gives you:
-
-- Full macOS environment in isolation (your host stays clean)
-- iMessage support via `imsg` (the default local path is impossible on Linux/Windows)
-- Instant reset by cloning VMs
-- No extra hardware or cloud costs
-
-### Hosted Mac providers (cloud)
-
-If you want macOS in the cloud, hosted Mac providers work too:
-
-- [MacStadium](https://www.macstadium.com/) (hosted Macs)
-- Other hosted Mac vendors also work; follow their VM + SSH docs
-
-Once you have SSH access to a macOS VM, continue at step 6 below.
-
----
-
-## Quick path (Lume, experienced users)
-
-1. Install Lume
-2. `lume create fengming --os macos --ipsw latest`
-3. Complete Setup Assistant, enable Remote Login (SSH)
-4. `lume run fengming --no-display`
-5. SSH in, install FengMing, configure channels
-6. Done
-
----
-
-## What you need (Lume)
-
-- Apple Silicon Mac (M1/M2/M3/M4)
-- macOS Sequoia or later on the host
-- ~60 GB free disk space per VM
-- ~20 minutes
-
----
-
-## 1) Install Lume
-
-```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"
-```
-
-If `~/.local/bin` isn't in your PATH:
-
-```bash
-echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc && source ~/.zshrc
-```
-
-Verify:
-
-```bash
-lume --version
-```
-
-Docs: [Lume Installation](https://cua.ai/docs/lume/guide/getting-started/installation)
-
----
-
-## 2) Create the macOS VM
-
-```bash
-lume create fengming --os macos --ipsw latest
-```
-
-This downloads macOS and creates the VM. A VNC window opens automatically.
-
-<Note>
-The download can take a while depending on your connection.
-</Note>
-
----
-
-## 3) Complete Setup Assistant
-
-In the VNC window:
-
-1. Select language and region
-2. Skip Apple ID (or sign in if you want iMessage later)
-3. Create a user account (remember the username and password)
-4. Skip all optional features
-
-After setup completes:
-
-1. Enable SSH: Open System Settings -> General -> Sharing and enable "Remote Login".
-2. For headless VM use, enable auto-login: Open System Settings -> Users & Groups, select "Automatically log in as:", and choose the VM user.
-
----
-
-## 4) Get the VM IP address
-
-```bash
-lume get fengming
-```
-
-Look for the IP address (usually `192.168.64.x`).
-
----
-
-## 5) SSH into the VM
-
-```bash
-ssh youruser@192.168.64.X
-```
-
-Replace `youruser` with the account you created, and the IP with your VM's IP.
-
----
-
-## 6) Install FengMing
-
-Inside the VM:
-
-```bash
-npm install -g fengming@latest
-fengming onboard --install-daemon
-```
-
-Follow the onboarding prompts to set up your model provider (Anthropic, OpenAI, etc.).
-
----
-
-## 7) Configure channels
-
-Edit the config file:
-
-```bash
-nano ~/.fengming/fengming.json
-```
-
-Add your channels:
-
-```json5
-{
-  channels: {
-    whatsapp: {
-      dmPolicy: "allowlist",
-      allowFrom: ["+15551234567"],
-    },
-    telegram: {
-      botToken: "YOUR_BOT_TOKEN",
-    },
-  },
-}
-```
-
-Then login to WhatsApp (scan QR):
-
-```bash
-fengming channels login
-```
-
----
-
-## 8) Run the VM headlessly
-
-Stop the VM and restart without display:
-
-```bash
-lume stop fengming
-lume run fengming --no-display
-```
-
-The VM runs in the background. FengMing's daemon keeps the gateway running.
-
-To check status:
-
-```bash
-ssh youruser@192.168.64.X "fengming status"
-```
-
----
-
-## Bonus: iMessage integration
-
-This is the killer feature of running on macOS. Use [iMessage](/channels/imessage) with `imsg` to add Messages to FengMing.
-
-Inside the VM:
-
-1. Sign in to Messages.
-2. Install `imsg`.
-3. Grant Full Disk Access and Automation permission for the process running FengMing/`imsg`.
-4. Verify RPC support with `imsg rpc --help`.
-
-Add to your FengMing config:
-
-```json5
-{
-  channels: {
-    imessage: {
-      enabled: true,
-      cliPath: "imsg",
-      dbPath: "~/Library/Messages/chat.db",
-    },
-  },
-}
-```
-
-Restart the gateway. Now your agent can send and receive iMessages.
-
-Full setup details: [iMessage channel](/channels/imessage)
-
----
-
-## Save a golden image
-
-Before customizing further, snapshot your clean state:
-
-```bash
-lume stop fengming
-lume clone fengming fengming-golden
-```
-
-Reset anytime:
-
-```bash
-lume stop fengming && lume delete fengming
-lume clone fengming-golden fengming
-lume run fengming --no-display
-```
-
----
-
-## Running 24/7
-
-Keep the VM running by:
-
-- Keeping your Mac plugged in
-- Disabling sleep in System Settings → Energy Saver
-- Using `caffeinate` if needed
-
-For true always-on, consider a dedicated Mac mini or a small VPS. See [VPS hosting](/vps).
-
----
-
-## Troubleshooting
-
-| Problem                  | Solution                                                                           |
-| ------------------------ | ---------------------------------------------------------------------------------- |
-| Can't SSH into VM        | Check "Remote Login" is enabled in VM's System Settings                            |
-| VM IP not showing        | Wait for VM to fully boot, run `lume get fengming` again                           |
-| Lume command not found   | Add `~/.local/bin` to your PATH                                                    |
-| WhatsApp QR not scanning | Ensure you're logged into the VM (not host) when running `fengming channels login` |
-
----
-
-## Related docs
-
-- [VPS hosting](/vps)
-- [Nodes](/nodes)
-- [Gateway remote](/gateway/remote)
-- [iMessage channel](/channels/imessage)
-- [Lume Quickstart](https://cua.ai/docs/lume/guide/getting-started/quickstart)
-- [Lume CLI Reference](https://cua.ai/docs/lume/reference/cli-reference)
-- [Unattended VM Setup](https://cua.ai/docs/lume/guide/fundamentals/unattended-setup) (advanced)
-- [Docker Sandboxing](/install/docker) (alternative isolation approach)

package/docs/install/migrating-claude.md

@@ -1,165 +0,0 @@
----
-summary: "Move Claude Code and Claude Desktop local state into FengMing with a previewed import"
-read_when:
-  - You are coming from Claude Code or Claude Desktop and want to keep instructions, MCP servers, and skills
-  - You need to understand what FengMing imports automatically and what stays archive-only
-title: "Migrating from Claude"
----
-
-FengMing imports local Claude state through the bundled Claude migration provider. The provider previews every item before changing state, redacts secrets in plans and reports, and creates a verified backup before apply.
-
-<Note>
-Onboarding imports require a fresh FengMing setup. If you already have local FengMing state, reset config, credentials, sessions, and the workspace first, or use `fengming migrate` directly with `--overwrite` after reviewing the plan.
-</Note>
-
-## Two ways to import
-
-<Tabs>
-  <Tab title="Onboarding wizard">
-    The wizard offers Claude when it detects local Claude state.
-
-    ```bash
-    fengming onboard --flow import
-    ```
-
-    Or point at a specific source:
-
-    ```bash
-    fengming onboard --import-from claude --import-source ~/.claude
-    ```
-
-  </Tab>
-  <Tab title="CLI">
-    Use `fengming migrate` for scripted or repeatable runs. See [`fengming migrate`](/cli/migrate) for the full reference.
-
-    ```bash
-    fengming migrate claude --dry-run
-    fengming migrate apply claude --yes
-    ```
-
-    Add `--from <path>` to import a specific Claude Code home or project root.
-
-  </Tab>
-</Tabs>
-
-## What gets imported
-
-<AccordionGroup>
-  <Accordion title="Instructions and memory">
-    - Project `CLAUDE.md` and `.claude/CLAUDE.md` content is copied or appended into the FengMing agent workspace `AGENTS.md`.
-    - User `~/.claude/CLAUDE.md` content is appended into workspace `USER.md`.
-
-  </Accordion>
-  <Accordion title="MCP servers">
-    MCP server definitions are imported from project `.mcp.json`, Claude Code `~/.claude.json`, and Claude Desktop `claude_desktop_config.json` when present.
-  </Accordion>
-  <Accordion title="Skills and commands">
-    - Claude skills with a `SKILL.md` file are copied into the FengMing workspace skills directory.
-    - Claude command Markdown files under `.claude/commands/` or `~/.claude/commands/` are converted into FengMing skills with `disable-model-invocation: true`.
-
-  </Accordion>
-</AccordionGroup>
-
-## What stays archive-only
-
-The provider copies these into the migration report for manual review, but does **not** load them into live FengMing config:
-
-- Claude hooks
-- Claude permissions and broad tool allowlists
-- Claude environment defaults
-- `CLAUDE.local.md`
-- `.claude/rules/`
-- Claude subagents under `.claude/agents/` or `~/.claude/agents/`
-- Claude Code caches, plans, and project history directories
-- Claude Desktop extensions and OS-stored credentials
-
-FengMing refuses to execute hooks, trust permission allowlists, or decode opaque OAuth and Desktop credential state automatically. Move what you need by hand after reviewing the archive.
-
-## Source selection
-
-Without `--from`, FengMing inspects the default Claude Code home at `~/.claude`, the sampled Claude Code `~/.claude.json` state file, and the Claude Desktop MCP config on macOS.
-
-When `--from` points at a project root, FengMing imports only that project's Claude files such as `CLAUDE.md`, `.claude/settings.json`, `.claude/commands/`, `.claude/skills/`, and `.mcp.json`. It does not read your global Claude home during a project-root import.
-
-## Recommended flow
-
-<Steps>
-  <Step title="Preview the plan">
-    ```bash
-    fengming migrate claude --dry-run
-    ```
-
-    The plan lists everything that will change, including conflicts, skipped items, and sensitive values redacted from nested MCP `env` or `headers` fields.
-
-  </Step>
-  <Step title="Apply with backup">
-    ```bash
-    fengming migrate apply claude --yes
-    ```
-
-    FengMing creates and verifies a backup before applying.
-
-  </Step>
-  <Step title="Run doctor">
-    ```bash
-    fengming doctor
-    ```
-
-    [Doctor](/gateway/doctor) checks for config or state issues after the import.
-
-  </Step>
-  <Step title="Restart and verify">
-    ```bash
-    fengming gateway restart
-    fengming status
-    ```
-
-    Confirm the gateway is healthy and your imported instructions, MCP servers, and skills are loaded.
-
-  </Step>
-</Steps>
-
-## Conflict handling
-
-Apply refuses to continue when the plan reports conflicts (a file or config value already exists at the target).
-
-<Warning>
-Rerun with `--overwrite` only when replacing the existing target is intentional. Providers may still write item-level backups for overwritten files in the migration report directory.
-</Warning>
-
-For a fresh FengMing install, conflicts are unusual. They typically appear when you re-run the import on a setup that already has user edits.
-
-## JSON output for automation
-
-```bash
-fengming migrate claude --dry-run --json
-fengming migrate apply claude --json --yes
-```
-
-With `--json` and no `--yes`, apply prints the plan and does not mutate state. This is the safest mode for CI and shared scripts.
-
-## Troubleshooting
-
-<AccordionGroup>
-  <Accordion title="Claude state lives outside ~/.claude">
-    Pass `--from /actual/path` (CLI) or `--import-source /actual/path` (onboarding).
-  </Accordion>
-  <Accordion title="Onboarding refuses to import on an existing setup">
-    Onboarding imports require a fresh setup. Either reset state and re-onboard, or use `fengming migrate apply claude` directly, which supports `--overwrite` and explicit backup control.
-  </Accordion>
-  <Accordion title="MCP servers from Claude Desktop did not import">
-    Claude Desktop reads `claude_desktop_config.json` from a platform-specific path. Point `--from` at that file's directory if FengMing did not detect it automatically.
-  </Accordion>
-  <Accordion title="Claude commands became skills with model invocation disabled">
-    By design. Claude commands are user-triggered, so FengMing imports them as skills with `disable-model-invocation: true`. Edit each skill's frontmatter if you want the agent to invoke them automatically.
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-- [`fengming migrate`](/cli/migrate): full CLI reference, plugin contract, and JSON shapes.
-- [Migration guide](/install/migrating): all migration paths.
-- [Migrating from Hermes](/install/migrating-hermes): the other cross-system import path.
-- [Onboarding](/cli/onboard): wizard flow and non-interactive flags.
-- [Doctor](/gateway/doctor): post-migration health check.
-- [Agent workspace](/concepts/agent-workspace): where `AGENTS.md`, `USER.md`, and skills live.

package/docs/install/migrating-hermes.md

@@ -1,178 +0,0 @@
----
-summary: "Move from Hermes to FengMing with a previewed, reversible import"
-read_when:
-  - You are coming from Hermes and want to keep your model config, prompts, memory, and skills
-  - You want to know what FengMing imports automatically and what stays archive-only
-  - You need a clean, scripted migration path (CI, fresh laptop, automation)
-title: "Migrating from Hermes"
----
-
-FengMing imports Hermes state through a bundled migration provider. The provider previews everything before changing state, redacts secrets in plans and reports, and creates a verified backup before apply.
-
-<Note>
-Imports require a fresh FengMing setup. If you already have local FengMing state, reset config, credentials, sessions, and the workspace first, or use `fengming migrate` directly with `--overwrite` after reviewing the plan.
-</Note>
-
-## Two ways to import
-
-<Tabs>
-  <Tab title="Onboarding wizard">
-    The fastest path. The wizard detects Hermes at `~/.hermes` and shows a preview before applying.
-
-    ```bash
-    fengming onboard --flow import
-    ```
-
-    Or point at a specific source:
-
-    ```bash
-    fengming onboard --import-from hermes --import-source ~/.hermes
-    ```
-
-  </Tab>
-  <Tab title="CLI">
-    Use `fengming migrate` for scripted or repeatable runs. See [`fengming migrate`](/cli/migrate) for the full reference.
-
-    ```bash
-    fengming migrate hermes --dry-run    # preview only
-    fengming migrate apply hermes --yes  # apply with confirmation skipped
-    ```
-
-    Add `--from <path>` when Hermes lives outside `~/.hermes`.
-
-  </Tab>
-</Tabs>
-
-## What gets imported
-
-<AccordionGroup>
-  <Accordion title="Model configuration">
-    - Default model selection from Hermes `config.yaml`.
-    - Configured model providers and custom OpenAI-compatible endpoints from `providers` and `custom_providers`.
-
-  </Accordion>
-  <Accordion title="MCP servers">
-    MCP server definitions from `mcp_servers` or `mcp.servers`.
-  </Accordion>
-  <Accordion title="Workspace files">
-    - `SOUL.md` and `AGENTS.md` are copied into the FengMing agent workspace.
-    - `memories/MEMORY.md` and `memories/USER.md` are **appended** to the matching FengMing memory files instead of overwriting them.
-
-  </Accordion>
-  <Accordion title="Memory configuration">
-    Memory config defaults for FengMing file memory. External memory providers such as Honcho are recorded as archive or manual-review items so you can move them deliberately.
-  </Accordion>
-  <Accordion title="Skills">
-    Skills with a `SKILL.md` file under `skills/<name>/` are copied, along with per-skill config values from `skills.config`.
-  </Accordion>
-  <Accordion title="Auth credentials">
-    Interactive `fengming migrate` asks before importing auth credentials, with yes selected by default. Accepted imports include supported OAuth credentials from Hermes `auth.json`, OpenCode OpenAI OAuth credentials from OpenCode `auth.json`, OpenCode and GitHub Copilot entries from OpenCode `auth.json`, and the [supported `.env` keys](/cli/migrate#supported-env-keys). Use `--include-secrets` for non-interactive `fengming migrate` credential import, `--no-auth-credentials` to skip it, or onboarding `--import-secrets` when importing from the onboarding wizard.
-  </Accordion>
-</AccordionGroup>
-
-## What stays archive-only
-
-The provider copies these into the migration report directory for manual review, but does **not** load them into live FengMing config or credentials:
-
-- `plugins/`
-- `sessions/`
-- `logs/`
-- `cron/`
-- `mcp-tokens/`
-- `state.db`
-
-FengMing refuses to execute or trust this state automatically because the formats and trust assumptions can drift between systems. Move what you need by hand after reviewing the archive.
-
-## Recommended flow
-
-<Steps>
-  <Step title="Preview the plan">
-    ```bash
-    fengming migrate hermes --dry-run
-    ```
-
-    The plan lists everything that will change, including conflicts, skipped items, and any sensitive items. Plan output redacts nested secret-looking keys.
-
-  </Step>
-  <Step title="Apply with backup">
-    ```bash
-    fengming migrate apply hermes --yes
-    ```
-
-    FengMing creates and verifies a backup before applying. This non-interactive example imports non-secret state. Run without `--yes` to answer the credential prompt, or add `--include-secrets` to include supported credentials in unattended runs.
-
-  </Step>
-  <Step title="Run doctor">
-    ```bash
-    fengming doctor
-    ```
-
-    [Doctor](/gateway/doctor) reapplies any pending config migrations and checks for issues introduced during the import.
-
-  </Step>
-  <Step title="Restart and verify">
-    ```bash
-    fengming gateway restart
-    fengming status
-    ```
-
-    Confirm the gateway is healthy and your imported model, memory, and skills are loaded.
-
-  </Step>
-</Steps>
-
-## Conflict handling
-
-Apply refuses to continue when the plan reports conflicts (a file or config value already exists at the target).
-
-<Warning>
-Rerun with `--overwrite` only when replacing the existing target is intentional. Providers may still write item-level backups for overwritten files in the migration report directory.
-</Warning>
-
-For a fresh FengMing install, conflicts are unusual. They typically appear when you re-run the import on a setup that already has user edits.
-
-If a conflict surfaces mid-apply (for example, an unexpected race on a config file), Hermes marks remaining dependent config items as `skipped` with reason `blocked by earlier apply conflict` instead of writing them partially. The migration report records each blocked item so you can resolve the original conflict and rerun the import.
-
-## Secrets
-
-Interactive `fengming migrate` asks whether to import detected auth credentials, with yes selected by default.
-
-- Accepting the prompt imports supported OAuth credentials from Hermes `auth.json`, OpenCode OpenAI OAuth credentials from OpenCode `auth.json`, OpenCode and GitHub Copilot entries from OpenCode `auth.json`, and the [supported `.env` keys](/cli/migrate#supported-env-keys).
-- Use `--no-auth-credentials` or choose no at the prompt to import non-secret state only.
-- Use `--include-secrets` when running unattended with `--yes`.
-- Use onboarding `--import-secrets` when importing credentials from the onboarding wizard.
-- For SecretRef-managed credentials, configure the SecretRef source after the import completes.
-
-## JSON output for automation
-
-```bash
-fengming migrate hermes --dry-run --json
-fengming migrate apply hermes --json --yes
-```
-
-With `--json` and no `--yes`, apply prints the plan and does not mutate state. This is the safest mode for CI and shared scripts.
-
-## Troubleshooting
-
-<AccordionGroup>
-  <Accordion title="Apply refuses with conflicts">
-    Inspect the plan output. Each conflict identifies the source path and the existing target. Decide per item whether to skip, edit the target, or rerun with `--overwrite`.
-  </Accordion>
-  <Accordion title="Hermes lives outside ~/.hermes">
-    Pass `--from /actual/path` (CLI) or `--import-source /actual/path` (onboarding).
-  </Accordion>
-  <Accordion title="Onboarding refuses to import on an existing setup">
-    Onboarding imports require a fresh setup. Either reset state and re-onboard, or use `fengming migrate apply hermes` directly, which supports `--overwrite` and explicit backup control.
-  </Accordion>
-  <Accordion title="API keys did not import">
-    Interactive `fengming migrate` imports API keys only when you accept the credential prompt. Non-interactive `--yes` runs require `--include-secrets`; onboarding imports require `--import-secrets`. Only the [supported `.env` keys](/cli/migrate#supported-env-keys) are recognized; other variables in `.env` are ignored.
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-- [`fengming migrate`](/cli/migrate): full CLI reference, plugin contract, and JSON shapes.
-- [Onboarding](/cli/onboard): wizard flow and non-interactive flags.
-- [Migrating](/install/migrating): move an FengMing install between machines.
-- [Doctor](/gateway/doctor): post-migration health check.
-- [Agent workspace](/concepts/agent-workspace): where `SOUL.md`, `AGENTS.md`, and memory files live.