logos-ui-qml-builder

name	logos-ui-qml-builder
description	Use when the user wants to create, extend, or debug a Logos ui_qml module and needs concrete guidance for QML-only versus backend-backed ui_qml, view versus optional backend main, mkLogosQmlModule, logos.callModule, .rep and typed replica flows, standalone nix run, and Basecamp loading expectations.

Logos UI QML Builder

Use this skill for real ui_qml work once the builder has already chosen the QML surface.

Quick start

• Read references/ui-qml-shapes.md to choose between QML-only and backend-backed ui_qml.
• Read references/qml-bridge-and-replicas.md before suggesting logos.callModule, .rep, or typed replica wiring.
• Read references/packaging-and-standalone.md before giving mkLogosQmlModule, nix run, or install guidance.

When the target project has its own CLAUDE.md, prefer it for build commands and QML paths. The logos-basecamp/CLAUDE.md covers QML inspector and plugin loading.

Workflow

1. Confirm the work is ui_qml, not legacy ui and not a core module.
2. Decide the shape:
   • QML-only with a required view and no backend main
   • Backend-backed ui_qml with view plus backend main and .rep interface
3. Start from the correct shape:
   • metadata.json
   • flake.nix using mkLogosQmlModule
   • Main.qml
   • Optional backend sources and .rep file
4. Prefer the builder reality order:
   • Current Basecamp/runtime behavior
   • Tutorial guidance
   • Older generated AI context files
5. Keep compatibility warnings explicit:
   • view is the stable ui_qml entry contract in current Basecamp source
   • Older repos may carry main: Main.qml or manual manifest.json patterns
   • Legacy IComponent/ui paths are not the default ui_qml story
6. Route packaging, installation, and reset/debug loops to logos-module-build-loop.

Runtime warnings (from validated testing)

• Pure QML plugins work in local Nix-built Basecamp but this pattern is underdocumented in official tooling.
• The Logos Design System (import Logos.Theme 1.0) is NOT available in all portable builds (e.g. AppImage v0.1.1). Use hardcoded colors as fallback.
• Basecamp does not hot-reload plugins. After rebuilding an LGX, you must kill basecamp, clean installed modules, and relaunch.
• pkill for cleanup returns exit code 1 if no processes match. Do not chain cleanup commands with &&.

Reference map

• references/ui-qml-shapes.md -> QML-only versus backend-backed ui_qml
• references/qml-bridge-and-replicas.md -> logos.callModule, .rep, and typed replica patterns
• references/packaging-and-standalone.md -> mkLogosQmlModule, nix run, and install-path guidance

Quality rules

• Prefer ui_qml as the default QML builder path unless the user is explicitly targeting legacy ui.
• Mention view, optional backend main, and mkLogosQmlModule explicitly when they matter.
• Keep QML-only and backend-backed ui_qml distinct.
• Warn when repo metadata shape diverges from the current Basecamp view contract.
• Route packaging, install, and runtime-debug loops to logos-module-build-loop.
• Do not promise that the Logos Design System is available in all builds.