omarchy-ui 0.0.7-x86_64-linux → 0.0.9-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d389e6d9a8382cb8feec3a900ce2b4ee14001d214a069e96be8e7567e549f39e
-  data.tar.gz: 77d33296ea0cc16f08a93bb94a17607a3b50d19e036f2649304a89fcc4b9f455
+  metadata.gz: 82c12f3f51c0d9242be7386a4994c4f3fe8b333d04489e4055b671054cb2f0e2
+  data.tar.gz: e693d5b68a5ad055b40fbb910b4bb6ef41b6de7405027396305f256ad744875d
 SHA512:
-  metadata.gz: 2be91201712539398abbf26b03cc3298947d2ff040da32e7171009ef70fdb4127adb7ab5992088176a5f28d5f901cdf4bcdfec68e65c13123bcb3fc61c2206f7
-  data.tar.gz: 89953562fbc3a943290234a297e5cd0f6ecf98b9f7b17a9188a5072716cf42e39e7281c724b97d2b4926df7aabd973485dbbc012ad3285447aaf36de9a7f5514
+  metadata.gz: 807cb5e30c33130681351065bc7fce902a7c4c125f1c6b47e8827db0ec6b49695745ab60d61da9475153f8abf1422940df280154af797ede39ef218a9097c449
+  data.tar.gz: c2f3532f53a5725e7c6e7cd9de667ebbb2dddd086204af8172f8b262c010e4fef2470b73716a7496c9859d396f43b22814e03926949944e2e1c080e1e64ca5a2

data/README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-  <img alt="Omarchy UI 0.0.7" src="https://img.shields.io/badge/Omarchy_UI-0.0.7-b7ff5a?style=flat-square&labelColor=111711">
+  <img alt="Omarchy UI 0.0.9" src="https://img.shields.io/badge/Omarchy_UI-0.0.9-b7ff5a?style=flat-square&labelColor=111711">
   <img alt="Ruby 3.1 or newer" src="https://img.shields.io/badge/Ruby-3.1%2B-cc342d?style=flat-square&logo=ruby&logoColor=white">
   <img alt="Zui 0.0.10" src="https://img.shields.io/badge/Zui-0.0.10-7ee14b?style=flat-square&labelColor=111711">
   <img alt="241 components" src="https://img.shields.io/badge/components-241-75d943?style=flat-square&labelColor=111711">
@@ -46,27 +46,29 @@ and the Omarchy adapter.
 </table>
 
 > [!IMPORTANT]
-> Omarchy UI currently targets **Omarchy on x86-64 Linux** and is marked experimental. The reusable
-> Zui application module can also run with Zui's native host on Linux, macOS, and Windows.
+> Omarchy UI currently targets **Omarchy on x86-64 Linux**. Reusable Zui application modules can
+> also run through Zui's native host on Linux, macOS, and Windows.
 
 ## Choose a workflow
 
 | Build | Use it for | Primary surface | Delivery |
 | --- | --- | --- | --- |
-| Omarchy application | Full desktop tools and standalone interfaces | `app :main` | `omarchy_ui run` or `omarchy_ui bundle` |
-| Omarchy plugin | Bar widgets, panels, and shell-integrated tools | `bar_widget` and `panel` | `omarchy_ui validate` and `omarchy_ui push` |
+| Omarchy application | Full desktop tools and standalone interfaces | `app :main` | `omarchy_ui new NAME`, then `run` or `bundle` |
+| Omarchy plugin | Bar widgets, panels, and shell-integrated tools | `bar_widget` and `panel` | `omarchy_ui new NAME --plugin`, then `push` or `bundle` |
 | Portable Zui application | The same application UI outside Omarchy | `app :main` | The platform-neutral [Zui toolchain](https://github.com/AdamMusa/zui#developer-workflow) |
 
 ## Requirements
 
-- Omarchy on x86-64 Linux;
-- Ruby 3.1 or newer while installing the gem and developing applications;
-- optional Qt modules for components that use features such as Quick 3D or Multimedia.
+- Omarchy on x86-64 Linux
+- Ruby 3.1 or newer for installation and development
+- Qt 6 development tools, CMake, Ninja, and a C++ compiler for `bundle`, `validate`, and `push`
+- Optional Qt modules for components that use features such as Quick 3D or Multimedia
 
-The finished Omarchy bundle includes the Omarchy adapter, mruby executable, and a Zui-generated QML
-runtime tree-shaken to the components referenced by that application. The destination does not need
-Ruby or framework gems. A component fails with an explicit error when its required Qt module or
-resource is unavailable; Omarchy UI never substitutes a different component.
+Omarchy UI turns Ruby and assets into an Omarchy-compatible application or plugin. It owns the
+metadata, entry points, adapter, validation, tree-shaken and AOT-compiled Zui QML, and embedded mruby
+runtime. Omarchy UI invokes the build tools; projects do not contain CMake files or distribution
+scripts. The finished package does not require Ruby or framework gems. Components report a clear
+error when a required Qt module or resource is unavailable.
 
 ## Quick start
 
@@ -78,20 +80,36 @@ gem install omarchy-ui
 
 The gem installs the compatible Zui version as a dependency.
 
-### 2. Generate an application
+### 2. Generate a project
 
 ```bash
 omarchy_ui new Counter
 cd counter
 ```
 
+For an integrated Omarchy plugin instead:
+
+```bash
+omarchy_ui new "System Status" --plugin
+cd system-status
+```
+
+Both commands create a ready-to-run Ruby project. Developers write the interface and behavior;
+Omarchy UI generates the Omarchy package without application-owned QML, shell entry points, or
+handwritten manifests.
+
+Each project includes a Ruby-native `config.rb` with its type, identity, version, entry point, and
+plugin metadata. `bundle`, `validate`, and `push` use this single configuration.
+
 The generator creates a small, host-independent project:
 
 ```text
 counter/
+├── LICENSE
 ├── app.rb                  # reusable Zui application
 ├── components/
 │   └── welcome.rb          # application-owned Ruby UI module
+├── config.rb               # project identity and build settings
 ├── main.rb                 # Omarchy launcher
 └── README.md
 ```
@@ -102,8 +120,8 @@ counter/
 omarchy_ui run main.rb
 ```
 
-`run` bundles the project's Ruby entry point, asks Zui to tree-shake the QML runtime, prepares the Omarchy host,
-then launches it through Quickshell.
+`run` bundles the project's Ruby entry point, asks Zui to tree-shake the QML runtime, prepares the
+Omarchy host, and launches it through Quickshell.
 
 ## Application model
 
@@ -228,48 +246,17 @@ QML is not required.
 
 ## Omarchy plugins
 
-A Ruby-powered plugin is an ordinary Omarchy plugin repository with `manifest.json` and `main.rb`
-at its root. Omarchy UI adds the generated service, panel, bar-widget, framework, and runtime files
-while staging the plugin; do not commit generated copies to the application source.
+Generate a plugin project with one command:
 
-```text
-system-status/
-├── manifest.json
-├── main.rb
-└── assets/
+```bash
+omarchy_ui new "System Status" --plugin
+cd system-status
 ```
 
-### Manifest
-
-This complete manifest declares the adapter surfaces used by the Ruby definition below:
-
-```json
-{
-  "schemaVersion": 1,
-  "id": "example.system-status",
-  "name": "System Status",
-  "version": "0.1.0",
-  "author": "Example Author",
-  "license": "MIT",
-  "description": "A Ruby-powered status panel for Omarchy.",
-  "kinds": ["service", "bar-widget", "panel"],
-  "keepLoaded": true,
-  "entryPoints": {
-    "service": "Service.qml",
-    "barWidget": "BarWidget.qml",
-    "panel": "Panel.qml"
-  },
-  "barWidget": {
-    "displayName": "System Status",
-    "description": "Open the current system status.",
-    "category": "System",
-    "allowMultiple": false,
-    "defaultSection": "right"
-  }
-}
-```
+Developers work in Ruby and add their own assets. Omarchy UI supplies the plugin metadata, shell
+surfaces, native host, tree-shaken Zui package, validation, and installation lifecycle.
 
-### Ruby entry point
+The Ruby entry point uses ordinary Zui components:
 
 ```ruby
 # main.rb
@@ -294,36 +281,26 @@ OmarchyUI.plugin do
 end
 ```
 
-`bar_widget` declares the shell-owned bar surface. `panel :status` declares the panel opened by
-`open_panel :status`. The manifest must declare the corresponding entry points.
+`bar_widget` and `panel :status` are the developer-facing surface declarations. Omarchy UI maps them
+to the required shell entry points when it builds or stages the plugin.
 
 ### Validate and install
 
 ```bash
-omarchy_ui validate path/to/system-status
-omarchy_ui push path/to/system-status
+omarchy_ui validate
+omarchy_ui push
 ```
 
-`validate` checks a fully staged copy, including the bundled Ruby entry point and generated adapter.
-`push` then:
-
-1. stages and validates the complete plugin;
-2. backs up an existing installation when present;
-3. installs it atomically under `~/.config/omarchy/plugins/<plugin-id>`;
-4. enables the plugin; and
-5. restarts the Omarchy shell.
+`validate` generates and checks the plugin without modifying the Ruby project. `push` builds,
+validates, installs, enables, and reloads it for development.
 
 During development, suppress either lifecycle action when needed:
 
 ```bash
-omarchy_ui push path/to/system-status --no-enable
-omarchy_ui push path/to/system-status --no-restart
+omarchy_ui push --no-enable
+omarchy_ui push --no-restart
 ```
 
-> [!WARNING]
-> Omarchy plugins execute as unsandboxed user code inside the shell environment. Review the Ruby,
-> assets, manifest, generated package, and provenance before installing a third-party plugin.
-
 ## Command-line reference
 
 ```text
@@ -332,10 +309,11 @@ omarchy_ui <command> [arguments]
 
 | Command | Arguments | Result |
 | --- | --- | --- |
-| `omarchy_ui new NAME` | One application name | Creates a new application directory using a URL-safe form of the name |
+| `omarchy_ui new NAME` | One project name | Creates an Omarchy application project |
+| `omarchy_ui new NAME --plugin` | One project name and `--plugin` | Creates an Omarchy plugin project |
 | `omarchy_ui run FILE` | One Ruby entry point | Runs an application through the Omarchy/Quickshell host |
-| `omarchy_ui bundle [DIRECTORY]` | Zero or one project directory | Creates `dist/<project-name>` with the application, Omarchy adapter, runtime, and tree-shaken Zui QML |
-| `omarchy_ui validate [DIRECTORY]` | Zero or one plugin directory | Stages the complete plugin and delegates validation to `omarchy plugin validate` |
+| `omarchy_ui bundle [DIRECTORY]` | Zero or one project directory | Generates the distributable package and prints its location |
+| `omarchy_ui validate [DIRECTORY]` | Zero or one plugin directory | Stages the plugin and delegates validation to `omarchy plugin validate` |
 | `omarchy_ui push [DIRECTORY]` | Optional `--no-enable` and `--no-restart` | Atomically installs and activates a validated plugin |
 | `omarchy_ui version` | None | Prints the installed Omarchy UI version |
 
@@ -344,38 +322,29 @@ not forward arbitrary Ruby arguments.
 
 ## Packaging
 
-Create a distributable application from the project root:
+Create the distributable package from the project root:
 
 ```bash
 omarchy_ui bundle
-./dist/my-application/run
 ```
 
-The bundle contains:
+Omarchy UI assembles the Ruby source and assets, Omarchy entry points, native host, checksummed
+runtime, and only the Zui components used by the project. It then AOT-compiles the generated QML into
+a content-addressed Qt module and discards the generated component, control, theme, and font source
+tree. Applications receive a direct launcher; plugins must pass Omarchy validation before the
+command succeeds. Omarchy UI pins Zui 0.0.10 so the compiled UI matches the Zui core embedded in the
+deterministic mruby runtime.
 
-```text
-dist/my-application/
-├── main.rb                     # bundled application source
-├── assets/                     # application-owned resources
-├── App.qml                     # Omarchy host entry point
-├── Service.qml                 # process and surface bridge
-├── Panel.qml                   # shell panel adapter
-├── BarWidget.qml               # shell bar adapter
-├── ControlNode.qml             # generated Zui protocol renderer
-├── Components/Builtins/        # only component adapters selected by Zui
-├── Controls/ Theme/ Fonts/     # generated renderer dependencies
-├── zui-tree-shake.json         # auditable selected-component report
-├── Commons@ Ui@                # links to Omarchy's shell modules
-├── omarchy-ui-runtime          # embedded mruby executable
-├── omarchy-ui-runtime.sha256
-├── RUNTIME_PROVENANCE.md
-└── run
-```
+Current Omarchy manifests resolve entry points by filename, so a package retains four minimal loader
+files: `App.qml`, `Service.qml`, `Panel.qml`, and `BarWidget.qml`. They contain only an import and a
+compiled type instance; the application interface is stored in native `.so` artifacts. The package
+also includes `omarchy-ui-qml-bundle.json` with the module URI and exact Qt version, plus
+`omarchy-ui-qml-bundle.sha256` for artifact verification. `QML_PROVENANCE.md` explains the native
+artifacts for package reviewers. Compiled packages should be built against the Qt version shipped by
+their target Omarchy release.
 
-Plugin bundles use the same runtime package and are validated against their manifest before the
-bundle command succeeds. Generated packages exclude `.git`, previous `dist` output, and stale
-adapter/runtime files before regenerating the minimal QML package. Omarchy UI pins Zui 0.0.10 so the
-tree-shaken QML exactly matches the Zui core embedded in the deterministic mruby runtime.
+The source `config.rb` is the build configuration. Omarchy UI generates plugin manifests from it;
+developers never maintain a separate manifest.
 
 ## Component catalog
 
@@ -442,10 +411,12 @@ Zui DSL · state · events · bindings · scheduler
           │
           │ versioned JSON render, patch, event, and effect protocol
           ▼
-Omarchy Service.qml process bridge ───── embedded mruby runtime
+Omarchy process bridge ───────────────── embedded mruby runtime
           │
           ▼
-Zui ControlNode + native component catalog
+Tree-shaken Zui host + component catalog
+          │
+          │ bundle: Qt AOT module + four loader shims
           │
           ▼
 App window · Omarchy panel · Omarchy bar widget
@@ -463,8 +434,9 @@ The dependency direction is deliberate:
 - **Applications own** Ruby source, assets, state, behavior, and reusable UI modules.
 
 At bundle, validation, and push time, Omarchy UI asks Zui to analyze the bundled Ruby syntax and
-generate only the required component adapters plus their renderer dependencies. The four Omarchy
-host files then replace Zui's generic desktop host. Read the full [QML ownership and adapter
+generate only the required component adapters plus their renderer dependencies. Omarchy UI overlays
+its host, compiles the complete generated QML graph into a content-addressed Qt module, and emits the
+minimal loader files required by Omarchy. Read the full [QML ownership and adapter
 boundary](docs/qml-support.md).
 
 ## Runtime integrity
@@ -504,11 +476,11 @@ bodies are never recorded. Per-plugin logs rotate at 128 KiB under
 | `Ruby file not found` | Pass an existing entry point to `omarchy_ui run`, normally `main.rb` |
 | `Omarchy QML module not found` | Confirm the Omarchy shell installation provides `/usr/share/omarchy/shell/Commons` and `Ui` |
 | A component reports a missing module | Install or enable the Qt module required by that declared component |
-| Plugin validation fails | Run `omarchy_ui validate` and correct the manifest or staged project error before pushing |
+| Plugin validation fails | Run `omarchy_ui validate` and correct the reported Ruby, asset, or generated-metadata error before pushing |
 | A pushed plugin is installed but inactive | Run `omarchy plugin enable <id>` and `omarchy restart shell` after resolving the reported shell error |
-| The bundle destination already exists | Review or move the existing `dist/<project-name>` directory before bundling again |
+| The bundle destination already exists | Review or move the previously generated package before bundling again |
 
-Omarchy UI reports unsupported properties, components, events, paths, manifests, and runtime
+Omarchy UI reports unsupported properties, components, events, paths, generated metadata, and runtime
 resources directly. Preserve the original error when opening an issue.
 
 ## Development

data/lib/omarchy_ui/cli.rb

@@ -27,7 +27,7 @@ module OmarchyUI
       when "validate" then validate(arguments)
       when "version", "--version", "-v" then @out.puts(OmarchyUI::VERSION); 0
       else
-        @err.puts("Usage: omarchy_ui <new NAME|run FILE|bundle [DIRECTORY]|push [DIRECTORY]|validate [DIRECTORY]|version>")
+        @err.puts("Usage: omarchy_ui <new NAME [--plugin]|run FILE|bundle [DIRECTORY]|push [DIRECTORY]|validate [DIRECTORY]|version>")
         command.nil? ? 0 : 64
       end
     rescue Interrupt
@@ -67,14 +67,30 @@ module OmarchyUI
     end
 
     def new_project(arguments)
+      plugin = !arguments.delete("--plugin").nil?
       name = arguments.shift || raise(ArgumentError, "new requires a project name")
-      raise ArgumentError, "new accepts only an application name" unless arguments.empty?
+      raise ArgumentError, "new accepts a name and optional --plugin" unless arguments.empty?
       destination = File.expand_path(slug(name))
-      Generator.new(path: destination, name: name).create
-      @out.puts("Created standalone Omarchy UI app in #{destination}")
+      kind = plugin ? :plugin : :application
+      Generator.new(path: destination, name: name, kind:, author: default_author).create
+      label = plugin ? "Omarchy-compliant plugin" : "self-contained Omarchy application"
+      @out.puts("Created #{label} in #{destination}")
       0
     end
 
+    def default_author
+      configured = ENV["OMARCHY_UI_AUTHOR"].to_s.strip
+      return configured unless configured.empty?
+
+      output, _error, status = Open3.capture3("git", "config", "--get", "user.name")
+      git_author = output.to_s.strip
+      return git_author if status.success? && !git_author.empty?
+
+      ENV["USER"].to_s.strip.then { |user| user.empty? ? "Omarchy UI Developer" : user }
+    rescue SystemCallError
+      "Omarchy UI Developer"
+    end
+
     def slug(value)
       result = value.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|\-\z/, "")
       raise ArgumentError, "name must contain letters or numbers" if result.empty?
@@ -83,6 +99,10 @@ module OmarchyUI
 
     def validate(arguments)
       source = File.expand_path(arguments.shift || Dir.pwd)
+      raise ArgumentError, "validate accepts one directory" unless arguments.empty?
+      config = ProjectConfig.load(source)
+      raise ArgumentError, "validate requires a plugin project" if config&.application?
+
       with_staged_project(source) do |staging|
         system("omarchy", "plugin", "validate", staging) ? 0 : 1
       end
@@ -91,15 +111,22 @@ module OmarchyUI
     def bundle_project(arguments)
       source = File.expand_path(arguments.shift || Dir.pwd)
       raise ArgumentError, "bundle accepts one directory" unless arguments.empty?
-      raise ArgumentError, "main.rb not found: #{source}" unless File.file?(File.join(source, "main.rb"))
-      destination = File.join(source, "dist", File.basename(source))
+      config = ProjectConfig.load(source)
+      entrypoint = config&.entrypoint || "main.rb"
+      raise ArgumentError, "#{entrypoint} not found: #{source}" unless File.file?(File.join(source, entrypoint))
+      precompiled = config.nil? && compiled_package?(source)
+      destination = File.join(source, "dist", config&.slug || File.basename(source))
       raise ArgumentError, "bundle destination already exists: #{destination}" if File.exist?(destination)
       FileUtils.mkdir_p(destination)
-      entries = application_entries(source)
+      entries = precompiled ? package_entries(source) : application_entries(source, config:)
       FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, destination)
-      bundle_ruby_entrypoint(source, destination)
-      Runtime.install_package(destination)
-      if File.file?(File.join(destination, "manifest.json"))
+      unless precompiled
+        config.write_manifest(destination) if config&.plugin?
+        bundle_ruby_entrypoint(source, destination, entrypoint:)
+        Runtime.install_package(destination, compiled: !config.nil?)
+      end
+      plugin = config ? config.plugin? : File.file?(File.join(destination, "manifest.json"))
+      if plugin
         raise ArgumentError, "bundled plugin validation failed" unless system("omarchy", "plugin", "validate", destination)
         @out.puts("Bundled plugin in #{destination}")
         return 0
@@ -115,7 +142,9 @@ module OmarchyUI
         app_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
         export OMARCHY_UI_RUNTIME="$app_dir/omarchy-ui-runtime"
         export OMARCHY_UI_PROJECT_DIR="$app_dir"
-        export OMARCHY_UI_RUBY_PROGRAM="$app_dir/main.rb"
+        export OMARCHY_UI_RUBY_PROGRAM="$app_dir/#{entrypoint}"
+        export QML2_IMPORT_PATH="$app_dir${QML2_IMPORT_PATH:+:$QML2_IMPORT_PATH}"
+        export QML_IMPORT_PATH="$app_dir${QML_IMPORT_PATH:+:$QML_IMPORT_PATH}"
         export QT_LOGGING_RULES="${QT_LOGGING_RULES:+$QT_LOGGING_RULES;}qt.qpa.services.warning=false"
         exec quickshell --path "$app_dir/App.qml"
       SH
@@ -131,17 +160,33 @@ module OmarchyUI
       [ENV["QT_LOGGING_RULES"], "qt.qpa.services.warning=false"].compact.reject(&:empty?).join(";")
     end
 
-    def application_entries(source)
+    def application_entries(source, config: ProjectConfig.load(source))
       generated = Runtime::GENERATED_ENTRIES + Runtime::AUDIT_FILES + %w[run Commons Ui]
+      generated.concat([ProjectConfig::FILE_NAME, "manifest.json"]) if config
       Dir.children(source).reject { |entry| %w[.git dist].include?(entry) || generated.include?(entry) }
     end
 
+    def package_entries(source)
+      Dir.children(source).reject { |entry| %w[.git dist].include?(entry) }
+    end
+
+    def compiled_package?(source)
+      report = File.join(source, QmlCompiler::REPORT)
+      return false unless File.file?(report)
+
+      QmlCompiler.verify!(source)
+      true
+    end
+
     def push(arguments)
       enable = !arguments.delete("--no-enable")
       restart = !arguments.delete("--no-restart")
       source = File.expand_path(arguments.shift || Dir.pwd)
+      raise ArgumentError, "push accepts one directory" unless arguments.empty?
+      config = ProjectConfig.load(source)
+      raise ArgumentError, "push requires a plugin project" if config&.application?
       manifest_path = File.join(source, "manifest.json")
-      manifest = JSON.parse(File.read(manifest_path))
+      manifest = config ? config.manifest : JSON.parse(File.read(manifest_path))
       plugin_id = manifest.fetch("id")
       raise ArgumentError, "invalid plugin id" unless VALID_ID.match?(plugin_id)
       plugin_root = File.expand_path("~/.config/omarchy/plugins")
@@ -184,12 +229,18 @@ module OmarchyUI
 
     def stage_project(source, parent: nil, prefix: ".omarchy-ui-staging-")
       raise ArgumentError, "project directory not found: #{source}" unless File.directory?(source)
+      config = ProjectConfig.load(source)
+      precompiled = config.nil? && compiled_package?(source)
       staging = parent ? Dir.mktmpdir(prefix, parent) : Dir.mktmpdir(prefix)
-      entries = application_entries(source)
+      entries = precompiled ? package_entries(source) : application_entries(source, config:)
       FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, staging) unless entries.empty?
-      if File.file?(File.join(staging, "main.rb"))
-        bundle_ruby_entrypoint(source, staging)
-        Runtime.install_package(staging)
+      unless precompiled
+        config.write_manifest(staging) if config&.plugin?
+        entrypoint = config&.entrypoint || "main.rb"
+        if File.file?(File.join(staging, entrypoint))
+          bundle_ruby_entrypoint(source, staging, entrypoint:)
+          Runtime.install_package(staging, compiled: !config.nil?)
+        end
       end
       staging
     rescue StandardError
@@ -197,9 +248,11 @@ module OmarchyUI
       raise
     end
 
-    def bundle_ruby_entrypoint(source, destination)
-      entrypoint = File.join(source, "main.rb")
-      File.write(File.join(destination, "main.rb"), SourceBundle.new(entrypoint, root: source).call)
+    def bundle_ruby_entrypoint(source, destination, entrypoint: "main.rb")
+      source_entrypoint = File.join(source, entrypoint)
+      destination_entrypoint = File.join(destination, entrypoint)
+      FileUtils.mkdir_p(File.dirname(destination_entrypoint))
+      File.write(destination_entrypoint, SourceBundle.new(source_entrypoint, root: source).call)
     end
 
     def activate_plugin(plugin_id)

data/lib/omarchy_ui/generator.rb

@@ -4,9 +4,15 @@ require "fileutils"
 
 module OmarchyUI
   class Generator
-    def initialize(path:, name: nil)
+    PROJECT_KINDS = %i[application plugin].freeze
+
+    def initialize(path:, name: nil, kind: :application, plugin_id: nil, author: nil)
       @path = File.expand_path(path)
       @name = name || File.basename(@path).split(/[-_]/).map(&:capitalize).join(" ")
+      @kind = kind.to_sym
+      @plugin_id = plugin_id || "local.#{project_slug}"
+      @author = author.to_s.strip.empty? ? "Omarchy UI Developer" : author.to_s.strip
+      raise ArgumentError, "unsupported project kind: #{@kind}" unless PROJECT_KINDS.include?(@kind)
     end
 
     def create
@@ -14,9 +20,11 @@ module OmarchyUI
       created = true
       FileUtils.mkdir_p(File.join(@path, "components"))
       File.write(File.join(@path, "main.rb"), main_program)
-      File.write(File.join(@path, "app.rb"), application_program)
+      File.write(File.join(@path, "app.rb"), application_program) unless plugin?
+      File.write(File.join(@path, ProjectConfig::FILE_NAME), project_config)
       File.write(File.join(@path, "components", "welcome.rb"), welcome_component)
       File.write(File.join(@path, "README.md"), readme)
+      File.write(File.join(@path, "LICENSE"), license)
       @path
     rescue StandardError
       FileUtils.remove_entry(@path) if created && File.directory?(@path)
@@ -26,6 +34,8 @@ module OmarchyUI
     private
 
     def main_program
+      return plugin_program if plugin?
+
       <<~RUBY
         # frozen_string_literal: true
 
@@ -36,6 +46,33 @@ module OmarchyUI
       RUBY
     end
 
+    def plugin_program
+      <<~RUBY
+        # frozen_string_literal: true
+
+        require "omarchy_ui"
+        require_relative "components/welcome"
+
+        OmarchyUI.plugin(ui: #{constant_name}::UI) do
+          bar_widget do
+            row spacing: 7 do
+              text "#{@name}"
+            end
+            on_click { open_panel :#{surface_name} }
+          end
+
+          panel :#{surface_name} do
+            scroll width: 560, height: 620 do
+              welcome_card(
+                title: "#{@name}",
+                message: "Your Omarchy plugin is ready. Build the interface with Ruby and Zui components."
+              )
+            end
+          end
+        end
+      RUBY
+    end
+
     def application_program
       <<~RUBY
         # frozen_string_literal: true
@@ -80,6 +117,8 @@ module OmarchyUI
     end
 
     def readme
+      return plugin_readme if plugin?
+
       <<~MARKDOWN
         # #{@name}
 
@@ -92,10 +131,98 @@ module OmarchyUI
         ```
 
         Reusable Ruby UI components live in `components/` and load with ordinary Ruby
-        `require_relative`. Run `omarchy_ui bundle` to create a self-contained distribution.
+        `require_relative`. Project identity and build settings live in `config.rb`.
+
+        ## Build
+
+        ```bash
+        omarchy_ui bundle
+        ```
+
+        Omarchy UI tree-shakes and compiles the UI, then generates the complete self-contained
+        application package required by Omarchy.
+      MARKDOWN
+    end
+
+    def plugin_readme
+      <<~MARKDOWN
+        # #{@name}
+
+        A pure Ruby Omarchy plugin built with Omarchy UI and Zui.
+
+        ## Validate
+
+        ```bash
+        omarchy_ui validate
+        ```
+
+        ## Install for development
+
+        ```bash
+        omarchy_ui push
+        ```
+
+        ## Build
+
+        ```bash
+        omarchy_ui bundle
+        ```
+
+        Write the plugin interface and behavior in Ruby under `main.rb` and `components/`.
+        Public plugin identity and release metadata live in `config.rb`. Omarchy UI tree-shakes and
+        compiles the UI, then generates and validates the complete Omarchy-compatible plugin package.
       MARKDOWN
     end
 
+    def project_config
+      config = ProjectConfig.generate(
+        name: @name,
+        slug: project_slug,
+        kind: @kind,
+        author: @author,
+        plugin_id: @plugin_id
+      )
+      config
+    end
+
+    def license
+      <<~TEXT
+        MIT License
+
+        Copyright (c) #{Time.now.year} #{@author}
+
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+      TEXT
+    end
+
+    def plugin?
+      @kind == :plugin
+    end
+
+    def project_slug
+      File.basename(@path).downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|\-\z/, "")
+    end
+
+    def surface_name
+      project_slug.tr("-", "_")
+    end
+
     def constant_name
       @name.gsub(/[^a-zA-Z0-9]+/, " ").split.map(&:capitalize).join.then do |name|
         name.empty? || name.match?(/\A\d/) ? "OmarchyApplication" : name

data/lib/omarchy_ui/project_config.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OmarchyUI
+  class ProjectConfig
+    FILE_NAME = "config.rb"
+    PROJECT_TYPES = %i[application plugin].freeze
+    SLUG = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+    SECTIONS = %i[left center right].freeze
+
+    class Builder
+      FIELDS = %i[type id name slug version author license description entrypoint].freeze
+
+      FIELDS.each do |field|
+        define_method(field) { |value| @values[field] = value }
+      end
+
+      def initialize
+        @values = {}
+      end
+
+      def bar_widget(&definition)
+        widget = WidgetBuilder.new
+        widget.instance_eval(&definition)
+        @values[:bar_widget] = widget.to_h
+      end
+
+      def build(path: FILE_NAME)
+        ProjectConfig.new(@values, path:).tap(&:validate!)
+      end
+    end
+
+    class WidgetBuilder
+      FIELDS = %i[display_name description category default_section].freeze
+
+      FIELDS.each do |field|
+        define_method(field) { |value| @values[field] = value }
+      end
+
+      def initialize
+        @values = {}
+      end
+
+      def to_h
+        @values.dup
+      end
+    end
+
+    attr_reader :path
+
+    def self.define(&definition)
+      raise ArgumentError, "project config requires a block" unless definition
+
+      Builder.new.tap { |builder| builder.instance_eval(&definition) }.build
+    end
+
+    def self.generate(name:, slug:, kind:, author:, plugin_id: nil)
+      type = kind.to_sym
+      raise ArgumentError, "unsupported project type: #{type}" unless PROJECT_TYPES.include?(type)
+
+      lines = [
+        "# frozen_string_literal: true",
+        "",
+        "OmarchyUI.configure do",
+        "  type #{type.inspect}"
+      ]
+      lines << "  id #{(plugin_id || "local.#{slug}").inspect}" if type == :plugin
+      lines.concat([
+        "  name #{name.inspect}",
+        "  slug #{slug.inspect}",
+        "  version \"0.1.0\""
+      ])
+      if type == :plugin
+        lines.concat([
+          "  author #{author.inspect}",
+          "  license \"MIT\"",
+          "  description #{"A Ruby-powered #{name} plugin generated by Omarchy UI.".inspect}",
+          "  entrypoint \"main.rb\"",
+          "",
+          "  bar_widget do",
+          "    display_name #{name.inspect}",
+          "    description #{"Open #{name}.".inspect}",
+          "    category \"System\"",
+          "    default_section :right",
+          "  end"
+        ])
+      else
+        lines << "  entrypoint \"main.rb\""
+      end
+      lines << "end"
+      lines.join("\n") + "\n"
+    end
+
+    def self.load(root)
+      path = File.join(File.expand_path(root), FILE_NAME)
+      return nil unless File.file?(path)
+
+      value = Module.new.module_eval(File.read(path), path, 1)
+      unless value.is_a?(ProjectConfig)
+        raise ArgumentError, "#{FILE_NAME} must return an OmarchyUI::ProjectConfig"
+      end
+
+      new(value.to_h, path:).tap(&:validate!)
+    rescue SyntaxError, NameError, NoMethodError => error
+      raise ArgumentError, "invalid #{FILE_NAME}: #{error.message}"
+    end
+
+    def initialize(data, path:)
+      @data = data
+      @path = path
+    end
+
+    def type
+      value = @data[:type]
+      value.respond_to?(:to_sym) ? value.to_sym : value
+    end
+
+    def application? = type == :application
+    def plugin? = type == :plugin
+    def name = @data.fetch(:name)
+    def slug = @data.fetch(:slug)
+    def entrypoint = @data.fetch(:entrypoint)
+
+    def to_h
+      @data.dup
+    end
+
+    def manifest
+      raise ArgumentError, "project config describes an application, not a plugin" unless plugin?
+
+      widget = @data.fetch(:bar_widget)
+      {
+        "schemaVersion" => 1,
+        "id" => @data.fetch(:id),
+        "name" => name,
+        "version" => @data.fetch(:version),
+        "author" => @data.fetch(:author),
+        "license" => @data.fetch(:license),
+        "description" => @data.fetch(:description),
+        "kinds" => ["service", "bar-widget", "panel"],
+        "keepLoaded" => true,
+        "entryPoints" => {
+          "service" => "Service.qml",
+          "barWidget" => "BarWidget.qml",
+          "panel" => "Panel.qml"
+        },
+        "barWidget" => {
+          "displayName" => widget.fetch(:display_name),
+          "description" => widget.fetch(:description),
+          "category" => widget.fetch(:category),
+          "allowMultiple" => false,
+          "defaultSection" => widget.fetch(:default_section).to_s
+        }
+      }
+    end
+
+    def write_manifest(destination)
+      File.write(File.join(destination, "manifest.json"), JSON.pretty_generate(manifest) + "\n")
+    end
+
+    def validate!
+      raise ArgumentError, "invalid project config" unless @data.is_a?(Hash)
+      raise ArgumentError, "invalid project type" unless PROJECT_TYPES.include?(type)
+      required_string!(:name)
+      required_string!(:slug)
+      raise ArgumentError, "invalid project slug" unless SLUG.match?(@data[:slug])
+      required_string!(:version)
+      required_string!(:entrypoint)
+      validate_entrypoint!
+      validate_plugin! if plugin?
+      self
+    end
+
+    private
+
+    def required_string!(key, object = @data)
+      value = object[key]
+      raise ArgumentError, "invalid project config field: #{key}" unless value.is_a?(String) && !value.strip.empty?
+
+      value
+    end
+
+    def validate_entrypoint!
+      parts = entrypoint.split(/[\\\/]/)
+      if entrypoint.start_with?("/") || parts.empty? || parts.include?("..") || !entrypoint.end_with?(".rb")
+        raise ArgumentError, "invalid project entrypoint"
+      end
+    end
+
+    def validate_plugin!
+      %i[id author license description].each { |key| required_string!(key) }
+      raise ArgumentError, "invalid plugin id" unless VALID_ID.match?(@data[:id])
+
+      widget = @data[:bar_widget]
+      raise ArgumentError, "plugin project config is missing bar widget metadata" unless widget.is_a?(Hash)
+
+      %i[display_name description category].each { |key| required_string!(key, widget) }
+      section = widget[:default_section]
+      valid_section = section.respond_to?(:to_sym) && SECTIONS.include?(section.to_sym)
+      raise ArgumentError, "invalid default bar section" unless valid_section
+    end
+  end
+
+  def self.configure(&definition)
+    ProjectConfig.define(&definition)
+  end
+end

data/lib/omarchy_ui/qml_compiler.rb

@@ -0,0 +1,386 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "open3"
+require "pathname"
+require "tmpdir"
+
+module OmarchyUI
+  class QmlCompiler
+    FORMAT_VERSION = 1
+    ENTRY_TYPES = {
+      "App.qml" => "App",
+      "BarWidget.qml" => "BarWidget",
+      "Panel.qml" => "Panel",
+      "Service.qml" => "Service"
+    }.freeze
+    SOURCE_ENTRIES = (ENTRY_TYPES.keys + %w[ControlNode.qml Components Controls Theme Fonts]).freeze
+    COMPILED_ROOT = "OmarchyUI"
+    REPORT = "omarchy-ui-qml-bundle.json"
+    CHECKSUM = "omarchy-ui-qml-bundle.sha256"
+    PROVENANCE = "QML_PROVENANCE.md"
+
+    def self.compile!(path)
+      new(path).compile!
+    end
+
+    def self.verify!(path)
+      new(path).verify!
+    end
+
+    def initialize(path)
+      @path = File.expand_path(path)
+    end
+
+    def compile!
+      validate_sources!
+      tools = build_tools
+      qt_version = qt_version!(tools.fetch(:qtpaths))
+
+      Dir.mktmpdir("omarchy-ui-qml-compile-") do |temporary|
+        source = File.join(temporary, "source")
+        build = File.join(temporary, "build")
+        stage_sources(source)
+        qml_files = relative_files(source, "**/*.qml")
+        resources = relative_files(source, "Fonts/**/*") +
+          %w[Controls/qmldir Theme/qmldir].select { |entry| File.file?(File.join(source, entry)) }
+        fingerprint = source_fingerprint(source, qml_files + resources, qt_version:)
+        segment = "B#{fingerprint[0, 20]}"
+        uri = "OmarchyUI.Bundles.#{segment}"
+        target = "omarchy_ui_bundle_#{segment.downcase}"
+        module_path = File.join(*uri.split("."))
+
+        File.write(File.join(source, "CMakeLists.txt"), cmake_project(
+          qml_files:,
+          resources: resources.sort,
+          uri:,
+          target:,
+          module_path:
+        ))
+        configure!(tools.fetch(:qt_cmake), source, build)
+        build!(tools.fetch(:cmake), build)
+        deploy!(
+          build:,
+          module_path:,
+          target:,
+          uri:,
+          fingerprint:,
+          qml_files:,
+          resources:,
+          source:,
+          expected_qt_version: qt_version
+        )
+      end
+    end
+
+    def verify!
+      report_path = File.join(@path, REPORT)
+      raise ArgumentError, "compiled QML report is missing: #{report_path}" unless File.file?(report_path)
+
+      report = JSON.parse(File.read(report_path))
+      unless report["format"] == "qt-aot-qml-module" && report["format_version"] == FORMAT_VERSION
+        raise ArgumentError, "unsupported compiled QML package format"
+      end
+      ENTRY_TYPES.each_key do |entry|
+        raise ArgumentError, "compiled QML entry shim is missing: #{entry}" unless File.file?(File.join(@path, entry))
+      end
+      module_path = safe_relative_path(report.fetch("module_path"))
+      raise ArgumentError, "compiled QML qmldir is missing" unless File.file?(File.join(@path, module_path, "qmldir"))
+
+      artifacts = report.fetch("artifacts")
+      raise ArgumentError, "compiled QML package must contain two libraries" unless artifacts.length == 2
+      artifacts.each do |artifact|
+        relative = safe_relative_path(artifact.fetch("path"))
+        unless relative.start_with?("#{module_path}/") && relative.end_with?(".so")
+          raise ArgumentError, "compiled QML artifact is outside its module: #{relative}"
+        end
+        absolute = File.join(@path, relative)
+        raise ArgumentError, "compiled QML artifact is missing: #{relative}" unless File.file?(absolute)
+        unless File.size(absolute) == artifact.fetch("bytes") &&
+            Digest::SHA256.file(absolute).hexdigest == artifact.fetch("sha256")
+          raise ArgumentError, "compiled QML artifact checksum mismatch: #{relative}"
+        end
+      end
+      report
+    rescue JSON::ParserError, KeyError, TypeError => error
+      raise ArgumentError, "invalid compiled QML report: #{error.message}"
+    end
+
+    private
+
+    def safe_relative_path(path)
+      value = path.to_s
+      clean = File.expand_path(value, @path)
+      unless !value.empty? && !Pathname.new(value).absolute? && clean.start_with?("#{@path}/")
+        raise ArgumentError, "unsafe compiled QML path: #{value.inspect}"
+      end
+      clean.delete_prefix("#{@path}/")
+    end
+
+    def validate_sources!
+      missing = ENTRY_TYPES.keys.reject { |entry| File.file?(File.join(@path, entry)) }
+      missing << "ControlNode.qml" unless File.file?(File.join(@path, "ControlNode.qml"))
+      return if missing.empty?
+
+      raise ArgumentError, "cannot compile QML; generated files are missing: #{missing.join(', ')}"
+    end
+
+    def build_tools
+      {
+        qt_cmake: find_executable("/usr/lib/qt6/bin/qt-cmake", "qt-cmake"),
+        qtpaths: find_executable("/usr/lib/qt6/bin/qtpaths", "qtpaths6", "qtpaths"),
+        cmake: find_executable("cmake"),
+        ninja: find_executable("ninja"),
+        compiler: find_executable("c++", "g++", "clang++")
+      }
+    end
+
+    def qt_version!(qtpaths)
+      output, error, status = Open3.capture3(qtpaths, "--query", "QT_VERSION")
+      version = output.strip
+      return version if status.success? && !version.empty?
+
+      detail = error.strip
+      raise ArgumentError, "could not determine the Qt build version#{detail.empty? ? '' : ": #{detail}"}"
+    end
+
+    def find_executable(*candidates)
+      candidates.each do |candidate|
+        if candidate.include?(File::SEPARATOR)
+          return candidate if File.file?(candidate) && File.executable?(candidate)
+          next
+        end
+
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |directory|
+          path = File.join(directory, candidate)
+          return path if File.file?(path) && File.executable?(path)
+        end
+      end
+      raise ArgumentError, "compiled QML packaging requires #{candidates.first}"
+    end
+
+    def stage_sources(destination)
+      FileUtils.mkdir_p(destination)
+      SOURCE_ENTRIES.each do |entry|
+        source = File.join(@path, entry)
+        next unless File.exist?(source)
+
+        FileUtils.cp_r(source, File.join(destination, entry))
+      end
+    end
+
+    def relative_files(root, pattern)
+      Dir.glob(File.join(root, pattern), File::FNM_DOTMATCH)
+        .select { |path| File.file?(path) }
+        .map { |path| path.delete_prefix("#{root}/") }
+        .sort
+    end
+
+    def source_fingerprint(root, files, qt_version:)
+      digest = Digest::SHA256.new
+      digest << "omarchy-ui-qml-bundle\0" << FORMAT_VERSION.to_s << "\0"
+      digest << "qt\0" << qt_version << "\0"
+      files.sort.each do |relative|
+        digest << relative << "\0" << File.binread(File.join(root, relative)) << "\0"
+      end
+      digest.hexdigest
+    end
+
+    def cmake_project(qml_files:, resources:, uri:, target:, module_path:)
+      <<~CMAKE
+        cmake_minimum_required(VERSION 3.21)
+
+        project(OmarchyUICompiledBundle LANGUAGES CXX)
+
+        find_package(Qt6 6.8 REQUIRED COMPONENTS Core Qml Quick QuickControls2)
+        qt_standard_project_setup(REQUIRES 6.8)
+
+        qt_add_library(#{target} SHARED)
+        qt_add_qml_module(#{target}
+          URI #{uri}
+          VERSION 1.0
+          OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/#{module_path}"
+          QML_FILES
+        #{cmake_entries(qml_files)}
+          RESOURCES
+        #{cmake_entries(resources)}
+          DISCARD_QML_CONTENTS
+          NO_LINT
+        )
+
+        set(module_output "${CMAKE_BINARY_DIR}/#{module_path}")
+        set_target_properties(
+          #{target}
+          #{target}plugin
+          PROPERTIES
+            LIBRARY_OUTPUT_DIRECTORY "${module_output}"
+            BUILD_RPATH "\\$ORIGIN"
+            BUILD_WITH_INSTALL_RPATH TRUE
+            INSTALL_RPATH "\\$ORIGIN"
+        )
+
+        target_compile_options(
+          #{target}
+          PRIVATE
+            "-ffile-prefix-map=${CMAKE_CURRENT_SOURCE_DIR}=."
+            "-ffile-prefix-map=${CMAKE_CURRENT_BINARY_DIR}=."
+        )
+        target_compile_options(
+          #{target}plugin
+          PRIVATE
+            "-ffile-prefix-map=${CMAKE_CURRENT_SOURCE_DIR}=."
+            "-ffile-prefix-map=${CMAKE_CURRENT_BINARY_DIR}=."
+        )
+        target_link_options(#{target} PRIVATE "-Wl,--build-id=none")
+        target_link_options(#{target}plugin PRIVATE "-Wl,--build-id=none")
+        target_link_libraries(
+          #{target}
+          PRIVATE Qt6::Core Qt6::Qml Qt6::Quick Qt6::QuickControls2
+        )
+
+        file(WRITE "${CMAKE_BINARY_DIR}/qt-version.txt" "${Qt6Core_VERSION}\n")
+      CMAKE
+    end
+
+    def cmake_entries(entries)
+      entries.map { |entry| "    #{cmake_string(entry)}" }.join("\n")
+    end
+
+    def cmake_string(value)
+      escaped = value.gsub("\\", "\\\\").gsub('"', '\\"')
+      %Q("#{escaped}")
+    end
+
+    def configure!(qt_cmake, source, build)
+      run_build_command!(
+        "QML configure",
+        qt_cmake,
+        "-S", source,
+        "-B", build,
+        "-G", "Ninja",
+        "-DCMAKE_BUILD_TYPE=Release"
+      )
+    end
+
+    def build!(cmake, build)
+      run_build_command!("QML compilation", cmake, "--build", build, "--parallel")
+    end
+
+    def run_build_command!(label, *command)
+      environment = {
+        "LC_ALL" => "C.UTF-8",
+        "SOURCE_DATE_EPOCH" => "1",
+        "TZ" => "UTC"
+      }
+      output, error, status = Open3.capture3(environment, *command)
+      return if status.success?
+
+      detail = "#{output}\n#{error}".lines.last(40).join.strip
+      raise ArgumentError, "#{label} failed#{detail.empty? ? '' : ":\n#{detail}"}"
+    end
+
+    def deploy!(build:, module_path:, target:, uri:, fingerprint:, qml_files:, resources:, source:,
+      expected_qt_version:)
+      built_module = File.join(build, module_path)
+      artifact_names = ["lib#{target}.so", "lib#{target}plugin.so", "qmldir"]
+      missing = artifact_names.reject { |name| File.file?(File.join(built_module, name)) }
+      unless missing.empty?
+        raise ArgumentError, "QML compilation did not produce: #{missing.join(', ')}"
+      end
+      qt_version = File.read(File.join(build, "qt-version.txt")).strip
+      unless qt_version == expected_qt_version
+        raise ArgumentError,
+          "Qt compiler mismatch: qtpaths reported #{expected_qt_version}, CMake found #{qt_version}"
+      end
+
+      compiled_root = File.join(@path, COMPILED_ROOT)
+      FileUtils.remove_entry(compiled_root) if File.directory?(compiled_root)
+      destination = File.join(@path, module_path)
+      FileUtils.mkdir_p(destination)
+      artifact_names.each { |name| FileUtils.cp(File.join(built_module, name), destination) }
+      qmldir = File.join(destination, "qmldir")
+      File.write(qmldir, File.read(qmldir).rstrip + "\n")
+
+      SOURCE_ENTRIES.each { |entry| remove_generated(File.join(@path, entry)) }
+      ENTRY_TYPES.each do |entry, type|
+        File.write(File.join(@path, entry), entry_shim(module_path, type, uri:))
+      end
+
+      artifact_paths = artifact_names.filter_map do |name|
+        next if name == "qmldir"
+
+        relative = File.join(module_path, name)
+        absolute = File.join(@path, relative)
+        {
+          "path" => relative,
+          "sha256" => Digest::SHA256.file(absolute).hexdigest,
+          "bytes" => File.size(absolute)
+        }
+      end
+      report = {
+        "format" => "qt-aot-qml-module",
+        "format_version" => FORMAT_VERSION,
+        "qt_version" => qt_version,
+        "module_uri" => uri,
+        "module_path" => module_path,
+        "source_fingerprint" => fingerprint,
+        "source_files" => qml_files.length,
+        "source_bytes" => (qml_files + resources).sum { |file| File.size(File.join(source, file)) },
+        "entry_shims" => ENTRY_TYPES.keys,
+        "artifacts" => artifact_paths
+      }
+      File.write(File.join(@path, REPORT), JSON.pretty_generate(report) + "\n")
+      checksums = artifact_paths.map { |artifact| "#{artifact.fetch('sha256')}  #{artifact.fetch('path')}" }
+      File.write(File.join(@path, CHECKSUM), checksums.join("\n") + "\n")
+      File.write(File.join(@path, PROVENANCE), provenance(report))
+      report
+    end
+
+    def remove_generated(path)
+      File.directory?(path) ? FileUtils.remove_entry(path) : FileUtils.rm_f(path)
+    end
+
+    def entry_shim(module_path, type, uri:)
+      import = type == "App" ? uri : %Q("#{module_path}")
+      <<~QML
+        import QtQuick
+        import #{import} as Compiled
+
+        Compiled.#{type} {}
+      QML
+    end
+
+    def provenance(report)
+      artifacts = report.fetch("artifacts").map do |artifact|
+        "- `#{artifact.fetch('path')}` — `#{artifact.fetch('sha256')}`"
+      end.join("\n")
+      <<~MARKDOWN
+        # Compiled QML provenance
+
+        Omarchy UI generated this package's native Qt module from the tree-shaken Zui and
+        Omarchy host QML graph. Generated QML source contents were discarded after AOT compilation.
+
+        - Format: `#{report.fetch('format')}` version #{report.fetch('format_version')}
+        - Qt: `#{report.fetch('qt_version')}`
+        - Module: `#{report.fetch('module_uri')}`
+        - Source fingerprint: `#{report.fetch('source_fingerprint')}`
+
+        ## Artifacts
+
+        #{artifacts}
+
+        Verify the packaged libraries from the plugin directory:
+
+        ```bash
+        sha256sum --check #{CHECKSUM}
+        ```
+
+        `App.qml`, `Service.qml`, `Panel.qml`, and `BarWidget.qml` are the minimal loader shims
+        required by Omarchy's file-based entry-point contract. Application UI lives in the compiled
+        module recorded by `#{REPORT}`.
+      MARKDOWN
+    end
+  end
+end

data/lib/omarchy_ui/runtime.rb

@@ -16,8 +16,14 @@ module OmarchyUI
     AUDIT_FILES = %w[
       omarchy-ui-runtime.sha256 runtime-provenance.json RUNTIME_PROVENANCE.md
     ].freeze
-    GENERATED_ENTRIES = (ADAPTER_FILES + ZUI_GENERATED_ENTRIES +
-      [TREE_SHAKE_REPORT, "omarchy-ui-runtime"]).freeze
+    GENERATED_ENTRIES = (ADAPTER_FILES + ZUI_GENERATED_ENTRIES + [
+      TREE_SHAKE_REPORT,
+      QmlCompiler::COMPILED_ROOT,
+      QmlCompiler::REPORT,
+      QmlCompiler::CHECKSUM,
+      QmlCompiler::PROVENANCE,
+      "omarchy-ui-runtime"
+    ]).freeze
 
     def executable
       override = ENV["OMARCHY_UI_RUNTIME"]
@@ -39,7 +45,7 @@ module OmarchyUI
       FileUtils.rm_f(temporary) if temporary && File.exist?(temporary)
     end
 
-    def install_package(path, framework_root: FRAMEWORK_ROOT, project: path)
+    def install_package(path, framework_root: FRAMEWORK_ROOT, project: path, compiled: false)
       FileUtils.mkdir_p(path)
       GENERATED_ENTRIES.each do |entry|
         generated = File.join(path, entry)
@@ -67,6 +73,7 @@ module OmarchyUI
         source = File.join(framework_root, "vendor", "runtime", "x86_64-linux", file)
         FileUtils.cp(source, File.join(path, file)) if File.file?(source)
       end
+      QmlCompiler.compile!(path) if compiled
       path
     end
 

data/lib/omarchy_ui.rb

@@ -11,7 +11,7 @@ rescue LoadError
 end
 
 module OmarchyUI
-  VERSION = "0.0.7"
+  VERSION = "0.0.9"
   ZUI_VERSION = Zui::VERSION
   FRAMEWORK_ROOT = File.expand_path("..", __dir__)
 
@@ -126,5 +126,7 @@ module Zui
   end
 end
 
+require_relative "omarchy_ui/project_config"
 require_relative "omarchy_ui/generator"
+require_relative "omarchy_ui/qml_compiler"
 require_relative "omarchy_ui/runtime"

data/vendor/runtime/x86_64-linux/RUNTIME_PROVENANCE.md

@@ -17,4 +17,4 @@ The workflow checks out every external input at a full commit digest, performs t
 builds, requires byte-identical executables, and signs the resulting SHA through GitHub's
 artifact attestation service. Machine-readable provenance is included in
 `runtime-provenance.json`; independent verification instructions are in
-[`docs/runtime-build.md`](../../../docs/runtime-build.md).
+the [runtime build documentation](https://github.com/AdamMusa/omarchy-ui/blob/main/docs/runtime-build.md).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omarchy-ui
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.9
 platform: x86_64-linux
 authors:
 - Adam Moussa Ali
@@ -39,6 +39,8 @@ files:
 - lib/omarchy_ui.rb
 - lib/omarchy_ui/cli.rb
 - lib/omarchy_ui/generator.rb
+- lib/omarchy_ui/project_config.rb
+- lib/omarchy_ui/qml_compiler.rb
 - lib/omarchy_ui/runtime.rb
 - vendor/runtime/x86_64-linux/RUNTIME_PROVENANCE.md
 - vendor/runtime/x86_64-linux/omarchy-ui-runtime