pllan 2026.3.43 → 2026.3.45

package/docs/sv/install/updating.md

@@ -0,0 +1,128 @@
+---
+summary: "Updating Pllan safely (global install or source), plus rollback strategy"
+read_when:
+  - Updating Pllan
+  - Something breaks after an update
+title: "Updating"
+---
+
+# Updating
+
+Keep Pllan up to date.
+
+## Recommended: `pllan update`
+
+The fastest way to update. It detects your install type (npm or git), fetches the latest version, runs `pllan doctor`, and restarts the gateway.
+
+```bash
+pllan update
+```
+
+To switch channels or target a specific version:
+
+```bash
+pllan update --channel beta
+pllan update --tag main
+pllan update --dry-run   # preview without applying
+```
+
+See [Development channels](/install/development-channels) for channel semantics.
+
+## Alternative: re-run the installer
+
+```bash
+curl -fsSL https://pllan.ai/install.sh | bash
+```
+
+Add `--no-onboard` to skip onboarding. For source installs, pass `--install-method git --no-onboard`.
+
+## Alternative: manual npm or pnpm
+
+```bash
+npm i -g pllan@latest
+```
+
+```bash
+pnpm add -g pllan@latest
+```
+
+## Auto-updater
+
+The auto-updater is off by default. Enable it in `~/.pllan/pllan.json`:
+
+```json5
+{
+  update: {
+    channel: "stable",
+    auto: {
+      enabled: true,
+      stableDelayHours: 6,
+      stableJitterHours: 12,
+      betaCheckIntervalHours: 1,
+    },
+  },
+}
+```
+
+| Channel  | Behavior                                                                                                      |
+| -------- | ------------------------------------------------------------------------------------------------------------- |
+| `stable` | Waits `stableDelayHours`, then applies with deterministic jitter across `stableJitterHours` (spread rollout). |
+| `beta`   | Checks every `betaCheckIntervalHours` (default: hourly) and applies immediately.                              |
+| `dev`    | No automatic apply. Use `pllan update` manually.                                                           |
+
+The gateway also logs an update hint on startup (disable with `update.checkOnStart: false`).
+
+## After updating
+
+<Steps>
+
+### Run doctor
+
+```bash
+pllan doctor
+```
+
+Migrates config, audits DM policies, and checks gateway health. Details: [Doctor](/gateway/doctor)
+
+### Restart the gateway
+
+```bash
+pllan gateway restart
+```
+
+### Verify
+
+```bash
+pllan health
+```
+
+</Steps>
+
+## Rollback
+
+### Pin a version (npm)
+
+```bash
+npm i -g pllan@<version>
+pllan doctor
+pllan gateway restart
+```
+
+Tip: `npm view pllan version` shows the current published version.
+
+### Pin a commit (source)
+
+```bash
+git fetch origin
+git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
+pnpm install && pnpm build
+pllan gateway restart
+```
+
+To return to latest: `git checkout main && git pull`.
+
+## If you are stuck
+
+- Run `pllan doctor` again and read the output carefully.
+- Check: [Troubleshooting](/gateway/troubleshooting)
+- Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)

package/docs/sv/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
+
+Pllan 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/pllan/pllan-YYYY-MM-DD.log`
+
+The date uses the gateway host's local timezone.
+
+You can override this in `~/.pllan/pllan.json`:
+
+```json
+{
+  "logging": {
+    "file": "/path/to/pllan.log"
+  }
+}
+```
+
+## How to read logs
+
+### CLI: live tail (recommended)
+
+Use the CLI to tail the gateway log file via RPC:
+
+```bash
+pllan 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
+pllan 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
+pllan 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 `~/.pllan/pllan.json`.
+
+```json
+{
+  "logging": {
+    "level": "info",
+    "file": "/tmp/pllan/pllan-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 **`PLLAN_LOG_LEVEL`** environment variable (e.g. `PLLAN_LOG_LEVEL=debug`). The env var takes precedence over the config file, so you can raise verbosity for a single run without editing `pllan.json`. You can also pass the global CLI option **`--log-level <level>`** (for example, `pllan --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.
+- Pllan 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):
+
+```
+PLLAN_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": "pllan-gateway",
+      "traces": true,
+      "metrics": true,
+      "logs": true,
+      "sampleRate": 0.2,
+      "flushIntervalMs": 60000
+    }
+  }
+}
+```
+
+Notes:
+
+- You can also enable the plugin with `pllan 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:
+
+- `pllan.tokens` (counter, attrs: `pllan.token`, `pllan.channel`,
+  `pllan.provider`, `pllan.model`)
+- `pllan.cost.usd` (counter, attrs: `pllan.channel`, `pllan.provider`,
+  `pllan.model`)
+- `pllan.run.duration_ms` (histogram, attrs: `pllan.channel`,
+  `pllan.provider`, `pllan.model`)
+- `pllan.context.tokens` (histogram, attrs: `pllan.context`,
+  `pllan.channel`, `pllan.provider`, `pllan.model`)
+
+Message flow:
+
+- `pllan.webhook.received` (counter, attrs: `pllan.channel`,
+  `pllan.webhook`)
+- `pllan.webhook.error` (counter, attrs: `pllan.channel`,
+  `pllan.webhook`)
+- `pllan.webhook.duration_ms` (histogram, attrs: `pllan.channel`,
+  `pllan.webhook`)
+- `pllan.message.queued` (counter, attrs: `pllan.channel`,
+  `pllan.source`)
+- `pllan.message.processed` (counter, attrs: `pllan.channel`,
+  `pllan.outcome`)
+- `pllan.message.duration_ms` (histogram, attrs: `pllan.channel`,
+  `pllan.outcome`)
+
+Queues + sessions:
+
+- `pllan.queue.lane.enqueue` (counter, attrs: `pllan.lane`)
+- `pllan.queue.lane.dequeue` (counter, attrs: `pllan.lane`)
+- `pllan.queue.depth` (histogram, attrs: `pllan.lane` or
+  `pllan.channel=heartbeat`)
+- `pllan.queue.wait_ms` (histogram, attrs: `pllan.lane`)
+- `pllan.session.state` (counter, attrs: `pllan.state`, `pllan.reason`)
+- `pllan.session.stuck` (counter, attrs: `pllan.state`)
+- `pllan.session.stuck_age_ms` (histogram, attrs: `pllan.state`)
+- `pllan.run.attempt` (counter, attrs: `pllan.attempt`)
+
+### Exported spans (names + key attributes)
+
+- `pllan.model.usage`
+  - `pllan.channel`, `pllan.provider`, `pllan.model`
+  - `pllan.sessionKey`, `pllan.sessionId`
+  - `pllan.tokens.*` (input/output/cache_read/cache_write/total)
+- `pllan.webhook.processed`
+  - `pllan.channel`, `pllan.webhook`, `pllan.chatId`
+- `pllan.webhook.error`
+  - `pllan.channel`, `pllan.webhook`, `pllan.chatId`,
+    `pllan.error`
+- `pllan.message.processed`
+  - `pllan.channel`, `pllan.outcome`, `pllan.chatId`,
+    `pllan.messageId`, `pllan.sessionKey`, `pllan.sessionId`,
+    `pllan.reason`
+- `pllan.session.stuck`
+  - `pllan.state`, `pllan.ageMs`, `pllan.queueDepth`,
+    `pllan.sessionKey`, `pllan.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 `pllan 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/sv/network.md

@@ -0,0 +1,54 @@
+---
+summary: "Network hub: gateway surfaces, pairing, discovery, and security"
+read_when:
+  - You need the network architecture + security overview
+  - You are debugging local vs tailnet access or pairing
+  - You want the canonical list of networking docs
+title: "Network"
+---
+
+# Network hub
+
+This hub links the core docs for how Pllan connects, pairs, and secures
+devices across localhost, LAN, and tailnet.
+
+## Core model
+
+- [Gateway architecture](/concepts/architecture)
+- [Gateway protocol](/gateway/protocol)
+- [Gateway runbook](/gateway)
+- [Web surfaces + bind modes](/web)
+
+## Pairing + identity
+
+- [Pairing overview (DM + nodes)](/channels/pairing)
+- [Gateway-owned node pairing](/gateway/pairing)
+- [Devices CLI (pairing + token rotation)](/cli/devices)
+- [Pairing CLI (DM approvals)](/cli/pairing)
+
+Local trust:
+
+- Local connections (loopback or the gateway host’s own tailnet address) can be
+  auto‑approved for pairing to keep same‑host UX smooth.
+- Non‑local tailnet/LAN clients still require explicit pairing approval.
+
+## Discovery + transports
+
+- [Discovery & transports](/gateway/discovery)
+- [Bonjour / mDNS](/gateway/bonjour)
+- [Remote access (SSH)](/gateway/remote)
+- [Tailscale](/gateway/tailscale)
+
+## Nodes + transports
+
+- [Nodes overview](/nodes)
+- [Bridge protocol (legacy nodes)](/gateway/bridge-protocol)
+- [Node runbook: iOS](/platforms/ios)
+- [Node runbook: Android](/platforms/android)
+
+## Security
+
+- [Security overview](/gateway/security)
+- [Gateway config reference](/gateway/configuration)
+- [Troubleshooting](/gateway/troubleshooting)
+- [Doctor](/gateway/doctor)