fengming 0.3.9 → 0.3.11

package/docs/providers/claude-max-api-proxy.md

@@ -1,191 +0,0 @@
----
-summary: "Community proxy to expose Claude subscription credentials as an OpenAI-compatible endpoint"
-read_when:
-  - You want to use Claude Max subscription with OpenAI-compatible tools
-  - You want a local API server that wraps Claude Code CLI
-  - You want to evaluate subscription-based vs API-key-based Anthropic access
-title: "Claude Max API proxy"
----
-
-**claude-max-api-proxy** is a community tool that exposes your Claude Max/Pro subscription as an OpenAI-compatible API endpoint. This allows you to use your subscription with any tool that supports the OpenAI API format.
-
-<Warning>
-This path is technical compatibility only. Anthropic has blocked some subscription
-usage outside Claude Code in the past. You must decide for yourself whether to use
-it and verify Anthropic's current billing rules before relying on it.
-
-Anthropic's current support docs say `claude -p` is Agent SDK/programmatic usage.
-Starting June 15, 2026, subscription-plan `claude -p` usage draws from a separate
-monthly Agent SDK credit first, then from usage credits at standard API rates if
-usage credits are enabled.
-</Warning>
-
-## Why use this?
-
-| Approach                  | Cost route                                      | Best for                                   |
-| ------------------------- | ----------------------------------------------- | ------------------------------------------ |
-| Anthropic API             | Pay per token through Claude Console or cloud   | Production apps, shared automation, volume |
-| Claude subscription proxy | Claude Code / `claude -p` plan and credit rules | Personal experiments with compatible tools |
-
-If you have a Claude Max or Pro subscription and want to use it with
-OpenAI-compatible tools, this proxy may fit some personal workflows. It is not an
-unlimited flat-rate path. API keys remain the clearer policy and billing path for
-production use.
-
-## How it works
-
-```
-Your App → claude-max-api-proxy → Claude Code CLI / claude -p → Anthropic
-     (OpenAI format)              (converts format)          (uses your login)
-```
-
-The proxy:
-
-1. Accepts OpenAI-format requests at `http://localhost:3456/v1/chat/completions`
-2. Converts them to Claude Code CLI commands
-3. Returns responses in OpenAI format (streaming supported)
-
-## Getting started
-
-<Steps>
-  <Step title="Install the proxy">
-    Requires Node.js 20+ and Claude Code CLI.
-
-    ```bash
-    npm install -g claude-max-api-proxy
-
-    # Verify Claude CLI is authenticated
-    claude --version
-    ```
-
-  </Step>
-  <Step title="Start the server">
-    ```bash
-    claude-max-api
-    # Server runs at http://localhost:3456
-    ```
-  </Step>
-  <Step title="Test the proxy">
-    ```bash
-    # Health check
-    curl http://localhost:3456/health
-
-    # List models
-    curl http://localhost:3456/v1/models
-
-    # Chat completion
-    curl http://localhost:3456/v1/chat/completions \
-      -H "Content-Type: application/json" \
-      -d '{
-        "model": "claude-opus-4",
-        "messages": [{"role": "user", "content": "Hello!"}]
-      }'
-    ```
-
-  </Step>
-  <Step title="Configure FengMing">
-    Point FengMing at the proxy as a custom OpenAI-compatible endpoint:
-
-    ```json5
-    {
-      env: {
-        OPENAI_API_KEY: "not-needed",
-        OPENAI_BASE_URL: "http://localhost:3456/v1",
-      },
-      agents: {
-        defaults: {
-          model: { primary: "openai/claude-opus-4" },
-        },
-      },
-    }
-    ```
-
-  </Step>
-</Steps>
-
-## Built-in catalog
-
-| Model ID          | Maps To         |
-| ----------------- | --------------- |
-| `claude-opus-4`   | Claude Opus 4   |
-| `claude-sonnet-4` | Claude Sonnet 4 |
-| `claude-haiku-4`  | Claude Haiku 4  |
-
-## Advanced configuration
-
-<AccordionGroup>
-  <Accordion title="Proxy-style OpenAI-compatible notes">
-    This path uses the same proxy-style OpenAI-compatible route as other custom
-    `/v1` backends:
-
-    - Native OpenAI-only request shaping does not apply
-    - No `service_tier`, no Responses `store`, no prompt-cache hints, and no
-      OpenAI reasoning-compat payload shaping
-    - Hidden FengMing attribution headers (`originator`, `version`, `User-Agent`)
-      are not injected on the proxy URL
-
-  </Accordion>
-
-  <Accordion title="Auto-start on macOS with LaunchAgent">
-    Create a LaunchAgent to run the proxy automatically:
-
-    ```bash
-    cat > ~/Library/LaunchAgents/com.claude-max-api.plist << 'EOF'
-    <?xml version="1.0" encoding="UTF-8"?>
-    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-    <plist version="1.0">
-    <dict>
-      <key>Label</key>
-      <string>com.claude-max-api</string>
-      <key>RunAtLoad</key>
-      <true/>
-      <key>KeepAlive</key>
-      <true/>
-      <key>ProgramArguments</key>
-      <array>
-        <string>/usr/local/bin/node</string>
-        <string>/usr/local/lib/node_modules/claude-max-api-proxy/dist/server/standalone.js</string>
-      </array>
-      <key>EnvironmentVariables</key>
-      <dict>
-        <key>PATH</key>
-        <string>/usr/local/bin:/opt/homebrew/bin:~/.local/bin:/usr/bin:/bin</string>
-      </dict>
-    </dict>
-    </plist>
-    EOF
-
-    launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
-    ```
-
-  </Accordion>
-</AccordionGroup>
-
-## Notes
-
-- This is a **community tool**, not officially supported by Anthropic or FengMing
-- Requires an active Claude Max/Pro subscription with Claude Code CLI authenticated
-- Inherits Claude Code `claude -p` billing, usage-credit, and rate-limit behavior
-- The proxy runs locally and does not send data to any third-party servers
-- Streaming responses are fully supported
-
-<Note>
-For native Anthropic integration with Claude CLI or API keys, see [Anthropic provider](/providers/anthropic). For OpenAI/Codex subscriptions, see [OpenAI provider](/providers/openai).
-</Note>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Anthropic provider" href="/providers/anthropic" icon="bolt">
-    Native FengMing integration with Claude CLI or API keys.
-  </Card>
-  <Card title="OpenAI provider" href="/providers/openai" icon="robot">
-    For OpenAI/Codex subscriptions.
-  </Card>
-  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
-    Overview of all providers, model refs, and failover behavior.
-  </Card>
-  <Card title="Configuration" href="/gateway/configuration" icon="gear">
-    Full config reference.
-  </Card>
-</CardGroup>

package/docs/providers/cloudflare-ai-gateway.md

@@ -1,119 +0,0 @@
----
-summary: "Cloudflare AI Gateway setup (auth + model selection)"
-title: "Cloudflare AI gateway"
-read_when:
-  - You want to use Cloudflare AI Gateway with FengMing
-  - You need the account ID, gateway ID, or API key env var
----
-
-Cloudflare AI Gateway sits in front of provider APIs and lets you add analytics, caching, and controls. For Anthropic, FengMing uses the Anthropic Messages API through your Gateway endpoint.
-
-| Property      | Value                                                                                    |
-| ------------- | ---------------------------------------------------------------------------------------- |
-| Provider      | `cloudflare-ai-gateway`                                                                  |
-| Base URL      | `https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic`               |
-| Default model | `cloudflare-ai-gateway/claude-sonnet-4-6`                                                |
-| API key       | `CLOUDFLARE_AI_GATEWAY_API_KEY` (your provider API key for requests through the Gateway) |
-
-<Note>
-For Anthropic models routed through Cloudflare AI Gateway, use your **Anthropic API key** as the provider key.
-</Note>
-
-When thinking is enabled for Anthropic Messages models, FengMing strips trailing
-assistant prefill turns before sending the payload through Cloudflare AI Gateway.
-Anthropic rejects response prefilling with extended thinking, while ordinary
-non-thinking prefill remains available.
-
-## Getting started
-
-<Steps>
-  <Step title="Set the provider API key and Gateway details">
-    Run onboarding and choose the Cloudflare AI Gateway auth option:
-
-    ```bash
-    fengming onboard --auth-choice cloudflare-ai-gateway-api-key
-    ```
-
-    This prompts for your account ID, gateway ID, and API key.
-
-  </Step>
-  <Step title="Set a default model">
-    Add the model to your FengMing config:
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-6" },
-        },
-      },
-    }
-    ```
-
-  </Step>
-  <Step title="Verify the model is available">
-    ```bash
-    fengming models list --provider cloudflare-ai-gateway
-    ```
-  </Step>
-</Steps>
-
-## Non-interactive example
-
-For scripted or CI setups, pass all values on the command line:
-
-```bash
-fengming onboard --non-interactive \
-  --mode local \
-  --auth-choice cloudflare-ai-gateway-api-key \
-  --cloudflare-ai-gateway-account-id "your-account-id" \
-  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
-  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY"
-```
-
-## Advanced configuration
-
-<AccordionGroup>
-  <Accordion title="Authenticated gateways">
-    If you enabled Gateway authentication in Cloudflare, add the `cf-aig-authorization` header. This is **in addition to** your provider API key.
-
-    ```json5
-    {
-      models: {
-        providers: {
-          "cloudflare-ai-gateway": {
-            headers: {
-              "cf-aig-authorization": "Bearer <cloudflare-ai-gateway-token>",
-            },
-          },
-        },
-      },
-    }
-    ```
-
-    <Tip>
-    The `cf-aig-authorization` header authenticates with the Cloudflare Gateway itself, while the provider API key (for example, your Anthropic key) authenticates with the upstream provider.
-    </Tip>
-
-  </Accordion>
-
-  <Accordion title="Environment note">
-    If the Gateway runs as a daemon (launchd/systemd), make sure `CLOUDFLARE_AI_GATEWAY_API_KEY` is available to that process.
-
-    <Warning>
-    A key exported only in an interactive shell will not help a launchd/systemd daemon unless that environment is imported there as well. Set the key in `~/.fengming/.env` or via `env.shellEnv` to ensure the gateway process can read it.
-    </Warning>
-
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
-    Choosing providers, model refs, and failover behavior.
-  </Card>
-  <Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
-    General troubleshooting and FAQ.
-  </Card>
-</CardGroup>

package/docs/providers/comfy.md

@@ -1,362 +0,0 @@
----
-summary: "ComfyUI workflow image, video, and music generation setup in FengMing"
-title: "ComfyUI"
-read_when:
-  - You want to use local ComfyUI workflows with FengMing
-  - You want to use Comfy Cloud with image, video, or music workflows
-  - You need the bundled comfy plugin config keys
----
-
-FengMing ships a bundled `comfy` plugin for workflow-driven ComfyUI runs. The plugin is entirely workflow-driven, so FengMing does not try to map generic `size`, `aspectRatio`, `resolution`, `durationSeconds`, or TTS-style controls onto your graph.
-
-| Property        | Detail                                                                           |
-| --------------- | -------------------------------------------------------------------------------- |
-| Provider        | `comfy`                                                                          |
-| Models          | `comfy/workflow`                                                                 |
-| Shared surfaces | `image_generate`, `video_generate`, `music_generate`                             |
-| Auth            | None for local ComfyUI; `COMFY_API_KEY` or `COMFY_CLOUD_API_KEY` for Comfy Cloud |
-| API             | ComfyUI `/prompt` / `/history` / `/view` and Comfy Cloud `/api/*`                |
-
-## What it supports
-
-- Image generation from a workflow JSON
-- Image editing with 1 uploaded reference image
-- Video generation from a workflow JSON
-- Video generation with 1 uploaded reference image
-- Music or audio generation through the shared `music_generate` tool
-- Output download from a configured node or all matching output nodes
-
-## Getting started
-
-Choose between running ComfyUI on your own machine or using Comfy Cloud.
-
-<Tabs>
-  <Tab title="Local">
-    **Best for:** running your own ComfyUI instance on your machine or LAN.
-
-    <Steps>
-      <Step title="Start ComfyUI locally">
-        Make sure your local ComfyUI instance is running (defaults to `http://127.0.0.1:8188`).
-      </Step>
-      <Step title="Prepare your workflow JSON">
-        Export or create a ComfyUI workflow JSON file. Note the node IDs for the prompt input node and the output node you want FengMing to read from.
-      </Step>
-      <Step title="Configure the provider">
-        Set `mode: "local"` and point at your workflow file. Here is a minimal image example:
-
-        ```json5
-        {
-          plugins: {
-            entries: {
-              comfy: {
-                config: {
-                  mode: "local",
-                  baseUrl: "http://127.0.0.1:8188",
-                  image: {
-                    workflowPath: "./workflows/flux-api.json",
-                    promptNodeId: "6",
-                    outputNodeId: "9",
-                  },
-                },
-              },
-            },
-          },
-        }
-        ```
-      </Step>
-      <Step title="Set the default model">
-        Point FengMing at the `comfy/workflow` model for the capability you configured:
-
-        ```json5
-        {
-          agents: {
-            defaults: {
-              imageGenerationModel: {
-                primary: "comfy/workflow",
-              },
-            },
-          },
-        }
-        ```
-      </Step>
-      <Step title="Verify">
-        ```bash
-        fengming models list --provider comfy
-        ```
-      </Step>
-    </Steps>
-
-  </Tab>
-
-  <Tab title="Comfy Cloud">
-    **Best for:** running workflows on Comfy Cloud without managing local GPU resources.
-
-    <Steps>
-      <Step title="Get an API key">
-        Sign up at [comfy.org](https://comfy.org) and generate an API key from your account dashboard.
-      </Step>
-      <Step title="Set the API key">
-        Provide your key through one of these methods:
-
-        ```bash
-        # Environment variable (preferred)
-        export COMFY_API_KEY="your-key"
-
-        # Alternative environment variable
-        export COMFY_CLOUD_API_KEY="your-key"
-
-        # Or inline in config
-        fengming config set plugins.entries.comfy.config.apiKey "your-key"
-        ```
-      </Step>
-      <Step title="Prepare your workflow JSON">
-        Export or create a ComfyUI workflow JSON file. Note the node IDs for the prompt input node and the output node.
-      </Step>
-      <Step title="Configure the provider">
-        Set `mode: "cloud"` and point at your workflow file:
-
-        ```json5
-        {
-          plugins: {
-            entries: {
-              comfy: {
-                config: {
-                  mode: "cloud",
-                  image: {
-                    workflowPath: "./workflows/flux-api.json",
-                    promptNodeId: "6",
-                    outputNodeId: "9",
-                  },
-                },
-              },
-            },
-          },
-        }
-        ```
-
-        <Tip>
-        Cloud mode defaults `baseUrl` to `https://cloud.comfy.org`. You only need to set `baseUrl` if you use a custom cloud endpoint.
-        </Tip>
-      </Step>
-      <Step title="Set the default model">
-        ```json5
-        {
-          agents: {
-            defaults: {
-              imageGenerationModel: {
-                primary: "comfy/workflow",
-              },
-            },
-          },
-        }
-        ```
-      </Step>
-      <Step title="Verify">
-        ```bash
-        fengming models list --provider comfy
-        ```
-      </Step>
-    </Steps>
-
-  </Tab>
-</Tabs>
-
-## Configuration
-
-Comfy supports shared top-level connection settings plus per-capability workflow sections (`image`, `video`, `music`):
-
-```json5
-{
-  plugins: {
-    entries: {
-      comfy: {
-        config: {
-          mode: "local",
-          baseUrl: "http://127.0.0.1:8188",
-          image: {
-            workflowPath: "./workflows/flux-api.json",
-            promptNodeId: "6",
-            outputNodeId: "9",
-          },
-          video: {
-            workflowPath: "./workflows/video-api.json",
-            promptNodeId: "12",
-            outputNodeId: "21",
-          },
-          music: {
-            workflowPath: "./workflows/music-api.json",
-            promptNodeId: "3",
-            outputNodeId: "18",
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-### Shared keys
-
-| Key                   | Type                   | Description                                                                           |
-| --------------------- | ---------------------- | ------------------------------------------------------------------------------------- |
-| `mode`                | `"local"` or `"cloud"` | Connection mode.                                                                      |
-| `baseUrl`             | string                 | Defaults to `http://127.0.0.1:8188` for local or `https://cloud.comfy.org` for cloud. |
-| `apiKey`              | string                 | Optional inline key, alternative to `COMFY_API_KEY` / `COMFY_CLOUD_API_KEY` env vars. |
-| `allowPrivateNetwork` | boolean                | Allow a private/LAN `baseUrl` in cloud mode.                                          |
-
-### Per-capability keys
-
-These keys apply inside the `image`, `video`, or `music` sections:
-
-| Key                          | Required | Default  | Description                                                                  |
-| ---------------------------- | -------- | -------- | ---------------------------------------------------------------------------- |
-| `workflow` or `workflowPath` | Yes      | --       | Path to the ComfyUI workflow JSON file.                                      |
-| `promptNodeId`               | Yes      | --       | Node ID that receives the text prompt.                                       |
-| `promptInputName`            | No       | `"text"` | Input name on the prompt node.                                               |
-| `outputNodeId`               | No       | --       | Node ID to read output from. If omitted, all matching output nodes are used. |
-| `pollIntervalMs`             | No       | --       | Polling interval in milliseconds for job completion.                         |
-| `timeoutMs`                  | No       | --       | Timeout in milliseconds for the workflow run.                                |
-
-The `image` and `video` sections also support:
-
-| Key                   | Required                             | Default   | Description                                         |
-| --------------------- | ------------------------------------ | --------- | --------------------------------------------------- |
-| `inputImageNodeId`    | Yes (when passing a reference image) | --        | Node ID that receives the uploaded reference image. |
-| `inputImageInputName` | No                                   | `"image"` | Input name on the image node.                       |
-
-## Workflow details
-
-<AccordionGroup>
-  <Accordion title="Image workflows">
-    Set the default image model to `comfy/workflow`:
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          imageGenerationModel: {
-            primary: "comfy/workflow",
-          },
-        },
-      },
-    }
-    ```
-
-    **Reference-image editing example:**
-
-    To enable image editing with an uploaded reference image, add `inputImageNodeId` to your image config:
-
-    ```json5
-    {
-      plugins: {
-        entries: {
-          comfy: {
-            config: {
-              image: {
-                workflowPath: "./workflows/edit-api.json",
-                promptNodeId: "6",
-                inputImageNodeId: "7",
-                inputImageInputName: "image",
-                outputNodeId: "9",
-              },
-            },
-          },
-        },
-      },
-    }
-    ```
-
-  </Accordion>
-
-  <Accordion title="Video workflows">
-    Set the default video model to `comfy/workflow`:
-
-    ```json5
-    {
-      agents: {
-        defaults: {
-          videoGenerationModel: {
-            primary: "comfy/workflow",
-          },
-        },
-      },
-    }
-    ```
-
-    Comfy video workflows support text-to-video and image-to-video through the configured graph.
-
-    <Note>
-    FengMing does not pass input videos into Comfy workflows. Only text prompts and single reference images are supported as inputs.
-    </Note>
-
-  </Accordion>
-
-  <Accordion title="Music workflows">
-    The bundled plugin registers a music-generation provider for workflow-defined audio or music outputs, surfaced through the shared `music_generate` tool:
-
-    ```text
-    /tool music_generate prompt="Warm ambient synth loop with soft tape texture"
-    ```
-
-    Use the `music` config section to point at your audio workflow JSON and output node.
-
-  </Accordion>
-
-  <Accordion title="Backward compatibility">
-    Existing top-level image config (without the nested `image` section) still works:
-
-    ```json5
-    {
-      plugins: {
-        entries: {
-          comfy: {
-            config: {
-              workflowPath: "./workflows/flux-api.json",
-              promptNodeId: "6",
-              outputNodeId: "9",
-            },
-          },
-        },
-      },
-    }
-    ```
-
-    FengMing treats that legacy shape as the image workflow config. You do not need to migrate immediately, but the nested `image` / `video` / `music` sections are recommended for new setups.
-
-    <Tip>
-    If you only use image generation, the legacy flat config and the new nested `image` section are functionally equivalent.
-    </Tip>
-
-  </Accordion>
-
-  <Accordion title="Live tests">
-    Opt-in live coverage exists for the bundled plugin:
-
-    ```bash
-    FENGMING_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
-    ```
-
-    The live test skips individual image, video, or music cases unless the matching Comfy workflow section is configured.
-
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Image Generation" href="/tools/image-generation" icon="image">
-    Image generation tool configuration and usage.
-  </Card>
-  <Card title="Video Generation" href="/tools/video-generation" icon="video">
-    Video generation tool configuration and usage.
-  </Card>
-  <Card title="Music Generation" href="/tools/music-generation" icon="music">
-    Music and audio generation tool setup.
-  </Card>
-  <Card title="Provider Directory" href="/providers/index" icon="layers">
-    Overview of all providers and model refs.
-  </Card>
-  <Card title="Configuration reference" href="/gateway/config-agents#agent-defaults" icon="gear">
-    Full config reference including agent defaults.
-  </Card>
-</CardGroup>