diff --git a/.claude/skills/aphoria-install/SKILL.md b/.claude/skills/aphoria-install/SKILL.md
index 29b5b27..b2d6df9 100644
--- a/.claude/skills/aphoria-install/SKILL.md
+++ b/.claude/skills/aphoria-install/SKILL.md
@@ -31,6 +31,9 @@ Default scans are fast and ephemeral. Server/persistence is opt-in.
 ### 5. Progressive Disclosure
 Start with minimal setup, add complexity only when needed.
 
+### 6. Document Issues
+When things don't work as expected, create notes in `~/.aphoria/notes/` to track bugs and learnings for future improvement.
+
 ## Installation Tiers
 
 | Tier | What | Who | Time |
@@ -78,6 +81,8 @@ Before starting, challenge assumptions:
 8. **Provide quick smoke test.** `aphoria scan .` in any project.
 9. **Show expected output.** Users know if it's working.
 10. **Include cleanup commands.** How to uninstall if needed.
+11. **Document issues in ~/.aphoria/notes/.** Create notes when things go wrong.
+12. **Check for past notes.** Review known issues before starting.
 
 ## Do Not
 
@@ -127,6 +132,8 @@ Stop. Questions:
 - Use the port scheme (181XX) for servers
 - Provide verification commands after each step
 - Include rollback/uninstall instructions
+- Create note in `~/.aphoria/notes/` when issues occur
+- Check for existing notes about known issues before installing
 
 ## Installation Protocol
 
@@ -340,3 +347,86 @@ When guiding installation, provide:
 | `STEMEDB_BIND_ADDR` | `127.0.0.1:18180` | Server bind address |
 | `APHORIA_API_KEY` | (none) | Auth token for hosted mode |
 | `RUST_LOG` | (none) | Debug logging (`aphoria=debug`) |
+
+## Issue Documentation Protocol
+
+When something doesn't work as expected, bugs occur, or workarounds are needed, create a note to track the experience.
+
+### Note Location
+
+```
+~/.aphoria/notes/{YYYY-MM-DD}-{issue-name}.md
+```
+
+Example: `~/.aphoria/notes/2026-02-07-rust-version-mismatch.md`
+
+### When to Create Notes
+
+Create a note when:
+- A step fails unexpectedly
+- Verification doesn't pass
+- A workaround was needed
+- Documentation was incomplete or wrong
+- Environment-specific issues occurred
+- User had to intervene manually
+
+### Note Format
+
+```markdown
+# Installation Note: [Issue Name]
+
+**Date:** YYYY-MM-DD HH:MM
+**Phase:** Prerequisites | Build | Init | Verify | Server
+**Outcome:** Success with issues | Partial failure | Complete failure
+
+## Environment
+- OS: [macOS/Linux/Windows]
+- Rust version: [rustc output]
+- Working directory: [path]
+
+## Issue Summary
+[One paragraph describing what went wrong]
+
+## Steps to Reproduce
+1. [Step that triggered the issue]
+2. [What was expected]
+3. [What actually happened]
+
+## Error Output
+```
+[Paste error messages or unexpected output]
+```
+
+## Workaround Applied
+[What was done to work around the issue, if any]
+
+## Root Cause (if known)
+[Why this happened]
+
+## Suggested Fix
+[How the skill/docs should be updated to prevent this]
+
+## Tags
+#bug #prerequisite #build #init #server #workaround
+```
+
+### Creating Notes
+
+```bash
+# Ensure directory exists
+mkdir -p ~/.aphoria/notes
+
+# Create note
+cat > ~/.aphoria/notes/$(date +%Y-%m-%d)-issue-name.md << 'EOF'
+[Note content]
+EOF
+```
+
+### Reviewing Past Notes
+
+Before installing, check for known issues:
+```bash
+ls ~/.aphoria/notes/ 2>/dev/null
+```
+
+If notes exist, warn user about known issues they may encounter.