Merge branch 'master' into docs-v2-issue563

Author: jstirnaman

.claude/skills/docs-cli-workflow/SKILL.md

@@ -83,12 +83,12 @@ Which do you prefer?
 ```
 I can use the docs CLI to find the source files for this page:
 
-npx docs edit <url>
+docs edit <url-or-path>
 
 **Why**: [1-2 sentences explaining the benefit]
 
 Options:
-1. **Use CLI** - I'll find and open the relevant files
+1. **Use CLI** - I'll find and list the relevant files (non-blocking)
 2. **I know the file** - Tell me the path and I'll edit directly
 
 Which do you prefer?
@@ -122,14 +122,43 @@ No additional guidance needed—the CLI manages product selection, file generati
 # Create new documentation from a draft
 npx docs create <draft-path> --products <product-key>
 
+# Create and open files in editor (non-blocking)
+npx docs create <draft-path> --products <product-key> --open
+
+# Create and open, wait for editor (blocking)
+npx docs create <draft-path> --products <product-key> --open --wait
+
 # Create at specific URL location
 npx docs create --url <url> --from-draft <draft-path>
 
-# Find and open files for an existing page
-npx docs edit <url>
-npx docs edit --list <url>  # List files without opening
+# Find and list files for an existing page (non-blocking, agent-friendly)
+docs edit <url-or-path>
+docs edit <url-or-path> --list        # List files without opening editor
+
+# Interactive editing (blocks until editor closes)
+docs edit <url-or-path> --wait
+
+# Use specific editor
+docs edit <url-or-path> --editor nano
+
+# Examples (both full URL and path work)
+docs edit https://docs.influxdata.com/influxdb3/core/admin/databases/
+docs edit /influxdb3/core/admin/databases/
 ```
 
+**Editor Selection** (checked in order):
+1. `--editor` flag
+2. `DOCS_EDITOR` environment variable
+3. `VISUAL` environment variable
+4. `EDITOR` environment variable
+5. System default
+
+**Important for AI Agents**: 
+- Both `docs edit` and `docs create --open` commands are non-blocking by default (launch editor in background and exit immediately)
+- This prevents agents from hanging while waiting for user editing
+- Use `--wait` only when you need to block until editing is complete
+- For `docs create`, omit `--open` to skip editor entirely (files are created and CLI exits)
+
 For full CLI documentation, run `npx docs --help`.
 
 ## Related Skills

.github/copilot-instructions.md

@@ -18,9 +18,96 @@
 | Install | `CYPRESS_INSTALL_BINARY=0 yarn install` | ~4s | Skip Cypress for CI |
 | Build | `npx hugo --quiet` | ~75s | NEVER CANCEL |
 | Dev Server | `npx hugo server` | ~92s | Port 1313 |
+| Create Docs | `docs create <draft> --products <keys>` | varies | AI-assisted scaffolding |
+| Create & Open | `docs create <draft> --products <keys> --open` | instant | Non-blocking (background) |
+| Create & Wait | `docs create <draft> --products <keys> --open --wait` | varies | Blocking (interactive) |
+| Edit Docs | `docs edit <url>` | instant | Non-blocking (background) |
+| Edit Docs (wait) | `docs edit <url> --wait` | varies | Blocking (interactive) |
+| List Files | `docs edit <url> --list` | instant | Show files without opening |
 | Test All | `yarn test:codeblocks:all` | 15-45m | NEVER CANCEL |
 | Lint | `yarn lint` | ~1m | Pre-commit checks |
 
+## CLI Tools
+
+### docs create - Create Documentation Files
+
+Scaffolds new documentation pages with AI-assisted analysis. **Optionally opens created files in editor.**
+
+**Examples:**
+```bash
+# Create from draft (no editor)
+docs create drafts/new-feature.md --products influxdb3_core
+
+# Create and open files (non-blocking, exits immediately)
+docs create drafts/new-feature.md --products influxdb3_core --open
+
+# Create and open, wait for editor (blocking, interactive)
+docs create drafts/new-feature.md --products influxdb3_core --open --wait
+
+# Use specific editor
+docs create drafts/new-feature.md --products influxdb3_core --open --editor nano
+
+# Create at specific URL location
+docs create --url /influxdb3/core/admin/new/ --from-draft drafts/feature.md
+```
+
+**Options:**
+- `--open` - Open created files in editor after creation (non-blocking by default)
+- `--wait` - Wait for editor to close (use with `--open`)
+- `--editor <cmd>` - Specify editor command (use with `--open`)
+- `--products <keys>` - Comma-separated product keys (required)
+- `--dry-run` - Show what would be created without creating files
+- `--yes` - Skip confirmation prompt
+
+### docs edit - Edit Documentation Files
+
+Opens documentation files in your editor. **Non-blocking by default** (agent-friendly).
+
+**Examples:**
+```bash
+# Quick edit (exits immediately, editor in background)
+docs edit https://docs.influxdata.com/influxdb3/core/admin/databases/
+docs edit /influxdb3/core/admin/databases/
+
+# Interactive edit (waits for editor to close)
+docs edit /influxdb3/core/admin/databases/ --wait
+
+# List files without opening
+docs edit /influxdb3/core/admin/databases/ --list
+
+# Use specific editor
+docs edit /influxdb3/core/admin/databases/ --editor nano
+```
+
+**Options:**
+- `--list` - List files without opening editor
+- `--wait` - Wait for editor to close (blocking mode)
+- `--editor <cmd>` - Specify editor command
+
+### Editor Configuration
+
+Both `docs create --open` and `docs edit` use the same editor resolution:
+
+**Priority order:**
+1. `--editor` flag
+2. `DOCS_EDITOR` environment variable
+3. `VISUAL` environment variable  
+4. `EDITOR` environment variable
+5. System default (vim, nano, etc.)
+
+**Examples:**
+```bash
+export EDITOR=vim        # For all CLI tools
+export DOCS_EDITOR=nano  # Specifically for docs CLI
+export DOCS_EDITOR="code --wait"  # VS Code with wait flag
+```
+
+**Important for AI Agents:** 
+- Both commands are **non-blocking by default** (exit immediately)
+- This prevents agents and automation from hanging
+- Use `--wait` flag only when you need blocking behavior
+- For `docs create`, omit `--open` to skip editor entirely
+
 ## Working Effectively
 
 ### Collaboration approach

.github/instructions/content.instructions.md

@@ -8,6 +8,43 @@ applyTo: "content/**/*.md"
 **Shortcodes reference**: [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md)
 **Working examples**: [content/example.md](../../content/example.md)
 
+## CLI Tools for Content Workflow
+
+### Creating New Content
+
+Use `docs create` for AI-assisted scaffolding:
+
+```bash
+# Create from draft
+docs create drafts/feature.md --products influxdb3_core
+
+# Create and open files in editor (non-blocking)
+docs create drafts/feature.md --products influxdb3_core --open
+
+# Create and open, wait for editor (blocking)
+docs create drafts/feature.md --products influxdb3_core --open --wait
+```
+
+### Editing Existing Content
+
+Use `docs edit` to quickly find and open content files:
+
+```bash
+# Find and list files (no editor)
+docs edit /influxdb3/core/admin/databases/ --list
+
+# Open in editor (non-blocking, exits immediately)
+docs edit /influxdb3/core/admin/databases/
+
+# Open and wait for editor (blocking, interactive)
+docs edit /influxdb3/core/admin/databases/ --wait
+
+# Use specific editor
+docs edit /influxdb3/core/admin/databases/ --editor nano
+```
+
+**Note:** Both commands are non-blocking by default (agent-friendly). Use `--wait` for interactive editing sessions.
+
 ## Required for All Content Files
 
 Every content file needs:

README.md

@@ -23,8 +23,24 @@ This repository includes a `docs` CLI tool for common documentation workflows:
 # Create new documentation from a draft
 npx docs create drafts/new-feature.md --products influxdb3_core
 
-# Edit existing documentation from a URL
+# Create and open files in editor (non-blocking)
+npx docs create drafts/new-feature.md --products influxdb3_core --open
+
+# Create and open, wait for editor (blocking)
+npx docs create drafts/new-feature.md --products influxdb3_core --open --wait
+
+# Edit existing documentation (supports full URLs or paths)
 npx docs edit https://docs.influxdata.com/influxdb3/core/admin/
+npx docs edit /influxdb3/core/admin/
+
+# Edit and wait for editor to close (blocking)
+npx docs edit /influxdb3/core/admin/ --wait
+
+# List files without opening
+npx docs edit /influxdb3/core/admin/ --list
+
+# Use a specific editor
+npx docs edit /influxdb3/core/admin/ --editor nano
 
 # Add placeholder syntax to code blocks
 npx docs placeholders content/influxdb3/core/admin/upgrade.md
@@ -35,6 +51,47 @@ npx docs --help
 
 The `docs` command is automatically configured when you run `yarn install`.
 
+### Editor Configuration
+
+The `docs edit` and `docs create --open` commands open documentation files in your preferred editor. By default, they launch the editor in the background and exit immediately (agent-friendly). Use the `--wait` flag for interactive editing sessions.
+
+**Setting Your Editor:**
+
+The CLI selects an editor in this priority order:
+
+1. `--editor` flag
+2. `DOCS_EDITOR` environment variable
+3. `VISUAL` environment variable
+4. `EDITOR` environment variable
+5. System default (vim, nano, etc.)
+
+**Examples:**
+
+```sh
+# Set editor for all commands
+export EDITOR=vim
+
+# Set editor specifically for docs CLI
+export DOCS_EDITOR=nano
+
+# Use VS Code with built-in wait flag
+export DOCS_EDITOR="code --wait"
+```
+
+**For Automated Workflows:**
+
+The default non-blocking behavior prevents AI agents and automation scripts from hanging:
+
+```sh
+# In a script or CI pipeline
+docs edit /some/url           # Returns immediately
+echo "Editor launched"        # This runs right away
+
+# If you need to wait (interactive editing)
+docs edit /some/url --wait    # Blocks until editor closes
+echo "Editor closed"          # This waits for editor to close
+```
+
 ## Documentation
 
 Comprehensive reference documentation for contributors:

content/telegraf/v1/aggregator-plugins/basicstats/_index.md

@@ -10,7 +10,7 @@ introduced: "v1.5.0"
 os_support: "freebsd, linux, macos, solaris, windows"
 related:
   - /telegraf/v1/configure_plugins/
-  - https://github.com/influxdata/telegraf/tree/v1.37.0/plugins/aggregators/basicstats/README.md, Basic Statistics Plugin Source
+  - https://github.com/influxdata/telegraf/tree/v1.37.1/plugins/aggregators/basicstats/README.md, Basic Statistics Plugin Source
 ---
 
 # Basic Statistics Aggregator Plugin

content/telegraf/v1/aggregator-plugins/derivative/_index.md

@@ -10,7 +10,7 @@ introduced: "v1.18.0"
 os_support: "freebsd, linux, macos, solaris, windows"
 related:
   - /telegraf/v1/configure_plugins/
-  - https://github.com/influxdata/telegraf/tree/v1.37.0/plugins/aggregators/derivative/README.md, Derivative Plugin Source
+  - https://github.com/influxdata/telegraf/tree/v1.37.1/plugins/aggregators/derivative/README.md, Derivative Plugin Source
 ---
 
 # Derivative Aggregator Plugin

content/telegraf/v1/aggregator-plugins/final/_index.md

@@ -10,7 +10,7 @@ introduced: "v1.11.0"
 os_support: "freebsd, linux, macos, solaris, windows"
 related:
   - /telegraf/v1/configure_plugins/
-  - https://github.com/influxdata/telegraf/tree/v1.37.0/plugins/aggregators/final/README.md, Final Plugin Source
+  - https://github.com/influxdata/telegraf/tree/v1.37.1/plugins/aggregators/final/README.md, Final Plugin Source
 ---
 
 # Final Aggregator Plugin

content/telegraf/v1/aggregator-plugins/histogram/_index.md

@@ -10,7 +10,7 @@ introduced: "v1.4.0"
 os_support: "freebsd, linux, macos, solaris, windows"
 related:
   - /telegraf/v1/configure_plugins/
-  - https://github.com/influxdata/telegraf/tree/v1.37.0/plugins/aggregators/histogram/README.md, Histogram Plugin Source
+  - https://github.com/influxdata/telegraf/tree/v1.37.1/plugins/aggregators/histogram/README.md, Histogram Plugin Source
 ---
 
 # Histogram Aggregator Plugin

content/telegraf/v1/aggregator-plugins/merge/_index.md

@@ -10,7 +10,7 @@ introduced: "v1.13.0"
 os_support: "freebsd, linux, macos, solaris, windows"
 related:
   - /telegraf/v1/configure_plugins/
-  - https://github.com/influxdata/telegraf/tree/v1.37.0/plugins/aggregators/merge/README.md, Merge Plugin Source
+  - https://github.com/influxdata/telegraf/tree/v1.37.1/plugins/aggregators/merge/README.md, Merge Plugin Source
 ---
 
 # Merge Aggregator Plugin

content/telegraf/v1/aggregator-plugins/minmax/_index.md

@@ -10,7 +10,7 @@ introduced: "v1.1.0"
 os_support: "freebsd, linux, macos, solaris, windows"
 related:
   - /telegraf/v1/configure_plugins/
-  - https://github.com/influxdata/telegraf/tree/v1.37.0/plugins/aggregators/minmax/README.md, Minimum-Maximum Plugin Source
+  - https://github.com/influxdata/telegraf/tree/v1.37.1/plugins/aggregators/minmax/README.md, Minimum-Maximum Plugin Source
 ---
 
 # Minimum-Maximum Aggregator Plugin