docs: clarify word audio vs recitation audio usage

docs/sdk/javascript/audio.mdx

@@ -6,7 +6,15 @@ slug: /sdk/javascript/audio
 
 import Link from "@docusaurus/Link";
 
-The Audio API provides access to audio recitations including chapter audio and verse-by-verse audio with timing.
+The Audio API provides access to recitation audio from the authenticated Content API, including chapter audio and verse-by-verse audio with optional timing data.
+
+## Choose the Right Audio Source
+
+| Use case | Fetch from | Returned shape | Notes |
+| --- | --- | --- | --- |
+| Single-word pronunciation | `word.audioUrl` from the [Verses API](/docs/sdk/javascript/verses) | Relative `wbw/...` asset path | Resolve it against `https://audio.qurancdn.com/` before playing it in the browser. |
+| Chapter playback | `client.audio.findAllChapterRecitations()` or `client.audio.findChapterRecitationById()` | Full chapter `audioUrl` | Use this for continuous chapter playback. |
+| Ayah playback with timing | `client.audio.findVerseRecitationsByChapter()` or `client.audio.findVerseRecitationsByKey()` | Verse recitation `url` plus optional `segments` | Use this for ayah recitations and highlighting. This is distinct from `word.audioUrl`. |
 
 ## Chapter Recitations
 
@@ -33,7 +41,7 @@ console.log(recitations[0]);
 | `chapterId` | `number` | Surah that the audio recitation belongs to.     |
 | `fileSize`  | `number` | File size in bytes.                             |
 | `format`    | `string` | Audio format, typically `mp3`.                  |
-| `audioUrl`  | `string` | Download URL for the chapter recitation.        |
+| `audioUrl`  | `string` | Full chapter recitation URL returned by the Content API. |
 
 ### Get Specific Chapter
 
@@ -65,13 +73,13 @@ audioFiles.forEach((audio) => {
 | Field       | Type        | Notes                                             |
 | ----------- | ----------- | ------------------------------------------------- |
 | `verseKey`  | `string`    | Verse identifier such as `2:255`.                 |
-| `url`       | `string`    | Direct URL to the verse audio file.               |
+| `url`       | `string`    | Verse recitation URL or path returned by the Content API. Distinct from `word.audioUrl`. |
 | `id`        | `number`    | Unique identifier for the verse recitation.       |
 | `chapterId` | `number`    | Surah that the verse belongs to.                  |
 | `segments`  | `Segment[]` | Optional timing metadata for word-level playback. |
 | `format`    | `string`    | Audio format, e.g. `mp3`.                         |
 
-`Segment` entries include the timestamp ranges (`start`, `end`) that power word-level playback.
+`Segment` entries include the timestamp ranges (`start`, `end`) that power highlighting and seek within the recitation.
 
 ### By Verse Key
 

docs/sdk/javascript/index.mdx

@@ -9,6 +9,8 @@ import TabItem from "@theme/TabItem";
 
 The official JavaScript/TypeScript SDK for the Quran.Foundation API. Works in Node.js and browsers.
 
+> Note: The SDK can run in browser code, but keep `clientSecret` on your server and make authenticated Content API calls from a backend or server-side runtime. Public word-by-word audio playback uses the separate `word.audioUrl` asset path described in the [Verses API](/docs/sdk/javascript/verses) and the backend-safe auth flow described in the [Content APIs Quickstart](/docs/quickstart/).
+
 <p>
   <a
     href="https://www.npmjs.com/package/@quranjs/api"

docs/sdk/javascript/verses.mdx

@@ -71,6 +71,30 @@ const verse = await client.verses.findByKey("1:1", {
 });
 ```
 
+Requesting `words: true` can include `word.audioUrl` for each word. That value is a relative word-by-word asset path such as `wbw/001_001_001.mp3`, not a `/content/api/v4/...` endpoint.
+
+### Word Audio Paths
+
+```ts
+const verse = await client.verses.findByKey("1:1", {
+  words: true,
+  wordFields: {
+    audio: true,
+    location: true,
+  },
+});
+
+const firstWord = verse.words?.[0];
+const wordAudioUrl = firstWord
+  ? new URL(
+      firstWord.audioUrl.replace(/^\/+/, ""),
+      "https://audio.qurancdn.com/",
+    ).toString()
+  : null;
+```
+
+Use `word.audioUrl` for single-word pronunciation playback. For chapter or ayah recitations, and for timing `segments`, use the [Audio API](/docs/sdk/javascript/audio) instead.
+
 ### With Tafsir
 
 ```ts
@@ -132,6 +156,7 @@ const random = await client.verses.findRandom({
 const verse = await client.verses.findByKey("1:1", {
   words: true,
   wordFields: {
+    audio: true,
     textUthmani: true,
     verseKey: true,
     location: true,