Problem

The README is 686 lines, and ~66% of it is reference material:

It reads like a reference manual wearing a landing page's clothes: someone arriving from GitHub or Packagist to answer "what is this and do I need it?" has to scroll past the full catalog of every rule. There's also duplicated content — install is documented twice (Quick Start + Installation), and configuration is explained in three different places.

Goal

The README should have one job: convince the reader, get them to a first green check, and point them to where to go next. Everything that is consultation (the rule catalog, the builders) is reference — and reference is searched, not read, so it shouldn't sit in the reading flow.

Reference and long-form guides move into a docs/ folder in the repo (markdown, browsable on GitHub, versioned with the code, reviewed in PRs).

Target README

A slim landing page (~150–180 lines):

• Hero — what it is + why it matters
• Quick comparison — when to choose PHPArkitect vs the alternatives (Deptrac, PHPat, Pest arch testing) (new content)
• Quick Start — install + init + check, unified (removes the duplicated Installation section)
• Core concepts — ClassSet / Rule / Expression, with one example
• A showcase recipe — one common architecture rule, linking to the cookbook
• Rules at a glance — an index table, linking to the full reference
• Further reading — links into docs/

Target docs/

Deliberately few files:

• docs/rules.md — the full rule catalog + Rule Builders (the "what rules exist" and "how to compose them" belong together)
• docs/configuration.md — the configuration reference table + config/baseline/output-format guide (the three duplicated config explanations merged into one)
• docs/cookbook.md — copy-paste recipes for real scenarios: layered architecture, hexagonal, DDD bounded contexts, "the domain must not depend on the framework", naming conventions (new content)
• docs/custom-rules.md — how to write your own Expression, based on the interface and a minimal example like IsFinal (new content)

Note on the comparison

Not a feature checkbox matrix (ages badly, easy to look biased) but an honest "when does each tool fit" framing. Every claim about other tools must be verified against their docs, not written from memory.