Amr Gharbeia
41de20d3f1
- Secret Exposure Gate + Privacy Filter (Bouncer) - Shell actuator safety harness (timeout, blocked patterns) - REPL-first enforcement (lisp validation gate, system-prompt-augment) - Engineering Standards lifecycle (two-track Org-first + REPL-first) - Literate Programming discipline (one function per block, reflect-back) - AGENTS.md: thin routing layer, skills are authoritative - SKILLS_DIR removed, ~/notes fallback eliminated - opencortex.sh: multi-distro (Debian+Fedora), configure, install service, backup, restore, help - infrastructure/opencortex.service (systemd user unit) - Docker: updated to debian:trixie, fixed build context - GitHub CI: lint + test workflows fixed, trigger on tags only - Gitea CI: deploy workflow paths fixed - README: one-line curl install, badges - USER_MANUAL: Deployment section (bare metal, Docker, backup) - .gitignore: skills/*.lisp and tests/*.lisp as generated artifacts - Prose/block refactor across all 35 org files - Test suite Tier 1: 43/45 pass (env-dependent failures isolated)
2.7 KiB
OpenCortex User 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 gateway link <platform> <token>`
Connects OpenCortex to external communication gateways.
- Example: `opencortex gateway link telegram <my_bot_token>`
- Example: `opencortex gateway unlink telegram` to disable
- Example: `opencortex gateway list` to see status
`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`:
- Check that your `PATH` includes `/usr/bin` and `/usr/local/bin`.
- Ensure `sbcl` is installed.
- If LLM connectivity fails, verify your API key in `~/.config/opencortex/.env`.