AGENTS.md
+86 −200
https://raw.githubusercontent.com/iannuttall/seo/HEAD/AGENTS.md
− This is the source for `seo`, a local-first TypeScript SEO CLI, library,− router skill, and stdio MCP server. The public repository is− `iannuttall/seo`. The public npm package is the unscoped `seo` package.− `PRODUCT.md` is the durable product definition: users, purpose, brand− personality, vocabulary, and anti-references. Read it before writing any− user-facing copy or making product-shape decisions. This file owns the− engineering contract.− `CONTENT.md` is the durable writing guide for website copy, documentation,− report pages, command help, onboarding, metadata, and README content. Read it− before writing or editing user-facing language.− Reading `CONTENT.md` is mandatory in the same task before writing, editing, or− generating user-facing copy. Do not rely on memory or treat shared template− copy as an exception.− The product has two primary users:− - Humans start with a guided prompt flow and one main report.− - Agents use explicit flags, structured JSON, the router skill, and MCP tools.− Keep the human path calm. Keep the agent path powerful. Both paths must use the− same core report logic and return the same evidence.− `CLAUDE.md` must stay a symlink to this file. Do not maintain separate copies of− agent instructions.− ## Product Direction− - The product is local first. Do not add a required hosted backend, account,− database, job queue, or telemetry service. The optional hosted MCP keeps a− small encrypted sign-in store (see MCP Rules); the CLI and library never− need it.− - Tokens, provider keys, settings, and short-lived caches stay on the user's− machine.− - The product is the data layer, the pipe. It fetches data and returns it.− It does not save reports, history, projects, or decisions between runs, and− it adds no command whose job is to keep them. The agent decides what to− store and what to log. A crawl may hold what it needs while it runs.− - Optional research providers extend first-party evidence with keyword,− result, domain, competitor, and link estimates. They must never replace or− silently blend with Search Console, Google Analytics, crawl, or live result− evidence.− - Optional provider packages may add analytics or research adapters through the− public provider SDK. The main package owns the contracts, installation,− credentials, resource limits, registry, report semantics, and provenance.− Provider packages return normalized evidence and never add report findings,− public commands, MCP tools, or skill files.+ `seo` is a TypeScript SEO CLI, a local stdio MCP server, a hosted MCP server+ (`https://seoskill.dev/mcp`, `apps/mcp`), one skill and the seoskill.dev site+ (`apps/web`). The public repo is `iannuttall/seo`; the npm package is the+ unscoped `seo`. `CLAUDE.md` is a symlink to this file.+ This file holds only the rules you need for coding here that the code cannot+ tell you. Product and privacy decisions are not rules for this file.+ - Read `CONTENT.md` before you write copy a person reads: site, docs, help+ text, result text, README, metadata.+ - Read `apps/web/AGENTS.md` before you touch `apps/web`.+ ## Code patterns+ - Each shared command and MCP tool is defined once in+ `packages/core/src/commands` (`tools.ts`). The CLI, the local MCP server+ and the hosted server only supply a `ToolSurface`. Never put report logic+ in a surface.+ - Core code must run in Node and in Cloudflare Workers.+ - Bing blocks Cloudflare's network, so `HOSTED_BING` stays off and Bing+ calls run locally.+ - Provider packages (`seo/provider-sdk`) return normalized evidence only.+ - Decision models sit behind `packages/core/src/decision-model.ts`.+ - Edits to an agent's MCP config keep unrelated settings, make a backup and+ never replace an entry that `seo` did not write.+ - The Clicky account password never leaves the server.+ ## Report truth+ - Keep zero, missing, unavailable, filtered, partial and capped distinct. A+ capped or partial source cannot support a zero or an all-clear.+ - Do not claim causation, ranking impact or indexing unless the evidence+ shows that exact thing. Label heuristics as heuristics.+ - Keep each source's own metric names. A Clicky visit is not a Google+ Analytics session or user. Research data never replaces or blends with+ first-party data.+ - Search Console dates use the `America/Los_Angeles` calendar through the+ shared final-data helper.+ - Sort with stable tie-breakers so input order never changes output.+ - Read every JSON API response with `readJson`, never `response.json()`.+ - Bound every fetch, list and output before the work starts, not after.+ Peak memory follows the active work window, not the site size.+ ## Real data never goes in the repo+ Never write a real domain, site, client name or real account data into+ code, tests, fixtures, comments, docs, commits or PR text. Use+ `example.com`, `example.org` or `*.example`. Grep the diff for real domains
Showing the first 40 of each.
