@@ -1,36 +1,87 @@
 #!/bin/bash
 # SPDX-License-Identifier: MPL-2.0
-# Initialize wiki with standard structure for a repo
+# Initialize (seed) a repository wiki with a standard structure.
+#
+# GitHub has no REST/GraphQL API to create a wiki or its first page: the backing
+# `<repo>.wiki.git` repo is created lazily, only once a page is saved. This script
+# is the estate work-around — it enables the wiki, then seeds it over git.
+#
+# Usage:
+#   init-wiki.sh <repo>                # owner defaults to $WIKI_OWNER or "hyperpolymath"
+#   init-wiki.sh <owner>/<repo>        # explicit owner (e.g. metadatastician/paint-type)
+#
+# Auth:
+#   - If GH_TOKEN or GITHUB_TOKEN is set (CI / GitHub App installation token), the
+#     wiki remote uses HTTPS token auth. Otherwise it falls back to SSH.
+#
+# Idempotent: existing wiki pages are never overwritten — only missing pages are added.
+
+set -euo pipefail
+
+ARG="${1:-}"
+if [[ -z "$ARG" ]]; then
+    echo "Usage: $0 <repo>|<owner>/<repo>" >&2
+    exit 1
+fi
 
-REPO="${1:-}"
+# Parse owner/repo (owner optional).
+if [[ "$ARG" == */* ]]; then
+    OWNER="${ARG%%/*}"
+    REPO="${ARG##*/}"
+else
+    OWNER="${WIKI_OWNER:-hyperpolymath}"
+    REPO="$ARG"
+fi
+SLUG="$OWNER/$REPO"
 
-if [[ -z "$REPO" ]]; then
-    echo "Usage: $0 <repo-name>"
-    exit 1
+# Token-aware wiki remote (App/CI token → HTTPS; else SSH).
+TOKEN="${GH_TOKEN:-${GITHUB_TOKEN:-}}"
+if [[ -n "$TOKEN" ]]; then
+    WIKI_REMOTE="https://x-access-token:${TOKEN}@github.com/${SLUG}.wiki.git"
+else
+    WIKI_REMOTE="git@github.com:${SLUG}.wiki.git"
 fi
 
-WIKI_DIR=""$HYPATIA_TMPDIR/wiki-init-"$$"
-mkdir -p "$WIKI_DIR"
-cd "$WIKI_DIR" || exit 1
+WIKI_DIR="$(mktemp -d "${TMPDIR:-/tmp}/wiki-init-XXXXXX")"
+cleanup() { rm -rf "$WIKI_DIR"; }
+trap cleanup EXIT
+
+echo "Initializing wiki for ${SLUG}..."
+
+# Step 1 — ensure the wiki feature is enabled (no-op if already on). Without this,
+# the .wiki.git remote may not exist server-side and the push below 404s.
+if ! gh api -X PATCH "repos/${SLUG}" -F has_wiki=true >/dev/null 2>&1; then
+    echo "warning: could not confirm has_wiki=true via API (insufficient scope?); continuing" >&2
+fi
 
-echo "Initializing wiki for hyperpolymath/$REPO..."
+cd "$WIKI_DIR"
 
-# Clone wiki repo (creates if doesn't exist when you push)
-if ! git clone "git@github.com:hyperpolymath/$REPO.wiki.git" wiki 2>/dev/null; then
-    # Wiki doesn't exist yet, create it
-    mkdir wiki
+# Step 2 — clone the wiki repo; if it has never been initialized, start it locally.
+if git clone "$WIKI_REMOTE" wiki 2>/dev/null; then
     cd wiki
-    git init
-    git remote add origin "git@github.com:hyperpolymath/$REPO.wiki.git"
 else
-    cd wiki
+    echo "Wiki repo not yet initialized server-side; creating first commit locally."
+    mkdir wiki && cd wiki
+    git init -q
+    git remote add origin "$WIKI_REMOTE"
 fi
 
-# Get repo description for context
-DESCRIPTION=$(gh repo view "hyperpolymath/$REPO" --json description --jq '.description // "No description available"' 2>/dev/null)
+DESCRIPTION=$(gh repo view "$SLUG" --json description --jq '.description // "No description available"' 2>/dev/null || echo "No description available")
+
+# write_page <filename> — reads heredoc from stdin; writes only if the page is
+# absent, so re-runs never clobber human-edited wiki pages.
+write_page() {
+    local file="$1"
+    if [[ -e "$file" ]]; then
+        echo "  skip (exists): $file"
+        cat >/dev/null   # drain heredoc
+        return
+    fi
+    cat > "$file"
+    echo "  add: $file"
+}
 
-# Create Home.md
-cat > Home.md << EOF
+write_page Home.md << EOF
 # $REPO
 
 $DESCRIPTION
@@ -50,8 +101,7 @@ See the [Getting Started](Getting-Started) guide to begin using this project.
 See the [Contributing](Contributing) guide for developer information.
 EOF
 
-# Create _Sidebar.md for navigation
-cat > _Sidebar.md << EOF
+write_page _Sidebar.md << EOF
 ### $REPO Wiki
 
 **For Users**
@@ -65,14 +115,12 @@ cat > _Sidebar.md << EOF
 - [API Reference](API-Reference)
 EOF
 
-# Create _Footer.md
-cat > _Footer.md << EOF
+write_page _Footer.md << EOF
 ---
-*[View on GitHub](https://github.com/hyperpolymath/$REPO) | [Report Issue](https://github.com/hyperpolymath/$REPO/issues/new) | [Discussions](https://github.com/hyperpolymath/$REPO/discussions)*
+*[View on GitHub](https://github.com/$SLUG) | [Report Issue](https://github.com/$SLUG/issues/new) | [Discussions](https://github.com/$SLUG/discussions)*
 EOF
 
-# Create Getting-Started.md
-cat > Getting-Started.md << EOF
+write_page Getting-Started.md << EOF
 # Getting Started
 
 ## Prerequisites
@@ -95,8 +143,7 @@ See the main repository README for installation instructions.
 - Read the [Architecture](Architecture) for understanding the codebase
 EOF
 
-# Create FAQ.md
-cat > FAQ.md << EOF
+write_page FAQ.md << EOF
 # Frequently Asked Questions
 
 ## General
@@ -107,16 +154,15 @@ $DESCRIPTION
 
 ### Where can I get help?
 
-- [GitHub Discussions](https://github.com/hyperpolymath/$REPO/discussions) - Community help
-- [Issues](https://github.com/hyperpolymath/$REPO/issues) - Bug reports
+- [GitHub Discussions](https://github.com/$SLUG/discussions) - Community help
+- [Issues](https://github.com/$SLUG/issues) - Bug reports
 
 ## Troubleshooting
 
 *Add common issues and solutions here.*
 EOF
 
-# Create Architecture.md
-cat > Architecture.md << EOF
+write_page Architecture.md << EOF
 # Architecture
 
 ## Overview
@@ -136,8 +182,7 @@ See the repository for the current directory structure.
 See the project's META.scm or ADR files for architectural decisions.
 EOF
 
-# Create Contributing.md
-cat > Contributing.md << EOF
+write_page Contributing.md << EOF
 # Contributing
 
 Thank you for your interest in contributing to $REPO!
@@ -164,11 +209,10 @@ Thank you for your interest in contributing to $REPO!
 
 ## Getting Help
 
-Use [GitHub Discussions](https://github.com/hyperpolymath/$REPO/discussions) for questions.
+Use [GitHub Discussions](https://github.com/$SLUG/discussions) for questions.
 EOF
 
-# Create API-Reference.md
-cat > API-Reference.md << EOF
+write_page API-Reference.md << EOF
 # API Reference
 
 *This page documents the public API of $REPO.*
@@ -186,19 +230,34 @@ See the project source code and inline documentation for detailed API informatio
 *Document configuration options here.*
 EOF
 
-# Commit and push
+# Step 3 — commit and push. Wikis default to the `master` branch; detect the current one.
 git add -A
 if git diff --cached --quiet 2>/dev/null; then
-    echo "No changes to commit"
-else
-    git commit -m "Initialize wiki with standard structure"
-    if git push -u origin master 2>/dev/null || git push -u origin main 2>/dev/null; then
-        echo "Wiki initialized successfully for $REPO"
-    else
-        echo "Failed to push wiki for $REPO"
-    fi
+    echo "No changes to commit (wiki already seeded)."
+    exit 0
+fi
+git commit -q -m "Initialize wiki with standard structure"
+
+BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || echo master)"
+if PUSH_ERR="$(git push -u origin "$BRANCH" 2>&1)"; then
+    echo "Wiki initialized successfully for ${SLUG}."
+    exit 0
 fi
 
-# Cleanup
-cd /
-rm -rf "$WIKI_DIR"
+# Push failed — surface the real reason and the lazy-init fallback.
+echo "Failed to push wiki for ${SLUG}." >&2
+echo "$PUSH_ERR" >&2
+if echo "$PUSH_ERR" | grep -qiE 'not found|does not exist'; then
+    cat >&2 <<MSG
+
+The wiki repo has never been initialized server-side, and pushing does not create
+it on this account/repo. GitHub only creates <repo>.wiki.git after the FIRST page
+is saved through the web UI — there is no API for it (see the open feature request).
+
+Fallback: create the first page once, then re-run this script:
+  1. Open https://github.com/${SLUG}/wiki  and click "Create the first page" -> Save.
+  2. Re-run: $0 ${SLUG}
+Or drive that single UI step with the estate browser-automation agent.
+MSG
+fi
+exit 1