Update README

When to run

• A new class or module was added to the project
• A new public method was added to an existing class (if significant enough to appear in the README)
• The roadmap changed (item completed, new item added, item rephrased)
• At the end of every working session — run alongside update-backlog, even if no explicit change was requested (skip only if the session contained no public API change and no roadmap change)

Do not update the README for:

• Internal refactoring with no public API change
• Bug fixes that don't affect documented behaviour
• Test-only changes

Before writing anything

Read the current README.md in full to understand the existing structure and tone before making any modifications. Preserve the existing tone.

Procedure by trigger

Trigger: new class or module added

Add a new section under the appropriate heading. Include:

• How it works — explain the core data structure and its invariant in plain English. Include an ASCII diagram if the structure is spatial. One short paragraph on the performance trade-offs vs. standard library alternatives.
• Architecture — a markdown table with columns Type and Role listing interfaces, implementations, and synchronized variants.
• Features — a bullet list of the main public capabilities.
• Usage — code examples that compile against the actual public API. Cover: basic construction, the most common operation, any class-specific feature. Examples must be self-contained.
• Thread safety (only if a synchronized variant exists) — summarise which implementation is thread-safe, the locking strategy, and iterator behaviour (fail-fast vs. snapshot).

Trigger: new public method on an existing class

Locate the existing section. Update only what has changed:

• Add to Features if the method is significant and not already implied
• Update Usage if a new example would be helpful
• Do not rewrite the whole section — surgical edits only

Trigger: roadmap changed

Locate the roadmap section. Apply one of:

• Item completed → remove it from the roadmap (it is now documented under the main sections)
• New item added → append a bullet with the same style as existing entries
• Item rephrased → edit in place

Style rules

• All text in English
• Backticks for all type names, method names, and code references inline
• Fenced code blocks for all code examples
• Tables use the compact |---|---| separator style
• No trailing whitespace
• Preserve all existing section order and heading levels exactly

Before presenting the result

Show the user a summary of what was changed:

• Which sections were added
• Which sections were modified
• Which sections were left untouched

Then present the updated content for review. Do not instruct the user to merge blindly — flag anything uncertain for their decision.