diff --git a/.gitignore b/.gitignore index 30be16944..03248e8f0 100644 --- a/.gitignore +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e014cd03e..f006cd92a 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 9e0412cc9..1bf9e21bd 100644 --- a/DEVELOPMENT.md +++ b/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 diff --git a/README.md b/README.md index f0a73b5b9..84a5956ac 100644 --- a/README.md +++ b/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) diff --git a/docs/CODEX_HANDOFF.md b/docs/CODEX_HANDOFF.md index 2130f0741..fbf9da6e2 100644 --- a/docs/CODEX_HANDOFF.md +++ b/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. diff --git a/docs/MOSAIC_ROADMAP.md b/docs/MOSAIC_ROADMAP.md index 9d88df958..a88d311f7 100644 --- a/docs/MOSAIC_ROADMAP.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index acda8e5d9..68075828d 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/T0_3_DOCUMENTATION_CONSOLIDATION_PLAN.md b/docs/T0_3_DOCUMENTATION_CONSOLIDATION_PLAN.md index 856090c97..412cea8d2 100644 --- a/docs/T0_3_DOCUMENTATION_CONSOLIDATION_PLAN.md +++ b/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. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 000000000..3f9dc9183 --- /dev/null +++ b/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.