durar-ai 2026.4.4

package/docs/nodes/voicewake.md

@@ -0,0 +1,66 @@
+---
+summary: "Global voice wake words (Gateway-owned) and how they sync across nodes"
+read_when:
+  - Changing voice wake words behavior or defaults
+  - Adding new node platforms that need wake word sync
+title: "Voice Wake"
+---
+
+# Voice Wake (Global Wake Words)
+
+Durar treats **wake words as a single global list** owned by the **Gateway**.
+
+- There are **no per-node custom wake words**.
+- **Any node/app UI may edit** the list; changes are persisted by the Gateway and broadcast to everyone.
+- macOS and iOS keep local **Voice Wake enabled/disabled** toggles (local UX + permissions differ).
+- Android currently keeps Voice Wake off and uses a manual mic flow in the Voice tab.
+
+## Storage (Gateway host)
+
+Wake words are stored on the gateway machine at:
+
+- `~/.Durar/settings/voicewake.json`
+
+Shape:
+
+```json
+{ "triggers": ["Durar", "claude", "computer"], "updatedAtMs": 1730000000000 }
+```
+
+## Protocol
+
+### Methods
+
+- `voicewake.get` → `{ triggers: string[] }`
+- `voicewake.set` with params `{ triggers: string[] }` → `{ triggers: string[] }`
+
+Notes:
+
+- Triggers are normalized (trimmed, empties dropped). Empty lists fall back to defaults.
+- Limits are enforced for safety (count/length caps).
+
+### Events
+
+- `voicewake.changed` payload `{ triggers: string[] }`
+
+Who receives it:
+
+- All WebSocket clients (macOS app, WebChat, etc.)
+- All connected nodes (iOS/Android), and also on node connect as an initial “current state” push.
+
+## Client behavior
+
+### macOS app
+
+- Uses the global list to gate `VoiceWakeRuntime` triggers.
+- Editing “Trigger words” in Voice Wake settings calls `voicewake.set` and then relies on the broadcast to keep other clients in sync.
+
+### iOS node
+
+- Uses the global list for `VoiceWakeManager` trigger detection.
+- Editing Wake Words in Settings calls `voicewake.set` (over the Gateway WS) and also keeps local wake-word detection responsive.
+
+### Android node
+
+- Voice Wake is currently disabled in Android runtime/Settings.
+- Android voice uses manual mic capture in the Voice tab instead of wake-word triggers.

package/docs/perplexity.md

@@ -0,0 +1,181 @@
+---
+summary: "Perplexity Search API and Sonar/OpenRouter compatibility for web_search"
+read_when:
+  - You want to use Perplexity Search for web search
+  - You need PERPLEXITY_API_KEY or OPENROUTER_API_KEY setup
+title: "Perplexity Search (legacy path)"
+---
+
+# Perplexity Search API
+
+Durar supports Perplexity Search API as a `web_search` provider.
+It returns structured results with `title`, `url`, and `snippet` fields.
+
+For compatibility, Durar also supports legacy Perplexity Sonar/OpenRouter setups.
+If you use `OPENROUTER_API_KEY`, an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`, or set `plugins.entries.perplexity.config.webSearch.baseUrl` / `model`, the provider switches to the chat-completions path and returns AI-synthesized answers with citations instead of structured Search API results.
+
+## Getting a Perplexity API key
+
+1. Create a Perplexity account at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)
+2. Generate an API key in the dashboard
+3. Store the key in config or set `PERPLEXITY_API_KEY` in the Gateway environment.
+
+## OpenRouter compatibility
+
+If you were already using OpenRouter for Perplexity Sonar, keep `provider: "perplexity"` and set `OPENROUTER_API_KEY` in the Gateway environment, or store an `sk-or-...` key in `plugins.entries.perplexity.config.webSearch.apiKey`.
+
+Optional compatibility controls:
+
+- `plugins.entries.perplexity.config.webSearch.baseUrl`
+- `plugins.entries.perplexity.config.webSearch.model`
+
+## Config examples
+
+### Native Perplexity Search API
+
+```json5
+{
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "pplx-...",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+      },
+    },
+  },
+}
+```
+
+### OpenRouter / Sonar compatibility
+
+```json5
+{
+  plugins: {
+    entries: {
+      perplexity: {
+        config: {
+          webSearch: {
+            apiKey: "<openrouter-api-key>",
+            baseUrl: "https://openrouter.ai/api/v1",
+            model: "perplexity/sonar-pro",
+          },
+        },
+      },
+    },
+  },
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+      },
+    },
+  },
+}
+```
+
+## Where to set the key
+
+**Via config:** run `Durar configure --section web`. It stores the key in
+`~/.Durar/Durar.json` under `plugins.entries.perplexity.config.webSearch.apiKey`.
+That field also accepts SecretRef objects.
+
+**Via environment:** set `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
+in the Gateway process environment. For a gateway install, put it in
+`~/.Durar/.env` (or your service environment). See [Env vars](/help/faq#env-vars-and-env-loading).
+
+If `provider: "perplexity"` is configured and the Perplexity key SecretRef is unresolved with no env fallback, startup/reload fails fast.
+
+## Tool parameters
+
+These parameters apply to the native Perplexity Search API path.
+
+| Parameter             | Description                                          |
+| --------------------- | ---------------------------------------------------- |
+| `query`               | Search query (required)                              |
+| `count`               | Number of results to return (1-10, default: 5)       |
+| `country`             | 2-letter ISO country code (e.g., "US", "DE")         |
+| `language`            | ISO 639-1 language code (e.g., "en", "de", "fr")     |
+| `freshness`           | Time filter: `day` (24h), `week`, `month`, or `year` |
+| `date_after`          | Only results published after this date (YYYY-MM-DD)  |
+| `date_before`         | Only results published before this date (YYYY-MM-DD) |
+| `domain_filter`       | Domain allowlist/denylist array (max 20)             |
+| `max_tokens`          | Total content budget (default: 25000, max: 1000000)  |
+| `max_tokens_per_page` | Per-page token limit (default: 2048)                 |
+
+For the legacy Sonar/OpenRouter compatibility path:
+
+- `query`, `count`, and `freshness` are accepted
+- `count` is compatibility-only there; the response is still one synthesized
+  answer with citations rather than an N-result list
+- Search API-only filters such as `country`, `language`, `date_after`,
+  `date_before`, `domain_filter`, `max_tokens`, and `max_tokens_per_page`
+  return explicit errors
+
+**Examples:**
+
+```javascript
+// Country and language-specific search
+await web_search({
+  query: "renewable energy",
+  country: "DE",
+  language: "de",
+});
+
+// Recent results (past week)
+await web_search({
+  query: "AI news",
+  freshness: "week",
+});
+
+// Date range search
+await web_search({
+  query: "AI developments",
+  date_after: "2024-01-01",
+  date_before: "2024-06-30",
+});
+
+// Domain filtering (allowlist)
+await web_search({
+  query: "climate research",
+  domain_filter: ["nature.com", "science.org", ".edu"],
+});
+
+// Domain filtering (denylist - prefix with -)
+await web_search({
+  query: "product reviews",
+  domain_filter: ["-reddit.com", "-pinterest.com"],
+});
+
+// More content extraction
+await web_search({
+  query: "detailed AI research",
+  max_tokens: 50000,
+  max_tokens_per_page: 4096,
+});
+```
+
+### Domain filter rules
+
+- Maximum 20 domains per filter
+- Cannot mix allowlist and denylist in the same request
+- Use `-` prefix for denylist entries (e.g., `["-reddit.com"]`)
+
+## Notes
+
+- Perplexity Search API returns structured web search results (`title`, `url`, `snippet`)
+- OpenRouter or explicit `plugins.entries.perplexity.config.webSearch.baseUrl` / `model` switches Perplexity back to Sonar chat completions for compatibility
+- Sonar/OpenRouter compatibility returns one synthesized answer with citations, not structured result rows
+- Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`)
+
+See [Web tools](/tools/web) for the full web_search configuration.
+See [Perplexity Search API docs](https://docs.perplexity.ai/docs/search/quickstart) for more details.

package/docs/pi-dev.md

@@ -0,0 +1,80 @@
+---
+title: "Pi Development Workflow"
+summary: "Developer workflow for Pi integration: build, test, and live validation"
+read_when:
+  - Working on Pi integration code or tests
+  - Running Pi-specific lint, typecheck, and live test flows
+---
+
+# Pi Development Workflow
+
+This guide summarizes a sane workflow for working on the pi integration in Durar.
+
+## Type Checking and Linting
+
+- Default local gate: `pnpm check`
+- Build gate: `pnpm build` when the change can affect build output, packaging, or lazy-loading/module boundaries
+- Full landing gate for Pi-heavy changes: `pnpm check && pnpm test`
+
+## Running Pi Tests
+
+Run the Pi-focused test set directly with Vitest:
+
+```bash
+pnpm test \
+  "src/agents/pi-*.test.ts" \
+  "src/agents/pi-embedded-*.test.ts" \
+  "src/agents/pi-tools*.test.ts" \
+  "src/agents/pi-settings.test.ts" \
+  "src/agents/pi-tool-definition-adapter*.test.ts" \
+  "src/agents/pi-hooks/**/*.test.ts"
+```
+
+To include the live provider exercise:
+
+```bash
+Durar_LIVE_TEST=1 pnpm test src/agents/pi-embedded-runner-extraparams.live.test.ts
+```
+
+This covers the main Pi unit suites:
+
+- `src/agents/pi-*.test.ts`
+- `src/agents/pi-embedded-*.test.ts`
+- `src/agents/pi-tools*.test.ts`
+- `src/agents/pi-settings.test.ts`
+- `src/agents/pi-tool-definition-adapter.test.ts`
+- `src/agents/pi-hooks/*.test.ts`
+
+## Manual Testing
+
+Recommended flow:
+
+- Run the gateway in dev mode:
+  - `pnpm gateway:dev`
+- Trigger the agent directly:
+  - `pnpm Durar agent --message "Hello" --thinking low`
+- Use the TUI for interactive debugging:
+  - `pnpm tui`
+
+For tool call behavior, prompt for a `read` or `exec` action so you can see tool streaming and payload handling.
+
+## Clean Slate Reset
+
+State lives under the Durar state directory. Default is `~/.Durar`. If `Durar_STATE_DIR` is set, use that directory instead.
+
+To reset everything:
+
+- `Durar.json` for config
+- `agents/<agentId>/agent/auth-profiles.json` for model auth profiles (API keys + OAuth)
+- `credentials/` for provider/channel state that still lives outside the auth profile store
+- `agents/<agentId>/sessions/` for agent session history
+- `agents/<agentId>/sessions/sessions.json` for the session index
+- `sessions/` if legacy paths exist
+- `workspace/` if you want a blank workspace
+
+If you only want to reset sessions, delete `agents/<agentId>/sessions/` for that agent. If you want to keep auth, leave `agents/<agentId>/agent/auth-profiles.json` and any provider state under `credentials/` in place.
+
+## References
+
+- [Testing](/help/testing)
+- [Getting Started](/start/getting-started)