docs: clarify Hosted widgets as SaaSKit portal vs Admin portal (SK-972)#817
docs: clarify Hosted widgets as SaaSKit portal vs Admin portal (SK-972)#817saif-at-scalekit wants to merge 7 commits into
Conversation
Rewrite Hosted widgets so developers know it is a redirect-based /ui/ portal (session, permissions, branding, no deep links/embeds), and cross-link Admin portal and organization domains for magic-link/iframe vs logged-in self-serve.
saif-at-scalekit
requested review from
AkshayParihar33,
amitash1912 and
ravibits
as code owners
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThis PR revises Hosted UI widgets documentation, adds scenario guidance, and updates related domain verification and Admin portal references. ChangesHosted Widgets Doc Rewrite
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Restore customer-problem openers, Steps-based module sections, and consistent Hosted UI widgets naming. Keep SaaSKit session, Admin portal comparison, and FAQ clarifications without competitive or roadmap tone.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx`:
- Around line 106-108: The hosted-widgets docs mention access and refresh tokens
without the required inline clarification. Update the affected prose in the
relevant docs section(s) and any repeated token references so each mention
explicitly states what the token contains, how long it is valid, and that it
must be handled securely; use the surrounding auth/session guidance in
hosted-widgets.mdx to keep the explanation consistent.
- Line 132: The hosted-widgets documentation contains several image markdown
entries in the content section that use empty alt text, so update each affected
image to include a descriptive alt string instead of `![]()`. Use the existing
correctly written image examples in this doc as the pattern, and fix the images
referenced by the hosted-widgets content near the org settings screenshots so
every `img`-style markdown entry has meaningful alt text.
- Around line 101-106: The “Integrate the portal” procedure is a sequential
setup flow but is currently written as a plain numbered Markdown list. Update
the content in hosted-widgets.mdx to wrap these steps in the existing <Steps>
component and keep the same four items inside it, following the pattern used by
other step-based docs. Refer to the “Integrate the portal” section and its
ordered list so the structure is corrected without changing the wording.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: f2fe9afe-0f4c-466e-bbdf-37aed0d5d666
📒 Files selected for processing (3)
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdxsrc/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdx
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: Redirect rules - scalekit-starlight
- GitHub Check: Header rules - scalekit-starlight
- GitHub Check: Pages changed - scalekit-starlight
🧰 Additional context used
📓 Path-based instructions (10)
**/*.mdx
📄 CodeRabbit inference engine (.cursorrules)
**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component:1. ## 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/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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).
- Headings that match a real API parameter, method, or field name
(e.g.,contactID,xero_tenant_id,executeTool) should preserve
the original casing. Do NOT flag these as sentence-case violations.- No heading should end with a colon or period.
Content structure
- Journey how-to guides MUST contain numbered
<Steps>(Starlight
component). This does NOT apply tosrc/content/docs/cookbooks/**
(blog-style recipes — optional<Steps>,<Tabs>after</Steps>OK;
see cookbookspath_instructions).- Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
- API reference pages MUST list parameters in a table with Name / Type /
Required / Description columns.- Every page MUST end with a clear "what's next" signal — either a
next:f...
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/docs/**/*.mdx
📄 CodeRabbit inference engine (.cursor/rules/starlight-steps-tabs-structure.mdc)
src/content/docs/**/*.mdx: In MDX documentation files,<Steps>must contain one continuous ordered list. Wrap<Steps>around a normal Markdown ordered list such as1. ## ...
In MDX documentation files, numbered step lines must start at column 0. Do not indent the1. ##,2. ##, etc.
In MDX documentation files, any content that belongs to a step must be indented with 3 spaces: paragraphs, bullets, images,<Tabs>,<TabItem>, and fenced code blocks
In MDX documentation files, prefer plain Markdown inside<Steps>. If the content is mostly<Tabs>or other JSX-heavy blocks, use normal section headings instead of<Steps>
In MDX documentation files, when<Tabs>is used inside a step, keep<Tabs>,<TabItem>,</TabItem>, and</Tabs>consistently nested under that step
In MDX documentation files, if a tabs block is not part of a numbered step, place it outside</Steps>
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/**/*.mdx
📄 CodeRabbit inference engine (CONTRIBUTING.md)
src/content/**/*.mdx: All documentation must live as MDX files insidesrc/content/
Every documentation page must have frontmatter with title (≤60 characters), description (≤160 characters), sidebar label, order, and tags
Write documentation in second person using 'you' and 'your application', present tense for descriptions, and imperative for step-by-step instructions
Avoid filler phrases like 'simply', 'just', 'easily' in documentation and be direct
Explain security implications when relevant in documentation
Every code block demonstrating an SDK operation must include all four languages (Node.js, Python, Go, Java) using synced tabs with syncKey='tech-stack'
SDK variable names are fixed and must not be renamed: Node.js usesscalekit, Python usesscalekit_client, Go usesscalekitClient, Java usesscalekitClient
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
**/*.{md,mdx,astro,ts}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
**/*.{md,mdx,astro,ts}: Usepnpm pretty-quick --stagedvia pre-commit git hook to auto-format all staged.md,.mdx,.astro,.tsfiles with Prettier
Runpnpm formatto auto-format all.md,.mdx,.astro,.tsfiles before pushing changes
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
src/content/docs/**/*.{md,mdx}: All documentation must follow a documentation-first workflow, and any code change must be accompanied by corresponding documentation updates.
Use the exact SDK variable names in all documentation and code examples: Node.jsscalekit, Pythonscalekit_client, GoscalekitClient, and JavascalekitClient.
Most code examples should include Node.js, Python, Go, and Java implementations with consistent variable naming; examples must show both success and error handling paths.
Product documentation for MCP Auth, Agent Auth, Full Stack Auth, Modular SCIM, and Modular SSO must use a journey-focused approach.
All technical content must be validated through testing, API examples must be current and functional, and security implications must be documented where relevant.
Write documentation with clear, skimmable structure: descriptive section titles, short paragraphs, topic sentences, key takeaways near the top, bullets/tables where useful, and bolded important concepts.
Use simple, unambiguous, active, present-tense, second-person language in documentation; avoid jargon, filler words, and insecure patterns such as hard-coded secrets.
Use imperative phrasing for procedures, front-load the action, explain why when useful, prefer examples over theory, and keep one idea per sentence or paragraph.
Use sentence case for all titles and headings, keep titles short and descriptive, make headings describe outcomes, and avoid gerunds when an imperative works better.
Use concise, sentence-case sidebar labels without punctuation; make them outcome- or object-focused and shorter than page titles.
Follow the correct page template for the document type: how-to guides, API references, concept pages, and release notes each have required sections.
Every documentation page must include frontmatter with at leasttitle,description, andsidebar.label, and those values must meet the stated length and navigation requirements.
Opening paragraphs must state ...
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/docs/**/*.{mdx,md}
📄 CodeRabbit inference engine (CLAUDE.md)
Use the specified code-commenting standards in inline code comments: avoid restating code, explain unidiomatic patterns, document parameters/returns/exceptions for complex logic, and use standard TODO/FIXME/NOTE formats.
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
**
⚙️ CodeRabbit configuration file
**: # CLAUDE.md - Scalekit Documentation GuideOverview
This file is the single source of truth for all documentation standards and AI assistant guidelines in this repository. All documentation must adhere to the rules defined below.
Core Principles
Documentation-first development
Every feature must include comprehensive, user-focused documentation. Documentation is not an afterthought but a first-class deliverable that guides implementation. All code changes require corresponding documentation updates.
Git workflow
- Do NOT include
Co-Authored-Bylines in commit messages- At the start of a fresh session, before making any changes, ask the user: "Do you want me to cut a new branch or work on the current branch?"
- Never force push (
git push --forceorgit push -f). If a push fails, stop and clearly explain the reason it failed — do not attempt workarounds without user confirmation.- For commit, push, and PR creation, spawn a subagent using the Haiku model to handle it. The pre-push hook generates large logs and PR creation output adds unnecessary noise to the main session context.
- Once the user confirms local testing works, or explicitly asks to commit and push, commit all changes, push the branch, and open a PR against
main. The PR must include:
- A crisp description of the changes
- A preview link in the format:
https://deploy-preview-{PR_NUMBER}--scalekit-starlight.netlify.app/{path-to-changed-page}/SDK variable names (critical)
CRITICAL: Use the exact variable names below in all documentation and code examples.
- Node.js:
scalekit- Python:
scalekit_client- Go:
scalekitClient- Java:
scalekitClientMulti-Language SDK Consistency
All code examples MUST include Node.js, Python, Go, and Java implementations with consistent variable naming conventions. Examples must show both success and error handling paths. Security implications must be explained for each implementation....
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
🧠 Learnings (13)
📚 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/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-03-17T16:01:50.487Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 506
File: src/content/docs/authenticate/fsa/quickstart.mdx:851-853
Timestamp: 2026-03-17T16:01:50.487Z
Learning: In the Scalekit Python SDK docs, clarify that LogoutUrlOptions is not exported from the top-level scalekit package __init__.py. The correct import path in code samples or reviews is: from scalekit.common.scalekit import LogoutUrlOptions. Do not flag this import path as incorrect in documentation or code reviews; ensure examples reflect the proper import path to avoid confusion for users.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (.mdx files), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag links for missing `target="_blank"` or `rel="noopener"` (avoid adding raw HTML anchors just to include those attributes), and keep the approach consistent with existing docs styling.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-04-25T07:22:18.321Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 633
File: src/components/templates/agent-connectors/_setup-heyreach.mdx:12-12
Timestamp: 2026-04-25T07:22:18.321Z
Learning: In this repo’s MDX documentation files, treat `@/...` paths as aliases that resolve to the `src/` directory (e.g., `@/assets/docs/foo/bar.png` -> `src/assets/docs/foo/bar.png`). When reviewing, do not flag `@`-prefixed image (or other asset) paths as broken; instead, verify that the corresponding physical file exists under `src/`.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (MD/MDX), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag external links for missing `target="_blank"` or `rel="noopener"`, and avoid converting Markdown links into raw HTML `<a>` tags just to add those attributes, since that would be inconsistent with the established doc pattern.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
🔇 Additional comments (4)
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdx (1)
168-168: LGTM!src/content/docs/guides/admin-portal.mdx (1)
58-58: LGTM!src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx (2)
27-70: LGTM!Also applies to: 84-99, 190-230, 257-296
2-23: 🎯 Functional CorrectnessRemove the
sidebar.orderrequirement here. This page is listed explicitly insrc/configs/sidebar.config.ts, so the missing frontmatter field is not needed.> Likely an incorrect or invalid review comment.
| 4. Users move between organization and user modules inside the portal using its navigation. | ||
|
|
||
| <TabItem value="signup" label="Signup"> | ||
| ```sh title="Authorization URL (signup)" showLineNumbers=false frame | ||
| <SCALEKIT_ENVIRONMENT_URL>/oauth/authorize? | ||
| response_type=code& | ||
| client_id=<SCALEKIT_CLIENT_ID>& | ||
| redirect_uri=<CALLBACK_URL>& | ||
| scope=openid+profile+email+offline_access& | ||
| state=<RANDOM_STATE>& | ||
| prompt=create | ||
| ``` | ||
| Scalekit checks the user's roles and permissions and shows only the modules they can use. If you store access and refresh tokens in your own backend cookies, follow the session patterns in the [SaaSKit quickstart](/authenticate/fsa/quickstart/) and [manage sessions](/authenticate/fsa/manage-session/) guides so the browser session Scalekit expects stays consistent with your app. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
Token reference lacks inline clarification.
This mentions "access and refresh tokens" without stating what they contain, their lifetime, or secure usage guidance inline (it links out to other guides instead). The same pattern recurs at line 277.
As per path instructions (src/content/docs/authenticate/**/*.mdx), "Any reference to tokens (idToken, accessToken, refreshToken) MUST clarify: what it contains, its lifetime, and how to use it securely."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx` around
lines 106 - 108, The hosted-widgets docs mention access and refresh tokens
without the required inline clarification. Update the affected prose in the
relevant docs section(s) and any repeated token references so each mention
explicitly states what the token contains, how long it is valid, and that it
must be handled securely; use the surrounding auth/session guidance in
hosted-widgets.mdx to keep the explanation consistent.
| Customers view and manage the organization profile, including allowed email domains, under **Organization settings**. | ||
|
|
||
| <Steps> | ||
|  |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Missing alt text on multiple images.
These screenshots use empty ![]() syntax instead of descriptive alt text (contrast with lines 164, 210, and 226, which already do this correctly).
As per path instructions, "All images MUST have descriptive alt text — not empty ![]() syntax."
🖼️ Proposed fix (example for line 132)
-
+Apply the same pattern to lines 138, 146, 154, 172, 182, and 188.
Also applies to: 138-138, 146-146, 154-154, 172-172, 182-182, 188-188
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx` at line
132, The hosted-widgets documentation contains several image markdown entries in
the content section that use empty alt text, so update each affected image to
include a descriptive alt string instead of `![]()`. Use the existing correctly
written image examples in this doc as the pattern, and fix the images referenced
by the hosted-widgets content near the org settings screenshots so every
`img`-style markdown entry has meaningful alt text.
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx`:
- Around line 2-7: Add a sidebar.order field to the frontmatter in
hosted-widgets.mdx so this doc stays in the intended position among the
authenticate/manage-users-orgs pages. Update the existing frontmatter next to
the title, description, tags, and sidebar.label entries, using the same ordering
pattern as the other docs in this section.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8a96a52d-f0c6-42fc-97da-dae21eee5530
📒 Files selected for processing (3)
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdxsrc/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdx
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: Redirect rules - scalekit-starlight
- GitHub Check: Header rules - scalekit-starlight
- GitHub Check: Pages changed - scalekit-starlight
🧰 Additional context used
📓 Path-based instructions (10)
**/*.mdx
📄 CodeRabbit inference engine (.cursorrules)
**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component:1. ## 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/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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).
- Headings that match a real API parameter, method, or field name
(e.g.,contactID,xero_tenant_id,executeTool) should preserve
the original casing. Do NOT flag these as sentence-case violations.- No heading should end with a colon or period.
Content structure
- Journey how-to guides MUST contain numbered
<Steps>(Starlight
component). This does NOT apply tosrc/content/docs/cookbooks/**
(blog-style recipes — optional<Steps>,<Tabs>after</Steps>OK;
see cookbookspath_instructions).- Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
- API reference pages MUST list parameters in a table with Name / Type /
Required / Description columns.- Every page MUST end with a clear "what's next" signal — either a
next:f...
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/docs/**/*.mdx
📄 CodeRabbit inference engine (.cursor/rules/starlight-steps-tabs-structure.mdc)
src/content/docs/**/*.mdx: In MDX documentation files,<Steps>must contain one continuous ordered list. Wrap<Steps>around a normal Markdown ordered list such as1. ## ...
In MDX documentation files, numbered step lines must start at column 0. Do not indent the1. ##,2. ##, etc.
In MDX documentation files, any content that belongs to a step must be indented with 3 spaces: paragraphs, bullets, images,<Tabs>,<TabItem>, and fenced code blocks
In MDX documentation files, prefer plain Markdown inside<Steps>. If the content is mostly<Tabs>or other JSX-heavy blocks, use normal section headings instead of<Steps>
In MDX documentation files, when<Tabs>is used inside a step, keep<Tabs>,<TabItem>,</TabItem>, and</Tabs>consistently nested under that step
In MDX documentation files, if a tabs block is not part of a numbered step, place it outside</Steps>
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/**/*.mdx
📄 CodeRabbit inference engine (CONTRIBUTING.md)
src/content/**/*.mdx: All documentation must live as MDX files insidesrc/content/
Every documentation page must have frontmatter with title (≤60 characters), description (≤160 characters), sidebar label, order, and tags
Write documentation in second person using 'you' and 'your application', present tense for descriptions, and imperative for step-by-step instructions
Avoid filler phrases like 'simply', 'just', 'easily' in documentation and be direct
Explain security implications when relevant in documentation
Every code block demonstrating an SDK operation must include all four languages (Node.js, Python, Go, Java) using synced tabs with syncKey='tech-stack'
SDK variable names are fixed and must not be renamed: Node.js usesscalekit, Python usesscalekit_client, Go usesscalekitClient, Java usesscalekitClient
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
**/*.{md,mdx,astro,ts}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
**/*.{md,mdx,astro,ts}: Usepnpm pretty-quick --stagedvia pre-commit git hook to auto-format all staged.md,.mdx,.astro,.tsfiles with Prettier
Runpnpm formatto auto-format all.md,.mdx,.astro,.tsfiles before pushing changes
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
src/content/docs/**/*.{md,mdx}: All documentation must follow a documentation-first workflow, and any code change must be accompanied by corresponding documentation updates.
Use the exact SDK variable names in all documentation and code examples: Node.jsscalekit, Pythonscalekit_client, GoscalekitClient, and JavascalekitClient.
Most code examples should include Node.js, Python, Go, and Java implementations with consistent variable naming; examples must show both success and error handling paths.
Product documentation for MCP Auth, Agent Auth, Full Stack Auth, Modular SCIM, and Modular SSO must use a journey-focused approach.
All technical content must be validated through testing, API examples must be current and functional, and security implications must be documented where relevant.
Write documentation with clear, skimmable structure: descriptive section titles, short paragraphs, topic sentences, key takeaways near the top, bullets/tables where useful, and bolded important concepts.
Use simple, unambiguous, active, present-tense, second-person language in documentation; avoid jargon, filler words, and insecure patterns such as hard-coded secrets.
Use imperative phrasing for procedures, front-load the action, explain why when useful, prefer examples over theory, and keep one idea per sentence or paragraph.
Use sentence case for all titles and headings, keep titles short and descriptive, make headings describe outcomes, and avoid gerunds when an imperative works better.
Use concise, sentence-case sidebar labels without punctuation; make them outcome- or object-focused and shorter than page titles.
Follow the correct page template for the document type: how-to guides, API references, concept pages, and release notes each have required sections.
Every documentation page must include frontmatter with at leasttitle,description, andsidebar.label, and those values must meet the stated length and navigation requirements.
Opening paragraphs must state ...
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/docs/**/*.{mdx,md}
📄 CodeRabbit inference engine (CLAUDE.md)
Use the specified code-commenting standards in inline code comments: avoid restating code, explain unidiomatic patterns, document parameters/returns/exceptions for complex logic, and use standard TODO/FIXME/NOTE formats.
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
**
⚙️ CodeRabbit configuration file
**: # CLAUDE.md - Scalekit Documentation GuideOverview
This file is the single source of truth for all documentation standards and AI assistant guidelines in this repository. All documentation must adhere to the rules defined below.
Core Principles
Documentation-first development
Every feature must include comprehensive, user-focused documentation. Documentation is not an afterthought but a first-class deliverable that guides implementation. All code changes require corresponding documentation updates.
Git workflow
- Do NOT include
Co-Authored-Bylines in commit messages- At the start of a fresh session, before making any changes, ask the user: "Do you want me to cut a new branch or work on the current branch?"
- Never force push (
git push --forceorgit push -f). If a push fails, stop and clearly explain the reason it failed — do not attempt workarounds without user confirmation.- For commit, push, and PR creation, spawn a subagent using the Haiku model to handle it. The pre-push hook generates large logs and PR creation output adds unnecessary noise to the main session context.
- Once the user confirms local testing works, or explicitly asks to commit and push, commit all changes, push the branch, and open a PR against
main. The PR must include:
- A crisp description of the changes
- A preview link in the format:
https://deploy-preview-{PR_NUMBER}--scalekit-starlight.netlify.app/{path-to-changed-page}/SDK variable names (critical)
CRITICAL: Use the exact variable names below in all documentation and code examples.
- Node.js:
scalekit- Python:
scalekit_client- Go:
scalekitClient- Java:
scalekitClientMulti-Language SDK Consistency
All code examples MUST include Node.js, Python, Go, and Java implementations with consistent variable naming conventions. Examples must show both success and error handling paths. Security implications must be explained for each implementation....
Files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
🧠 Learnings (13)
📚 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/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-03-17T16:01:50.487Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 506
File: src/content/docs/authenticate/fsa/quickstart.mdx:851-853
Timestamp: 2026-03-17T16:01:50.487Z
Learning: In the Scalekit Python SDK docs, clarify that LogoutUrlOptions is not exported from the top-level scalekit package __init__.py. The correct import path in code samples or reviews is: from scalekit.common.scalekit import LogoutUrlOptions. Do not flag this import path as incorrect in documentation or code reviews; ensure examples reflect the proper import path to avoid confusion for users.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (.mdx files), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag links for missing `target="_blank"` or `rel="noopener"` (avoid adding raw HTML anchors just to include those attributes), and keep the approach consistent with existing docs styling.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-04-25T07:22:18.321Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 633
File: src/components/templates/agent-connectors/_setup-heyreach.mdx:12-12
Timestamp: 2026-04-25T07:22:18.321Z
Learning: In this repo’s MDX documentation files, treat `@/...` paths as aliases that resolve to the `src/` directory (e.g., `@/assets/docs/foo/bar.png` -> `src/assets/docs/foo/bar.png`). When reviewing, do not flag `@`-prefixed image (or other asset) paths as broken; instead, verify that the corresponding physical file exists under `src/`.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (MD/MDX), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag external links for missing `target="_blank"` or `rel="noopener"`, and avoid converting Markdown links into raw HTML `<a>` tags just to add those attributes, since that would be inconsistent with the established doc pattern.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdxsrc/content/docs/guides/admin-portal.mdxsrc/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
🪛 LanguageTool
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
[grammar] ~76-~76: Use a hyphen to join words.
Context: ...ndled automatically. The portal stays up to date with new Scalekit capabilities. - *...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (5)
src/content/docs/authenticate/manage-users-orgs/organization-domains.mdx (1)
168-168: LGTM!src/content/docs/guides/admin-portal.mdx (1)
58-58: LGTM!src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx (3)
139-139: 📐 Maintainability & Code Quality | ⚡ Quick winMissing alt text on several images.
These screenshots still use empty
![]()syntax, unlike line 177 which already has descriptive alt text.🖼️ Proposed fix (apply pattern to all flagged lines)
- +As per path instructions, "All images MUST have descriptive alt text — not empty
![]()syntax."Also applies to: 145-145, 155-155, 165-165, 187-187, 201-201, 207-207
Source: Path instructions
147-149: 📐 Maintainability & Code Quality | ⚡ Quick winWeasel word "easy" in SSO step description.
"making it easy to connect their SSO connection" uses a flagged weasel word and awkwardly repeats "connect...connection".
✏️ Proposed fix
- Your customers can set up and manage Single Sign-On for their organization. The widget includes a setup guide tailored to their identity provider, making it easy to connect their SSO connection. + Your customers can set up and manage Single Sign-On for their organization. The widget includes a setup guide tailored to their identity provider.As per path instructions, "Flag weasel words: 'simply', 'just', 'easy', 'straightforward', 'obviously', 'of course', 'note that'."
Source: Path instructions
91-123: 🎯 Functional CorrectnessVerify
valueprop on<TabItem>is valid.
<TabItem value="login" label="Login">and<TabItem value="signup" label="Signup">include avalueattribute. Starlight'sTabItemAPI is documented to acceptlabel(and optionalicon), notvalue— this prop may be silently ignored.[web_search]
Does Starlight's TabItem component support a "value" prop?
| title: 'Hosted UI widgets' | ||
| description: 'Redirect users to a branded self-serve portal for organization settings, member management, SSO, SCIM, domains, and user profiles.' | ||
| tags: [hosted-widgets, organizations, users, permissions, branding, user-management, ui] | ||
| tableOfContents: true | ||
| sidebar: | ||
| label: 'Hosted UI widgets' |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check how this page is referenced in sidebar.config.ts (directory-based vs. explicit path)
rg -n "hosted-widgets|manage-users-orgs" src/configs/sidebar.config.ts -A3 -B3Repository: scalekit-inc/developer-docs
Length of output: 1989
Add sidebar.order to this page’s frontmatter src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx:2-7 so it stays in the correct sequence with the other authenticate/manage-users-orgs entries in the sidebar.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx` around
lines 2 - 7, Add a sidebar.order field to the frontmatter in hosted-widgets.mdx
so this doc stays in the intended position among the
authenticate/manage-users-orgs pages. Update the existing frontmatter next to
the title, description, tags, and sidebar.label entries, using the same ordering
pattern as the other docs in this section.
Source: Path instructions
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Document shared Scalekit cookies, login-page redirects, active org selection, simple Settings redirect, and Admin portal as the only embed.
Prefer plain "app" and "authentication flow" wording on the page.
Use enabled organization features language on Hosted UI widgets.
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/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx (1)
244-290: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAdd a closing “what's next” signal. The page ends on the scenario block, so readers do not get an explicit next step. Add
next:frontmatter or a final paragraph that points them to the next page in the journey. As per path instructions, every page must end with a clear “what's next” signal.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx` around lines 244 - 290, The hosted widgets docs page ends with the scenario section but no clear next-step signal, so add an explicit “what’s next” at the end of the page. Update the hosted widgets MDX content by either adding next frontmatter or appending a short closing paragraph that points readers to the next page in the journey, keeping the guidance aligned with the existing hosted UI widgets section.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx`:
- Around line 244-290: The hosted widgets docs page ends with the scenario
section but no clear next-step signal, so add an explicit “what’s next” at the
end of the page. Update the hosted widgets MDX content by either adding next
frontmatter or appending a short closing paragraph that points readers to the
next page in the journey, keeping the guidance aligned with the existing hosted
UI widgets section.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: d04a082e-85e1-4038-b8b3-8b4b09c405cd
📒 Files selected for processing (1)
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (10)
**/*.mdx
📄 CodeRabbit inference engine (.cursorrules)
**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component:1. ## 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.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).
- Headings that match a real API parameter, method, or field name
(e.g.,contactID,xero_tenant_id,executeTool) should preserve
the original casing. Do NOT flag these as sentence-case violations.- No heading should end with a colon or period.
Content structure
- Journey how-to guides MUST contain numbered
<Steps>(Starlight
component). This does NOT apply tosrc/content/docs/cookbooks/**
(blog-style recipes — optional<Steps>,<Tabs>after</Steps>OK;
see cookbookspath_instructions).- Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
- API reference pages MUST list parameters in a table with Name / Type /
Required / Description columns.- Every page MUST end with a clear "what's next" signal — either a
next:f...
Files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.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.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/manage-users-orgs/hosted-widgets.mdx
src/content/docs/**/*.mdx
📄 CodeRabbit inference engine (.cursor/rules/starlight-steps-tabs-structure.mdc)
src/content/docs/**/*.mdx: In MDX documentation files,<Steps>must contain one continuous ordered list. Wrap<Steps>around a normal Markdown ordered list such as1. ## ...
In MDX documentation files, numbered step lines must start at column 0. Do not indent the1. ##,2. ##, etc.
In MDX documentation files, any content that belongs to a step must be indented with 3 spaces: paragraphs, bullets, images,<Tabs>,<TabItem>, and fenced code blocks
In MDX documentation files, prefer plain Markdown inside<Steps>. If the content is mostly<Tabs>or other JSX-heavy blocks, use normal section headings instead of<Steps>
In MDX documentation files, when<Tabs>is used inside a step, keep<Tabs>,<TabItem>,</TabItem>, and</Tabs>consistently nested under that step
In MDX documentation files, if a tabs block is not part of a numbered step, place it outside</Steps>
Files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/**/*.mdx
📄 CodeRabbit inference engine (CONTRIBUTING.md)
src/content/**/*.mdx: All documentation must live as MDX files insidesrc/content/
Every documentation page must have frontmatter with title (≤60 characters), description (≤160 characters), sidebar label, order, and tags
Write documentation in second person using 'you' and 'your application', present tense for descriptions, and imperative for step-by-step instructions
Avoid filler phrases like 'simply', 'just', 'easily' in documentation and be direct
Explain security implications when relevant in documentation
Every code block demonstrating an SDK operation must include all four languages (Node.js, Python, Go, Java) using synced tabs with syncKey='tech-stack'
SDK variable names are fixed and must not be renamed: Node.js usesscalekit, Python usesscalekit_client, Go usesscalekitClient, Java usesscalekitClient
Files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
**/*.{md,mdx,astro,ts}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
**/*.{md,mdx,astro,ts}: Usepnpm pretty-quick --stagedvia pre-commit git hook to auto-format all staged.md,.mdx,.astro,.tsfiles with Prettier
Runpnpm formatto auto-format all.md,.mdx,.astro,.tsfiles before pushing changes
Files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
src/content/docs/**/*.{md,mdx}: All documentation must follow a documentation-first workflow, and any code change must be accompanied by corresponding documentation updates.
Use the exact SDK variable names in all documentation and code examples: Node.jsscalekit, Pythonscalekit_client, GoscalekitClient, and JavascalekitClient.
Most code examples should include Node.js, Python, Go, and Java implementations with consistent variable naming; examples must show both success and error handling paths.
Product documentation for MCP Auth, Agent Auth, Full Stack Auth, Modular SCIM, and Modular SSO must use a journey-focused approach.
All technical content must be validated through testing, API examples must be current and functional, and security implications must be documented where relevant.
Write documentation with clear, skimmable structure: descriptive section titles, short paragraphs, topic sentences, key takeaways near the top, bullets/tables where useful, and bolded important concepts.
Use simple, unambiguous, active, present-tense, second-person language in documentation; avoid jargon, filler words, and insecure patterns such as hard-coded secrets.
Use imperative phrasing for procedures, front-load the action, explain why when useful, prefer examples over theory, and keep one idea per sentence or paragraph.
Use sentence case for all titles and headings, keep titles short and descriptive, make headings describe outcomes, and avoid gerunds when an imperative works better.
Use concise, sentence-case sidebar labels without punctuation; make them outcome- or object-focused and shorter than page titles.
Follow the correct page template for the document type: how-to guides, API references, concept pages, and release notes each have required sections.
Every documentation page must include frontmatter with at leasttitle,description, andsidebar.label, and those values must meet the stated length and navigation requirements.
Opening paragraphs must state ...
Files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
src/content/docs/**/*.{mdx,md}
📄 CodeRabbit inference engine (CLAUDE.md)
Use the specified code-commenting standards in inline code comments: avoid restating code, explain unidiomatic patterns, document parameters/returns/exceptions for complex logic, and use standard TODO/FIXME/NOTE formats.
Files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
**
⚙️ CodeRabbit configuration file
**: # CLAUDE.md - Scalekit Documentation GuideOverview
This file is the single source of truth for all documentation standards and AI assistant guidelines in this repository. All documentation must adhere to the rules defined below.
Core Principles
Documentation-first development
Every feature must include comprehensive, user-focused documentation. Documentation is not an afterthought but a first-class deliverable that guides implementation. All code changes require corresponding documentation updates.
Git workflow
- Do NOT include
Co-Authored-Bylines in commit messages- At the start of a fresh session, before making any changes, ask the user: "Do you want me to cut a new branch or work on the current branch?"
- Never force push (
git push --forceorgit push -f). If a push fails, stop and clearly explain the reason it failed — do not attempt workarounds without user confirmation.- For commit, push, and PR creation, spawn a subagent using the Haiku model to handle it. The pre-push hook generates large logs and PR creation output adds unnecessary noise to the main session context.
- Once the user confirms local testing works, or explicitly asks to commit and push, commit all changes, push the branch, and open a PR against
main. The PR must include:
- A crisp description of the changes
- A preview link in the format:
https://deploy-preview-{PR_NUMBER}--scalekit-starlight.netlify.app/{path-to-changed-page}/SDK variable names (critical)
CRITICAL: Use the exact variable names below in all documentation and code examples.
- Node.js:
scalekit- Python:
scalekit_client- Go:
scalekitClient- Java:
scalekitClientMulti-Language SDK Consistency
All code examples MUST include Node.js, Python, Go, and Java implementations with consistent variable naming conventions. Examples must show both success and error handling paths. Security implications must be explained for each implementation....
Files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/hosted-widgets.mdx
🧠 Learnings (13)
📚 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.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.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/manage-users-orgs/hosted-widgets.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/manage-users-orgs/hosted-widgets.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/manage-users-orgs/hosted-widgets.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/manage-users-orgs/hosted-widgets.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/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-03-17T16:01:50.487Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 506
File: src/content/docs/authenticate/fsa/quickstart.mdx:851-853
Timestamp: 2026-03-17T16:01:50.487Z
Learning: In the Scalekit Python SDK docs, clarify that LogoutUrlOptions is not exported from the top-level scalekit package __init__.py. The correct import path in code samples or reviews is: from scalekit.common.scalekit import LogoutUrlOptions. Do not flag this import path as incorrect in documentation or code reviews; ensure examples reflect the proper import path to avoid confusion for users.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.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/manage-users-orgs/hosted-widgets.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/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (.mdx files), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag links for missing `target="_blank"` or `rel="noopener"` (avoid adding raw HTML anchors just to include those attributes), and keep the approach consistent with existing docs styling.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-04-25T07:22:18.321Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 633
File: src/components/templates/agent-connectors/_setup-heyreach.mdx:12-12
Timestamp: 2026-04-25T07:22:18.321Z
Learning: In this repo’s MDX documentation files, treat `@/...` paths as aliases that resolve to the `src/` directory (e.g., `@/assets/docs/foo/bar.png` -> `src/assets/docs/foo/bar.png`). When reviewing, do not flag `@`-prefixed image (or other asset) paths as broken; instead, verify that the corresponding physical file exists under `src/`.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (MD/MDX), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag external links for missing `target="_blank"` or `rel="noopener"`, and avoid converting Markdown links into raw HTML `<a>` tags just to add those attributes, since that would be inconsistent with the established doc pattern.
Applied to files:
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx
🔇 Additional comments (1)
src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx (1)
201-209: Same alt-text fix applies to the user widgets screenshots. The![]()images at lines 203 and 209 still need descriptive alt text.
- Remove Signup and login widgets section entirely (focus page on post-login /ui/ self-serve experience for signed-in users) - Remove redundant emdash explanations and duplicated 'Admin portal' distinction text - Simplify wording and remove unnecessary statements per review feedback (e.g. session details, query params) - Update D2 diagram to match simplified structure - Tighten cross-references and remove duplication in admin-portal.mdx and organization-domains.mdx - Clean up unused imports
|
|
||
| It is the same Scalekit session issued to your application for that user. After your [authentication flow](/authenticate/fsa/quickstart/), the browser holds Scalekit cookies for your environment or custom domain. Hosted UI widgets read those same cookies, so users do not sign in again when you redirect them to `/ui/`. | ||
|
|
||
| If your app stores access and refresh tokens only in your backend and never establishes Scalekit browser cookies, `/ui/` will not see that session. Complete the hosted auth redirect flow so Scalekit can set cookies in the browser. |
There was a problem hiding this comment.
@ekline this line can be removed as it is not valid.
There was a problem hiding this comment.
EkLine Docs Agent is working on this update. You can view the progress at EkLine Editor.
2 participants
Summary
Clarifies Hosted widgets docs so developers understand the SaaSKit self-serve experience at
/ui/(redirect-based portal, Scalekit platform session, permissions, shared branding) and how it differs from Admin portal (shareable magic link / iframe embed for enterprise SSO and SCIM).hosted-widgetsfor session model, portal entry, widget catalog, access management, branding, and common scenarios (no session, logout sync, no webhook hydration, no iframe for/ui/)/ui/and Admin portal when appropriateFixes SK-972
https://linear.app/scalekit/issue/SK-972/clarify-hosted-widgets-docs-and-related-pages
Related pages
/authenticate/manage-users-orgs/hosted-widgets//guides/admin-portal//authenticate/manage-users-orgs/organization-domains/Preview
https://deploy-preview-817--scalekit-starlight.netlify.app/authenticate/manage-users-orgs/hosted-widgets/
Test plan
Summary by CodeRabbit
/ui/portal behavior, organization selection after sign-in, and what each widget manages.