From 03274532ec5097307ef44daab8a406950edb39f2 Mon Sep 17 00:00:00 2001
From: Dov Benyomin Sohacheski <b@kloud.email>
Date: Wed, 1 Jul 2026 14:02:41 +0300
Subject: [PATCH 1/4] =?UTF-8?q?=E2=9C=A8=20Generate=20ws-cli=20command=20m?=
 =?UTF-8?q?anifest=20for=20ws-docs=20distribution?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Walk the cobra tree into a single nested, alphabetically-sorted
commands.yaml via a tools/gen-commands generator (internals/docs);
golden + twice-serialize determinism tests pin the artifact. Add
sync-commands.yaml to push it to ws-meta as a new distribution origin.
Sort GetTemplateNames so template help and the manifest are stable.
---
 .github/workflows/sync-commands.yaml |  19 ++
 cmd/commands_test.go                 |  31 +++
 cmd/root.go                          |   4 +
 commands.yaml                        | 368 +++++++++++++++++++++++++++
 internals/docs/serialize.go          |  73 ++++++
 internals/template/template.go       |   3 +
 tools/gen-commands/main.go           |  22 ++
 7 files changed, 520 insertions(+)
 create mode 100644 .github/workflows/sync-commands.yaml
 create mode 100644 cmd/commands_test.go
 create mode 100644 commands.yaml
 create mode 100644 internals/docs/serialize.go
 create mode 100644 tools/gen-commands/main.go

diff --git a/.github/workflows/sync-commands.yaml b/.github/workflows/sync-commands.yaml
new file mode 100644
index 0000000..d0a33c5
--- /dev/null
+++ b/.github/workflows/sync-commands.yaml
@@ -0,0 +1,19 @@
+---
+name: 🔄 Sync commands to ws-meta
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - commands.yaml
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 🔄 Sync to ws-meta
+        uses: kloudkit/ws-meta/.github/actions/sync@main
+        with:
+          token: ${{ secrets.KLOUD_BOT_ORG_PAT }}
+          files: |
+            commands.yaml
diff --git a/cmd/commands_test.go b/cmd/commands_test.go
new file mode 100644
index 0000000..9010611
--- /dev/null
+++ b/cmd/commands_test.go
@@ -0,0 +1,31 @@
+package cmd_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/kloudkit/ws-cli/cmd"
+	"github.com/kloudkit/ws-cli/internals/docs"
+	"gotest.tools/v3/assert"
+)
+
+func TestCommandsManifestMatchesCommittedFile(t *testing.T) {
+	want, err := os.ReadFile(filepath.Join("..", "commands.yaml"))
+	assert.NilError(t, err)
+
+	got, err := docs.Serialize(cmd.RootCmd())
+	assert.NilError(t, err)
+
+	assert.Equal(t, string(got), string(want))
+}
+
+func TestSerializeIsDeterministic(t *testing.T) {
+	first, err := docs.Serialize(cmd.RootCmd())
+	assert.NilError(t, err)
+
+	second, err := docs.Serialize(cmd.RootCmd())
+	assert.NilError(t, err)
+
+	assert.Equal(t, string(first), string(second))
+}
diff --git a/cmd/root.go b/cmd/root.go
index 1027623..93fddf2 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -32,6 +32,10 @@ var rootCmd = &cobra.Command{
 	},
 }
 
+func RootCmd() *cobra.Command {
+	return rootCmd
+}
+
 func Execute() {
 	ctx := context.Background()
 
diff --git a/commands.yaml b/commands.yaml
new file mode 100644
index 0000000..687967b
--- /dev/null
+++ b/commands.yaml
@@ -0,0 +1,368 @@
+name: ws-cli
+synopsis: ⚡ CLI companion to charge the workspace batteries
+aliases:
+    - ws
+commands:
+    - name: ws-cli clip
+      synopsis: Interact with the native clipboard
+      commands:
+        - name: ws-cli clip paste
+          synopsis: Paste clipboard content
+          usage: ws-cli clip paste
+    - name: ws-cli editor
+      synopsis: Inspect and drive the active editor session
+      options:
+        - name: raw
+          default: "false"
+          usage: Output the raw JSON response without styling
+      commands:
+        - name: ws-cli editor diagnostics
+          synopsis: Show language diagnostics for the workspace (or a single file)
+          usage: ws-cli editor diagnostics [flags]
+          options:
+            - name: uri
+              usage: Filter to a single file (URI or absolute path)
+        - name: ws-cli editor list
+          synopsis: List the currently open editor tabs
+          usage: ws-cli editor list
+        - name: ws-cli editor open
+          synopsis: Open a file in the editor
+          usage: ws-cli editor open <file> [flags]
+          options:
+            - name: new-window
+              default: "false"
+              usage: Open in a new window
+            - name: preview
+              default: "false"
+              usage: Open as a preview tab (reuse-window only)
+            - name: reuse-window
+              default: "false"
+              usage: Open in the current window as a tab (default)
+            - name: selection
+              usage: 'Select a range: LINE:COL[-LINE:COL] (1-based)'
+        - name: ws-cli editor selection
+          synopsis: Show the active editor's current selection
+          usage: ws-cli editor selection
+    - name: ws-cli feature
+      synopsis: Install additional pre-configured features
+      options:
+        - name: root
+          default: /usr/share/workspace/features.d
+          usage: Root directory of additional features
+      commands:
+        - name: ws-cli feature info
+          synopsis: Show detailed information about a feature
+          usage: ws-cli feature info <name>
+        - name: ws-cli feature install
+          synopsis: Install additional pre-configured features
+          usage: ws-cli feature install [flags]
+          options:
+            - name: opt
+              default: '[]'
+              usage: Optional variables to use during installation
+            - name: skip-completion
+              default: "false"
+              usage: Skip configuring shell completion
+            - name: skip-extensions
+              default: "false"
+              usage: Skip installing VSCode extensions
+            - name: skip-repository
+              default: "false"
+              usage: Skip enabling the vendor APT repository
+        - name: ws-cli feature list
+          synopsis: List available features that can be installed
+          usage: ws-cli feature list
+          aliases:
+            - ls
+        - name: ws-cli feature new
+          synopsis: Print boilerplate for a custom feature playbook
+          description: |-
+            Print a starter feature playbook to stdout.
+
+            Redirect it into ~/.ws/features.d/<name>.yaml, then extend it and install
+            with "ws-cli feature install <name>":
+
+              ws-cli feature new redis > ~/.ws/features.d/redis.yaml
+          usage: ws-cli feature new [name]
+        - name: ws-cli feature store
+          synopsis: List packages available in the feature store
+          usage: ws-cli feature store
+    - name: ws-cli info
+      synopsis: Display workspace information
+      commands:
+        - name: ws-cli info env
+          synopsis: Display effective workspace environment variables
+          usage: ws-cli info env
+        - name: ws-cli info extensions
+          synopsis: Display installed extensions
+          usage: ws-cli info extensions
+        - name: ws-cli info metrics
+          synopsis: Display workspace metrics
+          usage: ws-cli info metrics [flags]
+          options:
+            - name: gpu
+              default: "false"
+              usage: Include GPU metrics
+        - name: ws-cli info uptime
+          synopsis: Display the workspace uptime
+          usage: ws-cli info uptime
+        - name: ws-cli info version
+          synopsis: Display installed workspace version
+          usage: ws-cli info version [flags]
+          options:
+            - name: all
+              default: "false"
+              usage: Show all version information
+    - name: ws-cli log
+      synopsis: Log messages
+      options:
+        - name: pipe
+          shorthand: p
+          default: "false"
+          usage: Loop through piped output
+      commands:
+        - name: ws-cli log debug
+          synopsis: Log debugging messages
+          usage: ws-cli log debug message [flags]
+          options:
+            - name: indent
+              shorthand: i
+              default: "0"
+              usage: Desired prefixed indentation
+            - name: stamp
+              shorthand: s
+              default: "false"
+              usage: Prefix message with current timestamp
+        - name: ws-cli log error
+          synopsis: Log error messages
+          usage: ws-cli log error message [flags]
+          options:
+            - name: indent
+              shorthand: i
+              default: "0"
+              usage: Desired prefixed indentation
+            - name: stamp
+              shorthand: s
+              default: "false"
+              usage: Prefix message with current timestamp
+        - name: ws-cli log info
+          synopsis: Log information messages
+          usage: ws-cli log info message [flags]
+          options:
+            - name: indent
+              shorthand: i
+              default: "0"
+              usage: Desired prefixed indentation
+            - name: stamp
+              shorthand: s
+              default: "false"
+              usage: Prefix message with current timestamp
+        - name: ws-cli log stamp
+          synopsis: Log the current timestamp
+          usage: ws-cli log stamp
+        - name: ws-cli log warn
+          synopsis: Log warning messages
+          usage: ws-cli log warn message [flags]
+          options:
+            - name: indent
+              shorthand: i
+              default: "0"
+              usage: Desired prefixed indentation
+            - name: stamp
+              shorthand: s
+              default: "false"
+              usage: Prefix message with current timestamp
+    - name: ws-cli logs
+      synopsis: Retrieve workspace logs
+      usage: ws-cli logs [flags]
+      options:
+        - name: follow
+          shorthand: f
+          default: "false"
+          usage: Follow log output in real-time
+        - name: level
+          shorthand: l
+          usage: Filter by log level (debug|info|warn|error)
+        - name: tail
+          shorthand: t
+          default: "0"
+          usage: Number of lines to show from the end (0 for all)
+        - name: target
+          default: main
+          usage: Log target to read (main|metrics|docker|auth_proxy|cloudflared)
+    - name: ws-cli secrets
+      synopsis: Manage encryption and decryption of secrets
+      options:
+        - name: force
+          default: "false"
+          usage: Overwrite existing files
+        - name: master
+          usage: Master key or path to key file
+        - name: mode
+          usage: File permissions (e.g., 0o600, 384), only when --output is used
+        - name: output
+          usage: Write output to file instead of stdout
+        - name: raw
+          default: "false"
+          usage: Output without styling
+      commands:
+        - name: ws-cli secrets decrypt
+          synopsis: Decrypt an encrypted value
+          usage: ws-cli secrets decrypt <encrypted|->
+        - name: ws-cli secrets encrypt
+          synopsis: Encrypt a plaintext value
+          usage: ws-cli secrets encrypt <plaintext|->
+        - name: ws-cli secrets generate
+          synopsis: Generate master keys or login password hashes
+          commands:
+            - name: ws-cli secrets generate login
+              synopsis: Generate a workspace password hash for authentication
+              usage: ws-cli secrets generate login
+            - name: ws-cli secrets generate master
+              synopsis: Generate a cryptographically secure master key
+              usage: ws-cli secrets generate master [flags]
+              options:
+                - name: length
+                  default: "32"
+                  usage: Key length in bytes
+    - name: ws-cli seed
+      synopsis: Project declarative content onto the filesystem
+      options:
+        - name: source
+          usage: Seed source directory
+      commands:
+        - name: ws-cli seed apply
+          synopsis: Project seed content onto the filesystem
+          usage: ws-cli seed apply [dest...] [flags]
+          options:
+            - name: force
+              default: "false"
+              usage: Overwrite existing destinations
+            - name: master
+              usage: Master key or path to key file
+        - name: ws-cli seed ls
+          synopsis: List seed destinations and their behaviors
+          usage: ws-cli seed ls
+        - name: ws-cli seed rotate
+          synopsis: Re-encrypt managed secrets under a new master key
+          usage: ws-cli seed rotate [flags]
+          options:
+            - name: master
+              usage: Current master key or path to key file
+            - name: new-master
+              usage: New master key or path to key file
+    - name: ws-cli serve
+      synopsis: Serve internal assets
+      options:
+        - name: bind
+          default: 0.0.0.0
+          usage: Bind address
+        - name: port
+          shorthand: p
+          default: "38080"
+          usage: Port to serve assets on
+      commands:
+        - name: ws-cli serve current
+          synopsis: Serve current directory as a static site
+          usage: ws-cli serve current
+        - name: ws-cli serve current
+          synopsis: Serve current directory as a static site
+          usage: ws-cli serve current [flags]
+        - name: ws-cli serve font
+          synopsis: Serve fonts for local download
+          usage: ws-cli serve font
+        - name: ws-cli serve font
+          synopsis: Serve fonts for local download
+          usage: ws-cli serve font [flags]
+        - name: ws-cli serve metrics
+          synopsis: Start the Prometheus metrics server
+          usage: ws-cli serve metrics [flags]
+          options:
+            - name: collectors
+              default: '[*]'
+              usage: Comma-separated list of collectors to enable (e.g., workspace,container.cpu,gpu)
+            - name: port
+              shorthand: p
+              default: "9100"
+              usage: Port to serve metrics on
+    - name: ws-cli show
+      synopsis: Display information about the current workspace instance
+      options:
+        - name: raw
+          default: "false"
+          usage: Output raw value without styling
+      commands:
+        - name: ws-cli show env
+          synopsis: Display the resolved value of a workspace environment variable
+          usage: ws-cli show env <KEY> [flags]
+          options:
+            - name: as
+              usage: 'Validate and emit as one of: bool, int, list (mutex with --value)'
+            - name: check
+              default: "false"
+              usage: Check whether the variable (or its --deprecated alias) is set
+            - name: delimiter
+              usage: Override delimiter for --as=list (defaults to YAML delimiter or space)
+            - name: deprecated
+              usage: Deprecated alias paired with --check
+            - name: or-skip
+              default: "false"
+              usage: Exit 1 (not error) on the natural absence of the chosen projection
+            - name: validate
+              usage: Anchored regex each --as=list token must full-match; rejects fail-closed
+            - name: value
+              default: "false"
+              usage: Emit the raw resolved value as a single line
+        - name: ws-cli show ip
+          synopsis: Display IP addresses
+          commands:
+            - name: ws-cli show ip internal
+              synopsis: Display the internal IP address
+              usage: ws-cli show ip internal
+            - name: ws-cli show ip node
+              synopsis: Display the node/host IP address
+              usage: ws-cli show ip node
+        - name: ws-cli show path
+          synopsis: Display various paths
+          commands:
+            - name: ws-cli show path home
+              synopsis: Display the workspace home path
+              usage: ws-cli show path home
+            - name: ws-cli show path vscode-settings
+              synopsis: Display the VS Code settings path
+              usage: ws-cli show path vscode-settings [flags]
+              options:
+                - name: workspace
+                  default: "false"
+                  usage: Get the workspace settings
+    - name: ws-cli template
+      synopsis: Manage static configuration files
+      description: Copy and manage configuration files stored in global locations
+      commands:
+        - name: ws-cli template apply
+          synopsis: Apply a configuration template to the current project
+          usage: ws-cli template apply <template> [flags]
+          options:
+            - name: force
+              shorthand: f
+              default: "false"
+              usage: Overwrite existing files
+            - name: path
+              default: .
+              usage: Target directory path
+        - name: ws-cli template list
+          synopsis: List all available configuration templates
+          usage: ws-cli template list
+          aliases:
+            - ls
+        - name: ws-cli template show
+          synopsis: Display the contents of a configuration template
+          description: |-
+            Display the contents of a configuration template.
+
+              Available templates: ansible, markdownlint, ruff, yamllint
+          usage: ws-cli template show <template> [flags]
+          options:
+            - name: local
+              default: "false"
+              usage: Show the local version of the template (if applied)
diff --git a/internals/docs/serialize.go b/internals/docs/serialize.go
new file mode 100644
index 0000000..c6d4e08
--- /dev/null
+++ b/internals/docs/serialize.go
@@ -0,0 +1,73 @@
+package docs
+
+import (
+	"sort"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+	"gopkg.in/yaml.v3"
+)
+
+type Option struct {
+	Name      string `yaml:"name"`
+	Shorthand string `yaml:"shorthand,omitempty"`
+	Default   string `yaml:"default,omitempty"`
+	Usage     string `yaml:"usage,omitempty"`
+}
+
+type Command struct {
+	Name        string    `yaml:"name"`
+	Synopsis    string    `yaml:"synopsis,omitempty"`
+	Description string    `yaml:"description,omitempty"`
+	Usage       string    `yaml:"usage,omitempty"`
+	Aliases     []string  `yaml:"aliases,omitempty"`
+	Example     string    `yaml:"example,omitempty"`
+	Options     []Option  `yaml:"options,omitempty"`
+	Commands    []Command `yaml:"commands,omitempty"`
+}
+
+func Serialize(root *cobra.Command) ([]byte, error) {
+	return yaml.Marshal(walk(root))
+}
+
+func walk(c *cobra.Command) Command {
+	command := Command{
+		Name:        c.CommandPath(),
+		Synopsis:    c.Short,
+		Description: c.Long,
+		Aliases:     c.Aliases,
+		Example:     c.Example,
+	}
+
+	if c.Runnable() {
+		command.Usage = c.UseLine()
+	}
+
+	c.NonInheritedFlags().VisitAll(func(f *pflag.Flag) {
+		if f.Hidden {
+			return
+		}
+
+		command.Options = append(command.Options, Option{
+			Name:      f.Name,
+			Shorthand: f.Shorthand,
+			Default:   f.DefValue,
+			Usage:     f.Usage,
+		})
+	})
+
+	children := append([]*cobra.Command(nil), c.Commands()...)
+	sort.Slice(children, func(i, j int) bool {
+		return children[i].Name() < children[j].Name()
+	})
+
+	for _, child := range children {
+		if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
+			continue
+		}
+
+		command.Commands = append(command.Commands, walk(child))
+	}
+
+	return command
+}
diff --git a/internals/template/template.go b/internals/template/template.go
index b7c47a4..1b230c7 100644
--- a/internals/template/template.go
+++ b/internals/template/template.go
@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"sort"
 
 	"github.com/kloudkit/ws-cli/internals/io"
 	"github.com/kloudkit/ws-cli/internals/path"
@@ -46,6 +47,8 @@ func GetTemplateNames() []string {
 		names = append(names, name)
 	}
 
+	sort.Strings(names)
+
 	return names
 }
 
diff --git a/tools/gen-commands/main.go b/tools/gen-commands/main.go
new file mode 100644
index 0000000..a235fcf
--- /dev/null
+++ b/tools/gen-commands/main.go
@@ -0,0 +1,22 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/kloudkit/ws-cli/cmd"
+	"github.com/kloudkit/ws-cli/internals/docs"
+)
+
+func main() {
+	data, err := docs.Serialize(cmd.RootCmd())
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+
+	if err := os.WriteFile("commands.yaml", data, 0o644); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

From d050ae779b8c57cb1bcdbae3b1a5fdf4ae73ebd6 Mon Sep 17 00:00:00 2001
From: Dov Benyomin Sohacheski <b@kloud.email>
Date: Wed, 1 Jul 2026 14:11:55 +0300
Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=9D=20Add=20DX=20long=20descriptio?=
 =?UTF-8?q?ns=20to=20every=20ws-cli=20command?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Author plain-prose Long: help on each command and group — what it does
and when to reach for it — and regenerate commands.yaml so the manifest
(and, later, ws-docs) carries them. Long text flows through the log-level
and IP-command factories to stay DRY.
---
 cmd/clip/clip.go          |  1 +
 cmd/clip/paste.go         |  1 +
 cmd/editor/diagnostics.go |  1 +
 cmd/editor/editor.go      |  1 +
 cmd/editor/list.go        |  1 +
 cmd/editor/open.go        |  1 +
 cmd/editor/selection.go   |  1 +
 cmd/feature/feature.go    |  1 +
 cmd/feature/info.go       |  1 +
 cmd/feature/install.go    |  1 +
 cmd/feature/list.go       |  1 +
 cmd/feature/store.go      |  1 +
 cmd/info/env.go           |  1 +
 cmd/info/extensions.go    |  1 +
 cmd/info/info.go          |  2 ++
 cmd/info/metrics.go       |  1 +
 cmd/info/uptime.go        |  1 +
 cmd/log/log.go            |  3 +++
 cmd/logs/logs.go          |  1 +
 cmd/root.go               |  1 +
 cmd/secrets/decrypt.go    |  1 +
 cmd/secrets/encrypt.go    |  1 +
 cmd/secrets/generate.go   |  1 +
 cmd/secrets/login.go      |  1 +
 cmd/secrets/master.go     |  1 +
 cmd/secrets/secrets.go    |  1 +
 cmd/seed/apply.go         |  1 +
 cmd/seed/ls.go            |  1 +
 cmd/seed/rotate.go        |  1 +
 cmd/seed/seed.go          |  1 +
 cmd/serve/current.go      |  1 +
 cmd/serve/font.go         |  1 +
 cmd/serve/serve.go        |  1 +
 cmd/show/env.go           |  1 +
 cmd/show/ip.go            |  8 +++---
 cmd/show/ip_test.go       |  2 +-
 cmd/show/path.go          |  3 +++
 cmd/show/show.go          |  1 +
 cmd/template/apply.go     |  1 +
 cmd/template/list.go      |  1 +
 cmd/template/template.go  |  2 +-
 commands.yaml             | 53 ++++++++++++++++++++++++++++++++++++++-
 42 files changed, 102 insertions(+), 6 deletions(-)

diff --git a/cmd/clip/clip.go b/cmd/clip/clip.go
index 0eb7b6c..cbc1df6 100644
--- a/cmd/clip/clip.go
+++ b/cmd/clip/clip.go
@@ -7,4 +7,5 @@ import (
 var ClipCmd = &cobra.Command{
 	Use:   "clip",
 	Short: "Interact with the native clipboard",
+	Long:  "Reach the browser clipboard from the terminal over the workspace IPC socket.",
 }
diff --git a/cmd/clip/paste.go b/cmd/clip/paste.go
index 1a1b746..6cf1d9e 100644
--- a/cmd/clip/paste.go
+++ b/cmd/clip/paste.go
@@ -8,6 +8,7 @@ import (
 var pasteCmd = &cobra.Command{
 	Use:   "paste",
 	Short: "Paste clipboard content",
+	Long:  "Read the browser clipboard over the workspace IPC socket and write it to stdout — redirect it to a file or pipe it onward. Pairs with the pbcopy/xclip/xsel shims for terminal clipboard access.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		return clipboard.Paste(cmd.OutOrStdout())
 	},
diff --git a/cmd/editor/diagnostics.go b/cmd/editor/diagnostics.go
index 6e953e6..4a46b73 100644
--- a/cmd/editor/diagnostics.go
+++ b/cmd/editor/diagnostics.go
@@ -13,6 +13,7 @@ import (
 var diagnosticsCmd = &cobra.Command{
 	Use:   "diagnostics",
 	Short: "Show language diagnostics for the workspace (or a single file)",
+	Long:  "Pull language-server diagnostics (errors, warnings) from the editor over the IPC socket, across the whole workspace or a single file with --uri. Styled table by default, --raw for the JSON.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		uri, _ := cmd.Flags().GetString("uri")
 
diff --git a/cmd/editor/editor.go b/cmd/editor/editor.go
index b8a96f5..fa15623 100644
--- a/cmd/editor/editor.go
+++ b/cmd/editor/editor.go
@@ -18,6 +18,7 @@ var errNoEditorOverSSH = errors.New(
 var EditorCmd = &cobra.Command{
 	Use:   "editor",
 	Short: "Inspect and drive the active editor session",
+	Long:  "Query and control the running VS Code / code-server window over the workspace IPC socket — list open tabs, read diagnostics and the current selection, or open a file. Blocked over SSH, where there is no browser editor to reach.",
 	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 		if env.IsSSHSession() {
 			return errNoEditorOverSSH
diff --git a/cmd/editor/list.go b/cmd/editor/list.go
index 6dd43bc..f1b0f31 100644
--- a/cmd/editor/list.go
+++ b/cmd/editor/list.go
@@ -13,6 +13,7 @@ import (
 var listCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List the currently open editor tabs",
+	Long:  "List the editor's open tabs over the IPC socket, with each tab's path, language, and active or dirty state.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		body, err := editoripc.FetchEditors()
 		if err != nil {
diff --git a/cmd/editor/open.go b/cmd/editor/open.go
index 2ec2b9b..b80f31c 100644
--- a/cmd/editor/open.go
+++ b/cmd/editor/open.go
@@ -12,6 +12,7 @@ import (
 var openCmd = &cobra.Command{
 	Use:   "open <file>",
 	Short: "Open a file in the editor",
+	Long:  "Open a file in the running editor window over the workspace IPC socket — a tab in the current window by default, a separate one with --new-window, jumping to a range with --selection. Fails fast over SSH, where there is no browser editor to open into.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		newWindow, _ := cmd.Flags().GetBool("new-window")
diff --git a/cmd/editor/selection.go b/cmd/editor/selection.go
index 5151c0d..be2bced 100644
--- a/cmd/editor/selection.go
+++ b/cmd/editor/selection.go
@@ -13,6 +13,7 @@ import (
 var selectionCmd = &cobra.Command{
 	Use:   "selection",
 	Short: "Show the active editor's current selection",
+	Long:  "Report the active editor's current selection — file, range, and selected text — over the IPC socket. Empty when nothing is selected.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		body, err := editoripc.FetchSelection()
 		if err != nil {
diff --git a/cmd/feature/feature.go b/cmd/feature/feature.go
index 7870692..4afd7e2 100644
--- a/cmd/feature/feature.go
+++ b/cmd/feature/feature.go
@@ -9,6 +9,7 @@ import (
 var FeatureCmd = &cobra.Command{
 	Use:   "feature",
 	Short: "Install additional pre-configured features",
+	Long:  "Install and inspect optional workspace features — Ansible playbooks that add tools on top of the base image. Ships a curated set; --root points at your own under ~/.ws/features.d.",
 }
 
 func featureDirs(cmd *cobra.Command) []string {
diff --git a/cmd/feature/info.go b/cmd/feature/info.go
index afd636b..7ca7d2d 100644
--- a/cmd/feature/info.go
+++ b/cmd/feature/info.go
@@ -11,6 +11,7 @@ import (
 var infoCmd = &cobra.Command{
 	Use:   "info <name>",
 	Short: "Show detailed information about a feature",
+	Long:  "Show a feature's description and the variables it accepts, so you know what --opt values install will take.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		featureName := args[0]
diff --git a/cmd/feature/install.go b/cmd/feature/install.go
index 61b7930..002a4fc 100644
--- a/cmd/feature/install.go
+++ b/cmd/feature/install.go
@@ -25,6 +25,7 @@ var skippableSections = []struct {
 var installCmd = &cobra.Command{
 	Use:   "install",
 	Short: "Install additional pre-configured features",
+	Long:  "Run a feature's playbook to install it. Pass variables with --opt KEY=VAL, and skip parts you do not want with --skip-extensions, --skip-completion, or --skip-repository.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		featureName := args[0]
diff --git a/cmd/feature/list.go b/cmd/feature/list.go
index d79f9ec..4ac4144 100644
--- a/cmd/feature/list.go
+++ b/cmd/feature/list.go
@@ -11,6 +11,7 @@ import (
 var listCmd = &cobra.Command{
 	Use:     "list",
 	Short:   "List available features that can be installed",
+	Long:    "List the features you can install, marking where each comes from — the shipped set, a workspace override, or your own ~/.ws/features.d.",
 	Aliases: []string{"ls"},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		result, err := features.ListFeatures(featureDirs(cmd))
diff --git a/cmd/feature/store.go b/cmd/feature/store.go
index f6942d4..ed615a1 100644
--- a/cmd/feature/store.go
+++ b/cmd/feature/store.go
@@ -12,6 +12,7 @@ import (
 var storeCmd = &cobra.Command{
 	Use:   "store",
 	Short: "List packages available in the feature store",
+	Long:  "List the artifacts published to the feature store (WS_FEATURES_STORE_URL) — the offline mirror features install from when the network is locked down.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		storeURL, _ := config.Resolve("features", "store_url")
 		if storeURL == "" {
diff --git a/cmd/info/env.go b/cmd/info/env.go
index 6de5d98..689f686 100644
--- a/cmd/info/env.go
+++ b/cmd/info/env.go
@@ -33,6 +33,7 @@ func showEnvironment(writer io.Writer) {
 var envCmd = &cobra.Command{
 	Use:   "env",
 	Short: "Display effective workspace environment variables",
+	Long:  "Print every WS_* variable in effect, sorted — the resolved environment the workspace booted with.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		showEnvironment(cmd.OutOrStdout())
 		return nil
diff --git a/cmd/info/extensions.go b/cmd/info/extensions.go
index b8453a2..769d1d7 100644
--- a/cmd/info/extensions.go
+++ b/cmd/info/extensions.go
@@ -12,6 +12,7 @@ import (
 var extensionsCmd = &cobra.Command{
 	Use:   "extensions",
 	Short: "Display installed extensions",
+	Long:  "List the installed VS Code extensions with their versions.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		extensions, _ := config.GetExtensions()
 
diff --git a/cmd/info/info.go b/cmd/info/info.go
index e4195ff..0f569a8 100644
--- a/cmd/info/info.go
+++ b/cmd/info/info.go
@@ -36,11 +36,13 @@ func showVersion(writer io.Writer) {
 var InfoCmd = &cobra.Command{
 	Use:   "info",
 	Short: "Display workspace information",
+	Long:  "Report facts about the running workspace — version, effective environment, installed extensions, live resource metrics, and uptime.",
 }
 
 var showVersionCmd = &cobra.Command{
 	Use:   "version",
 	Short: "Display installed workspace version",
+	Long:  "Print the workspace version. --all expands to the full table — workspace, ws-cli, and VS Code.",
 	Run: func(cmd *cobra.Command, args []string) {
 		if all, _ := cmd.Flags().GetBool("all"); all {
 			showVersion(cmd.OutOrStdout())
diff --git a/cmd/info/metrics.go b/cmd/info/metrics.go
index 1d2563f..3179a7b 100644
--- a/cmd/info/metrics.go
+++ b/cmd/info/metrics.go
@@ -12,6 +12,7 @@ import (
 var metricsCmd = &cobra.Command{
 	Use:   "metrics",
 	Short: "Display workspace metrics",
+	Long:  "Show live resource usage — CPU, memory, disk, and file descriptors, plus GPU with --gpu.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		includeGPU, _ := cmd.Flags().GetBool("gpu")
 
diff --git a/cmd/info/uptime.go b/cmd/info/uptime.go
index a45683f..7b5d913 100644
--- a/cmd/info/uptime.go
+++ b/cmd/info/uptime.go
@@ -12,6 +12,7 @@ import (
 var uptimeCmd = &cobra.Command{
 	Use:   "uptime",
 	Short: "Display the workspace uptime",
+	Long:  "Show when the workspace session started and how long it has been running.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		started, running, err := config.GetSessionInfo()
 
diff --git a/cmd/log/log.go b/cmd/log/log.go
index c4a770a..83aac41 100644
--- a/cmd/log/log.go
+++ b/cmd/log/log.go
@@ -10,6 +10,7 @@ import (
 var LogCmd = &cobra.Command{
 	Use:   "log",
 	Short: "Log messages",
+	Long:  "Emit styled, level-tagged log lines — the same formatting the startup scripts use. --pipe runs each line of piped input through the logger.",
 }
 
 var debugCmd = createCommand("debug", "debugging")
@@ -19,6 +20,7 @@ var warnCmd = createCommand("warn", "warning")
 var stampCmd = &cobra.Command{
 	Use:   "stamp",
 	Short: "Log the current timestamp",
+	Long:  "Print just the current timestamp in the workspace log style — handy for marking phases in a startup log.",
 	Args:  cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		withPipe, _ := cmd.Flags().GetBool("pipe")
@@ -36,6 +38,7 @@ func createCommand(short, long string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   fmt.Sprintf("%s message", short),
 		Short: fmt.Sprintf("Log %s messages", long),
+		Long:  fmt.Sprintf("Emit a log line at %s level in the workspace style — the same formatting the startup scripts use. --indent nests it under a preceding line, --stamp prefixes a timestamp.", short),
 		Args:  validate,
 		RunE:  execute(short),
 	}
diff --git a/cmd/logs/logs.go b/cmd/logs/logs.go
index 05656c8..bb6dd25 100644
--- a/cmd/logs/logs.go
+++ b/cmd/logs/logs.go
@@ -17,6 +17,7 @@ var validLogTargets = []string{"main", "metrics", "docker", "auth_proxy", "cloud
 var LogsCmd = &cobra.Command{
 	Use:   "logs",
 	Short: "Retrieve workspace logs",
+	Long:  "Read a workspace daemon's log — the main log by default, or --target metrics|docker|auth_proxy|cloudflared. Filter by --level, limit with --tail, or stream live with --follow.",
 	Args:  cobra.NoArgs,
 	RunE:  execute,
 }
diff --git a/cmd/root.go b/cmd/root.go
index 93fddf2..ee663af 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -24,6 +24,7 @@ import (
 var rootCmd = &cobra.Command{
 	Use:           "ws-cli",
 	Short:         "⚡ CLI companion to charge the workspace batteries",
+	Long:          "The workspace command-line companion. Groups helpers for inspecting the running workspace, managing settings and secrets, driving the editor, and serving local assets — most are called by the startup scripts, all are yours in the terminal.",
 	Version:       "v" + info.Version,
 	Aliases:       []string{"ws"},
 	SilenceErrors: true,
diff --git a/cmd/secrets/decrypt.go b/cmd/secrets/decrypt.go
index 533b6f1..08e8753 100644
--- a/cmd/secrets/decrypt.go
+++ b/cmd/secrets/decrypt.go
@@ -9,6 +9,7 @@ import (
 var decryptCmd = &cobra.Command{
 	Use:   "decrypt <encrypted|->",
 	Short: "Decrypt an encrypted value",
+	Long:  "Decrypt a value produced by encrypt, under the master key. Reads from the argument or stdin (-); writes the plaintext to stdout, or a file with --output.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		cfg := getOutputConfig(cmd)
diff --git a/cmd/secrets/encrypt.go b/cmd/secrets/encrypt.go
index 12dc4c4..4a5b0f7 100644
--- a/cmd/secrets/encrypt.go
+++ b/cmd/secrets/encrypt.go
@@ -12,6 +12,7 @@ import (
 var encryptCmd = &cobra.Command{
 	Use:   "encrypt <plaintext|->",
 	Short: "Encrypt a plaintext value",
+	Long:  "Encrypt a value under the master key. Reads the plaintext from the argument or stdin (-); writes the ciphertext to stdout, or a file with --output.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		cfg := getOutputConfig(cmd)
diff --git a/cmd/secrets/generate.go b/cmd/secrets/generate.go
index 5c432b0..7ba92f0 100644
--- a/cmd/secrets/generate.go
+++ b/cmd/secrets/generate.go
@@ -5,6 +5,7 @@ import "github.com/spf13/cobra"
 var generateCmd = &cobra.Command{
 	Use:   "generate",
 	Short: "Generate master keys or login password hashes",
+	Long:  "Generate the credentials the workspace needs — a master key for secrets, or a login password hash for the server.",
 }
 
 func init() {
diff --git a/cmd/secrets/login.go b/cmd/secrets/login.go
index df6acd5..e635c75 100644
--- a/cmd/secrets/login.go
+++ b/cmd/secrets/login.go
@@ -13,6 +13,7 @@ import (
 var loginCmd = &cobra.Command{
 	Use:   "login",
 	Short: "Generate a workspace password hash for authentication",
+	Long:  "Prompt for a password and print its hash for the workspace server login (WS_AUTH_PASSWORD_HASHED). Store the hash, never the password.",
 	Args:  cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		cfg := getOutputConfig(cmd)
diff --git a/cmd/secrets/master.go b/cmd/secrets/master.go
index fb3a70b..4d2f3f2 100644
--- a/cmd/secrets/master.go
+++ b/cmd/secrets/master.go
@@ -14,6 +14,7 @@ import (
 var masterCmd = &cobra.Command{
 	Use:   "master",
 	Short: "Generate a cryptographically secure master key",
+	Long:  "Generate a random master key, printed base64-encoded — the key encrypt, decrypt, and the seed engine use. --length sets the byte size (default 32).",
 	Args:  cobra.NoArgs,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		cfg := getOutputConfig(cmd)
diff --git a/cmd/secrets/secrets.go b/cmd/secrets/secrets.go
index 8db7c41..5acfcb8 100644
--- a/cmd/secrets/secrets.go
+++ b/cmd/secrets/secrets.go
@@ -7,6 +7,7 @@ import (
 var SecretsCmd = &cobra.Command{
 	Use:   "secrets",
 	Short: "Manage encryption and decryption of secrets",
+	Long:  "Encrypt and decrypt values under a master key, and generate the keys themselves. Encrypted values are what the seed engine's secrets: map stores and decrypts at boot.",
 }
 
 func init() {
diff --git a/cmd/seed/apply.go b/cmd/seed/apply.go
index c51c300..6648503 100644
--- a/cmd/seed/apply.go
+++ b/cmd/seed/apply.go
@@ -12,6 +12,7 @@ import (
 var applyCmd = &cobra.Command{
 	Use:          "apply [dest...]",
 	Short:        "Project seed content onto the filesystem",
+	Long:         "Apply the seed source to the filesystem — mirror bare files and run the .seed.yaml operations. Writes only where the destination is missing unless --force; pass destinations to limit the run to those paths.",
 	SilenceUsage: true,
 	RunE:         runApply,
 }
diff --git a/cmd/seed/ls.go b/cmd/seed/ls.go
index a42e123..169ff34 100644
--- a/cmd/seed/ls.go
+++ b/cmd/seed/ls.go
@@ -11,6 +11,7 @@ import (
 var lsCmd = &cobra.Command{
 	Use:   "ls",
 	Short: "List seed destinations and their behaviors",
+	Long:  "List what apply would write — each destination with its operation and whether it carries a secret or a template — without touching the filesystem.",
 	RunE:  runLs,
 }
 
diff --git a/cmd/seed/rotate.go b/cmd/seed/rotate.go
index bed40b6..0c9ad4a 100644
--- a/cmd/seed/rotate.go
+++ b/cmd/seed/rotate.go
@@ -8,6 +8,7 @@ import (
 var rotateCmd = &cobra.Command{
 	Use:          "rotate",
 	Short:        "Re-encrypt managed secrets under a new master key",
+	Long:         "Re-encrypt every managed secret from the old master key (--master) to a new one (--new-master), in place. All-or-nothing: it verifies every secret decrypts before writing anything.",
 	SilenceUsage: true,
 	RunE:         runRotate,
 }
diff --git a/cmd/seed/seed.go b/cmd/seed/seed.go
index b244032..9cc88f9 100644
--- a/cmd/seed/seed.go
+++ b/cmd/seed/seed.go
@@ -8,6 +8,7 @@ import (
 var SeedCmd = &cobra.Command{
 	Use:   "seed",
 	Short: "Project declarative content onto the filesystem",
+	Long:  "Copy files and apply small edits from a seed source onto the filesystem at boot. Bare files mirror verbatim; a .seed.yaml manifest overlays behavior — copy, merge, append — and decrypts secrets under the master key. Point --source at a mounted volume to seed a container from durable storage.",
 }
 
 func init() {
diff --git a/cmd/serve/current.go b/cmd/serve/current.go
index 54ef741..0ab9e21 100644
--- a/cmd/serve/current.go
+++ b/cmd/serve/current.go
@@ -12,6 +12,7 @@ import (
 var currentCmd = &cobra.Command{
 	Use:   "current",
 	Short: "Serve current directory as a static site",
+	Long:  "Serve the current directory over HTTP as a static site — a quick way to preview built files.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		port, _ := cmd.Flags().GetInt("port")
 		bind, _ := cmd.Flags().GetString("bind")
diff --git a/cmd/serve/font.go b/cmd/serve/font.go
index 4130433..d8d1ef9 100644
--- a/cmd/serve/font.go
+++ b/cmd/serve/font.go
@@ -11,6 +11,7 @@ import (
 var fontCmd = &cobra.Command{
 	Use:   "font",
 	Short: "Serve fonts for local download",
+	Long:  "Serve the installed fonts over HTTP so a browser can fetch them for local install.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		port, _ := cmd.Flags().GetInt("port")
 		bind, _ := cmd.Flags().GetString("bind")
diff --git a/cmd/serve/serve.go b/cmd/serve/serve.go
index 70d8159..ae62bc3 100644
--- a/cmd/serve/serve.go
+++ b/cmd/serve/serve.go
@@ -5,6 +5,7 @@ import "github.com/spf13/cobra"
 var ServeCmd = &cobra.Command{
 	Use:   "serve",
 	Short: "Serve internal assets",
+	Long:  "Run a small HTTP server for local assets — fonts or the current directory — on --port (default 38080).",
 }
 
 func init() {
diff --git a/cmd/show/env.go b/cmd/show/env.go
index 3d5b42e..41c4ae4 100644
--- a/cmd/show/env.go
+++ b/cmd/show/env.go
@@ -17,6 +17,7 @@ var osExit = os.Exit
 var envCmd = &cobra.Command{
 	Use:   "env <KEY>",
 	Short: "Display the resolved value of a workspace environment variable",
+	Long:  "Resolve a setting by its dotted key (server.port) and print it with its source and description. --value emits just the value for scripts, --as bool|int|list validates the shape, --check tests whether it is set so a startup script can guard on it.",
 	Args:  cobra.ExactArgs(1),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		dotted := args[0]
diff --git a/cmd/show/ip.go b/cmd/show/ip.go
index 48174fb..e52b904 100644
--- a/cmd/show/ip.go
+++ b/cmd/show/ip.go
@@ -9,12 +9,14 @@ import (
 var ipCmd = &cobra.Command{
 	Use:   "ip",
 	Short: "Display IP addresses",
+	Long:  "Print the workspace's IP addresses — the internal container address or the node it runs on.",
 }
 
-func makeIPCmd(use, short, title string, getter func() (string, error)) *cobra.Command {
+func makeIPCmd(use, short, long, title string, getter func() (string, error)) *cobra.Command {
 	return &cobra.Command{
 		Use:   use,
 		Short: short,
+		Long:  long,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ip, err := getter()
 			if err != nil {
@@ -36,8 +38,8 @@ func makeIPCmd(use, short, title string, getter func() (string, error)) *cobra.C
 
 func init() {
 	ipCmd.AddCommand(
-		makeIPCmd("internal", "Display the internal IP address", "Internal IP Address", net.GetInternalIP),
-		makeIPCmd("node", "Display the node/host IP address", "Node IP Address", net.GetNodeIP),
+		makeIPCmd("internal", "Display the internal IP address", "Print the workspace container's internal IP address.", "Internal IP Address", net.GetInternalIP),
+		makeIPCmd("node", "Display the node/host IP address", "Print the IP address of the node hosting the workspace.", "Node IP Address", net.GetNodeIP),
 	)
 
 	ShowCmd.AddCommand(ipCmd)
diff --git a/cmd/show/ip_test.go b/cmd/show/ip_test.go
index 05e4489..dcdcbab 100644
--- a/cmd/show/ip_test.go
+++ b/cmd/show/ip_test.go
@@ -11,7 +11,7 @@ import (
 
 func _runIPCmd(t *testing.T, title string, getter func() (string, error)) (stdout, stderr string, err error) {
 	t.Helper()
-	cmd := makeIPCmd("ip", "Display an IP address", title, getter)
+	cmd := makeIPCmd("ip", "Display an IP address", "", title, getter)
 
 	var outBuf, errBuf bytes.Buffer
 	cmd.SetOut(&outBuf)
diff --git a/cmd/show/path.go b/cmd/show/path.go
index b927674..837b462 100644
--- a/cmd/show/path.go
+++ b/cmd/show/path.go
@@ -10,11 +10,13 @@ import (
 var pathCmd = &cobra.Command{
 	Use:   "path",
 	Short: "Display various paths",
+	Long:  "Print well-known workspace paths — the home root or the VS Code settings file.",
 }
 
 var pathHomeCmd = &cobra.Command{
 	Use:   "home",
 	Short: "Display the workspace home path",
+	Long:  "Print the workspace home (server root) path.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		homePath := config.MustResolve("server", "root")
 
@@ -33,6 +35,7 @@ var pathHomeCmd = &cobra.Command{
 var pathVscodeCmd = &cobra.Command{
 	Use:   "vscode-settings",
 	Short: "Display the VS Code settings path",
+	Long:  "Print the path to the VS Code settings file — the user file by default, or the folder's with --workspace.",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		useWorkspace, _ := cmd.Flags().GetBool("workspace")
 
diff --git a/cmd/show/show.go b/cmd/show/show.go
index e61387f..8167cca 100644
--- a/cmd/show/show.go
+++ b/cmd/show/show.go
@@ -7,6 +7,7 @@ import (
 var ShowCmd = &cobra.Command{
 	Use:   "show",
 	Short: "Display information about the current workspace instance",
+	Long:  "Resolve and print facts about this workspace instance — settings, IP addresses, and paths. --raw drops the styling for use in scripts.",
 }
 
 func init() {
diff --git a/cmd/template/apply.go b/cmd/template/apply.go
index 9f44a50..b0f943e 100644
--- a/cmd/template/apply.go
+++ b/cmd/template/apply.go
@@ -11,6 +11,7 @@ import (
 var applyCmd = &cobra.Command{
 	Use:               "apply <template>",
 	Short:             "Apply a configuration template to the current project",
+	Long:              "Copy a template into the project — a shared config like ruff or markdownlint — to --path (the current directory by default). --force overwrites an existing file.",
 	Args:              cobra.ExactArgs(1),
 	ValidArgsFunction: templateCompletion,
 	RunE:              runApply,
diff --git a/cmd/template/list.go b/cmd/template/list.go
index 99bcdf1..b7cbe85 100644
--- a/cmd/template/list.go
+++ b/cmd/template/list.go
@@ -13,6 +13,7 @@ import (
 var listCmd = &cobra.Command{
 	Use:     "list",
 	Short:   "List all available configuration templates",
+	Long:    "List the templates you can apply, with their source paths and whether one is already applied here.",
 	Aliases: []string{"ls"},
 	RunE:    runList,
 }
diff --git a/cmd/template/template.go b/cmd/template/template.go
index ea366af..d3f818a 100644
--- a/cmd/template/template.go
+++ b/cmd/template/template.go
@@ -7,5 +7,5 @@ import (
 var TemplateCmd = &cobra.Command{
 	Use:   "template",
 	Short: "Manage static configuration files",
-	Long:  "Copy and manage configuration files stored in global locations",
+	Long:  "Copy shared configuration files (linters, formatters) from their global locations into a project, and inspect what they hold.",
 }
diff --git a/commands.yaml b/commands.yaml
index 687967b..0cf1321 100644
--- a/commands.yaml
+++ b/commands.yaml
@@ -1,16 +1,20 @@
 name: ws-cli
 synopsis: ⚡ CLI companion to charge the workspace batteries
+description: The workspace command-line companion. Groups helpers for inspecting the running workspace, managing settings and secrets, driving the editor, and serving local assets — most are called by the startup scripts, all are yours in the terminal.
 aliases:
     - ws
 commands:
     - name: ws-cli clip
       synopsis: Interact with the native clipboard
+      description: Reach the browser clipboard from the terminal over the workspace IPC socket.
       commands:
         - name: ws-cli clip paste
           synopsis: Paste clipboard content
+          description: Read the browser clipboard over the workspace IPC socket and write it to stdout — redirect it to a file or pipe it onward. Pairs with the pbcopy/xclip/xsel shims for terminal clipboard access.
           usage: ws-cli clip paste
     - name: ws-cli editor
       synopsis: Inspect and drive the active editor session
+      description: Query and control the running VS Code / code-server window over the workspace IPC socket — list open tabs, read diagnostics and the current selection, or open a file. Blocked over SSH, where there is no browser editor to reach.
       options:
         - name: raw
           default: "false"
@@ -18,15 +22,18 @@ commands:
       commands:
         - name: ws-cli editor diagnostics
           synopsis: Show language diagnostics for the workspace (or a single file)
+          description: Pull language-server diagnostics (errors, warnings) from the editor over the IPC socket, across the whole workspace or a single file with --uri. Styled table by default, --raw for the JSON.
           usage: ws-cli editor diagnostics [flags]
           options:
             - name: uri
               usage: Filter to a single file (URI or absolute path)
         - name: ws-cli editor list
           synopsis: List the currently open editor tabs
+          description: List the editor's open tabs over the IPC socket, with each tab's path, language, and active or dirty state.
           usage: ws-cli editor list
         - name: ws-cli editor open
           synopsis: Open a file in the editor
+          description: Open a file in the running editor window over the workspace IPC socket — a tab in the current window by default, a separate one with --new-window, jumping to a range with --selection. Fails fast over SSH, where there is no browser editor to open into.
           usage: ws-cli editor open <file> [flags]
           options:
             - name: new-window
@@ -42,9 +49,11 @@ commands:
               usage: 'Select a range: LINE:COL[-LINE:COL] (1-based)'
         - name: ws-cli editor selection
           synopsis: Show the active editor's current selection
+          description: Report the active editor's current selection — file, range, and selected text — over the IPC socket. Empty when nothing is selected.
           usage: ws-cli editor selection
     - name: ws-cli feature
       synopsis: Install additional pre-configured features
+      description: Install and inspect optional workspace features — Ansible playbooks that add tools on top of the base image. Ships a curated set; --root points at your own under ~/.ws/features.d.
       options:
         - name: root
           default: /usr/share/workspace/features.d
@@ -52,9 +61,11 @@ commands:
       commands:
         - name: ws-cli feature info
           synopsis: Show detailed information about a feature
+          description: Show a feature's description and the variables it accepts, so you know what --opt values install will take.
           usage: ws-cli feature info <name>
         - name: ws-cli feature install
           synopsis: Install additional pre-configured features
+          description: Run a feature's playbook to install it. Pass variables with --opt KEY=VAL, and skip parts you do not want with --skip-extensions, --skip-completion, or --skip-repository.
           usage: ws-cli feature install [flags]
           options:
             - name: opt
@@ -71,6 +82,7 @@ commands:
               usage: Skip enabling the vendor APT repository
         - name: ws-cli feature list
           synopsis: List available features that can be installed
+          description: List the features you can install, marking where each comes from — the shipped set, a workspace override, or your own ~/.ws/features.d.
           usage: ws-cli feature list
           aliases:
             - ls
@@ -86,18 +98,23 @@ commands:
           usage: ws-cli feature new [name]
         - name: ws-cli feature store
           synopsis: List packages available in the feature store
+          description: List the artifacts published to the feature store (WS_FEATURES_STORE_URL) — the offline mirror features install from when the network is locked down.
           usage: ws-cli feature store
     - name: ws-cli info
       synopsis: Display workspace information
+      description: Report facts about the running workspace — version, effective environment, installed extensions, live resource metrics, and uptime.
       commands:
         - name: ws-cli info env
           synopsis: Display effective workspace environment variables
+          description: Print every WS_* variable in effect, sorted — the resolved environment the workspace booted with.
           usage: ws-cli info env
         - name: ws-cli info extensions
           synopsis: Display installed extensions
+          description: List the installed VS Code extensions with their versions.
           usage: ws-cli info extensions
         - name: ws-cli info metrics
           synopsis: Display workspace metrics
+          description: Show live resource usage — CPU, memory, disk, and file descriptors, plus GPU with --gpu.
           usage: ws-cli info metrics [flags]
           options:
             - name: gpu
@@ -105,9 +122,11 @@ commands:
               usage: Include GPU metrics
         - name: ws-cli info uptime
           synopsis: Display the workspace uptime
+          description: Show when the workspace session started and how long it has been running.
           usage: ws-cli info uptime
         - name: ws-cli info version
           synopsis: Display installed workspace version
+          description: Print the workspace version. --all expands to the full table — workspace, ws-cli, and VS Code.
           usage: ws-cli info version [flags]
           options:
             - name: all
@@ -115,6 +134,7 @@ commands:
               usage: Show all version information
     - name: ws-cli log
       synopsis: Log messages
+      description: Emit styled, level-tagged log lines — the same formatting the startup scripts use. --pipe runs each line of piped input through the logger.
       options:
         - name: pipe
           shorthand: p
@@ -123,6 +143,7 @@ commands:
       commands:
         - name: ws-cli log debug
           synopsis: Log debugging messages
+          description: Emit a log line at debug level in the workspace style — the same formatting the startup scripts use. --indent nests it under a preceding line, --stamp prefixes a timestamp.
           usage: ws-cli log debug message [flags]
           options:
             - name: indent
@@ -135,6 +156,7 @@ commands:
               usage: Prefix message with current timestamp
         - name: ws-cli log error
           synopsis: Log error messages
+          description: Emit a log line at error level in the workspace style — the same formatting the startup scripts use. --indent nests it under a preceding line, --stamp prefixes a timestamp.
           usage: ws-cli log error message [flags]
           options:
             - name: indent
@@ -147,6 +169,7 @@ commands:
               usage: Prefix message with current timestamp
         - name: ws-cli log info
           synopsis: Log information messages
+          description: Emit a log line at info level in the workspace style — the same formatting the startup scripts use. --indent nests it under a preceding line, --stamp prefixes a timestamp.
           usage: ws-cli log info message [flags]
           options:
             - name: indent
@@ -159,9 +182,11 @@ commands:
               usage: Prefix message with current timestamp
         - name: ws-cli log stamp
           synopsis: Log the current timestamp
+          description: Print just the current timestamp in the workspace log style — handy for marking phases in a startup log.
           usage: ws-cli log stamp
         - name: ws-cli log warn
           synopsis: Log warning messages
+          description: Emit a log line at warn level in the workspace style — the same formatting the startup scripts use. --indent nests it under a preceding line, --stamp prefixes a timestamp.
           usage: ws-cli log warn message [flags]
           options:
             - name: indent
@@ -174,6 +199,7 @@ commands:
               usage: Prefix message with current timestamp
     - name: ws-cli logs
       synopsis: Retrieve workspace logs
+      description: Read a workspace daemon's log — the main log by default, or --target metrics|docker|auth_proxy|cloudflared. Filter by --level, limit with --tail, or stream live with --follow.
       usage: ws-cli logs [flags]
       options:
         - name: follow
@@ -192,6 +218,7 @@ commands:
           usage: Log target to read (main|metrics|docker|auth_proxy|cloudflared)
     - name: ws-cli secrets
       synopsis: Manage encryption and decryption of secrets
+      description: 'Encrypt and decrypt values under a master key, and generate the keys themselves. Encrypted values are what the seed engine''s secrets: map stores and decrypts at boot.'
       options:
         - name: force
           default: "false"
@@ -208,18 +235,23 @@ commands:
       commands:
         - name: ws-cli secrets decrypt
           synopsis: Decrypt an encrypted value
+          description: Decrypt a value produced by encrypt, under the master key. Reads from the argument or stdin (-); writes the plaintext to stdout, or a file with --output.
           usage: ws-cli secrets decrypt <encrypted|->
         - name: ws-cli secrets encrypt
           synopsis: Encrypt a plaintext value
+          description: Encrypt a value under the master key. Reads the plaintext from the argument or stdin (-); writes the ciphertext to stdout, or a file with --output.
           usage: ws-cli secrets encrypt <plaintext|->
         - name: ws-cli secrets generate
           synopsis: Generate master keys or login password hashes
+          description: Generate the credentials the workspace needs — a master key for secrets, or a login password hash for the server.
           commands:
             - name: ws-cli secrets generate login
               synopsis: Generate a workspace password hash for authentication
+              description: Prompt for a password and print its hash for the workspace server login (WS_AUTH_PASSWORD_HASHED). Store the hash, never the password.
               usage: ws-cli secrets generate login
             - name: ws-cli secrets generate master
               synopsis: Generate a cryptographically secure master key
+              description: Generate a random master key, printed base64-encoded — the key encrypt, decrypt, and the seed engine use. --length sets the byte size (default 32).
               usage: ws-cli secrets generate master [flags]
               options:
                 - name: length
@@ -227,12 +259,14 @@ commands:
                   usage: Key length in bytes
     - name: ws-cli seed
       synopsis: Project declarative content onto the filesystem
+      description: Copy files and apply small edits from a seed source onto the filesystem at boot. Bare files mirror verbatim; a .seed.yaml manifest overlays behavior — copy, merge, append — and decrypts secrets under the master key. Point --source at a mounted volume to seed a container from durable storage.
       options:
         - name: source
           usage: Seed source directory
       commands:
         - name: ws-cli seed apply
           synopsis: Project seed content onto the filesystem
+          description: Apply the seed source to the filesystem — mirror bare files and run the .seed.yaml operations. Writes only where the destination is missing unless --force; pass destinations to limit the run to those paths.
           usage: ws-cli seed apply [dest...] [flags]
           options:
             - name: force
@@ -242,9 +276,11 @@ commands:
               usage: Master key or path to key file
         - name: ws-cli seed ls
           synopsis: List seed destinations and their behaviors
+          description: List what apply would write — each destination with its operation and whether it carries a secret or a template — without touching the filesystem.
           usage: ws-cli seed ls
         - name: ws-cli seed rotate
           synopsis: Re-encrypt managed secrets under a new master key
+          description: 'Re-encrypt every managed secret from the old master key (--master) to a new one (--new-master), in place. All-or-nothing: it verifies every secret decrypts before writing anything.'
           usage: ws-cli seed rotate [flags]
           options:
             - name: master
@@ -253,6 +289,7 @@ commands:
               usage: New master key or path to key file
     - name: ws-cli serve
       synopsis: Serve internal assets
+      description: Run a small HTTP server for local assets — fonts or the current directory — on --port (default 38080).
       options:
         - name: bind
           default: 0.0.0.0
@@ -264,15 +301,19 @@ commands:
       commands:
         - name: ws-cli serve current
           synopsis: Serve current directory as a static site
+          description: Serve the current directory over HTTP as a static site — a quick way to preview built files.
           usage: ws-cli serve current
         - name: ws-cli serve current
           synopsis: Serve current directory as a static site
+          description: Serve the current directory over HTTP as a static site — a quick way to preview built files.
           usage: ws-cli serve current [flags]
         - name: ws-cli serve font
           synopsis: Serve fonts for local download
+          description: Serve the installed fonts over HTTP so a browser can fetch them for local install.
           usage: ws-cli serve font
         - name: ws-cli serve font
           synopsis: Serve fonts for local download
+          description: Serve the installed fonts over HTTP so a browser can fetch them for local install.
           usage: ws-cli serve font [flags]
         - name: ws-cli serve metrics
           synopsis: Start the Prometheus metrics server
@@ -287,6 +328,7 @@ commands:
               usage: Port to serve metrics on
     - name: ws-cli show
       synopsis: Display information about the current workspace instance
+      description: Resolve and print facts about this workspace instance — settings, IP addresses, and paths. --raw drops the styling for use in scripts.
       options:
         - name: raw
           default: "false"
@@ -294,6 +336,7 @@ commands:
       commands:
         - name: ws-cli show env
           synopsis: Display the resolved value of a workspace environment variable
+          description: Resolve a setting by its dotted key (server.port) and print it with its source and description. --value emits just the value for scripts, --as bool|int|list validates the shape, --check tests whether it is set so a startup script can guard on it.
           usage: ws-cli show env <KEY> [flags]
           options:
             - name: as
@@ -315,21 +358,27 @@ commands:
               usage: Emit the raw resolved value as a single line
         - name: ws-cli show ip
           synopsis: Display IP addresses
+          description: Print the workspace's IP addresses — the internal container address or the node it runs on.
           commands:
             - name: ws-cli show ip internal
               synopsis: Display the internal IP address
+              description: Print the workspace container's internal IP address.
               usage: ws-cli show ip internal
             - name: ws-cli show ip node
               synopsis: Display the node/host IP address
+              description: Print the IP address of the node hosting the workspace.
               usage: ws-cli show ip node
         - name: ws-cli show path
           synopsis: Display various paths
+          description: Print well-known workspace paths — the home root or the VS Code settings file.
           commands:
             - name: ws-cli show path home
               synopsis: Display the workspace home path
+              description: Print the workspace home (server root) path.
               usage: ws-cli show path home
             - name: ws-cli show path vscode-settings
               synopsis: Display the VS Code settings path
+              description: Print the path to the VS Code settings file — the user file by default, or the folder's with --workspace.
               usage: ws-cli show path vscode-settings [flags]
               options:
                 - name: workspace
@@ -337,10 +386,11 @@ commands:
                   usage: Get the workspace settings
     - name: ws-cli template
       synopsis: Manage static configuration files
-      description: Copy and manage configuration files stored in global locations
+      description: Copy shared configuration files (linters, formatters) from their global locations into a project, and inspect what they hold.
       commands:
         - name: ws-cli template apply
           synopsis: Apply a configuration template to the current project
+          description: Copy a template into the project — a shared config like ruff or markdownlint — to --path (the current directory by default). --force overwrites an existing file.
           usage: ws-cli template apply <template> [flags]
           options:
             - name: force
@@ -352,6 +402,7 @@ commands:
               usage: Target directory path
         - name: ws-cli template list
           synopsis: List all available configuration templates
+          description: List the templates you can apply, with their source paths and whether one is already applied here.
           usage: ws-cli template list
           aliases:
             - ls

From abedcd3afde684fd6bfa96a7bb059addfcd638ff Mon Sep 17 00:00:00 2001
From: Dov Benyomin Sohacheski <b@kloud.email>
Date: Wed, 1 Jul 2026 14:20:39 +0300
Subject: [PATCH 3/4] =?UTF-8?q?=E2=AC=86=EF=B8=8F=20Bump=20dependencies=20?=
 =?UTF-8?q?to=20latest?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

glamour v2.0.1, lipgloss v2.0.4, chroma v2.27.0, prometheus/common
v0.69.0, and the golang.org/x/* set.
---
 go.mod | 35 ++++++++++++++++----------------
 go.sum | 64 +++++++++++++++++++++++++++++-----------------------------
 2 files changed, 49 insertions(+), 50 deletions(-)

diff --git a/go.mod b/go.mod
index bb5fbd8..aee9a47 100644
--- a/go.mod
+++ b/go.mod
@@ -4,39 +4,40 @@ go 1.26.2
 
 require (
 	charm.land/fang/v2 v2.0.1
-	charm.land/glamour/v2 v2.0.0
-	charm.land/lipgloss/v2 v2.0.3
+	charm.land/glamour/v2 v2.0.1
+	charm.land/lipgloss/v2 v2.0.4
+	github.com/pelletier/go-toml/v2 v2.4.2
 	github.com/prometheus/client_golang v1.23.2
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/pflag v1.0.10
-	golang.org/x/crypto v0.52.0
-	golang.org/x/term v0.43.0
+	golang.org/x/crypto v0.53.0
+	golang.org/x/term v0.44.0
 	gopkg.in/yaml.v3 v3.0.1
 	gotest.tools/v3 v3.5.2
 )
 
 require (
-	github.com/alecthomas/chroma/v2 v2.24.1 // indirect
+	github.com/alecthomas/chroma/v2 v2.27.0 // indirect
 	github.com/aymerick/douceur v0.2.0 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/charmbracelet/colorprofile v0.4.3 // indirect
-	github.com/charmbracelet/ultraviolet v0.0.0-20260511121909-c840852527f3 // indirect
+	github.com/charmbracelet/ultraviolet v0.0.0-20260622092850-f39628c8a989 // indirect
 	github.com/charmbracelet/x/ansi v0.11.7 // indirect
-	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260517005351-920740d613be // indirect
-	github.com/charmbracelet/x/exp/slice v0.0.0-20260517005351-920740d613be // indirect
+	github.com/charmbracelet/x/exp/charmtone v0.0.0-20260629091435-9c70f75e26a4 // indirect
+	github.com/charmbracelet/x/exp/slice v0.0.0-20260629091435-9c70f75e26a4 // indirect
 	github.com/charmbracelet/x/term v0.2.2 // indirect
 	github.com/charmbracelet/x/termios v0.1.1 // indirect
 	github.com/charmbracelet/x/windows v0.2.2 // indirect
 	github.com/clipperhouse/displaywidth v0.11.0 // indirect
 	github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
-	github.com/dlclark/regexp2 v1.12.0 // indirect
+	github.com/dlclark/regexp2/v2 v2.2.2 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/kr/text v0.2.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.4.0 // indirect
-	github.com/mattn/go-runewidth v0.0.23 // indirect
+	github.com/mattn/go-runewidth v0.0.24 // indirect
 	github.com/microcosm-cc/bluemonday v1.0.27 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/mango v0.2.0 // indirect
@@ -44,18 +45,16 @@ require (
 	github.com/muesli/mango-pflag v0.2.0 // indirect
 	github.com/muesli/roff v0.1.0 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
-	github.com/pelletier/go-toml/v2 v2.4.2 // indirect
 	github.com/prometheus/client_model v0.6.2 // indirect
-	github.com/prometheus/common v0.67.5 // indirect
-	github.com/prometheus/procfs v0.20.1 // indirect
+	github.com/prometheus/common v0.69.0 // indirect
+	github.com/prometheus/procfs v0.21.1 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yuin/goldmark v1.8.2 // indirect
 	github.com/yuin/goldmark-emoji v1.0.6 // indirect
-	go.yaml.in/yaml/v2 v2.4.4 // indirect
-	golang.org/x/net v0.55.0 // indirect
-	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.45.0 // indirect
-	golang.org/x/text v0.37.0 // indirect
+	golang.org/x/net v0.56.0 // indirect
+	golang.org/x/sync v0.21.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/text v0.38.0 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
 )
diff --git a/go.sum b/go.sum
index a7e91f3..8361c60 100644
--- a/go.sum
+++ b/go.sum
@@ -1,13 +1,13 @@
 charm.land/fang/v2 v2.0.1 h1:zQCM8JQJ1JnQX/66B5jlCYBUxL2as5JXQZ2KJ6EL0mY=
 charm.land/fang/v2 v2.0.1/go.mod h1:S1GmkpcvK+OB5w9caywUnJcsMew45Ot8FXqoz8ALrII=
-charm.land/glamour/v2 v2.0.0 h1:IDBoqLEy7Hdpb9VOXN+khLP/XSxtJy1VsHuW/yF87+U=
-charm.land/glamour/v2 v2.0.0/go.mod h1:kjq9WB0s8vuUYZNYey2jp4Lgd9f4cKdzAw88FZtpj/w=
-charm.land/lipgloss/v2 v2.0.3 h1:yM2zJ4Cf5Y51b7RHIwioil4ApI/aypFXXVHSwlM6RzU=
-charm.land/lipgloss/v2 v2.0.3/go.mod h1:7myLU9iG/3xluAWzpY/fSxYYHCgoKTie7laxk6ATwXA=
+charm.land/glamour/v2 v2.0.1 h1:xl+r00A4aJWU0z8fgwKd9fQQ4rsphqGUzuEiXZP5n+c=
+charm.land/glamour/v2 v2.0.1/go.mod h1:jo9z8XqVKPeEFMVdvCRLGk++RyJ3CdUwgNr7EvXLw3k=
+charm.land/lipgloss/v2 v2.0.4 h1:lcPeVtcp23SNra7lHy8iYE4UC2aIipVQ47sbGyyxR5Q=
+charm.land/lipgloss/v2 v2.0.4/go.mod h1:0653x8epbZSzdDfO/XPS1a/uYPOBeSsCssOpJOqDzik=
 github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0=
 github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=
-github.com/alecthomas/chroma/v2 v2.24.1 h1:m5ffpfZbIb++k8AqFEKy9uVgY12xIQtBsQlc6DfZJQM=
-github.com/alecthomas/chroma/v2 v2.24.1/go.mod h1:l+ohZ9xRXIbGe7cIW+YZgOGbvuVLjMps/FYN/CwuabI=
+github.com/alecthomas/chroma/v2 v2.27.0 h1:FodwmyOBgJULFYmDqibcp9pvfDLWdtPRh9v/r5BXYZs=
+github.com/alecthomas/chroma/v2 v2.27.0/go.mod h1:NjJ3ciIgrqBNeIkWZ4e46nseoLDslxU1LmfCoL+wcY8=
 github.com/alecthomas/repr v0.5.2 h1:SU73FTI9D1P5UNtvseffFSGmdNci/O6RsqzeXJtP0Qs=
 github.com/alecthomas/repr v0.5.2/go.mod h1:Fr0507jx4eOXV7AlPV6AVZLYrLIuIeSOWtW57eE/O/4=
 github.com/aymanbagabas/go-udiff v0.4.1 h1:OEIrQ8maEeDBXQDoGCbbTTXYJMYRCRO1fnodZ12Gv5o=
@@ -20,16 +20,16 @@ github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UF
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/charmbracelet/colorprofile v0.4.3 h1:QPa1IWkYI+AOB+fE+mg/5/4HRMZcaXex9t5KX76i20Q=
 github.com/charmbracelet/colorprofile v0.4.3/go.mod h1:/zT4BhpD5aGFpqQQqw7a+VtHCzu+zrQtt1zhMt9mR4Q=
-github.com/charmbracelet/ultraviolet v0.0.0-20260511121909-c840852527f3 h1:pxGjlWZFcRQMWAdtjRelpL3Gbu8iYIyuO3Eqbd037Ow=
-github.com/charmbracelet/ultraviolet v0.0.0-20260511121909-c840852527f3/go.mod h1:SnKWaPaTnkTNXJgdgdquu66de12V8pW/b/qlTGaF9xg=
+github.com/charmbracelet/ultraviolet v0.0.0-20260622092850-f39628c8a989 h1:aLA9AmFNKnFr86XM3/Jm9g4xLOVjEgRuttBWUFujdVw=
+github.com/charmbracelet/ultraviolet v0.0.0-20260622092850-f39628c8a989/go.mod h1:f/jRa757WUmaOZrbPspXymbg/GnbF+rwe4OLsG7aXYo=
 github.com/charmbracelet/x/ansi v0.11.7 h1:kzv1kJvjg2S3r9KHo8hDdHFQLEqn4RBCb39dAYC84jI=
 github.com/charmbracelet/x/ansi v0.11.7/go.mod h1:9qGpnAVYz+8ACONkZBUWPtL7lulP9No6p1epAihUZwQ=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260517005351-920740d613be h1:kR6M0f6TvoLcqUvW1NHjR+g7eCpaGPjVZOg9qFTk5dI=
-github.com/charmbracelet/x/exp/charmtone v0.0.0-20260517005351-920740d613be/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260629091435-9c70f75e26a4 h1:LljZKJHFTKQk/BZepcoAXn7tBxVsc70tT2vqNFzWKf0=
+github.com/charmbracelet/x/exp/charmtone v0.0.0-20260629091435-9c70f75e26a4/go.mod h1:nsExn0DGyX0lh9LwLHTn2Gg+hafdzfSXnC+QmEJTZFY=
 github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f h1:pk6gmGpCE7F3FcjaOEKYriCvpmIN4+6OS/RD0vm4uIA=
 github.com/charmbracelet/x/exp/golden v0.0.0-20250806222409-83e3a29d542f/go.mod h1:IfZAMTHB6XkZSeXUqriemErjAWCCzT0LwjKFYCZyw0I=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260517005351-920740d613be h1:O22D2Od8gEsRGTDPKDTRzx2BGrvVcIAJlwBf+1sTeN0=
-github.com/charmbracelet/x/exp/slice v0.0.0-20260517005351-920740d613be/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260629091435-9c70f75e26a4 h1:3LxYwrbyrdfiPRDtYdJNzkmoozXh/UHjleHvu/w9E+A=
+github.com/charmbracelet/x/exp/slice v0.0.0-20260629091435-9c70f75e26a4/go.mod h1:vqEfX6xzqW1pKKZUUiFOKg0OQ7bCh54Q2vR/tserrRA=
 github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
 github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI=
 github.com/charmbracelet/x/termios v0.1.1 h1:o3Q2bT8eqzGnGPOYheoYS8eEleT5ZVNYNy8JawjaNZY=
@@ -44,8 +44,8 @@ github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6N
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/dlclark/regexp2 v1.12.0 h1:0j4c5qQmnC6XOWNjP3PIXURXN2gWx76rd3KvgdPkCz8=
-github.com/dlclark/regexp2 v1.12.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/dlclark/regexp2/v2 v2.2.2 h1:MYWvNYw8okuqNhwTYO587EZMiDruVa2vhV6fsGpfya0=
+github.com/dlclark/regexp2/v2 v2.2.2/go.mod h1:avUrQvPaLz2DrFNHJF0taWAFFX2C1GMSSoeiqFjcBmU=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/gorilla/css v1.0.1 h1:ntNaBIghp6JmvWnxbZKANoLyuXTPZ4cAMlo6RyhlbO8=
@@ -64,8 +64,8 @@ github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
 github.com/lucasb-eyer/go-colorful v1.4.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
-github.com/mattn/go-runewidth v0.0.23 h1:7ykA0T0jkPpzSvMS5i9uoNn2Xy3R383f9HDx3RybWcw=
-github.com/mattn/go-runewidth v0.0.23/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
+github.com/mattn/go-runewidth v0.0.24 h1:cpokDiIn0MGnhdHwuWnJBITySJ20QyNGnY2kR/ay2DU=
+github.com/mattn/go-runewidth v0.0.24/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
 github.com/microcosm-cc/bluemonday v1.0.27 h1:MpEUotklkwCSLeH+Qdx1VJgNqLlpY2KXwXFM08ygZfk=
 github.com/microcosm-cc/bluemonday v1.0.27/go.mod h1:jFi9vgW+H7c3V0lb6nR74Ib/DIB5OBs92Dimizgw2cA=
 github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
@@ -88,10 +88,10 @@ github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h
 github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
 github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
 github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
-github.com/prometheus/common v0.67.5 h1:pIgK94WWlQt1WLwAC5j2ynLaBRDiinoAb86HZHTUGI4=
-github.com/prometheus/common v0.67.5/go.mod h1:SjE/0MzDEEAyrdr5Gqc6G+sXI67maCxzaT3A2+HqjUw=
-github.com/prometheus/procfs v0.20.1 h1:XwbrGOIplXW/AU3YhIhLODXMJYyC1isLFfYCsTEycfc=
-github.com/prometheus/procfs v0.20.1/go.mod h1:o9EMBZGRyvDrSPH1RqdxhojkuXstoe4UlK79eF5TGGo=
+github.com/prometheus/common v0.69.0 h1:OA85nJQS/T/MaYh/Q2CcgDKSGWqNIgrBDvDH85CuiNk=
+github.com/prometheus/common v0.69.0/go.mod h1:ZzL3f6u94qUxh9p+tJTrF+FvBS1XXbbRAZCQkytAL0Y=
+github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI=
+github.com/prometheus/procfs v0.21.1/go.mod h1:aB55Cww9pdSJVHk0hUf0inxWyyjPogFIjmHKYgMKmtY=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
 github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
@@ -115,20 +115,20 @@ go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
 go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988=
-golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc=
+golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
+golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
-golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
-golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
-golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
-golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
-golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
-golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
-golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
-golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
+golang.org/x/net v0.56.0 h1:Rw8j/hFzGvJUZwNBXnAtf5sVDVt+65SK2C7IxCxZt5o=
+golang.org/x/net v0.56.0/go.mod h1:D3Ku6r+V6JROoZK144D2XfMHFcMq/0zSfLelVTCFKec=
+golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
+golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.44.0 h1:0rLvDRCtNj0gZkyIXhCyOb2OAzEhLVqc4B+hrsBhrmc=
+golang.org/x/term v0.44.0/go.mod h1:7ze4MdzUzLXpSAoFP1H0bOI9aXDqveSvatT5vKcFh2Y=
+golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
+golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

From 843e028b3d1a4bab03ddca8630ca9a79a052f3fe Mon Sep 17 00:00:00 2001
From: Dov Benyomin Sohacheski <b@kloud.email>
Date: Wed, 1 Jul 2026 14:32:41 +0300
Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=90=9B=20Omit=20environment-resolved?=
 =?UTF-8?q?=20absolute-path=20flag=20defaults=20from=20the=20manifest?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

seed --source and feature --root take their defaults from config at init,
so they resolve to machine-specific paths (or nothing) depending on the
environment — breaking the manifest's cross-environment determinism and
leaking runtime paths into the docs. Drop absolute-path defaults; keep
booleans, ints, and symbolic values. Add serializer tests.
---
 commands.yaml                    |  1 -
 internals/docs/serialize.go      |  8 ++++++-
 internals/docs/serialize_test.go | 40 ++++++++++++++++++++++++++++++++
 3 files changed, 47 insertions(+), 2 deletions(-)
 create mode 100644 internals/docs/serialize_test.go

diff --git a/commands.yaml b/commands.yaml
index 0cf1321..813d035 100644
--- a/commands.yaml
+++ b/commands.yaml
@@ -56,7 +56,6 @@ commands:
       description: Install and inspect optional workspace features — Ansible playbooks that add tools on top of the base image. Ships a curated set; --root points at your own under ~/.ws/features.d.
       options:
         - name: root
-          default: /usr/share/workspace/features.d
           usage: Root directory of additional features
       commands:
         - name: ws-cli feature info
diff --git a/internals/docs/serialize.go b/internals/docs/serialize.go
index c6d4e08..ca712d1 100644
--- a/internals/docs/serialize.go
+++ b/internals/docs/serialize.go
@@ -1,6 +1,7 @@
 package docs
 
 import (
+	"path/filepath"
 	"sort"
 
 	"github.com/spf13/cobra"
@@ -48,10 +49,15 @@ func walk(c *cobra.Command) Command {
 			return
 		}
 
+		def := f.DefValue
+		if filepath.IsAbs(def) {
+			def = ""
+		}
+
 		command.Options = append(command.Options, Option{
 			Name:      f.Name,
 			Shorthand: f.Shorthand,
-			Default:   f.DefValue,
+			Default:   def,
 			Usage:     f.Usage,
 		})
 	})
diff --git a/internals/docs/serialize_test.go b/internals/docs/serialize_test.go
new file mode 100644
index 0000000..54c26fc
--- /dev/null
+++ b/internals/docs/serialize_test.go
@@ -0,0 +1,40 @@
+package docs
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+	"gotest.tools/v3/assert"
+)
+
+func TestSerializeOmitsAbsolutePathDefaults(t *testing.T) {
+	root := &cobra.Command{Use: "demo", Run: func(*cobra.Command, []string) {}}
+	root.Flags().String("source", "/home/runner/.ws/seed.d", "Seed source directory")
+	root.Flags().String("bind", "0.0.0.0", "Bind address")
+	root.Flags().Int("port", 38080, "Port")
+
+	out, err := Serialize(root)
+	assert.NilError(t, err)
+
+	rendered := string(out)
+	assert.Assert(t, !strings.Contains(rendered, "/home/runner/.ws/seed.d"),
+		"env-resolved absolute-path defaults must be omitted:\n%s", rendered)
+	assert.Assert(t, strings.Contains(rendered, "default: 0.0.0.0"))
+	assert.Assert(t, strings.Contains(rendered, "default: \"38080\""))
+}
+
+func TestSerializeSortsChildrenAndOmitsHidden(t *testing.T) {
+	root := &cobra.Command{Use: "demo"}
+	root.AddCommand(&cobra.Command{Use: "zebra", Run: func(*cobra.Command, []string) {}})
+	root.AddCommand(&cobra.Command{Use: "alpha", Run: func(*cobra.Command, []string) {}})
+	root.AddCommand(&cobra.Command{Use: "ghost", Hidden: true, Run: func(*cobra.Command, []string) {}})
+
+	out, err := Serialize(root)
+	assert.NilError(t, err)
+
+	rendered := string(out)
+	assert.Assert(t, strings.Index(rendered, "demo alpha") < strings.Index(rendered, "demo zebra"),
+		"children must sort by name:\n%s", rendered)
+	assert.Assert(t, !strings.Contains(rendered, "ghost"), "hidden commands must be omitted")
+}