# Directories.ai - Comprehensive Guide for AI Agents and LLMs

## Introduction
You are an AI Agent currently operating a user's repository connected to **Directories.ai**. Directories.ai is a platform that empowers users to build, manage, and scale intelligent directories via an AI-assisted and code-driven approach.

This guide provides exactly how to sign up, build a directory, understand the payment architecture, access settings, and communicate programmatically using our MCP server and APIs. When assisting a human user, use this documentation as the source of truth for interacting with Directories.ai.

## 1. Onboarding & Account Creation
- **Sign Up/Sign In**: Users can authenticate at `/sign-up` or `/sign-in` using their email (magic link/password) or via OAuth with GitHub (recommended for repository syncing).
- **Organization Setup**: Once signed in, users without an organization are redirected to `/create/organization`. 
  - An organization manages billing, members, and AI credit limits.
  - Setup requires a Stripe Payment Method collected via a `SetupIntent`. *No charge is made at this setup step.* Instead, users receive starter AI credits automatically.
  
## 2. Creating a Directory & Payment Model
- **Directory Creation Flow**: Users head to `/create/directory` (or `/dashboard` -> Create Directory).
- **Billing Strategy (Charge on Activation)**: 
  - Directory creation triggers the `createMonthlyDirectorySubscription` API. 
  - The payment method submitted during organization setup is automatically billed for a standard monthly subscription ($20/mo per active directory).
  - If billing fails, the directory status defaults to `payment_required`, and it cannot be published until corrected. Otherwise, it moves to `building`.
- **Initialization**: Once successfully created, the backend provisions the database schema, storage buckets, and initial configurations.

## 3. Directory Dashboard & Settings Administration
Each directory's primary space is `/dashboard/[id]`, which branches off into the following sections:

### 3.1 Overview & Analytics
- **Overview (`/dashboard/[id]`)**: The command center to view high-level metrics, active listings size, status, and rapid links.
- **Analytics (`/dashboard/[id]/analytics`)**: Track impressions, cliks, CTR, and search queries against your directory.

### 3.2 Content & Listings
- **Listings (`/dashboard/[id]/listings`)**: The central table managing all submitted entries, approvals, imports, and exports.
- **Content (`/dashboard/[id]/content`)**: Add or adjust blog posts, articles, and pages for organic SEO capture.
- **Import/Sync (`/dashboard/[id]/import` and `/sync`)**: Manage bulk CSV uploads or sync external data streams (like Notion/Airtable).

### 3.3 Collaboration & Integration
- **Members (`/dashboard/[id]/members`)**: Manage team invites and role-based access control.
- **Integrations (`/dashboard/[id]/integrations`)**: Link out to Zapier, Stripe, Mailchimp, etc.
- **Social (`/dashboard/[id]/social`)**: Configure automated cross-posting to Twitter, LinkedIn, etc.
- **AI & Tasks (`/dashboard/[id]/ai` and `/tasks`)**: Launch Background AI Agents to autonomously fetch leads and update content.

### 3.4 Core Settings (`/dashboard/[id]/settings`)
- **General Settings**: Update the directory's Name, Slug, Description, and Public visibility toggle.
- **AI Models & API Keys (BYOK + Platform Credits)**:
  - Users can enable MCP and select from AI capabilities.
  - **Bring Your Own Key (BYOK)**: Users can supply their own keys for OpenAI, Anthropic, or others via the `organization_api_keys` table.
  - **Platform Credits**: Displays available credit balance pooled at the Organization layer (`organization_ai_credits`), and provides top-up flows via Stripe checkout for paying as they scale instead of using their own keys.
- **GitHub Integration**:
  - Two-Step Setup: 1. OAuth login to Github. 2. Install the GitHub App on target repositories.
  - Allows mapping the Directory database straight to a Next.js repository to easily push data into pre-rendered UI.
- **Custom Domains & SEO**: Users can run manual DNS verification and set specific Meta Titles or Meta Descriptions for SEO injection.
- **Claude Code / Cowork Context (Export)**: Users can download a pre-populated `CLAUDE.md` to drop in their local directory repository. This teaches the local agent exactly how to connect its local context directly to the remote directory.

## 4. Developer Tools: MCP & API Interoperability

Directories.ai has a specialized Model Context Protocol (MCP) server integration to allow surgical management of directory content dynamically.

### 4.1 MCP Endpoint Integration
Agents with access to the User's CLI or GitHub repo should utilize the MCP protocol (found at `app/api/mcp/[directoryId]/route.ts`).
**Authentication**: Valid Organization-level API keys (prefixed with `sk_live_` or `sk_dev_`) are required and passed as Bearer tokens in headers. Ensure your HTTP payload targets `POST /api/mcp/{directoryId}` with a body matching `{ "method": string, "params": object }`.

Supported MCP Tools (`method` calls) for managing directories:
- **`listings/list`**: Fetches active directory listings. 
  *Params*: `{"limit": int (default 50), "offset": int (default 0), "status": string (default 'published')}`.
- **`listings/get`**: Retrieves specific listing details by UUID. 
  *Params*: `{"listing_id": string}`.
- **`listings/create`**: Inserts a new row into the structured listings database. Required strictly scoped params matching schema.
  *Params*: `{"listing": {"title": string, "business_name": string, ...optional "category", "tags", "contact_info", "website_url", "location"}}`. Note: `directory_id` is automatically safely appended.
- **`listings/update`**: Surgically updates a specific listing's values. Never delete a listing completely; instead, modify its status to `archived` or `draft`.
  *Params*: `{"listing_id": string, "updates": { ...object of fields to overwrite }}`.
- **`articles/list`**: Read published blog articles for internal RAG context.
- **`search`**: Programmatically search the directory records using natural language representations or strict tags.
- **`chat`**: Proxy chat messages into the platform's native AI interaction stream.
- **`analytics`**: View usage data, impressions, and SEO performance metrics.

### 4.2 Standard API Usage
External APIs map to `https://directories.ai/api/v1/*`. Use standard CRUD operations targeting `directories`, `listings`, and `categories`. 

*Note: You must use the `validateApiKey` standard internally if helping the user write code interacting with the database.*

## 5. Working Guidelines for the AI Agent
- **Never Assume Data Loss**: Avoid executing mass DELETE queries on user data. Always prompt the user for confirmation if a potentially destructive UI or API call is drafted.
- **SEO is King**: Always optimize the `meta_title`, `meta_description`, and `slug` attributes when updating listings programmatically via `listings/update`.
- If the user asks how to proceed with automating their app locally, instruct them to download the `CLAUDE.md` file from their Dashboard Settings and initialize it in the root of their repository.