Agent & LLM Integration Guide

This guide explains how AI agents, LLMs, and developer tools can programmatically access and use this documentation.

Access Methods

Method 1: Single File — Full Context

Fetch all documentation in one request:

GET https://test.zonevast.com/llms-full.txt

Returns all docs concatenated as plain text (~35 KB). Best for loading complete context in one fetch.

Method 2: Index File — Curated Links

GET https://test.zonevast.com/llms.txt

Returns a structured index with descriptions and file paths. Best for discovering what docs exist before fetching specific ones.

Method 3: Individual Raw Markdown Files

Fetch any specific doc file as raw markdown:

GET https://test.zonevast.com/api/docs/{path-to-file}.md

Examples:

URL	Content
/api/docs/guides/getting-started.md	Getting started guide
/api/docs/services/flex-auth-service/overview.md	Flex Auth service docs
/api/docs/services/auth-service/overview.md	Auth service docs
/api/docs/services/project-service/overview.md	Project & file upload docs
/api/docs/reference/headers-and-auth.md	Headers & JWT reference
/api/docs/reference/error-codes.md	Error codes & troubleshooting
/api/docs/standards/api-response-format.md	API response format
/api/docs/standards/pagination.md	Pagination standard
/api/docs/standards/error-responses.md	Error response formats

Response: text/plain; charset=utf-8 with full markdown content including frontmatter.

Method 4: Rendered HTML Pages

Browse docs in a browser:

GET https://test.zonevast.com/docs/{path}

Examples: /docs/guides/getting-started, /docs/services/flex-auth-service/overview

How to Use as an Agent

Step 1: Discover Available Docs

GET /llms.txt

Step 2: Read Relevant Service Docs

Pick the service you need and fetch its raw markdown:

GET /api/docs/services/flex-auth-service/overview.md

Step 3: Apply the Knowledge

When generating code:

1. Use the correct Base URL from the doc
2. Include required headers (Authorization, X-Project-ID)
3. Follow request/response examples from the doc
4. Handle errors as documented in error-codes.md

Example Agent Workflow

1. User asks: "How do I register a user with phone OTP?"

2. Agent fetches:
   GET /api/docs/services/flex-auth-service/overview.md

3. Agent reads the "Step 1: Registration" section

4. Agent generates code following the register-init → register-verify flow
   with correct URL, headers, and body format

5. Agent includes error handling from error-codes.md

Response Formats Summary

Endpoint	Format	Use Case
/llms.txt	Plain text (Markdown)	Index/discovery
/llms-full.txt	Plain text (Markdown)	Full context in one fetch
/api/docs/*.md	Plain text (Markdown)	Specific doc raw content
/docs/*	HTML (rendered)	Browser viewing

Adding New Documentation

File Structure

docs/
├── guides/
│   ├── getting-started.md
│   └── agent-llm-guide.md         ← This file
├── standards/
│   ├── api-response-format.md
│   ├── pagination.md
│   ├── search-and-filtering.md
│   ├── rate-limiting.md
│   ├── error-responses.md
│   ├── service-integration.md
│   └── file-uploads.md
├── services/
│   ├── flex-auth-service/
│   │   └── overview.md
│   ├── auth-service/
│   │   └── overview.md
│   ├── project-service/
│   │   └── overview.md
│   └── {new-service}/             ← Add new service here
│       └── overview.md
└── reference/
    ├── headers-and-auth.md
    └── error-codes.md

Required Frontmatter

Every .md file must start with this frontmatter:

---
title: Service Name
description: One-line description of what this doc covers
section: services | guides | reference
service: service-name
order: 1
tags: [tag1, tag2, tag3]
lastValidated: "YYYY-MM-DD"
---

Required fields:

• title — Page title
• description — Short description
• section — Must be services, guides, or reference
• order — Sort order within section

Optional fields:

• service — Service identifier (for services section only)
• tags — Array of search tags
• lastValidated — Date last checked for accuracy

Service Doc Template

Create docs/services/{service-name}/overview.md:

---
title: Service Name
description: What this service does and its tech stack.
section: services
service: service-name
order: N
tags: [tag1, tag2]
lastValidated: "YYYY-MM-DD"
---

# Service Name (package-name)

One paragraph explaining what this service does.

## Service Info

| Property | Value |
|----------|-------|
| Framework | ... |
| Database | ... |

## Base URLs

| Environment | URL |
|-------------|-----|
| **Test (dev)** | `https://test.zonevast.com/...` |
| **Local** | `http://localhost:XXXX/...` |

## Required Headers

\```http
Authorization: Bearer {accessToken}
X-Project-ID: <project-id>
Content-Type: application/json
\```

## Public Endpoints

### Endpoint Name

\```bash
curl -X METHOD https://test.zonevast.com/path \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Project-ID: <project-id>" \
  -d '{...}'
\```

Response:

\```json
{...}
\```

## Authenticated Endpoints

### Endpoint Name

\```bash
curl https://test.zonevast.com/path \
  -H "Authorization: Bearer TOKEN" \
  -H "X-Project-ID: <project-id>"
\```

## TypeScript Integration

\```typescript
const BASE = 'https://test.zonevast.com/...';

async function example() {
  // ...
}
\```

## Deployment

\```bash
cd /path/to/service/
npm run deploy:dev   # or zappa update dev
\```

After Adding New Docs

Run these commands:

# Validate frontmatter, check for broken links and duplicate slugs
npm run docs:validate

# Regenerate llms-full.txt with new content
npm run docs:generate

Both commands must pass before committing.

Build Verification

# Full production build to verify no errors
npm run build

Conventions

• All docs are English only (LTR direction)
• Use <project-id> as placeholder, never hardcode project IDs
• Include both curl and TypeScript examples
• Every endpoint must show required headers
• Link to related docs where applicable