From 4ed3930df045c8ebe52681140d9bc6039557fd80 Mon Sep 17 00:00:00 2001
From: AngelMsger <AngelMsger@Vip.QQ.Com>
Date: Mon, 18 May 2026 22:02:21 +0800
Subject: [PATCH] Add page version history, restore and watch commands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements tier 2 of the practical-coverage roadmap.

Version history — `page history` lists a page's versions; `page restore
--version N` rolls a page back. Restore has no native v1 endpoint, so it
fetches version N's body and republishes it as a new version via the existing
buildUpdatePage machinery — non-destructive, the history is kept. `restore`
supports `--dry-run`.

Watchers — `page watch` / `page unwatch` subscribe or unsubscribe the
authenticated user (the v1 user-watch endpoints act on the credentialed user,
so no current-user resolution is needed); `page watch-status` reports whether
you watch a page. `watch` / `unwatch` support `--dry-run`.

Each write op exposes a build* helper shared with `DescribeWrite`, keeping the
--dry-run preview in lock-step with the sent request. Regenerates the CLI
reference and updates the embedded confluence Skill.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |   7 ++
 docs/cli/README.md                            |   5 +
 docs/cli/index.html                           |  81 +++++++++++++
 internal/apiclient/client.go                  |   6 +
 internal/apiclient/mapping.go                 |  37 +++++-
 internal/apiclient/models.go                  |  24 ++++
 internal/apiclient/pages_write.go             |   4 +
 internal/apiclient/versions.go                |  85 ++++++++++++++
 internal/apiclient/versions_test.go           | 110 ++++++++++++++++++
 internal/apiclient/watch.go                   |  53 +++++++++
 internal/apiclient/watch_test.go              |  91 +++++++++++++++
 internal/app/app_test.go                      |  17 +++
 internal/app/page.go                          |   2 +
 internal/app/page_history.go                  |  91 +++++++++++++++
 internal/app/page_watch.go                    |  84 +++++++++++++
 internal/app/writes_test.go                   |  92 +++++++++++++++
 skills/confluence/SKILL.md                    |  18 ++-
 skills/confluence/references/writing-pages.md |  26 +++++
 18 files changed, 825 insertions(+), 8 deletions(-)
 create mode 100644 internal/apiclient/versions.go
 create mode 100644 internal/apiclient/versions_test.go
 create mode 100644 internal/apiclient/watch.go
 create mode 100644 internal/apiclient/watch_test.go
 create mode 100644 internal/app/page_history.go
 create mode 100644 internal/app/page_watch.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 57eb520..97842da 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Page version history: `page history` lists a page's versions, and
+  `page restore --version N` rolls a page back by republishing that version's
+  body as a new version (non-destructive — the history is kept). `restore`
+  supports `--dry-run`.
+- Page watch commands: `page watch` / `page unwatch` subscribe or unsubscribe
+  the authenticated user, and `page watch-status` reports whether you watch a
+  page. `watch` / `unwatch` support `--dry-run`.
 - Attachment write commands: `attachment upload` attaches a file to a page,
   `attachment update` replaces an attachment's content with a new version, and
   `attachment delete` removes one. Uploads use `multipart/form-data`; `--file -`
diff --git a/docs/cli/README.md b/docs/cli/README.md
index db4f738..1fefad3 100644
--- a/docs/cli/README.md
+++ b/docs/cli/README.md
@@ -70,8 +70,13 @@ is published at <https://angelmsger.github.io/confluence-cli/cli/>.
 | [`confluence-cli page delete`](https://angelmsger.github.io/confluence-cli/cli/#confluence-cli-page-delete) | Delete a page (move it to the trash) |
 | [`confluence-cli page descendants`](https://angelmsger.github.io/confluence-cli/cli/#confluence-cli-page-descendants) | List all descendant pages of a page |
 | [`confluence-cli page get`](https://angelmsger.github.io/confluence-cli/cli/#confluence-cli-page-get) | Fetch a page and render its body |
+| [`confluence-cli page history`](https://angelmsger.github.io/confluence-cli/cli/#confluence-cli-page-history) | List a page's version history |
 | [`confluence-cli page move`](https://angelmsger.github.io/confluence-cli/cli/#confluence-cli-page-move) | Move a page under a new parent and/or space |
+| [`confluence-cli page restore`](https://angelmsger.github.io/confluence-cli/cli/#confluence-cli-page-restore) | Restore a page to an earlier version |
+| [`confluence-cli page unwatch`](https://angelmsger.github.io/confluence-cli/cli/#confluence-cli-page-unwatch) | Stop watching a page |
 | [`confluence-cli page update`](https://angelmsger.github.io/confluence-cli/cli/#confluence-cli-page-update) | Update a page's title and/or body |
+| [`confluence-cli page watch`](https://angelmsger.github.io/confluence-cli/cli/#confluence-cli-page-watch) | Watch a page (subscribe to its notifications) |
+| [`confluence-cli page watch-status`](https://angelmsger.github.io/confluence-cli/cli/#confluence-cli-page-watch-status) | Report whether you watch a page |
 
 ## search
 
diff --git a/docs/cli/index.html b/docs/cli/index.html
index c0f1ea5..689e224 100644
--- a/docs/cli/index.html
+++ b/docs/cli/index.html
@@ -74,8 +74,13 @@
       <a href="#confluence-cli-page-delete">confluence-cli page delete</a>
       <a href="#confluence-cli-page-descendants">confluence-cli page descendants</a>
       <a href="#confluence-cli-page-get">confluence-cli page get</a>
+      <a href="#confluence-cli-page-history">confluence-cli page history</a>
       <a href="#confluence-cli-page-move">confluence-cli page move</a>
+      <a href="#confluence-cli-page-restore">confluence-cli page restore</a>
+      <a href="#confluence-cli-page-unwatch">confluence-cli page unwatch</a>
       <a href="#confluence-cli-page-update">confluence-cli page update</a>
+      <a href="#confluence-cli-page-watch">confluence-cli page watch</a>
+      <a href="#confluence-cli-page-watch-status">confluence-cli page watch-status</a>
       </div>
     <div class="side-group">
       <div class="side-title">search</div>
@@ -606,6 +611,23 @@ <h3>Examples</h3><pre><span class="c">  # render the whole page as Markdown</spa
   confluence-cli page get https://wiki.example.com/pages/viewpage.action?pageId=123456</pre>
     </section>
     
+    <section class="cmd" id="confluence-cli-page-history">
+      <h2>confluence-cli page history</h2>
+      <p class="short">List a page&#39;s version history</p>
+      <pre>confluence-cli page history &lt;id|url&gt; [flags]</pre>
+      
+      <h3>Options</h3>
+      <table>
+        <thead><tr><th>Flag</th><th>Default</th><th>Description</th></tr></thead>
+        <tbody>
+        <tr><td><code>--all</code></td><td><code>false</code></td><td>fetch every page of results</td></tr>
+        <tr><td><code>--limit</code></td><td><code>0</code></td><td>page size (default from config)</td></tr>
+        </tbody>
+      </table>
+      <h3>Examples</h3><pre>  confluence-cli page history 123456
+  confluence-cli page history 123456 --all --format table</pre>
+    </section>
+    
     <section class="cmd" id="confluence-cli-page-move">
       <h2>confluence-cli page move</h2>
       <p class="short">Move a page under a new parent and/or space</p>
@@ -627,6 +649,41 @@ <h3>Examples</h3><pre><span class="c">  # reparent a page</span>
   confluence-cli page move 123456 --target-space DOCS</pre>
     </section>
     
+    <section class="cmd" id="confluence-cli-page-restore">
+      <h2>confluence-cli page restore</h2>
+      <p class="short">Restore a page to an earlier version</p>
+      <pre>confluence-cli page restore &lt;id|url&gt; --version &lt;N&gt; [flags]</pre>
+      <p class="long">Republish an earlier version&#39;s body as a new version. The restore is
+non-destructive: the version history is left intact. Run `page history`
+first to find the version number to restore.</p>
+      <h3>Options</h3>
+      <table>
+        <thead><tr><th>Flag</th><th>Default</th><th>Description</th></tr></thead>
+        <tbody>
+        <tr><td><code>--dry-run</code></td><td><code>false</code></td><td>print the request without sending it</td></tr>
+        <tr><td><code>--message</code></td><td></td><td>version comment for the restore</td></tr>
+        <tr><td><code>--version</code></td><td><code>0</code></td><td>the version number to restore</td></tr>
+        </tbody>
+      </table>
+      <h3>Examples</h3><pre>  confluence-cli page restore 123456 --version 3
+  confluence-cli page restore 123456 --version 3 --message &#34;roll back bad edit&#34;</pre>
+    </section>
+    
+    <section class="cmd" id="confluence-cli-page-unwatch">
+      <h2>confluence-cli page unwatch</h2>
+      <p class="short">Stop watching a page</p>
+      <pre>confluence-cli page unwatch &lt;id|url&gt; [flags]</pre>
+      
+      <h3>Options</h3>
+      <table>
+        <thead><tr><th>Flag</th><th>Default</th><th>Description</th></tr></thead>
+        <tbody>
+        <tr><td><code>--dry-run</code></td><td><code>false</code></td><td>print the request without sending it</td></tr>
+        </tbody>
+      </table>
+      <h3>Examples</h3><pre>  confluence-cli page unwatch 123456</pre>
+    </section>
+    
     <section class="cmd" id="confluence-cli-page-update">
       <h2>confluence-cli page update</h2>
       <p class="short">Update a page&#39;s title and/or body</p>
@@ -655,6 +712,30 @@ <h3>Examples</h3><pre><span class="c">  # retitle a page, keeping its body</span
   confluence-cli page update 123456 --format markdown --body-file body.md --version 7</pre>
     </section>
     
+    <section class="cmd" id="confluence-cli-page-watch">
+      <h2>confluence-cli page watch</h2>
+      <p class="short">Watch a page (subscribe to its notifications)</p>
+      <pre>confluence-cli page watch &lt;id|url&gt; [flags]</pre>
+      
+      <h3>Options</h3>
+      <table>
+        <thead><tr><th>Flag</th><th>Default</th><th>Description</th></tr></thead>
+        <tbody>
+        <tr><td><code>--dry-run</code></td><td><code>false</code></td><td>print the request without sending it</td></tr>
+        </tbody>
+      </table>
+      <h3>Examples</h3><pre>  confluence-cli page watch 123456</pre>
+    </section>
+    
+    <section class="cmd" id="confluence-cli-page-watch-status">
+      <h2>confluence-cli page watch-status</h2>
+      <p class="short">Report whether you watch a page</p>
+      <pre>confluence-cli page watch-status &lt;id|url&gt;</pre>
+      
+      
+      <h3>Examples</h3><pre>  confluence-cli page watch-status 123456</pre>
+    </section>
+    
     <section class="cmd" id="confluence-cli-search">
       <h2>confluence-cli search</h2>
       <p class="short">Search pages with CQL or filter flags</p>
diff --git a/internal/apiclient/client.go b/internal/apiclient/client.go
index 154b669..ce3aec5 100644
--- a/internal/apiclient/client.go
+++ b/internal/apiclient/client.go
@@ -35,6 +35,12 @@ type Client interface {
 	CopyPage(ctx context.Context, req CopyPageReq) (*Page, error)
 	DescribeWrite(ctx context.Context, op any) (WriteRequestPlan, error)
 
+	ListPageVersions(ctx context.Context, id string, opt ListOpts) (ListResult[PageVersion], error)
+	RestorePage(ctx context.Context, req RestorePageReq) (*Page, error)
+
+	WatchStatus(ctx context.Context, pageID string) (bool, error)
+	SetWatch(ctx context.Context, req WatchReq) error
+
 	Search(ctx context.Context, cql string, opt ListOpts) (ListResult[SearchHit], error)
 
 	ListSpaces(ctx context.Context, opt SpaceListOpts) (ListResult[Space], error)
diff --git a/internal/apiclient/mapping.go b/internal/apiclient/mapping.go
index 1c40a56..9b604f0 100644
--- a/internal/apiclient/mapping.go
+++ b/internal/apiclient/mapping.go
@@ -43,13 +43,33 @@ type rawBody struct {
 }
 
 type rawVersion struct {
-	Number int    `json:"number"`
-	When   string `json:"when"`
-	By     struct {
+	Number    int    `json:"number"`
+	When      string `json:"when"`
+	Message   string `json:"message"`
+	MinorEdit bool   `json:"minorEdit"`
+	By        struct {
 		DisplayName string `json:"displayName"`
 	} `json:"by"`
 }
 
+type rawVersionList struct {
+	Results []rawVersion `json:"results"`
+	Size    int          `json:"size"`
+	Limit   int          `json:"limit"`
+}
+
+// rawContentVersion is one entry of a content's version history with the
+// version's content (and body) expanded.
+type rawContentVersion struct {
+	Number  int        `json:"number"`
+	Content rawContent `json:"content"`
+}
+
+// rawWatch is the response of the user-watch status endpoint.
+type rawWatch struct {
+	Watching bool `json:"watching"`
+}
+
 type rawSpace struct {
 	ID    any      `json:"id"` // server returns a number, Cloud a string
 	Key   string   `json:"key"`
@@ -140,6 +160,17 @@ func versionOf(v *rawVersion) *Version {
 	return &Version{Number: v.Number, When: v.When, By: v.By.DisplayName}
 }
 
+// pageVersionOf normalizes a raw version-history entry into a PageVersion.
+func pageVersionOf(r rawVersion) PageVersion {
+	return PageVersion{
+		Number:    r.Number,
+		When:      r.When,
+		By:        r.By.DisplayName,
+		Message:   r.Message,
+		MinorEdit: r.MinorEdit,
+	}
+}
+
 // mapPage normalizes a v1 content object into a Page.
 func (c *apiClient) mapPage(r rawContent) *Page {
 	p := &Page{
diff --git a/internal/apiclient/models.go b/internal/apiclient/models.go
index acb7919..7beb3f5 100644
--- a/internal/apiclient/models.go
+++ b/internal/apiclient/models.go
@@ -80,6 +80,15 @@ type Attachment struct {
 	DownloadURL string `json:"download_url,omitempty"`
 }
 
+// PageVersion is one entry in a page's version history.
+type PageVersion struct {
+	Number    int    `json:"number"`
+	When      string `json:"when,omitempty"`
+	By        string `json:"by,omitempty"`
+	Message   string `json:"message,omitempty"`
+	MinorEdit bool   `json:"minor_edit,omitempty"`
+}
+
 // Label is a normalized Confluence content label.
 type Label struct {
 	ID     string `json:"id,omitempty"`
@@ -221,6 +230,21 @@ type DeleteAttachmentReq struct {
 	AttachmentID string
 }
 
+// RestorePageReq is a request to restore a page to an earlier version. The
+// restore is non-destructive: it republishes the version's body as a new
+// version, leaving the history intact.
+type RestorePageReq struct {
+	ID      string
+	Version int    // the historical version number to restore
+	Message string // optional version comment for the restore
+}
+
+// WatchReq toggles whether the authenticated user watches a page.
+type WatchReq struct {
+	PageID   string
+	Watching bool // true = watch, false = unwatch
+}
+
 // AddLabelsReq is a request to add one or more labels to a page.
 type AddLabelsReq struct {
 	PageID string
diff --git a/internal/apiclient/pages_write.go b/internal/apiclient/pages_write.go
index ddc58d5..0c547d7 100644
--- a/internal/apiclient/pages_write.go
+++ b/internal/apiclient/pages_write.go
@@ -314,6 +314,10 @@ func (c *apiClient) DescribeWrite(ctx context.Context, op any) (WriteRequestPlan
 		method, path, payload, err = c.buildAddLabels(v)
 	case RemoveLabelReq:
 		method, path, err = c.buildRemoveLabel(v)
+	case RestorePageReq:
+		method, path, payload, err = c.buildRestorePage(ctx, v)
+	case WatchReq:
+		method, path, err = c.buildSetWatch(v)
 	default:
 		return WriteRequestPlan{}, cerrors.New(cerrors.CategoryInternal, "DRYRUN_BAD_OP",
 			"unsupported write operation for dry-run")
diff --git a/internal/apiclient/versions.go b/internal/apiclient/versions.go
new file mode 100644
index 0000000..e789a60
--- /dev/null
+++ b/internal/apiclient/versions.go
@@ -0,0 +1,85 @@
+package apiclient
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"strconv"
+
+	cerrors "github.com/angelmsger/confluence-cli/internal/errors"
+)
+
+// versions.go holds the page version-history operations: listing a page's
+// versions and restoring it to an earlier one. Restore has no native v1
+// endpoint, so it republishes a historical version's body as a new version,
+// reusing buildUpdatePage — the history is left intact.
+
+// ListPageVersions lists a page's version history, newest first.
+func (c *apiClient) ListPageVersions(ctx context.Context, id string, opt ListOpts) (ListResult[PageVersion], error) {
+	limit := c.limitOf(opt)
+	q := offsetQuery(opt.Cursor, limit)
+	path := c.v1Base() + "/content/" + url.PathEscape(id) + "/version"
+	var raw rawVersionList
+	if err := c.getJSON(ctx, path, q, &raw); err != nil {
+		return ListResult[PageVersion]{}, err
+	}
+	res := ListResult[PageVersion]{Next: nextOffsetToken(opt.Cursor, limit, len(raw.Results))}
+	for _, r := range raw.Results {
+		res.Items = append(res.Items, pageVersionOf(r))
+	}
+	return res, nil
+}
+
+// getPageVersionBody fetches the storage-format body of a historical version.
+func (c *apiClient) getPageVersionBody(ctx context.Context, id string, version int) (PageBody, error) {
+	q := url.Values{}
+	q.Set("expand", "content.body.storage")
+	path := c.v1Base() + "/content/" + url.PathEscape(id) + "/version/" + strconv.Itoa(version)
+	var raw rawContentVersion
+	if err := c.getJSON(ctx, path, q, &raw); err != nil {
+		return PageBody{}, err
+	}
+	b := bodyOf(raw.Content.Body)
+	if b == nil {
+		return PageBody{}, cerrors.Newf(cerrors.CategoryNotFound, "VERSION_NO_BODY",
+			"version %d of page %s has no retrievable body", version, id)
+	}
+	return PageBody{Value: b.Value, Format: "storage"}, nil
+}
+
+// buildRestorePage assembles the PUT request that restores a page to an earlier
+// version: it fetches that version's body and delegates to buildUpdatePage,
+// which carries over the current title and bumps the version number.
+func (c *apiClient) buildRestorePage(ctx context.Context, req RestorePageReq) (method, path string, payload any, err error) {
+	if req.ID == "" {
+		return "", "", nil, cerrors.New(cerrors.CategoryUsage, "PAGE_NO_ID",
+			"a page ID is required to restore a page")
+	}
+	if req.Version <= 0 {
+		return "", "", nil, cerrors.New(cerrors.CategoryUsage, "RESTORE_NO_VERSION",
+			"a positive --version is required to restore a page")
+	}
+	body, err := c.getPageVersionBody(ctx, req.ID, req.Version)
+	if err != nil {
+		return "", "", nil, err
+	}
+	message := req.Message
+	if message == "" {
+		message = fmt.Sprintf("Restored to version %d", req.Version)
+	}
+	return c.buildUpdatePage(ctx, UpdatePageReq{ID: req.ID, Body: &body, Message: message})
+}
+
+// RestorePage restores a page to an earlier version by republishing that
+// version's body as a new version.
+func (c *apiClient) RestorePage(ctx context.Context, req RestorePageReq) (*Page, error) {
+	method, path, payload, err := c.buildRestorePage(ctx, req)
+	if err != nil {
+		return nil, err
+	}
+	var raw rawContent
+	if err := c.doJSON(ctx, method, path, nil, payload, &raw); err != nil {
+		return nil, err
+	}
+	return c.mapPage(raw), nil
+}
diff --git a/internal/apiclient/versions_test.go b/internal/apiclient/versions_test.go
new file mode 100644
index 0000000..69e344a
--- /dev/null
+++ b/internal/apiclient/versions_test.go
@@ -0,0 +1,110 @@
+package apiclient
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+func TestListPageVersions(t *testing.T) {
+	t.Parallel()
+	var gotPath string
+	c, _ := newTestClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"results":[
+			{"number":3,"when":"2025-03-01T00:00:00Z","message":"latest","minorEdit":false,
+			 "by":{"displayName":"Alice"}},
+			{"number":2,"when":"2025-02-01T00:00:00Z","by":{"displayName":"Bob"}}],
+			"size":2,"limit":25}`))
+	}))
+
+	res, err := c.ListPageVersions(context.Background(), "123", ListOpts{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if gotPath != "/rest/api/content/123/version" {
+		t.Errorf("path = %q", gotPath)
+	}
+	if len(res.Items) != 2 {
+		t.Fatalf("versions = %+v", res.Items)
+	}
+	if res.Items[0].Number != 3 || res.Items[0].By != "Alice" || res.Items[0].Message != "latest" {
+		t.Errorf("version[0] = %+v", res.Items[0])
+	}
+}
+
+// restoreServer is a Confluence stand-in covering the three GETs and one PUT a
+// restore performs.
+func restoreServer(t *testing.T, putBody *[]byte) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case r.Method == http.MethodGet && strings.HasSuffix(r.URL.Path, "/version/2"):
+			w.Write([]byte(`{"number":2,"content":{"id":"123","type":"page","title":"Doc",
+				"body":{"storage":{"value":"<p>v2 body</p>","representation":"storage"}}}}`))
+		case r.Method == http.MethodGet && r.URL.Path == "/rest/api/content/123":
+			w.Write([]byte(`{"id":"123","type":"page","title":"Doc","version":{"number":7}}`))
+		case r.Method == http.MethodPut:
+			*putBody = readAll(r)
+			w.Write([]byte(`{"id":"123","type":"page","title":"Doc","version":{"number":8}}`))
+		default:
+			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+		}
+	})
+}
+
+func TestRestorePage(t *testing.T) {
+	t.Parallel()
+	var putBody []byte
+	c, _ := newTestClient(t, restoreServer(t, &putBody))
+
+	page, err := c.RestorePage(context.Background(), RestorePageReq{ID: "123", Version: 2})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if page.Version == nil || page.Version.Number != 8 {
+		t.Errorf("restored page = %+v", page)
+	}
+	body := string(putBody)
+	// The restore must PUT the v2 body, bump the version to 8 and carry a
+	// default restore message.
+	for _, want := range []string{`v2 body`, `"number":8`, `Restored to version 2`} {
+		if !strings.Contains(body, want) {
+			t.Errorf("restore PUT missing %q: %s", want, body)
+		}
+	}
+}
+
+func TestRestorePageValidation(t *testing.T) {
+	t.Parallel()
+	c, _ := newTestClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
+	if _, err := c.RestorePage(context.Background(), RestorePageReq{Version: 1}); err == nil {
+		t.Error("expected error for missing page ID")
+	}
+	if _, err := c.RestorePage(context.Background(), RestorePageReq{ID: "1"}); err == nil {
+		t.Error("expected error for missing version")
+	}
+}
+
+func TestDescribeWriteRestore(t *testing.T) {
+	t.Parallel()
+	var putBody []byte
+	c, srv := newTestClient(t, restoreServer(t, &putBody))
+
+	plan, err := c.DescribeWrite(context.Background(), RestorePageReq{ID: "123", Version: 2})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if plan.Method != http.MethodPut || plan.URL != srv.URL+"/rest/api/content/123" {
+		t.Errorf("plan = %s %s", plan.Method, plan.URL)
+	}
+	if putBody != nil {
+		t.Error("dry-run must not send the PUT")
+	}
+	if plan.Payload == nil {
+		t.Error("payload should be populated")
+	}
+}
diff --git a/internal/apiclient/watch.go b/internal/apiclient/watch.go
new file mode 100644
index 0000000..f5d58f9
--- /dev/null
+++ b/internal/apiclient/watch.go
@@ -0,0 +1,53 @@
+package apiclient
+
+import (
+	"context"
+	"net/url"
+
+	cerrors "github.com/angelmsger/confluence-cli/internal/errors"
+)
+
+// watch.go holds the page-watch operations for the authenticated user. The
+// v1 user-watch endpoints act on the credentialed user when no user is passed,
+// so no current-user resolution is needed.
+
+// watchPath returns the user-watch endpoint for a content ID.
+func (c *apiClient) watchPath(pageID string) string {
+	return c.v1Base() + "/user/watch/content/" + url.PathEscape(pageID)
+}
+
+// WatchStatus reports whether the authenticated user watches a page.
+func (c *apiClient) WatchStatus(ctx context.Context, pageID string) (bool, error) {
+	if pageID == "" {
+		return false, cerrors.New(cerrors.CategoryUsage, "WATCH_NO_PAGE",
+			"a page ID is required to check watch status")
+	}
+	var raw rawWatch
+	if err := c.getJSON(ctx, c.watchPath(pageID), nil, &raw); err != nil {
+		return false, err
+	}
+	return raw.Watching, nil
+}
+
+// buildSetWatch assembles the request that starts or stops watching a page.
+func (c *apiClient) buildSetWatch(req WatchReq) (method, path string, err error) {
+	if req.PageID == "" {
+		return "", "", cerrors.New(cerrors.CategoryUsage, "WATCH_NO_PAGE",
+			"a page ID is required to change watch status")
+	}
+	method = "DELETE"
+	if req.Watching {
+		method = "POST"
+	}
+	return method, c.watchPath(req.PageID), nil
+}
+
+// SetWatch starts (Watching=true) or stops (Watching=false) the authenticated
+// user watching a page.
+func (c *apiClient) SetWatch(ctx context.Context, req WatchReq) error {
+	method, path, err := c.buildSetWatch(req)
+	if err != nil {
+		return err
+	}
+	return c.doJSON(ctx, method, path, nil, nil, nil)
+}
diff --git a/internal/apiclient/watch_test.go b/internal/apiclient/watch_test.go
new file mode 100644
index 0000000..39241d3
--- /dev/null
+++ b/internal/apiclient/watch_test.go
@@ -0,0 +1,91 @@
+package apiclient
+
+import (
+	"context"
+	"net/http"
+	"testing"
+)
+
+func TestWatchStatus(t *testing.T) {
+	t.Parallel()
+	var gotPath string
+	c, _ := newTestClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"watching":true}`))
+	}))
+
+	watching, err := c.WatchStatus(context.Background(), "123")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if gotPath != "/rest/api/user/watch/content/123" {
+		t.Errorf("path = %q", gotPath)
+	}
+	if !watching {
+		t.Error("expected watching = true")
+	}
+}
+
+func TestSetWatch(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name     string
+		watching bool
+		method   string
+	}{
+		{"watch", true, http.MethodPost},
+		{"unwatch", false, http.MethodDelete},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			var got string
+			c, _ := newTestClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				got = r.Method + " " + r.URL.Path
+				w.WriteHeader(http.StatusNoContent)
+			}))
+			err := c.SetWatch(context.Background(), WatchReq{PageID: "123", Watching: tc.watching})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got != tc.method+" /rest/api/user/watch/content/123" {
+				t.Errorf("request = %q", got)
+			}
+		})
+	}
+}
+
+func TestWatchValidation(t *testing.T) {
+	t.Parallel()
+	c, _ := newTestClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
+	if _, err := c.WatchStatus(context.Background(), ""); err == nil {
+		t.Error("expected error for missing page ID")
+	}
+	if err := c.SetWatch(context.Background(), WatchReq{Watching: true}); err == nil {
+		t.Error("expected error for missing page ID")
+	}
+}
+
+func TestDescribeWriteWatch(t *testing.T) {
+	t.Parallel()
+	c, srv := newTestClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		t.Errorf("dry-run must not send a request: %s %s", r.Method, r.URL.Path)
+	}))
+
+	plan, err := c.DescribeWrite(context.Background(), WatchReq{PageID: "123", Watching: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if plan.Method != http.MethodPost || plan.URL != srv.URL+"/rest/api/user/watch/content/123" {
+		t.Errorf("watch plan = %s %s", plan.Method, plan.URL)
+	}
+
+	rm, err := c.DescribeWrite(context.Background(), WatchReq{PageID: "123", Watching: false})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rm.Method != http.MethodDelete {
+		t.Errorf("unwatch plan method = %s", rm.Method)
+	}
+}
diff --git a/internal/app/app_test.go b/internal/app/app_test.go
index f0434fc..3cd2d01 100644
--- a/internal/app/app_test.go
+++ b/internal/app/app_test.go
@@ -39,6 +39,23 @@ func mockConfluence(t *testing.T) *httptest.Server {
 		w.WriteHeader(http.StatusNotFound)
 		w.Write([]byte(`{"message":"No content found"}`))
 	})
+	mux.HandleFunc("/rest/api/content/123/version", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(`{"results":[
+			{"number":2,"when":"2025-02-01T00:00:00Z","message":"edit","by":{"displayName":"Bob"}},
+			{"number":1,"when":"2025-01-01T00:00:00Z","by":{"displayName":"Alice"}}],
+			"size":2,"limit":25}`))
+	})
+	mux.HandleFunc("/rest/api/content/123/version/1", func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(`{"number":1,"content":{"id":"123","type":"page","title":"Welcome",
+			"body":{"storage":{"value":"<p>v1 body</p>","representation":"storage"}}}}`))
+	})
+	mux.HandleFunc("/rest/api/user/watch/content/123", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodGet {
+			w.Write([]byte(`{"watching":true}`))
+			return
+		}
+		w.WriteHeader(http.StatusNoContent)
+	})
 	mux.HandleFunc("/rest/api/content/att900", func(w http.ResponseWriter, r *http.Request) {
 		w.Write([]byte(`{"id":"att900","type":"attachment","title":"notes.txt",
 			"container":{"id":"123"},"extensions":{"fileSize":5}}`))
diff --git a/internal/app/page.go b/internal/app/page.go
index 5e77b36..8343875 100644
--- a/internal/app/page.go
+++ b/internal/app/page.go
@@ -46,6 +46,8 @@ func newPageCmd(s *appState) *cobra.Command {
 		newPageGetCmd(s), newPageChildrenCmd(s), newPageDescendantsCmd(s),
 		newPageCreateCmd(s), newPageUpdateCmd(s), newPageDeleteCmd(s),
 		newPageMoveCmd(s), newPageCopyCmd(s),
+		newPageHistoryCmd(s), newPageRestoreCmd(s),
+		newPageWatchCmd(s), newPageUnwatchCmd(s), newPageWatchStatusCmd(s),
 	)
 	return cmd
 }
diff --git a/internal/app/page_history.go b/internal/app/page_history.go
new file mode 100644
index 0000000..0459e99
--- /dev/null
+++ b/internal/app/page_history.go
@@ -0,0 +1,91 @@
+package app
+
+import (
+	"github.com/angelmsger/confluence-cli/internal/apiclient"
+	cerrors "github.com/angelmsger/confluence-cli/internal/errors"
+	"github.com/spf13/cobra"
+)
+
+func newPageHistoryCmd(s *appState) *cobra.Command {
+	var (
+		limit int
+		all   bool
+	)
+	cmd := &cobra.Command{
+		Use:   "history <id|url>",
+		Short: "List a page's version history",
+		Example: "  confluence-cli page history 123456\n" +
+			"  confluence-cli page history 123456 --all --format table",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			id, err := resolveID(args[0])
+			if err != nil {
+				return err
+			}
+			ctx, cancel := cmdContext(s)
+			defer cancel()
+			client, err := s.newClient(ctx)
+			if err != nil {
+				return err
+			}
+			items, err := collectList(func(cursor string) (apiclient.ListResult[apiclient.PageVersion], error) {
+				return client.ListPageVersions(ctx, id, apiclient.ListOpts{Limit: limit, Cursor: cursor})
+			}, limit, all)
+			if err != nil {
+				return err
+			}
+			return s.emit(items)
+		},
+	}
+	cmd.Flags().IntVar(&limit, "limit", 0, "page size (default from config)")
+	cmd.Flags().BoolVar(&all, "all", false, "fetch every page of results")
+	return cmd
+}
+
+func newPageRestoreCmd(s *appState) *cobra.Command {
+	var (
+		version int
+		message string
+		dryRun  bool
+	)
+	cmd := &cobra.Command{
+		Use:   "restore <id|url> --version <N>",
+		Short: "Restore a page to an earlier version",
+		Long: "Republish an earlier version's body as a new version. The restore is\n" +
+			"non-destructive: the version history is left intact. Run `page history`\n" +
+			"first to find the version number to restore.",
+		Example: "  confluence-cli page restore 123456 --version 3\n" +
+			"  confluence-cli page restore 123456 --version 3 --message \"roll back bad edit\"",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			id, err := resolveID(args[0])
+			if err != nil {
+				return err
+			}
+			if version <= 0 {
+				return cerrors.New(cerrors.CategoryUsage, "RESTORE_NO_VERSION",
+					"--version must be a positive version number to restore")
+			}
+			ctx, cancel := cmdContext(s)
+			defer cancel()
+			client, err := s.newClient(ctx)
+			if err != nil {
+				return err
+			}
+			req := apiclient.RestorePageReq{ID: id, Version: version, Message: message}
+			if dryRun {
+				return emitDryRun(s, client, ctx, req)
+			}
+			page, err := client.RestorePage(ctx, req)
+			if err != nil {
+				return err
+			}
+			return s.emit(pageMetaOutput(page))
+		},
+	}
+	f := cmd.Flags()
+	f.IntVar(&version, "version", 0, "the version number to restore")
+	f.StringVar(&message, "message", "", "version comment for the restore")
+	f.BoolVar(&dryRun, "dry-run", false, "print the request without sending it")
+	return cmd
+}
diff --git a/internal/app/page_watch.go b/internal/app/page_watch.go
new file mode 100644
index 0000000..bdd54a7
--- /dev/null
+++ b/internal/app/page_watch.go
@@ -0,0 +1,84 @@
+package app
+
+import (
+	"github.com/angelmsger/confluence-cli/internal/apiclient"
+	"github.com/spf13/cobra"
+)
+
+// watchOutput is the result shape for the page-watch commands.
+type watchOutput struct {
+	PageID   string `json:"page_id"`
+	Watching bool   `json:"watching"`
+}
+
+// newPageSetWatchCmd builds `page watch` or `page unwatch`; watching selects
+// which.
+func newPageSetWatchCmd(s *appState, watching bool) *cobra.Command {
+	use, short, example := "watch <id|url>",
+		"Watch a page (subscribe to its notifications)",
+		"  confluence-cli page watch 123456"
+	if !watching {
+		use, short, example = "unwatch <id|url>",
+			"Stop watching a page",
+			"  confluence-cli page unwatch 123456"
+	}
+	var dryRun bool
+	cmd := &cobra.Command{
+		Use:     use,
+		Short:   short,
+		Example: example,
+		Args:    cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			id, err := resolveID(args[0])
+			if err != nil {
+				return err
+			}
+			ctx, cancel := cmdContext(s)
+			defer cancel()
+			client, err := s.newClient(ctx)
+			if err != nil {
+				return err
+			}
+			req := apiclient.WatchReq{PageID: id, Watching: watching}
+			if dryRun {
+				return emitDryRun(s, client, ctx, req)
+			}
+			if err := client.SetWatch(ctx, req); err != nil {
+				return err
+			}
+			return s.emit(watchOutput{PageID: id, Watching: watching})
+		},
+	}
+	cmd.Flags().BoolVar(&dryRun, "dry-run", false, "print the request without sending it")
+	return cmd
+}
+
+func newPageWatchCmd(s *appState) *cobra.Command   { return newPageSetWatchCmd(s, true) }
+func newPageUnwatchCmd(s *appState) *cobra.Command { return newPageSetWatchCmd(s, false) }
+
+func newPageWatchStatusCmd(s *appState) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "watch-status <id|url>",
+		Short:   "Report whether you watch a page",
+		Example: "  confluence-cli page watch-status 123456",
+		Args:    cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			id, err := resolveID(args[0])
+			if err != nil {
+				return err
+			}
+			ctx, cancel := cmdContext(s)
+			defer cancel()
+			client, err := s.newClient(ctx)
+			if err != nil {
+				return err
+			}
+			watching, err := client.WatchStatus(ctx, id)
+			if err != nil {
+				return err
+			}
+			return s.emit(watchOutput{PageID: id, Watching: watching})
+		},
+	}
+	return cmd
+}
diff --git a/internal/app/writes_test.go b/internal/app/writes_test.go
index 3279108..382d481 100644
--- a/internal/app/writes_test.go
+++ b/internal/app/writes_test.go
@@ -154,3 +154,95 @@ func TestCmdLabelRemoveDryRun(t *testing.T) {
 		t.Errorf("url = %v", got["url"])
 	}
 }
+
+func TestCmdPageHistory(t *testing.T) {
+	srv := mockConfluence(t)
+	out, err := runCLI(t, srv, "page", "history", "123")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got []map[string]any
+	if err := json.Unmarshal([]byte(out), &got); err != nil {
+		t.Fatalf("output not a JSON array: %v\n%s", err, out)
+	}
+	if len(got) != 2 || got[0]["number"].(float64) != 2 {
+		t.Errorf("versions = %v", got)
+	}
+}
+
+func TestCmdPageRestoreDryRun(t *testing.T) {
+	srv := mockConfluence(t)
+	out, err := runCLI(t, srv, "page", "restore", "123", "--version", "1", "--dry-run")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]any
+	json.Unmarshal([]byte(out), &got)
+	if got["dry_run"] != true || got["method"] != "PUT" {
+		t.Errorf("dry-run output = %v", got)
+	}
+}
+
+func TestCmdPageRestore(t *testing.T) {
+	srv := mockConfluence(t)
+	out, err := runCLI(t, srv, "page", "restore", "123", "--version", "1")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]any
+	json.Unmarshal([]byte(out), &got)
+	if got["id"] != "123" {
+		t.Errorf("restored page = %v", got)
+	}
+}
+
+func TestCmdPageRestoreNoVersion(t *testing.T) {
+	srv := mockConfluence(t)
+	if _, err := runCLI(t, srv, "page", "restore", "123"); err == nil {
+		t.Fatal("expected an error when --version is missing")
+	}
+}
+
+func TestCmdPageWatch(t *testing.T) {
+	srv := mockConfluence(t)
+	for _, tc := range []struct {
+		cmd      string
+		watching bool
+	}{{"watch", true}, {"unwatch", false}} {
+		out, err := runCLI(t, srv, "page", tc.cmd, "123")
+		if err != nil {
+			t.Fatalf("%s: %v", tc.cmd, err)
+		}
+		var got map[string]any
+		json.Unmarshal([]byte(out), &got)
+		if got["page_id"] != "123" || got["watching"] != tc.watching {
+			t.Errorf("%s output = %v", tc.cmd, got)
+		}
+	}
+}
+
+func TestCmdPageWatchStatus(t *testing.T) {
+	srv := mockConfluence(t)
+	out, err := runCLI(t, srv, "page", "watch-status", "123")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]any
+	json.Unmarshal([]byte(out), &got)
+	if got["watching"] != true {
+		t.Errorf("watch-status output = %v", got)
+	}
+}
+
+func TestCmdPageWatchDryRun(t *testing.T) {
+	srv := mockConfluence(t)
+	out, err := runCLI(t, srv, "page", "watch", "123", "--dry-run")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]any
+	json.Unmarshal([]byte(out), &got)
+	if got["dry_run"] != true || got["method"] != "POST" {
+		t.Errorf("dry-run output = %v", got)
+	}
+}
diff --git a/skills/confluence/SKILL.md b/skills/confluence/SKILL.md
index f165b2a..d68113d 100644
--- a/skills/confluence/SKILL.md
+++ b/skills/confluence/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: confluence
-version: 1.3.0
-description: "Use a Confluence wiki as an external knowledge base. Search, read and summarise Confluence pages, browse spaces and page trees, create and edit pages, read and post comments, upload and manage file attachments, and manage page labels. Use this skill when the user gives a Confluence page URL or ID, mentions a Confluence/wiki page, asks to find or look up something in Confluence, asks to read/summarise/extract a Confluence page, browse a space, list child pages, create/update/delete/move/copy a page, read page comments, post a comment, upload/replace/delete an attachment, or add/remove page labels. Works with both Confluence Cloud and Confluence Data Center / Server."
+version: 1.4.0
+description: "Use a Confluence wiki as an external knowledge base. Search, read and summarise Confluence pages, browse spaces and page trees, create and edit pages, view version history and restore earlier versions, read and post comments, upload and manage file attachments, manage page labels, and watch pages. Use this skill when the user gives a Confluence page URL or ID, mentions a Confluence/wiki page, asks to find or look up something in Confluence, asks to read/summarise/extract a Confluence page, browse a space, list child pages, create/update/delete/move/copy a page, view a page's history or restore an old version, read page comments, post a comment, upload/replace/delete an attachment, add/remove page labels, or watch/unwatch a page. Works with both Confluence Cloud and Confluence Data Center / Server."
 metadata:
   requires:
     bins: ["confluence-cli"]
@@ -30,6 +30,11 @@ guess an ID — run `confluence-cli search` first, then act on the ID from the h
 - User wants the structure under a page → `page children` / `page descendants`.
 - User wants to **create, edit, delete, move or copy** a page → `page create` /
   `update` / `delete` / `move` / `copy` (see [writing-pages.md](references/writing-pages.md)).
+- User wants a page's **version history**, or to **roll back** a page →
+  `page history` / `page restore --version N` (see
+  [writing-pages.md](references/writing-pages.md)).
+- User wants to **watch / unwatch** a page, or check if they watch it →
+  `page watch` / `page unwatch` / `page watch-status`.
 - User wants the **comments** on a page → `comment list`; to post one →
   `comment add` (see [comments.md](references/comments.md)).
 - User wants files on a page → `attachment list` / `attachment download`; to
@@ -53,6 +58,9 @@ confluence-cli page update <id|url>       # edit a page's title / body
 confluence-cli page delete <id|url>       # trash a page (needs --yes)
 confluence-cli page move <id|url>         # reparent / move to another space
 confluence-cli page copy <id|url>         # shallow-copy a page
+confluence-cli page history <id|url>      # list a page's version history
+confluence-cli page restore <id|url>      # restore an old version (--version N)
+confluence-cli page watch <id|url>        # watch / unwatch / check watch status
 confluence-cli search [cql]               # CQL search, or use --text/--author/...
 confluence-cli space list                 # list spaces
 confluence-cli space get <key>            # one space
@@ -87,9 +95,9 @@ Only fall back to `--scope full` when the whole page is genuinely needed.
 
 ## Large result sets
 
-`search`, `page children/descendants`, `comment list`, `attachment list` and
-`label list` return one page of results by default and print a stderr note
-when more exist.
+`search`, `page children/descendants`, `page history`, `comment list`,
+`attachment list` and `label list` return one page of results by default and
+print a stderr note when more exist.
 Add `--all` to fetch every page, or `--limit N` to size each request. For very
 large outputs use `--format ndjson` (one JSON object per line).
 
diff --git a/skills/confluence/references/writing-pages.md b/skills/confluence/references/writing-pages.md
index a2edbda..85923c1 100644
--- a/skills/confluence/references/writing-pages.md
+++ b/skills/confluence/references/writing-pages.md
@@ -71,3 +71,29 @@ confluence-cli page copy 12345 --title "Copy of Plan" --space DOCS
 
 `move` reparents a page and/or moves it to another space. `copy` is **shallow**:
 it duplicates the title and body only — not child pages or attachments.
+
+## Version history and restore
+
+```bash
+# list a page's versions (newest first)
+confluence-cli page history 12345
+
+# restore the page to an earlier version
+confluence-cli page history 12345                       # find the version number
+confluence-cli page restore 12345 --version 3
+confluence-cli page restore 12345 --version 3 --message "roll back bad edit"
+```
+
+Each history entry has `number`, `when`, `by`, `message` and `minor_edit`.
+`restore` is **non-destructive**: it republishes the chosen version's body as a
+new version, so the history is never lost. Use `--dry-run` to preview it.
+
+## Watching a page
+
+```bash
+confluence-cli page watch 12345          # subscribe to the page's notifications
+confluence-cli page unwatch 12345        # unsubscribe
+confluence-cli page watch-status 12345   # report whether you watch the page
+```
+
+These act on the user behind the configured credentials.