Flesh out docs

docs/conf.py

@@ -22,6 +22,9 @@
     "attrs_inline",   # enable inline {key=val} attributes for images/links/spans
 ]
 
+# Generate anchors for h1-h3 so pages can link to sections, e.g. search.md#search-by-id
+myst_heading_anchors = 3
+
 # Tell Sphinx to treat .md files as source files
 source_suffix = {
     ".rst": "restructuredtext",

docs/configuration.md

@@ -8,7 +8,7 @@
 | `VITE_AUTH_ENABLED`       | Enables login/logout                             |
 | `VITE_LOGIN_SERVICE`      | Login service URL                                |
 | `VITE_LOGOUT_SERVICE`     | Logout service URL                               |
-| `VITE_CROSSMATCH_ENABLED` | Shows the crossmatch button                      |
+| `VITE_CROSSMATCH_ENABLED` | Enables the [Cross Matcher](cross-matching.md)   |
 | `VITE_ORGANIZATION_NAME`  | Organization name shown in the navbar (optional) |
 | `VITE_APP_NAME`           | App name shown in the navbar                     |
 | `VITE_APP_TITLE`          | Title shown in the browser tab                   |

docs/cross-matching.md

@@ -0,0 +1,133 @@
+# Cross Matching
+
+The Cross Matcher is where reviewers decide what to do with **unassigned sources**: detections in LightcurveDB that haven't been linked to a known source. Each unassigned source is reviewed and either merged with a nearby candidate, matched to a SIMBAD object, registered as a new source, or classified as noise.
+
+Open it with the **Cross Matcher** button in the navigation bar, or go to `/unassigned`. The Cross Matcher is only available when `VITE_CROSSMATCH_ENABLED` is `true` (see [Configuration](configuration.md)). Otherwise the button is hidden and the `/unassigned` pages show _Page not found_.
+
+## Review statuses
+
+Every unassigned source has one of these statuses:
+
+| Status             | Meaning                                                                          |
+| ------------------ | -------------------------------------------------------------------------------- |
+| **Unmatched**      | Not reviewed yet. This is the default, and the only status you can act on.       |
+| **Merged**         | Merged into another unassigned source. Its detections now belong to that source. |
+| **External match** | Matched to a SIMBAD object.                                                      |
+| **Novel**          | Registered as a new source.                                                      |
+| **Noise**          | Classified as noise.                                                             |
+
+Merged, external match, novel and noise are all final. Once a source has one of these statuses, it can't be reviewed again.
+
+## Unassigned sources list
+
+The list page shows a table of unassigned sources:
+
+| Column              | Description                                    |
+| ------------------- | ---------------------------------------------- |
+| **Source ID**       | The unassigned source's ID                     |
+| **Position (ICRS)** | RA and Dec in degrees, to five decimal places  |
+| **First Seen**      | Time of the source's earliest detection        |
+| **Last Seen**       | Time of the source's latest detection          |
+| **Status**          | The source's [review status](#review-statuses) |
+| **Review**          | Opens the source's review page                 |
+
+- Use the **Status** dropdown above the table to show only sources with one status. The count above the table updates to match.
+- Click a column header to sort by that column.
+
+## Reviewing a source
+
+Click **Review** on a row to open that source's review page at `/unassigned/<source ID>`. Use **← All unassigned sources** to go back to the list.
+
+The header shows the source ID, its position, the number of detections and the time range they cover. If the source has already been reviewed, a banner below the header says who reviewed it, when, and what they decided. For an external match, the banner also links to the SIMBAD object.
+
+### Light curve
+
+A flux (mJy) versus time plot of the source's detections. Color shows frequency and marker shape shows optics tube. It works like the [source page light curve](source-page.md#light-curve), with these differences:
+
+- There's no flagged-observations toggle and no binned mode.
+- Flags on unassigned detections usually record where the data came from, not a problem with the measurement. So every detection is plotted, and none get a red outline.
+- Clicking a point shows its details, but cutouts aren't available for unassigned detections yet. The panel shows _Cutout Not Found_.
+
+### Sky position
+
+A plot of where each detection falls relative to the source's position, as RA and Dec offsets in arcminutes. Color shows frequency and marker shape shows optics tube.
+
+- The source's position is the ✕ at the center.
+- The dashed circle is the 2.0 arcminute beam radius.
+- Hover over a detection to see its time, RA, Dec, frequency, optics tube and offsets.
+
+Detections spread widely across the circle, or far outside it, can suggest the candidate is more than one object or is noise.
+
+### Interactive sky map
+
+An [Aladin Lite](https://aladin.cds.unistra.fr/AladinLite/doc/) map using the DSS2 color survey, centered on the source:
+
+- **Blue markers**: this source's detections.
+- **Orange markers**: other unassigned sources that are still unmatched.
+- **Dashed orange circle**: the 2.0 arcminute search radius.
+- **Large red triangles**: potential SIMBAD matches. Click one to see its identifier, object type and position.
+
+### Nearby unassigned sources
+
+Lists other **unmatched** sources within 2.0 arcminutes. Click an ID to open that source's review page.
+
+### Potential SIMBAD matches
+
+Your browser searches SIMBAD for objects within 2.0 arcminutes of the source. It returns up to 10 objects, ordered by how often each is cited in the literature, most-cited first. The time of the search is shown above the list. Each match shows:
+
+- its identifier, which opens the object in the CDS portal in a new tab,
+- its object type, and
+- its distance from the source in arcminutes.
+
+If the SIMBAD search fails, the section says so instead of showing an empty list. Reload the page to try again. An empty list means the search worked and found nothing.
+
+This section is hidden for sources that are already merged, matched or novel.
+
+## Making a review decision
+
+The **Review decision** section only appears for **unmatched** sources. Leaving a source unmatched is a valid choice. If you need more detections before deciding, take no action.
+
+### Enter your name
+
+Every action records who made it. Enter your name in the **Reviewer** field at the top of the section before taking any action. Action buttons stay disabled until you do. Your name is saved in your browser, so you only need to enter it once per browser.
+
+### Actions
+
+Each action opens a confirmation dialog first. **Cancel** is selected by default, so pressing `Enter` won't confirm by accident. After you confirm, you're taken back to the unassigned sources list. If the action fails, the dialog stays open and shows the error, so you can try again or cancel.
+
+#### Merge with a nearby source
+
+Use this when a nearby unassigned source is the same object as the one you're reviewing. Click **Merge** next to that source in **Nearby unassigned sources**. All of the nearby source's detections move to the source you're reviewing.
+
+The source you're reviewing stays **unmatched**, so you can keep merging or make another decision. The nearby source becomes **merged**, and its review page then only shows which source it was merged into, by whom and when.
+
+#### Accept an external match
+
+Use this when the source is a known object in SIMBAD:
+
+1. Select the object's radio button in **Potential SIMBAD matches**. The selected object's name appears in the **Review decision** section.
+2. Click **Accept external match**.
+
+The source becomes an **external match**, and the SIMBAD object's identifier, type, position, separation and search time are saved with the decision. This decision is registered with SOCat.
+
+#### Register a novel source
+
+Use this when the source is real but doesn't match any known object:
+
+1. Enter a name in **New source name**.
+2. Click **Register novel source**.
+
+The source becomes **novel** and is registered with SOCat under that name.
+
+#### Classify as noise
+
+Use this when the source isn't a real astrophysical object:
+
+1. Check the box confirming the source is noise.
+2. Click **Classify as noise**.
+
+The source becomes **noise**. Its detections are kept as a record of the review.
+
+```{warning}
+External match, novel and noise decisions are final and can't be undone. A merge also can't be undone for the source that was merged away.
+```

docs/index.md

@@ -7,6 +7,10 @@ LightView is the Simons Observatory Light Curve Viewer: a web application for br
    :hidden:
 
 getting-started.md
+sky-explorer.md
+search.md
+source-page.md
+cross-matching.md
 configuration.md
 releases.md
 

docs/search.md

@@ -0,0 +1,54 @@
+# Search
+
+The search bar in the navigation bar is available on every page. Use the dropdown on its left to choose the type of search, fill in the fields, then press `Enter` or click the search button (magnifying glass). The fields are cleared after each search.
+
+| Search type                                 | Status      |
+| ------------------------------------------- | ----------- |
+| **Cone search (ra, dec, radius)**           | Available   |
+| **Search by ID**                            | Available   |
+| **Search by catalog via SIMBAD**            | Coming soon |
+| **Search by flare strength and date range** | Coming soon |
+
+Search types marked "Coming soon" appear in the dropdown but can't be selected yet.
+
+## Cone search
+
+A cone search finds every source within a given radius of a position on the sky. All three fields are required and are in degrees:
+
+| Field      | Description                          |
+| ---------- | ------------------------------------ |
+| **ra**     | Right ascension of the cone's center |
+| **dec**    | Declination of the cone's center     |
+| **radius** | Radius of the cone                   |
+
+### Results
+
+Results open on their own page. The heading repeats the search parameters, for example:
+
+> Cone search results for '`{ {ra: 83.633}, {dec: 22.014}, {radius: 0.5} }`'
+
+The results table lists each matching source:
+
+| Column        | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| **Source ID** | The source's ID. Click it to open the source's page.         |
+| **RA (deg)**  | Right ascension in degrees, rounded to three decimal places. |
+| **Dec (deg)** | Declination in degrees, rounded to three decimal places.     |
+
+- Hover over an **RA** or **Dec** value to see it at full precision.
+- Click a column header to sort by that column. Click it again to change the sort direction.
+- If nothing falls within the cone, the table shows _No results_.
+
+### Linking to results
+
+Every cone search has its own URL, so you can bookmark results or share them:
+
+```text
+/search/cone?ra=83.633&dec=22.014&radius=0.5
+```
+
+Opening that URL runs the search again.
+
+## Search by ID
+
+Enter a **Source ID** to go straight to that source's page. If no source has that ID, the source page shows an error.

docs/sky-explorer.md

@@ -0,0 +1,75 @@
+# Sky Explorer
+
+The home page is built around the Sky Explorer: an all-sky map of every source, with a table of the sources currently in view below it. The map and table are linked. Panning, zooming and filtering the map changes which sources the table lists.
+
+## All-sky map
+
+The map plots every source by position on a full-sky Mollweide projection in equatorial coordinates. It is rendered with [Aladin Lite](https://aladin.cds.unistra.fr/AladinLite/doc/), so the usual Aladin controls work:
+
+- **Pan** by clicking and dragging.
+- **Zoom** with the scroll wheel or the zoom controls.
+- **Fullscreen**: use Aladin's fullscreen button to expand the map to fill the window.
+
+The map loads zoomed out far enough to show the whole sky.
+
+### Inspecting a source
+
+- **Hover** over a marker to see the source's name, RA and Dec.
+- **Click** a marker to open a light curve preview for that source.
+
+### Light curve preview
+
+Clicking a marker opens a preview panel with the source's light curve, broken out by frequency band. From the preview you can:
+
+- Click **View source page** to go to the source's full page, which has more plot options and data downloads.
+- Click another marker to switch the preview to that source.
+- Close the preview with the close button (✕) or the `Escape` key.
+
+### Filtering by median flux
+
+The header above the map shows how many sources are displayed, for example _Showing 1200 of 4500 sources_. To show only sources within a certain brightness range in one frequency band:
+
+1. Click **Filter by median flux** to open the filter menu.
+2. Choose a **Frequency band**. You can't apply a filter until you choose a band.
+3. Set the **Median flux range (mJy)** by dragging the slider handles or typing values into the **Min** and **Max** boxes. The range runs from 0.001 to 5 mJy. Typed values outside it are clamped to the nearest limit.
+4. While you adjust the range, the menu shows how many sources match, for example _250 of 4500 sources match_.
+5. Click **Apply filter**.
+
+Once a filter is applied:
+
+- Sources outside the range are hidden from the map. Sources with no median flux in the chosen band are hidden too.
+- The markers that remain are colored to match the chosen frequency band.
+- The header shows the active filter, for example _Filtered on f090 from 0.5 to 2 mJy_.
+- The table's **Median Flux** column shows each source's value in that band.
+
+To remove the filter, click the ❌ next to the active-filter summary, or click **Clear filter** in the filter menu.
+
+## Sources table
+
+The table below the map lists the sources that are both:
+
+- within the map's current field of view, and
+- not hidden by an active median flux filter.
+
+When the map is fully zoomed out, the table lists every source. As you zoom in or pan, it narrows to the part of the sky you're looking at. The table updates once the map stops moving.
+
+### Columns
+
+| Column          | Description                                                                                                                                  |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Name**        | The source name. Click it to open the light curve preview. The page scrolls back up to the map so you can see it.                            |
+| **RA (deg)**    | Right ascension, rounded to three decimal places.                                                                                            |
+| **Dec (deg)**   | Declination, rounded to three decimal places.                                                                                                |
+| **Median Flux** | Median flux in mJy for the band chosen in the flux filter. Shows _(unselected)_ in the header and `-` in each row until a filter is applied. |
+| **Source Page** | Opens the source's full page in a new tab.                                                                                                   |
+| **Download as** | Downloads the source's light curve data. Choose a format in the column header (Parquet, HDF5 or CSV), then click a row's download button.    |
+
+Hover over an RA, Dec or Median Flux value to see it at full precision.
+
+### Sorting
+
+Click the **RA**, **Dec** or **Median Flux** column header to sort by that column. Click it again to cycle through descending, ascending and unsorted. A ▲ or ▼ next to the header shows the current sort direction. You can only sort by **Median Flux** while a flux filter is applied.
+
+### Pagination
+
+The table shows 25 sources per page. Page controls appear above and below the table and show which rows are on screen, for example _Displaying 1 - 25 of 480_. Use the buttons to go to the first (`<<`), previous (`<`), next (`>`) or last (`>>`) page.