docs: add quickstart and troubleshooting docs

README.md

@@ -15,7 +15,58 @@ Anything already set in the process wins. Missing keys are filled by the first p
 
 ---
 
-## How to Use This
+## CLI Usage
+
+Local dev:
+1. Put a `.env` file beside your app.
+2. Optionally set `VAULT_ADDR` and authenticate to backfill missing secrets from Vault:
+   ```shell
+   VAULT_ADDR=https://vault.byu.edu vault login -method=oidc -path=byu-sso
+   ```
+
+1. Install the CLI:
+   ```bash
+   go install github.com/stuft2/envault/cmd/envchain@latest
+   ```
+1. Create a sample `.env`:
+   ```bash
+   cat > .env <<'EOF'
+   APP_NAME=envault-demo
+   PORT=8080
+   EOF
+   ```
+1. Run a command with backfilled env vars:
+   ```bash
+   envchain -- env | grep -E '^(APP_NAME|PORT)='
+   ```
+1. Verify output:
+   ```text
+   APP_NAME=envault-demo
+   PORT=8080
+   ```
+
+Optional Vault check:
+```bash
+envchain -vault-path "kvv2/<service>/dev/env-vars" -- env | grep '^YOUR_KEY='
+```
+
+CLI usage:
+
+```bash
+envchain [flags] -- <command> [args...]
+```
+
+Flags:
+
+- `-dotenv` (default `.env`): path to a dotenv file to backfill from. Pass an empty string to skip it.
+- `-vault-path`: KV v2 path to load from HashiCorp Vault. Leave empty to skip Vault.
+- `-verbose`: emit debug logs detailing how each provider resolves environment variables.
+
+Environment variables such as `VAULT_ADDR`, `VAULT_TOKEN`, and `VAULT_NAMESPACE` still control Vault behaviour.
+
+CI/Prod: rely on process env only. If you don’t set `VAULT_ADDR`, the Vault provider is inert, and a missing `.env` is ignored.
+
+## Programmatic Usage
 
 ### Injecting Environment Variables
 
@@ -74,7 +125,7 @@ if err := envault.InjectWithContext(ctx, dotenv.NewProvider(".env"), vault.NewPr
 }
 ```
 
-### Reading Environment Variables with Defaults
+## Reading Environment Variables with Defaults
 
 Instead of manually checking for missing values, use `GetEnvOrDefault`:
 
@@ -115,60 +166,59 @@ func main() {
 }
 ```
 
----
-
-## Recommended usage
- - Local dev:
-   1. Put a `.env` beside your app
-   2. Set `VAULT_ADDR` and authenticate (`vault login`) to populate missing secrets.
-     ```shell
-     VAULT_ADDR=https://vault.byu.edu vault login -method=oidc -path=byu-sso
-     ```
- - CI/Prod: rely on process env only. If you don’t set `VAULT_ADDR`, the Vault provider effectively becomes inert, and a missing `.env` is ignored.
+## External Dependencies
 
-### CLI helper
+* [joho/godotenv](https://github.com/joho/godotenv) — parse `.env` files.
 
-Instead of wiring `envault.Inject` into your code, you can wrap any command with the CLI:
+## CI / Local Checks
 
-```bash
-go run ./cmd/envchain -- <command> [args...]
-```
+CI runs on push and pull request via `.github/workflows/ci.yml`.
 
-Install it once and reuse it anywhere:
+Run the same checks locally:
 
 ```bash
-# recommended
-go install ./cmd/envchain
-# or without cloning the repo
-go install github.com/stuft2/envault/cmd/envchain@latest
+task fmt
+task lint
+task test
 ```
 
-Flags:
-
-- `-dotenv` (default `.env`): path to a dotenv file to backfill from. Pass an empty string to skip it.
-- `-vault-path`: KV v2 path to load from HashiCorp Vault. Leave empty to skip Vault.
-- `-verbose`: emit debug logs detailing how each provider resolves environment variables.
+---
 
-Environment variables such as `VAULT_ADDR`, `VAULT_TOKEN`, and `VAULT_NAMESPACE` still control Vault behaviour.
+## Troubleshooting
 
----
+Symptom: `vault: VAULT_ADDR is required to inject environment variables`  
+Cause: `-vault-path` is set, but `VAULT_ADDR` is missing.  
+Fix: export `VAULT_ADDR` (for example, `https://vault.byu.edu`) or remove `-vault-path`.
 
-## External Dependencies
+Symptom: `vault: VAULT_ADDR set but no token found (VAULT_TOKEN or ~/.vault-token)`  
+Cause: Vault address is configured, but auth token is unavailable.  
+Fix: set `VAULT_TOKEN` or run `vault login` so `~/.vault-token` exists.
 
-* [joho/godotenv](https://github.com/joho/godotenv) — parse `.env` files.
+Symptom: `vault: invalid VAULT_ADDR "...": ...`  
+Cause: `VAULT_ADDR` is malformed (missing scheme, invalid host, or invalid URL).  
+Fix: use a valid URL such as `https://vault.byu.edu` (or `https://vault.byu.edu/v1`).
 
-## CI / Local Checks
+Symptom: `Usage: envault [flags] -- command [args...]`  
+Cause: command was not passed after `--`.  
+Fix: provide a command after separator, for example `envchain -- env`.
 
-CI runs on push and pull request via `.github/workflows/ci.yml`.
+Symptom: `envault: failed to execute "..."`  
+Cause: the command after `--` is missing from `PATH` or not executable.  
+Fix: verify the executable name and run `which <command>` to confirm availability.
 
-Run the same checks locally:
+Symptom: expected value from `.env`/Vault is not applied  
+Cause: existing process env takes precedence over providers.  
+Fix: unset the key before running, for example:
 
 ```bash
-task fmt
-task lint
-task test
+export PORT=3000
+envchain -- env | grep '^PORT='    # PORT=3000 (existing env wins)
+unset PORT
+envchain -- env | grep '^PORT='    # PORT from .env or Vault
 ```
 
+Verbose mode note: `-verbose` logs provider flow and key names, not secret values. Secret-safe diagnostics and redaction guarantees will continue to improve as diagnostics features evolve.
+
 ## Project Docs
 
 - Usability feature docs: [`docs/README.md`](docs/README.md)

Taskfile.yml

@@ -1,5 +1,9 @@
 version: "3"
 
+env:
+  GOCACHE: "{{.TASKFILE_DIR}}/.cache/go-build"
+  GOLANGCI_LINT_CACHE: "{{.TASKFILE_DIR}}/.cache/golangci-lint"
+
 tasks:
   default:
     desc: Show available tasks
@@ -20,7 +24,7 @@ tasks:
   fmt:
     desc: Format Go source files using golangci-lint
     cmds:
-      - golangci-lint run --fix --disable-all --enable gofmt
+      - golangci-lint fmt
 
   build:
     desc: Build the envault CLI

docs/feature-roadmap.md

@@ -12,6 +12,7 @@ This document links to the per-feature specifications.
 1. [Vault Result Caching](./features/vault-result-caching.md)
 1. [Additional Providers](./features/additional-providers.md)
 1. [Key Filtering And Transform Rules](./features/key-filtering-and-transform.md)
+1. [Quickstart And Troubleshooting Docs](./features/quickstart-and-troubleshooting-docs.md)
 1. [CLI Test Coverage](./features/cli-test-coverage.md)
 1. [Continuous Integration](./features/continuous-integration.md)