fix(docs): enhance PQL manifest documentation for clarity and detail

[StarpTech]

Summary by CodeRabbit

• New Features

  • Introduced configurable manifest file name setting for persisted operations (PERSISTED_OPERATIONS_MANIFEST_FILE_NAME), allowing customization of the manifest filename with support for compression extensions.

• Documentation

  • Updated persisted operations documentation to clarify manifest file handling, compression support, and CDN mode behavior.

Checklist

• I have discussed my proposed changes in an issue and have received approval to proceed.
• I have followed the coding standards of the project.
• Tests or benchmarks have been added or updated.
• Documentation has been updated on https://github.com/wundergraph/docs-website.
• I have read the Contributors Guide.

Open Source AI Manifesto

This project follows the principles of the Open Source AI Manifesto. Please ensure your contribution aligns with its principles.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
wundergraphinc	🟢 Ready	View Preview	Apr 2, 2026, 10:38 AM

[coderabbitai]

Walkthrough

Updated documentation and JSON schema to clarify persisted operations manifest file configuration. Added a new PERSISTED_OPERATIONS_MANIFEST_FILE_NAME configuration option with details on object path construction, compression support, and CDN mode behavior. Removed hardcoded filename references in docs.

Changes

Cohort / File(s)	Summary
Documentation Updates docs-website/router/configuration.mdx, docs-website/router/persisted-queries/persisted-operations.mdx	Added and updated documentation for manifest file configuration: clarified generic "manifest file" terminology (removing hardcoded manifest.json references), documented new PERSISTED_OPERATIONS_MANIFEST_FILE_NAME config option with object path construction details, compression extension support, and CDN mode behavior.
Schema Definition router/pkg/config/config.schema.json	Updated manifest.file_name schema description to clarify relevance only for custom storage providers and ignoring in CDN mode while noting compression support.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• fix: validate filename and improve PQL docs #2733: Addresses the same persisted-operations manifest filename configuration topic with overlapping documentation and schema scope.
• feat(pqlmanifest): implement S3 polling support for PQL manifest #2726: Implements code and config changes for manifest file_name functionality that these documentation and schema updates clarify and document.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: enhancing PQL manifest documentation for clarity and detail across multiple documentation files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Router-nonroot image scan passed

✅ No security vulnerabilities found in image:

ghcr.io/wundergraph/cosmo/router:sha-b03a13606df4c8b17895abc85347967d8069e8ad-nonroot

[coderabbitai]

🧹 Nitpick comments (2)

docs-website/router/persisted-queries/persisted-operations.mdx (1)

121-121: Consider splitting the sentence for improved clarity.

The sentence packs multiple ideas into one complex structure. As per coding guidelines: "Prefer short, declarative sentences. If a sentence has more than one comma-separated clause, consider splitting it."

✨ Optional refinement for clarity

-By default, the router fetches persisted operations individually from the Cosmo CDN on each request. When the **PQL manifest** is enabled, the router instead loads all persisted operations from a single manifest file at startup and serves them entirely from memory, eliminating per-request network overhead.
+By default, the router fetches persisted operations individually from the Cosmo CDN on each request. When the **PQL manifest** is enabled, the router loads all persisted operations from a single manifest file at startup. Operations are served entirely from memory, eliminating per-request network overhead.

Based on learnings, As per coding guidelines: "Prefer short, declarative sentences. If a sentence has more than one comma-separated clause, consider splitting it."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs-website/router/persisted-queries/persisted-operations.mdx` at line 121,
The paragraph describing persisted operations is a long sentence that combines
multiple ideas; split it into two short, declarative sentences: one stating the
default behavior (“By default, the router fetches persisted operations
individually from the Cosmo CDN on each request.”) and a second explaining the
alternative when the PQL manifest is enabled (“When the PQL manifest is enabled,
the router loads all persisted operations from a single manifest file at startup
and serves them entirely from memory, eliminating per-request network
overhead.”). Update the sentence that mentions the PQL manifest and persisted
operations to follow this split so each clause is its own clear sentence.

docs-website/router/configuration.mdx (1)

1178-1179: Split these descriptions into short factual sentences for readability.

Both cells pack several behaviors into long clauses. Breaking them into short statements will match the doc style guide and make the table easier to scan.

Proposed rewrite

-| PERSISTED_OPERATIONS_MANIFEST_ENABLED      | persisted_operations.manifest.enabled      | <Icon icon="square" />                        | Enable the PQL manifest. When enabled, the router loads all persisted operations from a single manifest file and serves them from memory. Uses the `storage` config above when a provider is set, otherwise fetches from the Cosmo CDN. Only S3 and CDN storage providers are supported. | false         |
-| PERSISTED_OPERATIONS_MANIFEST_FILE_NAME    | persisted_operations.manifest.file_name    | <Icon icon="square" />                        | The manifest file name. Only used when a custom storage provider is configured. The router resolves the full object path as `<object_prefix>/<file_name>`. Use a `.gz` or `.zst` extension (e.g. `manifest.json.gz`) to enable transparent decompression. Ignored in CDN mode. | manifest.json |
+| PERSISTED_OPERATIONS_MANIFEST_ENABLED      | persisted_operations.manifest.enabled      | <Icon icon="square" />                        | Enable the PQL manifest. The router loads persisted operations from one manifest file and serves them from memory. If a storage provider is set, the router uses `persisted_operations.storage`. If no provider is set, the router fetches from the Cosmo CDN. Supported providers are S3 and CDN. | false         |
+| PERSISTED_OPERATIONS_MANIFEST_FILE_NAME    | persisted_operations.manifest.file_name    | <Icon icon="square" />                        | Manifest file name. Used only with a custom storage provider. The router resolves the object path as `<object_prefix>/<file_name>`. `.gz` and `.zst` extensions (for example `manifest.json.gz`) enable transparent decompression. Ignored in CDN mode. | manifest.json |

As per coding guidelines: "Prefer short, declarative sentences. If a sentence has more than one comma-separated clause, consider splitting it." and "Use structured lists when presenting multiple distinct items. Do not pack them into a single paragraph."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs-website/router/configuration.mdx` around lines 1178 - 1179, Split the
long table descriptions for PERSISTED_OPERATIONS_MANIFEST_ENABLED and
PERSISTED_OPERATIONS_MANIFEST_FILE_NAME into short, declarative sentences: for
PERSISTED_OPERATIONS_MANIFEST_ENABLED (persisted_operations.manifest.enabled)
break into separate sentences stating that it enables the PQL manifest, that
when enabled the router loads persisted operations from a single manifest file
and serves them from memory, that it uses the configured storage provider when
set otherwise fetches from the Cosmo CDN, and that only S3 and CDN providers are
supported; for PERSISTED_OPERATIONS_MANIFEST_FILE_NAME
(persisted_operations.manifest.file_name) split into sentences stating it is the
manifest file name, that it is only used with a custom storage provider, how the
router resolves the full object path (<object_prefix>/<file_name>), the note
about using .gz or .zst to enable transparent decompression, and that it is
ignored in CDN mode.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs-website/router/configuration.mdx`:
- Around line 1178-1179: Split the long table descriptions for
PERSISTED_OPERATIONS_MANIFEST_ENABLED and
PERSISTED_OPERATIONS_MANIFEST_FILE_NAME into short, declarative sentences: for
PERSISTED_OPERATIONS_MANIFEST_ENABLED (persisted_operations.manifest.enabled)
break into separate sentences stating that it enables the PQL manifest, that
when enabled the router loads persisted operations from a single manifest file
and serves them from memory, that it uses the configured storage provider when
set otherwise fetches from the Cosmo CDN, and that only S3 and CDN providers are
supported; for PERSISTED_OPERATIONS_MANIFEST_FILE_NAME
(persisted_operations.manifest.file_name) split into sentences stating it is the
manifest file name, that it is only used with a custom storage provider, how the
router resolves the full object path (<object_prefix>/<file_name>), the note
about using .gz or .zst to enable transparent decompression, and that it is
ignored in CDN mode.

In `@docs-website/router/persisted-queries/persisted-operations.mdx`:
- Line 121: The paragraph describing persisted operations is a long sentence
that combines multiple ideas; split it into two short, declarative sentences:
one stating the default behavior (“By default, the router fetches persisted
operations individually from the Cosmo CDN on each request.”) and a second
explaining the alternative when the PQL manifest is enabled (“When the PQL
manifest is enabled, the router loads all persisted operations from a single
manifest file at startup and serves them entirely from memory, eliminating
per-request network overhead.”). Update the sentence that mentions the PQL
manifest and persisted operations to follow this split so each clause is its own
clear sentence.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 86372e7f-de40-4fb2-b2e5-b258cfafd396

📥 Commits

Reviewing files that changed from the base of the PR and between 973c8dc and 3da01ef.

📒 Files selected for processing (3)

• docs-website/router/configuration.mdx
• docs-website/router/persisted-queries/persisted-operations.mdx
• router/pkg/config/config.schema.json

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 63.19%. Comparing base (0a35c0e) to head (3da01ef).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2734      +/-   ##
==========================================
- Coverage   63.24%   63.19%   -0.05%     
==========================================
  Files         251      251              
  Lines       26763    26763              
==========================================
- Hits        16925    16913      -12     
- Misses       8460     8470      +10     
- Partials     1378     1380       +2     

see 4 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.