docs: clarify content sync flows

[osamasayed]

Summary

• Add a Content Sync tutorial section with client-first flow diagrams, terminology, cache guidance, and recovery behavior.
• Improve Content Sync OpenAPI descriptions/examples and regenerate sync/snapshot reference pages.
• Add a Mermaid regression test for Content Sync sequence diagrams after the localhost parse failure.

Validation

• node --test tests/content-sync-mermaid.test.cjs
• node --test tests/*.test.cjs
• jq empty openAPI/content/v4.json
• git diff --check
• Local docs page /docs/tutorials/content-sync/getting-started/: previously verified in Chrome DevTools with no console errors after the Mermaid fix.

[cloudflare-workers-and-pages]

Deploying qf-api-docs with    Cloudflare Pages

Latest commit:	44281be
Status:	✅  Deploy successful!
Preview URL:	https://c8ed817d.qf-api-docs.pages.dev
Branch Preview URL:	https://docs-content-sync-devex.qf-api-docs.pages.dev

View logs

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 144f3ff684

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR expands the documentation around the Content Sync feature by adding a new tutorial section (with flow/sequence diagrams and caching guidance), improving the Content Sync OpenAPI descriptions/examples, and adding a regression test to ensure the tutorial’s Mermaid sequence diagrams continue to parse correctly.

Changes:

• Added a new “Content Sync” tutorials section (Getting Started, Client Flow, Offline Cache Patterns, Full Copies & Recovery).
• Updated Content Sync OpenAPI descriptions/schemas/examples and regenerated the corresponding reference pages.
• Added a Node test that parses Mermaid sequenceDiagram blocks in the new tutorial docs.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/content-sync-mermaid.test.cjs	Adds a regression test that parses Mermaid sequence diagrams from the Content Sync tutorial MDX files.
sidebars.js	Adds a new Tutorials sidebar category linking to the Content Sync tutorial pages.
openAPI/content/v4.json	Updates Content Sync endpoint descriptions and adds richer examples/schemas for sync & snapshot operations.
docs/tutorials/content-sync/category.json	Defines the generated index metadata for the new Content Sync tutorial section.
docs/tutorials/content-sync/getting-started.mdx	Introduces Content Sync terminology and the basic bootstrap/incremental client flow with diagrams.
docs/tutorials/content-sync/client-flow.mdx	Documents a recommended end-to-end client algorithm, pagination rules, and token rules.
docs/tutorials/content-sync/offline-cache-patterns.mdx	Provides offline caching patterns, schema suggestions, and transactional replacement guidance.
docs/tutorials/content-sync/full-copies-and-recovery.mdx	Explains snapshot usage, unavailable resources behavior, and error recovery flows.
docs/content_apis_versioned/resources-sync.api.mdx	Regenerated reference page reflecting the updated OpenAPI sync documentation/examples.
docs/content_apis_versioned/resources-snapshot.api.mdx	Regenerated reference page reflecting the updated OpenAPI snapshot documentation/examples.
docs/content_apis_versioned/4.0.0/resources-sync.api.mdx	Regenerated versioned reference page, but its sidebar/info frontmatter now differs from other 4.0.0 docs (needs correction).
docs/content_apis_versioned/4.0.0/resources-snapshot.api.mdx	Regenerated versioned reference page, but its sidebar/info frontmatter now differs from other 4.0.0 docs (needs correction).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

openAPI/content/v4.json:20427

• record_type is defined with a $ref plus a sibling description. Under OpenAPI 3.0 rules, sibling fields on a Reference Object are ignored, so consumers may not see the intended “row-level vs resource-level” guidance. Prefer expressing this via allOf (with the $ref) or by incorporating the guidance into ContentSyncRecordType’s own description.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated no new comments.