Onprem documentation#624
Conversation
anujsharmask
requested review from
amitash1912,
ravibits and
saif-at-scalekit
as code owners
WalkthroughAdds a new Self-hosted section: navigation and sidebar entries, two config constants, tooling hook adjustments, and a full set of documentation pages (installation, quickstart, setup script, configuration, requirements, troubleshooting, upgrades, overview) plus minor developer tooling and script tweaks. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/configs/sidebar.config.ts`:
- Around line 604-606: The 'self-hosted' topic definition is placed after the
'resources' topic which uses a catch-all pattern and, due to "first match wins",
will intercept /self-hosted/**/* pages; move the 'self-hosted' entry so it
appears before the 'resources' entry in sidebar.config.ts (reorder the
array/object entries so 'self-hosted': ['/self-hosted/**/*'] comes above the
'resources' topic) to ensure pages under /self-hosted/**/* are assigned to the
correct topic.
In `@src/content/docs/self-hosted/installation.mdx`:
- Line 22: The anchor linking to the Scalekit distribution portal currently
lacks safe external-link attributes; update the <a href={DISTR_URL}>Scalekit
distribution portal</a> anchor to include target="_blank" and rel="noopener",
and apply the same change to the other external anchor occurrences referenced
(anchors at the content lines around 27 and 109) so all external MDX links use
target="_blank" and rel="noopener".
In `@src/content/docs/self-hosted/setup-script.mdx`:
- Around line 272-275: The Helm OCI registry host is hardcoded as
ar.scalekit.cloud in the helm install command; update the docs to use the
existing config constant (REGISTRY_HOST) instead of the literal so the OCI path
is consistent with other self-hosted docs. Replace the hardcoded host in the
helm command string with ${REGISTRY_HOST} (or add a short preceding note showing
REGISTRY_HOST is the OCI registry) and ensure the associated example uses the
same variable names as other docs; update any surrounding text that references
the OCI registry to reference REGISTRY_HOST so readers know where to change it
if the registry changes.
In `@src/content/docs/self-hosted/troubleshooting.mdx`:
- Around line 19-22: Add a short opening paragraph before the "## Check pod
status first" heading that briefly explains the scope of the troubleshooting
page (what issues it covers, e.g., common Kubernetes/self-hosted deployment
failures and diagnostics) and when to use it (who should consult this page and
in what situations), keeping it concise (1–2 sentences) to satisfy the
documentation guideline requiring an overview paragraph.
- Line 122: Replace the markdown link for the Scalekit Slack community
("Scalekit Slack community" / `#self-hosted`) with an explicit anchor element
that includes target="_blank" and rel="noopener" so the external link opens in a
new tab securely; update the MDX line containing the Slack community link to use
the HTML <a> tag with those attributes while preserving the link URL and link
text.
- Around line 24-27: Replace hard-coded "scalekit" namespace and fixed registry
host in the troubleshooting examples with placeholder variables and a brief note
on how to set them (e.g., NAMESPACE and REGISTRY) so users can copy/paste for
custom installs; specifically update the commands shown (kubectl get pods -n
scalekit, kubectl describe pod <pod-name> -n scalekit, kubectl logs <pod-name>
-n scalekit --tail=100 and the other examples at the noted ranges) to use a
placeholder like ${NAMESPACE} (and ${REGISTRY} where registry host appears) and
add a one-line instruction telling users to export or replace those variables to
match their deployment.
In `@src/content/docs/self-hosted/upgrades.mdx`:
- Around line 1-15: The frontmatter places prev and next at the root which
breaks navigation; move the prev: and next: blocks so they are children of the
existing sidebar: block (increase their indentation to match other sidebar
children), remove them from the root level, and ensure the YAML indentation is
consistent so sidebar contains label, order, tags (if any), plus prev and next
entries; update the frontmatter in the Upgrades & maintenance document by
nesting the prev and next keys under sidebar (referencing the existing sidebar,
prev and next symbols).
🪄 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: 57293b8a-5d8d-4c91-83f2-b0a576a5fff8
⛔ Files ignored due to path filters (13)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yamlsrc/assets/docs/self-hosted/portal-app-config.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-deploy-success.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-deployment-config.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-deployments.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-home.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-login.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-new-deployment.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-pat-created.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-pat-form.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-pat-list.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-profile-icon.pngis excluded by!**/*.pngsrc/assets/docs/self-hosted/portal-profile-menu.pngis excluded by!**/*.png
📒 Files selected for processing (11)
src/configs/secondary-nav.config.tssrc/configs/self-hosted.tssrc/configs/sidebar.config.tssrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/setup-script.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/upgrades.mdx
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - scalekit-starlight
- GitHub Check: Header rules - scalekit-starlight
- GitHub Check: Pages changed - scalekit-starlight
🧰 Additional context used
📓 Path-based instructions (12)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy,gradle,xml,json}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Comments should not duplicate the code - avoid comments that simply restate what the code does; comments should add value beyond what's obvious from reading the code
Files:
src/configs/self-hosted.tssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}: Good comments do not excuse unclear code - refactor the code to be self-explanatory instead of using comments to explain poorly written code; use better variable names, function names, and code structure
Comments should dispel confusion, not cause it - ensure comments clarify rather than obscure the code's purpose; avoid cryptic or joke comments
Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Provide links to the original source of copied code - always attribute code copied from external sources with URLs to Stack Overflow answers, GitHub repositories, or documentation
Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Add comments when fixing bugs - document bug fixes with context about the issue, reference issue trackers and bug reports, and explain workarounds and their limitations
Use comments to mark incomplete implementations - use standard formats for TODO, FIXME, and NOTE comments with context about what needs to be done and reference issue trackers when possible
Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements
Files:
src/configs/self-hosted.tssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Use JSDoc standards for all function, class, and complex logic comments in JavaScript/TypeScript - include parameter descriptions (
@param), return values (@returns), types (@type), and descriptions; document exceptions and edge cases
Files:
src/configs/self-hosted.tssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
**/*.{js,ts,tsx,py,go,java}
📄 CodeRabbit inference engine (AGENTS.md)
Use exact SDK variable names: Node.js:
scalekit, Python:scalekit_client, Go:scalekitClient, Java:scalekitClient
Files:
src/configs/self-hosted.tssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
**/*.{ts,js,mjs}
⚙️ CodeRabbit configuration file
**/*.{ts,js,mjs}: Do NOT enforce code-commenting style rules on these files.
Specifically, do not flag:
- Comments that "duplicate" or restate what the code does.
- Missing comments on bug fixes, workarounds, or issue references.
- Missing inline documentation or explanatory comments.
Code comments are at the author's discretion.
Files:
src/configs/self-hosted.tssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
**/*.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.mdx
⚙️ CodeRabbit configuration file
**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:Frontmatter
titleMUST be ≤ 60 characters and clearly state what the page does.descriptionMUST be ≤ 160 characters, action-oriented, unique per page.sidebar.labelMUST be present and ≤ 30 characters.sidebar.orderMUST be set on every page that lives inside a section
with siblings, to enforce the journey order in sidebar.config.ts.- Flag any missing
prev/nextlinks on pages that are clearly
part of a sequential flow (e.g., quickstart → implement-login →
complete-login → manage-session → logout).Voice & Style (CLAUDE.md standards)
- Voice: confident, direct, collaborative, instructional.
- Person: second person only ("you", "your application"). Reject "we",
"our", "the developer", "the user".- Tense: present tense for descriptions; imperative mood for instructions.
- Flag weasel words: "simply", "just", "easy", "straightforward",
"obviously", "of course", "note that".- Flag passive voice constructions where active voice is clearer.
- Headings must be sentence case, not Title Case (except proper nouns).
- No heading should end with a colon or period.
Content structure
- 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:frontmatter link, a<LinkCard>, or an explicit paragraph
pointing the reader forward in the sidebar journey.Code examples
- ALL code examples that show SDK usage MUST include all four language
tabs...
Files:
src/content/docs/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.mdx
src/content/docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
src/content/docs/**/*.{md,mdx}: Every documentation page must include frontmatter with at least:title(≤60 chars),description(≤160 chars), andsidebar.label(1-3 words)
Use H2 for major sections, H3 for subsections, and H4 only inside<Steps>; never use H1 in body content and avoid nesting beyond H4
Use numbered lists only inside<Steps>for ordered procedures; use bulleted lists for unordered information
Use bold for first mention of important terms, UI elements, and dashboard paths; use inline code for technical identifiers (variables, functions, endpoints, scopes, environment variables, file paths, placeholders)
The<Steps>component requires a single continuous ordered list with proper indentation: steps at column 0, continuation content indented with exactly 3 spaces
Use<Aside>component with atitleattribute for cautions, tips, and notes
Use<Badge>component to indicate parameter requirements in tables and inline text
Use<details>blocks at the end of pages for FAQs, common scenarios, and troubleshooting
Split content into clear sections with descriptive, sentence-style titles; include a table of contents for documents with multiple sections; keep paragraphs short and isolate critical points in their own short paragraphs
Begin sections and paragraphs with standalone topic sentences that preview content; put topic words at the beginning to support fast skimming; put key takeaways and results at the top of documents
Use bullets and tables generously to structure information; bold important text to highlight key concepts and decisions
Keep sentences simple, right-branching, and unambiguous; avoid ambiguous noun stacks and demonstrative pronouns like 'this' or 'that' when the referent is not explicit
Maintain strict consistency in terminology, formatting, and style; do not presume the reader's state of mind or intentions; use direct, instructional language
Write more simply than you think you need to; optimize for readers new to the do...
Files:
src/content/docs/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.mdx
{src/configs/sidebar.config.ts,src/components/overrides/Header.astro,src/components/SecondaryNav.astro}
📄 CodeRabbit inference engine (CLAUDE.md)
Navigation structure must be coordinated across
src/configs/sidebar.config.tsandsrc/components/overrides/Header.astroandsrc/components/SecondaryNav.astro
Files:
src/configs/sidebar.config.ts
src/configs/sidebar.config.ts
📄 CodeRabbit inference engine (AGENTS.md)
Left sidebar is configured via
src/configs/sidebar.config.ts
Files:
src/configs/sidebar.config.ts
⚙️ CodeRabbit configuration file
src/configs/sidebar.config.ts: This file defines the user journey across ALL documentation sections.
When reviewing changes to this file:
- Verify that reordered items do not break the logical learning sequence
(e.g., "complete-login" must always come after "implement-login").- New items added to the FSA sidebar must follow the journey sequence:
Getting Started → User Auth → Auth Methods → Users & Orgs →
Authorization → Multi-App → APIs → Customize → Go Live.- Commented-out items (TODO) are acceptable but must include a comment
explaining WHY they are hidden.sidebarToSecondaryNavmappings MUST be updated whenever a new
sidebar section (id) is added.- External links MUST include the
attrsblock with
target: '_blank',rel: 'noopener noreferrer',class: 'external-link'.
Files:
src/configs/sidebar.config.ts
🧠 Learnings (55)
📓 Common learnings
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 546
File: public/api/scalekit.scalar.json:3511-3563
Timestamp: 2026-03-29T07:52:33.367Z
Learning: In scalekit-inc/developer-docs, when ambiguity is found in generated OpenAPI under public/api/**, open an upstream issue in scalekit-inc/scalekit documenting the contract change and link back to the PR comment, then resolve the review thread after posting the upstream issue link. Do not edit generated spec files directly in this repo.
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 0
File: :0-0
Timestamp: 2026-03-13T04:24:59.653Z
Learning: In scalekit-inc/developer-docs, for PRs focused on tooling and templatizing (e.g., extracting usage sections into reusable MDX templates and updating sync scripts), review comments about .mdx file content quality (casing, unused imports, import consolidation, endpoint descriptions, etc.) are considered out of scope and should be resolved without blocking the PR.
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
📚 Learning: 2026-03-26T11:25:44.361Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 538
File: src/content.config.ts:66-74
Timestamp: 2026-03-26T11:25:44.361Z
Learning: In `src/content.config.ts`, the `scalekit-inc/scalekit-expo-sdk` repo is intentionally present in the `github-releases` loader but absent from the `sdk-references` loader. This is by design: release version tracking is needed for the Expo SDK even though it does not yet have a `REFERENCE.md` file. Do not flag this divergence as a sync issue in future reviews.
Applied to files:
src/configs/self-hosted.ts
📚 Learning: 2026-03-25T16:04:34.150Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 532
File: astro.config.mjs:302-302
Timestamp: 2026-03-25T16:04:34.150Z
Learning: In scalekit-inc/developer-docs, the D2 diagram generation behavior (skipped when the `NETLIFY` env var is set via `netlify dev`) is already documented in CONTRIBUTING.md. Do not flag missing documentation for this behavior in `astro.config.mjs`.
Applied to files:
src/configs/self-hosted.tssrc/content/docs/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.mdx
📚 Learning: 2026-03-31T16:14:24.575Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: public/AGENTS.md:0-0
Timestamp: 2026-03-31T16:14:24.575Z
Learning: Never hard-code secrets: `SCALEKIT_CLIENT_ID`, `SCALEKIT_CLIENT_SECRET`, and `SCALEKIT_ENV_URL` must be loaded from environment variables
Applied to files:
src/configs/self-hosted.tssrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/setup-script.mdx
📚 Learning: 2026-03-13T03:51:44.897Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 489
File: src/content/docs/reference/agent-connectors/attio.mdx:24-24
Timestamp: 2026-03-13T03:51:44.897Z
Learning: For any agent connector documentation files located in src/content/docs/reference/agent-connectors/, use CDN URLs for connector logos with the host `https://cdn.scalekit.com/sk-connect/assets/provider-icons/` (e.g., `https://cdn.scalekit.com/sk-connect/assets/provider-icons/attio.svg`). The correct host is `cdn.scalekit.com`, NOT `cdn.scalekit.cloud`. Do not flag or change image src attributes that use `cdn.scalekit.com` for provider icons in this directory.
Applied to files:
src/configs/self-hosted.ts
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to **/*.{md,mdx} : Use exact SDK variable names: Node.js: `scalekit`, Python: `scalekit_client`, Go: `scalekitClient`, Java: `scalekitClient`
Applied to files:
src/configs/self-hosted.ts
📚 Learning: 2026-03-31T16:14:24.575Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: public/AGENTS.md:0-0
Timestamp: 2026-03-31T16:14:24.575Z
Learning: Applies to public/**/*.{js,ts,jsx,tsx} : Node.js SDK should use the variable name `scalekit`
Applied to files:
src/configs/self-hosted.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to src/configs/sidebar.config.ts : Left sidebar is configured via `src/configs/sidebar.config.ts`
Applied to files:
src/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to {src/configs/sidebar.config.ts,src/components/overrides/Header.astro,src/components/SecondaryNav.astro} : Navigation structure must be coordinated across `src/configs/sidebar.config.ts` and `src/components/overrides/Header.astro` and `src/components/SecondaryNav.astro`
Applied to files:
src/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to {src/components/overrides/Header.astro,src/components/SecondaryNav.astro} : Secondary navigation is managed through `src/components/overrides/Header.astro` and `src/components/SecondaryNav.astro`
Applied to files:
src/configs/secondary-nav.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Changes to navigation structure MUST be coordinated across both sidebar configuration and header/secondary nav components
Applied to files:
src/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
📚 Learning: 2026-03-05T11:29:12.786Z
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:12.786Z
Learning: In `src/content/docs/agent-auth/providers.mdx`, the `<Card>` components use `icon=" "` (a space) intentionally. This is a deliberate UX choice to render consistent colored boxes across all cards, because only some Starlight icon names resolve to actual icons while others do not. Do not flag `icon=" "` as a placeholder issue on this file.
Applied to files:
src/configs/secondary-nav.config.ts
📚 Learning: 2026-02-18T18:25:59.260Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 438
File: CONTRIBUTING.md:1-7
Timestamp: 2026-02-18T18:25:59.260Z
Learning: In scalekit-inc/developer-docs, root-level markdown files like CONTRIBUTING.md and README.md are standard GitHub repository files and do not require frontmatter. Only MDX files under src/content/docs/ that are processed by the Starlight docs system need frontmatter with title, description, and navigation metadata.
Applied to files:
src/content/docs/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdx
📚 Learning: 2026-02-10T05:32:59.967Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
Applied to files:
src/content/docs/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/configuration.mdx
📚 Learning: 2026-03-13T04:24:59.653Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 0
File: :0-0
Timestamp: 2026-03-13T04:24:59.653Z
Learning: In scalekit-inc/developer-docs, for PRs focused on tooling and templatizing (e.g., extracting usage sections into reusable MDX templates and updating sync scripts), review comments about .mdx file content quality (casing, unused imports, import consolidation, endpoint descriptions, etc.) are considered out of scope and should be resolved without blocking the PR.
Applied to files:
src/content/docs/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/system-requirements.mdx
📚 Learning: 2026-01-30T18:18:50.883Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx:31-49
Timestamp: 2026-01-30T18:18:50.883Z
Learning: In all Scalekit documentation files (MDX), treat the terms 'Applications', 'Single Page Application (SPA)', 'Native Application', and 'Web Application' as proper nouns and preserve their capitalization in headings and body text. Ensure these terms remain capitalized even when used in sentence case or within prose.
Applied to files:
src/content/docs/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.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/self-hosted/quickstart.mdxsrc/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdxsrc/content/docs/self-hosted/troubleshooting.mdxsrc/content/docs/self-hosted/setup-script.mdx
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Release notes and changelogs must be versioned and include Summary, detailed change sections (Added/Changed/Deprecated/Removed/Fixed/Security), Breaking changes, Migration guide, and Upgrade instructions
Applied to files:
src/content/docs/self-hosted/upgrades.mdxsrc/content/docs/self-hosted/system-requirements.mdx
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Release notes and change logs MUST include: Summary, detailed change sections (Added/Changed/Deprecated/Removed/Fixed/Security), Breaking changes, Migration guide, and Upgrade instructions
Applied to files:
src/content/docs/self-hosted/upgrades.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Keep documentation synchronized with product changes
Applied to files:
src/content/docs/self-hosted/upgrades.mdx
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to src/content/docs/guides/integrations/**/*.{md,mdx} : Integration guides in `src/content/docs/guides/integrations/` MUST be kept synchronized with their index pages
Applied to files:
src/content/docs/self-hosted/upgrades.mdx
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to src/content/docs/agentkit/**/*.{md,mdx} : Agentkit code examples live in the external repo **scalekit-developers/agent-auth-examples** organized as `javascript/frameworks/<framework>` and `python/frameworks/<framework>`; verify docs snippets match current implementations in that repo
Applied to files:
src/content/docs/self-hosted/upgrades.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Review and refresh documentation content regularly
Applied to files:
src/content/docs/self-hosted/upgrades.mdx
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to {src/content/docs/guides/integrations/**/*.{md,mdx},src/components/templates/_*.{ts,tsx,astro}} : Integration guides in `src/content/docs/guides/integrations/` must be kept synchronized with their corresponding index pages and use reusable template components from `src/components/templates/`
Applied to files:
src/content/docs/self-hosted/upgrades.mdx
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Set concise sidebar labels that match user vocabulary in navigation metadata
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-03-26T13:43:56.358Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 539
File: src/content/docs/cookbooks/search-scalekit-docs-in-your-ide.mdx:1-15
Timestamp: 2026-03-26T13:43:56.358Z
Learning: In scalekit-inc/developer-docs, the `/cookbooks` directory (src/content/docs/cookbooks/**/*.mdx) uses directory-based auto-generation in src/configs/sidebar.config.ts (mapped as '/cookbooks' and '/cookbooks/**/*'). Therefore, sidebar.label is NOT required in frontmatter for cookbook pages. Do not flag missing sidebar.label for files under this directory.
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-02-26T07:18:51.377Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 448
File: scripts/sync-agent-connectors.js:0-0
Timestamp: 2026-02-26T07:18:51.377Z
Learning: In src/content/docs/reference/agent-connectors/**/*.mdx files, sidebar.label frontmatter is not required because the sidebar configuration references the agent-connectors directory for auto-generation. Navigation ordering and grouping are managed centrally in the sidebar configuration file.
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Sidebar labels should be outcome- or object-focused: 'Install', 'CLI', 'HTTP server', 'Permissions'
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Sidebar labels should match page title semantics but be shorter when useful
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Set appropriate sidebar labels for navigation in frontmatter
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Sidebar labels must be concise and scannable (1–3 words), use sentence case with no punctuation, and be outcome- or object-focused matching page title semantics but shorter when useful
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to **/*.{md,mdx} : Use `<Tabs syncKey="tech-stack">` format for multi-language SDK samples with TabItem labels for each language
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-03-20T02:32:40.836Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 514
File: src/content/docs/agent-auth/quickstart.mdx:82-82
Timestamp: 2026-03-20T02:32:40.836Z
Learning: In Agent Auth documentation under src/content/docs/agent-auth/, the Node.js SDK installation command should use the stable package `scalekit-sdk/node` (no version pin). Agent Auth features are now available in the stable release. Do not flag the removal of the `2.2.0-beta.1` beta version pin or suggest adding it back. Any remaining references to the beta version across Agent Auth docs should be updated to use the stable package.
Applied to files:
src/content/docs/self-hosted/installation.mdx
📚 Learning: 2026-04-13T10:43:05.628Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 590
File: src/components/templates/agent-connectors/_usage-databricks.mdx:83-83
Timestamp: 2026-04-13T10:43:05.628Z
Learning: In `src/components/templates/agent-connectors/_usage-*.mdx` files, the trailing `## Scalekit Tools` heading at the end of every usage template is intentional and consistent across all 42+ connector usage templates. It acts as a structural anchor/separator that the parent connector reference page uses to append the tool-list section beneath the proxy API examples. Do not flag this heading as empty or duplicate in future reviews of these template files.
Applied to files:
src/content/docs/self-hosted/installation.mdx
📚 Learning: 2026-03-12T16:28:42.817Z
Learnt from: Pranesh-Raghu
Repo: scalekit-inc/developer-docs PR: 483
File: src/components/templates/agent-connectors/_setup-zendesk.mdx:20-20
Timestamp: 2026-03-12T16:28:42.817Z
Learning: In src/components/templates/agent-connectors/_setup-*.mdx files, using plain Markdown link syntax (e.g., [Scalekit dashboard](https://app.scalekit.com)) for external links is acceptable and intentional. Do not flag the absence of target="_blank" and rel="noopener" attributes in these agent-connector setup template files. This follows the established pattern across all connector templates in this directory.
Applied to files:
src/content/docs/self-hosted/installation.mdx
📚 Learning: 2026-04-20T17:03:02.786Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 619
File: src/components/templates/agent-connectors/_usage-posthogmcp.mdx:82-82
Timestamp: 2026-04-20T17:03:02.786Z
Learning: In `src/components/templates/agent-connectors/_usage-posthogmcp.mdx`, the trailing `## Scalekit Tools` heading is intentionally omitted. The parent connector page (`src/content/docs/agentkit/connectors/posthogmcp.mdx`) renders the tool list separately via the `ToolList` component and the imported `tools` dataset, so the structural anchor heading used by other `_usage-*.mdx` templates is not needed here. Do not flag the missing `## Scalekit Tools` heading in this file.
Applied to files:
src/content/docs/self-hosted/installation.mdx
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Include configuration comments in code examples: '// Get the signing secret from Scalekit dashboard > Interceptors tab'
Applied to files:
src/content/docs/self-hosted/installation.mdxsrc/content/docs/self-hosted/configuration.mdxsrc/content/docs/self-hosted/setup-script.mdx
📚 Learning: 2026-03-29T07:52:33.367Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 546
File: public/api/scalekit.scalar.json:3511-3563
Timestamp: 2026-03-29T07:52:33.367Z
Learning: In scalekit-inc/developer-docs, when ambiguity is found in generated OpenAPI under public/api/**, open an upstream issue in scalekit-inc/scalekit documenting the contract change and link back to the PR comment, then resolve the review thread after posting the upstream issue link. Do not edit generated spec files directly in this repo.
Applied to files:
src/content/docs/self-hosted/configuration.mdx
📚 Learning: 2026-03-27T16:01:50.430Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-27T16:01:50.430Z
Learning: Applies to public/api/**/*.{json,yaml,yml} : API reference specifications must be generated from the `scalekit-inc/scalekit` repository; generated OpenAPI/Swagger specs must be placed in `public/api/` directory; permanent API reference changes must be made in the source repository, not in spec files in `public/api/`
Applied to files:
src/content/docs/self-hosted/configuration.mdx
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to public/api/** : Store API specifications in `public/api/` directory; all permanent API reference changes must be made in the `scalekit-inc/scalekit` repository, not in direct spec file edits
Applied to files:
src/content/docs/self-hosted/configuration.mdx
📚 Learning: 2026-03-10T12:26:38.439Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 476
File: src/content/docs/guides/integrations/sso-integrations/okta-oidc.mdx:84-99
Timestamp: 2026-03-10T12:26:38.439Z
Learning: In scalekit-inc/developer-docs, integration guide pages under `src/content/docs/guides/integrations/` (including SSO integrations, SCIM integrations, and social connections) do not require a "what's next" signal, "Next steps" section, or concluding navigation links. Do not flag the absence of these elements on integration guide pages.
Applied to files:
src/content/docs/self-hosted/configuration.mdx
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to public/api/** : API specifications are generated from the `scalekit-inc/scalekit` repository and MUST be placed in `public/api/` directory
Applied to files:
src/content/docs/self-hosted/configuration.mdx
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Every documentation page must include frontmatter with at least: `title` (≤60 chars), `description` (≤160 chars), and `sidebar.label` (1-3 words)
Applied to files:
src/content/docs/self-hosted/system-requirements.mdx
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : API references must include Endpoint Summary, Authentication, Base URL, Parameters, Request, Response, and Errors (with tables)
Applied to files:
src/content/docs/self-hosted/system-requirements.mdx
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Concept pages must include Overview, How it works, Key concepts, Use cases, Trade-offs (where relevant), Best practices, and Related guides
Applied to files:
src/content/docs/self-hosted/system-requirements.mdxsrc/content/docs/self-hosted/overview.mdx
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : API reference pages MUST include: Endpoint Summary, Authentication, Base URL, Parameters, Request, Response, and Errors (with tables)
Applied to files:
src/content/docs/self-hosted/system-requirements.mdx
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Applied to files:
src/content/docs/self-hosted/overview.mdx
| // Self-hosted deployment | ||
| 'self-hosted': ['/self-hosted/**/*'], | ||
|
|
There was a problem hiding this comment.
Topic pattern placement may cause routing issues.
The self-hosted topic is defined after the resources topic, which includes a catch-all '/**/*' pattern. Per the comment at lines 553-554, "first match wins" — pages under /self-hosted/**/* will match the resources catch-all before reaching this pattern.
Move self-hosted above resources to ensure correct topic assignment:
Proposed fix
// Modular SCIM (directory provisioning)
'modular-scim': ['/directory/**/*'],
// Agent Auth / Connect
connect: ['/agent-auth/**/*', '/reference/agent-connectors/**/*'],
+ // Self-hosted deployment
+ 'self-hosted': ['/self-hosted/**/*'],
+
// === Resources (integrations, workflows, references) ===
resources: [
'/resources/code-samples/**/*',
...
'/**/*', // Catch-all: anything not matched above defaults here
],
- // Self-hosted deployment
- 'self-hosted': ['/self-hosted/**/*'],
-
// === Developer Kit (tools, code, SDKs, AI helpers) ===🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/configs/sidebar.config.ts` around lines 604 - 606, The 'self-hosted'
topic definition is placed after the 'resources' topic which uses a catch-all
pattern and, due to "first match wins", will intercept /self-hosted/**/* pages;
move the 'self-hosted' entry so it appears before the 'resources' entry in
sidebar.config.ts (reorder the array/object entries so 'self-hosted':
['/self-hosted/**/*'] comes above the 'resources' topic) to ensure pages under
/self-hosted/**/* are assigned to the correct topic.
|
|
||
| export const kubectlConnectCmd = `kubectl apply -n <namespace> -f "${DISTR_URL}/api/v1/connect?targetId=<targetId>&targetSecret=<targetSecret>"` | ||
|
|
||
| Deploy Scalekit on any Kubernetes cluster using the Helm chart distributed through the <a href={DISTR_URL}>Scalekit distribution portal</a>. The chart uses the Kubernetes **Gateway API** for ingress. |
There was a problem hiding this comment.
Add safe external-link attributes on distribution portal anchors.
These external links should include target="_blank" and rel="noopener".
Suggested patch
-Deploy Scalekit on any Kubernetes cluster using the Helm chart distributed through the <a href={DISTR_URL}>Scalekit distribution portal</a>. The chart uses the Kubernetes **Gateway API** for ingress.
+Deploy Scalekit on any Kubernetes cluster using the Helm chart distributed through the <a href={DISTR_URL} target="_blank" rel="noopener">Scalekit distribution portal</a>. The chart uses the Kubernetes **Gateway API** for ingress.
@@
- Log in to the <a href={DISTR_URL}>Scalekit distribution portal</a>. This token authenticates your cluster to pull both the Helm chart and container images from <code>{REGISTRY_HOST}</code>.
+ Log in to the <a href={DISTR_URL} target="_blank" rel="noopener">Scalekit distribution portal</a>. This token authenticates your cluster to pull both the Helm chart and container images from <code>{REGISTRY_HOST}</code>.
@@
- Deployments are created through the <a href={DISTR_URL}>Scalekit distribution portal</a>.
+ Deployments are created through the <a href={DISTR_URL} target="_blank" rel="noopener">Scalekit distribution portal</a>.As per coding guidelines, external links in MDX should include target="_blank" and rel="noopener".
Also applies to: 27-27, 109-109
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/content/docs/self-hosted/installation.mdx` at line 22, The anchor linking
to the Scalekit distribution portal currently lacks safe external-link
attributes; update the <a href={DISTR_URL}>Scalekit distribution portal</a>
anchor to include target="_blank" and rel="noopener", and apply the same change
to the other external anchor occurrences referenced (anchors at the content
lines around 27 and 109) so all external MDX links use target="_blank" and
rel="noopener".
| echo " helm install scalekit oci://ar.scalekit.cloud/scalekit/charts/scalekit \\" | ||
| echo " --version ${CHART_VERSION} \\" | ||
| echo " -n ${NAMESPACE} \\" | ||
| echo " --values=${VALUES_FILE}" |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider using the config constant for the OCI registry URL.
The Helm chart OCI path ar.scalekit.cloud is hardcoded here. For consistency with the rest of the self-hosted docs (which use REGISTRY_HOST from the config), consider documenting this as a note or extracting to a constant if the OCI registry could change.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/content/docs/self-hosted/setup-script.mdx` around lines 272 - 275, The
Helm OCI registry host is hardcoded as ar.scalekit.cloud in the helm install
command; update the docs to use the existing config constant (REGISTRY_HOST)
instead of the literal so the OCI path is consistent with other self-hosted
docs. Replace the hardcoded host in the helm command string with
${REGISTRY_HOST} (or add a short preceding note showing REGISTRY_HOST is the OCI
registry) and ensure the associated example uses the same variable names as
other docs; update any surrounding text that references the OCI registry to
reference REGISTRY_HOST so readers know where to change it if the registry
changes.
| ## Check pod status first | ||
|
|
||
| Before investigating specific errors, confirm which pods are unhealthy: | ||
|
|
There was a problem hiding this comment.
Add a one-paragraph overview before the first troubleshooting section.
The page starts directly with an H2. Add a short opening paragraph that states what this page covers and when to use it.
As per coding guidelines, documentation pages should begin with an overview paragraph that frames scope and usage.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/content/docs/self-hosted/troubleshooting.mdx` around lines 19 - 22, Add a
short opening paragraph before the "## Check pod status first" heading that
briefly explains the scope of the troubleshooting page (what issues it covers,
e.g., common Kubernetes/self-hosted deployment failures and diagnostics) and
when to use it (who should consult this page and in what situations), keeping it
concise (1–2 sentences) to satisfy the documentation guideline requiring an
overview paragraph.
| kubectl get pods -n scalekit | ||
| kubectl describe pod <pod-name> -n scalekit | ||
| kubectl logs <pod-name> -n scalekit --tail=100 | ||
| ``` |
There was a problem hiding this comment.
Avoid hard-coded namespace/registry values in troubleshooting commands.
Commands currently assume scalekit and a fixed registry host. That breaks copy/paste troubleshooting for installs that used a custom namespace or a different registry endpoint.
Suggested patch
-kubectl get pods -n scalekit
-kubectl describe pod <pod-name> -n scalekit
-kubectl logs <pod-name> -n scalekit --tail=100
+kubectl get pods -n <namespace>
+kubectl describe pod <pod-name> -n <namespace>
+kubectl logs <pod-name> -n <namespace> --tail=100
@@
-kubectl logs <pod-name> -n scalekit -c scalekit --tail=100
+kubectl logs <pod-name> -n <namespace> -c scalekit --tail=100
@@
-kubectl logs <pod-name> -n scalekit -c dashboard --tail=100
+kubectl logs <pod-name> -n <namespace> -c dashboard --tail=100
@@
-kubectl logs <pod-name> -n scalekit -c svix --tail=100
+kubectl logs <pod-name> -n <namespace> -c svix --tail=100
@@
-**Cause**: The cluster cannot pull images from `ar.scalekit.cloud` — usually a missing or incorrect registry secret.
+**Cause**: The cluster cannot pull images from <code>{REGISTRY_HOST}</code> — usually a missing or incorrect registry secret.
@@
-kubectl get secret artifact-registry-secret -n scalekit
+kubectl get secret artifact-registry-secret -n <namespace>
@@
-kubectl get jobs -n scalekit
-kubectl logs job/scalekit-db-migrations -n scalekit
+kubectl get jobs -n <namespace>
+kubectl logs job/scalekit-db-migrations -n <namespace>
@@
-kubectl logs <pod-name> -n scalekit -c scalekit --previous
+kubectl logs <pod-name> -n <namespace> -c scalekit --previous
@@
-kubectl get gateway -n scalekit
-kubectl describe gateway scalekit -n scalekit
+kubectl get gateway -n <namespace>
+kubectl describe gateway scalekit -n <namespace>As per coding guidelines, examples should be consistent, runnable, and aligned with the documented deployment workflow.
Also applies to: 33-40, 48-48, 54-55, 70-72, 86-87, 104-106
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/content/docs/self-hosted/troubleshooting.mdx` around lines 24 - 27,
Replace hard-coded "scalekit" namespace and fixed registry host in the
troubleshooting examples with placeholder variables and a brief note on how to
set them (e.g., NAMESPACE and REGISTRY) so users can copy/paste for custom
installs; specifically update the commands shown (kubectl get pods -n scalekit,
kubectl describe pod <pod-name> -n scalekit, kubectl logs <pod-name> -n scalekit
--tail=100 and the other examples at the noted ranges) to use a placeholder like
${NAMESPACE} (and ${REGISTRY} where registry host appears) and add a one-line
instruction telling users to export or replace those variables to match their
deployment.
|
|
||
| If the issue is not covered here: | ||
|
|
||
| - **Community**: Join the [Scalekit Slack community](https://join.slack.com/t/scalekit-community/shared_invite/zt-3gsxwr4hc-0tvhwT2b_qgVSIZQBQCWRw) in the `#self-hosted` channel. |
There was a problem hiding this comment.
Use explicit external-link attributes for the Slack community link.
Convert the markdown link to an anchor with target="_blank" and rel="noopener".
As per coding guidelines, external links in MDX should include target="_blank" and rel="noopener".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/content/docs/self-hosted/troubleshooting.mdx` at line 122, Replace the
markdown link for the Scalekit Slack community ("Scalekit Slack community" /
`#self-hosted`) with an explicit anchor element that includes target="_blank"
and rel="noopener" so the external link opens in a new tab securely; update the
MDX line containing the Slack community link to use the HTML <a> tag with those
attributes while preserving the link URL and link text.
| --- | ||
| title: Upgrades & maintenance | ||
| description: How to upgrade your self-hosted Scalekit deployment and perform routine maintenance tasks. | ||
| sidebar: | ||
| label: Upgrades & maintenance | ||
| order: 7 | ||
| tags: [self-hosted, upgrades, maintenance, helm, kubernetes] | ||
| tableOfContents: true | ||
| prev: | ||
| label: Installation | ||
| link: /self-hosted/installation/ | ||
| next: | ||
| label: Troubleshooting | ||
| link: /self-hosted/troubleshooting/ | ||
| --- |
There was a problem hiding this comment.
Frontmatter structure issue: prev/next should be nested under sidebar.
The prev and next fields at lines 9-14 are at the root level, but per the pattern in quickstart.mdx, they should be nested under sidebar:. This may cause navigation links to not render correctly.
Proposed fix
---
title: Upgrades & maintenance
description: How to upgrade your self-hosted Scalekit deployment and perform routine maintenance tasks.
sidebar:
label: Upgrades & maintenance
order: 7
+ prev:
+ label: Installation
+ link: /self-hosted/installation/
+ next:
+ label: Troubleshooting
+ link: /self-hosted/troubleshooting/
tags: [self-hosted, upgrades, maintenance, helm, kubernetes]
tableOfContents: true
-prev:
- label: Installation
- link: /self-hosted/installation/
-next:
- label: Troubleshooting
- link: /self-hosted/troubleshooting/
---🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/content/docs/self-hosted/upgrades.mdx` around lines 1 - 15, The
frontmatter places prev and next at the root which breaks navigation; move the
prev: and next: blocks so they are children of the existing sidebar: block
(increase their indentation to match other sidebar children), remove them from
the root level, and ensure the YAML indentation is consistent so sidebar
contains label, order, tags (if any), plus prev and next entries; update the
frontmatter in the Upgrades & maintenance document by nesting the prev and next
keys under sidebar (referencing the existing sidebar, prev and next symbols).
- Remove pnpm from dependencies (caused Volta to treat it as project-scoped binary) - Add volta section to package.json pinning node and pnpm versions - Fix setup-git-hooks.js: use pnpm exec instead of npx/pnpm dlx - Fix install-d2.sh: map Darwin to macos to match release artifact filenames - Add D2 auto-install check to pre-push hook - Update README and CONTRIBUTING to mention Volta as optional
# Conflicts: # pnpm-lock.yaml # src/configs/secondary-nav.config.ts
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
src/configs/sidebar.config.ts (1)
610-612:⚠️ Potential issue | 🟠 MajorMove
self-hostedtopic aboveresourcescatch-all.Because matching is first-win and
resourcesincludes/**/*at Line 607,/self-hosted/**/*can be captured before reachingself-hosted. Placeself-hostedbeforeresources.Suggested fix
// AgentKit / Connect connect: ['/agentkit/**/*'], + // Self-hosted deployment + 'self-hosted': ['/self-hosted/**/*'], + // === Resources (integrations, workflows, references) === resources: [ @@ '/cookbooks/**/*', '/**/*', // Catch-all: anything not matched above defaults here ], - - // Self-hosted deployment - 'self-hosted': ['/self-hosted/**/*'],🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/configs/sidebar.config.ts` around lines 610 - 612, The 'self-hosted' sidebar entry is placed after the broad 'resources' catch-all so its path '/self-hosted/**/*' will never match; locate the 'self-hosted' key and move that object/entry so it appears before the 'resources' entry (the one using '/**/*') in the sidebar config, ensuring first-match ordering lets '/self-hosted/**/*' be matched first.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/configs/secondary-nav.config.ts`:
- Around line 190-225: saasKitItems contains a duplicate "api-reference" entry:
the inline object with id 'api-reference' and the separate sharedSdksItem both
render the same menu (causing duplicate keys/active-state issues). Remove the
inline object (the block starting with id: 'api-reference') and replace it with
the existing sharedSdksItem reference (or remove sharedSdksItem and keep the
inline object, but ensure only one remains); ensure the final saasKitItems array
only includes a single 'api-reference' item and that its children (ids 'sdks'
and 'rest-apis') are preserved.
---
Duplicate comments:
In `@src/configs/sidebar.config.ts`:
- Around line 610-612: The 'self-hosted' sidebar entry is placed after the broad
'resources' catch-all so its path '/self-hosted/**/*' will never match; locate
the 'self-hosted' key and move that object/entry so it appears before the
'resources' entry (the one using '/**/*') in the sidebar config, ensuring
first-match ordering lets '/self-hosted/**/*' be matched first.
🪄 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: d56278cc-0a17-471d-83b6-6729a5b188f5
⛔ Files ignored due to path filters (65)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yamlpublic/d2/docs/agentkit/authentication/token-management-0.svgis excluded by!**/*.svgpublic/d2/docs/agentkit/mcp/configure-mcp-server-0.svgis excluded by!**/*.svgpublic/d2/docs/agentkit/mcp/configure-mcp-server-1.svgis excluded by!**/*.svgpublic/d2/docs/agentkit/mcp/configure-mcp-server-2.svgis excluded by!**/*.svgpublic/d2/docs/agentkit/openclaw-0.svgis excluded by!**/*.svgpublic/d2/docs/agentkit/overview-0.svgis excluded by!**/*.svgpublic/d2/docs/agentkit/user-verification-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/auth-methods/authentication-flow-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/authz/create-roles-permissions-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/authz/implement-access-control-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/authz/overview-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/fsa/multiapp/native-app-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/fsa/multiapp/overview-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/fsa/multiapp/single-page-app-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/fsa/multiapp/web-app-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/implement-workflows/implement-webhooks-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/interceptors/auth-flow-interceptors-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/m2m/api-auth-quickstart-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/m2m/api-keys-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/manage-users-orgs/custom-user-attributes-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/manage-users-orgs/email-domain-rules-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/manage-users-orgs/email-domain-rules-1.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/manage-users-orgs/hosted-widgets-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/manage-users-orgs/jit-provisioning-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/manage-users-orgs/merge-identities-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/manage-users-orgs/merge-identities-1.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/manage-users-orgs/scim-provisioning-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/auth-patterns-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/auth-patterns-1.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/auth-patterns-2.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/auth-patterns-3.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/auth-patterns-4.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/custom-auth-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/expressjs-quickstart-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/fastapi-fastmcp-quickstart-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/fastmcp-quickstart-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/intro-to-mcp-auth-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/intro-to-mcp-auth-1.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/intro-to-mcp-auth-2.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/overview-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/overview-1.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/overview-2.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/overview-3.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/topologies/agent-mcp-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/topologies/human-mcp-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/topologies/mcp-api-0.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/topologies/mcp-api-1.svgis excluded by!**/*.svgpublic/d2/docs/authenticate/mcp/topologies/mcp-api-2.svgis excluded by!**/*.svgpublic/d2/docs/cookbooks/render-github-pr-summarizer-0.svgis excluded by!**/*.svgpublic/d2/docs/dev-kit/tools/use-scalekit-credentials-0.svgis excluded by!**/*.svgpublic/d2/docs/directory/guides/group-based-role-assignment-0.svgis excluded by!**/*.svgpublic/d2/docs/directory/scim/quickstart-0.svgis excluded by!**/*.svgpublic/d2/docs/fsa/data-modelling-0.svgis excluded by!**/*.svgpublic/d2/docs/fsa/guides/manage-users-0.svgis excluded by!**/*.svgpublic/d2/docs/fsa/guides/user-invitations-0.svgis excluded by!**/*.svgpublic/d2/docs/guides/integrations/auth-systems/firebase-0.svgis excluded by!**/*.svgpublic/d2/docs/guides/integrations/auth-systems/firebase-1.svgis excluded by!**/*.svgpublic/d2/docs/guides/sso/sso-migration-strategy-0.svgis excluded by!**/*.svgpublic/d2/docs/guides/sso/sso-migration-strategy-1.svgis excluded by!**/*.svgpublic/d2/docs/mcp/auth-methods/custom-auth-0.svgis excluded by!**/*.svgpublic/d2/docs/mcp/auth-methods/enterprise-0.svgis excluded by!**/*.svgpublic/d2/docs/passwordless/oidc-0.svgis excluded by!**/*.svgpublic/d2/docs/sso/guides/idp-init-sso-0.svgis excluded by!**/*.svgpublic/d2/docs/sso/guides/idp-init-sso-1.svgis excluded by!**/*.svg
📒 Files selected for processing (9)
.prettierignore.simple-git-hooks.jsonCONTRIBUTING.mdREADME.mdpackage.jsonscripts/install-d2.shscripts/setup-git-hooks.jssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Redirect rules - scalekit-starlight
- GitHub Check: Header rules - scalekit-starlight
- GitHub Check: Pages changed - scalekit-starlight
🧰 Additional context used
📓 Path-based instructions (9)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy,gradle,xml,json}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Comments should not duplicate the code - avoid comments that simply restate what the code does; comments should add value beyond what's obvious from reading the code
Files:
scripts/setup-git-hooks.jspackage.jsonsrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}: Good comments do not excuse unclear code - refactor the code to be self-explanatory instead of using comments to explain poorly written code; use better variable names, function names, and code structure
Comments should dispel confusion, not cause it - ensure comments clarify rather than obscure the code's purpose; avoid cryptic or joke comments
Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Provide links to the original source of copied code - always attribute code copied from external sources with URLs to Stack Overflow answers, GitHub repositories, or documentation
Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Add comments when fixing bugs - document bug fixes with context about the issue, reference issue trackers and bug reports, and explain workarounds and their limitations
Use comments to mark incomplete implementations - use standard formats for TODO, FIXME, and NOTE comments with context about what needs to be done and reference issue trackers when possible
Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements
Files:
scripts/setup-git-hooks.jssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)
Use JSDoc standards for all function, class, and complex logic comments in JavaScript/TypeScript - include parameter descriptions (
@param), return values (@returns), types (@type), and descriptions; document exceptions and edge cases
Files:
scripts/setup-git-hooks.jssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
**/*.{js,ts,tsx,py,go,java}
📄 CodeRabbit inference engine (AGENTS.md)
Use exact SDK variable names: Node.js:
scalekit, Python:scalekit_client, Go:scalekitClient, Java:scalekitClient
Files:
scripts/setup-git-hooks.jssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
**/*.{ts,js,mjs}
⚙️ CodeRabbit configuration file
**/*.{ts,js,mjs}: Do NOT enforce code-commenting style rules on these files.
Specifically, do not flag:
- Comments that "duplicate" or restate what the code does.
- Missing comments on bug fixes, workarounds, or issue references.
- Missing inline documentation or explanatory comments.
Code comments are at the author's discretion.
Files:
scripts/setup-git-hooks.jssrc/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
**/*.{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:
README.mdCONTRIBUTING.md
**/*.{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:
README.mdCONTRIBUTING.md
{src/configs/sidebar.config.ts,src/components/overrides/Header.astro,src/components/SecondaryNav.astro}
📄 CodeRabbit inference engine (CLAUDE.md)
Navigation structure must be coordinated across
src/configs/sidebar.config.tsandsrc/components/overrides/Header.astroandsrc/components/SecondaryNav.astro
Files:
src/configs/sidebar.config.ts
src/configs/sidebar.config.ts
📄 CodeRabbit inference engine (AGENTS.md)
Left sidebar is configured via
src/configs/sidebar.config.ts
Files:
src/configs/sidebar.config.ts
⚙️ CodeRabbit configuration file
src/configs/sidebar.config.ts: This file defines the user journey across ALL documentation sections.
When reviewing changes to this file:
- Verify that reordered items do not break the logical learning sequence
(e.g., "complete-login" must always come after "implement-login").- New items added to the FSA sidebar must follow the journey sequence:
Getting Started → User Auth → Auth Methods → Users & Orgs →
Authorization → Multi-App → APIs → Customize → Go Live.- Commented-out items (TODO) are acceptable but must include a comment
explaining WHY they are hidden.sidebarToSecondaryNavmappings MUST be updated whenever a new
sidebar section (id) is added.- External links MUST include the
attrsblock with
target: '_blank',rel: 'noopener noreferrer',class: 'external-link'.
Files:
src/configs/sidebar.config.ts
🧠 Learnings (38)
📓 Common learnings
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 546
File: public/api/scalekit.scalar.json:3511-3563
Timestamp: 2026-03-29T07:52:33.367Z
Learning: In scalekit-inc/developer-docs, when ambiguity is found in generated OpenAPI under public/api/**, open an upstream issue in scalekit-inc/scalekit documenting the contract change and link back to the PR comment, then resolve the review thread after posting the upstream issue link. Do not edit generated spec files directly in this repo.
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 0
File: :0-0
Timestamp: 2026-03-13T04:24:59.653Z
Learning: In scalekit-inc/developer-docs, for PRs focused on tooling and templatizing (e.g., extracting usage sections into reusable MDX templates and updating sync scripts), review comments about .mdx file content quality (casing, unused imports, import consolidation, endpoint descriptions, etc.) are considered out of scope and should be resolved without blocking the PR.
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 424
File: public/api/scalekit.scalar.json:3451-3457
Timestamp: 2026-02-10T05:32:59.967Z
Learning: In scalekit-inc/developer-docs, the file public/api/scalekit.scalar.json is a generated OpenAPI artifact; reviewers should avoid direct edits. For inconsistencies (e.g., the /api/v1/permissions "type" query param description vs. enum), handle short-term via release/PR notes and track long-term fixes in the generator or source templates rather than modifying the generated JSON.
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Documentation must be organized into logical sections (FSA, SSO, Directory/SCIM, Connect, M2M, Guides, Reference) with proper sidebar configuration and navigation structure
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Use pnpm for package management
Applied to files:
scripts/setup-git-hooks.jsREADME.mdpackage.jsonCONTRIBUTING.md
📚 Learning: 2026-03-20T02:32:40.836Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 514
File: src/content/docs/agent-auth/quickstart.mdx:82-82
Timestamp: 2026-03-20T02:32:40.836Z
Learning: In Agent Auth documentation under src/content/docs/agent-auth/, the Node.js SDK installation command should use the stable package `scalekit-sdk/node` (no version pin). Agent Auth features are now available in the stable release. Do not flag the removal of the `2.2.0-beta.1` beta version pin or suggest adding it back. Any remaining references to the beta version across Agent Auth docs should be updated to use the stable package.
Applied to files:
README.md
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Release notes and changelogs must be versioned and include Summary, detailed change sections (Added/Changed/Deprecated/Removed/Fixed/Security), Breaking changes, Migration guide, and Upgrade instructions
Applied to files:
README.mdCONTRIBUTING.md
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Release notes and change logs MUST include: Summary, detailed change sections (Added/Changed/Deprecated/Removed/Fixed/Security), Breaking changes, Migration guide, and Upgrade instructions
Applied to files:
README.mdCONTRIBUTING.md
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to pnpm-lock.yaml : Use pnpm for package management
Applied to files:
README.mdCONTRIBUTING.md
📚 Learning: 2026-04-02T09:59:43.872Z
Learnt from: saravanan2003-hub
Repo: scalekit-inc/developer-docs PR: 564
File: package.json:22-28
Timestamp: 2026-04-02T09:59:43.872Z
Learning: In scalekit-inc/developer-docs, the Astro-related dependencies (astrojs/mdx, astrojs/netlify, astrojs/starlight, astrojs/starlight-tailwind, astrojs/vue) are intentionally kept on Astro 5.x.x versions (not Astro 6.x) for compatibility reasons. Do not flag these as unintentional downgrades or suggest upgrading to Astro 6.x.
Applied to files:
package.json.prettierignore
📚 Learning: 2026-03-25T16:04:34.150Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 532
File: astro.config.mjs:302-302
Timestamp: 2026-03-25T16:04:34.150Z
Learning: In scalekit-inc/developer-docs, the D2 diagram generation behavior (skipped when the `NETLIFY` env var is set via `netlify dev`) is already documented in CONTRIBUTING.md. Do not flag missing documentation for this behavior in `astro.config.mjs`.
Applied to files:
CONTRIBUTING.md.prettierignore
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to src/configs/sidebar.config.ts : Left sidebar is configured via `src/configs/sidebar.config.ts`
Applied to files:
src/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to {src/configs/sidebar.config.ts,src/components/overrides/Header.astro,src/components/SecondaryNav.astro} : Navigation structure must be coordinated across `src/configs/sidebar.config.ts` and `src/components/overrides/Header.astro` and `src/components/SecondaryNav.astro`
Applied to files:
src/configs/secondary-nav.config.ts.prettierignoresrc/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to {src/components/overrides/Header.astro,src/components/SecondaryNav.astro} : Secondary navigation is managed through `src/components/overrides/Header.astro` and `src/components/SecondaryNav.astro`
Applied to files:
src/configs/secondary-nav.config.ts.prettierignore
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Changes to navigation structure MUST be coordinated across both sidebar configuration and header/secondary nav components
Applied to files:
src/configs/secondary-nav.config.tssrc/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to {tailwind.config.mjs,src/**/*.{astro,tsx}} : Maintain compatibility with Tailwind CSS styling
Applied to files:
.prettierignore
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to {astro.config.mjs,src/**/*.astro} : Follow Astro + Starlight framework conventions
Applied to files:
.prettierignore
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to src/components/templates/_*.{ts,tsx,astro} : Reusable content components in `src/components/templates/` (files starting with `_`) MUST be used and maintained for consistency across integration guides
Applied to files:
.prettierignore
📚 Learning: 2026-03-26T07:11:30.213Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 536
File: src/pages/apis.astro:34-37
Timestamp: 2026-03-26T07:11:30.213Z
Learning: In `src/pages/apis.astro` (Scalekit developer-docs), CSS rules injected via the `head: [{ tag: 'style', content: ... }]` frontmatter field are page-scoped to the `/apis` route only. Broad selectors like `.content-panel { border-top: none !important; }` applied this way are intentional and acceptable — do not flag them as overly broad since they cannot affect other pages.
Applied to files:
.prettierignore
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to {src/content/docs/guides/integrations/**/*.{md,mdx},src/components/templates/_*.{ts,tsx,astro}} : Integration guides in `src/content/docs/guides/integrations/` must be kept synchronized with their corresponding index pages and use reusable template components from `src/components/templates/`
Applied to files:
.prettierignore
📚 Learning: 2026-03-27T17:20:20.449Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/starlight-steps-tabs-structure.mdc:0-0
Timestamp: 2026-03-27T17:20:20.449Z
Learning: Applies to src/content/docs/**/*.mdx : In MDX documentation files, when `<Tabs>` is used inside a step, keep `<Tabs>`, `<TabItem>`, `</TabItem>`, and `</Tabs>` consistently nested under that step
Applied to files:
.prettierignore
📚 Learning: 2026-03-16T21:02:51.181Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-03-16T21:02:51.181Z
Learning: Applies to **/*.mdx : Import `<Code>` from `astrojs/starlight/components` once per file below frontmatter in `.mdx` files
Applied to files:
.prettierignore
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.mdx : Use Tabs/TabItem components for multi-language or multi-framework examples in MDX documentation
Applied to files:
.prettierignore
📚 Learning: 2026-03-16T21:02:51.181Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-03-16T21:02:51.181Z
Learning: Applies to **/*.mdx : Prefer `<Code>` component when you need any of: filename/title, text markers, programmatic/dynamic content, or consistent theming across tabs
Applied to files:
.prettierignore
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Use normal section headings instead of `<Steps>` when content is mostly `<Tabs>`, long JSX blocks, or multiple embedded components
Applied to files:
.prettierignore
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: All changes must pass format checking with Prettier, build process without errors, Git hook validations, and content structure validation
Applied to files:
.simple-git-hooks.json
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Documentation must pass Git hook validations
Applied to files:
.simple-git-hooks.json
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Set concise sidebar labels that match user vocabulary in navigation metadata
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-03-26T13:43:56.358Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 539
File: src/content/docs/cookbooks/search-scalekit-docs-in-your-ide.mdx:1-15
Timestamp: 2026-03-26T13:43:56.358Z
Learning: In scalekit-inc/developer-docs, the `/cookbooks` directory (src/content/docs/cookbooks/**/*.mdx) uses directory-based auto-generation in src/configs/sidebar.config.ts (mapped as '/cookbooks' and '/cookbooks/**/*'). Therefore, sidebar.label is NOT required in frontmatter for cookbook pages. Do not flag missing sidebar.label for files under this directory.
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-02-26T07:18:51.377Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 448
File: scripts/sync-agent-connectors.js:0-0
Timestamp: 2026-02-26T07:18:51.377Z
Learning: In src/content/docs/reference/agent-connectors/**/*.mdx files, sidebar.label frontmatter is not required because the sidebar configuration references the agent-connectors directory for auto-generation. Navigation ordering and grouping are managed centrally in the sidebar configuration file.
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Sidebar labels should be outcome- or object-focused: 'Install', 'CLI', 'HTTP server', 'Permissions'
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Sidebar labels should match page title semantics but be shorter when useful
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to src/content/docs/**/*.{md,mdx} : Prioritize topics and explanations by value and frequency of use; never teach bad habits or insecure patterns (never hard-code secrets or API keys)
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Proactively address common setup and configuration problems
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T14:34:06.246Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 618
File: src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx:66-77
Timestamp: 2026-04-20T14:34:06.246Z
Learning: In `src/content/docs/authenticate/manage-users-orgs/hosted-widgets.mdx`, do not flag the absence of an explicit `state`/CSRF validation warning next to the authorization URL examples in the "Signup/login widgets" section. The page already links to `/authenticate/fsa/implement-login/` where that security guidance is covered. Flagging it here is considered out of scope for this page.
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-02-26T07:21:37.207Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 448
File: src/content/docs/reference/agent-connectors/googlesheets.mdx:89-131
Timestamp: 2026-02-26T07:21:37.207Z
Learning: In src/content/docs/reference/agent-connectors/** MDX files, tool headings (e.g., `googlesheets_create_spreadsheet`, `googlesheets_get_values`) intentionally use H2 (##) instead of H3 to ensure they appear in the table of contents for easier navigation. This is a deliberate UX choice for agent connector reference pages and should not be flagged as a hierarchy issue.
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Explain security implications whenever relevant
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Prioritize topics and explanations by value and frequency of use
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:30:52.410Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-20T11:30:52.410Z
Learning: Applies to **/*.{md,mdx} : Put the topic words at the beginning of topic sentences to support fast skimming
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-13T10:43:05.628Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 590
File: src/components/templates/agent-connectors/_usage-databricks.mdx:83-83
Timestamp: 2026-04-13T10:43:05.628Z
Learning: In `src/components/templates/agent-connectors/_usage-*.mdx` files, the trailing `## Scalekit Tools` heading at the end of every usage template is intentional and consistent across all 42+ connector usage templates. It acts as a structural anchor/separator that the parent connector reference page uses to append the tool-list section beneath the proxy API examples. Do not flag this heading as empty or duplicate in future reviews of these template files.
Applied to files:
src/configs/sidebar.config.ts
📚 Learning: 2026-04-20T11:29:40.242Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-20T11:29:40.242Z
Learning: Applies to **/*.{md,mdx} : Use `<Tabs syncKey="tech-stack">` format for multi-language SDK samples with TabItem labels for each language
Applied to files:
src/configs/sidebar.config.ts
🔇 Additional comments (10)
.prettierignore (1)
40-43: LGTM: scoped ignore entries with clear justification.This keeps the ignore surface narrow and documents the plugin limitation clearly for future cleanup.
src/configs/secondary-nav.config.ts (1)
18-18: Icon import is correctly wired.
IconLucideServeris used by the newself-hostednav item, so this change looks good.src/configs/sidebar.config.ts (2)
472-499: Self-hosted sidebar section is structured well.The section grouping (
Getting started/Deploy/Maintain) and route wiring are consistent with the new docs set.
731-733: Secondary-nav mapping was correctly added for the new sidebar ID.
'self-hosted': 'self-hosted'keeps top-nav highlighting consistent with the new section.As per coding guidelines: "
sidebarToSecondaryNavmappings MUST be updated whenever a new sidebar section (id) is added."scripts/install-d2.sh (1)
35-35: Correct OS mapping for D2 artifact resolution.Line 35 correctly maps
Darwintomacos, which aligns with the archive naming pattern used later in the download URL.scripts/setup-git-hooks.js (1)
42-42: Hook installer command is aligned with repo tooling.Using
pnpm exec simple-git-hooksat Line 42 is the right move for consistent tool execution in this repository.Based on learnings: Use pnpm for package management.
CONTRIBUTING.md (1)
50-50: Useful tooling note for consistent local setup.The optional Volta guidance at Line 50 is clear and fits well with the existing prerequisites section.
README.md (1)
73-73: Good consistency with contributor setup docs.Line 73 mirrors the Volta recommendation from contributor docs and keeps local version management guidance aligned.
package.json (1)
85-88: Volta pinning is well configured.The
voltablock at Lines 85-88 is a solid addition for reproducible Node/pnpm versions across environments.Based on learnings: Use pnpm for package management.
.simple-git-hooks.json (1)
3-3: This review comment references code that does not exist in the current repository. The.simple-git-hooks.jsonfile at HEAD does not contain the D2 installation logic in thepre-pushhook. The current pre-push hook only includes uncommitted changes check, generate-search-index, build, and log-preview-url.js commands—not thecommand -v d2check mentioned in the review.While the technical concern about PATH changes from subshells not persisting to parent processes is valid in principle, the specific code being reviewed is not present in the codebase.
> Likely an incorrect or invalid review comment.
| { | ||
| id: 'api-reference', | ||
| href: '#sdks-apis', | ||
| label: 'SDKs & APIs', | ||
| iconComponent: IconMdiCubeOutline, | ||
| children: [ | ||
| { | ||
| id: 'sdks', | ||
| href: '/sdks/', | ||
| label: 'SDKs', | ||
| iconComponent: IconSdk, | ||
| description: 'Ready-to-use libraries to implement auth in your app', | ||
| }, | ||
| { | ||
| id: 'rest-apis', | ||
| href: '/apis/#description/overview', | ||
| label: 'REST APIs', | ||
| iconComponent: IconApi, | ||
| description: 'Programmatic control to manage users, orgs, sessions etc.', | ||
| }, | ||
| ], | ||
| }, | ||
| { | ||
| id: 'self-hosted', | ||
| href: '/self-hosted/overview/', | ||
| label: 'Self-hosted', | ||
| iconComponent: IconLucideServer, | ||
| }, | ||
| // Temporarily hidden - Agent Auth | ||
| // { | ||
| // id: 'agent-actions', | ||
| // href: '/agent-actions/quickstart', | ||
| // label: 'Agent Auth', | ||
| // iconComponent: IconLucideBot, | ||
| // }, | ||
| sharedSdksItem, |
There was a problem hiding this comment.
Remove duplicated api-reference entry from saasKitItems.
saasKitItems now contains two api-reference entries (inline block + sharedSdksItem) with identical child IDs. This will duplicate the menu item and can break stable active-state/key behavior.
Suggested fix
- {
- id: 'api-reference',
- href: '#sdks-apis',
- label: 'SDKs & APIs',
- iconComponent: IconMdiCubeOutline,
- children: [
- {
- id: 'sdks',
- href: '/sdks/',
- label: 'SDKs',
- iconComponent: IconSdk,
- description: 'Ready-to-use libraries to implement auth in your app',
- },
- {
- id: 'rest-apis',
- href: '/apis/#description/overview',
- label: 'REST APIs',
- iconComponent: IconApi,
- description: 'Programmatic control to manage users, orgs, sessions etc.',
- },
- ],
- },
+ sharedSdksItem,
{
id: 'self-hosted',
href: '/self-hosted/overview/',
label: 'Self-hosted',
iconComponent: IconLucideServer,
},
@@
- sharedSdksItem,📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| { | |
| id: 'api-reference', | |
| href: '#sdks-apis', | |
| label: 'SDKs & APIs', | |
| iconComponent: IconMdiCubeOutline, | |
| children: [ | |
| { | |
| id: 'sdks', | |
| href: '/sdks/', | |
| label: 'SDKs', | |
| iconComponent: IconSdk, | |
| description: 'Ready-to-use libraries to implement auth in your app', | |
| }, | |
| { | |
| id: 'rest-apis', | |
| href: '/apis/#description/overview', | |
| label: 'REST APIs', | |
| iconComponent: IconApi, | |
| description: 'Programmatic control to manage users, orgs, sessions etc.', | |
| }, | |
| ], | |
| }, | |
| { | |
| id: 'self-hosted', | |
| href: '/self-hosted/overview/', | |
| label: 'Self-hosted', | |
| iconComponent: IconLucideServer, | |
| }, | |
| // Temporarily hidden - Agent Auth | |
| // { | |
| // id: 'agent-actions', | |
| // href: '/agent-actions/quickstart', | |
| // label: 'Agent Auth', | |
| // iconComponent: IconLucideBot, | |
| // }, | |
| sharedSdksItem, | |
| sharedSdksItem, | |
| { | |
| id: 'self-hosted', | |
| href: '/self-hosted/overview/', | |
| label: 'Self-hosted', | |
| iconComponent: IconLucideServer, | |
| }, | |
| // Temporarily hidden - Agent Auth | |
| // { | |
| // id: 'agent-actions', | |
| // href: '/agent-actions/quickstart', | |
| // label: 'Agent Auth', | |
| // iconComponent: IconLucideBot, | |
| // }, |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/configs/secondary-nav.config.ts` around lines 190 - 225, saasKitItems
contains a duplicate "api-reference" entry: the inline object with id
'api-reference' and the separate sharedSdksItem both render the same menu
(causing duplicate keys/active-state issues). Remove the inline object (the
block starting with id: 'api-reference') and replace it with the existing
sharedSdksItem reference (or remove sharedSdksItem and keep the inline object,
but ensure only one remains); ensure the final saasKitItems array only includes
a single 'api-reference' item and that its children (ids 'sdks' and 'rest-apis')
are preserved.
2 participants
Summary by CodeRabbit
New Features
Documentation
Chores