docs: improve multi-app and hosted widgets documentation#435
docs: improve multi-app and hosted widgets documentation#435saif-at-scalekit merged 7 commits intomainfrom
Conversation
- Update overview and manage-apps pages for clarity and organization - Improve hosted widgets documentation structure and content - Update SVG diagrams for multi-app and hosted-widgets - Update sidebar configuration See full changes in 2026-W7-hosted-widgets branch.
WalkthroughUpdated site navigation and documentation: sidebar label changed; multiple dev-kit code-samples paths moved to resources with redirects and secondary-nav updates; extensive rewrites of multi-app authentication docs (overview, manage-apps, SPA, web, native) and hosted-widgets to step-based flows with added Asides/PKCE/security guidance; small repo and YAML formatting edits. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
📝 Coding Plan
Comment |
saif-at-scalekit
requested review from
amitash1912 and
ravibits
as code owners
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx (1)
134-135:⚠️ Potential issue | 🟡 MinorUnintended horizontal rule between sections.
The
---on line 134 creates a horizontal rule, which appears unintentional between the Aside and the next section heading.Proposed fix
</Aside> ---- + ## Branding & customization🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx` around lines 134 - 135, Remove the unintended horizontal rule by deleting the standalone '---' line that precedes the "## Branding & customization" heading; ensure there's a single blank line between the Aside and the "## Branding & customization" heading so the section renders normally.
🧹 Nitpick comments (4)
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx (2)
53-87: Step content indentation should use 3 spaces, not 4.The Steps component content uses 4-space indentation throughout. Per guidelines, all step content must be indented with exactly 3 spaces to avoid parsing errors.
Example fix for first step (apply same pattern to all steps)
1. ### Manage organization settings - Your customers can view and manage their organization profile, including allowed email domains. Navigate to **Organization settings** to update organization details. + Your customers can view and manage their organization profile, including allowed email domains. Navigate to **Organization settings** to update organization details. -  + As per coding guidelines: "Each step in Steps component must use numbered format
1. ## Titlewith all step content indented with exactly 3 spaces" and "Aside components within Steps must be indented with 3 spaces to avoid Steps component parsing errors".Also applies to: 95-109
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx` around lines 53 - 87, The Steps component content uses 4-space indentation which violates the parsing rules; update every step block inside the Steps component so that all step body lines (including the Aside blocks and image links) are indented with exactly 3 spaces instead of 4, keeping the numbered step header format like "1. ### Manage organization settings" unchanged; locate the Steps component and fix indentation for each step body and each <Aside> block (e.g., the org_settings/org_member/org_sso/org_scim step blocks) and apply the same 3-space indentation pattern to the other offending block mentioned (lines ~95-109).
141-141: Heading capitalization inconsistency.The heading "Common Hosted Widgets scenarios" capitalizes "Hosted Widgets," but the page title uses "Hosted user management widgets" (lowercase). For consistency and sentence case guidelines, consider using lowercase unless "Hosted Widgets" is an official product name.
Proposed fix
-## Common Hosted Widgets scenarios +## Common hosted widgets scenariosAs per coding guidelines: "All headings in documentation files must use sentence casing (only the first word and any proper nouns are capitalized)".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx` at line 141, Change the heading "Common Hosted Widgets scenarios" to sentence case to match the document title and guidelines; replace it with "Common hosted user management widgets scenarios" (or "Common hosted widgets scenarios" if you prefer to match the page title "Hosted user management widgets") so the heading follows sentence casing and aligns with the page title; update the heading text where it appears as "Common Hosted Widgets scenarios".src/content/docs/authenticate/fsa/multiapp/overview.mdx (1)
101-109: Heading doesn't match content.The "Common scenarios" heading implies use cases, but the content describes troubleshooting steps for redirect URI mismatches, environment issues, session problems, and token rejection. Consider renaming to "Troubleshooting" or "Common issues" for clarity.
✏️ Suggested fix
-## Common scenarios +## Troubleshooting🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/fsa/multiapp/overview.mdx` around lines 101 - 109, The section header "## Common scenarios" is misleading because the following bullets are troubleshooting steps; update the heading text in the document where the literal "## Common scenarios" appears (in the multiapp overview content) to a clearer title such as "## Troubleshooting" or "## Common issues" so it matches the content about redirect URI mismatches, environment/session problems, and refresh token rejection.src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx (1)
99-102: Consider hyphenating compound adjectives.Per standard grammar rules, compound adjectives before a noun should be hyphenated: "Post-login URLs" and "Post-logout URLs".
✏️ Suggested fix
- - **Post login URLs**: Allowed values for `redirect_uri` used with `/oauth/authorize`. + - **Post-login URLs**: Allowed values for `redirect_uri` used with `/oauth/authorize`. - **Initiate login URL**: Where Scalekit redirects users when authentication starts outside your app. - - **Post logout URLs**: Where users are redirected after a successful logout. + - **Post-logout URLs**: Where users are redirected after a successful logout.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx` around lines 99 - 102, Update the compound adjectives to use hyphens: change the phrase "Post login URLs" to "Post-login URLs" and "Post logout URLs" to "Post-logout URLs" in the document (the lines defining allowed redirect_uri and logout redirect descriptions); ensure you only alter those visible phrases and keep the rest of the sentence unchanged.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
public/d2/docs/authenticate/fsa/multiapp/overview-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/manage-users-orgs/hosted-widgets-0.svgis excluded by!**/*.svg
📒 Files selected for processing (4)
src/configs/sidebar.config.tssrc/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
🧰 Additional context used
📓 Path-based instructions (7)
**/*.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. ## Titlewith 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/authenticate/manage-users-orgs/hosted-widgets.mdxsrc/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{md,mdx}: All code examples must include implementations in all 4 languages: Node.js, Python, Go, and Java
Include security comments in code examples explaining security threats and implications
Code examples must demonstrate both success and error paths
Frontmatter must include: title (≤60 characters), description (≤160 characters), sidebar label, order number, and tags array
Use second person ('you', 'your application') for writing voice in documentation
Use present tense for descriptions and imperative mood for instructions in documentation
**/*.{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...
Files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdxsrc/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/manage-users-orgs/hosted-widgets.mdxsrc/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
**/*.{js,ts,py,go,java,tsx,jsx}
📄 CodeRabbit inference engine (CLAUDE.md)
SDK variable names must follow language-specific conventions: Node.js uses
scalekit, Python usesscalekit_client, Go usesscalekitClient, Java usesscalekitClient
Files:
src/configs/sidebar.config.ts
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy,gradle,xml,json}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Comments should not duplicate the code - avoid comments that simply restate what the code does; comments should add value beyond what's obvious from reading the code
Files:
src/configs/sidebar.config.ts
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}: Good comments do not excuse unclear code - refactor the code to be self-explanatory instead of using comments to explain poorly written code; use better variable names, function names, and code structure
Comments should dispel confusion, not cause it - ensure comments clarify rather than obscure the code's purpose; avoid cryptic or joke comments
Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Provide links to the original source of copied code - always attribute code copied from external sources with URLs to Stack Overflow answers, GitHub repositories, or documentation
Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Add comments when fixing bugs - document bug fixes with context about the issue, reference issue trackers and bug reports, and explain workarounds and their limitations
Use comments to mark incomplete implementations - use standard formats for TODO, FIXME, and NOTE comments with context about what needs to be done and reference issue trackers when possible
Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements
Files:
src/configs/sidebar.config.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Use JSDoc standards for all function, class, and complex logic comments in JavaScript/TypeScript - include parameter descriptions (
@param), return values (@returns), types (@type), and descriptions; document exceptions and edge cases
Files:
src/configs/sidebar.config.ts
🧠 Learnings (16)
📓 Common learnings
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:72-179
Timestamp: 2026-02-02T05:55:51.251Z
Learning: In the `src/content/docs/authenticate/fsa/multiapp/` directory, the multi-app authentication documentation (native-app.mdx, single-page-app.mdx, web-app.mdx, overview.mdx) currently uses conceptual shell/curl examples instead of multi-language SDK code examples because the Scalekit SDKs have not yet been built/updated for multi-app functionality. Once the SDKs are ready, these files should be updated to include all 4 languages (Node.js, Python, Go, Java) using `<Tabs syncKey="tech-stack">`.
📚 Learning: 2026-01-30T18:20:07.851Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:1-6
Timestamp: 2026-01-30T18:20:07.851Z
Learning: In the scalekit-inc/developer-docs repository, MDX files under `src/content/docs/authenticate/fsa/multiapp/` do not use `order` or `tags` fields in their frontmatter. Ordering and grouping are managed centrally in `src/configs/sidebar.config.ts`.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdxsrc/configs/sidebar.config.ts
📚 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/authenticate/manage-users-orgs/hosted-widgets.mdxsrc/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/manage-users-orgs/hosted-widgets.mdxsrc/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-02-02T05:55:47.169Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:72-179
Timestamp: 2026-02-02T05:55:47.169Z
Learning: In the docs under src/content/docs/authenticate/fsa/multiapp/, once the Scalekit SDKs are ready, update the four MDX files (native-app.mdx, single-page-app.mdx, web-app.mdx, overview.mdx) to include multi-language SDK code examples for Node.js, Python, Go, and Java. Use a Tabs component with syncKey="tech-stack" to present the languages in a unified view, replacing the current shell/curl examples with equivalent code samples.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-01-30T18:20:02.309Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:1-6
Timestamp: 2026-01-30T18:20:02.309Z
Learning: For MDX files under src/content/docs/authenticate/fsa/multiapp/, do not include order or tags fields in the frontmatter. Ordering and grouping are managed centrally in src/configs/sidebar.config.ts. During reviews, verify that files in this directory omit frontmatter order and tags, and that any new or updated docs in this path align with the centralized sidebar configuration.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Start with an overview/value proposition and when to use the feature before detailed instructions
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use action-oriented headings in step-by-step guides within Steps components
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-02-02T08:57:31.739Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/single-page-app.mdx:0-0
Timestamp: 2026-02-02T08:57:31.739Z
Learning: Doc writers in the Scalekit repository should keep the term 'single page application' unhyphenated across all MDX files under src/content/docs/authenticate/fsa/multiapp (and related docs) to maintain a consistent style, even though standard grammar would hyphenate. Apply this exact phrasing in all relevant sections whenever referring to a SPA. If you encounter a compound adjective where 'single page application' would be used, write it as 'single page application' without a hyphen.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Set concise sidebar labels that match user vocabulary in navigation metadata
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-02-02T05:55:51.251Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:72-179
Timestamp: 2026-02-02T05:55:51.251Z
Learning: In the `src/content/docs/authenticate/fsa/multiapp/` directory, the multi-app authentication documentation (native-app.mdx, single-page-app.mdx, web-app.mdx, overview.mdx) currently uses conceptual shell/curl examples instead of multi-language SDK code examples because the Scalekit SDKs have not yet been built/updated for multi-app functionality. Once the SDKs are ready, these files should be updated to include all 4 languages (Node.js, Python, Go, Java) using `<Tabs syncKey="tech-stack">`.
Applied to files:
src/configs/sidebar.config.ts
🪛 LanguageTool
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
[grammar] ~99-~99: Use a hyphen to join words.
Context: ... ### Redirect URL types - Post login URLs: Allowed values for `redire...
(QB_NEW_EN_HYPHEN)
[grammar] ~101-~101: Use a hyphen to join words.
Context: ...ion starts outside your app. - Post logout URLs: Where users are redirecte...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (7)
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx (2)
1-11: LGTM on frontmatter and imports.The frontmatter follows guidelines with appropriate title length, description, sidebar label, and tags. The Steps import is correctly added alongside the existing Aside import.
112-133: LGTM on access management section.The permissions table is well-structured with clear purpose descriptions. The Aside explaining default roles and customization options provides helpful context.
src/configs/sidebar.config.ts (1)
68-68: LGTM!The label change from "Multi-App Authentication" to "Auth across multiple apps" is clearer and more user-friendly. It follows the sidebar label guidelines: concise (4 words), sentence case, and outcome-focused.
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx (1)
31-43: LGTM!The Steps component structure follows the correct format with numbered headings (
1. ## Title) and proper 3-space indentation. The Aside component is correctly nested within the step.src/content/docs/authenticate/fsa/multiapp/overview.mdx (3)
45-64: LGTM!The sequence diagram clearly illustrates the multi-app authentication flow, showing how users authenticate once and share sessions across applications. The logout flow correctly demonstrates session revocation propagation.
26-34: LGTM!The introduction effectively explains the value proposition of multi-app authentication with a concrete example, followed by clear benefits. The writing follows documentation guidelines with direct instructional style and present tense.
74-79: LGTM!The application types table provides a clear comparison with appropriate links to detailed guides. Column headers are concise and the content accurately describes each application type's characteristics.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx`:
- Line 56: The image alt text "Add MCP server" is misleading; locate every
Markdown image occurrence using the exact token "![Add MCP server]" in this file
(instances shown around the image tags) and replace it with accurate alt text
that reflects the screenshots—e.g., use "Create web application modal" for the
web app creation modal image and similar descriptive phrases for the other
images (e.g., "Multi-app list", "App settings modal", "Add application form") so
each image's alt attribute describes its actual content.
In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx`:
- Line 59: The image tags like
"" (and the other occurrences
referencing assets in hosted-widgets, e.g., org_settings.png and the images at
the other noted positions) are missing alt text; update each markdown image to
include meaningful alt text and a brief caption/contextual sentence nearby
(e.g., replace "" with
"" and add a short one-line
description below the image) to satisfy accessibility guidelines.
---
Outside diff comments:
In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx`:
- Around line 134-135: Remove the unintended horizontal rule by deleting the
standalone '---' line that precedes the "## Branding & customization" heading;
ensure there's a single blank line between the Aside and the "## Branding &
customization" heading so the section renders normally.
---
Nitpick comments:
In `@src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx`:
- Around line 99-102: Update the compound adjectives to use hyphens: change the
phrase "Post login URLs" to "Post-login URLs" and "Post logout URLs" to
"Post-logout URLs" in the document (the lines defining allowed redirect_uri and
logout redirect descriptions); ensure you only alter those visible phrases and
keep the rest of the sentence unchanged.
In `@src/content/docs/authenticate/fsa/multiapp/overview.mdx`:
- Around line 101-109: The section header "## Common scenarios" is misleading
because the following bullets are troubleshooting steps; update the heading text
in the document where the literal "## Common scenarios" appears (in the multiapp
overview content) to a clearer title such as "## Troubleshooting" or "## Common
issues" so it matches the content about redirect URI mismatches,
environment/session problems, and refresh token rejection.
In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx`:
- Around line 53-87: The Steps component content uses 4-space indentation which
violates the parsing rules; update every step block inside the Steps component
so that all step body lines (including the Aside blocks and image links) are
indented with exactly 3 spaces instead of 4, keeping the numbered step header
format like "1. ### Manage organization settings" unchanged; locate the Steps
component and fix indentation for each step body and each <Aside> block (e.g.,
the org_settings/org_member/org_sso/org_scim step blocks) and apply the same
3-space indentation pattern to the other offending block mentioned (lines
~95-109).
- Line 141: Change the heading "Common Hosted Widgets scenarios" to sentence
case to match the document title and guidelines; replace it with "Common hosted
user management widgets scenarios" (or "Common hosted widgets scenarios" if you
prefer to match the page title "Hosted user management widgets") so the heading
follows sentence casing and aligns with the page title; update the heading text
where it appears as "Common Hosted Widgets scenarios".
|
@coderabbitai please approve |
|
🧠 Learnings used✅ Actions performedComments resolved. Auto-approval is disabled; enable |
Co-Authored-By: Oz <oz-agent@warp.dev>
saif-at-scalekit
force-pushed
the
2026-W7-multiapp-hosted-widgets
branch
from
8e8e8cc to
adb0fbe
Compare
Update /sso/quickstart to /authenticate/auth-methods/enterprise-sso/ in native-app, single-page-app, and web-app guides. Co-Authored-By: Oz <oz-agent@warp.dev>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx`:
- Around line 111-118: The doc uses inconsistent variants ("Back channel logout
URL", "Back channel logout", "backchannel logout"); update all occurrences in
this file to the hyphenated compound form "back-channel logout" (e.g., change
the heading/label "Back channel logout URL" to "Back-channel logout URL", change
the Aside title and body text "Back channel logout" to "Back-channel logout",
and replace "backchannel logout" with "back-channel logout") so the terminology
is consistent with OAuth/OIDC compound modifier conventions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8d9d3bfa-029a-4fd4-ac58-2adac793cbd3
📒 Files selected for processing (7)
.cursor/rules/expressive-code.mdc.gitignoresrc/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (6)
**/*.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. ## Titlewith 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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
⚙️ CodeRabbit configuration file
**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:Frontmatter
titleMUST be ≤ 60 characters and clearly state what the page does.descriptionMUST be ≤ 160 characters, action-oriented, unique per page.sidebar.labelMUST be present and ≤ 30 characters.sidebar.orderMUST 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/nextlinks 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).
- No heading should end with a colon or period.
Content structure
- How-to guides MUST contain numbered
<Steps>(Starlight component).- 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:frontmatter link, a<LinkCard>, or an explicit paragraph
pointing the reader forward in the sidebar journey.Code examples
- ALL code examples that show SDK usage MUST include all four language
tabs: Node.js, Python, Go, Java — using<Tabs syncKey="tech-stack">.- SDK variable names are STRICTLY:
scalekit(Node.js),
scalekit_client(Python),scalekitClient(Go), ...
Files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
src/content/docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
src/content/docs/**/*.{md,mdx}: Product-based documentation (MCP Auth, Agent Auth, Full Stack Auth, Modular SCIM, Modular SSO) MUST follow a journey-focused approach. Each product represents a developer's journey toward implementing authentication in their projects.
Proactively address common setup and configuration problems. Keep code examples simple, self-contained, and exportable.
Use imperative for procedures: 'Install', 'Create', 'Run', 'Configure', 'Test'. Front-load the action and start sentences with the verb or key concept.
Explain why when useful. Briefly justify non-obvious steps. Prefer examples over theory; show the common path first and link to details.
Every page MUST include frontmatter with at least:title(≤60 characters),description(≤160 characters), andsidebar.label(1-3 words). Usesidebar.orderonly when navigation ordering matters. Useprev/nextfor sequential guides; useseeAlsofor related guides. EnabletableOfContentsfor longer pages with multiple major sections.
Opening paragraphs (1-3) MUST state what users will accomplish, when/why they need it, and preview the workflow using direct instructional language
The Steps component requires a single continuous ordered list. Steps must start at column 0 with no leading spaces. Continuation content (images, text) must be indented with exactly 3 spaces. Sub-bullet lists use 3 spaces with no blank line before bullets. No blank line immediately after Steps opening tag.
Documentation must be organized into logical sections (FSA, SSO, Directory/SCIM, Connect, M2M, Guides, Reference) with proper sidebar configuration and navigation structure
Files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
src/content/docs/authenticate/fsa/multiapp/**/*.mdx
⚙️ CodeRabbit configuration file
src/content/docs/authenticate/fsa/multiapp/**/*.mdx: This page is part of the multiapp section. Skip sidebar.order and tags checks.
Apply all other global MDX rules (title, description, voice, style, code examples, etc.).
Ordering is centralized in src/configs/sidebar.config.ts.
Files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
src/content/docs/authenticate/**/*.mdx
⚙️ CodeRabbit configuration file
src/content/docs/authenticate/**/*.mdx: This page lives in the primary authentication section.
- If it's a quickstart or step-based guide, it MUST use
<Steps>.- Auth method pages (passwordless, social, SSO, passkeys) MUST include
a brief "when to use this" section before the implementation steps.- Any reference to tokens (idToken, accessToken, refreshToken) MUST
clarify: what it contains, its lifetime, and how to use it securely.- The FSA quickstart (
authenticate/fsa/quickstart.mdx) is the
canonical entry point — no other page should duplicate its 5-step
install→redirect→callback→session→logout structure.
Files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
🧠 Learnings (57)
📓 Common learnings
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 0
File: :0-0
Timestamp: 2026-03-13T04:24:59.653Z
Learning: In scalekit-inc/developer-docs, for PRs focused on tooling and templatizing (e.g., extracting usage sections into reusable MDX templates and updating sync scripts), review comments about .mdx file content quality (casing, unused imports, import consolidation, endpoint descriptions, etc.) are considered out of scope and should be resolved without blocking the PR.
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:72-179
Timestamp: 2026-02-02T05:55:51.251Z
Learning: In the `src/content/docs/authenticate/fsa/multiapp/` directory, the multi-app authentication documentation (native-app.mdx, single-page-app.mdx, web-app.mdx, overview.mdx) currently uses conceptual shell/curl examples instead of multi-language SDK code examples because the Scalekit SDKs have not yet been built/updated for multi-app functionality. Once the SDKs are ready, these files should be updated to include all 4 languages (Node.js, Python, Go, Java) using `<Tabs syncKey="tech-stack">`.
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Product-based documentation (MCP Auth, Agent Auth, Full Stack Auth, Modular SCIM, Modular SSO) MUST follow a journey-focused approach. Each product represents a developer's journey toward implementing authentication in their projects.
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Documentation must be organized into logical sections (FSA, SSO, Directory/SCIM, Connect, M2M, Guides, Reference) with proper sidebar configuration and navigation structure
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 476
File: src/content/docs/guides/integrations/sso-integrations/okta-oidc.mdx:84-99
Timestamp: 2026-03-10T12:26:38.439Z
Learning: In scalekit-inc/developer-docs, integration guide pages under `src/content/docs/guides/integrations/` (including SSO integrations, SCIM integrations, and social connections) do not require a "what's next" signal, "Next steps" section, or concluding navigation links. Do not flag the absence of these elements on integration guide pages.
📚 Learning: 2026-02-02T05:55:47.169Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:72-179
Timestamp: 2026-02-02T05:55:47.169Z
Learning: In the docs under src/content/docs/authenticate/fsa/multiapp/, once the Scalekit SDKs are ready, update the four MDX files (native-app.mdx, single-page-app.mdx, web-app.mdx, overview.mdx) to include multi-language SDK code examples for Node.js, Python, Go, and Java. Use a Tabs component with syncKey="tech-stack" to present the languages in a unified view, replacing the current shell/curl examples with equivalent code samples.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-03-03T10:47:47.162Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Product-based documentation (MCP Auth, Agent Auth, Full Stack Auth, Modular SCIM, Modular SSO) MUST follow a journey-focused approach. Each product represents a developer's journey toward implementing authentication in their projects.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-03-03T10:47:47.162Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Documentation must be organized into logical sections (FSA, SSO, Directory/SCIM, Connect, M2M, Guides, Reference) with proper sidebar configuration and navigation structure
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-03-03T10:47:47.162Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Opening paragraphs (1-3) MUST state what users will accomplish, when/why they need it, and preview the workflow using direct instructional language
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Start with an overview/value proposition and when to use the feature before detailed instructions
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-03-03T10:47:47.162Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to **/*.{md,mdx} : Every documentation page MUST fit one primary type and follow its recommended structure: How-to Guide (Overview, Prerequisites, Procedure with Steps, Verify, Next Steps, FAQs), API Reference (Endpoint Summary, Authentication, Base URL, Parameters, Request, Response, Errors), Concept Page (Overview, How it works, Key concepts, Use cases, Trade-offs, Best practices, Related guides), or Release Notes/Change Log (Summary, change sections, Breaking changes, Migration guide, Upgrade instructions).
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-03-10T10:38:35.371Z
Learnt from: Pranesh-Raghu
Repo: scalekit-inc/developer-docs PR: 475
File: src/components/templates/agent-connectors/_setup-confluence.mdx:16-16
Timestamp: 2026-03-10T10:38:35.371Z
Learning: In `src/components/templates/agent-connectors/_setup-*.mdx` files, empty alt text `![]()` for redirect URI screenshots (e.g., `use-own-credentials-redirect-uri.png`) is a deliberate and consistent pattern across all connector setup template files. Do not flag missing alt text on these images in future reviews of files under `src/components/templates/agent-connectors/`.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-03-10T10:38:36.402Z
Learnt from: Pranesh-Raghu
Repo: scalekit-inc/developer-docs PR: 475
File: src/components/templates/agent-connectors/_setup-clickup.mdx:17-17
Timestamp: 2026-03-10T10:38:36.402Z
Learning: In `src/components/templates/agent-connectors/_setup-*.mdx` template files, empty alt text `![]()` is the established pattern for redirect URI screenshot images. Do not flag missing alt text on `![]()` markdown image syntax in these agent connector setup template files.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-03-12T16:29:33.506Z
Learnt from: Pranesh-Raghu
Repo: scalekit-inc/developer-docs PR: 483
File: src/components/templates/agent-connectors/_setup-bigquery.mdx:28-28
Timestamp: 2026-03-12T16:29:33.506Z
Learning: In `src/components/templates/agent-connectors/_setup-*.mdx` files, empty alt text (`![]()`) is acceptable for ALL inline images (not just redirect URI screenshots), including API-enablement screenshots such as `enable-bigquery-api.png`. Do not flag missing alt text for any inline image in these agent-connector setup template files.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Provide meaningful alt text for images in documentation
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-03-10T10:37:49.873Z
Learnt from: Pranesh-Raghu
Repo: scalekit-inc/developer-docs PR: 475
File: src/components/templates/agent-connectors/_setup-asana.mdx:15-15
Timestamp: 2026-03-10T10:37:49.873Z
Learning: In `src/components/templates/agent-connectors/`, all connector setup MDX files (e.g., _setup-asana.mdx, _setup-clickup.mdx, _setup-confluence.mdx, _setup-googlecalendar.mdx, _setup-intercom.mdx, _setup-monday.mdx, _setup-notion.mdx, _setup-zoom.mdx) intentionally use a single shared redirect URI screenshot (`use-own-credentials-redirect-uri.png` located under `@/assets/docs/agent-connectors/<connector-name>/`) for all redirect URI-related steps, even when steps show different UIs (e.g., Scalekit dashboard vs. the third-party console). Do not flag reuse of this image across multiple steps within the same connector file as an issue.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Reference images in MDX files with proper paths using `@/assets/docs/` prefix and include alt text
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Always include alt text and brief context near images in documentation
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-03-03T10:47:47.162Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to **/*.{md,mdx} : Use descriptive link text like 'See permission flags' not 'click here'. Prefer relative links for internal pages; include anchors for sections. Reference APIs consistently with backticks for code.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 Learning: 2026-03-12T16:26:46.707Z
Learnt from: Pranesh-Raghu
Repo: scalekit-inc/developer-docs PR: 483
File: src/components/templates/agent-connectors/_setup-bigquery.mdx:18-22
Timestamp: 2026-03-12T16:26:46.707Z
Learning: In `src/components/templates/agent-connectors/`, it is acceptable and intentional to reuse shared Google OAuth screenshots stored under `@/assets/docs/agent-connectors/gmail/` (e.g., `oauth-web-app.png`, `add-redirect-uri.png`) in other Google-service connector templates (e.g., `_setup-bigquery.mdx`, `_setup-google-ads.mdx`, etc.). Do not flag cross-connector image path reuse within the Google service connectors as an issue.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
📚 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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-03-10T12:26:38.439Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 476
File: src/content/docs/guides/integrations/sso-integrations/okta-oidc.mdx:84-99
Timestamp: 2026-03-10T12:26:38.439Z
Learning: In scalekit-inc/developer-docs, integration guide pages under `src/content/docs/guides/integrations/` (including SSO integrations, SCIM integrations, and social connections) do not require a "what's next" signal, "Next steps" section, or concluding navigation links. Do not flag the absence of these elements on integration guide pages.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-01-30T18:20:02.309Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:1-6
Timestamp: 2026-01-30T18:20:02.309Z
Learning: For MDX files under src/content/docs/authenticate/fsa/multiapp/, do not include order or tags fields in the frontmatter. Ordering and grouping are managed centrally in src/configs/sidebar.config.ts. During reviews, verify that files in this directory omit frontmatter order and tags, and that any new or updated docs in this path align with the centralized sidebar configuration.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-02-02T08:57:31.739Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/single-page-app.mdx:0-0
Timestamp: 2026-02-02T08:57:31.739Z
Learning: Doc writers in the Scalekit repository should keep the term 'single page application' unhyphenated across all MDX files under src/content/docs/authenticate/fsa/multiapp (and related docs) to maintain a consistent style, even though standard grammar would hyphenate. Apply this exact phrasing in all relevant sections whenever referring to a SPA. If you encounter a compound adjective where 'single page application' would be used, write it as 'single page application' without a hyphen.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.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/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdxsrc/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-03-12T05:02:13.454Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 487
File: src/content/docs/agent-auth/connections.mdx:0-0
Timestamp: 2026-03-12T05:02:13.454Z
Learning: In `src/content/docs/agent-auth/connections.mdx` (and Agent Auth docs in general), custom authentication (username/password/bearer-token flows) is intentionally out of scope for the current Agent Auth release. Do not flag the absence of custom authentication documentation in Agent Auth connection-type sections.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/web-app.mdxsrc/content/docs/authenticate/fsa/multiapp/native-app.mdx
📚 Learning: 2026-03-12T05:02:13.454Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 487
File: src/content/docs/agent-auth/connections.mdx:0-0
Timestamp: 2026-03-12T05:02:13.454Z
Learning: In `src/content/docs/agent-auth/connections.mdx` (and Agent Auth docs generally), custom authentication (username/password/bearer-token flows) is intentionally out of scope for the current Agent Auth release. Do not flag the absence of custom authentication connection type documentation in Agent Auth connection-type sections.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/web-app.mdx
📚 Learning: 2026-03-03T10:47:47.162Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to **/*.{md,mdx} : All technical content must be validated through testing. Security implications must be clearly documented. API examples must be current and functional. Authentication and integration examples must follow security best practices.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/web-app.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Include context comments explaining what's happening in code: '// Extract encrypted tokens from request cookies', '// Decrypt the access token before validation'
Applied to files:
src/content/docs/authenticate/fsa/multiapp/native-app.mdxsrc/content/docs/authenticate/fsa/multiapp/single-page-app.mdx
📚 Learning: 2026-03-03T10:47:47.162Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to **/*.{md,mdx} : Security comments MUST state the threat, why the pattern is required, and what can go wrong if omitted. Token examples SHOULD use tabs to separate decoded ID token and access token payloads.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/native-app.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.mdx : Use Aside component for notes, warnings, and tips in MDX documentation
Applied to files:
src/content/docs/authenticate/fsa/multiapp/single-page-app.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use Aside components for important notes, tips, and warnings in MDX documentation
Applied to files:
src/content/docs/authenticate/fsa/multiapp/single-page-app.mdx
📚 Learning: 2026-03-03T10:47:47.162Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to src/content/docs/guides/integrations/**/*.{md,mdx} : Integration guides in `src/content/docs/guides/integrations/` MUST be kept synchronized with their index pages: `src/content/docs/guides/integrations/index.mdx`, `src/content/docs/guides/integrations/sso-integrations/index.mdx`, `src/content/docs/guides/integrations/social-connections/index.mdx`, and `src/content/docs/guides/integrations/scim-integrations/index.mdx`.
Applied to files:
src/content/docs/authenticate/fsa/multiapp/overview.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use Expressive Code annotation methods: line numbers `{1,3,5-7}`, text matching `"exact text"`, regex patterns `/pattern/`, diff syntax `+/-` prefixes
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-03-03T10:47:47.162Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to **/*.{md,mdx} : Use language tabs with clear framework titles. Use Expressive Code features (line highlighting, collapse, wrap, frame="terminal", markers). Keep examples full and working: include imports (collapsible if noisy), realistic data, success and error paths.
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Use Expressive Code consistently across all documentation pages, preferring Starlight's `<Code>` component for rich features (titles, markers, accurate syntax highlighting) and dynamic snippets over fenced code blocks
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Follow comment standards in code examples and document the 'why' rather than the obvious 'what'
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Keep code examples minimal and runnable; avoid extraneous comments and explain intent above or below the block instead of inline
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Update code examples when APIs or behaviors change
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use Expressive Code marker types: 'mark' for neutral highlighting, 'ins' for insertions (green), 'del' for deletions (red)
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Keep code block annotations brief and purposeful - annotate only what matters
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:47:33.407Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/comment-standards.mdc:0-0
Timestamp: 2026-01-13T12:47:33.407Z
Learning: Applies to **/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy} : Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-03-13T04:24:59.653Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 0
File: :0-0
Timestamp: 2026-03-13T04:24:59.653Z
Learning: In scalekit-inc/developer-docs, for PRs focused on tooling and templatizing (e.g., extracting usage sections into reusable MDX templates and updating sync scripts), review comments about .mdx file content quality (casing, unused imports, import consolidation, endpoint descriptions, etc.) are considered out of scope and should be resolved without blocking the PR.
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-02-25T03:34:46.151Z
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:46.151Z
Learning: Import `Code` from 'astrojs/starlight/components' only when the MDX file actually uses the `<Code>` component. If the file uses only fenced code blocks (```), the Code import is not required.
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.mdx : Prefer `<Code>` component when code snippets need any of: filename/title, text markers, programmatic/dynamic content, or consistent theming across tabs
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Every code example must have a language specified (via `lang` prop in `<Code>` component or fenced language identifier)
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-03-03T10:47:47.162Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-03T10:47:47.162Z
Learning: Applies to **/*.{md,mdx} : Prefer fenced code blocks with language identifiers for all code; never use screenshots of code. Ensure code examples are runnable (or clearly marked as placeholders) and include error handling where appropriate.
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.mdx : Provide a `title` prop to the `<Code>` component when the snippet represents a file
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Keep code examples minimal, runnable, and focused on one concept
Applied to files:
.cursor/rules/expressive-code.mdc
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Fenced code blocks are acceptable for simple, static examples in Markdown/MDX, but always include a language identifier
Applied to files:
.cursor/rules/expressive-code.mdc
🪛 LanguageTool
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx
[grammar] ~117-~117: Use a hyphen to join words.
Context: ... Native applications cannot receive back channel logout notifications because the...
(QB_NEW_EN_HYPHEN)
src/content/docs/authenticate/fsa/multiapp/single-page-app.mdx
[grammar] ~30-~30: Use a hyphen to join words.
Context: ...en management, and logout in your single page application (SPA) using Authorizati...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (13)
.gitignore (1)
44-48: Ignore additions look correct and safe.These patterns are appropriate for local agent/tool artifacts and should reduce repo noise without affecting tracked source files.
.cursor/rules/expressive-code.mdc (2)
45-45: LGTM! Clear and actionable guideline for single-line snippets.This addition provides specific, helpful guidance for formatting single-line code snippets. The recommendation to disable line numbers and enable wrapping for single-line snippets improves readability and is consistent with Expressive Code's features.
47-47: Good normalization of quote style.Standardizing to regular quotes improves consistency across the technical documentation.
src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx (1)
57-57: Image alt text has been updated but could be more descriptive.The alt text has been improved from the previous "Add MCP server" placeholder. The current alt text describes the images appropriately:
- Line 57: "Create application modal showing app name and type selection"
- Line 77: "Application details page with configuration options"
- Line 94: "Client credentials section showing Client ID and secret management"
- Line 100: "SPA client ID section without client secret option"
- Line 113: "Redirect URLs configuration tab with URL types"
- Line 127: "Delete application button at bottom of configuration page"
These are accurate and descriptive.
Also applies to: 77-77, 94-94, 100-100, 113-113, 127-127
src/content/docs/authenticate/fsa/multiapp/web-app.mdx (2)
30-34: Well-structured introduction with clear value proposition.The opening paragraph effectively states what users will accomplish, explains when/why web apps use
client_secret, and previews the key topics covered. The tip linking to example apps provides immediate hands-on resources.
81-85: Security documentation is thorough and well-placed.The Aside notes effectively explain:
- Why web apps can safely use
client_secret(Line 81-85)- Why logout must be a browser redirect (Line 178-182)
These follow the guideline to explain the "why" with security implications clearly documented.
Also applies to: 178-182
src/content/docs/authenticate/fsa/multiapp/single-page-app.mdx (2)
30-30: Unhyphenated "single page application" is intentional.The static analysis flagged "single page application" for hyphenation, but this is the established style in this repository. Based on learnings, doc writers should keep the term unhyphenated across all MDX files in the multiapp section to maintain consistent style.
214-236: Excellent token storage security guidance.The token storage section provides:
- Clear comparison table of storage options with security trade-offs
- Actionable recommendations for high-security applications
- Strong caution about local storage risks
This follows best practices for documenting security implications with clear threat explanations.
src/content/docs/authenticate/fsa/multiapp/native-app.mdx (2)
94-98: Clear PKCE rationale for native apps.The Aside effectively explains why native apps cannot use
client_secret(binary extraction risk) and how PKCE protects against authorization code interception by device malware. This follows the guideline to document the threat, why the pattern is required, and what can go wrong.
232-250: Comprehensive platform-specific token storage guidance.The storage recommendations cover all major platforms with appropriate secure storage mechanisms. The caution about never embedding secrets in application binaries reinforces the PKCE requirement explained earlier and provides actionable guidance for backend API scenarios.
src/content/docs/authenticate/fsa/multiapp/overview.mdx (3)
27-33: Strong opening that clearly establishes value and scope.The introduction effectively:
- States what users will accomplish (shared authentication across apps)
- Explains when to use this (multiple apps, centralized session control)
- Previews key benefits (clearer audit logs, safer scope boundaries)
The LinkButton provides direct access to example implementations.
70-81: Clear application types comparison table.The table effectively differentiates between app types with:
- Direct links to detailed implementation guides
- Clear indicators for backend/secret usage
- Appropriate auth flow recommendations
The follow-up paragraph reinforces the benefit of separate clients while explaining they share the same session.
101-137: Helpful troubleshooting FAQ section.The collapsible FAQ format provides quick answers to common integration issues without cluttering the main content. Each answer is concise and actionable, helping developers quickly diagnose problems.
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/configs/sidebar.config.ts (1)
560-584:⚠️ Potential issue | 🟠 Major
dev-kittopic mapping is currently shadowed by the resources catch-all.Because matching is first-hit (as documented in this file), Line 572 (
'/**/*') captures/dev-kit/*before thedev-kittopic block at Lines 576-584. That makes the newdev-kittopic rules effectively unreachable for topic-based resolution.Suggested fix
resources: [ '/resources/code-samples/**/*', '/guides/integrations/**/*', '/authenticate/implement-workflows/**/*', '/authenticate/interceptors/**/*', '/reference/admin-portal/**/*', '/guides/webhooks-best-practices', '/reference/interceptors/**/*', '/guides/**/*', '/browse/**/*', '/reference/**/*', '/cookbooks', '/cookbooks/**/*', - '/**/*', // Catch-all: anything not matched above defaults here ], // === Developer Kit (tools, code, SDKs, AI helpers) === 'dev-kit': [ '/dev-kit/tools/**/*', '/dev-kit/sdks/**/*', '/dev-kit/ai-assisted-development/**/*', '/dev-kit/resources/**/*', '/dev-kit/build-with-ai/**/*', '/dev-kit/api-collections/**/*', '/dev-kit/**/*', ], + + // keep catch-all last so specific topics can match first + resources: [ + '/resources/code-samples/**/*', + '/guides/integrations/**/*', + '/authenticate/implement-workflows/**/*', + '/authenticate/interceptors/**/*', + '/reference/admin-portal/**/*', + '/guides/webhooks-best-practices', + '/reference/interceptors/**/*', + '/guides/**/*', + '/browse/**/*', + '/reference/**/*', + '/cookbooks', + '/cookbooks/**/*', + '/**/*', + ],Based on learnings: Navigation is configured via
src/configs/sidebar.config.ts; changes must preserve correct routing behavior across navigation mappings.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/configs/sidebar.config.ts` around lines 560 - 584, The 'dev-kit' topic block is unreachable because the preceding catch-all pattern '/**/*' captures everything first; move the catch-all ('/**/*') after the 'dev-kit' array so topic-based matching is first-hit and 'dev-kit' entries (e.g., '/dev-kit/tools/**/*', '/dev-kit/**/*') are evaluated before the catch-all, ensuring the 'dev-kit' topic mapping is not shadowed.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@src/configs/sidebar.config.ts`:
- Around line 560-584: The 'dev-kit' topic block is unreachable because the
preceding catch-all pattern '/**/*' captures everything first; move the
catch-all ('/**/*') after the 'dev-kit' array so topic-based matching is
first-hit and 'dev-kit' entries (e.g., '/dev-kit/tools/**/*', '/dev-kit/**/*')
are evaluated before the catch-all, ensuring the 'dev-kit' topic mapping is not
shadowed.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: a94c0aa7-9977-4a9d-8ee2-c836fe05e29e
📒 Files selected for processing (13)
src/configs/redirects.config.tssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.tssrc/content/docs/authenticate/fsa/multiapp/manage-apps.mdxsrc/content/docs/authenticate/mcp/intro-to-mcp-auth.mdxsrc/content/docs/authenticate/mcp/quickstart.mdxsrc/content/docs/index.mdxsrc/content/docs/resources/code-samples/agent-auth.mdxsrc/content/docs/resources/code-samples/code-samples.mdxsrc/content/docs/resources/code-samples/full-stack-auth.mdxsrc/content/docs/resources/code-samples/mcp-auth.mdxsrc/content/docs/resources/code-samples/modular-scim.mdxsrc/content/docs/resources/code-samples/modular-sso.mdx
1 participant
See full changes in 2026-W7-hosted-widgets branch.
Summary by CodeRabbit
Documentation
Chores
Style