diff --git a/README.md b/README.md
index ea3b6c9..23f6da7 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,8 @@
-Point Claude at a repository and let Lazarus help make it: Alive again, documented, and audited β behind a guard that **blocks** destructive commands before they ever run.
+**Point Claude at any repo β Lazarus makes it run, tells you what to fix, and makes the page worth showing.**
+
Nothing changes until you approve a plan. A guard blocks `rm -rf /` before it ever runs.
@@ -15,145 +16,78 @@ Point Claude at a repository and let Lazarus help make it: Alive again, document
-
-
----
-
-**Lazarus** is a Claude Code plugin for working on a codebase with an AI agent you can actually trust. It does **three jobs** on *any* repo β yours, one you inherited, an open-source project, healthy or broken:
-
-- π§ **Make it run** (`discover` β `repair`) β point it at code that won't start, or that you simply don't know yet. It investigates, proposes a plan with a concrete "done" checklist you approve, then works through the blockers until the app boots β and writes down what actually worked so the next person (or the next you) doesn't start from zero.
-- π§ **Assess it β and, if you choose, fix it** (`audit` β `audit-repair`) β get a principal-engineer read: what's risky, what to fix first, and whether to maintain, refactor, or rewrite. A report you act on, hand to a client β or have executed finding-by-finding, each behind your approval.
-- π
**Polish your repo's public page β and, if you choose, fix it too** (`gitalive` β `gitalive-repair`) β not the code: the **README and the files around it** (LICENSE, CONTRIBUTING, security policy, issue templates, markdown accessibility) β everything a visitor sees on your GitHub page *before* reading the source. Every finding cites a real standard (GitHub's community profile, CommonMark, WCAG) β never taste. Then `gitalive-repair` executes the findings you ratify, asking for the facts only you own (which license? what security contact?) instead of inventing them.
-
-Everything runs behind a guard that blocks destructive commands before they ever run β and **nothing changes until you approve a plan.** It'll resurrect a dead repo that won't even start (the namesake), but it's just as useful on healthy code you want made runnable, understood, assessed, or ready to show the world.
-
-## π§ Three goals, six commands
-
-Lazarus looks like six skills, but you only ever choose a **goal**. Each flows *plan β you approve β execute* β the commands are just the steps:
-
-| You want⦠| The journey | How it flows |
-|---|---|---|
-| **It running** β *"it won't start"* Β· *"I'm lost in this repo"* Β· *"I need to change it safely"* | π **`discover`** β π§ *you approve* β π§ **`repair`** | `discover` investigates read-only and writes a plan with a runnable "done" checklist; you approve it; `repair` works the blockers until each one passes β recording what actually worked in `CLAUDE.md`. |
-| **It assessed β and, if you choose, fixed** β *"what shape is this in?"* Β· *"maintain, refactor, or rewrite?"* Β· *"now go fix what the audit found"* | π§ **`audit`** β π§ *your call* β π οΈ **`audit-repair`** | `audit` writes a read-only, 12-section principal-engineer report. Stop there β it's a deliverable you can hand to a client β or ratify its Top 10 and `audit-repair` executes them **one at a time**, verifying each against its acceptance check. |
-| **Your repo page presentable** (the README + community files) **β and, if you choose, fixed** β *"polish my README"* Β· *"is this repo ready to go public?"* Β· *"set up CONTRIBUTING / templates"* | π
**`gitalive`** β π§ *your call* β π§° **`gitalive-repair`** | `gitalive` writes a read-only, project-type-aware audit β every finding citing a named standard, with a waiver file so it never nags you about deliberate choices. Stop there, or ratify the findings and `gitalive-repair` executes them one at a time β re-checking each before editing, asking for facts only you own (license, security contact) instead of inventing them, and running **zero commands** the whole time. |
-
-And the whole time β every journey, every step β the π‘οΈ **guard** blocks `rm -rf /`, force-push, `DROP TABLE`, and ~25 more destructive commands before they ever execute.
-
-> [!NOTE]
-> **Don't memorize the order β start anywhere.** The skills route you: type `/lazarus:repair` with no plan and it stops and offers to run `discover` first; finish `discover` and it names the next command; `audit-repair` refuses to run until an `audit` is ratified, and `gitalive-repair` refuses without a ratified `gitalive` audit. The journeys stay independent β none requires another, and `audit` or `gitalive` are perfectly useful as reports you never act on.
-
-**New here?** The three commands below get you running in under a minute β no config, no keys. **Want the internals?** The collapsible **Deep dive** sections further down open up the guard's design, the anti-hallucination model, and the research behind it. For the whole picture in one read, see the [complete project overview](docs/OVERVIEW.md).
+
+Install Β·
+Watch it work Β·
+The journeys Β·
+The guard Β·
+GitAlive Β·
+FAQ
+
-**Contents:** [Three goals, six commands](#-three-goals-six-commands) Β· [Install (no signup, no SSH keys)](#-install-no-signup-no-ssh-keys) Β· [Watch it work](#-watch-it-work) Β· [The journeys](#%EF%B8%8F-the-journeys) Β· [The part that makes it safe to actually run](#%EF%B8%8F-the-part-that-makes-it-safe-to-actually-run) Β· [GitAlive β your repo's proof of life](#-gitalive--your-repos-proof-of-life) Β· [lazarus-github: audit findings as GitHub Issues](#-lazarus-github--file-audit-findings-as-github-issues) Β· [FAQ](#-faq) Β· [Star this repo](#-star-this-repo-it-decides-what-comes-next)
+
-## β‘ Install (no signup, no SSH keys)
+## β‘ Install
-In any `claude` session, run these **three commands β one at a time** (press Enter after each; don't paste them together):
+Run these in any `claude` session β **one at a time**:
-**1 β add the marketplace**
```text
/plugin marketplace add https://github.com/CognitiveCodeAI/lazarus
-```
-**2 β install the plugin**
-```text
/plugin install lazarus@cognitivecode
-```
-**3 β activate it in your session**
-```text
/reload-plugins
```
-That's it. It installs **globally** β active in every repo you open. No file copying, no config, no API keys, no signup.
+No config, no API keys, no signup β installed globally, active in every repo you open.
> [!IMPORTANT]
-> **Don't skip step 3.** Installing *registers* the plugin, but its skills, hooks, and guard don't go live until you run `/reload-plugins` (or restart `claude`). If you tried a command below and nothing happened, this is almost always why.
-
-> [!WARNING]
-> **Use the full `https://β¦` URL, not the short `CognitiveCodeAI/lazarus` form.** The short form makes Claude Code clone over SSH; if you don't have GitHub SSH keys set up you'll get `Permission denied (publickey)` or `Host key verification failed`. The HTTPS URL needs no SSH and no auth β it just works.
+> Don't skip `/reload-plugins` β skills and the guard only go live after it (or a restart). And use the full `https://β¦` URL: the short form clones over SSH and fails without SSH keys.
-Then open any repo, run `claude`, and either type **`/lazarus:discover`** or **`/lazarus:audit`** β or just say *"make this run locally."* See it in action below. π
+Then open any repo and just say *"make this run locally."*
## π¬ Watch it work
-A scary repo to a running app β discover, you approve, repair, and the guard swatting a destructive command mid-run:
-
-## πΊοΈ The journeys
-
-Three independent journeys. One makes the code run; one tells you what to do about it β and fixes it, if you say so; one makes the repo worth showing.
-
-```mermaid
-flowchart LR
- A["any codebase
(broken or healthy)"] --> B{what do
you need?}
-
- B -->|make it run| C["π lazarus:discover
read-only"]
- C --> D["π DISCOVERY.md
plan + 'done' checklist"]
- D --> E(["π§ you approve
the checklist"])
- E --> F["π§ lazarus:repair
works the blockers"]
- F --> G["β
running app +
verified CLAUDE.md"]
-
- B -->|assess it| H["π§ lazarus:audit
read-only"]
- H --> I["π CODEBASE_AUDIT.md
risks Β· what to fix first
Β· refactor vs rewrite"]
- I -.->|"optional"| J(["π§ you ratify
the Top 10"])
- J --> K["π οΈ lazarus:audit-repair
one finding at a time"]
- K --> L["β
findings fixed +
verified against checks"]
-
- B -->|polish the repo page| M["π
lazarus:gitalive
read-only"]
- M --> N["π GITALIVE_AUDIT.md
scorecard Β· cited findings
Β· recommended fixes"]
- N -.->|"optional"| O(["π§ you ratify
the findings"])
- O --> P["π§° lazarus:gitalive-repair
one finding at a time, zero shell"]
- P --> Q["β
findings fixed +
GITALIVE_CHANGES.md"]
-
- style A fill:#fee2e2,stroke:#ef4444,color:#111
- style G fill:#dcfce7,stroke:#22c55e,color:#111
- style I fill:#e0f2fe,stroke:#0ea5e9,color:#111
- style N fill:#e0f2fe,stroke:#0ea5e9,color:#111
- style E fill:#fef9c3,stroke:#eab308,color:#111
- style J fill:#fef9c3,stroke:#eab308,color:#111
- style O fill:#fef9c3,stroke:#eab308,color:#111
- style L fill:#dcfce7,stroke:#22c55e,color:#111
- style Q fill:#dcfce7,stroke:#22c55e,color:#111
-```
+## π§ The three journeys
-**Type the command, or just describe what you want** β both work. The fast path is the command itself (start typing `/discover`, `/repair`, `/audit`, or `/gitalive` and it autocompletes); plain English triggers the same skill.
+Six skills, but you only ever choose a **goal**. Every journey is *plan β you approve β execute*:
-**Journey 1 β make it run**
+| You want⦠| Just say⦠| The journey | You get |
+|---|---|---|---|
+| π§ **It running** | *"make this run locally"* Β· *"why won't this start?"* | **`discover`** β π§ β **`repair`** | A ratified plan, the blockers fixed, a `CLAUDE.md` of *verified* commands |
+| π§ **It assessed β then fixed** | *"audit this repo"* Β· *"refactor or rewrite?"* | **`audit`** β π§ β **`audit-repair`** | A 12-section principal-engineer report; its Top 10 executed one finding at a time |
+| β‘ **It alive to visitors** | *"polish my README"* Β· *"ready to go public?"* | **`gitalive`** β π§ β **`gitalive-repair`** | A standards-cited repo-page audit; the fixes, behind your gate |
-| Command | Also triggers on⦠| What it does |
-|---|---|---|
-| **`/lazarus:discover`** | *"make this run locally"* Β· *"why won't this start?"* Β· *"onboard this repo"* Β· *"help me get oriented"* | Investigates **read-only**, writes `DISCOVERY.md` β a *repairability verdict*, a plan, and a concrete *definition of done* β then **stops and waits for you**. |
-| **`/lazarus:repair`** | *"execute the repair plan"* Β· *"fix this codebase"* Β· *"work the blockers"* | Works the blockers in order, logs every command it actually ran to `VERIFICATION_REPORT.md`, and promotes the commands that *truly worked* into a `CLAUDE.md`. Needs a ratified `DISCOVERY.md` first β and refuses one whose verdict is *not-repairable* (never-built features are feature work, not a repair). |
+**Start anywhere β the skills route you.** `repair` with no plan offers to run `discover`; every apply phase refuses to run without its ratified report. Each report is also a complete deliverable on its own. Commands are `/lazarus:`, but plain English triggers the same thing.
-**Journey 2 β assess it, then (optionally) fix it**
+## π‘οΈ The guard
-| Command | Also triggers on⦠| What it does |
-|---|---|---|
-| **`/lazarus:audit`** | *"review this code"* Β· *"audit this repo"* Β· *"what should we fix first?"* Β· *"refactor or rewrite?"* | Produces a 12-section `CODEBASE_AUDIT.md` β architecture, risks, security, frontend/accessibility, a phased plan. **Read-only**; feeds `audit-repair` if you choose to act on it. |
-| **`/lazarus:audit-repair`** | *"execute the audit"* Β· *"fix the audit findings"* Β· *"work the Top 10 action items"* Β· *"apply the modernization plan"* | Executes a ratified `CODEBASE_AUDIT.md` Β§11 **one finding at a time** β ratify β act β verify against each item's acceptance check β safety-rails first, behind the guard. The strategic apply phase, exactly as `repair` is for `discover`. |
+
-**Journey 3 β polish the repo page (README + community files), then (optionally) fix it**
+A `PreToolUse` hook inspects every shell command *before* it runs and refuses the dangerous ones β `rm -rf /`, force-push, `DROP TABLE`, `terraform destroy`, and ~25 more. It is **not** a politely-worded instruction the model can talk itself out of: it runs outside the model, fails closed, and composes with hooks you already have.
-| Command | Also triggers on⦠| What it does |
-|---|---|---|
-| **`/lazarus:gitalive`** | *"polish my README"* Β· *"is this repo ready to go public?"* Β· *"DevRel review"* Β· *"set up CONTRIBUTING / CODE_OF_CONDUCT / issue templates"* | **Read-only**, project-type-aware audit of the repo's public files β README, community-health files, markdown accessibility β every finding citing a named standard (GitHub community profile, CommonMark, WCAG, DiΓ‘taxis). Writes `GITALIVE_AUDIT.md` after you approve; a waiver file keeps your deliberate choices from being re-flagged. GitHub *settings* (topics, social preview) are out of scope β they need `gh`, which this skill structurally cannot run. |
-| **`/lazarus:gitalive-repair`** | *"apply the GitAlive audit"* Β· *"fix the repo-page findings"* Β· *"scaffold the community files"* Β· *"fix my README per the audit"* | Executes a ratified `GITALIVE_AUDIT.md` **one finding at a time** β re-observes before every edit (a finding fixed since the audit is logged `already-satisfied`, untouched), asks for facts only you own (license choice, security contact) **instead of inventing them**, refuses fixes that reach outside the presentation file family, and verifies each change against its rubric check in `GITALIVE_CHANGES.md`. **Zero shell** β like `gitalive`, it cannot run a command at all. |
+## β‘ GitAlive β your repo's proof of life
-> [!TIP]
-> **Pairs with `/code-review`** β a *built-in* Claude Code command (not part of Lazarus). Point it at your current diff for a focused bug-and-cleanup pass once the app runs.
+π§ββοΈ *IT'S ALIVE β now make the repo page prove it.* Your README is the first thing anyone checks to decide whether a project is worth their time. `gitalive` audits everything a visitor sees *before* the source β README, LICENSE, CONTRIBUTING, security policy, templates, accessibility β against **cited standards, never taste**. `gitalive-repair` fixes what you ratify, asking for facts only you own (which license? what security contact?) and running **zero shell commands**.
-> [!TIP]
-> **Turn an audit into a backlog.** The optional **`lazarus-github`** companion files an audit's findings as GitHub Issues β see the **lazarus-github** section below.
+
+

+
-## π‘οΈ The part that makes it safe to actually run
+That's not a mock-up β it's **this repo**, as GitAlive's first run found it and as it stands after the ratified fixes. Deliberate choices stay quiet: waive an item once and re-runs never nag you about it.
-Here's the headline. Letting an agent loose in an unfamiliar repo is terrifying because one confident-but-wrong command can wreck your machine. So Lazarus ships a **deterministic guard** β a `PreToolUse` hook that inspects every shell command *before* it runs and refuses the dangerous ones.
+## π§© The family
-
+```text
+lazarus/ β the marketplace
+βββ plugins/lazarus π§ core β the six skills, the repo-explorer subagent, the guard
+βββ plugins/lazarus-github π optional β files an audit's Top 10 as GitHub Issues
+βββ plugins/lazarus-forge π οΈ optional β pre-build design review for new skills/plugins
+```
-This is **not** a politely-worded instruction Claude can talk itself out of. It's a hook that runs outside the model and returns "no." It blocks `rm -rf /`, `git push --force`, `git reset --hard origin`, `DROP TABLE`, `terraform destroy`, `kubectl delete`, `npm publish`, and ~25 more patterns β and it **composes** with any hooks you already have, so nothing of yours is overwritten.
+Outward-facing integrations ship as **opt-in siblings, never in core** β the three-command install stays zero-config, and a `gh`/API failure can only reach someone who asked for it. The companion is one command: `/plugin install lazarus-github@cognitivecode`, then `/lazarus-github:issues` turns `CODEBASE_AUDIT.md` Β§11 into ratified, deduplicated GitHub Issues β re-runs never file twice.
---
@@ -165,12 +99,9 @@ This is **not** a politely-worded instruction Claude can talk itself out of. It'
Long-running agents have a documented failure mode: they quietly turn *guesses* into *established facts* over many turns, then act on them. Lazarus is engineered against that.
- **Confidence tags on every claim.** Everything written to `DISCOVERY.md` is tagged `[VERIFIED]` (observed in a real command), `[INFERRED]` (one strong signal), or `[ASSUMED]` (a guess). A claim **cannot** be promoted to `[VERIFIED]` without actually executing and observing it. Only `[VERIFIED]` facts are ever allowed into a `CLAUDE.md`.
-
-- **A mechanical Definition of Done.** Discovery doesn't end with a vibe ("looks done"). It ends with runnable assertions β *`install` exits 0*, *`build` exits 0*, *the start command stays up 30s*, *one real end-to-end smoke check passes*. Repair isn't finished until those check.
-
-- **Forensic file separation.** `DISCOVERY.md` (what we *believed* before) and `VERIFICATION_REPORT.md` (what we *observed* during) are kept as **separate files, never edited in place**. When something breaks three weeks later, you can see exactly what was assumed vs. proven.
-
-- **Plan Mode is the enforcement, not a request.** Discovery and audit run in Claude Code's Plan Mode, which is read-only *at the tool level*. It's a structural guarantee, not "please don't edit anything."
+- **A mechanical Definition of Done.** Discovery doesn't end with a vibe ("looks done"). It ends with runnable assertions β *`install` exits 0*, *the start command stays up 30s*, *one real end-to-end smoke check passes*.
+- **Forensic file separation.** What we *believed* before (`DISCOVERY.md`) and what we *observed* during (`VERIFICATION_REPORT.md`) are separate files, never edited in place β so you can always see what was assumed vs. proven.
+- **Plan Mode is the enforcement, not a request.** The read-only skills run read-only *at the tool level* β a structural guarantee, not "please don't edit anything."
@@ -179,17 +110,13 @@ Long-running agents have a documented failure mode: they quietly turn *guesses*
-The hook is a single bash script (`scripts/check-destructive.sh`) wired in via `hooks/hooks.json`. The non-obvious engineering:
-
-- **It reads tool input as JSON on stdin** and extracts `.tool_input.command`. (A common mistake is to read a `$CLAUDE_TOOL_INPUT_command` env var β that variable doesn't exist in current Claude Code, and a hook written against it silently passes *everything*. This one was built and tested against the real contract.)
-
-- **Precise extraction, four ways.** It pulls the command via the first available of `jq` β `python3` β `python` β `perl` (Perl uses core `JSON::PP`, present on stock macOS/Linux). It never does coarse text-matching on the raw payload, so a destructive word sitting in some *other* field (like a directory path) never causes a false block.
+One bash script (`scripts/check-destructive.sh`), wired via `hooks/hooks.json`:
-- **It fails *closed*.** If somehow none of those parsers exist, the hook blocks every bash command with an explanation rather than letting commands through unchecked. The safe failure mode is "stop," never "allow."
+- **Reads tool input as JSON on stdin** and extracts `.tool_input.command` precisely β never coarse text-matching, so a scary word in a file *path* never causes a false block. (Hooks that read a `$CLAUDE_TOOL_INPUT_command` env var silently pass everything β that variable doesn't exist. This one was built against the real contract.)
+- **Four parsers, fail-closed.** `jq` β `python3` β `python` β `perl` (core `JSON::PP`, stock on macOS/Linux). If none exist, it blocks every bash command rather than letting them through.
+- **`exit 2` = deny.** Claude sees the stderr and adjusts instead of retrying blindly.
-- **`exit 2` = deny.** The hook's stderr is shown to Claude, which adjusts instead of retrying blindly. Want to allow something it blocks? Run it yourself, outside Claude Code.
-
-Customizing the blocklist is one regex in one file. Extend it for your environment (your prod CLI, your migration tools) and push β every install picks it up.
+Customizing the blocklist is one regex in one file β fork, extend for your environment, and every install picks it up.
@@ -198,157 +125,61 @@ Customizing the blocklist is one regex in one file. Extend it for your environme
-The design choices aren't arbitrary; most trace to a specific 2026 empirical finding:
-
-- **Verified/inferred/assumed split** β agents convert assumptions into facts over long runs *(arXiv 2602.16666, "Towards a Science of AI Agent Reliability")*.
-- **Test-pass, not just build-pass, as the bar** β fix-related agent PRs fail most often at test cases, not builds *(arXiv 2602.00164)*.
-- **Definition-of-Done as evolving constraints** β repo repair is "search over evolving behavioral constraints," not optimization under fixed tests *(arXiv 2604.04580)*.
-- **Bias against rewrite** β un-merged agent PRs tend to be the large, sprawling ones; incremental beats rewrite on average *(arXiv 2601.15195)*.
-- **Cheap read-only exploration on Haiku** β mapping a large repo with read-only text tools on a small (Haiku-tier) model captures the structural signal at a fraction of the token cost of doing it on the main model.
-- **CLAUDE.md is normative, not community-converged** β there's still no settled standard, so the toolkit anchors to a commands-first structure *(arXiv 2510.21413)*.
+- **Verified/inferred/assumed split** β agents convert assumptions into facts over long runs *(arXiv 2602.16666)*.
+- **Test-pass, not just build-pass** β fix-related agent PRs fail most often at tests, not builds *(arXiv 2602.00164)*.
+- **Definition-of-Done as evolving constraints** β repo repair is "search over evolving behavioral constraints" *(arXiv 2604.04580)*.
+- **Bias against rewrite** β un-merged agent PRs tend to be the large, sprawling ones *(arXiv 2601.15195)*.
+- **README content research** β what visitors look for, and what's most often missing *(Prana et al., EMSE 2019)* β grounds the GitAlive rubric, alongside GitHub's community profile, CommonMark, and WCAG.
+- **Cheap read-only exploration on Haiku** β mapping a huge repo on a small model captures the structure at a fraction of the cost.
-
-π§© What's actually in the box
-
-
-
-This repo is a Claude Code **plugin marketplace** with a small, growing family:
-
-```text
-lazarus/ β the marketplace
-β
-βββ plugins/lazarus/ π§ core β /plugin install lazarus@cognitivecode
-β βββ skills/discover Β· repair Β· audit Β· audit-repair Β· gitalive Β· gitalive-repair
-β βββ agents/repo-explorer read-only Haiku subagent for huge repos
-β βββ hooks/ + scripts/check-destructive.sh the deterministic guard
-β
-βββ plugins/lazarus-github/ π optional companion β /plugin install lazarus-github@cognitivecode
-β βββ skills/issues turns an audit's Top 10 into GitHub Issues
-β
-βββ plugins/lazarus-forge/ π οΈ optional companion β /plugin install lazarus-forge@cognitivecode
- βββ skills/design-review pre-build quality gate for skill/plugin/agent/MCP/hook proposals
-```
-
-**Built to grow.** Anything outward-facing (creating GitHub issues, posting to Slack, filing Linear/Jira tickets) ships as an **opt-in sibling plugin**, never bundled into core β so the three-command install stays zero-config and an integration's `gh`/API failure can't reach anyone who didn't ask for it.
-
-The `repo-explorer` subagent is deliberately restricted (read-only tool allowlist, Haiku tier) so mapping a 5,000-file monolith doesn't burn your context or your budget.
-
-
-
-## β‘ GitAlive β your repo's proof of life
-
-π§ββοΈ *IT'S ALIVE β now make the repo page prove it.*
-
-Your README is the first thing anyone checks to decide whether a project is alive: real title, live badges, a license, a way to contribute, signs of care. **GitAlive** is that judgment, systematized β `gitalive` audits everything a visitor sees *before* the source (README, LICENSE, CONTRIBUTING, security policy, templates, markdown accessibility) against **cited standards, never taste**, and `gitalive-repair` fixes what you ratify.
-
-
-

-
-
-**That before/after isn't a mock-up β it's this repo.** GitAlive's first run graded the Lazarus README itself (0 Critical Β· 2 High Β· 2 Medium Β· 4 Low): it caught a CI pipeline wearing no badge, a project name that existed only inside a PNG, and contributor docs one plugin behind reality. Every finding fixed behind the ratify gate; the table of contents above was written by `gitalive-repair`. On the follow-up run it correctly detected 7 of 8 findings as already fixed and **touched nothing** β the re-observe-before-edit rule working as designed.
-
-```text
-/lazarus:gitalive # the audit β read-only, zero shell, writes GITALIVE_AUDIT.md
-/lazarus:gitalive-repair # the fixes β one finding at a time, asks for facts it can't know
-```
-
-Deliberate choices stay quiet: waive any item once (`.lazarus/gitalive-waivers.yml`) and re-runs never nag you about it again.
-
-## π lazarus-github β file audit findings as GitHub Issues
-
-After running `/lazarus:audit`, you can turn the audit's Top 10 Action Items into filed GitHub Issues with one command. **`lazarus-github` is the first sibling plugin** in the Lazarus ecosystem β opt-in, installed separately from core.
-
-**Install** (one at a time, like the core install):
-
-```text
-/plugin install lazarus-github@cognitivecode
-```
-```text
-/reload-plugins
-```
-
-**Use:**
-
-```text
-/lazarus-github:issues
-```
-
-The skill reads `CODEBASE_AUDIT.md` Β§11, shows you the proposed issues, lets you adjust titles and labels and pick which to file, then runs `gh issue create` for each one. **Ratify-before-create β nothing is filed silently.**
-
-**Idempotent on re-runs.** Each created issue carries a hidden provenance marker (``, keyed to a *stable per-item slug β not the rank*) plus a `lazarus-audit` label. Re-audit your repo, re-run `/lazarus-github:issues`, and items that already have an issue are skipped β only new findings get filed. Re-ranking on a re-audit can't cause duplicates, because the marker keys on the slug, not the position.
-
-**GitHub-only for v1.** Uses the `gh` CLI, which most developers already have β pre-authenticated in many environments (Codespaces, devcontainers, anyone who's run `gh auth login`). No API tokens to manage.
-
-**What it requires:** `gh` installed, authenticated (`gh auth status` succeeds), and resolving to the current repo (`gh repo view` succeeds). The skill fails fast with a clear message if any of these isn't true β it never partially files.
-
-### The sibling plugin pattern
-
-`lazarus-github` establishes the structural pattern for outward-facing integrations: each ships as a **separate opt-in plugin in the same marketplace, never bundled into core.** Core Lazarus stays small, fast, and zero-config; integrations grow the ecosystem by addition.
-
-**Why not one plugin with every integration?** Each tracker has its own auth story β Linear and Jira need API tokens and workspace config; GitLab brings its own CLI. Bundling them into core would force every user to pay the setup cost for integrations they'll never use. Sibling plugins let you install only what you need β and a `gh`/API failure can only ever reach someone who opted in.
-
-**Other tracker integrations** (Linear, Jira, GitLab) are part of the architectural vision β *not* committed roadmap items. If one would help you, [open a discussion](https://github.com/CognitiveCodeAI/lazarus/discussions); interest signals what to build next.
-
## β FAQ
-I installed it but /lazarus:discover (or the guard) does nothing. Why?
+I installed it but the commands (or the guard) do nothing. Why?
-You almost certainly skipped /reload-plugins. Installing registers the plugin; its skills, hooks, and guard only go live after you run /reload-plugins (or restart claude) in that session. Run it once and the /lazarus:discover, /lazarus:repair, /lazarus:audit, /lazarus:audit-repair, /lazarus:gitalive, and /lazarus:gitalive-repair commands appear.
+You almost certainly skipped /reload-plugins. Run it once (or restart claude) and all six /lazarus:* commands appear.
Will it actually change my code without asking?
-Discovery, audit, and gitalive are read-only (Plan Mode β and gitalive can't even run shell commands; they're removed from its tool pool). Repair, audit-repair, and gitalive-repair change files β but only after you ratify a plan (the "done" checklist, the audit's Top 10, or the GitAlive findings), and the guard blocks destructive shell commands throughout (gitalive-repair goes further: it runs no commands at all). You stay in the loop at the one decision that matters: ratifying what "done" means.
+The audit skills (discover, audit, gitalive) are read-only. The apply skills (repair, audit-repair, gitalive-repair) change files β but only after you ratify a plan, with the guard active throughout (and gitalive-repair can't run commands at all). You own the one decision that matters: what "done" means.
Do I need jq installed?
-No. The guard uses whichever of jq / python3 / python / perl is present. Stock macOS and most Linux ship perl with the core JSON::PP module, so the guard works out of the box even with no jq and no Python. If none of the four are present, it blocks bash commands until you install one β it never silently lets them through.
+No. The guard uses whichever of jq/python3/python/perl is present (stock macOS/Linux always has one), and blocks rather than allows if none are.
Does it work on Windows?
-Use WSL. The guard is a bash hook (scripts/check-destructive.sh), so it needs a Unix-like shell with one of jq/python3/python/perl. Under WSL (or Git Bash) everything works; in a bare Windows cmd/PowerShell session the hook can't execute, which means no protection β so run Lazarus from WSL. (The badges up top say macOS Β· Linux for this reason.)
+Use WSL. The guard is a bash hook; in a bare cmd/PowerShell session it can't execute, which means no protection.
How do updates work?
-Two steps. 1) Run /plugin update lazarus@cognitivecode (and the same for lazarus-github / lazarus-forge if you installed them). 2) Run /reload-plugins (or restart claude) β same rule as installing: the updated skills, hooks, and guard don't go live in your session until you reload. The plugin is git-SHA-versioned, so /plugin update always pulls the latest main β there's no version number you have to match. Tagged releases like v0.5.0 are human-readable changelog markers (see Releases), not something you pin to. Check what you're on with /plugin list.
+/plugin update lazarus@cognitivecode (and the same for any companions), then /reload-plugins. The plugin is git-SHA-versioned β updates always pull the latest main; tags like v0.8.0 are just changelog markers. Check yours with /plugin list.
Can I customize the blocked-command list?
-Yes β it's one regex in scripts/check-destructive.sh. Fork, edit, and point your team at your fork's marketplace.
+Yes β one regex in scripts/check-destructive.sh. Fork and point your team at your fork's marketplace.
-## β Star this repo (it decides what comes next)
+## β Star it
-
-
-**If Lazarus saved you an afternoon, drop a star.** β
+**If Lazarus saved you an afternoon, drop a star** β it's how the next person staring at a dead repo finds this, and it's how I decide what to build next.
-
-
-It's a 1-second click, and it does two things: it helps the next person staring at a dead repo actually *find* this, and it tells me whether to keep building in the open.
-
-I have **more Claude Code tools ready to ship** β I'm releasing them based on real signal. Stars and activity here are how I gauge whether people want them. So a star isn't just a thank-you; it's a vote for the next one.
-
-> β
**Just shipped: GitAlive** β‘ β the repo-page journey gets a name worthy of it. `presentation` β **`gitalive`**, `presentation-repair` β **`gitalive-repair`**: audit everything a visitor sees before your source, then fix what you ratify β re-checking each finding before editing, asking for facts only you own, running **zero shell commands**. See the before/after above β it's this very repo. β star and [open a discussion](https://github.com/CognitiveCodeAI/lazarus/discussions) to shape what's next.
-
-> π¬ Got an idea, a bug, or a repo Lazarus choked on? [Open an issue](https://github.com/CognitiveCodeAI/lazarus/issues) or start a [discussion](https://github.com/CognitiveCodeAI/lazarus/discussions) β I read every one.
+> β
**Just shipped: GitAlive** β‘ β the repo-page journey, renamed and spotlighted (see the before/after above β it's this very repo). Got an idea or a repo Lazarus choked on? [Open an issue](https://github.com/CognitiveCodeAI/lazarus/issues) or [start a discussion](https://github.com/CognitiveCodeAI/lazarus/discussions) β I read every one.
---
-**Maintaining or contributing?** See [MAINTAINING.md](./MAINTAINING.md) and [CONTRIBUTING.md](./CONTRIBUTING.md).
-