logos-module-build-loop

name	logos-module-build-loop
description	Use when the user needs the operational build loop for Logos modules or ui_qml apps, including nix build, ws build --auto-local, lm, logoscore, nix run, lgx, lgpm, Basecamp package-manager install, manual file-copy fallback, reset and cleanup loops, and compatibility-aware runtime warnings.

Logos Module Build Loop

Use this skill when the builder already knows the module shape and needs a reliable path to build, inspect, package, install, validate, and debug it.

Quick start

• Read references/build-commands.md for nix, ws, lm, logoscore, and nix run usage.
• Read references/packaging-and-install.md before giving lgx, lgpm, Basecamp, or manual install guidance.
• Read references/compatibility-matrix.md before recommending runtime validation on a specific setup.
• Read references/workspace-override-loop.md when the builder is working inside logos-workspace.

When working in logos-workspace, the CLAUDE.md there has comprehensive ws CLI reference, repo groups, override patterns, and tool documentation. Prefer it over bundled references for commands.

Workflow

1. Confirm the module shape and target runtime are already known.
2. Build in the cheapest correct path first:
   • nix build
   • ws build <repo> --auto-local when the workspace is the active environment
3. Inspect before runtime:
   • Check build outputs
   • lm metadata <plugin> and lm methods <plugin> --json
   • Check generated package artifacts
4. Choose the right runtime validation path:
   • logoscore for core
   • nix run for standalone-capable ui_qml
   • Basecamp load or install only after package and compatibility assumptions are explicit
5. Choose the install path deliberately:
   • Package-manager and LGX path first when the runtime expects it
   • Manual file-copy only as an explicit fallback with caveats
6. Surface compatibility warnings before runtime testing (see below).
7. Provide reset, cleanup, or retry loops when iterating on Basecamp or logos_host.

Runtime warnings (from validated testing)

These findings come from ground-truth runtime evaluation:

• PluginInterface vs LogosProviderBase -- these are not interchangeable in every runtime. A module targeting one may crash on a runtime expecting the other.
• Public Basecamp releases reject user-installed modules. GitHub releases #80-#111 did not discover file-dropped or lgpm-installed modules. Only Nix-built local apps reliably discovered them.
• LGX packaging works but has a variant naming bug. The builder produces linux-amd64-dev but some runtimes expect linux-amd64.
• CMake variable documentation gap. LOGOS_CPP_SDK_ROOT and LOGOS_MODULE_ROOT must be set but are not always documented. Nix handles this automatically; manual CMake builds must discover them.
• Basecamp does not hot-reload. After rebuilding an LGX: kill all basecamp processes (including orphaned logos_host children), remove installed module dirs, relaunch.
• pkill returns exit code 1 if no processes match. Use ; not && when chaining cleanup commands.
• Basecamp expects <name>.so but CMake produces <name>_plugin.so. Workaround: postInstall hook in flake.nix.

Basecamp reset procedure

pkill -9 -f 'logos_host|logos-basecamp|\.logos_host\.elf'
rm -rf "$HOME/.local/share/Logos/LogosBasecamp/modules/<module_name>"
rm -rf "$HOME/.local/share/Logos/LogosBasecamp/plugins/<plugin_name>"
# Relaunch basecamp

For a full reset: rm -rf "$HOME/.local/share/Logos/LogosBasecamp" -- basecamp re-preinstalls bundled modules on next launch.

Reference map

• references/build-commands.md -> nix, ws, lm, logoscore, and nix run
• references/packaging-and-install.md -> lgx, lgpm, Basecamp install, and manual fallback
• references/compatibility-matrix.md -> runtime and install-path drift warnings
• references/workspace-override-loop.md -> workspace --auto-local and --override-input loop

Quality rules

• Inspect before runtime whenever possible.
• Prefer package-manager and LGX paths over undocumented file-drop assumptions.
• Keep lm, logoscore, lgx, lgpm, ws, Basecamp install/reset, and compatibility warnings explicit.
• Use current runtime behavior and concrete artifacts as the source of truth.
• Do not promise runtime success when the active environment may be incompatible.
• Prefer the target project's CLAUDE.md for build and CLI commands over bundled references.