Back to Search-quality baseline: cross-source canonical (Phase 1.2, v1.2.0 candidate)

Query | Expected source | Actual top-1 | Expected source in top-10?
--- | --- | --- | ---
`App icon` | hig (0.5) | `apple-docs://swiftui/scene/dialogicon` | NO
`Touch targets` | hig (0.5) | `apple-docs://webkitjs/touchevent` | NO
`Dark mode` | hig (0.5) | `apple-docs://appintents/defining-your-app-s-focus-filter` | NO
`Quartz 2D` | apple-archive (0.5) | `apple-docs://coreimage/ciimage/init(cgimage:)` | NO
`Cocoa Bindings` | apple-archive (0.5) | `apple-docs://appkit/cocoa-bindings` | NO
`Key Value Observing` | apple-archive (0.5) | `apple-docs://swift/using-key-value-observing-in-swift` | NO

For each of these queries, the HIG or apple-archive corpus does have a relevant page (verified via `cupertino search "<query>" --source hig` and `--source apple-archive`):

Query | Verified HIG page | Verified apple-archive page
--- | --- | ---
`App icon` | `hig://general/appicons-appledeveloperdocumentation` | —
`Dark mode` | `hig://general/darkmode-appledeveloperdocumentation` | —
`Cocoa Bindings` | — | `apple-archive://TP40001075/CocoaBindings`
`Key Value Observing` | — | `apple-archive://10000177i/KeyValueObserving`
`Quartz 2D` | — | `apple-archive://TP30001066/dq_data_mgr`
`Touch targets` | (no exact-title page; HIG covers under "Gestures" / "Editing menus") | —

The pages exist. The ranker doesn't surface them because the apple-docs RRF contribution dominates.

### Why this happens, mechanically

RRF fuses per-source rank-1 contributions weighted by source authority:

    fused(d) = Σ_{s ∈ sources(d)} weight(s) / (k + rank_s(d))

For rank-1 in each source (k = 60):

Source | Weight | Rank-1 fused contribution
--- | --- | ---
apple-docs | 3.0 | 3.0 / 61 = 0.0492
swift-evolution / packages | 1.5 | 1.5 / 61 = 0.0246
swift-book / swift-org / samples | 1.0 | 1.0 / 61 = 0.0164
hig / apple-archive | 0.5 | 0.5 / 61 = 0.0082

Even when HIG has a perfect rank-1 hit and apple-docs has a tangential rank-1 hit, the apple-docs contribution wins by 6:1 in fused score. HIG can never surface at top-1 in the default unfiltered query unless apple-docs has nothing in its corpus to return — which essentially never happens (351K rows).

### Is this a bug?

No, it is the design. The source weights were tuned in `Search.SmartQuery.sourceWeights` (#254 Option B) specifically to bias toward apple-docs because that is the canonical reference for code-generating AI agents (cupertino's stated purpose per `README.md` and `docs/design/cupertino.md` §1.1). For an LLM grounding a Swift code-generation task, getting apple-docs at top-1 is the right answer even when HIG might be more conceptually relevant — the agent is writing code, not designing UX.

But it has a knowable cost. Designers, UX writers, and humans using cupertino to look up Apple's design guidance get apple-docs answers when HIG answers exist. The current workaround is the explicit `--source hig` flag. Documenting the cost here so it isn't a surprise the next time the question comes up.

### Possible future directions (out of scope for this audit)

1. Intent routing for design-vocabulary queries. Augment `Search.SmartQuery.symbolPreferredSources` (#254) with a `designPreferredSources` analogue: when a query matches design vocabulary (`app icon`, `dark mode`, `accessibility`, `typography`, `gestures`, `navigation pattern`), route to HIG/apple-docs only.
2. Source-weight reconfiguration as a setting. Expose source weights as user-settable so a designer can `cupertino config set source-weight hig 3.0`.
3. Composite top-3 rather than top-1. If the consumer reads top-3, the HIG hit may appear at rank 2 or 3, mitigating the issue without weight changes. Worth measuring.

None of these is proposed as immediate work; each is a candidate per the `feedback_code_changes_as_ideas_for_future` rule.