docs: align Motia docs with v1 migration cleanup#1325
Merged
Conversation
Refresh docs for Motia 1.0 by adding migration and package references, clarifying Motia vs iii naming, and hiding legacy examples from production routes, search, and generated LLM artifacts. Made-with: Cursor
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📝 WalkthroughWalkthroughThis PR encompasses extensive Motia v1.0 cleanup, including refactored handler signatures (removing context parameter injection in favor of direct imports), reorganized documentation with legacy example deprecation, removal of LLM-specific documentation, relocation of stream client exports to a separate Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 12
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (6)
frameworks/motia/docs/public/llm-docs/video-showcase.mdx.md (1)
3-3:⚠️ Potential issue | 🟡 MinorUpdate stale frontmatter description to match archived state.
Line 3 still promises active video demos, which now conflicts with the archived notice and may produce misleading snippets in search/LLM indexing.
✏️ Suggested doc metadata fix
-description: Watch Motia in action through our video demonstrations and tutorials +description: Archived page for legacy Motia video showcase content; use current docs, migration guide, and official channel instead🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/video-showcase.mdx.md` at line 3, Update the frontmatter "description" field in the file's metadata (the description key shown in video-showcase.mdx.md) so it reflects the archived state instead of promising active video demos — replace the current "Watch Motia in action through our video demonstrations and tutorials" text with a concise archived-note (e.g., indicating demos are removed/unavailable or this page is archived) so search/LLM snippets and the page header match the archived notice.frameworks/motia/docs/public/llm-docs/development-guide/project-structure.mdx.md (1)
323-345:⚠️ Potential issue | 🟠 MajorThe Python queue example still depends on the old context utilities.
This snippet now imports
enqueuedirectly, but it still requiresctxand builds the timestamp withctx.utils.dates.now(). That mixes the new and old patterns in one example. Replace the timestamp with a standard-library helper and update the handler shape so the example matches the rest of the v1 docs.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/development-guide/project-structure.mdx.md` around lines 323 - 345, The example mixes old ctx utilities with the new pattern: update the handler signature to remove the ctx parameter so it matches other v1 handlers (e.g., change async handler(input_data) instead of async handler(input_data, ctx)), and replace ctx.utils.dates.now().isoformat() with a stdlib timestamp (e.g., datetime.utcnow().isoformat()) so processed_at uses the standard library; keep the direct import of enqueue and the rest of the payload construction (original, processed_at, count) unchanged and ensure you import the required datetime helper at the top of the snippet.frameworks/motia/docs/public/llm-docs/deployment-guide/railway.mdx.md (1)
89-94:⚠️ Potential issue | 🟡 MinorWire the private Redis URL into the sample.
The guide tells users to set
REDIS_PRIVATE_URL, but every adapter example below still readsREDIS_URL. As written, the private URL never gets used. Either mapREDIS_URLto${{Redis.REDIS_PRIVATE_URL}}in the Railway commands or update the YAML examples to readREDIS_PRIVATE_URL.Also applies to: 191-246
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/deployment-guide/railway.mdx.md` around lines 89 - 94, The docs set REDIS_PRIVATE_URL but the adapter examples still reference REDIS_URL, so the private URL is never used; update either the Railway variable commands to map REDIS_URL to the private endpoint (set REDIS_URL='${{Redis.REDIS_PRIVATE_URL}}') or change all adapter config/examples to read REDIS_PRIVATE_URL instead of REDIS_URL; look for occurrences of REDIS_URL and REDIS_PRIVATE_URL in the file and ensure consistency across the railway variables block and the YAML/adapter examples so the private URL is actually consumed.frameworks/motia/docs/content/docs/development-guide/streams.mdx (1)
339-349:⚠️ Potential issue | 🟠 MajorUse the stream WebSocket port in this provider example.
Line 342 points to
ws://localhost:3000, but this doc uses stream API port3112elsewhere (Line 412). Keeping3000here can break local subscriptions for users copying this snippet.Suggested doc fix
- const streamAddress = useMemo(() => new URL('ws://localhost:3000').toString(), []) + const streamAddress = useMemo(() => new URL('ws://localhost:3112').toString(), [])🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/content/docs/development-guide/streams.mdx` around lines 339 - 349, The stream provider example in AppShell uses the wrong WebSocket port; update the streamAddress construction inside the AppShell component (where streamAddress = new URL('ws://localhost:3000').toString()) to use the stream API port 3112 instead of 3000 so it matches the rest of the docs and avoids breaking subscriptions when mounting MotiaStreamProvider; ensure the URL string passed to new URL(...) is changed to 'ws://localhost:3112'.frameworks/motia/docs/public/llm-docs/development-guide/streams.mdx.md (1)
339-349:⚠️ Potential issue | 🟡 MinorUse a consistent default stream WebSocket address across examples.
This page shows
ws://localhost:3000in one setup andws://localhost:3112in another. A single default (or an explicit proxy note) will reduce copy/paste setup errors.Also applies to: 404-413
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/development-guide/streams.mdx.md` around lines 339 - 349, Several examples use inconsistent default WebSocket addresses (ws://localhost:3000 vs ws://localhost:3112); update the AppShell component so the streamAddress constant (created via useMemo) uses a single canonical default (pick one port, e.g., ws://localhost:3112) and apply the same change to all other examples that set streamAddress or an equivalent default (lines showing MotiaStreamProvider, AppShell, and any other snippets creating streamAddress/useMemo) so every example uses the same default WebSocket URL or includes a consistent proxy note.frameworks/motia/docs/public/llm-docs/api-reference.mdx.md (1)
349-350:⚠️ Potential issue | 🟠 MajorUpdate cron examples in api-reference.mdx.md to use 7-field format.
Lines 349, 369, 387, 418, 437, 653, and 729 show 5-field cron expressions, but the iii engine documentation explicitly requires 7-field format (includes seconds and optional year). Converting
cron('0 9 * * *')tocron('0 0 9 * * * *')and similar for other examples will align with the documented standard and prevent users from copying incorrect schedules.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/api-reference.mdx.md` around lines 349 - 350, Update the 5-field cron examples to the iii engine's required 7-field format by adding seconds (and optional year) fields; replace occurrences like cron('0 9 * * *') with cron('0 0 9 * * * *') and similarly expand other examples (e.g., any cron('M H D M W') patterns) to the form cron('s m h D M W Y') so all examples in api-reference.mdx.md use the 7-field format used by the iii engine.
🟡 Minor comments (11)
frameworks/motia/docs/public/llm-docs/product-showcase/chessarena-ai.mdx.md-36-39 (1)
36-39:⚠️ Potential issue | 🟡 MinorFix small grammar issue in repo structure list.
Line 38 reads incomplete (
types/ shared types). Add “for” to match the other bullets’ style.Proposed edit
-- `types/` shared types +- `types/` for shared types🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/product-showcase/chessarena-ai.mdx.md` around lines 36 - 39, The repo structure bullet for `types/` is missing the word "for"; update the markdown list entry containing the `types/` token so it matches the other bullets' style (e.g., change the line with `types/ shared types` to include "for" so it reads like the other entries).frameworks/motia/docs/content/docs/concepts/overview.mdx-25-25 (1)
25-25:⚠️ Potential issue | 🟡 MinorUse v1 “HTTP” terminology instead of “API” in module list.
Line 25 mixes legacy wording with the updated docs vocabulary. Using “HTTP” here keeps migration messaging consistent.
✏️ Suggested wording update
-| **iii** | The runtime engine that runs infrastructure modules (queue, state, stream, cron, API, observability) | +| **iii** | The runtime engine that runs infrastructure modules (queue, state, stream, cron, HTTP, observability) |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/content/docs/concepts/overview.mdx` at line 25, Update the module list entry for the "**iii**" row in overview.mdx to use the v1 terminology: replace the word "API" with "HTTP" so the line reads "The runtime engine that runs infrastructure modules (queue, state, stream, cron, HTTP, observability)"; locate the string containing "**iii**" and modify only that token to maintain consistency with updated docs vocabulary.frameworks/motia/docs/public/llm-docs/getting-started/handler-migration-guide.mdx.md-668-676 (1)
668-676:⚠️ Potential issue | 🟡 MinorReview Python migration checklist item.
Line 670 suggests the handler signature
handler(request: ApiRequest[Any], ctx: FlowContext[Any]) -> ApiResponse[Any], but the code examples in lines 432-435 showhandler(request: ApiRequest[Any]) -> ApiResponse[Any]without actxparameter. The checklist should be consistent with the examples.📝 Suggested fix
-- Change handler signature to `handler(request: ApiRequest[Any], ctx: FlowContext[Any]) -> ApiResponse[Any]` +- Change handler signature to `handler(request: ApiRequest[Any]) -> ApiResponse[Any]` (ctx is optional if not using match/traceId/trigger)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/getting-started/handler-migration-guide.mdx.md` around lines 668 - 676, The checklist and examples are inconsistent about the handler signature: update either the checklist or the examples so they match; specifically ensure the handler definition shown in examples uses the same signature as the checklist (handler(request: ApiRequest[Any], ctx: FlowContext[Any]) -> ApiResponse[Any]) or change the checklist to the single-arg form (handler(request: ApiRequest[Any]) -> ApiResponse[Any]); locate the example `handler` function and the checklist line referring to `ApiRequest`, `FlowContext`, and `ApiResponse` and make them identical, and also ensure any SSE examples reference `MotiaHttpArgs` consistently where mentioned.frameworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.md-20-24 (1)
20-24:⚠️ Potential issue | 🟡 MinorAdd a language identifier to this fenced block.
Line 20 uses a plain fenced block; markdownlint (MD040) expects a language label.
Suggested doc fix
-``` +```text dist/ ├── index-production.js └── index-production.js.map</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@frameworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.mdaround
lines 20 - 24, The fenced code block that shows the dist tree (starting with the
line "dist/") lacks a language identifier which triggers markdownlint MD040;
update the fenced block delimiter fromtotext (or another appropriate
label) so the block becomes a labeled code fence (e.g., ```text) surrounding the
existing lines "dist/", "├── index-production.js", and "└──
index-production.js.map" in the docker.mdx.md content.</details> </blockquote></details> <details> <summary>frameworks/motia/docs/public/llm-docs/getting-started/migration-guide.mdx.md-601-611 (1)</summary><blockquote> `601-611`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language identifier to the cron diagram block.** Line 601 is a fenced block without a language, which triggers MD040. <details> <summary>Suggested doc fix</summary> ```diff -``` +```text ┌──────────── second (0-59) │ ┌────────── minute (0-59) ... * * * * * * * ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@frameworks/motia/docs/public/llm-docs/getting-started/migration-guide.mdx.md
around lines 601 - 611, The fenced cron diagram block currently has no language
identifier which triggers MD040; update the fenced code block that begins with
the cron diagram (the block containing "┌──────────── second (0-59)" and ending
with "* * * * * * *") to include a language token (e.g., add "text" after the
opening backticks so it becomes ```text) so the block is treated as a code fence
and MD040 is satisfied.</details> </blockquote></details> <details> <summary>frameworks/motia/docs/public/llm-docs/concepts/iii-engine.mdx.md-10-33 (1)</summary><blockquote> `10-33`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language identifier to the architecture code fence.** Line 10 should specify a fence language to satisfy MD040. <details> <summary>Suggested doc fix</summary> ```diff -``` +```text ┌─────────────────────────────────────────────┐ │ iii Engine │ ... └─────────────────────────────────────────────┘ ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@frameworks/motia/docs/public/llm-docs/concepts/iii-engine.mdx.mdaround
lines 10 - 33, The ASCII architecture diagram code fence is missing a language
identifier (causing MD040); update the opening triple-backtick in the diagram
block to include a language (e.g. use "text") so it reads ```text and leave the
diagram contents unchanged—look for the ASCII box diagram in the iii Engine
section and modify its opening fence accordingly.</details> </blockquote></details> <details> <summary>frameworks/motia/docs/public/llm-docs/deployment-guide/self-hosted.mdx.md-17-21 (1)</summary><blockquote> `17-21`: _⚠️ Potential issue_ | _🟡 Minor_ **Specify a language for the `dist/` tree code block.** Line 17 has an unlabeled fence; markdownlint will continue to report MD040. <details> <summary>Suggested doc fix</summary> ```diff -``` +```text dist/ ├── index-production.js └── index-production.js.map ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@frameworks/motia/docs/public/llm-docs/deployment-guide/self-hosted.mdx.md
around lines 17 - 21, The code block showing the dist/ directory tree uses an
unlabeled fence; add a language specifier (e.g., "text") to the opening triple
backticks for the block that contains "dist/" so markdownlint MD040 is
satisfied; update the fenced block that begins withand contains the tree lines ("dist/", "├── index-production.js", "└── index-production.js.map") to start withtext instead of just ``` to label the code block.</details> </blockquote></details> <details> <summary>frameworks/motia/docs/public/llm-docs/advanced-features/multi-language.mdx.md-12-28 (1)</summary><blockquote> `12-28`: _⚠️ Potential issue_ | _🟡 Minor_ **Add a language to the architecture code fence.** Line 12 uses an unlabeled fenced block, which will keep MD040 warnings active. <details> <summary>Suggested doc fix</summary> ```diff -``` +```text ┌──────────────────────────────────┐ │ iii Engine │ ... └──────────────────────────────────┘ ``` ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/advanced-features/multi-language.mdx.md` around lines 12 - 28, The fenced ASCII-art diagram block is unlabeled which triggers MD040; update the code fence that wraps the diagram (the ASCII art starting with the box "iii Engine" and ending with the bottom box) to include a language tag (e.g., add "text" after the opening triple backticks) so the block is explicitly labeled and the MD040 warning is resolved. ``` </details> </blockquote></details> <details> <summary>frameworks/motia/docs/public/llm-docs/concepts/steps.mdx.md-6-8 (1)</summary><blockquote> `6-8`: _⚠️ Potential issue_ | _🟡 Minor_ **Address markdownlint issues in changed blocks (MD037, MD040).** The commented video block (Lines 6-8) and cron diagram fenced block (starting Line 536) trigger markdownlint warnings. Please normalize formatting and add an explicit fence language for the cron diagram block. Also applies to: 536-546 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@frameworks/motia/docs/public/llm-docs/concepts/steps.mdx.mdaround lines 6 -
8, Remove the HTML comment wrapper around the JSX video block and convert that
snippet into a proper fenced code block (usehtml orjsx) so it no longer
contains bare HTML comments (addresses MD037), and for the cron diagram fenced
block (the block starting around the cron diagram) add an explicit fence
language (e.g.,text orcron) and normalize spacing/indentation so the
fenced block is clean (addresses MD040); locate the commented video snippet and
the cron diagram fenced block by the video JSX fragment and the cron diagram
content and apply these two changes.</details> </blockquote></details> <details> <summary>frameworks/motia/docs/public/llm-docs/development-guide/observability.mdx.md-173-173 (1)</summary><blockquote> `173-173`: _⚠️ Potential issue_ | _🟡 Minor_ **Fix markdown code block style at Line 173.** `markdownlint` flags this block as style-inconsistent (MD046). Please align this code block with the repository’s configured code block style to avoid docs lint noise in CI. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@frameworks/motia/docs/public/llm-docs/development-guide/observability.mdx.md
at line 173, The MD046 lint error is caused by an inconsistent code-fence at the
snippet starting withtypescript; fix it by converting the block to the repository’s fenced code-block style: ensure you have a proper opening fence with the language tag "typescript", a matching closing fence of the same backticks, and a blank line before and after the fenced block; locate the offending fence (the tokentypescript) and add the missing/consistent closingrules.frameworks/motia/docs/public/llm-docs/concepts/overview.mdx.md-6-8 (1)
6-8:⚠️ Potential issue | 🟡 MinorResolve markdownlint emphasis-marker warnings in the commented video block.
Lines 6-8 are flagged by MD037. Please adjust the comment formatting so markdownlint no longer parses this as malformed emphasis.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/concepts/overview.mdx.md` around lines 6 - 8, The JSX-style comment block around the video (the commented video block using {/* ... */}) is triggering markdownlint MD037; replace that JSX comment wrapper with an HTML comment instead (wrap the entire <video>...</video> block in <!-- ... -->) or alternatively put the block inside a fenced code block so the markdown parser won't treat the markup as emphasis; update the commented video block accordingly to use <!-- ... --> (or a ```html fenced block) so markdownlint no longer flags it.
🧹 Nitpick comments (10)
frameworks/motia/docs/public/llm-docs/product-showcase/chessarena-ai.mdx.md (1)
47-47: Avoid time-relative wording in static docs.“Based on the latest README...” can become stale quickly in generated docs. Prefer neutral wording (e.g., “According to the project README and package scripts”).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/product-showcase/chessarena-ai.mdx.md` at line 47, Replace the time-relative phrase "Based on the latest README and package scripts" with a neutral, non-time-sensitive alternative such as "According to the project README and package scripts" in the product-showcase text; locate the exact sentence in the content (the string "Based on the latest README and package scripts") and update it to the suggested neutral wording to avoid staleness in static docs.frameworks/motia/docs/content/docs/product-showcase/chessarena-ai.mdx (1)
20-21: Clarify “API” wording to avoid v1 naming ambiguity.Line [20] and Line [36] can be read as the legacy
apitrigger naming. Consider “HTTP entrypoints/services” when describing architecture, while keeping literal folder names intact.✏️ Suggested wording tweak
-- Event-driven orchestration across API and worker logic +- Event-driven orchestration across HTTP entrypoints and worker logic ... -- `api/` for backend and worker logic +- `api/` for backend HTTP entrypoints and worker logicAlso applies to: 36-37
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/content/docs/product-showcase/chessarena-ai.mdx` around lines 20 - 21, Replace ambiguous occurrences of the term "API" (and lowercase "api") in the prose lines (e.g., the bullet "Event-driven orchestration across API and worker logic" and the similar text around lines 36–37) with clearer phrasing such as "HTTP entrypoints/services" while leaving any literal folder or trigger names (folder names like "api" or code references) unchanged; update only the descriptive wording in the Markdown content of chessarena-ai.mdx so readers don’t confuse it with legacy `api` trigger naming.frameworks/motia/docs/content/docs/api-reference.mdx (1)
838-841: Incomplete spread syntax in code examples.The
items: [...]notation is ambiguous—it could be misread as literal code rather than a placeholder. Consider using a more explicit placeholder likeitems: ['item1', 'item2']oritems: someItemsArrayfor clarity.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/content/docs/api-reference.mdx` around lines 838 - 841, Replace the ambiguous placeholder in the example object so readers don't interpret "items: [...]" as literal syntax; update the `data` object (containing `orderId` and `messageGroupId`) to use an explicit items placeholder such as `items: ['item1', 'item2']` or `items: someItemsArray` so the `data` example is clear and valid-looking.frameworks/motia/docs/public/llm-docs/development-guide/motia-package-exports.mdx.md (1)
31-31: Consider clarifyingapiexport status.The
apiexport is listed alongsidehttp, but other documentation in this PR consistently useshttpas the new naming convention. Consider adding a note thatapiis a legacy alias for backward compatibility, or remove it if it's deprecated in v1.x.Suggested clarification
### Runtime primitives - `step` - `multiTriggerStep` -- `http`, `queue`, `cron`, `state`, `stream`, `api` +- `http`, `queue`, `cron`, `state`, `stream` +- `api` (legacy alias for `http`, prefer `http` in new code)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/development-guide/motia-package-exports.mdx.md` at line 31, Update the export list to clarify the status of the `api` export: either mark `api` explicitly as a legacy alias for `http` (e.g., append "(legacy alias for `http` — kept for backward compatibility)") or remove `api` entirely if deprecated in v1.x; ensure the `http` export remains the primary name and add a short note nearby stating the decision so readers know whether `api` is supported or removed.frameworks/motia/docs/app/docs/[[...slug]]/page.tsx (2)
80-86: Redundant filtering ingenerateStaticParams.
source.generateParams()already filters out legacy examples in production (as implemented inlib/source.ts). The additional filter on line 86 is redundant.♻️ Proposed simplification
export async function generateStaticParams() { - const params = source.generateParams() - - if (!isProduction) return params - - // Keep legacy examples files in-repo, but hide all example routes in production. - return params.filter((item) => !isLegacyExamplesSlug(item.slug)) + return source.generateParams() }The filtering is already handled by
source.generateParams()inlib/source.ts.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/app/docs/`[[...slug]]/page.tsx around lines 80 - 86, generateStaticParams performs an extra filter that removes legacy example slugs after calling source.generateParams(), but source.generateParams() already applies that filtering in production; remove the redundant params.filter(...) call (the predicate using isLegacyExamplesSlug) and simply return params (keeping the early return when !isProduction) so generateStaticParams delegates filtering to source.generateParams() and preserves existing behavior.
18-20: Duplicate helper function.This
isLegacyExamplesSlugfunction duplicates the one inlib/source.ts. Import it from there instead to maintain DRY principles and ensure consistent behavior.♻️ Proposed fix
-import { baseSource, source } from '@/lib/source' +import { baseSource, source, isLegacyExamplesSlug } from '@/lib/source' const isProduction = process.env.NODE_ENV === 'production' - -function isLegacyExamplesSlug(slug?: string[]) { - return slug?.[0] === 'examples' -}This requires exporting
isLegacyExamplesSlugfromlib/source.tsas suggested in that file's review.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/app/docs/`[[...slug]]/page.tsx around lines 18 - 20, Remove the duplicate isLegacyExamplesSlug function from the page component and instead import the shared isLegacyExamplesSlug helper from the module where it lives; update that module to export isLegacyExamplesSlug if it isn’t exported yet, then replace the local function in page.tsx with an import statement that references the shared isLegacyExamplesSlug to keep behavior DRY and consistent.frameworks/motia/docs/content/docs/development-guide/motia-package-exports.mdx (1)
29-31: Clarify theapiexport status.The PR summary mentions migrating HTTP trigger naming from
apitohttp. Line 31 lists bothhttpandapias runtime primitives. Consider adding a note indicating whetherapiis deprecated/legacy or intentionally kept for backwards compatibility.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/content/docs/development-guide/motia-package-exports.mdx` around lines 29 - 31, Update the documentation where the runtime primitives are listed (the exports `http` and `api` in the exports list) to clarify the status of `api`: explicitly state whether `api` is deprecated/legacy or intentionally retained for backward compatibility, and if deprecated add a short migration note instructing users to use `http` instead and show the recommended mapping; ensure the text mentions the exact export names `api` and `http` so readers can find them quickly and, if applicable, include a deprecation badge or parenthetical like “(deprecated, use `http`)”.frameworks/motia/docs/public/llm-docs/development-guide/authentication.mdx.md (1)
105-114: Consider noting header case-sensitivity and Bearer token format.The example accesses
request.headers['authorization']directly and splits on space assuming "Bearer token" format. HTTP headers are case-insensitive by spec, but object key access is case-sensitive. Consider adding a note about header normalization or using a case-insensitive lookup pattern in production code.📝 Example improvement for robustness
export async function requireAuth(request: ApiRequest<any>): Promise<TokenData> { - const authHeader = request.headers['authorization'] as string + // Headers may be lowercase or mixed-case depending on framework normalization + const authHeader = (request.headers['authorization'] ?? request.headers['Authorization']) as string if (!authHeader) { throw new HttpError(401, 'Missing authorization header') } - const [, token] = authHeader.split(' ') + const [scheme, token] = authHeader.split(' ') + if (scheme?.toLowerCase() !== 'bearer' || !token) { + throw new HttpError(401, 'Invalid authorization header format') + } return jwt.verify(token, process.env.JWT_SECRET!) as TokenData }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/development-guide/authentication.mdx.md` around lines 105 - 114, The requireAuth function reads request.headers['authorization'] and assumes a "Bearer token" format which is brittle because header keys are case-sensitive in the object and the value may not be "Bearer <token>"; update requireAuth to perform a case-insensitive lookup for the authorization header (e.g., check for 'authorization' and fallback to other casings or iterate headers keys) and validate the scheme by splitting and confirming the first part equals 'Bearer' (case-insensitive) before using jwt.verify; if the header is not found or the scheme/token are invalid, throw the same HttpError(401, ...) to preserve behavior.frameworks/motia/docs/lib/source.ts (1)
13-15: Consider exportingisLegacyExamplesSlugfor reuse.This helper function is duplicated in
frameworks/motia/docs/app/docs/[[...slug]]/page.tsx. Consider exporting it from this module to avoid duplication and ensure consistent behavior.♻️ Proposed fix
-function isLegacyExamplesSlug(slug?: string[]) { +export function isLegacyExamplesSlug(slug?: string[]) { return slug?.[0] === 'examples' }Then in
page.tsx:import { baseSource, source, isLegacyExamplesSlug } from '@/lib/source'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/lib/source.ts` around lines 13 - 15, The small helper isLegacyExamplesSlug is duplicated; export it from the source module (add an exported function named isLegacyExamplesSlug in the same module that currently contains it) and remove the duplicate implementation in page.tsx, then import isLegacyExamplesSlug from the source module into page.tsx alongside baseSource/source so the single exported function is reused across both places.frameworks/motia/docs/public/llm-docs/development-guide/state-management.mdx.md (1)
310-336: Avoid teaching get-mutate-set right after the atomic-update guidance.The page just tells readers to prefer
update()over manual get/modify/set, but this payment example still fetches the order, mutates it locally, and writes the whole object back. That undercuts the guidance above and reintroduces the racey pattern the new section is trying to eliminate. Please rewrite this status change withstateManager.update(...), then mirror the same fix in the Python and JavaScript tabs below.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/development-guide/state-management.mdx.md` around lines 310 - 336, The example in the ProcessPayment handler uses the racy get/mutate/set pattern; replace the get + local mutation + stateManager.set in the handler with a single atomic stateManager.update call (e.g., call stateManager.update('orders', orderId, updater) inside the exported handler so the order status is changed to 'paid' atomically), and apply the same replacement in the corresponding Python and JavaScript examples/tabs so all three snippets use stateManager.update instead of get + mutate + set; keep error handling (throwing if order missing) inside the updater or by checking the update result as appropriate.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@frameworks/motia/docs/app/api/search/route.ts`:
- Around line 7-18: The matcher is too broad (uses includes) and removes any URL
containing "/docs/examples"; update isLegacyExamplesUrl to only match the legacy
examples prefix using an anchored prefix check (e.g. use a regex like
^/docs/examples(?:/|$) or String.startsWith('/docs/examples/') ) so it only
returns true when the value begins with that legacy slug; keep
removeLegacyExamples logic the same but call the revised isLegacyExamplesUrl
when checking candidate.url and candidate.path.
- Around line 39-42: When returning the rewritten JSON payload (filteredPayload
from removeLegacyExamples) preserve all original response headers instead of
only Content-Type: create a copy of response.headers (e.g., new
Headers(response.headers) or equivalent), set/override 'Content-Type' to
'application/json' on that headers copy, and pass that headers object into the
new Response along with response.status so ETag, cache, and other headers from
the original response are retained.
In `@frameworks/motia/docs/content/docs/product-showcase/chessarena-ai.mdx`:
- Around line 47-53: Update the Node.js requirement text in the
chessarena-ai.mdx docs: replace the string "Node.js 18+" with "Node.js 22+" so
the prerequisites reflect the current LTS; look for the bullet list containing
"Node.js 18+" (in the product-showcase/chessarena-ai.mdx content) and update
that single line to "Node.js 22+".
In
`@frameworks/motia/docs/public/llm-docs/advanced-features/conditional-triggers.mdx.md`:
- Around line 39-42: The handler currently destructures injected context ({
logger, enqueue }) but other docs use a single ctx parameter and ctx.match()
style; update the export const handler function to accept (input, ctx) instead
of (input, { logger, enqueue }), replace logger calls with ctx.logger.info and
enqueue calls with ctx.enqueue (or use ctx.match() as shown in sibling examples)
so the example aligns with the standalone ctx pattern used in
multi-trigger-steps.mdx.md and step-helper.mdx.md.
In
`@frameworks/motia/docs/public/llm-docs/advanced-features/reactive-triggers.mdx.md`:
- Around line 44-54: Update the handler examples to use v1 import-based
logger/enqueue instead of context destructuring: change the import to include
enqueue, logger and Handlers (e.g., import { enqueue, logger, type Handlers, ...
} from 'motia') and modify the handler signature from async (input, { logger,
enqueue }) to async (input); inside the function use the imported logger and
enqueue (referencing the existing handler function named handler and its config
type) to log and enqueue as before.
In `@frameworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.md`:
- Around line 207-208: The Dockerfile RUN line uses "uv pip install --system -r
pyproject.toml", which doesn't resolve transitive dependencies; replace it with
a proper uv command such as "uv pip install --system ." to perform a
system-level install from the project, or use "uv sync --locked" (if you want
project-managed venv + lock-based install) or the compile pipe "uv pip compile
pyproject.toml | uv pip install --system -" for explicit dependency compilation;
update the RUN instruction that contains "uv pip install --system -r
pyproject.toml" accordingly to one of these recommended alternatives.
In `@frameworks/motia/docs/public/llm-docs/deployment-guide/fly.mdx.md`:
- Around line 54-87: The Dockerfile example and accompanying text present a
JavaScript/Bun-only runtime (uses motia build output, oven/bun:1.1-slim, and
iii) but the guide is written generically; update the guide to either scope this
section explicitly to JS-only projects or add a parallel Docker recipe and
runtime notes for Python or mixed projects—mentioning motia build, the
Dockerfile, FROM oven/bun:1.1-slim, iii, and any Python runtime (e.g., FROM
python:3.x or multi-stage with both Bun and Python) and explain needed build
artifacts and install steps for Python dependencies so Python/mixed projects can
follow the flow.
In `@frameworks/motia/docs/public/llm-docs/deployment-guide/railway.mdx.md`:
- Around line 123-160: The Dockerflow and build steps currently assume a
JavaScript-only project (references: motia build, COPY package.json, bun runtime
in the Dockerfile and use of dist/index-production.js), but the runtime image
never installs Python so Python or mixed projects will fail; either mark this
section explicitly as "JavaScript-only" and call out that motia build/COPY
package.json and the bun-based runtime are JS-specific, or add instructions to
support Python/mixed apps (e.g., use a base image that includes Python or
install Python and any required runtime deps in the Dockerfile, adjust
build/copy steps to include Python entry points and artifacts instead of or in
addition to dist/index-production.js, and ensure config.yaml and iii invocation
remain compatible). Addressing one of these two options and updating the text
around the Dockerfile and build steps will prevent readers from following a
JS-only workflow for Python or mixed projects.
In `@frameworks/motia/docs/public/llm-docs/development-guide/cli.mdx.md`:
- Around line 27-29: The page inconsistently references iii-config.yaml vs
config.yaml causing dev scripts to fail; pick one standard (prefer config.yaml)
and update all occurrences: change the scaffold description under the "motia-cli
create [name]" section to say it generates config.yaml, update the later
statement that "bare iii looks for config.yaml", adjust the recommended npm
script example ("dev": "iii") and the workflow example to use iii and iii -c
config.yaml only if keeping a different name, or better, change the workflow to
use iii (no -c) to match config.yaml; ensure all other instances (lines called
out: 55-60, 80-82, 163-171) are updated so filenames and example commands are
consistent.
In `@frameworks/motia/docs/public/llm-docs/development-guide/queue-config.mdx.md`:
- Around line 167-170: The TypeScript example is missing the Handlers type
import so `export const handler: Handlers<typeof config>` will not compile;
update the import line that currently imports `enqueue` to also import the
`Handlers` type (e.g., add `Handlers` to the import specifier) so `Handlers`,
`enqueue`, `handler`, and `config` resolve correctly in this snippet.
In
`@frameworks/motia/docs/public/llm-docs/development-guide/state-management.mdx.md`:
- Around line 239-267: The handler example still imports and types FlowContext
and includes an unused ctx parameter; remove FlowContext from the imports and
drop the ctx parameter and its type from the handler signature (i.e., change
async def handler(request: ApiRequest[Any]) -> ApiResponse[Any]): update any
type hints or signature references accordingly so the example uses the direct
imports enqueue/logger/state_manager and no FlowContext is present.
In `@frameworks/motia/docs/public/llm-docs/index.mdx.md`:
- Around line 9-22: The handler is using the deprecated v0 context pattern by
destructuring enqueue and logger from the second parameter; update to the v1
pattern by removing the second handler argument from the handler signature (keep
export const handler: Handlers<typeof config> = async ({ request }) => ...) and
import the standalone helpers directly from 'motia' (use the exported enqueue
and logger functions instead of extracting them from the context) so calls to
enqueue({ topic: 'user.created', data: request.body }) and logger.info(...) work
with the new v1 API.
---
Outside diff comments:
In `@frameworks/motia/docs/content/docs/development-guide/streams.mdx`:
- Around line 339-349: The stream provider example in AppShell uses the wrong
WebSocket port; update the streamAddress construction inside the AppShell
component (where streamAddress = new URL('ws://localhost:3000').toString()) to
use the stream API port 3112 instead of 3000 so it matches the rest of the docs
and avoids breaking subscriptions when mounting MotiaStreamProvider; ensure the
URL string passed to new URL(...) is changed to 'ws://localhost:3112'.
In `@frameworks/motia/docs/public/llm-docs/api-reference.mdx.md`:
- Around line 349-350: Update the 5-field cron examples to the iii engine's
required 7-field format by adding seconds (and optional year) fields; replace
occurrences like cron('0 9 * * *') with cron('0 0 9 * * * *') and similarly
expand other examples (e.g., any cron('M H D M W') patterns) to the form cron('s
m h D M W Y') so all examples in api-reference.mdx.md use the 7-field format
used by the iii engine.
In `@frameworks/motia/docs/public/llm-docs/deployment-guide/railway.mdx.md`:
- Around line 89-94: The docs set REDIS_PRIVATE_URL but the adapter examples
still reference REDIS_URL, so the private URL is never used; update either the
Railway variable commands to map REDIS_URL to the private endpoint (set
REDIS_URL='${{Redis.REDIS_PRIVATE_URL}}') or change all adapter config/examples
to read REDIS_PRIVATE_URL instead of REDIS_URL; look for occurrences of
REDIS_URL and REDIS_PRIVATE_URL in the file and ensure consistency across the
railway variables block and the YAML/adapter examples so the private URL is
actually consumed.
In
`@frameworks/motia/docs/public/llm-docs/development-guide/project-structure.mdx.md`:
- Around line 323-345: The example mixes old ctx utilities with the new pattern:
update the handler signature to remove the ctx parameter so it matches other v1
handlers (e.g., change async handler(input_data) instead of async
handler(input_data, ctx)), and replace ctx.utils.dates.now().isoformat() with a
stdlib timestamp (e.g., datetime.utcnow().isoformat()) so processed_at uses the
standard library; keep the direct import of enqueue and the rest of the payload
construction (original, processed_at, count) unchanged and ensure you import the
required datetime helper at the top of the snippet.
In `@frameworks/motia/docs/public/llm-docs/development-guide/streams.mdx.md`:
- Around line 339-349: Several examples use inconsistent default WebSocket
addresses (ws://localhost:3000 vs ws://localhost:3112); update the AppShell
component so the streamAddress constant (created via useMemo) uses a single
canonical default (pick one port, e.g., ws://localhost:3112) and apply the same
change to all other examples that set streamAddress or an equivalent default
(lines showing MotiaStreamProvider, AppShell, and any other snippets creating
streamAddress/useMemo) so every example uses the same default WebSocket URL or
includes a consistent proxy note.
In `@frameworks/motia/docs/public/llm-docs/video-showcase.mdx.md`:
- Line 3: Update the frontmatter "description" field in the file's metadata (the
description key shown in video-showcase.mdx.md) so it reflects the archived
state instead of promising active video demos — replace the current "Watch Motia
in action through our video demonstrations and tutorials" text with a concise
archived-note (e.g., indicating demos are removed/unavailable or this page is
archived) so search/LLM snippets and the page header match the archived notice.
---
Minor comments:
In `@frameworks/motia/docs/content/docs/concepts/overview.mdx`:
- Line 25: Update the module list entry for the "**iii**" row in overview.mdx to
use the v1 terminology: replace the word "API" with "HTTP" so the line reads
"The runtime engine that runs infrastructure modules (queue, state, stream,
cron, HTTP, observability)"; locate the string containing "**iii**" and modify
only that token to maintain consistency with updated docs vocabulary.
In
`@frameworks/motia/docs/public/llm-docs/advanced-features/multi-language.mdx.md`:
- Around line 12-28: The fenced ASCII-art diagram block is unlabeled which
triggers MD040; update the code fence that wraps the diagram (the ASCII art
starting with the box "iii Engine" and ending with the bottom box) to include a
language tag (e.g., add "text" after the opening triple backticks) so the block
is explicitly labeled and the MD040 warning is resolved.
In `@frameworks/motia/docs/public/llm-docs/concepts/iii-engine.mdx.md`:
- Around line 10-33: The ASCII architecture diagram code fence is missing a
language identifier (causing MD040); update the opening triple-backtick in the
diagram block to include a language (e.g. use "text") so it reads ```text and
leave the diagram contents unchanged—look for the ASCII box diagram in the iii
Engine section and modify its opening fence accordingly.
In `@frameworks/motia/docs/public/llm-docs/concepts/overview.mdx.md`:
- Around line 6-8: The JSX-style comment block around the video (the commented
video block using {/* ... */}) is triggering markdownlint MD037; replace that
JSX comment wrapper with an HTML comment instead (wrap the entire
<video>...</video> block in <!-- ... -->) or alternatively put the block inside
a fenced code block so the markdown parser won't treat the markup as emphasis;
update the commented video block accordingly to use <!-- ... --> (or a ```html
fenced block) so markdownlint no longer flags it.
In `@frameworks/motia/docs/public/llm-docs/concepts/steps.mdx.md`:
- Around line 6-8: Remove the HTML comment wrapper around the JSX video block
and convert that snippet into a proper fenced code block (use ```html or ```jsx)
so it no longer contains bare HTML comments (addresses MD037), and for the cron
diagram fenced block (the block starting around the cron diagram) add an
explicit fence language (e.g., ```text or ```cron) and normalize
spacing/indentation so the fenced block is clean (addresses MD040); locate the
commented video snippet and the cron diagram fenced block by the video JSX
fragment and the cron diagram content and apply these two changes.
In `@frameworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.md`:
- Around line 20-24: The fenced code block that shows the dist tree (starting
with the line "dist/") lacks a language identifier which triggers markdownlint
MD040; update the fenced block delimiter from ``` to ```text (or another
appropriate label) so the block becomes a labeled code fence (e.g., ```text)
surrounding the existing lines "dist/", "├── index-production.js", and "└──
index-production.js.map" in the docker.mdx.md content.
In `@frameworks/motia/docs/public/llm-docs/deployment-guide/self-hosted.mdx.md`:
- Around line 17-21: The code block showing the dist/ directory tree uses an
unlabeled fence; add a language specifier (e.g., "text") to the opening triple
backticks for the block that contains "dist/" so markdownlint MD040 is
satisfied; update the fenced block that begins with ``` and contains the tree
lines ("dist/", "├── index-production.js", "└── index-production.js.map") to
start with ```text instead of just ``` to label the code block.
In
`@frameworks/motia/docs/public/llm-docs/development-guide/observability.mdx.md`:
- Line 173: The MD046 lint error is caused by an inconsistent code-fence at the
snippet starting with ```typescript; fix it by converting the block to the
repository’s fenced code-block style: ensure you have a proper opening fence
with the language tag "typescript", a matching closing fence of the same
backticks, and a blank line before and after the fenced block; locate the
offending fence (the token ```typescript) and add the missing/consistent closing
``` and surrounding blank lines so the code block complies with markdownlint
rules.
In
`@frameworks/motia/docs/public/llm-docs/getting-started/handler-migration-guide.mdx.md`:
- Around line 668-676: The checklist and examples are inconsistent about the
handler signature: update either the checklist or the examples so they match;
specifically ensure the handler definition shown in examples uses the same
signature as the checklist (handler(request: ApiRequest[Any], ctx:
FlowContext[Any]) -> ApiResponse[Any]) or change the checklist to the single-arg
form (handler(request: ApiRequest[Any]) -> ApiResponse[Any]); locate the example
`handler` function and the checklist line referring to `ApiRequest`,
`FlowContext`, and `ApiResponse` and make them identical, and also ensure any
SSE examples reference `MotiaHttpArgs` consistently where mentioned.
In
`@frameworks/motia/docs/public/llm-docs/getting-started/migration-guide.mdx.md`:
- Around line 601-611: The fenced cron diagram block currently has no language
identifier which triggers MD040; update the fenced code block that begins with
the cron diagram (the block containing "┌──────────── second (0-59)" and ending
with "* * * * * * *") to include a language token (e.g., add "text" after the
opening backticks so it becomes ```text) so the block is treated as a code fence
and MD040 is satisfied.
In `@frameworks/motia/docs/public/llm-docs/product-showcase/chessarena-ai.mdx.md`:
- Around line 36-39: The repo structure bullet for `types/` is missing the word
"for"; update the markdown list entry containing the `types/` token so it
matches the other bullets' style (e.g., change the line with `types/ shared
types` to include "for" so it reads like the other entries).
---
Nitpick comments:
In `@frameworks/motia/docs/app/docs/`[[...slug]]/page.tsx:
- Around line 80-86: generateStaticParams performs an extra filter that removes
legacy example slugs after calling source.generateParams(), but
source.generateParams() already applies that filtering in production; remove the
redundant params.filter(...) call (the predicate using isLegacyExamplesSlug) and
simply return params (keeping the early return when !isProduction) so
generateStaticParams delegates filtering to source.generateParams() and
preserves existing behavior.
- Around line 18-20: Remove the duplicate isLegacyExamplesSlug function from the
page component and instead import the shared isLegacyExamplesSlug helper from
the module where it lives; update that module to export isLegacyExamplesSlug if
it isn’t exported yet, then replace the local function in page.tsx with an
import statement that references the shared isLegacyExamplesSlug to keep
behavior DRY and consistent.
In `@frameworks/motia/docs/content/docs/api-reference.mdx`:
- Around line 838-841: Replace the ambiguous placeholder in the example object
so readers don't interpret "items: [...]" as literal syntax; update the `data`
object (containing `orderId` and `messageGroupId`) to use an explicit items
placeholder such as `items: ['item1', 'item2']` or `items: someItemsArray` so
the `data` example is clear and valid-looking.
In
`@frameworks/motia/docs/content/docs/development-guide/motia-package-exports.mdx`:
- Around line 29-31: Update the documentation where the runtime primitives are
listed (the exports `http` and `api` in the exports list) to clarify the status
of `api`: explicitly state whether `api` is deprecated/legacy or intentionally
retained for backward compatibility, and if deprecated add a short migration
note instructing users to use `http` instead and show the recommended mapping;
ensure the text mentions the exact export names `api` and `http` so readers can
find them quickly and, if applicable, include a deprecation badge or
parenthetical like “(deprecated, use `http`)”.
In `@frameworks/motia/docs/content/docs/product-showcase/chessarena-ai.mdx`:
- Around line 20-21: Replace ambiguous occurrences of the term "API" (and
lowercase "api") in the prose lines (e.g., the bullet "Event-driven
orchestration across API and worker logic" and the similar text around lines
36–37) with clearer phrasing such as "HTTP entrypoints/services" while leaving
any literal folder or trigger names (folder names like "api" or code references)
unchanged; update only the descriptive wording in the Markdown content of
chessarena-ai.mdx so readers don’t confuse it with legacy `api` trigger naming.
In `@frameworks/motia/docs/lib/source.ts`:
- Around line 13-15: The small helper isLegacyExamplesSlug is duplicated; export
it from the source module (add an exported function named isLegacyExamplesSlug
in the same module that currently contains it) and remove the duplicate
implementation in page.tsx, then import isLegacyExamplesSlug from the source
module into page.tsx alongside baseSource/source so the single exported function
is reused across both places.
In
`@frameworks/motia/docs/public/llm-docs/development-guide/authentication.mdx.md`:
- Around line 105-114: The requireAuth function reads
request.headers['authorization'] and assumes a "Bearer token" format which is
brittle because header keys are case-sensitive in the object and the value may
not be "Bearer <token>"; update requireAuth to perform a case-insensitive lookup
for the authorization header (e.g., check for 'authorization' and fallback to
other casings or iterate headers keys) and validate the scheme by splitting and
confirming the first part equals 'Bearer' (case-insensitive) before using
jwt.verify; if the header is not found or the scheme/token are invalid, throw
the same HttpError(401, ...) to preserve behavior.
In
`@frameworks/motia/docs/public/llm-docs/development-guide/motia-package-exports.mdx.md`:
- Line 31: Update the export list to clarify the status of the `api` export:
either mark `api` explicitly as a legacy alias for `http` (e.g., append "(legacy
alias for `http` — kept for backward compatibility)") or remove `api` entirely
if deprecated in v1.x; ensure the `http` export remains the primary name and add
a short note nearby stating the decision so readers know whether `api` is
supported or removed.
In
`@frameworks/motia/docs/public/llm-docs/development-guide/state-management.mdx.md`:
- Around line 310-336: The example in the ProcessPayment handler uses the racy
get/mutate/set pattern; replace the get + local mutation + stateManager.set in
the handler with a single atomic stateManager.update call (e.g., call
stateManager.update('orders', orderId, updater) inside the exported handler so
the order status is changed to 'paid' atomically), and apply the same
replacement in the corresponding Python and JavaScript examples/tabs so all
three snippets use stateManager.update instead of get + mutate + set; keep error
handling (throwing if order missing) inside the updater or by checking the
update result as appropriate.
In `@frameworks/motia/docs/public/llm-docs/product-showcase/chessarena-ai.mdx.md`:
- Line 47: Replace the time-relative phrase "Based on the latest README and
package scripts" with a neutral, non-time-sensitive alternative such as
"According to the project README and package scripts" in the product-showcase
text; locate the exact sentence in the content (the string "Based on the latest
README and package scripts") and update it to the suggested neutral wording to
avoid staleness in static docs.
frameworks/motia/docs/content/docs/product-showcase/chessarena-ai.mdx
Outdated
Show resolved
Hide resolved
frameworks/motia/docs/public/llm-docs/advanced-features/conditional-triggers.mdx.md
Outdated
Show resolved
Hide resolved
frameworks/motia/docs/public/llm-docs/advanced-features/reactive-triggers.mdx.md
Outdated
Show resolved
Hide resolved
frameworks/motia/docs/public/llm-docs/deployment-guide/railway.mdx.md
Outdated
Show resolved
Hide resolved
frameworks/motia/docs/public/llm-docs/development-guide/cli.mdx.md
Outdated
Show resolved
Hide resolved
frameworks/motia/docs/public/llm-docs/development-guide/queue-config.mdx.md
Outdated
Show resolved
Hide resolved
frameworks/motia/docs/public/llm-docs/development-guide/state-management.mdx.md
Outdated
Show resolved
Hide resolved
Address validated review feedback across docs examples, deployment guides, trigger snippets, and search filtering, then regenerate public LLM docs from source so generated artifacts stay in sync. Made-with: Cursor
Adjust quick-start instructions to reference iii-config.yaml with an explicit -c flag for engine startup. Made-with: Cursor
Drop the commented video block from overview docs to keep MDX syntax valid in production builds, and refresh generated LLM artifacts. Made-with: Cursor
Contributor
There was a problem hiding this comment.
Actionable comments posted: 12
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
frameworks/motia/docs/content/docs/getting-started/handler-migration-guide.mdx (1)
188-196:⚠️ Potential issue | 🟡 MinorUndefined variables in code example.
The code snippet references
todoIdandnewTodowithout declaring them. For clarity, either declare these variables or add a comment indicating they come from outer scope/prior code.Suggested fix
export const handler: Handlers<typeof config> = async ({ request }) => { + const todoId = request.body.id // or however todoId is obtained + const newTodo = { ...request.body } const todo = await todoStream.get('inbox', todoId) await todoStream.set('inbox', todoId, newTodo)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/content/docs/getting-started/handler-migration-guide.mdx` around lines 188 - 196, The example handler exports an async function using undefined identifiers todoId and newTodo, which confuses readers; update the example around export const handler: Handlers<typeof config> to either declare todoId and newTodo (e.g., const todoId = '...'; const newTodo = {...}) before using them or add a clear inline comment above the todoStream calls explaining that todoId and newTodo are placeholders coming from outer scope/request payload; ensure the references appear before calling todoStream.get/set/delete/update so the snippet is self-contained and compiles.frameworks/motia/docs/public/llm-docs/development-guide/project-structure.mdx.md (1)
447-449:⚠️ Potential issue | 🟡 MinorInconsistent handler signature in troubleshooting example.
This example uses the old
(input, ctx)signature, but the v1 migration removesctxwhen onlystate,enqueue,logger, orstreamswere used. For consistency with other examples in this file (lines 307, 336, 364), update to the new pattern.Suggested fix
-export const handler: Handlers<typeof config> = async (input, ctx) => { +export const handler: Handlers<typeof config> = async (input) => { // Motia will discover and register this step }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/development-guide/project-structure.mdx.md` around lines 447 - 449, The handler example uses the old two-argument signature (input, ctx); update export const handler: Handlers<typeof config> to the v1 pattern by removing the second ctx parameter and using the single-argument form used elsewhere (destructure any needed fields like state, enqueue, logger, streams from the single parameter). Ensure the function signature for handler matches other examples in this file (remove ctx) and adjust any internal references to use the destructured fields instead.frameworks/motia/docs/public/llm-docs/development-guide/middleware.mdx.md (1)
182-182:⚠️ Potential issue | 🟡 MinorUpdate stale
reqterminology torequest.Line 182 still says middleware attaches data to
req, but all updated examples userequest(orcontextin Python). This can confuse migration readers.Suggested doc fix
-Middleware can attach data to the `req` object, making it available to your handler. This is perfect for authentication - verify the user once in middleware, then use their details in the handler. +Middleware can attach data to the `request` object (or `context` in Python), making it available to your handler. This is perfect for authentication - verify the user once in middleware, then use their details in the handler.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/development-guide/middleware.mdx.md` at line 182, Update the stale terminology in the sentence that currently says "req": replace "req" with "request" so the line reads that middleware can attach data to the `request` object, matching the rest of the examples; also mention `context` as the Python equivalent if present. Locate the sentence containing the `req` literal and change it to `request` (and optionally add "(or `context` in Python)") so terminology is consistent across examples.
🧹 Nitpick comments (10)
frameworks/motia/docs/public/llm-docs/development-guide/cli.mdx.md (1)
12-12: Polish compound adjective on Line 12.Use “mixed-language templates” for cleaner grammar in this context.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/development-guide/cli.mdx.md` at line 12, Update the phrase "mixed language templates" to the hyphenated form "mixed-language templates" in the motia-cli description (the sentence starting "The motia-cli scaffolds new Motia projects...") so the compound adjective is grammatically correct; search for the exact string "mixed language templates" in the file and replace it with "mixed-language templates".frameworks/motia/docs/public/llm-docs/advanced-features/conditional-triggers.mdx.md (2)
49-73: Make the HTTP example self-contained for copy/paste.This snippet relies on
zandStepConfigfrom prior context. For generated LLM/public docs, a standalone example is easier to use and less error-prone.Suggested doc tweak
```typescript +import type { StepConfig } from 'motia' +import { z } from 'zod' + const verifiedOrderSchema = z.object({ orderId: z.string(), amount: z.number(), user: z.object({ verified: z.boolean() }), })🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/advanced-features/conditional-triggers.mdx.md` around lines 49 - 73, The snippet is not self-contained because it uses z and StepConfig without imports; update the example so it can be copy/pasted by adding the required imports (e.g., import { z } from 'zod' and import type { StepConfig } from 'motia') at the top, then keep the verifiedOrderSchema and the exported config (name: 'VerifiedUserEndpoint', triggers array with condition using input.body.user?.verified). Ensure the file-level exports and the as const satisfies StepConfig remain intact so the example compiles standalone.
79-99:taskSchemais undefined in this snippet.Please define
taskSchema(or add a short note that it is reused from an earlier example) so the sample is executable without guesswork.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/advanced-features/conditional-triggers.mdx.md` around lines 79 - 99, The snippet references taskSchema but never defines it, causing the example to be non-executable; either add a short inline definition of taskSchema (e.g., a minimal schema used by the triggers and bodySchema) or add a clear comment that it’s reused from the earlier example and link to that definition. Update the exported config block (export const config = { name: 'SmartProcessor', ... } as const satisfies StepConfig) to reference the defined taskSchema symbol or replace taskSchema with the documented reference so readers can run the sample without guessing.frameworks/motia/docs/content/docs/development-guide/motia-package-exports.mdx (2)
57-60:motia/buildsection is too abstract without examples.Consider listing a few common exports (or linking a canonical API reference) so this section is immediately usable.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/content/docs/development-guide/motia-package-exports.mdx` around lines 57 - 60, The `motia/build` section is too abstract—add concrete examples and/or a canonical reference: show 2–3 common named exports (e.g., export names like buildConfig, createBuildPipeline, resolveBuildTarget) with brief one-line descriptions and example import snippets using `motia/build`, or add a direct link to the API reference for the full export list; update the `motia/build` paragraph to include these examples or the link so readers can immediately use the subpath in build workflows.
42-48: Add an explicit instability warning for internal exports.This section lists internals but doesn’t warn about stability expectations. A one-line caveat would prevent accidental coupling.
✍️ Suggested doc tweak
### Initialization and internals - `initIII`, `getInstance` - `setupStepEndpoint` - `generateStepId` - `Motia` + +These are internal-facing exports and may change; avoid using them in app code unless explicitly documented as stable.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/content/docs/development-guide/motia-package-exports.mdx` around lines 42 - 48, The docs list internal exports (initIII, getInstance, setupStepEndpoint, generateStepId, Motia) without warning they are unstable; add a one-line caveat directly above or below the "Initialization and internals" heading stating that these exports are internal, subject to change, and should not be relied on by external consumers, so readers are warned against coupling to initIII, getInstance, setupStepEndpoint, generateStepId, or Motia.frameworks/motia/docs/public/llm-docs/community-resources.mdx.md (1)
175-175: Consider alternative wording for clarity.The phrase "make our docs better" could be rephrased to "improve our documentation" or "enhance our documentation" for a slightly more formal tone. However, the current wording is clear and maintains a friendly, community-oriented voice that may be intentional for this context.
As per coding guidelines, static analysis suggests improving the wording at this line (MAKE_STYLE_BETTER).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/community-resources.mdx.md` at line 175, Replace the informal trailing phrase in the bullet "**Improve documentation** - Help make our docs better" with a more polished alternative; locate the exact string "**Improve documentation** - Help make our docs better" and update it to something like "**Improve documentation** - Improve our documentation" or "**Improve documentation** - Enhance our documentation" to satisfy the MAKE_STYLE_BETTER suggestion while preserving the bullet's intent and tone.frameworks/motia/docs/public/llm-docs/concepts/overview.mdx.md (1)
177-177: Use one canonical config filename to avoid migration confusion.Line 177 / Line 258 / Line 280 / Line 309 use
config.yaml, but the PR objective calls out explicitiii-config.yamlusage in quick-start. Keeping one canonical name across docs will reduce onboarding errors.Also applies to: 258-260, 280-280, 309-309
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/concepts/overview.mdx.md` at line 177, Several doc instances use different config filenames; standardize on one canonical name (choose either "config.yaml" or "iii-config.yaml") and update all occurrences accordingly: replace the <File name="config.yaml" /> tag and any textual references in overview.mdx.md (including the quick-start mention of "iii-config.yaml") so every reference (lines around 177, 258–260, 280, 309) uses the chosen canonical filename; ensure examples, code blocks, and the <File name="..."/> tag are consistent.frameworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.md (1)
38-38: Consider hardening the iii install step with version pinning.The Docker examples use
curl ... | shwithout verification. While full checksum verification isn't currently provided by the iii project, the install script supports version pinning via theVERSIONenvironment variable. Update the documentation to show pinning to a specific version (e.g.,RUN VERSION=<pinned-version> curl -fsSL https://install.iii.dev/iii/main/install.sh | sh) for better reproducibility and supply-chain guarantees in production deployments.Also applies to: 195-195
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.md` at line 38, Update the Dockerfile example that runs the iii installer to show version pinning: replace the bare "RUN curl -fsSL https://install.iii.dev/iii/main/install.sh | sh" example with one that sets VERSION to a specific release (e.g., "VERSION=<pinned-version>") before invoking the installer, and add a short note urging users to pin to a known release for reproducibility; make the same change where the same command appears later (the occurrence referenced at line 195) so both examples demonstrate VERSION-based pinning.frameworks/motia/docs/public/llm-docs/development-guide/streams.mdx.md (1)
486-498: Python ephemeral events example missing stream import/creation.The Python example uses
chat_message_streamwithout showing how it's imported or created, unlike the TS/JS tabs which show the import statements. This could confuse readers.📝 Suggested improvement
```python +from chat_messages_stream import chat_message_stream + await chat_message_stream.send( {"groupId": channel_id}, {"type": "typing", "data": {"userId": "user-123", "isTyping": True}} )🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/development-guide/streams.mdx.md` around lines 486 - 498, The Python snippet shows calls to chat_message_stream.send but doesn't show how chat_message_stream is created/imported; update the Python tab to include a brief import or creation line for chat_message_stream (e.g., import from the module that exports it or instantiate the ChatMessageStream client) so readers can run the example—refer to chat_message_stream and its send method to place the import/initialization immediately above the existing await chat_message_stream.send calls.frameworks/motia/docs/public/llm-docs/development-guide/middleware.mdx.md (1)
35-35: Resolve markdownlint MD046 warnings for code block style.These lines are currently flagged as “Expected: fenced; Actual: indented.” Converting those code blocks to fenced style consistently will keep docs lint-clean and prevent noisy regenerated artifacts.
Also applies to: 84-84, 170-170, 221-221, 240-240, 266-266, 286-286, 306-306
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/public/llm-docs/development-guide/middleware.mdx.md` at line 35, Several code blocks (e.g., the one defining authMiddleware: ApiMiddleware) are using indented style and triggering markdownlint MD046; replace each indented code block (including occurrences around the authMiddleware declaration and the other reported lines) with fenced code blocks using triple backticks and an appropriate language tag (e.g., ```ts or ```js) so the blocks are consistently fenced and lint-clean; ensure you keep the exact code content and indentation inside the fences and update all listed occurrences (lines around authMiddleware plus the other mentioned blocks) to the fenced style.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@frameworks/motia/docs/content/docs/advanced-features/conditional-triggers.mdx`:
- Around line 39-42: Replace deprecated ctx.logger and ctx.enqueue usage in the
handler by importing and using the standalone utilities: add "{ logger, enqueue
} from 'motia'" to the existing imports and change ctx.logger.info(...) to
logger.info(...) and await ctx.enqueue(...) to await enqueue(...). Update the
handler function (export const handler) accordingly so it calls logger.info with
the same message and metadata and calls enqueue with the same topic and data
payload.
In `@frameworks/motia/docs/content/docs/api-reference.mdx`:
- Around line 349-350: The cron examples use 7-field expressions like cron('0 0
9 * * * *') but Motia v1 only supports the 5-field format; update each
cron('...') call to the 5-field form by removing the leading seconds field and
the trailing year field (e.g., convert cron('0 0 9 * * * *') to cron('0 9 * *
*')), ensuring every cron(...) occurrence in the document is changed
accordingly.
In `@frameworks/motia/docs/content/docs/concepts/steps.mdx`:
- Around line 6-10: The <video> block is currently inside a fenced ```html code
fence so it renders as code; remove the opening ```html and closing ``` fence so
the raw <video> and nested <source> elements are placed directly in the MDX
document (ensure the <video> ... </video> tags remain unchanged and that MDX
allows raw HTML in this file).
In `@frameworks/motia/docs/content/docs/development-guide/project-structure.mdx`:
- Line 323: Replace usages of the deprecated datetime.utcnow() with a
timezone-aware alternative: import timezone and use datetime.now(timezone.utc)
instead; update the import line (currently "from datetime import datetime") to
include timezone (e.g., "from datetime import datetime, timezone") and change
any calls to datetime.utcnow() (references in this file at occurrences around
lines with datetime.utcnow()) to datetime.now(timezone.utc) so timestamps are
UTC-aware.
In `@frameworks/motia/docs/public/llm-docs/api-reference.mdx.md`:
- Line 1147: The example uses chat_messages_stream.getGroup which doesn't match
the Python SDK naming; change that call to the snake_case method
chat_messages_stream.get_group and await its result so it matches the defined
function get_group in motia.streams; update the example line to call await
chat_messages_stream.get_group("room-123") so the docs reflect the actual Python
API.
In `@frameworks/motia/docs/public/llm-docs/concepts/overview.mdx.md`:
- Line 20: The example uses state.set(...)/state.get(...) but the module is
imported as stateManager; update the example to call stateManager.set(...) and
stateManager.get(...) instead so it matches the canonical v1 API and the import
(`stateManager`) used at the top; locate the snippet that currently calls
state.set / state.get and replace those calls with stateManager.set and
stateManager.get respectively (leave the import line unchanged).
In `@frameworks/motia/docs/public/llm-docs/concepts/steps.mdx.md`:
- Around line 6-10: The video HTML/JSX block is currently enclosed in a code
fence so it renders as text; remove the surrounding triple-backtick fence and
the "```html" marker and leave the raw <video> ... <source> JSX/HTML markup
(including the className, poster, controls attributes and the <source> tag) so
the video player is rendered in the MDX file; update the fragment containing the
<video> element (the block between the backticks) in the steps.mdx.md content to
be plain JSX/HTML instead of a code block.
- Around line 680-687: Update the Python example to use snake_case instead of
camelCase: replace the import and all uses of stateManager with state_manager in
the Python Tab example (change from "from motia import stateManager" to "from
motia import state_manager" and update stateManager.set / stateManager.get to
state_manager.set / state_manager.get) so the sample matches the project's
Python naming conventions.
In `@frameworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.md`:
- Around line 164-165: Update the wording in the sentence that currently reads
"Make sure you have the pyproject.toml at your project and the steps folder" to
a clearer phrasing such as "Make sure your project includes pyproject.toml and a
steps/ folder", replacing the original sentence and preserving the references to
pyproject.toml and steps/.
- Around line 206-210: The Dockerfile installs the project with the RUN step
invoking "uv pip install --system ." before the local package source declared in
pyproject.toml ("packages = [\"steps\"]") is available, causing install
failures; fix this by moving the COPY steps ./steps line so the steps/ directory
is copied into the image before the RUN pip install step (ensure the COPY
pyproject.toml ./ remains before installation and that the RUN line invoking
"pip install --system ." runs after the COPY steps), so the package source
exists when the installer (the RUN pip install command) executes.
In `@frameworks/motia/docs/public/llm-docs/deployment-guide/self-hosted.mdx.md`:
- Around line 117-118: The curl invocation "RUN curl -fSL
https://install.iii.dev/iii/main/install.sh | sh" uses inconsistent flags
compared to other guides; update it to include the lowercase s (silent) as
"-fsSL" so the Dockerfile matches Railway/Fly docs and suppresses the progress
meter: replace the "curl -fSL" usage with "curl -fsSL" in the INSTALL command
line.
In `@frameworks/motia/docs/public/llm-docs/getting-started/quick-start.mdx.md`:
- Around line 86-93: Update the start command example to explicitly pass the
config file using the -c flag: replace the plain "iii" invocation with "iii -c
iii-config.yaml" and update the surrounding text so it consistently refers to
"iii-config.yaml" (instead of just "config.yaml") when explaining which file
tells the iii engine how to run Motia; ensure the code block under the "Start
the Project" section and any inline mentions match this flag and filename (the
command example and the explanatory sentence are the targets to change).
---
Outside diff comments:
In
`@frameworks/motia/docs/content/docs/getting-started/handler-migration-guide.mdx`:
- Around line 188-196: The example handler exports an async function using
undefined identifiers todoId and newTodo, which confuses readers; update the
example around export const handler: Handlers<typeof config> to either declare
todoId and newTodo (e.g., const todoId = '...'; const newTodo = {...}) before
using them or add a clear inline comment above the todoStream calls explaining
that todoId and newTodo are placeholders coming from outer scope/request
payload; ensure the references appear before calling
todoStream.get/set/delete/update so the snippet is self-contained and compiles.
In `@frameworks/motia/docs/public/llm-docs/development-guide/middleware.mdx.md`:
- Line 182: Update the stale terminology in the sentence that currently says
"req": replace "req" with "request" so the line reads that middleware can attach
data to the `request` object, matching the rest of the examples; also mention
`context` as the Python equivalent if present. Locate the sentence containing
the `req` literal and change it to `request` (and optionally add "(or `context`
in Python)") so terminology is consistent across examples.
In
`@frameworks/motia/docs/public/llm-docs/development-guide/project-structure.mdx.md`:
- Around line 447-449: The handler example uses the old two-argument signature
(input, ctx); update export const handler: Handlers<typeof config> to the v1
pattern by removing the second ctx parameter and using the single-argument form
used elsewhere (destructure any needed fields like state, enqueue, logger,
streams from the single parameter). Ensure the function signature for handler
matches other examples in this file (remove ctx) and adjust any internal
references to use the destructured fields instead.
---
Nitpick comments:
In
`@frameworks/motia/docs/content/docs/development-guide/motia-package-exports.mdx`:
- Around line 57-60: The `motia/build` section is too abstract—add concrete
examples and/or a canonical reference: show 2–3 common named exports (e.g.,
export names like buildConfig, createBuildPipeline, resolveBuildTarget) with
brief one-line descriptions and example import snippets using `motia/build`, or
add a direct link to the API reference for the full export list; update the
`motia/build` paragraph to include these examples or the link so readers can
immediately use the subpath in build workflows.
- Around line 42-48: The docs list internal exports (initIII, getInstance,
setupStepEndpoint, generateStepId, Motia) without warning they are unstable; add
a one-line caveat directly above or below the "Initialization and internals"
heading stating that these exports are internal, subject to change, and should
not be relied on by external consumers, so readers are warned against coupling
to initIII, getInstance, setupStepEndpoint, generateStepId, or Motia.
In
`@frameworks/motia/docs/public/llm-docs/advanced-features/conditional-triggers.mdx.md`:
- Around line 49-73: The snippet is not self-contained because it uses z and
StepConfig without imports; update the example so it can be copy/pasted by
adding the required imports (e.g., import { z } from 'zod' and import type {
StepConfig } from 'motia') at the top, then keep the verifiedOrderSchema and the
exported config (name: 'VerifiedUserEndpoint', triggers array with condition
using input.body.user?.verified). Ensure the file-level exports and the as const
satisfies StepConfig remain intact so the example compiles standalone.
- Around line 79-99: The snippet references taskSchema but never defines it,
causing the example to be non-executable; either add a short inline definition
of taskSchema (e.g., a minimal schema used by the triggers and bodySchema) or
add a clear comment that it’s reused from the earlier example and link to that
definition. Update the exported config block (export const config = { name:
'SmartProcessor', ... } as const satisfies StepConfig) to reference the defined
taskSchema symbol or replace taskSchema with the documented reference so readers
can run the sample without guessing.
In `@frameworks/motia/docs/public/llm-docs/community-resources.mdx.md`:
- Line 175: Replace the informal trailing phrase in the bullet "**Improve
documentation** - Help make our docs better" with a more polished alternative;
locate the exact string "**Improve documentation** - Help make our docs better"
and update it to something like "**Improve documentation** - Improve our
documentation" or "**Improve documentation** - Enhance our documentation" to
satisfy the MAKE_STYLE_BETTER suggestion while preserving the bullet's intent
and tone.
In `@frameworks/motia/docs/public/llm-docs/concepts/overview.mdx.md`:
- Line 177: Several doc instances use different config filenames; standardize on
one canonical name (choose either "config.yaml" or "iii-config.yaml") and update
all occurrences accordingly: replace the <File name="config.yaml" /> tag and any
textual references in overview.mdx.md (including the quick-start mention of
"iii-config.yaml") so every reference (lines around 177, 258–260, 280, 309) uses
the chosen canonical filename; ensure examples, code blocks, and the <File
name="..."/> tag are consistent.
In `@frameworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.md`:
- Line 38: Update the Dockerfile example that runs the iii installer to show
version pinning: replace the bare "RUN curl -fsSL
https://install.iii.dev/iii/main/install.sh | sh" example with one that sets
VERSION to a specific release (e.g., "VERSION=<pinned-version>") before invoking
the installer, and add a short note urging users to pin to a known release for
reproducibility; make the same change where the same command appears later (the
occurrence referenced at line 195) so both examples demonstrate VERSION-based
pinning.
In `@frameworks/motia/docs/public/llm-docs/development-guide/cli.mdx.md`:
- Line 12: Update the phrase "mixed language templates" to the hyphenated form
"mixed-language templates" in the motia-cli description (the sentence starting
"The motia-cli scaffolds new Motia projects...") so the compound adjective is
grammatically correct; search for the exact string "mixed language templates" in
the file and replace it with "mixed-language templates".
In `@frameworks/motia/docs/public/llm-docs/development-guide/middleware.mdx.md`:
- Line 35: Several code blocks (e.g., the one defining authMiddleware:
ApiMiddleware) are using indented style and triggering markdownlint MD046;
replace each indented code block (including occurrences around the
authMiddleware declaration and the other reported lines) with fenced code blocks
using triple backticks and an appropriate language tag (e.g., ```ts or ```js) so
the blocks are consistently fenced and lint-clean; ensure you keep the exact
code content and indentation inside the fences and update all listed occurrences
(lines around authMiddleware plus the other mentioned blocks) to the fenced
style.
In `@frameworks/motia/docs/public/llm-docs/development-guide/streams.mdx.md`:
- Around line 486-498: The Python snippet shows calls to
chat_message_stream.send but doesn't show how chat_message_stream is
created/imported; update the Python tab to include a brief import or creation
line for chat_message_stream (e.g., import from the module that exports it or
instantiate the ChatMessageStream client) so readers can run the example—refer
to chat_message_stream and its send method to place the import/initialization
immediately above the existing await chat_message_stream.send calls.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 118415b7-eca8-4749-a30d-dd5c464cf9b3
📒 Files selected for processing (58)
frameworks/motia/docs/app/api/search/route.tsframeworks/motia/docs/app/docs/[[...slug]]/page.tsxframeworks/motia/docs/content/docs/advanced-features/conditional-triggers.mdxframeworks/motia/docs/content/docs/advanced-features/multi-language.mdxframeworks/motia/docs/content/docs/advanced-features/reactive-triggers.mdxframeworks/motia/docs/content/docs/api-reference.mdxframeworks/motia/docs/content/docs/community-resources.mdxframeworks/motia/docs/content/docs/concepts/iii-engine.mdxframeworks/motia/docs/content/docs/concepts/overview.mdxframeworks/motia/docs/content/docs/concepts/steps.mdxframeworks/motia/docs/content/docs/contribution.mdxframeworks/motia/docs/content/docs/deployment-guide/docker.mdxframeworks/motia/docs/content/docs/deployment-guide/fly.mdxframeworks/motia/docs/content/docs/deployment-guide/railway.mdxframeworks/motia/docs/content/docs/deployment-guide/self-hosted.mdxframeworks/motia/docs/content/docs/development-guide/authentication.mdxframeworks/motia/docs/content/docs/development-guide/cli.mdxframeworks/motia/docs/content/docs/development-guide/middleware.mdxframeworks/motia/docs/content/docs/development-guide/motia-package-exports.mdxframeworks/motia/docs/content/docs/development-guide/project-structure.mdxframeworks/motia/docs/content/docs/development-guide/queue-config.mdxframeworks/motia/docs/content/docs/development-guide/state-management.mdxframeworks/motia/docs/content/docs/development-guide/streams.mdxframeworks/motia/docs/content/docs/getting-started/handler-migration-guide.mdxframeworks/motia/docs/content/docs/getting-started/migration-guide.mdxframeworks/motia/docs/content/docs/getting-started/quick-start.mdxframeworks/motia/docs/content/docs/index.mdxframeworks/motia/docs/content/docs/product-showcase/chessarena-ai.mdxframeworks/motia/docs/content/docs/video-showcase.mdxframeworks/motia/docs/lib/source.tsframeworks/motia/docs/public/llm-docs/advanced-features/conditional-triggers.mdx.mdframeworks/motia/docs/public/llm-docs/advanced-features/multi-language.mdx.mdframeworks/motia/docs/public/llm-docs/advanced-features/reactive-triggers.mdx.mdframeworks/motia/docs/public/llm-docs/api-reference.mdx.mdframeworks/motia/docs/public/llm-docs/community-resources.mdx.mdframeworks/motia/docs/public/llm-docs/concepts/iii-engine.mdx.mdframeworks/motia/docs/public/llm-docs/concepts/overview.mdx.mdframeworks/motia/docs/public/llm-docs/concepts/steps.mdx.mdframeworks/motia/docs/public/llm-docs/contribution.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/fly.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/railway.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/self-hosted.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/authentication.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/cli.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/middleware.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/motia-package-exports.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/project-structure.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/queue-config.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/state-management.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/streams.mdx.mdframeworks/motia/docs/public/llm-docs/getting-started/handler-migration-guide.mdx.mdframeworks/motia/docs/public/llm-docs/getting-started/migration-guide.mdx.mdframeworks/motia/docs/public/llm-docs/getting-started/quick-start.mdx.mdframeworks/motia/docs/public/llm-docs/index.mdx.mdframeworks/motia/docs/public/llm-docs/product-showcase/chessarena-ai.mdx.mdframeworks/motia/docs/public/llm-docs/video-showcase.mdx.mdframeworks/motia/docs/public/llms.txt
✅ Files skipped from review due to trivial changes (4)
- frameworks/motia/docs/content/docs/getting-started/migration-guide.mdx
- frameworks/motia/docs/content/docs/advanced-features/multi-language.mdx
- frameworks/motia/docs/public/llm-docs/advanced-features/reactive-triggers.mdx.md
- frameworks/motia/docs/content/docs/concepts/iii-engine.mdx
🚧 Files skipped from review as they are similar to previous changes (5)
- frameworks/motia/docs/public/llm-docs/development-guide/motia-package-exports.mdx.md
- frameworks/motia/docs/public/llm-docs/advanced-features/multi-language.mdx.md
- frameworks/motia/docs/public/llm-docs/product-showcase/chessarena-ai.mdx.md
- frameworks/motia/docs/public/llm-docs/concepts/iii-engine.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/queue-config.mdx.md
frameworks/motia/docs/content/docs/advanced-features/conditional-triggers.mdx
Outdated
Show resolved
Hide resolved
Comment on lines
+349
to
350
| cron('0 0 9 * * * *'), | ||
| ], |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
In Motia v1 cron triggers, which cron expression formats are officially supported: 5-field, 6-field (with seconds), and/or 7-field (with year)?
💡 Result:
In Motia v1 cron triggers, only the standard 5-field cron expression format (minute, hour, day of month, month, day of week) is officially supported. There is no evidence of support for 6-field (with seconds) or 7-field (with year) formats in the official documentation or examples.
Citations:
- 1: https://motia-dev-website.vercel.app/docs/concepts/steps/cron
- 2: https://motia.dev/docs/concepts/steps/cron
- 3: https://www.motia.dev/docs/development-guide/state-management
- 4: https://blog.motia.dev/build-an-email-marketing-system-with-motia-and-appwrite/
- 5: https://www.motia.dev/docs/api-reference
- 6: https://motia.dev/docs/examples/uptime-discord-monitor
- 7: https://www.motia.dev/
- 8: https://www.motia.dev
- 9: https://motia.dev/docs
Fix cron expressions: Motia v1 only supports 5-field format, not 7-field.
All cron examples in this file use 7-field expressions (e.g., '0 0 9 * * * *'), but Motia v1 officially supports only the standard 5-field format (minute, hour, day of month, month, day of week). Remove the trailing * * (seconds and year fields) from all cron examples to match the supported format.
Affected lines: 349–350, 369–370, 387–388, 418–419, 437–438, 653–654, 729–730.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@frameworks/motia/docs/content/docs/api-reference.mdx` around lines 349 - 350,
The cron examples use 7-field expressions like cron('0 0 9 * * * *') but Motia
v1 only supports the 5-field format; update each cron('...') call to the 5-field
form by removing the leading seconds field and the trailing year field (e.g.,
convert cron('0 0 9 * * * *') to cron('0 9 * * *')), ensuring every cron(...)
occurrence in the document is changed accordingly.
frameworks/motia/docs/content/docs/development-guide/project-structure.mdx
Outdated
Show resolved
Hide resolved
frameworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.md
Outdated
Show resolved
Hide resolved
frameworks/motia/docs/public/llm-docs/deployment-guide/docker.mdx.md
Outdated
Show resolved
Hide resolved
frameworks/motia/docs/public/llm-docs/deployment-guide/self-hosted.mdx.md
Outdated
Show resolved
Hide resolved
frameworks/motia/docs/public/llm-docs/getting-started/quick-start.mdx.md
Outdated
Show resolved
Hide resolved
…rtifacts - conditional-triggers: replace ctx.logger/ctx.enqueue with standalone imports (v1 API) - steps: unwrap <video> from code fence so it renders as MDX - overview: fix state.set/state.get → stateManager.set/stateManager.get - steps: fix Python stateManager → state_manager (snake_case) - api-reference: fix Python getGroup → get_group (snake_case) - project-structure: datetime.utcnow() → datetime.now(timezone.utc) - docker: fix Dockerfile COPY order (steps must be present before uv install) - docker: improve Python section prose - self-hosted: curl -fSL → -fsSL (consistent with other guides) - handler-migration-guide: add placeholder comment for undefined todoId/newTodo - motia-package-exports: add internal caveat and motia/build context - Regenerate all public/llm-docs from updated sources Made-with: Cursor
These files are auto-generated by `prepare-docs` which runs as part of `next build` on Vercel. No need to track them in the repo. Made-with: Cursor
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
frameworks/motia/docs/content/docs/api-reference.mdx (1)
838-859:⚠️ Potential issue | 🟡 MinorKeep enqueue payload examples consistent across language tabs.
TypeScript/JavaScript now use concrete
itemsvalues, but the Python tab still shows a placeholder list ([...]at Line 878). This creates avoidable schema ambiguity.Proposed doc alignment
await enqueue({ "topic": "order.processing", - "data": {"order_id": "123", "items": [...]}, + "data": {"order_id": "123", "items": ["item1", "item2"]}, "messageGroupId": "user-456" })🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@frameworks/motia/docs/content/docs/api-reference.mdx` around lines 838 - 859, The Python example in the docs needs to match the concrete payload used in the TypeScript/JavaScript tabs: update the Python enqueue/publish example that currently shows items as [...] to use concrete values like ['item1', 'item2'], include the same topic values ('order.created' / 'order.processing') and show messageGroupId for the FIFO example; locate the example around the enqueue/publish usage (symbol: enqueue) and the FIFO note (messageGroupId) and make the payloads consistent across language tabs so schema and intent are identical.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@frameworks/motia/docs/content/docs/getting-started/handler-migration-guide.mdx`:
- Around line 670-673: Update the HTTP handler migration guidance to remove any
mention of FlowContext and the non-exported MotiaHttpArgs and instead reflect
the actual http() helper signature: state that handlers should accept (request:
HttpRequest, response: HttpResponse) and return ApiResponse[Any] | None; replace
the earlier suggested handler signature and parameter examples that reference
FlowContext with the correct HttpRequest/HttpResponse contract; update the
import guidance to reference the appropriate exported symbols used by the helper
(e.g., http and the SDK’s HttpRequest/HttpResponse/ApiResponse types) and remove
references to FlowContext and MotiaHttpArgs so the docs match the http()
implementation.
---
Outside diff comments:
In `@frameworks/motia/docs/content/docs/api-reference.mdx`:
- Around line 838-859: The Python example in the docs needs to match the
concrete payload used in the TypeScript/JavaScript tabs: update the Python
enqueue/publish example that currently shows items as [...] to use concrete
values like ['item1', 'item2'], include the same topic values ('order.created' /
'order.processing') and show messageGroupId for the FIFO example; locate the
example around the enqueue/publish usage (symbol: enqueue) and the FIFO note
(messageGroupId) and make the payloads consistent across language tabs so schema
and intent are identical.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 37fbcc45-8d85-49e2-8759-bcdf06b9f264
📒 Files selected for processing (52)
frameworks/motia/docs/.gitignoreframeworks/motia/docs/content/docs/advanced-features/conditional-triggers.mdxframeworks/motia/docs/content/docs/api-reference.mdxframeworks/motia/docs/content/docs/concepts/overview.mdxframeworks/motia/docs/content/docs/concepts/steps.mdxframeworks/motia/docs/content/docs/deployment-guide/docker.mdxframeworks/motia/docs/content/docs/deployment-guide/self-hosted.mdxframeworks/motia/docs/content/docs/development-guide/motia-package-exports.mdxframeworks/motia/docs/content/docs/development-guide/project-structure.mdxframeworks/motia/docs/content/docs/getting-started/handler-migration-guide.mdxframeworks/motia/docs/public/llm-docs/ai-development-guide.mdx.mdframeworks/motia/docs/public/llm-docs/api-reference.mdx.mdframeworks/motia/docs/public/llm-docs/community-resources.mdx.mdframeworks/motia/docs/public/llm-docs/concepts/overview.mdx.mdframeworks/motia/docs/public/llm-docs/concepts/steps.mdx.mdframeworks/motia/docs/public/llm-docs/contribution.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/fly.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/getting-started.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/motia-cloud/architecture.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/motia-cloud/continuous-deployment.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/motia-cloud/deployment.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/motia-cloud/faq.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/motia-cloud/features.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/railway.mdx.mdframeworks/motia/docs/public/llm-docs/deployment-guide/self-hosted.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/adapters.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/cli.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/customizing-flows.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/environment-variables.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/flows.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/middleware.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/motia-config.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/observability.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/plugins.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/project-structure.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/queue-config.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/state-management.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/streams.mdx.mdframeworks/motia/docs/public/llm-docs/development-guide/testing.mdx.mdframeworks/motia/docs/public/llm-docs/getting-started/build-your-first-motia-app/ai-agents.mdx.mdframeworks/motia/docs/public/llm-docs/getting-started/build-your-first-motia-app/api-endpoints.mdx.mdframeworks/motia/docs/public/llm-docs/getting-started/build-your-first-motia-app/background-jobs.mdx.mdframeworks/motia/docs/public/llm-docs/getting-started/build-your-first-motia-app/index.mdx.mdframeworks/motia/docs/public/llm-docs/getting-started/build-your-first-motia-app/streaming-agents.mdx.mdframeworks/motia/docs/public/llm-docs/getting-started/build-your-first-motia-app/workflows.mdx.mdframeworks/motia/docs/public/llm-docs/getting-started/quick-start.mdx.mdframeworks/motia/docs/public/llm-docs/index.mdx.mdframeworks/motia/docs/public/llm-docs/product-showcase/chessarena-ai.mdx.mdframeworks/motia/docs/public/llm-docs/product-showcase/index.mdx.mdframeworks/motia/docs/public/llm-docs/video-showcase.mdx.mdframeworks/motia/docs/public/llm-docs/why-motia.mdx.mdframeworks/motia/docs/public/llms.txt
💤 Files with no reviewable changes (31)
- frameworks/motia/docs/public/llm-docs/development-guide/plugins.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/cli.mdx.md
- frameworks/motia/docs/public/llm-docs/concepts/overview.mdx.md
- frameworks/motia/docs/public/llm-docs/ai-development-guide.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/customizing-flows.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/motia-config.mdx.md
- frameworks/motia/docs/public/llm-docs/deployment-guide/self-hosted.mdx.md
- frameworks/motia/docs/public/llm-docs/deployment-guide/motia-cloud/architecture.mdx.md
- frameworks/motia/docs/public/llm-docs/community-resources.mdx.md
- frameworks/motia/docs/public/llm-docs/deployment-guide/railway.mdx.md
- frameworks/motia/docs/public/llm-docs/deployment-guide/motia-cloud/faq.mdx.md
- frameworks/motia/docs/public/llm-docs/getting-started/build-your-first-motia-app/ai-agents.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/flows.mdx.md
- frameworks/motia/docs/public/llm-docs/deployment-guide/getting-started.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/adapters.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/middleware.mdx.md
- frameworks/motia/docs/public/llm-docs/deployment-guide/motia-cloud/continuous-deployment.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/queue-config.mdx.md
- frameworks/motia/docs/public/llm-docs/deployment-guide/motia-cloud/features.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/testing.mdx.md
- frameworks/motia/docs/public/llm-docs/contribution.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/streams.mdx.md
- frameworks/motia/docs/public/llm-docs/deployment-guide/fly.mdx.md
- frameworks/motia/docs/public/llm-docs/api-reference.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/environment-variables.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/observability.mdx.md
- frameworks/motia/docs/public/llm-docs/getting-started/build-your-first-motia-app/api-endpoints.mdx.md
- frameworks/motia/docs/public/llm-docs/deployment-guide/motia-cloud/deployment.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/project-structure.mdx.md
- frameworks/motia/docs/public/llm-docs/concepts/steps.mdx.md
- frameworks/motia/docs/public/llm-docs/development-guide/state-management.mdx.md
🚧 Files skipped from review as they are similar to previous changes (5)
- frameworks/motia/docs/content/docs/development-guide/project-structure.mdx
- frameworks/motia/docs/content/docs/deployment-guide/self-hosted.mdx
- frameworks/motia/docs/content/docs/advanced-features/conditional-triggers.mdx
- frameworks/motia/docs/content/docs/development-guide/motia-package-exports.mdx
- frameworks/motia/docs/content/docs/deployment-guide/docker.mdx
Comment on lines
+670
to
673
| - Add imports: `from motia import ApiRequest, ApiResponse, http` (and `FlowContext` only if your handler needs `ctx`) | ||
| - Use `http()` helper in trigger definitions | ||
| - Change handler signature to `handler(request: ApiRequest[Any], ctx: FlowContext[Any]) -> ApiResponse[Any]` | ||
| - Change handler signature to `handler(request: ApiRequest[Any]) -> ApiResponse[Any]` (or include `ctx: FlowContext[Any]` when needed) | ||
| - Replace `req.get("body", {})` with `request.body` |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Verify Python SDK HTTP contracts in source docs/repo context.
fd -t f 'types.py|utils.py' sdk/packages/python/iii/src/iii | sort
echo "---- Contract excerpts ----"
rg -n -C3 'class ApiRequest|class ApiResponse|def http\(|FlowContext|HttpRequest, HttpResponse' \
sdk/packages/python/iii/src/iii/types.py \
sdk/packages/python/iii/src/iii/utils.pyRepository: iii-hq/iii
Length of output: 2452
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Read the actual docs file at the specified lines
echo "---- Docs file content (lines 665-680) ----"
sed -n '665,680p' frameworks/motia/docs/content/docs/getting-started/handler-migration-guide.mdx
echo ""
echo "---- Full context around lines 670-673 ----"
sed -n '660,690p' frameworks/motia/docs/content/docs/getting-started/handler-migration-guide.mdxRepository: iii-hq/iii
Length of output: 2138
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Check for MotiaHttpArgs type definition
echo "---- Search for MotiaHttpArgs in SDK ----"
rg -n 'MotiaHttpArgs' sdk/packages/python/iii/src/iii/
echo ""
echo "---- Check FlowContext usage in SDK types ----"
rg -n 'FlowContext' sdk/packages/python/iii/src/iii/types.py sdk/packages/python/iii/src/iii/utils.py
echo ""
echo "---- Full http() function definition ----"
sed -n '15,40p' sdk/packages/python/iii/src/iii/utils.pyRepository: iii-hq/iii
Length of output: 95
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Search for SSE-related types and args
echo "---- Search for SSE/Sse types in SDK ----"
rg -i 'sse|stream' sdk/packages/python/iii/src/iii/types.py sdk/packages/python/iii/src/iii/utils.py | head -20
echo ""
echo "---- Search for all *Args types in SDK ----"
rg 'class \w+Args' sdk/packages/python/iii/src/iii/types.py
echo ""
echo "---- Check what HttpRequest actually is ----"
rg -A10 'class HttpRequest' sdk/packages/python/iii/src/iii/types.py
echo ""
echo "---- Check all class definitions in types.py ----"
rg 'class \w+' sdk/packages/python/iii/src/iii/types.py | grep -v '^\s*#'Repository: iii-hq/iii
Length of output: 1317
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Get size of types.py to determine how to read it
wc -l sdk/packages/python/iii/src/iii/types.py
echo ""
echo "---- All exported classes/types in types.py ----"
rg '^class ' sdk/packages/python/iii/src/iii/types.py | head -30Repository: iii-hq/iii
Length of output: 507
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Read types.py to see available exports and types
cat -n sdk/packages/python/iii/src/iii/types.py | head -200Repository: iii-hq/iii
Length of output: 7173
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Search for FlowContext definition
echo "---- Search for FlowContext ----"
rg -n 'FlowContext|class FlowContext' sdk/packages/python/iii/src/iii/
echo ""
echo "---- Check __init__.py exports ----"
cat -n sdk/packages/python/iii/src/iii/__init__.pyRepository: iii-hq/iii
Length of output: 86
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Look at full utils.py to understand http() helper and any SSE functions
echo "---- Full utils.py content ----"
cat -n sdk/packages/python/iii/src/iii/utils.pyRepository: iii-hq/iii
Length of output: 2721
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Get __init__.py
cat sdk/packages/python/iii/src/iii/__init__.pyRepository: iii-hq/iii
Length of output: 2114
Remove FlowContext references from HTTP handler migration guidance.
Lines 670 and 672 incorrectly suggest FlowContext as an optional parameter for HTTP handlers. The Python SDK's http() helper function (exported in __init__.py and defined in utils.py:15-16) defines the actual contract as:
callback: Callable[[HttpRequest, HttpResponse], Awaitable[ApiResponse[Any] | None]]
This means HTTP handler callbacks accept (request: HttpRequest, response: HttpResponse) and return ApiResponse[Any] | None. FlowContext is not a valid parameter for HTTP handlers in the Python SDK. Additionally, MotiaHttpArgs mentioned in line 678 does not exist as an exported type in the SDK.
The guidance should be corrected to match the actual SDK contract without referencing non-existent types.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@frameworks/motia/docs/content/docs/getting-started/handler-migration-guide.mdx`
around lines 670 - 673, Update the HTTP handler migration guidance to remove any
mention of FlowContext and the non-exported MotiaHttpArgs and instead reflect
the actual http() helper signature: state that handlers should accept (request:
HttpRequest, response: HttpResponse) and return ApiResponse[Any] | None; replace
the earlier suggested handler signature and parameter examples that reference
FlowContext with the correct HttpRequest/HttpResponse contract; update the
import guidance to reference the appropriate exported symbols used by the helper
(e.g., http and the SDK’s HttpRequest/HttpResponse/ApiResponse types) and remove
references to FlowContext and MotiaHttpArgs so the docs match the http()
implementation.
sergiofilhowz
approved these changes
Mar 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refresh docs for Motia 1.0 by adding migration and package references, clarifying Motia vs iii naming, and hiding legacy examples from production routes, search, and generated LLM artifacts.
Summary by CodeRabbit
New Features
Bug Fixes
Documentation
Breaking Changes
protocolsinstead ofauthToken.loggerandenqueuenow imported rather than injected.stateManagerrenamed tostate_manager.iii-config.yamltoconfig.yaml.