# Operations guide

## Prerequisites

Ubuntu GNOME 24.04 or newer, the packaged Bare runtime, PipeWire/WirePlumber,
GNOME desktop portals, GTK4/libadwaita, AT-SPI2, and a QVAC-visible GPU are
required for the full runtime. Node.js is a build and test dependency only.
See [hardware compatibility](hardware-compatibility.md).

## Web installation

For the current Gitea rolling build:

~~~bash
curl -fsSL https://git.ssh.surf/snxraven/gnome-jarvis/raw/branch/main/packaging/web-installer.sh | bash -s -- --enable
~~~

The installer downloads the self-contained Bare bundle from the `rolling`
release and delegates to the repository installer. Re-running it replaces the
previous user-local application and extension trees after stopping
`jarvisd.service`; config and data stay in place. Omit `--enable` to copy
files without starting the service unless the daemon was already running.
Use `JARVIS_SERVER`, `JARVIS_REPO`, and `JARVIS_BUNDLE_URL` for a mirror.

## Development start

```bash
npm ci
npm test
npm run gpu-doctor
npm run cu-doctor
npm run voice-doctor
bare daemon/bare-entry.js
```

Use `npm run qvac:serve:diagnostic` only when a separate local client needs the
OpenAI-compatible endpoint. Keep its host at `127.0.0.1`.

## User service

```bash
systemctl --user daemon-reload
systemctl --user enable --now jarvisd.service
systemctl --user status jarvisd.service
journalctl --user -u jarvisd.service -f
```

The packaged service uses `~/.local/share/jarvis-qvac` and the generated config
at `~/.config/jarvis/qvac.config.json`. The repository development unit uses
the checkout path; use the packaged unit when testing installation behavior.

## Extension development

```bash
gnome-extensions enable jarvis@qvac.local
dbus-run-session -- gnome-shell --nested --wayland
```

Keep inference and long-running work in `jarvisd`. Reloading the Shell is only
needed for extension changes; daemon changes can use `node --watch`.

## State and storage

| Location | Contents | Default retention |
| --- | --- | --- |
| `~/.local/share/jarvis/memory` | harness memory and RAG data | user-managed |
| `~/.local/share/jarvis/voices` | local voice references | user-managed |
| `~/.local/share/jarvis/audit` | CU action metadata and hashes | user-managed |
| `~/.cache/jarvis` | models, jobs, temporary CU state | disposable |
| `~/Jarvis` | generated media and transcripts | user-managed |

Use the uninstall script with `--yes`; add `--purge-data` only to remove the
listed Jarvis-owned data locations.