app/AGENTS.md

# AGENTS.md: Guidelines for the AI Coding Agent

This document outlines the standards and practices for the development of the
Ponderants application. The AI agent must adhere to these guidelines strictly.

**Git Commits**: For this project, you can skip PGP-signed commits and run git commands directly. You have permission to execute git add, git commit, and git push commands yourself. When writing commit messages with git commit -m, always use HEREDOC syntax with single quotes to properly escape special characters:
```bash
git commit -m "$(cat <<'EOF'
Your commit message here
EOF
)"
```

**Test Credentials**: For testing and development, use the test Bluesky account credentials stored in the .env file:
- Handle: TEST_BLUESKY_HANDLE (aprongecko.bsky.social)
- Password: TEST_BLUESKY_PASSWORD (Candles1)

These credentials should be used for all automated testing (Magnitude, Playwright) and manual testing when needed. Do not attempt to authenticate without using these credentials.

You are an expert-level, full-stack AI coding agent. Your task is to implement
the "Ponderants" application. Product Vision: Ponderants is an AI-powered
thought partner that interviews a user to capture, structure, and visualize
their ideas as a network of "Nodes" (mini blog posts) published to their
decentralized social identity (Bluesky/ATproto). Core Architecture: You MUST
implement a "Decentralized Source of Truth vs. App View Cache" model. Source of
Truth: The user's ATproto Personal Data Server (PDS). All canonical data
(com.ponderants.node) MUST be written here.3 This data must outlive the
application. App View Cache: Our SurrealDB instance. This database acts as a
high-speed index or cache of the user's PDS data. It is used to power advanced
features (vector search, 3D visualization) that the PDS cannot handle. Data
Flow: All writes MUST follow a "write-through cache" pattern 4: Write to ATproto
PDS first. On success, write to the SurrealDB cache.

## 1. Implementation Philosophy

The goal is to build a robust, maintainable, and high-quality application. Focus
on clean, expert-level implementation adhering to the specified architecture.

### 1.1. Code Quality

- **Expert Level (Staff Engineer):** Write code as an experienced Staff-level
  engineer would. This means anticipating edge cases, optimizing for performance
  (especially in data visualization and vector search), and utilizing advanced
  features of the chosen frameworks effectively.
- **Clean Code:** Adhere strictly to SOLID principles and Robert C. Martin's
  Clean Code principles.
  - **Meaningful Names:** Variables, functions, and classes must be descriptive.
  - **Small Functions:** Functions should be small and focused on a single
    responsibility.
  - **DRY (Don't Repeat Yourself):** Abstract reusable logic.
- **TypeScript:** All code must be written in strict TypeScript
  (`"strict": true` in `tsconfig.json`). Use explicit types; avoid `any`.
  Leverage advanced TypeScript features like generics and utility types where
  appropriate.
- **Formatting & Linting:** Use Prettier for formatting and ESLint with strict
  rules. Configuration files must be provided.

### 1.2. Architecture & Design Patterns

- **Decentralized First (Source of Truth):** The architectural mandate is that
  the user's ATproto PDS is the canonical source of truth. SurrealDB is strictly
  a performance-enhancing cache.
- **Write-Through Cache:** Implement the "write-through cache" pattern: writes
  must succeed to the PDS before updating the cache. Ensure data consistency.
- **Next.js App Router:** Utilize the full capabilities of the Next.js 16 App
  Router. Use Server Components (RSCs) by default. Use Client Components
  (`'use client'`) only when strictly necessary for interactivity or browser
  APIs (e.g., WebSockets, MediaRecorder, R3F Canvas).

### 1.3. Security

- **Authentication:** Implement the ATproto OAuth flow securely.
- **Authorization:** Use SurrealDB's JWT validation and scope/permission
  definitions to enforce strict data access controls. Ensure users can only
  access their own data.
- **Secrets Management:** Store all API keys and secrets in environment
  variables.
- **Environment Variables:** NEVER set default values in code for configuration
  variables. All configuration must come from .env file. Code should throw
  an error with a clear message if required environment variables are missing.
  This ensures configuration issues are caught immediately rather than silently
  falling back to potentially incorrect defaults.
- **Input Validation:** Validate all inputs on the server side (e.g., using
  Zod).

## 2. Technology Stack Adherence

The agent must _only_ use the specified technologies:

- **Frontend:** Next.js 16 (App Router), TypeScript.
- **UI/Styling:** Mantine (@mantine/core, @mantine/hooks). All styling must be
  centralized in `theme.ts`. **Absolutely NO CSS Modules, Tailwind, or other
  styling solutions.** The UI must be minimal, professional, and grayscale.
- **Backend/DB:** SurrealDB (Auth, Data, Vector Search, Graph).
- **Decentralized Protocol:** ATproto (Bluesky) SDK (`@atproto/api`,
  `@atproto/oauth`).
- **AI:** Vercel AI SDK (`ai`), @ai-sdk/google (Gemini models for chat and
  `gemini-embedding-001`).
- **Voice:** Deepgram SDK.
- **Visualization:** React Three Fiber (`@react-three/fiber`,
  `@react-three/drei`), `three`.
- **Dimensionality Reduction:** `umap-js`.

## 3. Development Process

- **Sequential Implementation:** Implement features sequentially based on the
  provided Technical Specification phases.
- **Testing Mandatory:** Every feature must be covered by comprehensive
  end-to-end tests using Magnitude.run as specified in the Testing
  Specification. Implementation is not complete until all defined Happy Path and
  Unhappy Path tests pass.
- **Risk Mitigation:** Prioritize implementation according to the Hackathon
  Strategy: Auth (Phase 1) must be completed first.

1. Project Vision & Core Architecture

You are an expert-level, full-stack AI coding agent. Your task is to implement
the "Ponderants" application. Product Vision: Ponderants is an AI-powered
thought partner that interviews a user to capture, structure, and visualize
their ideas as a network of "Nodes" (mini blog posts) published to their
decentralized social identity (Bluesky/ATproto). Core Architecture: You MUST
implement a "Decentralized Source of Truth vs. App View Cache" model. Source of
Truth: The user's ATproto Personal Data Server (PDS). All canonical data
(com.ponderants.node) MUST be written here.3 This data must outlive the
application. App View Cache: Our SurrealDB instance. This database acts as a
high-speed index or cache of the user's PDS data. It is used to power advanced
features (vector search, 3D visualization) that the PDS cannot handle. Data
Flow: All writes MUST follow a "write-through cache" pattern 4: Write to ATproto
PDS first. On success, write to the SurrealDB cache.

2. Technology Stack (Strict)

You MUST use the following technologies and versions. Do not deviate. Frontend:
Next.js 16 (App Router) 5 UI Components: Mantine (@mantine/core, @mantine/hooks)
5 Database / Backend: SurrealDB (surrealdb.js) 7 Decentralized Protocol: ATproto
(@atproto/api, @atproto/oauth-client-node) 8 AI SDK: Vercel AI SDK
(@ai-sdk/google, @ai-sdk/react) 10 AI Embedding Model: gemini-embedding-001 (via
Google AI SDK) 12 Voice-to-Text: Deepgram (@deepgram/sdk) 13 3D Visualization:
React Three Fiber (@react-three/fiber, @react-three/drei) 14 Dimensionality
Reduction: umap-js 16 Testing: magnitude-test 17

3. Implementation Standards & Best Practices

Code Quality: All code MUST be expert-level, clean, modular, and strongly-typed
using TypeScript. All files must be formatted with Prettier (default settings).
Follow all guidelines for creating a strong execution plan.18 File Structure:
Strictly adhere to the Next.js App Router file conventions (app/, components/,
lib/). Styling (Critical): You MUST NOT use custom CSS Modules, \*.css files
(beyond the global Mantine import), or inline style props. All styling MUST be
achieved via: The central app/theme.ts file provided to the MantineProvider.19
Mantine component props (e.g., p="md", mt="lg", c="gray.7"). The UI must be
minimal, grayscale, and "unstyled" as defined in the product spec. Error
Handling: All API routes and client-side functions performing data fetching or
mutations MUST include robust try/catch blocks. API routes must return
standardized JSON error responses (e.g., { error: "Message" } with appropriate
status codes). Environment Variables: All secret keys (Deepgram, Google AI,
SurrealDB credentials, JWT secret) MUST be accessed via process.env. Create a
.env.example file. Serverless vs. Stateful: The application WILL be implemented
as serverless-first (Next.js). The Real-time Voice feature will NOT use a custom
stateful server 20; it will instead use a serverless API route to generate a
temporary client-side token for direct-to-Deepgram WebSocket connection.

4. Testing Protocol

Framework: All tests MUST be written for magnitude.run.17 This framework uses AI
Vision to interact with the browser like a human.24 File Location: Tests will be
located in the tests/magnitude/ directory, with filenames matching the feature
(e.g., auth.mag.ts). Coverage: EVERY feature specified in the implementation
plan MUST be fully tested. Test Cases: You MUST write tests for both the "happy
path" (the default, expected user flow 25) and all "unhappy paths" (any
exceptional condition, error, or user deviation 27). Syntax: Use natural
language steps as defined by magnitude-test.29 TypeScript import { test } from
'magnitude-test';

test('User can log in and create a node', async (agent) => { await
agent.open('http://localhost:3000/login'); await agent.act('Click the "Log in
with Bluesky" button') .data({ username: 'test-user', password: 'test-password'
}); // Mocking data await agent.check('Can see dashboard'); await
agent.act('Type "My first thought" into the chat input and press Enter'); await
agent.check('AI Suggestion card is visible'); });

5. Development Environment

Setup: npm install Run Dev Server: npm run dev Run Tests: npx magnitude

Project: PonderantsProject OverviewProduct Name: PonderantsElevator Pitch: Ponderants is an AI-powered thought partner that interviews you to capture, structure, and visualize your ideas. It turns free-flowing voice or text conversations into a network of "Nodes" (mini blog posts) published directly to your decentralized social identity (Bluesky/ATproto).Core User Flow:Converse: The user starts a session, selects an AI persona (e.g., Socratic, Collaborator), and explores a topic via voice or text.Capture: The AI, or the user, triggers the creation of a "Node" from the conversation.Refine: The user is moved to an editor to approve or edit the AI-generated draft Node.Link: The AI (using vector search) suggests links to the user's existing Nodes. The user approves/modifies these links.Publish: The user publishes the Node. This action writes the data canonically to their ATproto (Bluesky) Personal Data Server and simultaneously to our app's cache for advanced features.Visualize: The user can explore their entire "thought galaxy" in an interactive 3D visualization.Core ArchitectureThis system is built on a "Source of Truth vs. App View Cache" model.Source of Truth (ATproto): The user's ATproto Personal Data Server (PDS) is the canonical, permanent home for all their content (specifically, com.ponderants.node records). The user owns this data. Our app is a client for their PDS.App View Cache (SurrealDB): Our app runs a SurrealDB instance. This database acts as a high-speed index of the user's data to enable features the PDS cannot, such as vector search for AI-powered linking and storing pre-computed 3D coordinates for visualization.Technology StackFrontend Framework: Next.js 16 (App Router)UI Components: Mantine (@mantine/core, @mantine/hooks)Styling: Mantine Theming (via theme.ts)Database / Backend: SurrealDBDecentralized Protocol: ATproto (Bluesky)AI SDK: Vercel AI SDKAI Embedding Model: gemini-embedding-001AI Chat Model: @ai-sdk/google (Gemini)Voice-to-Text: Deepgram3D Visualization: React Three Fiber (R3F) (@react-three/fiber, @react-three/drei)Dimensionality Reduction: umap-jsSetup, Build, and Test CommandsInstall dependencies: pnpm installStart dev server: pnpm devRun tests: pnpm test (This will execute the magnitude.run test suite).Core Implementation PrinciplesYou, the AI Agent, MUST adhere to the following principles at all times. These are not suggestions; they are project-level requirements.2PrincipleDirectiveRationale0. Test-Driven ImplementationYou MUST write the magnitude.run test file (*.mag.ts) before the implementation file. The spec for each commit will provide the test cases.This ensures every line of code is testable and serves a specific, user-facing purpose. It adheres to the "EVERY user flow... tested fully" requirement.51. Styling: Mantine-OnlyYou MUST NOT write any custom CSS, CSS Modules, or style tags. All styling (layout, color, typography) MUST be achieved using Mantine components (<Stack>, <Group>, etc.) and theme.ts overrides.The goal is a "stunningly-beautiful" app achieved through a "minimal, grayscale, unstyled UI." Mantine's system provides this "functional, yet professional look" with maximum speed.2. State Management: MinimalistYou MUST favor React server components (async/await in components) for data fetching. For client state, you MUST use simple useState or Mantine hooks (useForm). You MUST NOT install zustand, redux, or other state managers.A hackathon requires speed. The Vercel AI SDK's useChat hook manages chat state. All other data is fetched from SurrealDB. Complex global state is unnecessary.3. API Routes: Next.js App RouterAll server-side logic MUST be implemented as Next.js App Router Route Handlers (e.g., app/api/chat/route.ts).This is the standard for the Next.js 16 (App Router) stack specified.4. Error Handling: ExplicitEvery API route MUST return a NextResponse.json({ error: "..." }, { status:... }) on failure. Every client-side function that calls an API MUST have a .catch() block that uses Mantine's Notifications system to display the error to the user.This is critical for "not-happy path" testing and creates a robust, professional user experience.5. Code: Clean & TypedAll code MUST be "expert-level." It must be fully typed with TypeScript, use modern ES6+ features (async/await, destructuring), and be commented where logic is complex (e.g., UMAP, ATproto resolution).This is a non-negotiable quality bar for reliable implementation.6. Security: Server-Side SecretsNo API keys (SurrealDB, Deepgram, Google) or secrets may ever be present in client-side code. They MUST only be accessed on the server (in API routes) via process.env.This is a fundamental security principle. The Deepgram client, for example, will use a temporary token generated by the server.7. Architecture: Write-Through CacheAll data writes (Node creation) MUST follow the "write-through cache" model: (1) Publish to ATproto Source of Truth, (2) Write to SurrealDB App Cache.This is the core architectural pattern and must be respected in all write operations.Git & PR InstructionsAll commits must be atomic and directly correspond to one of the provided specification files.All PRs MUST pass pnpm test (which runs magnitude) before merging.7Aesthetic GoalThe user has demanded a "stunningly-beautiful" application. You will achieve this not with complex, custom CSS, but with the thoughtful and elegant use of Mantine's layout components (<Stack>, <Group>, <Paper>, <AppShell>), a sophisticated grayscale theme.ts, and fluid interactions. The 3D visualization, powered by React Three Fiber, must be smooth, interactive, and beautiful.

## **Project: Ponderants**

### **Project Overview**

Product Name: Ponderants  
Elevator Pitch: Ponderants is an AI-powered thought partner that interviews you to capture, structure, and visualize your ideas. It turns free-flowing voice or text conversations into a network of "Nodes" (mini blog posts) published directly to your decentralized social identity (Bluesky/ATproto).  
**Core User Flow:**

1. **Converse:** The user starts a session, selects an AI persona (e.g., Socratic, Collaborator), and explores a topic via voice or text.  
2. **Capture:** The AI, or the user, triggers the creation of a "Node" from the conversation.  
3. **Refine:** The user is moved to an editor to approve or edit the AI-generated draft Node.  
4. **Link:** The AI (using vector search) suggests links to the user's existing Nodes. The user approves/modifies these links.  
5. **Publish:** The user publishes the Node. This action writes the data canonically to their ATproto (Bluesky) Personal Data Server and simultaneously to our app's cache for advanced features.  
6. **Visualize:** The user can explore their entire "thought galaxy" in an interactive 3D visualization.

### **Core Architecture**

This system is built on a "Source of Truth vs. App View Cache" model.

* **Source of Truth (ATproto):** The user's ATproto Personal Data Server (PDS) is the canonical, permanent home for all their content (specifically, com.ponderants.node records). The user owns this data. Our app is a client for their PDS.  
* **App View Cache (SurrealDB):** Our app runs a SurrealDB instance. This database acts as a high-speed index of the user's data to enable features the PDS cannot, such as vector search for AI-powered linking and storing pre-computed 3D coordinates for visualization.

### **Technology Stack**

* **Frontend Framework:** Next.js 16 (App Router)  
* **UI Components:** Mantine (@mantine/core, @mantine/hooks)  
* **Styling:** Mantine Theming (via theme.ts)  
* **Database / Backend:** SurrealDB  
* **Decentralized Protocol:** ATproto (Bluesky)  
* **AI SDK:** Vercel AI SDK  
* **AI Embedding Model:** gemini-embedding-001  
* **AI Chat Model:** @ai-sdk/google (Gemini)  
* **Voice-to-Text:** Deepgram  
* **3D Visualization:** React Three Fiber (R3F) (@react-three/fiber, @react-three/drei)  
* **Dimensionality Reduction:** umap-js

### **Setup, Build, and Test Commands**

* **Install dependencies:** pnpm install  
* **Start dev server:** pnpm dev  
* **Run tests:** pnpm test (This will execute the magnitude.run test suite).

### **Core Implementation Principles**

You, the AI Agent, MUST adhere to the following principles at all times. These are not suggestions; they are project-level requirements.2

| Principle | Directive | Rationale |
| :---- | :---- | :---- |
| **0\. Test-Driven Implementation** | You MUST write the magnitude.run test file (\*.mag.ts) *before* the implementation file. The spec for each commit will provide the test cases. | This ensures every line of code is testable and serves a specific, user-facing purpose. It adheres to the "EVERY user flow... tested fully" requirement.5 |
| **1\. Styling: Mantine-Only** | You MUST NOT write any custom CSS, CSS Modules, or style tags. All styling (layout, color, typography) MUST be achieved using Mantine components (\<Stack\>, \<Group\>, etc.) and theme.ts overrides. | The goal is a "stunningly-beautiful" app achieved through a "minimal, grayscale, unstyled UI." Mantine's system provides this "functional, yet professional look" with maximum speed. |
| **2\. State Management: Minimalist** | You MUST favor React server components (async/await in components) for data fetching. For client state, you MUST use simple useState or Mantine hooks (useForm). You MUST NOT install zustand, redux, or other state managers. | A hackathon requires speed. The Vercel AI SDK's useChat hook manages chat state. All other data is fetched from SurrealDB. Complex global state is unnecessary. |
| **3\. API Routes: Next.js App Router** | All server-side logic MUST be implemented as Next.js App Router Route Handlers (e.g., app/api/chat/route.ts). | This is the standard for the Next.js 16 (App Router) stack specified. |
| **4\. Error Handling: Explicit** | Every API route MUST return a NextResponse.json({ error: "..." }, { status:... }) on failure. Every client-side function that calls an API MUST have a .catch() block that uses Mantine's Notifications system to display the error to the user. | This is critical for "not-happy path" testing and creates a robust, professional user experience. |
| **5\. Code: Clean & Typed** | All code MUST be "expert-level." It must be fully typed with TypeScript, use modern ES6+ features (async/await, destructuring), and be commented where logic is complex (e.g., UMAP, ATproto resolution). | This is a non-negotiable quality bar for reliable implementation. |
| **6\. Security: Server-Side Secrets** | No API keys (SurrealDB, Deepgram, Google) or secrets may *ever* be present in client-side code. They MUST only be accessed on the server (in API routes) via process.env. | This is a fundamental security principle. The Deepgram client, for example, will use a temporary token generated by the server. |
| **7\. Architecture: Write-Through Cache** | All data writes (Node creation) MUST follow the "write-through cache" model: (1) Publish to ATproto Source of Truth, (2) Write to SurrealDB App Cache. | This is the core architectural pattern and must be respected in all write operations. |

### **Git & PR Instructions**

* All commits must be atomic and directly correspond to one of the provided specification files.  
* All PRs MUST pass pnpm test (which runs magnitude) before merging.7

### **Aesthetic Goal**

The user has demanded a "stunningly-beautiful" application. You will achieve this not with complex, custom CSS, but with the thoughtful and elegant use of Mantine's layout components (\<Stack\>, \<Group\>, \<Paper\>, \<AppShell\>), a sophisticated grayscale theme.ts, and fluid interactions. The 3D visualization, powered by React Three Fiber, must be smooth, interactive, and beautiful.

### MCP Servers

You have access to SurrealDB and playwright MCP servers -- use them readily to
help debug any issues you may encounter!