docs(framework): clarify README pitch, terms, and install list

README.md

@@ -30,9 +30,14 @@
 
 ---
 
-The **AI-Driven Dev Framework** is a marketplace — **skills, agents, commands, rules, prompts, templates, recipes…** — that helps you ship **high-quality features to production**.
+The **AI-Driven Dev Framework** installs a working SDLC (Software Development Life Cycle) into your AI coding tool — **skills, agents, commands, rules** — that turns a rough idea into a reviewed, shipped pull request:
 
-> Orchestrate your SDLC (Software Development Life Cycle) at scale, the agentic-engineering way.
+```text
+/aidd-dev:00-sdlc "add rate limiting to the /login endpoint"
+→ spec → plan → implement → review → ship (commit + PR opened)
+```
+
+Why not just write your own commands? → [FAQ](docs/FAQ.md#-why-aidd-instead-of-your-own-skills).
 
 ## ✅ Prerequisites
 
@@ -50,12 +55,14 @@ The **AI-Driven Dev Framework** is a marketplace — **skills, agents, commands,
 | **OpenCode** | ✅ Supported | Flat |
 | **Gemini · Mistral** | 🚧 In progress | — |
 
-<sub>Install steps per tool → [Other tools](#other-tools).</sub>
+<sub>**Marketplace** = installed and updated through your tool's plugin manager. **Flat** = files copied directly into your project, no plugin manager involved. Install steps per tool → [Other tools](#other-tools).</sub>
 
 ## 📦 Install
 
 ### Claude Code
 
+Installs the 6 stable plugins (`aidd-ui` is 🚧 alpha, install separately — see [Plugins](#-plugins)).
+
 **In the session** (slash commands)
 
 ```text
@@ -66,16 +73,26 @@ The **AI-Driven Dev Framework** is a marketplace — **skills, agents, commands,
 /plugin install aidd-vcs@aidd-framework
 /plugin install aidd-pm@aidd-framework
 /plugin install aidd-orchestrator@aidd-framework
+/plugin install aidd-ui@aidd-framework # 🚧 alpha, install separately
 ```
 
-**Command line** (same, prefixed with `claude`)
+
+<details>
+<summary><strong>Command line</strong> (same, prefixed with `claude`)</summary>
 
 ```bash
 claude plugin marketplace add ai-driven-dev/framework
-claude plugin install aidd-context@aidd-framework   # then aidd-refine, aidd-dev, aidd-vcs, aidd-pm, aidd-orchestrator
+claude plugin install aidd-context@aidd-framework
+claude plugin install aidd-refine@aidd-framework
+claude plugin install aidd-dev@aidd-framework
+claude plugin install aidd-vcs@aidd-framework
+claude plugin install aidd-pm@aidd-framework
+claude plugin install aidd-orchestrator@aidd-framework
+claude plugin install aidd-ui@aidd-framework # 🚧 alpha, install separately
 ```
+</details
 
-Update anytime: `/plugin marketplace update aidd-framework`.
+<br/>Update anytime: `/plugin marketplace update aidd-framework`.
 
 ### Other tools
 

docs/FAQ.md

@@ -2,6 +2,10 @@
 
 Most "how do I…" answers live in the README; this page covers what isn't documented elsewhere, plus common install issues and the framework's limits.
 
+## 🤔 Why AIDD instead of your own skills?
+
+You can write your own Claude Code skills — nothing stops you. AIDD exists because that setup is work every team repeats and re-debugs alone: the router/action split ([Skill](GLOSSARY.md#-skill) glossary entry), the plan → implement → review gating, the plugin packaging and versioning, the multi-tool support (Cursor, Copilot, Codex, OpenCode). AIDD ships that scaffolding pre-built and maintained, so you start from a working SDLC loop and only author the skill content specific to your project. If your workflow doesn't match the framework's shape, [`CREATE_PLUGIN.md`](CREATE_PLUGIN.md) shows how to build on the same scaffolding instead of replacing it.
+
 ## 📦 Install, update, other tools
 
 - **Install / first run** → [Quick start](../README.md#-quick-start).