Skip to content

Add Mastra AgentKit cookbook - #703

Merged
saif-at-scalekit merged 2 commits into
mainfrom
cookbook/mastra-agentkit
May 26, 2026
Merged

Add Mastra AgentKit cookbook#703
saif-at-scalekit merged 2 commits into
mainfrom
cookbook/mastra-agentkit

Conversation

@saif-at-scalekit

@saif-at-scalekit saif-at-scalekit commented May 19, 2026

Copy link
Copy Markdown
Collaborator

Adds a new cookbook: Build a Mastra agent with Scalekit AgentKit tools

Path: src/content/docs/cookbooks/mastra-agentkit.mdx

What this covers

  • Connecting a Mastra agent to Gmail tools through Scalekit AgentKit
  • Dynamic tool discovery using @scalekit-sdk/node (listTools → Mastra createTool wrappers)
  • Magic link authorization flow for end users
  • Complete TypeScript implementation with step-by-step walkthrough
  • Common mistakes, production notes, and next steps

Companion sample app

https://github.com/scalekit-developers/mastra-agentkit-example

Related Linear issue: SK-414

Summary by CodeRabbit

  • Documentation
    • New cookbook: step-by-step guide for building Mastra agents with Scalekit AgentKit connector tools. Includes setup and auth flow, example run outputs (first run vs subsequent runs), listing and using connector tools at runtime, running the agent loop with constructed tools, verification steps, passing custom prompts, common mistakes, production best practices (token refresh, per-user scoping, error handling), and related resources.

Review Change Stack

@coderabbitai

coderabbitai Bot commented May 19, 2026

Copy link
Copy Markdown
Contributor

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 874075a7-0bd9-43f0-ba87-bc0f6e0575ba

📥 Commits

Reviewing files that changed from the base of the PR and between 5e33082 and 8e172d2.

📒 Files selected for processing (1)
  • src/content/docs/cookbooks/mastra-agentkit.mdx
📜 Recent review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
  • GitHub Check: Redirect rules - scalekit-starlight
  • GitHub Check: Header rules - scalekit-starlight
  • GitHub Check: Pages changed - scalekit-starlight
🧰 Additional context used
📓 Path-based instructions (10)
**/*.mdx

📄 CodeRabbit inference engine (.cursorrules)

**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component: 1. ## Title with all step content indented with exactly 3 spaces
Use action-oriented headings in step-by-step guides within Steps components
Include code examples in all 4 languages (Node.js, Python, Go, Java) within Steps co...

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx

⚙️ CodeRabbit configuration file

**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:

Frontmatter

  • title MUST be ≤ 60 characters and clearly state what the page does.
  • description MUST be ≤ 160 characters, action-oriented, unique per page.
  • sidebar.label MUST be present and ≤ 30 characters.
  • sidebar.order MUST be set on every page that lives inside a section
    with siblings, to enforce the journey order in sidebar.config.ts.
  • Flag any missing prev / next links on pages that are clearly
    part of a sequential flow (e.g., quickstart → implement-login →
    complete-login → manage-session → logout).

Voice & Style (CLAUDE.md standards)

  • Voice: confident, direct, collaborative, instructional.
  • Person: second person only ("you", "your application"). Reject "we",
    "our", "the developer", "the user".
  • Tense: present tense for descriptions; imperative mood for instructions.
  • Flag weasel words: "simply", "just", "easy", "straightforward",
    "obviously", "of course", "note that".
  • Flag passive voice constructions where active voice is clearer.
  • Headings must be sentence case, not Title Case (except proper nouns).
  • Headings that match a real API parameter, method, or field name
    (e.g., contactID, xero_tenant_id, executeTool) should preserve
    the original casing. Do NOT flag these as sentence-case violations.
  • No heading should end with a colon or period.

Content structure

  • Journey how-to guides MUST contain numbered <Steps> (Starlight
    component). This does NOT apply to src/content/docs/cookbooks/**
    (blog-style recipes — optional <Steps>, <Tabs> after </Steps> OK;
    see cookbooks path_instructions).
  • Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
  • API reference pages MUST list parameters in a table with Name / Type /
    Required / Description columns.
  • Every page MUST end with a clear "what's next" signal — either a
    next: f...

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
**/*.{yml,yaml,md,mdx}

📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)

**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
**/*.{md,mdx}

📄 CodeRabbit inference engine (.cursor/rules/deno-docs-style.mdc)

**/*.{md,mdx}: Use sentence case for all titles and headings in MD/MDX documentation
Keep page titles short and descriptive (3–7 words when possible) in MD/MDX documentation
Use outcome-focused headings that describe results, not categories (e.g., 'Run a script' not 'Scripts')
Avoid gerunds in headings when an imperative works - prefer 'Configure proxies' over 'Configuring proxies'
Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Use sentence case in sidebar labels without punctuation
Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Present the primary use case (80% path) first in documentation, with edge cases later
Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Break up long documentation sections with subheadings every 3–6 paragraphs
Use asides for important notes, tips, cautions, and references in documentation
Provide runnable, minimal code examples that work as-is in documentation
Prefer CLI-first examples and show file layout when helpful in documentation
Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentation
Keep code block annotations brief and purposeful - annotate only what matters
Use consistent variable and file names across a documentation page
Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Prefer relative links for internal documentation pages and include anchors for section references
Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Use backticks for code, file names, CLI flags, and endpoints in documentation
Use lists for options and features in documentation; tables only when comparisons are cleare...

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
src/content/docs/**/*.mdx

📄 CodeRabbit inference engine (.cursor/rules/starlight-steps-tabs-structure.mdc)

src/content/docs/**/*.mdx: In MDX documentation files, <Steps> must contain one continuous ordered list. Wrap <Steps> around a normal Markdown ordered list such as 1. ## ...
In MDX documentation files, numbered step lines must start at column 0. Do not indent the 1. ##, 2. ##, etc.
In MDX documentation files, any content that belongs to a step must be indented with 3 spaces: paragraphs, bullets, images, <Tabs>, <TabItem>, and fenced code blocks
In MDX documentation files, prefer plain Markdown inside <Steps>. If the content is mostly <Tabs> or other JSX-heavy blocks, use normal section headings instead of <Steps>
In MDX documentation files, when <Tabs> is used inside a step, keep <Tabs>, <TabItem>, </TabItem>, and </Tabs> consistently nested under that step
In MDX documentation files, if a tabs block is not part of a numbered step, place it outside </Steps>

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
**/*.{ts,tsx,py,go,java,mdx,md}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx,py,go,java,mdx,md}: Use the exact SDK variable names: Node.js (scalekit), Python (scalekit_client), Go (scalekitClient), Java (scalekitClient)
Never hard-code secrets or API keys in code examples; use environment variables
Include security comments that state the threat, why the pattern is required, and what can go wrong if omitted

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
**/*.{mdx,md}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{mdx,md}: All code examples must use <Tabs syncKey="tech-stack"> format and include Node.js, Python, Go, and Java implementations (90% rule)
Use sentence case for all titles and headings in documentation
Use bold for first mention of important terms, UI elements, and dashboard paths (e.g., Dashboard > Authentication > Session Policy)
Use inline code for technical identifiers: variables, functions, endpoints, scopes, environment variables, file paths, and placeholders
Always include headers in tables; keep cell content concise and readable
Prefer fenced code blocks with language identifiers for all code; never use screenshots of code
Use descriptive link text; never use 'click here' or 'this' as link labels
Keep sentences simple, right-branching, and unambiguous; avoid ambiguous noun stacks and demonstrative pronouns
Use active voice; prefer 'Run the command' over 'The command should be run'
Use second person when giving instructions; address the reader as 'you'
Use present tense for procedures; 'This command installs…' not 'This command will install…'
Avoid hype, slang, and filler words like 'simply', 'just', 'obviously' in documentation
Use consistent terminology throughout; prefer standard names over synonyms
Explain security implications and threats for all security-related content
Use imperative verbs for procedure headings: 'Run a script' not 'Running a script'; 'Configure proxies' not 'Configuring proxies'
Headings must describe outcomes, not categories (good: 'Run a script'; bad: 'Scripts')
Split content into clear sections with descriptive, sentence-style titles that convey meaning without requiring the following paragraph
Keep paragraphs short; isolate critical points in their own short paragraphs
Begin sections and paragraphs with standalone topic sentences that preview content
Put the topic words at the beginning of topic sentences to support fast skimming
Put key takeaways and results at the top of documents and sections
Use bullets and tabl...

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
src/content/docs/**/*.{mdx,md}

📄 CodeRabbit inference engine (CLAUDE.md)

src/content/docs/**/*.{mdx,md}: Every documentation page must include frontmatter with at least: title, description, and sidebar.label
Page titles must be ≤60 characters and descriptions must be ≤160 characters
Sidebar labels must be concise (1-3 words) and use sentence case without punctuation
Use <Steps> component with single continuous ordered list; numbered steps start at column 0, continuation content indented with exactly 3 spaces
Use relative links for internal pages; include anchors for sections
Include a table of contents for documents with multiple sections; enable tableOfContents: true in frontmatter

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
src/content/**/*.mdx

📄 CodeRabbit inference engine (CONTRIBUTING.md)

src/content/**/*.mdx: All documentation must live as MDX files inside src/content/
Every documentation page must have frontmatter with title (≤60 characters), description (≤160 characters), sidebar label, order, and tags
Write documentation in second person using 'you' and 'your application', present tense for descriptions, and imperative for step-by-step instructions
Avoid filler phrases like 'simply', 'just', 'easily' in documentation and be direct
Explain security implications when relevant in documentation
Every code block demonstrating an SDK operation must include all four languages (Node.js, Python, Go, Java) using synced tabs with syncKey='tech-stack'
SDK variable names are fixed and must not be renamed: Node.js uses scalekit, Python uses scalekit_client, Go uses scalekitClient, Java uses scalekitClient

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
**/*.{md,mdx,astro,ts}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

**/*.{md,mdx,astro,ts}: Use pnpm pretty-quick --staged via pre-commit git hook to auto-format all staged .md, .mdx, .astro, .ts files with Prettier
Run pnpm format to auto-format all .md, .mdx, .astro, .ts files before pushing changes

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
src/content/docs/cookbooks/**/*.mdx

⚙️ CodeRabbit configuration file

src/content/docs/cookbooks/**/*.mdx: This file is a Scalekit cookbook: a standalone recipe under the
starlight-blog integration (prefix: cookbooks in astro.config.mjs).
Apply global MDX voice, style, links, and accessibility rules, but use
these cookbook-specific expectations:

Overrides to global MDX checks

  • Do NOT require sidebar.order — ordering follows the blog plugin and
    publication metadata, not sidebar.config.ts journey slots.
  • Do NOT require prev / next frontmatter — cookbooks are not a
    sequential product journey; cross-links and related docs are enough.
  • tableOfContents is optional — enable it when the post has many H2s.

Frontmatter

  • title and description follow the same length and clarity rules as
    global MDX.
  • Prefer sidebar.label for navigation consistency; if absent, do not
    treat it as a hard failure (older cookbooks may omit it).
  • date, tags, authors, excerpt, and featured are normal for
    cookbooks — verify tags match the topic (e.g. MCP, SSO, FSA).

Code examples

  • Require all four SDK tabs (Node.js, Python, Go, Java) ONLY when the
    snippet demonstrates Scalekit client SDK usage. For MCP setup, CLI,
    shell, framework-only (e.g. Next.js), or IDE configuration recipes,
    use the tabs or single-language blocks that fit the task. Do not
    demand four SDK languages for bash, JSON, env files, or non-SDK code.
  • Minimal examples (single command, config block) do not need both
    success and error paths unless the recipe is explicitly about errors.
  • Flag real-looking API keys or secrets — use placeholders such as
    YOUR_API_KEY or YOUR_CLIENT_SECRET.

<Steps> (overrides global "how-to MUST use Steps")

  • Do NOT require <Steps> on cookbooks. The global rule targets journey
    how-to pages; a cookbook may use H2 sections, <Tabs>, or prose.
  • Do NOT flag "missing Steps" when the procedure is already clear.
  • If <Steps> is used, <Tabs> or other blocks MAY appear after
    </Steps> (e.g. per–IDE ...

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
🧠 Learnings (14)
📚 Learning: 2026-01-30T18:18:50.883Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx:31-49
Timestamp: 2026-01-30T18:18:50.883Z
Learning: In all Scalekit documentation files (MDX), treat the terms 'Applications', 'Single Page Application (SPA)', 'Native Application', and 'Web Application' as proper nouns and preserve their capitalization in headings and body text. Ensure these terms remain capitalized even when used in sentence case or within prose.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-02-04T12:47:16.544Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 412
File: src/content/docs/dev-kit/tools/scalekit-dryrun.mdx:1-23
Timestamp: 2026-02-04T12:47:16.544Z
Learning: In scalekit-inc/developer-docs, the MDX frontmatter field order is required only when the sidebar configuration points to a directory (for auto-generation). If the sidebar.config.ts references a specific file path, the order field is not required. Apply this check to all MDX files under src/content/docs: if a file contributes to an auto-generated sidebar (directory path), ensure order is present; if it’s linked to a concrete file, order can be omitted. Use sidebar.config.ts to determine whether a given MDX file falls under directory-based vs file-specific sidebar references.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-02-25T08:57:12.201Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/quickstart.mdx:2-10
Timestamp: 2026-02-25T08:57:12.201Z
Learning: In Scalekit developer-docs (Astro Starlight), do not auto-suggest adding tableOfContents in frontmatter unless the user explicitly overrides the default behavior. The default enables tableOfContents with minHeadingLevel 2 and maxHeadingLevel 3. Only set tableOfContents when you want to customize heading levels or disable it entirely; otherwise omit it for other docs.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-02-25T13:04:27.491Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:9-17
Timestamp: 2026-02-25T13:04:27.491Z
Learning: Allow page-level CSS overrides in MDX frontmatter (head: style) for readability and engagement, even if it customizes typography beyond defaults. This applies to per-page UX decisions, including heading sizes and style tweaks, but keep overrides purposeful, accessible, and within the repository's design guidelines. Use these overrides sparingly and document the rationale for maintainability.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-03-05T11:29:08.125Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 463
File: src/content/docs/agent-auth/providers.mdx:35-73
Timestamp: 2026-03-05T11:29:08.125Z
Learning: In src/content/docs/agent-auth/providers.mdx, the Card components intentionally use icon=" " (a space) to render consistent colored boxes since some Starlight icon names resolve to icons and others do not. Do not flag icon=" " as a placeholder issue for this file; treat this as a deliberate UX choice specific to this MDX page and avoid raising a placeholder-icon warning here.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-03-09T07:27:56.794Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 469
File: src/content/docs/guides/integrations/scim-integrations/azure-scim.mdx:95-107
Timestamp: 2026-03-09T07:27:56.794Z
Learning: Do not enforce the 3-space indentation rule for Steps component content as a hard style rule in MDX files under src/content/docs/**/*.mdx. Only flag/rectify it if it causes visible rendering problems in the UI. Otherwise, allow current formatting; apply this rule only when rendering issues are observed and document any fixes.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-03-09T07:32:38.426Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 467
File: src/content/docs/sso/guides/sso-user-attributes.mdx:108-148
Timestamp: 2026-03-09T07:32:38.426Z
Learning: In MDX code samples under src/content/docs (and similar conceptual snippets in scalekit-inc/developer-docs), when an example's sole purpose is to show how to access a specific value (e.g., reading JWT claims after token validation), omit error/non-happy-path handling to keep the snippet focused. Do not flag the absence of error paths in narrowly scoped conceptual snippets.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-03-17T16:01:50.487Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 506
File: src/content/docs/authenticate/fsa/quickstart.mdx:851-853
Timestamp: 2026-03-17T16:01:50.487Z
Learning: In the Scalekit Python SDK docs, clarify that LogoutUrlOptions is not exported from the top-level scalekit package __init__.py. The correct import path in code samples or reviews is: from scalekit.common.scalekit import LogoutUrlOptions. Do not flag this import path as incorrect in documentation or code reviews; ensure examples reflect the proper import path to avoid confusion for users.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-02-25T03:34:41.147Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:31-31
Timestamp: 2026-02-25T03:34:41.147Z
Learning: In MDX files, import { Code } from 'astrojs/starlight/components' only if the MDX content actually uses the <Code> component. If the file uses only fenced code blocks (```), the import is not required. Apply this guideline to all MDX files (e.g., src/content/docs/**/*.mdx) to avoid unnecessary imports and reduce bundle size.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-02-25T18:41:00.639Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 446
File: src/content/docs/authenticate/m2m/api-auth-quickstart.mdx:78-78
Timestamp: 2026-02-25T18:41:00.639Z
Learning: Preserve full URLs inside code comments in MDX code blocks (bash/python/js) when the URLs are part of copyable examples. Do not flag these in code examples. Use relative paths in prose and hyperlinks within MDX; only enforce relative paths for markdown prose links, not for URLs inside code comments.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (.mdx files), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag links for missing `target="_blank"` or `rel="noopener"` (avoid adding raw HTML anchors just to include those attributes), and keep the approach consistent with existing docs styling.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-03-26T13:43:49.940Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 539
File: src/content/docs/cookbooks/search-scalekit-docs-in-your-ide.mdx:1-15
Timestamp: 2026-03-26T13:43:49.940Z
Learning: In scalekit-inc/developer-docs, cookbook pages under `src/content/docs/cookbooks/` use directory-based auto-generation for the sidebar (configured in `src/configs/sidebar.config.ts` with routes like `/cookbooks` and `/cookbooks/**/*`). For files in this directory, do not require or flag missing `sidebar.label` in the MDX frontmatter.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-04-25T07:22:18.321Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 633
File: src/components/templates/agent-connectors/_setup-heyreach.mdx:12-12
Timestamp: 2026-04-25T07:22:18.321Z
Learning: In this repo’s MDX documentation files, treat `@/...` paths as aliases that resolve to the `src/` directory (e.g., `@/assets/docs/foo/bar.png` -> `src/assets/docs/foo/bar.png`). When reviewing, do not flag `@`-prefixed image (or other asset) paths as broken; instead, verify that the corresponding physical file exists under `src/`.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (MD/MDX), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag external links for missing `target="_blank"` or `rel="noopener"`, and avoid converting Markdown links into raw HTML `<a>` tags just to add those attributes, since that would be inconsistent with the established doc pattern.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
🔇 Additional comments (2)
src/content/docs/cookbooks/mastra-agentkit.mdx (2)

85-120: Four-language SDK tabs are still missing in Scalekit SDK snippets.

This was already flagged and still applies: the Scalekit SDK examples remain Node.js-only instead of using <Tabs syncKey="tech-stack"> with Node.js, Python, Go, and Java.

Also applies to: 132-143, 151-178, 188-203


85-120: Runnable flow still lacks explicit error-path examples.

This was already flagged and still applies: the main SDK walkthrough remains success-path only and does not show explicit error handling around connected-account/auth/tool execution flow.

Also applies to: 132-143, 151-178, 188-203


Walkthrough

Adds a new Mastra + Scalekit AgentKit cookbook MDX page with setup, a complete src/index.ts walkthrough (client init, OAuth, runtime tool discovery, Mastra tool wrapping, agent run), verification examples, troubleshooting, production notes, and related links.

Changes

Mastra + Scalekit AgentKit Integration Cookbook

Layer / File(s) Summary
Overview and Setup
src/content/docs/cookbooks/mastra-agentkit.mdx
Page frontmatter, introduction, prerequisites, dependency installation, and .env variables (SCALEKIT_API_KEY, OpenAI vars, USER_IDENTIFIER, CONNECTION_NAME).
Implementation Walkthrough
src/content/docs/cookbooks/mastra-agentkit.mdx
Shows ScalekitClient initialization, getOrCreateConnectedAccount + getAuthorizationLink OAuth flow, scalekit.tools.listTools scoped by connector/identifier, wrapping discovered tools into Mastra createTool with a Zod passthrough schema, delegating execution to scalekit.tools.executeTool, and building/running the Mastra Agent.
Verification, Troubleshooting, and Production Guidance
src/content/docs/cookbooks/mastra-agentkit.mdx
Run and verification commands with sample first-run and subsequent outputs, common mistakes (pending OAuth, empty tool lists, identifier mismatches, schema issues), production notes (token refresh, per-user scoping, error handling, MCP alternative), next steps, and related resources table.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

  • scalekit-inc/developer-docs#681: Both cookbooks demonstrate AgentKit connected-account auth flow and runtime tool loading; this targets Mastra framework while PR #681 targets LangChain/LangSmith.
  • scalekit-inc/developer-docs#622: Also implements a per-user connected-account OAuth magic-link + polling pattern used to activate connector access before tool execution.

Suggested reviewers

  • ravibits
  • amitash1912
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'Add Mastra AgentKit cookbook' directly and accurately describes the main change: adding a new documentation page for building Mastra agents with Scalekit AgentKit tools.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch cookbook/mastra-agentkit
  • 🛠️ fix frontmatter
  • 🛠️ fix internal links

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.


Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/content/docs/cookbooks/mastra-agentkit.mdx`:
- Around line 85-120: Wrap the main runnable flow (the scalekit
connected-account checks and OAuth prompt around
scalekit.actions.getOrCreateConnectedAccount and
scalekit.actions.getAuthorizationLink), the subsequent tool
discovery/registration steps, and the agent execution/executeTool calls in
explicit try/catch blocks that log or surface errors and exit gracefully;
specifically add try/catch around the block that awaits
getOrCreateConnectedAccount and the authorization-link flow (including the
process.stdin prompt), add error handling around any tool discovery/creation
routines (e.g., createTool or tool registration calls), and wrap the Agent
execution/executeTool invocation with its own try/catch to log the error and
provide a clear fallback/exit path so the example shows both success and error
paths.
- Around line 85-120: The code examples use only the Node.js ScalekitClient
snippets (e.g., ScalekitClient, scalekit.actions.getOrCreateConnectedAccount,
scalekit.actions.getAuthorizationLink, IDENTIFIER, CONNECTION) but must include
four-language SDK tabs; update the MDX blocks by wrapping the existing Node.js
fence inside a <Tabs syncKey="tech-stack"> and add parallel tab panels for
Python, Go, and Java that show equivalent usage (instantiating the Scalekit
client, calling get_or_create_connected_account / GetOrCreateConnectedAccount or
similar SDK method names, and get_authorization_link / GetAuthorizationLink with
same IDENTIFIER/CONNECTION semantics); apply the same four-tab change to the
other code fences noted (around lines 132-143, 151-178, 188-203) so every
Scalekit example has Node.js, Python, Go, and Java variants.
- Around line 122-125: Update the instructional text to use second-person
phrasing consistently: replace third-person references like “the user” and “your
application never sees” with direct “you”/“your” wording in the paragraphs
mentioning getOrCreateConnectedAccount, getAuthorizationLink, and Scalekit (and
the other noted instructional blocks). Ensure lines describing the production
flow and CLI flow address the reader directly (e.g., “you would redirect the
user…” → “you redirect the user…” or “you handle the callback”), and apply the
same change to the other two sections called out.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0d29a3a5-6fcc-4ba6-8c1a-922829fab6c4

📥 Commits

Reviewing files that changed from the base of the PR and between f8f842d and 5e33082.

📒 Files selected for processing (1)
  • src/content/docs/cookbooks/mastra-agentkit.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (10)
**/*.mdx

📄 CodeRabbit inference engine (.cursorrules)

**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component: 1. ## Title with all step content indented with exactly 3 spaces
Use action-oriented headings in step-by-step guides within Steps components
Include code examples in all 4 languages (Node.js, Python, Go, Java) within Steps co...

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx

⚙️ CodeRabbit configuration file

**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:

Frontmatter

  • title MUST be ≤ 60 characters and clearly state what the page does.
  • description MUST be ≤ 160 characters, action-oriented, unique per page.
  • sidebar.label MUST be present and ≤ 30 characters.
  • sidebar.order MUST be set on every page that lives inside a section
    with siblings, to enforce the journey order in sidebar.config.ts.
  • Flag any missing prev / next links on pages that are clearly
    part of a sequential flow (e.g., quickstart → implement-login →
    complete-login → manage-session → logout).

Voice & Style (CLAUDE.md standards)

  • Voice: confident, direct, collaborative, instructional.
  • Person: second person only ("you", "your application"). Reject "we",
    "our", "the developer", "the user".
  • Tense: present tense for descriptions; imperative mood for instructions.
  • Flag weasel words: "simply", "just", "easy", "straightforward",
    "obviously", "of course", "note that".
  • Flag passive voice constructions where active voice is clearer.
  • Headings must be sentence case, not Title Case (except proper nouns).
  • Headings that match a real API parameter, method, or field name
    (e.g., contactID, xero_tenant_id, executeTool) should preserve
    the original casing. Do NOT flag these as sentence-case violations.
  • No heading should end with a colon or period.

Content structure

  • Journey how-to guides MUST contain numbered <Steps> (Starlight
    component). This does NOT apply to src/content/docs/cookbooks/**
    (blog-style recipes — optional <Steps>, <Tabs> after </Steps> OK;
    see cookbooks path_instructions).
  • Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
  • API reference pages MUST list parameters in a table with Name / Type /
    Required / Description columns.
  • Every page MUST end with a clear "what's next" signal — either a
    next: f...

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
**/*.{yml,yaml,md,mdx}

📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)

**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
**/*.{md,mdx}

📄 CodeRabbit inference engine (.cursor/rules/deno-docs-style.mdc)

**/*.{md,mdx}: Use sentence case for all titles and headings in MD/MDX documentation
Keep page titles short and descriptive (3–7 words when possible) in MD/MDX documentation
Use outcome-focused headings that describe results, not categories (e.g., 'Run a script' not 'Scripts')
Avoid gerunds in headings when an imperative works - prefer 'Configure proxies' over 'Configuring proxies'
Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Use sentence case in sidebar labels without punctuation
Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Present the primary use case (80% path) first in documentation, with edge cases later
Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Break up long documentation sections with subheadings every 3–6 paragraphs
Use asides for important notes, tips, cautions, and references in documentation
Provide runnable, minimal code examples that work as-is in documentation
Prefer CLI-first examples and show file layout when helpful in documentation
Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentation
Keep code block annotations brief and purposeful - annotate only what matters
Use consistent variable and file names across a documentation page
Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Prefer relative links for internal documentation pages and include anchors for section references
Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Use backticks for code, file names, CLI flags, and endpoints in documentation
Use lists for options and features in documentation; tables only when comparisons are cleare...

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
src/content/docs/**/*.mdx

📄 CodeRabbit inference engine (.cursor/rules/starlight-steps-tabs-structure.mdc)

src/content/docs/**/*.mdx: In MDX documentation files, <Steps> must contain one continuous ordered list. Wrap <Steps> around a normal Markdown ordered list such as 1. ## ...
In MDX documentation files, numbered step lines must start at column 0. Do not indent the 1. ##, 2. ##, etc.
In MDX documentation files, any content that belongs to a step must be indented with 3 spaces: paragraphs, bullets, images, <Tabs>, <TabItem>, and fenced code blocks
In MDX documentation files, prefer plain Markdown inside <Steps>. If the content is mostly <Tabs> or other JSX-heavy blocks, use normal section headings instead of <Steps>
In MDX documentation files, when <Tabs> is used inside a step, keep <Tabs>, <TabItem>, </TabItem>, and </Tabs> consistently nested under that step
In MDX documentation files, if a tabs block is not part of a numbered step, place it outside </Steps>

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
**/*.{ts,tsx,py,go,java,mdx,md}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx,py,go,java,mdx,md}: Use the exact SDK variable names: Node.js (scalekit), Python (scalekit_client), Go (scalekitClient), Java (scalekitClient)
Never hard-code secrets or API keys in code examples; use environment variables
Include security comments that state the threat, why the pattern is required, and what can go wrong if omitted

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
**/*.{mdx,md}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{mdx,md}: All code examples must use <Tabs syncKey="tech-stack"> format and include Node.js, Python, Go, and Java implementations (90% rule)
Use sentence case for all titles and headings in documentation
Use bold for first mention of important terms, UI elements, and dashboard paths (e.g., Dashboard > Authentication > Session Policy)
Use inline code for technical identifiers: variables, functions, endpoints, scopes, environment variables, file paths, and placeholders
Always include headers in tables; keep cell content concise and readable
Prefer fenced code blocks with language identifiers for all code; never use screenshots of code
Use descriptive link text; never use 'click here' or 'this' as link labels
Keep sentences simple, right-branching, and unambiguous; avoid ambiguous noun stacks and demonstrative pronouns
Use active voice; prefer 'Run the command' over 'The command should be run'
Use second person when giving instructions; address the reader as 'you'
Use present tense for procedures; 'This command installs…' not 'This command will install…'
Avoid hype, slang, and filler words like 'simply', 'just', 'obviously' in documentation
Use consistent terminology throughout; prefer standard names over synonyms
Explain security implications and threats for all security-related content
Use imperative verbs for procedure headings: 'Run a script' not 'Running a script'; 'Configure proxies' not 'Configuring proxies'
Headings must describe outcomes, not categories (good: 'Run a script'; bad: 'Scripts')
Split content into clear sections with descriptive, sentence-style titles that convey meaning without requiring the following paragraph
Keep paragraphs short; isolate critical points in their own short paragraphs
Begin sections and paragraphs with standalone topic sentences that preview content
Put the topic words at the beginning of topic sentences to support fast skimming
Put key takeaways and results at the top of documents and sections
Use bullets and tabl...

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
src/content/docs/**/*.{mdx,md}

📄 CodeRabbit inference engine (CLAUDE.md)

src/content/docs/**/*.{mdx,md}: Every documentation page must include frontmatter with at least: title, description, and sidebar.label
Page titles must be ≤60 characters and descriptions must be ≤160 characters
Sidebar labels must be concise (1-3 words) and use sentence case without punctuation
Use <Steps> component with single continuous ordered list; numbered steps start at column 0, continuation content indented with exactly 3 spaces
Use relative links for internal pages; include anchors for sections
Include a table of contents for documents with multiple sections; enable tableOfContents: true in frontmatter

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
src/content/**/*.mdx

📄 CodeRabbit inference engine (CONTRIBUTING.md)

src/content/**/*.mdx: All documentation must live as MDX files inside src/content/
Every documentation page must have frontmatter with title (≤60 characters), description (≤160 characters), sidebar label, order, and tags
Write documentation in second person using 'you' and 'your application', present tense for descriptions, and imperative for step-by-step instructions
Avoid filler phrases like 'simply', 'just', 'easily' in documentation and be direct
Explain security implications when relevant in documentation
Every code block demonstrating an SDK operation must include all four languages (Node.js, Python, Go, Java) using synced tabs with syncKey='tech-stack'
SDK variable names are fixed and must not be renamed: Node.js uses scalekit, Python uses scalekit_client, Go uses scalekitClient, Java uses scalekitClient

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
**/*.{md,mdx,astro,ts}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

**/*.{md,mdx,astro,ts}: Use pnpm pretty-quick --staged via pre-commit git hook to auto-format all staged .md, .mdx, .astro, .ts files with Prettier
Run pnpm format to auto-format all .md, .mdx, .astro, .ts files before pushing changes

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
src/content/docs/cookbooks/**/*.mdx

⚙️ CodeRabbit configuration file

src/content/docs/cookbooks/**/*.mdx: This file is a Scalekit cookbook: a standalone recipe under the
starlight-blog integration (prefix: cookbooks in astro.config.mjs).
Apply global MDX voice, style, links, and accessibility rules, but use
these cookbook-specific expectations:

Overrides to global MDX checks

  • Do NOT require sidebar.order — ordering follows the blog plugin and
    publication metadata, not sidebar.config.ts journey slots.
  • Do NOT require prev / next frontmatter — cookbooks are not a
    sequential product journey; cross-links and related docs are enough.
  • tableOfContents is optional — enable it when the post has many H2s.

Frontmatter

  • title and description follow the same length and clarity rules as
    global MDX.
  • Prefer sidebar.label for navigation consistency; if absent, do not
    treat it as a hard failure (older cookbooks may omit it).
  • date, tags, authors, excerpt, and featured are normal for
    cookbooks — verify tags match the topic (e.g. MCP, SSO, FSA).

Code examples

  • Require all four SDK tabs (Node.js, Python, Go, Java) ONLY when the
    snippet demonstrates Scalekit client SDK usage. For MCP setup, CLI,
    shell, framework-only (e.g. Next.js), or IDE configuration recipes,
    use the tabs or single-language blocks that fit the task. Do not
    demand four SDK languages for bash, JSON, env files, or non-SDK code.
  • Minimal examples (single command, config block) do not need both
    success and error paths unless the recipe is explicitly about errors.
  • Flag real-looking API keys or secrets — use placeholders such as
    YOUR_API_KEY or YOUR_CLIENT_SECRET.

<Steps> (overrides global "how-to MUST use Steps")

  • Do NOT require <Steps> on cookbooks. The global rule targets journey
    how-to pages; a cookbook may use H2 sections, <Tabs>, or prose.
  • Do NOT flag "missing Steps" when the procedure is already clear.
  • If <Steps> is used, <Tabs> or other blocks MAY appear after
    </Steps> (e.g. per–IDE ...

Files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
🧠 Learnings (14)
📚 Learning: 2026-01-30T18:18:50.883Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx:31-49
Timestamp: 2026-01-30T18:18:50.883Z
Learning: In all Scalekit documentation files (MDX), treat the terms 'Applications', 'Single Page Application (SPA)', 'Native Application', and 'Web Application' as proper nouns and preserve their capitalization in headings and body text. Ensure these terms remain capitalized even when used in sentence case or within prose.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-02-04T12:47:16.544Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 412
File: src/content/docs/dev-kit/tools/scalekit-dryrun.mdx:1-23
Timestamp: 2026-02-04T12:47:16.544Z
Learning: In scalekit-inc/developer-docs, the MDX frontmatter field order is required only when the sidebar configuration points to a directory (for auto-generation). If the sidebar.config.ts references a specific file path, the order field is not required. Apply this check to all MDX files under src/content/docs: if a file contributes to an auto-generated sidebar (directory path), ensure order is present; if it’s linked to a concrete file, order can be omitted. Use sidebar.config.ts to determine whether a given MDX file falls under directory-based vs file-specific sidebar references.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-02-25T08:57:12.201Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/quickstart.mdx:2-10
Timestamp: 2026-02-25T08:57:12.201Z
Learning: In Scalekit developer-docs (Astro Starlight), do not auto-suggest adding tableOfContents in frontmatter unless the user explicitly overrides the default behavior. The default enables tableOfContents with minHeadingLevel 2 and maxHeadingLevel 3. Only set tableOfContents when you want to customize heading levels or disable it entirely; otherwise omit it for other docs.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-02-25T13:04:27.491Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:9-17
Timestamp: 2026-02-25T13:04:27.491Z
Learning: Allow page-level CSS overrides in MDX frontmatter (head: style) for readability and engagement, even if it customizes typography beyond defaults. This applies to per-page UX decisions, including heading sizes and style tweaks, but keep overrides purposeful, accessible, and within the repository's design guidelines. Use these overrides sparingly and document the rationale for maintainability.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-03-05T11:29:08.125Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 463
File: src/content/docs/agent-auth/providers.mdx:35-73
Timestamp: 2026-03-05T11:29:08.125Z
Learning: In src/content/docs/agent-auth/providers.mdx, the Card components intentionally use icon=" " (a space) to render consistent colored boxes since some Starlight icon names resolve to icons and others do not. Do not flag icon=" " as a placeholder issue for this file; treat this as a deliberate UX choice specific to this MDX page and avoid raising a placeholder-icon warning here.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-03-09T07:27:56.794Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 469
File: src/content/docs/guides/integrations/scim-integrations/azure-scim.mdx:95-107
Timestamp: 2026-03-09T07:27:56.794Z
Learning: Do not enforce the 3-space indentation rule for Steps component content as a hard style rule in MDX files under src/content/docs/**/*.mdx. Only flag/rectify it if it causes visible rendering problems in the UI. Otherwise, allow current formatting; apply this rule only when rendering issues are observed and document any fixes.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-03-09T07:32:38.426Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 467
File: src/content/docs/sso/guides/sso-user-attributes.mdx:108-148
Timestamp: 2026-03-09T07:32:38.426Z
Learning: In MDX code samples under src/content/docs (and similar conceptual snippets in scalekit-inc/developer-docs), when an example's sole purpose is to show how to access a specific value (e.g., reading JWT claims after token validation), omit error/non-happy-path handling to keep the snippet focused. Do not flag the absence of error paths in narrowly scoped conceptual snippets.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-03-17T16:01:50.487Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 506
File: src/content/docs/authenticate/fsa/quickstart.mdx:851-853
Timestamp: 2026-03-17T16:01:50.487Z
Learning: In the Scalekit Python SDK docs, clarify that LogoutUrlOptions is not exported from the top-level scalekit package __init__.py. The correct import path in code samples or reviews is: from scalekit.common.scalekit import LogoutUrlOptions. Do not flag this import path as incorrect in documentation or code reviews; ensure examples reflect the proper import path to avoid confusion for users.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-02-25T03:34:41.147Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:31-31
Timestamp: 2026-02-25T03:34:41.147Z
Learning: In MDX files, import { Code } from 'astrojs/starlight/components' only if the MDX content actually uses the <Code> component. If the file uses only fenced code blocks (```), the import is not required. Apply this guideline to all MDX files (e.g., src/content/docs/**/*.mdx) to avoid unnecessary imports and reduce bundle size.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-02-25T18:41:00.639Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 446
File: src/content/docs/authenticate/m2m/api-auth-quickstart.mdx:78-78
Timestamp: 2026-02-25T18:41:00.639Z
Learning: Preserve full URLs inside code comments in MDX code blocks (bash/python/js) when the URLs are part of copyable examples. Do not flag these in code examples. Use relative paths in prose and hyperlinks within MDX; only enforce relative paths for markdown prose links, not for URLs inside code comments.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (.mdx files), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag links for missing `target="_blank"` or `rel="noopener"` (avoid adding raw HTML anchors just to include those attributes), and keep the approach consistent with existing docs styling.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-03-26T13:43:49.940Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 539
File: src/content/docs/cookbooks/search-scalekit-docs-in-your-ide.mdx:1-15
Timestamp: 2026-03-26T13:43:49.940Z
Learning: In scalekit-inc/developer-docs, cookbook pages under `src/content/docs/cookbooks/` use directory-based auto-generation for the sidebar (configured in `src/configs/sidebar.config.ts` with routes like `/cookbooks` and `/cookbooks/**/*`). For files in this directory, do not require or flag missing `sidebar.label` in the MDX frontmatter.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-04-25T07:22:18.321Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 633
File: src/components/templates/agent-connectors/_setup-heyreach.mdx:12-12
Timestamp: 2026-04-25T07:22:18.321Z
Learning: In this repo’s MDX documentation files, treat `@/...` paths as aliases that resolve to the `src/` directory (e.g., `@/assets/docs/foo/bar.png` -> `src/assets/docs/foo/bar.png`). When reviewing, do not flag `@`-prefixed image (or other asset) paths as broken; instead, verify that the corresponding physical file exists under `src/`.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (MD/MDX), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag external links for missing `target="_blank"` or `rel="noopener"`, and avoid converting Markdown links into raw HTML `<a>` tags just to add those attributes, since that would be inconsistent with the established doc pattern.

Applied to files:

  • src/content/docs/cookbooks/mastra-agentkit.mdx

Comment thread src/content/docs/cookbooks/mastra-agentkit.mdx
Comment thread src/content/docs/cookbooks/mastra-agentkit.mdx Outdated
@netlify

netlify Bot commented May 19, 2026

Copy link
Copy Markdown

Deploy Preview for scalekit-starlight ready!

Name Link
🔨 Latest commit 8e172d2
🔍 Latest deploy log https://app.netlify.com/projects/scalekit-starlight/deploys/6a0c13dd08205700089c75c7
😎 Deploy Preview https://deploy-preview-703--scalekit-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@saif-at-scalekit
saif-at-scalekit merged commit 7ae093a into main May 26, 2026
4 checks passed
@saif-at-scalekit
saif-at-scalekit deleted the cookbook/mastra-agentkit branch May 26, 2026 06:04
saif-at-scalekit added a commit that referenced this pull request May 27, 2026
* Add Mastra AgentKit cookbook: build a Mastra agent with Scalekit tools

* Use second-person phrasing consistently in instructional text
saif-at-scalekit added a commit that referenced this pull request Jul 6, 2026
…SKit (#706)

* Split API reference into per-product pages for AgentKit and SaaSKit

- Add Redocly CLI workflow: split monolithic spec into multi-file structure,
  then selectively bundle per-product specs with --remove-unused-components
- Create openapi/agentkit.yaml and openapi/saaskit.yaml as custom root files
  that  into the shared split structure
- Add pnpm split-api script chaining split + bundle for both products
- Add Scalar API reference pages at /agentkit/apis/ and /saaskit/apis/
- AgentKit page includes quickstart with auth, connected accounts, and tool execution
- Update secondary nav: AgentKit links to /agentkit/apis/, SaaSKit to /saaskit/apis/
- Update path fallbacks in secondary-nav-utils for new routes
- Existing /apis/ route with full combined spec remains unchanged

* Add bundled JSON specs and updated d2 diagrams

* Fix search index URL generation: slugify tag names and uppercase HTTP methods

Tag names like 'Connected Accounts' were lowercased but not slugified,
producing 'connected%20accounts' instead of 'connected-accounts'. HTTP
methods were lowercased ('get') but Scalar uses uppercase ('GET').

* Fix broken API reference anchor links

- java-spring-boot-jwt-timeout: #tag/authentication does not exist, changed to #tag/sessions
- check-sso-domain: lowercase get -> GET to match Scalar anchors
- create-roles-permissions: lowercase get -> GET
- custom-user-attributes: lowercase get -> GET

* Generate per-product API markdown and fix apis.md serving

- Extend openapi-to-markdown integration to generate markdown for all three
  specs: combined (apis.md), agentkit (agentkit/apis.md), saaskit (saaskit/apis.md)
- Write to both dist/ and public/ so files are always served as static assets,
  fixing intermittent 404s caused by SSR shadowing dist/ files
- Add Netlify cache headers for per-product markdown files
- Update llms.config.ts with per-product API markdown and OpenAPI spec links
- Update generate-llms-index.js with per-product entries in Optional section
- Add generated markdown files to .gitignore (build artifacts)

* Add cross-links between API references in spec info sections

Each product API reference now shows links to switch to the other
product's API reference or the combined reference.

* Commit API markdown files to public/ for reliable static serving

Remove .gitignore entries — these must be committed so Netlify's CDN
serves them as static assets without hitting SSR.

* Rewrite cross-links as intent-driven sentences

Instead of generic 'Other API references', each link now describes
what the user would be looking for when switching.

* sync docs: add HubSpot engagement tools (call/note/meeting update, email create/update) (#707)

* Add Atlassian Rovo MCP connector docs (#705)

* add Atlassian Rovo MCP connector docs

* add Atlassian Rovo MCP setup guide with domain configuration steps and screenshots

* fix: simplify Atlassian Rovo MCP setup guide for DCR flow, update screenshots

* resolve CodeRabbit comments: fix wrong-context param descriptions, capabilities bullet, category slug; update redirect URI screenshot with arrow

* resolve CodeRabbit: fix cross-contaminated param descriptions, clarify fetch capability, add cloudId workflow section

* sync connector docs: add new HubSpot engagement tools, re-apply atlassianmcp fixes post-sync

* Revert "sync connector docs: add new HubSpot engagement tools, re-apply atlassianmcp fixes post-sync"

This reverts commit 587d6f0.

* resolve CodeRabbit: fix compass/confluence param descriptions, inject common-workflows section, fix tool name prefix

* Add LeadIQ connector docs (#708)

* add LeadIQ connector docs: capabilities, setup guide, common workflows

* resolve CodeRabbit comments: fix company_domain→domain, frontmatter, add API keys screenshot

* fix: move LeadIQ API keys screenshot to correct assets path

* add ClickHouse connector docs (#709)

* add ClickHouse connector docs with capabilities and common workflows

Add ClickHouse agent connector documentation including setup guides, common workflow templates, and capability definitions to help developers integrate ClickHouse data sources with Scalekit agents.

* fix ClickHouse connector docs: correct parameter names, capitalization, and descriptions

* add Zapier MCP connector docs (#710)

* add Zapier MCP connector docs with capability bullets and common workflows

- Added Zapier MCP connector documentation page
- Added 6 capability bullets to capabilities.json
- Created common workflows template with 5 collapsible examples
- Updated connector catalog to include Zapier

* fix Zapier connector docs: correct skillDefinition param name and API Key casing

* Add redirect from /dev-kit/ to /dev-kit/build-with-ai/ (#711)

* Add MCP connector docs sync prod (#712)

* add Adobe Marketing Agent MCP connector docs

* fix: use API display_name for connector auth types (OAuth 2.1/DCR for MCP connectors)

resolveAuthType was hardcoding 'OAuth 2.0' for all OAUTH providers.
The API already provides display_name ('OAuth 2.1/DCR' vs 'OAuth 2.0')
and is_mcp flag — now used directly.

Also updates generateAuthSection prose for MCP connectors to mention
DCR and PKCE instead of generic OAuth 2.0 redirect description.

Re-synced all connector pages to pick up the fix.

* fix: escape single quotes in connectorAuthType frontmatter value

* add connector docs for adzvisermcp, commonroommcp, customeriomcp, fellowaimcp, firecrawlmcp, grainmcp, supermetricsmcp

* add firecrawl dashboard screenshot to setup docs

---------

Co-authored-by: Saif Ali Shaik <saif.shaik@scalekit.com>

* docs: add template redirect URIs and organization logo branding guides (#714)

* docs: add template redirect URIs and organization logo branding guides

* fix: escape curly braces in org logo branding MDX table

* docs: rename to organization branding and add pages to sidebar nav

* docs: rename organization-logo-branding to organization-branding

* docs: simplify template redirect and org branding docs

* code snippet changes

* docs: restructure org branding and template redirect URL pages

- Rename "Template redirect URIs" to "Template redirect URLs" throughout
- Separate dashboard and SDK instructions into distinct subsections
- Use createOrganization snippets consistently across all 4 SDKs
- Replace template variable resolution note with actionable org_id guidance
- Remove em-dashes, clean up surface table (remove internal paths)
- Update Java SDK version to v2.1.1+
- Add screenshot assets for org slug/logo and branding configuration

* docs: bump Java SDK version to 2.1.1 in install snippet

* docs: bump Java SDK version to 2.1.3

* chore: update auto-generated d2 diagram SVGs

* docs: address CodeRabbit review comments

- Add next: frontmatter to both pages for sidebar journey continuity
- Add tags to template-redirect-uris frontmatter
- Add title attribute to all Aside components
- Change TabItem value from 'nodejs' to canonical 'node' for tech-stack syncKey consistency

* docs: improve organization branding page structure and content

* docs: add section on passing organization_id to show org logo on login page

* docs: regenerate D2 diagram SVGs

* docs: rename template redirect URLs to org-specific redirect URLs with SDK examples

- Rename feature from "Template redirect URLs" to "Organization-specific redirect URLs" across template-redirect-uris.mdx
- Normalize URI → URL terminology in body prose
- Add SDK code examples (Node.js, Python, Go, Java) showing resolved redirectUri with organizationId
- Add worked example section with 4-step numbered list explaining the feature
- Add prev nav link in template-redirect-uris.mdx pointing to redirects.mdx
- Update next link in redirects.mdx to point to template-redirect-uris.mdx
- Add "Different redirect URL per organization" section in redirects.mdx
- Add logo file requirements in organization-branding.mdx (URL, formats, height)

* docs: add template redirect URIs asset and update SCIM quickstart diagram

* docs: improve template redirect URI guide with prose refinement and SDK examples

- Strengthen prose: add clarity that setting just one redirect URI is sufficient
- Add 'Set slug, metadata, or both' comments across all SDK language tabs
- Fix Go example with proper Metadata field and error handling
- Add screenshot assets documenting the redirect URI configuration

* docs: rename template-redirect-uris to org-redirect-urls with updated links

- Rename guides/dashboard/template-redirect-uris.mdx to org-redirect-urls.mdx
- Update sidebar config slug to org-redirect-urls
- Add URL redirect from old to new path
- Update redirects.mdx next link and cross-references
- Rename dashboard guide title to 'Configure redirect URLs'

* docs: remove unreferenced create-organization-slug-logo image

* docs: remove backward-compat redirect for template-redirect-uris (never released)

---------

Co-authored-by: amitash1912 <amit.ashish@scalekit.com>
Co-authored-by: Amit Ashish <amitashish@Amits-MacBook-Air.local>

* docs: add organization session policy documentation (#716)

- New guide: /authenticate/manage-organizations/organization-session-policy
- Cross-link from manage-session via consolidated Step 3 Aside
- Update hosted-widgets to surface session policy widget
- Sidebar entry under Manage users & orgs

* Add CrewAI cookbook, example page, and index entry (#702)

* docs(hubspot): optional scopes, app type guidance, and MCP connector sync (#718)

* add Adobe Marketing Agent MCP connector docs

* fix: use API display_name for connector auth types (OAuth 2.1/DCR for MCP connectors)

resolveAuthType was hardcoding 'OAuth 2.0' for all OAUTH providers.
The API already provides display_name ('OAuth 2.1/DCR' vs 'OAuth 2.0')
and is_mcp flag — now used directly.

Also updates generateAuthSection prose for MCP connectors to mention
DCR and PKCE instead of generic OAuth 2.0 redirect description.

Re-synced all connector pages to pick up the fix.

* fix: escape single quotes in connectorAuthType frontmatter value

* docs(hubspot): add optional scopes, app type guidance, and legacy app notes

* chore(docs): sync MCP connectors from prod catalog and fix duplicate clickhouse template

* revert: restore svg files unchanged from main

* fix: resolve coderabbit comments — fix duplicate googledwd heading, authType quoting, and broken anchor

* revert: restore svg files and org-redirect-urls.mdx to match main

* revert: restore sync-agent-connectors.js to match main

* chore(docs): re-sync agent connectors from prod catalog

---------

Co-authored-by: Saif Ali Shaik <saif.shaik@scalekit.com>

* Add AkshayParihar33 as code owner for MDX files (#720)

* Add AkshayParihar33 as code owner for MDX files

* Update CODEOWNERS comments to reflect current owner list

* Add xmcp quickstart guide for Scalekit MCP auth (#719)

* Add xmcp quickstart guide for Scalekit MCP auth

* Add pre-generated D2 diagram for xmcp quickstart

* Add xmcp quickstart to MCP Auth sidebar

* Update xmcp quickstart page title

* Add Mastra AgentKit cookbook (#703)

* Add Mastra AgentKit cookbook: build a Mastra agent with Scalekit tools

* Use second-person phrasing consistently in instructional text

* docs: replace {{slug}} with {{org_slug}} in redirect URL templates (#722)

Co-authored-by: Claude <noreply@anthropic.com>

* docs(agentkit): add meeting prep agent example to examples index (#724)

* feat(connectors): add hyperlink support in connector page descriptions (#727)

- Adds descriptionHtml frontmatter field and schema entry for connectors needing hyperlinks
- Connector page header and index cards render descriptionHtml via set:html when present
- Link styling inherits text color with underline for native appearance
- description-html.json stores overrides that survive connector regeneration
- sync-agent-connectors.js emits descriptionHtml when slug entry exists
- First implementation: Apify MCP connector links to https://mcp.apify.com

* docs(cookbook): FastRouter + Scalekit AgentKit tool-calling guide (#721)

* docs(cookbook): add FastRouter + Scalekit AgentKit tool-calling guide

* docs(cookbook): address CodeRabbit review feedback on FastRouter + AgentKit tool calling

* docs(cookbook): fix unused variables in Go example (fastrouter + AgentKit)

* Domain-verification: add Organization domains page and cross-links (#725)

* docs(domain-verification): add Organization domains page and cross-links

Adds a new "Organization domains" page covering DNS-based domain verification for SSO Home Realm Discovery and SCIM. Documents all four ways to add a domain (Admin Portal, Hosted Widgets, Dashboard, API), four new webhook events, and links the feature into existing SSO, JIT, SCIM, and Hosted Widgets pages.

Also fixes a pre-existing broken anchor in org-redirect-urls.mdx.

* docs(domain-verification): review feedback — reorder hosted widgets, update links and webhook payloads, remove check-sso-domain aside

* docs(domain-verification): add organization-domains screenshot assets

* docs(domain-verification): add SDK tabs for enable feature and portal link; reorganize onboard-enterprise-customers domain verification

* docs(domain-verification): complete SDK tabs expansion for enable feature and portal link endpoints

* chore: revert unrelated d2 svg regeneration from domain-verification PR

* Coderabbit comment fixes

* chore: remove orphan d2 svg for organization-domains (no diagram in source)

* Improvements

* docs: separate AgentKit and SaaSKit API references (SK-399)

- Refresh OpenAPI split from latest backend scalar (after PR 2191 / sk-422)
- Curate openapi/agentkit.yaml with real $ref entries for Connectors + full MCP surfaces
  (MCP, MCP Configurations, MCP Instances)
- Add production bundle scripts: bundle:agentkit, bundle:saaskit, bundle:apis
- Update tagsSorter in both AgentKit and unified All APIs Scalar pages to include new clean tags
- Replace unified scalar files (yaml + json) with fresh backend versions and remove temporary .new file
- Include new MCP and custom provider path files + schemas from fresh split
- Document deferred code samples for new surfaces (follow-up via scalekit-code-doctor per Option B)
- Production readiness pass: addressed review findings, verified bundles and separation

This closes the gaps between direct backend render and the docs pipeline for the new AgentKit surfaces.

* build: fix format:check and regenerate build artifacts after main merge

Reformats openapi/code_samples/javascript/** to match prettier config
(cosmetic only - tabs to spaces, no semicolons). Fixes one malformed
code sample (api_v1_organizations_{id}/get.js) that had invalid
placeholder syntax breaking prettier's parser. Regenerates
public/apis.md, agent-tools-index.json, and d2 diagram SVGs via the
normal build pipeline. pnpm run build now passes clean end to end.

* build: wire bundle:apis into build and stop checking generated apis.md

bundle:agentkit/bundle:saaskit now also emit the .json variant (needed
by the openapi-markdown integration, previously only .yaml was
produced and json was committed by hand). Wiring bundle:apis into the
build script means public/api/{agentkit,saaskit}.scalar.{yaml,json}
regenerate from openapi/ sources on every build instead of silently
drifting when someone forgets to run it manually.

Also excludes public/apis.md, public/agentkit/apis.md, and
public/saaskit/apis.md from prettier: they're regenerated fresh by
astro build every time (src/integrations/openapi-markdown.ts) after
format:check already ran, so checking their committed formatting is
pointless and was the actual cause of PR #706's Netlify build failure.

* docs(openapi): trim agentkit code samples to Node.js and Python only

Removes Go and Java x-codeSamples entries from api_v1_connected_accounts
and api_v1_execute_tool (the only two agentkit paths with samples so
far) and deletes the now-orphaned go/java source files. AgentKit only
needs Node.js and Python going forward.

* feat(openapi): add script to re-inject developer-docs code samples into combined spec

public/api/scalekit.scalar.{json,yaml} is manually copied from the
scalekit backend repo. Once backend removes its own x-codeSamples
injection pipeline, that copy will have no code samples at all — this
adds `pnpm run inject-code-samples` to backfill them from the same
openapi/code_samples/ files that already back the agentkit/saaskit
split bundles, so the combined /apis/ page stops depending on backend
for samples entirely.

Developer-docs samples take priority per language; languages with no
file here fall back to whatever the copied spec already had, so this
degrades gracefully whether backend still injects samples or not.

Documents the new required step in scripts/manual/API_REFERENCE_WORKFLOW.md.
Adds `yaml` as a direct devDependency for round-tripping the .yaml spec.

* build: add automated split-partition validation

Adds scripts/validate-api-split.js, wired into the build script right
after bundle:apis regenerates the split specs. Fails the build if the
agentkit/saaskit split ever stops being a clean partition of the
combined spec: an operation dropped from both, invented in a split, or
double-counted in both. Warns (non-fatal) on operations with no code
samples yet.

This is the mechanical check for "is the split still working" -
verified it correctly catches both a dropped operation and an
overlapping one before wiring it in.

* docs: document the agentkit/saaskit split workflow

Adds a section covering: the split isn't derived from the combined
spec anymore, how to add per-operation extensions (x-internal,
x-badges) and product-wide tags/info for agentkit.yaml/saaskit.yaml
directly, how to add a code sample, and the current gap where
inject-code-samples only backfills x-codeSamples on the combined page,
not other extensions.

* fix(api): restore user-by-external-id and MCP config sub-endpoints lost in merge

Four endpoints present in the current backend spec were missing from
the developer-docs API reference (combined and both splits):

- GET/PATCH/DELETE /api/v1/users:external/{external_id}          (SaaSKit)
- POST/PATCH/DELETE /api/v1/memberships/.../users:external/{external_id} (SaaSKit)
- POST /api/v1/mcp/configs/{config_id}/connected_accounts        (AgentKit)
- POST /api/v1/mcp/configs/{mcp_config_id}/tokens                (AgentKit)

Root cause: the first `git merge origin/main` on this branch resolved
the conflict on public/api/scalekit.scalar.{yaml,json} with --ours,
keeping the branch's older combined spec and discarding main's copy
which had users:external. The openapi/ split-source tree was stale the
same way. The branch was never refreshed from a current backend spec.

Fix (targeted, per the documented workflow — avoids a full re-split
that would wipe the code-sample $ref wiring): extracted the 4 missing
path files + 5 newly-referenced MCP component schemas from the current
backend spec via `redocly split`, added their $refs to the correct
product roots (users/memberships → saaskit.yaml, mcp → agentkit.yaml),
refreshed the combined public/api/scalekit.scalar.* from backend, and
re-ran inject-code-samples + bundle:apis.

Verified: combined path set now matches backend exactly (117 ops, was
109); validate-api-split passes as a clean partition (agentkit 30,
saaskit 87, overlap 0); full build passes.

* feat(openapi): replace exploded tree with Redocly plugin pipeline (SK-399)

- Add Redocly decorator plugin (openapi/plugins/scalekit.js) that filters
  operations by tag, injects x-codeSamples, and deep-merges overlay extensions
- Add product overlay files (openapi/extensions/{agentkit,saaskit,all}.yaml) for
  per-product tag filtering, curated tags, and info overrides
- Copy combined spec to openapi/scalekit.yaml as single source input
- Wire plugin in redocly.yaml with three API entries (agentkit, saaskit, all)
- Consolidate bundle:apis script to single redocly bundle command
- Delete ~350 superseded files: openapi/{paths,components,openapi.yaml}, old
  root specs (agentkit.yaml, saaskit.yaml), scripts/inject-code-samples.js
- Keep openapi/{webhooks,code_samples} for plugin consumption
- Validated: clean partition (107 ops = 20 agentkit + 87 saaskit, 0 overlap)
- Full build passes

* fix(openapi): prune tags with no operations from spec output

Empty tags (MCP, MCP Instances, ToolService) were declared in the backend
spec but had no operations (RPCs marked PREVIEW). Scalar rendered them as
empty sidebar sections. The plugin now strips tags that have zero surviving
operations after filtering.

* fix(nav): route API reference links to quickstart section

Link to #description/quickstart so users land on the quickstart guide
instead of the raw spec description when clicking API reference in the
secondary nav.

* fix(apis): remove stale MCP/MCP Instances from tag ordering arrays

MCP Servers and MCP Instances RPCs are marked PREVIEW in the backend and
excluded from the spec. Remove their entries from the tagsSorter arrays
in apis.astro and agentkit/apis.astro to keep the ordering config clean.

---------

Co-authored-by: Pranesh <praneshtaker@gmail.com>
Co-authored-by: srinivaskarre-sk <153999054+srinivaskarre-sk@users.noreply.github.com>
Co-authored-by: amitash1912 <amit.ashish@scalekit.com>
Co-authored-by: Amit Ashish <amitashish@Amits-MacBook-Air.local>
Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants