Development guide

Repository map

daemon/                         Bare daemon, QVAC master, voice, D-Bus
computer-use/                   observe/act session and host helpers
skills/                         harness tool adapters
apps/gnome-extension/           GNOME Shell ESM UI, HUD, and brand/
apps/control-center/            GTK4/libadwaita settings application
vendor/agent-harness/           copied cognitive core
dbus/                            introspection XML
packaging/                      installer, Bare launcher, artifacts
systemd/user/                    checkout development service
docs/                           maintained technical documentation
test/                            Node acceptance/unit fixtures

Brand tokens and SVG marks live under apps/gnome-extension/[email protected]/brand/. test/brand.test.js and test/license.test.js cover palette, AGPL/HoneyPeer, and St-safe HUD CSS.

Change workflow

Read the relevant architecture and safety contract.
Keep QVAC calls behind the master.
Keep Shell code asynchronous and presentation-only.
Add or update a focused test for changed behavior.
Run the local checks and update docs/roadmap status.
Use a descriptive Gitea commit and let CI validate the push.

Adding a QVAC capability

Add the capability to skills/catalog.js, implement its adapter in the appropriate skill module, add the master operation to the allowlist if needed, define its permission and unavailable states, and document the model/resource requirements. Never import @qvac/sdk from a skill.

Adding a desktop action

Prefer a structured GSettings, GIO, app D-Bus, or AT-SPI action. Only add a coordinate path when semantic access is unavailable. Computer-use actuation must emit a highlight and audit event and must pass the active grant and safety checks.

Commit and review expectations

Reviews should check single-master ownership, GPU enforcement, privacy retention, permission gates, lock-screen behavior, and truthful unavailable states. Release-affecting changes should include a migration note and a package smoke-test result.

2.1 KiB Raw Blame History