linux observer
docs: align README/INSTALL/AGENTS with system-anatomy canon
Replace surveillance-flavored verbs in owner-facing prose ("captures
screen and audio", "screen and audio capture works", "capture source")
with the system-anatomy canon's co-experience phrasing
("experiences your screen and audio along with you"). solstone-linux
is now framed in AGENTS.md project-overview prose as one of the
trinity's observers.
Add a "Brand canon" section to AGENTS.md pointing to
~/projects/extro/cmo/brand/system-anatomy.md, naming the banned
verbs in branded copy, and clarifying that internal architecture
vocabulary (the Capture loop, capture pipeline, module names) is
canon-permitted in code-only contexts and stays as-is.
Internal capture-loop references in AGENTS.md (lines 19, 40, 46, 69)
are unchanged. CLAUDE.md remains a symlink to AGENTS.md and rides
automatically. No source, test, or config changes.
Mirrors the precedent sweeps in the parent solstone repo
(commits ddec60d5 and 929448de).
+16
-6
+11
-1
AGENTS.md
+11
-1
AGENTS.md
···
4
4
5
5
## Project Overview
6
6
7
-
solstone-linux is a companion app that runs alongside the main [solstone](https://solstone.app) journal. It captures screen recordings and audio from a Linux desktop using PipeWire and GStreamer, stores segments locally, and syncs them to a solstone server. It runs as a systemd user service on GNOME Wayland sessions.
7
+
solstone-linux is a companion app that runs alongside the main [solstone](https://solstone.app) journal. It is one of the owner's observers — it experiences screen and audio along with the owner on a Linux desktop using PipeWire and GStreamer, stores segments locally, and syncs them to a solstone server. It runs as a systemd user service on GNOME Wayland sessions.
8
8
9
9
This is **not** part of the solstone monorepo. It is a standalone package with its own release lifecycle, installed via pipx alongside system-provided PyGObject/GStreamer bindings.
10
10
···
116
116
## Testing
117
117
118
118
Tests use pytest with standard mocking. No system dependencies required for tests — audio devices, DBus, and GStreamer are mocked. Run `make test` to execute the full suite.
119
+
120
+
## Brand canon
121
+
122
+
- **solstone-linux is an observer.** In the system anatomy, `solstone = observers + sol agent + journal`. This repo implements one of those observers.
123
+
- **The canon lives elsewhere.** Owner-facing terminology comes from `~/projects/extro/cmo/brand/system-anatomy.md`. The companion is `~/projects/extro/cmo/brand/voice-terminology.md`.
124
+
- **Use co-experience language in branded prose.** In README, INSTALL, onboarding text, settings copy, and error messages, describe solstone-linux as something that experiences screen and audio along with the owner. Never describe it as watching, recording, monitoring, or tracking the owner.
125
+
- **Keep code language in code-only contexts.** Internal architecture terms such as `Capture loop`, the capture pipeline, module names, and data-path names are canon-permitted here and must not be renamed just to match branded prose.
126
+
- **Edit with the surface in mind.** If the owner sees the string, follow the canon. If the text is naming code, pipelines, modules, or storage artifacts for engineers, the existing internal vocabulary stays.
127
+
128
+
Canon source of truth: `~/projects/extro/cmo/brand/system-anatomy.md`.
119
129
120
130
## License
121
131
+3
-3
INSTALL.md
+3
-3
INSTALL.md
···
1
1
# installing solstone-linux
2
2
3
-
these instructions are for a coding agent and human working together. solstone-linux is a standalone observer that captures screen and audio on linux desktops using PipeWire and GStreamer, and uploads to a solstone server.
3
+
these instructions are for a coding agent and human working together. solstone-linux is a standalone observer that experiences your screen and audio along with you on linux desktops using PipeWire and GStreamer, and uploads to a solstone server.
4
4
5
5
solstone must already be installed and running. if it isn't, start there: https://solstone.app/install
6
6
···
20
20
## what to sort out together
21
21
22
22
- **system dependencies.** the observer needs PyGObject, GStreamer, and PipeWire bindings from system packages. installing these requires sudo.
23
-
- **stream name.** this identifies the capture source. the machine's hostname is the typical choice.
23
+
- **stream name.** this identifies this observer's stream. the machine's hostname is the typical choice.
24
24
25
25
### remote sol
26
26
···
86
86
87
87
## notes
88
88
89
-
- activity detection (idle timeout, screen lock, power save) works on both GNOME and KDE. other desktops capture screen and audio fine but may not get activity-based segment boundaries.
89
+
- activity detection (idle timeout, screen lock, power save) works on both GNOME and KDE. on other desktops the observer still experiences your screen and audio fine, but activity-based segment boundaries won't trigger.
90
90
- the tray icon uses the StatusNotifierItem (SNI) D-Bus protocol. it works on KDE natively and GNOME with the AppIndicator extension. if no SNI host is available, the observer runs normally without a tray icon.
91
91
92
92
## appendix: GNOME tray support
+2
-2
README.md
+2
-2
README.md
···
1
1
# solstone-linux
2
2
3
-
Standalone Linux desktop observer for [solstone](https://solpbc.org). Captures screen and audio from a GNOME Wayland session, stores segments locally, and syncs to a solstone server.
3
+
Standalone Linux desktop observer for [solstone](https://solpbc.org). Experiences your screen and audio along with you on a GNOME Wayland session, stores segments locally, and syncs to a solstone server.
4
4
5
-
**Note:** Activity detection (idle timeout, screen lock, power save) currently requires a GNOME desktop. On other desktops (KDE, Sway, Hyprland, XFCE), screen and audio capture works but activity-based segment boundaries won't trigger.
5
+
**Note:** Activity detection (idle timeout, screen lock, power save) currently requires a GNOME desktop. On other desktops (KDE, Sway, Hyprland, XFCE), the observer still experiences your screen and audio, but activity-based segment boundaries won't trigger.
6
6
7
7
## System Dependencies
8
8