chore: improve README and CONTRIBUTING files

Author: tatomyr

CONTRIBUTING.md

@@ -1,6 +1,7 @@
 # Redocly CLI Contributing Guide
 
-Hi! We're really excited that you are interested in contributing to Redocly CLI. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.
+Hi! We're really excited that you are interested in contributing to Redocly CLI.
+Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.
 
 - [Issue reporting guidelines](#issue-reporting-guidelines)
 - [Pull request guidelines](#pull-request-guidelines)
@@ -48,7 +49,8 @@ npm install # or npm i
 
 To compile the code, run `npm run compile`. To do that on the fly, run `npm run watch` in a separate thread.
 
-To run a specific CLI command, use `npm run cli`, e.g. `npm run cli -- lint resources/museum.yaml --format=stylish`. Please notice that the extra `--` is required to pass arguments to the CLI rather than to NPM itself.
+To run a specific CLI command, use `npm run cli`, e.g. `npm run cli -- lint resources/museum.yaml --format=stylish`.
+Please notice that the extra `--` is required to pass arguments to the CLI rather than to NPM itself.
 
 Format your code with `npm run prettier` before committing.
 
@@ -70,13 +72,15 @@ To test local changes as a package, you can use the following steps:
 
 1. Optionally, bump the version of the packages ([see details](#version-updating)).
 
-1. Run `npm run pack:prepare` in the repository's root. This generates **redocly-cli.tgz**, **respect-core.tgz**, and **openapi-core.tgz** files.
+1. Run `npm run pack:prepare` in the repository's root.
+   This generates **redocly-cli.tgz**, **respect-core.tgz**, and **openapi-core.tgz** files.
 
 1. Copy those **.tgz** files to a destination folder and then run `npm install redocly-cli.tgz` there to install Redocly CLI. To install `openapi-core` do the same but with **openapi-core.tgz** file.
 
 ## Contribute documentation
 
-Additions and updates to our documentation are very welcome. You can find the documentation in the `docs/` folder, and this is published to https://redocly.com/docs/cli/ as part of our main website.
+Additions and updates to our documentation are very welcome.
+You can find the documentation in the `docs/` folder, and this is published to https://redocly.com/docs/cli/ as part of our main website.
 
 To preview your documentation changes locally:
 
@@ -90,11 +94,14 @@ redocly preview
 
 By default, you can access the docs preview at http://localhost:4000 or http://127.0.0.1:4000.
 
-> Please note that currently the custom markdoc tags used in the main website are not available in the local preview version, and links that point to the wider website do show as errors when using a local platform. The pull request workflows generate a full preview, so rest assured that you are able to check everything is in good shape before we review and merge your changes.
+> Please note that currently the custom markdoc tags used in the main website are not available in the local preview version, and links that point to the wider website do show as errors when using a local platform.
+> The pull request workflows generate a full preview, so rest assured that you are able to check everything is in good shape before we review and merge your changes.
 
 ### Prose linting
 
-We are proud of our docs. When you open a pull request, we lint the prose using [Vale](https://vale.sh/). You can also install this tool locally and run it from the root of the project with:
+We are proud of our docs.
+When you open a pull request, we lint the prose using [Vale](https://vale.sh/).
+You can also install this tool locally and run it from the root of the project with:
 
 ```bash
 vale docs/
@@ -110,7 +117,9 @@ We use [Markdownlint](https://github.com/DavidAnson/markdownlint) to check that
 
 ### Markdown link checking
 
-We use [`mlc`](https://github.com/becheran/mlc) to check the links in the `docs/` folder. This tool runs automatically on every pull request, but you can also run it locally if you want to. Visit the project homepage to find the installation instructions for your platform, and then run the command like this:
+We use [`mlc`](https://github.com/becheran/mlc) to check the links in the `docs/` folder.
+This tool runs automatically on every pull request, but you can also run it locally if you want to.
+Visit the project homepage to find the installation instructions for your platform, and then run the command like this:
 
 ```bash
 mlc docs/
@@ -120,7 +129,8 @@ It only checks links within the local docs (it can't check links to other docs s
 
 ## Built-in rules changes
 
-After adding a new rule, make sure it is added to the `minimal`, `recommended`, `recommended-strict` (the same as the previous but with warnings turned into error) and `all` rulesets with appropriate severity levels. The defaults are `off` for `minimal` and `recommended` and `error` for `all`.
+After adding a new rule, make sure it is added to the `minimal`, `recommended`, `recommended-strict` (the same as the previous but with warnings turned into error) and `all` rulesets with appropriate severity levels.
+The defaults are `off` for `minimal` and `recommended` and `error` for `all`.
 Also add the rule to the built-in rules list in [the config types tree](./packages/core/src/types/redocly-yaml.ts).
 
 Separately, open a merge request with the corresponding documentation changes.
@@ -137,11 +147,16 @@ Environment variables should not affect the **core** package logic.
 
 ### Command line arguments
 
-Use them to provide some arguments that are specific to a certain command. Think of them as modifiers. They should not affect the **core** package logic.
+Use them to provide some arguments that are specific to a certain command.
+Think of them as modifiers.
+They should not affect the **core** package logic.
 
 ### Configuration file
 
-The **redocly.yaml** file is the most flexible way of providing arguments. Please use it to provide arguments that are common for all the commands, for a specific command, or for a specific API. It could be used for providing arguments for both **cli** and **core** packages. Please refer to the [configuration file](https://redocly.com/docs/cli/configuration/) documentation for more details.
+The **redocly.yaml** file is the most flexible way of providing arguments.
+Please use it to provide arguments that are common for all the commands, for a specific command, or for a specific API.
+It could be used for providing arguments for both **cli** and **core** packages.
+Please refer to the [configuration file](https://redocly.com/docs/cli/configuration/) documentation for more details.
 
 ## Exit codes
 
@@ -215,14 +230,17 @@ If you made any changes, make sure to compile the code before running the tests.
       - **`packages/core/src/types`**: contains the common types for several OpenAPI versions.
       - **`packages/core/src/typings`**: contains the common Typescript typings.
 
+  - **`packages/respect-core`**: contains the Respect core package.
+
 - **`resources`**: contains some example API descriptions and configuration files that might be useful for testing.
 
 ## Release flow
 
 We use [Changesets](https://github.com/changesets/changesets) flow.
 After merging a PR with a changeset, the release PR is automatically created.
 
-If the pipelines are not starting, close and reopen the PR. Merging that PR triggers the release process.
+If the pipelines are not starting, close and reopen the PR.
+Merging that PR triggers the release process.
 
 ### Revert a release
 

README.md

@@ -1,6 +1,9 @@
 # Redocly CLI
 
-[@Redocly](https://redocly.com) CLI is your all-in-one OpenAPI utility. It builds, manages, improves, and quality-checks your OpenAPI descriptions, all of which comes in handy for various phases of the API Lifecycle. Create your own rulesets to make API governance easy, and publish beautiful API reference documentation. Supports OpenAPI 3.1, 3.0 and OpenAPI 2.0 (legacy Swagger).
+[@Redocly](https://redocly.com) CLI is your all-in-one OpenAPI utility.
+It builds, manages, improves, and quality-checks your OpenAPI descriptions, all of which comes in handy for various phases of the API Lifecycle.
+Create your own rulesets to make API governance easy, publish beautiful API reference documentation, and more.
+Supports OpenAPI 3.1, 3.0 and OpenAPI 2.0 (legacy Swagger), AsyncAPI 3.0 and 2.6, Arazzo 1.0.
 
 ![build and test](https://github.com/redocly/redocly-cli/actions/workflows/tests.yaml/badge.svg)
 ![npm (scoped)](https://img.shields.io/npm/v/@redocly/cli)
@@ -32,9 +35,8 @@ The minimum required versions of Node.js and NPM are 18.17.0 and 10.8.2 respecti
 
 ### Docker
 
-To give the Docker container access to the OpenAPI description files, you need to
-mount the containing directory as a volume. Assuming the API description is rooted
-in the current working directory, you need the following command:
+To give the Docker container access to the OpenAPI description files, you need to mount the containing directory as a volume.
+Assuming the API description is rooted in the current working directory, you need the following command:
 
 ```sh
 docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml
@@ -51,55 +53,72 @@ docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml
 
 ### Generate API reference documentation
 
-Redocly CLI is a great way to render API reference documentation. It uses open source [Redoc](https://github.com/redocly/redoc) to build your documentation. Use a command like this:
+Redocly CLI is a great way to render API reference documentation.
+It uses open source [Redoc](https://github.com/redocly/redoc) to build your documentation.
+Use a command like this:
 
 ```sh
 redocly build-docs openapi.yaml
 ```
 
-Your API reference docs are in `redoc-static.html` by default. You can customize this in many ways. [Read the main docs](https://redocly.com/docs/cli/commands/build-docs) for more information.
+Your API reference docs are in `redoc-static.html` by default.
+You can customize this in many ways.
+[Read the main docs](https://redocly.com/docs/cli/commands/build-docs) for more information.
 
-> :bulb: Redocly also has [hosted API reference docs](https://redocly.com/docs/api-registry/guides/api-registry-quickstart/), a (commercial) alternative to Redoc. Both Redoc and Redocly API reference docs can be worked on locally using the `preview-docs` command.
+> :bulb: Redocly also has [hosted API reference docs](https://redocly.com/docs/api-registry/guides/api-registry-quickstart/), a (commercial) alternative to Redoc.
+> Both Redoc and Redocly API reference docs can be worked on locally using the `preview-docs` command.
 
 ### Bundle multiple OpenAPI documents
 
-Having one massive OpenAPI description can be annoying, so most people split them up into multiple documents via `$ref`, only to later find out some tools don't support `$ref` or don't support multiple documents. Redocly CLI to the rescue! It has a `bundle` command you can use to recombine all of those documents back into one single document. The bundled output that Redocly CLI provides is clean, tidy, and looks like a human made it.
+Having one massive OpenAPI description can be annoying, so most people split them up into multiple documents via `$ref`, only to later find out some tools don't support `$ref` or don't support multiple documents.
+Redocly CLI to the rescue! It has a `bundle` command you can use to recombine all of those documents back into one single document.
+The bundled output that Redocly CLI provides is clean, tidy, and looks like a human made it.
 
 ### Automate API guidelines with Linting
 
-Check that your API matches the expected API guidelines by using the `lint` command. API guidelines are an important piece of API governance. They help to keep APIs consistent by enforcing the same standards and naming conventions, and they can also guide API teams through potential security hazards and other pitfalls. Automating API guidelines means you can keep APIs consistent and secure throughout their lifecycle. Even better, you can shape the design of the API before it even exists by combining API linting with a design-first API workflow.
+Check that your API matches the expected API guidelines by using the `lint` command.
+API guidelines are an important piece of API governance. They help to keep APIs consistent by enforcing the same standards and naming conventions, and they can also guide API teams through potential security hazards and other pitfalls.
+Automating API guidelines means you can keep APIs consistent and secure throughout their lifecycle.
+Even better, you can shape the design of the API before it even exists by combining API linting with a design-first API workflow.
 
-Our API linter is designed for speed on even large documents, and it's easy to run locally, in CI, or anywhere you need it. It's also designed for humans, with meaningful error messages to help you get your API right every time.
+Our API linter is designed for speed on even large documents, and it's easy to run locally, in CI, or anywhere you need it.
+It's also designed for humans, with meaningful error messages to help you get your API right every time.
 
 Try it like this:
 
 ```sh
 redocly lint openapi.yaml
 ```
 
-**Configure the rules** as you wish. Other API Linters use complicated identifiers like JSONPath, but Redocly makes life easy with simple expressions that understand the OpenAPI structure. You can either use the [built-in rules](https://redocly.com/docs/cli/rules) to mix-and-match your ideal API guidelines, or break out the tools to build your own.
+**Configure the rules** as you wish.
+Other API Linters use complicated identifiers like JSONPath, but Redocly makes life easy with simple expressions that understand the OpenAPI structure.
+You can either use the [built-in rules](https://redocly.com/docs/cli/rules) to mix-and-match your ideal API guidelines, or break out the tools to build your own.
 
-**Format the output** in whatever way you need. The `stylish` output is as good as it sounds, but if you need JSON or Checkstyle outputs to integrate with other tools, the `lint` command can output those too.
+**Format the output** in whatever way you need.
+The `stylish` output is as good as it sounds, but if you need JSON or Checkstyle outputs to integrate with other tools, the `lint` command can output those too.
 
 **Multiple files supported** so you don't need to bundle your API description to lint it; just point Redocly CLI at the "entry point" (e.g.: `openapi.yaml`) and it handles the rest.
 
 [Learn more about API standards and configuring Redocly rules](https://redocly.com/docs/cli/api-standards).
 
 ### Transform an OpenAPI description
 
-If your OpenAPI description isn't everything you hoped it would be, enhance it with the Redocly [decorators](https://redocly.com/docs/cli/decorators) feature. This allows you to:
+If your OpenAPI description isn't everything you hoped it would be, enhance it with the Redocly [decorators](https://redocly.com/docs/cli/decorators) feature.
+This allows you to:
 
 - Publish reference docs with a subset of endpoints for public use
 - Improve the docs by adding examples and descriptions
 - Adapt an existing OpenAPI description, and replace details like URLs for use on staging platforms
 
 ## Data collection
 
-This tool [collects data](./docs/usage-data.md) to help Redocly improve our products and services. You can opt out by setting the `REDOCLY_TELEMETRY` environment variable to `off`.
+This tool [collects data](./docs/usage-data.md) to help Redocly improve our products and services.
+You can opt out by setting the `REDOCLY_TELEMETRY` environment variable to `off`.
 
 ## Update notifications
 
-Redocly CLI checks for updates on startup. You can disable this by setting the `REDOCLY_SUPPRESS_UPDATE_NOTICE` environment variable to `true`.
+Redocly CLI checks for updates on startup.
+You can disable this by setting the `REDOCLY_SUPPRESS_UPDATE_NOTICE` environment variable to `true`.
 
 ## More resources
 
@@ -111,4 +130,5 @@ Thanks to [graphql-js](https://github.com/graphql/graphql-js) and [eslint](https
 
 ## Development
 
-Contributions are welcome! All the information you need is in [CONTRIBUTING.md](CONTRIBUTING.md).
+Contributions are welcome!
+All the information you need is in [CONTRIBUTING.md](CONTRIBUTING.md).