diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..371b539
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Institute of Software, Chinese Academy of Sciences (ISCAS)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES, LOSS OF USE, DATA, OR PROFITS, OR BUSINESS INTERRUPTION HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3226565
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+# go2spec
+
+[![Status](https://img.shields.io/badge/status-active_development-orange)](#overview)
+[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+[![Language](https://img.shields.io/badge/docs-English-blue)](README.md)
+[![中文文档](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-red)](README.zh.md)
+
+## Overview
+
+go2spec is a Go package helper for the openRuyi RPM packaging workflow. It collects upstream metadata from the Go ecosystem, generates source archives, and writes RPM spec files.
+
+## Installation
+
+### Build From Source
+
+```bash
+git clone <go2spec-repo-url>
+cd go2spec
+go build -o go2spec .
+```
+
+Run it with:
+
+```bash
+./go2spec help
+```
+
+## Quick Start
+
+### Generate a spec
+
+```bash
+go2spec pack golang.org/x/net
+```
+
+The command creates a file layout similar to this in the current directory:
+
+```text
+go-golang-x-net/
+go-golang-x-net/go-golang-x-net.spec
+go-golang-x-net_<version>.orig.tar.<gz|xz>
+```
+
+### Check existing spec updates without writing files
+
+```bash
+go2spec update -n /path/to/SPECS
+```
+
+`update` scans `/path/to/SPECS/go-*/*.spec`, then checks the latest upstream version.
+
+### Run updates concurrently
+
+```bash
+go2spec update -j 4 /path/to/SPECS
+```
+
+> Always run dry run mode first before modifying real spec files.
+
+## Documentation
+
+| Area | English | Chinese |
+|---|---|---|
+| Main README | [README.md](README.md) | [README.zh.md](docs/zh/README.zh.md) |
+| `pack` command | [docs/en/pack.en.md](docs/en/pack.en.md) | [docs/zh/pack.zh.md](docs/zh/pack.zh.md) |
+| `update` command | [docs/en/update.en.md](docs/en/update.en.md) | [docs/zh/update.zh.md](docs/zh/update.zh.md) |
+
+## Contributing
+
+- Read the [openRuyi Code of Conduct](https://openruyi.cn/governance/legal/code-of-conduct) and agree to follow it.
+- Read the [AI-assisted Contribution Policy](https://openruyi.cn/governance/policy/ai-contribution-policy), and note that this Pull Request contains substantial AI-assisted content when applicable.
+
+## License
+
+go2spec uses the BSD-3-Clause license. See [LICENSE](LICENSE).
diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 0000000..5d3a0c8
--- /dev/null
+++ b/README.zh.md
@@ -0,0 +1,75 @@
+# go2spec
+
+[![状态](https://img.shields.io/badge/status-active_development-orange)](#项目概览)
+[![许可证](https://img.shields.io/badge/license-BSD--3--Clause-blue)](LICENSE)
+[![English](https://img.shields.io/badge/docs-English-blue)](README.md)
+[![中文文档](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-red)](README.zh.md)
+
+## 项目概览
+
+go2spec 是面向 openRuyi RPM 打包流程的 Go 包辅助工具。它从 Go 生态获取上游元数据，生成源码归档，并输出 RPM spec。
+
+## 安装指南
+
+### 从源码构建
+
+```bash
+git clone <go2spec-repo-url>
+cd go2spec
+go build -o go2spec .
+```
+
+运行：
+
+```bash
+./go2spec help
+```
+
+## 快速开始
+
+### 生成 spec
+
+```bash
+go2spec pack golang.org/x/net
+```
+
+该命令会在当前目录生成类似下面的文件结构：
+
+```text
+go-golang-x-net/
+go-golang-x-net/go-golang-x-net.spec
+go-golang-x-net_<version>.orig.tar.<gz|xz>
+```
+
+### 不写入文件地检查现有 spec 更新
+
+```bash
+go2spec update -n /path/to/SPECS
+```
+
+`update` 会扫描 `/path/to/SPECS/go-*/*.spec`，然后检查上游最新版本。
+
+### 并发执行更新
+
+```bash
+go2spec update -j 4 /path/to/SPECS
+```
+
+> 建议始终先执行 dry run，再修改真实 spec 文件。
+
+## 文档导航
+
+| 内容 | English | 中文 |
+|---|---|---|
+| 主 README | [README.md](README.md) | [README.zh.md](README.zh.md) |
+| `pack` 命令 | [docs/en/pack.en.md](docs/en/pack.en.md) | [docs/zh/pack.zh.md](docs/zh/pack.zh.md) |
+| `update` 命令 | [docs/en/update.en.md](docs/en/update.en.md) | [docs/zh/update.zh.md](docs/zh/update.zh.md) |
+
+## 贡献
+
+- 阅读 [openRuyi 行为准则](https://openruyi.cn/governance/legal/code-of-conduct) 并同意遵守。
+- 阅读 [AI 辅助贡献政策](https://openruyi.cn/governance/policy/ai-contribution-policy)，且此 Pull Request 包含实质性的 AI 辅助内容时需要说明。
+
+## 许可证
+
+go2spec 使用 BSD-3-Clause 许可证，见 [LICENSE](LICENSE)。
diff --git a/docs/en/pack.en.md b/docs/en/pack.en.md
new file mode 100644
index 0000000..a32643b
--- /dev/null
+++ b/docs/en/pack.en.md
@@ -0,0 +1,58 @@
+# pack Command
+
+[![中文](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-red)](../zh/pack.zh.md)
+[![update command](https://img.shields.io/badge/docs-update-blue)](update.en.md)
+
+`pack` generates an RPM spec draft and a source archive from a Go import path.
+
+**This command is intended to produce a maintainable starting point, not a final package that can be submitted directly. Always review the generated spec manually before submitting it to openRuyi or using it for builds.**
+
+## Usage
+
+```bash
+go2spec pack [FLAG]... <go-package-importpath>
+```
+
+Example:
+
+```bash
+go2spec pack golang.org/x/net
+```
+
+## Flags
+
+```text
+-git_revision <rev>
+    Check out a specific git revision, such as a tag, branch, or commit
+
+-force_prerelease
+    Package HEAD or tip instead of preferring the latest tagged version
+
+-type <type>
+    Select the package type, supported values are library, program, library+program, and program+library
+
+-program_package_name <name>
+    Override the program package name, and the source package name when appropriate
+
+-allow_unknown_hoster
+    Allow package-name generation for unknown hosters, Review the generated name manually
+```
+
+## Output
+
+A successful run creates these files in the current directory:
+
+- `<package-name>/`, package working directory
+- `<package-name>/<package-name>.spec`, generated RPM spec draft
+- `<package-name>_<version>.orig.tar.<gz|xz>`, upstream source archive
+
+If the target package directory already exists and is not empty, go2spec aborts to avoid overwriting existing work.
+
+## Package Types
+
+- `library`, for Go library modules
+- `program`, for command packages whose root package is `main`
+- `library+program`, for projects that ship both library files and command subpackages
+- `program+library`, for program-first projects that also need a library subpackage
+
+When `-type` is omitted, go2spec uses pkg.go.dev package metadata and local `go list` output to infer the type.
diff --git a/docs/en/update.en.md b/docs/en/update.en.md
new file mode 100644
index 0000000..fb547ab
--- /dev/null
+++ b/docs/en/update.en.md
@@ -0,0 +1,46 @@
+# update Command
+
+[![中文](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-red)](../zh/update.zh.md)
+[![pack command](https://img.shields.io/badge/docs-pack-blue)](pack.en.md)
+
+`update` scans existing Go spec packages, checks the latest upstream version, and can update the spec version.
+
+## Usage
+
+```bash
+go2spec update [options] <SPECS_DIR>
+```
+
+`<SPECS_DIR>` must contain `go-*` subdirectories with spec files.
+
+```text
+SPECS_DIR/
+go-golang-x-net/
+go-golang-x-net/go-golang-x-net.spec
+```
+
+## Options
+
+```text
+-n
+    Dry run, detect updates only, do not modify files
+
+-j <num>
+    Number of concurrent checks, default is 3
+```
+
+## Recommended Workflow
+
+Start with dry run mode:
+
+```bash
+go2spec update -n /path/to/SPECS
+```
+
+Apply updates after reviewing the output:
+
+```bash
+go2spec update -j 4 /path/to/SPECS
+```
+
+Review the generated diff before committing packaging changes.
diff --git a/docs/zh/pack.zh.md b/docs/zh/pack.zh.md
new file mode 100644
index 0000000..2e060da
--- /dev/null
+++ b/docs/zh/pack.zh.md
@@ -0,0 +1,58 @@
+# pack 命令
+
+[![English](https://img.shields.io/badge/docs-English-blue)](../en/pack.en.md)
+[![update 命令](https://img.shields.io/badge/docs-update-blue)](update.zh.md)
+
+`pack` 根据 Go import path 生成 RPM spec 初稿和源码归档。
+
+**该命令用于生成可继续维护的起点，不是最终可直接提交的包，提交到 openRuyi 或用于构建前必须人工 review 生成的 spec。**
+
+## 用法
+
+```bash
+go2spec pack [FLAG]... <go-package-importpath>
+```
+
+示例：
+
+```bash
+go2spec pack golang.org/x/net
+```
+
+## 参数
+
+```text
+-git_revision <rev>
+    checkout 指定 git revision，例如 tag、branch 或 commit
+
+-force_prerelease
+    打包 HEAD 或 tip，而不是优先选择最新 tag
+
+-type <type>
+    选择包类型，支持 library、program、library+program 和 program+library
+
+-program_package_name <name>
+    覆盖程序包名，适用时也覆盖源包名
+
+-allow_unknown_hoster
+    允许未知 hoster 参与包名生成，生成结果必须人工检查
+```
+
+## 输出
+
+执行成功后会在当前目录创建：
+
+- `<package-name>/`，package 工作目录
+- `<package-name>/<package-name>.spec`，生成的 RPM spec 初稿
+- `<package-name>_<version>.orig.tar.<gz|xz>`，上游源码归档
+
+如果目标 package 目录已存在且非空，go2spec 会停止执行，以避免覆盖已有工作。
+
+## 包类型
+
+- `library`，适合 Go library module
+- `program`，适合根 package 为 `main` 的命令包
+- `library+program`，适合同时发布库文件和命令子包的项目
+- `program+library`，适合以程序为主，同时需要库子包的项目
+
+不传 `-type` 时，go2spec 会根据 pkg.go.dev package 元数据和本地 `go list` 输出推断类型。
diff --git a/docs/zh/update.zh.md b/docs/zh/update.zh.md
new file mode 100644
index 0000000..5ab0c3d
--- /dev/null
+++ b/docs/zh/update.zh.md
@@ -0,0 +1,46 @@
+# update 命令
+
+[![English](https://img.shields.io/badge/docs-English-blue)](../en/update.en.md)
+[![pack 命令](https://img.shields.io/badge/docs-pack-blue)](pack.zh.md)
+
+`update` 扫描已有 Golang spec 包，检查上游最新版本，并可更新 spec 版本。
+
+## 用法
+
+```bash
+go2spec update [options] <SPECS_DIR>
+```
+
+`<SPECS_DIR>` 必须包含带 spec 文件的 `go-*` 子目录。
+
+```text
+SPECS_DIR/
+go-golang-x-net/
+go-golang-x-net/go-golang-x-net.spec
+```
+
+## 参数
+
+```text
+-n
+    dry run，只检测更新，不修改文件
+
+-j <num>
+    并发检查数量，默认 3
+```
+
+## 推荐流程
+
+先执行 dry run：
+
+```bash
+go2spec update -n /path/to/SPECS
+```
+
+确认输出后再执行更新：
+
+```bash
+go2spec update -j 4 /path/to/SPECS
+```
+
+提交 packaging 变更前必须 review 生成的 diff。