omarchy-ui 0.0.8-x86_64-linux → 0.0.10-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbe75336899d8f9674166011c929469db798869f88b32f45a3b61505b0713d01
-  data.tar.gz: bb5f2e4f0dfec4578992d17d5f3fdc5530d5b2c73d4aeebcfada553355077f94
+  metadata.gz: ba33f1f0b7fead5be0f82726faeeb3815b94386f679732ee4945d840374a1023
+  data.tar.gz: bc7bfb798a46491d22085e3f81cbde27da3b9f14149b1ec63bd3e36b182f83c7
 SHA512:
-  metadata.gz: 9776119537e37548ea84ca4129647a6f94b64944ae75315e776db661220aefeb4cc80527ed93a1b1c9410e0b80d2a547c77a2aae6674f770decc354bdee2a505
-  data.tar.gz: 6856581d58533845967d37daae2679cbf9601f9555aa724b9a9cbf04da0a62a8b15cd146df6d3b36551dec85ad29a13189ba1bdb01a143c2a3cfed87f46d2bb4
+  metadata.gz: c76b00784fdf4a0371269d79d570e10ece613faf94449f2e40025a7a5a7a45b53080b259a7a68cedc7e21c89cc03e628cc3e3301c04db806145db19cc2b0d6ed
+  data.tar.gz: f4511e5523b4a033be1d80682305d99e0502721186cf8330d3c4d10e332bf0e85233d96f1b59840c54f7679e34abe4b8018b170357170b1bff6e1e38f4f697e6

data/README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-  <img alt="Omarchy UI 0.0.8" src="https://img.shields.io/badge/Omarchy_UI-0.0.8-b7ff5a?style=flat-square&labelColor=111711">
+  <img alt="Omarchy UI 0.0.10" src="https://img.shields.io/badge/Omarchy_UI-0.0.10-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,8 +46,8 @@ 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
 
@@ -59,15 +59,16 @@ and the Omarchy adapter.
 
 ## 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
 
-Omarchy UI generates a complete Omarchy-compatible application or plugin package from the
-developer's Ruby and assets. It owns the Omarchy metadata, entry points, adapter, validation,
-tree-shaken Zui QML, and embedded mruby runtime. The finished package 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
 
@@ -79,7 +80,7 @@ gem install omarchy-ui
 
 The gem installs the compatible Zui version as a dependency.
 
-### 2. Generate a complete project
+### 2. Generate a project
 
 ```bash
 omarchy_ui new Counter
@@ -93,13 +94,12 @@ omarchy_ui new "System Status" --plugin
 cd system-status
 ```
 
-Both commands create a ready-to-run Ruby project. Omarchy UI generates the complete compliant
-application or plugin package; developers do not write QML, shell entry points, or an Omarchy
-manifest by hand.
+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` containing its type, identity, release version,
-entry point, and—for plugins—public marketplace metadata. `bundle`, `validate`, and `push` read this
-single configuration when assembling the complete package.
+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:
 
@@ -120,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
 
@@ -246,16 +246,15 @@ QML is not required.
 
 ## Omarchy plugins
 
-Generate a complete plugin project with one command:
+Generate a plugin project with one command:
 
 ```bash
 omarchy_ui new "System Status" --plugin
 cd system-status
 ```
 
-The generated project already satisfies Omarchy's structural requirements. Developers work in Ruby
-and add their own assets; Omarchy UI owns the required plugin metadata, shell surfaces, native host,
-tree-shaken Zui package, validation, and install lifecycle.
+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.
 
 The Ruby entry point uses ordinary Zui components:
 
@@ -282,8 +281,8 @@ OmarchyUI.plugin do
 end
 ```
 
-`bar_widget` and `panel :status` are the complete developer-facing surface declarations. Omarchy UI
-maps them to the required Omarchy shell entry points when it builds or stages the plugin.
+`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
 
@@ -292,8 +291,21 @@ omarchy_ui validate
 omarchy_ui push
 ```
 
-`validate` generates and checks the complete plugin without mutating the Ruby project. `push` safely
-builds, validates, installs, enables, and reloads the plugin for development.
+`validate` generates and checks the plugin without modifying the Ruby project. `push` builds,
+validates, installs, enables, and reloads it for development.
+
+To publish, target a separate public distribution repository. Omarchy UI rebuilds the thin package,
+enforces the marketplace contract, pushes it, and prints the complete submission for review:
+
+```bash
+omarchy_ui publish --repo YOUR_GITHUB_NAME/PLUGIN_REPOSITORY \
+  --category System --tags system,quickshell --create
+```
+
+After reviewing the printed title, metadata, and five marketplace attestations, rerun the same
+command with `--submit`. It creates a submission or refreshes an existing open one. This two-step
+flow prevents accidental replacement of the source repository and ensures the ownership statement
+is reviewed before it is posted.
 
 During development, suppress either lifecycle action when needed:
 
@@ -302,10 +314,6 @@ 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, generated package, and provenance before installing a third-party plugin.
-
 ## Command-line reference
 
 ```text
@@ -314,11 +322,12 @@ omarchy_ui <command> [arguments]
 
 | Command | Arguments | Result |
 | --- | --- | --- |
-| `omarchy_ui new NAME` | One project name | Creates a complete Omarchy application project |
-| `omarchy_ui new NAME --plugin` | One project name and `--plugin` | Creates a complete Omarchy-compliant plugin project |
+| `omarchy_ui new NAME` | One project name | Creates an Omarchy application project |
+| `omarchy_ui new NAME --plugin --github USER` | One project name, `--plugin`, and optional GitHub user | Creates a marketplace-ready 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 | Generates the complete distributable package and prints its location |
-| `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 publish [DIRECTORY]` | Required `--repo`, `--category`, `--tags`; optional `--create`, `--submit` | Builds and pushes a thin distribution repository, then previews or submits its marketplace issue |
+| `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 |
 
@@ -327,19 +336,29 @@ not forward arbitrary Ruby arguments.
 
 ## Packaging
 
-Create the complete distributable package from the project root:
+Create the distributable package from the project root:
 
 ```bash
 omarchy_ui bundle
 ```
 
-Omarchy UI prints the generated package location. It automatically assembles the bundled Ruby and
-assets, Omarchy metadata and entry points, native host, checksummed runtime provenance, and only the
-Zui QML components used by the project. Application packages receive a direct launcher; plugin
-packages are validated against Omarchy's requirements before the command succeeds. Omarchy UI pins
-Zui 0.0.10 so generated QML exactly matches the Zui core embedded in the deterministic mruby runtime.
-The source `config.rb` remains the authoritative build configuration; plugin manifests are generated
-from it in the distributable package and are never maintained separately by the developer.
+Omarchy UI assembles one bundled Ruby program and required assets, native runtime, manifest, and only
+the Zui components used by the project. It AOT-compiles the generated QML into a content-addressed Qt
+module, then 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.
+
+Current Omarchy entry points resolve by filename, so a package retains only the required generated
+loader shims. Applications keep `App.qml`; standard plugins keep `Service.qml`, `Panel.qml`, and
+`BarWidget.qml`. Each shim contains only an import and a compiled type instance. The application
+interface is authored in Ruby and stored in native `.so` artifacts. Distributable packages do not
+include generated QML source, build reports, audit/provenance folders, checksums, tests, or CI files.
+They also omit `config.rb` and Ruby files already folded into `main.rb`.
+Compiled packages should be built against the Qt version shipped by their target Omarchy release.
+
+The source `config.rb` is the build configuration. Omarchy UI generates plugin manifests from it;
+developers never maintain a separate manifest.
 
 ## Component catalog
 
@@ -406,10 +425,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 + required loader shims
           │
           ▼
 App window · Omarchy panel · Omarchy bar widget
@@ -427,8 +448,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

data/Service.qml

@@ -499,4 +499,27 @@ Item {
     repeat: false
     onTriggered: root.startRuby()
   }
+
+  // A desktop surface is rendered by the same long-lived service that owns
+  // the Ruby runtime. Its DesktopStage adapter creates the layer-shell window;
+  // plugins keep all scene structure, state, and interaction in Ruby.
+  ControlNode {
+    id: desktopRenderer
+    visible: root.ready && root.rootId("desktop") !== ""
+    bridge: root
+    surfaceName: "desktop"
+    controlId: root.rootId(surfaceName)
+  }
+
+  IpcHandler {
+    target: root.manifest && root.manifest.id ? String(root.manifest.id) : "omarchy-ui"
+
+    function playPause(): string {
+      var desktopId = root.rootId("desktop")
+      if (desktopId === "") return "not-ready"
+      return root.sendEvent("desktop", desktopId, "shortcut", { name: "play_pause" })
+        ? "ok"
+        : "not-ready"
+    }
+  }
 }

data/lib/omarchy_ui/cli.rb

@@ -23,11 +23,12 @@ module OmarchyUI
       when "run" then run_file(arguments)
       when "new" then new_project(arguments)
       when "bundle" then bundle_project(arguments)
+      when "publish" then publish(arguments)
       when "push" then push(arguments)
       when "validate" then validate(arguments)
       when "version", "--version", "-v" then @out.puts(OmarchyUI::VERSION); 0
       else
-        @err.puts("Usage: omarchy_ui <new NAME [--plugin]|run FILE|bundle [DIRECTORY]|push [DIRECTORY]|validate [DIRECTORY]|version>")
+        @err.puts("Usage: omarchy_ui <new NAME [--plugin] [--github USER]|run FILE|bundle [DIRECTORY]|publish [DIRECTORY] --repo OWNER/REPO --category CATEGORY --tags TAGS [--create] [--submit]|push [DIRECTORY]|validate [DIRECTORY]|version>")
         command.nil? ? 0 : 64
       end
     rescue Interrupt
@@ -68,11 +69,14 @@ module OmarchyUI
 
     def new_project(arguments)
       plugin = !arguments.delete("--plugin").nil?
+      github_user = extract_option!(arguments, "--github")
       name = arguments.shift || raise(ArgumentError, "new requires a project name")
-      raise ArgumentError, "new accepts a name and optional --plugin" unless arguments.empty?
+      raise ArgumentError, "new accepts a name, --plugin, and --github USER" unless arguments.empty?
+      raise ArgumentError, "--github is only valid with --plugin" if github_user && !plugin
       destination = File.expand_path(slug(name))
       kind = plugin ? :plugin : :application
-      Generator.new(path: destination, name: name, kind:, author: default_author).create
+      github_user ||= default_github_user if plugin
+      Generator.new(path: destination, name: name, kind:, author: default_author, github_user:).create
       label = plugin ? "Omarchy-compliant plugin" : "self-contained Omarchy application"
       @out.puts("Created #{label} in #{destination}")
       0
@@ -91,6 +95,30 @@ module OmarchyUI
       "Omarchy UI Developer"
     end
 
+    def default_github_user
+      configured = ENV["OMARCHY_UI_GITHUB_USER"].to_s.strip
+      return configured unless configured.empty?
+
+      output, _error, status = Open3.capture3("gh", "api", "user", "--jq", ".login")
+      login = output.to_s.strip
+      return login if status.success? && !login.empty?
+
+      raise ArgumentError,
+        "plugin generation needs --github USER or OMARCHY_UI_GITHUB_USER (gh auth login can provide it automatically)"
+    rescue Errno::ENOENT
+      raise ArgumentError, "plugin generation needs --github USER or OMARCHY_UI_GITHUB_USER"
+    end
+
+    def extract_option!(arguments, name)
+      index = arguments.index(name)
+      return nil unless index
+
+      value = arguments[index + 1]
+      raise ArgumentError, "#{name} requires a value" if value.nil? || value.start_with?("--")
+      arguments.slice!(index, 2)
+      value
+    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?
@@ -114,16 +142,21 @@ module OmarchyUI
       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, config:)
+      entries = precompiled ? package_entries(source) : application_entries(source, config:)
       FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, destination)
-      config.write_manifest(destination) if config&.plugin?
-      bundle_ruby_entrypoint(source, destination, entrypoint:)
-      Runtime.install_package(destination)
+      unless precompiled
+        config.write_manifest(destination) if config&.plugin?
+        bundle_ruby_entrypoint(source, destination, entrypoint:)
+        Runtime.install_package(destination, compiled: true)
+      end
+      prune_bundled_ruby_sources(destination, entrypoint:)
       plugin = config ? config.plugin? : File.file?(File.join(destination, "manifest.json"))
       if plugin
+        PluginPackage.validate!(destination)
         raise ArgumentError, "bundled plugin validation failed" unless system("omarchy", "plugin", "validate", destination)
         @out.puts("Bundled plugin in #{destination}")
         return 0
@@ -140,6 +173,8 @@ module OmarchyUI
         export OMARCHY_UI_RUNTIME="$app_dir/omarchy-ui-runtime"
         export OMARCHY_UI_PROJECT_DIR="$app_dir"
         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
@@ -156,9 +191,54 @@ module OmarchyUI
     end
 
     def application_entries(source, config: ProjectConfig.load(source))
-      generated = Runtime::GENERATED_ENTRIES + Runtime::AUDIT_FILES + %w[run Commons Ui]
+      generated = Runtime::GENERATED_ENTRIES + %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) }
+      Dir.children(source).reject do |entry|
+        (PluginPackage::DEVELOPMENT_ENTRIES + PluginPackage::SOURCE_CONTROL_ENTRIES).include?(entry) ||
+          generated.include?(entry)
+      end
+    end
+
+    def package_entries(source)
+      excluded = PluginPackage::DEVELOPMENT_ENTRIES + PluginPackage::SOURCE_CONTROL_ENTRIES +
+        Runtime::LEGACY_METADATA_FILES
+      Dir.children(source).reject { |entry| excluded.include?(entry) }
+    end
+
+    def compiled_package?(source)
+      compiled_root = File.join(source, QmlCompiler::COMPILED_ROOT, "Bundles")
+      shims = QmlCompiler::ENTRY_TYPES.keys.any? { |entry| File.file?(File.join(source, entry)) }
+      return false unless File.directory?(compiled_root) && shims
+
+      QmlCompiler.verify!(source)
+      true
+    end
+
+    def publish(arguments)
+      repository = extract_option!(arguments, "--repo")
+      category = extract_option!(arguments, "--category")
+      tags = extract_option!(arguments, "--tags").to_s.split(",")
+      create = !arguments.delete("--create").nil?
+      submit = !arguments.delete("--submit").nil?
+      source = File.expand_path(arguments.shift || Dir.pwd)
+      raise ArgumentError, "publish accepts one directory and publish options" unless arguments.empty?
+      config = ProjectConfig.load(source)
+      raise ArgumentError, "publish requires an Omarchy UI plugin project" unless config&.plugin?
+
+      with_staged_project(source) do |staging|
+        raise ArgumentError, "staged plugin validation failed" unless system("omarchy", "plugin", "validate", staging)
+        PluginPublisher.publish!(
+          package: staging,
+          source:,
+          repository:,
+          category:,
+          tags:,
+          create:,
+          submit:,
+          out: @out
+        )
+      end
+      0
     end
 
     def push(arguments)
@@ -213,15 +293,20 @@ 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, config:)
+      entries = precompiled ? package_entries(source) : application_entries(source, config:)
       FileUtils.cp_r(entries.map { |entry| File.join(source, entry) }, staging) unless entries.empty?
-      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)
+      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: true)
+        end
       end
+      prune_bundled_ruby_sources(staging, entrypoint: "main.rb") if File.file?(File.join(staging, "manifest.json"))
+      PluginPackage.validate!(staging) if File.file?(File.join(staging, "manifest.json"))
       staging
     rescue StandardError
       FileUtils.remove_entry(staging) if staging && File.exist?(staging)
@@ -235,6 +320,17 @@ module OmarchyUI
       File.write(destination_entrypoint, SourceBundle.new(source_entrypoint, root: source).call)
     end
 
+    def prune_bundled_ruby_sources(destination, entrypoint: "main.rb")
+      kept = File.expand_path(entrypoint, destination)
+      Dir.glob(File.join(destination, "**", "*.rb"), File::FNM_DOTMATCH).each do |path|
+        FileUtils.rm_f(path) unless File.expand_path(path) == kept
+      end
+      directories = Dir.glob(File.join(destination, "**", "*"), File::FNM_DOTMATCH)
+        .select { |path| File.directory?(path) && !File.symlink?(path) }
+        .sort_by { |path| -path.count(File::SEPARATOR) }
+      directories.each { |path| Dir.rmdir(path) if Dir.empty?(path) }
+    end
+
     def activate_plugin(plugin_id)
       return if system("omarchy", "plugin", "enable", plugin_id)
       system("omarchy-shell", "shell", "rescanPlugins")

data/lib/omarchy_ui/generator.rb

@@ -5,12 +5,17 @@ require "fileutils"
 module OmarchyUI
   class Generator
     PROJECT_KINDS = %i[application plugin].freeze
+    GITHUB_USER = /\A(?!-)[A-Za-z0-9-]{1,39}(?<!-)\z/
 
-    def initialize(path:, name: nil, kind: :application, plugin_id: nil, author: nil)
+    def initialize(path:, name: nil, kind: :application, plugin_id: nil, author: nil, github_user: 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}"
+      @github_user = github_user.to_s.strip
+      if plugin? && !GITHUB_USER.match?(@github_user)
+        raise ArgumentError, "plugin generation needs a valid GitHub username"
+      end
+      @plugin_id = plugin_id || "io.github.#{@github_user.downcase}.#{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
@@ -124,6 +129,9 @@ module OmarchyUI
 
         A pure Ruby desktop application built with Zui and the Omarchy UI host.
 
+        The interface and behavior are authored entirely in Ruby. Omarchy UI generates QML only
+        as a temporary build input, compiles it, and ships no handwritten QML source.
+
         ## Run
 
         ```bash
@@ -139,7 +147,10 @@ module OmarchyUI
         omarchy_ui bundle
         ```
 
-        Omarchy UI generates the complete self-contained application package required by Omarchy.
+        Omarchy UI tree-shakes and compiles the UI, then generates the complete self-contained
+        application package required by Omarchy. The package contains the bundled Ruby program,
+        native runtime, compiled Qt module, and one generated `App.qml` loader shim—no build reports
+        or generated QML source tree.
       MARKDOWN
     end
 
@@ -149,6 +160,26 @@ module OmarchyUI
 
         A pure Ruby Omarchy plugin built with Omarchy UI and Zui.
 
+        The interface and behavior are authored entirely in Ruby. Omarchy UI generates QML only
+        as a temporary build input, compiles it, and ships no handwritten QML source.
+
+        ## Install
+
+        ```bash
+        omarchy plugin add https://github.com/#{@github_user}/#{project_slug}.git --enable
+        ```
+
+        ## Remove
+
+        ```bash
+        omarchy plugin remove #{@plugin_id}
+        ```
+
+        ## Dependencies
+
+        - Omarchy Quattro on x86-64 Linux
+        - No additional runtime dependency in the generated starter
+
         ## Validate
 
         ```bash
@@ -168,8 +199,11 @@ module OmarchyUI
         ```
 
         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 uses it to
-        generate and validate the complete Omarchy-compatible plugin package.
+        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.
+        The package contains the bundled Ruby program, native runtime, compiled Qt module, manifest,
+        and only the generated loader shims named by that manifest—no build reports, audit folder,
+        tests, or generated QML source tree.
       MARKDOWN
     end