@lingochunk/mcp 0.3.0 → 0.8.0

package/README.md

@@ -8,18 +8,29 @@ transcripts and clips, and your library.
 It is a thin client over the LingoChunk public API (`/api/v1`): read-only tools
 for your vocabulary, transcripts and audio, plus write tools to add review cards,
 export Anki decks and save lessons. The app stays closed source; this repo is
-just the client, the committed API spec, and two lesson skills.
+the client, the committed API spec, and the skills - and the skills are open to
+contributions (see [CONTRIBUTING.md](CONTRIBUTING.md)).
 
-> Install: `/plugin marketplace add lxol/lingochunk-mcp` in Claude Code (server
+> 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
 
-Eleven tools, each wrapping one public endpoint. The first seven are read-only;
-the last four (phase 3) 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. |
@@ -27,32 +38,74 @@ the last four (phase 3) 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. |
-
-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. Closes the revision loop: lessons are immutable, so revise = read -> save new -> delete old. |
+| `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. |
+| `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
 
@@ -61,13 +114,14 @@ Plus three skills:
 This repo is its own plugin marketplace. In Claude Code:
 
 ```
-/plugin marketplace add lxol/lingochunk-mcp
+/plugin marketplace add lingochunk/lingochunk-mcp
 /plugin install lingochunk@lingochunk-mcp
 ```
 
-The plugin's `.mcp.json` runs the published server via `npx -y @lingochunk/mcp`
-(no build step needed) and reads your token from the environment, so export it
-in the shell you start Claude Code from:
+The plugin's `.mcp.json` runs the published server via npx, pinned to the
+exact version the plugin was released with (no build step needed), and reads
+your token from the environment, so export it in the shell you start Claude
+Code from:
 
 ```bash
 export LINGOCHUNK_TOKEN=lcp_your_token_here
@@ -89,6 +143,134 @@ 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,
+so any MCP-capable agent can run it. The recipe is always the same - run
+`npx -y @lingochunk/mcp` with `LINGOCHUNK_TOKEN` in its environment - and
+most clients express it as JSON like this:
+
+```json
+{
+  "mcpServers": {
+    "lingochunk": {
+      "command": "npx",
+      "args": ["-y", "@lingochunk/mcp"],
+      "env": { "LINGOCHUNK_TOKEN": "lcp_your_token_here" }
+    }
+  }
+}
+```
+
+Where that config lives per client (differences noted):
+
+| Client | Where |
+|---|---|
+| Claude Desktop | Settings -> Developer -> Edit Config (`claude_desktop_config.json`) |
+| Cursor | `~/.cursor/mcp.json`, or `.cursor/mcp.json` per project |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| VS Code (Copilot agent mode) | `.vscode/mcp.json`, with top-level key `servers` instead of `mcpServers` |
+| Gemini CLI | `~/.gemini/settings.json` |
+| Codex CLI | `~/.codex/config.toml`, as `[mcp_servers.lingochunk]` with the same command/args/env in TOML |
+
+Where your client supports it, prefer referencing an environment variable
+over pasting the token into the config file (VS Code can prompt for it via
+`inputs`; CLI clients usually inherit your shell environment).
+
+The skills are not Claude-specific either: each one is a plain-markdown
+playbook (`skills/<name>/SKILL.md`). Claude Code auto-loads them through the
+plugin; with any other agent, point it at the file (or paste it as context)
+and ask for a lesson. Every hard guarantee - the schema, verbatim transcript
+quoting, sentence positions - is enforced server-side on save, so the
+quality contract holds no matter which agent is driving.
+
+## Updating and checking versions
+
+Two artefacts ship from this repo and version separately:
+
+| Artefact | Carries | Check the version with |
+|---|---|---|
+| Claude Code plugin `lingochunk` | the skills + the server launcher | `claude plugin list`, or `/plugin` -> Installed |
+| npm package `@lingochunk/mcp` | the MCP server (the tools) | `npx -y @lingochunk/mcp --version` |
+
+### Update the plugin (Claude Code)
+
+```
+/plugin marketplace update lingochunk-mcp
+/reload-plugins
+```
+
+The first refreshes the marketplace; the second activates updated skills in
+the RUNNING session (new sessions load them automatically). To compare the
+installed version against what the marketplace offers:
+
+```bash
+claude plugin list --json --available
+```
+
+Set-and-forget alternative: `/plugin` -> Marketplaces -> select
+`lingochunk-mcp` -> **Enable auto-update** (third-party marketplaces have it
+disabled by default; official ones are on). With it enabled, Claude Code
+refreshes at startup and prompts `/reload-plugins` when something changed.
+
+An update only appears when the plugin's `version` was bumped - Claude Code
+uses it as the cache key, which is why our release rule (CONTRIBUTING.md)
+bumps it on every user-visible change.
+
+### Update the MCP server
+
+The plugin pins the exact server version in its `.mcp.json`, so **updating
+the plugin updates the server too** - no separate step. A running session
+keeps its old server process; `/reload-plugins` (or a new session)
+reconnects to the new one.
+
+**Standalone installs** (`claude mcp add ... npx -y @lingochunk/mcp`, or the
+other-agents configs above) are exposed to an npx trap: npx caches packages
+in `~/.npm/_npx` and does NOT re-check the registry once cached, so an
+unpinned `@lingochunk/mcp` can run a stale server indefinitely. To check and
+fix:
+
+```bash
+npx -y @lingochunk/mcp --version      # what npx actually runs
+npm view @lingochunk/mcp version      # latest published
+rm -rf ~/.npm/_npx                    # blunt fix: clear the npx cache, relaunch
+```
+
+Or make your config always-fresh by using `@lingochunk/mcp@latest` (checks
+the registry on every launch: ~1-3 s extra startup and a registry
+dependency), or pin `@lingochunk/mcp@<version>` and move the pin yourself
+when you want the update.
+
 ## Configuration
 
 | Variable | Required | Default | Meaning |
@@ -100,41 +282,80 @@ claude mcp add lingochunk --env LINGOCHUNK_TOKEN=lcp_... -- node /absolute/path/
 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"
 or "quiz me on the words I'm learning". The `lingochunk-lesson` skill drives the
 workflow: pick the source, pull a transcript slice, gather and **filter** your
-vocabulary (never quizzing you on mastered words), fetch short audio clips, and
-render one shareable HTML file. See `skills/lingochunk-lesson/`.
+vocabulary (never quizzing you on mastered words), then compose a structured
+`lesson.v1` document that the app renders natively - real episode audio, live
+word state, crosslinks, Ask AI - with an offline HTML export available in-app.
+A submission can hold many lessons, so different skills (or repeated runs) add
+lessons side by side under the episode's Lessons tab. See
+`skills/lingochunk-lesson/`.
 
 ## Repository layout
 
 ```
 src/                                    the MCP server (TypeScript, stdio)
-skills/lingochunk-lesson/               the lesson skill
-skills/lingochunk-lesson/assets/lesson-template.html   self-contained HTML template
+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
 spec/openapi-public-v1.json             the committed public API spec (the contract)
+scripts/validate-lesson.ts              validate a lesson.v1 document against the spec
 scripts/smoke.ts                        live smoke test (run by hand, never in CI)
-test/                                   vitest unit tests (mocked fetch)
+test/                                   vitest unit tests (mocked fetch) + example validation
 .claude-plugin/plugin.json              Claude Code plugin manifest
 .mcp.json                               MCP server definition for the plugin
 ```
 
+## Contributing a skill
+
+Skills are markdown pedagogy, not code: a `SKILL.md` playbook plus an example
+`lesson.v1` document that CI validates against the committed spec. Anyone can
+contribute one - a dictation drill, an exam rehearsal, a due-words review
+session - and AI-drafted skills are explicitly welcome. Start with
+[CONTRIBUTING.md](CONTRIBUTING.md) and
+[docs/skill-authoring.md](docs/skill-authoring.md).
+
 ## Development
 
 ```bash
 npm install        # deps + build (prepare)
 npm run build      # compile src/ -> dist/
 npm run typecheck  # type-check without emitting
-npm test           # vitest unit tests (mocked fetch; no network)
+npm test           # vitest unit tests (mocked fetch; no network) + skill example validation
+npm run validate:lesson -- <doc.json>   # validate a lesson.v1 document (Node 22.6+)
 ```
 
 `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 `3c226795`.
+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,8 +182,16 @@ export declare class LingoChunkClient {
     private raiseForStatus;
     /** GET a JSON endpoint. */
     private getJson;
+    /** 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>;
@@ -60,9 +201,60 @@ 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. Owner-scoped server-side; 404 for HTML
+     *  lessons (they have no document) and for foreign/unknown ids. */
+    getLessonDocument(lessonId: string): Promise<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. */
     exportDeck(deckId: number): Promise<DeckExportStart>;
     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>;
 }