easyp-tech · Feb 21, 2026 · Feb 15, 2026 · Feb 21, 2026
diff --git a/.gitignore b/.gitignore
@@ -2,7 +2,7 @@
 certs
 .env
 bin
-easyp
+/easyp
 coverage.out
 easyp.lock
 .DS_Store

diff --git a/README.md b/README.md
@@ -115,8 +115,6 @@ While Protocol Buffers offer significant technical advantages over REST/JSON, ac
 EasyP uses a single `easyp.yaml` file for all configuration:
 
 ```yaml
-version: v1alpha
-
 # Dependencies
 deps:
   - github.com/googleapis/googleapis@common-protos-1_3_1
@@ -150,9 +148,8 @@ lint:
 # Validate the default easyp.yaml with JSON output (default)
 easyp validate-config
 
-# Validate a custom file with text output
-easyp validate-config --config example.easyp.yaml --format text
-```
+# Validate a custom file with text output (global --format flag)
+easyp --format text validate-config --config example.easyp.yaml
 ```
 
 ## Community

diff --git a/docs/dist/docs/guide/cli/breaking-changes/breaking-changes.md b/docs/dist/docs/guide/cli/breaking-changes/breaking-changes.md
@@ -40,8 +40,6 @@ This provides strong compatibility guarantees while being less strict than some
 Configure breaking changes detection in your `easyp.yaml`:
 
 ```yaml
-version: v1alpha
-
 breaking:
   # Git reference to compare against (branch, tag, or commit hash)
   against_git_ref: "main"

diff --git a/docs/dist/docs/guide/cli/configuration/configuration.md b/docs/dist/docs/guide/cli/configuration/configuration.md
@@ -13,6 +13,7 @@ Available for all commands:
 | `--cfg` | `-c` | `EASYP_CFG` | Configuration file path | `easyp.yaml` |
 | `--config` | | `EASYP_CFG` | Alias for `--cfg` | `easyp.yaml` |
 | `--debug` | `-d` | `EASYP_DEBUG` | Enable debug mode | `false` |
+| `--format` | `-f` | `EASYP_FORMAT` | Output format for commands that support multiple formats (`text`/`json`) | command-specific default |
 
 **Examples:**
 ```bash
@@ -37,7 +38,7 @@ easyp lint [flags]
 |------|-------|-------------|-------------|---------|
 | `--path` | `-p` | | Directory path to lint | `.` |
 | `--root` | `-r` | | Base directory for file search | Current working directory |
-| `--format` | `-f` | `EASYP_FORMAT` | Output format (text/json) | `text` |
+| `--format` | `-f` | `EASYP_FORMAT` | Uses global format flag (`text`/`json`) | Inherits global default |
 
 **Examples:**
 ```bash
@@ -48,7 +49,7 @@ easyp lint --path proto/
 easyp lint --root src/IPC/Contracts --path .
 
 # JSON output format
-easyp lint --format json
+easyp lint --format json   # global flag
 
 # Combined flags
 easyp lint -p proto/ -f json
@@ -85,7 +86,7 @@ easyp breaking [flags]
 |------|-------|-------------|-------------|---------|
 | `--against` | | | Git ref to compare against | (required) |
 | `--path` | `-p` | | Directory path to check | `.` |
-| `--format` | `-f` | `EASYP_FORMAT` | Output format (text/json) | `text` |
+| `--format` | `-f` | `EASYP_FORMAT` | Uses global format flag (`text`/`json`) | Inherits global default |
 
 **Examples:**
 ```bash
@@ -96,7 +97,7 @@ easyp breaking --against main
 easyp breaking --against develop --path proto/
 
 # JSON output
-easyp breaking --against main --format json
+easyp breaking --against main --format json   # global flag
 ```
 
 **Init command:**
@@ -117,6 +118,10 @@ easyp init
 easyp init --dir proto-project/
 ```
 
+`easyp init` is interactive:
+- If `buf.yml`/`buf.yaml` exists in the target directory root, it asks whether to migrate from Buf.
+- If `easyp.yaml` already exists, it asks for overwrite confirmation.
+
 **Validate-config command:**
 ```bash
 easyp validate-config [flags]
@@ -125,15 +130,15 @@ easyp validate-config [flags]
 | Flag | Short | Environment | Description | Default |
 |------|-------|-------------|-------------|---------|
 | `--config` | `-c` | `EASYP_CFG` | Configuration file path | `easyp.yaml` |
-| `--format` | `-f` | | Output format (`json` or `text`) | `json` |
+| `--format` (global) | `-f` | `EASYP_FORMAT` | Output format for commands that support multiple formats (`json` or `text`) | command-specific (`json` for `validate-config`) |
 
 **Examples:**
 ```bash
 # Validate default config with JSON output (exit 0 when no errors)
 easyp validate-config
 
-# Validate a different file with text output
-easyp validate-config --config example.easyp.yaml --format text
+# Validate a different file with text output (global --format)
+easyp --format text validate-config --config example.easyp.yaml
 ```
 
 **Package management commands:**
@@ -180,7 +185,7 @@ EasyP supports environment variables for configuration:
 | `EASYP_CFG` | Path to configuration file | `easyp.yaml` |
 | `EASYP_DEBUG` | Enable debug logging | `false` |
 | `EASYPPATH` | Cache and modules storage directory | `$HOME/.easyp` |
-| `EASYP_FORMAT` | Output format for lint command | `text` |
+| `EASYP_FORMAT` | Output format for supported commands (`text`/`json`). If not set, each command uses its own default. | command-specific default |
 | `EASYP_ROOT_GENERATE_PATH` | Root path for generate command | `.` |
 | `EASYP_INIT_DIR` | Directory for init command | `.` |
 
@@ -223,7 +228,6 @@ EasyP supports both YAML and JSON configuration formats:
 
 #### YAML Format (Recommended)
 ```yaml
-version: v1alpha
 lint:
   use:
     - BASIC
@@ -247,7 +251,6 @@ breaking:
 #### JSON Format
 ```json
 {
-  "version": "v1alpha",
   "lint": {
     "use": ["BASIC", "COMMENT_SERVICE"]
   },
@@ -281,8 +284,6 @@ EasyP supports environment variable expansion directly in the `easyp.yaml` confi
 
 **Example with all supported features:**
 ```yaml
-version: v1alpha
-
 deps:
   # Basic expansion: ${VAR} - expands to the value of VAR
   - ${GOOGLEAPIS_REPO}@${GOOGLEAPIS_VERSION}
@@ -322,17 +323,18 @@ generate:
 
 ### `version`
 
-**Required.** Specifies the configuration schema version.
+**Optional (legacy compatibility).** This field is accepted for backward compatibility and can be omitted in new configs.
 
 **Type:** `string`
-**Accepted values:** `v1alpha`
-**Default:** None (must be specified)
+**Default:** omitted
+**Recommendation:** if you keep it, use `v1alpha`
 
 ```yaml
+# Optional compatibility field (can be omitted)
 version: v1alpha
 ```
 
-Future versions will be `v1beta`, `v1`, etc. Currently only `v1alpha` is supported.
+The runtime behavior does not depend on this field.
 
 ### `lint`
 
@@ -760,7 +762,6 @@ Can be overridden by the `--against` CLI flag.
 ### Minimal Configuration
 
 ```yaml
-version: v1alpha
 lint:
   use:
     - MINIMAL
@@ -769,7 +770,6 @@ lint:
 ### Development Configuration
 
 ```yaml
-version: v1alpha
 lint:
   use:
     - BASIC
@@ -798,7 +798,6 @@ generate:
 ### Production Configuration
 
 ```yaml
-version: v1alpha
 lint:
   use:
     - MINIMAL
@@ -845,7 +844,6 @@ breaking:
 ### Multi-Service Configuration
 
 ```yaml
-version: v1alpha
 lint:
   use:
     - BASIC
@@ -900,8 +898,8 @@ EasyP validates configuration files on startup and provides helpful error messag
 # Invalid rule name
 Error: invalid rule: INVALID_RULE_NAME
 
-# Missing required field
-Error: version field is required
+# Missing required field in generate section
+Error: required field "plugins" is missing (path: generate.plugins)
 
 # Invalid dependency format
 Error: invalid dependency format: invalid-repo-url
@@ -913,9 +911,9 @@ Use `easyp --debug` for detailed validation information.
 
 EasyP is fully compatible with Buf configurations. To migrate:
 
-1. Rename `buf.yaml` to `easyp.yaml`
-2. Change `version: v1` to `version: v1alpha`
+1. Place `buf.yaml` or `buf.yml` in the project root
+2. Run `easyp init` and confirm migration when prompted
 3. Update `deps` format if using BSR modules
-4. Adjust any custom lint rules or breaking change configurations
+4. Review migrated lint/breaking settings and adjust as needed
 
 Most Buf configurations work without changes in EasyP.
diff --git a/docs/dist/docs/guide/cli/generator/examples/go.md b/docs/dist/docs/guide/cli/generator/examples/go.md
@@ -49,8 +49,6 @@ message EchoStreamResponse {
 Create and configure the easyp.yaml configuration file:
 
 ```yaml
-version: v1alpha
-
 generate:
   plugins:
     - name: go

diff --git a/docs/dist/docs/guide/cli/generator/examples/grpc-gateway.md b/docs/dist/docs/guide/cli/generator/examples/grpc-gateway.md
@@ -71,8 +71,6 @@ message EchoResponse {
 Update your `easyp.yaml` configuration file to include the necessary dependencies and plugins:
 
 ```yaml
-version: v1alpha
-
 deps:  # [!code ++]
   - github.com/googleapis/googleapis  # [!code ++]
 

diff --git a/docs/dist/docs/guide/cli/generator/examples/validate.md b/docs/dist/docs/guide/cli/generator/examples/validate.md
@@ -52,8 +52,6 @@ message EchoStreamResponse {
 Create and configure the easyp.yaml configuration file:
 
 ```yaml
-version: v1alpha
-
 deps: # [!code ++]
   - github.com/bufbuild/protoc-gen-validate  # [!code ++]
 

diff --git a/docs/dist/docs/guide/cli/generator/generator.md b/docs/dist/docs/guide/cli/generator/generator.md
@@ -34,8 +34,6 @@ EasyP includes a powerful generator that simplifies the process of generating co
 ### Complete Configuration Example
 
 ```yaml
-version: v1alpha
-
 # Package manager dependencies
 deps:
   - github.com/googleapis/googleapis@common-protos-1_3_1
@@ -821,6 +819,29 @@ When multiple rules match the same file or field, the following precedence appli
 
 EasyP's managed mode is compatible with `buf`'s managed mode. The same configuration format and behavior apply, making it easy to migrate between tools or use both in the same workflow.
 
+## Descriptor Set Generation
+
+**https://protobuf.dev/programming-guides/techniques/#self-description**
+
+EasyP supports generating binary FileDescriptorSet files using the `--descriptor_set_out` flag. This allows you to create self-describing protobuf messages that include schema information alongside the data.
+
+**CLI flags:**
+
+- `--descriptor_set_out <path>` - Output path for the binary FileDescriptorSet
+- `--include_imports` - Include all transitive dependencies in the FileDescriptorSet
+
+**Example:**
+
+```bash
+# Generate descriptor set with only target files
+easyp generate --descriptor_set_out=./schema.pb
+
+# Generate descriptor set with all dependencies
+easyp generate --descriptor_set_out=./schema.pb --include_imports
+```
+
+Self-describing messages are useful for dynamic message parsing, runtime schema validation, schema registries, and building generic gRPC clients. For more information, see the [Protocol Buffers documentation on self-description](https://protobuf.dev/programming-guides/techniques/#self-description).
+
 ## Package Manager Integration
 
 One of EasyP's most powerful features is the seamless integration between the package manager and code generator. This integration eliminates the common problem of managing proto dependencies manually and ensures that your generated code always has access to the correct versions of imported proto files.

diff --git a/docs/dist/docs/guide/cli/linter/linter.md b/docs/dist/docs/guide/cli/linter/linter.md
@@ -17,8 +17,6 @@ EasyP linter provides flexible configuration options to adapt to different proje
 ### Complete Configuration Example
 
 ```yaml
-version: v1alpha
-
 lint:
   # Rules and categories to use
   use:

diff --git a/docs/dist/docs/guide/cli/package-manager/package-manager.md b/docs/dist/docs/guide/cli/package-manager/package-manager.md
@@ -69,8 +69,6 @@ EasyP uses a two-tier caching system inspired by Go modules:
 Configure dependencies in your `easyp.yaml` file:
 
 ```yaml
-version: v1alpha
-
 deps:
   - github.com/googleapis/googleapis@common-protos-1_3_1
   - github.com/grpc-ecosystem/grpc-gateway@v2.19.1
@@ -335,7 +333,6 @@ git config --global http.sslCAInfo /path/to/certificate.pem
 ```bash
 # 1. Create configuration
 cat > easyp.yaml << EOF
-version: v1alpha
 deps:
   - github.com/googleapis/googleapis
   - github.com/grpc-ecosystem/grpc-gateway@v2.19.1
@@ -494,7 +491,7 @@ find ~/.easyp/mod -type d -name "v0.0.0-*" -mtime +30 -exec rm -rf {} \;
 
 ```dockerfile
 # Stage 1: Download dependencies
-FROM ghcr.io/easyp-tech/easyp:latest AS deps
+FROM easyp/easyp:latest AS deps
 WORKDIR /workspace
 COPY easyp.yaml easyp.lock ./
 RUN easyp mod vendor

diff --git a/docs/dist/docs/guide/introduction/quickstart.md b/docs/dist/docs/guide/introduction/quickstart.md
@@ -29,13 +29,14 @@ Start by creating an `easyp.yaml` configuration file in your project root:
 easyp init
 ```
 
-This creates a basic configuration file that you'll customize in the following steps.
+This command generates a commented template with default lint and breaking settings.
+`easyp init` is interactive: if `buf.yml`/`buf.yaml` exists in the target root, EasyP asks whether to migrate it; if `easyp.yaml` already exists, it asks before overwriting.
 
 ## Configure linting
 
 Linting helps catch errors and ensures your Protobuf files follow best practices. EasyP provides default rules compatible with Buf standards.
 
-Add lint configuration to your `easyp.yaml`:
+`easyp init` already generates a lint section. Adjust it if needed, for example:
 
 ```yaml
 lint:

diff --git a/docs/dist/docs/ru-guide/cli/breaking-changes/breaking-changes.md b/docs/dist/docs/ru-guide/cli/breaking-changes/breaking-changes.md
@@ -40,8 +40,6 @@ EasyP реализует уровень проверки **WIRE+**:
 Настройка в `easyp.yaml`:
 
 ```yaml
-version: v1alpha
-
 breaking:
   # Git reference для сравнения (branch, tag или commit hash)
   against_git_ref: "main"
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,7 +2,7 @@ @@
     certs
     .env
     bin
-    easyp
+    /easyp
     coverage.out
     easyp.lock
     .DS_Store
@@ Expand Down @@