1 files changed, 96 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e39cbd6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# gemcms
+
+`gemcms` is a small CLI CMS for Gemini capsules.
+
+It keeps capsule content as plain files, generates Gemtext into `public/`, and validates common mistakes before publishing.
+
+## Quick Start
+
+```bash
+go run ./cmd/gemcms create capsule my-capsule --title "My Capsule" --host gemini.example.org --import ~/articles --section journal --tags gemini --build
+cd my-capsule
+
+go run ../cmd/gemcms add ~/article.md --section journal --tags gemini --draft --menu top
+go run ../cmd/gemcms add ~/notes/ --section journal --tags gemini
+go run ../cmd/gemcms create article "Hello Gemini" --tags gemini,capsule
+go run ../cmd/gemcms create page about --title "About"
+go run ../cmd/gemcms menu add top page about --label "About"
+go run ../cmd/gemcms status
+go run ../cmd/gemcms health
+go run ../cmd/gemcms build
+go run ../cmd/gemcms check
+```
+
+Inside an installed build, replace `go run ../cmd/gemcms` with `gemcms`.
+
+## Commands
+
+```text
+gemcms add <file-or-directory> [--type article|page] [--section name] [--tags a,b] [--draft] [--menu name]
+gemcms create capsule <name> [--title title] [--host host] [--import path] [--section name] [--tags a,b] [--menu name] [--build]
+gemcms create site <name> [--title title] [--host host]
+gemcms create page <slug> [--title title]
+gemcms create article <title> [--section name] [--tags a,b] [--draft]
+gemcms create section <name> [--title title]
+gemcms create menu <name>
+gemcms create widget <type> [--name name] [--section name] [--limit n]
+gemcms menu add <menu> <home|page|section|article|custom> [target] [--label label] [--url url]
+gemcms list <pages|articles|menus|widgets>
+gemcms status
+gemcms health
+gemcms build
+gemcms check
+```
+
+See [docs/help.md](docs/help.md) for the full command and option reference.
+
+## Capsule Layout
+
+```text
+capsule.toml
+content/
+  pages/
+  articles/
+assets/
+site/
+  menus/
+  sections/
+  widgets/
+public/
+```
+
+Content files use Gemtext with optional frontmatter:
+
+```text
++++
+title = "Hello Gemini"
+type = "article"
+slug = "hello-gemini"
+date = "2026-07-07"
+tags = ["gemini", "capsule"]
++++
+
+# Hello Gemini
+
+Gemtext content goes here.
+```
+
+Imported Markdown can also use simple YAML frontmatter:
+
+```text
+---
+title: Hello Gemini
+tags: gemini, capsule
+---
+
+# Hello Gemini
+```
+
+If no `--title` is provided, `gemcms add` uses frontmatter `title` first, then the first `# Heading`, then the file name.
+
+Use build-time blocks in Gemtext:
+
+```text
+{{ menu top }}
+{{ widget recent-articles }}
+```