#+TITLE: Passepartout User Manual
#+AUTHOR: Passepartout Contributors
#+STARTUP: content
#+FILETAGS: :docs:manual:

* Introduction
Welcome to Passepartout. Passepartout is a neurosymbolic AI agent and a Lisp Machine operating system designed to autonomously maintain your Memex (knowledge base) and interact with you via multiple, equal-citizen interfaces.

* Installation
Passepartout is bootstrapped via a single shell script.

** Quick start (curl)

#+begin_src bash
curl -fsSL https://raw.githubusercontent.com/amrgharbeia/passepartout/main/passepartout | bash -s configure
#+end_src

This will:
1. Install system dependencies (SBCL, Emacs, git, curl, socat — detected for Debian or Fedora)
2. Install Quicklisp (Common Lisp package manager)
3. Tangle literate Org sources into runnable Lisp
4. Launch the interactive setup wizard (LLM providers, gateways)

If you already have Emacs installed, the installer skips it and uses your existing installation.

* Configuration
The system is configured via a `.env` file in the project root. Essential variables include:

- `OPENROUTER_API_KEY`: Your LLM provider key.
- `PROVIDER_CASCADE`: The fallback order for LLM providers (e.g., `openrouter,ollama,anthropic`).
- `MEMEX_DIR`: The absolute path to your knowledge base (defaults to `~/memex`).

* Interacting with Passepartout
Because of the Unified Envelope Architecture, the kernel treats all clients as interchangeable. You must first boot the background daemon:

#+begin_src bash
./passepartout --boot &
#+end_src

** Terminal User Interface (TUI)
For a rich, split-pane terminal experience:
#+begin_src bash
./passepartout tui
#+end_src

** Command Line Interface (CLI)
For raw, pipe-friendly interaction:
#+begin_src bash
./passepartout cli
#+end_src

** TUI Commands

When connected via the TUI, the following commands are available (type them in the input area and press Enter):

| Command               | Action                                                 |
|-----------------------+--------------------------------------------------------|
| ~/help~               | List all available commands                             |
| ~/focus <project>~    | Set the agent's foveal focus to a project by name      |
| ~/scope memex~        | Set scope to full memex (all projects visible)         |
| ~/scope session~      | Set scope to current session only                       |
| ~/scope project~      | Set scope to focused project only                       |
| ~/unfocus~            | Clear the foveal focus                                  |
| ~/approve HITL-xxxx~  | Approve a pending HITL action by its token              |
| ~/deny HITL-xxxx~     | Deny a pending HITL action by its token                 |
| ~/theme <name>~       | Switch theme (dark, light, solarized, gruvbox)         |
| ~/cost~               | Toggle session cost display in status bar               |
| ~/voice on~           | Enable voice capture (planned v0.7.3)                  |
| ~/voice off~          | Disable voice capture                                   |
| ~/quit~               | Save history and exit (planned v0.3.3)                 |

For multi-line input, start the line with ~\~ then press Enter to insert a newline without sending.

** Human-in-the-Loop Approval

When the Dispatcher blocks a high-risk action (shell command, network call, core file modification), it creates a Flight Plan requiring your approval.

1. The TUI displays a yellow message: ~→ HITL required: /approve HITL-ab12~
2. Review the proposed action in the Dispatcher trace (expand with Tab)
3. Type ~/approve HITL-ab12~ to approve, or ~/deny HITL-ab12~ to deny
4. Approved actions are re-injected into the pipeline and executed
5. Denied actions are discarded and the Dispatcher records the decision as a permanent rule

Each approval or denial teaches the Dispatcher — the rule counter in the status bar (~[Rules: 47]~) increments with every decision.

* The Memex Structure
Passepartout assumes a local folder structure representing your "Memex".
- Core memories and identities are mapped to Org-mode files.
- The `Scribe` background worker distills chronological logs into structured Zettelkasten notes.
- The `Gardener` continuously repairs broken links and flags orphaned nodes.

* Deployment

** Bare metal (Debian / Fedora)

The ~configure~ command supports both Debian-based (Ubuntu, Pop, Mint) and Fedora-based (RHEL, Rocky) distributions. It detects your distro automatically and installs the correct packages.

#+begin_src bash
./passepartout configure              # interactive
./passepartout configure --non-interactive  # headless
./passepartout configure --with-firewall    # also open port 9105
#+end_src

After configuration, you can re-run ~configure~ any time to add providers or link gateways.

** Binary install (save-lisp-and-die)

For platforms where SBCL cannot be installed (corporate laptops, shared hosts, constrained environments), a self-contained binary is provided:

#+begin_src bash
curl -fsSL https://github.com/amrgharbeia/passepartout/releases/latest/download/passepartout -o passepartout
chmod +x passepartout
./passepartout daemon
#+end_src

This binary bundles SBCL, all required Lisp code, native embedding inference, and a Swank server on port 4005. The experience is identical to a source install — the REPL is available, skills hot-reload, and the image is mutable. Memory survives snapshots.

The binary is a convenience for constrained platforms. It is not a sealed container. The system remains constitutionally open — connect with SLIME, trace functions, inspect memory objects, modify the system while it runs.

** systemd service (auto-start on boot)

#+begin_src bash
./passepartout install service
#+end_src

Installs a user-level systemd unit that starts the daemon on login. Logs are available via ~journalctl --user -u passepartout.service -f~.

To remove:

#+begin_src bash
./passepartout uninstall service
#+end_src

** Docker

A Debian-based Docker image is provided for containerized deployment.

#+begin_src bash
cd infrastructure/docker
docker-compose up -d
#+end_src

This builds an image from ~debian:trixie-slim~ with all dependencies pre-installed. The memex directory is mounted from the host.

** Backup

#+begin_src bash
./passepartout backup ~/my-backup.tar.gz
#+end_src

Backs up the config, data, and memex directories.

** Restore

#+begin_src bash
./passepartout restore ~/my-backup.tar.gz
#+end_src

Restores from a backup file. Run ~passepartout doctor~ afterward to verify integrity.

* Troubleshooting

** The daemon won't start
- Check SBCL is installed: ~which sbcl~
- Run ~passepartout doctor~ to diagnose
- Check port 9105 is free: ~lsof -i :9105~
- Check the log output for errors

** The TUI connects but shows "Disconnected"
- The daemon may have crashed. Run ~passepartout daemon~ in another terminal
- If the daemon is running, check it's listening: ~lsof -i :9105~
- Use ~/reconnect~ (planned v0.6.0) to reconnect without restarting the TUI

** The LLM returns garbage or fails to respond
- Run ~passepartout doctor~ to verify your LLM provider keys
- Check ~PROVIDER_CASCADE~ in your ~.env~ file
- Try switching models: edit ~.env~ and restart the daemon
- If using local models via Ollama, verify Ollama is running: ~ollama list~

** Memory fails to load on startup
- Check ~/memory.snap~ exists and is valid S-expression format
- Run ~passepartout doctor~ to diagnose memory integrity
- If corrupted, delete ~/memory.snap~ and restart — the daemon starts with empty memory