docs: add UST.space ratings extension guide

docs/dashboard/timetable-planner/overview.mdx

@@ -66,3 +66,4 @@ The unit total is calculated once per course, even when the course has multiple
 
 - [Search and filtering](/docs/dashboard/timetable-planner/search-and-filtering)
 - [Study Planner integration](/docs/dashboard/timetable-planner/study-planner-integration)
+- [UST.space ratings extension](/docs/dashboard/timetable-planner/ust-space-ratings-extension)

docs/dashboard/timetable-planner/ust-space-ratings-extension.mdx

@@ -0,0 +1,125 @@
+---
+sidebar_position: 4
+title: UST.space ratings extension
+description: Install the Chrome extension that retrieves, displays, filters, and saves UST.space course ratings in Timetable Planner.
+---
+
+# UST.space ratings extension
+
+The **UST.space Ratings for USThing** Chrome extension retrieves aggregate course ratings from [UST.space](https://ust.space/) and sends them to [Timetable Planner](https://app.usthing.xyz/timetable-planner). Timetable Planner displays the ratings beside matching courses and saves successful results to your USThing account.
+
+:::warning Unsupported extension
+No official support is provided for this extension. Install and use it at your own risk. Changes to Chrome, USThing, or UST.space may cause it to stop working without notice.
+:::
+
+The extension requires Chrome 102 or later and installs from a downloadable ZIP file as an unpacked extension.
+
+## Set up the extension
+
+### 1. Download and extract the ZIP
+
+[Download the UST.space Ratings extension ZIP](#)
+
+{/* Download placeholder: Replace # with the published extension ZIP URL. */}
+
+After downloading:
+
+1. Extract the ZIP file.
+2. Move the extracted extension folder to a permanent location on your computer.
+3. Open the folder and confirm that it contains `manifest.json` and a `dist` folder.
+
+Do not delete or move this folder after loading it in Chrome. Chrome uses the extracted files to run the unpacked extension.
+
+### 2. Load it in Chrome
+
+1. Open `chrome://extensions`.
+2. Turn on **Developer mode**.
+3. Select **Load unpacked**.
+4. Choose the extracted folder that contains `manifest.json`. Do not choose the ZIP file or the `dist` subfolder.
+5. Confirm that **UST.space Ratings for USThing** is enabled.
+
+{/* Screenshot placeholder: Chrome Extensions page with Developer mode, Load unpacked, and the enabled extension. Suggested file: ./img/ust-space-ratings-load-unpacked.png */}
+
+When a new extension build is available, download and extract the new ZIP, replace the files in your existing extension folder, select **Reload** on the extension card, and reload Timetable Planner.
+
+### 3. Sign in and verify the connection
+
+1. Sign in to [UST.space](https://ust.space/login).
+2. Sign in to USThing and open [Timetable Planner](https://app.usthing.xyz/timetable-planner).
+3. Reload the planner if it was already open when you enabled the extension.
+4. Search for a course. Rating badges appear beside a course after its rating is retrieved.
+
+{/* Screenshot placeholder: Timetable Planner search results showing UST.space rating badges. Suggested file: ./img/ust-space-ratings-course-badges.png */}
+
+## Understand the rating badges
+
+A rated course shows four letter-grade badges in this order:
+
+| Position | Metric |
+| --- | --- |
+| 1 | Content |
+| 2 | Teaching |
+| 3 | Grading |
+| 4 | Workload |
+
+Hover over a badge to see the metric name, numeric aggregate score, and letter grade. A course that exists on UST.space but has no reviews shows **No reviews** instead.
+
+Ratings can appear in collapsed search results, expanded section-combination results, and Course Details. Select **View on UST.Space** in Course Details to open the source review page.
+
+## How retrieval and saving work
+
+The extension runs only on supported USThing Timetable Planner pages. It retrieves ratings automatically for course results that are currently shown and when you open Course Details.
+
+:::info Synced across your devices
+Fetched ratings are stored by Timetable Planner in your USThing account. They are synchronized to other devices where you sign in with the same account. The extension is only required on a device that needs to retrieve new or refreshed ratings.
+:::
+
+- **Search results:** after a result has been retrieved and acknowledged by the planner, the extension waits seven days before requesting that course again for the same USThing site.
+- **Course Details:** each distinct opening requests the course rating and bypasses the seven-day search interval.
+- **Saving:** rated and confirmed no-review results appear immediately, then Timetable Planner saves them to your authenticated USThing account.
+- **Fallback:** saved ratings remain visible when the extension is disabled, UST.space cannot be reached, or its session is unavailable.
+
+The seven-day record is scoped to the USThing site and course, and is shared by USThing users in the same Chrome profile.
+
+## Filter courses by rating
+
+1. Search for courses in Timetable Planner.
+2. Select **Filter by rating** above the results.
+3. Choose a minimum letter grade for any combination of **Content**, **Teaching**, **Grading**, and **Workload**.
+4. Select **Include unrated courses** if courses confirmed to have no reviews should remain visible.
+5. Select **Apply**.
+
+A rated course must meet every enabled minimum. Courses whose rating has not been retrieved remain visible so a temporary extension or network problem does not hide possible results.
+
+{/* Screenshot placeholder: Filter by UST.space rating dialog with metric minima and Include unrated courses. Suggested file: ./img/ust-space-ratings-filter.png */}
+
+## Data and permissions
+
+The extension requests access to `https://ust.space/*` so its background worker can retrieve course reviews using the UST.space session already active in Chrome. It does not request Chrome cookie permission.
+
+Chrome extension storage contains only the last acknowledged search-fetch time for each USThing site and course. It does not retain rating payloads. Timetable Planner saves usable rating summaries and their source responses in user-scoped USThing storage.
+
+## Troubleshooting
+
+Remember that this extension is provided without official support. The following checks may help, but assistance and fixes are not guaranteed.
+
+### UST.space Access Required appears
+
+Select **Sign in** in the planner warning, complete the UST.space sign-in, then return focus to the Timetable Planner tab. The extension retries after the tab regains focus.
+
+{/* Screenshot placeholder: Timetable Planner UST.space Access Required warning and Sign in link. Suggested file: ./img/ust-space-ratings-access-required.png */}
+
+If the warning remains, check whether Chrome is blocking the extension's access to UST.space or preventing the UST.space session from being sent with cross-site requests.
+
+### No rating badges appear
+
+- Confirm that the extension is enabled at `chrome://extensions`.
+- Select **Reload** on its extension card, then reload Timetable Planner.
+- Confirm that the downloaded ZIP was fully extracted.
+- Confirm that the loaded folder contains `manifest.json` and generated files under `dist`.
+- Confirm that you loaded the extracted extension folder rather than the ZIP file or `dist`.
+- Sign in to UST.space and return to the planner tab.
+
+### A search result shows an older saved rating
+
+Search retrieval is limited to once every seven days after a successful acknowledgment. Open the course's Course Details to request a fresh result without waiting for that interval.