Atom eve seo

agent/SETUP.md

@@ -0,0 +1,91 @@
+---
+env:
+  - name: GSC_CREDENTIALS_JSON
+    description: JSON key of a Google service account added as a user on your Search Console property
+    url: https://console.cloud.google.com/iam-admin/serviceaccounts
+  - name: DATAFORSEO_LOGIN
+    description: DataForSEO API login, for the competitive SERP picture
+    url: https://app.dataforseo.com/api-access
+  - name: DATAFORSEO_PASSWORD
+    description: DataForSEO API password, shown next to the login
+    url: https://app.dataforseo.com/api-access
+  - name: GH_TOKEN
+    description: GitHub token with write access to the blog repo; only for the optional pull-request flow
+    url: https://github.com/settings/personal-access-tokens
+    optional: true
+config:
+  - name: Search Console property
+    description: The property the agent reads rankings from
+    example: sc-domain:example.com
+  - name: Project domain
+    description: The site being improved
+    example: example.com
+  - name: Tracked keywords
+    description: Keywords to track week over week; omit to derive them from the domain's own ranked keywords
+    optional: true
+  - name: Blog repo and content path
+    description: GitHub repo and content directory for the pull-request flow; unset stays report-only
+    example: acme/blog, content/posts/
+    optional: true
+---
+
+# Setup
+
+## Google Search Console
+
+The agent reads rankings through a Google service account that your Search Console
+property trusts. Any Google Cloud project on any of your Google accounts works; the
+only thing that ties it to your site is adding its email as a user in Search Console.
+
+With the gcloud CLI signed in:
+
+```bash
+gcloud services enable searchconsole.googleapis.com
+gcloud iam service-accounts create seo-improver
+gcloud iam service-accounts keys create /tmp/seo-improver-key.json \
+  --iam-account=seo-improver@PROJECT_ID.iam.gserviceaccount.com
+```
+
+Without gcloud: in the [Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts),
+enable the Search Console API, create a service account (no roles needed), and add a
+JSON key under Keys, then Add key. Keep the key file outside the project and delete it
+once the env var is set.
+
+Then the one step that is always manual: in [Search Console](https://search.google.com/search-console),
+select the property, open Settings, then Users and permissions, click Add user, and add
+the service account's email. Restricted permission is enough; the agent only reads.
+
+Set `GSC_CREDENTIALS_JSON` to the entire key-file JSON as a single line.
+
+To verify: mint an access token from the key (JWT bearer grant against
+`https://oauth2.googleapis.com/token`, scope `https://www.googleapis.com/auth/webmasters.readonly`)
+and `GET https://www.googleapis.com/webmasters/v3/sites`. The token-minting code ships in
+`agent/lib/search-console.ts`, ready to reuse. Free and read-only. The property
+must appear with a `permissionLevel` other than `siteUnverifiedUser`; an empty list means
+the user-add step is missing or still propagating (it can take a minute).
+
+## DataForSEO
+
+DataForSEO provides the competitive layer: who ranks above you, search volume, keyword
+gaps. Sign up at [dataforseo.com](https://dataforseo.com) (trial credit available), then
+copy the API login and password from the [API Access page](https://app.dataforseo.com/api-access).
+The API credentials are separate from your dashboard sign-in.
+
+To verify: `GET https://api.dataforseo.com/v3/appendix/user_data` with HTTP Basic auth
+(login:password). Free and read-only; expect `status_code: 20000` in the response body.
+
+## Store the values
+
+Local runs read `.env.local` (gitignored). Deployed and scheduled runs read Vercel
+project env: `vercel env add NAME production` takes the value from stdin, so pipe it in.
+Keep `GSC_CREDENTIALS_JSON` on a single line, quoted so the embedded quotes and
+backslashes survive dotenv parsing.
+
+## Point it at your project
+
+Fill in the `<!-- project-config -->` block at the top of `agent/instructions.md` with
+your property, domain, and optional keywords and blog repo. Leaving the blog repo unset
+keeps the agent report-only. Setting it lets the agent open pull requests against your
+blog: it runs the `gh` CLI in its sandbox and never pushes to your default branch. `gh`
+authenticates from `GH_TOKEN`; if the GitHub CLI is signed in locally, `gh auth token`
+prints one, or create a fine-grained token with write access to just that repo.