docs: update main README with clear documentation structure

Author: apiad

README.md

@@ -1,84 +1,71 @@
-# OpenCode Template Repository
+# OpenCode
 
 <div align="center">
 
 [![Release](https://img.shields.io/github/v/release/apiad/opencode?style=for-the-badge&color=blue)](https://github.com/apiad/opencode/releases)
 [![License](https://img.shields.io/github/license/apiad/opencode?style=for-the-badge&color=success)](LICENSE)
-[![Template](https://img.shields.io/badge/Repository-Template-blueviolet?style=for-the-badge&logo=github)](https://github.com/apiad/opencode/generate)
 
-**Template repository for OpenCode-powered projects.**
+**An intelligent, multi-agent CLI framework for software engineering automation.**
 
-*This repository provides templates and configuration for bootstrapping new projects with the OpenCode framework.*
-
-#### [View opencode-core for the framework implementation](https://github.com/apiad/opencode-core)
+*This repository provides the installer, templates, and documentation. The actual framework lives in [opencode-core](https://github.com/apiad/opencode-core).*
 
 </div>
 
 ---
 
-## Architecture
-
-OpenCode uses a two-repository architecture:
-
-| Repository | Purpose |
-|------------|---------|
-| [opencode-core](https://github.com/apiad/opencode-core) | Core framework, agents, and commands |
-| This repository (opencode) | Templates, configuration, and project bootstrap |
+## Quick Start
 
-When you initialize a new project, the installation script pulls templates from this repository and links them with the core framework.
+```bash
+curl -fsSL https://apiad.github.io/opencode/install.sh | bash
+```
 
----
+## Installation Modes
 
-## Quick Start
+The installer supports two modes:
 
-The fastest way to bootstrap a new project:
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `--mode=copy` | Copy framework files into your project | Self-contained, no external dependencies |
+| `--mode=link` | Link to opencode-core as a git submodule | Auto-updates with the framework |
 
 ```bash
+# Interactive mode (prompts for mode selection)
 curl -fsSL https://apiad.github.io/opencode/install.sh | bash
-```
 
-### Installation Modes
+# Explicit copy mode
+curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --mode=copy
 
-The installer supports two modes:
+# Explicit link mode
+curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --mode=link
+```
 
-| Mode | Description |
-|------|-------------|
-| `--mode=copy` | Copy framework files (updates require manual sync) |
-| `--mode=link` | Symlink to opencode-core (auto-updates with the framework) |
+Run `--help` for all options.
 
-Run `curl -fsSL https://apiad.github.io/opencode/install.sh | bash -s -- --help` for options.
+## Architecture
 
----
+OpenCode uses a two-repository architecture:
 
-## Directory Structure
+| Repository | Purpose |
+|------------|---------|
+| [opencode](https://github.com/apiad/opencode) (this repo) | Installer, templates, documentation |
+| [opencode-core](https://github.com/apiad/opencode-core) | Framework runtime, agents, commands |
 
-```
-.
-├── templates/           # Project templates
-│   ├── .gitignore
-│   ├── CHANGELOG.md
-│   ├── README.md
-│   ├── makefile
-│   └── tasks.yaml
-├── .knowledge/          # Agent knowledge base
-│   ├── drafts/
-│   ├── log/
-│   ├── notes/
-│   └── plans/
-└── .opencode/          # Framework configuration (installed)
-```
+When you install OpenCode, the script pulls templates from this repository and links them with the core framework.
 
----
+## Features
 
-## For Framework Development
+- **Disciplined Workflows** — Agents follow structured phases: discovery → planning → execution → verification
+- **Test-Commit-Revert (TCR)** — Built-in TDD discipline for all code changes
+- **Evidence-Based** — Every claim cites specific sources
+- **Configurable** — Customize agents, commands, and style guidelines
 
-If you're developing the framework itself, see [opencode-core](https://github.com/apiad/opencode-core) for:
-- Core agent implementations
-- Command definitions
-- Framework utilities
+## Documentation
 
----
+- [User Guide](docs/user-guide.md) — Getting started and usage
+- [Developer Guide](docs/develop.md) — Contributing and development
+- [Deployment](docs/deploy.md) — Installation modes and hosting
+- [Updating](docs/updating.md) — Keeping your installation up-to-date
 
-## License & Contribution
+## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](LICENSE) file for details.