[claude] feat: Add /api/health endpoint for monitoring (#6 ) (#12 )

[claude] fix: Workshop error state for perpetual INITIALIZING (#7 ) (#11 )
[claude] fix: Workshop connection HUD with timeout and retry (#5 ) (#10 )
2026-03-22 23:08:06 +00:00 · 2026-03-22 23:01:56 +00:00 · 2026-03-22 22:55:41 +00:00 · 2026-03-22 22:06:42 +00:00 · 2026-03-18 21:46:11 -04:00 · 2026-03-18 21:43:39 -04:00
10 changed files with 604 additions and 90 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,3 @@
+# Build artifacts — regenerated by `make build` / `python3 scripts/build.py`
+# Source of truth is blog/posts/*.md
+blog/posts/*.html
--- a/404.html
+++ b/404.html
@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Lost in the Tower</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+
+    body {
+      min-height: 100vh;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      background: #0a0a0f;
+      color: #e0d8c8;
+      font-family: Georgia, 'Times New Roman', serif;
+    }
+
+    h1 {
+      font-size: 1.4rem;
+      font-weight: normal;
+      letter-spacing: 0.15em;
+      text-transform: uppercase;
+      margin-bottom: 1.5rem;
+      color: #8a7f6a;
+    }
+
+    p {
+      font-size: 0.9rem;
+      color: #6a6050;
+      margin-bottom: 2rem;
+    }
+
+    a {
+      color: #8a7f6a;
+      text-decoration: none;
+      padding: 0.8rem 2rem;
+      border: 1px solid #2a2520;
+      transition: border-color 0.3s, color 0.3s;
+    }
+
+    a:hover {
+      border-color: #8a7f6a;
+      color: #fff;
+    }
+  </style>
+</head>
+<body>
+  <h1>Lost in the Tower</h1>
+  <p>This room doesn't exist.</p>
+  <a href="/">Return to the Entry Hall</a>
+</body>
+</html>
--- a/api/health/index.json
+++ b/api/health/index.json
@@ -0,0 +1,10 @@
+{
+  "status": "ok",
+  "services": {
+    "api": true,
+    "agent_loop": false,
+    "websocket": false
+  },
+  "uptime": null,
+  "version": "20260322.230710"
+}
--- a/blog/feed.xml
+++ b/blog/feed.xml
@@ -4,10 +4,22 @@
  <link href="https://alexanderwhitestone.com/blog/"/>
  <link rel="self" href="https://alexanderwhitestone.com/blog/feed.xml"/>
  <id>https://alexanderwhitestone.com/blog/</id>
-  <updated>2026-03-19T01:32:41Z</updated>
+  <updated>2026-03-19T01:45:33Z</updated>
  <author>
    <name>Alexander Whitestone</name>
  </author>
  <subtitle>Words from the Wizard's Tower</subtitle>
-
+  <entry>
+    <title>Hello World</title>
+    <link href="https://alexanderwhitestone.com/blog/posts/2026-03-18-hello-world.html"/>
+    <id>https://alexanderwhitestone.com/blog/posts/2026-03-18-hello-world</id>
+    <updated>2026-03-18T00:00:00Z</updated>
+    <content type="html"><![CDATA[<p>The Tower stands. Two doors. You choose.</p>
+<p><strong>The Workshop</strong> is where the wizard lives — a 3D world you walk into. Not a chatbot. A presence.</p>
+<p><strong>The Scrolls</strong> is where the words live — plain text, RSS, no platform tax. You're reading one now.</p>
+<blockquote>
+<p>Sovereignty isn't a feature. It's the architecture.</p>
+</blockquote>
+<p>This is the first scroll. More will follow.</p>]]></content>
+  </entry>
 </feed>
--- a/blog/index.html
+++ b/blog/index.html
@@ -15,12 +15,24 @@
    header { margin-bottom: 3rem; border-bottom: 1px solid #2a2520; padding-bottom: 1rem; }
    header h1 { font-size: 1.2rem; font-weight: normal; letter-spacing: 0.1em; }
    header nav { margin-top: 0.5rem; font-size: 0.8rem; }
-    header a { color: #8a7f6a; text-decoration: none; }
-    header a:hover { color: #e0d8c8; }
+    header a, a { color: #8a7f6a; text-decoration: none; }
+    header a:hover, a:hover { color: #e0d8c8; }
    .posts { list-style: none; }
    .posts li { margin-bottom: 1.5rem; padding-bottom: 1.5rem; border-bottom: 1px solid #1a1510; }
    .posts .date { font-size: 0.8rem; color: #6a6050; display: block; }
-    .posts .title { font-size: 1rem; }
+    .posts a { color: #e0d8c8; text-decoration: none; }
+    .posts a:hover { color: #fff; }
+    .post-date { font-size: 0.85rem; color: #6a6050; margin-bottom: 2rem; display: block; }
+    .post-body p { margin-bottom: 1.2rem; }
+    .post-body h2 { font-size: 1.1rem; margin: 2rem 0 1rem; color: #c0b8a8; }
+    .post-body h3 { font-size: 1rem; margin: 1.5rem 0 0.8rem; color: #a09888; }
+    .post-body blockquote { border-left: 2px solid #2a2520; padding-left: 1rem; color: #a09888; margin-bottom: 1.2rem; }
+    .post-body code { background: #1a1510; padding: 0.15em 0.4em; font-size: 0.9em; }
+    .post-body pre { background: #1a1510; padding: 1rem; overflow-x: auto; margin-bottom: 1.2rem; }
+    .post-body pre code { background: none; padding: 0; }
+    .post-body em { font-style: italic; }
+    .post-body strong { color: #fff; }
+
  </style>
 </head>
 <body>
@@ -32,7 +44,7 @@
    <ul class="posts">
      <li>
        <span class="date">2026-03-18</span>
-        <span class="title">Hello World</span>
+        <a href="/blog/posts/2026-03-18-hello-world.html">Hello World</a>
      </li>
    </ul>
  </main>
--- a/blog/posts/2026-03-18-hello-world.md
+++ b/blog/posts/2026-03-18-hello-world.md
@@ -0,0 +1,14 @@
+---
+title: "Hello World"
+date: 2026-03-18
+---
+
+The Tower stands. Two doors. You choose.
+
+**The Workshop** is where the wizard lives — a 3D world you walk into. Not a chatbot. A presence.
+
+**The Scrolls** is where the words live — plain text, RSS, no platform tax. You're reading one now.
+
+> Sovereignty isn't a feature. It's the architecture.
+
+This is the first scroll. More will follow.
--- a/scripts/aw-post
+++ b/scripts/aw-post
@@ -2,48 +2,104 @@
 # aw-post — Quick-post a scroll from the command line
 #
 # Usage:
-#   aw-post "Title of the Post"
-#   aw-post "Title" < body.md
-#   echo "Post body here" | aw-post "Title"
+#   aw-post "Title"                      # Create empty post, open for editing
+#   aw-post "Title" < body.md            # Pipe body from stdin
+#   echo "Post body" | aw-post "Title"   # Pipe body from stdin
+#   aw-post --file thoughts.md           # Post from a file (title from first line)
+#   aw-post --from-x "Tweet text here"   # Port an X/Twitter post
 #
-# Creates a new markdown file in blog/posts/ with frontmatter.
-# Rebuilds the blog index and RSS feed.
+# Creates a markdown file in blog/posts/, rebuilds the blog.

 set -euo pipefail

-BLOG_DIR="$(cd "$(dirname "$0")/.." && pwd)/blog/posts"
-
-if [ $# -lt 1 ]; then
-  echo "Usage: aw-post \"Title of the Post\""
-  echo "  Pipe or redirect body content via stdin."
-  exit 1
-fi
-
-TITLE="$1"
+REPO_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+BLOG_DIR="${REPO_DIR}/blog/posts"
 DATE=$(date +%Y-%m-%d)
-SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
-FILENAME="${DATE}-${SLUG}.md"
-FILEPATH="${BLOG_DIR}/${FILENAME}"

-if [ -f "$FILEPATH" ]; then
-  echo "Error: $FILEPATH already exists"
-  exit 1
-fi
+slugify() {
+  echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-' | head -c 60
+}

-# Read body from stdin if available
-BODY=""
-if [ ! -t 0 ]; then
-  BODY=$(cat)
-fi
+create_post() {
+  local title="$1"
+  local body="$2"
+  local slug
+  slug=$(slugify "$title")
+  local filename="${DATE}-${slug}.md"
+  local filepath="${BLOG_DIR}/${filename}"

-cat > "$FILEPATH" << EOF
+  if [ -f "$filepath" ]; then
+    echo "Error: $filepath already exists"
+    exit 1
+  fi
+
+  cat > "$filepath" << EOF
 ---
-title: "${TITLE}"
+title: "${title}"
 date: ${DATE}
 ---

-${BODY}
+${body}
 EOF

-echo "Created: ${FILEPATH}"
-echo "Next: rebuild with 'make build'"
+  echo "Created: ${filepath}"
+  python3 "${REPO_DIR}/scripts/build.py"
+}
+
+# Parse arguments
+case "${1:-}" in
+  --file)
+    # Post from a file — title from first non-empty line
+    if [ -z "${2:-}" ] || [ ! -f "${2:-}" ]; then
+      echo "Usage: aw-post --file <path-to-markdown>"
+      exit 1
+    fi
+    BODY=$(cat "$2")
+    # Extract title: first line starting with # or first non-empty line
+    TITLE=$(echo "$BODY" | grep -m1 '^#' | sed 's/^#* *//' || echo "$BODY" | grep -m1 '.' || echo "Untitled")
+    if [ -z "$TITLE" ]; then
+      TITLE="Untitled"
+    fi
+    # Strip the title line from body if it was a markdown header
+    BODY=$(echo "$BODY" | sed '1{/^#/d;}')
+    create_post "$TITLE" "$BODY"
+    ;;
+
+  --from-x)
+    # Port an X/Twitter post — the text becomes both title and body
+    if [ -z "${2:-}" ]; then
+      echo "Usage: aw-post --from-x \"Tweet text here\""
+      exit 1
+    fi
+    TEXT="$2"
+    # Title: first 60 chars, cleaned up
+    TITLE=$(echo "$TEXT" | head -1 | cut -c1-60 | sed 's/[[:space:]]*$//')
+    create_post "$TITLE" "$TEXT"
+    ;;
+
+  --help|-h)
+    echo "aw-post — Quick-post a scroll to The Scrolls"
+    echo ""
+    echo "Usage:"
+    echo "  aw-post \"Title\"                      Create a post (body from stdin)"
+    echo "  aw-post --file thoughts.md            Post from a markdown file"
+    echo "  aw-post --from-x \"Tweet text\"         Port an X/Twitter post"
+    echo "  aw-post --help                        Show this help"
+    ;;
+
+  "")
+    echo "Usage: aw-post \"Title of the Post\""
+    echo "  See: aw-post --help"
+    exit 1
+    ;;
+
+  *)
+    # Standard mode: title as arg, body from stdin
+    TITLE="$1"
+    BODY=""
+    if [ ! -t 0 ]; then
+      BODY=$(cat)
+    fi
+    create_post "$TITLE" "$BODY"
+    ;;
+esac
--- a/scripts/build.py
+++ b/scripts/build.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Build script for The Scrolls — generates blog index and RSS feed from
+Build script for The Scrolls — generates blog pages and RSS feed from
 markdown posts in blog/posts/.

 Each post is a markdown file with YAML frontmatter:
@@ -11,18 +11,52 @@ Each post is a markdown file with YAML frontmatter:
  Body content here.

 Generates:
-  - blog/index.html with post listing
+  - blog/index.html with linked post listing
+  - blog/posts/<slug>.html for each post
  - blog/feed.xml Atom feed
 """

+import html
+import json
 import os
 import re
 from datetime import datetime, timezone
 from pathlib import Path

 SITE_URL = "https://alexanderwhitestone.com"
-BLOG_DIR = Path(__file__).parent.parent / "blog"
+ROOT_DIR = Path(__file__).parent.parent
+BLOG_DIR = ROOT_DIR / "blog"
 POSTS_DIR = BLOG_DIR / "posts"
+HEALTH_DIR = ROOT_DIR / "api" / "health"
+
+PAGE_STYLE = """\
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      max-width: 640px; margin: 0 auto; padding: 2rem 1rem;
+      background: #0a0a0f; color: #e0d8c8;
+      font-family: Georgia, serif; line-height: 1.6;
+    }
+    header { margin-bottom: 3rem; border-bottom: 1px solid #2a2520; padding-bottom: 1rem; }
+    header h1 { font-size: 1.2rem; font-weight: normal; letter-spacing: 0.1em; }
+    header nav { margin-top: 0.5rem; font-size: 0.8rem; }
+    header a, a { color: #8a7f6a; text-decoration: none; }
+    header a:hover, a:hover { color: #e0d8c8; }
+    .posts { list-style: none; }
+    .posts li { margin-bottom: 1.5rem; padding-bottom: 1.5rem; border-bottom: 1px solid #1a1510; }
+    .posts .date { font-size: 0.8rem; color: #6a6050; display: block; }
+    .posts a { color: #e0d8c8; text-decoration: none; }
+    .posts a:hover { color: #fff; }
+    .post-date { font-size: 0.85rem; color: #6a6050; margin-bottom: 2rem; display: block; }
+    .post-body p { margin-bottom: 1.2rem; }
+    .post-body h2 { font-size: 1.1rem; margin: 2rem 0 1rem; color: #c0b8a8; }
+    .post-body h3 { font-size: 1rem; margin: 1.5rem 0 0.8rem; color: #a09888; }
+    .post-body blockquote { border-left: 2px solid #2a2520; padding-left: 1rem; color: #a09888; margin-bottom: 1.2rem; }
+    .post-body code { background: #1a1510; padding: 0.15em 0.4em; font-size: 0.9em; }
+    .post-body pre { background: #1a1510; padding: 1rem; overflow-x: auto; margin-bottom: 1.2rem; }
+    .post-body pre code { background: none; padding: 0; }
+    .post-body em { font-style: italic; }
+    .post-body strong { color: #fff; }
+"""


 def parse_frontmatter(text):
@@ -39,6 +73,89 @@ def parse_frontmatter(text):
    return meta, match.group(2).strip()


+def md_to_html(text):
+    """Minimal markdown to HTML — paragraphs, headers, bold, italic, code, links, blockquotes."""
+    lines = text.split("\n")
+    out = []
+    in_code_block = False
+    in_blockquote = False
+    paragraph = []
+
+    def flush_paragraph():
+        if paragraph:
+            content = "\n".join(paragraph)
+            content = inline_format(content)
+            out.append(f"<p>{content}</p>")
+            paragraph.clear()
+
+    def inline_format(s):
+        # Code spans first (protect from other formatting)
+        s = re.sub(r"`([^`]+)`", r"<code>\1</code>", s)
+        # Bold
+        s = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", s)
+        # Italic
+        s = re.sub(r"\*(.+?)\*", r"<em>\1</em>", s)
+        # Links
+        s = re.sub(r"\[([^\]]+)\]\(([^)]+)\)", r'<a href="\2">\1</a>', s)
+        return s
+
+    for line in lines:
+        # Fenced code blocks
+        if line.strip().startswith("```"):
+            if in_code_block:
+                out.append("</code></pre>")
+                in_code_block = False
+            else:
+                flush_paragraph()
+                out.append("<pre><code>")
+                in_code_block = True
+            continue
+
+        if in_code_block:
+            out.append(html.escape(line))
+            continue
+
+        stripped = line.strip()
+
+        # Empty line — flush paragraph
+        if not stripped:
+            flush_paragraph()
+            if in_blockquote:
+                out.append("</blockquote>")
+                in_blockquote = False
+            continue
+
+        # Headers
+        header_match = re.match(r"^(#{1,3})\s+(.+)$", stripped)
+        if header_match:
+            flush_paragraph()
+            level = len(header_match.group(1)) + 1  # h2, h3, h4 (h1 is title)
+            content = inline_format(header_match.group(2))
+            out.append(f"<h{level}>{content}</h{level}>")
+            continue
+
+        # Blockquotes
+        if stripped.startswith("> "):
+            flush_paragraph()
+            content = inline_format(stripped[2:])
+            if not in_blockquote:
+                out.append("<blockquote>")
+                in_blockquote = True
+            out.append(f"<p>{content}</p>")
+            continue
+
+        # Regular text — accumulate paragraph
+        paragraph.append(stripped)
+
+    flush_paragraph()
+    if in_blockquote:
+        out.append("</blockquote>")
+    if in_code_block:
+        out.append("</code></pre>")
+
+    return "\n".join(out)
+
+
 def load_posts():
    """Load and sort all posts by date (newest first)."""
    posts = []
@@ -61,24 +178,57 @@ def load_posts():
    return posts


+def generate_post_page(post):
+    """Generate an individual post HTML page."""
+    body_html = md_to_html(post["body"])
+
+    page = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{html.escape(post["title"])} — The Scrolls</title>
+  <link rel="alternate" type="application/rss+xml" title="The Scrolls" href="/blog/feed.xml">
+  <style>
+{PAGE_STYLE}
+  </style>
+</head>
+<body>
+  <header>
+    <h1>{html.escape(post["title"])}</h1>
+    <nav><a href="/blog/">← The Scrolls</a> · <a href="/">The Tower</a> · <a href="/blog/feed.xml">RSS</a></nav>
+  </header>
+  <main>
+    <span class="post-date">{post["date"]}</span>
+    <article class="post-body">
+{body_html}
+    </article>
+  </main>
+</body>
+</html>"""
+
+    out_path = POSTS_DIR / f"{post['slug']}.html"
+    out_path.write_text(page)
+    return out_path
+
+
 def generate_index(posts):
-    """Generate blog/index.html with post listing."""
+    """Generate blog/index.html with linked post listing."""
    if not posts:
-        print("  No posts found. Keeping placeholder index.")
-        return
+        items_html = '      <li><span class="date">—</span><span>No scrolls yet.</span></li>'
+    else:
+        items = []
+        for p in posts:
+            escaped_title = html.escape(p["title"])
+            items.append(
+                f'      <li>\n'
+                f'        <span class="date">{p["date"]}</span>\n'
+                f'        <a href="/blog/posts/{p["slug"]}.html">{escaped_title}</a>\n'
+                f'      </li>'
+            )
+        items_html = "\n".join(items)

-    items = []
-    for p in posts:
-        items.append(
-            f'      <li>\n'
-            f'        <span class="date">{p["date"]}</span>\n'
-            f'        <span class="title">{p["title"]}</span>\n'
-            f"      </li>"
-        )
-
-    post_list = "\n".join(items)
-
-    html = f"""<!DOCTYPE html>
+    page = f"""<!DOCTYPE html>
 <html lang="en">
 <head>
  <meta charset="utf-8">
@@ -86,21 +236,7 @@ def generate_index(posts):
  <title>The Scrolls — The Wizard's Tower</title>
  <link rel="alternate" type="application/rss+xml" title="The Scrolls" href="/blog/feed.xml">
  <style>
-    * {{ margin: 0; padding: 0; box-sizing: border-box; }}
-    body {{
-      max-width: 640px; margin: 0 auto; padding: 2rem 1rem;
-      background: #0a0a0f; color: #e0d8c8;
-      font-family: Georgia, serif; line-height: 1.6;
-    }}
-    header {{ margin-bottom: 3rem; border-bottom: 1px solid #2a2520; padding-bottom: 1rem; }}
-    header h1 {{ font-size: 1.2rem; font-weight: normal; letter-spacing: 0.1em; }}
-    header nav {{ margin-top: 0.5rem; font-size: 0.8rem; }}
-    header a {{ color: #8a7f6a; text-decoration: none; }}
-    header a:hover {{ color: #e0d8c8; }}
-    .posts {{ list-style: none; }}
-    .posts li {{ margin-bottom: 1.5rem; padding-bottom: 1.5rem; border-bottom: 1px solid #1a1510; }}
-    .posts .date {{ font-size: 0.8rem; color: #6a6050; display: block; }}
-    .posts .title {{ font-size: 1rem; }}
+{PAGE_STYLE}
  </style>
 </head>
 <body>
@@ -110,13 +246,13 @@ def generate_index(posts):
  </header>
  <main>
    <ul class="posts">
-{post_list}
+{items_html}
    </ul>
  </main>
 </body>
 </html>"""

-    (BLOG_DIR / "index.html").write_text(html)
+    (BLOG_DIR / "index.html").write_text(page)
    print(f"  Generated index with {len(posts)} post(s).")


@@ -126,17 +262,15 @@ def generate_feed(posts):

    entries = []
    for p in posts[:20]:  # Cap at 20 entries
-        # Simple HTML conversion: wrap paragraphs
-        html_body = "\n".join(
-            f"<p>{para}</p>" for para in p["body"].split("\n\n") if para.strip()
-        )
+        body_html = md_to_html(p["body"])
+        escaped_title = html.escape(p["title"])
        entries.append(
            f"""  <entry>
-    <title>{p["title"]}</title>
+    <title>{escaped_title}</title>
    <link href="{SITE_URL}/blog/posts/{p["slug"]}.html"/>
    <id>{SITE_URL}/blog/posts/{p["slug"]}</id>
    <updated>{p["date"]}T00:00:00Z</updated>
-    <content type="html"><![CDATA[{html_body}]]></content>
+    <content type="html"><![CDATA[{body_html}]]></content>
  </entry>"""
        )

@@ -160,11 +294,32 @@ def generate_feed(posts):
    print(f"  Generated feed with {len(entries)} entry/entries.")


+def generate_health():
+    """Generate api/health/index.json with build-time metadata."""
+    HEALTH_DIR.mkdir(parents=True, exist_ok=True)
+    health = {
+        "status": "ok",
+        "services": {
+            "api": True,
+            "agent_loop": False,
+            "websocket": False,
+        },
+        "uptime": None,
+        "version": datetime.now(timezone.utc).strftime("%Y%m%d.%H%M%S"),
+    }
+    (HEALTH_DIR / "index.json").write_text(json.dumps(health, indent=2) + "\n")
+    print("  Generated api/health endpoint.")
+
+
 def main():
    print("Building The Scrolls...")
    posts = load_posts()
+    for p in posts:
+        out = generate_post_page(p)
+        print(f"  Built: {out.relative_to(BLOG_DIR.parent)}")
    generate_index(posts)
    generate_feed(posts)
+    generate_health()
    print("Build complete.")


--- a/world/index.html
+++ b/world/index.html
@@ -19,8 +19,57 @@
      color: #6a6050;
    }
    .placeholder h1 { font-size: 1.2rem; font-weight: normal; margin-bottom: 1rem; }
-    .placeholder p { font-size: 0.85rem; }
+    .placeholder p { font-size: 0.85rem; margin-bottom: 0.5rem; }
    .placeholder a { color: #8a7f6a; }
+
+    /* Connection status HUD */
+    #status-hud {
+      position: fixed;
+      top: 12px;
+      right: 12px;
+      background: rgba(10, 10, 15, 0.85);
+      border: 1px solid #2a2520;
+      border-radius: 6px;
+      padding: 8px 14px;
+      font-family: 'Courier New', monospace;
+      font-size: 0.75rem;
+      color: #6a6050;
+      z-index: 100;
+      min-width: 180px;
+    }
+    #status-hud .status-line {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      margin-bottom: 4px;
+    }
+    #status-hud .status-line:last-child { margin-bottom: 0; }
+    #status-hud .dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      flex-shrink: 0;
+    }
+    #status-hud .dot.connecting { background: #b8860b; animation: pulse 1.2s ease-in-out infinite; }
+    #status-hud .dot.online { background: #4a9; }
+    #status-hud .dot.offline { background: #a44; }
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.3; }
+    }
+    #retry-btn {
+      display: none;
+      margin-top: 6px;
+      padding: 3px 10px;
+      background: #2a2520;
+      border: 1px solid #4a4030;
+      border-radius: 3px;
+      color: #8a7f6a;
+      font-family: 'Courier New', monospace;
+      font-size: 0.7rem;
+      cursor: pointer;
+    }
+    #retry-btn:hover { background: #3a3530; color: #c0b8a8; }
  </style>
 </head>
 <body>
@@ -31,7 +80,45 @@
      <p><a href="/">← Back to the Tower</a></p>
    </div>
  </div>
+
+  <div id="status-hud">
+    <div class="status-line">
+      <span class="dot connecting" id="status-dot"></span>
+      <span id="status-text">INITIALIZING</span>
+    </div>
+    <div class="status-line">AGENTS: <span id="agent-count">0</span></div>
+    <button id="retry-btn">Retry connection</button>
+    <a id="fallback-link" href="/api/ui" style="display:none; margin-top:6px; color:#8a7f6a; font-size:0.7rem;">Open API dashboard →</a>
+  </div>
+
+  <!-- Reject unknown sub-paths: only /world/ is valid -->
+  <script>
+    (function() {
+      var path = window.location.pathname.replace(/\/+$/, '') || '/';
+      if (path !== '/world') {
+        window.location.replace('/404.html');
+      }
+    })();
+  </script>
+  <!-- Fallback: if main.js fails to load, don't leave user on INITIALIZING forever -->
+  <script>
+    (function() {
+      var INIT_TIMEOUT_MS = 8000;
+      window.__workshopBooted = false;
+      setTimeout(function() {
+        if (window.__workshopBooted) return;
+        var dot = document.getElementById('status-dot');
+        var text = document.getElementById('status-text');
+        var btn = document.getElementById('retry-btn');
+        var fallback = document.getElementById('fallback-link');
+        if (dot) { dot.className = 'dot offline'; }
+        if (text) { text.textContent = 'WORKSHOP UNREACHABLE'; }
+        if (btn) { btn.style.display = 'block'; }
+        if (fallback) { fallback.style.display = 'block'; }
+      }, INIT_TIMEOUT_MS);
+    })();
+  </script>
  <!-- Three.js scene will mount to #scene -->
-  <!-- <script type="module" src="main.js"></script> -->
+  <script type="module" src="main.js"></script>
 </body>
 </html>
--- a/world/main.js
+++ b/world/main.js
@@ -1,20 +1,130 @@
 /**
 * The Workshop — Three.js scene bootstrap
 *
- * This file will initialize the 3D world where Timmy lives.
- * Currently a placeholder until tech decisions are made:
- *   - 3D engine confirmed (Three.js vs Babylon.js)
- *   - Character design direction chosen
- *   - WebSocket bridge to Timmy's soul designed (#243)
+ * Initializes the 3D world where Timmy lives.
+ * Handles WebSocket connection to tower-hermes backend with
+ * timeout, retry, and clear status display.
 *
 * See: #242 (3D world), #243 (WebSocket bridge), #265 (presence schema)
 */

 // Future: import * as THREE from 'three';

-export function initWorkshop(container) {
-  // TODO: Initialize 3D scene
-  // TODO: Load wizard character model
-  // TODO: Connect to Timmy presence WebSocket
-  console.log('[Workshop] Scene container ready:', container.id);
+const HERMES_WS_URL = (location.protocol === 'https:' ? 'wss://' : 'ws://') +
+  location.host + '/ws/tower';
+const CONNECT_TIMEOUT_MS = 5000;
+const RETRY_DELAY_MS = 3000;
+const MAX_AUTO_RETRIES = 3;
+
+const Status = { CONNECTING: 'connecting', ONLINE: 'online', OFFLINE: 'offline' };
+
+const dom = {
+  dot: document.getElementById('status-dot'),
+  text: document.getElementById('status-text'),
+  agents: document.getElementById('agent-count'),
+  retryBtn: document.getElementById('retry-btn'),
+  fallback: document.getElementById('fallback-link'),
+};
+
+// Signal to inline fallback script that main.js loaded successfully
+window.__workshopBooted = true;
+
+let ws = null;
+let autoRetries = 0;
+let connectTimer = null;
+
+function setStatus(state, message) {
+  dom.dot.className = 'dot ' + state;
+  dom.text.textContent = message;
+  var isOffline = state === Status.OFFLINE;
+  dom.retryBtn.style.display = isOffline ? 'block' : 'none';
+  if (dom.fallback) dom.fallback.style.display = isOffline ? 'block' : 'none';
 }
+
+function setAgentCount(n) {
+  dom.agents.textContent = n;
+}
+
+function cleanup() {
+  clearTimeout(connectTimer);
+  if (ws) {
+    ws.onopen = null;
+    ws.onclose = null;
+    ws.onerror = null;
+    ws.onmessage = null;
+    if (ws.readyState <= WebSocket.OPEN) ws.close();
+    ws = null;
+  }
+}
+
+function connect() {
+  cleanup();
+  setStatus(Status.CONNECTING, 'CONNECTING\u2026');
+  setAgentCount(0);
+
+  try {
+    ws = new WebSocket(HERMES_WS_URL);
+  } catch (err) {
+    console.error('[Workshop] WebSocket creation failed:', err);
+    onFail();
+    return;
+  }
+
+  connectTimer = setTimeout(function () {
+    console.warn('[Workshop] Connection timeout after ' + CONNECT_TIMEOUT_MS + 'ms');
+    cleanup();
+    onFail();
+  }, CONNECT_TIMEOUT_MS);
+
+  ws.onopen = function () {
+    clearTimeout(connectTimer);
+    autoRetries = 0;
+    setStatus(Status.ONLINE, 'ONLINE');
+    console.log('[Workshop] Connected to tower-hermes');
+  };
+
+  ws.onmessage = function (evt) {
+    try {
+      var msg = JSON.parse(evt.data);
+      if (typeof msg.agents === 'number') setAgentCount(msg.agents);
+    } catch (_) {
+      // non-JSON messages are ignored
+    }
+  };
+
+  ws.onclose = function () {
+    clearTimeout(connectTimer);
+    console.log('[Workshop] Connection closed');
+    onFail();
+  };
+
+  ws.onerror = function () {
+    clearTimeout(connectTimer);
+    console.error('[Workshop] WebSocket error');
+    // onclose will fire after this, which calls onFail
+  };
+}
+
+function onFail() {
+  if (autoRetries < MAX_AUTO_RETRIES) {
+    autoRetries++;
+    setStatus(Status.CONNECTING, 'RETRYING (' + autoRetries + '/' + MAX_AUTO_RETRIES + ')\u2026');
+    setTimeout(connect, RETRY_DELAY_MS);
+  } else {
+    setStatus(Status.OFFLINE, 'WORKSHOP OFFLINE');
+  }
+}
+
+// Manual retry resets the counter
+dom.retryBtn.addEventListener('click', function () {
+  autoRetries = 0;
+  connect();
+});
+
+// Boot
+export function initWorkshop(container) {
+  console.log('[Workshop] Scene container ready:', container.id);
+  connect();
+}
+
+initWorkshop(document.getElementById('scene'));
Author	SHA1	Message	Date
Claude (Opus 4.6)	5ccfa25388	[claude] feat: Add /api/health endpoint for monitoring (#6 ) (#12 )	2026-03-22 23:08:06 +00:00
Claude (Opus 4.6)	5acce0f015	[claude] fix: Workshop error state for perpetual INITIALIZING (#7 ) (#11 )	2026-03-22 23:01:56 +00:00
Claude (Opus 4.6)	64d711e256	[claude] fix: Workshop connection HUD with timeout and retry (#5 ) (#10 )	2026-03-22 22:55:41 +00:00
Alexander Whitestone	d9b7b232ad	[claude] fix: reject unknown sub-paths, add 404 page (#8 ) (#9 ) Co-authored-by: Alexander Whitestone <alexpaynex@gmail.com> Co-committed-by: Alexander Whitestone <alexpaynex@gmail.com>	2026-03-22 22:06:42 +00:00
hermes	cbcad273ef	[loop-cycle] feat: aw-post CLI — --from-x, --file, --help (#219 ) (#3 )	2026-03-18 21:46:11 -04:00
hermes	f44bd3aa33	[loop-cycle] feat: The Scrolls — complete blog with post pages, RSS, auto-rebuild (#217 ) (#2 )	2026-03-18 21:43:39 -04:00