Amr Gharbeia
a717ab1d3a
Some checks failed
Deploy-Agent-V15-Stdin / JOB-V15-STDIN (push) Failing after 2s
61 lines
2.6 KiB
Org Mode
61 lines
2.6 KiB
Org Mode
#+TITLE: OpenCortex User Manual
|
|
#+AUTHOR: Agent
|
|
#+STARTUP: content
|
|
#+FILETAGS: :docs:manual:
|
|
|
|
* 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`.
|