| language_get_vocabulary | Return a flattened vocabulary list for the given scenario id or slug. Combines every vocabulary_list section into one array. | — |
| language_practice_dialogue | Return a roleplay starter prompt for the speaker at speakerIndex in the scenario's first dialogue section. | — |
| language_generate_exercise | Generate a new exercise of the given type (fill_blank / translate / multiple_choice / matching / short_answer) based on the scenario content. | — |
| language_create_scenario | Create a new language scenario in DRAFT status. Returns { scenarioId, slug, title, sectionIds[] }. Slug auto-generated. Required: title + targetLanguage (ISO 639-1/BCP-47) + nativeLanguage + level (CEFR A1..C2). When seedDefaults=true the 7 default sections (dialogue/vocabulary_list/grammar_note/exercise/visual/audio/cultural_note) are pre-populated; otherwise the scenario starts empty. Caller must be authenticated. | — |
| language_add_section | Append a typed section to an existing language scenario. Accepts scenarioId (cuid or slug) + sectionType (dialogue|vocabulary_list|grammar_note|exercise|visual|audio|cultural_note) + content (typed per sectionType — pass null/omit to use the type default) + optional chapterId (same scenario; sections read in chapter.order → section.order). Returns { sectionId, key, order, typeId, versionId }. Validates moduleId === "language". Auto-assigns next order; key defaults to "<typeId>-<order>" if omitted. NOTE: authoring a multi-chapter scenario with parallel agents — split work by chapter (one writer per chapter) or use language_add_sections to write a whole chapter atomically. | — |
| language_add_sections | Append MULTIPLE typed sections to a language scenario in ONE atomic call — the array order IS the reading order, so parallel agents cannot interleave even within the same chapter. Accepts scenarioId (cuid or slug) + optional chapterId (same scenario; ALL sections placed there) + sections[] (1-50, each { sectionType, content?, label?, key? }; content null/omit → type default). Prefer one add_sections call per chapter when authoring a multi-chapter scenario. Returns { scenarioId, scenarioSlug, chapterId, sections: [{ sectionId, key, order, typeId, versionId }] }. Caller must be authenticated. | — |
| language_create_collection | Create a new Course-typed collection (language module). Returns { collectionId, slug, title, type, itemCount, addedScenarioIds }. Slug auto-generated from title (collision-suffixed). Optionally pre-populate with caller-owned language scenarios (scenarios: id or slug, max 50; non-owned or non-language silently skipped). Caller must be authenticated; ownership = ctx.user. | — |
| language_update_section | Update a language section's content and/or label. content is FULL replace (no field merge) — caller sends whole content object, validated against the section's typeId schema (one of: dialogue, vocabulary_list, grammar_note, exercise, visual, audio, cultural_note). Creates new SectionVersion when content changes, no-op when hash matches. Caller must own the parent scenario. Returns { sectionId, versionId, version, contentHash, contentChanged, labelChanged }. At least one of content/label required. label:null removes the label. | — |
| language_convert_section | Convert a language section to a DIFFERENT section type (e.g. exercise → dialogue) IN PLACE: order, chapterId and key are preserved so the section keeps its exact position in the scenario. Because typeId is immutable, this deletes the old section and recreates it at the same slot with the new type — the section's id changes and the OLD version history is discarded (expected, inherent to type change). content is the FULL new content object, validated against targetType's schema (one of: dialogue, vocabulary_list, grammar_note, exercise, visual, audio, cultural_note). targetType MUST differ from the current type (use language_update_section for same-type content edits). Caller must own the parent scenario. Returns { oldSectionId, newSectionId, fromType, toType, key, order, chapterId, versionId, version }. | — |
| language_delete_section | Delete a language section and all its versions. Caller must own the parent scenario. Returns { deletedSectionId, scenarioId, scenarioSlug, deletedVersionCount }. Hard delete — irreversible. Use with care. | — |
| language_update_scenario | Update a language scenario's metadata (title/description/tags/status/contentLanguage). At least one field required. tags is PUT semantics. description:null clears stored summary. contentLanguage is a BCP-47 tag (e.g. 'de-DE', 'tr') = the scenario's target teaching language, used for audio-section TTS "Dinle" pronunciation (independent of the page UI locale); null clears it. status accepts DRAFT/PUBLISHED/ARCHIVED but use language_publish_scenario for the canonical publish path (it also creates a ScenarioVersion snapshot). Caller must own the scenario. Returns updated row { scenarioId, slug, title, status, tags, description }. | — |
| language_publish_scenario | Publish a language scenario — creates a new ScenarioVersion snapshot (sectionManifest pointer list) and flips status to PUBLISHED. Re-publishing is allowed (version monotonically increments). Empty scenarios are rejected. Caller must own the scenario. Returns { scenarioId, versionId, version, publishedAt, sectionCount }. | — |
| language_add_to_collection | Add a scenario to a language-typed collection (type=Course). Caller must own the collection. Cross-module items allowed. Duplicate check: if scenario already in collection the call fails. order optional — defaults to append. Returns { collectionId, scenarioId, itemId, order, scenarioModuleId }. | — |
| language_remove_from_collection | Remove a scenario from a language-typed collection (type=Course). Caller must own the collection. Returns { collectionId, scenarioId, removed:true }. Throws if scenario is not in the collection. Other items keep their order (no compaction). | — |
| language_add_wiki_section | Create a new EMPTY wiki section on a language scenario. The section starts with zero concepts — call language_wiki_add_concept for each glossary entry. Accepts scenarioId (cuid) or slug. Returns { sectionId, key, order, versionId, scenarioSlug }. Section label defaults to 'Kavramlar' when omitted. Caller must own the scenario. | — |
| language_wiki_add_concept | Append a single concept card to a language scenario's wiki section. The section must already exist (call language_add_wiki_section first). slug must be unique within the section. definition is the 1-2 sentence collapsed-card summary; overview is the long markdown body. examples and references default to empty arrays. Creates a new SectionVersion. Returns { sectionId, conceptSlug, versionId, version, conceptCount }. | — |
| language_wiki_update_concept | Patch a single concept in a language scenario's wiki section. Identified by slug (slug itself is immutable). patch is partial: any field omitted is unchanged. Pass examples: [] or references: [] to clear arrays. Creates a new SectionVersion if content actually changed. Returns { sectionId, conceptSlug, versionId, version, contentChanged }. | — |
| language_wiki_remove_concept | Remove a single concept from a language wiki section by slug. The section itself stays (even if it becomes empty — drop via delete_section). Creates a new SectionVersion. Returns { sectionId, removedSlug, versionId, version, conceptCount }. | — |