Docs: JavaScript SDK onboarding, starter workflow, and generated API sync

[basit3407]

Summary

This PR updates the public API docs for the coordinated JavaScript SDK, starter kit, and create-app rollout.

The docs now present the runtime-specific SDK entrypoints as the recommended path for new code:

• @quranjs/api/server for backend, serverless, worker, Content, Search, and confidential OAuth2 flows.
• @quranjs/api/public for browser/mobile PKCE and frontend user-session flows.

The SDK remains backwards-compatible: existing import { QuranClient } from "@quranjs/api" integrations are still supported. The migration docs now describe the split entrypoints as recommended cleanup, not a breaking upgrade requirement.

What Changed

• Clarified that word.audioUrl is a relative word-by-word asset path resolved against https://audio.qurancdn.com/, not a Content API endpoint.
• Updated JavaScript SDK onboarding docs for the public/server runtime split.
• Clarified legacy root QuranClient compatibility across the SDK index, entrypoint matrix, and migration guides.
• Documented the npx @quranjs/create-app@latest ... starter path on onboarding pages.
• Added canonical AI handoff prompt markers expected by the docs tests.
• Fixed the docs test script to run cross-platform with node --test tests.
• Added TypeScript declarations for OpenAPI theme modules used by the custom ApiDemoPanel curl sample override.
• Committed generated API docs that yarn build was recreating, eliminating generated-doc drift.
• Restored Cloudflare production build helpers: postbuild:seo and generated API alias cleanup.
• Ignored .claude/ worktree noise so local tooling does not pollute repo status.

Coordinated PRs

• API SDK: SDK updates: runtime-split Quran API clients and generated contracts api-js#49
• Starter kit: https://github.com/quran/qf-starter-kit/pull/1
• Create app: https://github.com/quran/quranjs-create-app/pull/1
• API docs: Docs: JavaScript SDK onboarding, starter workflow, and generated API sync #147

Required Merge Order

1. Merge and release SDK updates: runtime-split Quran API clients and generated contracts api-js#49 first.
2. Merge https://github.com/quran/qf-starter-kit/pull/1 second, after the SDK release is available on npm.
3. Merge https://github.com/quran/quranjs-create-app/pull/1 third, after the starter template is finalized.
4. Merge this docs PR last, so public docs match the final released SDK, starter, and create-app behavior.

Validation

Previously run locally on Windows/PowerShell:

• yarn test
• yarn typecheck
• yarn build
• yarn re-gen && npx docusaurus build && yarn postbuild:seo

For the latest docs-only compatibility clarification, no full rebuild was rerun. The targeted checks were:

• git diff --check -- docs/sdk/javascript/index.mdx docs/sdk/javascript/entrypoint-matrix.mdx docs/sdk/javascript/migration-cheat-sheet.mdx docs/sdk/javascript/v1-migration-guide.mdx
• Targeted search for stale mandatory-migration wording in docs/sdk/javascript/*.mdx

Cross-Repo Validation

Manually validated that the documented SDK, starter kit, and create-app flow works together in a generated Next.js app using pre-live credentials.

• Built the local SDK branch and installed it into a generated starter app.
• Scaffolded the app through the local create-app branch and synced starter template.
• Passed generated-app smoke checks: npm run smoke:config and npm run smoke:routes.
• Passed focused starter tests in the generated app: 16 passed.
• Verified live pre-live SDK calls for Content, Search, and signed-in User APIs.
• Signed-in user smoke covered OIDC userinfo, QuranReflect profile, bookmark list read, note create/delete, and collection create/delete.

Reviewer Notes

• This docs PR should merge last because it describes the final developer-facing flow.
• The generated API docs included here are intentional; they remove generated-doc drift from the production build.
• The docs reference @quranjs/create-app@latest, so the create-app package should be publish-ready before these docs are promoted.

Linked Issues

Closes quran/api-js#47.

[cloudflare-workers-and-pages]

Deploying qf-api-docs with    Cloudflare Pages

Latest commit:	bcdd02a
Status:	✅  Deploy successful!
Preview URL:	https://58788b62.qf-api-docs.pages.dev
Branch Preview URL:	https://sdk-updates.qf-api-docs.pages.dev

View logs

[Copilot]

Pull request overview

This PR updates the public documentation site to match the new JavaScript SDK runtime split (@quranjs/api/server vs @quranjs/api/public), adds an NPX-based starter onboarding path, and syncs generated/derived docs outputs and supporting build/test tooling.

Changes:

• Adds/updates JS SDK docs for the new runtime entrypoints, including new “matrix/quickstart” pages and updated endpoint pages.
• Adds an npx @quranjs/create-app@latest ... starter tutorial and enforces onboarding consistency via new node:test checks.
• Updates llms.txt generation ordering/URL normalization and adds TS declaration shims for OpenAPI theme modules used by the custom API demo panel.

Reviewed changes

Copilot reviewed 27 out of 29 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/tutorials-onboarding-docs.test.cjs	Adds tests enforcing the public NPX scaffold command + canonical prompt marker + no local-only patterns on key onboarding pages.
tests/sdk-docs-config.test.cjs	Adds tests asserting new JS SDK docs are present in shared sidebars and excluded from llms output where appropriate.
src/theme/openapi-theme.d.ts	Adds TS module declarations for theme modules used by custom OpenAPI demo panel overrides.
sidebars.js	Adds the new JS SDK doc IDs into the shared “SDKs → JS/TS” sidebar items.
plugins/llms-txt-plugin.js	Reorders sections, normalizes slug-to-URL behavior, and prioritizes key JS SDK/onboarding pages in llms output.
docs/tutorials/oidc/user-apis-quickstart.mdx	Adds a pointer to the recommended JS SDK runtime split and the NPX starter tutorial.
docs/tutorials/oidc/starter-with-npx.mdx	Adds a new public onboarding tutorial for scaffolding via npx @quranjs/create-app@latest.
docs/tutorials/oidc/getting-started-with-oauth2.mdx	Adds the “Fastest Way To Start” scaffold section + canonical prompt marker.
docs/tutorials/oidc/example-integration.mdx	Adds a scaffold-first note before the standalone OAuth2 example.
docs/tutorials/oidc/client-setup.mdx	Rewrites/condenses OAuth2 client setup guidance and frontmatter metadata.
docs/sdk/javascript/index.mdx	Rewrites the SDK landing page around runtime entrypoints, scaffold onboarding, and AI handoff prompt.
docs/sdk/javascript/app-shapes.mdx	Adds an “app shapes” decision guide mapping app type → runtime → API families.
docs/sdk/javascript/runtime-matrix.mdx	Adds a runtime capabilities matrix for server vs public usage.
docs/sdk/javascript/auth-matrix.mdx	Adds a concise matrix explaining confidential vs public vs proxy client patterns.
docs/sdk/javascript/entrypoint-matrix.mdx	Adds a quick reference mapping import path → intended use.
docs/sdk/javascript/apis-by-runtime.mdx	Adds a matrix mapping API families to supported runtimes.
docs/sdk/javascript/server-quickstart.mdx	Adds a backend-focused SDK quickstart page.
docs/sdk/javascript/public-quickstart.mdx	Adds a frontend/mobile focused quickstart page for the public entrypoint.
docs/sdk/javascript/full-stack.mdx	Adds a recommended full-stack (public+server) architecture quickstart.
docs/sdk/javascript/common-errors.mdx	Adds a common errors table tailored to the runtime split.
docs/sdk/javascript/migration-cheat-sheet.mdx	Adds a compact migration cheat sheet from legacy client usage to entrypoints.
docs/sdk/javascript/v1-migration-guide.mdx	Replaces the legacy migration guide content with a brief pointer to new entrypoints.
docs/sdk/javascript/chapters.mdx	Updates Chapters docs to the new client.content.v4.* server usage pattern.
docs/sdk/javascript/verses.mdx	Updates Verses docs to the new server client usage pattern.
docs/sdk/javascript/audio.mdx	Updates Audio docs to the new server client usage pattern.
docs/sdk/javascript/resources.mdx	Updates Resources docs to the new server client usage pattern.
docs/sdk/javascript/juzs.mdx	Updates Juzs docs to the new server client usage pattern.
docs/sdk/javascript/search.mdx	Updates Search docs to the new client.search.v1.query server usage pattern.
.gitignore	Ignores .claude/ worktree noise.

---

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

[Copilot]

Pull request overview

Copilot reviewed 27 out of 29 changed files in this pull request and generated 9 comments.

---

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

[basit3407]

Ported the remaining word-by-word audio clarification from superseded #123 / quran/api-js#48 into this PR. The docs now explain that word.audioUrl is a relative wbw asset path resolved against https://audio.qurancdn.com/, and is distinct from chapter or ayah recitation audio.

[Copilot]

Pull request overview

Copilot reviewed 47 out of 49 changed files in this pull request and generated 3 comments.

---

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (4)

src/components/AgentPromptCallout/index.tsx:1

• The prompt content is hardcoded here but also exists as a canonical public artifact in static/agent-prompts/qf-next-starter.md (and is referenced from static/.well-known/agent-prompts/index.json). Maintaining multiple sources of truth increases drift risk (formatting, wording, even the presence of the prompt ID header). Consider making the “Copy prompt” payload derive from the canonical prompt artifact (e.g., fetch /agent-prompts/qf-next-starter.md at click time, or generate both the static file and this in-code constant from a single build-time source) so the copied text always matches the published prompt verbatim.
  src/pages/index.tsx:1
• This clipboard helper is duplicated (a nearly identical copyText exists in src/components/AgentPromptCallout/index.tsx). Duplication makes it easy for fallback behavior, error handling, or future browser compatibility tweaks to diverge between “copy command” and “copy prompt”. Consider extracting a shared utility/hook (e.g., copyToClipboard(text)) and reusing it in both places.
  sidebars.js:1
• The sidebar ordering places migration-cheat-sheet before v1-migration-guide, but the docs front matter sets v1-migration-guide to sidebar_position: 14 and migration-cheat-sheet to sidebar_position: 16, implying the opposite order. Since this sidebar is explicitly ordered, the sidebar_position values become misleading metadata for future maintainers. Consider either adjusting the explicit sidebar order to match the declared positions or removing/aligning the sidebar_position fields for these pages to avoid contradictory sources of ordering truth.
  tests/prelive-docs-config.test.cjs:1
• urls.filter(... urls.indexOf(...) ...) is O(n²) and llms.txt can grow to hundreds/thousands of links as docs expand. Using a Set to detect duplicates in a single pass keeps this test linear and avoids slowing CI as the docs corpus grows.

---

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

[Copilot]

Pull request overview

Copilot reviewed 50 out of 52 changed files in this pull request and generated 3 comments.

---

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