Amr Gharbeia
95d1ea3fed
- Add deepseek and nvidia entries to gateway-provider config - Add DEEPSEEK_API_KEY and NVIDIA_API_KEY to .env.example - Add deepseek and nvidia to doctor's LLM provider check - Fix remaining harness-log → log-message reference
62 lines
2.7 KiB
Org Mode
62 lines
2.7 KiB
Org Mode
#+TITLE: Passepartout User Manual
|
|
#+AUTHOR: Agent
|
|
#+STARTUP: content
|
|
#+FILETAGS: :docs:manual:
|
|
|
|
* Introduction
|
|
Welcome to the Passepartout User Manual. This guide provides the operational knowledge required to manage your sovereign Lisp Machine and its neural skills.
|
|
|
|
* System Architecture
|
|
Passepartout follows a "Purified Kernel" model. The core harness handles essential I/O, while all high-level logic resides in sovereign skills.
|
|
|
|
** XDG Directory Standard
|
|
To ensure POSIX compliance, Passepartout stores its files in standard Linux locations:
|
|
|
|
| Type | Path | Purpose |
|
|
| :--- | :--- | :--- |
|
|
| **Config** | `~/.config/passepartout/` | User settings, `.env` secrets, and provider registry. |
|
|
| **Data** | `~/.local/share/passepartout/` | Tangled Lisp artifacts and the compiled engine. |
|
|
| **State** | `~/.local/state/passepartout/` | Brain snapshots, logs, and Merkle-memory. |
|
|
| **Bin** | `~/.local/bin/passepartout` | The global CLI shim. |
|
|
|
|
* Command Reference
|
|
|
|
** `passepartout setup`
|
|
The interactive configuration wizard. Use this to:
|
|
- Define your identity and the Agent's name.
|
|
- Register LLM providers (Ollama, Groq, Anthropic, etc.).
|
|
- The wizard automatically splits sensitive tokens into `~/.config/passepartout/.env`.
|
|
|
|
** `passepartout gateway link <platform> <token>`
|
|
Connects Passepartout to external communication gateways.
|
|
- **Example:** `passepartout gateway link telegram <my_bot_token>`
|
|
- **Example:** `passepartout gateway unlink telegram` to disable
|
|
- **Example:** `passepartout gateway list` to see status
|
|
|
|
** `passepartout doctor`
|
|
Your primary diagnostic tool. Run this if the system feels sluggish or fails to boot. It verifies:
|
|
- External dependencies (sbcl, git, socat).
|
|
- XDG directory existence and permissions.
|
|
- LLM connectivity.
|
|
|
|
** `passepartout tui`
|
|
Launches the native Lisp Terminal User Interface.
|
|
- **Highlighting:** Semantic color-coding for Lisp and Org syntax.
|
|
- **Scrolling:** Use `PgUp`/`PgDn` to navigate history.
|
|
- **Exit:** Type `/exit` or `Ctrl+C` to close.
|
|
|
|
* Configuration Strategy
|
|
Passepartout uses a **Hybrid Storage** model for maximum security and flexibility.
|
|
|
|
** 1. Secrets (`.env`)
|
|
Found in `~/.config/passepartout/.env`. This file stores raw API tokens. It is never automatically read by the Lisp structural parser to prevent accidental leakage into logs.
|
|
|
|
** 2. Metadata (`providers.lisp`)
|
|
Found in `~/.config/passepartout/providers.lisp`. This stores non-sensitive configuration like model names, base URLs, and user preferences as native Lisp S-expressions.
|
|
|
|
* Troubleshooting
|
|
If `passepartout doctor` reports a `FAIL`:
|
|
1. Check that your `PATH` includes `/usr/bin` and `/usr/local/bin`.
|
|
2. Ensure `sbcl` is installed.
|
|
3. If LLM connectivity fails, verify your API key in `~/.config/passepartout/.env`.
|