R1

2026-09-11 14:55:34 -04:00
parent 660294d0aa
commit 25b2c4be2e
33 changed files with 1293 additions and 34 deletions
@@ -0,0 +1,56 @@
+# 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) |
+| 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 Node process.
+- “Master” means the singleton in `daemon/qvac-master.js`.
+- Mermaid diagrams use Gitea-compatible fenced Markdown.