[self-care:docs-build-time-investigator] Skip unchanged scheduled docs rebuilds when dashboard/doc inputs are unchanged

The latest 8 successful `docs.yml` runs over the last ~1 hour show the workflow already spends most of its time waiting on a separately dispatched dashboard build that usually restores cached activity data and completes quickly; the only repeated >10-second cost left in `docs.yml` itself is `npm ci` plus `npm run docs:build`, which together take a median 13.5s of an 87s median workflow. One outlier run (33805671222) stretched the `dashboard` job to 82s because the dispatched `dashboard-build.yml` run started 29s after the activity job completed even though the cached path skipped activity refresh. The best evidence-backed improvement in the current suggestion cycle is therefore to **avoid unnecessary scheduled docs rebuilds when neither docs inputs nor dashboard inputs changed**, rather than more caching inside the build jobs.

### Summary
Add a lightweight change gate to `.github/workflows/docs.yml` so the 15-minute scheduled trigger exits early unless files that can change the Pages output have changed since the last successful Pages deployment, or unless a freshness policy explicitly requires a rebuild. This targets the dominant cost still visible in the sampled runs: repeated end-to-end workflow executions with no meaningful work beyond cache restores, `npm ci`, Astro build, artifact packaging, and deploy.

### Timing evidence
- Evidence window: 2026-09-03 20:31 UTC to 2026-09-03 21:32 UTC, latest 8 successful completed `docs.yml` runs within the allowed 14-day / 20-run cap.
- Comparable successful runs: 8 total (`schedule`: 5, `push`: 3). No queue delay was visible in GitHub metadata for these runs.
- `docs.yml` workflow duration: median **87s**, p90 **213s**.
- `docs.yml` job durations:
- `dashboard`: median **36s**, p90 **82s**
- `build`: median **26.5s**, p90 **34s**
- `deploy`: median **9.5s**, p90 **11s**
- In the `build` job, the repeated step costs were:
- `Install dependencies` (`npm ci`): **8–10s** across all 8 samples
- `Build documentation` (`npm run docs:build`): **4–6s** across all 8 samples
- artifact download / upload / Pages packaging steps: usually **1–3s** each
- Dispatched `dashboard-build.yml` runs tied to the same docs runs completed in median **26s** total (p90 **70s**). In all 8 sampled dashboard-build runs, `Check for a cached activity snapshot` succeeded and `Dispatch activity refresh` was skipped, confirming cache hits from trusted step metadata.
- Outlier disclosure: run `33805671222` reached **213s** total because its `dashboard` job lasted **82s** while the paired dashboard-build run itself still used the cached path and only took **70s** total. The extra delay came from dispatch/wait behavior, not from docs generation.

### Bottleneck
The largest remaining avoidable cost is not a cache miss inside `build` or `dashboard-build`; it is **running the whole docs pipeline every 15 minutes even when the scheduled build has nothing new to publish**. Current workflow source:
- `.github/workflows/docs.yml` schedules every 15 minutes and always dispatches `dashboard-build.yml`, then always runs checkout → `npm ci` → `npm run docs:build` → artifact mount → Pages deploy.
- `.github/workflows/dashboard-build.yml` already verifies cached activity data with `actions/cache/restore` and skips `Dispatch activity refresh` when a snapshot exists, so the dashboard side is already using the available cache path effectively in the sampled runs.

Because the sampled successful runs were largely back-to-back rebuilds of unchanged inputs, a change gate that no-ops most scheduled runs would remove the entire median **87s** end-to-end execution for those runs, comfortably exceeding the 60-second / 15% threshold.

### Recommended changes
In `.github/workflows/docs.yml`:
1. Insert a cheap preflight job before `dashboard` that determines whether any docs-affecting inputs changed since the last successful docs deployment (for example: `docs/**`, `dashboard/**`, `public/**`, `astro.config.mjs`, root/package manifests, workflow sources that affect dashboard generation, and any freshness sentinel if dashboard data must periodically refresh).
2. Run `dashboard`, `build`, and `deploy` only when the preflight reports `should_build=true`; otherwise exit the workflow successfully with a short log explaining why the scheduled run skipped.
3. Keep `push` and manual `workflow_dispatch` behavior unchanged so correctness and operator-forced refreshes still work.
4. If dashboard freshness truly requires periodic rebuilds even without repository changes, encode that explicitly in the preflight (for example, rebuild only when the cached activity snapshot is older than a defined age), instead of always rebuilding every 15 minutes.

Likely implementation points:
- `.github/workflows/docs.yml` schedule and job graph
- existing dashboard input paths already listed under the `push.paths` filter in `.github/workflows/docs.yml`, which can seed the preflight comparison set
- optionally reuse the request-id / dispatch structure already present in `.github/workflows/docs.yml` and `.github/workflows/dashboard-build.yml`

### Expected effect and validation
Expected effect:
- For scheduled runs with no relevant changes, save nearly the entire current median workflow execution: about **87 seconds per skipped run**.
- This is materially larger than optimizing `npm ci` or Astro build further, because those two steps together account for only ~**13.5 seconds median** in the current sample.

Validation plan:
1. Compare 1–2 days of scheduled runs before and after the gate.
2. Measure skip rate, median scheduled-run duration, and total GitHub-hosted runner minutes consumed.
3. Confirm manual and push-triggered docs builds still publish correctly.
4. Confirm any explicit freshness policy still triggers rebuilds often enough for dashboard correctness.

### Caveats
- Confidence: **medium-high** for the timing conclusion, because the sample has 8 comparable successful runs with consistent step timings and trusted cache-hit evidence from `dashboard-build.yml`. Confidence is lower on the exact skip policy because freshness requirements are not fully expressed in the workflow today.
- This recommendation is intentionally **not** to change `npm` caching or dashboard activity caching: trusted logs already show cache-hit behavior on the dashboard side, and `actions/setup-node` + `cache: npm` keeps the remaining dependency-install cost relatively small.
- Failed dashboard-build runs existed outside the successful sample window and should still be reviewed separately, but they do not change the finding that most successful scheduled builds are repeated low-value rebuilds.

### Control Plane
- Correlation ID: `33808080389-122`
- Central repository: `githubnext/gh-aw-cao`
- Control plane run: `https://github.com/githubnext/gh-aw-cao/actions/runs/33808080389`

### References
- Workflow source: `.github/workflows/docs.yml`
- Workflow source: `.github/workflows/dashboard-build.yml`
- `docs.yml` runs:
- `33808371432` — https://github.com/githubnext/gh-aw-cao/actions/runs/33808371432
- `33807479311` — https://github.com/githubnext/gh-aw-cao/actions/runs/33807479311
- `33806737192` — https://github.com/githubnext/gh-aw-cao/actions/runs/33806737192
- `33805671222` — https://github.com/githubnext/gh-aw-cao/actions/runs/33805671222
- `33805665939` — https://github.com/githubnext/gh-aw-cao/actions/runs/33805665939
- `33804455245` — https://github.com/githubnext/gh-aw-cao/actions/runs/33804455245
- `33804157645` — https://github.com/githubnext/gh-aw-cao/actions/runs/33804157645
- `33802787743` — https://github.com/githubnext/gh-aw-cao/actions/runs/33802787743
- Paired `dashboard-build.yml` runs:
- `33808385860`, `33807493934`, `33806749014`, `33805821191`, `33805677106`, `33804472575`, `33804175090`, `33802814853`

> Generated by [SelfCare / Docs Build Time](https://github.com/githubnext/gh-aw-cao/actions/runs/33808529467) · pi · gpt54 · 49.7 AIC · ⌖ 8.44 AIC · ⊞ 8.5K · [◷](https://github.com/search?q=repo%3Agithubnext%2Fgh-aw-cao+is%3Aissue+%22gh-aw-workflow-call-id%3A+githubnext%2Fgh-aw-cao%2Fself-care-docs-build-time-investigator%22&type=issues)
> - [x] expires on Sep 17, 2026, 9:40 PM UTC

Start by reading .github/workflows/docs.yml and .github/workflows/dashboard-build.yml, especially the schedule, push.paths filter, job dependencies, and dispatch structure. Define the preflight inputs and freshness behavior from the issue, then validate that unchanged scheduled runs skip successfully while push and manual runs still execute dashboard, build, and deploy; compare skip rate and runner time over 1–2 days.

Written by the indexing model from the issue text.