Amr Gharbeia
42e07801ce
Some checks failed
Deploy (Gitea) / deploy (push) Failing after 3s
Test results: 86 pass, 0 fail across 21 suites. TUI integration: 7/7 pass. Features: - 9-vector deterministic dispatcher gates (secrets, paths, shells, network) - Human-in-the-Loop Flight Plan workflow for blocked actions - Event Orchestrator: unified hooks + cron + tier-based routing - Context Manager: stack-based project scoping with persistence - Model-Tier Routing: per-slot provider cascades with privacy filter - Memory Scope Segmentation: memex/session/project with scope-aware retrieval - Asynchronous Embedding Gateway: provider-agnostic vectors with cron job - TUI Experience: scrollback, history, status bar, themes, tab completion - v0.2.x Backfill Remediation: 14 stale/todo/stub items resolved - Multi-distro deployment: Debian + Fedora, systemd, Docker - 31 literate Org files with full prose Fixes: - CLI test: fiveam:is t -> pass/fail handler-case - Cascade-parsing integration test: load provider before checking - Version strings 0.2.0 -> 0.3.0 in core-communication, tui-main, architecture
183 lines
7.4 KiB
Org Mode
183 lines
7.4 KiB
Org Mode
#+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 |