Yazelix Nova Documentation

Yazelix is an ecosystem of specialized forks, plugins, and libraries designed to work together. Key components include:

• Mars: A GUI terminal used by yzx launch featuring Kitty graphics, cursor shaders, and session integration.
• Yazelix Zellij: A multiplexer fork with Kitty graphics passthrough and managed runtime appearance switching.
• Yazelix Helix: An editor fork with isolated configuration and workspace bridge hooks.
• Zellij Plugins: Includes Pane Orchestrator (manages workspace roots, panes, and focus), Popup (manages floating TUI panes), and Bar (provides status widgets and session details).
• Ratconfig: A reusable Ratatui configuration editor and TOML patching/migration library.
• Yazelix Screen: Provides terminal welcome animations and an aquarium via yzx screen.
• Yazelix Cursors: Provides shared cursor presets and validation for Ratconfig.
• Yazi Bistro: A collection of curated Yazi flavors.
• auto-layout.yazi: A Yazi plugin that adjusts column layout based on pane width.
• zjstatus: A Zellij fork providing activity-aware tab markers.

Yazelix operates through a series of formal 'Runtime Contracts' (IDs C1 through C13) that define how different components (CLI, Desktop, Terminal, Shell, Editor, and Config UI) interact. These contracts ensure stability across the ecosystem by assigning specific 'Owners' to each behavior and defining 'Checks' to validate them.

Key areas of the runtime include:

• Front-door & Desktop (C1, C8): Handles CLI entry, headless enter mode, and desktop application launching.
• Terminal & Shell Bridge (C2-C7, C10, C12): Manages appearance authority (Mars/Zellij), layout templates, Nu/Yazi layering, and Helix editor bridging.
• Popups (C9a-C9e): Manages the Kitty protocol, role-based popups, custom command popups, and Git/LazyGit integration.
• Config UI (C11a-C11d): Handles semantic schema persistence, inventory management for tools (Mars/Cursors/Starship/Yazi), and Helix row observation.
• Installation (C13): Defines the package combinations for Mars, Helix, and Yazi, including Home Manager integration.

Yazelix manages Yazi configurations by providing a structured asset tree that supports native TOML, optional Lua, and keymap sidecars.

Asset Tree Structure

Your managed configuration should reside in ~/.config/yazelix/yazi/ and follow this structure:

• yazi.toml: Main configuration (native TOML tables merge recursively).
• theme.toml: Theme settings.
• package.toml: Opaque metadata passed to Yazi as ya pkg.
• starship.toml: Complete replacement for the packaged compact Starship header config (not a merge layer). Its presence activates materialization.
• init.lua: Lua initialization.
• keymap.toml: Keymap sidecar.
• plugins/*.yazi/: Yazi plugin directories.
• flavors/*.yazi/: Yazi flavor directories.

Configuration Merging Rules

• TOML Tables: Merge recursively.
• Scalars and Arrays: User values replace packaged values.
• plugin.prepend_fetchers: Uses replace-plus-managed-Git semantics, preserving user fetchers while restoring the two sidebar Git fetchers exactly once.
• Starship: The presence of yazi/starship.toml triggers materialization, linking it into the effective config as yazelix_starship.toml.

Note: Normal ~/.config/yazi is not read by Yazelix.

Yazelix manages the dark/light mode authority via the root appearance.mode.

Mars Integration

When Mars is included, a global save or reset updates mars.appearance.preset in ~/.config/yazelix/mars/config.toml. Mars uses a directory watcher to reload these changes automatically. To prevent overrides, the runtime removes any inherited MARS_APPEARANCE environment variable before yzx launch.

Zellij Integration

Yazelix passes the root dark/light mode to managed Zellij sessions. Zellij resolves this by matching theme_dark or theme_light. Managed sessions ignore ambient terminal appearance to ensure the root mode remains authoritative. A save from within a session calls set-dark-theme or set-light-theme against that specific session.

Yazi Integration

Each managed Yazi launch reads the root mode and selects the matching native flavor (flavor.dark or flavor.light). If a light side is absent, it defaults to Yazi Bistro's Bluloco Light. If a dark side is absent, it uses Yazi's native preset. The source theme.toml is never rewritten.

Yazelix uses a grid-based motion model inspired by Helix/Vim. The Alt and Ctrl Alt layers handle focus and movement, while Alt Shift accesses specific workspace surfaces.

Focus and Movement

Workspace Surfaces (Alt Shift)

Specialized Popups and Commands

• Yazi: Alt Shift Y toggles the full Yazi popup.
• Command Menu: Alt Shift M toggles the command palette.
• Visuals: Alt Shift S opens a transient full-screen random visual.
• Session Control: Ctrl q quits the Yazelix session.
• Pane Control: Alt m opens a new pane; Alt Shift F toggles fullscreen for the focused pane.
• Editor/Yazi Toggle: Ctrl y toggles focus between the editor and Yazi sidebar.

Yazelix uses a root appearance authority (Contract C2) to manage visual settings across Mars, Zellij, and Yazi.

• Root Mode: Saving the root appearance.mode automatically switches the Ratconfig palette and projects the setting into the writable Mars configuration via mars.appearance.preset.
• Mars Live Reload: Mars reloads the following settings live when changed via the root config:
  • opacity
  • font size
  • line height
  • scrollbar
  • bell behavior
• Window Dimensions: width and height settings apply to newly created windows.
• Fallback Behavior: If the Mars configuration is symlinked or read-only, Yazelix does not modify the file; instead, it passes the root mode to the launch via the MARS_APPEARANCE environment variable.
• Yazi Integration: Managed Yazi instances read the root mode, and the materializer projects the selected native flavor into a generated theme.toml without altering user or Home Manager source files.

Yazelix uses a layered configuration model where packaged defaults are applied first, followed by sparse user overrides. This allows you to customize specific settings without maintaining a full copy of the tool's default configuration.

Configuration Directory Structure

By default, user overrides are placed in ~/.config/yazelix/. You can override this root directory using the YAZELIX_CONFIG_HOME environment variable.

Default Directory Layout:

• config.toml: Sparse semantic overrides for the root.
• cursors.toml: Shared cursor selection and effects.
• mars/config.toml: Sparse Mars overrides.
• zellij/config.kdl: Guarded scalar sidecar.
• zellij/plugins.kdl: Extra plugins only.
• starship.toml: Sparse prompt overrides.
• nu/{env,config}.nu: Nu configuration (applied after packaged Nu).
• helix/*: Helix configuration (created on demand).
• yazi/{yazi.toml,theme.toml,package.toml,starship.toml,init.lua,keymap.toml,plugins/,flavors/}: Yazi specific files.

Layering Logic by Surface

Note: Host configurations located at ~/.config/{helix,yazi,starship} are not loaded by default.