diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..0471104
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,47 @@
+SHELL := /bin/bash
+POSTS := content/posts
+
+.DEFAULT_GOAL := help
+
+.PHONY: help new serve build publish clean
+
+help:
+	@echo 'targets:'
+	@echo '  make new SLUG=<slug> TITLE="<标题>" [SUMMARY="<摘要>"]   # 新建文章'
+	@echo '  make serve                                              # hugo server -D (需装 hugo)'
+	@echo '  make build                                              # hugo build 到 public/'
+	@echo '  make publish MSG="post: <slug>"                         # commit + push, 触发 CI'
+	@echo '  make clean                                              # rm -rf public/'
+
+new:
+	@test -n "$(SLUG)"  || { echo 'SLUG required';  exit 1; }
+	@test -n "$(TITLE)" || { echo 'TITLE required'; exit 1; }
+	@test ! -e $(POSTS)/$(SLUG).md || { echo "$(POSTS)/$(SLUG).md already exists"; exit 1; }
+	@DATE="$$(date '+%Y-%m-%dT%H:%M:%S%:z')"; \
+	{ \
+	  echo '---'; \
+	  echo 'title: "$(TITLE)"'; \
+	  echo "date: $$DATE"; \
+	  echo 'draft: false'; \
+	  if [ -n "$(SUMMARY)" ]; then echo 'summary: "$(SUMMARY)"'; fi; \
+	  echo '---'; \
+	  echo ''; \
+	  echo '<!-- 正文写这里 (markdown) -->'; \
+	} > $(POSTS)/$(SLUG).md
+	@echo "created $(POSTS)/$(SLUG).md"
+
+serve:
+	hugo server -D
+
+build:
+	hugo --minify --gc
+
+publish:
+	@test -n "$(MSG)" || { echo 'MSG required (e.g. MSG="post: 你好世界")'; exit 1; }
+	git add content/
+	@git diff --cached --quiet && { echo 'nothing to commit'; exit 1; } || true
+	git commit -m "$(MSG)"
+	git push
+
+clean:
+	rm -rf public/
diff --git a/README.md b/README.md
index 70b5c1e..77b1e67 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,67 @@
 # blog
 
-Hugo blog (gnoc-managed)
\ No newline at end of file
+Fam 的博客源码 (Hugo + PaperMod 主题),线上 https://famzheng.me/。
+
+## 写一篇文章
+
+```bash
+make new SLUG=hello-world TITLE='你好，世界' SUMMARY='第一篇,随便聊聊'
+$EDITOR content/posts/hello-world.md      # 写正文 (markdown)
+make publish MSG='post: hello world'      # commit + push,触发 CI
+```
+
+约 1 分钟后文章在 `https://famzheng.me/posts/<slug>/` 上线。
+CI 状态: <https://famzheng.me/gitea/fam/blog/actions>
+
+## 目录
+
+```
+content/posts/                # 文章 markdown,文件名 = URL slug
+hugo.toml                     # 站点配置 (baseURL, 主题选项, social 链接)
+layouts/                      # 主题 override (尽量别动)
+static/                       # favicon 等公开资源
+themes/PaperMod/              # 主题 (git submodule, 尽量别动)
+.gitea/workflows/publish.yml  # CI: hugo build -> rsync 到 /var/gnoc/hugo-public/
+```
+
+## Frontmatter
+
+每篇文章顶部 YAML:
+
+```yaml
+---
+title: "标题"
+date: 2026-04-30T10:00:00+01:00
+draft: false
+summary: "一句话摘要 (可选,影响列表页和 og:description)"
+---
+```
+
+`make new` 会填好这四个字段,你只需要写正文。
+
+## 文风 (供 AI 参考)
+
+- 第一人称、口语化,不要 AI 流水账
+- 标题简洁,正文别堆 emoji
+- 长度 500-2000 字偏多,宁短勿长
+- 写之前先扫一眼 `content/posts/*.md` 已发文章,对齐 Fam 的语气
+
+## 部署机制
+
+```
+git push origin main
+  → Gitea 触发 .gitea/workflows/publish.yml
+  → host shell act_runner (gnoc 用户, 在 famzheng.com 节点)
+  → 装 hugo 0.147.6 extended → hugo --minify --gc → rsync public/ /var/gnoc/hugo-public/
+  → k8s gnoc-hugo/hugo (nginx) hostPath 直出
+  → ingress famzheng.me/ 命中
+```
+
+## 本地预览 (可选)
+
+需要 hugo 0.147.6 extended:
+
+```bash
+make serve    # http://localhost:1313, 热重载, draft 也能看
+make build    # 一次性 build 到 public/, sanity check
+```