# Development guide

## Repository map

```text
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 and agent-workspace/
dbus/                            introspection XML
packaging/                      installer, Bare launcher, artifacts
systemd/user/                    checkout development service
docs/                           maintained technical documentation
test/                            Node acceptance/unit fixtures
```

Live agent memory lives in `~/.local/share/jarvis/workspace`, seeded from
`vendor/agent-harness/agent-workspace`. Brand tokens and SVG marks live under
`apps/gnome-extension/jarvis@qvac.local/brand/`. `test/brand.test.js` and
`test/license.test.js` cover palette, AGPL/HoneyPeer, and St-safe HUD CSS.

## 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.