MDX Limo
CLAUDE.md — Auctor

CLAUDE.md — Auctor

Auctor is a bounded-autonomy content operator: it runs the content lifecycle for Consul (consul.so) from research through publishing, with human approval gates at every major transition. Single operator, database-first, policy-governed.

Mental Model

Three execution surfaces: Web UI (Next.js, port 3000), Desktop (Electron + native Claude Code binary), MCP tools (17 tools proxied through Next.js).

Monoagent pattern. One agent (auctor) handles all tasks, loading domain-specific skills on demand. Legacy role IDs (competitive-intelligence, search-landscape, content-strategy, content-brief, writer, editor, final-cleanup, publishing, seo-autofix) exist for backward compatibility in workflow steps — they map to skill hints via agentIdToSkills, not separate agents.

Database-first. Postgres/Supabase is canonical truth. Four schemas: auctor (control plane — pipeline, competitors, keywords, config), consul (publish destination — posts, categories), generative (legacy, migrating to auctor), mastra (framework state — do not modify directly).

Skills as editable doctrine. Expertise lives in versioned Markdown files, not hardcoded prompts. 9 default skill domains managed by frontend/src/content-engine/skills/catalog.ts.

Commands

Package managers: pnpm (workspace root, frontend, desktop, packages), uv (Python backend).

1pnpm dev # Frontend dev server (port 3000) 2pnpm dev:backend # Backend (uvicorn, port 8000) 3pnpm dev:all # Both concurrently 4pnpm dev:all-desktop # All three + Electron 5 6pnpm build # Production build (frontend) 7pnpm lint # ESLint 8pnpm test:frontend # Vitest 9 10cd backend && uv sync --extra dev # Python deps 11cd backend && uv run pytest # All backend tests 12cd backend && uv run pytest tests/test_extract.py::test_health -v # Single test

Database

Supabase projects:

Generative, Inc. (lmwnjkhdhrsruedgqsza, us-east-2). Use these IDs with Supabase MCP tools. This is where auctor lives 95%) of work will be here.

Consul Agent (wsagglvhelbkpalingjk, us-west-2) this is where we publish and push content to.

Web App

Stack: Next.js 16 (App Router), React 19, TypeScript 5.7, Tailwind CSS v4, shadcn/ui (new-york), Supabase JS, Mastra AI. Path alias @/* → frontend root.

All pages use the (app) route group (shell layout: sidebar + header + context panel + agent dock). Routes are in frontend/app/(app)/. Navigation: frontend/lib/app-navigation.ts.

Header system: The header is an action bar, NOT a title display. Pages inject controls via useHeaderSlot(). Never render page titles in the header.

Data fetching: Server components call repositories directly. Client mutations go through /api/content-engine/ routes. Agent chat uses useChat() from @ai-sdk/react.

Desktop

Electron app spawns the native Claude Code binary (Mach-O at ~/.local/bin/claude) via child_process.spawn() with stdin/stdout JSON lines.

Tool policy: Read tools auto-allow. Write/edit tools allow if inside workspace. Safe git auto-allow. Destructive git and MCP publish require approval.

Key files: desktop/src/claude/runtime-manager.ts (session lifecycle), resolve-binary.ts (Mach-O validation), env-assembly.ts (8-layer env), tool-policy.ts (approval rules).

Activity Log

auctor.activity_log is the single observability stream. Every meaningful action must write to it.

Categories: agent, workflow, content, competitor, seo, job, config, automation, chat. Sources: system, agent, user, scheduler, mcp. Use recordActivityWithContext() — fire-and-forget, never block. Dot-notation actions: category.verb (e.g., content.draft_published, job.started). Always pass costUsd/tokenCount/durationMs for LLM calls. Link entities via entityType/entityId/workflowRunId.

Rules

  1. NEVER use @anthropic-ai/claude-code npm SDK for desktop runtime — crashes on Node 25+. Use native binary only.
  2. process.execPath in Electron returns the Electron binary. Use env.NODE ?? 'node' for child processes.
  3. Always log activity for new background processes, agent steps, workflows, jobs, user-facing mutations.
  4. Never block on logging — fire-and-forget only.
  5. Keep type parity between frontend/lib/types.ts and backend/app/models.py for extraction types.
  6. Flat layouts — no Card wrappers. Use flat sections with spacing and borders.
  7. shadcn/ui components in components/ui/ are generated — avoid manual edits.
  8. next.config.mjs ignores TS build errors and disables image optimization.
  9. batchedIn() for large .in() queries (100-item PostgREST limit).
  10. Always dry_run=true before auctor_publish.

Key References

For detailed documentation beyond this file:

  • Database schema (all tables, columns, relationships): docs/database-schema.md
  • Pipeline testing and fixtures: docs/pipeline-testing.md
  • System whitepaper and thesis: docs/auctor-agent-whitepaper.md
  • Workflow details: frontend/src/mastra/workflows/content-engine-workflows.ts
  • MCP contracts and operating spec: packages/auctor-mcp/src/contracts.ts, operating-spec.ts
  • Agent metadata and role mappings: frontend/src/mastra/agents/agent-metadata.ts
  • Extraction presets: frontend/lib/pipeline-configs.ts, frontend/lib/presets.ts
Created with MDX Limo
CLAUDE.md — Auctor | MDX Limo