docs: reorganize agent-auth around canonical docs

README.md

@@ -24,17 +24,34 @@ This plugin adds the complete Scalekit auth stack to your projects — whether t
 
 ### Installation
 
+```sh
+# One-line installer
+curl -fsSL https://raw.githubusercontent.com/scalekit-inc/claude-code-authstack/main/install.sh | bash
+```
+
+Or install manually inside Claude Code:
+
 ```sh
 # Start Claude REPL
 claude
 
 # Add Scalekit Auth Stack marketplace
 /plugin marketplace add scalekit-inc/claude-code-authstack
 
-# Run the plugins wizard
+# Install AgentKit for AI agents
+/plugin install agent-auth@scalekit-auth-stack
+
+# Open the plugins wizard
 /plugins
 ```
 
+After installation, enable auto-update:
+
+1. Open `/plugins`
+2. Go to `Marketplaces`
+3. Select `scalekit-auth-stack`
+4. Enable `auto-update`
+
 ---
 
 ### Available Plugins
@@ -125,12 +142,15 @@ Use this to add login, callback handling, sessions, and logout flows to web apps
 #### Documentation
 
 - [Scalekit Documentation](https://docs.scalekit.com) — Complete guides and API reference
+- [LLM docs map](https://docs.scalekit.com/llms.txt) — High-level index of published Scalekit documentation sets
+- [Docs sitemap](https://docs.scalekit.com/sitemap-0.xml) — Stable sitemap for discovering published docs pages
 - [Build with AI overview](https://docs.scalekit.com/dev-kit/build-with-ai/) — Claude, Codex, Copilot CLI, Cursor setup flows
 - [Modular SSO guide](https://docs.scalekit.com/authenticate/sso/add-modular-sso/) — Implement enterprise SSO
 - [MCP Auth guide](https://docs.scalekit.com/authenticate/mcp/quickstart/) — Secure MCP servers
 - [Full-stack auth guide](https://docs.scalekit.com/authenticate/fsa/quickstart/) — Add login, callback, and session management
 - [SCIM directory sync guide](https://docs.scalekit.com/directory/scim/quickstart/) — Provision and deprovision users
-- [Agent Auth Guide](https://docs.scalekit.com/agent-auth/quickstart/) — Authentication for AI agents
+- [AgentKit overview](https://docs.scalekit.com/agentkit/overview.md) — Connect agents to authenticated tools through connectors, connections, and connected accounts
+- [AgentKit quickstart](https://docs.scalekit.com/agentkit/quickstart.md) — Build an agent that makes authenticated tool calls on behalf of users
 
 #### Resources
 

install.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+REPO_SLUG="${CLAUDE_CODE_AUTHSTACK_REPO:-scalekit-inc/claude-code-authstack}"
+REPO_REF="${CLAUDE_CODE_AUTHSTACK_REF:-main}"
+SOURCE_DIR="${CLAUDE_CODE_AUTHSTACK_SOURCE_DIR:-}"
+
+if [[ -n "$SOURCE_DIR" ]]; then
+  exec "${SOURCE_DIR%/}/scripts/install_claude_marketplace.sh"
+fi
+
+TMP_DIR="$(mktemp -d)"
+cleanup() {
+  rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT
+
+ARCHIVE_URL="https://github.com/${REPO_SLUG}/archive/refs/heads/${REPO_REF}.tar.gz"
+ARCHIVE_PATH="$TMP_DIR/claude-code-authstack.tar.gz"
+
+echo "Downloading Scalekit Auth Stack for Claude Code from:"
+echo "  $ARCHIVE_URL"
+
+curl -fsSL "$ARCHIVE_URL" -o "$ARCHIVE_PATH"
+tar -xzf "$ARCHIVE_PATH" -C "$TMP_DIR"
+
+EXTRACTED_DIR="$(find "$TMP_DIR" -mindepth 1 -maxdepth 1 -type d | head -n 1)"
+
+if [[ -z "$EXTRACTED_DIR" ]] || [[ ! -x "$EXTRACTED_DIR/scripts/install_claude_marketplace.sh" ]]; then
+  echo "Failed to find installer in downloaded archive." >&2
+  exit 1
+fi
+
+exec "$EXTRACTED_DIR/scripts/install_claude_marketplace.sh"

plugins/agent-auth/.claude-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "agent-auth",
-  "description": "Implements Scalekit Agent Auth so AI agents can act in third-party apps (Gmail, Slack, Calendar, Notion) on behalf of users.",
-  "version": "1.8.2",
+  "description": "Sets up Scalekit AgentKit in Claude Code so agents can authorize users, discover tools, and execute authenticated tool calls across connectors.",
+  "version": "2.0.0",
   "author": {
     "name": "Scalekit",
     "email": "hi@scalekit.com"
   },
   "homepage": "https://docs.scalekit.com/dev-kit/build-with-ai/agent-auth/",
   "repository": "https://github.com/scalekit-inc/claude-code-authstack",
   "license": "MIT",
-  "keywords": ["scalekit", "agent-auth", "oauth", "connected-accounts"]
+  "keywords": ["scalekit", "agentkit", "agent-auth", "connectors", "tools", "connected-accounts"]
 }

plugins/agent-auth/.env.example

@@ -0,0 +1,5 @@
+SCALEKIT_ENV_URL=https://your-env.scalekit.dev
+SCALEKIT_CLIENT_ID=skc_your_client_id
+SCALEKIT_CLIENT_SECRET=your_client_secret
+# Optional sample connection name copied exactly from AgentKit -> Connections
+GMAIL_CONNECTION_NAME=MY_GMAIL

plugins/agent-auth/README.md

@@ -0,0 +1,98 @@
+# AgentKit for Claude Code
+
+## Purpose
+This plugin brings Scalekit AgentKit into Claude Code so an agent can connect users to third-party apps, discover the right tools, and execute authenticated tool calls on their behalf. It is organized as a hybrid structure: a Tessl-like canonical content layer and a Claude-specific adapter layer.
+
+Canonical content lives in:
+- `docs/` for durable AgentKit knowledge
+- `skills/` for task-oriented workflows
+- `rules/` for cross-cutting guidance
+
+Claude runtime files remain in place as adapters:
+- `.claude-plugin/`
+- `.mcp.json`
+- `commands/` for legacy slash-command aliases and compatibility shims
+- `hooks/`
+- `agents/`
+
+The plugin treats live AgentKit metadata as the source of truth for tool names, `input_schema`, and `output_schema`. Connector notes are curated guidance, not a guaranteed exhaustive catalog.
+
+## Installation
+```sh
+claude /plugin install agent-auth@scalekit-auth-stack
+```
+
+Start with the canonical docs entrypoint at [`docs/index.md`](docs/index.md).
+
+Official Scalekit docs:
+- [LLM docs map](https://docs.scalekit.com/llms.txt)
+- [Docs sitemap](https://docs.scalekit.com/sitemap-0.xml)
+- [AgentKit overview](https://docs.scalekit.com/agentkit/overview.md)
+- [AgentKit quickstart](https://docs.scalekit.com/agentkit/quickstart.md)
+- [AgentKit connectors](https://docs.scalekit.com/agentkit/connectors.md)
+- [AgentKit examples](https://docs.scalekit.com/agentkit/examples.md)
+
+## Skills Reference
+- `/agent-auth:integrating-agent-auth`
+  Integrates AgentKit into app code or an agent workflow and routes into the core docs.
+- `/agent-auth:discovering-agentkit-tools`
+  Uses live AgentKit metadata to find tools, inspect schemas, and narrow the tool set.
+- `/agent-auth:testing-agentkit-tools`
+  Generates authorization links, fetches live tool metadata, and executes tools from Claude Code. This is the preferred runnable playground surface.
+- `/agent-auth:building-agent-mcp-server`
+  Exposes AgentKit tools through MCP for MCP-compatible runtimes.
+- `/agent-auth:production-readiness-scalekit`
+  Runs a structured production-readiness checklist for AgentKit integrations.
+
+Legacy command alias:
+- `/test-tool [generate-link|get-tool|execute-tool ...]`
+  Compatibility wrapper for older usage. Prefer `/agent-auth:testing-agentkit-tools ...`.
+
+## Configuration
+Required environment variables:
+- `SCALEKIT_ENV_URL`
+- `SCALEKIT_CLIENT_ID`
+- `SCALEKIT_CLIENT_SECRET`
+
+Optional sample variable:
+- `GMAIL_CONNECTION_NAME`
+
+Legacy aliases supported by the testing command:
+- `TOOL_ENV_URL`
+- `TOOL_CLIENT_ID`
+- `TOOL_CLIENT_SECRET`
+
+Example `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "scalekit": {
+      "type": "http",
+      "url": "https://mcp.scalekit.com"
+    }
+  }
+}
+```
+
+## Usage Examples
+Typical flow for a new connector integration:
+1. Read [`docs/index.md`](docs/index.md) for the canonical model and [`docs/connections.md`](docs/connections.md) for connection naming.
+2. Create the connection in `AgentKit -> Connections`.
+3. Use `/agent-auth:integrating-agent-auth` to scaffold connected-account creation and authorization.
+4. Use `/agent-auth:discovering-agentkit-tools` or `/agent-auth:testing-agentkit-tools get-tool --provider GMAIL` to inspect the live tool catalog and schema.
+5. Use `/agent-auth:testing-agentkit-tools generate-link --connection-name <dashboard-connection-name> --identifier user_123` if the user still needs to authorize.
+6. Use `/agent-auth:testing-agentkit-tools execute-tool --tool-name gmail_fetch_mails --connection-name <dashboard-connection-name> --identifier user_123 --tool-input '{"query":"is:unread","max_results":5}'` to validate the payload before wiring it into application code.
+
+## Troubleshooting
+1. No tools show up for a connector:
+   Use live discovery first. The current tool inventory comes from AgentKit metadata, not static connector notes.
+2. The connection exists but auth or execution fails:
+   Verify that `connection_name` matches the exact dashboard value. It is not always the connector slug such as `gmail`.
+3. Tool execution fails after a user already connected:
+   Re-check the connected account status and re-authorize if the account is not `ACTIVE`.
+
+## Security
+This plugin needs AgentKit API credentials for your Scalekit environment. Store them in environment variables or a local secret manager, and never commit them to source control.
+
+Connected accounts are per-user authorization boundaries. Use the correct identifier, request minimum necessary scopes, and keep the tool set constrained before handing tools to an LLM.

plugins/agent-auth/commands/test-tool.md

@@ -0,0 +1,34 @@
+---
+description: Legacy compatibility alias for the AgentKit testing skill
+argument-hint: "[generate-link|get-tool|execute-tool] [args...]"
+allowed-tools: Bash
+---
+
+# Legacy AgentKit Tool Tester
+
+This command is a legacy compatibility alias for `/agent-auth:testing-agentkit-tools`.
+
+Prefer invoking the skill directly:
+
+```text
+/agent-auth:testing-agentkit-tools $ARGUMENTS
+```
+
+**Arguments:** $ARGUMENTS
+
+## Your task
+
+Parse `$ARGUMENTS` exactly as the testing skill would and run the same bundled script from the plugin root:
+
+```bash
+skills/testing-agentkit-tools/scripts/connect.py
+```
+
+Keep this command behavior aligned with the skill:
+
+- use `uv run python` when `uv` exists, otherwise `python3`, otherwise `python`
+- accept both `SCALEKIT_*` and legacy `TOOL_*` credential variables
+- inspect live metadata before guessing `tool_input`
+- show the command output, exact command, resolved parameters, and exact payload for `execute-tool`
+
+Do not maintain separate workflow rules here. The testing skill is the source of truth.

plugins/agent-auth/docs/byoc.md

@@ -0,0 +1,48 @@
+# Bring Your Own Credentials
+
+Bring Your Own Credentials (BYOC) lets you use your own OAuth applications and credentials instead of shared Scalekit defaults.
+
+## Why teams use BYOC
+
+Common reasons:
+
+- your branding appears during consent flows
+- you want your own quotas and provider relationship
+- you need stricter compliance or audit ownership
+- you want a more fully whitelabeled production experience
+
+## Official Scalekit docs
+
+- [Bring your own credentials](https://docs.scalekit.com/agentkit/advanced/bring-your-own-oauth.md)
+
+## What changes
+
+With BYOC:
+
+- the connection is still managed in AgentKit
+- connected accounts still authorize users in the same model
+- tools are still discovered and executed through AgentKit
+
+Only the credentials and upstream app ownership change.
+
+## Operational impact
+
+Moving to BYOC can require users to re-authorize, because the underlying OAuth application has changed.
+
+Plan for:
+
+- re-authentication
+- updated consent screens
+- different quotas or limits
+- provider-specific app verification steps
+
+## Where it fits in the plugin
+
+BYOC is a connection-level concern, not a tool-discovery concern.
+
+Set up the connection correctly first, then discover tools and test execution as usual.
+
+## Related docs
+
+- [connections.md](connections.md)
+- [connected-accounts.md](connected-accounts.md)

plugins/agent-auth/docs/code-samples.md

@@ -0,0 +1,54 @@
+# Code Samples
+
+This page is the canonical code-sample entrypoint for the plugin.
+
+Use it to choose an implementation style before opening a larger sample repository.
+
+## Common paths
+
+| Goal | Recommended path |
+|---|---|
+| Validate one tool quickly | Use `/agent-auth:testing-agentkit-tools` |
+| Integrate AgentKit into app code | Use `integrating-agent-auth` |
+| Build an agent with a framework | Use framework-specific examples below |
+| Expose tools over MCP | Use `building-agent-mcp-server` |
+
+## Framework directions
+
+- LangChain: fetch a narrow tool set and hand only the relevant tools to the agent
+- Google ADK: use AgentKit-authenticated tool wrappers for Gemini-based agents
+- Direct SDK usage: best for deterministic or single-tool flows
+- MCP: best when you want tools exposed to MCP-compatible runtimes
+
+## Official Scalekit docs
+
+- [AgentKit examples](https://docs.scalekit.com/agentkit/examples.md)
+- [Code samples](https://docs.scalekit.com/agentkit/code-samples.md)
+- [LangChain example](https://docs.scalekit.com/agentkit/examples/langchain.md)
+- [Google ADK example](https://docs.scalekit.com/agentkit/examples/google-adk.md)
+
+## Important rule
+
+Do not treat example code as a fixed tool catalog.
+
+Examples show patterns, not the current truth of:
+
+- which tools exist
+- what their schemas look like
+- which fields are required today
+
+Use [tool-discovery.md](tool-discovery.md) first when the exact tool surface matters.
+
+## Suggested sample flow
+
+1. Set up a connection.
+2. Create or fetch the connected account.
+3. Discover the exact tool and schema.
+4. Test it with the live playground.
+5. Move the validated payload into application or agent code.
+
+## Related docs
+
+- [tool-discovery.md](tool-discovery.md)
+- [connections.md](connections.md)
+- [connected-accounts.md](connected-accounts.md)