1 files changed, 70 insertions, 0 deletions
diff --git a/docs/decisions.md b/docs/decisions.md
new file mode 100644
index 0000000..54a759b
--- /dev/null
+++ b/docs/decisions.md
@@ -0,0 +1,70 @@
+# Decisions
+
+## 2026-07-07 - Build A Go CLI First
+
+Decision:
+
+Implement `gemcms` first as a Go command-line tool.
+
+Rationale:
+
+- A single static binary fits the self-hosted Gemini audience.
+- The core workflows are filesystem and text processing tasks.
+- Avoiding a web admin panel keeps the first version simple and robust.
+
+Consequences:
+
+- The first user experience is terminal-first.
+- A TUI or local web editor can be added later without changing the capsule format.
+
+## 2026-07-07 - Keep Capsules File-Based
+
+Decision:
+
+Store pages, articles, menus, widgets, and config as project files. Do not use a database.
+
+Rationale:
+
+- Gemini capsules are naturally static and text-first.
+- File storage keeps content easy to edit, back up, diff, and publish.
+- A database would add operational cost before it solves a real problem.
+
+Consequences:
+
+- Build-time validation and generation are important.
+- Future features should preserve direct file editability.
+
+## 2026-07-07 - Treat Widgets As Build-Time Blocks
+
+Decision:
+
+Widgets are static Gemtext blocks expanded during `gemcms build`.
+
+Rationale:
+
+- Gemini has no browser-side runtime.
+- Static blocks keep output simple and portable.
+- Menus, recent articles, indexes, and similar blocks can be generated reliably.
+
+Consequences:
+
+- Widget behavior is deterministic at build time.
+- Interactive runtime widgets are out of scope for the core CMS.
+
+## 2026-07-07 - Import Existing Content As A First-Class Workflow
+
+Decision:
+
+Support importing one file or a directory of Markdown/Gemtext files through `gemcms add`, and support `gemcms create capsule` for creating a capsule, importing content, and optionally building output in one command.
+
+Rationale:
+
+- Many users will already have notes or articles as `.md` or `.gmi` files.
+- A CMS for Gemini should reduce setup friction rather than requiring manual folder work.
+- Keeping imports deterministic and file-based preserves direct editability.
+
+Consequences:
+
+- Import behavior must infer metadata from frontmatter, headings, and filenames.
+- Directory imports should skip unrelated files rather than fail on them.
+- Health/status commands become important for confidence after bulk imports.