logos-co

Create a Logos full app — a combined module + UI app project in a single root directory

Activate when creating a new Logos module with the universal C++ interface. Covers scaffolding, metadata.json, flake.nix with code generator, CMakeLists.txt, and the pure C++ impl header.

Activate when configuring Nix flake.nix for a Logos module. Covers flake inputs, follows declarations, preConfigure for code generation, mkLogosModule, overrides for local development, and workspace integration.

Activate when packaging a Logos module or UI app for distribution as an LGX package. Covers lgx create, adding platform variants, verification, portable builds, and installation via lgpm.

Activate when writing tests for Logos modules. Covers the logos-test-framework (LOGOS_TEST macros, LogosTestContext, module mocking, C library mocking, event testing), logos_test() CMake integration, logoscore integration tests, and Nix check configuration.

Activate when wrapping an external C or C++ library as a Logos universal module. Covers external_libraries in metadata.json, flake input configuration, extern C includes, and the Go library special case.

Activate when registering a new module in the logos-workspace. Covers adding git submodules, flake.nix inputs with follows declarations, scripts/ws REPOS array, repo groups, and dep-graph.nix regeneration.

Activate when implementing inter-module communication in Logos. Covers LogosAPI::callModule(), LogosResult handling, dependency declaration in metadata.json, generated client stubs, and the QML bridge.

Use when the user wants to create, extend, or debug a Logos core module and needs concrete guidance for metadata.json, flake.nix, CMakeLists.txt, mkLogosModule, code generation, external-library wrapping, inter-module calls, and logoscore-friendly validation.

Use when the user needs to discover the right Logos repo, choose a module, inspect a repo before editing, decide on a module shape, plan Basecamp integration, or operate logoscore. This is the single entry skill for Logos orientation, routing, and pre-build decisions.

Use when the user wants to run a documented Logos operator flow such as the LEZ wallet and token workflows, blockchain node quickstart, delivery API compose stack, chat demo, AnonComms mixnet demo, app-alpha build, or headless-node logoscore subset. Covers all docs-backed journeys with explicit gap handling.

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.

Use when the user wants to bootstrap a standalone Logos Scaffold project, choose between the default and LEZ framework templates, understand the required first-success path, or reason about Scaffold's localnet, wallet, deploy, doctor, and report flows without guessing from the CLI surface.

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.

Surface a build-time value from metadata.json (e.g. version) into the QML UI, since the `logos` QML bridge exposes no module metadata. Threads the value through CMake (string(JSON …) + a compile definition) → a READONLY .rep PROP set in the backend constructor → a QML `backend.<prop>` binding. Use when the UI needs to display anything held in metadata.json — version, display_name, category — kept in sync from that single source.

Make one Logos module call (and subscribe to events from) another — declaring the dependency in metadata.json + flake.nix and reaching it through the generated typed `modules().<dep>` wrapper. Covers all three authoring flavors (universal core, universal ui_qml, explicit ui_qml plugin). Use when a module needs to invoke another module's methods/events (e.g. example_forum using delivery_module, forum_ui using forum_app).

Use the Logos delivery_module (liblogosdelivery / Waku messaging) from another module — bootstrap a node, subscribe to a content topic, send a payload, and handle the message events. Covers the createNode config, the synchronous-call + async-event model, and the plain-text send/receive recipe. Use when a module needs to send/receive messages over the Logos messaging network (e.g. example_forum broadcasting on a topic).

Restyle a Logos ui_qml module's QML view with the Logos design system — swap raw QtQuick.Controls + hardcoded hex colors for Logos.Controls components and Theme.palette/spacing/typography tokens. Covers the import path (no flake.nix change), the control swaps, the color/spacing/typography token mapping, and the LogosTextField API differences. Use when a module's Main.qml is styled with bespoke colors and you want it to match the design system.

Rename a Logos C++ module end to end — every file, identifier, and config field that must change so it still builds with `nix build .`. Covers both authoring flavors: universal "core" modules (impl class only) and "ui_qml" modules (C++ backend + .rep + QML view). Use when changing a module's name (e.g. "minimal" → "broadcast_module" or "ui_example" → "broadcast_app").

Use for the `lgs` / `logos-scaffold` CLI as a whole — bootstrap a project, run setup/build/deploy/localnet/wallet/doctor/report, diagnose CLI errors, or adopt scaffold in an existing project. Covers the full CLI surface, the `.scaffold/` state layout, and error → recovery patterns. Entry point that routes into `lez-template`, `lez-framework-template`, or `basecamp` once project context is identified.

Use when running any `lgs basecamp …` subcommand or working on a Logos module project (a project that builds `.lgx` artefacts via `flake.nix#packages.<system>.lgx`). Covers `setup` / `modules` / `install` / `launch` / `build-portable` / `doctor` / `docs`, the `[basecamp.modules]` schema, per-profile XDG isolation under `.scaffold/basecamp/profiles/{alice,bob}/`, clean-slate launch semantics, two-instance p2p dogfooding, and AppImage-targeted portable builds. Activates additionally on presence of `[basecamp.modules]` in `scaffold.toml` or `.scaffold/basecamp/profiles/`. Independent of template skills.

Use when working inside a project scaffolded with scaffold's lez-framework template — Anchor-on-Solana parallel for LEZ with

Use when working inside a project scaffolded with the bare LEZ template (`lgs new` default — raw Rust + risc0 guest programs, no framework macros). Identify by scaffold.toml without `framework = "lez-framework"`, presence of `methods/guest/src/bin/*.rs`, and absence of `idl/` + `crates/lez-client-gen/`.

Activate when creating, building, testing, or modifying Logos modules — C++ Qt plugins, metadata.json config, CMake builds, LogosAPI usage, inter-module communication, code generation, packaging (LGX), or working with logos-cpp-sdk, logos-liblogos, logos-module, logos-module-builder repos.

Activate when adding a new git repo/submodule to the workspace, registering a repo in flake.nix or scripts/ws, promoting a non-flake repo to a flake repo, or the user says "add repo", "register repo", "new repo".

Activate when the user wants to merge a chain of dependent cross-repo PRs, orchestrate multi-repo PR merges, or says "merge chain", "merge PRs", "/merge-chain". Expects a logos-workspace PR as input.

Activate when creating, modifying, or extending a QML control in this repo (src/qml/Logos/Controls/). Covers base-class choice (extend Qt Quick Control vs use plain Control), public API design (open for extension, closed for modification), alias patterns for testability, unit tests, and storybook pages.