some readme updates (#19)

* checkpoint

* big woo energy

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* more readme edits

Author: threepointone

README.md

@@ -1,23 +1,74 @@
 # 🧠 Cloudflare Agents
 
-🚧 **Work in Progress** 🚧
+![agents-header](https://github.com/user-attachments/assets/f6d99eeb-1803-4495-9c5e-3cf07a37b402)
 
-A collection of examples and tools for building AI agents that run on Cloudflare Workers. The goal is to make it easy to build stateful, long-running agents that can communicate in real-time and run at the edge.
+_This project is in active development. Join us in shaping the future of intelligent agents._
 
-## Current Status
+Welcome to a new paradigm in AI development. Cloudflare Agents provides the foundation for building intelligent, stateful agents that persist, think, and evolve at the edge of the network.
 
-This is an early-stage project. We're currently building out:
+## Vision
 
-- Example implementations
-- Documentation and guides
-- A core agent framework
+We're creating a framework where AI agents can:
 
-Stay tuned for updates!
+- Maintain persistent state and memory
+- Engage in real-time communication
+- Process and learn from interactions
+- Operate autonomously at global scale
+- Hibernate when idle, awaken when needed
+
+## Project Status
+
+This project is actively evolving. Current focus areas:
+
+### Ready for Use
+
+- Core agent framework with state management
+- Real-time WebSocket communication
+- HTTP endpoints and routing
+- React integration hooks
+- Basic AI chat capabilities
+
+### In Development
+
+- Advanced memory systems
+- WebRTC for audio/video
+- Email integration
+- Evaluation framework
+- Enhanced observability
+- Self-hosting guide
 
 ## Getting Started
 
-Check out the `/examples` directory for current implementations. Each example has its own README with setup instructions.
+### Quick Start
+
+```bash
+# Create a new project
+npm create cloudflare@latest -- --template agents
+
+# Or add to existing project
+npm install @cloudflare/agents
+```
+
+## Documentation
+
+For comprehensive documentation and guides:
+
+- [Core Framework](packages/agents/README.md)
+- [The Anthropic Patterns for building effective agents](guides/anthropic-patterns/README.md)
+- [Human in the Loop](guides/humans-in-the-loop/README.md)
+- [Playground](examples/playground/README.md)
+
+## Contributing
+
+We welcome contributions! Whether it's:
+
+- New examples
+- Documentation improvements
+- Bug fixes
+- Feature suggestions
 
 ## License
 
-MIT License - feel free to use and adapt as needed.
+MIT License - Build something meaningful.
+
+---

docs/index.md

@@ -0,0 +1,22 @@
+- get started
+- add to an existing project
+- routing
+- human in the loop
+- control flow
+- state
+- sync-engine
+- ai-sdk
+- tools
+- other stacks
+- http/ws
+- email
+- a/v
+- scheduling
+- pause/resume
+- memory
+- evals
+- observability
+- connect anything
+- self hosting
+- how is this different from durable objects?
+- resources / read more

examples/playground/README.md

@@ -1,3 +1,35 @@
-## agents playground
+# Agent Playground
 
-Just a bunch of trials for stuff.
+A collection of interactive examples demonstrating core agent capabilities.
+
+## Running the Examples
+
+```bash
+# Install dependencies
+npm install
+
+# Start the development server
+npm start
+```
+
+Visit `localhost:5173` to explore the examples.
+
+## Examples
+
+### State Synchronization
+
+Demonstrates real-time state synchronization across multiple clients:
+
+- Counter with shared state
+- Text input synchronization
+- Color picker with live updates
+- Multi-window synchronization
+
+### Temporal Patterns
+
+Shows how agents can schedule and manage tasks over time:
+
+- Immediate actions (10-second intervals)
+- Daily scheduled tasks
+- Cron-based scheduling
+- Future date scheduling