@seoagent-official/seoagent 1.67.0 → 1.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seoagent-official/seoagent",
-  "version": "1.67.0",
+  "version": "1.69.0",
   "description": "The persistent AI SEO agent for Claude Code. Audits, keyword strategy, briefs, articles, real product screenshots from your repo, and the autopilot loop (cloud detects → CLI executes → ack closes) — other SEO tools write the prompt, SEOAgent runs it.",
   "type": "module",
   "bin": {

package/skills/references/screenshots.md

@@ -47,6 +47,21 @@ Each gap that passes the SaaS gate is a screenshot to capture. When auditing/ref
 4. **Save it** to the repo's public asset directory — detect the convention (`public/screenshots/`, `static/screenshots/`, `assets/`) and create `screenshots/` there if absent. Name it `{page-slug}-{section}.png` (e.g. `pricing-hero.png`, `seo-audit-feature.png`).
 5. **Reference it** in the page/article with descriptive, keyword-aware alt text and responsive markup that matches how the site embeds images (Next.js `<Image>`, MDX `![alt](path)`, an existing image component — match the site's pattern). Alt text describes the screen + the keyword, e.g. `alt="SEOAgent dashboard showing a completed technical SEO audit with severity badges"`.
 
+## Auth-gated screens (log in for the capture)
+
+The most valuable SaaS screenshots — the dashboard, the audit view, the data tables — usually sit **behind login**. A route that redirects to `/login` is not a dead end: on **the user's own product, on their machine, with their go-ahead**, log in and capture the real UI. (Only ever do this for the project in the current repo — never a third-party site.)
+
+1. **Detect the auth system** from the repo — Supabase (`@supabase/ssr`, an `sb-<ref>-auth-token` cookie), NextAuth, Clerk, a custom JWT, etc. Find the login route and the callback route (e.g. `app/auth/confirm`).
+2. **Establish a session without a password** — never set or reset the user's password (it locks them out of their own account):
+   - **Supabase:** use the **service-role key already in the app's server env** to mint a one-time link for an account that owns real data — `supabase.auth.admin.generateLink({ type: 'magiclink', email })` → take `properties.hashed_token` → drive the app's *own* callback (`/auth/confirm?token_hash=<hash>&type=magiclink`) so the app sets the session cookie itself. Don't hand-craft the cookie.
+   - **Other providers:** reuse an existing local session/token if one is on disk; otherwise follow that provider's admin/impersonation path.
+   - **Pick the account that owns real data** (query for the row owner — e.g. the `user_token`/`website_token` that owns the site's rows) so the dashboard renders content, not an empty state.
+3. **Drive it with the repo's existing headless browser.** If Playwright/Puppeteer is **already a dependency** (check `package.json` — many apps ship it for tests/workers), use it to follow the login and capture. The "don't add Playwright" rule still holds — *don't add* one just for screenshots; only reuse what's already installed. If there's none, fall back.
+4. **Boot gotchas.** The dev server may refuse to start because the local `.env.local` is missing, or its var names have drifted from what the code reads (e.g. Supabase renamed `ANON_KEY`→`PUBLISHABLE_KEY` and `SERVICE_ROLE_KEY`→`SECRET_KEY`). Copy/alias the needed vars locally (the file is gitignored) to boot the server, and **remove any copied secrets when you're done**.
+5. **Mask PII in every authenticated frame** (see Conventions): before each screenshot, replace the account email, real name, and any billing info in the DOM with placeholders (`you@yourcompany.com`) and hide account menus. Product data — audit findings, keywords, page metrics — is fine to show; personal identifiers are not.
+
+If you genuinely can't get a session (no service-role key, external SSO you can't mint for, no headless browser already installed), fall back (below): leave a `SCREENSHOT-TODO`, and ask the user to run the dev server while logged in — or to drop the PNG in themselves.
+
 ## Frontmatter
 
 When the page uses `images:` frontmatter (landing pages, content), record the screenshot as a captured asset, not an AI prompt:
@@ -66,7 +81,7 @@ images:
 
 ## Fallback (never block the page)
 
-If the product can't be rendered/captured (no dev server, no screenshot tool available, the route needs auth you don't have, or there's no real UI yet):
+If the product can't be rendered/captured (no dev server, no screenshot tool available, the route needs auth you can't establish even via **Auth-gated screens** above, or there's no real UI yet):
 
 - Leave a marker where the shot belongs so the gap is visible and actionable later:
   ```html