#+TITLE: Flight Plan: Emacs Client UX Overhaul
#+DATE: 2026-04-07
#+FILETAGS: :plan:ux:emacs:interface:psf:

* Phase A: Demand (Verify State)
- Current state: The `opencortex` Emacs client uses a single buffer for both input and output, or a clunky side-window for reasoning. The interface is rudimentary and lacks modern chat application affordances.
- User feedback indicates that responses and reasoning streams are sometimes missing or hard to read.
- Objective: Design a comprehensive, intuitive, and modern UX for the Emacs client.

* Key Requirements
1.  **Dedicated Input Area**: A text box (minibuffer or dedicated window at the bottom) for user input, distinct from the chat history.
2.  **Main History Buffer**: A primary buffer displaying the conversation history, agent outputs, and system logs.
3.  **Syntax Highlighting**: Enhanced colorization depending on the syntax (e.g., Lisp code, shell commands, Org-mode elements).
4.  **Diff Visualization**: Clear, visual representation of proposed code changes or diffs, akin to modern CLI tools (e.g., `gemini-cli` or `magit`).
5.  **Overall Appeal**: A comprehensive design that feels modern and intuitive for users accustomed to tools like Claude Code or ChatGPT interfaces.

* Phase B: Blueprint (Architectural Design)

** 1. Window Layout Management
We will abandon the single-buffer approach and adopt a dual-window layout for the chat interface:
-   **`*opencortex-chat*` (Top, 80% height)**: A read-only `special-mode` or customized `org-mode` buffer dedicated to displaying the conversation history, agent responses, and tool execution logs.
-   **`*opencortex-input*` (Bottom, 20% height)**: A dedicated `markdown-mode` or `org-mode` buffer for composing messages. Pressing `C-c C-c` here will send the contents to the daemon, clear the input buffer, and append the user's message to the main chat buffer.

** 2. The Output Formatting Engine (Syntax & Color)
To make the main chat buffer appealing, we need a robust formatting engine within `opencortex.el`:
-   **Structured Insertion**: When the daemon sends an `:insert-at-end` command, the Emacs client will parse the payload.
-   **Font-Lock Extensions**: We will define custom `font-lock` rules for the `*opencortex-chat*` buffer to highlight specific elements:
    -   *User Messages*: Distinct background or font face.
    -   *Agent Responses*: Standard Org-mode styling.
    -   *Tool Executions (Reasoning)*: Dimmed or italicized text for "Thinking..." or "Executing shell command: `ls`".
    -   *Code Blocks*: Native syntax highlighting for `#+begin_src` blocks using `org-src-fontify-natively`.

** 3. Diff Visualization Interface
To handle code modifications safely and beautifully:
-   When the agent proposes a file change, it will send a structured `:diff` or `:patch` payload rather than raw text.
-   The Emacs client will intercept this payload and present it using `diff-mode` or a custom overlay within the chat buffer, providing visual red/green highlights for removals and additions.
-   *Interactive Acceptance*: The user can press a key (e.g., `C-c C-y`) on the diff to accept and apply the patch, realizing the "Active Approval Mode" pattern in Emacs.

** 4. The Reasoning Stream Integration
-   Instead of a separate right-side window that clutters the workspace, the reasoning stream (Probabilistic Engine thoughts, tool calls) will be integrated directly into the main `*opencortex-chat*` buffer.
-   It will be presented as a collapsible Org-mode drawer (e.g., `:REASONING:`) or formatted as dimmed, transient text that provides transparency without overwhelming the primary conversation.

* Phase C: Tester (Verification Strategy)
-   Launch `M-x opencortex`.
-   Verify the dual-window layout appears correctly.
-   Type a message in the input buffer, send it, and verify it clears and appears in the main buffer.
-   Trigger a tool call and verify the reasoning stream is formatted clearly (and distinct from the final answer).
-   Trigger a file modification and verify the diff visualization is presented elegantly.

* Migration Strategy
This overhaul requires significant changes to:
1.  `projects/opencortex/src/opencortex.el` (The Emacs client).
2.  `notes/org-skill-chat.org` (To update the expected payload formats if we move beyond simple `:insert-at-end`).