add DOMAIN.md file to initial commits

DOMAIN.md

@@ -0,0 +1,45 @@
+# DOMAIN.md — Git Worktree Concepts
+
+## Git Worktrees
+
+A git worktree is a linked working directory that shares the same repository but checks out a different branch. Multiple worktrees can exist simultaneously, each on its own branch, without switching branches in any of them.
+
+### Key Commands
+
+- `git worktree list` — show all linked worktrees with paths and branches
+- `git worktree add <path> [branch]` — create a new linked worktree
+- `git worktree add -b <new-branch> <path>` — create with a new branch
+- `git worktree remove <path>` — remove a linked worktree (refuses if uncommitted changes)
+- `git worktree prune` — clean up stale entries for deleted worktrees
+
+### Terminology
+
+| Term | Definition |
+|------|-----------|
+| **Main repo** | The original repository directory (where `.git/` lives for non-bare repos) |
+| **Linked worktree** | An additional working directory linked to the same repo via `git worktree add` |
+| **Bare repo** | A `.git/` without a working tree — used as the central store when all worktrees are linked |
+| **Detached HEAD** | When a worktree checks out a commit directly instead of a branch |
+
+### Constraints (from git itself)
+
+- You cannot create a nested worktree (worktree inside a worktree).
+- Multiple worktrees on the same branch is possible with `-f` but dangerous and not recommended.
+- `git worktree remove` refuses if there are uncommitted or untracked changes.
+- The main repo counts as a "worktree" in `git worktree list`.
+
+## pi Session Concepts
+
+| Term | Definition |
+|------|-----------|
+| **Session** | A conversation context within pi, tied to a specific cwd/branch |
+| **Cwd change** | When pi changes its working directory (e.g., switching worktrees) |
+| **Branch display** | The footer indicator showing which git branch pi is tracking |
+| **Back-switching** | Restoring the previous session when returning to the main repo from a worktree |
+
+### How Sessions Relate to Worktrees
+
+- Each worktree can have its own session for focused context.
+- Switching worktrees updates the branch display automatically (pi reads HEAD from the new cwd).
+- Users are offered a choice: create a fresh session or keep the current one.
+- Back-switching restores the session that was active before leaving the main repo.