Single-source provider guides: bundled docs/guides catalog serving MCP, /guides pages, and raw text/markdown

[kentcdodds]

Summary

Provider connect guides existed only as agent-improvised prompts ("walk me through creating my own OAuth app"), and coding_guide_get fetched docs/guides/*.md from raw.githubusercontent.com at request time. This PR makes docs/guides/ a single bundled source of truth served three ways, and adds five verified provider connect guides.

• Guide catalog (packages/worker/src/guides/): every guide carries YAML frontmatter (id, title, summary, category, provider, lastVerified); markdown is imported at build time (same pattern as blog posts) so MCP, web, and raw-markdown responses always serve identical deployed content.
• coding_guide_get now serves the bundled catalog — no request-time GitHub dependency; enum, per-guide descriptions, and search keywords derive from frontmatter. openapi_integrations becomes loadable for the first time.
• Web pages /guides and /guides/:slug (blog-area chunk, SSR + .json twins), with a Guides link in the site header and footer.
• Markdown content negotiation: /guides.md, /guides/:slug.md, /blog/:slug.md, plus Accept: text/markdown on the HTML routes (Vary: Accept; HTML wins ties so browsers are unaffected).
• Five provider guides (docs/guides/providers/): Google, GitHub, Notion, Spotify, Discord — verified console steps (August 2026), prefilled /connect/oauth / /account/secrets/new links, personal-token lanes where they exist, minimal-scope tiers, execute smoke tests, and the sharp edges (Google's Testing-mode 7-day refresh-token trap, Spotify's Premium requirement, Discord's OAuth-vs-bot split, Gmail restricted scopes).
• Surfacing: integrations-page suggestion cards gain "Setup guide" links and guide-first copyable prompts (plus a Notion card); the onboarding setup prompt points agents at provider_* guides; docs updated (docs/guides/README.md, docs/use/first-steps.md, docs/use/index.md). A parity test pins suggestion guideSlugs to real catalog entries.
• UI primitives: markdown renderer gains an opt-in first-party link policy (root-relative links like /connect/oauth?..., user-scope paths still refused) and copyable code blocks (copy-code-block.tsx); the untrusted default is unchanged.

Testing

• npm run validate fully green (all 12 jobs: 1882 unit tests, 8 Playwright e2e, MCP e2e, lint/format/typecheck/docs checks).
• New unit tests: frontmatter contract + catalog integrity, markdown negotiation, guide handlers, coding_guide_get serving every bundled guide, integration-suggestion ↔ catalog parity.
• Manual dev-server verification of all four markdown lanes (.md twins, Accept: text/markdown, browser Accept → HTML, blog twin) and a recorded browser walkthrough.
• The copy button's click → "Copied" cycle was additionally verified headless (with and without clipboard permission) after an automation false alarm — logs showed the interaction healthy end to end.

System recap — extends existing primitives (medium risk)

Mode: recap · Base: main @ 34614dc1 · Head: 00d3bf8d

Classification: extends — no new taxonomy primitive; app-ui gains routes/negotiation and capability-registry's coding_guide_get changes its content source from runtime GitHub fetch to the build-time guide catalog (new shared module packages/worker/src/guides/, plumbing under existing primitives).

Primitives touched

Primitive	Group	Impact
app-ui	surfaces	extends — /guides routes, .md twins + Accept: text/markdown negotiation, first-party markdown links, copyable code blocks
capability-registry	assistant	extends — coding_guide_get serves the bundled catalog; enum/keywords derive from guide frontmatter
app-sessions	auth	composes — onboarding setup prompt copy only (onboarding-data.ts)

System map

Guide markdown flows from docs/guides/ through the bundled catalog into both the MCP capability and the web routes.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	guides["docs/guides/*.md<br/>frontmatter + body"]:::touched
	catalog["guides catalog<br/>build-time bundle (#worker/guides)"]:::touched
	appUi["app-ui<br/>Browser app (Remix 3)"]:::extended
	capabilityRegistry["capability-registry<br/>Capability registry"]:::extended
	guides -->|"import at build time"| catalog
	catalog -->|"coding_guide_get body/title from frontmatter id"| capabilityRegistry
	catalog -->|"/guides + /guides/:slug SSR + .json"| appUi
	catalog -->|"/guides/:slug.md + Accept: text/markdown"| appUi
	appUi -->|"Setup guide links + guide-first prompts on /account/integrations"| catalog
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Before / after

before: coding_guide_get -> fetch raw.githubusercontent.com/main/docs/guides/<file>.md (runtime network dependency)
after:  coding_guide_get -> bundled guide catalog (deployed content, no network); web + raw markdown serve the same bundle

before: GET /guides -> 404
after:  GET /guides | /guides.json | /guides.md | /guides/:slug | .json | .md ; blog posts gain /blog/:slug.md

Invariants

Per-user isolation untouched: guides are static repo content with no user data; the untrusted markdown link policy (user-scope refusal) stays the default and applies under the first-party policy too.

  

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 23b32287-1eaa-4282-b115-8b4927429b86

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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