Add AI-powered documentation update command

Introduce a new `elastic-package update documentation` command that leverages
LLM providers to automatically generate and update package documentation.

Key features:
- Two operation modes:
  * Rewrite mode: Full documentation regeneration from package structure
  * Modify mode: Targeted changes to existing documentation
- Multi-file support: Update any markdown file in _dev/build/docs/
- Interactive and non-interactive workflows
- Provider flexibility: Support for Gemini API and local LLM servers

Implementation details:
- Add new LLM framework in internal/llmagent/ with:
  * Provider abstraction for different LLM backends
  * Documentation agent with package analysis tools
  * MCP (Model Context Protocol) tools integration
  * Interactive UI with browser-based markdown preview
- Configuration via environment variables or profile config
- Graceful degradation: Show manual update instructions when no provider configured

Command flags:
- --non-interactive: Skip prompts and auto-accept first result
- --modify-prompt: Specify targeted modification instructions
- --doc-file: Select specific markdown file to update

This enables maintainers to quickly generate comprehensive, template-compliant
documentation by analyzing package structure, data streams, and configuration.

Co-Authored-By: Jonathan Molinatto <[email protected]>
Co-Authored-By: Claude <[email protected]>

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: mjwolf

README.md

@@ -638,6 +638,53 @@ Use this command to uninstall the package in Kibana.
 
 The command uses Kibana API to uninstall the package in Kibana. The package must be exposed via the Package Registry.
 
+### `elastic-package update`
+
+_Context: global_
+
+Use this command to update package resources.
+
+The command can help update existing resources in a package. Currently only documentation is supported.
+
+### `elastic-package update documentation`
+
+_Context: global_
+
+Use this command to update package documentation using an AI agent or to get manual instructions for update.
+
+The AI agent supports two modes:
+1. Rewrite mode (default): Full documentation regeneration
+   - Analyzes your package structure, data streams, and configuration
+   - Generates comprehensive documentation following Elastic's templates
+   - Creates or updates markdown files in /_dev/build/docs/
+2. Modify mode: Targeted documentation changes
+   - Makes specific changes to existing documentation
+   - Requires existing documentation file at /_dev/build/docs/
+   - Use --modify-prompt flag for non-interactive modifications
+
+Multi-file support:
+   - Use --doc-file to specify which markdown file to update (defaults to README.md)
+   - In interactive mode, you'll be prompted to select from available files
+   - Supports packages with multiple documentation files (e.g., README.md, vpc.md, etc.)
+
+Interactive workflow:
+After confirming you want to use the AI agent, you'll choose between rewrite or modify mode.
+You can review results and request additional changes iteratively.
+
+Non-interactive mode:
+Use --non-interactive to skip all prompts and automatically accept the first result from the LLM.
+Combine with --modify-prompt "instructions" for targeted non-interactive changes.
+
+If no LLM provider is configured, this command will print instructions for updating the documentation manually.
+
+Configuration options for LLM providers (environment variables or profile config):
+- GEMINI_API_KEY / llm.gemini.api_key: API key for Gemini
+- GEMINI_MODEL / llm.gemini.model: Model ID (defaults to gemini-2.5-pro)
+- LOCAL_LLM_ENDPOINT / llm.local.endpoint: Endpoint for local LLM server
+- LOCAL_LLM_MODEL / llm.local.model: Model name for local LLM (defaults to llama2)
+- LOCAL_LLM_API_KEY / llm.local.api_key: API key for local LLM (optional)
+- LLM_EXTERNAL_PROMPTS / llm.external_prompts: Enable external prompt files (defaults to false).
+
 ### `elastic-package version`
 
 _Context: global_
@@ -690,6 +737,101 @@ The following settings are available per profile:
   Currently, it is supported "basic" and "[trial](https://www.elastic.co/guide/en/elasticsearch/reference/current/start-trial.html)",
   which enables all subscription features for 30 days.  Defaults to "trial".
 
+### AI-powered Documentation Configuration
+
+The `elastic-package update documentation` command supports AI-powered documentation generation using various LLM providers.
+
+**⚠️ IMPORTANT PRIVACY NOTICE:**
+When using AI-powered documentation generation, **file content from your local file system within the package directory may be sent to the configured LLM provider**. This includes manifest files, configuration files, field definitions, and other package content. The generated documentation **must be reviewed for accuracy and correctness** before being finalized, as LLMs may occasionally produce incorrect or hallucinated information.
+
+#### Operation Modes
+
+The command supports two modes of operation:
+
+1. **Rewrite Mode** (default): Full documentation regeneration
+   - Analyzes your package structure, data streams, and configuration
+   - Generates comprehensive documentation following Elastic's templates
+   - Creates or updates the README.md file in `/_dev/build/docs/`
+
+2. **Modify Mode**: Targeted documentation changes
+   - Makes specific changes to existing documentation
+   - Requires existing README.md file at `/_dev/build/docs/README.md`
+   - Use `--modify-prompt` flag for non-interactive modifications
+
+#### Workflow Options
+
+**Interactive Mode** (default): 
+The command will guide you through the process, allowing you to:
+- Choose between rewrite or modify mode
+- Review generated documentation
+- Request iterative changes
+- Accept or cancel the update
+
+**Non-Interactive Mode**:
+Use `--non-interactive` to skip all prompts and automatically accept the first result.
+Combine with `--modify-prompt "instructions"` for targeted non-interactive changes.
+
+If no LLM provider is configured, the command will print manual instructions for updating documentation.
+
+#### LLM Provider Configuration
+
+You can configure LLM providers through **profile settings** (in `~/.elastic-package/profiles/<profile>/config.yml`) as an alternative to environment variables:
+
+* `llm.gemini.api_key`: API key for Google Gemini LLM services  
+* `llm.gemini.model`: Gemini model ID (defaults to `gemini-2.5-pro`)
+* `llm.local.endpoint`: Endpoint URL for local OpenAI-compatible LLM servers
+* `llm.local.model`: Model name for local LLM servers (defaults to `llama2`)
+* `llm.local.api_key`: API key for local LLM servers (optional, if authentication is required)
+* `llm.external_prompts`: Enable loading custom prompt files from profile or data directory (defaults to `false`)
+
+Environment variables (e.g., `GEMINI_API_KEY`, `LOCAL_LLM_ENDPOINT`) take precedence over profile configuration.
+
+#### Usage Examples
+
+```bash
+# Interactive documentation update (rewrite mode)
+elastic-package update documentation
+
+# Interactive modification mode
+elastic-package update documentation
+# (choose "Modify" when prompted)
+
+# Non-interactive rewrite
+elastic-package update documentation --non-interactive
+
+# Non-interactive targeted changes
+elastic-package update documentation --modify-prompt "Add more details about authentication configuration"
+
+# Use specific profile with LLM configuration
+elastic-package update documentation --profile production
+```
+
+#### Advanced Features
+
+**Preserving Human-Edited Content:**
+
+Manually edited sections can be preserved by wrapping them with HTML comment markers:
+
+```html
+<!-- PRESERVE START -->
+Important manual content to preserve
+<!-- PRESERVE END -->
+```
+
+Any content between these markers will be preserved exactly as-is during AI-generated documentation updates. The system will automatically validate preservation after generation and warn if marked content was modified or removed.
+
+**Service Knowledge Base:**
+
+Place a `docs/knowledge_base/service_info.md` file in your package to provide authoritative service information. This file is treated as the source of truth and takes precedence over web search results during documentation generation.
+
+**Custom Prompts:**
+
+Enable `llm.external_prompts` in your profile config to use custom prompt files. Place them in:
+- `~/.elastic-package/profiles/<profile>/prompts/` (profile-specific)
+- `~/.elastic-package/prompts/` (global)
+
+Available prompt files: `initial_prompt.txt`, `revision_prompt.txt`, `limit_hit_prompt.txt`
+
 ## Useful environment variables
 
 There are available some environment variables that could be used to change some of the
@@ -747,6 +889,13 @@ There are available some environment variables that could be used to change some
     - `ELASTIC_PACKAGE_ESMETRICSTORE_PASSWORD`: Password for the user.
     - `ELASTIC_PACKAGE_ESMETRICSTORE_CA_CERT`: Path to the CA certificate to connect to the Elastic stack services.
 
+- To configure LLM providers for AI-powered documentation generation (`elastic-package update documentation`):
+    - `GEMINI_API_KEY`: API key for Gemini LLM services
+    - `GEMINI_MODEL`: Gemini model ID (defaults to `gemini-2.5-pro`)
+    - `LOCAL_LLM_ENDPOINT`: Endpoint URL for local OpenAI-compatible LLM servers.
+    - `LOCAL_LLM_MODEL`: Model name for local LLM servers (defaults to `llama2`)
+    - `LOCAL_LLM_API_KEY`: API key for local LLM servers (optional, if authentication is required)
+
 
 ## Release process
 

cmd/root.go

@@ -37,6 +37,7 @@ var commands = []*cobraext.Command{
 	setupStatusCommand(),
 	setupTestCommand(),
 	setupUninstallCommand(),
+	setupUpdateCommand(),
 	setupVersionCommand(),
 }
 

cmd/update.go

@@ -0,0 +1,41 @@
+// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+// or more contributor license agreements. Licensed under the Elastic License;
+// you may not use this file except in compliance with the Elastic License.
+
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/elastic/elastic-package/internal/cobraext"
+	"github.com/elastic/elastic-package/internal/install"
+)
+
+const updateLongDescription = `Use this command to update package resources.
+
+The command can help update existing resources in a package. Currently only documentation is supported.`
+
+func setupUpdateCommand() *cobraext.Command {
+	updateDocumentationCmd := &cobra.Command{
+		Use:   "documentation",
+		Short: "Update package documentation",
+		Long:  updateDocumentationLongDescription,
+		Args:  cobra.NoArgs,
+		RunE:  updateDocumentationCommandAction,
+	}
+	updateDocumentationCmd.Flags().Bool("non-interactive", false, "run in non-interactive mode, accepting the first result from the LLM")
+	updateDocumentationCmd.Flags().String("modify-prompt", "", "modification instructions for targeted documentation changes (skips full rewrite)")
+	updateDocumentationCmd.Flags().String("doc-file", "", "specify which markdown file to update (e.g., README.md, vpc.md). Defaults to README.md")
+
+	cmd := &cobra.Command{
+		Use:   "update",
+		Short: "Update package resources",
+		Long:  updateLongDescription,
+	}
+	cmd.AddCommand(updateDocumentationCmd)
+	cmd.PersistentFlags().StringP(cobraext.ProfileFlagName, "p", "", fmt.Sprintf(cobraext.ProfileFlagDescription, install.ProfileNameEnvVar))
+
+	return cobraext.NewCommand(cmd, cobraext.ContextGlobal)
+}