diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml index 3c5614b8..342d00e7 100644 --- a/.github/workflows/codespell.yml +++ b/.github/workflows/codespell.yml @@ -20,3 +20,4 @@ jobs: - uses: codespell-project/actions-codespell@406322ec52dd7b488e48c1c4b82e2a8b3a1bf630 # v2.1 with: ignore_words_file: .codespellignore + skip: './.git,./pnpm-lock.yaml' diff --git a/.gitignore b/.gitignore index 458f5900..f8dd1a98 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ .next +_pagefind/ node_modules .pnpm-store .vercel diff --git a/.npmrc b/.npmrc new file mode 100644 index 00000000..6c59086d --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +enable-pre-post-scripts=true diff --git a/ab.md b/ab.md deleted file mode 100644 index e69de29b..00000000 diff --git a/agents.md b/agents.md new file mode 100644 index 00000000..7259689e --- /dev/null +++ b/agents.md @@ -0,0 +1,458 @@ +# Lamatic Docs - AI Agent Instructions + +> Comprehensive rules and guidelines for AI coding agents working on the Lamatic.ai documentation codebase. + +--- + +## General Rules + +- This is the documentation website for **Lamatic.ai**, an AI middleware platform. +- Built with **Next.js 14** + **Nextra 2** (docs theme). Nextra docs: https://nextra.site +- All pages live in the `/pages` folder and are rendered by Nextra's file-based routing. +- Reusable React components are in `/components`. UI primitives follow **shadcn/ui** conventions in `/components/ui`. +- The dev server runs on **http://localhost:3333** (`npm run dev`). +- Package manager: **pnpm** (v9.1.2). Node version: **v18.18** (see `.nvmrc`). + +### Frontend + +- When using Tailwind CSS, **never use explicit/hardcoded colors**. Always use the semantic color tokens defined via CSS variables (light/dark mode aware). +- Use the `cn()` utility from `@/lib/utils` for conditional class merging (clsx + tailwind-merge). +- Radix UI primitives are used for accessible, unstyled components. Wrap them with Tailwind styles following existing patterns. + +### Key Commands + +```bash +pnpm install # Install dependencies +pnpm dev # Start dev server on port 3333 +pnpm build # Production build +pnpm start # Start production server +pnpm analyze # Bundle analysis +``` + +--- + +## Project Structure + +``` +lamatic-docs/ +├── pages/ # All documentation content (MDX) + Next.js pages +│ ├── docs/ # Core platform documentation +│ │ ├── agents/ # Agent types (Text, JSON, Multi-Modal, Supervisor) +│ │ ├── flows/ # Flow editor and deployment +│ │ ├── nodes/ # Node documentation (AI nodes, etc.) +│ │ ├── api-integration/ # API keys, SDKs (Go, React, Next.js) +│ │ ├── context/ # Memory Store, Vector DB +│ │ ├── ide/ # IDE features +│ │ ├── interface/ # Interface configuration +│ │ ├── mcp-tools/ # MCP/Tools integration +│ │ ├── tests/ # Testing documentation +│ │ └── concepts/ # LLM Prompting, RAG, etc. +│ ├── guides/ # Step-by-step tutorial guides +│ ├── integrations/ # Third-party integration docs +│ ├── templates/ # Agent kit templates +│ ├── agentkits/ # Agent kit pages +│ └── _meta.json # Top-level navigation config +├── components/ # React components +│ ├── ui/ # shadcn/ui primitives (button, card, dialog, etc.) +│ ├── icons/ # Icon components +│ ├── Video.tsx # Video/CloudflareVideo embedding +│ ├── Frame.tsx # Content frame wrapper +│ ├── MainContentWrapper.tsx +│ ├── CustomTOC.tsx +│ ├── PageContributors.tsx +│ └── availability.tsx # AvailabilityBanner/AvailabilitySidebar +├── lib/ # Utilities, constants, data +├── public/ # Static assets (images, icons) +├── theme.config.tsx # Nextra theme configuration +├── next.config.mjs # Next.js configuration +├── tailwind.config.js # Tailwind CSS configuration +└── style.css # Global styles with CSS variables +``` + +--- + +## Documentation Pages + +### Frontmatter + +Every documentation page **must** include YAML frontmatter: + +```mdx +--- +title: "Page Title" +description: "A concise SEO-friendly description of the page content." +--- +``` + +Optional frontmatter fields: + +| Field | Type | Description | +|---------------|---------|--------------------------------------------------| +| `title` | string | Page title (required) | +| `description` | string | SEO description (required) | +| `ogImage` | string | Custom Open Graph image URL | +| `ogVideo` | string | Open Graph video URL (mp4) | +| `availability`| object | Feature availability status for sidebar display | + +### Page Structure + +Follow this structure for consistency: + +1. **Frontmatter** - Title, description, and metadata +2. **Introduction** - 1-2 sentences explaining what the page covers and why it matters +3. **Prerequisites** (if applicable) - What the reader needs before starting +4. **Main Content** - Organized with clear headings (`##`, `###`) +5. **Code Examples** - With proper syntax highlighting and clear placeholders +6. **Tips & Callouts** - Using the `` component +7. **Related Resources** - Links to relevant docs, guides, or integrations + +### Writing Style + +- **Clarity and conciseness** - Avoid jargon; use plain language +- **Active voice** - "Configure the API key" not "The API key should be configured" +- **Second person** - Address the reader as "you" +- **Imperative mood for instructions** - "Run the command" not "You should run the command" +- **Descriptive link text** - "See the [deployment guide](/docs/deployments)" not "Click [here](/docs/deployments)" + +### Headings + +- Use hierarchical headers (`##`, `###`, `####`). Never skip levels. +- Page title comes from frontmatter `title` - do **not** add an `# H1` heading in the content. +- Keep headings short and descriptive. + +--- + +## Navigation & Routing + +### _meta.json Files + +Navigation structure is defined by `_meta.json` files in each directory. These control: +- Page ordering in the sidebar +- Display titles +- Separators between sections +- External links +- Hidden pages + +Example: +```json +{ + "-- Section Name": { + "type": "separator", + "title": "Section Name" + }, + "page-slug": { + "title": "Display Title", + "type": "doc" + } +} +``` + +When adding a new page, **always update the corresponding `_meta.json`** to include it in the navigation. + +### Internal Links + +- Use **relative paths** for internal links: `/docs/flows/editor`, not full URLs +- Verify that all internal links point to valid pages +- When linking between sections, use the full path from root: `/guides/getting-started` + +--- + +## Component Usage + +### Globally Available Components + +These components are registered in `theme.config.tsx` and available in all MDX files **without imports**: + +| Component | Usage | +|-----------------------|--------------------------------------------| +| `` | Wrap images/content for consistent styling | +| `` / `` | Tabbed content sections | +| `` | Step-by-step numbered instructions | +| `` / `` | Card grid layouts | +| `` | Info, warning, or error callouts | +| `