diff --git a/CHANGELOG.md b/CHANGELOG.md
index ad98b56..5c78bfe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,79 @@ xlgo 框架更新日志。本文档遵循 [Keep a Changelog](https://keepachange
 
 ---
 
+## [1.0.4] - 2026-06-22
+
+> 本版本定位为 **DX & Docs release**：开发体验与文档改进，无破坏性 API 变更。对应体检报告 #25/#27/#28/#29/#30。
+
+### Added ✨
+
+#### CLI 多模板（#28）
+
+`xlgo new` 新增 `--template` 参数，支持三种脚手架模板：
+
+```bash
+xlgo new myapp --template minimal     # 轻量 HTTP，无 MySQL/Redis 依赖
+xlgo new myapp --template api         # 标准业务 API，含分层目录（默认）
+xlgo new myapp --template fullstack   # 全组件，NewFullStack 一键启用
+```
+
+- `minimal`：仅 logger + health + 示例路由，目录结构最小化，第一次接触 xlgo 从这里开始
+- `api`：含 handler/model/repository/service 分层 + MySQL/Redis/JWT 配置（默认模板）
+- `fullstack`：`NewFullStack` 全组件 + Swagger + Storage
+
+#### examples/ 目录（#29）
+
+新增两个可运行示例，帮助快速上手：
+
+- `examples/minimal/` — 50 行可跑，不依赖外部服务
+- `examples/full/` — MySQL + Redis + JWT + user CRUD 完整示例（登录发 token、认证路由、创建/查询用户）
+- `examples/README.md` — 运行说明与接口文档
+
+#### docs/ 文档结构（#30）
+
+- 新增 `docs/` 目录，`docs/plans/` 归档历史规划与体检报告
+- 新增 `docs/README.md` 文档索引
+- `Version_Update_Plan_v1.0.2.md` → `docs/plans/`
+- `Version_v1.0.2_report.md` → `docs/plans/`
+- 早期 `report.md` → `docs/plans/v2.0-review.md`
+- `CHANGELOG.md` / `GUIDE.md` 按惯例保留在仓库根目录
+
+### Changed 🔄
+
+#### 模块路径文档改进（#25）
+
+经评估**保留** `xlgo-core` 模块路径——`-core` 后缀反映这是 xlgo 多产品系列（xlgo-core / xlgo-orm / xlgo-ai ...）的核心产品，不去掉。模块路径（`github.com/EthanCodeCraft/xlgo-core`）与包名（`xlgo`）不同是 Go 惯例（cf. `github.com/gin-gonic/gin` → 包名 `gin`）。
+
+改进文档说明，消除新用户 `go mod tidy` 撞墙的困惑：
+
+- README 快速开始新增「模块路径与包名」小节，给出完整 import 示例：
+  ```go
+  import xlgo "github.com/EthanCodeCraft/xlgo-core"
+  ```
+- CLAUDE.md `Import Path Note` 措辞明确化，说明 module path / package name / `-core` 语义
+
+#### Without* Option 定位文档化（#27）
+
+经调研 `Without*` 系列 Option 有真实用例（测试覆盖「先开再关」语义 + `NewFullStack` 后排除单项），**不删除、不标 Deprecated**，改为文档化其定位：
+
+- `app.go` `WithoutLogger` 注释说明：`Without*` 主要用于 `NewFullStack` / `RunFullStack` 启用全部组件后排除个别项
+- README 快速开始补充用法说明：`xlgo.NewFullStack(xlgo.WithoutSwaggerRoutes())`
+
+### 依赖与构建
+
+- `.gitignore` 整理：忽略 `CLAUDE.md`、构建产物（`*.exe` / `bin/`）、临时发版文件（`gitHub_release_*.md`）
+
+### 升级说明
+
+v1.0.4 **无破坏性变更**，从 v1.0.3 升级只需：
+
+```bash
+go get github.com/EthanCodeCraft/xlgo-core@v1.0.4
+go mod tidy
+```
+
+---
+
 ## [1.0.3] - 2026-06-22
 
 > 本版本定位为 **bug fix release**：收口 v1.0.2 引入的破坏性清理，并修复 4 个轻量 bug + 依赖复查。
@@ -341,8 +414,9 @@ v1.0.2 引入可插拔方言注册表后，`gorm.io/driver/postgres` 成为直
 - 基础框架功能
 - 完整示例代码
 
-[Unreleased]: https://github.com/EthanCodeCraft/xlgo-core/compare/v1.0.3...HEAD
+[Unreleased]: https://github.com/EthanCodeCraft/xlgo-core/compare/v1.0.4...HEAD
+[1.0.4]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.0.4
 [1.0.3]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.0.3
-[1.0.2]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.0.2
+[1.0.2]: https://github.com/EthanCodeCraft/xlgo-core/compare/v1.0.1...v1.0.3
 [1.0.1]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.0.1
 [1.0.0]: https://github.com/EthanCodeCraft/xlgo-core/releases/tag/v1.0.0
diff --git a/README.md b/README.md
index efb2a47..e6198d8 100644
--- a/README.md
+++ b/README.md
@@ -734,6 +734,18 @@ docker run -d -p 8080:8080 xlgo-app:latest
 
 > 完整变更历史见 [CHANGELOG.md](./CHANGELOG.md)。
 
+### v1.0.4 (2026-06-22)
+
+> 本版本定位为 **DX & Docs release**：开发体验与文档改进，无破坏性 API 变更。
+
+- **CLI 多模板** - `xlgo new --template minimal/api/fullstack`，支持轻量 HTTP / 标准业务 / 全组件三种脚手架
+- **examples/ 目录** - 新增 `examples/minimal`（无依赖可跑）与 `examples/full`（mysql+redis+jwt+user CRUD）可运行示例
+- **模块路径文档** - 明确说明 module path `xlgo-core` 与 package name `xlgo` 的关系，补完整 import 示例（保留 `-core`，xlgo 多产品系列）
+- **Without* 定位** - 文档化 `Without*` Option 主要用于 `NewFullStack` 后排除单项
+- **文档结构** - 规划文档归档到 `docs/plans/`，新增 `docs/README.md` 索引
+
+升级：`go get github.com/EthanCodeCraft/xlgo-core@v1.0.4`（无破坏性变更）
+
 ### v1.0.3 (2026-06-22)
 
 > 本版本定位为 **bug fix release**：收口 v1.0.2 引入的破坏性清理，并修复 4 个轻量 bug + 依赖复查。完整说明见 [CHANGELOG.md#unreleased](./CHANGELOG.md#unreleased)。
diff --git a/app.go b/app.go
index 37e3ade..03296b7 100644
--- a/app.go
+++ b/app.go
@@ -24,7 +24,7 @@ import (
 
 // Version 框架版本号。发版时只改这一处，避免版本字面量散落各处。
 // CLI（xlgo version）、脚手架生成的 go.mod 等均引用此常量。
-const Version = "1.0.3"
+const Version = "1.0.4"
 
 // HealthCheckFunc 健康检查函数
 type HealthCheckFunc func(context.Context) error