flecto 2.1.0 → 3.0.0

package/README.md

@@ -5,52 +5,35 @@
 <h1 align="center">Flecto</h1>
 
 <p align="center">
-  <strong>Config changes, in plain English — with risk flags built in.</strong><br/>
-  Watch · Diff · Policy · CI · Webhooks
+  <strong>Know what your config actually changed — and whether it's risky.</strong>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/flecto"><img alt="npm" src="https://img.shields.io/npm/v/flecto?style=flat-square&color=34d399&labelColor=0b1220"/></a>
   <a href="https://github.com/myselfsiddharth/Flecto/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/myselfsiddharth/Flecto/ci.yml?branch=main&style=flat-square&label=CI&labelColor=0b1220"/></a>
   <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-8fa3bf?style=flat-square&labelColor=0b1220"/></a>
-  <a href="https://github.com/myselfsiddharth/Flecto/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/myselfsiddharth/Flecto?style=flat-square&color=fbbf24&labelColor=0b1220"/></a>
+  <a href="#documentation"><img alt="Docs" src="https://img.shields.io/badge/docs-read-34d399?style=flat-square&labelColor=0b1220"/></a>
 </p>
 
 <p align="center">
-  <a href="https://github.com/myselfsiddharth/Flecto/stargazers">⭐ Star this repo</a> if Flecto saves you from a noisy config diff — it helps others find the project.
-</p>
-
-<p align="center">
-  <img src="docs/assets/flecto-demo.png" alt="Flecto watch demo in the terminal" width="920"/>
-</p>
-
-<p align="center">
-  <img src="docs/assets/demo-watch.svg" alt="Animated Flecto watch output" width="920"/>
+  <img src="docs/assets/demo-watch.svg" alt="Flecto reporting semantic config changes in the terminal" width="920"/>
 </p>
 
 ---
 
-## Why teams use Flecto
+Config drives the parts of a system that break loudest: connection pools, feature
+flags, TLS, retries, secrets. But we still review it as text — so a reordered key
+looks identical to a doubled pool size, and `debug: true` slips through in a
+40-line formatting diff.
 
-Line diffs lie about config. Formatting churn, key reorders, and “small” YAML edits hide the changes that actually matter in production.
+Flecto reads config as structure, not lines. It tells you what changed in plain
+English, flags what looks risky, and gives you an exit code to gate on.
 
-**Flecto** turns structured config into semantic events:
-
-- What changed (`pool_size: 5 → 20`)
-- What was added or removed
-- What looks risky (secrets, dangerous toggles, pool jumps)
-- What to do next (CI gate, webhook, shell command)
-
-See the [changelog and migration notes](CHANGELOG.md) for release history and
-upcoming v2.1 behavior changes.
-
-> Diff tools compare trees. **Flecto watches, scores risk, and alerts.**
-
-| Without Flecto | With Flecto |
+| Reviewing config without Flecto | With Flecto |
 |---|---|
-| `+  40 lines of YAML noise` | `~ database.pool_size: 5 → 20` |
-| Hope someone notices `debug: true` | Policy finding → CI fails |
-| “Something in `.env` changed” | Exact keys + optional secret masking |
+| `+ 40 lines of YAML noise` | `~ database.pool_size: 5 → 20` |
+| Hope someone notices `debug: true` | Policy finding → build fails |
+| "Something in `.env` changed" | The exact keys, with secrets masked |
 
 ---
 
@@ -60,358 +43,372 @@ upcoming v2.1 behavior changes.
 npm install -g flecto
 ```
 
-Requires Node.js 20.19.0 or later.
+Requires **Node.js 20.19.0+**. Verify:
 
 ```bash
 flecto --version
 flecto doctor
 ```
 
----
-
-## Quick start
-
-```bash
-flecto watch config/prod.yaml
-flecto watch .env
-flecto watch settings.json
-flecto watch pyproject.toml
-flecto watch app.ini
-```
-
-That’s it — Flecto prints a clear summary on every meaningful change.
+Prefer not to install globally? Every example below works with
+`npx --yes flecto@3` instead of `flecto`.
 
 ---
 
-## Features at a glance
-
-- **Semantic diffs** for JSON, YAML, TOML, INI, and dotenv (`.env`, `.env.*`, `*.env`)
-- **Live watch** with optional command + webhook delivery
-- **Policy packs** (`default`, `strict-prod`, `compose`, `node-runtime`) + custom `policies/*.json` + local ESM plugins
-- **CI mode** with JSON / NDJSON / GitHub annotations and fail rules
-- **Snapshots & diffs** for deploy scripts and pre-commit hooks
-- **Profiles** via `--profile` or `FLECTO_PROFILE`
-- **Default array identity** (`id` / `name`, or `--array-id-key`) and secret masking
-
----
+## Quick start
 
-## Common use cases
+A complete walkthrough, start to finish. Copy-paste it anywhere.
 
-### Watch multiple files
+**1. Create a config file to track.**
 
 ```bash
-flecto watch "config/**/*.yaml" ".env"
+mkdir flecto-demo && cd flecto-demo && mkdir config
+cat > config/prod.yaml <<'EOF'
+database:
+  host: db.internal
+  pool_size: 5
+  ssl: true
+logging:
+  level: info
+  debug: false
+EOF
 ```
 
-### Verbose before/after
+**2. Save it as your baseline.**
 
 ```bash
-flecto watch config/prod.yaml --mode verbose
+flecto watch config/prod.yaml --snapshot
+```
+
+```
+✓ Snapshot saved: /path/to/flecto-demo/.flecto-snapshots/4b8cbbd70d1832a2.json
 ```
 
-### Ignore noisy keys
+**3. Make the kind of edit that causes incidents.**
 
 ```bash
-flecto watch config/prod.yaml --ignore "updated_at,meta.timestamp"
+cat > config/prod.yaml <<'EOF'
+database:
+  host: db.internal
+  pool_size: 20
+  ssl: true
+logging:
+  level: info
+  debug: true
+EOF
 ```
 
-| Pattern | What it ignores |
-|---|---|
-| `meta.timestamp` | That exact key |
-| `meta` | Everything under `meta.*` |
-| `servers[*].meta.timestamp` | That key inside any array item |
-| `**.updated_at` | Any key named `updated_at`, anywhere |
-
-### Run a command on change
+**4. Ask what changed.**
 
 ```bash
-flecto watch .env --command "docker-compose restart app"
+flecto watch config/prod.yaml --diff
 ```
 
-Changes are passed as JSON via `FLECTO_CHANGES` (large payloads may use `FLECTO_CHANGES_FILE`).
+```
+/path/to/flecto-demo/config/prod.yaml — 2 changes from snapshot:
+  ~ database.pool_size: 5 → 20
+  ~ logging.debug: false → true
+```
 
-### Webhooks
+Two sentences instead of a diff you have to interpret. Now let Flecto judge it:
 
 ```bash
-flecto watch config/prod.yaml \
-  --webhook https://hooks.example.com/notify \
-  --webhook-header "Authorization: Bearer TOKEN"
+flecto ci config/prod.yaml --format github-annotations
 ```
 
-Envelope shape (`schema_version: "2.0"`):
-
-```json
-{
-  "schema_version": "2.0",
-  "event_id": "uuid",
-  "event_type": "changes",
-  "emitted_at": "2026-04-14T10:42:31.000Z",
-  "file": "/absolute/path/to/config/prod.yaml",
-  "changes": [
-    { "type": "changed", "path": "database.pool_size", "before": 5, "after": 20 }
-  ],
-  "policies": [
-    {
-      "id": "pool-size-jump",
-      "severity": "warn",
-      "path": "database.pool_size",
-      "message": "Pool size increased from 5 to 20 (>=2x).",
-      "pack": "default"
-    }
-  ]
-}
+```
+::warning title=flecto changed::database.pool_size
+::warning title=flecto changed::logging.debug
+::warning title=flecto policy pool-size-jump [default]::database.pool_size: Pool size increased from 5 to 20 (>=2x).
+::error title=flecto policy dangerous-toggle-enabled [default]::logging.debug: Potentially dangerous toggle enabled.
 ```
 
-JSON Schema: [`schemas/flecto-envelope-2.0.json`](schemas/flecto-envelope-2.0.json).
+Exit code `1`. In CI, that's a failed build — before the change ships.
 
-### Policy packs and profiles
+**5. Watch it live.** Leave this running and edit the file in another window:
 
 ```bash
-flecto ci config/prod.yaml --profile prod --snapshot-ref HEAD~1
+flecto watch config/prod.yaml
 ```
 
-```json
-{
-  "defaults": {
-    "policies": ["default"],
-    "maskSecrets": false
-  },
-  "profiles": {
-    "prod": {
-      "policies": ["default", "strict-prod"],
-      "severityRemap": { "pool-size-jump": "error" },
-      "maskSecrets": true
-    }
-  }
-}
+```
+flecto watching /path/to/flecto-demo/config/prod.yaml
+Press Ctrl+C to stop.
+
+[18:24:48] /path/to/flecto-demo/config/prod.yaml — 2 changes
+  ~ database.pool_size: 5 → 20
+  ~ logging.debug: false → true
+  ! policy(warn) [default] database.pool_size: Pool size increased from 5 to 20 (>=2x).
+  ! policy(error) [default] logging.debug: Potentially dangerous toggle enabled.
 ```
 
-Profile selection: `--profile` > `FLECTO_PROFILE` > defaults.  
-Custom packs: `policies/<id>.json`. Plugins: local ESM exporting `evaluate(changes, ctx)`.
+That's the whole product. Everything below is depth.
 
-#### Declarative rule predicates
+---
 
-Rules combine their top-level predicates with AND. In addition to `when`, regex
-`match.path`, `afterEquals`, and `numericJump`, packs can use:
+## What you can do with it
 
-- `beforeEquals`, `afterIn`, and `beforeIn` for exact values or allowed value lists.
-- `beforeTruthy: true` and `afterTruthy: true` to require a truthy before/after value.
-- `afterMatches` to require a string after value that matches a regular expression.
-- `numericDelta: { "min": 10 }` to match an absolute numeric change of at least 10.
-- `match.pathEquals` and `match.pathPrefix` for exact or prefix path matching without regex.
-- `allOf` and `anyOf` arrays of simple match clauses. Every `allOf` clause and at least
-  one `anyOf` clause must match. Clauses support the same value, truthiness, numeric, and
-  `match` predicates, but cannot nest composition.
+### Catch risky changes before they merge
 
-```json
-{
-  "id": "risky-feature-enable",
-  "severity": "error",
-  "allOf": [
-    { "match": { "pathPrefix": "features." } },
-    { "afterTruthy": true }
-  ],
-  "anyOf": [
-    { "afterEquals": true },
-    { "afterIn": ["unsafe", "disabled"] }
-  ]
-}
+Add one step to your workflow and risky config edits show up as annotations on
+the pull request:
+
+```yaml
+permissions:
+  contents: read
+
+steps:
+  - uses: actions/checkout@v7
+    with:
+      fetch-depth: 2
+  - uses: myselfsiddharth/Flecto/.github/actions/flecto-ci@main
+    with:
+      targets: config/**/*.{yaml,yml,json,toml,ini}
+      snapshot-ref: HEAD~1
 ```
 
-Pack loading fails closed for unknown rule or `match` fields, invalid regexes, and invalid
-predicate shapes, so misspelled predicates cannot silently disable a rule.
+Prefer a summary nobody can miss? `--format pr-comment` renders the changes and
+policy findings as markdown and, when you opt in with `--pr-comment-post` inside
+a GitHub PR run, keeps **one** sticky comment up to date instead of adding a new
+one per push. Without that flag it just prints the markdown, so it can't post
+from your laptop.
 
-Use `severityRemap` in defaults or a profile to change pack rule severities without forking a pack:
+The `flecto-pr-risk` Action is that, packaged — the whole adoption is one
+`uses:`, with the baseline resolved from the pull request rather than `HEAD~1`:
 
-```json
-{
-  "profiles": {
-    "dev": {
-      "severityRemap": { "pool-size-jump": "off" }
-    },
-    "prod": {
-      "severityRemap": { "pool-size-jump": "error" }
-    }
-  }
-}
+```yaml
+permissions:
+  contents: read
+  pull-requests: write
+
+steps:
+  - uses: actions/checkout@v7
+    with:
+      fetch-depth: 0
+  - uses: myselfsiddharth/Flecto/.github/actions/flecto-pr-risk@main
 ```
 
-Each key is a rule id and each value must be `info`, `warn`, `error`, or `off`. The remap applies after all configured built-in and local packs load, before findings and CI `--fail-on` checks. When multiple packs provide the same rule id, the remap applies to every matching pack rule. Plugin findings are unchanged. Unknown rule ids print a warning instead of being ignored silently.
+A fork's pull request gets a read-only token, so the comment is skipped with a
+warning there — the check itself still runs and still fails on risky changes.
+
+Works on any CI runner — it's a plain CLI with meaningful exit codes.
+→ **[CI guide](docs/ci.md)**
 
-Authoring guides: [policy packs](docs/policy-packs.md) · [plugins](docs/plugins.md) · [plugin cookbook](docs/plugin-cookbook.md).
+### Trigger automation on change
 
-### Discover policy packs
+Restart a service, reload a process, or notify an endpoint whenever config moves:
 
 ```bash
-flecto policies list
-flecto policies list --json
+flecto watch .env --command "docker-compose restart app"
+
+flecto watch config/prod.yaml \
+  --webhook https://hooks.example.com/notify \
+  --delivery-mode at-least-once
 ```
 
-The command lists every bundled and local pack that resolves from the current
-working directory, including its source path and rule count. For a given pack
-id, Flecto resolves local files before bundled packs in this order:
-`policies/<id>.json`, `policies/<id>.yaml`, `policies/<id>.yml`, then the
-built-in pack. A local pack with the same id overrides its built-in counterpart.
+Changes arrive as a versioned JSON envelope, and `at-least-once` persists and
+retries failed deliveries.
 
-### Array identity matching
+Posting straight to chat needs no receiver of your own — `--webhook-format`
+shapes the body for Slack, Discord, or Teams, colored by the highest policy
+severity:
 
 ```bash
-flecto watch config/services.yaml
+flecto watch config/prod.yaml \
+  --webhook "https://hooks.slack.com/services/T000/B000/XXXX" \
+  --webhook-format slack
 ```
 
-Arrays of objects automatically match by a shared, unique `id` key, falling back
-to `name` when `id` is unavailable. This avoids false changes when named items
-are reordered. Use a custom identity field when needed:
+→ **[Webhooks and commands](docs/webhooks.md)**
 
-```bash
-flecto watch config/services.yaml --array-id-key serviceKey
-```
+### Compare two environments
 
-To restore index-based diffs for every array, pass `--no-array-id`:
+"Works in staging, fails in prod" is usually one key apart:
 
 ```bash
-flecto watch config/services.yaml --no-array-id
+flecto compare config/prod.yaml config/staging.yaml
+```
+
+```
+"+" exists only in the compared file, "-" only in the baseline, "~" differs
+/path/to/config/staging.yaml — 2 changes from /path/to/config/prod.yaml:
+  - only_in_prod: true
+  ~ database.pool_size: 5 → 20
+  ! policy(warn) [default] database.pool_size: Pool size increased from 5 to 20 (>=2x).
 ```
 
-In `.flectorc`, set `"arrayId": false` in `defaults` or a profile for the same
-escape hatch.
+The first file is the baseline, the files don't have to share a format, and
+`--format json` gives you the same output `flecto ci` produces.
+→ **[CLI reference](docs/cli-reference.md#flecto-compare-filea-fileb)**
 
-### Command + webhook together
+### Track drift over time
 
 ```bash
-flecto watch .env \
-  --command "make reload" \
-  --webhook https://hooks.example.com/notify
+flecto history config/prod.yaml --limit 10
 ```
 
-### Retry on failure
+Snapshots stay on your machine in `.flecto-snapshots/`. Nothing is uploaded and
+no account is required. → **[CLI reference](docs/cli-reference.md#flecto-history-files)**
+
+### Share what changed before the incident
 
 ```bash
-flecto watch config/prod.yaml \
-  --webhook https://hooks.example.com/notify \
-  --delivery-mode at-least-once \
-  --on-alert-failure retry
+flecto report --limit 20 --mask-secrets --output drift.html
 ```
 
-| Flag | Options | What it does |
-|---|---|---|
-| `--delivery-mode` | `best-effort` (default), `at-least-once` | Persist and retry failed webhook events |
-| `--on-alert-failure` | `warn`, `exit`, `retry` | Behavior when command/webhook fails |
+One HTML file from that same local history: a timeline per file, every change
+with its UTC timestamp, and policy findings grouped by severity. Fully
+self-contained — inline styles, no fonts, no CDN scripts, no analytics — so you
+can attach it to an incident thread and it renders offline. No server and no
+account, same as everything else here.
+→ **[CLI reference](docs/cli-reference.md#flecto-report-files)**
 
----
+### Review a Kubernetes change before it reaches a cluster
 
-## Snapshots & diffs
+ArgoCD, Flux, and `helm diff` compare the cluster to the repo — which needs a
+cluster, and an apply that already happened. Flecto compares the manifests *this
+pull request would produce* against the ones `main` produces:
 
 ```bash
-flecto watch config/prod.yaml --snapshot
-flecto watch config/prod.yaml --diff
-flecto history config/prod.yaml --limit 10
+helm template api ./charts/api -f values/prod.yaml > /tmp/head.yaml
+flecto compare /tmp/base.yaml /tmp/head.yaml --policies kubernetes --fail-on error
 ```
 
-Exit codes: `0` clean · `1` changes detected.
+```
+~ Service/prod/api.spec.type: "ClusterIP" → "LoadBalancer"
+  ! policy(error) [kubernetes] Service type is LoadBalancer, which exposes the
+    workload outside the cluster. Confirm the exposure is intended.
+```
 
-`flecto history` stays local: it lists recent snapshots from `.flecto-snapshots/` with their timestamps and semantic change counts from the previous snapshot. Counts use the same ignore paths, array identity, and order settings as `flecto watch --diff` (CLI flags or `.flectorc`). Omit files to view all saved snapshot history.
+Multi-document YAML is keyed by `kind/namespace/name`, so findings name the
+resource. Flecto never runs `helm` or `kustomize` — you render, it diffs, so any
+renderer works and no binary is needed in CI.
+→ **[Kubernetes](docs/kubernetes.md)**
 
----
+### Encode your own rules
 
-## CI mode
+Beyond the built-in packs, write rules as declarative JSON or YAML — no code:
 
-```bash
-flecto ci "config/**/*.yaml" \
-  --snapshot-ref HEAD~1 \
-  --format github-annotations \
-  --fail-on "changed,policy,error"
+```json
+{
+  "id": "risky-feature-enable",
+  "severity": "error",
+  "allOf": [
+    { "match": { "pathPrefix": "features." } },
+    { "afterTruthy": true }
+  ]
+}
 ```
 
-**Formats:** `json`, `ndjson`, `github-annotations`  
-**Fail triggers:** `changed`, `added`, `removed`, `policy`, `error`, `warn`  
-Unresolved `--snapshot-ref` fails closed (no silent empty baseline).  
-If every target is missing or unsupported, `flecto ci` and `flecto watch --snapshot` exit non-zero (pass `--allow-empty` to opt out).
+For anything a predicate can't express, a local ESM plugin exporting
+`evaluate(changes, ctx)` gets the full change set.
+→ **[Writing policy packs](docs/policy-packs.md)** · **[Plugins](docs/plugins.md)**
 
-### GitHub Action
+### Cut the noise
 
-Use the [Flecto CI Action](.github/actions/flecto-ci/action.yml) to run `flecto ci` in a workflow with GitHub annotations enabled by default. A complete local-action workflow is available at [`examples/github-action/flecto-ci.yml`](examples/github-action/flecto-ci.yml).
+```bash
+flecto watch config/prod.yaml --ignore "updated_at,**.meta.timestamp"
+```
 
-```yaml
-permissions:
-  contents: read
+Arrays of objects are matched by `id` or `name`, so reordering a list of named
+services doesn't read as a wall of changes.
+→ **[Configuration](docs/configuration.md)**
 
-steps:
-  - uses: actions/checkout@v7
-    with:
-      fetch-depth: 2
-  - uses: myselfsiddharth/Flecto/.github/actions/flecto-ci@main
-    with:
-      targets: config/**/*.{yaml,yml,json,toml,ini}
-      snapshot-ref: HEAD~1
-```
+---
 
-`contents: read` is required by `actions/checkout`. The Action emits workflow-command annotations and needs no write permissions. Keep `fetch-depth: 2` (or use `fetch-depth: 0`) when using the default `HEAD~1` baseline.
+## Built-in policy packs
 
-| Input | Default | Description |
-|---|---|---|
-| `targets` | `config/**/*.{yaml,yml,json,toml,ini}` | Whitespace-separated paths or glob patterns to check |
-| `fail-on` | `policy,error` | Comma-separated events that fail the job |
-| `policies` | _(empty)_ | Comma-separated policy pack IDs; omit to use `.flectorc` / Flecto defaults |
-| `profile` | _(empty)_ | Optional `.flectorc` profile |
-| `format` | `github-annotations` | Flecto output format |
-| `snapshot-ref` | `HEAD~1` | Git ref or snapshot file used as the baseline |
-| `node-version` | `20` | Node.js version used to run Flecto |
+| Pack | Catches |
+|---|---|
+| `default` | Secret-like keys added or changed, secret-shaped *values* under any key, dangerous toggles, pool-size jumps |
+| `strict-prod` | The same ground, with production-grade severities and matching |
+| `compose` | Privileged services, host networking, Docker socket mounts, sensitive bind mounts |
+| `kubernetes` | Privileged containers, host namespaces, weakened `runAsNonRoot`, added `SYS_ADMIN`, unpinned images, replica jumps, dropped limits, `LoadBalancer`/`NodePort` exposure |
+| `node-runtime` | Dropped engine requirements, TLS verification bypasses, debug/inspector flags |
+| `terraform` | Replaced and destroyed stateful resources, ingress opened to `0.0.0.0/0`, IAM wildcards, public S3, capacity jumps |
+| `sops` | Decryption recipients added or removed, a MAC that moved on its own, a file that stopped being encrypted |
 
-The Action runs `npx --yes flecto@2 ci`: the major version is pinned so compatible Flecto updates are received. For fully reproducible builds, pin the Action reference to a commit SHA and replace `@2` in a forked Action with an exact published Flecto version.
+```bash
+flecto policies list          # see what resolves here, built-in and local
+flecto ci "config/**/*.yaml" --policies "default,strict-prod" --fail-on policy
+```
 
----
+Pass files or glob patterns, quoted so your shell doesn't expand them first — a
+bare directory is not a valid target.
 
-## Built-in policy checks
+A local `policies/<id>.json` overrides the built-in pack of the same id, and
+`severityRemap` raises or silences individual rules per profile without forking
+anything. → **[Policy packs](docs/policy-packs.md)**
 
-Built-in pack ids:
+Community packs ship on npm as `flecto-pack-<id>` packages — a package name and
+one declarative JSON file, nothing else:
 
-- `default` — secrets, dangerous toggles, and pool-size jumps.
-- `strict-prod` — stricter severities and matching for production use.
-- `compose` — privileged services, host networking, Docker socket mounts, and sensitive host-directory bind mounts.
-- `node-runtime` — removed Node.js engine requirements, TLS verification bypasses, and enabled Node debugging or inspector options.
+```bash
+npm install --save-dev flecto-pack-deployment-safety
+flecto policies add deployment-safety
+```
 
-Fail CI with `--fail-on policy`.
+`policies add` validates the pack, writes it to `policies/deployment-safety.json`,
+and runs no code from the package. →
+**[Installing community packs](docs/policy-packs.md#installing-a-community-pack)**
 
 ---
 
-## Migrating from envelope 1.1
+## Supported formats
 
-- `schema_version` is now `"2.0"`
-- Type name is `FlectoEnvelope` (docs/types)
-- New `policies` array on change envelopes
-- Webhook headers unchanged (`X-Flecto-*`)
+| Format | Extensions |
+|---|---|
+| JSON | `.json` |
+| YAML | `.yaml`, `.yml` |
+| TOML | `.toml` |
+| INI | `.ini` |
+| dotenv | `.env`, `.env.*`, `*.env` |
+| age (armored) | `.age`, or any file whose contents are one armored blob |
+
+Multi-document YAML (`---`-separated, the usual shape of a Kubernetes manifest)
+is supported. Each document is diffed under its own key — `kind/name` for
+Kubernetes-shaped documents, so a document inserted at the top of the file does
+not renumber every other path. →
+**[Multi-document YAML](docs/configuration.md#multi-document-yaml)**
 
 ---
 
-## Tuning for network drives / odd editors
+## Encrypted files
+
+A `sops`- or age-encrypted file is detected from its **contents**, and diffed
+structurally:
 
-```bash
-flecto watch config/prod.yaml --polling --interval 500
 ```
+  + cache: {"ttl_seconds":300}
+  ~ database.password: <encrypted value changed>
+  + sops.age.age1exampleexample…: {"recipient":"age1exampleexample…","enc":"<encrypted value>"}
+```
+
+You get keys added and removed, which encrypted values moved, and — the useful
+part — who can decrypt the file. A recipient added is a genuine security event
+and the `sops` pack raises it as one.
 
-Polling is off by default (interval default `100ms` when enabled).
+**Flecto never decrypts.** It never shells out to `sops` or `age`, never reads a
+key file or agent socket, and never prints ciphertext — not even without
+`--mask-secrets`. Ciphertext is replaced with an opaque sentinel in the parser,
+so no diff, snapshot, webhook, or report can carry it. →
+**[Encrypted files](docs/encrypted-files.md)**
 
 ---
 
-## Config file (`.flectorc`)
+## Configuration
+
+Most teams commit a `.flectorc` so local runs and CI agree:
 
 ```bash
 flecto init
 ```
 
-Looks for `.flectorc`, `.flectorc.json`, `.flectorc.yaml`, or `.flectorc.yml`.
-
 ```json
 {
   "defaults": {
-    "mode": "compact",
-    "interval": 100,
-    "ignore": ["**.updated_at"],
-    "deliveryMode": "best-effort",
-    "onAlertFailure": "warn",
     "policies": ["default"],
-    "arrayId": true
+    "ignore": ["**.updated_at"]
   },
   "profiles": {
     "dev": { "mode": "verbose" },
@@ -422,81 +419,80 @@ Looks for `.flectorc`, `.flectorc.json`, `.flectorc.yaml`, or `.flectorc.yml`.
       "maskSecrets": true
     }
   },
-  "files": ["config/**/*.{yaml,yml,json,toml,ini}", ".env", ".env.*", "*.env"],
-  "exclude": ["**/node_modules/**"]
+  "files": ["config/**/*.{yaml,yml,json,toml,ini}", ".env"]
 }
 ```
 
 ```bash
 flecto watch --profile dev
 flecto ci --profile ci
-flecto doctor
 ```
 
-CLI flags override profile/default values.
+Explicit CLI flags win over profiles, which win over `defaults`.
+→ **[Full configuration reference](docs/configuration.md)**
 
 ---
 
-## Output format reference
-
-### Compact (default)
-
-```
-[HH:MM:SS] <filepath> — N changes
-  ~ path: before → after     (yellow — value changed)
-  + path: value              (green  — key added)
-  - path: value              (red    — key removed)
-```
-
-### Verbose (`--mode verbose`)
+## Commands
 
-```
-[HH:MM:SS] <filepath> — N changes
-  ~ path
-    before: old_value
-    after:  new_value
-```
+| Command | What it does |
+|---|---|
+| `flecto watch [files...]` | Watch for changes and print them as they happen |
+| `flecto watch --snapshot` | Save the current state as a baseline |
+| `flecto watch --diff` | Compare against the baseline and exit |
+| `flecto ci [files...]` | One-shot check with a gate-able exit code |
+| `flecto compare <fileA> <fileB>` | Diff two files against each other (`fileA` is the baseline) |
+| `flecto plan <planFiles...>` | Review `terraform show -json` output and gate on it |
+| `flecto history [files...]` | Summarize drift across local snapshots |
+| `flecto report [files...]` | Render that history as a self-contained HTML file |
+| `flecto policies add <name>` | Install a pack from an `flecto-pack-*` npm package |
+| `flecto policies list` | List available policy packs |
+| `flecto policies test <dir>` | Assert pack and plugin findings from fixtures |
+| `flecto init` | Create a `.flectorc` from detected stack signals |
+| `flecto doctor` | Check setup, config, and environment |
+
+→ **[Every flag, every command](docs/cli-reference.md)**
 
 ---
 
-## Error handling
+## Documentation
 
-| Situation | Behavior |
+| Guide | Covers |
 |---|---|
-| File not found | Error + exit 1 |
-| Unsupported format | Lists supported extensions + exit 1 |
-| Parse error while watching | Warning, last valid state kept |
-| Command / webhook fails | Warning (unless `--on-alert-failure exit`) |
-| Ctrl+C | Clean shutdown |
+| **[CLI reference](docs/cli-reference.md)** | Every command, flag, and exit code |
+| **[Configuration](docs/configuration.md)** | `.flectorc`, profiles, ignore patterns, array identity, masking |
+| **[Encrypted files](docs/encrypted-files.md)** | SOPS and age: what is detected, what is reported, why nothing is decrypted |
+| **[CI](docs/ci.md)** | Baselines, fail triggers, output formats, the bundled GitHub Actions |
+| **[Kubernetes](docs/kubernetes.md)** | Diffing rendered Helm/Kustomize manifests before they reach a cluster |
+| **[Terraform plans](docs/terraform.md)** | Reviewing `terraform show -json` output and the `terraform` pack |
+| **[Webhooks and commands](docs/webhooks.md)** | Envelope shape, delivery modes, command environment |
+| **[Policy packs](docs/policy-packs.md)** | Writing declarative rules |
+| **[Plugins](docs/plugins.md)** · **[Cookbook](docs/plugin-cookbook.md)** | Rules that need real code |
+| **[Troubleshooting](docs/troubleshooting.md)** | When something doesn't behave |
+| **[Changelog](CHANGELOG.md)** | Release history and migration notes |
 
 ---
 
 ## How it works
 
-1. **Parser** — format by extension / dotenv naming → structured values  
-2. **Watcher** — [chokidar](https://github.com/paulmillr/chokidar) + debounce  
-3. **Differ** — semantic tree diff (objects, arrays, ignore rules, automatic array ids)
-4. **Policy engine** — packs + plugins → severity findings  
-5. **Envelope** — versioned automation payload (`2.0`)  
-6. **Alerter** — command and/or webhook with retry modes  
-
----
-
-## Contributing
-
-Flecto is open source. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, PR rules, and review expectations.  
-Please read the [Code of Conduct](CODE_OF_CONDUCT.md) and [Security policy](SECURITY.md).
+1. **Parse** — format detected by extension or dotenv naming → structured values
+2. **Watch** — [chokidar](https://github.com/paulmillr/chokidar) with debounce
+3. **Diff** — semantic tree comparison with ignore rules and array identity
+4. **Evaluate** — policy packs and plugins → severity-tagged findings
+5. **Emit** — a versioned envelope (`schema_version: "2.0"`)
+6. **Deliver** — terminal output, shell command, webhook, or CI annotations
 
-Roadmap lives in [GitHub milestones](https://github.com/myselfsiddharth/Flecto/milestones).
+Flecto runs entirely on your machine. Snapshots are local files, and nothing
+leaves the process unless you configure a webhook or command.
 
 ---
 
-## Star the project
-
-If Flecto helps your team catch a risky config change — **[star the repo](https://github.com/myselfsiddharth/Flecto)** so more people can find it.
-
----
+## Project
 
-## License
+- **Questions and ideas** — [Discussions](https://github.com/myselfsiddharth/Flecto/discussions)
+- **Bugs and requests** — [Issues](https://github.com/myselfsiddharth/Flecto/issues)
+- **Contributing** — [CONTRIBUTING.md](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
+- **Security** — [SECURITY.md](SECURITY.md), private disclosure only
+- **Roadmap** — [Milestones](https://github.com/myselfsiddharth/Flecto/milestones)
 
-MIT — see [LICENSE](./LICENSE).
+Released under the [MIT License](LICENSE).