docs: t0 3 d6 public wiki boundary

.gitignore

@@ -74,6 +74,7 @@ docs/*
 !docs/ARCHITECTURE.md
 !docs/MOSAIC_IDENTITY.md
 !docs/MOSAIC_ROADMAP.md
+!docs/USER_GUIDE.md
 !docs/history/
 !docs/history/README.md
 !docs/history/CODEX_HANDOFF_PRE_D5.txt

CONTRIBUTING.md

@@ -2,8 +2,10 @@
 
 We appreciate your interest in contributing to Mosaic!
 
-Use the [documentation index](docs/README.md) to find the developer guide, pull-request workflow,
-current project state, and engineering contracts.
+Start with the [developer guide](DEVELOPMENT.md), then use the
+[documentation index](docs/README.md) to find architecture and current engineering contracts.
+Code contributors must follow the canonical [pull-request workflow](docs/PREPARE_PR.md) and
+[validation contract](docs/VALIDATION.md); this page does not redefine either process.
 
 ## Code of Conduct
 

DEVELOPMENT.md

@@ -2,6 +2,9 @@
 
 See the [Contributing](CONTRIBUTING.md) guide for general contribution information and the
 [engineering documentation index](docs/README.md) for repository workflows and architecture.
+Before publishing a change, follow [safe pull-request preparation](docs/PREPARE_PR.md). The
+[validation architecture](docs/VALIDATION.md) defines local feedback and authoritative hosted
+validation; this guide covers development setup rather than those operating contracts.
 
 ##  Overview
 

README.md

@@ -3,8 +3,6 @@
 Mosaic is a downstream Android TV client derived from
 [Wholphin](https://github.com/damontecres/Wholphin).
 
-See the [documentation index](docs/README.md) for engineering and contributor guidance.
-
 ## Installation
 
 Mosaic is currently distributed directly through GitHub Releases. [![Current Mosaic Release](https://img.shields.io/github/release/constbogdan/Mosaic.svg)](https://github.com/constbogdan/Mosaic/releases/latest)

docs/CODEX_HANDOFF.md

@@ -2,9 +2,8 @@
 
 ## Current checkpoint
 
-T0-3 documentation consolidation D1–D4 is complete. D5 is implementing canonical architecture,
-identity, roadmap, agent guidance, and bounded continuity. D6 public/Wiki work and D7 final
-consistency remain open. T0-3 and Baseline T0 are not complete.
+T0-3 documentation consolidation D1–D5 is complete. D6 is defining the public/Wiki boundary; D7
+final consistency remains open. T0-3 and Baseline T0 are not complete.
 
 Current repository identity is exactly `constbogdan/Mosaic`; upstream remains
 `damontecres/Wholphin`. Work begins from current protected `origin/main` on a purpose-specific
@@ -31,10 +30,9 @@ not current instruction.
 
 ## Immediate continuity
 
-- D5 must finish consumer-aware documentation path migration and comprehensive link, anchor,
-  classification, prepare-pr, pre-commit, and Fast validation.
-- D6 must not begin in D5. Do not create or publish Wiki content or substantially rewrite public
-  installation/help prose.
+- D6 owns public product guidance, contributor routing, and the rule that optional Wiki content
+  cannot replace versioned engineering authority. Wiki publication remains a separate operator
+  action.
 - D7 will own the final documentation consistency and status audit. Do not declare T0-3 or Baseline
   T0 complete before that separately reviewed acceptance.
 

docs/MOSAIC_ROADMAP.md

@@ -9,17 +9,17 @@ the [documentation index](README.md).
 - T0-1 validation, operator UX, and pipeline simplification — complete.
 - T0-2 bounded authority/bootstrap/diagnostic corrections — complete.
 - T0-3.0 Mosaic identity establishment — complete.
-- T0-3 documentation consolidation — D1–D4 complete; D5 in progress. D6 and D7 remain open.
+- T0-3 documentation consolidation — D1–D5 complete; D6 public/Wiki boundary is in progress and D7
+  remains open.
 
 Baseline T0 remains open until the separately defined T0-3 completion and final consistency work is
-accepted. Current D5 work does not declare either T0-3 or Baseline T0 complete.
+accepted. Current D6 work does not declare either T0-3 or Baseline T0 complete.
 
 ## Current priorities
 
-1. Finish D5 canonical architecture, identity, roadmap, agent guidance, and bounded handoff.
-2. D6: separately reviewed public/Wiki boundary work; no Wiki publication is implied.
-3. D7: final documentation consistency, link, ownership, and status audit.
-4. Resume evidence-driven product work from the feature roadmap below.
+1. Complete D6 public/Wiki boundary work; no Wiki publication is implied.
+2. D7: final documentation consistency, link, ownership, and status audit.
+3. Resume evidence-driven product work from the feature roadmap below.
 
 ## Product direction
 

docs/README.md

@@ -1,12 +1,15 @@
 # Mosaic documentation
 
 This page answers where to find Mosaic documentation. It is an index, not an operating runbook.
-Role labels distinguish current authority from continuity and point-in-time engineering evidence.
+Role labels distinguish public guidance, contributor orientation, engineering authority, current
+continuity, and point-in-time evidence.
 
 ## Start here
 
 - **Public product entry point** — [Mosaic README](../README.md): what Mosaic is, installation,
   updates, and compatibility.
+- **Public user guidance** — [Mosaic user guide](USER_GUIDE.md): installation and sideloading,
+  Stable versus Development, automatic updates, optional Seerr integration, and troubleshooting.
 - **Product roadmap** — [Mosaic roadmap](MOSAIC_ROADMAP.md): current program status, product
   direction, major completed phases, and remaining work.
 - **Current continuity** — [Codex handoff](CODEX_HANDOFF.md): current checkpoint, recent continuity,
@@ -25,6 +28,19 @@ Role labels distinguish current authority from continuity and point-in-time engi
 - **Agent guidance** — [Repository agent instructions](AGENTS.md): permanent repository-specific
   rules for coding agents.
 
+## Public and engineering boundary
+
+- **Public product documentation** — the root [README](../README.md) is the concise product entry
+  point; the [user guide](USER_GUIDE.md) owns user-facing setup, channels, and troubleshooting.
+- **Contributor orientation** — [Contributing](../CONTRIBUTING.md) and the
+  [developer guide](../DEVELOPMENT.md) explain where to start and route deeper work here.
+- **Versioned engineering authority** — architecture, validation, publication, signing,
+  repository identity, and upstream rules are owned only by the canonical repository documents
+  indexed below.
+- **Optional GitHub Wiki** — no Wiki content is currently published or maintained from this
+  repository. A future Wiki may offer user-facing summaries, but must identify and link its
+  versioned source and cannot become engineering authority.
+
 ## Current project state
 
 - **Product roadmap** — [Mosaic roadmap](MOSAIC_ROADMAP.md): where the product and engineering

docs/T0_3_DOCUMENTATION_CONSOLIDATION_PLAN.md

@@ -1,6 +1,6 @@
 # T0-3 documentation consolidation audit and plan
 
-Status: **D1-D4 COMPLETE; D5 implemented pending review. D6 has not begun.**
+Status: **D1-D5 COMPLETE; D6 implemented pending review. D7 has not begun.**
 
 This audit describes the documentation set at `main` commit
 `44564901cbdb7ffce4b1c0704aa2d53f93c40fa9`. It does not move, delete, rename, or broadly rewrite
@@ -369,5 +369,24 @@ explicit precedence back to `AGENTS.md`. Roadmap path consumers in agent guidanc
 and `prepare-pr.config.psd1` migrated to `MOSAIC_ROADMAP.md`; architecture and identity are retained
 as high-risk documentation inputs rather than weakening classification.
 
-D5 changes documentation ownership only. D6 public/Wiki work and D7 final consistency remain open;
-T0-3 and Baseline T0 are not complete.
+At D5 closure, D6 public/Wiki work and D7 final consistency remained open; T0-3 and Baseline T0
+were not complete.
+
+## D6 implementation decisions
+
+D6 keeps the root `README.md` as the concise public product entry point and creates
+`USER_GUIDE.md` as the versioned public owner for installation, updates, Stable versus Development,
+optional Seerr integration, bounded troubleshooting, and bug-reporting orientation. Contributor
+entry points now route explicitly to `PREPARE_PR.md`, `VALIDATION.md`, and the documentation index
+instead of restating those contracts.
+
+No `docs/wiki-source/` tree was created. Maintaining parallel Wiki-source pages would duplicate the
+new user guide before a Wiki publication workflow or demonstrated audience need exists. A future
+GitHub Wiki is therefore an optional presentation layer: it may summarize user-facing subjects,
+must link its versioned repository source, cannot own engineering or security contracts, and may be
+published only through a separate explicit operator action.
+
+`docs/README.md` now distinguishes public product documentation, contributor orientation,
+versioned engineering authority, current continuity, history, and the optional Wiki boundary. No
+validation, publication, signing, provenance, Hold, repository-authentication, or upstream contract
+changed. D7 remains the final consistency and status audit; T0-3 and Baseline T0 remain open.

docs/USER_GUIDE.md

@@ -0,0 +1,100 @@
+# Mosaic user guide
+
+This is the versioned source for Mosaic's user-facing installation, update-channel, Seerr, and
+troubleshooting guidance. The root [README](../README.md) remains the public product entry point.
+Engineering behavior is governed by the canonical documents in the
+[documentation index](README.md), not by this guide or a GitHub Wiki summary.
+
+## Install Mosaic
+
+Mosaic is distributed as an APK through [GitHub Releases](https://github.com/constbogdan/Mosaic/releases).
+It is not currently distributed through an app store.
+
+1. On the Android TV or Fire TV device, allow the application used to open the APK to install
+   unknown apps. Android presents the exact setting differently across device versions.
+2. Download the APK from the [current Stable release](https://github.com/constbogdan/Mosaic/releases/latest).
+3. Transfer it by USB, network share, a TV file-transfer application, or ADB and open it on the
+   device.
+4. If Android blocks installation, return to the per-application install permission and confirm
+   that the application opening the APK is allowed to install unknown apps.
+
+Mosaic requires Android 6+ or Fire TV OS 6+ and a reachable Jellyfin server. The root README records
+the currently tested Jellyfin versions.
+
+## Updates
+
+After installation, Mosaic automatically checks for updates. Available updates can be installed
+from Mosaic settings. The first in-app update may prompt Android to grant Mosaic permission to
+install updates; follow the device's system prompt.
+
+Current releases are available on the [Mosaic Releases page](https://github.com/constbogdan/Mosaic/releases).
+
+## Stable and Development channels
+
+- **Stable** is intended for normal use. It receives explicitly promoted releases and is the
+  recommended channel for most users.
+- **Development** provides newer testing builds from the
+  [`develop` release](https://github.com/constbogdan/Mosaic/releases/tag/develop). It may update and
+  change more frequently.
+
+Choose the channel in Mosaic's update settings. Switching channels changes which releases Mosaic
+offers; it does not require a separate application installation.
+
+The engineering publication and security contracts remain in
+[Development releases](MOSAIC_DEVELOPMENT_RELEASE.md) and [Stable and Hold](MOSAIC_STABLE.md).
+
+## Seerr integration
+
+Seerr is optional. Mosaic's base Jellyfin browsing and playback remain usable when Seerr is not
+configured or is temporarily unavailable.
+
+When configured, Seerr extends the user experience with discovery, requests, watchlist state,
+acquisition progress, and information about content not yet available in Jellyfin. For full
+compatibility, configure Seerr itself to integrate with the same Jellyfin server used by Mosaic.
+Mosaic is generally tested with the latest stable Seerr release; older releases may not behave as
+expected.
+
+## Troubleshooting
+
+### Installation or update is blocked
+
+- Confirm the device permits the application opening the APK to install unknown apps.
+- For an in-app update, confirm Mosaic has the corresponding install permission when Android asks.
+- Confirm the APK came from the canonical `constbogdan/Mosaic` Releases page.
+
+### Mosaic is missing from the Android TV launcher or looks incorrect
+
+Record the device and OS version and include a screenshot when reporting the problem. This guide
+does not prescribe a device-specific launcher repair that the project has not verified.
+
+### Seerr features are unavailable
+
+Confirm the configured Seerr server is reachable, is a supported stable version, and is integrated
+with the same Jellyfin server used by Mosaic. Jellyfin-only features should remain available while
+Seerr is unavailable.
+
+### Stable and Development are confusing
+
+Use Stable for normal consumption. Use Development only when you intentionally want newer testing
+builds and accept more frequent change.
+
+### Report a problem
+
+Search existing [Mosaic issues](https://github.com/constbogdan/Mosaic/issues) first. A useful report
+includes the Mosaic version and channel, Android TV or Fire TV model and OS version, Jellyfin and
+Seerr versions where relevant, reproduction steps, expected and observed behavior, and screenshots
+or logs that do not contain credentials.
+
+Contributors proposing a fix should continue with [Contributing](../CONTRIBUTING.md), the
+[developer guide](../DEVELOPMENT.md), and the [engineering documentation index](README.md).
+
+## GitHub Wiki boundary
+
+Mosaic does not currently maintain a separate Wiki source tree. A future GitHub Wiki may provide
+short user-facing copies or navigation for installation, channels, Seerr setup, troubleshooting,
+and contributor orientation. Publishing it requires a separate explicit operator action.
+
+A Wiki must link to this versioned guide for user behavior and to the repository documentation
+index for engineering contracts. It must not independently define validation, exact-tree evidence,
+release or signing authority, repository authentication, provenance, Hold behavior, or upstream
+ownership and synchronization.