doc: reafirmed project goals and direction

README.md

@@ -1,8 +1,10 @@
 # rdb-discovery
 
-A small CLI-first tool for repeatable software project discovery and delivery.
+A small CLI-first tool that helps you generate and maintain useful project context files for AI-assisted development.
 
-It creates markdown files that help humans and AI coding agents understand:
+## Purpose
+
+rdb-discovery exists to make it easier for humans and AI coding agents to understand:
 
 - what is being built
 - why it exists
@@ -10,6 +12,20 @@ It creates markdown files that help humans and AI coding agents understand:
 - what task should be done next
 - what stage the project is currently in
 
+The tool creates and manages a set of markdown files — your project's source-of-truth context.
+
+## Core workflow
+
+1. **Ask discovery questions** — `rdb discover` captures answers about the product, architecture, risks, and open questions.
+2. **Capture answers** — Structured responses are stored in `context/discovery-log.md` alongside confidence scores and follow-ups.
+3. **Generate context files** — `rdb init` creates standardised project files (`product-brief.md`, `architecture.md`, `decisions.md`, etc.).
+4. **Support agent implementation** — `rdb prompt` produces ready-to-paste implementation prompts for Claude Code or Cline, and `rdb start` / `rdb complete` manage task lifecycles.
+
+## Support features (not the product)
+
+- **Telemetry** records structured agent activity events in `.rdb/session-log.jsonl`. It enables future analysis but is not the main offering.
+- **Guardrails** detect agent stalls, repeated reads, and inconsistent state to keep projects on track. They support the workflow but are secondary.
+
 ## Install for local development
 
 ```bash
@@ -21,23 +37,24 @@ pip install -e '.[dev]'
 ## Commands
 
 ```bash
-rdb init
-rdb discover
-rdb status
-rdb next
-rdb start TASK-001
-rdb complete TASK-001
-rdb handoff
+rdb init             # Create standard project structure and context files
+rdb discover         # Ask 10 core discovery questions, record answers
+rdb guardrails       # Check for agent stalls and state inconsistencies
+rdb prompt           # Generate implementation prompt for the next task
+rdb start TASK-001   # Mark a task as in progress
+rdb complete TASK-001# Mark a task as done
+rdb status           # Show current stage and active task
+rdb next             # Print the next task to work on
+rdb handoff          # Generate agent handoff notes
 ```
 
 ## Bootstrap workflow
 
 1. Run `rdb init`
 2. Run `rdb discover`
-3. Run `rdb status`
-4. Run `rdb next`
-5. Give the next task to Claude Code or Cline
-6. Commit after each completed task
+3. Review `rdb status` and `rdb next`
+4. Give the next prompt to Claude Code or Cline via `rdb prompt`
+5. Commit after each completed task
 
 ## Project structure