docs: document deployment model, version pinning, and Hugo future-date gotcha (#65)

* Fix the future date issue so the page is live.
* Bump GitHub Actions to versions running on Node.js 24 (#64)
* docs: document deployment model, version pinning, and Hugo future-date gotcha

Signed-off-by: Steve Scargall <37674041+sscargal@users.noreply.github.com>

Author: sscargal

.claude/skills/hugo-chores/SKILL.md

@@ -17,6 +17,24 @@ Perform maintenance tasks on the MemMachine website repository. Subcommands hand
 /hugo-chores update-npm         # audit and update npm dependencies
 ```
 
+## Deployment Model
+
+The site deploys automatically. Every push to `main` triggers the GitHub Actions workflow at `.github/workflows/hugo.yaml`, which builds the site with Hugo and deploys the output to GitHub Pages. There is no manual deploy step — merging a PR to `main` is the deploy.
+
+**All tool versions are pinned as `env:` vars at the top of that workflow file:**
+
+```yaml
+env:
+  DART_SASS_VERSION: 1.91.0
+  GO_VERSION: 1.25.0
+  HUGO_VERSION: 0.149.0
+  NODE_VERSION: 22.18.0
+```
+
+To upgrade any tool, edit the corresponding env var in `.github/workflows/hugo.yaml` and push to main.
+
+---
+
 ## What You Must Do When Invoked
 
 If no subcommand is given, print the usage above and list the available subcommands with one-line descriptions. Do not run any commands.
@@ -54,11 +72,10 @@ If the latest is newer, proceed.
 
 ### Step 4 — Update the workflow file
 
-In `.github/workflows/hugo.yaml`, find the Hugo installation step. Update the version string from the old version to the new version. Use the Edit tool for a targeted replacement.
+In `.github/workflows/hugo.yaml`, update the `HUGO_VERSION` env var at the top of the `build` job. Use the Edit tool for a targeted replacement.
 
-Common patterns to update:
-- `extended_0.149.0` → `extended_{new_version}` (without the leading `v`)
-- `HUGO_VERSION: '0.149.0'` → `HUGO_VERSION: '{new_version}'`
+The exact line to change (no quotes around the version):
+- `HUGO_VERSION: 0.149.0` → `HUGO_VERSION: {new_version}` (without a leading `v`)
 
 ### Step 5 — Update documentation
 

.claude/skills/write-blog/SKILL.md

@@ -29,7 +29,7 @@ If any of the following are not provided in the invocation arguments, ask for th
 | **author** | Yes | Author's full name as it should appear on the post |
 | **description** | Yes | One sentence for SEO and social preview cards |
 | **tags** | Yes | Comma-separated list (e.g., "AI Agent, Integration, LLM"). Always include at least one. |
-| **date** | Yes | Publish date in `YYYY-MM-DD` format. Defaults to today if not provided. |
+| **date** | Yes | Publish date in `YYYY-MM-DD` format. Defaults to today if not provided. **Must not be in the future** — Hugo silently suppresses future-dated posts at build time unless `--buildFuture` is passed. If the post won't appear, check the date first. |
 | **featured** | No | Should this post appear in the homepage carousel? (add tag `"featured"`) |
 
 ### Step 2 — Derive the slug and path
@@ -60,6 +60,8 @@ YYYY-MM-DDTHH:MM:SS-07:00   # Pacific Daylight Time (summer)
 ```
 Default time: `09:00:00` (9 AM).
 
+> **Date gotcha:** Hugo silently drops any post whose `date` is in the future — it will not appear in the local server or the deployed site. Always use today's date or a past date. If you do not know the current date, ask the user before writing the file.
+
 ### Step 4 — Build the tags array
 
 Start with the user-provided tags. Clean each tag:
@@ -87,11 +89,12 @@ draft: false
   Replace this comment with your blog post content.
   
   BEFORE PUBLISHING:
-  1. Add featured_image.png to this directory (same folder as this index.md)
-  2. Set draft: false in the frontmatter above
-  3. Preview: hugo server --buildDrafts --bind 0.0.0.0
-  4. Build check: hugo --gc --minify
-  5. Commit with signed commit: git commit -sS -m "Add blog: {title}"
+  1. Confirm the date above is today or in the past — Hugo silently hides future-dated posts
+  2. Add featured_image.png to this directory (same folder as this index.md)
+  3. Set draft: false in the frontmatter above
+  4. Preview: hugo server --buildDrafts --bind 0.0.0.0
+  5. Build check: hugo --gc --minify
+  6. Commit with signed commit: git commit -sS -m "Add blog: {title}"
 -->
 ```
 

AGENTS.md

@@ -14,12 +14,13 @@ This repository is the source for [memmachine.ai](https://memmachine.ai/), the p
 
 | Component | Version | Notes |
 |-----------|---------|-------|
-| Hugo | ≥ 0.149.0 **Extended** | Must be Extended edition (Sass support) |
-| Go | ≥ 1.25.0 | Hugo module dependency |
-| Node.js | ≥ 22.x | PostCSS / Autoprefixer |
+| Hugo | ≥ 0.149.0 **Extended** | Must be Extended edition (Sass support); pinned via `HUGO_VERSION` in workflow |
+| Dart Sass | 1.91.0 | CSS compilation; pinned via `DART_SASS_VERSION` in workflow |
+| Go | ≥ 1.25.0 | Hugo module dependency; pinned via `GO_VERSION` in workflow |
+| Node.js | ≥ 22.x | PostCSS / Autoprefixer; pinned via `NODE_VERSION` in workflow |
 | npm | bundled with Node.js | Dependency management |
 | Theme | `memmachine` (custom) | Lives in `themes/memmachine/` |
-| Deployment | GitHub Pages | Via `.github/workflows/hugo.yaml` |
+| Deployment | GitHub Pages | Push to `main` → GitHub Actions → Pages (automatic) |
 
 ---
 
@@ -169,7 +170,18 @@ The `memmachine` theme is fully custom (not a Hugo community theme). It uses:
 
 File: `.github/workflows/hugo.yaml`
 
-Triggers on: push to `main` branch, or manual workflow dispatch.
+Triggers on: push to `main` branch, or manual workflow dispatch. **Merging a PR to `main` is the deploy** — there is no separate deploy step.
+
+All tool versions are pinned as `env:` vars at the top of the `build` job:
+
+| Variable | Current value |
+|----------|--------------|
+| `HUGO_VERSION` | `0.149.0` |
+| `DART_SASS_VERSION` | `1.91.0` |
+| `GO_VERSION` | `1.25.0` |
+| `NODE_VERSION` | `22.18.0` |
+
+To upgrade any tool, edit its variable and push. The download URLs in the workflow derive the version from these vars automatically.
 
 Steps:
 1. Checkout (with submodules, full history)

archetypes/blog.md

@@ -7,3 +7,4 @@ author: ""
 description: ""
 draft: true
 ---
+{{/* NOTE: Hugo silently hides posts whose date is in the future. Keep date = today or earlier. */}}

content/AGENTS.md

@@ -75,7 +75,7 @@ draft: true
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
 | `title` | string | Yes | Full title, used in `<h1>`, og:title, and blog card |
-| `date` | RFC 3339 | Yes | ISO 8601 with timezone offset, e.g. `2026-04-27T09:00:00-08:00` |
+| `date` | RFC 3339 | Yes | ISO 8601 with timezone offset, e.g. `2026-04-27T09:00:00-08:00`. **Must be today or in the past.** Hugo silently suppresses future-dated posts — they will not appear in local preview or the deployed site unless `--buildFuture` is passed. |
 | `featured_image` | string | Yes | Filename only (not path); file must be in the same directory as `index.md` |
 | `tags` | string array | Yes | Used for taxonomy pages; include `"featured"` to appear in homepage carousel |
 | `author` | string | Yes | Full name as it should appear on the post |
@@ -97,10 +97,13 @@ Common existing tags: `"AI Agent"`, `"AI Memory"`, `"Generative AI"`, `"LLM"`, `
 ### Publishing
 
 When the post is ready:
-1. Set `draft: false` in frontmatter.
-2. Build and preview locally: `hugo server --buildDrafts` → `hugo server`
-3. Commit with a signed commit: `git commit -sS -m "Add blog: Post Title"`
-4. Open a pull request against the upstream `main` branch.
+1. Confirm `date` is today or in the past — a future date silently prevents the post from appearing.
+2. Set `draft: false` in frontmatter.
+3. Build and preview locally: `hugo server --buildDrafts` → `hugo server` (no drafts flag confirms the post is visible).
+4. Commit with a signed commit: `git commit -sS -m "Add blog: Post Title"`
+5. Open a pull request against the upstream `main` branch.
+
+> **If a post is missing after publish:** Check `date` first. Hugo drops future-dated content without any warning. Use `hugo server --buildFuture` to temporarily reveal them during debugging.
 
 ---