Skip to content

docs(server): match the app's connection dialog and its version rule - #199

Merged
fylorn merged 2 commits into
mainfrom
docs/seo2-server
Sep 25, 2026
Merged

fylorn merged 2 commits into
mainfrom
docs/seo2-server

Conversation

@fylorn

@fylorn fylorn commented Sep 25, 2026

Copy link
Copy Markdown
Contributor

docs/server.md and docs/server.zh-CN.md described the desktop app's side of a remote connection in ways the app does not behave, and told readers to keep the server on the latest release, which can break the connection.

What changes

Connecting (section 4)

  • The settings section is Settings → Connection (「设置 → 连接」), not "Connections" (title in ThinkWatch Lite's src/connection/connection.i18n.tsx on dev). The dialog's Name field is listed with the other three.
  • "The app tests the connection before saving" was only true of one button. Per src/connection/ProfileDialog.tsx: Test connection tests without saving; Save and switch tests first, saves only on success, then asks for confirmation (SwitchDialog); Save stores the connection untested. Switching to a remote connection always tests it first and stays on the current connection when the test fails (SwitchDialog.tsx, connector::test).
  • While connected to a remote core, ChatGPT accounts sign in with a device code only (remote.i18n.tsx, deviceOnly). This now sits next to the three things the server refuses.
  • "on its own computer" becomes "with its local core" / "on the machine it runs on".

Versions (Requirements, Install, Upgrading)

The handshake accepts only an exact control-plane protocol match (tw-link handshake.rs: answer.proto != proto is a VersionMismatch), so the server has to run the core version the app includes. The latest release can be newer: v0.48.0 is protocol 21, and ThinkWatch Lite 2026.9.16 includes v0.47.0 (protocol 20). The page used to say "upgrade the server and the desktop app together" next to twcore upgrade --restart, which installs the latest release.

  • Requirements: the server runs the core version the desktop app includes. The app checks it during the handshake and, when the versions differ, refuses the connection and shows both.
  • Install: the plain command installs the latest release; … | sudo sh -s -- --version <version> installs a particular one, and the app names the version it needs when they differ.
  • Upgrading leads with sudo twcore upgrade --version <version> --restart and states that --version also installs an older release (upgrade::plan, test a_pinned_version_installs_even_when_it_is_older, present since v0.47.0). --check and --restart without --version are described as working with the latest release.
  • Removed: "shows the command above with the version it needs". Today the app shows both versions and a bare twcore upgrade; the text now says that recent versions of the app show sudo twcore upgrade --version <version> --restart with the version filled in, which becomes true once the app change that adds it is released.
  • twcore upgrade does not touch the data, but a version whose request store has another schema starts with an empty request history (tw_store::open removes data.db and blobs/ on a schema mismatch; v0.47.0 is schema 19, v0.48.0 is 20). The Upgrading section says so.

The Chinese page carries the same changes and replaces a colloquial phrase in the handshake-throttling sentence.

Checked

  • Rendered both pages through the GitHub Markdown API: every bold label closes (including the Chinese button names followed directly by text) and the three new #upgrading / #升级 links point at existing headings.
  • cargo fmt --all -- --check passes, and cargo test -p tw-config --test manual passes (it parses the YAML examples in these two files; none changed).

🤖 Generated with Claude Code

fylorn and others added 2 commits September 25, 2026 19:07
docs/server.md and its Chinese version described the desktop app's side
of a remote connection in ways the app does not behave:

- The settings section is Connection, not Connections, and the add
  dialog also asks for a name.
- "The app tests the connection before saving" is true of Save and
  switch only. Test connection tests without saving, Save and switch
  tests before it saves and asks before it switches, and Save stores
  the connection untested. Switching to a remote connection always
  tests it first and stays on the current connection on failure.
- The app connects only to a core that speaks its control-plane
  protocol version, which in practice means the core version the app
  includes. The latest release can be newer than that (core v0.48.0 is
  protocol 21; ThinkWatch Lite 2026.9.16 includes v0.47.0, protocol
  20), so "upgrade the server and the app together" with a plain
  `twcore upgrade` could break the connection. The page now installs
  and switches with `--version <version>`, notes that `--version` also
  installs an older release, and says that recent versions of the app
  show that command when the versions differ. The claim that the app
  shows "the command above with the version it needs" is gone: today
  it shows both versions and a bare `twcore upgrade`.
- `twcore upgrade` leaves the data alone, but a version whose request
  store has another schema starts with an empty request history. The
  Upgrading section says so.
- While connected to a remote core, the app signs ChatGPT accounts in
  with a device code only; the page now says so next to the three
  things a remote connection cannot do.

The Chinese page also drops a colloquial phrase in the handshake
throttling sentence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…the keychain

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fylorn
fylorn merged commit 5ba2b7e into main Sep 25, 2026
4 checks passed
@fylorn
fylorn deleted the docs/seo2-server branch September 25, 2026 11:28
@fylorn fylorn mentioned this pull request Sep 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant