chore: adds a rule on how to manage Steps component#452
chore: adds a rule on how to manage Steps component#452saif-at-scalekit wants to merge 2 commits intomainfrom
Conversation
saif-at-scalekit
requested review from
amitash1912 and
ravibits
as code owners
saif-at-scalekit
changed the title
WalkthroughConsolidates documentation governance by making Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/commands/speckit.constitution.md:
- Around line 86-108: Remove the duplicate "<Steps> Indentation Rules" section
from this command file and migrate the canonical content into the project
constitution (the single source of truth); alternatively leave only a short
reference/copy in CLAUDE.md and delete the full rules here. Update any internal
references so documentation points to the constitution, and ensure the "<Steps>"
rules exist in only one place to avoid duplication and maintenance drift.
In `@CLAUDE.md`:
- Around line 158-180: Move the canonical "Starlight <Steps> Indentation Rules"
content into the project constitution document (the authoritative
constitution.md) and remove the duplicate section from speckit.constitution.md;
in CLAUDE.md keep a short reference pointing readers to the constitution for the
full rules and retain only a brief summary, ensuring the authoritative rules
(steps at column 0, continuation content indented exactly 3 spaces, no blank
line after <Steps>, treat block as a single continuous list) live only in the
constitution and duplicates are deleted.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
.claude/commands/speckit.constitution.mdCLAUDE.md
📜 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 (3)
**/*.{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:
CLAUDE.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:
CLAUDE.md
CLAUDE.md
⚙️ CodeRabbit configuration file
CLAUDE.md: CLAUDE.md is the quick-reference for AI assistant behavior in this repo.
- It MUST reference
.specify/memory/constitution.mdas the single
source of truth.- SDK variable names section is CRITICAL — any change here must be
intentional and reflected across all code examples in the docs.- The "Quality Checklist" section must end every AI-generated draft
withSTYLE-CHECK: [PASSED | TODO].
Files:
CLAUDE.md
🧠 Learnings (14)
📓 Common learnings
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} : Use sequential steps with verification checks for procedures in documentation
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 Steps component for sequential instructions in MDX documentation
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} : Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : Use numbered lists only inside `<Steps>` components for ordered procedures; use bulleted lists for unordered information
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 : Aside components within Steps must be indented with 3 spaces to avoid Steps component parsing errors
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use numbered format within Steps component: `1. ## Title` with all step content indented with exactly 3 spaces
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 : Each step in Steps component must use numbered format `1. ## Title` with exactly 3-space indentation for all step content
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 : Tabs components within Steps must be indented with 3 spaces, TabItem at same level as parent Tabs, code blocks properly indented within TabItem
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 : Ensure no trailing whitespace on empty lines within Steps components to avoid indentation errors
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Test MDX documentation locally before committing to catch parsing and Steps component indentation errors
📚 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} : Use sequential steps with verification checks for procedures in documentation
Applied to files:
.claude/commands/speckit.constitution.mdCLAUDE.md
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Use Expressive Code consistently across all documentation pages, preferring Starlight's `<Code>` component for rich features (titles, markers, accurate syntax highlighting) and dynamic snippets over fenced code blocks
Applied to files:
.claude/commands/speckit.constitution.mdCLAUDE.md
📚 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 : Each step in Steps component must use numbered format `1. ## Title` with exactly 3-space indentation for all step content
Applied to files:
.claude/commands/speckit.constitution.mdCLAUDE.md
📚 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 : Aside components within Steps must be indented with 3 spaces to avoid Steps component parsing errors
Applied to files:
.claude/commands/speckit.constitution.mdCLAUDE.md
📚 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 : Tabs components within Steps must be indented with 3 spaces, TabItem at same level as parent Tabs, code blocks properly indented within TabItem
Applied to files:
.claude/commands/speckit.constitution.mdCLAUDE.md
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use numbered format within Steps component: `1. ## Title` with all step content indented with exactly 3 spaces
Applied to files:
.claude/commands/speckit.constitution.mdCLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : Use numbered lists only inside `<Steps>` components for ordered procedures; use bulleted lists for unordered information
Applied to files:
.claude/commands/speckit.constitution.mdCLAUDE.md
📚 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 : Ensure no trailing whitespace on empty lines within Steps components to avoid indentation errors
Applied to files:
.claude/commands/speckit.constitution.mdCLAUDE.md
📚 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} : Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Applied to files:
.claude/commands/speckit.constitution.mdCLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : Use H2 for major sections, H3 for subsections, and H4 only inside `<Steps>`; never use H1 in body content and avoid nesting beyond H4
Applied to files:
.claude/commands/speckit.constitution.md
📚 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: Copy indentation from working Steps examples rather than typing manually to ensure proper MDX parsing
Applied to files:
.claude/commands/speckit.constitution.mdCLAUDE.md
📚 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: Test MDX documentation locally before committing to catch parsing and Steps component indentation errors
Applied to files:
CLAUDE.md
📚 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 : Add context before and after code blocks within Steps components to explain what the code accomplishes
Applied to files:
CLAUDE.md
| ## Starlight <Steps> Indentation Rules | ||
|
|
||
| The `<Steps>` component requires a single continuous `<ol>`. Any broken indentation splits it into multiple blocks and causes a build error. | ||
|
|
||
| **Rules**: | ||
|
|
||
| 1. Numbered steps must start at column 0 — no leading spaces | ||
| - ❌ WRONG — creates a sub-list, breaks the `<ol>` | ||
| - ✅ CORRECT — steps at column 0 | ||
|
|
||
| 2. Continuation content (images, text) must be indented with exactly 3 spaces | ||
| - ❌ WRONG — image at 4 spaces becomes a new block | ||
| - ✅ CORRECT — 3 spaces keeps it inside the list item | ||
|
|
||
| 3. Sub-bullet lists under a step use 3 spaces | ||
| - ❌ WRONG — 4 spaces, or blank line before the bullets | ||
| - ✅ CORRECT — 3 spaces, no blank line before bullets | ||
|
|
||
| 4. No blank line immediately after `<Steps>` opening tag | ||
| - ❌ WRONG — blank line after `<Steps>` | ||
| - ✅ CORRECT — content starts immediately after `<Steps>` | ||
|
|
||
| **Quick mental model**: Treat the entire `<Steps>` block as a single continuous list. All content (steps, continuation text, images, sub-bullets) must be indented to stay within that list structure. |
There was a problem hiding this comment.
Misplaced content: Move Steps rules to constitution or remove from this file.
This command file is specifically for managing the project constitution at .specify/memory/constitution.md. Adding general documentation formatting rules here is inconsistent with the file's purpose.
Per CLAUDE.md's own guidance: "The single source of truth for documentation rules is the project constitution at .specify/memory/constitution.md."
These Steps indentation rules should either:
- Be added to the constitution itself (as the source of truth), then referenced from CLAUDE.md
- Exist only in CLAUDE.md as a quick-reference copy
- Be removed from this command file entirely
The duplication across two files creates maintenance burden and risks inconsistency.
📋 Recommended approach
Remove this section from .claude/commands/speckit.constitution.md and ensure it exists in only one canonical location (preferably the constitution with a reference in CLAUDE.md).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/commands/speckit.constitution.md around lines 86 - 108, Remove the
duplicate "<Steps> Indentation Rules" section from this command file and migrate
the canonical content into the project constitution (the single source of
truth); alternatively leave only a short reference/copy in CLAUDE.md and delete
the full rules here. Update any internal references so documentation points to
the constitution, and ensure the "<Steps>" rules exist in only one place to
avoid duplication and maintenance drift.
| ### Starlight <Steps> Indentation Rules | ||
|
|
||
| The `<Steps>` component requires a single continuous `<ol>`. Any broken indentation splits it into multiple blocks and causes a build error. | ||
|
|
||
| **Rules**: | ||
|
|
||
| 1. Numbered steps must start at column 0 — no leading spaces | ||
| - ❌ WRONG — creates a sub-list, breaks the `<ol>` | ||
| - ✅ CORRECT — steps at column 0 | ||
|
|
||
| 2. Continuation content (images, text) must be indented with exactly 3 spaces | ||
| - ❌ WRONG — image at 4 spaces becomes a new block | ||
| - ✅ CORRECT — 3 spaces keeps it inside the list item | ||
|
|
||
| 3. Sub-bullet lists under a step use 3 spaces | ||
| - ❌ WRONG — 4 spaces, or blank line before the bullets | ||
| - ✅ CORRECT — 3 spaces, no blank line before bullets | ||
|
|
||
| 4. No blank line immediately after `<Steps>` opening tag | ||
| - ❌ WRONG — blank line after `<Steps>` | ||
| - ✅ CORRECT — content starts immediately after `<Steps>` | ||
|
|
||
| **Quick mental model**: Treat the entire `<Steps>` block as a single continuous list. All content (steps, continuation text, images, sub-bullets) must be indented to stay within that list structure. |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Document duplication concern: Consider consolidating source of truth.
This section duplicates content also added to .claude/commands/speckit.constitution.md (lines 86-108). The rules themselves are excellent and align with existing learnings, but the duplication creates maintenance risk.
Per your own guidance (line 5): "The single source of truth for documentation rules is the project constitution at .specify/memory/constitution.md."
Consider this architecture:
- Add these rules to
.specify/memory/constitution.md(the authoritative source) - Keep this section in CLAUDE.md but add a reference note: "See constitution for detailed rationale"
- Remove from
.claude/commands/speckit.constitution.mdentirely
This maintains CLAUDE.md's role as a "quick reference" while respecting the constitution as the source of truth.
Based on learnings, the actual rules here are correct: exactly 3-space indentation for continuation content, steps at column 0, no blank line after <Steps> tag, and treating the entire block as a single continuous list.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 158 - 180, Move the canonical "Starlight <Steps>
Indentation Rules" content into the project constitution document (the
authoritative constitution.md) and remove the duplicate section from
speckit.constitution.md; in CLAUDE.md keep a short reference pointing readers to
the constitution for the full rules and retain only a brief summary, ensuring
the authoritative rules (steps at column 0, continuation content indented
exactly 3 spaces, no blank line after <Steps>, treat block as a single
continuous list) live only in the constitution and duplicates are deleted.
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
…management from the documentation.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 395-411: Add the mandatory STYLE-CHECK completion line to the
"Quality Checklist" section by appending a final bullet or line that reads
exactly: STYLE-CHECK: [PASSED | TODO]; ensure this line appears as the explicit
end-of-draft marker immediately after the existing checklist items so every
AI-generated draft must include it.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (5)
.coderabbit.yaml.gitignoreCLAUDE.mdCONTRIBUTING.mdREADME.md
📜 Review details
🧰 Additional context used
📓 Path-based instructions (3)
**/*.{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:
CONTRIBUTING.mdCLAUDE.mdREADME.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:
CONTRIBUTING.mdCLAUDE.mdREADME.md
CLAUDE.md
⚙️ CodeRabbit configuration file
CLAUDE.md: CLAUDE.md is the single source of truth for all documentation standards in this repo.
- SDK variable names section is CRITICAL — any change here must be
intentional and reflected across all code examples in the docs.- The "Quality Checklist" section must end every AI-generated draft
withSTYLE-CHECK: [PASSED | TODO].
Files:
CLAUDE.md
🧠 Learnings (69)
📓 Common learnings
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 Steps component for sequential instructions in MDX documentation
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 : Each step in Steps component must use numbered format `1. ## Title` with exactly 3-space indentation for all step content
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} : Use sequential steps with verification checks for procedures in documentation
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/ted-docs-philosophy.mdc:0-0
Timestamp: 2026-01-13T12:48:26.894Z
Learning: Applies to **/*.{md,mdx} : Documentation titles and all sentences must follow ted-docs-philosophy principles: write simply and clearly with short, unambiguous sentences; avoid jargon unless necessary; use clear section titles, short paragraphs, topic sentences, and bulleted lists; maintain consistency in style, formatting, and terminology; use imperative mood and right-branching sentences; bold important information; introduce topics broadly and prioritize by value
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Use Expressive Code consistently across all documentation pages, preferring Starlight's `<Code>` component for rich features (titles, markers, accurate syntax highlighting) and dynamic snippets over fenced code blocks
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Documentation-First Development: Every feature must include comprehensive, user-focused documentation as a first-class deliverable that guides implementation, and all code changes require corresponding documentation updates
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
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} : Apply consistent spacing and typography in documentation
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Follow comment standards in code examples and document the 'why' rather than the obvious 'what'
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} : Write simply and directly with short sentences and plain language in documentation
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} : Maintain consistent terminology across documentation pages
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
📚 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:
.coderabbit.yamlCONTRIBUTING.mdCLAUDE.mdREADME.md
📚 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} : Maintain consistent terminology across documentation pages
Applied to files:
.coderabbit.yamlCONTRIBUTING.mdCLAUDE.mdREADME.md
📚 Learning: 2026-01-13T12:48:26.894Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/ted-docs-philosophy.mdc:0-0
Timestamp: 2026-01-13T12:48:26.894Z
Learning: Applies to **/*.{md,mdx} : Documentation titles and all sentences must follow ted-docs-philosophy principles: write simply and clearly with short, unambiguous sentences; avoid jargon unless necessary; use clear section titles, short paragraphs, topic sentences, and bulleted lists; maintain consistency in style, formatting, and terminology; use imperative mood and right-branching sentences; bold important information; introduce topics broadly and prioritize by value
Applied to files:
.coderabbit.yamlCONTRIBUTING.mdCLAUDE.mdREADME.md
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Keep headings parallel with similar grammatical form within a section in documentation
Applied to files:
.coderabbit.yamlREADME.md
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Follow comment standards in code examples and document the 'why' rather than the obvious 'what'
Applied to files:
.coderabbit.yamlCLAUDE.mdREADME.md
📚 Learning: 2026-01-13T12:47:33.407Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/comment-standards.mdc:0-0
Timestamp: 2026-01-13T12:47:33.407Z
Learning: Applies to **/*.{js,ts,tsx,jsx} : 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
Applied to files:
.coderabbit.yaml
📚 Learning: 2026-01-13T12:47:33.407Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/comment-standards.mdc:0-0
Timestamp: 2026-01-13T12:47:33.407Z
Learning: Applies to **/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy} : Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements
Applied to files:
.coderabbit.yaml
📚 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} : Prefer CLI-first examples and show file layout when helpful in documentation
Applied to files:
.coderabbit.yaml.gitignoreCONTRIBUTING.mdCLAUDE.mdREADME.md
📚 Learning: 2026-01-13T12:47:33.407Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/comment-standards.mdc:0-0
Timestamp: 2026-01-13T12:47:33.407Z
Learning: Applies to **/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy} : 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
Applied to files:
.coderabbit.yaml
📚 Learning: 2026-01-13T12:47:33.407Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/comment-standards.mdc:0-0
Timestamp: 2026-01-13T12:47:33.407Z
Learning: Applies to **/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy} : Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Applied to files:
.coderabbit.yaml
📚 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:
.coderabbit.yaml.gitignoreCONTRIBUTING.md
📚 Learning: 2026-01-13T12:47:33.407Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/comment-standards.mdc:0-0
Timestamp: 2026-01-13T12:47:33.407Z
Learning: Applies to **/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy} : Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Applied to files:
.coderabbit.yaml
📚 Learning: 2026-01-13T12:48:19.565Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/expressive-code.mdc:0-0
Timestamp: 2026-01-13T12:48:19.565Z
Learning: Applies to **/*.{md,mdx} : Use Expressive Code consistently across all documentation pages, preferring Starlight's `<Code>` component for rich features (titles, markers, accurate syntax highlighting) and dynamic snippets over fenced code blocks
Applied to files:
CONTRIBUTING.mdCLAUDE.md
📚 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} : Write simply and directly with short sentences and plain language in documentation
Applied to files:
CONTRIBUTING.mdCLAUDE.mdREADME.md
📚 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} : Don't assume reader knowledge of advanced concepts in documentation
Applied to files:
CONTRIBUTING.mdCLAUDE.md
📚 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} : Don't use inconsistent terminology across documentation pages
Applied to files:
CONTRIBUTING.mdCLAUDE.mdREADME.md
📚 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} : Apply consistent spacing and typography in documentation
Applied to files:
CONTRIBUTING.md
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use consistent SDK variable naming: Node.js='scalekit', Python='scalekit_client', Go='scalekitClient', Java='scalekitClient'
Applied to files:
CONTRIBUTING.mdCLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : Use Go variable name `scalekitClient` in all SDK examples
Applied to files:
CONTRIBUTING.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : Use Java variable name `scalekitClient` in all SDK examples
Applied to files:
CONTRIBUTING.mdCLAUDE.md
📚 Learning: 2026-02-25T13:04:35.551Z
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:35.551Z
Learning: In scalekit-inc/developer-docs MDX files, page-level CSS overrides in frontmatter (via `head:` tag with style content) are acceptable when used to improve readability and make content more inviting to readers, even if they override default Starlight typography. UX decisions on heading sizes can be made on a per-page basis to optimize the reading experience.
Applied to files:
CONTRIBUTING.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : Use Node.js variable name `scalekit` in all SDK examples
Applied to files:
CONTRIBUTING.mdCLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : Use Python variable name `scalekit_client` in all SDK examples
Applied to files:
CONTRIBUTING.md
📚 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:
CONTRIBUTING.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: All changes must follow Prettier format checking standards
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Update code examples when APIs or behaviors change
Applied to files:
CLAUDE.md
📚 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:
CLAUDE.mdREADME.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Documentation-First Development: Every feature must include comprehensive, user-focused documentation as a first-class deliverable that guides implementation, and all code changes require corresponding documentation updates
Applied to files:
CLAUDE.md
📚 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:
CLAUDE.md
📚 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} : Use sequential steps with verification checks for procedures in documentation
Applied to files:
CLAUDE.mdREADME.md
📚 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 : Ensure no trailing whitespace on empty lines within Steps components to avoid indentation errors
Applied to files:
CLAUDE.md
📚 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 : Aside components within Steps must be indented with 3 spaces to avoid Steps component parsing errors
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Write documentation in simple, right-branching, unambiguous sentences; avoid ambiguous noun stacks and demonstrative pronouns; maintain strict consistency in terminology, formatting, and style; use direct instructional language
Applied to files:
CLAUDE.mdREADME.md
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Start with an overview/value proposition and when to use the feature before detailed instructions
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : All code examples must use `<Tabs syncKey="tech-stack">` format for multi-language SDK samples with all 4 languages (Node.js, Python, Go, Java) for at least 90% of SDK-related snippets
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Technical Accuracy and Security: All technical content must be validated through testing; security implications must be clearly documented; API examples must be current and functional; authentication and integration examples must follow security best practices
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : All code examples must include imports (collapsible if noisy), realistic data, success and error paths with security comments stating the threat, why the pattern is required, and what can go wrong if omitted
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Journey-Focused Documentation: Product-based documentation (MCP Auth, Agent Auth, Full Stack Auth, Modular SCIM, Modular SSO) MUST follow a journey-focused approach representing a developer's journey toward implementing authentication
Applied to files:
CLAUDE.md
📚 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 code examples in all 4 languages (Node.js, Python, Go, Java) within Steps components
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-02T05:55:51.251Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/native-app.mdx:72-179
Timestamp: 2026-02-02T05:55:51.251Z
Learning: In the `src/content/docs/authenticate/fsa/multiapp/` directory, the multi-app authentication documentation (native-app.mdx, single-page-app.mdx, web-app.mdx, overview.mdx) currently uses conceptual shell/curl examples instead of multi-language SDK code examples because the Scalekit SDKs have not yet been built/updated for multi-app functionality. Once the SDKs are ready, these files should be updated to include all 4 languages (Node.js, Python, Go, Java) using `<Tabs syncKey="tech-stack">`.
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:47:33.407Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/comment-standards.mdc:0-0
Timestamp: 2026-01-13T12:47:33.407Z
Learning: Applies to **/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy} : Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Be broadly helpful in documentation by writing simply for new readers, avoiding abbreviations and jargon without clear definition, proactively addressing setup and configuration problems, keeping examples simple and self-contained, prioritizing by value and frequency, and never teaching bad habits or insecure patterns
Applied to files:
CLAUDE.md
📚 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} : Ensure code examples reflect current APIs and are tested when possible
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Make docs easy to skim by splitting content into clear sections with descriptive sentence-style titles, including a table of contents for multi-section documents, keeping paragraphs short, beginning sections with topic sentences, and using bullets and tables generously
Applied to files:
CLAUDE.md
📚 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} : Use active voice and imperative mood for steps and procedures in documentation
Applied to files:
CLAUDE.mdREADME.md
📚 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} : Follow a logical heading hierarchy (H2, H3, H4) and keep sections focused and scannable
Applied to files:
CLAUDE.md
📚 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: Use one idea per sentence or paragraph in documentation to improve skimmability
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Applied to files:
CLAUDE.mdREADME.md
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:47:12.462Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/browsecentral-labels.mdc:0-0
Timestamp: 2026-01-13T12:47:12.462Z
Learning: Applies to **/*.{yml,yaml,md,mdx} : BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
Applied to files:
CLAUDE.md
📚 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: Explain what matters to a developer trying to get work done - use audience-first language in documentation
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:47:52.148Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/deno-docs-style.mdc:0-0
Timestamp: 2026-01-13T12:47:52.148Z
Learning: Applies to **/*.{md,mdx} : Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Applied to files:
CLAUDE.md
📚 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 : Each step in Steps component must use numbered format `1. ## Title` with exactly 3-space indentation for all step content
Applied to files:
CLAUDE.md
📚 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 : Tabs components within Steps must be indented with 3 spaces, TabItem at same level as parent Tabs, code blocks properly indented within TabItem
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use numbered format within Steps component: `1. ## Title` with all step content indented with exactly 3 spaces
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : Use numbered lists only inside `<Steps>` components for ordered procedures; use bulleted lists for unordered information
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to **/*.{md,mdx} : Use H2 for major sections, H3 for subsections, and H4 only inside `<Steps>`; never use H1 in body content and avoid nesting beyond H4
Applied to files:
CLAUDE.md
📚 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} : Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Applied to files:
CLAUDE.md
📚 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 : Always include security comments in security-related code with pattern: '// Security: ALWAYS verify requests are from Scalekit before processing'
Applied to files:
CLAUDE.md
📚 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:
CLAUDE.md
📚 Learning: 2026-01-13T12:46:55.260Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursorrules:0-0
Timestamp: 2026-01-13T12:46:55.260Z
Learning: Applies to **/*.mdx : Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Applied to files:
CLAUDE.md
📚 Learning: 2026-02-25T18:40:05.360Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-25T18:40:05.360Z
Learning: Applies to src/content/docs/guides/integrations/**/*.mdx : Integration guides located in `src/content/docs/guides/integrations/` MUST be kept synchronized with their index pages at `sso-integrations/index.mdx`, `social-connections/index.mdx`, and `scim-integrations/index.mdx`
Applied to files:
CLAUDE.md
📚 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 todo/next step comments in code examples: '// TODO: Store user session (next guide covers this)', '// Next step: Create a session and log in the user'
Applied to files:
CLAUDE.md
📚 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 CheckItem component for best practices and checklists in MDX documentation
Applied to files:
CLAUDE.md
📚 Learning: 2026-01-13T12:48:11.566Z
Learnt from: CR
Repo: scalekit-inc/developer-docs PR: 0
File: .cursor/rules/documentation-guide.mdc:0-0
Timestamp: 2026-01-13T12:48:11.566Z
Learning: Applies to **/*.{md,mdx} : Provide links to related concepts, guides, and references in documentation
Applied to files:
CLAUDE.md
📚 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} : Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Applied to files:
CLAUDE.md
📚 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} : Maintain proper heading hierarchy and list semantics in documentation for accessibility
Applied to files:
README.md
📚 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} : Don't create overly long, unfocused documentation content
Applied to files:
README.md
🪛 markdownlint-cli2 (0.21.0)
CLAUDE.md
[warning] 275-275: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 309-309: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (6)
CLAUDE.md (2)
184-207: Strong addition:<Steps>indentation rules are precise and easy to enforce.This section clearly codifies the parser-sensitive constraints and should reduce recurring
<Steps>formatting regressions.
242-313: Fix fence delimiter mismatch: outer fence must open and close with matching backtick counts.The outer fence opens at line 242 with four backticks (`````mdx`) but closes at line 312 with three (````). Inner code blocks (lines 245, 261, 278, 296) open with three backticks but incorrectly close with four at lines 257, 275, and 292.
To fix: Keep the outer fence at four backticks (
mdx ...), and ensure inner code blocks close with three backticks to match their opening.Correct fix
Lines 257, 275, 292: change ```` to ``` Line 312: change ``` to ````Likely an incorrect or invalid review comment.
CONTRIBUTING.md (1)
33-33: Good governance alignment to a single standards source.Both updates consistently direct contributors to
CLAUDE.md, reducing rule fragmentation.Also applies to: 258-258
README.md (1)
117-120: Looks good — concise and consistent source-of-truth messaging.This update keeps contributor guidance clear and avoids split standards references.
.coderabbit.yaml (1)
196-200: Config update is coherent and schema-safe.The
CLAUDE.mdinstruction block is clear and consistent with the PR’s centralization objective..gitignore (1)
37-38: The current.gitignoreconfiguration is working correctly—the file is not ignored.The exception on line 37 successfully prevents
.claude/commands/speckit.constitution.mdfrom being ignored despite the broad.claude/pattern on line 38. This was verified withgit check-ignore, which confirms the file is not being ignored.The assumption in the original comment that "last-match-wins" would cause the parent pattern to override the negation does not apply here; the more specific negation pattern takes precedence over the broader ignore pattern.
No changes needed.
Likely an incorrect or invalid review comment.
| ## Quality Checklist | ||
|
|
||
| Before publishing documentation, verify: | ||
|
|
||
| - [ ] Headings and titles use sentence case | ||
| - [ ] Page opens with a clear, one-paragraph summary | ||
| - [ ] Steps use imperative verbs and are task-focused | ||
| - [ ] Examples are runnable and minimal, with contextual titles | ||
| - [ ] Sidebar label is concise (1-3 words) and matches the page | ||
| - [ ] Links are descriptive; APIs/flags use code formatting | ||
| - [ ] Terminology is consistent across the page | ||
| - [ ] No filler words ("just", "simply", "basically"), no passive voice where avoidable | ||
| - [ ] Code examples include all 4 languages (90% rule) | ||
| - [ ] SDK variable names follow the NON-NEGOTIABLE naming convention | ||
| - [ ] Security implications are explained where relevant | ||
| - [ ] Frontmatter includes title, description, and sidebar.label | ||
|
|
There was a problem hiding this comment.
Add the mandatory STYLE-CHECK completion line to the checklist.
The Quality Checklist currently omits the explicit end-of-draft marker requirement.
✅ Proposed addition
- [ ] Frontmatter includes title, description, and sidebar.label
+- [ ] End AI-generated drafts with `STYLE-CHECK: [PASSED | TODO]`As per coding guidelines, CLAUDE.md requires: “The "Quality Checklist" section must end every AI-generated draft with STYLE-CHECK: [PASSED | TODO].”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 395 - 411, Add the mandatory STYLE-CHECK completion
line to the "Quality Checklist" section by appending a final bullet or line that
reads exactly: STYLE-CHECK: [PASSED | TODO]; ensure this line appears as the
explicit end-of-draft marker immediately after the existing checklist items so
every AI-generated draft must include it.
2 participants
Summary by CodeRabbit