================================================================
COLLABORHYTHM RATINGS BOUNCER — LOGIC README
Version : V1 — 5_13_26
================================================================

WHAT THE BOUNCER DOES
---------------------
The Ratings Bouncer is the front door to the Collaborhythm archive.
It forces every visitor to choose an access level before entering.
That choice controls exactly what pages, hallways, and collections
are visible throughout the session.

No level = no entry.


HOW ACCESS LEVELS WORK
-----------------------
Levels are ordered from most restrictive to least:

  1. G           — All ages. Fully clean content only.
  2. PG          — Mild content. Generally school-safe.
  3. PG-13       — Mature themes, some strong language. Teens+.
  4. R           — Explicit language, graphic themes. Adults 18+.
  5. NC-17       — No minors. Explicit and graphic throughout. 18+.
  6. X           — Fully explicit. No exceptions. 18+.
  7. FULL ACCESS — Every page. Every rating. No filters.
                   ZIP Vault and Full Switchboard only appear here.

Each level INCLUDES all pages at or below that level.
Choosing PG-13 shows G + PG + PG-13 pages. Not R and above.

Level selection is passed via URL parameter:
  FILTERED_HALLWAY_VIEW_PROTOTYPE_5_13_26.html?level=PG-13


HOW THE JOHNNY RULE IS APPLIED
--------------------------------
The Johnny Rule: "If Johnny in 8th grade would get in trouble
showing it to his teacher, it must sit ABOVE the PG threshold."

Applied to each page at the time of rating assignment:

  PASS (G / PG)    — Johnny hands it to the teacher no problem.
  WARN (PG-13)     — Johnny hesitates. Teacher might ask questions.
  FAIL (R)         — Johnny gets detention.
  FAIL (NC-17)     — Johnny gets expelled.
  FAIL (X)         — Johnny's parents get called. School involved.
  FAIL (FULL)      — Johnny moves to another country.

The Johnny Rule is a gut-check, not a legal standard.
It is applied first. MPAA-style ratings are applied second.
When the two conflict, the more restrictive rating wins.


HOW PAGES ARE FILTERED
-----------------------
Each page in the access matrix has:

  rating              — the page's assigned content rating
  bouncer_visible_at  — list of tiers that can see this page
  trigger_warning     — whether a warning is shown before access
  hallway_group       — which hallway bucket the page belongs to

Filtering logic (JavaScript, client-side):
  tierAllows(userTier, pageTier):
    if userTier is FULL_ACCESS → always true
    else → TIER_ORDER[userTier] >= TIER_ORDER[pageTier]

Pages the user cannot access at their tier:
  — still appear in the hallway view, but are grayed and locked
  — show a lock icon and "requires higher access level" message
  — are not clickable


THE ACCESS MATRIX JSON
-----------------------
File: RATINGS_ACCESS_MATRIX_SAMPLE_5_13_26.json

Each entry contains:
  id                    — unique page identifier
  title                 — display name
  url                   — Yola page slug or full URL
  rating                — assigned rating
  highest_content_rating— if the page links to higher-rated content
  johnny_test           — plain-English Johnny Rule result
  access_tier           — tier required to access
  hallway_group         — which hallway this page belongs to
  trigger_warning_needed— true/false
  trigger_warnings      — list of specific warning strings
  bouncer_visible_at    — list of tiers that can see the page

To add a new page: add a new entry to the pages array.
To change a rating: update rating + bouncer_visible_at + johnny_test.


HOW THE HALLWAY VIEW WORKS
---------------------------
File: FILTERED_HALLWAY_VIEW_PROTOTYPE_5_13_26.html

After level selection, the user sees:
  - Their selected level displayed in the topbar
  - Count of visible vs locked pages
  - Hallway cards showing which groups have accessible content
  - Full page list sorted: visible first, locked second
  - Trigger warnings shown on applicable pages
  - Lock icon and message on inaccessible pages

The hallway groups are:
  Set Lists · Song Lists · Quick Guide · Reviews
  Themes / Moods · Videos · Lyrics · Relationship Maps
  Full Switchboard · ZIP Vault


HOW THIS CONNECTS TO THE FULL SYSTEM
--------------------------------------
The access matrix JSON is the master content registry.
When the full 34-page Yola site is complete:

  1. Every page gets an entry in the matrix
  2. Matrix is loaded by the bouncer engine
  3. Bouncer filters the full sitemap at runtime
  4. User sees only what their level allows

Future steps:
  — Replace sample pages with full 34-page entry list
  — Add real Yola URLs to each entry
  — Wire bouncer front door into Yola homepage
  — Add optional session persistence (localStorage or URL params)
  — Consider server-side gating for NC-17 / X tiers


YOLA DEPLOYMENT NOTES
----------------------
Both HTML files are Yola-safe:
  - All CSS scoped to .crhm-bouncer / .crhm-hallway wrappers
  - No conflicting class names
  - No external dependencies beyond Google Fonts
  - Level passed via URL parameter (no server required)
  - No cookies — uses sessionStorage with URL param fallback

Deployment order:
  1. Upload RATINGS_BOUNCER_FRONT_DOOR_V1_5_13_26.html to Yola
  2. Upload FILTERED_HALLWAY_VIEW_PROTOTYPE_5_13_26.html to Yola
  3. Confirm both files are in same Yola directory (URL param link works)
  4. Set bouncer front door as entry point for the archive section

================================================================
END OF BOUNCER LOGIC README
================================================================
