docs: update project documentation with simplified, focused content

- Streamline README, API, architecture, and usage documentation
- Reduce complexity and focus on core functionality
- Update roadmap with more pragmatic, near-term goals
- Simplify contributing guidelines
- Improve overall documentation clarity and readability

docs/usage.md

@@ -1,34 +1,96 @@
 # Usage Guide
 
-This guide explains how to use the Home Assistant MCP Server for smart home device management and integration with language learning systems.
+This guide explains how to use the Home Assistant MCP Server for basic device management and integration.
 
-## Basic Usage
+## Basic Setup
 
 1. **Starting the Server:**
-   - For development: run `npm run dev`.
-   - For production: run `npm run build` followed by `npm start`.
+   - Development mode: `bun run dev`
+   - Production mode: `bun run start`
 
-2. **Accessing the Web Interface:**
-   - Open [http://localhost:3000](http://localhost:3000) in your browser.
+2. **Accessing the Server:**
+   - Default URL: `http://localhost:3000`
+   - Ensure Home Assistant credentials are configured in `.env`
 
-3. **Real-Time Updates:**
-   - Connect to the SSE endpoint at `/subscribe_events?token=YOUR_TOKEN&domain=light` to receive live updates.
+## Device Control
 
-## Advanced Features
+### REST API Interactions
 
-1. **API Interactions:**
-   - Use the REST API for operations such as device control, automation, and add-on management.
-   - See [API Documentation](api.md) for details.
+Basic device control can be performed via the REST API:
 
-2. **Tool Integrations:**
-   - Multiple tools are available (see [Tools Documentation](tools/tools.md)), for tasks like automation management and notifications.
+```typescript
+// Turn on a light
+fetch('http://localhost:3000/api/control', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${token}`
+  },
+  body: JSON.stringify({
+    entity_id: 'light.living_room',
+    command: 'turn_on',
+    parameters: { brightness: 50 }
+  })
+});
+```
 
-3. **Security Settings:**
-   - Configure token-based authentication and environment variables as per the [Configuration Guide](getting-started/configuration.md).
+### Supported Commands
 
-4. **Customization and Extensions:**
-   - Extend server functionality by developing new tools as outlined in the [Development Guide](development/development.md).
+- `turn_on`
+- `turn_off`
+- `toggle`
+- `set_brightness`
+
+### Supported Entities
+
+- Lights
+- Switches
+- Climate controls
+- Media players
+
+## Real-Time Updates
+
+### WebSocket Connection
+
+Subscribe to real-time device state changes:
+
+```typescript
+const ws = new WebSocket('ws://localhost:3000/events');
+ws.onmessage = (event) => {
+  const deviceUpdate = JSON.parse(event.data);
+  console.log('Device state changed:', deviceUpdate);
+};
+```
+
+## Authentication
+
+All API requests require a valid JWT token in the Authorization header.
+
+## Limitations
+
+- Basic device control only
+- Limited error handling
+- Minimal third-party integrations
 
 ## Troubleshooting
 
-If you experience issues, review the [Troubleshooting Guide](troubleshooting.md). 
+1. Verify Home Assistant connection
+2. Check JWT token validity
+3. Ensure correct entity IDs
+4. Review server logs for detailed errors
+
+## Configuration
+
+Configure the server using environment variables in `.env`:
+
+```
+HA_URL=http://homeassistant:8123
+HA_TOKEN=your_home_assistant_token
+JWT_SECRET=your_jwt_secret
+```
+
+## Next Steps
+
+- Explore the [API Documentation](api.md)
+- Check [Troubleshooting Guide](troubleshooting.md)
+- Review [Contributing Guidelines](contributing.md)