Merge pull request #72 from agent-ecosystem/fix-rendering-strategy-diagnostics

Fix rendering strategy diagnostics

Author: dacharyc

SCORING.md

@@ -59,7 +59,7 @@ Whether agents can process your pages without losing content.
 
 | Check                                                                            | Weight        | What it measures                                                                                      |
 | -------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------- |
-| [rendering-strategy](https://agentdocsspec.com/spec/#rendering-strategy)         | Critical (10) | Whether pages use server-side rendering. Client-side (SPA) pages deliver empty shells to agents.      |
+| [rendering-strategy](https://agentdocsspec.com/spec/#rendering-strategy)         | Critical (10) | Whether pages are fully server-rendered, server-rendered but sparse, or empty SPA shells.             |
 | [page-size-markdown](https://agentdocsspec.com/spec/#page-size-markdown)         | High (7)      | Whether markdown pages fit within agent processing limits (~100K characters).                         |
 | [page-size-html](https://agentdocsspec.com/spec/#page-size-html)                 | High (7)      | Whether HTML pages, once converted to text, fit within agent processing limits.                       |
 | [content-start-position](https://agentdocsspec.com/spec/#content-start-position) | Medium (4)    | Whether documentation content starts near the top of the page, or is buried under boilerplate CSS/JS. |
@@ -160,17 +160,19 @@ Some problems are severe enough that no amount of other good behavior should com
 
 ### Critical check caps
 
-| Condition                                          | Cap    | Why                                                                            |
-| -------------------------------------------------- | ------ | ------------------------------------------------------------------------------ |
-| `llms-txt-exists` fails                            | 59 (D) | Agents lose primary navigation but may still use HTML/markdown paths directly. |
-| `rendering-strategy`: 75%+ of pages are SPA shells | 39 (F) | Most content is invisible to agents.                                           |
-| `rendering-strategy`: 50%+ of pages are SPA shells | 59 (D) | Significant content is invisible to agents.                                    |
-| `auth-gate-detection`: 75%+ of pages require auth  | 39 (F) | Most documentation is inaccessible.                                            |
-| `auth-gate-detection`: 50%+ of pages require auth  | 59 (D) | Significant documentation is inaccessible.                                     |
-| `no-viable-path` diagnostic fires (see below)      | 39 (F) | Agents have no effective way to access content at all.                         |
+| Condition                                         | Cap    | Why                                                                            |
+| ------------------------------------------------- | ------ | ------------------------------------------------------------------------------ |
+| `llms-txt-exists` fails                           | 59 (D) | Agents lose primary navigation but may still use HTML/markdown paths directly. |
+| `rendering-strategy`: proportion ≤ 0.25           | 39 (F) | Most content is invisible to agents.                                           |
+| `rendering-strategy`: proportion ≤ 0.50           | 59 (D) | Significant content is invisible to agents.                                    |
+| `auth-gate-detection`: 75%+ of pages require auth | 39 (F) | Most documentation is inaccessible.                                            |
+| `auth-gate-detection`: 50%+ of pages require auth | 59 (D) | Significant documentation is inaccessible.                                     |
+| `no-viable-path` diagnostic fires (see below)     | 39 (F) | Agents have no effective way to access content at all.                         |
 
 When multiple caps apply, the lowest one wins.
 
+The `rendering-strategy` proportion is `(serverRendered + sparseContent × 0.5) / total`: empty SPA shells count fully against the proportion, while server-rendered-but-sparse pages count at half weight.
+
 The `rendering-strategy` and `auth-gate-detection` caps do not apply when the check has `scoreDisplayMode: "notApplicable"` (insufficient data). If we don't trust the data enough to include it in the score, we don't trust it enough to cap the score either.
 
 ## Interaction diagnostics
@@ -292,7 +294,7 @@ If multiple conditions are met, the highest coefficient applies.
 
 **Affects**: `page-size-html`, `content-start-position`, `tabbed-content-serialization`, `section-header-quality`
 
-If pages are SPA shells, measuring HTML quality is meaningless. This coefficient equals the `rendering-strategy` check's proportion: if 90% of pages render correctly, these checks count for 90% of their weight.
+If pages are SPA shells, measuring HTML quality is meaningless; if pages are sparse, HTML quality counts for less because agents have less content to work with. This coefficient equals the same weighted proportion that drives the score caps above: `(serverRendered + sparseContent × 0.5) / total`. Fully server-rendered pages count for full weight, sparse pages count for half, and SPA shells count for nothing.
 
 ### Index truncation coefficient
 

docs/agent-score-calculation.md

@@ -95,25 +95,25 @@ Checks that test multiple pages use proportional scoring. If `page-size-html` te
 
 These checks sample pages from your site and score based on the pass rate across those pages:
 
-| Check                          | What's measured per page                                            |
-| ------------------------------ | ------------------------------------------------------------------- |
-| `rendering-strategy`           | Whether the page is server-rendered or an SPA shell                 |
-| `page-size-html`               | Whether the HTML-to-text conversion fits within size limits         |
-| `page-size-markdown`           | Whether the markdown version fits within size limits                |
-| `content-start-position`       | How far into the response actual content begins                     |
-| `content-negotiation`          | Whether the server returns markdown for this page                   |
-| `markdown-url-support`         | Whether the `.md` URL variant returns markdown                      |
-| `http-status-codes`            | Whether a fabricated bad URL returns a proper 404                   |
-| `redirect-behavior`            | Whether redirects use standard HTTP methods                         |
-| `auth-gate-detection`          | Whether the page is publicly accessible                             |
-| `llms-txt-directive-html`      | Whether the HTML page includes a directive pointing to llms.txt     |
-| `llms-txt-directive-md`        | Whether the markdown page includes a directive pointing to llms.txt |
-| `tabbed-content-serialization` | Whether tabbed content creates oversized output                     |
-| `section-header-quality`       | Whether tab section headers include variant context                 |
-| `markdown-code-fence-validity` | Whether code fences are properly closed                             |
-| `markdown-content-parity`      | Whether markdown and HTML versions match                            |
-| `cache-header-hygiene`         | Whether cache headers allow timely updates                          |
-| `auth-alternative-access`      | Whether auth-gated pages have alternative access paths              |
+| Check                          | What's measured per page                                                                     |
+| ------------------------------ | -------------------------------------------------------------------------------------------- |
+| `rendering-strategy`           | Whether the page is fully server-rendered, server-rendered but sparse, or an empty SPA shell |
+| `page-size-html`               | Whether the HTML-to-text conversion fits within size limits                                  |
+| `page-size-markdown`           | Whether the markdown version fits within size limits                                         |
+| `content-start-position`       | How far into the response actual content begins                                              |
+| `content-negotiation`          | Whether the server returns markdown for this page                                            |
+| `markdown-url-support`         | Whether the `.md` URL variant returns markdown                                               |
+| `http-status-codes`            | Whether a fabricated bad URL returns a proper 404                                            |
+| `redirect-behavior`            | Whether redirects use standard HTTP methods                                                  |
+| `auth-gate-detection`          | Whether the page is publicly accessible                                                      |
+| `llms-txt-directive-html`      | Whether the HTML page includes a directive pointing to llms.txt                              |
+| `llms-txt-directive-md`        | Whether the markdown page includes a directive pointing to llms.txt                          |
+| `tabbed-content-serialization` | Whether tabbed content creates oversized output                                              |
+| `section-header-quality`       | Whether tab section headers include variant context                                          |
+| `markdown-code-fence-validity` | Whether code fences are properly closed                                                      |
+| `markdown-content-parity`      | Whether markdown and HTML versions match                                                     |
+| `cache-header-hygiene`         | Whether cache headers allow timely updates                                                   |
+| `auth-alternative-access`      | Whether auth-gated pages have alternative access paths                                       |
 
 ### Single-resource checks (all-or-nothing)
 
@@ -150,14 +150,16 @@ Some problems are severe enough that no amount of other passing checks should co
 | Condition                                                                             | Cap    | Why                                                    |
 | ------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------ |
 | `llms-txt-exists` fails                                                               | 59 (D) | Agents lose their primary navigation mechanism.        |
-| `rendering-strategy`: 75%+ SPA shells                                                 | 39 (F) | Most content is invisible to agents.                   |
-| `rendering-strategy`: 50%+ SPA shells                                                 | 59 (D) | Significant content is invisible.                      |
+| `rendering-strategy`: proportion ≤ 0.25                                               | 39 (F) | Most content is invisible to agents.                   |
+| `rendering-strategy`: proportion ≤ 0.50                                               | 59 (D) | Significant content is invisible.                      |
 | `auth-gate-detection`: 75%+ pages gated                                               | 39 (F) | Most documentation is inaccessible.                    |
 | `auth-gate-detection`: 50%+ pages gated                                               | 59 (D) | Significant documentation is inaccessible.             |
 | [No viable path](/interaction-diagnostics#no-viable-path-to-content) diagnostic fires | 39 (F) | Agents have no effective way to access content at all. |
 
 When multiple caps apply, the lowest one wins.
 
+The `rendering-strategy` proportion is `(serverRendered + sparseContent × 0.5) / total`: empty SPA shells count fully against the proportion, while server-rendered-but-sparse pages count at half weight. A site that's entirely SPA shells has proportion 0 (caps at F). A site that's half shells and half full content has proportion 0.5 (caps at D). A site that's entirely sparse-but-rendered has proportion 0.5 (also caps at D, on the assumption that sparse pages are half-broken on average); after the heuristic fix, legitimately short pages no longer count as sparse, so this scenario is much rarer.
+
 The `rendering-strategy` and `auth-gate-detection` caps do not apply when the check is marked as not applicable due to [insufficient data](#insufficient-data). If there isn't enough data to include the check in the score, there isn't enough data to cap the score based on it either.
 
 ## Insufficient data
@@ -197,7 +199,7 @@ Note that `markdown-url-support` is intentionally excluded from this coefficient
 
 **Affects**: `page-size-html`, `content-start-position`, `tabbed-content-serialization`, `section-header-quality`
 
-If pages are SPA shells, measuring HTML quality is meaningless. This coefficient equals the `rendering-strategy` check's pass proportion: if 90% of pages render correctly, these checks count for 90% of their weight.
+If pages are SPA shells, measuring HTML quality is meaningless; if pages are sparse, HTML quality counts for less because agents have less content to work with. This coefficient equals the same proportion that drives the score caps above: `(serverRendered + sparseContent × 0.5) / total`. Fully server-rendered pages count for full weight, sparse pages count for half, and SPA shells count for nothing.
 
 ### Index truncation coefficient
 

docs/checks/page-size.md

@@ -21,26 +21,28 @@ The rendering strategy is a property of the framework and its configuration, not
 
 ### Results
 
-| Result | Condition                                                                                                 |
-| ------ | --------------------------------------------------------------------------------------------------------- |
-| Pass   | Pages contain substantive server-rendered content (headings, prose, code blocks)                          |
-| Warn   | Some content present but sparse (possible partial hydration or lazy loading)                              |
-| Fail   | SPA shell detected (framework markers like `id="__next"`, minimal visible text, no page-specific content) |
+| Result | Condition                                                                                                                      |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| Pass   | Pages contain substantive server-rendered content (headings, prose, code blocks)                                               |
+| Warn   | Pages render server-side but have unusually short body content (legitimately short pages, or partial hydration / lazy loading) |
+| Fail   | SPA shell detected (framework markers like `id="__next"`, minimal visible text, no page-specific content)                      |
+
+When the check warns, the [`sparse-content-html` diagnostic](/interaction-diagnostics#sparse-content-on-the-html-path) fires if more than 25% of sampled pages are sparse. When the check fails, the [`spa-shell-html-invalid` diagnostic](/interaction-diagnostics#spa-shells-invalidate-html-path) fires if more than 25% of sampled pages are actual shells.
 
 ### How to fix
 
-**If this check warns**, verify that key content is present in the server-rendered HTML response. Some pages may use component-level client rendering or lazy loading for specific sections.
+**If this check warns**, spot-check the affected pages by fetching them with `curl` or another HTTP client that doesn't run JavaScript. If the pages contain their full intended content, no action is needed; some pages are legitimately brief. If content is missing from the server response, the page may use component-level client rendering or lazy loading for specific sections.
 
 **If this check fails**, enable server-side rendering or static site generation in your docs platform. This is typically a configuration change, not a code rewrite.
 
 ### Score impact
 
-This is a Critical check with two score caps:
+This is a Critical check with two score caps based on a weighted proportion: `(serverRendered + sparseContent × 0.5) / total`. Empty SPA shells count fully against the proportion; sparse pages count at half weight.
 
-- At 50%+ SPA shells, the score is [capped at D (59)](/agent-score-calculation#score-caps).
-- At 75%+ SPA shells, the score is [capped at F (39)](/agent-score-calculation#score-caps).
+- When the proportion is at most 0.50, the score is [capped at D (59)](/agent-score-calculation#score-caps).
+- When the proportion is at most 0.25, the score is [capped at F (39)](/agent-score-calculation#score-caps).
 
-The `rendering-strategy` pass rate also drives the [HTML path coefficient](/agent-score-calculation#html-path-coefficient). If 90% of pages render correctly, HTML quality checks (`page-size-html`, `content-start-position`, `tabbed-content-serialization`, `section-header-quality`) count for 90% of their weight.
+The same proportion drives the [HTML path coefficient](/agent-score-calculation#html-path-coefficient). If 90% of pages render correctly with no sparse pages, HTML quality checks (`page-size-html`, `content-start-position`, `tabbed-content-serialization`, `section-header-quality`) count for 90% of their weight.
 
 ---
 

docs/improve-your-score.md

@@ -72,9 +72,11 @@ This also unblocks five dependent checks (`llms-txt-valid`, `llms-txt-size`, `ll
 
 **Enable server-side rendering**
 
-If `rendering-strategy` warns or fails, your site is delivering empty JavaScript shells to agents. Enable SSR or static site generation in your docs platform. This is typically a configuration flag, not a code change.
+If `rendering-strategy` fails, your site is delivering empty JavaScript shells to agents. Enable SSR or static site generation in your docs platform. This is typically a configuration flag, not a code change.
 
-At 50%+ SPA shells, the score is [capped at D](/agent-score-calculation#score-caps) regardless of everything else.
+If `rendering-strategy` warns, your pages render server-side but have unusually short body content. Spot-check a few of them with `curl` to confirm the full content is in the HTML response. If the pages are legitimately short, no action is needed. If content is missing, your renderer may be hydrating sections client-side; emitting them server-side will fix it.
+
+When SPA shells (and sparse pages, weighted at half) exceed half the sampled pages, the score is [capped at D](/agent-score-calculation#score-caps) regardless of everything else; when they exceed three quarters, it's capped at F.
 
 **Remove or work around authentication gates**