Merge remote-tracking branch 'github/main'

repository.json describes vDiff itself; "tags": true means a release is a
pushed git tag. channel.json is the file users add to their "channels"
setting - it holds nothing but repository URLs, so packages added to it
later reach existing users without them changing anything.

The two are easy to confuse: Package Control rejects a file under
"channels" unless it has a top-level "repositories" key, so a repository
file belongs in "repositories". The README spells that out.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitattributes

@@ -0,0 +1,11 @@
+# Keep the release archive to what Sublime actually loads. Package Control
+# installs whatever the tag's zip contains, and GitHub builds that zip with
+# git archive, which honours export-ignore.
+.claude/            export-ignore
+tests/              export-ignore
+.gitattributes      export-ignore
+.gitignore          export-ignore
+diff.sublime-project export-ignore
+TODO.txt            export-ignore
+channel.json        export-ignore
+repository.json     export-ignore

.python-version

@@ -1 +1 @@
-3.8
+3.14

README.md

@@ -4,18 +4,48 @@ Review what a coding agent changed without leaving Sublime Text: the whole file,
 insertions in green, in the file's own syntax highlighting. Stage, unstage or discard the file, or jump
 to the real file at the caret's line.
 
-Install: symlink this directory into `Packages` as `vDiff` (Python 3.8 plugin host, no dependencies).
+Needs Sublime Text build 4213 or later, the build that replaced the Python 3.8 plugin host with
-On first use vDiff writes the scopes it paints changes with into `Packages/User/<your scheme>.sublime-color-scheme`;
+Python 3.14. No dependencies.
-Sublime loads a scheme file it has not seen before only at startup, so restart it once to get the colours.
 
-Command Palette:
+## Install with Package Control
+
+vDiff is not on the default channel, so add this one first. Open
+**Preferences → Package Settings → Package Control → Settings** and put the channel URL in the
+`channels` array of the right-hand (User) pane:
+
+```json
+{
+    "channels": [
+        "https://packagecontrol.io/channel_v3.json",
+        "https://raw.githubusercontent.com/vaclavt/vdiff/main/channel.json"
+    ]
+}
+```
+
+Keep `https://packagecontrol.io/channel_v3.json` in the list — dropping it hides every default
+package. Then run **Package Control: Install Package** from the Command Palette and pick **vDiff**.
+Upgrades arrive through **Package Control: Upgrade Package** like any other package.
+
+## Install from source
+
+Clone or symlink the repository into the Sublime Text `Packages` directory as `vDiff`:
+
+```bash
+git clone https://github.com/vaclavt/vdiff.git \
+  "$HOME/Library/Application Support/Sublime Text/Packages/vDiff"
+```
+
+Use one method or the other, not both: an unpacked `Packages/vDiff` directory overrides the
+`vDiff.sublime-package` that Package Control installs.
+
+## Command Palette
 
 - **vDiff: Changed Files** – uncommitted changes (staged, unstaged, untracked). Arrowing through
   the list previews each file; Enter keeps it, Esc goes back to what was shown.
 - **vDiff: Recent Commits** – last N commits, then the files of the chosen commit. A key binding to
   `vdiff_commits` with `{"sha": "HEAD"}` skips the list and reviews the last commit directly.
 
-Keys inside the review view:
+## Keys inside the review view
 
 | key | action |
 |---|---|
@@ -32,3 +62,46 @@ Keys inside the review view:
 | Esc | close the view |
 
 The header links do the same with the mouse. Settings: `vDiff.sublime-settings`.
+
+## The channel
+
+Two files in this repository feed Package Control, and the distinction between them matters:
+
+- `repository.json` — a **repository** file. Its top-level key is `packages`, and it describes
+  vDiff itself: where the code lives and which releases exist. `"tags": true` means Package
+  Control reads the repository's git tags, so publishing a release is just
+  `git tag v1.0.1 && git push --tags`. A package whose tags are all unpushed resolves to zero
+  releases, and Package Control drops it from the list without an error — if vDiff is missing
+  from **Install Package**, check the tags reached GitHub.
+- `channel.json` — a **channel** file. Its top-level key is `repositories`, and it is nothing but
+  a list of repository-file URLs. This is the one users add to `channels`.
+
+The indirection is what makes a channel worth having: users add one URL once, and every package
+you later append to `repositories` shows up in their **Install Package** list without them
+changing anything.
+
+### Adding another package to the channel
+
+Append the URL of that package's *repository* file to `repositories` in `channel.json`:
+
+```json
+{
+    "$schema": "sublime://packagecontrol.io/schemas/channel",
+    "schema_version": "4.0.0",
+    "repositories": [
+        "https://raw.githubusercontent.com/vaclavt/vdiff/main/repository.json",
+        "https://raw.githubusercontent.com/vaclavt/vAI/main/channel.json"
+    ]
+}
+```
+
+Two things to watch:
+
+- The URL must be a repository file (top-level `packages`), whatever it is named. vAI's
+  `channel.json` is a repository file despite its name, so it belongs in a `repositories` array —
+  Package Control rejects any file without a `repositories` key when it is listed under `channels`.
+- Package Control fetches anonymously over HTTPS, so the URL has to be publicly readable. A
+  package on a private host is not installable this way.
+
+If you would rather skip the channel for a single package, a repository file can be added directly
+to the `repositories` array of Package Control's settings instead.

channel.json

@@ -0,0 +1,7 @@
+{
+    "$schema": "sublime://packagecontrol.io/schemas/channel",
+    "schema_version": "4.0.0",
+    "repositories": [
+        "https://raw.githubusercontent.com/vaclavt/vdiff/main/repository.json"
+    ]
+}

repository.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "sublime://packagecontrol.io/schemas/repository",
+    "schema_version": "4.0.0",
+    "packages": [
+        {
+            "name": "vDiff",
+            "details": "https://github.com/vaclavt/vdiff",
+            "description": "Review uncommitted changes and commits in Sublime Text: whole files with deletions in red and insertions in green, in the file's own syntax highlighting",
+            "author": "vaclavt",
+            "labels": ["git", "diff", "review", "vcs"],
+            "releases": [
+                {
+                    "sublime_text": ">=4213",
+                    "platforms": ["*"],
+                    "python_versions": ["3.14"],
+                    "tags": true
+                }
+            ]
+        }
+    ]
+}