Streamline LLM guidance and fix file reference format

- Move guidance to project root as guidance.md, integrate with mdbook via include
- Streamline guidance from verbose version to ~60% shorter while keeping essentials
- Update file reference format to [`filename:line`][] (rustdoc-style) throughout
- Fix webview regex to detect <code>[filename:line][]</code> pattern in rendered HTML
- Refine sample review to use 'code-first tour' approach with code references as headers
- Update guidance to emphasize guided code tours rather than pure narrative style
- Fix UUID-based socket paths to avoid Unix socket path length truncation issues

Guidance now produces more focused, structured reviews while being much easier
for LLMs to digest. Fresh Claude validation shows high-quality output.

Author: nikomatsakis

extension/.vscode/launch.json

@@ -6,8 +6,9 @@
             "type": "extensionHost",
             "request": "launch",
             "args": [
-                "--extensionDevelopmentPath=${workspaceFolder}",
-            ]
+                "--extensionDevelopmentPath=${workspaceFolder}"
+            ],
+            "cwd": "${workspaceFolder}/playground"
         }
     ]
 }

extension/src/extension.ts

@@ -2,6 +2,7 @@ import * as vscode from 'vscode';
 import * as net from 'net';
 import * as path from 'path';
 import * as fs from 'fs';
+import * as crypto from 'crypto';
 import { ReviewWebviewProvider } from './reviewWebview';
 
 // 💡: Types for IPC communication with MCP server
@@ -110,20 +111,12 @@ function createIPCServer(context: vscode.ExtensionContext, reviewProvider: Revie
 }
 
 function getSocketPath(context: vscode.ExtensionContext): string {
-    // 💡: Use workspace-specific storage to avoid conflicts between projects
-    const storageUri = context.storageUri || context.globalStorageUri;
-    const socketDir = storageUri.fsPath;
-    
-    // Ensure directory exists
-    if (!fs.existsSync(socketDir)) {
-        fs.mkdirSync(socketDir, { recursive: true });
-    }
-    
-    // 💡: Platform-specific socket naming (Windows uses named pipes)
+    // 💡: Use UUID-based filename to avoid path length limits and ensure uniqueness
     if (process.platform === 'win32') {
-        return `\\\\.\\pipe\\dialectic-${Date.now()}`;
+        return `\\\\.\\pipe\\dialectic-${crypto.randomUUID()}`;
     } else {
-        return path.join(socketDir, 'dialectic.sock');
+        // Use /tmp with UUID for short, unique socket path
+        return `/tmp/dialectic-${crypto.randomUUID()}.sock`;
     }
 }
 

extension/src/reviewWebview.ts

@@ -167,10 +167,10 @@ export class ReviewWebviewProvider {
      * Process HTML to make file:line references clickable
      */
     private processFileReferences(html: string): string {
-        // 💡: Find patterns like (src/main.rs:42) and make them clickable
+        // 💡: Find patterns like [`src/main.rs:42`][] (rustdoc-style) and make them clickable
         return html.replace(
-            /\(([^:)]+):(\d+)\)/g,
-            '<a href="#" class="file-ref" data-file="$1" data-line="$2">($1:$2)</a>'
+            /<code>\[([^:\]]+):(\d+)\]<\/code>\[\]/g,
+            '<a href="#" class="file-ref" data-file="$1" data-line="$2"><code>[$1:$2][]</code></a>'
         );
     }
 
@@ -327,17 +327,17 @@ export class ReviewWebviewProvider {
 The application needed secure user authentication to protect user data and enable personalized features. This implements a JWT-based authentication system with secure password hashing.
 
 ## Changes Made
-- Added authentication middleware (src/auth/middleware.ts:23)
-- Created user login/signup endpoints (src/routes/auth.ts:45) 
-- Updated user model with password hashing (src/models/user.ts:67)
-- Added JWT token generation and validation (src/utils/jwt.ts:12)
+- Added authentication middleware [\`src/auth/middleware.ts:23\`][]
+- Created user login/signup endpoints [\`src/routes/auth.ts:45\`][] 
+- Updated user model with password hashing [\`src/models/user.ts:67\`][]
+- Added JWT token generation and validation [\`src/utils/jwt.ts:12\`][]
 
 ## Implementation Details
 
-### Authentication Flow (src/auth/middleware.ts:23)
+### Authentication Flow [\`src/auth/middleware.ts:23\`][]
 The middleware intercepts requests and validates JWT tokens. If the token is valid, the user object is attached to the request for downstream handlers to use.
 
-### Password Security (src/models/user.ts:67)
+### Password Security [\`src/models/user.ts:67\`][]
 Passwords are hashed using bcrypt with a salt factor of 12. The plaintext password is never stored in the database.
 
 ## Design Decisions

guidance.md

@@ -0,0 +1,82 @@
+# AI Assistant Guidelines for Dialectic
+
+## When to Present Reviews
+
+Call `present_review` after making significant code changes when:
+- You've implemented a feature or made substantial modifications
+- The user asks for a review or explanation of changes
+- You've completed a logical unit of work that warrants documentation
+
+**Don't** call for minor fixes, work-in-progress changes, or every individual file modification.
+
+## Review Structure
+
+### Write as Code Tours
+Structure reviews as guided tours through specific code locations. Lead with the code reference, then explain what's happening there and why it matters. Order sections to follow the logical flow of operations, not file order.
+
+### Include Context and Reasoning
+Explain not just what changed, but why:
+- Design decisions and trade-offs made
+- Alternative approaches considered  
+- Known limitations or future improvements needed
+
+### Use Consistent Structure
+- **Summary** - High-level overview suitable for commit message
+- **Implementation Walkthrough** - Narrative code tour
+- **Design Decisions** - Rationale for key choices
+- **Next Steps** - Future considerations
+
+## Code References
+
+**CRITICAL**: Use [`filename:line`][] format for all code references:
+- [`src/auth.ts:23`][] - Points to specific line
+- [`README.md:1`][] - Points to file beginning
+
+This renders as clickable links in VSCode and aligns with rustdoc conventions.
+
+## Update Modes
+- `replace` (default) - Complete review rewrite
+- `update-section` - Modify specific section (specify section header)  
+- `append` - Add new content to existing review
+
+## Sample Review
+
+```markdown
+# Add comprehensive error handling to user registration
+
+## Summary
+Enhanced user registration endpoint with proper validation, duplicate detection, 
+and structured error responses for better client integration.
+
+## Code Tour
+
+### Input Validation [`src/routes/auth.ts:34`][]
+
+Here we validate email format, password strength, and required fields before 
+processing the registration. Invalid inputs return structured error responses 
+with specific field-level feedback rather than generic "validation failed" 
+messages to improve UX.
+
+### Duplicate Detection [`src/models/user.ts:89`][]
+
+This query checks for existing accounts before creating new users. Running this 
+check before password hashing avoids unnecessary computation on duplicate attempts 
+and provides better performance for the common case of legitimate registrations.
+
+### Error Response Handling [`src/routes/auth.ts:67`][]
+
+Database operations are wrapped in try-catch blocks with specific handling for 
+constraint violations, connection issues, and unexpected failures. Each error 
+type returns appropriate HTTP status codes with consistent `{error, message, details}` 
+structure across all endpoints.
+
+## Design Decisions
+
+- **Early duplicate detection**: Checks email uniqueness before expensive bcrypt hashing
+- **Structured error format**: Consistent response shape for easier client handling
+
+## Next Steps
+
+- Add rate limiting for registration attempts
+- Implement email verification workflow
+```

md/design/ai-guidelines.md

@@ -1,84 +1,7 @@
 # AI Assistant Guidelines
 
-*This chapter defines how AI assistants should effectively use the Dialectic system. This content will eventually be incorporated into user installation instructions.*
+*This chapter defines how AI assistants should effectively use the Dialectic system.*
 
-## When to Present Reviews
-
-Call `present-review` after making significant code changes when:
-- You've implemented a feature or made substantial modifications
-- The user asks for a review or explanation of changes
-- You've completed a logical unit of work that warrants documentation
-
-**Don't** call `present-review` for:
-- Minor single-line fixes or typos
-- Work-in-progress changes that aren't ready for review
-- Every individual file modification during active development
-
-## Review Structure Guidelines
-
-### Use Narrative Style
-Write reviews as guided tours through the code, not just lists of changes:
-
-**Good**: "When a user logs in (auth.ts:23), we first validate their credentials against the database. If successful, we generate a JWT token (auth.ts:45) and store the session..."
-
-**Poor**: "Modified auth.ts lines 23-50. Added login function. Updated token generation."
-
-### Include Context and Reasoning
-Explain not just what changed, but why:
-- Design decisions and trade-offs made
-- Alternative approaches considered
-- Known limitations or future improvements needed
-
-### Structure with Clear Sections
-Use consistent markdown structure:
-- **Summary** - High-level overview
-- **Implementation Walkthrough** - Narrative code tour  
-- **Design Decisions** - Rationale for key choices
-- **Next Steps** - Future considerations
-
-## Code References
-
-Use `file:line` format for all code references:
-- `src/auth.ts:23` - Points to specific line
-- `README.md:1` - Points to file beginning
-- Include context about what the reference shows
-
-*TODO: Add guidelines for referencing ranges, functions, classes*
-
-## Update Modes
-
-### replace
-Use for complete review rewrites when:
-- The changes are too extensive for incremental updates
-- The review structure needs significant reorganization
-
-### update-section  
-Use to modify specific parts when:
-- Only certain components changed
-- You want to preserve other sections unchanged
-- Specify the section header to update
-
-### append
-Use to add new content when:
-- Adding information about additional changes
-- Including follow-up notes or discoveries
-
-## Best Practices
-
-*TODO: Expand with specific examples and anti-patterns*
-
-- Keep line references current by updating them as you make further changes
-- Use descriptive section headers that make navigation easy
-- Balance detail with readability - explain complex logic but don't over-document obvious code
-- Include rationale for non-obvious design choices
-
-## Common Pitfalls
-
-*TODO: Document common mistakes and how to avoid them*
-
-## Integration with Socratic Shell
-
-This tool works best within the collaborative patterns established by the socratic shell project:
-- Use reviews to facilitate dialogue, not just report status
-- Encourage questions and iteration rather than assuming first implementations are final
-- Preserve the reasoning process for future reference
+```
+{{#include ../../guidance.md}}
+```

server/src/index.ts

@@ -52,7 +52,8 @@ class DialecticMCPServer {
             name: 'present_review',
             description: [
               'Display a code review in the VSCode review panel.',
-              'Reviews should be structured markdown with clear sections and actionable feedback.'
+              'Reviews should be structured markdown with clear sections and actionable feedback.',
+              'Use [`filename:line`][] format for file references (rustdoc-style).'
             ].join(' '),
             inputSchema: {
               type: 'object',
@@ -64,7 +65,8 @@ class DialecticMCPServer {
                     '1) Brief summary suitable for commit message,',
                     '2) Detailed findings with file references,',
                     '3) Specific suggestions for improvement.',
-                    'Use `file:line` format for code references (e.g., `src/main.ts:42`).'
+                    'Use [`filename:line`][] format for file references.',
+                    'Example: "Updated authentication in [`src/auth.rs:45`][]"'
                   ].join(' '),
                 },
                 mode: {