npm - flecto - Versions diffs - 4.1.0 → 4.1.1 - Mend

flecto 4.1.0 → 4.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,36 @@ The format is based on [Keep a Changelog], and this project adheres to
 ## [Unreleased]
+## [4.1.1] - 2026-09-29
+### Fixed
+- **The root `action.yml` description was too long to list on the Marketplace.**
+  GitHub rejects a listing whose description is 125 characters or more; 4.1.0
+  shipped 194. It is now 119, and a test pins the limit — the constraint is not
+  in GitHub's metadata-syntax documentation and the publish form only reports it
+  at publish time, by which point the release is already cut.
+  The rest of the pitch — that Flecto never runs `terraform`, `helm`, or `sops`,
+  and never decrypts — lives in the README, which has room for it.
+### Fixed
+- **Documented Action pins moved from `@v4.0.0` to `@v4.1.0`.** Tags are
+  immutable, and the fix that stopped the bundled Actions installing the pre-4.0
+  CLI shipped *in* 4.1.0 — so while the examples said `@v4.0.0` they pointed at a
+  tag whose `flecto-ci` and `flecto-pr-risk` still run `flecto@3`, the line
+  exposed to the baseline-shadowing bypass 4.0 closed.
+  **If you pinned `@v4.0.0` following an earlier example, repin to `@v4.1.0`.**
+  The CLI at `flecto@4.0.0` is fine; it is only the bundled Action metadata at
+  that tag that is not. [docs/ci.md](docs/ci.md#pinning) now warns against it.
+  [RELEASE.md](RELEASE.md) gained a step that repins the documented Actions as
+  part of every release. That step is the real fix — the bug was not the pin, it
+  was that nothing tied the documented pin to the release that fixed what it
+  pointed at.
 ## [4.1.0] - 2026-09-29
 ### Added
@@ -1292,7 +1322,8 @@ fixed — those runs were never actually gated — but the failure is new.
 - Misconfigured policy packs/plugins cause `watch` to exit non-zero instead of
   continuing with no policies.
-[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v4.1.0...HEAD
+[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v4.1.1...HEAD
+[4.1.1]: https://github.com/myselfsiddharth/Flecto/compare/v4.1.0...v4.1.1
 [4.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v4.0.0...v4.1.0
 [4.0.0]: https://github.com/myselfsiddharth/Flecto/compare/v3.1.0...v4.0.0
 [3.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.2...v3.1.0

package/README.md CHANGED Viewed

@@ -1,11 +1,8 @@
-<p align="center">
-  <img src="docs/assets/flecto-hero.png" alt="Flecto — semantic config watcher" width="920"/>
-</p>
 <h1 align="center">Flecto</h1>
 <p align="center">
-  <strong>Know what your config actually changed — and whether it's risky.</strong>
+  <strong>Flecto reads your Terraform plan and Kubernetes changes and posts a
+  plain-English risk summary on every pull request, blocking the dangerous ones.</strong>
 </p>
 <p align="center">
@@ -15,178 +12,87 @@
   <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>
----
-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.
-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 |
-The same engine reads whatever your change actually lives in:
-| You are reviewing | Flecto reads |
-|---|---|
-| App config — YAML, JSON, TOML, INI, dotenv | the files directly |
-| A Terraform change | `terraform show -json` output, via `flecto plan` |
-| A Kubernetes change | rendered manifests from `helm`, `kustomize`, or anything else |
-| A SOPS-encrypted file | its structure and recipients — **never its plaintext** |
-It never invokes `terraform`, `helm`, `kustomize`, `sops`, or `age`, so nothing
-extra has to exist on the CI runner.
 ---
-## Install
-```bash
-npm install -g flecto
-```
+## What lands on the pull request
-Requires **Node.js 20.19.0+**. Verify:
-```bash
-flecto --version
-flecto doctor
-```
+<p align="center">
+  <img src="docs/assets/flecto-pr-comment.png" alt="Flecto's comment on a pull request: check failing, six policy errors naming an IAM wildcard, a disabled S3 public-access block, and security group ingress opened to 0.0.0.0/0" width="960"/>
+</p>
-Prefer not to install globally? Every example below works with
-`npx --yes flecto@4` instead of `flecto`.
+That is a real comment on a
+**[real pull request](https://github.com/myselfsiddharth/flecto-example-terraform/pull/1)**
+you can open right now. The PR says it is about partner access and changes eight
+lines; it opens the web tier to the internet, turns off the bucket's
+public-access protection, and widens an IAM policy to `s3:*` on `*`.
----
+One sticky comment, updated in place on every push. Exit code `1`, so the build
+fails before the change ships.
-## Quick start
+**[The same gate on an ordinary change](https://github.com/myselfsiddharth/flecto-example-terraform/pull/2)**
+reports *no findings* and passes. That matters as much: a check that fires on
+everything gets uninstalled in a week.
-A complete walkthrough, start to finish. Copy-paste it anywhere.
+<details>
+<summary>The same report as text, and what a plan with existing state adds</summary>
-**1. Create a config file to track.**
+The comment above, as `flecto plan` prints it:
-```bash
-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
 ```
+❌ Check failing — 30 changes in 1 file — 0 changed, 30 added, 0 removed.
+Policy: 6 errors.
-**2. Save it as your baseline.**
-```bash
-flecto watch config/prod.yaml --snapshot
-```
+aws_security_group.web.ingress[0].cidr_blocks[0]
+  terraform-security-group-open-ingress
+  Security group ingress will accept traffic from the whole internet
+  (0.0.0.0/0). Restrict the source to a known CIDR, a prefix list, or
+  another security group.
-```
-✓ Snapshot saved: /path/to/flecto-demo/.flecto-snapshots/4b8cbbd70d1832a2.json
-```
+aws_s3_bucket_public_access_block.uploads.block_public_acls        (+3 more)
+  terraform-s3-public-access-block-disabled
+  S3 public access block is being turned off or removed.
-**3. Make the kind of edit that causes incidents.**
-```bash
-cat > config/prod.yaml <<'EOF'
-database:
-  host: db.internal
-  pool_size: 20
-  ssl: true
-logging:
-  level: info
-  debug: true
-EOF
+aws_iam_role_policy.app.policy
+  terraform-iam-wildcard
+  IAM policy grants a wildcard action or resource ("*").
 ```
-**4. Ask what changed.**
+The example repository has no Terraform state, so every resource shows as
+`create`. With existing state, a plan that replaces a database also reports:
-```bash
-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
+aws_db_instance.main.#action
+  terraform-stateful-resource-destroyed
+  Terraform will destroy a stateful resource. Its data does not survive.
+  Take a final snapshot, or add a prevent_destroy lifecycle block, before
+  applying.
 ```
-Two sentences instead of a diff you have to interpret. Now let Flecto judge it:
-```bash
-flecto ci config/prod.yaml --format github-annotations
-```
-```
-::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.
-```
-Exit code `1`. In CI, that's a failed build — before the change ships.
-**5. Watch it live.** Leave this running and edit the file in another window:
-```bash
-flecto watch config/prod.yaml
-```
-```
-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.
-```
-That's the whole product. Everything below is depth.
+</details>
 ---
-## What you can do with it
+## Add it in 60 seconds
-### Catch risky changes before they merge
-Add one step to your workflow and risky config edits show up as annotations on
-the pull request:
+**Terraform** — point it at the plan JSON:
 ```yaml
 permissions:
   contents: read
+  pull-requests: write
 steps:
   - uses: actions/checkout@v7
+  - run: |
+      terraform plan -out=tf.plan
+      terraform show -json tf.plan > plan.json
+  - uses: myselfsiddharth/Flecto/.github/actions/flecto-pr-risk@v4.1.0
     with:
-      fetch-depth: 2
-  - uses: myselfsiddharth/Flecto/.github/actions/flecto-ci@v4.0.0
-    with:
-      targets: config/**/*.{yaml,yml,json,toml,ini}
-      snapshot-ref: HEAD~1
+      terraform-plan: plan.json
+      fail-on: error
 ```
-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`:
+**Kubernetes** — render your manifests, then diff them against the PR's base:
 ```yaml
 permissions:
@@ -197,324 +103,64 @@ steps:
   - uses: actions/checkout@v7
     with:
       fetch-depth: 0
-  - uses: myselfsiddharth/Flecto/.github/actions/flecto-pr-risk@v4.0.0
-```
-GitLab and Bitbucket work the same way — Flecto detects the host from CI
-variables, or `--pr-provider` forces one. See [CI](docs/ci.md#providers).
-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 \
-  --delivery-mode at-least-once
-```
-Changes arrive as a versioned JSON envelope, and `at-least-once` persists and
-retries failed deliveries.
-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
-```
-→ **[Webhooks and commands](docs/webhooks.md)**
-### Compare two environments
-"Works in staging, fails in prod" is usually one key apart:
-```bash
-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).
-```
-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)**
-### Track drift over time
-```bash
-flecto history config/prod.yaml --limit 10
-```
-Snapshots stay on your machine in `.flecto-snapshots/`. Nothing is uploaded and
-no account is required. To read the same history on a CI runner, save it to the
-git-tracked store instead — `--snapshot-store shared` writes a committable
-`.flecto/snapshots/`, masking secret-like values into digests as it goes.
-→ **[CLI reference](docs/cli-reference.md#flecto-history-files)**
-### Share what changed before the incident
-```bash
-flecto report --limit 20 --mask-secrets --output drift.html
-```
-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
-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
-```
-```
-~ 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)**
-### Read a Terraform plan in plain English
-`terraform plan` output is precise and long. Flecto turns it into the handful of
-lines a reviewer actually needs to argue about:
-```bash
-terraform show -json plan.tfplan > plan.json
-flecto plan plan.json --fail-on error
-```
-```
-plan.json — plan format 1.2
-Plan: 0 to add, 1 to change, 0 to destroy, 1 to replace.
-  ~ aws_security_group.web.ingress[0].cidr_blocks[0]: "10.0.0.0/8" → "0.0.0.0/0"
-  - aws_db_instance.main.#action: "replace" [terraform will destroy and recreate aws_db_instance.main]
-  ~ aws_db_instance.main.password: "(sensitive value)" → "(sensitive value)" [sensitive]
-  ! policy(error) [terraform] …cidr_blocks[0]: Security group ingress will accept
-    traffic from the whole internet (0.0.0.0/0). Restrict the source to a known CIDR…
-  ! policy(error) [terraform] …#action: Terraform will destroy a stateful resource.
-    Its data does not survive. Take a final snapshot, or add a prevent_destroy…
-```
-A **replace reads as a removal**, not a benign update — a recreated database
-should never look like a config tweak. Values Terraform marks sensitive are
-redacted during parsing, before the policy engine or any formatter sees them, and
-`after_unknown` renders as `(known after apply)` rather than `null`.
-**Flecto never runs `terraform`** — you produce the JSON, it reads it, so nothing
-extra has to exist on the CI runner.
-→ **[Terraform plans](docs/terraform.md)**
-### Encode your own rules
-Beyond the built-in packs, write rules as declarative JSON or YAML — no code:
-```json
-{
-  "id": "risky-feature-enable",
-  "severity": "error",
-  "allOf": [
-    { "match": { "pathPrefix": "features." } },
-    { "afterTruthy": true }
-  ]
-}
-```
-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 --ignore "updated_at,**.meta.timestamp"
+  - run: helm template ./chart > rendered.yaml
+  - uses: myselfsiddharth/Flecto/.github/actions/flecto-pr-risk@v4.1.0
+    with:
+      targets: rendered.yaml
+      policies: kubernetes
 ```
-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)**
+Flecto **never invokes** `terraform`, `helm`, `kustomize`, `sops`, or `age`, so
+nothing extra has to exist on the runner. → **[CI guide](docs/ci.md)**
 ---
-## Built-in policy packs
-| 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 |
-| `github-actions` | Changed workflow triggers, widened permissions, self-hosted runners, unpinned actions, pull-request head checkout, and secrets interpolated into `run` |
-```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.
-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:
-```bash
-npm install --save-dev flecto-pack-deployment-safety
-flecto policies add deployment-safety
-```
-`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)**
+## What it catches
+- **A database about to be destroyed** — `terraform plan` says `replace`, the
+  diff says the data does not survive
+- **Ingress widened to the world** — `10.0.0.0/8` → `0.0.0.0/0` on a security
+  group
+- **An IAM policy gone wildcard** — `Action: "*"` where it used to be scoped
+- **S3 public-access protection switched off** — the block removed, not just
+  loosened
+- **A container turned privileged**, or `runAsNonRoot` quietly weakened
+- **Resource limits removed** from a Deployment, so one pod can starve a node
+- **An image tag unpinned** — `:1.4.0` → `:latest`
+- **A new recipient on a SOPS file** — someone who could not decrypt it now can
+- **`debug: true` in a 40-line formatting diff**, or a connection pool
+  quadrupled
+Rules live in [policy packs](docs/policy-packs.md) you can extend, remap, or
+replace.
 ---
-## Supported formats
+## Also works as
-| Format | Extensions |
+| | |
 |---|---|
-| JSON / JSONC | `.json`, `.jsonc` |
-| YAML | `.yaml`, `.yml` |
-| TOML | `.toml` |
-| INI | `.ini` |
-| dotenv | `.env`, `.env.*`, `*.env` |
-| age (armored) | `.age`, or any file whose contents are one armored blob |
-`.json` accepts comments and trailing commas, so `tsconfig.json`,
-`.vscode/settings.json`, `jsconfig.json`, and `devcontainer.json` are read as
-written. →
-**[JSON with comments](docs/configuration.md#json-with-comments)**
-Terraform plan JSON (`terraform show -json`) is read by **`flecto plan`**, which
-applies Terraform's own sensitivity marking. Point `plan` at it rather than `ci`
-or `watch` — those treat it as ordinary JSON and will print values Terraform
-marks sensitive ([#113](https://github.com/myselfsiddharth/Flecto/issues/113)).
-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)**
----
-## Encrypted files
-A `sops`- or age-encrypted file is detected from its **contents**, and diffed
-structurally:
-```
-  + 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.
-**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)**
+| **A CLI** | `flecto ci`, `flecto plan`, `flecto compare` — plain exit codes, any runner → **[CLI reference](docs/cli-reference.md)** |
+| **A file watcher** | `flecto watch` reports changes as you edit → **[Getting started](docs/getting-started.md)** |
+| **A webhook / command trigger** | Restart a service or notify an endpoint on change → **[Webhooks](docs/webhooks.md)** |
+| **An MCP server** | Read-only `diff`, `check`, `explain` tools for agents → **[MCP](docs/mcp.md)** |
+| **An editor language server** | `flecto lsp` — diagnostics while you type → **[Editor](docs/editor.md)** |
+| **A drift detector** | `flecto-drift` compares declared config against what is running → **[Drift](docs/drift.md)** |
 ---
-## Configuration
-Most teams commit a `.flectorc` so local runs and CI agree:
-```bash
-flecto init
-```
-```json
-{
-  "defaults": {
-    "policies": ["default"],
-    "ignore": ["**.updated_at"]
-  },
-  "profiles": {
-    "dev": { "mode": "verbose" },
-    "ci": { "failOn": "policy,error" },
-    "prod": {
-      "policies": ["default", "strict-prod"],
-      "severityRemap": { "pool-size-jump": "error" },
-      "maskSecrets": true
-    }
-  },
-  "files": ["config/**/*.{yaml,yml,json,toml,ini}", ".env"]
-}
-```
-```bash
-flecto watch --profile dev
-flecto ci --profile ci
-```
+## Stability
-Explicit CLI flags win over profiles, which win over `defaults`.
-→ **[Full configuration reference](docs/configuration.md)**
+Flecto runs inside your merge path. The **JSON envelope**
+(`schema_version: "2.0"`), **exit codes** (`0` clean, `1` failed — it fails
+closed), **`.flectorc`** keys, and **command and flag names** follow
+[semver](https://semver.org/), and no breaking change to them ships without a
+minor release that warns first. The one exception is a security fix.
----
+Terminal output, message wording, and anything under `src/` are deliberately
+**not** stable — parse `--format json`.
-## Commands
-| 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 explain [files...]` | Advisory, model-generated narration of the masked diff (opt-in, your own key) |
-| `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 mcp` | Serve read-only diff/check/explain tools to an agent over MCP |
-| `flecto lsp` | Show findings and changes as diagnostics while a config file is edited |
-| `flecto doctor` | Check setup, config, and environment |
-→ **[Every flag, every command](docs/cli-reference.md)**
+→ **[Full stability policy](docs/stability.md)**
 ---
@@ -522,75 +168,30 @@ Explicit CLI flags win over profiles, which win over `defaults`.
 | Guide | Covers |
 |---|---|
-| **[CLI reference](docs/cli-reference.md)** | Every command, flag, and exit code |
-| **[Configuration](docs/configuration.md)** | `.flectorc`, profiles, ignore patterns, array identity, masking |
-| **[Editor diagnostics](docs/editor.md)** | `flecto lsp` setup for Neovim, Helix, Emacs, and where diagnostics land |
-| **[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 |
-| **[Performance](docs/performance.md)** | Where time goes at scale, and how much smaller a diff is than the config |
-| **[Kubernetes](docs/kubernetes.md)** | Diffing rendered Helm/Kustomize manifests before they reach a cluster |
+| **[Getting started](docs/getting-started.md)** | A full walkthrough, from install to a failing build |
+| **[CI](docs/ci.md)** | Baselines, fail triggers, output formats, the bundled Actions, pinning |
 | **[Terraform plans](docs/terraform.md)** | Reviewing `terraform show -json` output and the `terraform` pack |
+| **[Kubernetes](docs/kubernetes.md)** | Diffing rendered Helm/Kustomize manifests before they reach a cluster |
+| **[Comparison](docs/comparison.md)** | Honest comparison with Checkov, Trivy/tfsec, conftest/OPA, tf-summarize, dyff |
+| **[Supported formats](docs/formats.md)** | YAML, JSON, TOML, INI, dotenv, age — and what each one accepts |
+| **[Encrypted files](docs/encrypted-files.md)** | SOPS and age: what is detected, why nothing is decrypted |
+| **[Configuration](docs/configuration.md)** | `.flectorc`, profiles, ignore patterns, array identity, masking |
+| **[CLI reference](docs/cli-reference.md)** | Every command, flag, and exit code |
+| **[Policy packs](docs/policy-packs.md)** | Writing declarative rules |
+| **[Plugins](docs/plugins.md)** · **[Cookbook](docs/plugin-cookbook.md)** | Rules that need real code |
 | **[Webhooks and commands](docs/webhooks.md)** | Envelope shape, delivery modes, command environment |
 | **[MCP server](docs/mcp.md)** | Read-only diff/check/explain tools for agents, and the security posture |
 | **[Explain](docs/explain.md)** | Opt-in model narration of a diff: what is sent, what it can never do, cost |
-| **[Policy packs](docs/policy-packs.md)** | Writing declarative rules |
-| **[Plugins](docs/plugins.md)** · **[Cookbook](docs/plugin-cookbook.md)** | Rules that need real code |
-| **[Live drift](docs/drift.md)** | `flecto-drift`: comparing a declared config against what is actually running |
+| **[Editor diagnostics](docs/editor.md)** | `flecto lsp` setup for Neovim, Helix, Emacs |
+| **[Live drift](docs/drift.md)** | `flecto-drift`: declared config versus what is actually running |
+| **[Performance](docs/performance.md)** | Where time goes at scale |
+| **[Stability](docs/stability.md)** | What you can build against, and the deprecation sequence |
 | **[Troubleshooting](docs/troubleshooting.md)** | When something doesn't behave |
-| **[Stability](docs/stability.md)** | What you can build against, what you cannot, and the deprecation sequence |
-| **[Migrating to 4.0](docs/migrating-to-4.md)** | The five breaking changes, and how to tell whether they affect you |
+| **[Migrating to 4.0](docs/migrating-to-4.md)** | The five breaking changes, and whether they affect you |
 | **[Changelog](CHANGELOG.md)** | Release history and migration notes |
 ---
-## How it works
-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
-Flecto runs entirely on your machine. Snapshots are local files, and nothing
-leaves the process unless you configure a webhook or command.
----
-## Stability
-Flecto runs inside your merge path, so here is what you can build against.
-These follow [semver](https://semver.org/) and are covered by the deprecation
-sequence below:
-- **The JSON envelope** (`schema_version: "2.0"`) — existing fields keep their
-  name, type, and meaning; new fields are additive. Schemas in [`schemas/`](schemas).
-- **Exit codes** — `0` clean, `1` a fail trigger matched or the run could not
-  complete. That is the whole set, and Flecto fails closed.
-- **`.flectorc`** — documented keys keep their name, meaning, and default.
-- **Command and flag names**, and what a flag accepts.
-**No breaking change to those ships without a minor release that warns first**,
-names the replacement, and says which version removes the old form. The one
-exception is a security fix: if a surface can make `flecto ci` report a clean run
-on a change that is not clean, it gets closed in the next release with an
-advisory. 4.0 was exactly that — five breaking changes, every one a bypass.
-Deliberately **not** stable: terminal and `pr-comment` output (presentation —
-parse `--format json` instead), message wording, anything under `src/`, and
-snapshot file internals. Built-in packs gain rules in minor releases; rule IDs
-never change meaning.
-Flecto reached 4.0 in four months, which is fast. That churn was front-loaded
-into a period with no real users, and 4.0 was forced by a
-[security review](docs/security-review.md) finding real bypasses. The intent now
-is minor releases only — anything needing a 5.0 waits in
-[`docs/v5-proposals.md`](docs/v5-proposals.md).
-→ **[Full stability policy](docs/stability.md)**
----
 ## Project
 - **Questions and ideas** — [Discussions](https://github.com/myselfsiddharth/Flecto/discussions)

package/package.json CHANGED Viewed

@@ -4,7 +4,7 @@
     "access": "public",
     "provenance": true
   },
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "Reads your Terraform plan and Kubernetes changes and posts a plain-English risk summary on every pull request, blocking the dangerous ones",
   "license": "MIT",
   "keywords": [