@lingochunk/mcp 0.3.1 → 0.9.0

package/README.md

@@ -14,13 +14,23 @@ contributions (see [CONTRIBUTING.md](CONTRIBUTING.md)).
 > Install: `/plugin marketplace add lingochunk/lingochunk-mcp` in Claude Code (server
 > plus lesson skills), or `npx -y @lingochunk/mcp` as a standalone MCP server.
 
+**A creator rather than a coder?** If you make audio (a podcast, a YouTube
+channel, classes) and want your episodes to become annotated transcripts,
+lessons, courses and multi-language study guides your audience can use, start
+with **[LingoChunk for creators](docs/creator-guide.md)** - no programming
+required, everything happens by talking to an AI assistant.
+
 ## What it gives an agent
 
-Twelve tools, each wrapping one public endpoint. The first seven are read-only;
-the last five write to your account.
+Thirty tools. Twelve read from your account; sixteen write to it; two serve
+guidance: `whats_possible` answers "what can I do here?" with a short menu
+and an example prompt per area, and `get_authoring_guide` serves the full
+authoring craft guides so remote clients that never see the skills still
+compose good lessons, cards and annotations.
 
 | Tool | Scope | What it does |
 |---|---|---|
+| `whats_possible` | none | The quick tour: every area this connection covers (discuss, vocabulary, lessons, courses, cards, languages, creator notes, publishing), one example prompt each. The agent answers short and offers to go deeper per area. |
 | `get_vocabulary` | `vocab:read` | Your vocabulary, aggregated per word with FSRS maturity (known/learning/new/due). Filterable; incremental sync via `since` + `cursor` (additive-only, so full-resync periodically). |
 | `lookup_word` | `vocab:read` | One word: your own context plus a shared-lexicon gender/CEFR fallback. Grounds an LLM's guesses. |
 | `list_library` | `content:read` | Your ready-to-study episodes (own + followed collections), cursor-paginated. |
@@ -28,33 +38,75 @@ the last five write to your account.
 | `get_audio_url` | `content:read` | A short-lived presigned URL to the full native audio (Range-capable). |
 | `search_examples` | `content:read` | Example sentences across your library, by word (`lemma`) or text (`q`). A capped sample, not exhaustive. |
 | `get_audio_clip` | `content:read` | Cuts a short native-audio snippet, **saves it to a local file**, and returns `{path, media_type, size_bytes}` for embedding in lessons. |
+| `get_authoring_guide` | none | Returns the full craft guide for `topic` (`overview`, `lesson`, `course`, `cards`, `annotations`, `add-language`, `discuss`) - the same content as the bundled skills, embedded in the package so remote clients get it too. Call it before composing. |
 | `list_decks` | `cards:write` or `decks:export` | Your study decks with card counts, for picking a `deck_id` to add to or export. |
 | `add_card` | `cards:write` | Adds a card to your review queue (FSRS, starts new). Preferred: the `card.v1` kinds (`word`, `phrase`, `collocation`, `idiom`, `chunk`, `grammar`, `cloze`, `contrast`, `qa`, `production`) anchored to a verbatim transcript sentence - the server derives the highlight/blur painting and native-audio clip, so the card matches the app's own. Legacy: `kind=vocab` from your vocabulary, or `kind=custom` front/back. Omit `deck_id` to use the deck for the card's own submission. |
 | `export_anki_deck` | `decks:export` | Exports a deck to Anki `.apkg` (no LLM), polling internally; returns a download URL when ready. A deck with no linked episode can't be exported. |
-| `save_lesson` | `lessons:write` | Saves a lesson to your private library (100 max). Preferred: a structured `lesson.v1` document the app renders natively (Lessons tab on the episode, real audio, live word state, Ask AI); returns metadata + an `app_url`. Legacy: a self-contained HTML file (10 MB cap) opened via a short-lived view URL. |
-| `delete_lesson` | `lessons:write` | Permanently deletes one saved lesson by id (destructive; owner-scoped server-side). Mainly for iterating: re-saving creates a new lesson, so superseded drafts count against the 100-lesson cap. |
-
-Plus three skills:
-
+| `validate_lesson` | `lessons:write` | Dry-run validates a `lesson.v1` document WITHOUT saving it, reporting EVERY problem at once (schema faults with a `loc`, reference faults with the same codes `save_lesson` raises) so you fix a document in one pass. Stores nothing; spends no lesson-cap budget. Call it before `save_lesson`. |
+| `save_lesson` | `lessons:write` | Saves a lesson to your private library (100 max). Preferred: a structured `lesson.v1` document the app renders natively (Lessons tab on the episode, real audio, live word state, Ask AI); returns metadata + an `app_url`. Legacy: a self-contained HTML file (10 MB cap) opened via a short-lived view URL. Optional `course_id` (+ `sequence`) files it under a course. Creators: `visibility:'public'` publishes the lesson to everyone who can view the source episode (documents only, own episodes only). |
+| `list_lessons` | `lessons:write` | Your saved lessons, newest first (id, title, language, format, source episode, and `course_id`/`sequence`/`course_title` when filed under a course), cursor-paginated - for finding ids and seeing what already exists. |
+| `get_lesson` | `lessons:write` | Reads back a saved `lesson.v1` document by id, plus its `version` token. Opens the revision loop: `get_lesson` -> edit -> `update_lesson` revises in place. |
+| `update_lesson` | `lessons:write` | Revises a saved `lesson.v1` document IN PLACE (same id, same `app_url`, same visibility/course): surgical block `ops` keyed to the app's 1-based § handles, or a full replacement `document`. `base_version` guards against overwriting a concurrent edit (409 `stale_document`). |
+| `delete_lesson` | `lessons:write` | Permanently deletes one saved lesson by id (destructive; owner-scoped server-side). For lessons the user is done with - revision is `update_lesson`, not delete + re-save. |
+| `create_course` | `lessons:write` | Creates a course: a named, ordered series to file lessons under. Returns its id, for `save_lesson`'s `course_id`. Authored via the API only (no in-app course editor). |
+| `list_courses` | `lessons:write` | Your courses, newest first, each with its lesson count - for finding a `course_id` or seeing what series exist. |
+| `delete_course` | `lessons:write` | Deletes one course by id (destructive to the grouping, idempotent). Its lessons SURVIVE - their `course_id` is set null, un-grouping them; authored content is never deleted. |
+| `list_languages` | `content:read` | An episode's target languages and how to add more: the fan-out group so far (each with its own submission id + status), `available_targets` (ordinary Groq targets), `simplify_targets` (leveled same-language codes like `de-a2`) and in-progress drafts. |
+| `get_translation_source` | `content:read` | Pages the primary's sentences to translate yourself: source text, the pivot-language gloss per sentence and per token (which fixes each word's sense). Feeds the draft flow. |
+| `add_language` | `translations:write` | Fans an episode out into 1-10 extra **ordinary** target languages server-side (Groq, no tokens of yours); returns a job per language. Leveled same-language codes are rejected here - use the draft flow. |
+| `put_language_translations` | `translations:write` | Uploads a batch (1-100) of agent-written draft sentences (whole-sentence translation + one meaning per token) for a target or leveled language; returns per-sentence rejections to repair. |
+| `commit_language` | `translations:write` | Validates a complete draft and applies it, minting the sibling deck; polls the job and returns the new submission id when ready. |
+| `discard_language_draft` | `translations:write` | Deletes the in-progress draft rows for a language (destructive; never a committed sibling). |
+| `list_annotations` | `content:read` | An episode's creator annotations (each a markdown note on a transcript sentence span), plus `count` and `max_annotations` so you can budget and avoid duplicates. |
+| `create_annotation` | `annotations:write` | Attaches a markdown creator note to a sentence span (Unicode code-point offsets into the sentence's `display`, or a whole-sentence note); the response echoes `selected_text` to verify the span. |
+| `update_annotation` | `annotations:write` | Replaces one annotation's note in place (the anchor stays put). |
+| `delete_annotation` | `annotations:write` | Deletes one annotation (destructive); also how you fix a mis-anchored span before re-creating it. |
+
+Plus seven skills:
+
+- **`lingochunk-overview`** - the "what can I do?" tour: a short menu of
+  every area (with an example prompt each) and instructions to answer
+  briefly, then expand whichever area the user picks.
 - **`lingochunk-lesson`** - composes a coursebook-style `lesson.v1` document
   (listen, text, vocabulary, one grammar point, graded exercises, review)
   from the tools above, filtering out words you already know; the app
   renders it natively and can export an offline HTML worksheet.
+- **`lingochunk-course`** - plans a multi-lesson series: slices an episode (or
+  collection) into coherent parts, creates a course, then builds N lessons via
+  the lesson skill with a different grammar point and ramping difficulty per
+  lesson, each filed under the course in order.
 - **`lingochunk-cards`** - builds native-grade flashcards with the `card.v1`
   kinds: verbatim transcript anchors, per-kind guidance (grammar =
   production cloze of the morpheme with a hint), and a quality rubric
   distilled from the known failure modes of AI-generated cards.
 - **`lingochunk-discuss`** - a lighter, conversational "talk me through this
   episode" workflow.
+- **`lingochunk-add-language`** - adds another language to one of your episodes
+  as a new sibling deck: either the server-side Groq fan-out for an ordinary
+  target, or an agent-supplied translation you write sentence by sentence and
+  commit - the only way to build a leveled same-language deck (e.g.
+  "German (A2)", German audio glossed in simpler A2 German).
+- **`lingochunk-annotate`** - finds the genuinely useful expressions in one of
+  your episodes (idioms, phrasal verbs, collocations, discourse markers,
+  culture-bound references) and attaches a short markdown creator note to each
+  exact span: an iris tint + note sheet for you, a forward-only note card for
+  your followers.
+
+The Claude Code plugin installs these as skills. Every client also gets the
+same guidance two other ways that need no plugin: as MCP **prompts** (one per
+skill, named `lingochunk-lesson`, `lingochunk-cards`, ...) in the client's
+prompt/slash picker, and via the **`get_authoring_guide`** tool the model can
+call itself before composing.
 
 ## Prerequisites
 
 - Node.js >= 18.
 - A LingoChunk **personal access token**: in LingoChunk, open Settings -> API
   access, create a token, and grant the scopes you need (`vocab:read` +
-  `content:read` cover the read tools; add `cards:write`, `decks:export` and
-  `lessons:write` for the write tools). The token is shown once and starts with
-  `lcp_`. The 403 errors from the tools name the exact scope you are missing.
+  `content:read` cover the read tools; add `cards:write`, `decks:export`,
+  `lessons:write`, `translations:write` and `annotations:write` for the write
+  tools). The token is shown once and starts with `lcp_`. The 403 errors from
+  the tools name the exact scope you are missing.
 
 ## Use it
 
@@ -92,6 +144,36 @@ npm install     # installs deps and builds dist/ via the prepare script
 claude mcp add lingochunk --env LINGOCHUNK_TOKEN=lcp_... -- node /absolute/path/to/lingochunk-mcp/dist/index.js
 ```
 
+### Option C - hosted server (no install: claude.ai, ChatGPT, Le Chat, ...)
+
+The same server also runs hosted at `https://lingochunk.com/mcp` as a
+standard **remote MCP server** (Streamable HTTP). Nothing to install - paste
+the URL into any client that supports custom remote MCP servers and **sign in
+with your LingoChunk account when the client prompts you** (OAuth 2.1 with a
+consent screen; the grant appears in Settings -> API tokens, revocable like
+any token). Clients with a token field can instead send a personal access
+token as a Bearer credential:
+
+| Client | Where |
+|---|---|
+| claude.ai (web/desktop/mobile, incl. Free) | Settings -> Connectors -> *Add custom connector* -> URL `https://lingochunk.com/mcp` -> a LingoChunk sign-in/consent screen opens; approve and you are connected |
+| Claude Code | `claude mcp add --transport http lingochunk https://lingochunk.com/mcp` (OAuth on first use), or pass `--header "Authorization: Bearer lcp_..."` to use a token instead |
+| ChatGPT (paid plans) | Settings -> enable *Developer mode* -> Apps -> "+" -> URL (OAuth), or URL + your token |
+| Mistral Le Chat | *+ Add Connector* -> Custom MCP Connector -> URL (auth auto-detected) |
+| Perplexity (Pro/Max), Grok, Manus | add a custom connector/MCP server by URL, sign in or paste an API key |
+
+Differences from the local server: `get_audio_clip` is unavailable (it writes
+files, which only makes sense on your own machine - use `get_audio_url`), and
+skills don't auto-load (the server exposes each skill as an MCP **prompt**,
+and agents can pull the same guidance through the `get_authoring_guide` tool).
+
+**If your client offers neither OAuth nor a token field**, embed the token in
+the URL: `https://lingochunk.com/mcp/t/lcp_...`. That URL then IS a
+credential - treat it like a password, prefer a token with only the scopes you
+need, and revoke it in Settings if it ever leaks. OAuth sign-in or a header,
+when your client supports one, is always preferred (URLs end up in access
+logs).
+
 ## Use with other agents
 
 Nothing in the server is Claude-specific: it is a standard stdio MCP server,
@@ -201,6 +283,22 @@ when you want the update.
 The token is only ever sent as an `Authorization: Bearer` header to the
 configured origin; it is never written to disk or logged.
 
+### Hosted (remote) mode
+
+`node dist/index.js --http` serves the same tools over Streamable HTTP for
+remote MCP clients (see Option C). The process is stateless and multi-user:
+`LINGOCHUNK_TOKEN` is not read - every request must carry its own
+`Authorization: Bearer lcp_...` header, which is forwarded verbatim to the
+API (the API stays the sole authority; the server stores nothing). A
+`Dockerfile` is included.
+
+| Variable | Required | Default | Meaning |
+|---|---|---|---|
+| `LINGOCHUNK_MCP_PORT` | no | `8100` | Listen port (`PORT` honoured as fallback). |
+| `LINGOCHUNK_BASE_URL` | no | `https://lingochunk.com` | API origin; co-located deployments should point at the loopback origin. |
+
+Endpoints: `POST /mcp` (the MCP wire), `GET /health` (liveness).
+
 ## Building a lesson
 
 Ask your agent something like "build me a lesson from yesterday's German episode"
@@ -217,10 +315,15 @@ lessons side by side under the episode's Lessons tab. See
 
 ```
 src/                                    the MCP server (TypeScript, stdio)
+skills/lingochunk-overview/             the "what can I do?" tour skill
 skills/lingochunk-lesson/               the coursebook lesson skill
+skills/lingochunk-course/               the multi-lesson course planner skill
 skills/lingochunk-cards/                the flashcard (card.v1) skill
 skills/lingochunk-discuss/              the "discuss an episode" skill
+skills/lingochunk-add-language/         the add-language / draft-translation skill
+skills/lingochunk-annotate/             the useful-expression annotation skill
 skills/*/examples/                      example lesson.v1 documents (CI-validated)
+docs/creator-guide.md                   the guide for content creators (start here if you make audio)
 docs/skill-authoring.md                 how to write a new skill
 docs/skill-template.md                  SKILL.md starting point
 docs/integrations/fluent.md             how to plug this into the fluent tutor plugin
@@ -253,7 +356,7 @@ npm run validate:lesson -- <doc.json>   # validate a lesson.v1 document (Node 22
 
 `spec/openapi-public-v1.json` is the source contract; it is exported from the
 LingoChunk repo (`make generate-openapi-public`) and refreshed here on each API
-release. This copy was taken from LingoChunk commit `0db02377`.
+release. This copy was taken from LingoChunk commit `31c47289`.
 
 ### Live smoke test
 

package/dist/client.d.ts

@@ -24,6 +24,139 @@ export interface DeckExportStatus {
     status: "ready" | "pending" | "failed" | "none";
     download_url?: string;
 }
+/** One target language present on a submission's fan-out group. */
+export interface SubmissionLanguage {
+    language: string;
+    submission_id: string;
+    status: string;
+    is_primary: boolean;
+}
+/** An in-progress agent-supplied translation draft for one language. */
+export interface DraftSummary {
+    language: string;
+    sentences_drafted: number;
+    sentence_count: number;
+}
+/** Result of GET /submissions/{id}/languages. */
+export interface SubmissionLanguages {
+    source_language: string;
+    languages: SubmissionLanguage[];
+    /** Ordinary Groq targets addable via add_language (source + existing removed). */
+    available_targets: string[];
+    /** Leveled same-language codes (e.g. de-a2) for the draft flow only. */
+    simplify_targets: string[];
+    drafts: DraftSummary[];
+}
+/** One source token as the Groq translator would see it. */
+export interface SourceToken {
+    surface: string;
+    lemma: string;
+    pos: string;
+    pivot_meaning: string;
+}
+/** One source sentence to translate, with its pivot-language gloss. */
+export interface SourceSentence {
+    position: number;
+    text: string;
+    pivot_translation: string;
+    tokens: SourceToken[];
+}
+/** Result of GET /submissions/{id}/translation-source (one page). */
+export interface TranslationSource {
+    source_language: string;
+    pivot_language: string;
+    sentence_count: number;
+    sentences: SourceSentence[];
+    /** null when the page exhausts the submission. */
+    next_from_position: number | null;
+}
+/** Result of POST /submissions/{id}/languages (Groq fan-out trigger). */
+export interface AddLanguagesResult {
+    jobs: {
+        language: string;
+        job_id: string;
+    }[];
+    skipped: {
+        language: string;
+        reason: string;
+    }[];
+}
+/** One draft sentence in a PUT batch: whole-sentence target text (null = no
+ *  sentence back) plus one meaning per source token, in order. */
+export interface DraftSentence {
+    position: number;
+    translation: string | null;
+    meanings: string[];
+}
+/** Result of PUT /submissions/{id}/translations/{language}. */
+export interface PutTranslationsResult {
+    accepted: number;
+    rejected: {
+        position: number;
+        reason: string;
+        expected?: number;
+        got?: number;
+    }[];
+    sentences_drafted: number;
+    sentence_count: number;
+}
+/** Result of POST /submissions/{id}/translations/{language}/commit. */
+export interface CommitDraftResult {
+    job_id: string;
+    language: string;
+}
+/** Result of GET /jobs/{id}: status of a fan-out or draft-apply job. */
+export interface JobStatus {
+    status: string;
+    progress?: number;
+    step?: string | null;
+    error?: string | null;
+}
+/** Result of DELETE /submissions/{id}/translations/{language}. */
+export interface DeleteDraftResult {
+    deleted_sentences: number;
+}
+/** One creator annotation: a markdown note anchored to a transcript sentence,
+ *  tinted onto a char span or the whole sentence. */
+export interface AnnotationV1 {
+    id: number;
+    /** The sentence's stable id (survives split/merge), from get_transcript. */
+    sentence_id: number;
+    /** null (with char_end) for a whole-sentence note; else a code-point offset. */
+    char_start: number | null;
+    char_end: number | null;
+    /** Server snapshot of display[char_start:char_end]; verify it after create. */
+    selected_text: string | null;
+    note: string;
+    /** The sentence was edited since; the app hides the tint until re-anchored. */
+    stale: boolean;
+    start_time: number | null;
+    end_time: number | null;
+}
+/** Result of GET /submissions/{id}/annotations. */
+export interface AnnotationList {
+    /** Ordered by sentence, then char_start. */
+    annotations: AnnotationV1[];
+    count: number;
+    /** The per-submission cap, so an agent can budget how many more to add. */
+    max_annotations: number;
+}
+/** Body of POST /submissions/{id}/annotations. char_start/char_end are
+ *  both-or-neither (neither = a whole-sentence note); offsets are Unicode
+ *  code points into the sentence's display. */
+export interface CreateAnnotationBody {
+    sentence_id: number;
+    char_start?: number | null;
+    char_end?: number | null;
+    note: string;
+    start_time?: number | null;
+    end_time?: number | null;
+}
+/** Result of DELETE /submissions/{id}/annotations/{annotation_id}. */
+export interface DeleteAnnotationResult {
+    deleted: boolean;
+    annotation_id: number;
+}
 export type QueryValue = string | number | boolean | undefined | null;
 /** How long any single request may take before we abort it. */
 export declare const REQUEST_TIMEOUT_MS = 30000;
@@ -49,10 +182,21 @@ export declare class LingoChunkClient {
     private raiseForStatus;
     /** GET a JSON endpoint. */
     private getJson;
+    /** GET a JSON endpoint, also capturing one response header (e.g. the
+     *  lesson optimistic-concurrency token in X-Lesson-Version). */
+    private getJsonWithHeader;
+    /** PUT a JSON body, also capturing one response header. */
+    private putJsonWithHeader;
     /** DELETE an endpoint; success is 204 with no body to parse. */
     private deleteNoContent;
     /** POST a JSON body to an endpoint and parse the JSON response. */
     private postJson;
+    /** PUT a JSON body to an endpoint and parse the JSON response. */
+    private putJson;
+    /** PATCH a JSON body to an endpoint and parse the JSON response. */
+    private patchJson;
+    /** DELETE an endpoint that returns a JSON body (unlike deleteNoContent). */
+    private deleteJson;
     getVocabulary(params: Record<string, QueryValue>): Promise<unknown>;
     lookupWord(params: Record<string, QueryValue>): Promise<unknown>;
     listLibrary(params: Record<string, QueryValue>): Promise<unknown>;
@@ -62,6 +206,35 @@ export declare class LingoChunkClient {
     listDecks(): Promise<unknown>;
     addCard(body: object): Promise<unknown>;
     createLesson(body: object): Promise<unknown>;
+    /** Dry-run validate a lesson.v1 document without saving it: reports every
+     *  failing category at once (schema + reference), so a document can be fixed
+     *  in one pass instead of save -> 400 -> fix cycles. Stores nothing. */
+    validateLesson(body: object): Promise<unknown>;
+    listLessons(params: Record<string, QueryValue>): Promise<unknown>;
+    /** Create a course: a named, ordered series to file lessons under. */
+    createCourse(body: object): Promise<unknown>;
+    /** The caller's courses, newest first, each with its lesson_count. */
+    listCourses(): Promise<unknown>;
+    /** Delete a course (owner-scoped). Its lessons survive - the DB sets their
+     *  course_id NULL, un-grouping them. 404 for a foreign or unknown id. */
+    deleteCourse(courseId: string): Promise<void>;
+    /** The stored lesson.v1 document plus its optimistic-concurrency token
+     *  (the X-Lesson-Version response header; a caller echoes it verbatim as
+     *  an update's base_version). Owner-scoped server-side; 404 for HTML
+     *  lessons (they have no document) and for foreign/unknown ids. */
+    getLessonDocument(lessonId: string): Promise<{
+        version: string | null;
+        document: unknown;
+    }>;
+    /** Replace a lesson.v1 document in place (owner-scoped; same id, same
+     *  app_url). base_version is the X-Lesson-Version token the edit is based
+     *  on - if the lesson changed since, the server answers 409 stale_document
+     *  instead of overwriting the other writer. Returns the refreshed lesson
+     *  metadata plus the NEW token for chained edits. */
+    updateLesson(lessonId: string, document: unknown, baseVersion: string): Promise<{
+        version: string | null;
+        lesson: unknown;
+    }>;
     /** Owner-scoped server-side: a foreign or unknown id is a 404, never a leak. */
     deleteLesson(lessonId: string): Promise<void>;
     /** Start an Anki export (no body). 400 for a deck with no linked submission. */
@@ -69,4 +242,38 @@ export declare class LingoChunkClient {
     exportDeckStatus(deckId: number): Promise<DeckExportStatus>;
     /** GET a clip as raw audio bytes (the endpoint streams audio, not JSON). */
     getAudioClip(submissionId: string, start: number, end: number): Promise<AudioClip>;
+    /** (a) The submission's fan-out group languages, addable targets, leveled
+     *  simplify targets, and in-progress drafts. */
+    listSubmissionLanguages(submissionId: string): Promise<SubmissionLanguages>;
+    /** (b) A page of the primary's sentences (source text + pivot glosses) as the
+     *  Groq translator would see them, for the agent to translate. */
+    getTranslationSource(submissionId: string, params: Record<string, QueryValue>): Promise<TranslationSource>;
+    /** (c) Trigger the server-side Groq fan-out into extra ordinary target
+     *  languages; returns a job per accepted language plus per-code skips. */
+    addLanguages(submissionId: string, languages: string[]): Promise<AddLanguagesResult>;
+    /** (d) Upsert a batch of agent-supplied draft sentences for one language. */
+    putTranslations(submissionId: string, language: string, body: {
+        generator?: string;
+        sentences: DraftSentence[];
+    }): Promise<PutTranslationsResult>;
+    /** (e) Validate a complete draft and enqueue the apply job that mints the
+     *  sibling submission. 409 when the draft misses sentence positions. */
+    commitTranslationDraft(submissionId: string, language: string): Promise<CommitDraftResult>;
+    /** (f) Owner-scoped job status, for polling a fan-out (c) or draft-apply (e)
+     *  job to completion. */
+    getJob(jobId: string): Promise<JobStatus>;
+    /** (g) Delete the draft rows for one language (never a committed sibling). */
+    deleteTranslationDraft(submissionId: string, language: string): Promise<DeleteDraftResult>;
+    /** List a submission's creator annotations (ordered), with the per-submission
+     *  cap so an agent can budget how many more to add. */
+    listAnnotations(submissionId: string): Promise<AnnotationList>;
+    /** Create one annotation on a sentence span (or the whole sentence). The
+     *  response echoes the server's selected_text snapshot so the caller can
+     *  verify the span it anchored. */
+    createAnnotation(submissionId: string, body: CreateAnnotationBody): Promise<AnnotationV1>;
+    /** Replace one annotation's markdown note (anchor unchanged; staleness is
+     *  recomputed against the current sentence). */
+    updateAnnotation(submissionId: string, annotationId: number, note: string): Promise<AnnotationV1>;
+    /** Delete one annotation. Returns {deleted, annotation_id}. */
+    deleteAnnotation(submissionId: string, annotationId: number): Promise<DeleteAnnotationResult>;
 }

package/dist/client.js

@@ -134,6 +134,34 @@ export class LingoChunkClient {
         }
         return (await res.json());
     }
+    /** GET a JSON endpoint, also capturing one response header (e.g. the
+     *  lesson optimistic-concurrency token in X-Lesson-Version). */
+    async getJsonWithHeader(path, header) {
+        const res = await fetch(this.buildUrl(path), {
+            method: "GET",
+            headers: this.authHeaders("application/json"),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            await this.raiseForStatus(res);
+        }
+        return { data: (await res.json()), header: res.headers.get(header) };
+    }
+    /** PUT a JSON body, also capturing one response header. */
+    async putJsonWithHeader(path, body, header) {
+        const headers = this.authHeaders("application/json");
+        headers["Content-Type"] = "application/json";
+        const res = await fetch(this.buildUrl(path), {
+            method: "PUT",
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            await this.raiseForStatus(res);
+        }
+        return { data: (await res.json()), header: res.headers.get(header) };
+    }
     /** DELETE an endpoint; success is 204 with no body to parse. */
     async deleteNoContent(path) {
         const res = await fetch(this.buildUrl(path), {
@@ -161,6 +189,48 @@ export class LingoChunkClient {
         }
         return (await res.json());
     }
+    /** PUT a JSON body to an endpoint and parse the JSON response. */
+    async putJson(path, body) {
+        const headers = this.authHeaders("application/json");
+        headers["Content-Type"] = "application/json";
+        const res = await fetch(this.buildUrl(path), {
+            method: "PUT",
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            await this.raiseForStatus(res);
+        }
+        return (await res.json());
+    }
+    /** PATCH a JSON body to an endpoint and parse the JSON response. */
+    async patchJson(path, body) {
+        const headers = this.authHeaders("application/json");
+        headers["Content-Type"] = "application/json";
+        const res = await fetch(this.buildUrl(path), {
+            method: "PATCH",
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            await this.raiseForStatus(res);
+        }
+        return (await res.json());
+    }
+    /** DELETE an endpoint that returns a JSON body (unlike deleteNoContent). */
+    async deleteJson(path) {
+        const res = await fetch(this.buildUrl(path), {
+            method: "DELETE",
+            headers: this.authHeaders("application/json"),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            await this.raiseForStatus(res);
+        }
+        return (await res.json());
+    }
     // --- Read endpoints (thin pass-throughs; the tools shape the arguments) ---
     getVocabulary(params) {
         return this.getJson("/vocab", params);
@@ -190,6 +260,45 @@ export class LingoChunkClient {
     createLesson(body) {
         return this.postJson("/lessons", body);
     }
+    /** Dry-run validate a lesson.v1 document without saving it: reports every
+     *  failing category at once (schema + reference), so a document can be fixed
+     *  in one pass instead of save -> 400 -> fix cycles. Stores nothing. */
+    validateLesson(body) {
+        return this.postJson("/lessons/validate", body);
+    }
+    listLessons(params) {
+        return this.getJson("/lessons", params);
+    }
+    /** Create a course: a named, ordered series to file lessons under. */
+    createCourse(body) {
+        return this.postJson("/courses", body);
+    }
+    /** The caller's courses, newest first, each with its lesson_count. */
+    listCourses() {
+        return this.getJson("/courses");
+    }
+    /** Delete a course (owner-scoped). Its lessons survive - the DB sets their
+     *  course_id NULL, un-grouping them. 404 for a foreign or unknown id. */
+    deleteCourse(courseId) {
+        return this.deleteNoContent(`/courses/${encodeURIComponent(courseId)}`);
+    }
+    /** The stored lesson.v1 document plus its optimistic-concurrency token
+     *  (the X-Lesson-Version response header; a caller echoes it verbatim as
+     *  an update's base_version). Owner-scoped server-side; 404 for HTML
+     *  lessons (they have no document) and for foreign/unknown ids. */
+    async getLessonDocument(lessonId) {
+        const { data, header } = await this.getJsonWithHeader(`/lessons/${encodeURIComponent(lessonId)}/document`, "x-lesson-version");
+        return { version: header, document: data };
+    }
+    /** Replace a lesson.v1 document in place (owner-scoped; same id, same
+     *  app_url). base_version is the X-Lesson-Version token the edit is based
+     *  on - if the lesson changed since, the server answers 409 stale_document
+     *  instead of overwriting the other writer. Returns the refreshed lesson
+     *  metadata plus the NEW token for chained edits. */
+    async updateLesson(lessonId, document, baseVersion) {
+        const { data, header } = await this.putJsonWithHeader(`/lessons/${encodeURIComponent(lessonId)}/document`, { document, base_version: baseVersion }, "x-lesson-version");
+        return { version: header, lesson: data };
+    }
     /** Owner-scoped server-side: a foreign or unknown id is a 404, never a leak. */
     deleteLesson(lessonId) {
         return this.deleteNoContent(`/lessons/${encodeURIComponent(lessonId)}`);
@@ -226,5 +335,60 @@ export class LingoChunkClient {
         const contentType = res.headers.get("content-type") ?? "audio/mpeg";
         return { data, contentType };
     }
+    // --- Language / translation endpoints (phase 4) -------------------------
+    /** (a) The submission's fan-out group languages, addable targets, leveled
+     *  simplify targets, and in-progress drafts. */
+    listSubmissionLanguages(submissionId) {
+        return this.getJson(`/submissions/${encodeURIComponent(submissionId)}/languages`);
+    }
+    /** (b) A page of the primary's sentences (source text + pivot glosses) as the
+     *  Groq translator would see them, for the agent to translate. */
+    getTranslationSource(submissionId, params) {
+        return this.getJson(`/submissions/${encodeURIComponent(submissionId)}/translation-source`, params);
+    }
+    /** (c) Trigger the server-side Groq fan-out into extra ordinary target
+     *  languages; returns a job per accepted language plus per-code skips. */
+    addLanguages(submissionId, languages) {
+        return this.postJson(`/submissions/${encodeURIComponent(submissionId)}/languages`, { languages });
+    }
+    /** (d) Upsert a batch of agent-supplied draft sentences for one language. */
+    putTranslations(submissionId, language, body) {
+        return this.putJson(`/submissions/${encodeURIComponent(submissionId)}/translations/${encodeURIComponent(language)}`, body);
+    }
+    /** (e) Validate a complete draft and enqueue the apply job that mints the
+     *  sibling submission. 409 when the draft misses sentence positions. */
+    commitTranslationDraft(submissionId, language) {
+        return this.postJson(`/submissions/${encodeURIComponent(submissionId)}/translations/${encodeURIComponent(language)}/commit`);
+    }
+    /** (f) Owner-scoped job status, for polling a fan-out (c) or draft-apply (e)
+     *  job to completion. */
+    getJob(jobId) {
+        return this.getJson(`/jobs/${encodeURIComponent(jobId)}`);
+    }
+    /** (g) Delete the draft rows for one language (never a committed sibling). */
+    deleteTranslationDraft(submissionId, language) {
+        return this.deleteJson(`/submissions/${encodeURIComponent(submissionId)}/translations/${encodeURIComponent(language)}`);
+    }
+    // --- Creator annotation endpoints (phase 5) -----------------------------
+    /** List a submission's creator annotations (ordered), with the per-submission
+     *  cap so an agent can budget how many more to add. */
+    listAnnotations(submissionId) {
+        return this.getJson(`/submissions/${encodeURIComponent(submissionId)}/annotations`);
+    }
+    /** Create one annotation on a sentence span (or the whole sentence). The
+     *  response echoes the server's selected_text snapshot so the caller can
+     *  verify the span it anchored. */
+    createAnnotation(submissionId, body) {
+        return this.postJson(`/submissions/${encodeURIComponent(submissionId)}/annotations`, body);
+    }
+    /** Replace one annotation's markdown note (anchor unchanged; staleness is
+     *  recomputed against the current sentence). */
+    updateAnnotation(submissionId, annotationId, note) {
+        return this.patchJson(`/submissions/${encodeURIComponent(submissionId)}/annotations/${annotationId}`, { note });
+    }
+    /** Delete one annotation. Returns {deleted, annotation_id}. */
+    deleteAnnotation(submissionId, annotationId) {
+        return this.deleteJson(`/submissions/${encodeURIComponent(submissionId)}/annotations/${annotationId}`);
+    }
 }
 //# sourceMappingURL=client.js.map