# Seven integration boundary

Vuka installs Seven from the published `v4.4.0` wheel described in `upstream/SEVEN_RELEASE.env`. The build fails on a checksum mismatch. It never clones `seven-ai`, imports `_legacy`, applies downstream patches, or writes into Seven's repository.

Vuka may provide:

- a Debian package or `/opt/vuka` virtual environment containing the verified wheel and locked dependencies;
- an XDG autostart adapter and desktop settings UI;
- an avatar/panel client talking to Seven's authenticated loopback API;
- OS-specific camera, microphone, robotics and application dependencies;
- a Vuka-owned extension and socket-activated root authority service;
- migration orchestration that calls Seven's supported CLI.

Vuka may not rewrite Seven's identity, bypass its data migration, share its API token with unrelated applications, or claim that process startup proves a greeting was heard.

## Image installation

The image build downloads the published Seven wheel plus the two pure-Python voice adapters required for an offline greeting. Every artifact URL, version and SHA-256 is pinned under `upstream/`; a checksum mismatch stops the build. Seven is installed into `/opt/vuka/seven`, using Kali-packaged runtime dependencies through a system-site-packages virtual environment. The hook uses `--no-deps` and cannot silently resolve a newer PyPI dependency.

The system-wide KDE autostart entry launches `vuka-seven-runtime` without a terminal window. That supervisor starts the default-on animated/ASCII Seven surface, starts the idempotent Ollama model bootstrap and continuously runs Seven's unchanged public `--talk` mode. It maps Seven's emitted listening/thinking/speaking lifecycle into the visible companion, restarts Seven after a failure, and restores the normal Plasma panel whenever Seven is unavailable. Plasma panel changes are asynchronous and best-effort, so a slow KDE D-Bus helper cannot terminate the voice loop. `pyttsx3` and eSpeak NG provide offline speech, while PyAudio and SpeechRecognition provide microphone input.

## Desktop and root authority

Seven deliberately has two cooperating authority planes:

1. `/usr/local/bin/seven --talk` runs as the logged-in user inside the X11 graphical session under `vuka-seven-runtime`. That process owns the display, audio session and user device access needed by Seven's published screenshot, screen-vision, keyboard, mouse, window, microphone, camera, application and serial/robotics tools. Vuka sets Seven's camera and robotics capability flags on by default; actual devices remain hardware-dependent.
2. `vuka-seven-rootd.socket` activates `vuka-seven-rootd.service` as real UID 0. Vuka's system extension registers `root_status`, `run_root`, `root_read_file`, `root_write_file` and `root_service` in Seven's full tool registry. Requests from members of the local `sudo` group cross a mode-`0660` Unix socket and are executed without a sandbox or confirmation broker.

Running the graphical process itself as root would not make it “more OS-like”; it would detach Seven from the user's desktop/audio session, create root-owned files in the user's home, and make application control less reliable. The split design gives Seven both the user's live graphical context and a genuine unrestricted root execution path.

Every root request writes a root-only record to `/var/log/vuka-seven-rootd.jsonl` and the system journal. The record includes caller identity, action, duration, result and a command digest. This is accountability, not containment: a successful root command can alter or erase the OS, its logs and its safeguards. Any process running as a `sudo`-group user can reach the same socket, so compromise of Seven or that account is equivalent to full machine compromise. This is an intentional Vuka product choice requested by its owner, and must be disclosed during onboarding.

Vuka adds no sandbox, container, capability filter or confirmation interception to either plane. X11, PyAutoGUI, `wmctrl`, `xdotool`, OpenCV, PyAudio and serial libraries are installed so Seven can act on the real session. Vuka's desktop extension also supplies non-blocking application/desktop-entry launch, X11 window focus and a combined desktop-context tool; this avoids treating a long-lived GUI child as a still-running shell command. Wayland launchers are retained under `/usr/share/vuka/disabled-wayland-sessions` for administrator recovery, but Release 1 defaults to X11 because Wayland intentionally prevents several kinds of global screen/input automation.

Seven updates are explicit version bumps: update the tag, wheel name, URL and SHA-256 together, rebuild, run Seven's installed lifecycle checks, then run Vuka's login/desktop matrix.