Skip to content

Documentation pass for Windows support #6

Description

@shtirlitsDva

Task: Documentation pass for Windows support

Description

Update README, the website docs, CLAUDE.md, and the plugin reference docs so Windows installation, configuration paths, and plugin usage are all documented. The PRD specifies WezTerm as the only supported Windows terminal — say so explicitly. Per CLAUDE.md, site/docs.html must stay in sync with README.md, so any README change in this task gets a matching site/docs.html change in the same PR.

Acceptance Criteria

  • README.md Installation section gains a "Windows" subsection with go install github.com/shtirlitsDva/revdiff/cmd/revdiff@latest and a one-line note that WezTerm is the supported terminal. Mention that build.ps1 exists for local builds.
  • README.md Config section gains a callout that on Windows the config root is %APPDATA%\revdiff\ (mapping to ~/.config/revdiff/ on Unix). Show the equivalent paths for config, keybindings, and themes/.
  • README.md Plugin section notes that both plugins work on Windows + WezTerm. List the limitation that only WezTerm is supported on Windows.
  • site/docs.html mirrors all the README changes verbatim. Verify by side-by-side diff after editing.
  • CLAUDE.md adds a Windows note next to the existing ~/.config/revdiff/ documentation lines so future agent sessions know about both layouts. Use the XML-like heading format from the user's global CLAUDE.md (e.g., <windows>...</windows> inside the relevant <section>).
  • .claude-plugin/skills/revdiff/references/install.md adds Windows install steps.
  • .claude-plugin/skills/revdiff/references/config.md documents the %APPDATA%\revdiff\ path mapping.
  • .claude-plugin/skills/revdiff/references/usage.md is unchanged unless something is genuinely platform-specific (the audit found no usage-level differences — keys and flags are platform-neutral).
  • site/index.html is not changed in this task unless a Windows mention fits naturally in the features grid. Per the PRD this is optional, not blocking.
  • No code files modified — this is documentation only.
  • Markdown lints clean (use whatever linter the project already runs; if none, visual review).

Technical Details

Files to modify

  • README.md
  • site/docs.html
  • CLAUDE.md
  • .claude-plugin/skills/revdiff/references/install.md
  • .claude-plugin/skills/revdiff/references/config.md

Files to read (for context, do not modify)

  • The PRD at .claude/prds/windows-support.md for the canonical Windows path mapping and the WezTerm-only constraint.
  • The audit in this conversation for the exact line numbers of existing ~/.config/revdiff/ references in README.md (lines 189–242 per the audit) and CLAUDE.md (lines 64, 68, 73 per the audit).
  • The completed task 001 file for the exact os.UserConfigDir() path each helper produces — copy those literal paths into the docs so they match what --dump-config actually shows.

Content guidance

README — Installation subsection (insert under existing Installation):

### Windows

revdiff supports Windows 10/11 with [WezTerm](https://wezfurlong.org/wezterm/) as the terminal.
Other Windows terminals (cmd.exe, Windows Terminal, mintty) are not validated.

Install via Go:

    go install github.com/shtirlitsDva/revdiff/cmd/revdiff@latest

Or build from a local checkout:

    .\build.ps1

This produces `.bin\revdiff.exe`.

README — Config section addendum:

On Windows, configuration lives under `%APPDATA%\revdiff\`:

| Resource     | Unix path                          | Windows path                        |
|--------------|------------------------------------|-------------------------------------|
| Config       | `~/.config/revdiff/config`         | `%APPDATA%\revdiff\config`          |
| Keybindings  | `~/.config/revdiff/keybindings`    | `%APPDATA%\revdiff\keybindings`     |
| Themes       | `~/.config/revdiff/themes/`        | `%APPDATA%\revdiff\themes\`         |

CLAUDE.md note:
Wrap Windows-specific notes in the XML-like heading style required by the user's global CLAUDE.md. Place them adjacent to the existing config-path documentation, not in a separate section at the end of the file.

Notes

  • site/docs.html is hand-maintained HTML (not generated). Edit it directly. Match the structure of existing sections.
  • Do not add references to revdiff-planning plugin Windows behavior that go beyond what task 004 actually delivers — keep docs honest.
  • Do not mention the GoReleaser/CI Windows binary path — it's explicitly out of scope per the PRD.
  • Do not add a :warning: or note: callout for WSL — the PRD says WSL is incidental, not validated, and not supported. Don't create false expectations.

Dependencies

  • None for creation — the documented behavior is locked in by the PRD.
  • The docs reference paths and commands that come out of tasks 001 and 002, so the content should not be merged before those tasks land. (Tracking this as a soft sequencing concern, not a hard depends_on.)
  • Validation in task 006 cross-checks the docs against actual behavior.

Effort Estimate

  • Size: S
  • Scope: targeted edits to ~5 markdown/HTML files. No new pages.

Definition of Done

  • All five files updated
  • site/docs.html reads identically to README on Windows-related sections (CLAUDE.md sync rule honored)
  • No code files modified
  • A reader following the new docs on Windows can install, configure, and use revdiff without surprises
  • Code reviewed

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

epic:windows-supportBelongs to the windows-support epicin-progressWork has started on this issuetaskTask within an epic

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions