Document local development dependencies

README.md

@@ -1,2 +1,54 @@
-* This is the code repository for the Ask KennyB blog.  I'm using it to keep my files in sync as I work on the blog project.  This is my frist attempt at using a Git-based versioning system, but I think this will be a powerful tool for keeping this project going and backing up my my site with the mechanisms already in Cloudron where it's hosted.
+# AskKennyB
-* Eventually, I'll use Gitea to share my docker compose stack for my homelab as well.
+
+This repository contains the source for the Ask KennyB static site. The site source lives under `askkennyb/` and is built with Hugo.
+
+## Deployment Model
+
+Pushes to `main` trigger the Gitea workflow in `.gitea/workflows/deploy.yml`.
+
+That workflow:
+- builds the site with `hugo --minify -s askkennyb`
+- deploys the generated output in `askkennyb/public/` to Cloudron Surfer
+
+Because CI builds the site on each push, `askkennyb/public/` is local build output and is intentionally ignored in Git.
+
+## Local Development Dependencies
+
+These tools should be available on any development machine used for this project:
+
+- `git`: source control
+- `ssh`: access to the Gitea remote at `ssh://git@code.askkb.com:29418/kbondelie/AskKennyB.git`
+- `hugo`: required for local builds and previewing the site
+- `ripgrep` (`rg`): recommended for fast searching in content and config
+- `node` and `npm`: required for the Cloudron Surfer CLI
+- `cloudron-surfer` (`surfer`): optional for local deploy testing; CI also uses it
+
+## Version Notes
+
+- Use a recent Hugo version. This repo's vendored `PaperMod` theme declares a minimum Hugo version of `0.146.0`.
+- `node` should be reasonably current. The Gitea workflow currently uses Node 18.
+
+## Environment Verification
+
+After setting up a new machine, these commands should work:
+
+```bash
+git --version
+ssh -V
+hugo version
+rg --version
+node --version
+npm --version
+surfer --version
+```
+
+You can verify the site builds locally with:
+
+```bash
+hugo --minify -s askkennyb
+```
+
+## Notes
+
+- The `PaperMod` theme is currently vendored in `askkennyb/themes/PaperMod`.
+- `.codex` is intentionally left in the repo root as local project context.