From 4b04df6ffce261121903f0c57769811d0fc9d209 Mon Sep 17 00:00:00 2001
From: JivusAyrus <suvijsurya76@gmail.com>
Date: Mon, 28 Jul 2025 16:12:02 +0530
Subject: [PATCH 1/8] feat: add documentation for plugin commands

---
 docs/cli/router/plugin/create.mdx  |  58 +++++++++++
 docs/cli/router/plugin/delete.mdx  |  62 ++++++++++++
 docs/cli/router/plugin/publish.mdx | 150 +++++++++++++++++++++++++++++
 3 files changed, 270 insertions(+)
 create mode 100644 docs/cli/router/plugin/create.mdx
 create mode 100644 docs/cli/router/plugin/delete.mdx
 create mode 100644 docs/cli/router/plugin/publish.mdx

diff --git a/docs/cli/router/plugin/create.mdx b/docs/cli/router/plugin/create.mdx
new file mode 100644
index 00000000..f766de26
--- /dev/null
+++ b/docs/cli/router/plugin/create.mdx
@@ -0,0 +1,58 @@
+---
+title: "Create"
+description: "Creates a federated plugin subgraph on the control plane."
+icon: plus
+---
+
+## Usage
+
+<Note>
+  A plugin subgraph name must be unique within a namespace.
+</Note>
+
+```bash
+npx wgc router plugin create [pluginName] --label [labelName]
+```
+
+<Info>
+  After creating a plugin subgraph, you can publish it with [wgc router plugin
+  publish](/cli/router/plugin/publish).
+</Info>
+
+## Description
+
+The `npx wgc router plugin create` command allows you to create a new plugin subgraph within the Cosmo platform. Plugin subgraphs are specialized GraphQL schemas that extend the functionality of your federated graph through plugins. The `[pluginName]` argument specifies the name of the new plugin subgraph. Use `npx wgc router plugin create -h` to see all the available options.
+
+## **Parameters**
+
+- `[pluginName]`: The name of the plugin subgraph you want to create. It should be a unique identifier (within the namespace) and is used to uniquely identify your plugin subgraph.
+
+## **Options**
+
+- `-n, --namespace` : The namespace of the plugin subgraph (Default: "default").
+
+- `--label`: Assign multiple labels to the new plugin subgraph. Labels are used to categorize and organize subgraphs based on specific criteria (e.g., team, department, project).
+
+  - Example: `--label team=A`
+
+- `--readme <path-to-readme>:` The path to the markdown file which describes the plugin subgraph.
+
+## **Examples**
+
+- Create a new plugin subgraph named "projects" with the label "team=A":
+
+```bash
+npx wgc router plugin create projects --label team=A
+```
+
+- Create a new plugin subgraph with a readme file:
+
+```bash
+npx wgc router plugin create projects --label team=infrastructure --readme ./plugin-readme.md
+```
+
+- Create a plugin subgraph in a specific namespace:
+
+```bash
+npx wgc router plugin create projects --namespace production --label env=prod
+```
diff --git a/docs/cli/router/plugin/delete.mdx b/docs/cli/router/plugin/delete.mdx
new file mode 100644
index 00000000..321bfbbe
--- /dev/null
+++ b/docs/cli/router/plugin/delete.mdx
@@ -0,0 +1,62 @@
+---
+title: "Delete"
+description: "Deletes a plugin subgraph on the control plane. The plugin subgraph will be deleted from all federated graphs."
+icon: trash
+---
+
+## Usage
+
+```bash
+npx wgc router plugin delete <name> [-f, --force]
+```
+
+<Note>
+  **Delete** is an irreversible action. However, the change will only be visible
+  to the routers once the composition has been successful. Until then, the
+  routers will operate with the most recent valid composition. Please use
+  [subgraph check](/cli/subgraph/check) to understand the impact of your change.
+</Note>
+
+## Description
+
+The `npx wgc router plugin delete` command allows you to delete a plugin subgraph on the Cosmo platform's control plane. When you delete a plugin subgraph, all associated data and configurations will be permanently removed. Use this command with caution, as the action cannot be undone.
+
+## Parameters
+
+- `<name>`: The name of the plugin subgraph you want to delete. This should be the exact name of the plugin subgraph you wish to remove.
+
+## Options
+
+- `-n, --namespace` : The namespace of the plugin subgraph (Default: "default").
+
+- `-f, --force`: An optional flag that allows you to force delete the plugin subgraph without being prompted for confirmation. Use this option if you want to delete the plugin subgraph without additional prompts.
+
+- `--suppress-warnings`: This flag suppresses any warnings produced by composition.
+
+## Examples
+
+1. Delete the plugin subgraph named "projects":
+
+   ```bash
+   npx wgc router plugin delete projects
+   ```
+
+2. Force delete the plugin subgraph named "projects" without confirmation:
+
+   ```bash
+   npx wgc router plugin delete projects -f
+   ```
+
+3. Delete a plugin subgraph in a specific namespace:
+
+   ```bash
+   npx wgc router plugin delete projects -n production
+   ```
+
+## Notes
+
+- The `npx wgc router plugin delete` command interacts with the Cosmo platform's control plane to delete the specified plugin subgraph.
+
+- When using the `--force` option, the command will not prompt for confirmation, so exercise caution to prevent accidental data loss.
+
+- If composition errors occur during deletion, the plugin subgraph will still be deleted, but the router will continue to work with the latest valid schema until the composition issues are resolved.
diff --git a/docs/cli/router/plugin/publish.mdx b/docs/cli/router/plugin/publish.mdx
new file mode 100644
index 00000000..e12139d6
--- /dev/null
+++ b/docs/cli/router/plugin/publish.mdx
@@ -0,0 +1,150 @@
+---
+title: "Publish"
+description: "Publishes a plugin subgraph on the control plane. If the plugin subgraph doesn't exist, it will be created and the Docker image will be built and pushed to the registry."
+icon: upload
+---
+
+## **Usage**
+
+```bash
+npx wgc router plugin publish <name> --schema [schemaFilePath] --go-module-path [path] --docker-file [dockerFilePath]
+```
+
+<Note>
+  **Publish** is an irreversible action. However, the change will only be
+  visible to the routers once the composition has been successful. Until then,
+  the routers will operate with the most recent valid composition. Please use
+  [subgraph check](/cli/subgraph/check) to understand the impact of your change.
+</Note>
+
+## **Description**
+
+The `npx wgc router plugin publish` command enables you to publish a plugin subgraph to the Cosmo platform. Publishing a plugin subgraph makes it available for use by federated graphs, allowing them to extend functionality through custom plugins. The command builds and pushes a Docker image containing your plugin to the registry, then publishes the subgraph schema to the control plane.
+
+The `<name>` argument specifies the name of the plugin subgraph, while the required options define the schema file, Go module path, and Docker configuration needed to build and deploy your plugin.
+
+## **Parameters**
+
+- `<name>`: The name of the plugin subgraph to publish. It is used to uniquely identify your plugin subgraph.
+
+## **Options**
+
+### **Required Options**
+
+- `--schema <path-to-schema>`: The schema file to upload to the plugin subgraph. This file should contain the complete GraphQL schema definition for your plugin.
+
+  - Example: `--schema ./plugin.graphql`
+
+- `--go-module-path <path>`: The path of the Go module, used for Go proto generation. This is required for building the plugin.
+
+  - Example: `--go-module-path github.com/myorg/myplugin`
+
+- `--docker-file <path-to-docker-file>`: The path to your Dockerfile that defines how to build the plugin container image.
+
+  - Example: `--docker-file ./Dockerfile`
+
+### **Optional Options**
+
+<Note>
+  If the plugin subgraph has already been created previously, the `label`
+  parameter will be ignored. Use [subgraph update](/cli/subgraph/update) to
+  update these values.
+</Note>
+
+- `-n, --namespace [string]`: The namespace of the plugin subgraph (Default: "default").
+
+- `--docker-context <docker-context>`: The path at which Docker should have context to build the image. Defaults to "." (current directory).
+
+  - Example: `--docker-context ./build-context`
+
+- `--proto-schema <path_to_proto_schema>`: The path to the proto schema file. Must be used together with `--proto-mapping` and `--proto-lock`.
+
+  - Example: `--proto-schema ./schema.proto`
+
+- `--proto-mapping <path_to_proto_mapping>`: The path to the proto mapping file. Must be used together with `--proto-schema` and `--proto-lock`.
+
+  - Example: `--proto-mapping ./mapping.json`
+
+- `--proto-lock <path_to_proto_lock>`: The path to the proto lock file. Must be used together with `--proto-schema` and `--proto-mapping`.
+
+  - Example: `--proto-lock ./proto.lock`
+
+<Note>
+  If any proto option is specified, all three must be provided:
+  `--proto-schema`, `--proto-mapping`, and `--proto-lock`.
+</Note>
+
+- `--platform [platforms...]`: The platforms used to build the Docker image. Pass multiple platforms separated by spaces. Supported formats: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, `windows/amd64`. Defaults to `linux/amd64`.
+
+  - Example: `--platform linux/amd64 linux/arm64`
+
+- `--label [labels...]`: Assign multiple labels to the new plugin subgraph. Labels are used to categorize and organize subgraphs based on specific criteria (e.g., team, department, project). The labels are passed in the format `<key>=<value>`.
+
+  - Example: `--label team=backend --label environment=production`
+
+<Note>
+  If you are *creating* a plugin subgraph for the first time with `router plugin publish`, the `label` parameter can be used to set labels. Note that a subgraph will only be considered for a federated graph composition if the subgraph's labels match the labels matcher of that federated graph.
+
+If you are not creating a plugin subgraph for the first time, the `label` parameter will be ignored. To update the labels of an existing plugin subgraph, use [subgraph update](/cli/subgraph/update).
+
+</Note>
+
+- `--fail-on-composition-error`: If set, the command will fail if the composition of the federated graph fails.
+
+- `--fail-on-admission-webhook-error`: If set, the command will fail if the admission webhook fails.
+
+- `--suppress-warnings`: This flag suppresses any warnings produced by composition.
+
+## **Examples**
+
+### Publish a plugin subgraph with required options
+
+```bash
+npx wgc router plugin publish projects \
+  --schema ./projects.graphql \
+  --go-module-path github.com/myorg/projects \
+  --docker-file ./Dockerfile
+```
+
+### **Create and publish a plugin subgraph with labels and multi-platform support**
+
+```bash
+npx wgc router plugin publish projects \
+  --schema ./projects.graphql \
+  --go-module-path github.com/myorg/projects \
+  --docker-file ./Dockerfile \
+  --label team=backend --label environment=production \
+  --platform linux/amd64 linux/arm64
+```
+
+### **Publish with proto files and custom Docker context**
+
+```bash
+npx wgc router plugin publish projects \
+  --schema ./projects.graphql \
+  --go-module-path github.com/myorg/projects \
+  --docker-file ./build/Dockerfile \
+  --docker-context ./build \
+  --proto-schema ./schema.proto \
+  --proto-mapping ./mapping.json \
+  --proto-lock ./proto.lock
+```
+
+## **Build Process**
+
+The publish command performs the following steps:
+
+1. **Validation**: Validates that all required files exist and proto options are properly configured
+2. **Image Build**: Builds the Docker image using `docker buildx build` with the specified platforms
+3. **Image Push**: Pushes the built image to the plugin registry
+4. **Schema Publish**: Publishes the GraphQL schema to the control plane
+
+## **Notes**
+
+- The `npx wgc router plugin publish` command interacts with the Cosmo platform's control plane to publish the specified plugin subgraph and builds a Docker image that gets pushed to the plugin registry.
+
+- Ensure that Docker is installed and running on your system, as the command builds and pushes Docker images as part of the publication process.
+
+- Double-check that all file paths provided for the various options point to the correct locations of the respective files.
+
+- If the build process fails at any step, the command will exit with an error and provide details about what went wrong.

From 3e90b26fe2b3e0e7cd8d0385e3c9ede3c20bd233 Mon Sep 17 00:00:00 2001
From: JivusAyrus <suvijsurya76@gmail.com>
Date: Wed, 30 Jul 2025 16:10:26 +0530
Subject: [PATCH 2/8] feat: update plugin publish command documentation to
 reflect new usage and directory structure

---
 docs/cli/router/plugin/publish.mdx | 105 ++++++++++++++++-------------
 1 file changed, 57 insertions(+), 48 deletions(-)

diff --git a/docs/cli/router/plugin/publish.mdx b/docs/cli/router/plugin/publish.mdx
index e12139d6..56686c6b 100644
--- a/docs/cli/router/plugin/publish.mdx
+++ b/docs/cli/router/plugin/publish.mdx
@@ -7,9 +7,13 @@ icon: upload
 ## **Usage**
 
 ```bash
-npx wgc router plugin publish <name> --schema [schemaFilePath] --go-module-path [path] --docker-file [dockerFilePath]
+npx wgc router plugin publish <name> --plugin [pluginDirectoryPath]
 ```
 
+<Note>
+  **Prerequisites**: Before publishing, you must first scaffold your plugin using `npx wgc router plugin init <name>` to create the required directory structure and files.
+</Note>
+
 <Note>
   **Publish** is an irreversible action. However, the change will only be
   visible to the routers once the composition has been successful. Until then,
@@ -21,7 +25,7 @@ npx wgc router plugin publish <name> --schema [schemaFilePath] --go-module-path
 
 The `npx wgc router plugin publish` command enables you to publish a plugin subgraph to the Cosmo platform. Publishing a plugin subgraph makes it available for use by federated graphs, allowing them to extend functionality through custom plugins. The command builds and pushes a Docker image containing your plugin to the registry, then publishes the subgraph schema to the control plane.
 
-The `<name>` argument specifies the name of the plugin subgraph, while the required options define the schema file, Go module path, and Docker configuration needed to build and deploy your plugin.
+The command expects a specific directory structure for your plugin and automatically locates the necessary files within the plugin directory. You should first run `npx wgc router plugin init <name>` to scaffold the proper directory structure.
 
 ## **Parameters**
 
@@ -31,17 +35,17 @@ The `<name>` argument specifies the name of the plugin subgraph, while the requi
 
 ### **Required Options**
 
-- `--schema <path-to-schema>`: The schema file to upload to the plugin subgraph. This file should contain the complete GraphQL schema definition for your plugin.
-
-  - Example: `--schema ./plugin.graphql`
+- `--plugin <path-to-plugin-directory>`: The path to the plugin directory containing your plugin files.
 
-- `--go-module-path <path>`: The path of the Go module, used for Go proto generation. This is required for building the plugin.
+### **Plugin Directory Structure**
 
-  - Example: `--go-module-path github.com/myorg/myplugin`
+The plugin directory must contain the following files in their expected locations (created automatically by `npx wgc router plugin init`):
 
-- `--docker-file <path-to-docker-file>`: The path to your Dockerfile that defines how to build the plugin container image.
-
-  - Example: `--docker-file ./Dockerfile`
+- `src/schema.graphql`: The GraphQL schema definition for your plugin
+- `Dockerfile`: The Dockerfile that defines how to build the plugin container image
+- `generated/service.proto`: The protocol buffer schema file
+- `generated/mapping.json`: The protocol buffer mapping file
+- `generated/service.proto.lock.json`: The protocol buffer lock file
 
 ### **Optional Options**
 
@@ -53,27 +57,6 @@ The `<name>` argument specifies the name of the plugin subgraph, while the requi
 
 - `-n, --namespace [string]`: The namespace of the plugin subgraph (Default: "default").
 
-- `--docker-context <docker-context>`: The path at which Docker should have context to build the image. Defaults to "." (current directory).
-
-  - Example: `--docker-context ./build-context`
-
-- `--proto-schema <path_to_proto_schema>`: The path to the proto schema file. Must be used together with `--proto-mapping` and `--proto-lock`.
-
-  - Example: `--proto-schema ./schema.proto`
-
-- `--proto-mapping <path_to_proto_mapping>`: The path to the proto mapping file. Must be used together with `--proto-schema` and `--proto-lock`.
-
-  - Example: `--proto-mapping ./mapping.json`
-
-- `--proto-lock <path_to_proto_lock>`: The path to the proto lock file. Must be used together with `--proto-schema` and `--proto-mapping`.
-
-  - Example: `--proto-lock ./proto.lock`
-
-<Note>
-  If any proto option is specified, all three must be provided:
-  `--proto-schema`, `--proto-mapping`, and `--proto-lock`.
-</Note>
-
 - `--platform [platforms...]`: The platforms used to build the Docker image. Pass multiple platforms separated by spaces. Supported formats: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, `windows/amd64`. Defaults to `linux/amd64`.
 
   - Example: `--platform linux/amd64 linux/arm64`
@@ -100,41 +83,56 @@ If you are not creating a plugin subgraph for the first time, the `label` parame
 ### Publish a plugin subgraph with required options
 
 ```bash
-npx wgc router plugin publish projects \
-  --schema ./projects.graphql \
-  --go-module-path github.com/myorg/projects \
-  --docker-file ./Dockerfile
+npx wgc router plugin publish projects --plugin ./my-plugin
 ```
 
 ### **Create and publish a plugin subgraph with labels and multi-platform support**
 
 ```bash
 npx wgc router plugin publish projects \
-  --schema ./projects.graphql \
-  --go-module-path github.com/myorg/projects \
-  --docker-file ./Dockerfile \
+  --plugin ./my-plugin \
   --label team=backend --label environment=production \
   --platform linux/amd64 linux/arm64
 ```
 
-### **Publish with proto files and custom Docker context**
+### **Publish with custom namespace**
 
 ```bash
 npx wgc router plugin publish projects \
-  --schema ./projects.graphql \
-  --go-module-path github.com/myorg/projects \
-  --docker-file ./build/Dockerfile \
-  --docker-context ./build \
-  --proto-schema ./schema.proto \
-  --proto-mapping ./mapping.json \
-  --proto-lock ./proto.lock
+  --plugin ./my-plugin \
+  --namespace production
 ```
 
+## **Typical Workflow**
+
+Here's the recommended workflow for developing and publishing a plugin:
+
+1. **Initialize the plugin**:
+
+   ```bash
+   npx wgc router plugin init my-plugin
+   ```
+
+   This creates the plugin in the `plugins/my-plugin/` directory.
+
+2. **Develop your plugin**: Modify the generated files as needed:
+
+   - Edit `src/schema.graphql` to define your GraphQL schema
+   - Implement your plugin logic in `src/main.go`
+   - Update the `Dockerfile` if needed for custom build requirements
+
+3. **Test your plugin locally**: Use the generated `Makefile` commands to build and test
+
+4. **Publish the plugin**:
+   ```bash
+   npx wgc router plugin publish my-plugin --plugin ./plugins/my-plugin
+   ```
+
 ## **Build Process**
 
 The publish command performs the following steps:
 
-1. **Validation**: Validates that all required files exist and proto options are properly configured
+1. **Validation**: Validates that all required files exist in the plugin directory at their expected locations
 2. **Image Build**: Builds the Docker image using `docker buildx build` with the specified platforms
 3. **Image Push**: Pushes the built image to the plugin registry
 4. **Schema Publish**: Publishes the GraphQL schema to the control plane
@@ -145,6 +143,17 @@ The publish command performs the following steps:
 
 - Ensure that Docker is installed and running on your system, as the command builds and pushes Docker images as part of the publication process.
 
-- Double-check that all file paths provided for the various options point to the correct locations of the respective files.
+- The command expects a specific directory structure with files in predetermined locations. Make sure your plugin follows this structure (created by running `npx wgc router plugin init <name>`):
+
+  ```
+  my-plugin/
+  ├── src/
+  │   └── schema.graphql
+  ├── generated/
+  │   ├── service.proto
+  │   ├── mapping.json
+  │   └── service.proto.lock.json
+  └── Dockerfile
+  ```
 
 - If the build process fails at any step, the command will exit with an error and provide details about what went wrong.

From dc892608e986fdd331f07367463ce3d76eaa4108 Mon Sep 17 00:00:00 2001
From: JivusAyrus <suvijsurya76@gmail.com>
Date: Wed, 30 Jul 2025 18:32:53 +0530
Subject: [PATCH 3/8] feat: refine plugin publish command documentation to
 clarify usage and directory structure

---
 docs/cli/router/plugin/publish.mdx | 30 ++++++++++++++++--------------
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/docs/cli/router/plugin/publish.mdx b/docs/cli/router/plugin/publish.mdx
index 56686c6b..6a045fc6 100644
--- a/docs/cli/router/plugin/publish.mdx
+++ b/docs/cli/router/plugin/publish.mdx
@@ -7,7 +7,7 @@ icon: upload
 ## **Usage**
 
 ```bash
-npx wgc router plugin publish <name> --plugin [pluginDirectoryPath]
+npx wgc router plugin publish [directory]
 ```
 
 <Note>
@@ -25,18 +25,14 @@ npx wgc router plugin publish <name> --plugin [pluginDirectoryPath]
 
 The `npx wgc router plugin publish` command enables you to publish a plugin subgraph to the Cosmo platform. Publishing a plugin subgraph makes it available for use by federated graphs, allowing them to extend functionality through custom plugins. The command builds and pushes a Docker image containing your plugin to the registry, then publishes the subgraph schema to the control plane.
 
-The command expects a specific directory structure for your plugin and automatically locates the necessary files within the plugin directory. You should first run `npx wgc router plugin init <name>` to scaffold the proper directory structure.
+The command expects a specific directory structure for your plugin and automatically locates the necessary files within the plugin directory. The plugin name is derived from the directory name. You should first run `npx wgc router plugin init <name>` to scaffold the proper directory structure.
 
 ## **Parameters**
 
-- `<name>`: The name of the plugin subgraph to publish. It is used to uniquely identify your plugin subgraph.
+- `[directory]`: The path to the plugin directory (optional, defaults to current directory). The plugin name is automatically derived from the directory name.
 
 ## **Options**
 
-### **Required Options**
-
-- `--plugin <path-to-plugin-directory>`: The path to the plugin directory containing your plugin files.
-
 ### **Plugin Directory Structure**
 
 The plugin directory must contain the following files in their expected locations (created automatically by `npx wgc router plugin init`):
@@ -80,17 +76,16 @@ If you are not creating a plugin subgraph for the first time, the `label` parame
 
 ## **Examples**
 
-### Publish a plugin subgraph with required options
+### Publish a plugin subgraph
 
 ```bash
-npx wgc router plugin publish projects --plugin ./my-plugin
+npx wgc router plugin publish ./plugins/my-plugin
 ```
 
 ### **Create and publish a plugin subgraph with labels and multi-platform support**
 
 ```bash
-npx wgc router plugin publish projects \
-  --plugin ./my-plugin \
+npx wgc router plugin publish ./plugins/my-plugin \
   --label team=backend --label environment=production \
   --platform linux/amd64 linux/arm64
 ```
@@ -98,8 +93,7 @@ npx wgc router plugin publish projects \
 ### **Publish with custom namespace**
 
 ```bash
-npx wgc router plugin publish projects \
-  --plugin ./my-plugin \
+npx wgc router plugin publish ./plugins/my-plugin \
   --namespace production
 ```
 
@@ -124,8 +118,14 @@ Here's the recommended workflow for developing and publishing a plugin:
 3. **Test your plugin locally**: Use the generated `Makefile` commands to build and test
 
 4. **Publish the plugin**:
+
    ```bash
-   npx wgc router plugin publish my-plugin --plugin ./plugins/my-plugin
+   # Option 1: Specify the directory path
+   npx wgc router plugin publish ./plugins/my-plugin
+
+   # Option 2: Run from within the plugin directory
+   cd ./plugins/my-plugin
+   npx wgc router plugin publish
    ```
 
 ## **Build Process**
@@ -156,4 +156,6 @@ The publish command performs the following steps:
   └── Dockerfile
   ```
 
+- The plugin name is automatically derived from the directory name (e.g., if your plugin is in `./plugins/my-awesome-plugin`, the plugin name will be `my-awesome-plugin`).
+
 - If the build process fails at any step, the command will exit with an error and provide details about what went wrong.

From b17675dcdb446160430e48db688a14e66129e615 Mon Sep 17 00:00:00 2001
From: JivusAyrus <suvijsurya76@gmail.com>
Date: Thu, 7 Aug 2025 23:19:43 +0530
Subject: [PATCH 4/8] feat: add documentation for the generate command in
 router plugin

---
 docs/cli/router/plugin/generate.mdx | 90 +++++++++++++++++++++++++++++
 docs/cli/router/plugin/publish.mdx  |  1 +
 2 files changed, 91 insertions(+)
 create mode 100644 docs/cli/router/plugin/generate.mdx

diff --git a/docs/cli/router/plugin/generate.mdx b/docs/cli/router/plugin/generate.mdx
new file mode 100644
index 00000000..21620280
--- /dev/null
+++ b/docs/cli/router/plugin/generate.mdx
@@ -0,0 +1,90 @@
+---
+title: "Generate"
+description: "Generate proto and gRPC code for a router plugin"
+icon: "code"
+---
+
+# wgc router plugin generate
+
+The `generate` command creates Protocol Buffers definitions, mapping files, and gRPC code based on your GraphQL schema. This command is useful when you want to generate the necessary code without compiling binaries.
+
+## Usage
+
+```bash
+wgc router plugin generate [directory] [options]
+```
+
+## Arguments
+
+| Argument    | Description             | Default                 |
+| ----------- | ----------------------- | ----------------------- |
+| `directory` | Directory of the plugin | `.` (current directory) |
+
+## Options
+
+| Option                       | Description                                                          | Default                               |
+| ---------------------------- | -------------------------------------------------------------------- | ------------------------------------- |
+| `--go-module-path <path>`    | Go module path to use for the plugin                                 | `github.com/wundergraph/cosmo/plugin` |
+| `--skip-tools-installation`  | Skip tool installation                                               | `false`                               |
+| `--force-tools-installation` | Force tools installation regardless of version check or confirmation | `false`                               |
+
+## Description
+
+This command performs the code generation steps of the plugin build process:
+
+1. **Generate Proto and Mapping Files**: Processes your GraphQL schema to generate Protocol Buffers definitions and mapping files
+2. **Generate gRPC Code**: Uses the generated Proto files to create Go code for the gRPC service
+3. **Install Go Dependencies**: Installs all required Go dependencies for your plugin
+
+The `generate` command is equivalent to running [`build`](./build) with the `--generate-only` flag. Use this when you're iterating on your GraphQL schema and need to regenerate the code without compiling binaries.
+
+## Required Tools
+
+The generate command will automatically check for and install the necessary toolchain when required tools can't be found in the right version on your system. You can control this behavior with the `--skip-tools-installation` and `--force-tools-installation` flags.
+
+You can also install the dependencies manually and use an IDE with Go support. The following table shows the current versions and download links for the required tools:
+
+| Tool                      | Version                    | Installation Link                                                          |
+| ------------------------- | -------------------------- | -------------------------------------------------------------------------- |
+| Go                        | >=1.22.0 (Last 2 versions) | [Releases](https://go.dev/doc/install)                                     |
+| Protocol Buffers (protoc) | ^29.3                      | [Releases](https://protobuf.dev/installation/)                             |
+| protoc-gen-go             | ^1.34.2                    | [GitHub Releases](https://github.com/protocolbuffers/protobuf-go/releases) |
+| protoc-gen-go-grpc        | ^1.5.1                     | [GitHub Releases](https://github.com/grpc/grpc-go/releases)                |
+
+## Examples
+
+### Generate code for the current directory
+
+```bash
+wgc router plugin generate
+```
+
+### Generate code for a specific plugin directory
+
+```bash
+wgc router plugin generate ./my-plugin
+```
+
+### Generate with a custom Go module path
+
+```bash
+wgc router plugin generate --go-module-path github.com/myorg/my-plugin ./my-plugin
+```
+
+### Skip tool installation (useful in CI environments)
+
+```bash
+wgc router plugin generate --skip-tools-installation ./my-plugin
+```
+
+## Output
+
+The generate process creates the following outputs:
+
+- **Proto files**: Protocol Buffers definitions in the `generated/` directory
+- **Mapping files**: Schema mapping files that connect your GraphQL schema to the gRPC service
+- **Generated Go code**: gRPC client and server code in the `generated/` directory
+- **Go dependencies**: All required dependencies will be installed in your Go module
+
+After generating, you can continue development with your IDE or run [`build`](./build) to compile the plugin into binaries.
+
diff --git a/docs/cli/router/plugin/publish.mdx b/docs/cli/router/plugin/publish.mdx
index 6a045fc6..a3cb3647 100644
--- a/docs/cli/router/plugin/publish.mdx
+++ b/docs/cli/router/plugin/publish.mdx
@@ -50,6 +50,7 @@ The plugin directory must contain the following files in their expected location
   parameter will be ignored. Use [subgraph update](/cli/subgraph/update) to
   update these values.
 </Note>
+- `--name [string]`: The name of the plugin subgraph. If not provided, the name will be derived from the directory name.
 
 - `-n, --namespace [string]`: The namespace of the plugin subgraph (Default: "default").
 

From 564e938090a2bf4c4aeb5b927c9b6080055b6c0a Mon Sep 17 00:00:00 2001
From: JivusAyrus <suvijsurya76@gmail.com>
Date: Thu, 7 Aug 2025 23:37:47 +0530
Subject: [PATCH 5/8] feat: enhance feature subgraph documentation to clarify
 routing URL requirements and base subgraph types

---
 .../create-feature-subgraph.mdx                 | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/docs/cli/feature-subgraph/create-feature-subgraph.mdx b/docs/cli/feature-subgraph/create-feature-subgraph.mdx
index 9c3ee3ae..14741f0d 100644
--- a/docs/cli/feature-subgraph/create-feature-subgraph.mdx
+++ b/docs/cli/feature-subgraph/create-feature-subgraph.mdx
@@ -19,7 +19,6 @@ Create a feature subgraph based on an existing subgraph for your federated graph
 
 <Note>
   A feature subgraph does not function in isolation. One or more feature subgraphs must compose a [feature flag](/cli/feature-flags), which itself must be enabled to take effect.
-
 </Note>
 ```bash
 wgc feature-subgraph create my-feature-subgraph --subgraph my-subgraph --routing-url http://localhost:4000
@@ -29,6 +28,10 @@ The alias for `feature-subgraph` is `fs`.
 
 Note that unless specified by the `--namespace` parameter, the namespace will be automatically passed as "default".
 
+<Note>
+  The type of the feature subgraph is determined by the type of the base subgraph. For example, if the base subgraph is a plugin subgraph, the feature subgraph will also be a plugin subgraph.
+</Note>
+
 ## Parameters
 
 * `<name>`: The name of the feature subgraph to create. Must be unique among all subgraphs and feature subgraphs within the specified (otherwise "default") namespace.
@@ -36,13 +39,9 @@ Note that unless specified by the `--namespace` parameter, the namespace will be
 ## Required Options
 
 <Note>
-  If the routing URL is not supplied, or the base subgraph does not exist in the specified (otherwise "default") namespace, the command will fail.
+  If the base subgraph does not exist in the specified (otherwise "default") namespace, the command will fail.
 </Note>
 
-`-r , --routing-url`: Set the URL for the subgraph's data source. This URL defines the endpoint from which the subgraph will fetch data.
-
-* Example: `--routing-url http://localhost:4001/graphql`
-
 `--subgraph`: The name of the existing base subgraph for which the feature subgraph is to be created.
 
 ## Options
@@ -51,6 +50,12 @@ Note that unless specified by the `--namespace` parameter, the namespace will be
   Feature subgraphs do not use labels directly; labels are set by the [feature flag](/cli/feature-flags) that the feature subgraph(s) compose.
 </Info>
 
+<Note>
+  If the base subgraph is not a plugin subgraph, the routing url is required.
+</Note>
+
+* `-r , --routing-url`: Set the URL for the subgraph's data source. This URL defines the endpoint from which the subgraph will fetch data.
+
 * `-n, --namespace` : The namespace of the feature subgraph (defaults to "default"). Returns an error if the feature flag does not exist in that namespace.
 
 * `--subscription-url:` Use a different URL for subscription requests. If no subscription URL is provided, the router URL is used for subscriptions.

From 0b1db4cafcc9f4bda67e25668215044ae942c2e7 Mon Sep 17 00:00:00 2001
From: JivusAyrus <suvijsurya76@gmail.com>
Date: Thu, 7 Aug 2025 23:39:58 +0530
Subject: [PATCH 6/8] feat: add warning to subgraph publish documentation about
 using router plugin for plugin subgraphs

---
 docs/cli/subgraph/publish.mdx | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/cli/subgraph/publish.mdx b/docs/cli/subgraph/publish.mdx
index cd101890..9a8f165d 100644
--- a/docs/cli/subgraph/publish.mdx
+++ b/docs/cli/subgraph/publish.mdx
@@ -22,6 +22,10 @@ The `npx wgc subgraph publish` command enables you to publish a specific subgrap
 A previously created [Event-Driven Graph (EDG)](/federation/event-driven-federated-subscriptions)cannot be changed into a regular subgraph. Similarly, a regular subgraph cannot be changed into an EDG. Attempting to do either of these actions will result in an error.
 </Warning>
 
+<Warning>
+  If you want to publish a plugin subgraph, you must use the [router plugin publish](/cli/router/plugin/publish) command instead.
+</Warning>
+
 ## **Parameters**
 
 * `[subgraphName]`: The name of the subgraph you want to publish. Make sure to use the correct name of the subgraph you previously created.

From b22c0f78d56414bc8a6dfc846baf0f951374d1bc Mon Sep 17 00:00:00 2001
From: JivusAyrus <suvijsurya76@gmail.com>
Date: Fri, 8 Aug 2025 01:31:52 +0530
Subject: [PATCH 7/8] feat: enhance plugin publish documentation with custom
 name usage and formatting improvements

---
 docs/cli/router/plugin/publish.mdx | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/docs/cli/router/plugin/publish.mdx b/docs/cli/router/plugin/publish.mdx
index a3cb3647..6c7bb2a6 100644
--- a/docs/cli/router/plugin/publish.mdx
+++ b/docs/cli/router/plugin/publish.mdx
@@ -50,7 +50,8 @@ The plugin directory must contain the following files in their expected location
   parameter will be ignored. Use [subgraph update](/cli/subgraph/update) to
   update these values.
 </Note>
-- `--name [string]`: The name of the plugin subgraph. If not provided, the name will be derived from the directory name.
+- `--name [string]`: The name of the plugin subgraph. If not provided, the name will
+be derived from the directory name.
 
 - `-n, --namespace [string]`: The namespace of the plugin subgraph (Default: "default").
 
@@ -91,6 +92,19 @@ npx wgc router plugin publish ./plugins/my-plugin \
   --platform linux/amd64 linux/arm64
 ```
 
+### **Publish with custom name**
+
+<Note>
+  If the plugin name is not provided, the name will be derived from the
+  directory name. This is mainly used to publish plugin feature subgraphs, as
+  the directory will still be the base subgraph.
+</Note>
+
+```bash
+npx wgc router plugin publish ./plugins/my-plugin \
+  --name my-custom-name
+```
+
 ### **Publish with custom namespace**
 
 ```bash

From a810f4d02c65e572c52e3e6458dbf1d4e8ac38a6 Mon Sep 17 00:00:00 2001
From: JivusAyrus <suvijsurya76@gmail.com>
Date: Fri, 8 Aug 2025 18:13:27 +0530
Subject: [PATCH 8/8] fix: update plugin publish documentation to clarify
 default platform behavior and include current platform support

---
 docs/cli/router/plugin/publish.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/cli/router/plugin/publish.mdx b/docs/cli/router/plugin/publish.mdx
index 6c7bb2a6..b12c227f 100644
--- a/docs/cli/router/plugin/publish.mdx
+++ b/docs/cli/router/plugin/publish.mdx
@@ -55,7 +55,7 @@ be derived from the directory name.
 
 - `-n, --namespace [string]`: The namespace of the plugin subgraph (Default: "default").
 
-- `--platform [platforms...]`: The platforms used to build the Docker image. Pass multiple platforms separated by spaces. Supported formats: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, `windows/amd64`. Defaults to `linux/amd64`.
+- `--platform [platforms...]`: The platforms used to build the Docker image. Pass multiple platforms separated by spaces. Supported formats: `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, `windows/amd64`. Defaults to `linux/amd64` and includes your current platform if supported.
 
   - Example: `--platform linux/amd64 linux/arm64`