docs: flesh out README with real usage, safety, architecture, and dev commands (T08 start)

- Actual examples based on current cya behavior
- Installation, safety notes, boundaries
- Links to workplan and fix-consistency reminder

Part of CYA-WP-0001 T08 (documentation & handoff readiness).

README.md

@@ -1,3 +1,84 @@
-Cya provides a console-native, backend-agnostic LLM helper that understands local work, 
-remembers, is under user control, and helps get things done without requiring command-line 
-trivia to be kept in human memory.
+# cya — console-native assistant for local work
+
+`cya` lets you express intent in natural language from your terminal and receive
+safe, explainable, context-aware help.
+
+It is the CLI surface for the capabilities domain. It owns orchestration,
+the user experience, and the safety layer. It talks to `llm-connect` only
+through a stable adapter boundary and keeps all memory under explicit
+user-controlled ports (implemented by `phase-memory`).
+
+## Status
+
+This is the first narrow MVP slice (CYA-WP-0001). The tool is already
+usable after `pip install -e .`:
+
+- `cya "your request in plain English"`
+- `cya --explain-context "..."` — shows exactly what local context would be sent
+- Automatic rule-based risk classification with mandatory confirmation for anything destructive, privileged, mass-edit, or network-affecting
+- All LLM interaction flows through a documented `LLMAdapter` seam (currently a deterministic fake; ready for real `llm-connect`)
+
+## Installation (development)
+
+```bash
+git clone <this-repo>
+cd can-you-assist
+pip install -e .
+cya --help
+```
+
+## Usage examples
+
+```bash
+# Normal request (safe path)
+cya "show me the recent git history for this repo"
+
+# Risky request — will show classification + require explicit confirmation
+cya "delete every log file older than 30 days in this tree"
+
+# See exactly what context would be collected and sent
+cya --explain-context "explain the changes in the last commit"
+```
+
+The output includes a structured suggestion, rationale, and (when relevant) a
+clear preview + confirmation prompt. Nothing executes without your explicit yes.
+
+## Safety (core product behavior)
+
+- Genuine rule-based assessment is the primary mechanism.
+- Results are available to the model.
+- Anything above "safe" produces a preview and blocks until you confirm in the
+  launching terminal.
+- No autonomous execution in this slice.
+
+See the risk classifier tests and workplan T03 for the exact rules and invariants.
+
+## Architecture & boundaries (important)
+
+- `can-you-assist` (this repo): CLI, context collection, safety, orchestration.
+- `llm-connect`: Provider access, config, token counting, structured responses.
+  All interaction goes through `cya/llm/adapter.py` (`LLMAdapter` Protocol).
+- `phase-memory`: Durable, user-controlled memory. This slice has only
+  strictly minimal explicit no-op ports (see `cya/memory/__init__.py`).
+
+See `workplans/CYA-WP-0001-console-native-mvp.md` for the full task breakdown,
+decisions, and integration guide.
+
+## Development
+
+```bash
+pip install -e .
+pytest tests/ -q
+cya "..."   # manual verification
+```
+
+## License
+
+MIT (see LICENSE).
+
+## Workplan & coordination
+
+- Workplan: `workplans/CYA-WP-0001-console-native-mvp.md`
+- State Hub workstream: `repo-integration-can-you-assist`
+- Operator reminder after changes: `cd ~/state-hub && make fix-consistency REPO=can-you-assist`
+