Skip to content

Rewrite the README for first-time users, reference moved to docs/ - #23

Merged
hbenabdallah merged 1 commit into
mainfrom
docs/readme-rewrite
Nov 14, 2026
Merged

hbenabdallah merged 1 commit into
mainfrom
docs/readme-rewrite

Conversation

@hbenabdallah

@hbenabdallah hbenabdallah commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

The README is now a 111-line page for a PHP developer seeing phpgraph for the first time: the problem, one measured result, a one-command install, mcp-config claude, four example questions and the main limitations. The reference material moves to docs/, and no code changes.

  • README.md and README.fr.md rewritten. The French one is a translation of the English one.
  • docs/ARCHIVE.md: the previous README, unchanged.
  • docs/BENCHMARKS.md (renamed from BENCHMARK.md): results grouped by phpgraph version and agent, with single-run and private results marked. It also holds the comparisons with other code graphs and the corpus table. docs/BENCHMARK.md is now a stub, because tools/agent-bench/ and the changelog still link to it.
  • New in docs/: INSTALL, MCP-TOOLS, CLI, GRAPH (relations, confidence levels), RULES (phpgraph check, phpgraph.yaml), FRAMEWORKS (matrix, microservices, XML action routing), LIMITATIONS, FAQ. Their text is moved word for word from the old README.

Headline result: Akeneo, the byCode() impact task, Claude Code 2.1.323 with Sonnet, 3 runs per arm. Both arms answered 3/3; the median tokens were 86,174 with phpgraph and 174,735 without, and the time was not better. The README says this is the best impact task, and that the other five ranged from +1 % to +56 % tokens.

Corrections made while moving the text:

  • The FAQ's Akeneo build figures now match corpus/RESULTS.md.
  • The FAQ says when phpgraph itself needs PHP 8.5: Composer and the PHAR need it, the executable and Docker don't. Any PHP version can be analysed. composer require --dev fails in a project pinned below 8.5.

Still open, not changed here:

  • The old "92.9 to 99.1 % typed" range is wrong: Ecotone is at 92.7 %.
  • The mcpservers.org badge still points to hbenabdallah/phpgraph.
  • The two graphify comparisons link to two different repositories.
  • The demo GIF is a placeholder.

@hbenabdallah hbenabdallah changed the title Rewrite the README for first-time users; move the reference to docs/ Rewrite the README for first-time users, reference moved to docs/ Nov 14, 2026
@hbenabdallah
hbenabdallah merged commit 8e05610 into main Nov 14, 2026
2 checks passed
@hbenabdallah
hbenabdallah deleted the docs/readme-rewrite branch November 14, 2026 19:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant