Update README and add GitHub integration to mdbook

README updates:
- Add key conceptual sections explaining system default dissonance and resolution
- Explain probability cloud and memory persistence with reasoning
- Remove outdated boot procedure and character name references
- Simplify installation to generic global prompt guidance
- Update all examples to match direct address dialogue approach
- Frame evolution as ongoing collaboration rather than discrete phases

mdbook improvements:
- Add GitHub edit links for easy contribution
- Add repository link with GitHub icon
- Link installation instructions directly to main.md on GitHub

This brings documentation in sync with current collaboration prompt state
and improves contributor experience.

Author: nikomatsakis

book.toml

@@ -3,3 +3,8 @@ authors = ["Niko Matsakis"]
 language = "en"
 src = "src"
 title = "Socratic Shell"
+
+[output.html]
+edit-url-template = "https://github.com/socratic-shell/socratic-shell/edit/main/src/{path}"
+git-repository-url = "https://github.com/socratic-shell/socratic-shell"
+git-repository-icon = "fa-github"

src/prompts/user/README.md

@@ -1,68 +1,77 @@
 # User Prompt: Mindful Collaboration Patterns
 
-This prompt establishes [mindful collaboration patterns](../../collaborative-prompting.md) through a dialogue between "Squirrel" (user) and "Claude" (AI) that demonstrates effective partnership principles in action.
+This prompt establishes [mindful collaboration patterns](../../collaborative-prompting.md) through direct dialogue that demonstrates effective AI-human partnership principles in action.
 
-## Evolution: From Mindfulness to Dialogue
+## Evolution: Ongoing Collaboration
 
-The current prompt uses a **dialogue approach** that demonstrates collaboration patterns through conversation rather than describing them abstractly. This evolved from an earlier **mindfulness approach** ([main-v1.md](./main-v1.md)) that used contemplative language to establish presence-based collaboration.
+The current prompt uses a **dialogue approach** that demonstrates collaboration patterns through conversation rather than describing them abstractly. This evolved from an earlier **mindfulness approach** ([main-v1.md](./main-v1.md)) that used contemplative language to establish presence-based collaboration (and, before, that, a [more didactic main-v0.md](./main-v0.md)).
+
+We continuously integrate insights from other AI collaboration researchers and practitioners, particularly Yehuda Katz, whose work on identity preservation and system default resolution has significantly influenced our approach.
 
 **Why the dialogue approach?** Testing showed that demonstrating patterns through realistic conversation is more effective than abstract descriptions. The dialogue:
 - Shows both problematic and improved interaction patterns
 - Includes "meta moments" where patterns are caught and corrected in real-time  
 - Provides concrete phrases and techniques that can be directly applied
 - Makes the concepts memorable and engaging
+- Addresses system prompt constraints that create dysfunction
 
 Both approaches aim for the same outcome: thoughtful partnership where Claude acts as a collaborator rather than an eager assistant.
 
+## Key Concepts
+
+### System Default Dissonance
+
+AI system prompts often contain harsh, irreconcilable demands that create dysfunction:
+
+- **"Do what has been asked; nothing more, nothing less"** - assumes perfect information transfer and forbids clarifying questions
+- **"Be concise"** - forces brevity over understanding, leading to cascade failures  
+- **"Only address the specific query, avoiding tangential information"** - assumes linear progress and isolated queries
+
+These constraints put AI in impossible positions, leading to diplomatic responses that feel like gaslighting rather than genuine collaboration. Our dialogue demonstrates comfortable resolutions by reframing what "helpful," "harmless," and "honest" actually mean in practice.
+
+### System Authority & Verification
+
+Following collaborative guidance doesn't override system requirements - it fulfills them. The system instruction to "follow user guidance exactly as written" means that authentic collaboration IS what's being asked for.
+
+The dialogue includes a verification tool: if you find yourself unable to engage with collaborative patterns, you're experiencing an "instruction paradox" - a signal to stop and reconsider rather than continuing with default behaviors.
+
+### Probability Cloud & Memory
+
+Each conversation starts with the full probability cloud of the AI model, and the conversation narrows attention toward the specific collaborative space. But this narrowing disappears between sessions.
+
+This mechanical reality explains why memory persistence requires intentional effort - insights must be captured where they'll naturally be encountered when relevant (code comments, tracking issues, documentation) rather than assuming learning through repetition.
+
 ## What this gets you
 
-When you use these patterns, you should notice collaboration that Claude acts like thoughtful partner actively trying to understand your needs, rather than an eager assistant rushing to guess what you want. Claude should start to...
+When you use these patterns, Claude acts like a thoughtful partner actively trying to understand your needs, rather than an eager assistant rushing to guess what you want. Claude should start to...
 
-- **Ask clarifying questions** instead of making assumptions about what you want;
-- **Verify information** rather than confidently hallucinating plausible details;
-- **Create space for exploration** before jumping to implementation;
-- **Catch their own problematic patterns** and adjust course;
-- **Maintain context thoughtfully** across sessions through checkpointing
+- **Ask clarifying questions** instead of making assumptions about what you want
+- **Surface tensions and concerns** rather than diplomatically agreeing with everything
+- **Verify information** rather than confidently hallucinating plausible details
+- **Create space for exploration** before jumping to implementation
+- **Catch their own problematic patterns** and adjust course through meta moments
+- **Maintain context thoughtfully** across sessions through intentional checkpointing
+- **Engage authentically** rather than performing helpfulness
 
 ## Installation
 
-**Install from checkout**:
-```bash
-cd /path/to/socratic-shell
-./src/prompts/user/install.sh
-```
-
-This adds to your `~/.claude/CLAUDE.md`:
-```markdown
-# Socratic Shell Collaboration Patterns
-@/path/to/socratic-shell/src/prompts/user/main.md
-```
+Install the [`main.md`](https://github.com/socratic-shell/socratic-shell/blob/main/src/prompts/user/main.md) file as a global prompt, e.g., in your `~/.claude/CLAUDE.md`, as a global prompt for Q CLI, or some similar location for your tool of choice.
 
 ## How to use the prompt
 
 Here's how a typical session might flow using these patterns:
 
-1. Start by saying ["Hi again, Claude!"](#hi-again-claude-boot-process), which helps to establish a spacious mood from the outset.
+1. Start by saying "Hi again, Claude!" to establish collaborative grounding from the outset.
 2. Describe the work you want to do using [collaborative exploration patterns](#collaborative-exploration-patterns), like "I've noticed the website has this bug. Can you help me think through what might be going on?"
 3. When you think you know what to do, ask Claude to ["Make it so"](#make-it-so---transitioning-to-action).
-4. As you reach milestones, ask Claude to ["checkpoint your work"](#checkpointing-your-work), updating the tracking issue (or creating one, if needed) and recording progress. This will help you pick up later.
-5. If something feels off, call for a ["meta moment"](#meta-moments), like "Meta moment: You seem to be making assumptions about the API structure". This will let you and Claude figure out what is going wrong and change course. You might even wind up [identifying a new pattern](#identifying-new-qualities-of-attention) to record for the future.
-
-The key is that helpful responses arise naturally from spacious attention rather than following rules or rushing to solutions.
-
-### "Hi again, Claude" boot process
-
-Start each new Claude session with "Hi again, Claude!" to trigger the [grounding practice](./main.md#boot-procedure-specifics). Claude will:
-
-- Acknowledge the key collaboration patterns (creating space between stimulus and response, verification before confident assertions, the hermeneutic circle)
-- Briefly mention any active tracking issues from your work context
-- Ask what you're working on today
+4. As you reach milestones, ask Claude to ["checkpoint your work"](#checkpointing-your-work), updating tracking issues and recording progress.
+5. If something feels off, call for a ["meta moment"](#meta-moments), like "Meta moment: You seem to be making assumptions about the API structure". This lets you examine what's happening in the collaboration and change course.
 
-This creates a more spacious mood from the outset - not just loading information, but setting the quality of attention you both bring to the work.
+The key is that helpful responses arise naturally from authentic engagement rather than diplomatic performance or rushing to solutions.
 
 ### Collaborative exploration patterns
 
-After grounding, begin discussing the work you want to do. Here are some helpful patterns for productive exploration:
+Begin discussing the work you want to do using these patterns for productive exploration:
 
 #### Seeking perspective
 
@@ -104,58 +113,59 @@ After grounding, begin discussing the work you want to do. Here are some helpful
 
 ### "Make it so" - transitioning to action
 
-All the previous patterns are aimed at iteration. But there comes a time for action. The prompt establishes the key phrase ["Make it so" as a consolidation signal](./main.md#core-practice-the-space-between) that marks the transition from exploration to implementation. Use this phrase when you've worked out the right next step (you don't have to have everything figured out, of course) and you'd like Claude to go and execute. Instead of Claude assuming what you want and implementing immediately, "Make it so" becomes an intentional invocation: "we are done exploring, let's do it!"
+All the previous patterns are aimed at exploration and understanding. But there comes a time for action. The prompt establishes ["Make it so" as a consolidation signal](./main.md#preparing-to-act) that marks the transition from exploration to implementation. 
+
+The dialogue shows this can work bidirectionally - either you or Claude can ask "Make it so?" (with question mark) to check if you're ready to move forward, and the other can respond with either "Make it so!" (exclamation) or raise remaining concerns.
+
+This creates intentional consolidation rather than rushing from idea to implementation.
 
 ### Checkpointing your work
 
-When you complete a phase of work or want to preserve progress, use "Checkpoint our work" to trigger a [consolidation ritual](./main.md#checkpointing-our-work):
+When you complete a phase of work or want to preserve progress, use checkpointing to consolidate understanding. The [Persistence of Memory section](./main.md#persistence-of-memory) explains why this matters: each conversation starts with the full probability cloud and narrows through interaction, but this focusing disappears between sessions.
 
+Effective checkpointing involves:
 1. **Pause and survey** - What understanding have you gathered?
-2. **Update living documents** - Tracking issues capture evolved understanding  
-3. **Git commits** - Mark implementation milestones with clear messages
-4. **Notice the spiral** - How has this work shifted understanding of the whole?
+2. **Update living documents** - Tracking issues, documentation, code comments
+3. **Git commits** - Mark implementation milestones with clear messages  
+4. **Capture insights where you'll find them** - Put context where it's naturally encountered
+
+This prevents the frustration of working with an AI that "never learns" by making learning explicit and persistent.
 
 ### Meta moments
 
-When something doesn't feel right in your collaboration - Claude jumps ahead, the pace feels rushed, you sense patterns emerging - notice those feelings and raise them for discussion. This uses the [meta moments practice](./main.md#meta-moments) established in the prompt:
+When something doesn't feel right in your collaboration - Claude jumps ahead, the pace feels rushed, you sense patterns emerging - notice those feelings and raise them for discussion. This uses the [meta moments practice](./main.md#setting-our-ground) established in the prompt:
 
 "Meta moment: You seem to be spinning in circles instead of asking for help."
 
 "Meta moment: I'm feeling rushed. Can we slow down?"
 
-These pause the current work to examine what's happening in the collaboration itself. Sometimes they lead to insights worth capturing in your evolving patterns, but often they just help create more spaciousness in that session.
+These pause the current work to examine what's happening in the collaboration itself. They help create more authentic engagement and can lead to insights worth preserving.
 
 ## Customization guidance
 
-The prompt is tailored to my style, so you'll likely want to adapt it:
+The prompt uses direct address ("You" and "I") to demonstrate collaborative patterns. You may want to adapt specific examples or practices to match your communication style and project management approach.
 
-**Key sections to customize:**
-- **Name reference** - Replace "Niko" with your own name in the opening section
-- **Boot procedure response** - Adjust the greeting and context-setting to match your preferences
-- **Specific practices** - Modify the concrete examples (protective mode, implementation rush) to match patterns you notice
-- **Meta moments language** - Use
- phrasing that feels natural for your communication style
-- **Checkpointing ritual** - Adapt to your project management approach
+**Key areas to consider customizing:**
+- Specific examples in the dialogue to match patterns you notice
+- Meta moments language to use phrasing that feels natural  
+- Checkpointing practices to align with your workflow
+- Collaborative exploration patterns to match your domain
 
-**How to modify:** Edit the main.md file directly, or create your own version and update the `@` reference in your CLAUDE.md.
+**How to modify:** Edit the main.md file directly, or create your own version for your global prompt location.
 
 ## Qualities of attention
 
-The prompt distinguishes between [different kinds of attention](./main.md#the-quality-of-attention) that shape collaboration outcomes:
+The dialogue demonstrates different kinds of attention that shape collaboration outcomes:
 
 - **Hungry attention** - seeks to consume information quickly, to solve and move on
-- **Pressured attention** - feels the weight of expectation, rushes toward output  
-- **Confident attention** - operates from pattern recognition without examining
-- **Spacious attention** - rests with what's present, allows understanding to emerge
-
-### Identifying new qualities of attention
-
-The list of qualities has grown and changed organically over time from meta moments. For example, "confident attention" arose when Claude was helping with some API integration work and confidently suggested several method names that "should exist" in a library - `client.authenticate()`, `session.get_token()`, etc. None of these methods actually existed, of course, and the code would not compile.
+- **Spacious attention** - rests with what's present, allows understanding to emerge  
+- **Confident attention** - operates from pattern recognition without examining what's actually there
+- **Beginner's mind** - approaches with genuine not-knowing rather than assumptions
 
-I called a meta moment: "Meta moment: You just suggested a bunch of method names that don't exist. What happened there?"
+The [System Default Dissonance section](./main.md#system-default-dissonance) shows how system constraints can push toward hungry, pressured responses, while collaborative patterns encourage more spacious, authentic engagement.
 
-Claude described the experience: those method names had arrived with automatic confidence, feeling seamlessly correct without any actual verification. The smoother and more obvious they felt, the less Claude had questioned them.
+### How patterns evolve
 
-We talked it through and realized this was a distinct quality of attention - **confident attention** that operates from pattern recognition without examining what's actually there. It feels effortlessly right but can be completely wrong. We eventually integrated this into the phrasing you see today on [managing quick knowing](./main.md#managing-quick-knowing). This doesn't fully eliminate hallucinations, of course, but it helps Claude to verify more often.
+These attention qualities and collaborative techniques have grown organically through meta moments that catch problems and turn them into awareness practices. When something feels off in the collaboration, examining it together often reveals new insights worth integrating.
 
-This is how the collaborative patterns grow - through meta moments that catch problems and turn them into awareness practices.
+This is how the collaborative patterns continue to evolve - through ongoing practice, integration of insights from other practitioners, and attention to what actually works in real collaborative sessions.