Skip to content

Add Windows symlink setup guidance and linkable docs for shared-team adoption #276

@yacosta738

Description

@yacosta738

Summary

Windows symlink behavior is a team adoption concern, not just a local OS detail. Teams need clear documentation for native Windows contributors, especially around Developer Mode, git config core.symlinks true, expected failure modes, and WSL recommendations.

Goal

Create a dedicated, linkable documentation section for Windows setup and ensure product messaging can point users there.

Scope

Documentation first. If lightweight product copy updates are needed to reference the docs anchor from wizard/help output, include them only if they stay tightly scoped.

Required content

  • Native Windows prerequisites for symlink creation
    • Developer Mode or elevated shell
    • git config core.symlinks true
  • What broken states look like
    • symlink checkout as plain text files
    • missing files when symlinks are gitignored and apply was not run
    • apply failures due to permissions
  • WSL as the recommended lower-friction path when appropriate
  • How to verify symlinks are working correctly
  • Guidance for repo maintainers adopting AgentSync in teams with Windows users

Acceptance criteria

  • A dedicated, linkable Windows setup section exists in docs
  • The docs explain prerequisites, symptoms, recovery steps, and verification commands
  • The content is written for both Windows users and teammates on other platforms who need to support them
  • Relevant docs pages cross-link to the Windows setup section
  • If product copy is updated, it references the stable docs anchor instead of embedding long platform guidance inline

Notes

Keep the product default unchanged. This issue is about making the Windows trade-offs explicit and discoverable.

Metadata

Metadata

Assignees

Labels

agentdocumentationImprovements or additions to documentationimprovementquestionFurther information is requested

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions