docs: lowercase internal docs + migrate website docs to public-docs/ (#634)
* docs: rename to lowercase + drop leftover plans Rename docs in docs/ to lowercase kebab-case for consistency and update all references in CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, packages/server/CLAUDE.md, and inter-doc links. Drop two leftover design plan docs: - docs/ATTACHMENT_BASED_REVIEW_CONTEXT_PLAN.md - docs/plan-approval-normalization.md * docs: drop stale uppercase entries from case-insensitive rename * feat(website): power /docs from public-docs/ markdown tree Move website docs out of TSX route components and into a root-level public-docs/ directory of plain markdown files with frontmatter (title, description, nav, order). - Add packages/website/src/docs.ts loader using import.meta.glob with ?raw to compile the markdown into the bundle at build time. - Replace the 9 hand-written docs/*.tsx routes with a single $.tsx catch-all that renders any slug via react-markdown. - Drive the docs sidebar nav from frontmatter order/nav. - Auto-discover docs routes in vite.config.ts so the sitemap stays in sync without manual edits. * fix(website): bind dev server to 0.0.0.0 so port collisions trigger fallback `host: "127.0.0.1"` (or unset) lets macOS coexist with another process holding an IPv6 dual-stack `*:8082` socket, so Vite never sees EADDRINUSE and silently binds alongside it. Forcing IPv4 wildcard makes the conflict real, and Vite's default `strictPort: false` falls through to the next free port. * fix(website): restore docs page styling after markdown migration Add a .docs-prose class that mirrors the styling the original docs/*.tsx components hand-rolled (h1/h2/h3 sizes, paragraph/list spacing, link colors, code blocks, callout-style blockquotes). ReactMarkdown was emitting unstyled HTML because the previous wrapper class only had inline-code rules — headings and code blocks fell back to user-agent defaults.
This commit is contained in:
Mohamed Boudra
@@ -0,0 +1,118 @@
|
||||
---
|
||||
title: Configuration
|
||||
description: Configure Paseo via config.json, environment variables, and CLI overrides.
|
||||
nav: Configuration
|
||||
order: 8
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
Paseo loads configuration from a single JSON file in your Paseo home directory, with optional environment variable and CLI overrides.
|
||||
|
||||
## Where config lives
|
||||
|
||||
By default, Paseo uses `~/.paseo` as its home directory. The configuration file is:
|
||||
|
||||
```bash
|
||||
~/.paseo/config.json
|
||||
```
|
||||
|
||||
You can change the home directory by setting `PASEO_HOME` or passing `--home` to `paseo daemon start`.
|
||||
|
||||
## Precedence
|
||||
|
||||
Paseo merges configuration in this order:
|
||||
|
||||
1. Defaults
|
||||
2. `config.json`
|
||||
3. Environment variables
|
||||
4. CLI flags
|
||||
|
||||
Lists append across sources (for example, `hostnames` and `cors.allowedOrigins`).
|
||||
|
||||
## Example
|
||||
|
||||
Minimal example that configures listening address, hostnames, and MCP:
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://paseo.sh/schemas/paseo.config.v1.json",
|
||||
"version": 1,
|
||||
"daemon": {
|
||||
"listen": "127.0.0.1:6767",
|
||||
"hostnames": ["localhost", ".localhost"],
|
||||
"mcp": { "enabled": true }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`daemon.hostnames` is the primary field. The old `daemon.allowedHosts` name still works as a deprecated alias for backward compatibility.
|
||||
|
||||
## Agent providers
|
||||
|
||||
Agent providers — both the first-class ones Paseo ships with and custom entries you add under `agents.providers` — are documented on their own page.
|
||||
|
||||
See [Providers](/docs/providers) for first-class providers, how to point Claude at Anthropic-compatible endpoints (Z.AI, Alibaba/Qwen), multiple profiles, custom binaries, ACP agents, and the `additionalModels` merge behavior. The full field reference lives on GitHub at [docs/custom-providers.md](https://github.com/getpaseo/paseo/blob/main/docs/custom-providers.md).
|
||||
|
||||
## Voice
|
||||
|
||||
Voice is configured through `features.dictation` and `features.voiceMode`, with provider credentials under `providers`.
|
||||
|
||||
For voice philosophy, architecture, and complete local/OpenAI setup examples, see [Voice docs](/docs/voice).
|
||||
|
||||
## Logging
|
||||
|
||||
Daemon logging uses separate console and file sinks by default:
|
||||
|
||||
- Console: `info` and above
|
||||
- File (`$PASEO_HOME/daemon.log`): `trace` and above
|
||||
- File rotation: `10m` max file size, `2` retained files total (active + 1 rotated)
|
||||
|
||||
```json
|
||||
{
|
||||
"log": {
|
||||
"console": {
|
||||
"level": "info",
|
||||
"format": "pretty"
|
||||
},
|
||||
"file": {
|
||||
"level": "trace",
|
||||
"path": "daemon.log",
|
||||
"rotate": {
|
||||
"maxSize": "10m",
|
||||
"maxFiles": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Legacy fields `log.level` and `log.format` are still supported and map to the new destination settings.
|
||||
|
||||
## Common env vars
|
||||
|
||||
- `PASEO_HOME` — set Paseo home directory
|
||||
- `PASEO_LISTEN` — override `daemon.listen`
|
||||
- `PASEO_HOSTNAMES` — override/extend `daemon.hostnames`
|
||||
- `PASEO_ALLOWED_HOSTS` — deprecated alias for `PASEO_HOSTNAMES`
|
||||
- `PASEO_LOG_CONSOLE_LEVEL` — override `log.console.level`
|
||||
- `PASEO_LOG_FILE_LEVEL` — override `log.file.level`
|
||||
- `PASEO_LOG_FILE_PATH` — override `log.file.path`
|
||||
- `PASEO_LOG_FILE_ROTATE_SIZE` — override `log.file.rotate.maxSize`
|
||||
- `PASEO_LOG_FILE_ROTATE_COUNT` — override `log.file.rotate.maxFiles`
|
||||
- `PASEO_LOG`, `PASEO_LOG_FORMAT` — legacy log overrides (still supported)
|
||||
- `OPENAI_API_KEY` — override OpenAI provider key
|
||||
- `PASEO_VOICE_LLM_PROVIDER` — override voice LLM provider (`claude`, `codex`, `opencode`)
|
||||
- `PASEO_DICTATION_STT_PROVIDER`, `PASEO_VOICE_STT_PROVIDER`, `PASEO_VOICE_TTS_PROVIDER` — override voice provider selection (`local` or `openai`)
|
||||
- `PASEO_LOCAL_MODELS_DIR` — control local model directory
|
||||
- `PASEO_DICTATION_LOCAL_STT_MODEL` — override local dictation STT model
|
||||
- `PASEO_VOICE_LOCAL_STT_MODEL`, `PASEO_VOICE_LOCAL_TTS_MODEL` — override local voice STT/TTS models
|
||||
- `PASEO_VOICE_LOCAL_TTS_SPEAKER_ID`, `PASEO_VOICE_LOCAL_TTS_SPEED` — optional local voice TTS tuning
|
||||
|
||||
## Schema
|
||||
|
||||
For editor autocomplete/validation, set `$schema` to:
|
||||
|
||||
```
|
||||
https://paseo.sh/schemas/paseo.config.v1.json
|
||||
```
|
||||
Reference in New Issue
Block a user