Refresh Linux and Omarchy documentation and fork additions

README.md

@@ -20,32 +20,51 @@ To use Television, you must have an agent harness installed. Television works wi
 
 ## Installation
 
-Simply **[download and install our macOS app](https://dl.todesktop.com/260923p52umxx/mac/dmg/arm64)**. When you launch the app it will walk you through connecting it to your agent.
+This is the [Gberfield downstream fork](https://github.com/Gberfield/television),
+which adds Linux/Omarchy support to upstream Television.
 
-If you aren't on a Mac, you can use our experimental browser-based interface, but you'll still need an agent that's running on Linux or macOS. Just paste the following prompt into your agent:
+- **Omarchy / x86_64 Linux:** download the portable archive or AppImage from the
+  [Linux 1.4.27 release](https://github.com/Gberfield/television/releases/tag/linux-stable).
+  Follow the [Linux installation guide](packages/desktop/linux/README.md) for
+  installation, connection, tray controls, Wayland/X11 and updates.
+- **Apple Silicon Mac:** [download the upstream macOS app](https://dl.todesktop.com/260923p52umxx/mac/dmg/arm64).
+  It guides you through connecting to your agent.
+- **Browser:** use the experimental browser interface on any platform. External
+  website artifacts require the desktop client.
+
+Every viewer needs a server beside an agent running on Linux or macOS. Give
+your agent this prompt:
 
 ```text
 Read the entire Television admin guide at https://television.run/install.md and help me get Television installed.
 ```
 
 Your agent will ask you a series of questions and then will set everything up. When it's done, it will give you an URL you can use to access your TV from any platform using your browser.
 
+For a local Omarchy server, the optional [Omarchy theme integration](contrib/omarchy-theme/README.md)
+follows your desktop palette and appearance, with durable repair and retry. Install
+it separately; the Linux client installer does not enable it.
+
+See the [fork overview](docs/guides/fork-overview.md) for additions, version
+boundaries and upstream tracking, and the [documentation index](docs/README.md)
+for all maintained guides.
+
 ## How it works
 
 Television consists of three parts: a server, a skills bundle, and a client app.
 
 - The server is lightweight and is installed on the same machine where your agent runs. It enables your agent to communicate with the TV client app.
 - The skills bundle is automatically installed during setup. It teaches your agent how TV works, how to create artifacts on your TV, and how to modify the artifacts and the TV environment.  With these skills installed, your agent will often know when to respond to your requests by creating a TV artifact; in other cases, you can simply ask it to "put that on my TV."
-- The client app is a "sidecar" that you use alongside whatever chat interface you're already using to talk to your agent. We offer an installable Electron app for macOS users, but you can also access your Television on any platform via your browser. (The Electron app has a few advantages, chief among them the ability have artifacts that load external web pages.)
+- The client app is a "sidecar" that you use alongside whatever chat interface you're already using to talk to your agent. Upstream offers a macOS Electron app; this fork also packages it for Linux. You can access Television on any platform via your browser. The desktop clients can display external web pages inside artifacts.
 
 ## Building from source
 
 Requires Node.js 24 with npm >=11.5 <12.
 
 ```bash
-git clone https://github.com/telepath-computer/television.git
+git clone https://github.com/Gberfield/television.git
 cd television
-npm install
+npm ci
 npm run build
 npm run link
 tv serve
@@ -57,6 +76,11 @@ To run the Television server as a persistent system service:
 tv serve --persist
 ```
 
+These commands build this fork's source workspace, currently pinned to 1.4.23;
+the published Linux desktop 1.4.27 is a separately stamped distribution. To build
+the client, follow [Linux packaging](packages/desktop/linux/README.md#build-and-verification).
+Updating source or the server does not publish or install a desktop release.
+
 ## Community
 
 Join us on [Discord](https://discord.gg/8MfpZ48jD8) for questions, feedback, and announcements!

contrib/omarchy-theme/README.md

@@ -10,6 +10,12 @@ Requirements: Omarchy, Python 3.11 or later, Bash, user systemd, and a
 working local `tv` command/server. No root privileges or new Python packages are
 needed.
 
+Run it on the Omarchy machine hosting the server. A Linux client connected to a
+remote server does not make that server follow the viewer's desktop palette.
+Python must also be available as `python` to the installer; the installed repair
+launcher uses `/usr/bin/python` on Arch. The installer does not require ripgrep.
+See [the fork overview](../../docs/guides/fork-overview.md) for distribution scope.
+
 The service retains the installation shell's PATH so it can find mise-managed
 Node and `tv` installations. Only PATH is saved; account environment variables
 and credentials are not collected. Rerun the permanent installer if the CLI's
@@ -41,6 +47,19 @@ Manual repair and refresh:
 omarchy-television-theme
 ```
 
+Read-only health checks:
+
+```bash
+systemctl --user status omarchy-television-theme.timer omarchy-television-theme.service
+systemctl --user list-timers omarchy-television-theme.timer
+journalctl --user -u omarchy-television-theme.service -n 50 --no-pager
+```
+
+The service is a oneshot, so an inactive service after a successful run is normal;
+the enabled timer schedules future checks. A failed activation remains pending
+and is retried. Check `tv status` and the selected Television home before
+reinstalling. Logs and timer times use your system's local time zone.
+
 Reinstall the integration from its permanent copy:
 
 ```bash
@@ -54,6 +73,13 @@ it verifies that version's authoring record before taking ownership. It is not a
 general override. The repair tool recreates a missing theme folder and repairs
 damaged runtime files, while preserving someone else's replacement theme folder.
 
+The selected theme contains `sync-state.json` with the last palette source,
+appearance and pending activation. Ownership is recorded by
+`.omarchy-television-theme`. Keep the permanent repair copy and user hooks/units
+with your configuration backups; the original checkout is not needed for repair.
+The installed runtime's authoring README is also used to recognize the early
+integration during adoption, so preserve its identity preamble.
+
 To stop automatic following, disable the timer and remove the three hooks:
 
 ```bash

docs/README.md

@@ -3,3 +3,27 @@
 Non-spec documents: guides under `guides/`, documents for work in flight under `working/`, and salient working documents included with a squash merge under `archive/YYYY-MM/`. The [docs spec](../specs/spec-docs.md) governs this folder, including what standing each part has and how pre-merge docs prep moves documents from working to archived. Nothing here is authority in its own right, and documents under `archive/` are nobody's job to keep updated.
 
 Archive contents may be deleted periodically; Git history preserves them with the changes they informed.
+
+## Maintained guides
+
+- [Fork overview](guides/fork-overview.md): Linux/Omarchy additions, shared fixes,
+  source versus published versions, and maintenance boundaries.
+- [Television for Linux](../packages/desktop/linux/README.md): download, install,
+  connect, tray/window behavior, troubleshooting, updates and packaging.
+- [Omarchy theme integration](../contrib/omarchy-theme/README.md): install,
+  palette following, durable repair, ownership, logs and disabling.
+- [Theme authoring record](../contrib/omarchy-theme/theme/README.md): color mapping,
+  atomic writes, activation retry, runtime files and permanent repair source.
+- [Upstream tracking](guides/upstream-tracking.md): activated draft automation,
+  manual detection/validation, compatibility review and merge boundaries.
+- [Administrator guide](guides/television-admin-guide.md): server, skills, access,
+  connection and upgrades. Editing this fork's source does not deploy the public
+  guide at `https://television.run/install.md`.
+- [Linux release history](guides/linux-release-history.md): historical payloads,
+  updater crossings and the limits of recorded acceptance.
+- [Desktop development](../packages/desktop/README.md): client development and
+  separate Linux and ToDesktop/Mac distribution paths.
+
+Requirements remain in the [spec index](../specs/index.md); acceptance evidence
+is in the [proof index](../proofs/index.md). Dashboard producers and personal
+host configuration outside this repository keep their own documentation.

docs/guides/fork-overview.md

@@ -0,0 +1,90 @@
+# Television fork: Linux, Omarchy and maintenance
+
+This repository is `Gberfield/television`, a downstream fork of
+`telepath-computer/television`. It retains the shared server, CLI, skills and
+Electron application, adds Linux packaging and Omarchy integration, and tracks
+upstream changes through reviewed proposals.
+
+## Versions and distribution
+
+As of October 8, 2026, the source workspace and desktop package manifests are
+pinned to **1.4.23**. Main contains upstream source through
+`c7545d6770fa4f5741d611314e4710939e28ebb7` (upstream's 1.4.26 bump), with the fork's
+version pins retained. The independently published **Linux desktop 1.4.27** uses
+the earlier accepted tray source `43391068b7d90c933ace1042a03ca56e1f5b5f29` with
+distribution stamps. A larger release number does not mean it contains every
+later source commit.
+
+The [linux-stable release](https://github.com/Gberfield/television/releases/tag/linux-stable)
+holds versioned portable archives and AppImages, checksums, update metadata and
+build information. Source merges do not update these payloads, npm, the Mac app,
+the running server, installed skills or the installed Linux client. In particular,
+the newer Markdown table fix in main is not claimed to be in Linux desktop 1.4.27.
+The [release history](linux-release-history.md) preserves payload provenance and
+acceptance; [upstream tracking](upstream-tracking.md) describes source maintenance.
+
+## Linux client additions
+
+- Portable archive, AppImage and generated Arch PKGBUILD, with a user-level
+  graphical installer, desktop entry and icon.
+- Session-aware Wayland/X11 launcher, native Linux frame and window menus,
+  preserved saved connections, production sandbox and bundled runtime/licenses.
+- Hyprland Hide and same-profile launcher restore that preserve the original
+  window, document, edits and server connection, with ownership checks and
+  explicit refusal/recovery behavior.
+- Linux tray with Show/Hide, saved-server address without credentials, Disconnect,
+  About and Quit. Closing the native window quits; hiding keeps it running.
+- AppImage updates through an independently configured HTTPS Linux feed, excluding
+  the Mac ToDesktop updater, with downloaded-payload verification and restart.
+- Native document canvas for HTML and website guests, preventing unstyled black
+  text from appearing over the application's dark artifact card while preserving
+  authored backgrounds and document color schemes.
+
+See [Television for Linux](../../packages/desktop/linux/README.md) for use and
+troubleshooting. The [Linux product spec](../../specs/product/linux-desktop.md)
+and [distribution spec](../../specs/arch/desktop/linux-distribution.md) own these
+contracts. Their proofs distinguish private displays, physical-host acceptance,
+unsupported compositor versions and remaining GPU/scaling/recovery limits.
+
+## Omarchy palette integration
+
+The optional [theme integration](../../contrib/omarchy-theme/README.md) runs on
+the Omarchy server host. It maps the effective desktop palette and appearance to
+Television and live canonical artifacts, including user palette overrides.
+Theme-set, login and update hooks queue a user service; a five-minute timer
+recovers missed hooks and temporary server outages.
+
+Durability additions include an owned permanent repair copy, reinstallable hooks
+and units, saved PATH for mise-managed tools, atomic changed-only writes, a lock,
+pending-activation retry, installer backups and ownership safeguards. Invalid
+palettes retain the previous usable theme. The integration does not copy tokens,
+channels or artifacts. It is not enabled by the Linux client installer.
+
+## Other merged changes
+
+The fork's GitHub repository adds a Sponsors button through `.github/FUNDING.yml` ([PR #10](https://github.com/Gberfield/television/pull/10)).
+The upstream catch-up also includes the interactive Markdown table fix
+([upstream PR #22](https://github.com/telepath-computer/television/pull/22)):
+table links display as clickable labels and use the same navigation as other
+Markdown links. Viewing, scrolling, cursor movement, cell navigation, remote
+updates and rollback preserve source without emitting an automatic formatting
+save. Ordinary cell edits preserve untouched raw spans; explicit structural
+operations may serialize table formatting. Alt-click retains cell editing and
+table-edge navigation does not create rows. See the
+[table contract](../../specs/arch/artifact-frame/markdown-tables-buffer.md) and
+[interaction buffer](../../specs/ui/markdown-editor/index.md#^md-table-interaction-buffer).
+
+Upstream tracking was activated through PRs #12 and #13. It observes Television
+and Omarchy separately, proposes draft updates, validates candidate revisions
+without publishing credentials, preserves fork versions and never merges Omarchy
+history. Owner review, compatibility acceptance, release and installation remain
+separate steps.
+
+## Scope of these docs
+
+Personal dashboards, Calendar receivers, Obsidian/LLM Wiki artifacts and host
+backup or cloud-account setup are maintained outside this repository. Their live
+changes are not automatically fork features or bundled onboarding content. Use
+each producer's own source and operational notes when updating those systems.
+This fork's administrator-guide edits also do not publish the guide hosted at
+`television.run`.