Amr Gharbeia
41de20d3f1
Some checks failed
Deploy (Gitea) / deploy (push) Failing after 11s
- 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)
62 lines
2.7 KiB
Org Mode
62 lines
2.7 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 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`:
|
|
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`.
|