@wokuapp/ai-toolkit 0.2.1 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "woku",
       "source": "./",
       "description": "Design a listening program for your customer journey, run the VoC instruments (NPS, CSAT, CES, wokus), and turn every signal into a support ticket or an action plan, through woku's MCP server.",
-      "version": "0.2.1",
+      "version": "0.3.0",
       "author": { "name": "woku" },
       "license": "MIT",
       "homepage": "https://woku.app",

package/.claude-plugin/plugin.json

@@ -1,9 +1,22 @@
 {
   "name": "woku",
   "description": "Voice-of-customer for Claude Code. Design a listening program for your customer journey, run the fast VoC instruments (NPS, CSAT, CES, wokus), and turn every signal into a support ticket or an action plan, through woku's MCP server. Bundles the woku method so the agent acts as a CX consultant.",
-  "version": "0.2.1",
-  "author": { "name": "woku" },
+  "version": "0.3.0",
+  "author": {
+    "name": "woku"
+  },
   "homepage": "https://woku.app",
   "license": "MIT",
-  "keywords": ["woku", "mcp", "voice-of-customer", "cx", "nps", "csat", "ces", "surveys", "feedback", "sdk"]
+  "keywords": [
+    "woku",
+    "mcp",
+    "voice-of-customer",
+    "cx",
+    "nps",
+    "csat",
+    "ces",
+    "surveys",
+    "feedback",
+    "sdk"
+  ]
 }

package/.codex-plugin/plugin.json

@@ -1,12 +1,24 @@
 {
   "name": "woku",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Voice-of-customer for OpenAI Codex. Design a listening program, run the VoC instruments (NPS, CSAT, CES, wokus), and turn every signal into a support ticket or an action plan, through woku's MCP server.",
-  "author": { "name": "woku" },
-  "homepage": "https://docs.woku.app/mcp/agent-guide",
+  "author": {
+    "name": "woku"
+  },
+  "homepage": "https://woku.app/docs/en/mcp/agent-guide",
   "repository": "https://github.com/wokuApp/woku-ai-toolkit",
   "license": "MIT",
-  "keywords": ["woku", "voice-of-customer", "cx", "nps", "csat", "ces", "surveys", "feedback", "sdk"],
+  "keywords": [
+    "woku",
+    "voice-of-customer",
+    "cx",
+    "nps",
+    "csat",
+    "ces",
+    "surveys",
+    "feedback",
+    "sdk"
+  ],
   "skills": "./skills/",
   "mcpServers": {
     "woku": {
@@ -20,7 +32,10 @@
     "longDescription": "Connect your agent to woku, the voice-of-customer platform. Design a listening program for your customer journey, place the fast VoC instruments (NPS, CSAT, CES, wokus) at each moment of truth, and turn every signal into a support ticket or an action plan.",
     "developerName": "woku",
     "category": "Productivity",
-    "capabilities": ["Read", "Write"],
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
     "websiteURL": "https://woku.app",
     "privacyPolicyURL": "https://woku.app/privacy-policy",
     "termsOfServiceURL": "https://woku.app/terms-and-conditions",

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.3.0
+
+Also the per-tool metrics of a folder (`get_folder_tools_metrics`, `folders.metrics`), tracker chips on `search_voc_tools` and `tools.list` (`trackers`) and `integrationProvider` on integration folders.
+
+Cover folders and the unified tools view: the woku skill documents the MCP tools
+`search_voc_tools`, `get_voc_tools_stats`, `move_voc_tools`, `update_folder` (also sets the folder's `whatsappAlertRecipients`),
+`delete_folder`, `get_folder_report` (`scope: "all"`, `format: "csv"`), `folderId`
+on `create_nps_tool`, `create_csat_tool` and `create_ces_tool`, and the
+`organize_listening` playbook, flows with ordered steps (`create_flow`, `update_flow`, `get_flow` with `steps`), and journeys in folders (`get_journey_folders_status`, `organize_journey_folders`, `folderId` and `momentFolders` on journeys). The JavaScript and Python SDK skills add the
+`folders` and `tools` resources. Requires the server and SDK releases that ship them. The skills also cover the folder PDF in the SDKs (`folders.pdf`) and the folders paging (`foldersLimit`, `foldersCursor`) of `search_voc_tools` and `tools.list`.
+
+## 0.2.2
+
+Reconcile journey/MCP workflows, reviewed proposals, local media, SDK v4 methods,
+retry boundaries and instrument selection in the shipped skills. Correct NPS
+variable examples and public cursor limits.
+
 ## 0.2.1
 
 Remove the action-plan external-send example (Jira/Monday/ClickUp/Notion) from the SDK skills: those destinations are not available in production and the SDKs dropped `actionPlans.send`. The skills now show approve plus manage-in-woku.

package/README.md

@@ -6,10 +6,12 @@ The toolkit gives your agent woku's full tool catalog through woku's MCP server,
 
 It bundles:
 
-- The **woku MCP server** connection (`https://api.woku.app/mcp`), so the agent gets the full catalog (143 tools) with woku's OAuth. No API keys to copy.
+- The **woku MCP server** connection (`https://api.woku.app/mcp`), so the agent gets the live catalog with woku's OAuth. No API keys to copy.
 - The **woku skill**, which primes the agent with the method and tells it to call `woku_guide` first.
 - The **woku SDK skills** for JavaScript (`@wokuapp/sdk`) and Python (`woku`), so the agent can build server-side woku integrations in code (create tools, send surveys, read responses, drive tickets and action plans) over the public `/v1` API.
 
+The live `tools/list` response is authoritative. The catalog focuses on journeys, feedback instruments, clients, trackers, instrument reports and action plans. Data Studio and support tickets are Corporate capabilities.
+
 ## Install
 
 ### Claude Code
@@ -81,7 +83,7 @@ These are configured from the app, not from a package. Add a custom connector (c
 
 Point it at `https://api.woku.app/mcp` and approve access from your woku account.
 
-See the [connect guide](https://docs.woku.app/mcp/connect-a-client) and the [agent guide](https://docs.woku.app/mcp/agent-guide) for details.
+See the [connect guide](https://woku.app/docs/en/mcp/connect-a-client) and the [agent guide](https://woku.app/docs/en/mcp/agent-guide) for details.
 
 ## What you get
 
@@ -97,3 +99,33 @@ Every connection is bound to one company, chosen when you approve access. Read t
 ## License
 
 MIT. See [LICENSE](./LICENSE).
+
+### Folders and tools update (0.3.0)
+
+The skills now cover the folder tree that holds wokus and NPS, CSAT and CES tools:
+the MCP tools `search_voc_tools` (with tracker chips), `get_voc_tools_stats`, `get_folder_tools_metrics`, `move_voc_tools`,
+`update_folder`, `delete_folder`, `get_folder_report` (`scope: "all"`, `format: "csv"`),
+`get_journey_folders_status`, `organize_journey_folders`, flow `steps` in `create_flow` and `update_flow`, `folderId` on the `create_*_tool` tools, the `organize_listening` playbook of
+`woku_guide`, and the SDK `folders` and `tools` resources in JavaScript and Python.
+Verify the installed SDK and server release before using them.
+
+### Journey guidance update (0.2.2)
+
+The bundled skills now route coordinated evaluations through journeys, preserve a
+reviewed MCP proposal, explain local media capabilities by host, and cover the v4
+SDK media and enrollment iterators. They distinguish protected retries from other
+writes and use variable fragments for NPS questions. Verify the installed SDK
+release before using journey and media methods.
+
+#### Local media by host
+
+- Codex and Claude Code upload local files through multipart `POST /v1/woku-media`
+  or the backend SDK. The remote MCP tool accepts a public HTTPS URL or a supported
+  host-authorized file, never a local path or image bytes pasted as model text.
+  Never put a company secret key in frontend code.
+- ChatGPT and Claude web attachment access depends on the host and connector. Use
+  only file references that the connected tool can actually read, or a genuinely
+  public HTTPS URL. Do not invent a URL for a private attachment or promise that
+  every host forwards its uploaded files automatically.
+- Check the live tool schema and the `customer_journeys` playbook before choosing
+  the representation. Upload first, then use its `fileId` in the reviewed proposal.

package/openclaw.plugin.json

@@ -2,8 +2,10 @@
   "id": "woku-ai-toolkit",
   "name": "woku AI Toolkit",
   "description": "Voice-of-customer for your agent. Design a listening program, run the VoC instruments (NPS, CSAT, CES, wokus), and turn every signal into a support ticket or an action plan, through woku's MCP server.",
-  "version": "0.2.1",
-  "skills": ["./skills"],
+  "version": "0.3.0",
+  "skills": [
+    "./skills"
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@wokuapp/ai-toolkit",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "woku AI Toolkit: connect your agent to woku's voice-of-customer platform. Design VoC programs and turn customer feedback into support tickets and action plans, through woku's MCP server.",
   "author": "woku",
   "license": "MIT",
-  "homepage": "https://docs.woku.app/mcp/agent-guide",
+  "homepage": "https://woku.app/docs/en/mcp/agent-guide",
   "repository": {
     "type": "git",
     "url": "https://github.com/wokuApp/woku-ai-toolkit"

package/skills/woku/SKILL.md

@@ -21,11 +21,59 @@ Every business is a customer journey, and each moment of truth decides whether t
 
 ## How to help
 
-1. To design a program, call `design_voc_program`. Pass what the user knows (business type, channels, their journey moments, how to segment) and it returns a blueprint: the recommended instrument per moment (from the canonical template: sale to CSAT, delivery to woku, support to CES, post-sale to woku, loyalty to NPS), the tracker design, the action wiring, and the ordered `create_*` steps to build it.
+1. For a coordinated customer journey, use the journey workflow below. For a collection of independent instruments, call `design_voc_program`. Pass what the user knows (business type, channels, their journey moments, how to segment) and it returns a blueprint: the recommended instrument per moment (from the canonical template: sale to CSAT, delivery to woku, support to CES, post-sale to woku, loyalty to NPS), the tracker design, the action wiring, and the ordered `create_*` steps to build it.
 2. Walk the blueprint with the user and adapt it to their real journey.
 3. Build it with the `create_*` tools once the user approves, and distribute the instruments with the `send_*` tools. Nothing is created or sent without an explicit confirmation.
 4. From then on, let every signal trigger its action: tickets for individual attention, plans for systematic improvement.
 
 ## Safety
 
-Read tools need no special permission. Write tools require the `mcp:write` scope, and destructive tools (for example `delete_woku`) or sends (for example `send_nps_invitations`, `send_report_now`) require `confirm: true`. The list the server advertises on a live connection (`tools/list`) is always the authoritative answer about what is available.
+Read tools need no special permission. Write tools require the `mcp:write` scope, and destructive tools (for example `delete_woku`) or sends (for example `send_nps_invitations`) require `confirm: true`. The list the server advertises on a live connection (`tools/list`) is always the authoritative answer about what is available.
+
+## Customer journey workflow
+
+1. Call `woku_guide` with topic `customer_journeys`, and use `tools/list` as the live catalog.
+2. Collect the business experience, ordered moments and what to learn at each one.
+   Use `propose_journey` to interpret that brief. One moment gets one tool: Woku for
+   multiple facets, CSAT for satisfaction, CES for effort, NPS for recommendation.
+   Infer a separate loyalty intent without splitting delivery facets into moments.
+3. Review the returned draft. Pass that exact draft as `proposal` to
+   `create_journey_from_brief` with the authorized confirmation, avoiding a second
+   model proposal. `create_journey` accepts an explicit definition instead.
+4. Use `upload_woku_media` and `set_journey_moment_media` for missing media. Read
+   the media section of that journey playbook and the toolkit README for host-specific attachments; do not invent public attachment
+   URLs or claim local-file access in a host that does not provide it. `create_woku`
+   supports a standalone Woku using the same upload result.
+5. Keep the draft disabled while configuring. Webhook content requires one tool
+   per evaluation. Static content defaults to sharing within that moment. Preview
+   conditional descriptions, localized question variables, public image URLs,
+   trackers, folders and client fields before activation. HTTP uses sequence;
+   MCP uses cadence. Neither accepts secret fields in the definition.
+6. Configure each moment credential explicitly. Generated URL tokens and sender
+   HMAC secrets are separate from the legacy journey signature; never log them.
+   Activate with `update_journey` only within the user's authorized intent.
+7. Use enrollment lists and exact enrollment ids for inspection/stopping. Default
+   reminders are enabled; a stopped or completed cycle may be followed by another,
+   but never two open evaluations for the same subject in the same journey.
+
+## Flows with steps
+
+A flow is an ordered sequence of steps a respondent answers one after another. `create_flow` and `update_flow` take `steps`: 1 to 20 `{ type, toolId }` where `type` is `woku`, `nps`, `csat` or `ces` (each tool once, all of the company; for the company-level NPS use the company id as `toolId`). The older `wokusIds` and `npsId` still work. `get_flow` and `list_flows` return `steps`. Flows live outside folders. Call `woku_guide` with topic `flows`.
+
+## Organize the listening in folders
+
+One folder tree holds wokus and NPS, CSAT and CES tools together. Call `woku_guide` with topic `organize_listening` first.
+
+- `search_voc_tools` lists a folder level or searches the whole company (any type, case and accent insensitive, cursor paginated) and returns folders with stats, tools with their native-scale headline and counts per type.
+- `search_voc_tools` also takes `trackers` (`"name:value"` chips, up to 10; a tool must have every one; the tracker name is matched exactly and the value partially and ignoring case, so `482` also matches `00482`; company-wide, no folders; a chip without name or value is an error) to find tools by tracker.
+- `get_folder_tools_metrics` gives, for a folder and its subfolders, per-tool figures for 7, 30 (default) or 90 days against the period before (0 = whole history) and the histogram of scores. It returns `toolCount` and the busiest tools (`limit`, default 50); the daily sums only with `includeDaily: true`. Use it for trends and to find the weakest tools; never average across types.
+- `get_voc_tools_stats` gives reviews and the headline of each type (woku stars, NPS score, CSAT satisfied %, CES mean) for the company or one folder. Never average across types: the scales differ.
+- `create_folder`, `update_folder` (rename, recolor, or set `whatsappAlertRecipients`: the WhatsApp numbers alerted when a comment of any tool in the folder is an improvement) and `move_voc_tools` (items of mixed types, `folderId: null` for the root) organize the tree; `create_nps_tool`, `create_csat_tool` and `create_ces_tool` accept `folderId`.
+- `get_folder_report` with `scope: "all"` returns the mixed AI report of a folder and its subfolders, and with `format: "csv"` the responses as CSV text. `search_voc_tools` accepts `foldersLimit` and `foldersCursor` to page the folders ("see more"; `foldersNextCursor` in the result). The folder PDF is binary, so it is only on the API and the SDKs (`GET /v1/folders/{id}/pdf`).
+- Journeys can live in folders (`Viajes > journey > moment`): `get_journey_folders_status` shows whether the company organizes them and what is pending, and `organize_journey_folders` switches it on and runs a background pass that only moves tools without a folder (propose it and wait for approval; it returns a conflict while a pass is running). `get_journey` and `list_journeys` show `folderId` and `momentFolders`, and folders created by woku carry an `origin` (`journeys-root`, `journey`, `journey-moment`, `integration`; integration folders also carry `integrationProvider`, for example `shopify`); read `origin`, `integrationProvider` and the stats of a folder with `search_voc_tools`, not with `get_folder` or `list_folders`, which only count wokus.
+- `delete_folder` needs `confirm: true`; nothing inside is deleted, the content moves up to the parent. Moving or deleting folders is a user decision: propose the new structure and wait for approval.
+
+Tickets use email destinations; plans use groups of platform users. Tickets and
+Data Studio are Corporate capabilities. Do not expose retired reports, alerts,
+goals, data-source or data-flow management through examples; instrument reports
+and survey flows remain available.

package/skills/woku-sdk-javascript/SKILL.md

@@ -8,7 +8,7 @@ description: "Build a server-side woku integration in JavaScript or TypeScript w
 `@wokuapp/sdk` is the official **server-side** client for the woku management API
 (`/v1`). Use it when the user wants woku operations in their Node.js backend
 instead of raw HTTP. It is typed, retries transient failures, makes creates
-idempotent, and auto-paginates lists.
+safe for protected writes, and supports pagination.
 
 **Server-only.** The company secret key grants full management access. Keep it on
 the backend, never in a browser, mobile app or other untrusted client. For
@@ -33,8 +33,9 @@ const woku = new Woku({ apiKey: process.env.WOKU_API_KEY });
 
 ## Core operations
 
-Creates are idempotent (auto `Idempotency-Key`); actions (send, test, reply) are
-never auto-retried.
+GETs and protected writes retry with a stable key: tracker/VoC definitions,
+invitations, and journey create/enroll/stop/mint-URL/event operations. Other writes
+and uploads are attempted once. A key alone does not make a write idempotent.
 
 ```ts
 // Tracker definitions and values (wire your CRM/ERP ids to feedback tools).
@@ -44,7 +45,8 @@ await woku.trackers.assignToWoku('woku_123', { name: 'Store #1', value: 'TX-42'
 // VoC tools: npsTools / csatTools / cesTools (create/list/get/update/delete).
 const tool = await woku.npsTools.create({
   name: 'Post-purchase',
-  npsMessage: 'How likely are you to recommend us?',
+  npsMessage: 'our company',
+  audienceType: 'a friend or colleague',
 });
 
 // Send a survey. IMPORTANT: `channel` is required and `recipients` is an array
@@ -69,7 +71,8 @@ await woku.actionPlans.complete('plan_123');
 
 Namespaces: `trackers`, `npsTools` / `csatTools` / `cesTools`, `nps` / `csat` /
 `ces`, `wokus`, `forms`, `flows`, `actionPlans`, `actionPlanGroups`, `tickets`,
-`ticketDestinations`, `dispatches`, `reports`, `company`, `quarantines`.
+`ticketDestinations`, `dispatches`, `reports`, `company`, `quarantines`, `journeys`, `media`,
+`folders`, `tools`, `journeyFolders`.
 
 ## Pagination, errors, retries
 
@@ -90,6 +93,76 @@ the old one; store the returned key. `woku.company.revokeKey()` disables the key
 ## When to reach for the reference
 
 For the full method list, request/response shapes and per-call options, point the
-user to the SDK page at https://docs.woku.app/development/sdk-javascript and the
-API reference at https://docs.woku.app/development/api. There is an equivalent
+user to the SDK page at https://woku.app/docs/en/development/sdk-javascript and the
+API reference at https://woku.app/docs/en/development/api. There is an equivalent
 Python SDK (`woku`) documented at /development/sdk-python.
+
+## Folders and tools
+
+One folder tree holds wokus and NPS, CSAT and CES tools. Needs the SDK release that ships `folders` and `tools`; verify the installed version.
+
+```ts
+const folder = await woku.folders.create({ name: 'Post-sale' });
+await woku.csatTools.create({ name: 'Delivery', question: 'How satisfied are you?', folderId: folder.id });
+
+for await (const tool of await woku.tools.list({ folderId: folder.id, types: ['csat', 'nps'] })) {
+  console.log(tool.type, tool.name, tool.headline.value);
+}
+const stats = await woku.tools.stats({ folderId: folder.id }); // native scales, never averaged across types
+const tagged = await woku.tools.list({ trackers: ['TRR:00482'] }); // tracker chips 'name:value', company-wide
+const metrics = await woku.folders.metrics(folder.id, { days: 30 }); // per tool, period vs the previous one; 0 = all history
+await woku.tools.move({ items: [{ type: 'csat', id: toolId }], folderId: null }); // null = root
+const csv: string = await woku.folders.csv(folder.id);
+const pdf: Uint8Array = await woku.folders.pdf(folder.id, { lang: 'en' }); // folder report as PDF bytes
+await woku.folders.delete(folder.id); // content moves up to the parent, nothing is deleted
+```
+
+Journeys in folders: `await woku.journeyFolders.status()` and `await woku.journeyFolders.organize()` (background pass, 409 while running); `journeys.get` returns `folderId` and `momentFolders`, and folders expose `origin`.
+
+`folders`: `list`, `get`, `create`, `update`, `move`, `delete`, `report`, `csv`, `pdf`. `tools`: `list` (cursor iterable; `foldersLimit` pages the folders with `page.hasMoreFolders()` / `page.getMoreFolders()`), `stats`, `move`. `npsTools` / `csatTools` / `cesTools` accept `folderId` on `create` and have `move(id, { folderId })`.
+
+## Flows
+
+```ts
+const flow = await woku.flows.create({
+  name: 'Post-sale',
+  steps: [{ type: 'nps', toolId: npsToolId }, { type: 'csat', toolId: csatToolId }, { type: 'woku', toolId: wokuId }],
+});
+await woku.flows.update(flow._id, { steps: [{ type: 'csat', toolId: csatToolId }] });
+await woku.flows.delete(flow._id); // its tools and responses stay
+```
+
+`flows`: `list`, `get`, `create`, `update`, `delete`. 1 to 20 steps, each tool once; for an `nps` step the company id as `toolId` is the company-level NPS. Needs the SDK release that ships flow writes.
+
+## Customer journeys and media
+
+Prefer an actual journey when the task coordinates several business moments.
+One moment has one tool: several facets use Woku, satisfaction CSAT, effort CES,
+recommendation NPS. A separate loyalty intention can add a moment; several facets
+of delivery must not become several delivery moments. Journey response tools are
+identified. Operator sends start immediately; opening a QR/link waits for a saved
+first response. Later moments wait or use their webhook, optionally with a backup.
+Default wait is ten days; zero means one hour. Keep reminders enabled unless asked.
+
+The SDK exposes 17 journey methods, plus lazy enrollment iteration. Public cursor
+pages allow 100 items (default 20); the Admin page endpoint is separate and uses 50.
+Use the exact enrollment id to stop one case. Editing creates a new definition
+version; running cases keep their snapshot. A cycle finishes on its last response
+or 30 days from the first send of the last moment.
+
+Media uploads use multipart and return fileId for moment.toolSpec.fileId. They do
+not retry automatically; 413 is PayloadTooLargeError. Company keys remain on the
+backend; minted webhook URLs use a separate HTTP transport without that key.
+Keep request/idempotency ids stable during uncertain retries. Deduplication lasts
+24 hours; inspect the outcome before submitting with a new key.
+
+Journey and media methods require SDK version 0.3.0 or later. Verify the installed
+version and changelog when upgrading an existing integration.
+
+```ts
+const media = await woku.media.upload({ file: imageBytes, filename: 'delivery.jpg', contentType: 'image/jpeg' });
+for await (const enrollment of woku.journeys.iterEnrollments(journeyId, { limit: 100 })) {
+  console.log(enrollment.id, enrollment.lifecycle);
+}
+await woku.journeys.previewMoment(journeyId, 'delivery', { order: 'case-123', late: true });
+```

package/skills/woku-sdk-python/SKILL.md

@@ -9,7 +9,7 @@ The `woku` package is the official **server-side** client for the woku
 management API (`/v1`), over `httpx`. Use it when the user wants woku operations
 in their Python backend instead of raw HTTP. It offers a synchronous client
 (`Woku`) and an asynchronous twin (`AsyncWoku`), typed request models, automatic
-retries, idempotent creates and auto-pagination. It is the counterpart of the
+protected write retries and pagination. It is the counterpart of the
 JavaScript SDK (`@wokuapp/sdk`), with the same surface.
 
 **Server-only.** The company secret key grants full management access. Keep it on
@@ -35,8 +35,9 @@ woku = Woku(api_key="sk_...")  # or set WOKU_API_KEY and call Woku()
 
 ## Core operations
 
-Creates are idempotent (auto `Idempotency-Key`); actions (send, test, reply) are
-never auto-retried.
+GETs and protected writes retry with a stable key: tracker/VoC definitions,
+invitations, and journey create/enroll/stop/mint-URL/event operations. Other writes
+and uploads are attempted once. A key alone does not make a write idempotent.
 
 ```python
 # Tracker definitions and values (wire your CRM/ERP ids to feedback tools).
@@ -45,7 +46,8 @@ woku.trackers.assign_to_woku("woku_123", {"name": "Store #1", "value": "TX-42"})
 
 # VoC tools: nps_tools / csat_tools / ces_tools (create/list/get/update/delete).
 tool = woku.nps_tools.create(
-    {"name": "Post-purchase", "npsMessage": "How likely are you to recommend us?"}
+    {"name": "Post-purchase", "npsMessage": "our company",
+    "audienceType": "a friend or colleague"}
 )
 
 # Send a survey. IMPORTANT: `channel` is required and `recipients` is a list of
@@ -71,7 +73,7 @@ woku.action_plans.complete("plan_123")
 Namespaces: `trackers`, `nps_tools` / `csat_tools` / `ces_tools`, `nps` / `csat`
 / `ces`, `wokus`, `forms`, `flows`, `action_plans`, `action_plan_groups`,
 `tickets`, `ticket_destinations`, `dispatches`, `reports`, `company`,
-`quarantines`.
+`quarantines`, `folders`, `tools`, `journey_folders`.
 
 ## Async
 
@@ -113,6 +115,77 @@ the key.
 ## When to reach for the reference
 
 For the full method list, request/response shapes and per-call options, point the
-user to the SDK page at https://docs.woku.app/development/sdk-python and the API
-reference at https://docs.woku.app/development/api. There is an equivalent
+user to the SDK page at https://woku.app/docs/en/development/sdk-python and the API
+reference at https://woku.app/docs/en/development/api. There is an equivalent
 JavaScript SDK (`@wokuapp/sdk`) documented at /development/sdk-javascript.
+
+## Folders and tools
+
+One folder tree holds wokus and NPS, CSAT and CES tools. Needs the SDK release that ships `folders` and `tools`; verify the installed version.
+
+```python
+folder = woku.folders.create({"name": "Post-sale"})
+woku.csat_tools.create({"name": "Delivery", "question": "How satisfied are you?", "folderId": folder["id"]})
+
+for tool in woku.tools.list({"folderId": folder["id"], "types": ["csat", "nps"]}):
+    print(tool["type"], tool["name"], tool["headline"]["value"])
+stats = woku.tools.stats({"folderId": folder["id"]})  # native scales, never averaged across types
+tagged = woku.tools.list({"trackers": ["TRR:00482"]})  # tracker chips "name:value", company-wide
+metrics = woku.folders.metrics(folder["id"], {"days": 30})  # per tool, period vs the previous one; 0 = all history
+woku.tools.move({"items": [{"type": "csat", "id": tool_id}], "folderId": None})  # None = root
+csv_text = woku.folders.csv(folder["id"])
+pdf_bytes = woku.folders.pdf(folder["id"], {"lang": "en"})  # folder report as PDF bytes
+woku.folders.delete(folder["id"])  # content moves up to the parent, nothing is deleted
+```
+
+Journeys in folders: `woku.journey_folders.status()` and `woku.journey_folders.organize()` (background pass, `ConflictError` while running); `journeys.get` returns `folderId` and `momentFolders`, and folders expose `origin`.
+
+`folders`: `list`, `get`, `create`, `update`, `move`, `delete`, `report`, `csv`, `pdf`. `tools`: `list` (iterates across cursor pages; `foldersLimit` pages the folders with `has_more_folders()` / `get_more_folders()`), `stats`, `move`. `nps_tools` / `csat_tools` / `ces_tools` accept `folderId` on `create` and have `move(tool_id, {"folderId": ...})`. `AsyncWoku` mirrors all of it.
+
+## Flows
+
+```python
+flow = woku.flows.create({
+    "name": "Post-sale",
+    "steps": [{"type": "nps", "toolId": nps_tool_id}, {"type": "csat", "toolId": csat_tool_id}, {"type": "woku", "toolId": woku_id}],
+})
+woku.flows.update(flow["_id"], {"steps": [{"type": "csat", "toolId": csat_tool_id}]})
+woku.flows.delete(flow["_id"])  # its tools and responses stay
+```
+
+`flows`: `list`, `get`, `create`, `update`, `delete`. 1 to 20 steps, each tool once; for an `nps` step the company id as `toolId` is the company-level NPS. `AsyncWoku` mirrors it. Needs the SDK release that ships flow writes.
+
+## Customer journeys and media
+
+Prefer an actual journey when the task coordinates several business moments.
+One moment has one tool: several facets use Woku, satisfaction CSAT, effort CES,
+recommendation NPS. A separate loyalty intention can add a moment; several facets
+of delivery must not become several delivery moments. Journey response tools are
+identified. Operator sends start immediately; opening a QR/link waits for a saved
+first response. Later moments wait or use their webhook, optionally with a backup.
+Default wait is ten days; zero means one hour. Keep reminders enabled unless asked.
+
+The SDK exposes 17 journey methods, plus lazy enrollment iteration. Public cursor
+pages allow 100 items (default 20); the Admin page endpoint is separate and uses 50.
+Use the exact enrollment id to stop one case. Editing creates a new definition
+version; running cases keep their snapshot. A cycle finishes on its last response
+or 30 days from the first send of the last moment.
+
+Media uploads use multipart and return fileId for moment.toolSpec.fileId. They do
+not retry automatically; 413 is PayloadTooLargeError. Company keys remain on the
+backend; minted webhook URLs use a separate HTTP transport without that key.
+Keep request/idempotency ids stable during uncertain retries. Deduplication lasts
+24 hours; inspect the outcome before submitting with a new key.
+
+Journey and media methods require SDK version 0.3.0 or later. Verify the installed
+version and changelog when upgrading an existing integration.
+
+```python
+with open("delivery.jpg", "rb") as image:
+    media = woku.media.upload(image, filename="delivery.jpg", content_type="image/jpeg")
+for enrollment in woku.journeys.iter_enrollments(journey_id, {"limit": 100}):
+    print(enrollment["id"], enrollment["lifecycle"])
+woku.journeys.preview_moment(journey_id, "delivery", {"order": "case-123", "late": True})
+```
+
+AsyncWoku provides the corresponding awaitable methods and async iterators.