passepartout/USER_MANUAL.org

OpenCortex User Manual

• Introduction
• System Architecture
  • XDG Directory Standard
• Command Reference
  • `opencortex setup`
  • `opencortex link <platform> <token>`
  • `opencortex doctor`
  • `opencortex tui`
• Configuration Strategy
  • 1. Secrets (`.env`)
  • 2. Metadata (`providers.lisp`)
• Troubleshooting

Introduction

Welcome to the OpenCortex User Manual. This guide provides the operational knowledge required to manage your sovereign Lisp Machine and its neural skills.

System Architecture

OpenCortex 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, OpenCortex stores its files in standard Linux locations:

Type	Path	Purpose
:—	:—	:—
Config	`~/.config/opencortex/`	User settings, `.env` secrets, and provider registry.
Data	`~/.local/share/opencortex/`	Tangled Lisp artifacts and the compiled engine.
State	`~/.local/state/opencortex/`	Brain snapshots, logs, and Merkle-memory.
Bin	`~/.local/bin/opencortex`	The global CLI shim.

Command Reference

`opencortex 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/opencortex/.env`.

`opencortex link <platform> <token>`

Connects OpenCortex to external communication gateways.

• Example: `opencortex link telegram <my_bot_token>`
• Performs real-time API verification before saving.

`opencortex 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.

`opencortex 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

OpenCortex uses a Hybrid Storage model for maximum security and flexibility.

1. Secrets (`.env`)

Found in `~/.config/opencortex/.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/opencortex/providers.lisp`. This stores non-sensitive configuration like model names, base URLs, and user preferences as native Lisp S-expressions.

Troubleshooting

If `opencortex 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/opencortex/.env`.