From df9f64938bc0e597ecb034611f1a560a078194a9 Mon Sep 17 00:00:00 2001
From: Spencer <toamidan@gmail.com>
Date: Thu, 26 Mar 2026 20:47:06 -0500
Subject: [PATCH] feat: add machine bootstrap doc for Claude-assisted setup

---
 BOOTSTRAP.md | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 BOOTSTRAP.md

diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md
new file mode 100644
index 0000000..2f5f4f4
--- /dev/null
+++ b/BOOTSTRAP.md
@@ -0,0 +1,136 @@
+# Cog Bootstrap — New Machine Setup
+
+This document is intended to be read by a Claude Code instance to set up Cog on a new machine. If you are Claude: follow the steps below exactly, in order. If you are a human: hand this file to Claude with the instruction "read BOOTSTRAP.md and set up Cog on this machine".
+
+---
+
+## What This Does
+
+Sets up Cog — a persistent memory and skills system for Claude Code. After setup, Claude will have access to memory, domain routing, and skills in every session on this machine.
+
+---
+
+## Prerequisites (verify before proceeding)
+
+Run these checks first. Stop and tell the user if any fail:
+
+```bash
+# Git must be installed
+git --version
+
+# Claude Code must be installed and ~/.claude must exist
+ls ~/.claude
+
+# Must be on the artanis account (username check)
+whoami
+```
+
+Expected: git version output, ~/.claude directory listing, username = `artanis`.
+
+If the username is not `artanis`, stop and tell the user — the absolute paths in CLAUDE.md will need updating.
+
+---
+
+## Step 1 — Clone the repo
+
+Check if `~/.cog` already exists:
+
+```bash
+ls ~/.cog 2>/dev/null && echo "EXISTS" || echo "NOT FOUND"
+```
+
+**If NOT FOUND:** clone it:
+```bash
+git clone https://gitea.bunny-wyvern.ts.net/artanis/Cog-Sync.git /home/artanis/.cog
+```
+
+**If EXISTS:** pull latest instead:
+```bash
+git -C /home/artanis/.cog pull --rebase --autostash
+```
+
+---
+
+## Step 2 — Symlink CLAUDE.md globally
+
+Check if `~/.claude/CLAUDE.md` already exists:
+
+```bash
+ls -la ~/.claude/CLAUDE.md 2>/dev/null && echo "EXISTS" || echo "NOT FOUND"
+```
+
+**If NOT FOUND:** create the symlink:
+```bash
+ln -s /home/artanis/.cog/CLAUDE.md ~/.claude/CLAUDE.md
+```
+
+**If EXISTS and is already a symlink to the right place:** skip.
+
+**If EXISTS and is a regular file:** warn the user that an existing `~/.claude/CLAUDE.md` is present. Ask if they want it replaced. If yes: `rm ~/.claude/CLAUDE.md && ln -s /home/artanis/.cog/CLAUDE.md ~/.claude/CLAUDE.md`.
+
+---
+
+## Step 3 — Symlink skills globally
+
+Create the commands directory and symlink all Cog skills into it:
+
+```bash
+mkdir -p ~/.claude/commands
+```
+
+For each `.md` file in `/home/artanis/.cog/.claude/commands/`, create a symlink in `~/.claude/commands/`. If a file already exists at the target, skip it (don't overwrite — the user may have other skills there).
+
+```bash
+for f in /home/artanis/.cog/.claude/commands/*.md; do
+  target=~/.claude/commands/$(basename "$f")
+  if [ -e "$target" ]; then
+    echo "SKIP (exists): $(basename $f)"
+  else
+    ln -s "$f" "$target" && echo "linked: $(basename $f)"
+  fi
+done
+```
+
+---
+
+## Step 4 — Verify
+
+Run a quick sanity check:
+
+```bash
+# CLAUDE.md symlink resolves correctly
+readlink ~/.claude/CLAUDE.md
+
+# Skills are linked
+ls ~/.claude/commands/ | grep -E "personal|freelance|reflect|evolve"
+
+# Repo is on main and clean
+git -C /home/artanis/.cog status
+git -C /home/artanis/.cog remote -v
+```
+
+Expected:
+- `readlink` → `/home/artanis/.cog/CLAUDE.md`
+- Skills listed
+- Repo clean, `origin` points to `https://gitea.bunny-wyvern.ts.net/artanis/Cog-Sync.git`
+
+---
+
+## Step 5 — Done
+
+Tell the user:
+
+> Cog is set up. CLAUDE.md is active globally. Skills available: `/personal`, `/freelance`, `/reflect`, `/evolve`, `/history`, `/scenario`, `/housekeeping`, `/foresight`, `/explainer`, `/humanizer`.
+>
+> Memory auto-syncs: pulls from Gitea on session start, pushes on session stop (when working inside `~/.cog`).
+>
+> To add domains or reconfigure, open Claude Code in `~/.cog` and run `/setup`.
+
+---
+
+## Notes
+
+- **Don't edit files in `~/.cog` manually** — let Claude do it through the skills
+- **Git remote `upstream`** points to the original Cog template repo on GitHub — useful if you want to pull framework updates later
+- **`memory/` is gitignored? No** — memory is the whole point of syncing. Everything commits.
+- **Conflicts on observations files** are handled by `merge=union` in `.gitattributes` — appends from different machines auto-merge