From 35c0b727e7d5fadd5f01eb5b1ef8dc9f9181a3aa Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 8 May 2026 15:29:54 +0000
Subject: [PATCH 1/8] Rename website/ directory to app/

https://claude.ai/code/session_01MqEqGhP1guGx5VuFsLaws2
---
 {website => app}/assets/fonts/.gitkeep  | 0
 {website => app}/assets/images/.gitkeep | 0
 {website => app}/config.yml             | 0
 {website => app}/index.html             | 0
 {website => app}/nav.yml                | 0
 {website => app}/pages/home.md          | 0
 {website => app}/posts/.gitkeep         | 0
 {website => app}/search.json            | 0
 8 files changed, 0 insertions(+), 0 deletions(-)
 rename {website => app}/assets/fonts/.gitkeep (100%)
 rename {website => app}/assets/images/.gitkeep (100%)
 rename {website => app}/config.yml (100%)
 rename {website => app}/index.html (100%)
 rename {website => app}/nav.yml (100%)
 rename {website => app}/pages/home.md (100%)
 rename {website => app}/posts/.gitkeep (100%)
 rename {website => app}/search.json (100%)

diff --git a/website/assets/fonts/.gitkeep b/app/assets/fonts/.gitkeep
similarity index 100%
rename from website/assets/fonts/.gitkeep
rename to app/assets/fonts/.gitkeep
diff --git a/website/assets/images/.gitkeep b/app/assets/images/.gitkeep
similarity index 100%
rename from website/assets/images/.gitkeep
rename to app/assets/images/.gitkeep
diff --git a/website/config.yml b/app/config.yml
similarity index 100%
rename from website/config.yml
rename to app/config.yml
diff --git a/website/index.html b/app/index.html
similarity index 100%
rename from website/index.html
rename to app/index.html
diff --git a/website/nav.yml b/app/nav.yml
similarity index 100%
rename from website/nav.yml
rename to app/nav.yml
diff --git a/website/pages/home.md b/app/pages/home.md
similarity index 100%
rename from website/pages/home.md
rename to app/pages/home.md
diff --git a/website/posts/.gitkeep b/app/posts/.gitkeep
similarity index 100%
rename from website/posts/.gitkeep
rename to app/posts/.gitkeep
diff --git a/website/search.json b/app/search.json
similarity index 100%
rename from website/search.json
rename to app/search.json

From 24670a66dd60f5f07fdfd91eaa785fbbda94beea Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 8 May 2026 16:05:04 +0000
Subject: [PATCH 2/8] Rebuild mdcms as proper CLI tool (v0.3)

- Replace interactive TUI with click-based subcommands:
  register, delete, view, build
- build accepts NAME (registry), --path, or CWD for GitHub Actions use
- Switch to PyYAML for frontmatter and nav.yml parsing
- Add pyproject.toml with click + PyYAML deps and mdcms entry point
- Add v0.3 version marker to app/config.yml and app/index.html
- Registry moves to ~/.config/mdcms/sites.json (XDG-compliant)
- Project root is now the directory containing index.html (no website/ subdir)
- register auto-downloads template from GitHub if no site found

https://claude.ai/code/session_01MqEqGhP1guGx5VuFsLaws2
---
 app/config.yml |    3 +-
 app/index.html |    3 +-
 mdcms.py       | 1470 +++++++++++++-----------------------------------
 pyproject.toml |   26 +
 4 files changed, 413 insertions(+), 1089 deletions(-)
 create mode 100644 pyproject.toml

diff --git a/app/config.yml b/app/config.yml
index 6c32f19..86727da 100644
--- a/app/config.yml
+++ b/app/config.yml
@@ -1,4 +1,5 @@
-# MD-CMS v0.2 — Site configuration
+# mdcms v0.3 | DO NOT REMOVE THIS COMMENT
+# MD-CMS v0.3 — Site configuration
 #
 # Only `sitename` and `navigation` are required. Uncomment and edit the rest
 # as needed. See https://kbenestad.codeberg.page/md-cms for the full reference.
diff --git a/app/index.html b/app/index.html
index ec16766..a80ba18 100644
--- a/app/index.html
+++ b/app/index.html
@@ -1,5 +1,6 @@
+<!-- mdcms v0.3 | DO NOT REMOVE THIS COMMENT -->
 <!--
-  MD-CMS v0.2 — Renderer
+  MD-CMS v0.3 — Renderer
 
   Copyright 2026 Kristian Benestad | kbenestad.codeberg.page
 
diff --git a/mdcms.py b/mdcms.py
index 22b7a29..5c94e51 100644
--- a/mdcms.py
+++ b/mdcms.py
@@ -1,173 +1,139 @@
 #!/usr/bin/env python3
 #
-# MD-CMS v0.2.2 — Companion CLI
+# mdcms v0.3 — CLI companion
 #
-# LICENCE
-#   Copyright 2026 Kristian Benestad | docs.benestad.net
-#
-#   Licensed under the Apache License, Version 2.0 (the "Licence");
-#   you may not use this file except in compliance with the Licence.
-#   You may obtain a copy of the Licence at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#   Unless required by applicable law or agreed to in writing, software
-#   distributed under the Licence is distributed on an "AS IS" BASIS,
-#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#   See the Licence for the specific language governing permissions and
-#   limitations under the Licence.
+# Copyright 2026 Kristian Benestad
+# Apache License, Version 2.0 — https://www.apache.org/licenses/LICENSE-2.0
 
-"""MD-CMS v0.2.2 — Companion CLI.
-
-Scans `pages/` and `posts/` in the active website directory and writes
-`nav.yml` and `search.json`. Also manages a registry of named website paths
-so the tool can be invoked from anywhere on the system.
-"""
+"""MD-CMS v0.3 — CLI tool for managing and building MD-CMS sites."""
 
 import json
 import os
 import re
-import sys
-import subprocess
-import time
+import urllib.error
 import urllib.request
-import webbrowser
-import zipfile
 from pathlib import Path
 
-VERSION = "0.2"
-DATE = "2026-04-16"
-BANNER_URL = f"https://raw.githubusercontent.com/kbenestad/mdcms/refs/heads/main/resources/banner/v{VERSION}.txt"
-HELP_URL = "https://docs.benestad.net"
+import click
+import yaml
 
-CONFIG_DIR = Path.home() / ".mdcms"
-PATHS_FILE = CONFIG_DIR / "paths.json"
+CLI_VERSION = "0.3"
+MIN_SUPPORTED_VERSION = "0.3"
 
-SEP = "-" * 80
+MARKER_RE = re.compile(r"mdcms v(\d+\.\d+)", re.IGNORECASE)
+CATEGORY_CODE_RE = re.compile(r"^[a-zA-Z0-9\-]+$")
+
+REGISTRY_FILE = Path.home() / ".config" / "mdcms" / "sites.json"
+GITHUB_CONTENTS_API = "https://api.github.com/repos/kbenestad/mdcms/contents/app"
 
 
-# ─── Path registry ───────────────────────────────────────────
+# ─── Version helpers ──────────────────────────────────────────
 
-def load_registry():
-    if PATHS_FILE.exists():
+def _parse_ver(v: str) -> tuple:
+    return tuple(int(x) for x in v.split("."))
+
+
+def read_site_version(site_path: Path) -> "str | None":
+    config = site_path / "config.yml"
+    if not config.exists():
+        return None
+    try:
+        first_line = config.read_text(encoding="utf-8").split("\n", 1)[0]
+        m = MARKER_RE.search(first_line)
+        return m.group(1) if m else None
+    except OSError:
+        return None
+
+
+def version_status(site_version: str) -> "tuple[str, str]":
+    """Returns (status_code, display_message). status_code: 'ok', 'outdated', 'unsupported', 'newer'."""
+    sv = _parse_ver(site_version)
+    min_sv = _parse_ver(MIN_SUPPORTED_VERSION)
+    cur = _parse_ver(CLI_VERSION)
+    if sv < min_sv:
+        return "unsupported", f"v{site_version} — below minimum supported v{MIN_SUPPORTED_VERSION}"
+    if sv < cur:
+        return "outdated", f"v{site_version} — update available (CLI is v{CLI_VERSION})"
+    if sv > cur:
+        return "newer", f"v{site_version} — site newer than CLI (consider upgrading mdcms)"
+    return "ok", f"v{site_version}"
+
+
+# ─── Registry ─────────────────────────────────────────────────
+
+def load_registry() -> dict:
+    if REGISTRY_FILE.exists():
         try:
-            return json.loads(PATHS_FILE.read_text(encoding="utf-8"))
+            return json.loads(REGISTRY_FILE.read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError):
             pass
-    return {"active": None, "paths": {}}
+    return {"sites": {}}
 
 
-def save_registry(reg):
-    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
-    PATHS_FILE.write_text(json.dumps(reg, indent=2), encoding="utf-8")
+def save_registry(reg: dict):
+    REGISTRY_FILE.parent.mkdir(parents=True, exist_ok=True)
+    REGISTRY_FILE.write_text(json.dumps(reg, indent=2), encoding="utf-8")
 
 
-def active_path():
-    reg = load_registry()
-    name = reg.get("active")
-    if not name:
-        return None, None
-    p = reg["paths"].get(name)
-    if not p:
-        return None, None
-    return name, Path(p)
+def resolve_site_path(name: "str | None", path_override: "str | None") -> Path:
+    """Resolve a site path from name (registry), --path override, or CWD."""
+    if path_override:
+        return Path(path_override).resolve()
+    if name:
+        reg = load_registry()
+        if name not in reg["sites"]:
+            raise click.ClickException(
+                f"Site '{name}' not found. Use 'mdcms view' to list registered sites."
+            )
+        return Path(reg["sites"][name]["path"])
+    return Path.cwd()
 
 
-# ─── Frontmatter parser ──────────────────────────────────────
+# ─── Config reading ───────────────────────────────────────────
 
-def parse_frontmatter(filepath):
-    """Return (meta_dict, body_text). Meta is a flat key:value map."""
+def read_config(site_path: Path) -> dict:
+    config_file = site_path / "config.yml"
+    if not config_file.exists():
+        return {}
     try:
-        content = Path(filepath).read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError) as e:
-        print(f"  Warning: could not read {filepath}: {e}")
-        return None, ""
+        text = config_file.read_text(encoding="utf-8")
+        return yaml.safe_load(text) or {}
+    except (OSError, yaml.YAMLError):
+        return {}
 
+
+def get_category_info(cfg: dict) -> dict:
+    use = str(cfg.get("categories-use", "no")).lower() in ("yes", "true")
+    default_cat = cfg.get("default-category") or {}
+    default_code = default_cat.get("code") if isinstance(default_cat, dict) else None
+    cats = cfg.get("categories") or []
+    codes = [c["code"] for c in cats if isinstance(c, dict) and "code" in c]
+    return {"use": use, "default_code": default_code, "codes": codes}
+
+
+# ─── Frontmatter parsing ─────────────────────────────────────
+
+def parse_frontmatter(filepath: Path) -> "tuple[dict, str]":
+    try:
+        content = filepath.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return {}, ""
     match = re.match(r"^---\s*\n(.*?)\n---\s*\n", content, re.DOTALL)
     if not match:
         return {}, content
-
-    meta = {}
-    for line in match.group(1).split("\n"):
-        line = line.strip()
-        if not line or line.startswith("#"):
-            continue
-        colon = line.find(":")
-        if colon == -1:
-            continue
-        key = line[:colon].strip()
-        value = line[colon + 1:].strip()
-        if (value.startswith('"') and value.endswith('"')) or \
-           (value.startswith("'") and value.endswith("'")):
-            value = value[1:-1]
-        if value.lower() == "true":
-            value = True
-        elif value.lower() == "false":
-            value = False
-        elif re.match(r"^\d+$", value):
-            value = int(value)
-        meta[key] = value
-
+    try:
+        meta = yaml.safe_load(match.group(1)) or {}
+    except yaml.YAMLError:
+        meta = {}
     return meta, content[match.end():]
 
 
 # ─── Scanner ─────────────────────────────────────────────────
 
-CATEGORY_CODE_RE = re.compile(r"^[a-zA-Z0-9\-]+$")
-
-
-def parse_config_categories(text):
-    """Extract category info from config.yml.
-
-    Returns {'use': bool, 'default_code': str|None, 'codes': [str, ...]}.
-    Only looks at `categories-use`, `default-category.code`, and `categories[].code`.
-    The `code` field must be the first key of each category item (per spec example).
-    """
-    use = False
-    default_code = None
-    codes = []
-    in_default = False
-    in_categories = False
-
-    for raw in text.splitlines():
-        line = raw.rstrip()
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        if not line.startswith(" "):
-            in_default = False
-            in_categories = False
-            if line.startswith("categories-use:"):
-                val = line.split(":", 1)[1].strip().strip('"\'')
-                use = val.lower() in ("yes", "true")
-            elif line.rstrip(":") == "default-category":
-                in_default = True
-            elif line.rstrip(":") == "categories":
-                in_categories = True
-            continue
-        if in_default and line.startswith("  ") and not line.startswith("    "):
-            m = re.match(r"^  (\S+):\s*(.*)$", line)
-            if m and m.group(1) == "code":
-                default_code = m.group(2).strip().strip('"\'')
-        if in_categories and line.startswith("  - "):
-            m = re.match(r"^  - (\S+):\s*(.*)$", line)
-            if m and m.group(1) == "code":
-                codes.append(m.group(2).strip().strip('"\''))
-
-    return {"use": use, "default_code": default_code, "codes": codes}
-
-
-def identify_variant(path_rel, known_codes):
-    """Split a .md path into (base_without_ext, category_code_or_None).
-
-    `base_without_ext` includes the directory and base name but no extension
-    and no category suffix. `known_codes` is the set of valid category codes
-    (default + additional). A trailing `.<code>` in the filename is only
-    recognised as a category suffix if `<code>` is in `known_codes`.
-    """
-    if not path_rel.endswith(".md"):
+def identify_variant(rel: str, known_codes: set) -> "tuple[str | None, str | None]":
+    if not rel.endswith(".md"):
         return None, None
-    stem = path_rel[:-3]
+    stem = rel[:-3]
     base_name = os.path.basename(stem)
     if "." in base_name:
         head, _, suffix = stem.rpartition(".")
@@ -176,30 +142,31 @@ def identify_variant(path_rel, known_codes):
     return stem, None
 
 
-def scan_and_categorize(directory, known_codes):
-    """Scan a directory for .md files. Each returned record includes `base` and
-    `code` (`None` for files without a category suffix)."""
+def scan_and_categorize(directory: Path, site_root: Path, known_codes: set) -> list:
     records = []
-    if not os.path.isdir(directory):
+    if not directory.is_dir():
         return records
     for root, dirs, files in os.walk(directory):
         dirs.sort()
         for name in sorted(files):
             if not name.endswith(".md"):
                 continue
-            full = os.path.join(root, name)
-            rel = os.path.relpath(full, ".").replace("\\", "/")
+            full = Path(root) / name
+            rel = str(full.relative_to(site_root)).replace("\\", "/")
             base, code = identify_variant(rel, known_codes)
             if base is None:
                 continue
             meta, body = parse_frontmatter(full)
-            if meta is None or meta.get("draft", False):
+            if meta.get("draft", False):
                 continue
             records.append({
                 "file": rel,
                 "base": base,
                 "code": code,
-                "title": meta.get("title") or os.path.basename(base).replace("_", " ").replace("-", " ").title(),
+                "title": (
+                    meta.get("title")
+                    or Path(base).name.replace("_", " ").replace("-", " ").title()
+                ),
                 "sort": meta.get("sort"),
                 "section-id": meta.get("section-id"),
                 "author": meta.get("author"),
@@ -215,47 +182,24 @@ def scan_and_categorize(directory, known_codes):
     return records
 
 
-def group_by_base(records):
-    """Group records by their conceptual base path. Returns {base: {code: record}}."""
-    groups = {}
+def group_by_base(records: list) -> dict:
+    groups: dict = {}
     for r in records:
         groups.setdefault(r["base"], {})[r["code"]] = r
     return groups
 
 
-def select_primary(variants_dict, default_code):
-    """Pick a representative record for a page group.
-
-    Priority: default-coded variant → base file → first available.
-    """
-    if default_code and default_code in variants_dict:
-        return variants_dict[default_code]
-    if None in variants_dict:
-        return variants_dict[None]
-    return next(iter(variants_dict.values()))
+def select_primary(variants: dict, default_code: "str | None") -> dict:
+    if default_code and default_code in variants:
+        return variants[default_code]
+    if None in variants:
+        return variants[None]
+    return next(iter(variants.values()))
 
 
-def _coerce(v):
-    """Coerce a YAML scalar string to a Python value."""
-    if v == "" or v.lower() in ("null", "~"):
-        return None
-    if v == "true":
-        return True
-    if v == "false":
-        return False
-    if (v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'")):
-        return v[1:-1]
-    if re.match(r"^-?\d+$", v):
-        return int(v)
-    m = re.match(r"^\[(.*)\]$", v)
-    if m:
-        inner = m.group(1).strip()
-        return [_coerce(x.strip()) for x in inner.split(",")] if inner else []
-    return v
+# ─── Nav / search generators ─────────────────────────────────
 
-
-def _emit_value(v):
-    """Quote a YAML scalar if it contains characters that would confuse the parser."""
+def _emit_value(v) -> str:
     if v is None:
         return ""
     s = str(v)
@@ -264,93 +208,9 @@ def _emit_value(v):
     return s
 
 
-def parse_nav_yml(text):
-    """Parse the nav.yml subset we emit. Returns (sections, pages) as lists of dicts.
-
-    Handles:
-      - top-level keys `sections:` and `pages:`
-      - list items at 2-space indent: `  - key: value`
-      - item properties at 4-space indent: `    key: value`
-      - one level of nested dict at 6-space indent (for `categorynames`)
-    Ignores unknown top-level keys. Not a general YAML parser.
-    """
-    sections, pages = [], []
-    block = None
-    item = None
-    nested_key = None
-
-    def flush():
-        nonlocal item
-        if item is None:
-            return
-        if block == "sections":
-            sections.append(item)
-        elif block == "pages":
-            pages.append(item)
-        item = None
-
-    for raw in text.splitlines():
-        line = raw.rstrip()
-        stripped = line.lstrip()
-        if not stripped or stripped.startswith("#"):
-            continue
-
-        # Top-level key
-        if not line.startswith(" "):
-            flush()
-            key = line.split(":", 1)[0].strip()
-            block = key if key in ("sections", "pages") else None
-            nested_key = None
-            continue
-
-        if block is None:
-            continue
-
-        # 6-space nested dict content
-        m = re.match(r"^      (\S[^:]*):\s*(.*)$", line)
-        if m and nested_key is not None and item is not None:
-            item.setdefault(nested_key, {})[m.group(1).strip()] = _coerce(m.group(2).strip())
-            continue
-
-        # 2-space list item start
-        m = re.match(r"^  - (\S[^:]*):\s*(.*)$", line)
-        if m:
-            flush()
-            item = {m.group(1).strip(): _coerce(m.group(2).strip())}
-            nested_key = None
-            continue
-
-        if item is None:
-            continue
-
-        # 4-space item property
-        m = re.match(r"^    (\S[^:]*):\s*(.*)$", line)
-        if m:
-            key = m.group(1).strip()
-            val = m.group(2).strip()
-            if val == "":
-                nested_key = key
-                item[key] = {}
-            else:
-                nested_key = None
-                item[key] = _coerce(val)
-
-    flush()
-    return sections, pages
-
-
-# ─── Section merge (phase 2) ─────────────────────────────────
-
-def merge_sections(page_entries, existing_sections):
-    """Merge existing sections with auto-created stubs for new section-ids.
-
-    Returns (merged_sections, auto_created_codes).
-    Preserves every field on existing sections; only adds new entries.
-    """
+def merge_sections(page_entries: list, existing_sections: list) -> "tuple[list, list]":
     by_code = {s["code"]: dict(s) for s in existing_sections if s.get("code")}
-
     referenced = sorted({p.get("section-id") for p in page_entries if p.get("section-id")})
-
     auto_created = []
     for code in referenced:
         if code in by_code:
@@ -366,65 +226,47 @@ def merge_sections(page_entries, existing_sections):
             "pagesvisibility": "visible",
         }
         auto_created.append(code)
-
     merged = sorted(by_code.values(), key=lambda s: (s.get("sort") or 999, s["code"]))
     return merged, auto_created
 
 
-def build_page_nav(page_groups, existing_pages, categories_use=False, default_code=None):
-    """Produce the page nav list. One entry per conceptual page (grouped by base).
-
-    When `categories_use`, adds `variants` (list of category codes with an
-    actual file on disk — the base file counts as the default category) and
-    `titles` (per-category titles). Preserves nav.yml `sort` when the file
-    path matches.
-    """
+def build_page_nav(
+    page_groups: dict,
+    existing_pages: list,
+    categories_use: bool = False,
+    default_code: "str | None" = None,
+) -> list:
     existing_by_file = {p["file"]: p for p in existing_pages if p.get("file")}
     out = []
     for base, variants in sorted(page_groups.items()):
         file = base + ".md"
         primary = select_primary(variants, default_code)
-
         existing = existing_by_file.get(file, {})
-        sort = existing.get("sort")
-        if sort is None:
-            sort = primary.get("sort")
-        if sort is None:
-            sort = 100
-
-        entry = {
+        sort = existing.get("sort") or primary.get("sort") or 100
+        entry: dict = {
             "file": file,
             "title": primary.get("title", ""),
             "section-id": primary.get("section-id"),
             "sort": sort,
         }
-
         if categories_use:
-            covered = set()
-            titles = {}
+            covered = {}
             for code, record in variants.items():
                 key = code if code is not None else default_code
-                if key is None:
-                    continue
-                covered.add(key)
-                titles[key] = record.get("title", "")
-            entry["variants"] = sorted(covered)
-            entry["titles"] = titles
-
+                if key:
+                    covered[key] = record.get("title", "")
+            entry["variants"] = sorted(covered.keys())
+            entry["titles"] = covered
         out.append(entry)
     out.sort(key=lambda p: (p["sort"], p["file"]))
     return out
 
 
-# ─── Generators ──────────────────────────────────────────────
-
-def generate_nav_yml(sections, pages, categories_use=False):
-    """Emit nav.yml with `sections:` and `pages:` blocks."""
+def generate_nav_yml(sections: list, pages: list, categories_use: bool = False) -> str:
     lines = [
-        "# nav.yml — generated by mdcms.py",
+        "# nav.yml — generated by mdcms",
         "# Manual edits to section metadata (defaultname, sort, parent, parent-sort,",
-        "# pagesvisibility, categorynames) are preserved on rebuild. New sections",
-        "# are auto-created from page frontmatter section-id values.",
+        "# pagesvisibility, categorynames) are preserved on rebuild.",
         "",
         "sections:",
     ]
@@ -466,14 +308,15 @@ def generate_nav_yml(sections, pages, categories_use=False):
     return "\n".join(lines)
 
 
-def generate_search_json(records, categories_use=False, default_code=None):
-    """Emit search.json. When `categories_use`, each entry gets a `category` field
-    and the `file` is the conceptual base path (so search results link to the
-    same URL regardless of which variant matched)."""
+def generate_search_json(
+    records: list,
+    categories_use: bool = False,
+    default_code: "str | None" = None,
+) -> str:
     out = []
     for r in records:
         file_path = (r["base"] + ".md") if "base" in r else r.get("file", "")
-        entry = {
+        entry: dict = {
             "file": file_path,
             "title": r.get("title", ""),
             "section-id": r.get("section-id"),
@@ -492,864 +335,317 @@ def generate_search_json(records, categories_use=False, default_code=None):
     return json.dumps(out, indent=2, ensure_ascii=False)
 
 
-# ─── Banner ──────────────────────────────────────────────────
+# ─── Core build logic ─────────────────────────────────────────
 
-def load_banner():
-    try:
-        req = urllib.request.Request(BANNER_URL, headers={"User-Agent": f"mdcms/{VERSION}"})
-        with urllib.request.urlopen(req, timeout=3) as r:
-            return r.read().decode("utf-8").strip()
-    except Exception:
-        return None
+def run_build(site_path: Path):
+    """Scan pages/ and posts/, write nav.yml and search.json. Raises ClickException on failure."""
+    if not site_path.is_dir():
+        raise click.ClickException(f"Directory not found: {site_path}")
 
+    site_version = read_site_version(site_path)
+    if site_version is None:
+        raise click.ClickException(
+            "No mdcms version marker found in config.yml. "
+            "Is this an mdcms site? Run 'mdcms register' to initialise one."
+        )
 
-# ─── UI helpers ──────────────────────────────────────────────
+    status, msg = version_status(site_version)
+    if status == "unsupported":
+        raise click.ClickException(f"Site version not supported: {msg}")
+    if status in ("outdated", "newer"):
+        click.echo(click.style(f"Warning: {msg}", fg="yellow"))
 
-def clear():
-    os.system("cls" if os.name == "nt" else "clear")
+    if not (site_path / "pages").is_dir():
+        raise click.ClickException("pages/ directory not found in site.")
 
+    cfg = read_config(site_path)
+    cat = get_category_info(cfg)
 
-def header():
-    print(f"MD-CMS v{VERSION} ({DATE}) (C) Kristian Benestad")
-    print("Apache 2.0 Licence")
-    print(SEP)
-
-
-def pause():
-    input("\nPress Enter to continue...")
-
-
-# ─── Build actions (options 3 & 4) ───────────────────────────
-
-def do_build_nav_and_search(project):
-    """Option 3: scan pages/ and posts/ in project/website/, write nav.yml and search.json."""
-    site = project / "website"
-    if not site.is_dir():
-        print(f"  Error: {site} not found.")
-        return
-    os.chdir(site)
-    print(f"Working directory: {site}")
-    print()
-
-    if not os.path.isdir("pages"):
-        print("  Error: pages/ folder not found.")
-        return
-
-    # Load category config from config.yml so filename parsing can recognise
-    # category suffixes. Missing / disabled = no category handling.
-    cat_cfg = {"use": False, "default_code": None, "codes": []}
-    if os.path.isfile("config.yml"):
-        try:
-            cat_cfg = parse_config_categories(Path("config.yml").read_text(encoding="utf-8"))
-        except Exception as e:
-            print(f"  Warning: could not read category config ({e}).")
-
-    # Validate codes
-    all_declared = [c for c in [cat_cfg["default_code"]] + cat_cfg["codes"] if c]
-    invalid = [c for c in all_declared if not CATEGORY_CODE_RE.match(c)]
+    all_codes = [c for c in ([cat["default_code"]] + cat["codes"]) if c]
+    invalid = [c for c in all_codes if not CATEGORY_CODE_RE.match(c)]
     if invalid:
-        print(f"  Error: invalid category code(s) {invalid}. Must match [a-zA-Z0-9-]+.")
-        return
+        raise click.ClickException(f"Invalid category code(s): {invalid}")
+    if cat["use"] and not cat["default_code"]:
+        raise click.ClickException("categories-use: yes but no default-category.code defined.")
 
-    if cat_cfg["use"] and not cat_cfg["default_code"]:
-        print("  Error: categories-use: yes but no default-category.code defined.")
-        return
+    known_codes = set(all_codes) if cat["use"] else set()
 
-    known_codes = set(all_declared) if cat_cfg["use"] else set()
-
-    # Scan
-    page_records = scan_and_categorize("pages", known_codes)
-    post_records = scan_and_categorize("posts", known_codes)
-    print(f"Scanned pages/ — {len(page_records)} file(s)")
-    print(f"Scanned posts/ — {len(post_records)} file(s)")
+    page_records = scan_and_categorize(site_path / "pages", site_path, known_codes)
+    post_records = scan_and_categorize(site_path / "posts", site_path, known_codes)
+    click.echo(f"  pages/  {len(page_records)} file(s)")
+    click.echo(f"  posts/  {len(post_records)} file(s)")
 
     page_groups = group_by_base(page_records)
 
-    # Existing nav.yml → preserve manual edits
-    existing_sections, existing_pages = [], []
-    if os.path.isfile("nav.yml"):
+    existing_sections: list = []
+    existing_pages: list = []
+    nav_file = site_path / "nav.yml"
+    if nav_file.exists():
         try:
-            existing_sections, existing_pages = parse_nav_yml(
-                Path("nav.yml").read_text(encoding="utf-8")
-            )
-        except Exception as e:
-            print(f"  Warning: could not parse existing nav.yml ({e}); starting fresh.")
+            nav_data = yaml.safe_load(nav_file.read_text(encoding="utf-8")) or {}
+            existing_sections = [s for s in (nav_data.get("sections") or []) if isinstance(s, dict)]
+            existing_pages = [p for p in (nav_data.get("pages") or []) if isinstance(p, dict)]
+        except (OSError, yaml.YAMLError) as e:
+            click.echo(click.style(f"Warning: could not parse nav.yml ({e}); starting fresh.", fg="yellow"))
 
-    # One representative record per conceptual page, for section-id discovery
-    primary_entries = [select_primary(v, cat_cfg["default_code"]) for v in page_groups.values()]
+    primary_entries = [select_primary(v, cat["default_code"]) for v in page_groups.values()]
     sections, auto_created = merge_sections(primary_entries, existing_sections)
 
     page_nav = build_page_nav(
         page_groups, existing_pages,
-        categories_use=cat_cfg["use"],
-        default_code=cat_cfg["default_code"],
+        categories_use=cat["use"],
+        default_code=cat["default_code"],
     )
 
-    Path("nav.yml").write_text(
-        generate_nav_yml(sections, page_nav, categories_use=cat_cfg["use"]),
+    nav_file.write_text(
+        generate_nav_yml(sections, page_nav, categories_use=cat["use"]),
         encoding="utf-8",
     )
-    print("Wrote nav.yml")
+    click.echo("  Wrote nav.yml")
 
-    # Filter out draft-section pages from search.
     draft_codes = {s["code"] for s in sections if s.get("pagesvisibility") == "draft"}
     live_pages = [r for r in page_records if r.get("section-id") not in draft_codes]
-    Path("search.json").write_text(
+
+    (site_path / "search.json").write_text(
         generate_search_json(
             live_pages + post_records,
-            categories_use=cat_cfg["use"],
-            default_code=cat_cfg["default_code"],
+            categories_use=cat["use"],
+            default_code=cat["default_code"],
         ),
         encoding="utf-8",
     )
-    print(f"Wrote search.json ({len(live_pages) + len(post_records)} entries)")
+    click.echo(f"  Wrote search.json ({len(live_pages) + len(post_records)} entries)")
 
     if auto_created:
-        print()
-        print(f"  Notice: {len(auto_created)} section(s) auto-created from page frontmatter:")
-        for c in auto_created:
-            print(f"      - {c}")
-        print("  Edit nav.yml to customise defaultname, sort, parent, or pagesvisibility.")
+        click.echo(click.style(
+            f"\nNotice: {len(auto_created)} section(s) auto-created: {', '.join(auto_created)}\n"
+            "Edit nav.yml to set defaultname, sort, parent, or pagesvisibility.",
+            fg="cyan",
+        ))
 
 
-def do_build_search_only(project):
-    """Option 4: regenerate search.json only."""
-    site = project / "website"
-    if not site.is_dir():
-        print(f"  Error: {site} not found.")
-        return
-    os.chdir(site)
+# ─── GitHub template download ─────────────────────────────────
 
-    cat_cfg = {"use": False, "default_code": None, "codes": []}
-    if os.path.isfile("config.yml"):
-        try:
-            cat_cfg = parse_config_categories(Path("config.yml").read_text(encoding="utf-8"))
-        except Exception:
-            pass
-    known_codes = set(c for c in [cat_cfg["default_code"]] + cat_cfg["codes"] if c) if cat_cfg["use"] else set()
-
-    page_records = scan_and_categorize("pages", known_codes)
-    post_records = scan_and_categorize("posts", known_codes)
-
-    draft_codes = set()
-    if os.path.isfile("nav.yml"):
-        try:
-            sections, _ = parse_nav_yml(Path("nav.yml").read_text(encoding="utf-8"))
-            draft_codes = {s["code"] for s in sections if s.get("pagesvisibility") == "draft"}
-        except Exception:
-            pass
-    live_pages = [r for r in page_records if r.get("section-id") not in draft_codes]
-
-    Path("search.json").write_text(
-        generate_search_json(
-            live_pages + post_records,
-            categories_use=cat_cfg["use"],
-            default_code=cat_cfg["default_code"],
-        ),
-        encoding="utf-8",
+def _github_get(url: str) -> bytes:
+    req = urllib.request.Request(
+        url,
+        headers={
+            "User-Agent": f"mdcms/{CLI_VERSION}",
+            "Accept": "application/vnd.github.v3+json",
+        },
     )
-    print(f"Wrote search.json — {len(live_pages) + len(post_records)} entries.")
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        return resp.read()
 
 
-# ─── Option 7: path management ───────────────────────────────
-
-def manage_paths():
-    while True:
-        clear()
-        header()
-        reg = load_registry()
-        print("Website paths\n")
-        if not reg["paths"]:
-            print("  (none defined)")
-        else:
-            for name, p in reg["paths"].items():
-                marker = "*" if name == reg.get("active") else " "
-                print(f"  {marker} {name}  →  {p}")
-        print()
-        print("  a  Add a path")
-        print("  s  Set active path")
-        print("  r  Remove a path")
-        print("  b  Back")
-        print()
-        choice = input("Select: ").strip().lower()
-
-        if choice == "a":
-            name = input("Name: ").strip()
-            if not name:
-                continue
-            p = input("Path to project root (containing website/ folder): ").strip()
-            if not p:
-                continue
-            path = Path(p).expanduser().resolve()
-            if not path.is_dir():
-                print(f"  Not a directory: {path}")
-                pause()
-                continue
-            if not (path / "website").is_dir():
-                print(f"  No website/ subfolder in: {path}")
-                pause()
-                continue
-            reg["paths"][name] = str(path)
-            if not reg.get("active"):
-                reg["active"] = name
-            save_registry(reg)
-            pause()
-        elif choice == "s":
-            if not reg["paths"]:
-                pause()
-                continue
-            name = input("Name to activate: ").strip()
-            if name in reg["paths"]:
-                reg["active"] = name
-                save_registry(reg)
-            else:
-                print("  Not found.")
-                pause()
-        elif choice == "r":
-            if not reg["paths"]:
-                pause()
-                continue
-            name = input("Name to remove: ").strip()
-            if name in reg["paths"]:
-                del reg["paths"][name]
-                if reg.get("active") == name:
-                    reg["active"] = next(iter(reg["paths"]), None)
-                save_registry(reg)
-            else:
-                print("  Not found.")
-                pause()
-        elif choice == "b":
-            return
+def _download_tree(api_url: str, dest: Path, depth: int = 0):
+    items = json.loads(_github_get(api_url).decode("utf-8"))
+    for item in items:
+        item_dest = dest / item["name"]
+        if item["type"] == "dir":
+            item_dest.mkdir(parents=True, exist_ok=True)
+            _download_tree(item["url"], item_dest, depth + 1)
+        elif item["type"] == "file":
+            click.echo(f"  {'  ' * depth}{item['name']}")
+            item_dest.parent.mkdir(parents=True, exist_ok=True)
+            item_dest.write_bytes(_github_get(item["download_url"]))
 
 
-# ─── Option 8: webserver ─────────────────────────────────────
-
-def start_webserver(project):
-    port = 8800
-    site = project / "website"
-    if not site.is_dir():
-        print(f"\n  Error: {site} not found.")
-        return
-    os.chdir(site)
-    print(f"\nStarting python3 -m http.server {port} in {site}")
-    print("Press Ctrl+C to stop.\n")
+def download_template(dest: Path):
+    click.echo(f"Downloading site template into {dest} ...")
     try:
-        proc = subprocess.Popen([sys.executable, "-m", "http.server", str(port)])
-        time.sleep(0.8)
-        webbrowser.open(f"http://localhost:{port}/")
-        proc.wait()
-    except KeyboardInterrupt:
-        proc.terminate()
-        print("\nStopped.")
+        _download_tree(GITHUB_CONTENTS_API, dest)
+        click.echo(click.style("Template downloaded successfully.", fg="green"))
+    except urllib.error.URLError as e:
+        raise click.ClickException(f"Download failed: {e}")
 
 
-# ─── Option 9 & 10 ───────────────────────────────────────────
+# ─── CLI commands ─────────────────────────────────────────────
 
-def online_help():
-    print(f"Opening {HELP_URL} ...")
-    webbrowser.open(HELP_URL)
-    pause()
+@click.group()
+@click.version_option(CLI_VERSION, prog_name="mdcms")
+def cli():
+    """MD-CMS — Markdown-based CMS companion CLI.
 
-
-def about():
-    clear()
-    header()
-    print("MD-CMS is a lightweight Markdown-based CMS by Kristian Benestad.")
-    print()
-    print(f"  Docs:     https://docs.benestad.net")
-    print(f"  Repo:     https://github.com/kbenestad/mdcms")
-    print()
-    print("Licensed under the Apache License, Version 2.0.")
-    print("  https://www.apache.org/licenses/LICENSE-2.0")
-    pause()
-
-
-# ─── Validation ──────────────────────────────────────────────
-
-def _read_file(path):
-    """Read a file, returning (text, error). On failure text is None."""
-    try:
-        return Path(path).read_text(encoding="utf-8"), None
-    except OSError as e:
-        return None, str(e)
-
-
-def validate_config(site):
-    """Check config.yml for missing or invalid values.
-
-    Returns a list of dicts: {'field': ..., 'issue': ..., 'current': ...}.
+    Manage and build MD-CMS sites locally or in CI/CD pipelines.
     """
-    path = site / "config.yml"
-    text, err = _read_file(path)
-    if text is None:
-        return [{"field": "config.yml", "issue": f"Cannot read file: {err}", "current": None}]
-
-    issues = []
-
-    # Simple key extraction from the raw text (reuses our non-YAML parser style)
-    def get_top(key):
-        for line in text.splitlines():
-            if line.startswith(key + ":"):
-                return line.split(":", 1)[1].strip().strip('"\'')
-        return None
-
-    # sitename
-    sn = get_top("sitename")
-    if not sn:
-        issues.append({"field": "sitename", "issue": "Missing site name", "current": sn})
-
-    # navigation
-    nav = get_top("navigation")
-    if nav and nav not in ("sidebar", "topbar"):
-        issues.append({"field": "navigation", "issue": f"Must be 'sidebar' or 'topbar'", "current": nav})
-
-    # category validation
-    cat_cfg = parse_config_categories(text)
-    if cat_cfg["use"]:
-        if not cat_cfg["default_code"]:
-            issues.append({"field": "default-category.code",
-                           "issue": "categories-use: yes but no default category code defined",
-                           "current": None})
-        if not cat_cfg["codes"]:
-            issues.append({"field": "categories",
-                           "issue": "categories-use: yes but no additional categories defined",
-                           "current": None})
-
-        # Validate all codes
-        all_codes = [c for c in [cat_cfg["default_code"]] + cat_cfg["codes"] if c]
-        for code in all_codes:
-            if not CATEGORY_CODE_RE.match(code):
-                issues.append({"field": f"category code '{code}'",
-                               "issue": "Must match [a-zA-Z0-9-]+",
-                               "current": code})
-
-        # Check for duplicate codes
-        seen = set()
-        for code in all_codes:
-            if code in seen:
-                issues.append({"field": f"category code '{code}'",
-                               "issue": "Duplicate category code",
-                               "current": code})
-            seen.add(code)
-
-    return issues
 
 
-def validate_nav(site):
-    """Check nav.yml for missing or invalid values.
+@cli.command()
+@click.argument("name")
+@click.argument("path", required=False, default=None, type=click.Path())
+def register(name, path):
+    """Register a site by NAME at PATH (default: current directory).
 
-    Returns a list of dicts: {'field': ..., 'issue': ..., 'current': ...}.
+    If no mdcms site is found at the target path, the starter template is
+    downloaded from GitHub automatically.
     """
-    path = site / "nav.yml"
-    text, err = _read_file(path)
-    if text is None:
-        return [{"field": "nav.yml", "issue": f"Cannot read file: {err}", "current": None}]
+    reg = load_registry()
 
-    try:
-        sections, pages = parse_nav_yml(text)
-    except Exception as e:
-        return [{"field": "nav.yml", "issue": f"Parse error: {e}", "current": None}]
-
-    issues = []
-
-    # Load category config to check categorynames
-    config_text, _ = _read_file(site / "config.yml")
-    cat_cfg = parse_config_categories(config_text) if config_text else {"use": False, "default_code": None, "codes": []}
-    sectionnames_mode = None
-    if config_text:
-        for line in config_text.splitlines():
-            if line.startswith("categories-sectionnames:"):
-                sectionnames_mode = line.split(":", 1)[1].strip().strip('"\'')
-
-    all_codes = [c for c in [cat_cfg["default_code"]] + cat_cfg["codes"] if c]
-
-    # Section checks
-    section_codes = set()
-    for i, s in enumerate(sections):
-        label = f"sections[{i}]"
-        if not s.get("code"):
-            issues.append({"field": f"{label}.code", "issue": "Missing section code", "current": None})
-        else:
-            section_codes.add(s["code"])
-        if not s.get("defaultname"):
-            issues.append({"field": f"{label}.defaultname",
-                           "issue": f"Missing default name for section '{s.get('code', '?')}'",
-                           "current": None})
-        pv = s.get("pagesvisibility", "visible")
-        if pv not in ("visible", "hidden", "draft"):
-            issues.append({"field": f"{label}.pagesvisibility",
-                           "issue": f"Must be visible, hidden, or draft",
-                           "current": pv})
-        if s.get("parent") and s.get("parent-sort") is None:
-            issues.append({"field": f"{label}.parent-sort",
-                           "issue": f"parent is set but parent-sort is missing",
-                           "current": None})
-
-        # categorynames check
-        if cat_cfg["use"] and sectionnames_mode == "per-category":
-            cn = s.get("categorynames") or {}
-            for code in all_codes:
-                if code not in cn:
-                    issues.append({"field": f"{label}.categorynames.{code}",
-                                   "issue": f"Missing category name for '{code}' in section '{s.get('code', '?')}'",
-                                   "current": None})
-
-    # Page checks
-    for i, p in enumerate(pages):
-        label = f"pages[{i}]"
-        if not p.get("file"):
-            issues.append({"field": f"{label}.file", "issue": "Missing file path", "current": None})
-        if not p.get("title"):
-            issues.append({"field": f"{label}.title",
-                           "issue": f"Missing title for '{p.get('file', '?')}'",
-                           "current": None})
-        sid = p.get("section-id")
-        if sid and sid not in section_codes:
-            issues.append({"field": f"{label}.section-id",
-                           "issue": f"Section-id '{sid}' not defined in sections",
-                           "current": sid})
-
-    return issues
-
-
-def _print_issues(issues, label):
-    """Print validation issues in a readable format."""
-    if not issues:
-        print(f"\n  {label}: no issues found.")
-        return
-    print(f"\n  {label}: {len(issues)} issue(s):\n")
-    for iss in issues:
-        cur = f" (current: {iss['current']})" if iss["current"] is not None else ""
-        print(f"    • {iss['field']}: {iss['issue']}{cur}")
-
-
-# ─── Option 1: Prepare for upload ───────────────────────────
-
-def do_prepare_for_upload(project):
-    """Validate config + nav, build search.json, create zip."""
-    site = project / "website"
-    if not site.is_dir():
-        print(f"\n  Error: {site} not found.")
-        return
-
-    print()
-
-    # Step 1: Validate config.yml
-    config_issues = validate_config(site)
-    _print_issues(config_issues, "config.yml")
-
-    # Step 2: Validate nav.yml
-    nav_issues = validate_nav(site)
-    _print_issues(nav_issues, "nav.yml")
-
-    total_issues = len(config_issues) + len(nav_issues)
-    if total_issues > 0:
-        print()
-        fix = input(f"  {total_issues} issue(s) found. Continue anyway? (y/n): ").strip().lower()
-        if fix != "y":
-            print("  Aborted.")
-            return
-
-    # Step 3: Build search.json
-    print()
-    try:
-        do_build_search_only(project)
-    except Exception as e:
-        print(f"  Error building search.json: {e}")
-        return
-
-    # Step 4: Create zip
-    print()
-    cwd = Path.cwd()
-    default_dest = cwd / "website.zip"
-    dest_input = input(f"  Zip destination [{default_dest}]: ").strip()
-    dest = Path(dest_input) if dest_input else default_dest
-    dest = dest.expanduser().resolve()
-
-    # Ensure parent directory exists
-    dest.parent.mkdir(parents=True, exist_ok=True)
-
-    try:
-        count = 0
-        with zipfile.ZipFile(dest, "w", zipfile.ZIP_DEFLATED) as zf:
-            for root, dirs, files in os.walk(site):
-                dirs.sort()
-                for name in sorted(files):
-                    full = Path(root) / name
-                    arcname = full.relative_to(site)
-                    zf.write(full, arcname)
-                    count += 1
-        print(f"\n  Created {dest} ({count} files)")
-    except OSError as e:
-        print(f"\n  Error creating zip: {e}")
-
-
-# ─── Option 2: Build from scratch ───────────────────────────
-
-def do_build_from_scratch(project):
-    """Interactive wizard to create config.yml, folder structure, and home.md."""
-    site = project / "website"
-
-    print("\n  Build from scratch wizard\n")
-
-    # Check for existing config
-    if (site / "config.yml").exists():
-        overwrite = input("  config.yml already exists. Overwrite? (y/n): ").strip().lower()
-        if overwrite != "y":
-            print("  Aborted.")
-            return
-
-    # Gather settings
-    sitename = input("  Site name: ").strip() or "My Site"
-
-    nav_choice = ""
-    while nav_choice not in ("sidebar", "topbar"):
-        nav_choice = input("  Navigation layout (sidebar/topbar) [sidebar]: ").strip().lower() or "sidebar"
-
-    nav_pos = "left"
-    if nav_choice == "sidebar":
-        while nav_pos not in ("left", "right"):
-            nav_pos = input("  Navigation position (left/right) [left]: ").strip().lower() or "left"
-
-    search_choice = input("  Enable search? (yes/no) [yes]: ").strip().lower() or "yes"
-    search_on = search_choice in ("yes", "y", "true")
-
-    # Categories
-    use_categories = input("  Use categories? (yes/no) [no]: ").strip().lower()
-    use_categories = use_categories in ("yes", "y")
-
-    cat_block = ""
-    if use_categories:
-        default_code = input("  Default category code (e.g. en): ").strip() or "en"
-        default_name = input(f"  Default category display name [{default_code}]: ").strip() or default_code
-        select_text = input("  Category selector label [Select language]: ").strip() or "Select language"
-
-        extra_cats = []
-        print("  Add additional categories (leave code blank to finish):")
-        while True:
-            code = input("    Code: ").strip()
-            if not code:
-                break
-            if not CATEGORY_CODE_RE.match(code):
-                print(f"    Invalid code '{code}'. Must match [a-zA-Z0-9-]+.")
-                continue
-            name = input(f"    Display name [{code}]: ").strip() or code
-            direction = input(f"    Direction (ltr/rtl) [ltr]: ").strip().lower() or "ltr"
-            extra_cats.append({"code": code, "name": name, "direction": direction})
-
-        if not extra_cats:
-            print("  No additional categories added — disabling categories.")
-            use_categories = False
-        else:
-            cat_block = f"""
-# ─── Category settings ───────────────────────────
-categories-use: yes
-categories-sectionnames: same
-categories-selecttext: "{select_text}"
-
-# ─── Default category ────────────────────────────
-default-category:
-  code: {default_code}
-  name: {default_name}
-  direction: ltr
-  message: "Read in {default_name}"
-
-# ─── Additional categories ───────────────────────
-categories:
-"""
-            for c in extra_cats:
-                cat_block += f"""  - code: {c['code']}
-    name: {c['name']}
-    direction: {c['direction']}
-    message: "{c['name']}"
-    notfoundmessage: "Not available in {c['name']}"
-"""
-
-    # Create folder structure
-    for d in ["pages", "posts", "assets/fonts", "assets/images"]:
-        (site / d).mkdir(parents=True, exist_ok=True)
-
-    # Write config.yml
-    config_text = f"""# ─── Site settings ───────────────────────────────
-sitename: {sitename}
-navigation: {nav_choice}
-{"nav-position: " + nav_pos if nav_choice == "sidebar" else ""}
-search: {"true" if search_on else "false"}
-{cat_block}
-# ─── Appearance ──────────────────────────────────
-light:
-  bg: "#ededed"
-  bg-nav: "#ffffff"
-  font-colour: "#1a1a1a"
-  accent: "#29307d"
-  accent-hover: "#f9ad18"
-
-dark:
-  bg: "#14171c"
-  bg-nav: "#1a1e25"
-  font-colour: "#d4d4d4"
-  accent: "#7b83d4"
-  accent-hover: "#f9ad18"
-"""
-    (site / "config.yml").write_text(config_text, encoding="utf-8")
-    print(f"\n  Wrote config.yml")
-
-    # Write home.md if it doesn't exist
-    home = site / "pages" / "home.md"
-    if not home.exists():
-        home.write_text(
-            f"---\ntitle: Home\nsort: 100\n---\n\n# Welcome to {sitename}\n\n"
-            "This is the default landing page.\n",
-            encoding="utf-8",
+    if name in reg["sites"]:
+        raise click.ClickException(
+            f"'{name}' is already registered. Use 'mdcms delete {name}' to remove it first."
         )
-        print("  Created pages/home.md")
 
-    # Create .gitkeep files in empty dirs
-    for d in ["posts", "assets/fonts", "assets/images"]:
-        gk = site / d / ".gitkeep"
-        if not gk.exists() and not any((site / d).iterdir()):
-            gk.write_text("", encoding="utf-8")
+    site_path = Path(path).resolve() if path else Path.cwd()
 
-    # Run option 3 to generate nav.yml + search.json
-    print()
-    try:
-        do_build_nav_and_search(project)
-    except Exception as e:
-        print(f"  Error during build: {e}")
+    if not site_path.is_dir():
+        raise click.ClickException(f"Directory not found: {site_path}")
 
+    # Warn if path is already registered under a different name
+    for existing_name, info in reg["sites"].items():
+        if Path(info["path"]).resolve() == site_path:
+            click.echo(click.style(
+                f"Warning: this path is already registered as '{existing_name}'.",
+                fg="yellow",
+            ))
 
-# ─── Option 5: Correct config.yml ───────────────────────────
+    site_version = read_site_version(site_path)
 
-def do_correct_config(project):
-    """Check config.yml for missing/invalid values and prompt to fix."""
-    site = project / "website"
-    config_path = site / "config.yml"
-
-    issues = validate_config(site)
-    _print_issues(issues, "config.yml")
-
-    if not issues:
-        return
-
-    fix = input("\n  Fix interactively? (y/n): ").strip().lower()
-    if fix != "y":
-        return
-
-    text, err = _read_file(config_path)
-    if text is None:
-        print(f"  Cannot read config.yml: {err}")
-        return
-
-    lines = text.splitlines()
-
-    for iss in issues:
-        field = iss["field"]
-        print(f"\n  Issue: {field} — {iss['issue']}")
-
-        if field == "sitename":
-            val = input("  Enter site name: ").strip()
-            if val:
-                # Find and replace or append
-                replaced = False
-                for i, ln in enumerate(lines):
-                    if ln.startswith("sitename:"):
-                        lines[i] = f"sitename: {val}"
-                        replaced = True
-                        break
-                if not replaced:
-                    lines.insert(0, f"sitename: {val}")
-                print(f"    Set sitename to: {val}")
-
-        elif field == "navigation":
-            val = ""
-            while val not in ("sidebar", "topbar"):
-                val = input("  Navigation (sidebar/topbar): ").strip().lower()
-            for i, ln in enumerate(lines):
-                if ln.startswith("navigation:"):
-                    lines[i] = f"navigation: {val}"
-                    break
-
-        elif "category code" in field and "Invalid" in iss.get("issue", ""):
-            print("    Please edit config.yml manually to fix category codes.")
-
-        else:
-            print("    Please edit config.yml manually to fix this issue.")
-
-    # Write back
-    config_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
-    print("\n  Saved config.yml")
-
-
-# ─── Option 6: Correct nav.yml ─────────────────────────────
-
-def do_correct_nav(project):
-    """Check nav.yml for missing/invalid values and prompt to fix."""
-    site = project / "website"
-    nav_path = site / "nav.yml"
-
-    issues = validate_nav(site)
-    _print_issues(issues, "nav.yml")
-
-    if not issues:
-        return
-
-    # For missing categorynames, offer to auto-fill from defaultname
-    text, err = _read_file(nav_path)
-    if text is None:
-        print(f"  Cannot read nav.yml: {err}")
-        return
-
-    try:
-        sections, pages = parse_nav_yml(text)
-    except Exception as e:
-        print(f"  Cannot parse nav.yml: {e}")
-        return
-
-    # Separate auto-fixable (missing categorynames) from manual fixes
-    catname_issues = [i for i in issues if ".categorynames." in i["field"]]
-    other_issues = [i for i in issues if ".categorynames." not in i["field"]]
-
-    if other_issues:
-        print("\n  The following issues require manual editing of nav.yml:")
-        for iss in other_issues:
-            print(f"    • {iss['field']}: {iss['issue']}")
-
-    if catname_issues:
-        print(f"\n  {len(catname_issues)} missing category name(s) found.")
-        fill = input("  Auto-fill missing categorynames from defaultname? (y/n): ").strip().lower()
-        if fill == "y":
-            # Load category codes
-            config_text, _ = _read_file(site / "config.yml")
-            cat_cfg = parse_config_categories(config_text) if config_text else {"use": False, "default_code": None, "codes": []}
-            all_codes = [c for c in [cat_cfg["default_code"]] + cat_cfg["codes"] if c]
-
-            for s in sections:
-                cn = s.get("categorynames") or {}
-                changed = False
-                for code in all_codes:
-                    if code not in cn:
-                        cn[code] = s.get("defaultname", s.get("code", ""))
-                        changed = True
-                if changed:
-                    s["categorynames"] = cn
-
-            # Regenerate nav.yml
-            config_text2, _ = _read_file(site / "config.yml")
-            cat_use = False
-            if config_text2:
-                cat_use = parse_config_categories(config_text2)["use"]
-
-            nav_path.write_text(
-                generate_nav_yml(sections, pages, categories_use=cat_use),
-                encoding="utf-8",
+    if site_version is None:
+        click.echo(f"No mdcms site found at {site_path}.")
+        download_template(site_path)
+        site_version = read_site_version(site_path)
+        if site_version is None:
+            raise click.ClickException(
+                "Downloaded template but could not read version marker. Please check config.yml."
             )
-            print("  Saved nav.yml with auto-filled category names.")
-            print("  Edit nav.yml to provide correct translations.")
+
+    status, msg = version_status(site_version)
+    if status == "unsupported":
+        raise click.ClickException(f"Site version not supported: {msg}")
+    if status in ("outdated", "newer"):
+        click.echo(click.style(f"Warning: {msg}", fg="yellow"))
+
+    reg["sites"][name] = {"path": str(site_path), "version": site_version}
+    save_registry(reg)
+    click.echo(click.style(f"Registered '{name}' → {site_path}", fg="green"))
 
 
-# ─── Sections-sitemap (§2.3) ────────────────────────────────
-# Note: sections-sitemap is not yet implemented. Section headings
-# remain non-clickable in the renderer.
+@cli.command("delete")
+@click.argument("name")
+def delete_site(name):
+    """Remove a registered site. Does not delete any files."""
+    reg = load_registry()
+    if name not in reg["sites"]:
+        raise click.ClickException(f"Site '{name}' not found.")
+
+    info = reg["sites"][name]
+    click.echo(f"Site: {name}")
+    click.echo(f"Path: {info['path']}")
+    click.confirm("\nRemove this registration? (Site files will not be deleted.)", abort=True)
+
+    del reg["sites"][name]
+    save_registry(reg)
+    click.echo(click.style(f"Removed '{name}'.", fg="green"))
 
 
-# ─── Main menu ───────────────────────────────────────────────
+@cli.command()
+@click.argument("name", required=False)
+def view(name):
+    """List all registered sites, or show details for NAME."""
+    reg = load_registry()
 
-def main_menu():
-    while True:
-        clear()
-        header()
-        banner = load_banner()
-        if banner:
-            print(banner)
-            print()
-        name, website = active_path()
-        if name:
-            print(f"WEBSITE: {name}  ({website})")
-        else:
-            print("WEBSITE: (none — select in option 7)")
-        print()
-        print("  1  Prepare for upload")
-        print("  2  Build config.yml and nav.yml from scratch")
-        print("  3  Build nav.yml and search.json (new pages/sections)")
-        print("  4  Build search.json (updated pages only)")
-        print("  5  Correct missing values in config.yml")
-        print("  6  Correct missing values in nav.yml")
-        print("  7  Define website path")
-        print("  8  Start python webserver")
-        print("  9  Online help")
-        print(" 10  About MD-CMS")
-        print()
-        print(SEP)
-        choice = input("Select option (q to quit): ").strip().lower()
-
-        if choice == "q":
+    if not name:
+        if not reg["sites"]:
+            click.echo("No sites registered. Use 'mdcms register <name> [path]'.")
             return
-        if choice == "7":
-            manage_paths()
-            continue
-        if choice == "10":
-            about()
-            continue
-        if choice == "9":
-            online_help()
-            continue
+        click.echo(f"{'NAME':<20} {'VERSION':<12} {'STATUS':<12} PATH")
+        click.echo("─" * 72)
+        for site_name, info in sorted(reg["sites"].items()):
+            site_path = Path(info["path"])
+            site_version = read_site_version(site_path)
+            if site_version is None:
+                ver_str = "?"
+                status_label = click.style("no marker", fg="red")
+            else:
+                status, _ = version_status(site_version)
+                ver_str = f"v{site_version}"
+                if status == "unsupported":
+                    status_label = click.style("unsupported", fg="red")
+                elif status == "outdated":
+                    status_label = click.style("outdated", fg="yellow")
+                elif status == "newer":
+                    status_label = click.style("site newer", fg="cyan")
+                else:
+                    status_label = click.style("current", fg="green")
+            click.echo(f"{site_name:<20} {ver_str:<12} {status_label:<12} {info['path']}")
+        return
 
-        # Options 1-6 and 8 require an active website path
-        if choice in {"1", "2", "3", "4", "5", "6", "8"}:
-            if not website:
-                print("\n  No active website path. Use option 7 first.")
-                pause()
-                continue
-            if not (website / "website").is_dir() and choice != "2":
-                print(f"\n  Error: {website / 'website'} not found.")
-                pause()
-                continue
+    if name not in reg["sites"]:
+        raise click.ClickException(f"Site '{name}' not found.")
 
-        if choice == "1":
-            try:
-                do_prepare_for_upload(website)
-            except Exception as e:
-                print(f"\n  Error: {e}")
-            pause()
-        elif choice == "2":
-            try:
-                do_build_from_scratch(website)
-            except Exception as e:
-                print(f"\n  Error: {e}")
-            pause()
-        elif choice == "3":
-            try:
-                do_build_nav_and_search(website)
-            except Exception as e:
-                print(f"\n  Error: {e}")
-            pause()
-        elif choice == "4":
-            try:
-                do_build_search_only(website)
-            except Exception as e:
-                print(f"\n  Error: {e}")
-            pause()
-        elif choice == "5":
-            try:
-                do_correct_config(website)
-            except Exception as e:
-                print(f"\n  Error: {e}")
-            pause()
-        elif choice == "6":
-            try:
-                do_correct_nav(website)
-            except Exception as e:
-                print(f"\n  Error: {e}")
-            pause()
-        elif choice == "8":
-            start_webserver(website)
+    info = reg["sites"][name]
+    site_path = Path(info["path"])
+    cfg = read_config(site_path)
+    cat = get_category_info(cfg)
+    site_version = read_site_version(site_path)
 
+    if site_version:
+        _, ver_display = version_status(site_version)
+    else:
+        ver_display = "unknown (no version marker in config.yml)"
+
+    pages_dir = site_path / "pages"
+    posts_dir = site_path / "posts"
+    page_count = sum(1 for _ in pages_dir.rglob("*.md")) if pages_dir.is_dir() else 0
+    post_count = sum(1 for _ in posts_dir.rglob("*.md")) if posts_dir.is_dir() else 0
+
+    sections = []
+    nav_file = site_path / "nav.yml"
+    if nav_file.exists():
+        try:
+            nav_data = yaml.safe_load(nav_file.read_text(encoding="utf-8")) or {}
+            sections = [
+                s.get("code", "?")
+                for s in (nav_data.get("sections") or [])
+                if isinstance(s, dict)
+            ]
+        except (OSError, yaml.YAMLError):
+            pass
+
+    click.echo(f"Site:        {name}")
+    click.echo(f"Path:        {site_path}")
+    click.echo(f"Version:     {ver_display}")
+    click.echo(f"Site name:   {cfg.get('sitename', '(not set)')}")
+    click.echo(f"Navigation:  {cfg.get('navigation', '(not set)')}")
+    click.echo(f"Pages:       {page_count}")
+    click.echo(f"Posts:       {post_count}")
+    if cat["use"]:
+        all_codes = [cat["default_code"]] + cat["codes"]
+        click.echo(f"Categories:  enabled — {', '.join(c for c in all_codes if c)}")
+    else:
+        click.echo("Categories:  disabled")
+    click.echo(f"Sections:    {', '.join(sections) if sections else '(none)'}")
+
+
+@cli.command()
+@click.argument("name", required=False)
+@click.option(
+    "--path", "path_override",
+    type=click.Path(),
+    default=None,
+    help="Path to site root. Overrides NAME and current directory. Use this in CI/CD.",
+)
+def build(name, path_override):
+    """Build nav.yml and search.json for a site.
+
+    \b
+    Examples:
+      mdcms build mysite          # registered site by name
+      mdcms build --path ./site   # explicit path (no registry needed)
+      mdcms build                 # uses current directory (ideal for GitHub Actions)
+    """
+    site_path = resolve_site_path(name, path_override)
+    click.echo(f"Building: {site_path}")
+    run_build(site_path)
+    click.echo(click.style("Build complete.", fg="green"))
+
+
+# ─── Entry point ─────────────────────────────────────────────
 
 def main():
-    try:
-        main_menu()
-    except KeyboardInterrupt:
-        print()
+    cli()
 
 
 if __name__ == "__main__":
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..b042193
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.backends.legacy:build"
+
+[project]
+name = "mdcms"
+version = "0.3.0"
+description = "MD-CMS — Markdown-based CMS companion CLI"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Kristian Benestad" }]
+requires-python = ">=3.9"
+dependencies = [
+    "click>=8.0",
+    "PyYAML>=6.0",
+]
+
+[project.scripts]
+mdcms = "mdcms:main"
+
+[project.urls]
+Homepage = "https://github.com/kbenestad/mdcms"
+Documentation = "https://docs.benestad.net"
+
+[tool.setuptools]
+py-modules = ["mdcms"]

From a1cc0874aa7b968acbc0f95c7d708a95df2bb96a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 8 May 2026 16:17:43 +0000
Subject: [PATCH 3/8] Add release workflow for cross-platform binary builds

Triggered on version tags (v*). Builds standalone binaries via PyInstaller
on Linux/macOS/Windows runners, wraps the Linux binary in a .deb via fpm,
and attaches all artifacts to a GitHub release.

https://claude.ai/code/session_01MqEqGhP1guGx5VuFsLaws2
---
 .github/workflows/release.yml | 116 ++++++++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 .github/workflows/release.yml

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..83249f9
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,116 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build — ${{ matrix.label }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            label: Linux amd64
+            binary_name: mdcms
+            artifact_name: mdcms-linux-amd64
+            make_deb: true
+
+          - os: macos-latest
+            label: macOS arm64
+            binary_name: mdcms
+            artifact_name: mdcms-macos-arm64
+            make_deb: false
+
+          - os: windows-latest
+            label: Windows amd64
+            binary_name: mdcms.exe
+            artifact_name: mdcms-windows-amd64
+            make_deb: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install pyinstaller click pyyaml
+
+      - name: Build binary
+        run: pyinstaller --onefile --name mdcms mdcms.py
+
+      - name: Rename binary (non-Windows)
+        if: matrix.os != 'windows-latest'
+        run: mv dist/mdcms dist/${{ matrix.artifact_name }}
+
+      - name: Rename binary (Windows)
+        if: matrix.os == 'windows-latest'
+        run: mv dist/mdcms.exe dist/${{ matrix.artifact_name }}.exe
+
+      - name: Build .deb (Linux only)
+        if: matrix.make_deb
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          gem install fpm --no-document
+          fpm \
+            -s dir -t deb \
+            -n mdcms \
+            -v "$VERSION" \
+            --description "MD-CMS companion CLI — manage and build MD-CMS sites" \
+            --url "https://github.com/kbenestad/mdcms" \
+            --maintainer "Kristian Benestad" \
+            --license "Apache-2.0" \
+            --architecture amd64 \
+            --category utils \
+            dist/mdcms-linux-amd64=/usr/local/bin/mdcms
+
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact_name }}
+          path: |
+            dist/${{ matrix.artifact_name }}
+            dist/${{ matrix.artifact_name }}.exe
+          if-no-files-found: ignore
+
+      - name: Upload .deb artifact
+        if: matrix.make_deb
+        uses: actions/upload-artifact@v4
+        with:
+          name: deb-package
+          path: "*.deb"
+
+  release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: false
+
+      - name: List artifacts
+        run: find artifacts -type f
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: mdcms ${{ github.ref_name }}
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-') }}
+          generate_release_notes: true
+          files: |
+            artifacts/mdcms-linux-amd64/mdcms-linux-amd64
+            artifacts/mdcms-macos-arm64/mdcms-macos-arm64
+            artifacts/mdcms-windows-amd64/mdcms-windows-amd64.exe
+            artifacts/deb-package/*.deb

From 48b52d74e09a32fd43bff463c6c932900387059d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 8 May 2026 16:21:28 +0000
Subject: [PATCH 4/8] Replace softprops/action-gh-release with official gh CLI

https://claude.ai/code/session_01MqEqGhP1guGx5VuFsLaws2
---
 .github/workflows/release.yml | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 83249f9..c4bb53d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -103,14 +103,19 @@ jobs:
         run: find artifacts -type f
 
       - name: Create release
-        uses: softprops/action-gh-release@v2
-        with:
-          name: mdcms ${{ github.ref_name }}
-          draft: false
-          prerelease: ${{ contains(github.ref_name, '-') }}
-          generate_release_notes: true
-          files: |
-            artifacts/mdcms-linux-amd64/mdcms-linux-amd64
-            artifacts/mdcms-macos-arm64/mdcms-macos-arm64
-            artifacts/mdcms-windows-amd64/mdcms-windows-amd64.exe
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          PRERELEASE=""
+          if [[ "${{ github.ref_name }}" == *"-"* ]]; then
+            PRERELEASE="--prerelease"
+          fi
+          gh release create "${{ github.ref_name }}" \
+            --repo "${{ github.repository }}" \
+            --title "mdcms ${{ github.ref_name }}" \
+            --generate-notes \
+            $PRERELEASE \
+            artifacts/mdcms-linux-amd64/mdcms-linux-amd64 \
+            artifacts/mdcms-macos-arm64/mdcms-macos-arm64 \
+            artifacts/mdcms-windows-amd64/mdcms-windows-amd64.exe \
             artifacts/deb-package/*.deb

From bd3001c74e434ec07f471eaa6282cc8c45348a8c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 8 May 2026 16:22:42 +0000
Subject: [PATCH 5/8] Rename resources/ to docs/

https://claude.ai/code/session_01MqEqGhP1guGx5VuFsLaws2
---
 {resources => docs}/banner/v0.1.txt     | 0
 {resources => docs}/banner/v0.2.1.txt   | 0
 {resources => docs}/banner/v0.2.2.txt   | 0
 {resources => docs}/banner/v0.2.txt     | 0
 {resources => docs}/documentation.md    | 0
 {resources => docs}/knownlimitations.md | 0
 {resources => docs}/quickstart.md       | 0
 7 files changed, 0 insertions(+), 0 deletions(-)
 rename {resources => docs}/banner/v0.1.txt (100%)
 rename {resources => docs}/banner/v0.2.1.txt (100%)
 rename {resources => docs}/banner/v0.2.2.txt (100%)
 rename {resources => docs}/banner/v0.2.txt (100%)
 rename {resources => docs}/documentation.md (100%)
 rename {resources => docs}/knownlimitations.md (100%)
 rename {resources => docs}/quickstart.md (100%)

diff --git a/resources/banner/v0.1.txt b/docs/banner/v0.1.txt
similarity index 100%
rename from resources/banner/v0.1.txt
rename to docs/banner/v0.1.txt
diff --git a/resources/banner/v0.2.1.txt b/docs/banner/v0.2.1.txt
similarity index 100%
rename from resources/banner/v0.2.1.txt
rename to docs/banner/v0.2.1.txt
diff --git a/resources/banner/v0.2.2.txt b/docs/banner/v0.2.2.txt
similarity index 100%
rename from resources/banner/v0.2.2.txt
rename to docs/banner/v0.2.2.txt
diff --git a/resources/banner/v0.2.txt b/docs/banner/v0.2.txt
similarity index 100%
rename from resources/banner/v0.2.txt
rename to docs/banner/v0.2.txt
diff --git a/resources/documentation.md b/docs/documentation.md
similarity index 100%
rename from resources/documentation.md
rename to docs/documentation.md
diff --git a/resources/knownlimitations.md b/docs/knownlimitations.md
similarity index 100%
rename from resources/knownlimitations.md
rename to docs/knownlimitations.md
diff --git a/resources/quickstart.md b/docs/quickstart.md
similarity index 100%
rename from resources/quickstart.md
rename to docs/quickstart.md

From 8a253e420e63d34a2a8a1246c9761b6b8ecee207 Mon Sep 17 00:00:00 2001
From: kbenestad <kristian@benestad.net>
Date: Fri, 8 May 2026 23:30:05 +0700
Subject: [PATCH 6/8] Revise CLAUDE.md for project updates and clarity

Updated project documentation for MD-CMS, including changes to the CLI tool description, repository layout, and version markers. Adjusted folder names and clarified local preview instructions.
---
 CLAUDE.md | 125 +++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 91 insertions(+), 34 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 285f61f..8014c48 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,55 +6,92 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 MD-CMS is a markdown-based static site system with two distinct parts:
 
-1. **`mdcms.py`** — a zero-dependency Python 3 CLI tool (standard library only). It scans content, generates `nav.yml` and `search.json`, validates config, and packages a zip for deployment.
-2. **`website/index.html`** — a single-file browser renderer that reads markdown, config, and nav at runtime entirely client-side. There is no build pipeline, no compilation, no server.
+1. **`mdcms.py`** — a Python 3 CLI tool (`click` + `PyYAML`). Manages a registry of sites, scans content, generates `nav.yml` and `search.json`, and is designed for both local use and GitHub Actions pipelines.
+2. **`app/index.html`** — a single-file browser renderer that reads markdown, config, and nav at runtime entirely client-side. There is no build pipeline, no compilation, no server.
 
-The `website/` folder is the deployable artifact. `mdcms.py` lives outside it.
+The `app/` folder is the deployable artifact and the starter template downloaded when registering a new site. `mdcms.py` lives outside it.
 
-## Running the CLI
+## Repository layout
 
-```bash
-python3 mdcms.py
+```
+mdcms.py                        ← CLI tool
+pyproject.toml                  ← packaging (entry point, dependencies)
+app/
+  index.html                    ← renderer + v0.3 version marker
+  config.yml                    ← starter config + v0.3 version marker
+  nav.yml                       ← generated
+  search.json                   ← generated
+  pages/
+  posts/
+  assets/
+docs/
+  banner/
+  documentation.md
+  knownlimitations.md
+  quickstart.md
+.github/workflows/release.yml   ← cross-platform release builds
+samplesite/                     ← reference implementation (not deployed)
 ```
 
-This opens an interactive menu. Key options:
+## CLI commands
 
-| Option | Action |
-|--------|--------|
-| 1 | Validate config + nav, rebuild search.json, export `website.zip` |
-| 2 | Interactive wizard to create `config.yml` and folder structure from scratch |
-| 3 | Scan `pages/` and `posts/`, write `nav.yml` and `search.json` |
-| 4 | Rebuild `search.json` only (faster, for content-only updates) |
-| 5 | Check and interactively fix `config.yml` issues |
-| 6 | Check and interactively fix `nav.yml` issues |
-| 7 | Register/switch website paths (stored in `~/.mdcms/paths.json`) |
-| 8 | Start `python3 -m http.server 8800` and open browser |
+Install: `pip install mdcms` / `pipx install mdcms` — or use the standalone binary from a GitHub release.
 
-**Local preview:** Always use option 8 (or run `python3 -m http.server 8800` in `website/`) rather than opening `index.html` directly — browsers block local file access due to CORS.
+During development, run directly: `python3 mdcms.py <command>`
+
+| Command | Description |
+|---|---|
+| `mdcms register <name> [path]` | Register a site. Downloads starter template from GitHub if no mdcms site is found at the path. Defaults to current directory. |
+| `mdcms delete <name>` | Remove a site from the registry. Does not delete files. Prompts for confirmation. |
+| `mdcms view` | List all registered sites with version and status. |
+| `mdcms view <name>` | Show details: path, version, sitename, pages/posts count, sections, categories. |
+| `mdcms build <name>` | Build `nav.yml` and `search.json` for a registered site. |
+| `mdcms build --path <path>` | Build using an explicit path — no registry needed. Intended for CI/CD. |
+| `mdcms build` | Build using current working directory. Simplest form for GitHub Actions. |
+
+**Local preview:** Run `python3 -m http.server 8800` in the site directory and open `http://localhost:8800`. Do not open `index.html` directly — browsers block local file access due to CORS.
 
 ## Architecture of `mdcms.py`
 
-The file is a single-module Python script with these logical layers, in order:
+Single-module Python script. Logical layers in order:
 
-1. **Path registry** — `~/.mdcms/paths.json` stores named project paths. `active_path()` returns the currently selected project.
-2. **Frontmatter parser** (`parse_frontmatter`) — reads `---` YAML blocks with a hand-rolled parser (no PyYAML). Returns a flat `{key: value}` dict with type coercion (bool, int, quoted strings).
-3. **Category system** — category codes are parsed from `config.yml` by `parse_config_categories()`. Variant files use `basename.<code>.md` naming (e.g. `about.nb.md`). `identify_variant()` only recognises a suffix as a category code if it appears in the declared code list.
-4. **Scanner** (`scan_and_categorize`) — walks `pages/` or `posts/`, skips drafts (`draft: true` in frontmatter), returns records including first 5000 chars of body for search indexing.
-5. **Nav/search generators** — `generate_nav_yml()` and `generate_search_json()` produce the output files. `parse_nav_yml()` is a hand-rolled parser for reading back nav.yml (not a general YAML parser — only handles the exact format it emits).
-6. **Validators** (`validate_config`, `validate_nav`) — return lists of `{field, issue, current}` dicts for display; used in options 1, 5, and 6.
-7. **Menu actions** (`do_*` functions) — one per menu option, called by `main_menu()`.
+1. **Version helpers** — `read_site_version()` reads the `mdcms v0.3` marker from the first line of `config.yml`. `version_status()` classifies sites as `ok`, `outdated`, `newer`, or `unsupported` against `MIN_SUPPORTED_VERSION`.
+2. **Registry** — `~/.config/mdcms/sites.json` stores `{name: {path, version}}`. `load_registry()` / `save_registry()` / `resolve_site_path()`.
+3. **Config reading** — `read_config()` reads `config.yml` with `yaml.safe_load()`. `get_category_info()` extracts category settings from the parsed dict.
+4. **Frontmatter parser** (`parse_frontmatter`) — reads `---` YAML blocks using `yaml.safe_load()`. Returns `(meta_dict, body_text)`.
+5. **Category system** — `identify_variant()` splits `.md` paths into `(base, category_code)`. A suffix is only treated as a category code if it appears in the declared code list.
+6. **Scanner** (`scan_and_categorize`) — walks a directory, skips drafts, returns records with the first 5000 chars of body for search indexing. Paths are relative to `site_root`.
+7. **Nav/search generators** — `generate_nav_yml()` emits a fixed-format YAML subset. `generate_search_json()` emits a JSON array. `merge_sections()` preserves existing section metadata on rebuild.
+8. **Core build** (`run_build`) — orchestrates the full build: version check → config read → scan → merge → write nav.yml and search.json.
+9. **Template download** (`download_template`) — fetches `app/` from GitHub via the Contents API using `urllib` (no extra dependencies). Recursively downloads files and directories.
+10. **CLI commands** (`register`, `delete`, `view`, `build`) — implemented with `click`. Entry point: `main()` → `cli()`.
 
-## Content structure inside `website/`
+## Version markers
+
+Every mdcms site has a version marker on the first line of two files:
+
+- `config.yml` line 1: `# mdcms v0.3 | DO NOT REMOVE THIS COMMENT`
+- `index.html` line 1: `<!-- mdcms v0.3 | DO NOT REMOVE THIS COMMENT -->`
+
+`register` and `build` both read the marker from `config.yml` to detect and validate the site. Sites with no marker are not recognised as mdcms sites. Sites below `MIN_SUPPORTED_VERSION` are rejected.
+
+There are two distinct version numbers:
+- **CLI version** (`CLI_VERSION` in `mdcms.py`, `version` in `pyproject.toml`) — bumped with every release.
+- **Site format version** (markers in `config.yml` and `index.html`) — only bumped when the site file format has a breaking change. Many CLI releases may share the same site format version.
+
+## Site structure
+
+The registered path points directly to the directory containing `index.html` (the site root). There is no `website/` subdirectory.
 
 ```
-website/
-  index.html          ← renderer (edit to change site behaviour)
+<site-root>/
+  index.html          ← renderer
   config.yml          ← required: sitename, navigation; rest optional
-  nav.yml             ← generated; manual edits to section metadata are preserved on rebuild
+  nav.yml             ← generated; manual edits to section metadata are preserved
   search.json         ← generated
   pages/
     home.md           ← default landing page
-    about.md          ← default variant
+    about.md
     about.nb.md       ← Norwegian variant (category suffix = nb)
   posts/
     2025-01-01-my-first-post.md
@@ -113,15 +150,35 @@ paginate: yes
 
 Reliable tags (others are known-broken): `posts-datetime-chronological-byyearmonth`, `posts-datetime-reversechronological`. Use `datetime` frontmatter (format: `YYYY-MM-DD HH:MM`) for posts — `date` alone does not work reliably.
 
+## Release workflow
+
+`.github/workflows/release.yml` triggers on version tags (`v*`). Uses a matrix of three runners:
+
+| Runner | Output |
+|---|---|
+| `ubuntu-latest` | `mdcms-linux-amd64` binary + `mdcms_<version>_amd64.deb` (via PyInstaller + fpm) |
+| `macos-latest` | `mdcms-macos-arm64` binary |
+| `windows-latest` | `mdcms-windows-amd64.exe` |
+
+All artifacts are attached to the GitHub release using `gh release create`.
+
+**Release checklist** — before tagging:
+1. Update `CLI_VERSION` in `mdcms.py`
+2. Update `version` in `pyproject.toml`
+3. Update site format markers in `app/config.yml` and `app/index.html` only if the site format changed
+
+Then: `git tag v0.3.1 && git push origin v0.3.1`
+
 ## Known limitations
 
-- `mdcms.py` always expects the deployable site in a `website/` subdirectory of the registered project path.
 - Most `posts-*` tag variants are broken. Only `posts-datetime-chronological-byyearmonth` and `posts-datetime-reversechronological` reliably work.
 - Section headings in the nav are non-clickable (sections-sitemap is not yet implemented).
 
 ## Key implementation details
 
-- `parse_nav_yml()` and `parse_config_categories()` are **not** general YAML parsers — they only handle the exact indentation/format that `mdcms.py` itself produces. Do not assume they handle arbitrary YAML.
+- `generate_nav_yml()` emits a fixed-format YAML subset. It is **not** a general YAML emitter — do not assume it handles arbitrary structures.
+- `yaml.safe_load()` is used for all YAML reading (config.yml, nav.yml, frontmatter). The nav.yml parser depends on PyYAML, not a hand-rolled parser.
 - Category code validation uses `CATEGORY_CODE_RE = re.compile(r"^[a-zA-Z0-9\-]+$")` — codes must match this.
+- `scan_and_categorize()` takes both `directory` and `site_root` — paths in records are always relative to `site_root`.
 - The `samplesite/` directory is a reference implementation with multi-language categories (English, Norwegian, Arabic including RTL). It is not deployed; it exists for reference and testing.
-- `website/` in the repo root is a minimal starter template (single page, no categories).
+- Template download uses `urllib` (stdlib) only — no `requests` dependency.

From 0d0dfa7268f9badfc10b6582caf1a8ea3827f92c Mon Sep 17 00:00:00 2001
From: kbenestad <kristian@benestad.net>
Date: Fri, 8 May 2026 23:34:06 +0700
Subject: [PATCH 7/8] Add release guide for mdcms

This guide provides detailed steps for releasing a new version of mdcms, including prerequisites, setup, version bumping, tagging, and monitoring the build process.
---
 docs/release.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 docs/release.md

diff --git a/docs/release.md b/docs/release.md
new file mode 100644
index 0000000..baceab2
--- /dev/null
+++ b/docs/release.md
@@ -0,0 +1,92 @@
+# Releasing a new version of mdcms
+
+This guide covers publishing a new mdcms release — producing binaries, a `.deb` package, and a GitHub release with all artifacts attached.
+
+## Prerequisites
+
+- Push access to `kbenestad/mdcms` on GitHub
+- GitHub Actions enabled on the repository (it is by default on new repos)
+
+## One-time GitHub setup
+
+### Enable workflow write permissions
+
+The release workflow creates a GitHub release using the built-in `GITHUB_TOKEN`. You need to confirm it has write access:
+
+1. Go to your repository on GitHub
+2. **Settings → Actions → General**
+3. Scroll to **Workflow permissions**
+4. Select **Read and write permissions**
+5. Click **Save**
+
+That's the only setup required. No secrets, no tokens, no third-party services.
+
+## The release checklist
+
+Before tagging a release, update the version number in two places:
+
+**`mdcms.py`** — find this line near the top and bump it:
+```python
+CLI_VERSION = "0.3.1"
+```
+
+**`pyproject.toml`** — bump the matching line:
+```toml
+version = "0.3.1"
+```
+
+> **Site format version** — the markers in `app/config.yml` and `app/index.html` (`# mdcms v0.3`) are separate from the CLI version. Only update them if the site file format has a breaking change that requires users to re-download the template. Most releases do not touch these.
+
+Commit the version bump:
+```bash
+git add mdcms.py pyproject.toml
+git commit -m "Bump version to 0.3.1"
+git push origin main
+```
+
+## Tagging the release
+
+Push a version tag to trigger the workflow:
+```bash
+git tag v0.3.1
+git push origin v0.3.1
+```
+
+The tag must start with `v`. The workflow triggers immediately.
+
+> **Pre-releases** — if the tag contains a hyphen (e.g. `v0.4.0-beta.1`), the GitHub release is automatically marked as pre-release.
+
+## What the workflow does
+
+The workflow (`.github/workflows/release.yml`) runs three parallel jobs:
+
+| Runner | Output |
+|---|---|
+| `ubuntu-latest` | `mdcms-linux-amd64` (standalone binary) + `mdcms_0.3.1_amd64.deb` |
+| `macos-latest` | `mdcms-macos-arm64` (standalone binary) |
+| `windows-latest` | `mdcms-windows-amd64.exe` |
+
+Each binary is built with PyInstaller — Python is bundled inside, so end users need nothing pre-installed. The `.deb` is built with `fpm` and installs mdcms to `/usr/local/bin`.
+
+A final job collects all artifacts and creates the GitHub release with auto-generated release notes.
+
+## Monitoring the build
+
+1. Go to **Actions** on the repository
+2. Click the workflow run triggered by your tag
+3. Each platform job takes roughly 3–5 minutes
+
+If a job fails, the release is not created. Fix the issue, delete the tag, and re-push:
+```bash
+git tag -d v0.3.1
+git push origin --delete v0.3.1
+# fix the issue, then re-tag
+git tag v0.3.1
+git push origin v0.3.1
+```
+
+## The finished release
+
+Once all jobs pass, the release appears under **Releases** on the repository with:
+- Auto-generated changelog (commits since the last tag)
+- All four artifacts attached for download

From 01341db24bb700fb90eff63318a72d7b2590de6b Mon Sep 17 00:00:00 2001
From: kbenestad <kristian@benestad.net>
Date: Fri, 8 May 2026 23:34:34 +0700
Subject: [PATCH 8/8] Add installation and setup guide for mdcms

This guide details the installation of mdcms, site registration, local builds, and GitHub Actions setup for automatic updates.
---
 docs/install.md | 161 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100644 docs/install.md

diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 0000000..294ccf6
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,161 @@
+# Setting up mdcms for your site
+
+This guide walks through installing mdcms, registering your site, and setting up automatic builds on GitHub so that `nav.yml` and `search.json` are always up to date when you push content.
+
+## 1. Install mdcms
+
+Choose one method:
+
+**Standalone binary (no Python required — recommended for most users)**
+
+Download the binary for your platform from the [latest release](https://github.com/kbenestad/mdcms/releases/latest):
+
+- **Linux:** `mdcms-linux-amd64` → move to `/usr/local/bin/mdcms` and `chmod +x`
+- **Linux (deb):** `mdcms_<version>_amd64.deb` → `sudo dpkg -i mdcms_<version>_amd64.deb`
+- **macOS:** `mdcms-macos-arm64` → move to `/usr/local/bin/mdcms` and `chmod +x`
+- **Windows:** `mdcms-windows-amd64.exe` → rename to `mdcms.exe` and place it somewhere on your PATH
+
+**Via pipx (Python users)**
+```bash
+pipx install mdcms
+```
+
+Verify the installation:
+```bash
+mdcms --version
+```
+
+---
+
+## 2. Register your site
+
+Navigate to your site directory (where `index.html` lives) and register it:
+
+```bash
+cd /path/to/your/site
+mdcms register mysite
+```
+
+Or pass the path explicitly:
+```bash
+mdcms register mysite /path/to/your/site
+```
+
+**If no mdcms site exists at that path**, mdcms will download the starter template from GitHub automatically — `index.html`, `config.yml`, `pages/`, `posts/`, and `assets/` will be created for you.
+
+**If a site already exists** (you cloned an existing mdcms repo), mdcms will detect the version marker in `config.yml` and register it as-is.
+
+---
+
+## 3. Edit your config
+
+Open `config.yml` in your site directory and set at minimum:
+
+```yaml
+sitename: Your Site Name
+navigation: topbar    # or: sidebar
+```
+
+---
+
+## 4. Build locally
+
+Run a build to generate `nav.yml` and `search.json` from your content:
+
+```bash
+mdcms build mysite
+```
+
+Check your site by starting a local server:
+```bash
+cd /path/to/your/site
+python3 -m http.server 8800
+```
+
+Then open `http://localhost:8800` in your browser.
+
+---
+
+## 5. Set up automatic builds on GitHub
+
+When you push new pages or posts to GitHub, you'll want `nav.yml` and `search.json` rebuilt automatically. This is done with a simple GitHub Actions workflow.
+
+### One-time GitHub setup
+
+1. Go to your site repository on GitHub
+2. **Settings → Actions → General**
+3. Under **Workflow permissions**, select **Read and write permissions**
+4. Click **Save**
+
+This allows the workflow to commit the rebuilt files back to your repository.
+
+### Add the workflow file
+
+Create `.github/workflows/build.yml` in your site repository with this content:
+
+```yaml
+name: Build
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "pages/**"
+      - "posts/**"
+      - "config.yml"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install mdcms
+        run: pip install mdcms
+
+      - name: Build
+        run: mdcms build
+
+      - name: Commit updated files
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add nav.yml search.json
+          git diff --staged --quiet || git commit -m "Build: update nav.yml and search.json"
+          git push
+```
+
+Commit and push this file to your repository. From that point on, every push that touches `pages/`, `posts/`, or `config.yml` will automatically rebuild and commit `nav.yml` and `search.json`.
+
+> The workflow only commits if the files actually changed — `git diff --staged --quiet` skips the commit if nothing is different.
+
+---
+
+## Day-to-day workflow
+
+1. Write or edit a page in `pages/` or a post in `posts/`
+2. Commit and push to `main`
+3. GitHub Actions rebuilds `nav.yml` and `search.json` automatically (~30 seconds)
+4. Your deployed site picks up the changes immediately
+
+To build locally at any time (without pushing):
+```bash
+mdcms build mysite
+```
+
+---
+
+## Useful commands
+
+```bash
+mdcms view                  # list all registered sites
+mdcms view mysite           # show details for a site
+mdcms build mysite          # build nav.yml + search.json
+mdcms build --path .        # build from current directory (no registry needed)
+mdcms delete mysite         # remove a site from the local registry
+```