Agent connection guide

WebmasterID has two related systems:

• WebmasterID Core — the tracker, the ingest API, the operator dashboard. Collects and structures events.
• webmasterid-agent — a separate AI-assisted growth-intelligence project. Reads sanitised analytics aggregates from Core, runs verified crawls inside the operator's workspace, computes per-page SEO state and the internal-link graph, generates recommendations and paste-ready prompts.

The end-to-end flow

The locked invariant of the platform is this sequence. Every step where the agent could "go further" is intentionally a human gate.

Tracker collects events
  → Core stores + aggregates owner-scoped data
  → Agent reads sanitised analytics aggregates (Core rule engine
    OR webmasterid-agent)
  → Agent generates recommendations / prompts / drafts
  → Human reviews
  → Human approves
  → Claude / Codex implements MANUALLY
  → Human deploys / reviews externally

The tracker / agent boundary

The agent is read-only with respect to analytics collection. The lines below are non-negotiable.

The agent must NEVER

• send commands to the tracker
• modify tracker behaviour
• generate synthetic events / fake traffic
• bypass bot detection
• manipulate analytics collection in any way
• auto-deploy / auto-push code
• auto-post / auto-email / auto-outreach
• scrape AI platforms or attempt to manipulate AI systems
• modify external websites

The agent may

• read sanitised analytics aggregates (owner-scoped)
• generate recommendations
• generate Markdown reports
• generate paste-ready Claude / Codex implementation prompts
• create reviewable drafts in the action queue for human approval

Approval is operator authorisation, never auto-execution

Approving an action draft is a state change inside WebmasterID. It is not a trigger for any external action. Marking a draft approved means the operator has reviewed the prompt / link / recommendation and is authorised to act on it manually. Marking it completed means the operator has finished acting.

webmasterid-agent (separate project)

webmasterid-agent is a separate, deeper growth-intelligence system. Conceptually it has these modules (canonical M1–M11 roadmap):

• Crawler snapshots (M2) — verified workspace crawls of the operator's own owned domains. Robots.txt honoured, rate-limited, conservative defaults.
• Per-page SEO state (M3) — metadata, headings, internal/external links, structured-data presence, derived from the latest crawl snapshot.
• Internal-link graph (M3) — source → target internal links extracted from the snapshot.
• Recommendation engine (M4) — traffic-weighted recommendations combining crawl signal with sanitised Core analytics.
• Prompt engine — paste-ready Claude Code prompts. Generating a prompt is not execution.
• Approval queue (M6) — mirror of Core's action-draft model.
• Promotion Opportunity Intelligence (M7) — score relevance + risk; emit drafts. Never auto-outreach.
• Content Opportunity Engine (M8) — clusters / orphan / thin / stub pages; emit content_creation prompts. Never mass AI content.
• AI Referral Intelligence (M9) — strengthen pages already receiving AI-assistant referrals. Never scrape AI platforms, never generate fake AI traffic, never manipulate AI systems.
• Internal Linking Intelligence Graph (M10) — internal authority scoring, source → target recommendations. Never auto-insert links, never hidden links.
• Cross-site Growth Intelligence (M11) — operator's OWN sites only. Never cross-tenant.

How Core integration works today (v1.5.x)

• Core exposes GET /api/agent/manifest — a stable, owner-safe orientation manifest with the canonical M0–M12 roadmap, the safe tool registry, the playbook, and the locked forbidden-actions list.
• Core exposes GET /api/agent/system-state — owner-scoped counts only (active sites, archived, pending + approved drafts, new + reviewing access requests) plus arecommendedAttention list.
• webmasterid-agent should treat the manifest's tools array as the canonical capability list. Tools with requiresApproval: true MUST result in a draft, never direct execution. Tools with externalEffect: true (currently zero) require both an approval gate AND a manual execution step.
• webmasterid-agent recommendations should sync into Core's /agent/actions queue as analytics_report or site_improvement_prompt drafts. Always go through Core's v1.3 sanitiser.
• webmasterid-agent should consume Core data via /api/agent/context or /api/reports/context. Never query Core's analytics tables directly.

The safe workflow, one more time

1. Analyse owned data (Core or webmasterid-agent).
2. Recommend.
3. Draft (action draft / approval queue item).
4. Approve (operator authorisation, not auto-execution).
5. Implement manually (you, or Claude Code, or Codex — running locally).
6. Deploy externally (you, with whatever your deploy pipeline is).

Related

• /architecture — the system shape (tracker → ingest → DB → dashboard).
• /docs/api — the agent + system-state endpoints.