#+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`.