docs: document sync hooks, gitattributes, global setup, and remotes

README.md

@@ -28,6 +28,50 @@ Then open Claude Code anywhere and say:
 
 Claude will symlink `CLAUDE.md` globally, wire up the skills, and verify the install. Takes about a minute.
 
+## This Install — What's Different
+
+This repo is a personalised fork of the Cog template, synced across machines via Gitea. Several things are set up here that aren't in the upstream template:
+
+### Auto-Sync Hooks
+
+Two hooks in `.claude/settings.json` keep memory in sync automatically when working inside `~/.cog`:
+
+| Hook | Trigger | What it does |
+|------|---------|--------------|
+| `SessionStart` | Every time Claude Code opens | `git pull --rebase --autostash` — pulls latest memory from Gitea |
+| `Stop` | Every time Claude finishes responding | Commits any changed memory files and pushes to Gitea |
+
+The Stop hook is a no-op if nothing changed. The SessionStart hook stashes any local edits, pulls, then reapplies them — so it won't stomp in-progress work.
+
+### Conflict-Safe Merges
+
+`.gitattributes` sets `merge=union` on append-only observation files:
+
+```
+memory/**/observations.md merge=union
+memory/cog-meta/self-observations.md merge=union
+```
+
+If two machines both append observations on the same day, git merges them as a union (keeps both) instead of raising a conflict.
+
+### Global CLAUDE.md
+
+`~/.claude/CLAUDE.md` is a symlink to `/home/artanis/.cog/CLAUDE.md`. This makes Cog's instructions and memory active in every Claude Code session, regardless of working directory. Skills are similarly symlinked from `~/.cog/.claude/commands/` into `~/.claude/commands/`.
+
+The `CLAUDE.md` includes an explicit base path declaration so memory reads resolve correctly from any working directory:
+> **Base path**: `/home/artanis/.cog/` — all `memory/` references resolve relative to this directory.
+
+### Git Remotes
+
+| Remote | URL | Purpose |
+|--------|-----|---------|
+| `origin` | `https://gitea.bunny-wyvern.ts.net/artanis/Cog-Sync.git` | Personal sync — push/pull memory across machines |
+| `upstream` | `https://github.com/marciopuga/cog.git` | Original Cog template — pull framework updates when needed |
+
+To pull upstream improvements into your install: `git fetch upstream && git merge upstream/main`.
+
+---
+
 ## Quick Start (fresh install from template)
 
 Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview).