#!/usr/bin/env bash # wiki-maintain.sh — Agent Estate Wiki maintenance entrypoint # Run daily at 03:00 AWST via cron (wiki-stocktake-maintenance job) # # Does three things: # 1. Regenerates systems/skills-index.md from live ~/.hermes/skills/ tree # 2. Audits EVERY page for staleness (>21 days since `updated` frontmatter) # 3. Rebuilds Quartz static site into public/ set -euo pipefail WIKI_DIR="/home/hermes/workspace/agent-estate-wiki" SKILLS_DIR="$HOME/.hermes/skills" STOCKTAKE_DIR="$WIKI_DIR/raw/stocktake" QUARTZ_CONTENT_DIR="$WIKI_DIR/public" TODAY=$(date +%Y%m%d) cd "$WIKI_DIR" echo "[wiki-maintain] Starting maintenance at $(date -Iseconds)" echo "" # ============================================================================= # [1/3] Regenerate skills-index.md from live skill tree # ============================================================================= echo "[1/3] Regenerating systems/skills-index.md from $SKILLS_DIR..." python3 << 'PYTHON_SCRIPT' import sys from pathlib import Path from datetime import date import subprocess skills_dir = Path("/home/hermes/.hermes/skills") output = Path("/home/hermes/workspace/agent-estate-wiki/systems/skills-index.md") # Use find to get all SKILL.md files, then group by their immediate parent category # This handles nested structures like context-engineering-collection/skills/foo/SKILL.md result = subprocess.run( ["find", str(skills_dir), "-name", "SKILL.md", "-type", "f"], capture_output=True, text=True ) skill_files = [Path(p) for p in result.stdout.strip().split('\n') if p] # Group by the top-level category (first directory under skills_dir) categories = {} for skill_md in skill_files: # Get relative path from skills_dir try: rel = skill_md.relative_to(skills_dir) except ValueError: continue # Skip if not under skills_dir (e.g., broken symlinks) # Top-level category is the first part of the path category = rel.parts[0] skill_name = skill_md.parent.name # The directory containing SKILL.md # Read the description from the skill file try: content = skill_md.read_text(errors='ignore')[:2000] lines = content.split('\n') desc = "" in_frontmatter = False for line in lines: if line.strip() == '---': in_frontmatter = not in_frontmatter continue if not in_frontmatter and line.strip(): desc = line.strip() break if len(desc) > 200: desc = desc[:197] + "..." except Exception as e: desc = f"[error reading: {e}]" if category not in categories: categories[category] = [] # Avoid duplicates (same skill_name in same category) if not any(name == skill_name for name, _ in categories[category]): categories[category].append((skill_name, desc)) # Sort skills within each category for cat in categories: categories[cat] = sorted(categories[cat], key=lambda x: x[0]) # Build the markdown today = date.today().isoformat() lines = [ "---", "title: Installed Skills", "type: system", "status: active", "created: 2026-07-22", f"updated: {today}", f"verified_on: {today}", "confidence: high", "tags: [skills, hermes]", "sources: []", "---", "", "# Installed Skills", "", f"**Total installed: {sum(len(v) for v in categories.values())} skills** in `~/.hermes/skills/`.", "", "This page is auto-regenerated from the live skill inventory. Do not hand-edit.", "", "## Stock-take notes", "- Category = directory structure under `~/.hermes/skills/` (`category/skill/SKILL.md`).", "- Skills directly under `~/.hermes/skills/` group under `uncategorized`.", "", ] # Write categories (sorted, excluding 'uncategorized' which goes last) for cat_name in sorted(categories.keys()): skills = categories[cat_name] # Format category name (capitalize first letter of each word) cat_display = cat_name.replace('-', ' ').title() lines.append(f"## {cat_display} ({len(skills)})") lines.append("") for skill_name, desc in skills: # Format skill name skill_display = skill_name.replace('-', ' ') if desc: lines.append(f"- `{skill_name}` — {desc}") else: lines.append(f"- `{skill_name}` — (no description)") lines.append("") output.write_text('\n'.join(lines)) print(f" Written {output} with {sum(len(v) for v in categories.values())} skills in {len(categories)} categories") PYTHON_SCRIPT echo "" # ============================================================================= # [2/3] Freshness audit — check every page's `updated` frontmatter # ============================================================================= REPORT="$STOCKTAKE_DIR/freshness-$TODAY.txt" echo "[2/3] Auditing wiki freshness (threshold: >21 days)..." python3 "$STOCKTAKE_DIR/_freshness_audit.py" "$WIKI_DIR" "$REPORT" 21 echo "" # ============================================================================= # [3/3] Rebuild Quartz static site and deploy to public/ # ============================================================================= # Quartz v4/v5 lives in a SEPARATE source tree (/home/hermes/workspace/quartz-temp); # the wiki repo only holds the Markdown. The build reads content/ from that tree # and emits public/ there, which we then deploy into the wiki repo's public/. # # PITFALL (hit 2026-10-20): the previous version of this step tested for # `quartz.config.ts` and `npx`, and the repo has NEITHER — Quartz v4/v5 uses # `quartz.config.yaml`. The test always failed, so the site silently stopped # being rebuilt (published site was 40 days stale). Do not reintroduce a # config-file existence test that isn't the real one: check quartz.config.yaml. echo "[3/3] Rebuilding Quartz static site..." QUARTZ_DIR="/home/hermes/workspace/quartz-temp" QUARTZ_CONTENT="$QUARTZ_DIR/content" QUARTZ_PUBLIC="$QUARTZ_DIR/public" QUARTZ_DEPLOY_DIR="$WIKI_DIR/public" if [ ! -f "$QUARTZ_DIR/quartz.config.yaml" ]; then echo " ERROR: $QUARTZ_DIR/quartz.config.yaml not found — cannot build the Quartz site." >&2 echo " The published site will stay stale. Fix the Quartz source tree before continuing." >&2 exit 1 fi # --- sync wiki Markdown into the Quartz content tree ------------------------- # raw/ is excluded on purpose: it holds raw config dumps and the stocktake # reports, which have never been part of the published site. public/ and .git # are excluded to avoid copying build output into the input tree. rm -rf "$QUARTZ_CONTENT" mkdir -p "$QUARTZ_CONTENT" tar -C "$WIKI_DIR" \ --exclude=./public --exclude=./.git --exclude=./node_modules --exclude=./raw \ -cf - . | tar -C "$QUARTZ_CONTENT" -xf - echo " Synced wiki content into $QUARTZ_CONTENT" # --- build ------------------------------------------------------------------- cd "$QUARTZ_DIR" # PIPESTATUS is required: a plain pipeline would report tail's exit code (0) # and silently swallow a failed build. npx quartz build 2>&1 | tail -8 BUILD_RC=${PIPESTATUS[0]} if [ "$BUILD_RC" -ne 0 ]; then echo " ERROR: Quartz build failed (exit $BUILD_RC)." >&2 exit 1 fi # --- deploy ------------------------------------------------------------------ # Clear the CONTENTS of public/ rather than removing the directory itself: # hermes-wiki-serve.service runs with its cwd inside public/, so replacing the # directory inode leaves the running server serving a deleted directory (all # requests 404) until it is restarted. find "$QUARTZ_DEPLOY_DIR" -mindepth 1 -delete cp -a "$QUARTZ_PUBLIC/." "$QUARTZ_DEPLOY_DIR/" echo " Deployed $(find "$QUARTZ_DEPLOY_DIR" -type f | wc -l) files to $QUARTZ_DEPLOY_DIR" systemctl --user restart hermes-wiki-serve.service 2>/dev/null \ && echo " Restarted hermes-wiki-serve.service" \ || echo " WARNING: could not restart hermes-wiki-serve.service — verify the site manually" echo "" echo "[wiki-maintain] Maintenance complete at $(date -Iseconds)" echo " Freshness report: $REPORT" echo "" # Print summary head -5 "$REPORT" tail -3 "$REPORT"