Update to Moknah

{
  "name": "moknah-studio-reference",
  "description": "Reference for operating Moknah Audio Studio - the Project/Chapter/Line data model, the tool call sequence, create_project options, batch editing, QA status codes, job polling, what costs credits, plan gating and hard limits. Use when you need the mechanics of a specific tool or option rather than a production workflow.",
  "included_files": [],
  "skill_md_contents": "---\nname: moknah-studio-reference\ndescription: Reference for operating Moknah Audio Studio - the Project/Chapter/Line data model, the tool call sequence, create_project options, batch editing, QA status codes, job polling, what costs credits, plan gating and hard limits. Use when you need the mechanics of a specific tool or option rather than a production workflow.\n---\n\n# Moknah Audio Studio reference\n\nMechanics and lookup tables. For workflows see `moknah-audiobook-production`;\nfor parameters see `moknah-voice-settings`.\n\n## Data model\n\n```\nProject -> Chapters -> Lines\n```\n\n- A **line** is one spoken unit and one TTS request.\n- A line is *converted* once it has rendered audio.\n- `total_chars` on a line means **billed** characters and is `0` until the line\n  renders. It is not the length of the text - never use it to estimate size.\n\nProjects persist. After an interruption call `get_project` and continue; never\nrestart a book.\n\n## Core call sequence\n\n1. `create_project(filename, file_base64, options)` -> returns a `job_ref`\n2. `get_job(job_ref)` every ~5 s until `is_terminal`; on failure read `error`\n3. `get_project(project_id)` to inspect chapters and lines\n4. `list_voices` -> `set_project_voice` (+ `set_line_voice_settings` for exceptions)\n5. `estimate_project_generation` / `estimate_edits` -> show credits, get approval\n6. `generate_audio(project_id, mode)` -> `job_ref` -> poll -> `get_job_result`\n\nUse `get_project` for an overview (chapters + counts, no line text - safe on huge\nbooks) and `get_chapter` only for chapters you actually need to read. Never\nre-fetch what you already have.\n\n## `create_project` options\n\n| Option | Values / meaning |\n|---|---|\n| `chapter_style` | `None` / `Heading 1` / `Heading 2` / `Title` - Word chapter detection |\n| `include_chapter_title` | keep the heading as the chapter title |\n| `normalization` | `\"0\"` Basic (free) · `\"2\"` AI-Enhanced (1 credit/char, file only, **Standard Arabic only** - applies contextual tashkeel) |\n| `enable_translation` | with `source_language` / `target_language` (file only; AI-Enhanced output is Arabic-only) |\n| `line_split_mode` | `sentences` / `newline` / `custom` (+ `line_split_custom`) |\n| `start_page` / `end_page` | PDF body range - skip cover, TOC, appendices |\n\nNever use AI-Enhanced normalization on dialects or non-Arabic text.\n\n## Standalone text-to-speech\n\n`text_to_speech(text, voice_id, settings?, confirm_spend)` needs no project and\nworks on **every plan**, including free.\n\n- `confirm_spend=false` (default) returns a **free estimate** and generates nothing\n- `confirm_spend=true` starts a **background** render and returns a `job_ref` -\n  poll `get_job` until `is_terminal`, then `get_job_result` for the public audio\n  URL. Rendering runs on the worker, so the call never times out even for long\n  text or the slower tashkeel / emotions settings.\n\n## Inline audio player\n\n`play_audio(audio_url= | job_ref=, title?)` renders an inline play button (the\n`ui://moknah/audio-player` MCP Apps widget) in hosts that support MCP Apps -\ne.g. ChatGPT. Pass the public audio URL from a finished render, or its `job_ref`\nand it resolves the URL for you. **Only Moknah audio is accepted** - the URL host\nmust be `moknah.io` or `*.moknah.io`, so the player can't be pointed at an\nexternal source. In hosts without MCP Apps (currently Claude) it returns the URL\ninstead of a rendered player.\n\nSettings overrides: `temperature`, `similarity`, `speed`, `expressiveness`,\n`emotions_mode`, `prerecording`. Omitted keys inherit the user's saved settings.\n\n## Batch editing - prefer this\n\n`update_lines` applies up to **200 edits in one request**. Each item is\n`{line_id, text?, settings?, qa_status?}` in any combination; items apply\nindependently and the response reports per-item ok/error.\n\nUse it for AI-QA corrections across a chapter, bulk revoicing, and QA sign-off.\nFall back to `update_line` / `set_line_voice_settings` only for a single line.\nNever loop single-line calls when one batch call would do.\n\n**Adding lines in bulk:** `add_lines(chapter_id, lines=[{text, position?, settings?,\nqa_status?}])` creates up to 200 new lines in ONE call (FREE), with per-item\nsuccess/failure and the new line ids. Prefer it over looping `add_line`. To split\na text blob into lines automatically instead, use `add_chapter(text=...)` or\n`create_project(text=...)`.\n\n**Reading in bulk:** `get_chapter(chapter_id)` returns all of a chapter's lines;\n`get_project(project_id, with_tree=true)` returns every line with text;\n`get_line_audio(line_ids=[...])` returns many lines' audio at once. Never fetch\nlines one at a time.\n\n## QA status codes\n\n| Code | Meaning |\n|---|---|\n| 1 | NotStarted |\n| 2 | InitialOutputReady |\n| 3 | UnderReview |\n| 4 | RevisionsRequired |\n| 5 | AwaitingReview |\n| 6 | Finalized |\n\n## Jobs\n\n`job_ref` is `<kind>:<id>` - e.g. `project:1234`, `chapter:58210`,\n`transcription:<uuid>`, `task:<uuid>`.\n\nPoll `get_job` until `is_terminal` (`completed` / `failed` / `cancelled`), then\n`get_job_result` for the artifact URL. `get_job_result` returns a URL, not bytes.\n\n## What costs credits\n\n**Free:** creating projects, editing text, reordering, voice settings, QA status,\n`merge_chapters_audio`, `merge_chapters_subtitle`, and every `estimate_*` call.\n\n**Billed:** generation (TTS), PDF OCR, AI-normalization, translation,\ntranscription, AI-QA.\n\nAlways call the matching `estimate_*` tool and show the number before a billable\naction. Never spend credits the user did not explicitly approve.\n\n### When credits run out\n\n`INSUFFICIENT_CREDITS` reports the shortfall. Tell the user plainly how much is\nmissing, offer to **reduce scope** as a real option (rendering one chapter now is\na legitimate answer), and point them to their Moknah account to manage their plan.\nTreat it as a next step, never a dead end.\n\n## Access rules - absolute\n\n- **Owner or team only.** Every tool re-checks permissions on each object. Other\n  users' content is invisible and untouchable.\n- **No admin.** Staff and superuser privileges are stripped over MCP. There is no\n  tool for any admin page or feature and none will succeed. Never offer one.\n- **Plan gate.** Studio tools raise `UPGRADE_REQUIRED` for plans without Audio\n  Studio.\n\nTools that work on **every** plan, including free:\n`text_to_speech`, `list_voices`, `play_voice_sample`, `estimate_text_to_speech`,\n`check_credits`, `get_balance`, `get_job`, `get_job_result`, `download_result`.\n\n## Hard limits\n\n| Limit | Value |\n|---|---|\n| Lines per chapter | 200 |\n| Characters per request, emotions ON | 3,000 |\n| Characters per request, emotions OFF | 10,000 |\n| Breaks per line | 20 |\n| Total pause per line | 30 s |\n| PDF upload | 50 MB |\n| Batch edits per `update_lines` call | 200 |\n\nDestructive tools (`delete_project`, `delete_chapter`, `delete_line`) require\n`confirm=true`.\n"
}