From a872008d44c56f6a08d246cb702c3a2dcf127ef2 Mon Sep 17 00:00:00 2001
From: Maofeng <hornjs@qq.com>
Date: Mon, 27 Jul 2026 05:03:24 +0800
Subject: [PATCH] docs: add project overview

- summarize the package, Runtime, Console, component, and frontend modules
- provide startup, component packaging, and WIT publication commands
- explain Registry dependency resolution and local path replace
- keep local architecture design drafts outside version control
---
 .gitignore |  1 +
 README.md  | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 README.md

diff --git a/.gitignore b/.gitignore
index 43314de..9912c81 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@
 /.idea/
 /components/*/wit/deps/
 /components/*/wit/.deps.*
+/docs/design/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9a1629b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+# Wasmeld
+
+Wasmeld 是面向 WebAssembly Component 的服务运行与管理平台。内部服务编译为
+Component，在受限 Wasmtime Sandbox 中以常驻 Actor 运行，并通过稳定 WIT 契约
+暴露能力。
+
+## 结构
+
+```text
+crates/wasmeld-runtime   Component Runtime 与 Sandbox
+crates/wasmeld-console   管理 API 与持久化
+crates/wasmeld-package   wasmeld CLI、组件包与 WIT 依赖管理
+components/              示例 Component
+console/                 TanStack Start 管理面
+wit/                     Wasmeld WIT package 源码
+```
+
+## 启动
+
+后端：
+
+```bash
+cargo +stable run -p wasmeld-console
+```
+
+管理面：
+
+```bash
+cd console
+npm run dev
+```
+
+构建组件：
+
+```bash
+cargo run -p wasmeld-package --bin wasmeld -- \
+  pack components/echo/Cargo.toml --locked
+```
+
+发布 WIT Package：
+
+```bash
+cargo run -p wasmeld-package --bin wasmeld -- \
+  wit publish wit/service --registry http://127.0.0.1:8080
+```
+
+组件在 `wasmeld.toml` 中声明 Registry 和精确版本依赖，`wasmeld wit fetch` 会递归
+解析依赖、生成 `wit/deps`，并将完整解析结果记录在 `wit.lock`。本地开发可使用
+`[replace]` 临时覆盖 Registry 来源。