feat: simplify interfaces and add docs

Author: LucaButBoring

.vitepress/config.mts

@@ -12,12 +12,61 @@ export default withMermaid(
       outline: [2, 3],
 
       nav: [
+        { text: "SDK", link: "/typescript/" },
         { text: "SEPs", link: "/seps/2663-tasks-extension" },
         { text: "Specification", link: "/specification/2026-07-28/tasks" },
       ],
 
       sidebar: {
-        "specification/": [
+        "/typescript/": [
+          {
+            text: "Introduction",
+            items: [
+              { text: "Getting started", link: "/typescript/" },
+              {
+                text: "Call your first tool",
+                link: "/typescript/getting-started",
+              },
+              {
+                text: "Migrate from the base SDK",
+                link: "/typescript/migrating-from-the-sdk",
+              },
+            ],
+          },
+          {
+            text: "Clients",
+            items: [
+              {
+                text: "Observe and control execution",
+                link: "/typescript/client/execution",
+              },
+              {
+                text: "Handle input and recover tasks",
+                link: "/typescript/client/input-and-recovery",
+              },
+              {
+                text: "[2025-11-25] Receive sampling and elicitation requests",
+                link: "/typescript/receiver",
+              },
+            ],
+          },
+          {
+            text: "Advanced",
+            items: [
+              {
+                text: "Integrate adapters and schemas",
+                link: "/typescript/adapters-and-schemas",
+              },
+            ],
+          },
+          {
+            text: "Help",
+            items: [
+              { text: "Troubleshooting", link: "/typescript/troubleshooting" },
+            ],
+          },
+        ],
+        "/specification/": [
           {
             text: "Specification",
             items: [
@@ -29,7 +78,7 @@ export default withMermaid(
             ],
           },
         ],
-        "seps/": [
+        "/seps/": [
           {
             text: "SEPs",
             items: [

README.md

@@ -1,24 +1,25 @@
 # MCP Tasks Extension
-This repository contains the official [Model Context Protocol](https://modelcontextprotocol.io) Tasks extension (`io.modelcontextprotocol/tasks`), based on [SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663).
 
-## Overview
+This repository contains the official [Model Context Protocol](https://modelcontextprotocol.io) Tasks extension (`io.modelcontextprotocol/tasks`), based on [SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663).
 
-This extension defines the **Tasks** primitive for the Model Context Protocol (MCP). Tasks are durable state machines that carry information about the underlying execution state of a request, enabling requestor polling and deferred result retrieval. Each task is uniquely identifiable by a receiver-generated **task ID**.
+## Why Tasks?
 
-Tasks are useful for:
+Some MCP requests finish quickly. Others run for minutes, wait for human input, or need to survive a disconnected client. The Tasks extension lets a receiver return a durable task handle so the requester can follow progress and retrieve the result later.
 
-- Representing expensive computations and batch processing requests
-- Integrating seamlessly with external job/workflow APIs
-- Enabling call-now, fetch-later execution patterns
+Use Tasks for long computations, approval workflows, external job systems, and call-now/fetch-later APIs.
 
 **Extension Identifier:** `io.modelcontextprotocol/tasks`
 
+## Use it from TypeScript
+
+The `@modelcontextprotocol/ext-tasks` package provides generation-agnostic requester lifecycle APIs and 2025-11-25 Tasks receiver support. Start with the [TypeScript package guide](https://modelcontextprotocol.github.io/ext-tasks/typescript/) or [call your first task-enabled tool](https://modelcontextprotocol.github.io/ext-tasks/typescript/getting-started.html).
+
 ## Schemas
 
-| Version | Status | TypeScript | JSON Schema |
-| --- | --- | --- | --- |
-| `2026-07-28` | Stable | [`schema.ts`](schema/2026-07-28/schema.ts) | [`schema.json`](schema/2026-07-28/schema.json) |
-| `draft` | Development | [`schema.ts`](schema/draft/schema.ts) | [`schema.json`](schema/draft/schema.json) |
+| Version      | Status      | TypeScript                                 | JSON Schema                                    |
+| ------------ | ----------- | ------------------------------------------ | ---------------------------------------------- |
+| `2026-07-28` | Stable      | [`schema.ts`](schema/2026-07-28/schema.ts) | [`schema.json`](schema/2026-07-28/schema.json) |
+| `draft`      | Development | [`schema.ts`](schema/draft/schema.ts)      | [`schema.json`](schema/draft/schema.json)      |
 
 Released schema directories are immutable snapshots with version-specific JSON Schema identifiers. Development and schema generation target `schema/draft/` only. To create a release snapshot from the current draft:
 
@@ -30,8 +31,7 @@ npm run snapshot:schema -- YYYY-MM-DD
 
 ### SDK Package
 
-The redistributable TypeScript package lives in `packages/ext-tasks`. It is an
-npm workspace that publishes as `@modelcontextprotocol/ext-tasks`.
+The redistributable package lives in `packages/ext-tasks` and publishes as `@modelcontextprotocol/ext-tasks`.
 
 ```bash
 # Run schema, package, and packed-consumer checks
@@ -44,8 +44,7 @@ npm run test:watch
 npm run pack:package
 ```
 
-The package intentionally has no root export. Consumers import `/core`,
-`/core/v1`, `/core/v2`, or `/client`.
+The package intentionally has no root export. Consumers import `/client`, `/receiver`, `/core`, `/core/v1`, or `/core/v2`; the guide explains which entry point owns each workflow.
 
 ### Schema Generation