flecto 2.0.0 → 3.0.0

package/README.md

@@ -1,21 +1,39 @@
-# Flecto
+<p align="center">
+  <img src="docs/assets/flecto-hero.png" alt="Flecto — semantic config watcher" width="920"/>
+</p>
 
-**Flecto watches your config files and tells you exactly what changed — in plain English.**
+<h1 align="center">Flecto</h1>
 
-No more staring at raw line diffs. When your `.env`, `YAML`, `JSON`, `TOML`, or `INI` file changes, Flecto shows you what actually happened:
+<p align="center">
+  <strong>Know what your config actually changed — and whether it's risky.</strong>
+</p>
 
-```
-[10:42:31] config/prod.yaml — 3 changes
-  ~ database.pool_size: 5 → 20
-  + feature_flags.dark_mode: true
-  - deprecated.old_key
-```
+<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="#documentation"><img alt="Docs" src="https://img.shields.io/badge/docs-read-34d399?style=flat-square&labelColor=0b1220"/></a>
+</p>
+
+<p align="center">
+  <img src="docs/assets/demo-watch.svg" alt="Flecto reporting semantic config changes in the terminal" width="920"/>
+</p>
 
 ---
 
-## Why 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.
 
-Standard file watchers tell you *a file changed*. Flecto tells you *what* changed and *why it might matter* — flagging secrets, dangerous toggles, and risky config jumps automatically.
+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.
+
+| Reviewing config without Flecto | With Flecto |
+|---|---|
+| `+ 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 |
 
 ---
 
@@ -25,340 +43,456 @@ Standard file watchers tell you *a file changed*. Flecto tells you *what* change
 npm install -g flecto
 ```
 
-After that, `flecto` is available globally from anywhere.
+Requires **Node.js 20.19.0+**. Verify:
+
+```bash
+flecto --version
+flecto doctor
+```
+
+Prefer not to install globally? Every example below works with
+`npx --yes flecto@3` instead of `flecto`.
 
 ---
 
-## Quick Start
+## Quick start
+
+A complete walkthrough, start to finish. Copy-paste it anywhere.
 
-Watch any config file:
+**1. Create a config file to track.**
 
 ```bash
-flecto watch config/prod.yaml
-flecto watch .env
-flecto watch settings.json
-flecto watch pyproject.toml
+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
 ```
 
-That's it. Flecto starts watching and prints a clear summary every time something changes.
+**2. Save it as your baseline.**
 
----
+```bash
+flecto watch config/prod.yaml --snapshot
+```
 
-## Common Use Cases
+```
+✓ Snapshot saved: /path/to/flecto-demo/.flecto-snapshots/4b8cbbd70d1832a2.json
+```
 
-### Watch multiple files at once
+**3. Make the kind of edit that causes incidents.**
 
 ```bash
-flecto watch "config/**/*.yaml" ".env"
+cat > config/prod.yaml <<'EOF'
+database:
+  host: db.internal
+  pool_size: 20
+  ssl: true
+logging:
+  level: info
+  debug: true
+EOF
 ```
 
-### See detailed before/after values
+**4. Ask what changed.**
 
 ```bash
-flecto watch config/prod.yaml --mode verbose
+flecto watch config/prod.yaml --diff
+```
+
+```
+/path/to/flecto-demo/config/prod.yaml — 2 changes from snapshot:
+  ~ database.pool_size: 5 → 20
+  ~ logging.debug: false → true
 ```
 
-### Ignore noisy keys (like timestamps)
+Two sentences instead of a diff you have to interpret. Now let Flecto judge it:
 
 ```bash
-flecto watch config/prod.yaml --ignore "updated_at,meta.timestamp"
+flecto ci config/prod.yaml --format github-annotations
 ```
 
-You can ignore exact keys, entire subtrees, wildcards, or keys anywhere in the file:
+```
+::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.
+```
 
-| 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 |
+Exit code `1`. In CI, that's a failed build — before the change ships.
 
-### Run a command when something changes
+**5. Watch it live.** Leave this running and edit the file in another window:
 
 ```bash
-flecto watch .env --command "docker-compose restart app"
+flecto watch config/prod.yaml
 ```
 
-Flecto passes the changes as JSON to your command via the `FLECTO_CHANGES` environment variable.
+```
+flecto watching /path/to/flecto-demo/config/prod.yaml
+Press Ctrl+C to stop.
 
-### Send changes to a webhook
+[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.
+```
 
-```bash
-flecto watch config/prod.yaml --webhook https://hooks.example.com/notify
+That's the whole product. Everything below is depth.
+
+---
+
+## What you can do with it
+
+### Catch risky changes before they merge
+
+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
 ```
 
-Add auth headers if needed:
+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.
+
+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`:
+
+```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
+```
+
+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)**
+
+### Trigger automation on change
+
+Restart a service, reload a process, or notify an endpoint whenever config moves:
 
 ```bash
+flecto watch .env --command "docker-compose restart app"
+
 flecto watch config/prod.yaml \
   --webhook https://hooks.example.com/notify \
-  --webhook-header "Authorization: Bearer TOKEN"
+  --delivery-mode at-least-once
 ```
 
-Each webhook payload includes a full event envelope:
+Changes arrive as a versioned JSON envelope, and `at-least-once` persists and
+retries failed deliveries.
 
-```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"
-    }
-  ]
-}
+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/prod.yaml \
+  --webhook "https://hooks.slack.com/services/T000/B000/XXXX" \
+  --webhook-format slack
 ```
 
-Envelope JSON Schema: [`schemas/flecto-envelope-2.0.json`](schemas/flecto-envelope-2.0.json).
+→ **[Webhooks and commands](docs/webhooks.md)**
+
+### Compare two environments
 
-### Policy packs and profiles
+"Works in staging, fails in prod" is usually one key apart:
 
 ```bash
-flecto ci config/prod.yaml --profile prod --snapshot-ref HEAD~1
+flecto compare config/prod.yaml config/staging.yaml
 ```
 
-`.flectorc.json` example:
-
-```json
-{
-  "defaults": {
-    "policies": ["default"],
-    "maskSecrets": false
-  },
-  "profiles": {
-    "prod": {
-      "policies": ["default", "strict-prod"],
-      "maskSecrets": true
-    }
-  }
-}
+```
+"+" 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).
 ```
 
-Profile selection: `--profile` > `FLECTO_PROFILE` > defaults. Custom packs live in `policies/<id>.json`. Local ESM plugins export `evaluate(changes, ctx)`.
+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)**
 
-### Opt-in array identity matching
+### Track drift over time
 
 ```bash
-flecto watch config/services.yaml --array-id-key id
+flecto history config/prod.yaml --limit 10
 ```
 
-Without the flag, arrays still diff by index (1.x behavior).
-
-### Migrating from envelope 1.1
+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)**
 
-- `schema_version` is now `"2.0"`
-- Envelope type name is `FlectoEnvelope` (was `SentinelEnvelope` in docs/types only)
-- New `policies` array on change envelopes
-- Webhook headers are unchanged (`X-Flecto-*`)
-### Use both command and webhook together
+### Share what changed before the incident
 
 ```bash
-flecto watch .env \
-  --command "make reload" \
-  --webhook https://hooks.example.com/notify
+flecto report --limit 20 --mask-secrets --output drift.html
 ```
 
-### Retry on failure
+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
+
+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 \
-  --webhook https://hooks.example.com/notify \
-  --delivery-mode at-least-once \
-  --on-alert-failure retry
+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
 ```
 
-| Flag | Options | What it does |
-|---|---|---|
-| `--delivery-mode` | `best-effort` (default), `at-least-once` | Whether to persist and retry failed webhook events |
-| `--on-alert-failure` | `warn`, `exit`, `retry` | What happens if a command or webhook fails |
+```
+~ 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.
+```
 
----
+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)**
 
-## Snapshots & Diffs
+### Encode your own rules
 
-Save a baseline snapshot of your file:
+Beyond the built-in packs, write rules as declarative JSON or YAML — no code:
 
-```bash
-flecto watch config/prod.yaml --snapshot
-# Saved to .flecto-snapshots/<id>.json
+```json
+{
+  "id": "risky-feature-enable",
+  "severity": "error",
+  "allOf": [
+    { "match": { "pathPrefix": "features." } },
+    { "afterTruthy": true }
+  ]
+}
 ```
 
-Then compare the current file against it anytime:
+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)**
+
+### Cut the noise
 
 ```bash
-flecto watch config/prod.yaml --diff
+flecto watch config/prod.yaml --ignore "updated_at,**.meta.timestamp"
 ```
 
-Exit codes:
-- `0` — no changes (file is clean)
-- `1` — changes detected
-
-This is useful in deployment scripts and pre-commit hooks.
+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)**
 
 ---
 
-## CI Mode
+## Built-in policy packs
 
-Catch risky config changes before they ship:
+| 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 |
 
 ```bash
-flecto ci "config/**/*.yaml" \
-  --snapshot-ref HEAD~1 \
-  --format github-annotations \
-  --fail-on "changed,policy,error"
+flecto policies list          # see what resolves here, built-in and local
+flecto ci "config/**/*.yaml" --policies "default,strict-prod" --fail-on policy
 ```
 
-**Output formats:** `json`, `ndjson`, `github-annotations`
+Pass files or glob patterns, quoted so your shell doesn't expand them first — a
+bare directory is not a valid target.
 
-**Fail triggers:** `changed`, `added`, `removed`, `policy`, `error`, `warn`
+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)**
 
----
+Community packs ship on npm as `flecto-pack-<id>` packages — a package name and
+one declarative JSON file, nothing else:
 
-## Built-in Policy Checks
+```bash
+npm install --save-dev flecto-pack-deployment-safety
+flecto policies add deployment-safety
+```
 
-Flecto automatically flags changes that look risky:
+`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)**
 
-- 🔑 **Secrets touched** — keys named `secret`, `token`, `password`, `api_key`, etc.
-- ⚠️ **Dangerous toggles** — `debug: true`, `disable_tls`, `skip_tls_verify`, `allow_insecure`
-- 📈 **Large pool size jumps** — `pool_size` doubled or more
+---
+
+## Supported formats
 
-Policy violations can fail your CI pipeline with `--fail-on policy`.
+| 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 or Odd Editors
+## Encrypted files
 
-Some editors write files via a temp file swap, which can confuse standard watchers. Enable polling mode:
+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>"}
 ```
 
-Default polling interval is `100ms`. Polling is off by default.
+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.
 
----
+**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)
+---
 
-Set your defaults once so you don't have to repeat flags every time.
+## Configuration
 
-Generate a starter config:
+Most teams commit a `.flectorc` so local runs and CI agree:
 
 ```bash
 flecto init
 ```
 
-Flecto looks for `.flectorc`, `.flectorc.json`, `.flectorc.yaml`, or `.flectorc.yml`.
-
-Example:
-
 ```json
 {
   "defaults": {
-    "mode": "compact",
-    "interval": 100,
-    "ignore": ["**.updated_at"],
-    "deliveryMode": "best-effort",
-    "onAlertFailure": "warn"
+    "policies": ["default"],
+    "ignore": ["**.updated_at"]
   },
   "profiles": {
     "dev": { "mode": "verbose" },
-    "ci": { "failOn": "policy,error" }
+    "ci": { "failOn": "policy,error" },
+    "prod": {
+      "policies": ["default", "strict-prod"],
+      "severityRemap": { "pool-size-jump": "error" },
+      "maskSecrets": true
+    }
   },
-  "files": ["config/**/*.yaml", ".env"],
-  "exclude": ["**/node_modules/**"]
+  "files": ["config/**/*.{yaml,yml,json,toml,ini}", ".env"]
 }
 ```
 
-Use a named profile:
-
 ```bash
 flecto watch --profile dev
 flecto ci --profile ci
 ```
 
-CLI flags always override profile/default values.
-
-Verify your setup:
-
-```bash
-flecto doctor
-```
+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
-  + path: value
-    (key added)
-```
+| 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
-
-Flecto is designed to keep running even when things go wrong:
+## Documentation
 
-| Situation | Behavior |
+| Guide | Covers |
 |---|---|
-| File not found | Error message + exit 1 |
-| Unsupported file format | Lists supported extensions + exit 1 |
-| File has a parse error | Warning shown, last valid state kept, watching continues |
-| Command fails | Warning shown, watcher continues |
-| Webhook fails | Warning shown, watcher continues |
-| Ctrl+C | Clean shutdown message |
+| **[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 |
 
 ---
 
-## Running Tests
+## How it works
 
-```bash
-npm test
-# or directly:
-node --test test/*.test.js
-```
+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
 
-Tests cover the differ, watcher behavior, webhook delivery, policy logic, and CI command behavior.
+Flecto runs entirely on your machine. Snapshots are local files, and nothing
+leaves the process unless you configure a webhook or command.
 
 ---
 
-## How It Works
-
-1. **Parser** — detects the file format by extension and parses it into structured JS values.
-2. **Watcher** — uses [chokidar](https://github.com/paulmillr/chokidar) with debouncing so rapid saves don't flood you with events.
-3. **Differ** — computes a semantic diff (not a line diff), supporting objects, arrays, scalars, and ignore rules.
-4. **Policy engine** — inspects the changes for patterns that look risky and adds severity findings.
-5. **Envelope** — wraps each batch of changes in a versioned event schema ready for automation.
-6. **Alerter** — delivers events via command execution and/or webhook, with configurable retry logic.
-
----
+## 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).