Skip to content

AGENTS.md

Latest commit

 

History

History
184 lines (134 loc) · 7.62 KB

AGENTS.md

File metadata and controls

184 lines (134 loc) · 7.62 KB
Error in user YAML: (<unknown>): did not find expected alphabetic or numeric character while scanning an alias at line 2 column 8
---
description: Instructions building apps with MCP
globs: *
alwaysApply: true
---

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

Read Before Anything Else

Read in this exact order before any implementation:

  1. context/project-overview.md
  2. context/architecture.md
  3. context/ui-tokens.md
  4. context/ui-rules.md
  5. context/ui-registry.md
  6. context/code-standards.md
  7. context/library-docs.md
  8. context/build-plan.md
  9. context/progress-tracker.md

Rules That Never Change

  • Never use hardcoded hex values or raw Tailwind color classes
  • Update progress-tracker.md and ui-registry.md after every feature
  • Before any third party library — load its installed skill first, then read context/library-docs.md for project-specific rules
  • If the same problem persists after one corrective prompt — stop immediately and run /recover

Invariants — Never Violate These

  • API routes contain no UI logic. Components contain no DB logic.
  • Agent code in agent/ never imports from components/ or actions/
  • Server Actions never call agent functions — only API routes call agent functions
  • All InsForge DB writes from the agent go through lib/insforge-server.ts only
  • Easy Apply is never touched — external apply URLs only
  • Every Stagehand act() call is wrapped in try/catch
  • Match threshold always comes from MATCH_THRESHOLD in lib/utils.ts
  • AgentSpan step IDs always use format apply-{job_id}

Available Skills

  • /architect — before any complex feature. Think before building.
  • /imprint — after any new UI component. Capture patterns.
  • /review — before demo or when something feels off.
  • /recover — when something breaks after one failed correction.
  • /remember save — when a feature spans multiple sessions.
  • /remember restore — when returning after a multi-session feature.

InsForge SDK Documentation - Overview

What is InsForge?

Backend-as-a-service (BaaS) platform providing:

  • Database: PostgreSQL with PostgREST API
  • Authentication: Email/password + OAuth (Google, GitHub)
  • Storage: File upload/download
  • AI: OpenRouter key provisioning and model catalog for direct OpenAI-compatible integrations
  • Functions: Serverless function deployment
  • Realtime: WebSocket pub/sub (database + client events)

Installation

The following is a step-by-step guide to installing and using the InsForge TypeScript SDK for Web applications. If you are building other types of applications, please refer to:

🚨 CRITICAL: Follow these steps in order

Step 1: Download Template

Use the download-template MCP tool to create a new project with your backend URL and anon key pre-configured.

Step 2: Install SDK

npm install @insforge/sdk@latest

Step 3: Create SDK Client

You must create a client instance using createClient() with your base URL and anon key:

import { createClient } from '@insforge/sdk';

const client = createClient({
  baseUrl: 'https://your-app.region.insforge.app',  // Your InsForge backend URL
  anonKey: 'your-anon-key-here'       // Get this from backend metadata
});

API BASE URL: Your API base URL is https://your-app.region.insforge.app.

Getting Detailed Documentation

🚨 CRITICAL: Always Fetch Documentation Before Writing Code

InsForge provides official SDKs and REST APIs, use them to interact with InsForge services from your application code.

Before writing or editing any InsForge integration code, you MUST call the fetch-docs or fetch-sdk-docs MCP tool to get the latest SDK documentation. This ensures you have accurate, up-to-date implementation patterns.

Use the InsForge fetch-docs MCP tool to get specific SDK documentation:

Available documentation types:

  • "instructions" - Essential backend setup (START HERE)
  • "real-time" - Real-time pub/sub (database + client events) via WebSockets
  • "db-sdk-typescript" - Database operations with TypeScript SDK
  • Authentication - Choose based on implementation:
    • "auth-sdk-typescript" - TypeScript SDK methods for custom auth flows
    • "auth-components-react" - Pre-built auth UI for React+Vite (singlepage App)
    • "auth-components-react-router" - Pre-built auth UI for React(Vite+React Router) (Multipage App)
    • "auth-components-nextjs" - Pre-built auth UI for Nextjs (SSR App)
  • "storage-sdk" - File storage operations
  • "functions-sdk" - Serverless functions invocation
  • "ai-integration-sdk" - AI integration with the provisioned OpenRouter key and OpenAI SDK
  • "real-time" - Real-time pub/sub (database + client events) via WebSockets
  • "deployment" - Deploy frontend applications via MCP tool

These documentations are mostly for TypeScript SDK. For other languages, you can also use fetch-sdk-docs mcp tool to get specific documentation.

Use the InsForge fetch-sdk-docs MCP tool to get specific SDK documentation

You can fetch sdk documentation using the fetch-sdk-docs MCP tool with specific feature type and language.

Available feature types:

  • db - Database operations
  • storage - File storage operations
  • functions - Serverless functions invocation
  • auth - User authentication
  • ai - AI integration with the provisioned OpenRouter key and OpenAI SDK
  • realtime - Real-time pub/sub (database + client events) via WebSockets

Available languages:

  • typescript - JavaScript/TypeScript SDK
  • swift - Swift SDK (for iOS, macOS, tvOS, and watchOS)
  • kotlin - Kotlin SDK (for Android and JVM applications)
  • rest-api - REST API

When to Use SDK vs MCP Tools

Always SDK for Application Logic:

  • Authentication (register, login, logout, profiles)
  • Database CRUD (select, insert, update, delete)
  • Storage operations (upload, download files)
  • AI integration via the provisioned OpenRouter key with the OpenAI SDK or OpenRouter HTTP API
  • Serverless function invocation

Use MCP Tools for Infrastructure:

  • Project scaffolding (download-template) - Download starter templates with InsForge integration
  • Backend setup and metadata (get-backend-metadata)
  • Database schema management (run-raw-sql, get-table-schema)
  • Storage bucket creation (create-bucket, list-buckets, delete-bucket)
  • Serverless function deployment (create-function, update-function, delete-function)
  • Frontend deployment (create-deployment) - Deploy frontend apps to InsForge hosting

Important Notes

  • For auth: use auth-sdk for custom UI, or framework-specific components for pre-built UI
  • SDK returns {data, error} structure for all operations
  • Database inserts require array format: [{...}]
  • Serverless functions have single endpoint (no subpaths)
  • Storage: Upload files to buckets, store URLs in database
  • AI integrations should call OpenRouter directly with baseURL: "https://openrouter.ai/api/v1" and a server-side OPENROUTER_API_KEY
  • EXTRA IMPORTANT: Use Tailwind CSS 3.4 (do not upgrade to v4). Lock these dependencies in package.json