docs: align parents guide PR with contribution policy

Docs/NUVIO_PULL_REQUEST.md

@@ -1,48 +1,76 @@
-# Add native Parents Guide details section
+## Summary
 
-## Problem
+Draft implementation of a native, localized Parents Guide accordion on movie and series details. It uses a separately hosted, open-source metadata-only API and does not change streams, playback, or source selection.
 
-Nuvio currently has a brief player-start content-warning overlay, but the details screen cannot show sourced category summaries or scene-level parental advisories before playback.
+## PR type
 
-## Proposed solution and placement
+- [ ] Reproducible bug fix
+- [ ] UI glitch/bug fix
+- [ ] Behavior bug/regression fix
+- [ ] Small maintenance only, with no UI or behavior change
+- [ ] Docs accuracy fix
+- [ ] Translation/localization only
+- [ ] Approved larger or directional change
 
-Add a native, localized `ParentsGuideSection` to the details screen. The keyed lazy-list section is inserted immediately after Movie/Series Details and before More Like This; when users reorder or hide metadata sections it remains before recommendations. It is independent from stream and playback-source code.
+This remains unchecked while the feature request is awaiting explicit maintainer approval.
 
-The top-level row and each category are independently expandable. The section supports loading, available, partial, unavailable, error/retry, stale cache, spoiler hiding, severity text, optional timestamps, source attribution, and a contribution action. Touch targets are at least 48 dp and screen-reader descriptions are provided.
+## Why
 
-## Architecture
+Families cannot currently review sourced category summaries or scene-level parental advisories before playback. The proposed section covers sex and nudity, violence and gore, profanity, alcohol/drugs/smoking, and frightening/intense scenes without affecting the normal details flow when data is unavailable.
 
-- `ParentsGuideRemoteDataSource`: minimal HTTP GET using the existing multiplatform network primitive.
-- `ParentsGuideCache`: successful results for 24 hours and unavailable results for one hour; stale successful data is returned when refresh fails.
-- `ParentsGuideClient`/`ParentsGuideRepository`: request coalescing, identifier mapping, error isolation, and UI-state mapping.
-- `ParentsGuideModels`: strict kotlinx.serialization wire model and canonical category/severity ordering.
-- `ParentsGuideSection`: theme-derived Compose accordion components.
-- `ParentsGuideConfig`: build-generated `PARENTS_GUIDE_API_BASE_URL`. It defaults to the production service at `https://nuvio-parents-guide-addon.vercel.app`; local builds can override it in `local.properties` or the environment.
+## Issue or approval
 
-The Stremio v3 protocol has no standard Parents Guide resource. The companion addon publishes a valid no-stream manifest and a custom `/parentsguide/:type/:id.json` resource; this client calls the equivalent versioned API directly.
+Awaiting a maintainer decision in #1600. This PR is intentionally a draft and is not submitted as review-ready before approval.
 
-## Privacy
+## UI / behavior impact
 
-Only the current title's IMDb/TMDB/Stremio identifier, media type, optional season/episode, and language are sent. No viewing history, profile identity, library state, playback position, or stream information is transmitted.
+- [ ] No UI change
+- [ ] No behavior change
+- [ ] UI changed only to fix a documented glitch/bug
+- [ ] Behavior changed only to fix a documented bug/regression
+- [ ] UI change has explicit maintainer approval
+- [ ] Behavior change has explicit maintainer approval
 
-## Screenshots
+The implementation adds UI and network/cache behavior. The approval boxes will remain unchecked unless maintainers approve #1600.
 
-Required before marking the draft PR ready for review: collapsed, expanded categories, scene detail, partial, unavailable, error, dark/light, large text, and RTL screenshots. No screenshot is claimed because a working simulator/device was not available in this environment.
+## Policy check
 
-## Tests performed
+- [x] I have read and understood `CONTRIBUTING.md`.
+- [x] This PR is small, focused, and limited to one problem.
+- [x] This PR is not cosmetic-only.
+- [ ] Any UI change fixes a linked glitch/bug and includes visual proof, or this PR has no UI change.
+- [ ] Any behavior change fixes a linked bug/regression or has explicit approval, or this PR has no behavior change.
+- [x] This PR does not bundle unrelated refactors, cleanups, formatting, or drive-by changes.
+- [x] This PR does not add dependencies, architecture changes, migrations, or product-direction changes without explicit approval.
+- [x] I listed the testing performed below.
 
-- Passed iOS simulator shared-source compilation: `./gradlew :composeApp:compileKotlinIosSimulatorArm64`
-- iOS simulator tests compiled and linked, but execution could not be completed because the simulator service hung.
-- Android was not verified because the Android SDK is unavailable in this environment.
+The approval-dependent checks will be completed only after explicit approval and visual proof.
 
-Added tests cover JSON/status/provenance/timestamps, partial success, network error isolation, cache hit/expiry, identifier resolution, category order/severity, spoiler filtering, and timestamp formatting.
+## Scope boundaries
 
-## Compatibility and fallback
+- No streaming resource, torrent behavior, playback-source behavior, or navigation redesign.
+- Sends only the current title identifiers, media type, optional season/episode, and language.
+- API errors are isolated from metadata loading and the rest of the details page.
+- Uses the existing Show Parental Guide preference as the master switch.
+- Initial cache is process-local; persistent settings/cache are outside this draft.
 
-The feature reuses the existing Show Parental Guide preference as its master enable switch. With the feature disabled, no request or section is added. With no configured endpoint or no guide, the normal details page remains functional and an unavailable state is shown. API errors are contained in the section and never fail metadata loading. Cached data can be displayed offline.
+## Testing
 
-## Known limitations
+- Backend: formatting, lint, strict type-check, 12 Vitest tests, production build, Vercel deployment, Neon readiness, and external endpoint smoke tests passed.
+- Mobile: `./gradlew :composeApp:compileKotlinIosSimulatorArm64` passed after the production endpoint was configured.
+- iOS tests compiled and linked, but simulator execution could not complete because the local simulator service hung.
+- Android was not verified because the Android SDK is unavailable in the current environment.
 
-- Cache is process-local in this first contribution; it supports transient offline use but not restoration after app restart.
-- Episode requests include season/episode when encoded in the current ID. A future follow-up can surface an explicit episode selector and persist display preferences independently.
-- Initial new strings are English and require community translation after merge.
+Added mobile tests cover JSON/status/provenance/timestamps, partial success, network error isolation, cache hit/expiry, identifier resolution, category ordering/severity, spoiler filtering, and timestamp formatting.
+
+## Screenshots / Video (UI changes only)
+
+Pending feature approval and access to a working simulator/device. Before review, this draft needs collapsed, expanded-category, scene-detail, partial, unavailable, error, dark/light, large-text, and RTL captures.
+
+## Breaking changes
+
+None. With the feature disabled, no request or section is added. Missing guides and API failures leave the normal details page functional.
+
+## Linked issues
+
+#1600 — awaiting explicit maintainer approval.