docs(github-pages): document swipe page and full manifest schema

- Document the per-digest swipe/triage page that is published alongside
  each digest.
- Add an exhaustive manifest schema (top-level Manifest + every
  ManifestEntry field).
- Replace the non-existent 'scheduler' section with how automatic
  publishing actually works.

Author: ma111e

docs/github-pages.md

@@ -3,7 +3,7 @@
 Downlink can automatically publish each digest as a self-contained HTML page to a GitHub Pages repository. After every successful digest generation, it:
 
 1. Clones (or pulls) your Pages repo locally.
-2. Writes the digest HTML file (e.g. `digests/downlink-digest-2026-04-24_1200.html`).
+2. Writes the digest HTML file (e.g. `digests/downlink-digest-2026-04-24_1200.html`) and a companion swipe/triage page (`digests/downlink-swipe-2026-04-24_1200.html`).
 3. Regenerates `digests/index.html` and `digests/manifest.json` listing all digests, newest first.
 4. Writes a root `index.html` that renders the digest archive and reads files from the configured output directory.
 5. Commits and pushes the changed files.
@@ -15,13 +15,13 @@ Downlink can automatically publish each digest as a self-contained HTML page to
 
 If you don't have one, create a repository named `<your-username>.github.io` (for a user site) or any repo with GitHub Pages enabled on a branch.
 
-In the repo's **Settings → Pages**, set the source to the branch you'll push to (e.g. `main`, root `/`).
+In the repo's **Settings -> Pages**, set the source to the branch you'll push to (e.g. `main`, root `/`).
 
 ---
 
 ## 2. Create a Personal Access Token
 
-Go to **GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens** (or classic tokens).
+Go to **GitHub -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens** (or classic tokens).
 
 For normal publishing, the token needs **Contents: Read and write** on the target repository.
 
@@ -63,16 +63,16 @@ Add a `github_pages` block inside `notifications`:
 | Field | Required | Default | Description |
 |---|---|---|---|
 | `enabled` | yes | `false` | Enable or disable publishing. |
-| `repo_url` | yes | — | HTTPS clone URL of the Pages repo. |
+| `repo_url` | yes | / | HTTPS clone URL of the Pages repo. |
 | `branch` | no | `main` | Branch to clone and push to. When `configure_pages` is true, this is also configured as the GitHub Pages source branch. |
 | `configure_pages` | no | `false` | Configure the GitHub Pages source to `branch` at `/` before publishing. Requires extra token permissions. |
-| `token` | no* | — | GitHub PAT. Prefer `DOWNLINK_GH_PAGES_TOKEN` env var instead. |
+| `token` | no* | / | GitHub PAT. Prefer `DOWNLINK_GH_PAGES_TOKEN` env var instead. |
 | `output_dir` | no | `digests` | Safe relative subdirectory inside the repo where digest files are written. Absolute paths, `.`, `..`, and parent traversal are rejected. |
-| `base_url` | no | — | Public URL of the site (e.g. `https://your-username.github.io`). Used to build links in Discord notifications. |
+| `base_url` | no | / | Public URL of the site (e.g. `https://your-username.github.io`). Used to build links in Discord notifications. |
 | `commit_author` | no | `downlink-bot` | Git commit author name. |
 | `commit_email` | no | `downlink-bot@users.noreply.github.com` | Git commit author email. |
 | `clone_dir` | no | `$TMPDIR/downlink-ghpages` | Local path where the repo is cloned. Persists across runs to avoid full re-clones. |
-| `discord_webhook_url` | no | — | A **separate** Discord webhook to notify when a page is published. Distinct from the main digest webhook. |
+| `discord_webhook_url` | no | / | A **separate** Discord webhook to notify when a page is published. Distinct from the main digest webhook. |
 
 *\* `token` must be provided via config or environment variable for publishing to work.*
 
@@ -87,7 +87,7 @@ export DOWNLINK_GH_PAGES_TOKEN=github_pat_...
 ./server
 ```
 
-Or put the token directly in `config.json` under `github_pages.token` — but be careful not to commit it.
+Or put the token directly in `config.json` under `github_pages.token` - but be careful not to commit it.
 
 ---
 
@@ -109,7 +109,7 @@ Every config field has a corresponding flag on the `server` command. Flags overr
 --gh-pages-discord-webhook <url> Discord webhook for publish notifications
 ```
 
-Example — enable for one run without touching `config.json`:
+Example - enable for one run without touching `config.json`:
 
 ```sh
 export DOWNLINK_GH_PAGES_TOKEN=github_pat_...
@@ -126,15 +126,47 @@ export DOWNLINK_GH_PAGES_TOKEN=github_pat_...
 
 On each digest generation:
 
-- **`<output_dir>/downlink-digest-YYYY-MM-DD_HHMM.html`** — self-contained dark-themed HTML page for that digest (same file sent to Discord).
-- **`<output_dir>/manifest.json`** — machine-readable archive data for the digest index, newest first. Each digest entry includes `filename`, `started_at`, `time_window`, `article_count`, `must_count`, `should_count`, `may_count`, `opt_count`, `provider`, `model`, `headlines`, and `summary`.
-- **`<output_dir>/index.html`** — regenerated archive UI with latest-digest hero, search, filters, sort controls, log/grid/timeline layouts, keyboard navigation, and pinned digests in browser local storage.
-- **`index.html`** — root archive UI that loads `<output_dir>/manifest.json` and links digest pages under `<output_dir>`.
+- **`<output_dir>/downlink-digest-YYYY-MM-DD_HHMM.html`** - self-contained dark-themed HTML page for that digest (same file sent to Discord).
+- **`<output_dir>/downlink-swipe-YYYY-MM-DD_HHMM.html`** - self-contained mobile-friendly "swipe" triage view of the same digest, linked from the articles page. Shares its timestamp.
+- **`<output_dir>/manifest.json`** - machine-readable archive data for the digest index, newest first. See [Manifest schema](#manifest-schema) below for every field.
+- **`<output_dir>/index.html`** - regenerated archive UI with latest-digest hero, search, filters, sort controls, log/grid/timeline layouts, keyboard navigation, and pinned digests in browser local storage.
+- **`index.html`** - root archive UI that loads `<output_dir>/manifest.json` and links digest pages under `<output_dir>`.
 
 If `output_dir` is empty, Downlink uses `digests`. Publishing directly to the repo root is not supported.
 
 The browser-facing archive index uses `manifest.json` directly. The manifest follows the current archive schema only; old manifests should be regenerated by publishing a new digest or reinitializing the Pages structure.
 
+### Manifest schema
+
+Top-level `manifest.json` object:
+
+| Field | Type | Description |
+|---|---|---|
+| `generated_at` | string | Timestamp when the manifest was last (re)generated. |
+| `source_repo` | string | The Pages repository URL the manifest was written to. |
+| `digests` | array | List of digest entries, newest first (see below). |
+
+Each entry in `digests`:
+
+| Field | Type | Description |
+|---|---|---|
+| `filename` | string | Digest HTML filename (e.g. `downlink-digest-2026-04-24_1200.html`). |
+| `started_at` | string | When digest generation started. |
+| `period_start` | string | Start of the time window the digest covers. Omitted when unset. |
+| `time_window` | string | Human-readable description of the covered time window. |
+| `article_count` | int | Total number of articles in the digest. |
+| `must_count` | int | Articles tagged "Must Read". |
+| `should_count` | int | Articles tagged "Should Read". |
+| `may_count` | int | Articles tagged "May Read". |
+| `opt_count` | int | Articles tagged "Optional". |
+| `provider` | string | Analysis provider used for the digest summary. |
+| `model` | string | Primary model name. |
+| `models` | array | All unique model names across the summary and per-article analysis. Omitted when empty. |
+| `title` | string | Digest title. Omitted when unset. |
+| `headlines` | array | Headline strings shown in the archive index. |
+| `headline_priorities` | array | Per-headline priority labels, aligned with `headlines`. Omitted when empty. |
+| `summary` | string | Digest summary (markdown). |
+
 ---
 
 ## 7. Discord publish notification
@@ -153,12 +185,12 @@ If `base_url` is not set, the message omits the URL. Failure to send this notifi
 
 On the first publish, Downlink clones the repository into `clone_dir` (shallow, depth 1). On subsequent runs it pulls the latest from origin before writing and committing. This means:
 
-- The clone persists between server restarts — no full re-clone each time.
+- The clone persists between server restarts - no full re-clone each time.
 - If two concurrent digest generations race, the second push may be rejected as non-fast-forward; Downlink will pull and retry once automatically.
 - If you need to force a fresh clone, delete the `clone_dir` directory.
 
 ---
 
-## 9. Scheduler usage
+## 9. Automatic publishing
 
-The scheduler triggers digest generation on the server via gRPC. Because publishing is wired into the server-side pipeline, no extra scheduler configuration is needed — any digest the scheduler generates will be published automatically if `github_pages.enabled` is `true` in the server's `config.json`.
+Publishing is wired into the server-side digest pipeline, so no extra configuration is needed beyond `github_pages.enabled`. Any digest generated against the server - via `dlk digest generate` or the gRPC `DigestService` - is published automatically when `github_pages.enabled` is `true` in the server's `config.json`. To publish on a schedule, run `dlk digest generate` from cron (or any external scheduler) against the running server.