docs(readme): introduce Entity.aggregate, and fix stale schema and flag lines

[btravers]

Summary

• Both READMEs (root and packages/entity, which is what npm shows) gain an Aggregates section: a short Subscription showing no update(), emit returning a sealed decision (events, expectedVersion), and save(decision) for state or event persistence. It links the how-to and says when to use Entity instead.
• Entity(...) stays the hero example: an aggregate is built on it, and most models are entities.
• Stale lines fixed: updateInput is derived from input (No wire projection: nested entities break z.toJSONSchema, and undefined/null is bridged by hand at every boundary #72), output is something you pick a response from by allowlist (Teach explicit public contracts instead of treating stored state as the default response body #138), and the flag lists gain identity (Identity comparison alongside structural equals() #38) and unbranded (Branding requirement taxes leaf values, and the brands leak into consumers #73).
• The how-to lists in both READMEs link "Model an event-driven aggregate".

No code change. No changeset.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 14 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: btravstack/entity/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: d1fa98a8-d07a-4084-b685-466bb1676ab1

📥 Commits

Reviewing files that changed from the base of the PR and between 7eb045c and 6065aeb.

📒 Files selected for processing (2)

• README.md
• packages/entity/README.md

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot review overview

🟢 Approval recommended

It is a documentation-only change whose every claim and code example I verified as accurate and consistent against the current source.

Review effort: Balanced
Findings: None

What changed in this PR

This documentation-only PR adds an Aggregates section to both the root README.md and packages/entity/README.md (the npm-facing one), introducing Entity.aggregate with a Subscription example that shows the two-call declaration form, emit returning a sealed decision (events, expectedVersion), and persistence via save(decision). It also corrects stale lines in the schema-member and field-flag tables so they match the current API.

I verified the technical content against the source:

• The aggregate example matches aggregate.ts (two-call form, events/opens/evolve, emit/start/replay, make(row, { version }), decision.events/decision.expectedVersion), and the unbranded status: z.enum(...) field legitimately passes the OnlyNominal check (shape.ts).
• updateInput is indeed derived from input minus immutable keys (entity.ts:144-147), so the output → input correction is accurate.
• The new identity and unbranded flags exist and the descriptions are correct — identity implies immutable (field.ts:96).
• The linked how-to/model-an-event-driven-aggregate page exists, and the two READMEs are mutually consistent.

Changes:

• Added an Aggregates section (identical prose in both READMEs) documenting Entity.aggregate, decisions, and state-vs-event persistence.
• Fixed stale schema-member lines: output is "pick a response by allowlist" and updateInput derives from input (not output).
• Extended the field-flag documentation with identity and unbranded, and added the "model an event-driven aggregate" how-to link.

File	Description
README.md	Adds Aggregates section, corrects output/updateInput table rows, adds identity/unbranded flag rows, and links the new how-to.
packages/​entity/​README.md	Mirrors the same Aggregates section, updateInput-from-input fix, flag-list prose update, and how-to link for the npm-visible README.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.