docs: document Flatpak integration, add guide for socket access, and remove obsolete test utility

Author: shanefagan

docs/todo.md

@@ -3,7 +3,7 @@
 ## Phase 5: Ecosystem & Context Maturity
 - [x] **System Diagnostics**: Gathers RAM, CPU, GPU, and API info with long-term caching (5m).
 - [x] **Dynamic Hardware Detection**: Use udev database for vendor-neutral GPU/peripheral reporting.
-- [ ] **Flatpak Integration**: Document and test the "Socket Export" strategy for allowing Flatpak-based OBS to query the daemon.
+- [x] **Flatpak Integration**: Documented the "Socket Export" strategy in `examples/FLATPAK.md`.
 
 ## Phase 6: Packaging & CI
 - [x] **GitHub Actions Workflow**: Automate build, test, and portable tree assembly.
@@ -14,4 +14,5 @@
 - [x] **Portable Service Hardening**: Refine the sandbox to work across different distro library versions.
 
 - [x] **Logo & Identity**: Create a simple icon/logo for the project.
+- [x] **Interface Refactoring & Cleanup**: Moved generated code to `OUT_DIR` and implemented `DynamicInterface` for `get_description` parity.
 

examples/FLATPAK.md

@@ -0,0 +1,43 @@
+# Flatpak Integration with `contextd`
+
+Applications running inside a Flatpak sandbox can still interact with `contextd`, but they must be granted permission to access the Unix domain sockets exposed by the daemon.
+
+## Granting Access
+
+To allow a Flatpak application to communicate with `contextd`, you need to expose the directory containing the sockets.
+
+### 1. For the Public Sockets (Core & RGB Observer)
+The public sockets live in `/run/contextd/public`. Most applications (like OBS or game overlays) only need read access to this directory to query the active game or observe lighting vibes.
+
+**Via Command Line:**
+```bash
+flatpak override <app-id> --filesystem=/run/contextd/public:ro
+```
+
+**In a Flatpak Manifest (JSON):**
+```json
+"finish-args": [
+    "--filesystem=/run/contextd/public:ro"
+]
+```
+
+### 2. For the Private Socket (RGB Control)
+The RGB Control socket lives in `/run/contextd/private`. Only authorized lighting controllers should have access to this.
+
+**Via Command Line:**
+```bash
+flatpak override <app-id> --filesystem=/run/contextd/private:rw
+```
+
+**In a Flatpak Manifest (JSON):**
+```json
+"finish-args": [
+    "--filesystem=/run/contextd/private:rw"
+]
+```
+
+## Security Note
+
+Since `contextd` uses Varlink over Unix sockets, the security is handled at the filesystem level. By granting access to the `/run/contextd` subdirectories, the Flatpak application is able to see and connect to the sockets just like a native host application.
+
+The daemon itself uses file permissions on the sockets (typically `0666` or restricted by group) to further manage access, but the Flatpak sandbox requires the explicit filesystem mount to even see the socket nodes.

examples/README.md

@@ -28,6 +28,10 @@ A minimal C example demonstrating how to use POSIX sockets to send a Varlink JSO
 - **`c/get_active_game.c`**: Pure C with no external dependencies (uses standard `sys/socket.h` and `sys/un.h`).
   *Compile and run:* `gcc c/get_active_game.c -o get_active_game && ./get_active_game`
 
+## Flatpak Integration
+If you are developing a sandboxed application (like a Flatpak), you need to grant it access to the daemon's sockets.
+- See [FLATPAK.md](FLATPAK.md) for manifest configuration and command-line overrides.
+
 ## Socket Paths
 Remember the daemon exposes three interfaces:
 1. **Core Socket**: `/run/contextd/public/contextd.socket`