sota.txt

A sota.txt file is a plain-text file you place in your project root to describe what your app does, how to use it, and its purpose. It helps AI agents (like Claude via MCP) understand your project when deploying, modifying, or debugging -- giving them the context they need to make better decisions.

Why sota.txt?

AI agents work better with context. When an agent deploys or modifies your app via the sota.io MCP server, it can read your sota.txt to understand:

Project purpose -- what the app does and who it's for
Tech stack -- frameworks, databases, and key dependencies
Key endpoints -- routes, APIs, and their purpose
Conventions -- project-specific patterns and constraints

Think of it as a README for AI -- concise, structured, machine-readable context that complements your existing README.md.

Format

sota.txt is plain text with no strict schema. We recommend a simple structure with sections using Markdown-style headings:

# My App

> Brief one-line description of what this app does.

## Tech Stack
- Framework: Next.js 15
- Database: PostgreSQL (via sota.io managed DB)
- Auth: Supabase Auth

## Key Endpoints
- / — Landing page
- /dashboard — User dashboard (auth required)
- /api/webhooks — Incoming webhook handler

## Environment Variables
- DATABASE_URL — Auto-injected by sota.io
- STRIPE_SECRET_KEY — Stripe payments
- NEXT_PUBLIC_APP_URL — Public app URL

## Notes
- Uses ISR for product pages (revalidate: 60)
- Background jobs run via /api/cron (Vercel-style cron)

Keep it focused on what an AI agent needs to know, not everything a human README would cover.

Where to Place It

Put sota.txt in your project root directory, next to package.json, requirements.txt, or Dockerfile. It gets deployed with your app automatically.

my-app/
  sota.txt          <-- here
  package.json
  src/
  ...

Example: Minimal

For simple projects, a few lines are enough:

# My Portfolio
> Personal portfolio site built with Next.js.
Static site, no database, no auth.
Deploy and forget.

Example: Full-Stack App

For more complex projects, include tech stack details, endpoints, and deployment notes:

# SaaS Dashboard

> Multi-tenant analytics dashboard with real-time data.

## Tech Stack
- Framework: Next.js 15 (App Router)
- Database: PostgreSQL via sota.io managed DB
- Auth: Supabase Auth (magic link + OAuth)
- Payments: Stripe (subscriptions)
- Real-time: Server-Sent Events

## Key Endpoints
- / — Marketing landing page
- /login — Authentication (magic link)
- /dashboard — Main analytics view (auth required)
- /api/webhooks/stripe — Stripe webhook handler
- /api/events/stream — SSE endpoint for real-time updates

## Environment Variables
- DATABASE_URL — Auto-injected by sota.io
- SUPABASE_URL — Supabase project URL
- SUPABASE_ANON_KEY — Supabase public key
- STRIPE_SECRET_KEY — Stripe API key
- STRIPE_WEBHOOK_SECRET — Stripe webhook signature

## Notes
- Uses Row Level Security (RLS) for tenant isolation
- Stripe webhooks must be verified via signature
- ISR for marketing pages (revalidate: 3600)
- Dashboard uses client-side data fetching with SWR

How AI Agents Use It

When an AI agent (via MCP) works with your project, it can read sota.txt to understand context before making changes. This leads to better decisions about:

Framework conventions -- respecting your project's patterns
File structure -- knowing where to put new code
Deployment configuration -- understanding env vars and dependencies
Architecture -- avoiding changes that break existing patterns

The sota.io MCP server looks for sota.txt in your project root automatically.

Tips

Keep it concise -- aim for under 100 lines. AI context windows are limited.
Focus on AI needs -- what would an AI agent need to know to work on this project?
Update it -- refresh when your stack or architecture changes significantly.
Complement, don't replace -- sota.txt works alongside your README.md, not instead of it.
Be specific -- mention exact framework versions, specific patterns, and concrete conventions.