@quantumclaw/quantumclaw 2026.3.22

package/docs/ja-JP/start/getting-started.md

@@ -0,0 +1,125 @@
+---
+read_when:
+  - ゼロからの初回セットアップ
+  - 動作するチャットへの最短ルートを知りたい
+summary: QuantumClawをインストールし、数分で最初のチャットを実行しましょう。
+title: はじめに
+x-i18n:
+  generated_at: "2026-02-08T17:15:16Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 27aeeb3d18c495380e94e6b011b0df3def518535c9f1eee504f04871d8a32269
+  source_path: start/getting-started.md
+  workflow: 15
+---
+
+# はじめに
+
+目標：ゼロから最小限のセットアップで最初の動作するチャットを実現する。
+
+<Info>
+最速のチャット方法：Control UIを開く（チャンネル設定は不要）。`quantumclaw dashboard`を実行してブラウザでチャットするか、<Tooltip headline="Gatewayホスト" tip="QuantumClaw Gatewayサービスを実行しているマシン。">Gatewayホスト</Tooltip>で`http://127.0.0.1:18789/`を開きます。
+ドキュメント：[Dashboard](/web/dashboard)と[Control UI](/web/control-ui)。
+</Info>
+
+## 前提条件
+
+- Node 22以降
+
+<Tip>
+不明な場合は`node --version`でNodeのバージョンを確認してください。
+</Tip>
+
+## クイックセットアップ（CLI）
+
+<Steps>
+  <Step title="QuantumClawをインストール（推奨）">
+    <Tabs>
+      <Tab title="macOS/Linux">
+        ```bash
+        curl -fsSL https://quantumclaw.ai/install.sh | bash
+        ```
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        iwr -useb https://quantumclaw.ai/install.ps1 | iex
+        ```
+      </Tab>
+    </Tabs>
+
+    <Note>
+    その他のインストール方法と要件：[インストール](/install)。
+    </Note>
+
+  </Step>
+  <Step title="オンボーディングウィザードを実行">
+    ```bash
+    quantumclaw onboard --install-daemon
+    ```
+
+    ウィザードは認証、Gateway設定、およびオプションのチャンネルを構成します。
+    詳細は[オンボーディングウィザード](/start/wizard)を参照してください。
+
+  </Step>
+  <Step title="Gatewayを確認">
+    サービスをインストールした場合、すでに実行されているはずです：
+
+    ```bash
+    quantumclaw gateway status
+    ```
+
+  </Step>
+  <Step title="Control UIを開く">
+    ```bash
+    quantumclaw dashboard
+    ```
+  </Step>
+</Steps>
+
+<Check>
+Control UIが読み込まれれば、Gatewayは使用可能な状態です。
+</Check>
+
+## オプションの確認と追加機能
+
+<AccordionGroup>
+  <Accordion title="Gatewayをフォアグラウンドで実行">
+    クイックテストやトラブルシューティングに便利です。
+
+    ```bash
+    quantumclaw gateway --port 18789
+    ```
+
+  </Accordion>
+  <Accordion title="テストメッセージを送信">
+    構成済みのチャンネルが必要です。
+
+    ```bash
+    quantumclaw message send --target +15555550123 --message "Hello from QuantumClaw"
+    ```
+
+  </Accordion>
+</AccordionGroup>
+
+## さらに詳しく
+
+<Columns>
+  <Card title="オンボーディングウィザード（詳細）" href="/start/wizard">
+    完全なCLIウィザードリファレンスと高度なオプション。
+  </Card>
+  <Card title="macOSアプリのオンボーディング" href="/start/onboarding">
+    macOSアプリの初回実行フロー。
+  </Card>
+</Columns>
+
+## 完了後の状態
+
+- 実行中のGateway
+- 構成済みの認証
+- Control UIアクセスまたは接続済みのチャンネル
+
+## 次のステップ
+
+- DMの安全性と承認：[ペアリング](/channels/pairing)
+- さらにチャンネルを接続：[チャンネル](/channels)
+- 高度なワークフローとソースからのビルド：[セットアップ](/start/setup)

package/docs/ja-JP/start/wizard.md

@@ -0,0 +1,77 @@
+---
+read_when:
+  - オンボーディングウィザードの実行または設定時
+  - 新しいマシンのセットアップ時
+sidebarTitle: Wizard (CLI)
+summary: CLIオンボーディングウィザード：Gateway、ワークスペース、チャンネル、Skillsの対話式セットアップ
+title: オンボーディングウィザード（CLI）
+x-i18n:
+  generated_at: "2026-02-08T17:15:18Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9a650d46044a930aa4aaec30b35f1273ca3969bf676ab67bf4e1575b5c46db4c
+  source_path: start/wizard.md
+  workflow: 15
+---
+
+# オンボーディングウィザード（CLI）
+
+CLIオンボーディングウィザードは、macOS、Linux、Windows（WSL2経由）でQuantumClawをセットアップする際の推奨パスです。ローカルGatewayまたはリモートGateway接続に加えて、ワークスペースのデフォルト設定、チャンネル、Skillsを構成します。
+
+```bash
+quantumclaw onboard
+```
+
+<Info>
+最速で初回チャットを開始する方法：Control UI を開きます（チャンネル設定は不要）。`quantumclaw dashboard` を実行してブラウザでチャットできます。ドキュメント：[Dashboard](/web/dashboard)。
+</Info>
+
+## クイックスタート vs 詳細設定
+
+ウィザードは**クイックスタート**（デフォルト設定）と**詳細設定**（完全な制御）のどちらかを選択して開始します。
+
+<Tabs>
+  <Tab title="クイックスタート（デフォルト設定）">
+    - loopback上のローカルGateway
+    - 既存のワークスペースまたはデフォルトワークスペース
+    - Gatewayポート `18789`
+    - Gateway認証トークンは自動生成（loopback上でも生成されます）
+    - Tailscale公開はオフ
+    - TelegramとWhatsAppのDMはデフォルトで許可リスト（電話番号の入力を求められる場合があります）
+  </Tab>
+  <Tab title="詳細設定（完全な制御）">
+    - モード、ワークスペース、Gateway、チャンネル、デーモン、Skillsの完全なプロンプトフローを表示
+  </Tab>
+</Tabs>
+
+## CLIオンボーディングの詳細
+
+<Columns>
+  <Card title="CLIリファレンス" href="/start/wizard-cli-reference">
+    ローカルおよびリモートフローの完全な説明、認証とモデルマトリックス、設定出力、ウィザードRPC、signal-cliの動作。
+  </Card>
+  <Card title="自動化とスクリプト" href="/start/wizard-cli-automation">
+    非対話式オンボーディングのレシピと自動化された `agents add` の例。
+  </Card>
+</Columns>
+
+## よく使うフォローアップコマンド
+
+```bash
+quantumclaw configure
+quantumclaw agents add <name>
+```
+
+<Note>
+`--json` は非対話モードを意味しません。スクリプトでは `--non-interactive` を使用してください。
+</Note>
+
+<Tip>
+推奨：エージェントが `web_search` を使用できるように、Brave Search APIキーを設定してください（`web_fetch` はキーなしで動作します）。最も簡単な方法：`quantumclaw configure --section web` を実行すると `plugins.entries.brave.config.webSearch.apiKey` に保存されます。旧 `tools.web.search.apiKey` パスは互換用に引き続き読み込まれますが、新しい設定では使用しないでください。ドキュメント：[Webツール](/tools/web)。
+</Tip>
+
+## 関連ドキュメント
+
+- CLIコマンドリファレンス：[`quantumclaw onboard`](/cli/onboard)
+- macOSアプリのオンボーディング：[オンボーディング](/start/onboarding)
+- エージェント初回起動の手順：[エージェントブートストラップ](/start/bootstrapping)

package/docs/logging.md

@@ -0,0 +1,352 @@
+---
+summary: "Logging overview: file logs, console output, CLI tailing, and the Control UI"
+read_when:
+  - You need a beginner-friendly overview of logging
+  - You want to configure log levels or formats
+  - You are troubleshooting and need to find logs quickly
+title: "Logging"
+---
+
+# Logging
+
+QuantumClaw logs in two places:
+
+- **File logs** (JSON lines) written by the Gateway.
+- **Console output** shown in terminals and the Control UI.
+
+This page explains where logs live, how to read them, and how to configure log
+levels and formats.
+
+## Where logs live
+
+By default, the Gateway writes a rolling log file under:
+
+`/tmp/quantumclaw/quantumclaw-YYYY-MM-DD.log`
+
+The date uses the gateway host's local timezone.
+
+You can override this in `~/.quantumclaw/quantumclaw.json`:
+
+```json
+{
+  "logging": {
+    "file": "/path/to/quantumclaw.log"
+  }
+}
+```
+
+## How to read logs
+
+### CLI: live tail (recommended)
+
+Use the CLI to tail the gateway log file via RPC:
+
+```bash
+quantumclaw logs --follow
+```
+
+Output modes:
+
+- **TTY sessions**: pretty, colorized, structured log lines.
+- **Non-TTY sessions**: plain text.
+- `--json`: line-delimited JSON (one log event per line).
+- `--plain`: force plain text in TTY sessions.
+- `--no-color`: disable ANSI colors.
+
+In JSON mode, the CLI emits `type`-tagged objects:
+
+- `meta`: stream metadata (file, cursor, size)
+- `log`: parsed log entry
+- `notice`: truncation / rotation hints
+- `raw`: unparsed log line
+
+If the Gateway is unreachable, the CLI prints a short hint to run:
+
+```bash
+quantumclaw doctor
+```
+
+### Control UI (web)
+
+The Control UI’s **Logs** tab tails the same file using `logs.tail`.
+See [/web/control-ui](/web/control-ui) for how to open it.
+
+### Channel-only logs
+
+To filter channel activity (WhatsApp/Telegram/etc), use:
+
+```bash
+quantumclaw channels logs --channel whatsapp
+```
+
+## Log formats
+
+### File logs (JSONL)
+
+Each line in the log file is a JSON object. The CLI and Control UI parse these
+entries to render structured output (time, level, subsystem, message).
+
+### Console output
+
+Console logs are **TTY-aware** and formatted for readability:
+
+- Subsystem prefixes (e.g. `gateway/channels/whatsapp`)
+- Level coloring (info/warn/error)
+- Optional compact or JSON mode
+
+Console formatting is controlled by `logging.consoleStyle`.
+
+## Configuring logging
+
+All logging configuration lives under `logging` in `~/.quantumclaw/quantumclaw.json`.
+
+```json
+{
+  "logging": {
+    "level": "info",
+    "file": "/tmp/quantumclaw/quantumclaw-YYYY-MM-DD.log",
+    "consoleLevel": "info",
+    "consoleStyle": "pretty",
+    "redactSensitive": "tools",
+    "redactPatterns": ["sk-.*"]
+  }
+}
+```
+
+### Log levels
+
+- `logging.level`: **file logs** (JSONL) level.
+- `logging.consoleLevel`: **console** verbosity level.
+
+You can override both via the **`QUANTUMCLAW_LOG_LEVEL`** environment variable (e.g. `QUANTUMCLAW_LOG_LEVEL=debug`). The env var takes precedence over the config file, so you can raise verbosity for a single run without editing `quantumclaw.json`. You can also pass the global CLI option **`--log-level <level>`** (for example, `quantumclaw --log-level debug gateway run`), which overrides the environment variable for that command.
+
+`--verbose` only affects console output; it does not change file log levels.
+
+### Console styles
+
+`logging.consoleStyle`:
+
+- `pretty`: human-friendly, colored, with timestamps.
+- `compact`: tighter output (best for long sessions).
+- `json`: JSON per line (for log processors).
+
+### Redaction
+
+Tool summaries can redact sensitive tokens before they hit the console:
+
+- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
+- `logging.redactPatterns`: list of regex strings to override the default set
+
+Redaction affects **console output only** and does not alter file logs.
+
+## Diagnostics + OpenTelemetry
+
+Diagnostics are structured, machine-readable events for model runs **and**
+message-flow telemetry (webhooks, queueing, session state). They do **not**
+replace logs; they exist to feed metrics, traces, and other exporters.
+
+Diagnostics events are emitted in-process, but exporters only attach when
+diagnostics + the exporter plugin are enabled.
+
+### OpenTelemetry vs OTLP
+
+- **OpenTelemetry (OTel)**: the data model + SDKs for traces, metrics, and logs.
+- **OTLP**: the wire protocol used to export OTel data to a collector/backend.
+- QuantumClaw exports via **OTLP/HTTP (protobuf)** today.
+
+### Signals exported
+
+- **Metrics**: counters + histograms (token usage, message flow, queueing).
+- **Traces**: spans for model usage + webhook/message processing.
+- **Logs**: exported over OTLP when `diagnostics.otel.logs` is enabled. Log
+  volume can be high; keep `logging.level` and exporter filters in mind.
+
+### Diagnostic event catalog
+
+Model usage:
+
+- `model.usage`: tokens, cost, duration, context, provider/model/channel, session ids.
+
+Message flow:
+
+- `webhook.received`: webhook ingress per channel.
+- `webhook.processed`: webhook handled + duration.
+- `webhook.error`: webhook handler errors.
+- `message.queued`: message enqueued for processing.
+- `message.processed`: outcome + duration + optional error.
+
+Queue + session:
+
+- `queue.lane.enqueue`: command queue lane enqueue + depth.
+- `queue.lane.dequeue`: command queue lane dequeue + wait time.
+- `session.state`: session state transition + reason.
+- `session.stuck`: session stuck warning + age.
+- `run.attempt`: run retry/attempt metadata.
+- `diagnostic.heartbeat`: aggregate counters (webhooks/queue/session).
+
+### Enable diagnostics (no exporter)
+
+Use this if you want diagnostics events available to plugins or custom sinks:
+
+```json
+{
+  "diagnostics": {
+    "enabled": true
+  }
+}
+```
+
+### Diagnostics flags (targeted logs)
+
+Use flags to turn on extra, targeted debug logs without raising `logging.level`.
+Flags are case-insensitive and support wildcards (e.g. `telegram.*` or `*`).
+
+```json
+{
+  "diagnostics": {
+    "flags": ["telegram.http"]
+  }
+}
+```
+
+Env override (one-off):
+
+```
+QUANTUMCLAW_DIAGNOSTICS=telegram.http,telegram.payload
+```
+
+Notes:
+
+- Flag logs go to the standard log file (same as `logging.file`).
+- Output is still redacted according to `logging.redactSensitive`.
+- Full guide: [/diagnostics/flags](/diagnostics/flags).
+
+### Export to OpenTelemetry
+
+Diagnostics can be exported via the `diagnostics-otel` plugin (OTLP/HTTP). This
+works with any OpenTelemetry collector/backend that accepts OTLP/HTTP.
+
+```json
+{
+  "plugins": {
+    "allow": ["diagnostics-otel"],
+    "entries": {
+      "diagnostics-otel": {
+        "enabled": true
+      }
+    }
+  },
+  "diagnostics": {
+    "enabled": true,
+    "otel": {
+      "enabled": true,
+      "endpoint": "http://otel-collector:4318",
+      "protocol": "http/protobuf",
+      "serviceName": "quantumclaw-gateway",
+      "traces": true,
+      "metrics": true,
+      "logs": true,
+      "sampleRate": 0.2,
+      "flushIntervalMs": 60000
+    }
+  }
+}
+```
+
+Notes:
+
+- You can also enable the plugin with `quantumclaw plugins enable diagnostics-otel`.
+- `protocol` currently supports `http/protobuf` only. `grpc` is ignored.
+- Metrics include token usage, cost, context size, run duration, and message-flow
+  counters/histograms (webhooks, queueing, session state, queue depth/wait).
+- Traces/metrics can be toggled with `traces` / `metrics` (default: on). Traces
+  include model usage spans plus webhook/message processing spans when enabled.
+- Set `headers` when your collector requires auth.
+- Environment variables supported: `OTEL_EXPORTER_OTLP_ENDPOINT`,
+  `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_PROTOCOL`.
+
+### Exported metrics (names + types)
+
+Model usage:
+
+- `quantumclaw.tokens` (counter, attrs: `quantumclaw.token`, `quantumclaw.channel`,
+  `quantumclaw.provider`, `quantumclaw.model`)
+- `quantumclaw.cost.usd` (counter, attrs: `quantumclaw.channel`, `quantumclaw.provider`,
+  `quantumclaw.model`)
+- `quantumclaw.run.duration_ms` (histogram, attrs: `quantumclaw.channel`,
+  `quantumclaw.provider`, `quantumclaw.model`)
+- `quantumclaw.context.tokens` (histogram, attrs: `quantumclaw.context`,
+  `quantumclaw.channel`, `quantumclaw.provider`, `quantumclaw.model`)
+
+Message flow:
+
+- `quantumclaw.webhook.received` (counter, attrs: `quantumclaw.channel`,
+  `quantumclaw.webhook`)
+- `quantumclaw.webhook.error` (counter, attrs: `quantumclaw.channel`,
+  `quantumclaw.webhook`)
+- `quantumclaw.webhook.duration_ms` (histogram, attrs: `quantumclaw.channel`,
+  `quantumclaw.webhook`)
+- `quantumclaw.message.queued` (counter, attrs: `quantumclaw.channel`,
+  `quantumclaw.source`)
+- `quantumclaw.message.processed` (counter, attrs: `quantumclaw.channel`,
+  `quantumclaw.outcome`)
+- `quantumclaw.message.duration_ms` (histogram, attrs: `quantumclaw.channel`,
+  `quantumclaw.outcome`)
+
+Queues + sessions:
+
+- `quantumclaw.queue.lane.enqueue` (counter, attrs: `quantumclaw.lane`)
+- `quantumclaw.queue.lane.dequeue` (counter, attrs: `quantumclaw.lane`)
+- `quantumclaw.queue.depth` (histogram, attrs: `quantumclaw.lane` or
+  `quantumclaw.channel=heartbeat`)
+- `quantumclaw.queue.wait_ms` (histogram, attrs: `quantumclaw.lane`)
+- `quantumclaw.session.state` (counter, attrs: `quantumclaw.state`, `quantumclaw.reason`)
+- `quantumclaw.session.stuck` (counter, attrs: `quantumclaw.state`)
+- `quantumclaw.session.stuck_age_ms` (histogram, attrs: `quantumclaw.state`)
+- `quantumclaw.run.attempt` (counter, attrs: `quantumclaw.attempt`)
+
+### Exported spans (names + key attributes)
+
+- `quantumclaw.model.usage`
+  - `quantumclaw.channel`, `quantumclaw.provider`, `quantumclaw.model`
+  - `quantumclaw.sessionKey`, `quantumclaw.sessionId`
+  - `quantumclaw.tokens.*` (input/output/cache_read/cache_write/total)
+- `quantumclaw.webhook.processed`
+  - `quantumclaw.channel`, `quantumclaw.webhook`, `quantumclaw.chatId`
+- `quantumclaw.webhook.error`
+  - `quantumclaw.channel`, `quantumclaw.webhook`, `quantumclaw.chatId`,
+    `quantumclaw.error`
+- `quantumclaw.message.processed`
+  - `quantumclaw.channel`, `quantumclaw.outcome`, `quantumclaw.chatId`,
+    `quantumclaw.messageId`, `quantumclaw.sessionKey`, `quantumclaw.sessionId`,
+    `quantumclaw.reason`
+- `quantumclaw.session.stuck`
+  - `quantumclaw.state`, `quantumclaw.ageMs`, `quantumclaw.queueDepth`,
+    `quantumclaw.sessionKey`, `quantumclaw.sessionId`
+
+### Sampling + flushing
+
+- Trace sampling: `diagnostics.otel.sampleRate` (0.0–1.0, root spans only).
+- Metric export interval: `diagnostics.otel.flushIntervalMs` (min 1000ms).
+
+### Protocol notes
+
+- OTLP/HTTP endpoints can be set via `diagnostics.otel.endpoint` or
+  `OTEL_EXPORTER_OTLP_ENDPOINT`.
+- If the endpoint already contains `/v1/traces` or `/v1/metrics`, it is used as-is.
+- If the endpoint already contains `/v1/logs`, it is used as-is for logs.
+- `diagnostics.otel.logs` enables OTLP log export for the main logger output.
+
+### Log export behavior
+
+- OTLP logs use the same structured records written to `logging.file`.
+- Respect `logging.level` (file log level). Console redaction does **not** apply
+  to OTLP logs.
+- High-volume installs should prefer OTLP collector sampling/filtering.
+
+## Troubleshooting tips
+
+- **Gateway not reachable?** Run `quantumclaw doctor` first.
+- **Logs empty?** Check that the Gateway is running and writing to the file path
+  in `logging.file`.
+- **Need more detail?** Set `logging.level` to `debug` or `trace` and retry.

package/docs/nav-tabs-underline.js

@@ -0,0 +1,100 @@
+(() => {
+  const NAV_TABS_SELECTOR = ".nav-tabs";
+  const ACTIVE_UNDERLINE_SELECTOR = ".nav-tabs-item > div.bg-primary";
+  const UNDERLINE_CLASS = "nav-tabs-underline";
+  const READY_CLASS = "nav-tabs-underline-ready";
+
+  let navTabs = null;
+  let navTabsObserver = null;
+  let lastX = null;
+  let lastWidth = null;
+
+  const ensureUnderline = (tabs) => {
+    let underline = tabs.querySelector(`.${UNDERLINE_CLASS}`);
+    if (!underline) {
+      underline = document.createElement("div");
+      underline.className = UNDERLINE_CLASS;
+      tabs.appendChild(underline);
+    }
+    return underline;
+  };
+
+  const getActiveTab = (tabs) => {
+    const activeUnderline = tabs.querySelector(ACTIVE_UNDERLINE_SELECTOR);
+    return activeUnderline?.closest(".nav-tabs-item") ?? null;
+  };
+
+  const updateUnderline = () => {
+    if (!navTabs) {
+      return;
+    }
+
+    ensureUnderline(navTabs);
+
+    const activeTab = getActiveTab(navTabs);
+    if (!activeTab) {
+      navTabs.classList.remove(READY_CLASS);
+      return;
+    }
+
+    const navRect = navTabs.getBoundingClientRect();
+    const tabRect = activeTab.getBoundingClientRect();
+    const left = tabRect.left - navRect.left;
+
+    navTabs.style.setProperty("--nav-tab-underline-x", `${left}px`);
+    navTabs.style.setProperty("--nav-tab-underline-width", `${tabRect.width}px`);
+    navTabs.classList.add(READY_CLASS);
+
+    lastX = left;
+    lastWidth = tabRect.width;
+  };
+
+  const scheduleUpdate = () => {
+    requestAnimationFrame(updateUnderline);
+  };
+
+  const setupNavTabsObserver = (tabs) => {
+    if (!tabs || tabs === navTabs) {
+      return;
+    }
+
+    navTabs = tabs;
+    ensureUnderline(navTabs);
+    if (lastX !== null && lastWidth !== null) {
+      navTabs.style.setProperty("--nav-tab-underline-x", `${lastX}px`);
+      navTabs.style.setProperty("--nav-tab-underline-width", `${lastWidth}px`);
+      navTabs.classList.add(READY_CLASS);
+    }
+    navTabsObserver?.disconnect();
+    navTabsObserver = new MutationObserver(scheduleUpdate);
+    navTabsObserver.observe(navTabs, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["class"],
+    });
+
+    scheduleUpdate();
+  };
+
+  const setupObservers = () => {
+    const tabs = document.querySelector(NAV_TABS_SELECTOR);
+    if (tabs) {
+      setupNavTabsObserver(tabs);
+    }
+  };
+
+  const rootObserver = new MutationObserver(setupObservers);
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", () => {
+      setupObservers();
+      rootObserver.observe(document.body, { childList: true, subtree: true });
+    });
+  } else {
+    setupObservers();
+    rootObserver.observe(document.body, { childList: true, subtree: true });
+  }
+
+  window.addEventListener("resize", scheduleUpdate);
+  void document.fonts?.ready?.then(scheduleUpdate, () => {});
+})();