#+TITLE: OpenCortex User Manual
#+AUTHOR: OpenCortex Contributors
#+STARTUP: content
#+FILETAGS: :docs:manual:

* Introduction
Welcome to OpenCortex v0.1.0 (The Autonomous Foundation). OpenCortex 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
OpenCortex is bootstrapped via a single shell script.

** Quick start (curl)

#+begin_src bash
curl -fsSL https://raw.githubusercontent.com/amrgharbeia/opencortex/main/opencortex.sh | bash -s configure
#+end_src

** From a clone

#+begin_src bash
git clone https://github.com/amrgharbeia/opencortex.git ~/projects/opencortex
~/projects/opencortex/opencortex.sh configure
#+end_src

Both methods 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 OpenCortex
Because of the Unified Envelope Architecture, the kernel treats all clients as interchangeable. You must first boot the background daemon:

#+begin_src bash
./opencortex.sh --boot &
#+end_src

** Terminal User Interface (TUI)
For a rich, split-pane terminal experience:
#+begin_src bash
./opencortex.sh tui
#+end_src

** Command Line Interface (CLI)
For raw, pipe-friendly interaction:
#+begin_src bash
./opencortex.sh cli
#+end_src

** Emacs Integration
OpenCortex functions as your "foveal vision" inside Emacs.
1. Ensure `org-agent.el` is loaded.
2. Run `M-x opencortex-connect`.
3. Interact via the `*opencortex-chat*` buffer.

* The Memex Structure
OpenCortex 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
./opencortex.sh configure              # interactive
./opencortex.sh configure --non-interactive  # headless
./opencortex.sh configure --with-firewall    # also open port 9105
#+end_src

After configuration, you can re-run ~configure~ any time to add providers or link gateways.

** systemd service (auto-start on boot)

#+begin_src bash
./opencortex.sh install service
#+end_src

Installs a user-level systemd unit that starts the daemon on login. Logs are available via ~journalctl --user -u opencortex.service -f~.

To remove:

#+begin_src bash
./opencortex.sh 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
./opencortex.sh backup ~/my-backup.tar.gz
#+end_src

Backs up the config, data, and memex directories.

** Restore

#+begin_src bash
./opencortex.sh restore ~/my-backup.tar.gz
#+end_src

Restores from a backup file. Run ~opencortex doctor~ afterward to verify integrity.