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:

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.

Database Setup: The application uses SurrealDB running in Docker Compose for the app cache layer:

1. Start the database services:

   docker compose up -d
   

2. This starts two services:

   • surrealdb: The main SurrealDB instance (port 8000)
   • surrealmcp: SurrealMCP server for MCP access (port 8080)

3. Start the Next.js development server:

   pnpm dev
   

4. To stop the services:

   docker compose down
   

5. Configuration:

   • SurrealDB runs in-memory mode (data is not persisted between restarts)
   • Namespace: ponderants
   • Database: main
   • Credentials: root/root

Note: Always start docker compose services before starting the Next.js dev server to ensure the database is available.

Testing Workflow: All new features must follow a rigorous testing process before being committed:

1. Manual Testing with Playwright MCP:

   • Use Playwright MCP tools to manually test all functionality interactively
   • Test both happy paths (expected user flows) and unhappy paths (errors, edge cases)
   • Document each step you verify during manual testing - these become test cases
   • If you encounter issues during manual testing (e.g., 404 errors, unexpected behavior), investigate and fix them before proceeding
   • Use the following pattern:

     1. Navigate to the feature
     2. Perform user actions (clicks, typing, etc.)
     3. Verify expected outcomes
     4. Test error scenarios
     5. Verify cleanup/state updates
     

2. Write Comprehensive Magnitude Tests:

   • After manually verifying functionality with Playwright MCP, write extensive Magnitude tests covering ALL verified behaviors
   • Each manual test step should have a corresponding Magnitude test assertion
   • Test files are located in tests/magnitude/ with .mag.ts extension
   • Use the test credentials from .env (TEST_BLUESKY_HANDLE, TEST_BLUESKY_PASSWORD)
   • Include both happy path and unhappy path test cases
   • Example test structure:

     import { test } from 'magnitude-test';
     
     const TEST_HANDLE = process.env.TEST_BLUESKY_HANDLE;
     const TEST_PASSWORD = process.env.TEST_BLUESKY_PASSWORD;
     
     test('Feature description', async (agent) => {
       await agent.act('Navigate to /page');
       await agent.act('Perform user action');
       await agent.check('Verify expected outcome');
     });
     

3. Reusable Playwright Scaffolding:

   • Abstract common patterns (auth, navigation, etc.) into helper files in tests/playwright/helpers/
   • These helpers should be usable both during manual Playwright MCP testing AND by Magnitude tests
   • Examples: tests/playwright/helpers/chat.ts, tests/playwright/helpers/galaxy.ts, tests/playwright/helpers/node.ts
   • For auth setup, use Playwright's global setup pattern (see https://playwright.dev/docs/test-global-setup-teardown)
   • Current auth setup: tests/playwright/auth.setup.ts

4. Generating Playwright Code:

   • Use https://playwright.dev/docs/test-agents to generate Playwright test code when helpful
   • This tool can convert natural language test descriptions into Playwright code

5. Test Execution:

   • Run Magnitude tests: pnpm test or npx magnitude
   • Ensure ALL tests pass before committing
   • If tests fail, fix the implementation or update the tests to match the correct behavior

6. Pre-Commit Checklist:

   • ✅ All manual testing with Playwright MCP completed and verified
   • ✅ All Magnitude tests written and cover all verified functionality
   • ✅ Database verified for expected state after operations (e.g., deletions actually removed records)
   • ✅ Run magnitude tests for current feature FIRST: pnpm test tests/magnitude/your-feature.mag.ts
   • ✅ Verify current feature tests pass
   • ✅ Run ALL magnitude tests: pnpm test
   • ✅ Verify ENTIRE test suite passes
   • ✅ No console errors or warnings in production code paths
   • CRITICAL: Do NOT commit until ALL tests pass - feature tests AND full test suite
   • Only commit after ALL checklist items are complete

7. Documentation:

   • Document test coverage in tests/README.md
   • Add comments to complex test scenarios explaining the business logic being tested

Testing Resources:

• Playwright Global Setup/Teardown: https://playwright.dev/docs/test-global-setup-teardown
• Playwright Test Agents: https://playwright.dev/docs/test-agents
• Playwright Docker: https://playwright.dev/docs/docker
• Magnitude.run Documentation: https://magnitude.run/docs
• Project Test README: tests/README.md

Playwright Docker Setup:

Playwright is integrated into docker-compose for consistent testing environments:

1. Run Playwright tests with docker-compose:

   # Start database services
   docker compose up -d
   
   # Start Next.js dev server
   pnpm dev
   
   # Run Playwright tests in Docker (in another terminal)
   docker compose run --rm playwright
   

2. Alternative: Use the 'test' profile:

   # Start all services including Playwright
   docker compose --profile test up
   
   # Or run tests one-off without keeping services up
   docker compose --profile test run --rm playwright
   

3. Benefits:

   • Non-root user execution (pwuser) for security
   • Consistent browser versions across environments
   • Integrated with existing docker-compose setup
   • Uses host networking to access dev server on localhost:3000
   • Node modules volume prevents permission issues

4. Configuration:

   • Environment variables loaded from .env file
   • Uses network_mode: host to access dev server
   • Runs with profiles: [test] to keep it optional

CI/CD with Gitea Actions:

Magnitude tests run automatically on every push and pull request using a fully containerized setup:

1. Configuration: .gitea/workflows/magnitude.yml

2. Workflow steps (simplified to just 2 steps!):

   • Create .env file with secrets
   • Run docker compose -f docker-compose.ci.yml --profile test up
   • Upload test results and show logs on failure
   • Cleanup

3. Required Secrets (configure in Gitea repository settings):

   • ANTHROPIC_API_KEY - For Magnitude AI vision testing
   • TEST_BLUESKY_HANDLE - Test account handle
   • TEST_BLUESKY_PASSWORD - Test account password
   • ATPROTO_CLIENT_ID, ATPROTO_REDIRECT_URI
   • GOOGLE_API_KEY, DEEPGRAM_API_KEY
   • SURREAL_JWT_SECRET

4. CI-specific docker-compose: docker-compose.ci.yml

   • Fully containerized (SurrealDB + Next.js + Magnitude)
   • Excludes surrealmcp (only needed for local MCP development)
   • Health checks ensure services are ready before tests run
   • Uses in-memory SurrealDB for speed
   • Services dependency chain: magnitude → nextjs → surrealdb

5. Debugging CI failures locally:

   # Runs the EXACT same docker-compose setup as CI
   ./scripts/test-ci-locally.sh
   
   # Or manually:
   docker compose -f docker-compose.ci.yml --profile test up \
     --abort-on-container-exit \
     --exit-code-from magnitude
   

   Since CI just runs docker-compose, you can reproduce failures exactly without any differences between local and CI environments!

6. Test results: Available as workflow artifacts for 30 days

7. Why this approach is better:

   • ✅ Identical local and CI environments (both use same docker-compose.ci.yml)
   • ✅ Fast debugging (no push-test-fail cycles)
   • ✅ Self-contained (all dependencies in containers)
   • ✅ Simple (just 2 steps in CI workflow)
   • ✅ Reproducible (docker-compose ensures consistency)

Testing Framework Separation:

• Playwright: Used for manual testing with Playwright MCP and global auth setup

  • Location: tests/playwright/
  • Helpers: tests/playwright/helpers.ts
  • Auth setup: tests/playwright/auth.setup.ts
  • Run: npx playwright test

• Magnitude: Used for automated end-to-end testing in development and CI/CD

  • Location: tests/magnitude/
  • Helpers: tests/magnitude/helpers.ts
  • Configuration: magnitude.config.ts (uses Claude Sonnet 4.5)
  • Run: npx magnitude or pnpm test

Both frameworks are independent and can be used separately or together depending on the testing need.

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 (, , 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 (, , , ), 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!