docs: update reference docs

[reubeno]

No description provided.

[Copilot]

Pull request overview

Adds/refreshes reference documentation to better reflect current brush feature flags, configuration knobs, and bash-compat coverage, including a new reference page for experimental features.

Changes:

• Add docs/reference/experimental.md describing build-time and run-time experimental features and how to enable them.
• Update configuration reference to document equivalent CLI flags and clarify precedence/default behavior for syntax-highlighting and [experimental] settings.
• Refresh compatibility and top-level README statements (test-count figures and supported/unsupported feature callouts), and link the new experimental doc from the reference index.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/reference/experimental.md	New reference page enumerating experimental Cargo features and runtime experimental toggles.
docs/reference/configuration.md	Expands tables to include CLI flags and clarifies defaults/precedence for UI + experimental settings.
docs/reference/compatibility.md	Updates the compatibility reference to reflect additional supported features and updated test-count figures.
docs/reference/README.md	Adds the experimental-features page to the reference index.
README.md	Updates “at a glance” bullets to align with current defaults and compatibility notes.

[github-actions]

Performance Benchmark Report

Benchmark name	Baseline (μs)	Test/PR (μs)	Delta (μs)	Delta %
clone_shell_object	17.21 μs	17.41 μs	0.20 μs	🟠 +1.19%
eval_arithmetic	0.15 μs	0.15 μs	0.00 μs	⚪ Unchanged
expand_one_string	1.59 μs	1.56 μs	-0.04 μs	⚪ Unchanged
for_loop	29.44 μs	29.93 μs	0.49 μs	⚪ Unchanged
full_peg_complex	57.93 μs	57.72 μs	-0.21 μs	⚪ Unchanged
full_peg_for_loop	6.42 μs	6.24 μs	-0.18 μs	🟢 -2.87%
full_peg_nested_expansions	16.24 μs	16.31 μs	0.07 μs	⚪ Unchanged
full_peg_pipeline	4.14 μs	4.16 μs	0.02 μs	⚪ Unchanged
full_peg_simple	1.75 μs	1.76 μs	0.00 μs	⚪ Unchanged
function_call	3.22 μs	3.30 μs	0.08 μs	⚪ Unchanged
instantiate_shell	54.06 μs	54.24 μs	0.18 μs	⚪ Unchanged
instantiate_shell_with_init_scripts	25728.92 μs	26964.19 μs	1235.27 μs	🟠 +4.80%
parse_peg_bash_completion	2092.40 μs	2078.36 μs	-14.04 μs	⚪ Unchanged
parse_peg_complex	20.27 μs	20.34 μs	0.07 μs	⚪ Unchanged
parse_peg_for_loop	2.02 μs	2.00 μs	-0.02 μs	⚪ Unchanged
parse_peg_pipeline	2.02 μs	2.02 μs	0.00 μs	⚪ Unchanged
parse_peg_simple	1.07 μs	1.07 μs	-0.00 μs	⚪ Unchanged
run_echo_builtin_command	17.23 μs	17.04 μs	-0.19 μs	⚪ Unchanged
tokenize_sample_script	3.62 μs	3.39 μs	-0.23 μs	🟢 -6.41%

Code Coverage Report: Only Changed Files listed

Package	Base Coverage	New Coverage	Difference
Overall Coverage	🟢 75.39%	🟢 75.39%	⚪ 0%

Minimum allowed coverage is 70%, this run produced 75.39%

Test Summary: bash-completion test suite

Outcome	Count	Percentage
✅ Pass	1582	75.01
❗️ Error	18	0.85
❌ Fail	155	7.35
⏩ Skip	339	16.07
❎ Expected Fail	13	0.62
✔️ Unexpected Pass	2	0.09
📊 Total	2109	100.00

[github-actions]

Test Results

    5 files     40 suites   16m 24s ⏱️
2 472 tests 2 472 ✅ 0 💤 0 ❌
7 685 runs  7 685 ✅ 0 💤 0 ❌

Results for commit 4ba58be.