fengming 0.3.9 → 0.3.11

package/docs/tools/goal.md

@@ -1,217 +0,0 @@
----
-doc-schema-version: 1
-summary: "Session goals: durable per-session objectives, /goal controls, model goal tools, token budgets, and TUI status"
-read_when:
-  - You want FengMing to keep one objective visible across a long session
-  - You need to pause, resume, block, complete, or clear a session goal
-  - You want to understand the get_goal, create_goal, and update_goal tools
-  - You want to see how goals appear in the TUI
-title: "Goal"
----
-
-# Goal
-
-A **goal** is one durable objective attached to the current FengMing session.
-It gives the agent and the operator a shared target for long-running work,
-without turning that target into a background task, reminder, cron job, or
-standing order.
-
-Goals are session state. They move with the session key, survive process
-restarts, show up in `/goal`, are available to the model through the goal
-tools, and appear in the TUI footer when the active session has one.
-
-## Quick start
-
-Set a goal:
-
-```text
-/goal start get CI green for PR 87469 and push the fix
-```
-
-Check it:
-
-```text
-/goal
-```
-
-Pause it when work is intentionally waiting:
-
-```text
-/goal pause waiting for CI
-```
-
-Resume it:
-
-```text
-/goal resume
-```
-
-Mark it complete:
-
-```text
-/goal complete pushed and verified
-```
-
-Clear it:
-
-```text
-/goal clear
-```
-
-## What goals are for
-
-Use a goal when a session has a concrete outcome that should remain visible
-across many turns:
-
-- A PR closeout: fix, verify, autoreview, push, and open or update the PR.
-- A debug run: reproduce the bug, identify the owning surface, patch, and prove
-  the fix.
-- A docs pass: read the relevant docs, write the new page, cross-link it, and
-  verify the docs build.
-- A maintenance task: inspect current state, make bounded changes, run the right
-  checks, and report what changed.
-
-A goal is not a task queue. Use [Task Flow](/automation/taskflow),
-[tasks](/automation/tasks), [cron jobs](/automation/cron-jobs), or
-[standing orders](/automation/standing-orders) when work should run detached,
-repeat on a schedule, fan out into managed sub-work, or persist as a policy.
-
-## Command reference
-
-`/goal` without arguments prints the current goal summary:
-
-```text
-Goal
-Status: active
-Objective: get CI green for PR 87469 and push the fix
-Tokens used: 12k
-Token budget: 12k/50k
-
-Commands: /goal pause, /goal complete, /goal clear
-```
-
-Commands:
-
-- `/goal` or `/goal status` shows the current goal.
-- `/goal start <objective>` creates a new goal for the current session.
-- `/goal set <objective>` and `/goal create <objective>` are aliases for
-  `start`.
-- `/goal pause [note]` pauses an active goal.
-- `/goal resume [note]` resumes a paused, blocked, usage-limited, or
-  budget-limited goal.
-- `/goal complete [note]` marks the goal achieved.
-- `/goal done [note]` is an alias for `complete`.
-- `/goal block [note]` marks the goal blocked.
-- `/goal blocked [note]` is an alias for `block`.
-- `/goal clear` removes the goal from the session.
-
-Only one goal can exist on a session at a time. Starting a second goal fails
-until the current one is cleared.
-
-## Statuses
-
-Goals use a small status set:
-
-- `active`: the session is pursuing the goal.
-- `paused`: the operator paused the goal; `/goal resume` makes it active again.
-- `blocked`: the agent or operator reported a real blocker; `/goal resume`
-  makes it active again when new information or state is available.
-- `budget_limited`: the configured token budget was reached; `/goal resume`
-  restarts pursuit from the same objective.
-- `usage_limited`: reserved for usage-limit stop states; `/goal resume`
-  restarts pursuit when allowed.
-- `complete`: the goal was achieved. Complete goals are terminal; use
-  `/goal clear` before starting another goal.
-
-`/new` and `/reset` clear the current session goal because they intentionally
-start fresh session context.
-
-## Token budgets
-
-Goals can have an optional positive token budget. The budget is stored with the
-goal and measured from the session's fresh token count at creation time. If the
-current session only has stale or unknown token usage when the goal starts,
-FengMing waits for the next fresh session token snapshot and uses that as the
-baseline, so tokens spent before the goal existed are not charged to the goal.
-
-When token usage reaches the budget, the goal changes to `budget_limited`. This
-does not delete the goal or erase the objective. It tells the operator and the
-agent that the goal is no longer actively being pursued until it is resumed or
-cleared.
-
-Token budgets are a session-goal guardrail, not a billing cap. Provider quota,
-cost reporting, and context-window behavior still use the normal FengMing
-usage and model controls.
-
-## Model tools
-
-FengMing exposes three core goal tools to agent harnesses:
-
-- `get_goal`: read the current session goal, including status, objective, token
-  usage, and token budget.
-- `create_goal`: create a goal only when the user, system, or developer
-  instructions explicitly request one. It fails if the session already has a
-  goal.
-- `update_goal`: mark the goal `complete` or `blocked`.
-
-The model cannot silently pause, resume, clear, or replace a goal. Those are
-operator/session controls through `/goal` and reset commands. This keeps the
-agent from quietly moving the target while preserving a clean path for the
-agent to report achievement or a genuine blocker.
-
-The `update_goal` tool should mark a goal `complete` only when the objective is
-actually achieved. It should mark a goal `blocked` only when the same blocking
-condition has repeated and the agent cannot make meaningful progress without
-new user input or an external-state change.
-
-## TUI
-
-The TUI keeps the active session's goal visible in the footer next to the
-agent, session, model, run controls, and token counts.
-
-Footer examples:
-
-- `Pursuing goal (12k/50k)` for an active goal with a token budget.
-- `Goal paused (/goal resume)` for a paused goal.
-- `Goal blocked (/goal resume)` for a blocked goal.
-- `Goal hit usage limits (/goal resume)` for a usage-limited goal.
-- `Goal unmet (50k/50k)` for a budget-limited goal.
-- `Goal achieved (42k)` for a completed goal.
-
-The footer is intentionally compact. Use `/goal` for the full objective, note,
-token budget, and available commands.
-
-## Channel behavior
-
-The `/goal` command works in command-capable FengMing sessions, including the
-TUI and chat surfaces that permit text commands. Goal state is attached to the
-session key, not the transport. If two surfaces use the same session, they see
-the same goal.
-
-Goal state is not a delivery directive. It does not force replies through a
-channel, change queue behavior, approve tools, or schedule work.
-
-## Troubleshooting
-
-`Goal error: goal already exists` means the session already has a goal. Use
-`/goal` to inspect it, `/goal complete` if it is done, or `/goal clear` before
-starting a different objective.
-
-`Goal error: goal not found` means the session has no goal yet. Start one with
-`/goal start <objective>`.
-
-`Goal error: goal is already complete` means the goal is terminal. Clear it
-before starting or resuming another objective.
-
-If token usage looks like `0` or stale, the active session may not have a fresh
-token snapshot yet. Usage refreshes as FengMing records session usage and
-transcript-derived totals.
-
-## Related
-
-- [Slash commands](/tools/slash-commands)
-- [TUI](/web/tui)
-- [Session tool](/concepts/session-tool)
-- [Compaction](/concepts/compaction)
-- [Task Flow](/automation/taskflow)
-- [Standing orders](/automation/standing-orders)

package/docs/tools/grok-search.md

@@ -1,129 +0,0 @@
----
-summary: "Grok web search via xAI web-grounded responses"
-read_when:
-  - You want to use Grok for web_search
-  - You want to use xAI OAuth or an XAI_API_KEY for web search
-title: "Grok search"
----
-
-FengMing supports Grok as a `web_search` provider, using xAI web-grounded
-responses to produce AI-synthesized answers backed by live search results
-with citations.
-
-Grok web search prefers your existing xAI OAuth sign-in when one is available.
-If no OAuth profile exists, the same xAI API key can also power the built-in
-`x_search` tool for X (formerly Twitter) post search and the `code_execution`
-tool. If you store the key under `plugins.entries.xai.config.webSearch.apiKey`,
-FengMing reuses it as a fallback for the bundled xAI model provider too.
-
-For post-level X metrics such as reposts, replies, bookmarks, or views, prefer
-`x_search` with the exact post URL or status ID instead of a broad search
-query.
-
-## Onboarding and configure
-
-If you choose **Grok** during:
-
-- `fengming onboard`
-- `fengming configure --section web`
-
-FengMing can use an existing xAI OAuth profile without prompting for a separate
-web-search key. If OAuth is not available, it falls back to xAI API-key setup.
-FengMing can also show a separate follow-up step to enable `x_search` with the
-same xAI credential. That follow-up:
-
-- only appears after you choose Grok for `web_search`
-- is not a separate top-level web-search provider choice
-- can optionally set the `x_search` model during the same flow
-
-If you skip it, you can enable or change `x_search` later in config.
-
-## Sign in or get an API key
-
-<Steps>
-  <Step title="Use xAI OAuth">
-    If you already signed in with xAI during onboarding or model auth, choose
-    Grok as the `web_search` provider. No separate API key is required:
-
-    ```bash
-    fengming onboard --auth-choice xai-oauth
-    fengming config set tools.web.search.provider grok
-    ```
-
-  </Step>
-  <Step title="Use an API key fallback">
-    Get an API key from [xAI](https://console.x.ai/) when OAuth is unavailable
-    or you intentionally want key-backed web-search config.
-  </Step>
-  <Step title="Store the key">
-    Set `XAI_API_KEY` in the Gateway environment, or configure via:
-
-    ```bash
-    fengming configure --section web
-    ```
-
-  </Step>
-</Steps>
-
-## Config
-
-```json5
-{
-  plugins: {
-    entries: {
-      xai: {
-        config: {
-          webSearch: {
-            apiKey: "xai-...", // optional if xAI OAuth or XAI_API_KEY is available
-            baseUrl: "https://api.x.ai/v1", // optional Responses API proxy/base URL override
-          },
-        },
-      },
-    },
-  },
-  tools: {
-    web: {
-      search: {
-        provider: "grok",
-      },
-    },
-  },
-}
-```
-
-**Credential alternatives:** sign in with `fengming models auth login
---provider xai --method oauth`, set `XAI_API_KEY` in the Gateway environment,
-or store `plugins.entries.xai.config.webSearch.apiKey`. For a gateway install,
-put env vars in `~/.fengming/.env`.
-
-## How it works
-
-Grok uses xAI web-grounded responses to synthesize answers with inline
-citations, similar to Gemini's Google Search grounding approach.
-
-## Supported parameters
-
-Grok search supports `query`.
-
-`count` is accepted for shared `web_search` compatibility, but Grok still
-returns one synthesized answer with citations rather than an N-result list.
-
-Provider-specific filters are not currently supported.
-
-Grok uses a provider-specific 60 second default timeout because xAI Responses
-web-grounded searches can run longer than the shared `web_search` default. Set
-`tools.web.search.timeoutSeconds` to override it.
-
-## Base URL overrides
-
-Set `plugins.entries.xai.config.webSearch.baseUrl` when Grok web search should
-route through an operator proxy or xAI-compatible Responses endpoint. FengMing
-posts to `<baseUrl>/responses` after trimming trailing slashes. `x_search`
-uses the same `webSearch.baseUrl` fallback unless
-`plugins.entries.xai.config.xSearch.baseUrl` is set.
-
-## Related
-
-- [Web Search overview](/tools/web) -- all providers and auto-detection
-- [x_search in Web Search](/tools/web#x_search) -- first-class X search via xAI
-- [Gemini Search](/tools/gemini-search) -- AI-synthesized answers via Google grounding