idossha · idossha · Sep 13, 2026 · Sep 13, 2026 · Sep 13, 2026 · Sep 13, 2026
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,19 @@
+# Keep editor saves consistent with the existing Lua sources.
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+# Preserve intentional Markdown hard line breaks; do not auto-reflow prose.
+trim_trailing_whitespace = false
+max_line_length = 110
+
+[*.m]
+# Match the MATLAB fixtures so editor saves do not rewrite indentation.
+indent_size = 4
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -0,0 +1,24 @@
+# One dependency-free suite: no MATLAB license, GUI, or heavyweight build job.
+name: Tests
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  headless:
+    runs-on: ubuntu-24.04
+    # Local suite takes about a second; cap package installation/network stalls.
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Install Neovim
+        run: sudo apt-get update && sudo apt-get install -y neovim
+      - name: Run headless regression suite
+        env:
+          NVIM_LOG_FILE: ${{ runner.temp }}/nvim.log
+        run: nvim --headless -u NONE -l tests/run.lua
+      - name: Check patch whitespace
+        run: git diff --check HEAD^
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,5 @@
 referecnce/
 .DS_Store
+
+# Neovim diagnostics are local runtime output.
+.nvimlog
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,21 @@
+# Changelog
+
+## [Unreleased]
+
+### Fixed
+
+- **Keep the MATLAB editor from opening at breakpoints** — newly launched sessions
+  apply a temporary editor setting while retaining figure support. Set
+  `suppress_editor_on_breakpoint = false` to keep MATLAB's own behavior. Saved
+  preferences are unchanged; releases without the setting warn and require the
+  manual Editor/Debugger preference.
+- **Execute the selected cell accurately** — a section marker belongs to its own
+  cell, the first unmarked line is included, and execution stops before the next cell.
+- **Keep terminal commands intact** — MATLAB executable paths support spaces and
+  quotes, existing tmux panes are recognized by exact ID, and code is sent literally
+  without adding escapes to MATLAB strings.
+
+### Added
+
+- **Contributor and testing guidance** — focused manuals and a dependency-free
+  headless regression suite run by CI. Live MATLAB checks remain separately opt-in.
diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md
@@ -0,0 +1,18 @@
+This guide covers contributions; [docs/TESTING.md](docs/TESTING.md) owns test commands
+and [docs/RELEASING.md](docs/RELEASING.md) owns publication checks.
+
+# Contributing
+
+Clone the repository and add the checkout to Neovim's runtime path, then call
+`require('matlab').setup()` in a disposable development configuration. Normal use
+requires MATLAB and tmux; the automated Lua suite does not.
+
+Keep changes focused and follow the existing Lua modules and two-space indentation.
+Preserve user configuration and avoid unrelated formatting changes. Add a regression
+case for a behavior fix, update its authoritative documentation, and describe
+user-visible changes in [CHANGELOG.md](CHANGELOG.md).
+
+Before opening a pull request, run the checks in the testing manual and `git diff --check`.
+Describe the defect, resulting behavior, commands run, and any unverified MATLAB or
+platform behavior. Include reproduction steps and versions for bug reports. Never
+include license files, credentials, private workspace data, or personal startup scripts.
diff --git a/MATLAB_debug.md b/MATLAB_debug.md
diff --git a/README.md b/README.md
@@ -1,6 +1,9 @@
 **matlab.nvim** is a modern Neovim plugin for MATLAB integration with tmux.
 
-**Contributions are welcome!**
+**Contributions are welcome!** See [CONTRIBUTIONS.md](CONTRIBUTIONS.md).
+
+Project docs: [architecture](docs/ARCHITECTURE.md), [decisions](docs/DECISIONS.md),
+[testing](docs/TESTING.md), [roadmap](docs/ROADMAP.md), and [release checks](docs/RELEASING.md).
 
 ![Demo of Neovim MATLAB Plugin](docs/example.gif)
 
@@ -12,13 +15,13 @@
 - Access MATLAB documentation for functions
 - Save and load MATLAB workspace files
 - Native MATLAB debugger integration
-- Visual breakpoint inicators
-- tep-through execution (over, into, out)
-- Debug siebar with variables, call stack, breakpoints
+- Visual breakpoint indicators
+- Step-through execution (over, into, out)
+- Debug sidebar with variables, call stack, breakpoints
 
 ## Requirements
 
-- **Neovim**: 0.7.0 or later
+- **Neovim**: 0.9.0 or later
 - **tmux**: Must be installed and running
 - **MATLAB**: Any recent version
 
@@ -55,13 +58,14 @@ require('matlab').setup({
   executable = 'matlab',
 
   -- Tmux pane configuration
-  panel_size = 50,
+  panel_size = 50, -- Example override; see lua/matlab/config.lua for defaults
   panel_size_type = 'percentage',
   tmux_pane_direction = 'right',
   tmux_pane_focus = true,
 
   -- Behavior
   auto_start = true,
+  suppress_editor_on_breakpoint = true,
   default_mappings = true,
   minimal_notifications = true,
 
@@ -120,53 +124,8 @@ plot(x, y);
 
 ## Debugging
 
-### Quick Start
-
-1. Set breakpoints: `<Leader>mdb`
-2. Start debugging: `<Leader>mds` (or `F5`)
-3. Step through code:
-   - `<Leader>mdc` or `F5` - Continue to next breakpoint
-   - `<Leader>mdn` or `F10` - Step over
-   - `<Leader>mdi` or `F11` - Step into
-   - `<Leader>mdo` or `F12` - Step out
-4. Stop debugging: `<Leader>mdq` (or `Shift+F5`)
-
-### Debug Commands
-
-| Key | Command | Description |
-|-----|---------|-------------|
-| `<Leader>mds` | `:MatlabDebugStart` | Start debugging |
-| `<Leader>mdq` | `:MatlabDebugStop` | Stop debugging |
-| `<Leader>mdc` | `:MatlabDebugContinue` | Continue execution |
-| `<Leader>mdn` | `:MatlabDebugStepOver` | Step over line |
-| `<Leader>mdi` | `:MatlabDebugStepInto` | Step into function |
-| `<Leader>mdo` | `:MatlabDebugStepOut` | Step out of function |
-| `<Leader>mdb` | `:MatlabDebugToggleBreakpoint` | Toggle breakpoint |
-| `<Leader>mdB` | `:MatlabDebugClearBreakpoints` | Clear all breakpoints |
-| `<Leader>mde` | `:MatlabDebugEval` | Evaluate expression |
-| `<Leader>mdu` | `:MatlabDebugUI` | Toggle debug sidebar |
-
-### Visual Indicators
-
-- **Breakpoints**: Red circle (●) with full-line highlighting
-- **Current line**: Blue arrow (▶) with full-line highlighting
-
-### Debug Sidebar
-
-Toggle with `<Leader>mdu` or `:MatlabDebugUI`. Shows call stack, breakpoints, and workspace variables.
-
-| Key | Action |
-|-----|--------|
-| `q` | Close sidebar |
-| `r` | Refresh display |
-| `w` | Update workspace from MATLAB |
-| `<CR>` | Jump to location under cursor |
-
-### Debug Tips
-
-- Files auto-save when starting debug session
-- Breakpoints persist within Neovim session
-- Use MATLAB commands directly in tmux pane (`whos`, `dbstack`, etc.)
+See [Debugging](docs/DEBUGGING.md) for the breakpoint workflow, editor suppression
+while retaining plots, commands, sidebar controls, and limitations.
 
 ## Troubleshooting
 
@@ -193,10 +152,12 @@ require('matlab').setup({
 ```
 
 Check configuration: `:MatlabShowConfig`
-View logs: `~/.cache/nvim/matlab_nvim.log`  
+View logs: `~/.cache/nvim/matlab_nvim.log`
 
 Inspired by [MortenStabenau/matlab-vim](https://github.com/MortenStabenau/matlab-vim), rewritten in Lua for Neovim.
 
 ## License
 
+Inspired by [MortenStabenau/matlab-vim](https://github.com/MortenStabenau/matlab-vim), rewritten in Lua for Neovim.
+
 MIT
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -0,0 +1,62 @@
+This is the architecture contract; [README.md](../README.md) covers setup. Deviations require
+updating this file and appending to [DECISIONS.md](DECISIONS.md) in the same change.
+Section numbers are stable and must not be renumbered.
+
+# Architecture contract
+
+## 1. MATLAB startup
+
+Lua builds the MATLAB command and tmux hosts its interactive terminal, preserving
+the existing architecture instead of adding a separate debugger transport.
+
+**Editor suppression is session-local.** `suppress_editor_on_breakpoint` defaults
+to true and applies `OpenFileAtBreakpoint.TemporaryValue = false` before startup
+code. False leaves MATLAB's preference untouched. Failure warns and continues,
+so older MATLAB releases remain usable. No persistent preference API is used.
+
+**Figure support remains available.** Keep `-nodesktop -nosplash`; do not add
+`-nodisplay`, `-nojvm`, or `-noFigureWindows` to suppress the editor.
+
+## 2. Verification and scope
+
+The dependency-free headless suite checks Lua behavior with controlled external
+operations. [TESTING.md](TESTING.md) owns commands, fixtures, and acceptance checks.
+CI runs the same suite; it cannot certify a licensed MATLAB desktop session.
+Automatic navigation redesign and reconfiguring existing MATLAB panes are outside
+this revision. No debugger framework or test-library dependency is introduced.
+
+## 3. Component boundaries
+
+| Component | Responsibility |
+| --- | --- |
+| `plugin/matlab.vim`, `ftplugin/matlab.lua` | MATLAB filetype detection and buffer-local mappings. Setup remains an explicit user call. |
+| `lua/matlab/init.lua`, `config.lua` | Public commands, lifecycle autocommands, and merged configuration. |
+| `lua/matlab/tmux.lua` | Executable discovery, terminal-pane lifecycle, startup arguments, and command transport. |
+| `lua/matlab/commands.lua`, `cells.lua`, `workspace.lua` | Script/cell execution, cell folds, documentation, and workspace commands. |
+| `lua/matlab/debug.lua` | Session state, breakpoint signs, native MATLAB debug commands, and location parsing. |
+| `lua/matlab/debug_ui.lua` | Scratch-buffer sidebar, terminal-derived call stack, and temporary-file workspace exchange. |
+| `lua/matlab/utils.lua` | Notifications and log output. |
+
+**MATLAB remains the execution engine.** Lua sends native MATLAB statements through
+tmux; no MATLAB Engine or Debug Adapter Protocol connection is maintained. Debugger
+location updates inspect terminal output and match open buffer basenames. This makes
+terminal formatting and duplicate filenames integration limits, not protocol guarantees.
+
+**Configuration has one source of truth.** Defaults live in
+[`config.lua`](../lua/matlab/config.lua). Setup deep-merges user options so nested
+mapping overrides retain unrelated defaults. Examples in the README are configuration
+examples, not a second defaults declaration.
+
+## 4. Documentation and change boundaries
+
+[DEBUGGING.md](DEBUGGING.md) owns the interactive debugger manual,
+[TESTING.md](TESTING.md) owns verification, [RELEASING.md](RELEASING.md) owns publication,
+and [ROADMAP.md](ROADMAP.md) records outstanding work. Historical reasons belong in
+[DECISIONS.md](DECISIONS.md), not duplicate user guides.
+
+Public startup behavior is defined by `lua/matlab/config.lua` and
+`lua/matlab/tmux.lua`; changes to the editor setting, opt-out, or launch flags must
+update this contract and its regression coverage together. An absent
+`suppress_editor_on_breakpoint` option uses the enabled default described in §1.
+Keep shell argument escaping separate from MATLAB string escaping to avoid commands
+changing meaning when paths contain spaces or quotes.