Auctor Launch Checklist

Current State Snapshot (Live from Supabase)

Environment Variables

Phase 1: Infrastructure — Get It Running

1.1 Add Missing API Keys

• Add ANTHROPIC_API_KEY to .env
• Add FIRECRAWL_API_KEY to .env
• Add DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD to .env
• Push updated env to vault: npx dotenv-vault@latest push

1.2 Verify Database Migrations

All Supabase migrations are already applied (78 migrations through keyword_clusters_and_serp_features). All schemas exist (auctor, consul, generative, mastra). No migration work needed.

• Confirmed: All 78 Supabase migrations applied
• Confirmed: auctor schema has all tables
• Confirmed: consul.posts exists (33 published posts)
• Confirmed: mastra schema exists (PostgresStore auto-created tables)

1.3 Install Dependencies & Build

• pnpm install — installs frontend + packages/auctor-mcp
• cd backend && uv sync --extra dev — Python backend deps
• pnpm build — verify Next.js builds (ignoreBuildErrors: true suppresses TS errors)
• Investigate any runtime errors that surface

1.4 Start Services

• pnpm dev — frontend starts on http://localhost:3000
• Verify Supabase connectivity: curl http://localhost:3000/api/content-engine/site
• Confirm site config returns (1 site target already exists)

1.5 Branch & Code Hygiene

Current branch: altonwells/fix-build-errors — 31 uncommitted changes, 4 deleted files.

• Review uncommitted changes (git diff)
• Commit or stash all changes
• Merge to main or create PR
• Resolve divergence (1 ahead, 4 behind main)

Phase 2: Site Configuration — Verify Foundation

2.1 Verify Site Registration

The site target already exists (1 row in auctor.site_targets).

• Navigate to /settings/site
• Verify: site name, brand name, owned domain are correct
• Verify: siteKey is set (used as foreign key across all data)
• API check: GET /api/content-engine/site returns populated config with stats

2.2 Verify Agent Configuration

11 agent runtime configs already exist in auctor.agent_runtime_config.

• Navigate to /settings/agents
• Review model assignments per agent role
• Confirm ANTHROPIC_API_KEY is set (agents won't work without it)
• Test: start a chat session via the agent harness — verify it responds

2.3 Verify Strategy Directive

1 strategy directive already exists.

• Review the active directive — does it reflect current content goals?
• Update if needed: content types, keyword tiers, posting cadence, priority rules
• This directive feeds the strategy planning workflow with guardrails

Phase 3: Populate Competitors — Fill the Gaps

3.1 Review Existing Competitor Data

33 competitor domains registered, 805 pages crawled, 250 snapshots captured.

• Navigate to /competitors
• Review which domains are registered and their crawl status
• Identify gaps: domains with 0 pages crawled, stale crawl dates
• Verify competitor tiers (1-3) and classifications are set

3.2 Crawl Missing Pages

Requires FIRECRAWL_API_KEY.

• For domains with low page counts, trigger discovery: mode=discover
• For blog/content sections, trigger crawl: mode=crawl_section with path patterns
• Monitor via /activity log or /competitors/[id]/status
• Target: all major competitor blog/content pages crawled with markdown content

3.3 Extract Signals from Crawled Pages

51 document extractions exist, but 346 documents are indexed — many pages lack extractions.

• Run page extraction workflow on un-extracted documents
• Extracts: keyword signals (high/medium/low prominence), topics, entities, schema.org
• Syncs competitor pages → auctor.documents for unified access
• Captures SEO metadata: title tags, meta descriptions, heading structure

3.4 Collect Domain Rankings (Requires DataForSEO)

Currently 0 rows in domain_rankings — no ranking data collected yet.

• Ensure DATAFORSEO_LOGIN/PASSWORD are set
• Fetch ranked_keywords per competitor domain → domain_rankings (~$0.05/call)
• Fetch domain_intersection for own domain vs competitors → keyword_domain_overlaps (~$0.02/call)
• Monthly budget: $100/month default, 80% warning, 95% hard stop

Phase 4: Populate Keywords & Mappings

4.1 Review Existing Keywords

178 tracked keywords exist, but 0 clusters and 0 keyword metrics.

• Navigate to /keywords
• Review keyword list — check lifecycle stages, intents, priorities
• Identify keywords lacking metrics or cluster assignments

4.2 Derive Additional Keywords from Competitor Data

• Run keyword derivation: deriveKeywordsFromCompetitors()
  • Sources: LangExtract keyword_signal extractions from competitor pages
  • Scoring: frequency across sources, prominence weighting, intent detection
  • Filters: 3-120 character length, deduplication
• Review new candidates, approve/reject

4.3 Enrich Keywords with Metrics (Requires DataForSEO)

0 rows in keyword_metrics — no enrichment done yet.

• Refresh metrics for all 178+ tracked keywords (~$0.01/keyword)
• Data collected: search volume, competition, difficulty, CPC, monthly trends
• AI search data: hasAiOverview, aiSearchVolume
• Budget: ~$1.78 for current keyword count

4.4 Cluster Keywords

0 rows in keyword_clusters — clustering hasn't been run.

• Run keyword clustering algorithm (Union-Find on SERP URL overlap)
• Requires SERP data — may need to fetch SERPs first via serp_live (~$0.02/keyword)
• Output: clusters with pillar keyword + satellites
• Each cluster gets: totalVolume, avgDifficulty, opportunityScore
• Review via /keywords UI — adjust pillars and groupings

4.5 Map Keywords → Content

• Keywords connect to content via clusterKey on plan items and documents
• Each plan item targets a targetKeyword and optionally links to a cluster
• Briefs receive keywordMapping (primary + secondary → outline sections)
• Lifecycle auto-tracks: discovery → research → targeting → ranking → decline

4.6 Google Search Console (Optional — Free)

• If GSC_CLIENT_EMAIL/GSC_PRIVATE_KEY are available:
  • Pull query performance: clicks, impressions, CTR, position
  • Stored in gsc_performance — free, no budget impact
  • Enriches keyword intelligence with real ranking data from your own domain

Phase 5: Verify MCP Tool Exposure

5.1 Start MCP Server

• Ensure pnpm dev is running (MCP proxies to Next.js API)
• Claude Code should auto-discover all auctor tools via .mcp.json

5.2 Test Each MCP Tool

• All read tools return populated data
• Write tools (manage_plan, run_workflow) execute successfully
• Activity log captures MCP mutations with source: 'mcp'

5.3 MCP Authentication (Production)

• For local dev: endpoints are open (no auth needed)
• For deployed access: set AUCTOR_MCP_SECRET bearer token

Phase 6: Full Content Creation Lifecycle

6.1 Strategy → Plan Items

Three paths to create plan items:

Path A — AI Strategy Workflow:

• Competitive intelligence → search landscape → content strategy
• Generates 3-6 prioritized plan items
• Suspends at calendar review gate → resume with approval='approve'

Path B — Manual via MCP:

Path C — Manual via UI:

• Navigate to /strategy/calendar → create and schedule items

• Create 2-3 plan items via any path

• Verify they appear in /strategy/calendar

• Verify auctor_list_content(stage='plan') returns them

6.2 Plan Item → Brief

• Agent generates brief: angle, outline, keyword mapping, competitor differentiation, voice
• Workflow suspends at brief approval gate
• Resume: auctor_run_workflow(action='resume', workflow='brief', run_id=<id>, approval='approve')
• Verify: content_briefs row with status='approved'

6.3 Brief → Draft

• Writer agent generates full markdown (title, meta, body, FAQ, schema, internal links)
• Editor agent reviews and refines (iterative cycles)
• Workflow suspends at human review gate — deep-edit capability
• Final cleanup agent normalizes without changing editorial voice
• SEO validation runs (20+ criteria, blocks if score < 10)
• Verify: content_drafts row created

6.4 Interactive Draft Editing

• Read draft section map
• Apply a test patch (edit a section heading or content)
• Verify patch history is tracked
• Chat-based editing: bind draft to thread via boundThreadId

6.5 Publish

• Dry run returns validation report (SEO score, warnings, blockers)
• Publish writes to consul.posts table
• Activity log records content.draft_published
• Indexing notification fires (currently stub — wire Google Indexing API later)

6.6 Monitor the Pipeline

• /activity — verify unified activity log captured every step
• /strategy/calendar — verify pipeline view shows items at each stage
• Keyword lifecycle: verify auto-updates (discovery → targeting → ranking)

Phase 7: Operational Readiness

7.1 End-to-End Smoke Test

• Complete one full cycle from competitor crawl to published post
• Verify activity log has entries for every step
• Verify MCP tools return correct data at each stage
• Verify /strategy/calendar reflects accurate pipeline state

7.2 Automations (Optional)

1 automation already exists in auctor.automations.

• Review existing automation — is it configured correctly?
• Consider adding: weekly competitor crawl, monthly keyword refresh, daily pipeline digest
• Set humanInTheLoop: true for critical automations (publishing, strategy changes)

7.3 Cost Guardrails

• DataForSEO: $100/month default cap (80% warning, 95% hard stop)
• Firecrawl: ~$0.01/page crawled — monitor total page count
• Anthropic: agent token costs tracked per workflow in activity log
• Monitor: costUsd, tokenCount, durationMs fields in activity log

7.4 Known Gaps (Non-Blocking)

Quick Reference

Key Files

Commands

MCP Tools Summary