docs: Update README with agent-first positioning#140
Open
saif-at-scalekit wants to merge 3 commits into
Open
Conversation
saif-at-scalekit
requested review from
Avinash-Kamath and
jranaskit
as code owners
WalkthroughRewrote and restructured the README: replaced left-aligned logo markup with a centered image, simplified badges, condensed feature/auth sections, removed prerequisites/minimum requirements, updated examples (added Django/Flask, Poetry install, FastAPI token handling), and added Helpful links and Contributing sections. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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: 3
🧹 Nitpick comments (4)
README.md (4)
34-34: Inconsistent capitalization in feature list.The bullet point starts with lowercase "passwordless" while all other bullets in both feature sections use title case. This breaks visual consistency.
📝 Proposed fix for consistency
-- **passwordless Authentication** — magic links, OTP, and modern auth flows +- **Passwordless Authentication** — magic links, OTP, and modern auth flows🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 34, The feature list bullet "passwordless Authentication" is inconsistent with the title case used elsewhere; update the text to "Passwordless Authentication" (replace the lowercase leading 'p' with uppercase) and scan the other bullets in both feature sections to ensure all items use Title Case for visual consistency.
118-118: Inconsistent capitalization in link text.The link text uses "setup Guide" with lowercase "s", while other links in the section use proper title case. This breaks visual consistency.
📝 Proposed fix for consistency
-- [setup Guide](https://docs.scalekit.com/guides/setup-scalekit/) — initial platform configuration +- [Setup Guide](https://docs.scalekit.com/guides/setup-scalekit/) — initial platform configuration🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 118, The link text "setup Guide" is inconsistently capitalized; update the link text in README.md to use title case (e.g., "Setup Guide") to match other links in the section—locate the anchor with the text "setup Guide" and change it to "Setup Guide" while keeping the URL (https://docs.scalekit.com/guides/setup-scalekit/) unchanged.
26-26: Inconsistent capitalization in technical acronyms.The line contains "Mcp" and "Dcr/pkce" which appear to be acronyms. For consistency and readability, consider using standard uppercase format: "MCP-Native OAuth 2.1" and "DCR/PKCE support".
📝 Proposed capitalization fix
-- **Mcp-Native OAuth 2.1** — Purpose-built for Model Context Protocol with Dcr/pkce support +- **MCP-Native OAuth 2.1** — Purpose-built for Model Context Protocol with DCR/PKCE support🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 26, Update the inconsistent acronym capitalization in the README: change "Mcp-Native OAuth 2.1" to "MCP-Native OAuth 2.1" and "Dcr/pkce" to "DCR/PKCE support" so both "MCP" and "DCR/PKCE" use standard uppercase formatting for technical acronyms.
100-104: Add blank lines around the table for proper markdown formatting.Markdown best practices require blank lines before and after tables to ensure proper rendering across different parsers and platforms.
📝 Proposed fix for table spacing
Framework Repository Description FastAPI scalekit-fastapi-example Modern async Python API framework Django scalekit-django-auth-example Django web framework integration Flask scalekit-flask-auth-example Flask microframework integration
</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@README.mdaround lines 100 - 104, The markdown table starting with "|
Framework | Repository | Description |" lacks surrounding blank lines which can
break rendering; add a single blank line immediately before and after that table
(i.e., insert a newline above the header row and another newline after the final
"| Flask ..." row or before the following "---") so the table is separated
from adjacent paragraphs and renders correctly in all markdown parsers.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@README.md:
- Line 5: The logo
tag in README.md is missing an alt attribute; add
meaningful alt text (e.g., alt="ScaleKit logo") to the existingelement
so screen readers can describe the image and improve accessibility.- Around line 52-58: Update the README example to import and instantiate the
correct exported class: replace the incorrect import/use of Scalekit with
ScalekitClient and change the constructor argument name environment_url to
env_url so the instantiation uses ScalekitClient(...) with client_id,
client_secret, and env_url parameters.- Around line 71-78: The FastAPI example uses the wrong exported name and
inconsistent parameter names; update the import to use the exported
ScalekitClient (not Scalekit) and make the constructor call use the correct
parameter name env_url (consistent with other examples), e.g. instantiate
ScalekitClient(..., env_url="https://your-env.scalekit.com", client_id="...",
client_secret="...") so the example compiles and matches the library API.
Nitpick comments:
In@README.md:
- Line 34: The feature list bullet "passwordless Authentication" is inconsistent
with the title case used elsewhere; update the text to "Passwordless
Authentication" (replace the lowercase leading 'p' with uppercase) and scan the
other bullets in both feature sections to ensure all items use Title Case for
visual consistency.- Line 118: The link text "setup Guide" is inconsistently capitalized; update
the link text in README.md to use title case (e.g., "Setup Guide") to match
other links in the section—locate the anchor with the text "setup Guide" and
change it to "Setup Guide" while keeping the URL
(https://docs.scalekit.com/guides/setup-scalekit/) unchanged.- Line 26: Update the inconsistent acronym capitalization in the README: change
"Mcp-Native OAuth 2.1" to "MCP-Native OAuth 2.1" and "Dcr/pkce" to "DCR/PKCE
support" so both "MCP" and "DCR/PKCE" use standard uppercase formatting for
technical acronyms.- Around line 100-104: The markdown table starting with "| Framework |
Repository | Description |" lacks surrounding blank lines which can break
rendering; add a single blank line immediately before and after that table
(i.e., insert a newline above the header row and another newline after the final
"| Flask ..." row or before the following "---") so the table is separated
from adjacent paragraphs and renders correctly in all markdown parsers.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `f4cca2dc-ef2f-44b1-be09-3b6674029435` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between e72387e0eeb54cfba7ec9bad6e16e8be42ae80e4 and 1aabdd77ae6a9d3020cc7e6b9431d5f4c6be995a. </details> <details> <summary>⛔ Files ignored due to path filters (1)</summary> * `scalekit-logo.svg` is excluded by `!**/*.svg` </details> <details> <summary>📒 Files selected for processing (1)</summary> * `README.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
- Refactor README structure for better readability - Add agent-first features section ahead of human auth - Update messaging to emphasize 'auth stack for agents' positioning - Add scalekit-logo.svg asset for consistent branding - Improve documentation links and quick start section - Align features description with current capabilities
saif-at-scalekit
force-pushed
the
docs/update-readme-agent-first
branch
from
1aabdd7 to
6583518
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
README.md (1)
52-58:⚠️ Potential issue | 🔴 CriticalFix SDK class name and constructor argument names in examples (currently inconsistent and likely incorrect).
Lines 52–58 and 71–77 use
Scalekitand mixenvironment_url/env_url. These examples should match the actual exported class and constructor signature exactly, otherwise copy-paste usage breaks.#!/bin/bash # Verify exported symbol and constructor parameters for README examples. set -euo pipefail echo "=== exports ===" fd -i "__init__.py" scalekit --exec sed -n '1,200p' echo echo "=== client class + __init__ signatures ===" ast-grep --pattern $'class $$$ {\n $$$\n}' --lang python 2>/dev/null || true rg -n -C3 --type=py '\bclass\s+Scalekit\w*\b|def __init__\(' scalekit echo echo "=== current README usage ===" rg -n -C2 'from scalekit import|Scalekit\(|ScalekitClient\(|environment_url|env_url' README.mdAlso applies to: 71-77
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 52 - 58, The README examples use the wrong/ inconsistent SDK class and constructor names (Scalekit vs actual export) and mix environment_url/env_url; open scalekit/__init__.py and the class definition (look for class ScalekitClient or similar and its def __init__ signature) to confirm the exact exported class name and parameter names, then update the README examples (both occurrences around the two example blocks) to instantiate the real exported class (e.g., ScalekitClient if that is the export) and use the exact constructor parameter names (replace environment_url/env_url with the actual parameter name found) so the copy-paste sample matches the source.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Around line 93-95: Do not return the access token in the response body and
harden the cookie flags: remove echoing token["access_token"] from the
Response(content=...) and instead set the token only via response.set_cookie
with security attributes (httponly=True, secure=True, samesite='Lax' or
'Strict', and consider path='/' and a sensible max_age). Update the example
where Response and response.set_cookie are used so the access token is not in
the body and the cookie is created with the recommended flags.
- Around line 99-105: The Markdown table in README.md violates markdownlint rule
MD058 because it isn't surrounded by blank lines; add a single empty line
immediately before the table's opening line ("| Framework | Repository |
Description |") and a single empty line immediately after the table's closing
line ("| **Flask** ... |") so the table block is separated from surrounding
content and linting passes.
---
Duplicate comments:
In `@README.md`:
- Around line 52-58: The README examples use the wrong/ inconsistent SDK class
and constructor names (Scalekit vs actual export) and mix
environment_url/env_url; open scalekit/__init__.py and the class definition
(look for class ScalekitClient or similar and its def __init__ signature) to
confirm the exact exported class name and parameter names, then update the
README examples (both occurrences around the two example blocks) to instantiate
the real exported class (e.g., ScalekitClient if that is the export) and use the
exact constructor parameter names (replace environment_url/env_url with the
actual parameter name found) so the copy-paste sample matches the source.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 6de5959e-5cae-4615-985e-21117e3eeec9
⛔ Files ignored due to path filters (2)
images/scalekit.jpgis excluded by!**/*.jpgscalekit-logo.svgis excluded by!**/*.svg
📒 Files selected for processing (1)
README.md
dhaneshbs
approved these changes
Mar 31, 2026
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Around line 22-23: Fix the README intro sentence by capitalizing the first
word and removing the awkward punctuation around the Scalekit link: replace the
phrase beginning "this is the official Python SDK for [Scalekit](...)," (which
contains "Scalekit](...), —") with a clean sentence like "This is the official
Python SDK for Scalekit — the auth stack for agents." Ensure the em-dash is
correctly placed (no stray comma) and preserve the following sentence "This
Python SDK enables both traditional B2B authentication and cutting-edge agentic
workflows." to keep flow and clarity.
- Line 5: Decide which logo file to use and make README consistent: either
update README's image reference (replace ./images/scalekit.jpg with
./scalekit-logo.svg) if you intend to use the SVG at repo root, or move
scalekit-logo.svg into the images/ folder and keep the README referencing
./images/scalekit.jpg (or replace the JPG with ./images/scalekit-logo.svg).
Ensure the README image src, alt text ("Scalekit"), and sizing (height="64") are
updated to match the chosen file name (scalekit.jpg or scalekit-logo.svg) and
that the referenced file actually exists in that path.
- Line 106: Remove the stray triple-backtick fence that follows the FastAPI code
snippet (the extra ``` closing delimiter) so the Markdown renders correctly;
locate the trailing fenced code delimiter that appears immediately after the
FastAPI example and delete that lone ``` line so the code block is properly
terminated only once.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| ## 🤖 Agent-First Features | ||
| <a href="https://scalekit.com" target="_blank" rel="noopener noreferrer"> | ||
| <picture> | ||
| <img src="./images/scalekit.jpg" alt="Scalekit" height="64"> |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify logo assets and README references.
set -euo pipefail
echo "== README image references =="
rg -n '\<img\s+src=' README.md
echo
echo "== Image files in repo (case-insensitive) =="
fd -i 'scalekit.*\.(svg|png|jpg|jpeg|webp)$' .
echo
echo "== Files under images/ =="
fd . images -t f || trueRepository: scalekit-inc/scalekit-sdk-python
Length of output: 201
🏁 Script executed:
#!/bin/bash
# Verify logo assets and README references (corrected)
set -euo pipefail
echo "== README image references =="
rg 'img.*src=' README.md || echo "No matches found"
echo
echo "== Image files in repo (case-insensitive) =="
fd -i 'scalekit.*\.(svg|png|jpg|jpeg|webp)$' . || echo "No matching image files found"
echo
echo "== Files under images/ directory =="
if [ -d images ]; then
fd . images -t f
echo "Directory exists"
else
echo "images/ directory does not exist"
fi
echo
echo "== README.md first 20 lines =="
head -20 README.md || echo "README.md not found"Repository: scalekit-inc/scalekit-sdk-python
Length of output: 1376
Confirm whether README should reference the SVG logo or the JPG file.
The referenced JPG file at ./images/scalekit.jpg exists and is correctly linked in README. However, an SVG file (scalekit-logo.svg) also exists at the repository root. If the PR objective was to add an SVG logo asset, the README should likely reference that instead, or the SVG should be moved to the images/ directory for consistency.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 5, Decide which logo file to use and make README
consistent: either update README's image reference (replace
./images/scalekit.jpg with ./scalekit-logo.svg) if you intend to use the SVG at
repo root, or move scalekit-logo.svg into the images/ folder and keep the README
referencing ./images/scalekit.jpg (or replace the JPG with
./images/scalekit-logo.svg). Ensure the README image src, alt text ("Scalekit"),
and sizing (height="64") are updated to match the chosen file name (scalekit.jpg
or scalekit-logo.svg) and that the referenced file actually exists in that path.
Comment on lines
+22
to
+23
| this is the official Python SDK for [Scalekit](https://scalekit.com), — the auth stack for agents. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (Mcp/APIs, delegated actions), all unified on one platform. | ||
| This Python SDK enables both traditional B2B authentication and cutting-edge agentic workflows. |
There was a problem hiding this comment.
Fix intro sentence grammar/capitalization for clarity.
The opening sentence starts with lowercase and has awkward punctuation (Scalekit](...), —). Clean this up to keep the README polished.
Suggested edit
-this is the official Python SDK for [Scalekit](https://scalekit.com), — the auth stack for agents. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (Mcp/APIs, delegated actions), all unified on one platform.
+This is the official Python SDK for [Scalekit](https://scalekit.com) — the auth stack for agents. Build secure AI products faster with authentication for humans (SSO, passwordless, full-stack auth) and agents (MCP/APIs, delegated actions), all unified on one platform.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 22 - 23, Fix the README intro sentence by
capitalizing the first word and removing the awkward punctuation around the
Scalekit link: replace the phrase beginning "this is the official Python SDK for
[Scalekit](...)," (which contains "Scalekit](...), —") with a clean sentence
like "This is the official Python SDK for Scalekit — the auth stack for agents."
Ensure the em-dash is correctly placed (no stray comma) and preserve the
following sentence "This Python SDK enables both traditional B2B authentication
and cutting-edge agentic workflows." to keep flow and clarity.
| import uvicorn | ||
| uvicorn.run(app, port=8080) | ||
| ``` | ||
| ``` |
There was a problem hiding this comment.
Remove the stray fenced code delimiter at Line 106.
There is an extra triple-backtick after the FastAPI snippet. This can break Markdown rendering for the following sections.
Proposed fix
@@
-```</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.0)</summary>
[warning] 106-106: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @README.md at line 106, Remove the stray triple-backtick fence that follows
the FastAPI code snippet (the extra closing delimiter) so the Markdown renders correctly; locate the trailing fenced code delimiter that appears immediately after the FastAPI example and delete that lone line so the code
block is properly terminated only once.
</details>
<!-- fingerprinting:phantom:triton:hawk:871a2b5e-49a0-4308-a849-e4aecc08311d -->
<!-- This is an auto-generated comment by CodeRabbit -->
Avinash-Kamath
approved these changes
Apr 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Updates the README with improved structure and agent-first messaging:
Summary by CodeRabbit