serpkin 0.2.0 → 0.2.1

package/README.md

@@ -1,12 +1,34 @@
 # serpkin
 
-The SEO teammate for your coding agent. One command connects your repository, your agent and Serpkin.
+**The SEO teammate for Claude Code, Codex and Cursor.** Serpkin reads your site and your real search data, picks the one SEO fix worth doing next, and hands it to your coding agent with the files to change. After you ship, it checks the preview and measures whether the change helped.
 
 ```sh
 npx serpkin
 ```
 
-Requires Node 22 or newer. No dependencies.
+[Website](https://serpkin.com) · [Guides](https://serpkin.com/guides) · [Free SEO checker](https://serpkin.com/tools/seo-check) · [Claude Code](https://serpkin.com/integrations/claude-code) · [Cursor](https://serpkin.com/integrations/cursor) · [Codex](https://serpkin.com/integrations/codex)
+
+## Quick start
+
+1. In your website's repository, run `npx serpkin`. It signs you in, connects your agent and registers the site (about a minute).
+2. Ask your agent: _"What should I do for SEO?"_
+3. Your agent implements the mission. Before you merge, run `npx serpkin check <preview-url>` to catch SEO regressions.
+
+Requires Node 22 or newer. No dependencies. There is a free plan (one site); see [pricing](https://serpkin.com/#pricing).
+
+## What you get
+
+- **One mission at a time**, chosen from a crawl of your site and, once connected, your Google Search Console data. Not a list of 200 warnings.
+- **Patch-ready instructions**: the files to edit (from your route map), code snippets for metadata, sitemaps, redirects and structured data, and a definition of done.
+- **A preview check** that fails on regressions such as a new `noindex`, a removed title or canonical, or a broken sitemap.
+- **Results**: Serpkin verifies the fix on production and reports what changed in search afterwards.
+
+| Agent       | How it connects                                                      |
+| ----------- | -------------------------------------------------------------------- |
+| Claude Code | Plugin with a skill, slash commands and hooks, or a plain MCP server |
+| Cursor      | `.cursor/mcp.json` plus a project rule                               |
+| Codex       | `~/.codex/config.toml` plus a section in `AGENTS.md`                 |
+| Others      | Any MCP client: `https://serpkin.com/api/mcp` with your agent key    |
 
 ## What `npx serpkin` does
 
@@ -95,3 +117,23 @@ Preview hosts must be the site's own domain or subdomains, or `*.vercel.app`, `*
 ### GitHub Action
 
 Copy [`templates/github-action.yml`](templates/github-action.yml) to `.github/workflows/serpkin.yml` then add a repository secret `SERPKIN_API_KEY` (create a key with `npx serpkin` or in Settings → Agent setup) and a repository variable `SERPKIN_SITE_ID` (the `site_id` from `.serpkin.json`). The workflow doesn't check out the pull request, so code or config from a PR never runs while the key is available, and it pins the CLI version. It runs on `deployment_status` events, which Vercel sends when a preview finishes deploying. It checks the deployment's `target_url` and fails the job when the preview introduces a regression. If your previews use Vercel Deployment Protection, Serpkin's requests get HTTP 401. Allow them through, or the check reports the preview as unreachable.
+
+## What leaves your machine
+
+- **Sent to Serpkin:** your site URL, the answers you give during setup (the site description defaults to the one in `package.json`), and the route map (URL paths and the source file names that serve them, up to 2,000 routes). Your agent sends what it asks Serpkin for through MCP.
+- **Never sent:** your source code, environment files or the contents of your repository. To detect the framework and build the route map, the CLI reads `package.json` and the file names in your routes folder, not their contents. It also updates your agent's config files (`.mcp.json`, `.cursor/`, `AGENTS.md`, `~/.codex/config.toml`) as described above.
+- **Stored locally:** your agent key in `~/.config/serpkin/credentials.json` (mode 600), never in the repository.
+
+Details: [privacy policy](https://serpkin.com/legal/privacy).
+
+## Troubleshooting
+
+- **Serpkin can't reach your site**: Serpkin needs a public URL. Use a preview deploy with `--url`, not `localhost`.
+- **Preview check returns 401**: your preview is behind deployment protection. Allow Serpkin's requests or check a public preview.
+- **The agent doesn't see Serpkin**: make sure `SERPKIN_API_KEY` is exported in the shell your agent starts from, then restart the agent.
+- **Start over**: re-run `npx serpkin`. It reuses the stored key and site and refreshes only its own blocks.
+
+## Support and license
+
+Questions or bugs: [serpkin.com](https://serpkin.com) or the [plugin repository](https://github.com/apwn/serpkin-plugin/issues). MIT licensed (this CLI and the Claude Code plugin).
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serpkin",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Connect your coding agent to Serpkin: sign in, register your site, upload its route map, and check pull-request previews for SEO regressions.",
   "type": "module",
   "bin": {

package/plugin/serpkin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "serpkin",
   "displayName": "Serpkin",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The SEO brain for your coding agent: ranked SEO missions with patch-ready plans, preview checks and verification.",
   "author": {
     "name": "Serpkin",

package/templates/github-action.yml

@@ -36,4 +36,4 @@ jobs:
           # Passed through env, not interpolated into the script, so the URL can't inject shell.
           PREVIEW_URL: ${{ github.event.deployment_status.target_url }}
         # Pinned version and registry; update the version deliberately.
-        run: npx --yes --registry=https://registry.npmjs.org serpkin@0.2.0 check "$PREVIEW_URL" --site "$SERPKIN_SITE_ID"
+        run: npx --yes --registry=https://registry.npmjs.org serpkin@0.2.1 check "$PREVIEW_URL" --site "$SERPKIN_SITE_ID"