48 lines
1.9 KiB
Markdown
48 lines
1.9 KiB
Markdown
# Development guide
|
|
|
|
## Repository map
|
|
|
|
```text
|
|
daemon/ Node 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 and Shell bridge
|
|
apps/control-center/ GTK4/libadwaita settings application
|
|
vendor/agent-harness/ copied cognitive core
|
|
dbus/ introspection XML
|
|
packaging/ installer, service, artifacts, release API
|
|
systemd/user/ checkout development service
|
|
docs/ maintained technical documentation
|
|
test/ Node acceptance/unit fixtures
|
|
```
|
|
|
|
## Change workflow
|
|
|
|
1. Read the relevant architecture and safety contract.
|
|
2. Keep QVAC calls behind the master.
|
|
3. Keep Shell code asynchronous and presentation-only.
|
|
4. Add or update a focused test for changed behavior.
|
|
5. Run the local checks and update docs/roadmap status.
|
|
6. 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.
|