fengming 0.3.9 → 0.3.11

package/docs/tools/btw.md

@@ -1,159 +0,0 @@
----
-summary: "Ephemeral side questions with /btw"
-read_when:
-  - You want to ask a quick side question about the current session
-  - You are implementing or debugging BTW behavior across clients
-title: "BTW side questions"
----
-
-`/btw` lets you ask a quick side question about the **current session** without
-turning that question into normal conversation history. `/side` is an alias.
-
-It is modeled after Claude Code's `/btw` behavior, but adapted to FengMing's
-Gateway and multi-channel architecture.
-
-## What it does
-
-When you send:
-
-```text
-/btw what changed?
-```
-
-FengMing:
-
-1. snapshots the current session context,
-2. runs a separate ephemeral side query,
-3. answers only the side question,
-4. leaves the main run alone,
-5. does **not** write the BTW question or answer to session history,
-6. emits the answer as a **live side result** rather than a normal assistant message.
-
-The important mental model is:
-
-- same session context
-- separate one-shot side query
-- same native harness transport when the session uses a native harness
-- no future context pollution
-- no transcript persistence
-
-For Codex harness sessions, BTW stays inside Codex by forking the active
-app-server thread as an ephemeral side thread. That keeps Codex OAuth and native
-thread behavior intact while still isolating the side answer from the parent
-transcript. Like Codex `/side`, the side thread keeps the current Codex
-permissions and native tool surface, with guardrails that tell the model not to
-treat inherited parent-thread work as active instructions. Non-Codex runtimes
-keep the older direct one-shot path.
-
-## What it does not do
-
-`/btw` does **not**:
-
-- create a new durable session,
-- continue the unfinished main task,
-- write BTW question/answer data to transcript history,
-- appear in `chat.history`,
-- survive a reload.
-
-It is intentionally **ephemeral**.
-
-## How context works
-
-BTW uses the current session as **background context only**.
-
-If the main run is currently active, FengMing snapshots the current message
-state and includes the in-flight main prompt as background context, while
-explicitly telling the model:
-
-- answer only the side question,
-- do not resume or complete the unfinished main task,
-- do not steer the parent conversation.
-
-That keeps BTW isolated from the main run while still making it aware of what
-the session is about.
-
-## Delivery model
-
-BTW is **not** delivered as a normal assistant transcript message.
-
-At the Gateway protocol level:
-
-- normal assistant chat uses the `chat` event
-- BTW uses the `chat.side_result` event
-
-This separation is intentional. If BTW reused the normal `chat` event path,
-clients would treat it like regular conversation history.
-
-Because BTW uses a separate live event and is not replayed from
-`chat.history`, it disappears after reload.
-
-## Surface behavior
-
-### TUI
-
-In TUI, BTW is rendered inline in the current session view, but it remains
-ephemeral:
-
-- visibly distinct from a normal assistant reply
-- dismissible with `Enter` or `Esc`
-- not replayed on reload
-
-### External channels
-
-On channels like Telegram, WhatsApp, and Discord, BTW is delivered as a
-clearly labeled one-off reply because those surfaces do not have a local
-ephemeral overlay concept.
-
-The answer is still treated as a side result, not normal session history.
-
-### Control UI / web
-
-The Gateway emits BTW correctly as `chat.side_result`, and BTW is not included
-in `chat.history`, so the persistence contract is already correct for web.
-
-The current Control UI still needs a dedicated `chat.side_result` consumer to
-render BTW live in the browser. Until that client-side support lands, BTW is a
-Gateway-level feature with full TUI and external-channel behavior, but not yet
-a complete browser UX.
-
-## When to use BTW
-
-Use `/btw` when you want:
-
-- a quick clarification about the current work,
-- a factual side answer while a long run is still in progress,
-- a temporary answer that should not become part of future session context.
-
-Examples:
-
-```text
-/btw what file are we editing?
-/side what changed while the main run continued?
-/btw what does this error mean?
-/btw summarize the current task in one sentence
-/btw what is 17 * 19?
-```
-
-## When not to use BTW
-
-Do not use `/btw` when you want the answer to become part of the session's
-future working context.
-
-In that case, ask normally in the main session instead of using BTW.
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Slash commands" href="/tools/slash-commands" icon="terminal">
-    Native command catalog and chat directives.
-  </Card>
-  <Card title="Thinking levels" href="/tools/thinking" icon="brain">
-    Reasoning effort levels for the side-question model call.
-  </Card>
-  <Card title="Session" href="/concepts/session" icon="comments">
-    Session keys, history, and persistence semantics.
-  </Card>
-  <Card title="Steer command" href="/tools/steer" icon="arrow-right">
-    Inject a steering message into the active run without ending it.
-  </Card>
-</CardGroup>

package/docs/tools/capability-cookbook.md

@@ -1,12 +0,0 @@
----
-summary: "Redirect to /plugins/adding-capabilities"
-title: "Adding capabilities (redirect)"
-redirect: /plugins/adding-capabilities
----
-
-This contributor guide moved to [Adding capabilities](/plugins/adding-capabilities).
-
-## Related
-
-- [Plugin internals](/plugins/architecture)
-- [Building plugins](/plugins/building-plugins)

package/docs/tools/clawhub.md

@@ -1,5 +0,0 @@
----
-summary: "Redirect to /clawhub"
-title: "ClawHub (redirect)"
-redirect: /clawhub
----

package/docs/tools/code-execution.md

@@ -1,173 +0,0 @@
----
-summary: "code_execution: run sandboxed remote Python analysis with xAI"
-read_when:
-  - You want to enable or configure code_execution
-  - You want remote analysis without local shell access
-  - You want to combine x_search or web_search with remote Python analysis
-title: "Code execution"
----
-
-`code_execution` runs sandboxed remote Python analysis on xAI's Responses API. It is registered by the bundled `xai` plugin (under the `tools` contract) and dispatches to the same `https://api.x.ai/v1/responses` endpoint used by `x_search`.
-
-| Property           | Value                                                                             |
-| ------------------ | --------------------------------------------------------------------------------- |
-| Tool name          | `code_execution`                                                                  |
-| Provider plugin    | `xai` (bundled, `enabledByDefault: true`)                                         |
-| Auth               | xAI auth profile, `XAI_API_KEY`, or `plugins.entries.xai.config.webSearch.apiKey` |
-| Default model      | `grok-4-1-fast`                                                                   |
-| Default timeout    | 30 seconds                                                                        |
-| Default `maxTurns` | unset (xAI applies its own internal limit)                                        |
-
-This is different from local [`exec`](/tools/exec):
-
-- `exec` runs shell commands on your machine or paired node.
-- `code_execution` runs Python in xAI's remote sandbox.
-
-Use `code_execution` for:
-
-- Calculations.
-- Tabulation.
-- Quick statistics.
-- Chart-style analysis.
-- Analyzing data returned by `x_search` or `web_search`.
-
-Do **not** use it when you need local files, your shell, your repo, or paired devices. Use [`exec`](/tools/exec) for that.
-
-## Setup
-
-<Steps>
-  <Step title="Provide xAI credentials">
-    Sign in with Grok OAuth using an eligible SuperGrok or X Premium subscription,
-    use the remote-friendly device-code flow, or store an API key. OAuth works
-    for `code_execution` and `x_search`; `XAI_API_KEY` or plugin web-search
-    config can also power Grok `web_search`.
-
-    ```bash
-    fengming models auth login --provider xai --method oauth
-    fengming models auth login --provider xai --device-code
-    ```
-
-    During a fresh install, the same auth choices are available inside
-    onboarding:
-
-    ```bash
-    fengming onboard --install-daemon
-    fengming onboard --install-daemon --auth-choice xai-device-code
-    ```
-
-    Or use an API key:
-
-    ```bash
-    fengming models auth login --provider xai --method api-key
-    export XAI_API_KEY=xai-...
-    ```
-
-    Or via config:
-
-    ```json5
-    {
-      plugins: {
-        entries: {
-          xai: {
-            config: {
-              webSearch: {
-                apiKey: "xai-...",
-              },
-            },
-          },
-        },
-      },
-    }
-    ```
-
-  </Step>
-
-  <Step title="Enable and tune code_execution">
-    `code_execution` is available when xAI credentials are available. Set
-    `plugins.entries.xai.config.codeExecution.enabled` to `false` to disable it,
-    or use the same block to tune the model and timeout.
-
-    ```json5
-    {
-      plugins: {
-        entries: {
-          xai: {
-            config: {
-              codeExecution: {
-                enabled: true,
-                model: "grok-4-1-fast", // override the default xAI code-execution model
-                maxTurns: 2,            // optional cap on internal tool turns
-                timeoutSeconds: 30,     // request timeout (default: 30)
-              },
-            },
-          },
-        },
-      },
-    }
-    ```
-
-  </Step>
-
-  <Step title="Restart the Gateway">
-    ```bash
-    fengming gateway restart
-    ```
-
-    `code_execution` shows up in the agent's tool list once the xAI plugin re-registers with `enabled: true`.
-
-  </Step>
-</Steps>
-
-## How to use it
-
-Ask naturally and make the analysis intent explicit:
-
-```text
-Use code_execution to calculate the 7-day moving average for these numbers: ...
-```
-
-```text
-Use x_search to find posts mentioning FengMing this week, then use code_execution to count them by day.
-```
-
-```text
-Use web_search to gather the latest AI benchmark numbers, then use code_execution to compare percent changes.
-```
-
-The tool takes a single `task` parameter internally, so the agent should send the full analysis request and any inline data in one prompt.
-
-## Errors
-
-When the tool runs without auth, it returns a structured `missing_xai_api_key` error pointing at the auth-profile, env var, and config options. The error is JSON, not a thrown exception, so the agent can self-correct:
-
-```json
-{
-  "error": "missing_xai_api_key",
-  "message": "code_execution needs xAI credentials. Run `fengming onboard --auth-choice xai-oauth` to sign in with Grok, run `fengming onboard --auth-choice xai-api-key`, set `XAI_API_KEY` in the Gateway environment, or configure `plugins.entries.xai.config.webSearch.apiKey`.",
-  "docs": "https://docs.fengming.ai/tools/code-execution"
-}
-```
-
-## Limits
-
-- This is remote xAI execution, not local process execution.
-- Treat results as ephemeral analysis, not a persistent notebook session.
-- Do not assume access to local files or your workspace.
-- For fresh X data, use [`x_search`](/tools/web#x_search) first and pipe the result into `code_execution`.
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Exec tool" href="/tools/exec" icon="terminal">
-    Local shell execution on your machine or paired node.
-  </Card>
-  <Card title="Exec approvals" href="/tools/exec-approvals" icon="shield">
-    Allow/deny policy for shell execution.
-  </Card>
-  <Card title="Web tools" href="/tools/web" icon="globe">
-    `web_search`, `x_search`, and `web_fetch`.
-  </Card>
-  <Card title="xAI provider" href="/providers/xai" icon="microchip">
-    Grok models, web/x search, and code execution config.
-  </Card>
-</CardGroup>

package/docs/tools/creating-skills.md

@@ -1,158 +0,0 @@
----
-summary: "Build and test custom workspace skills with SKILL.md"
-title: "Creating skills"
-read_when:
-  - You are creating a new custom skill in your workspace
-  - You need a quick starter workflow for SKILL.md-based skills
----
-
-Skills teach the agent how and when to use tools. Each skill is a directory
-containing a `SKILL.md` file with YAML frontmatter and markdown instructions.
-
-For how skills are loaded and prioritized, see [Skills](/tools/skills).
-
-## Create your first skill
-
-<Steps>
-  <Step title="Create the skill directory">
-    Skills live in your workspace. Create a new folder:
-
-    ```bash
-    mkdir -p ~/.fengming/workspace/skills/hello-world
-    ```
-
-    You can group skills in subfolders when your library grows:
-
-    ```bash
-    mkdir -p ~/.fengming/workspace/skills/personal/hello-world
-    ```
-
-    Group folders are only organizational. The skill is still named by
-    `SKILL.md` frontmatter, so `name: hello-world` is invoked as
-    `/hello-world`.
-
-  </Step>
-
-  <Step title="Write SKILL.md">
-    Create `SKILL.md` inside that directory. The frontmatter defines metadata,
-    and the markdown body contains instructions for the agent.
-
-    ```markdown
-    ---
-    name: hello-world
-    description: A simple skill that says hello.
-    ---
-
-    # Hello World Skill
-
-    When the user asks for a greeting, use the `echo` tool to say
-    "Hello from your custom skill!".
-    ```
-
-    Use hyphen-case with lowercase letters, digits, and hyphens for the skill
-    `name`. Keep the leaf folder name and frontmatter `name` aligned.
-
-  </Step>
-
-  <Step title="Add tools (optional)">
-    You can define custom tool schemas in the frontmatter or instruct the agent
-    to use existing system tools (like `exec` or `browser`). Skills can also
-    ship inside plugins alongside the tools they document.
-
-  </Step>
-
-  <Step title="Load the skill">
-    Verify the skill loaded:
-
-    ```bash
-    fengming skills list
-    ```
-
-    FengMing watches nested `SKILL.md` files under skills roots. If the watcher
-    is disabled or you are continuing an existing session, start a new session
-    so the model receives the refreshed skills list:
-
-    ```bash
-    # From chat
-    /new
-
-    # Or restart the gateway
-    fengming gateway restart
-    ```
-
-  </Step>
-
-  <Step title="Test it">
-    Send a message that should trigger the skill:
-
-    ```bash
-    fengming agent --message "give me a greeting"
-    ```
-
-    Or just chat with the agent and ask for a greeting.
-
-  </Step>
-</Steps>
-
-## Skill metadata reference
-
-The YAML frontmatter supports these fields:
-
-| Field                               | Required | Description                                                    |
-| ----------------------------------- | -------- | -------------------------------------------------------------- |
-| `name`                              | Yes      | Unique identifier using lowercase letters, digits, and hyphens |
-| `description`                       | Yes      | One-line description shown to the agent                        |
-| `metadata.fengming.os`              | No       | OS filter (`["darwin"]`, `["linux"]`, etc.)                    |
-| `metadata.fengming.requires.bins`   | No       | Required binaries on PATH                                      |
-| `metadata.fengming.requires.config` | No       | Required config keys                                           |
-
-## Advanced features
-
-Once a basic skill works, these fields help make it reliable and portable:
-
-- **Conditional activation** — use `requires.bins`, `requires.env`, or
-  `requires.config` to load the skill only when required dependencies are
-  available. See [Skills reference: gating](/tools/skills#gating).
-- **Environment and API-key wiring** — use `skills.entries.<name>.env` and
-  `skills.entries.<name>.apiKey` to inject host-side environment for a skill
-  turn. See [Skills reference: config wiring](/tools/skills#config-wiring).
-- **Invocation control** — set `user-invocable: false` to hide a slash command,
-  or `disable-model-invocation: true` to keep a command-style skill out of the
-  model prompt. See [Skills reference: frontmatter](/tools/skills#frontmatter).
-- **Direct command dispatch** — use `command-dispatch: tool` with
-  `command-tool` when a slash command should call a tool directly instead of
-  routing through the model.
-- **Portable paths** — use `{baseDir}` in `SKILL.md` when referencing scripts
-  or assets inside the skill directory.
-- **Publishing** — use the ClawHub skill when preparing a skill for publication.
-  It documents the current `clawhub publish` command shape and required
-  metadata.
-
-## Best practices
-
-- **Be concise** — instruct the model on _what_ to do, not how to be an AI
-- **Safety first** — if your skill uses `exec`, ensure prompts don't allow arbitrary command injection from untrusted input
-- **Test locally** — use `fengming agent --message "..."` to test before sharing
-- **Use ClawHub** — browse and contribute skills at [ClawHub](https://clawhub.ai)
-
-## Where skills live
-
-| Location                        | Precedence | Scope                 |
-| ------------------------------- | ---------- | --------------------- |
-| `\<workspace\>/skills/`         | Highest    | Per-agent             |
-| `\<workspace\>/.agents/skills/` | High       | Per-workspace agent   |
-| `~/.agents/skills/`             | Medium     | Shared agent profile  |
-| `~/.fengming/skills/`           | Medium     | Shared (all agents)   |
-| Bundled (shipped with FengMing) | Low        | Global                |
-| `skills.load.extraDirs`         | Lowest     | Custom shared folders |
-
-Each skills root can contain direct skill folders such as
-`skills/hello-world/SKILL.md` or grouped folders such as
-`skills/personal/hello-world/SKILL.md`.
-
-## Related
-
-- [Skills reference](/tools/skills) — loading, precedence, and gating rules
-- [Skills config](/tools/skills-config) — `skills.*` config schema
-- [ClawHub](/clawhub) — public skill registry
-- [Building Plugins](/plugins/building-plugins) — plugins can ship skills