diff --git a/INSTALL.md b/INSTALL.md index fa1a1c0..77f0014 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,14 +1,14 @@ -# installing solstone-linux +# Installing solstone-linux -these instructions are for a coding agent and human working together. sol for -Linux experiences your screen and audio along with you using PipeWire and -GStreamer, and syncs segments to your journal. +These instructions are for a coding agent and human working together. The +solstone app on linux takes in what you share with it using PipeWire and +GStreamer, and all of it goes into your journal. -your journal must already be available. if it is not, start there: -https://solstone.app/install. create a pair link for this device in your journal +Your journal must already be available. If it is not, start there: +https://solstone.app/install. Create a pair link for this device in your journal and save it as `pair-link.txt`. -## system dependencies +## System dependencies **Fedora:** ``` @@ -30,9 +30,9 @@ sudo pacman -S libpulse gstreamer gst-plugins-base gst-plugins-good gst-plugin-p sudo zypper install libpulse0 gstreamer gstreamer-plugins-base gstreamer-plugins-good gstreamer-plugin-pipewire pipewire-pulseaudio xdg-desktop-portal xdg-utils ``` -## install a release +## Install a release -use the Debian or RPM package published for your distribution when available. +Use the Debian or RPM package published for your distribution when available. The portable installer is in the matching release source checkout, not inside the archive: @@ -50,25 +50,26 @@ matching release source. Alternatively, extract the archive, copy beneath the same installation prefix before running the service and setup commands. -the archive includes `INSTALL-NOTES`, which is the canonical cross-distribution +The archive includes `INSTALL-NOTES`, which is the canonical cross-distribution runtime dependency list. Native packages install the same binary and icon set. The service command writes the systemd user unit and desktop autostart entry, -enables the unit, and starts sol. +enables the unit, and starts the solstone app. -pairing is the only setup path: +Pairing is the only setup path: ```bash solstone-linux setup < pair-link.txt ``` -the pair link comes from your journal. a journal on the same machine uses the -same private link as any other journal. there is no URL, key, local installation -of the journal or Python, or direct fallback to configure. sol can continue -capturing while unpaired or offline and saves segments locally. +The pair link comes from your journal. A journal on the same machine uses the +same private network path as any other journal. There is no URL, key, local installation +of the journal or Python, or direct fallback to configure. The solstone app can +continue taking in what you share while unpaired or offline. That material goes +into your journal once the connection is available. -## build from source +## Build from source -install rustup, a C toolchain, CMake, pkg-config, GLib/GStreamer development headers, and PulseAudio development headers. Then: +Install rustup, a C toolchain, CMake, pkg-config, GLib/GStreamer development headers, and PulseAudio development headers. Then: ```bash git clone https://github.com/solpbc/solstone-linux.git @@ -82,9 +83,9 @@ systemctl --user start solstone-linux ``` `rust-toolchain.toml` selects the exact compiler, components, and target. `make -install` explicitly establishes them and cargo-deny before installing sol. +install` explicitly establishes them and cargo-deny before installing the app. -## update from source +## Update from source ```bash git pull @@ -95,26 +96,26 @@ solstone-linux setup < pair-link.txt systemctl --user start solstone-linux ``` -setup and runtime deliberately share one private-state lock. stop sol before -pairing. if sol is running, setup exits before consuming any input and leaves -capture, config, and private state unchanged. +Setup and runtime deliberately share one private-state lock. Stop the solstone app before +pairing. If the solstone app is running, setup exits before consuming any input and leaves +intake state, configuration, and private state unchanged. -## verify +## Verify ```bash systemctl --user status solstone-linux solstone-linux status ``` -## desktop notes +## Desktop notes -Activity detection uses screen-lock and power-save signals to notice when you step away. GNOME provides both signals; KDE Wayland provides screen lock; X11 can also provide DPMS power save. Where neither signal is available, solstone-linux still experiences your screen and audio, but activity-based segment boundaries do not trigger. +Activity detection uses screen-lock and power-save signals to notice when you step away. GNOME provides both signals; KDE Wayland provides screen lock; X11 can also provide DPMS power save. Where neither signal is available, the solstone app on linux still takes in what you share and that material goes into your journal, but activity-based segment boundaries do not trigger. The tray uses the StatusNotifierItem D-Bus protocol. KDE supports it directly. -GNOME requires an AppIndicator extension; without an SNI host, sol continues +GNOME requires an AppIndicator extension; without an SNI host, the solstone app continues normally without a tray icon. -## historical note: version 0.4.5 +## Historical note: version 0.4.5 -version 0.4.5 was the final pre-native Python release. current installation uses +Version 0.4.5 was the final pre-native Python release. Current installation uses the native Debian, RPM, or portable package described above. diff --git a/README.md b/README.md index bee6650..664f8b3 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,9 @@ # solstone-linux -sol for Linux experiences your screen and audio along with you on a GNOME -Wayland session, stores segments locally, and syncs them to your journal on -[solstone](https://solpbc.org). +The solstone app on linux takes in what you share with it on a GNOME Wayland +session; all of it goes into your journal, which lives on a device you own. -**Note:** Activity detection uses screen-lock and power-save signals to notice when you step away. Coverage varies by desktop: GNOME provides both signals; KDE (Wayland) provides screen lock only; any X11 session also provides DPMS power save; other Wayland desktops provide screen lock where the compositor exposes it. Where neither signal is available, solstone-linux still experiences your screen and audio, but activity-based segment boundaries won't trigger. +**Note:** Activity detection uses screen-lock and power-save signals to notice when you step away. Coverage varies by desktop: GNOME provides both signals; KDE (Wayland) provides screen lock only; any X11 session also provides DPMS power save; other Wayland desktops provide screen lock where the compositor exposes it. Where neither signal is available, the solstone app on linux still takes in what you share and that material goes into your journal, but activity-based segment boundaries will not trigger. ## System dependencies @@ -53,10 +52,10 @@ to a directory on `PATH` and `share/icons/hicolor` beneath the same prefix. The archive includes `packaging/INSTALL-NOTES`, the canonical runtime-dependency list. See `INSTALL.md` for package installation, tray notes, and troubleshooting. Pairing is the only setup path. The pair link comes from your journal. A journal -on the same machine connects through the same private link as any other journal; -there is no URL, key, local Python installation, or direct fallback to configure. -Sol can continue capturing while unpaired or offline and will save segments -locally. +on the same machine connects through the same private network path as any other journal; +There is no URL, key, local Python installation, or direct fallback to configure. +The solstone app can continue taking in what you share while unpaired or offline. +That material goes into your journal once the connection is available. ### Developers building from source @@ -75,9 +74,9 @@ systemctl --user start solstone-linux solstone-linux setup < pair-link.txt ``` -Setup and runtime deliberately share one private-state lock. Stop sol before -pairing. If sol is running, setup exits before consuming the pair link and leaves -capture, config, and private state unchanged. +Setup and runtime deliberately share one private-state lock. Stop the solstone app before +pairing. If the solstone app is running, setup exits before consuming the pair link and leaves +intake state, configuration, and private state unchanged. For an upgrade that needs a new pair link: @@ -100,18 +99,14 @@ solstone-linux run solstone-linux status ``` -Paired devices also include a diagnostics-only status beacon in your journal: -identity, version, uptime, and sync liveness counts only, with none of the -screen or audio sol experiences with you. +## Protocol contract -## Observer contract +The `observer-client` contract is owned by the journal and frozen here as a byte-exact, language-neutral bundle at `vendor/observer-client-contract/`. This app adopts bundle version 1.0.2 and verifies it offline with `make check-observer-contract`. -The observer-client contract is owned by the solstone journal and frozen here as a byte-exact, language-neutral bundle at `vendor/observer-client-contract/`. This observer adopts bundle version 1.0.2 and verifies it offline with `make check-observer-contract`. - -The bundle version, the solstone-linux application release, and observer wire-protocol version 2 are independent versions. When the observer and authority disagree, resolve the incompatibility at the journal authority first; do not rewrite the vendored contract or weaken consumer conformance. +The bundle version, the solstone-linux application release, and wire-protocol version 2 are independent versions. When the app and authority disagree, resolve the incompatibility at the journal authority first; do not rewrite the vendored contract or weaken consumer conformance. See `contracts/README.md` for the verified import ritual and public provenance record. ## License -AGPL-3.0-only — Copyright (c) 2026 sol pbc +AGPL-3.0-only. Copyright (c) 2026 sol pbc.