Goal

Create a minimal working web interface that demonstrates successful communication with an AI provider API. This stage proves your hosting environment is configured correctly, your API key works, and the fundamental request/response cycle functions as expected.

By the end of this stage, you'll have a simple chat interface where you can type a message and receive a response from the AI. No conversation storage, no configuration files, no advanced features—just the core connection working reliably.

This foundation is critical. Everything else builds on this basic cycle.

Before You Begin

Pre-flight checklist:

  1. Read all documentation in the docs/ folder (especially architecture.md and testing.md)
  2. Create a TODO list for tracking implementation progress through all build stages (store in docs/TODO.md or your preferred location)

Components to Build

1. HTML Chat Interface

A web page with a message input field, a send button, and an area to display the conversation. This is the user-facing interface where messages are typed and AI responses appear.

Why it exists: Provides the basic UI for interaction. Doesn't need to be polished yet—focus on functionality.

2. Client-Side JavaScript

Code that captures user input, sends it to your API proxy, receives the response, and displays it in the interface.

Why it exists: Handles the browser-side logic. Manages the conversation flow and updates the UI with responses.

3. API Proxy (Server-Side PHP)

A PHP component that receives requests from your client JavaScript, forwards them to the AI provider's API with your API key, and returns the response.

Why it exists: Keeps your API key secure (never exposed to the browser). Centralizes the connection to the AI provider. This is a critical security boundary.

4. System Instruction (Hardcoded)

A basic system instruction that shapes the AI's behavior. For Stage 1, this will be hardcoded directly in your API proxy. Something simple like "You are a helpful assistant" is sufficient—the goal is to prove the instruction mechanism works, not to perfect the pedagogical approach yet. Ask the user if they want a more substantial system instruction at this stage.

Why it exists: Even at this early stage, the AI needs some instruction on how to behave. This will become configurable and modular in later stages, but for now, a simple hardcoded instruction proves the concept.

Implementation Tasks

Use the following tasks as a guide. Create your own TODO list and track progress as you work.

Environment Setup

Build the HTML Interface

Build Client-Side JavaScript

Build the API Proxy

Add the System Instruction

Test the Complete Flow

Success Indicators

When Stage 1 is complete, you should observe these behaviors:

Basic Functionality

System Instruction Working

Error Handling

Technical Validation

Testing and Verification

Before proceeding to Stage 2:

  1. Test the happy path: Send several different messages and verify appropriate responses
  2. Test error conditions: Temporarily break your API key or endpoint and verify errors are handled gracefully
  3. Verify security: Check browser developer tools to confirm your API key is never exposed
  4. Review your code: Ensure you understand what each component does and why it exists

Consult testing.md for additional verification strategies and troubleshooting guidance.

What You've Accomplished

With Stage 1 complete, you have:

You've built something functional, tested it, and understand how it works. This is the hardest part—everything from here adds features to a working system.

STOP: Before Proceeding to Stage 2

Do not move forward until:

When Stage 1 is working completely:

  1. Update your TODO list - mark Stage 1 tasks complete, add any notes or learnings
  2. Create a git commit with your working Stage 1 code
  3. Update any other contextual documents you're maintaining (notes, decisions, etc.)
  4. Proceed to stage-2-context.md