mozilla · groovecoder · Aug 3, 2026 · Aug 3, 2026
@@ -6,15 +6,16 @@
 
 Software projects depend on hundreds of libraries. Those libraries release updates constantly. Each update creates a small task: check the change, run the tests, merge it in. Multiply that across dozens of projects and the backlog grows fast.
 
-BLEnder handles it. It watches your projects for dependency updates, decides which ones are safe, and merges them. For big updates that might change how a library works, BLEnder reviews the change to merge it or flag it for you to review. When an update breaks something, BLEnder reads the error, and commits a fix for you to review. 
+BLEnder handles it. It watches your projects for dependency updates, decides which ones are safe, and merges them. For big updates that might change how a library works, BLEnder reviews the change to merge or flag it for you to review. When an update breaks something, BLEnder reads the error, and commits a fix for you to review. 
 
-**One install covers all the orgs.** BLEnder runs on its own. Your projects don't need secrets or processes to get started beyond a short onboarding step.
+BLEnder runs on its own. Your projects don't need secrets or processes to get started beyond [a short onboarding step](#getting-started).
 
 ### At a glance
 
-- **Safe small updates get merged.** Small, compatible updates with clean tests are approved and merged with no human involvement.
-- **Major updates get reviewed.** Major version changes are analyzed for breaking changes. Safe ones merge. Uncertain ones get a written report for a human to decide.
-- **Broken updates get fixed.** When an update breaks the build, BLEnder reads the errors, writes a code fix, and commits it.
+- **Merges safe small updates.** Small, compatible updates with clean tests are approved and merged with no human involvement.
+- **Reviews major updates.** Major version changes are analyzed for breaking changes. Safe ones merge. Uncertain ones get a written report for a maintainer to decide.
+- **Fixes broken updates.** When an update breaks the build, BLEnder reads the errors, writes a code fix, and adds the fix to the update PR.
+- **Triages security alerts**. BLEnder investigates dependabot security alerts to see if your code actually uses the vulnerable dependency code. 
 - **Everything is auditable.** Every decision is posted as a comment on the update. Nothing happens in the dark.
 
 ---
@@ -33,11 +34,11 @@ For patch and minor updates, BLEnder checks:
 4. The library's compatibility score is 70% or higher
 5. No security advisories affect the new version
 
-All five must pass. If any check fails, the update waits or gets routed elsewhere.
+When all five checks pass, BLEnder marks the PR to auto-merge. If any check fails, BLEnder leaves a comment.
 
 ### Major version review
 
-Major version bumps can change how a library works. When BLEnder sees a major update, it uses [Claude Code](https://claude.com/product/claude-code) to:
+Major version bumps can change how a library works. When BLEnder sees a major update, it uses a locked-down, sandboxed [Claude Code](https://claude.com/product/claude-code) to:
 
 1. Read the library's release notes and new code
 2. Scan your code for affected areas
@@ -51,8 +52,8 @@ Major version bumps can change how a library works. When BLEnder sees a major up
 When BLEnder sees an update the breaks the repos checks, BLEnder:
 
 1. Collects the test output and error logs
-2. Sends them to [Claude Code](https://claude.com/product/claude-code) (Anthropic's AI) inside a locked-down sandbox with no network access and no credentials
-3. Validates the fix — rejects changes to sensitive files and scans for leaked secrets
+2. Sends them to a locked-down, sandboxed [Claude Code](https://claude.com/product/claude-code) to create a fix.
+3. Validates the fix.
 4. Commits the fix to the update
 
 The AI cannot access the internet, call any APIs, or see any credentials. Its output is validated before anything is committed.
@@ -62,14 +63,10 @@ The AI cannot access the internet, call any APIs, or see any credentials. Its ou
 The sweep also picks up open [Dependabot security alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts). For each one, BLEnder reads the codebase in a sandbox to judge whether the vulnerability actually reaches your project, then acts on the verdict:
 
 - **Unaffected** — dismisses the alert (when `dismiss_unaffected` is on) or opens a lock-file bump PR for a clean transitive fix.
-- **Affected** — opens a private security advisory and a fork where it drafts a fix.
+- **Affected** — opens a private security advisory and a fork where it creates a fix.
 
 You can tune this with the `investigate` config: turn it off per repo, set a minimum `severity_threshold`, or cap Claude's turns and budget.
 
-### Auto-engineer (experimental)
-
-BLEnder can also take on issue-driven code changes: label an issue, and it plans, implements, and self-reviews the work across separate steps. This is **off by default** and broader than the Dependabot flow. Enable it per repo under the `auto_engineer` config.
-
 ---
 
 ## Dashboard
@@ -86,14 +83,14 @@ Install the BLEnder GitHub App on your organization. Grant it access to the repo
 
 ### 2. Run onboarding
 
-Go to **BLEnder Setup** in the Actions tab and run the workflow for your project. BLEnder will analyze the project and open a pull request with a tailored configuration.
+Run [the Update BLEnder Config workflow in the BLEnder Actions](https://github.com/mozilla/blender/actions/workflows/build-setup.yml) workflow for your repo. BLEnder will analyze the project and open an onboarding pull request in the repo.
 
 ### 3. Review the onboarding pull request
 
 The pull request adds a `.blender/` directory with two files:
 
-- **`blender.yml`** — project metadata (name, language versions, install command)
-- **`agents.md`** — agent instructions BLEnder uses when fixing broken updates: install steps, exact CI and test commands, linters, and other repo knowledge
+- **`blender.yml`** — the BLEnder config file. (See [below](#project-config-blenderblenderyml))
+- **`agents.md`** — agent instructions BLEnder will use. (See [below](#agent-instructions-blenderagentsmd))
 
 If your repo has no existing agent instructions file, the PR also symlinks `CLAUDE.md`, `AGENTS.md`, and `.github/copilot-instructions.md` to `agents.md`.
 
@@ -103,6 +100,10 @@ Review that the configuration looks right and merge it. BLEnder starts working o
 
 ## Configuration
 
+### Default config
+
+BLEnder's defaults are in its own [`config/defaults.yml`](config/defaults.yml) file. You may override any of these in your repo's `.blender/blender.yml` project config.
+
 ### Project config (`.blender/blender.yml`)
 
 Onboarding generates this file. A minimal example:
@@ -123,51 +124,12 @@ Available fields:
 
 Omit fields that don't apply.
 
+You may also override any of BLEnder's [default configs](#default-config) in your repo's `.blender/blender.yml` project config.
+
 ### Agent instructions (`.blender/agents.md`)
 
 Onboarding generates this file. It holds the repo knowledge BLEnder needs to fix a broken update: install steps, the exact CI and test commands, linters, and language versions. When the repo already has an agent instructions file (like `CLAUDE.md`), BLEnder writes only the delta — what those files don't already cover.
 
-### Default settings
-
-BLEnder ships with defaults in [`config/defaults.yml`](config/defaults.yml):
-
-```yaml
-automerge:
-  dry_run: false
-  allow_major: false
-  review_major: true
-  min_compatibility_score: 70
-  check_advisories: true
-
-fix:
-  dry_run: false
-  max_claude_turns: 30
-  max_budget_usd: 2.00
-  max_fix_attempts: 3
-
-investigate:
-  enabled: true
-  dry_run: false
-  max_claude_turns: 20
-  max_budget_usd: 1.50
-  severity_threshold: ""      # "", "low", "medium", "high", or "critical"
-  dismiss_unaffected: false
-
-auto_engineer:                # experimental, off by default
-  enabled: false
-  dry_run: true
-  issue_label: "auto-engineer"
-  trusted_author_associations: "OWNER"
-  forbidden_paths: ".github/ .env .circleci/"
-  max_plan_turns: 20
-  max_plan_budget_usd: 1.50
-  max_implement_turns: 40
-  max_implement_budget_usd: 4.00
-  max_self_review_turns: 15
-  max_self_review_budget_usd: 1.00
-```
-
-Override any of these in your project's `.blender/blender.yml`.
 
 ---