docs: improve multi-app and hosted widgets documentation#435
docs: improve multi-app and hosted widgets documentation#435saif-at-scalekit wants to merge 1 commit 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.
📝 WalkthroughWalkthroughThis PR updates authentication documentation and renames a sidebar label. Changes include rewriting multi-app authentication guides with improved step-based workflows using the Steps component, restructuring the overview documentation with modified sequence diagrams, reorganizing hosted widgets documentation with new UI patterns, and updating the sidebar label from "Multi-App Authentication" to "Auth across multiple apps". Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
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".
| - **Native Application**: Desktop or mobile apps. Public clients with PKCE enforced. | ||
|
|
||
|  | ||
|  |
There was a problem hiding this comment.
Image alt text is misleading.
The alt text says "Add MCP server" but this image shows multi-app web application creation. Update the alt text to describe the actual content, such as "Create web application modal" or similar.
This same issue appears in all image references in this file (lines 56, 74, 85, 91, 104, 114).
🔧 Suggested fixes for all images
- 
+ - 
+ - 
+ - 
+ - 
+ - 
+ 📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
|  | |
|  |
🤖 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` at 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.
| Your customers can view and manage their organization profile, including allowed email domains. Navigate to **Organization settings** to update organization details. | ||
|
|
||
| ### Member management | ||
|  |
There was a problem hiding this comment.
Add alt text to all images for accessibility.
All image references are missing alt text. Per guidelines, always include descriptive alt text for images in documentation.
Proposed fix for image alt text
- 
+ - 
+ - 
+ - 
+ - 
+ - 
+ As per coding guidelines: "Always include alt text and brief context near images in documentation" and "Provide meaningful alt text for images in documentation".
Also applies to: 65-65, 75-75, 85-85, 101-101, 107-107
🤖 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
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.
1 participant
See full changes in 2026-W7-hosted-widgets branch.
Summary by CodeRabbit