schema/user.md          →  users_create, users_get, users_list, users_update, users_delete
schema/recipe.md        →  recipes_create, recipes_get, recipes_list, ...
rules/permissions.md    →  enforced on every operation
workflows/publish.md    →  run_workflow("publish")

┌─────────────────────────────────────────────────────────────┐
│                     Your Project (Markdown)                 │
│  schema/*.md   actions/*.md   rules/*.md   workflows/*.md   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                    ┌──────▼──────┐
                    │  NLBackend  │  ← compiles schemas, registers tools
                    │  MCP Server │  ← file-based DB, auto CRUD
                    └──────┬──────┘
                           │ stdio (MCP protocol)
                    ┌──────▼──────┐
                    │  Claude /   │  ← calls users_create, query_db, etc.
                    │  Any LLM    │
                    └─────────────┘

curl -fsSL https://bun.sh/install | bash

git clone https://github.com/your-org/nlbackend.git
cd nlbackend
bun install

# Scaffold a new project
bun run src/cli.ts init my-app

# Task

A task in a to-do list.

## Fields

- **id**: string, auto uuid, immutable
- **title**: string, required, min 1, max 200
- **done**: boolean, default false
- **created_at**: string, auto timestamp, immutable
- **updated_at**: string, auto timestamp

bun run src/index.ts ./my-app

bun run src/cli.ts config ./my-app

{
  "mcpServers": {
    "my-app": {
      "command": "bun",
      "args": ["run", "/path/to/nlbackend/src/index.ts", "/path/to/my-app"]
    }
  }
}

my-app/
├── project.md              # Name & description
├── claude.md               # Instructions for the Building LLM
├── schema/                 # Data models (one .md per entity)
│   └── claude.md           # Conventions for writing schemas
├── actions/                # Custom MCP tools beyond CRUD
│   └── claude.md
├── rules/                  # Business rules & validation
│   └── claude.md
├── workflows/              # Multi-step processes (saga pattern)
│   └── claude.md
├── integrations/           # External service configs (email, webhooks)
│   └── claude.md
├── config/server.md        # LLM provider settings
├── tests/                  # Natural language test scenarios
│   └── claude.md
└── db/                     # Auto-managed file database

nlbackend <project-path>              # Start the MCP server
nlbackend <project-path> --compile    # Start with LLM compilation
nlbackend init [<folder>]             # Create a new project from template
nlbackend config [<project-path>]     # Output MCP client connection config
nlbackend test [<project-path>]       # Run .test.md natural language tests
nlbackend version                     # Print version

# Search Recipes

> Tier: 2
> Auth: public

Searches recipes by keyword, cuisine, or ingredients.

## Input
- **query**: string, optional — keyword search
- **cuisine**: string, optional — filter by cuisine type
- **max_time**: integer, optional — max cooking time in minutes

## Output
Returns matching recipes sorted by relevance.

# Permissions

## Only owners can edit
A user can only update or delete a recipe if they are the author.

## Admin override
Users with role "admin" can update or delete any record.

# Publish Recipe

## Trigger
When a recipe's status changes to "published".

## Steps
1. Validate all required fields are present
2. Generate a URL-friendly slug from the title
3. Send notification email to followers
4. Update recipe status to "published"

## On failure
If any step fails, revert the status to "draft".

# Email Integration

## Provider
Resend (https://api.resend.com)

## Authentication
API key stored in environment variable RESEND_API_KEY

## Available Actions

### Send Email
- **to**: email address (required)
- **subject**: text (required)
- **body**: text or html (required)

# User CRUD Tests

## Create a user
- Given an authenticated user with role "admin"
- When calling users_create with:
    - username: "alice"
    - email: "alice@example.com"
- Then response contains field "id"
- And response field "username" equals "alice"

bun install
bun test              # 62 unit tests
bun run typecheck     # TypeScript strict mode

# Run the example project
bun run src/index.ts ./example-recipes

# Run the smoke test (29 end-to-end tests)
bun run example-recipes/tests/smoke-test.ts