# JARVIS-QVAC documentation

JARVIS-QVAC is a local-first voice and computer-use assistant for Ubuntu GNOME.
This directory is the maintained technical reference for the repository.

## Start here

| Need | Document |
| --- | --- |
| Understand the system | [Architecture](architecture.md) |
| Run it locally | [Operations](operations.md) and [Local demo](local-demo.md) |
| Understand the voice loop | [Voice pipeline](voice-pipeline.md) |
| Build desktop control | [Computer use](computer-use.md) |
| Integrate QVAC | [QVAC runtime](qvac-runtime.md) |
| Run the packaged runtime | [Bare runtime](bare-runtime.md) |
| Understand the agent | [Harness integration](harness-integration.md) |
| Use the D-Bus API | [API reference](api.md) |
| Build and release with Gitea | [CI and releases](ci-gitea.md) |
| Review privacy and safety | [Security and privacy](security-privacy.md) |
| Test changes | [Testing](testing.md) |
| Diagnose failures | [Troubleshooting](troubleshooting.md) |
| Track implementation | [Roadmap](ROADMAP.md) |

## Runtime promise

The project has one cognition loop and one QVAC authority. `jarvisd` owns the
QVAC SDK worker, model lifecycle, GPU policy, scheduler, and cancellation. The
vendored harness supplies planning, sessions, memory, and tool-loop behavior.
The GNOME Shell extension only renders state and forwards desktop facts. It
does not load models or perform inference.

```mermaid
flowchart LR
  U[User] --> G[GNOME Shell extension]
  G <--> D[jarvisd]
  D --> H[Vendored agent harness]
  D --> Q[Single QVAC master]
  D --> C[Computer-use backend]
  D --> A[PipeWire audio]
  Q --> GPU[GPU inference]
```

## Implementation truth

The roadmap distinguishes implemented behavior (`[x]`), partial behavior
(``[~]``), and planned behavior (`[ ]`). A doctor command or acceptance test
is the source of truth for host-dependent capabilities. In particular, GPU
visibility, wake-word bridge availability, portal consent, and live EIS input
must be verified on the target GNOME session.

## Documentation conventions

- Commands are run from the repository root unless stated otherwise.
- Paths beginning with `~` are user-scoped paths.
- `jarvisd` means the user service and its packaged Bare process.
- “Master” means the singleton in `daemon/qvac-master.js`.
- Mermaid diagrams use Gitea-compatible fenced Markdown.

Jarvis is released by HoneyPeer, LLC under the GNU Affero General Public
License v3 or later. See [LICENSE](../LICENSE) and [COPYRIGHT](../COPYRIGHT).

- [Settings and voice customization](settings.md)