Engineering

Engineering pages cover how Orion is built: its architecture, its public interfaces, and proposals for changing them.

An audit or proposal is a snapshot. It recommends changes as of the day it was written, and once a change is settled, the call moves into the decisions. For what Orion accepts today, see the CLI and MCP reference.

Threads

• Architecture: how the CLI, server, app, desktop shell, MCP server, and sources fit together.
• CLI and agents: the CLI as the one implementation, its queries and batch edits, and the MCP server that wraps it.
• Data and sync: one document per canvas under a shared lock, backups, merges, undo, and the move toward operations and files.
• Interface audit: what stays, changes, or goes on each public surface before the first release.
• Performance: the 1,000-card target, the work that keeps the canvas responsive, and the perf harness that checks each pull request.

Timeline

Each date is when the pull request was opened. Pull requests still open are marked as in review.

October 5, 2026

• Rolling backups of the data file before each write, kept for a day and a month.
• A Tauri desktop shell around the app, with a native window.
• Three-way merge for saves that lose a race, instead of dropping the edit.
• Workspaces with their own data folders.
• Ingest from GitHub, Jira, and hop through each source's command.
• Animate less, after WebKit's GPU process stayed near 40% CPU while idle.

October 6, 2026

• orion focus lets agents see the group and selection open in the app.
• orion serve serves the app's data from the CLI and removes the app's own store.
• The packaged desktop app runs the server as a bundled sidecar.

October 7, 2026

• StyLua in CI checks Luau formatting.
• A debug bar shows frame timing and animation toggles.
• Spelled-out names across the codebase.

October 8, 2026

• Redraw only what changes, with per-card selectors.
• Storybook and component stories.
• One React component per module.
• An MCP server built into the CLI binary.
• Queries and batch edits in one transaction, with dry runs and revision checks.

October 9, 2026

• Refs on cards, replacing the GitHub-specific card fields.
• One card view model that every card skin renders from.
• Source adapters behind ingest and sync.
• Undo and redo for canvas edits.
• A perf harness that compares a branch against main.
• A skill for before and after screenshots on pull requests.

October 10, 2026

• CI on Linux.
• A perf comparison on each pull request.
• The desktop sidecar built by a Lute script.
• A platform matrix and CI uploads.
• The CLI packaged as a zip that Rokit and Foreman can install.
• Perf noise judged by run-to-run spread.
• Orion's own window chrome in the desktop app.
• System diagrams with components and labeled links, merged October 17.
• Conventions and pitfalls written down for agents.
• App preferences saved in the data folder.

October 11, 2026

• CI on the self-hosted runner.
• Perf runs one at a time.
• A product charter, and file-backed canvases with a SQLite index planned in it.
• Nested groups laid out deepest first.
• Source options split by kind, and new pull requests attached to the card their branch was recorded on.
• orion import adds cards for a list of refs in one step.
• orion tidy and orion check for layout.
• Scrolling always pans, and the zoom-on-scroll setting goes.
• Perf on exclusive cores, and draft pull requests skip perf.
• The desktop app keeps its server port across launches.
• Settled decisions recorded in the decisions log.

October 12, 2026

• Perf compares against the merge commit's first parent.
• Where priority and size come from recorded in the decisions log.
• Groups removed with their contents.

October 13, 2026

• Ingest refreshes pull requests, and orion sync is deprecated.
• Finished cards stamped Done once they're closed out.
• Interfaces tighten in stages before 0.1.0, recorded in the decisions log.
• Noun-then-verb CLI commands.
• A VitePress docs site with a generated CLI and MCP reference.
• Only the cards near the view draw.
• Compact cards at far zoom.
• Folded groups preview what they hold.
• Storybook published through Chromatic, and the build shown in --version.
• The desktop app installs to /Applications for every user.
• A card's timeline from the canvas log, merged October 17.
• Canvas edits as operations, part one (in review).
• MCP tools for every CLI option, apply a plan, the canvas log, and reveal (all in review).

October 14, 2026

• GitHub sync kept under GitHub's query time limit.

October 15, 2026

• Store locks reclaimed only when their writer is gone.
• App test coverage posted as a pull request comment.
• A mutation testing script for Luau modules.
• Undo tested against random edits and the store tested under concurrent writers (both in review).

October 16, 2026

• Desktop installer and app uploads only from main.
• Orion licensed under MIT.

October 17, 2026

• The README restructured, with its detail moved into the docs.
• Lute scripts fail when they error after yielding.
• Workspaces renamed to canvases in data, routes, MCP, and docs, with an automatic folder migration.
• orion_tidy and orion_check MCP tools.
• Cards closed out at once when finished in the app.
• MCP calls queued behind the canvas lock instead of failing.
• Per-frame paint work cut (in review).
• An audit of Orion's public interfaces (in review).
• A Development section on the docs site.