docs: simplify README for users

Rewrite the README to be shorter and benefit-oriented: a one-line pitch, a
3-command quick start, a compact command table, and a small config example.
Drops the verbose per-command walkthrough and edge-case prose (still covered by
--help and .dev-env.example.yml).

Author: nazarli-shabnam

README.md

@@ -1,195 +1,71 @@
 # envkit
 
-**envkit** is a CLI that manages local development environments from a single config file. Define dependencies, databases, and services in one place; run one command to set up the project, generate Docker Compose, and optionally snapshot or share configs—without committing secrets.
+Set up your whole local dev environment with one command. Define your dependencies, databases, and services in a single file — then let envkit install everything, spin up Docker, and keep your setup shareable and versioned. Secrets stay in `.env`, never in your config.
 
-**Requirements:** Node.js >= 16
-
----
-
-## What it does
-
-- **Setup** — Uses your `.dev-env.yml` to install dependencies and run database migrations and seed commands in one go.
-- **Generate** — Builds a `docker-compose.yml` from the same config (databases, services, network).
-- **Snapshots** — Saves and restores config versions under `.devkit/snapshots/` so you can switch between setups.
-- **Share** — Exports a sanitized config (secrets replaced with placeholders) or imports a shared config file into your project.
-
-Configuration is a single YAML file; secrets live in `.env` and are referenced as `${VAR_NAME}`. The CLI discovers the project root from your current directory (it looks for `.dev-env.yml` or markers like `package.json`).
-
----
+> Requires Node.js 16+
 
 ## Install
 
 ```bash
 npm install -g dev-env-kit
 ```
 
-After installation you can use either:
-
-- **`envkit <command>`** — short name
-- **`dev-env-kit <command>`** — same, using the package name
-
-After install, **path-setup** runs automatically: if you're in an interactive terminal, you may be prompted to add envkit to your PATH so `envkit` works from any folder. You can run it again anytime with `npx dev-env-kit path-setup` or `npx dev-env-kit pathsetup` (no hyphen; use `pathsetup` if your shell doesn't like `path-setup`).
-
-If the command is still not found, use:
-
-```bash
-npx dev-env-kit <command>
-```
-
----
-
-## How to use
-
-### 1. Add a config file
-
-You need a `.dev-env.yml` in your project root for **setup**, **generate**, **share export**, and **snapshot create**. If you don’t have one yet:
-
-- **Interactive terminal:** Run `envkit init` to create `.dev-env.yml` via a short wizard. If you run a command that needs config (e.g. `envkit setup`) without a config file, the CLI will ask whether to run `envkit init` now.
-- **Non-interactive (CI, scripts):** Create `.dev-env.yml` by hand or run `envkit init` in a terminal first; otherwise those commands exit with a message to create a config or run `envkit init`.
-
-**If you already have an example file**, the fastest way to start is to copy it and edit it:
-
-```bash
-cp .dev-env.example.yml .dev-env.yml
-```
-
-The example file documents all options (dependencies, databases, services, env vars, Docker settings). Keep sensitive values in a `.env` file and reference them in the config with `${VAR_NAME}` so they never end up in version control.
-
-See [.dev-env.example.yml](./.dev-env.example.yml) for the full reference.
-
-### 2. Set up the environment
-
-From the project root (or any subdirectory):
-
-```bash
-envkit setup
-```
-
-This installs dependencies, runs database migrations, and runs seed commands according to your config. You can narrow what runs:
-
-| Option        | Description                          |
-|---------------|--------------------------------------|
-| `--skip-deps` | Skip dependency installation         |
-| `--skip-db`   | Skip database migrations and seed    |
-| `--dry-run`   | Show what would run, without running |
-
-### 3. Validate your config
-
-Check that `.dev-env.yml` (and any `.env`) is well-formed without running setup or generate — handy for CI and pre-commit hooks:
-
-```bash
-envkit validate
-```
-
-It exits non-zero on a missing or invalid config. Add `--strict` to also fail on warnings (e.g. hardcoded passwords, port conflicts) and unresolved `${VAR}` references:
-
-```bash
-envkit validate --strict
-```
-
-### 4. Generate Docker Compose
-
-When `docker.enabled` is set in your config, you can generate a Compose file from it:
-
-```bash
-envkit generate
-```
-
-Output goes to `docker-compose.yml` by default. Use `-o <file>` to write elsewhere, e.g. `envkit generate -o docker-compose.dev.yml`. To preview the generated Compose without writing a file (e.g. to pipe or inspect it), use `--dry-run`:
-
-```bash
-envkit generate --dry-run
-```
-
-### 5. Snapshots
-
-Save the current config as a named snapshot under `.devkit/snapshots/`:
-
-```bash
-envkit snapshot create [name]
-```
-
-If you omit the name, a timestamp-based name is used. List existing snapshots:
-
-```bash
-envkit snapshot list
-```
+This gives you the `envkit` command (also available as `dev-env-kit`). If your shell can't find it afterward, run `envkit path-setup` once.
 
-Restore a snapshot. This overwrites `.dev-env.yml`, but your current config is automatically backed up to a `pre-restore-<timestamp>` snapshot first, and you'll be asked to confirm in an interactive terminal (use `--yes` to skip the prompt in scripts):
+## Quick start
 
 ```bash
-envkit snapshot restore <name>
+envkit init      # answer a few questions to create .dev-env.yml
+envkit setup     # install dependencies + run migrations/seeds
+envkit generate  # create docker-compose.yml from your config
 ```
 
-Delete a snapshot you no longer need:
+That's the whole loop. Run any command from your project root or any subfolder — envkit finds the project automatically.
 
-```bash
-envkit snapshot delete <name>
-```
+## Commands
 
-### 6. Share config (export / import)
+| Command | What it does |
+|---------|--------------|
+| `envkit init` | Create your `.dev-env.yml` with a short interactive wizard. |
+| `envkit setup` | Install dependencies and run database migrations + seeds. Skip parts with `--skip-deps`, `--skip-db`, or preview with `--dry-run`. |
+| `envkit validate` | Check your config is valid — great for CI. Use `--strict` to also fail on warnings. |
+| `envkit generate` | Build a `docker-compose.yml` from your config. `--dry-run` prints it instead of writing. |
+| `envkit snapshot create/list/restore/delete` | Save and switch between config versions. Restoring backs up your current config first. |
+| `envkit share export` / `import` | Share your setup with teammates — secrets are swapped for placeholders on export. |
 
-Export a safe-to-share copy of your config (passwords and secrets become placeholders like `${DB_PASSWORD}`):
+Add `-v` for more detail or `-q` for less. Run `envkit <command> --help` anytime.
 
-```bash
-envkit share export
-```
+## Configuration
 
-By default this writes `dev-env.shared.yml`. Use `-o <file>` to change the path.
+Everything lives in one `.dev-env.yml` at your project root. Keep secrets in a `.env` file and reference them with `${VAR_NAME}`:
 
-Import a shared config file (it is validated and then written to `.dev-env.yml` by default). The `<file>` path is resolved relative to your **current working directory**:
+```yaml
+name: my-app
 
-```bash
-envkit share import path/to/dev-env.shared.yml
-```
+dependencies:
+  - type: npm
+    command: npm install
 
-Use `-o <file>` to write to a different path (also relative to the current directory unless you pass an absolute path). To check a shared file is valid without writing anything (useful in CI), pass `--validate-only`:
+databases:
+  - type: postgresql
+    port: 5432
+    user: ${DB_USER}
+    password: ${DB_PASSWORD}
+    database: myapp
 
-```bash
-envkit share import path/to/dev-env.shared.yml --validate-only
+docker:
+  enabled: true
 ```
 
-### Global options
+See [.dev-env.example.yml](./.dev-env.example.yml) for every available option. Don't have a config yet? Just run `envkit init` — or if you run `envkit setup` without one, it'll offer to create it for you.
 
-- **`-v, --verbose`** — More detailed log output.
-- **`-q, --quiet`** — Reduce output.
-
-Example: `envkit -q setup`
-
----
-
-## Command reference
-
-| Command | Description |
-|--------|-------------|
-| `envkit init` | Create `.dev-env.yml` interactively (wizard). Run from a project folder when you don’t have a config yet. |
-| `envkit setup` | Install dependencies, run database migrations, and run seed commands from your config. Use `--skip-deps`, `--skip-db`, or `--dry-run` to limit what runs. |
-| `envkit validate` | Validate `.dev-env.yml` (and `.env`) without running setup or generate. Add `--strict` to fail on warnings and unresolved `${VAR}` references. CI/pre-commit friendly. |
-| `envkit generate` | Generate `docker-compose.yml` from your config (requires `docker.enabled` in config). Use `-o <file>` to set the output path, or `--dry-run` to print without writing. |
-| `envkit snapshot create [name]` | Save the current `.dev-env.yml` as a snapshot under `.devkit/snapshots/`. Omit `name` to use a timestamp. |
-| `envkit snapshot list` | List all saved snapshots. |
-| `envkit snapshot restore <name>` | Restore a snapshot; overwrites `.dev-env.yml` (current config is backed up first). Use `--yes` to skip the confirmation prompt. |
-| `envkit snapshot delete <name>` | Delete a saved snapshot. |
-| `envkit share export` | Export a sanitized config (secrets → placeholders) to share safely. Default output: `dev-env.shared.yml`; use `-o <file>` to override. |
-| `envkit share import <file>` | Import a shared config file; writes to `.dev-env.yml` by default. Use `-o <file>` to write elsewhere, or `--validate-only` to validate without writing. |
-| `envkit path-setup` or `envkit pathsetup` | Add the npm global bin folder to your PATH so `envkit` works from any directory. Use if the shell says “envkit” is not recognized after a global install. |
-
-For more detail: `envkit --help` or `envkit <command> --help`.
----
-
-## Development and testing
-
-To work on the source or run tests:
+## Contributing
 
 ```bash
 npm install
 npm test
 ```
 
-Use `npm test -- --coverage` for a coverage report.
-
----
-
 ## License
 
 MIT