fengming 0.3.9 → 0.3.11

package/docs/start/wizard.md

@@ -1,141 +0,0 @@
----
-summary: "CLI onboarding: guided setup for gateway, workspace, channels, and skills"
-read_when:
-  - Running or configuring CLI onboarding
-  - Setting up a new machine
-title: "Onboarding (CLI)"
-sidebarTitle: "Onboarding: CLI"
----
-
-CLI onboarding is the **recommended** way to set up FengMing on macOS,
-Linux, or Windows (via WSL2; strongly recommended).
-It configures a local Gateway or a remote Gateway connection, plus channels, skills,
-and workspace defaults in one guided flow.
-
-```bash
-fengming onboard
-```
-
-## Locale
-
-The CLI wizard localizes fixed onboarding copy. It resolves locale from
-`FENGMING_LOCALE`, then `LC_ALL`, then `LC_MESSAGES`, then `LANG`, and falls
-back to English. Supported wizard locales are `en`, `zh-CN`, and `zh-TW`.
-
-```bash
-FENGMING_LOCALE=zh-CN fengming onboard
-```
-
-Names and stable identifiers stay literal: `FengMing`, `Gateway`, `Tailscale`,
-commands, config keys, URLs, provider IDs, model IDs, and plugin/channel labels
-are not translated.
-
-<Info>
-Fastest first chat: open the Control UI (no channel setup needed). Run
-`fengming dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).
-</Info>
-
-To reconfigure later:
-
-```bash
-fengming configure
-fengming agents add <name>
-```
-
-<Note>
-`--json` does not imply non-interactive mode. For scripts, use `--non-interactive`.
-</Note>
-
-<Tip>
-CLI onboarding includes a web search step where you can pick a provider
-such as Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search,
-Ollama Web Search, Perplexity, SearXNG, or Tavily. Some providers require an
-API key, while others are key-free. You can also configure this later with
-`fengming configure --section web`. Docs: [Web tools](/tools/web).
-</Tip>
-
-## QuickStart vs Advanced
-
-Onboarding starts with **QuickStart** (defaults) vs **Advanced** (full control).
-
-<Tabs>
-  <Tab title="QuickStart (defaults)">
-    - Local gateway (loopback)
-    - Workspace default (or existing workspace)
-    - Gateway port **18789**
-    - Gateway auth **Token** (auto-generated, even on loopback)
-    - Tool policy default for new local setups: `tools.profile: "coding"` (existing explicit profile is preserved)
-    - DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals)
-    - Tailscale exposure **Off**
-    - Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)
-
-  </Tab>
-  <Tab title="Advanced (full control)">
-    - Exposes every step (mode, workspace, gateway, channels, daemon, skills).
-
-  </Tab>
-</Tabs>
-
-## What onboarding configures
-
-**Local mode (default)** walks you through these steps:
-
-1. **Model/Auth** — choose any supported provider/auth flow (API key, OAuth, or provider-specific manual auth), including Custom Provider
-   (OpenAI-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model.
-   Security note: if this agent will run tools or process webhook/hooks content, prefer the strongest latest-generation model available and keep tool policy strict. Weaker/older tiers are easier to prompt-inject.
-   For non-interactive runs, `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext API key values.
-   In non-interactive `ref` mode, the provider env var must be set; passing inline key flags without that env var fails fast.
-   In interactive runs, choosing secret reference mode lets you point at either an environment variable or a configured provider ref (`file` or `exec`), with a fast preflight validation before saving.
-   For Anthropic, interactive onboarding/configure offers **Anthropic Claude CLI** as the preferred local path and **Anthropic API key** as the recommended production path. Anthropic setup-token also remains available as a supported token-auth path.
-2. **Workspace** — Location for agent files (default `~/.fengming/workspace`). Seeds bootstrap files.
-3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
-   In interactive token mode, choose default plaintext token storage or opt into SecretRef.
-   Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
-4. **Channels** — built-in and official plugin chat channels such as iMessage, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
-5. **Daemon** — Installs a LaunchAgent (macOS), systemd user unit (Linux/WSL2), or native Windows Scheduled Task with per-user Startup-folder fallback.
-   If token auth requires a token and `gateway.auth.token` is SecretRef-managed, daemon install validates it but does not persist the resolved token into supervisor service environment metadata.
-   If token auth requires a token and the configured token SecretRef is unresolved, daemon install is blocked with actionable guidance.
-   If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, daemon install is blocked until mode is set explicitly.
-6. **Health check** — Starts the Gateway and verifies it's running.
-7. **Skills** — Installs recommended skills and optional dependencies.
-
-<Note>
-Re-running onboarding does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`).
-CLI `--reset` defaults to config, credentials, and sessions; use `--reset-scope full` to include workspace.
-If the config is invalid or contains legacy keys, onboarding asks you to run `fengming doctor` first.
-</Note>
-
-**Remote mode** only configures the local client to connect to a Gateway elsewhere.
-It does **not** install or change anything on the remote host.
-
-## Add another agent
-
-Use `fengming agents add <name>` to create a separate agent with its own workspace,
-sessions, and auth profiles. Running without `--workspace` launches onboarding.
-
-What it sets:
-
-- `agents.list[].name`
-- `agents.list[].workspace`
-- `agents.list[].agentDir`
-
-Notes:
-
-- Default workspaces follow `~/.fengming/workspace-<agentId>`.
-- Add `bindings` to route inbound messages (onboarding can do this).
-- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.
-
-## Full reference
-
-For detailed step-by-step breakdowns and config outputs, see
-[CLI Setup Reference](/start/wizard-cli-reference).
-For non-interactive examples, see [CLI Automation](/start/wizard-cli-automation).
-For the deeper technical reference, including RPC details, see
-[Onboarding Reference](/reference/wizard).
-
-## Related docs
-
-- CLI command reference: [`fengming onboard`](/cli/onboard)
-- Onboarding overview: [Onboarding Overview](/start/onboarding-overview)
-- macOS app onboarding: [Onboarding](/start/onboarding)
-- Agent first-run ritual: [Agent Bootstrapping](/start/bootstrapping)

package/docs/style.css

@@ -1,137 +0,0 @@
-#content > h1:first-of-type {
-  display: none !important;
-}
-
-.nav-tabs {
-  position: relative;
-}
-
-.nav-tabs-item > div {
-  opacity: 0;
-}
-
-.nav-tabs-underline {
-  position: absolute;
-  left: 0;
-  bottom: 0;
-  height: 1.5px;
-  width: var(--nav-tab-underline-width, 0);
-  transform: translateX(var(--nav-tab-underline-x, 0));
-  background-color: rgb(var(--primary));
-  border-radius: 999px;
-  pointer-events: none;
-  opacity: 0;
-  transition:
-    transform 260ms ease-in-out,
-    width 260ms ease-in-out,
-    opacity 160ms ease-in-out;
-  will-change: transform, width;
-}
-
-html.dark .nav-tabs-underline {
-  background-color: rgb(var(--primary-light));
-}
-
-.nav-tabs-underline-ready .nav-tabs-underline {
-  opacity: 1;
-}
-
-.showcase-hero {
-  display: grid;
-  gap: 18px;
-  margin: 8px 0 22px;
-  padding: clamp(18px, 3vw, 30px);
-  border: 1px solid color-mix(in oklab, rgb(var(--primary)) 24%, transparent);
-  border-radius: 8px;
-  background: color-mix(in oklab, rgb(var(--primary)) 5%, transparent);
-  box-shadow: 0 18px 48px -34px rgba(0, 0, 0, 0.45);
-}
-
-.showcase-kicker {
-  margin: 0;
-  font-size: 12px;
-  font-weight: 700;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-  opacity: 0.72;
-}
-
-.showcase-lead {
-  margin: 0;
-  max-width: 48rem;
-  font-size: clamp(18px, 2vw, 23px);
-  line-height: 1.6;
-}
-
-.showcase-actions,
-.showcase-jump-links {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 10px;
-}
-
-.showcase-actions a,
-.showcase-jump-links a {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  min-height: 40px;
-  padding: 0 14px;
-  border: 1px solid color-mix(in oklab, rgb(var(--primary)) 24%, transparent);
-  border-bottom: 1px solid color-mix(in oklab, rgb(var(--primary)) 24%, transparent);
-  border-radius: 8px;
-  background: color-mix(in oklab, rgb(var(--primary)) 4%, transparent);
-  text-decoration: none;
-  transition:
-    transform 0.16s ease,
-    border-color 0.16s ease,
-    background 0.16s ease;
-}
-
-.showcase-actions a:first-child {
-  background: color-mix(in oklab, rgb(var(--primary)) 12%, transparent);
-  border-color: color-mix(in oklab, rgb(var(--primary)) 36%, transparent);
-}
-
-.showcase-actions a:hover,
-.showcase-jump-links a:hover {
-  transform: translateY(-1px);
-  border-color: color-mix(in oklab, rgb(var(--primary)) 46%, transparent);
-}
-
-.showcase-highlights {
-  display: grid;
-  grid-template-columns: repeat(3, minmax(0, 1fr));
-  gap: 12px;
-}
-
-.showcase-highlight {
-  padding: 14px;
-  border: 1px solid color-mix(in oklab, rgb(var(--primary)) 18%, transparent);
-  border-radius: 8px;
-  background: color-mix(in oklab, rgb(var(--primary)) 3%, transparent);
-}
-
-.showcase-highlight strong {
-  display: block;
-  margin-bottom: 6px;
-}
-
-.showcase-highlight span,
-.showcase-section-intro {
-  opacity: 0.74;
-}
-
-.showcase-jump-links {
-  margin: 18px 0 28px;
-}
-
-.showcase-section-intro {
-  margin: 0 0 16px;
-}
-
-@media (max-width: 960px) {
-  .showcase-highlights {
-    grid-template-columns: 1fr;
-  }
-}

package/docs/superpowers/specs/2026-04-22-tweakcn-custom-theme-import-design.md

@@ -1,316 +0,0 @@
-# Tweakcn Custom Theme Import Design
-
-Status: approved in terminal on 2026-04-22
-
-## Summary
-
-Add exactly one browser-local custom Control UI theme slot that can be imported from a tweakcn share link. The existing built-in theme families remain `claw`, `knot`, and `dash`. The new `custom` family behaves like a normal FengMing theme family and supports `light`, `dark`, and `system` mode when the imported tweakcn payload includes both light and dark token sets.
-
-The imported theme is stored only in the current browser profile with the rest of the Control UI settings. It is not written to gateway config and does not sync across devices or browsers.
-
-## Problem
-
-The Control UI theme system is currently closed over three hard-coded theme families:
-
-- `ui/src/ui/theme.ts`
-- `ui/src/ui/views/config.ts`
-- `ui/src/styles/base.css`
-
-Users can switch among built-in families and mode variants, but they cannot bring in a theme from tweakcn without editing repo CSS. The requested outcome is smaller than a general theming system: keep the three built-ins and add one user-controlled imported slot that can be replaced from a tweakcn link.
-
-## Goals
-
-- Keep the existing built-in theme families unchanged.
-- Add exactly one imported custom slot, not a theme library.
-- Accept a tweakcn share link or a direct `https://tweakcn.com/r/themes/{id}` URL.
-- Persist the imported theme in browser local storage only.
-- Make the imported slot work with existing `light`, `dark`, and `system` mode controls.
-- Keep failure behavior safe: a bad import never breaks the active UI theme.
-
-## Non goals
-
-- No multi-theme library or browser-local list of imports.
-- No gateway-side persistence or cross-device sync.
-- No arbitrary CSS editor or raw theme JSON editor.
-- No automatic loading of remote font assets from tweakcn.
-- No attempt to support tweakcn payloads that only expose one mode.
-- No repo-wide theming refactor beyond the seams required for the Control UI.
-
-## User decisions already made
-
-- Keep the three built-in themes.
-- Add one tweakcn-powered import slot.
-- Store the imported theme in the browser, not gateway config.
-- Support `light`, `dark`, and `system` for the imported slot.
-- Overwriting the custom slot with the next import is the intended behavior.
-
-## Recommended approach
-
-Add a fourth theme family id, `custom`, to the Control UI theme model. The `custom` family becomes selectable only when a valid tweakcn import is present. The imported payload is normalized into an FengMing-specific custom theme record and stored in browser local storage with the rest of the UI settings.
-
-At runtime, FengMing renders a managed `<style>` tag that defines the resolved custom CSS variable blocks:
-
-```css
-:root[data-theme="custom"] { ... }
-:root[data-theme="custom-light"] { ... }
-```
-
-This keeps custom theme variables scoped to the `custom` family and avoids leaking inline CSS variables into the built-in families.
-
-## Architecture
-
-### Theme model
-
-Update `ui/src/ui/theme.ts`:
-
-- Extend `ThemeName` to include `custom`.
-- Extend `ResolvedTheme` to include `custom` and `custom-light`.
-- Extend `VALID_THEME_NAMES`.
-- Update `resolveTheme()` so `custom` mirrors the existing family behavior:
-  - `custom + dark` -> `custom`
-  - `custom + light` -> `custom-light`
-  - `custom + system` -> `custom` or `custom-light` based on OS preference
-
-No legacy aliases are added for `custom`.
-
-### Persistence model
-
-Extend `UiSettings` persistence in `ui/src/ui/storage.ts` with one optional custom-theme payload:
-
-- `customTheme?: ImportedCustomTheme`
-
-Recommended stored shape:
-
-```ts
-type ImportedCustomTheme = {
-  sourceUrl: string;
-  themeId: string;
-  label: string;
-  importedAt: string;
-  light: Record<string, string>;
-  dark: Record<string, string>;
-};
-```
-
-Notes:
-
-- `sourceUrl` stores the original user input after normalization.
-- `themeId` is the tweakcn theme id extracted from the URL.
-- `label` is the tweakcn `name` field when present, else `Custom`.
-- `light` and `dark` are already normalized FengMing token maps, not raw tweakcn payloads.
-- The imported payload lives beside other browser-local settings and is serialized in the same local-storage document.
-- If stored custom-theme data is missing or invalid on load, ignore the payload and fall back to `theme: "claw"` when the persisted family was `custom`.
-
-### Runtime application
-
-Add a narrow custom-theme stylesheet manager in the Control UI runtime, owned near `ui/src/ui/app-settings.ts` and `ui/src/ui/theme.ts`.
-
-Responsibilities:
-
-- Create or update one stable `<style id="fengming-custom-theme">` tag in `document.head`.
-- Emit CSS only when a valid custom theme payload exists.
-- Remove the style tag content when the payload is cleared.
-- Keep built-in family CSS in `ui/src/styles/base.css`; do not splice imported tokens into the checked-in stylesheet.
-
-This manager runs whenever settings are loaded, saved, imported, or cleared.
-
-### Light-mode selectors
-
-Implementation should prefer `data-theme-mode="light"` for cross-family light styling rather than special-casing `custom-light`. If an existing selector is pinned to `data-theme="light"` and needs to apply to every light family, broaden it as part of this work.
-
-## Import UX
-
-Update `ui/src/ui/views/config.ts` in the `Appearance` section:
-
-- Add a `Custom` theme card beside `Claw`, `Knot`, and `Dash`.
-- Show the card as disabled when no imported custom theme exists.
-- Add an import panel under the theme grid with:
-  - one text input for a tweakcn share link or `/r/themes/{id}` URL
-  - one `Import` button
-  - one `Replace` path when a custom payload already exists
-  - one `Clear` action when a custom payload already exists
-- Show the imported theme label and source host when a payload exists.
-- If the active theme is `custom`, importing a replacement applies immediately.
-- If the active theme is not `custom`, importing only stores the new payload until the user selects the `Custom` card.
-
-The quick settings theme picker in `ui/src/ui/views/config-quick.ts` should also show `Custom` only when a payload exists.
-
-## URL parsing and remote fetch
-
-The browser import path accepts:
-
-- `https://tweakcn.com/themes/{id}`
-- `https://tweakcn.com/r/themes/{id}`
-
-Implementation should normalize both forms to:
-
-- `https://tweakcn.com/r/themes/{id}`
-
-The browser then fetches the normalized `/r/themes/{id}` endpoint directly.
-
-Use a narrow schema validator for the external payload. A zod schema is preferred because this is an untrusted external boundary.
-
-Required remote fields:
-
-- top-level `name` as optional string
-- `cssVars.theme` as optional object
-- `cssVars.light` as object
-- `cssVars.dark` as object
-
-If either `cssVars.light` or `cssVars.dark` is missing, reject the import. This is deliberate: the approved product behavior is full mode support, not best-effort synthesis of a missing side.
-
-## Token mapping
-
-Do not mirror tweakcn variables blindly. Normalize a bounded subset into FengMing tokens and derive the rest in a helper.
-
-### Tokens imported directly
-
-From each tweakcn mode block:
-
-- `background`
-- `foreground`
-- `card`
-- `card-foreground`
-- `popover`
-- `popover-foreground`
-- `primary`
-- `primary-foreground`
-- `secondary`
-- `secondary-foreground`
-- `muted`
-- `muted-foreground`
-- `accent`
-- `accent-foreground`
-- `destructive`
-- `destructive-foreground`
-- `border`
-- `input`
-- `ring`
-- `radius`
-
-From shared `cssVars.theme` when present:
-
-- `font-sans`
-- `font-mono`
-
-If a mode block overrides `font-sans`, `font-mono`, or `radius`, the mode-local value wins.
-
-### Tokens derived for FengMing
-
-The importer derives FengMing-only variables from the imported base colors:
-
-- `--bg-accent`
-- `--bg-elevated`
-- `--bg-hover`
-- `--panel`
-- `--panel-strong`
-- `--panel-hover`
-- `--chrome`
-- `--chrome-strong`
-- `--text`
-- `--text-strong`
-- `--chat-text`
-- `--muted`
-- `--muted-strong`
-- `--accent-hover`
-- `--accent-muted`
-- `--accent-subtle`
-- `--accent-glow`
-- `--focus`
-- `--focus-ring`
-- `--focus-glow`
-- `--secondary`
-- `--secondary-foreground`
-- `--danger`
-- `--danger-muted`
-- `--danger-subtle`
-
-Derivation rules live in a pure helper so they can be tested independently. Exact color-mixing formulas are an implementation detail, but the helper must satisfy two constraints:
-
-- preserve readable contrast close to the imported theme intent
-- produce stable output for the same imported payload
-
-### Tokens ignored in v1
-
-These tweakcn tokens are intentionally ignored in the first version:
-
-- `chart-*`
-- `sidebar-*`
-- `font-serif`
-- `shadow-*`
-- `tracking-*`
-- `letter-spacing`
-- `spacing`
-
-This keeps the scope on the tokens the current Control UI actually needs.
-
-### Fonts
-
-Font stack strings are imported if present, but FengMing does not load remote font assets in v1. If the imported stack references fonts that are unavailable in the browser, normal fallback behavior applies.
-
-## Failure behavior
-
-Bad imports must fail closed.
-
-- Invalid URL format: show inline validation error, do not fetch.
-- Unsupported host or path shape: show inline validation error, do not fetch.
-- Network failure, non-OK response, or malformed JSON: show inline error, keep current stored payload untouched.
-- Schema failure or missing light/dark blocks: show inline error, keep current stored payload untouched.
-- Clear action:
-  - removes the stored custom payload
-  - removes the managed custom style tag content
-  - if `custom` is active, switches theme family back to `claw`
-- Invalid stored custom payload on first load:
-  - ignore the stored payload
-  - do not emit custom CSS
-  - if persisted theme family was `custom`, fall back to `claw`
-
-At no point should a failed import leave the active document with partial custom CSS variables applied.
-
-## Files expected to change in implementation
-
-Primary files:
-
-- `ui/src/ui/theme.ts`
-- `ui/src/ui/storage.ts`
-- `ui/src/ui/app-settings.ts`
-- `ui/src/ui/views/config.ts`
-- `ui/src/ui/views/config-quick.ts`
-- `ui/src/styles/base.css`
-
-Likely new helpers:
-
-- `ui/src/ui/custom-theme.ts`
-
-Tests:
-
-- `ui/src/ui/app-settings.test.ts`
-- `ui/src/ui/storage.node.test.ts`
-- `ui/src/ui/views/config.browser.test.ts`
-- new focused tests for URL parsing and payload normalization
-
-## Testing
-
-Minimum implementation coverage:
-
-- parse share-link URL into tweakcn theme id
-- normalize `/themes/{id}` and `/r/themes/{id}` into the fetch URL
-- reject unsupported hosts and malformed ids
-- validate tweakcn payload shape
-- map a valid tweakcn payload into normalized FengMing light and dark token maps
-- load and save the custom payload in browser-local settings
-- resolve `custom` for `light`, `dark`, and `system`
-- disable `Custom` selection when no payload exists
-- apply imported theme immediately when `custom` is already active
-- fall back to `claw` when the active custom theme is cleared
-
-Manual verification target:
-
-- import a known tweakcn theme from Settings
-- switch among `light`, `dark`, and `system`
-- switch between `custom` and the built-in families
-- reload the page and confirm the imported custom theme persists locally
-
-## Rollout notes
-
-This feature is intentionally small. If users later ask for multiple imported themes, rename, export, or cross-device sync, treat that as a follow-on design. Do not pre-build a theme library abstraction in this implementation.