diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..404e2c7
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,44 @@
+# Contributing to Vibebox
+
+Thanks for your interest in contributing! This guide keeps PRs small, reviewable, and consistent with the project’s
+development workflow.
+
+**Prerequisites**
+
+- macOS on Apple Silicon (required for the virtualization backend)
+- Rust `1.91.1` or newer (see `Cargo.toml`)
+
+**Getting Started**
+
+1. Fork the repo and create a feature branch.
+2. Build once to validate your toolchain:
+
+```bash
+cargo build --locked
+```
+
+**Development Commands**
+
+- Format: `cargo fmt --all -- --check`
+- Lint: `cargo clippy --all-targets --all-features -- -D warnings`
+- Test: `cargo test --locked`
+- Build: `cargo build --locked`
+
+**Submitting Changes**
+
+- Keep changes focused and scoped to one problem.
+- Update or add tests when behavior changes.
+- If you change user-facing behavior, update docs or help text.
+- Avoid adding heavy dependencies without a clear reason.
+
+**Reporting Issues**
+Please include:
+
+- macOS version and hardware (Apple Silicon model)
+- Vibebox version (`vibebox --version`)
+- Steps to reproduce
+- Logs from `.vibebox/cli.log`, `.vibebox/vm_root.log` and `.vibebox/vm_manager.log`
+
+**Security**
+If you believe you’ve found a security issue, please avoid public disclosure. Open a private report via GitHub Security
+Advisories instead.
diff --git a/README.md b/README.md
index e69de29..ae0dd78 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,82 @@
+<p align="center">
+  <a href="https://vibebox.robcholz.com">
+    <picture>
+      <img src="docs/banner.png" alt="VibeBox logo">
+    </picture>
+  </a>
+</p>
+<p align="center">The open source AI coding agent.</p>
+
+[![Crates.io][crates-badge]][crates-url]
+[![MIT licensed][mit-badge]][mit-url]
+[![Build Status][actions-badge]][actions-url]
+
+[crates-badge]: https://img.shields.io/crates/v/vibebox.svg
+
+[crates-url]: https://crates.io/crates/vibebox
+
+[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
+
+[mit-url]: https://github.com/robcholz/vibebox/blob/main/LICENSE
+
+[actions-badge]: https://github.com/robcholz/vibebox/workflows/CI/badge.svg
+
+[actions-url]: https://github.com/robcholz/vibebox/actions?query=workflow%3ACI+branch%3Amain
+
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="README.zh.md">简体中文</a> |
+</p>
+
+[![OpenCode Terminal UI](docs/screenshot.png)](https://vibebox.robcholz.com)
+
+---
+
+### Installation
+
+```bash
+# YOLO
+curl -fsSL https://raw.githubusercontent.com/robcholz/vibebox/main/install | bash
+
+# Package managers
+cargo install vibebox
+```
+
+> [!TIP]
+> We truly recommend you to use `YOLO`.
+
+todo
+
+### Documentation
+
+todo
+
+### Contributing
+
+If you're interested in contributing to VibeBox, please read our [contributing docs](CONTRIBUTING.md) before
+submitting a pull request.
+
+### Using VibeBox
+
+Feel free to use, but remember to promote VibeBox as well!
+
+### FAQ
+
+#### How is this different from other Sandboxes?
+
+Vibebox is built for fast, repeatable local sandboxes with minimal ceremony. What’s different here:
+
+- Warm startup is typically under **6 seconds** on my M3, so you can jump back in quickly.
+- One simple command — `vibebox` — drops you into the sandbox from your project.
+- Configuration lives in `vibebox.toml`, where you can set CPU, RAM, disk size, and mounts.
+
+### Special Thank
+
+[vibe](https://github.com/lynaghk/vibe) by lynaghk.
+
+And amazing Rust community, without your rich crates and fantastic toolchain like [crates.io](https://crates.io), this
+wouldn't be possible!
+
+---
+
+**Follow me on X** [X.com](https://x.com/robcholz)
diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 0000000..e69de29
diff --git a/docs/banner.png b/docs/banner.png
new file mode 100644
index 0000000..d1b04f3
Binary files /dev/null and b/docs/banner.png differ
diff --git a/docs/screenshot.png b/docs/screenshot.png
new file mode 100644
index 0000000..a5e6bcc
Binary files /dev/null and b/docs/screenshot.png differ