Refresh README and docs homepage pitch#114
Merged
Merged
Conversation
Replace the README's 10-bullet "Why OpenArmature" feature inventory with 5 differentiating reasons-to-choose, ordered for an engineer or architect evaluating OA against alternatives: 1. Workflows to agents, one engine (LLM-infused pipelines first; agents and deterministic ETL as the spectrum endpoints). 2. Crash-safe resume by spec contract (built for preemptible compute and queue workers, not just human-in-the-loop interrupts). 3. Destination-pluggable observability (native OTel for vendor neutrality, separate native LangfuseObserver for teams on Langfuse, no SaaS lock-in to a framework-vendor-owned product). 4. Bad graphs don't compile (.compile rejects six categories of structural error before invoke is reachable). 5. Spec, not just code (public language-agnostic spec with conformance fixtures bounding the future surprise space). Match the same positioning on docs/index.md's homepage card grid. Swap the six feature-inventory cards (typed-state, compile-time, observable, checkpointable, fan-out, async/LLM-agnostic) for six reason-to-choose cards mirroring the README order, with a sixth card capturing parallelism (fan-out + parallel-branches + nested attribution correctness, formalized) that's genuinely differentiated against LangGraph's Send-based primitive. Existing card icons retained. "Open specification" section stays at the bottom of the homepage.
There was a problem hiding this comment.
Pull request overview
Refreshes the project’s “why” narrative so the README and docs homepage present a concise, evaluation-oriented pitch (reasons-to-choose) instead of a longer feature inventory.
Changes:
- Rewrites
README.md“Why OpenArmature” into 5 differentiating reasons and adds a pointer to the full concepts catalog. - Updates
docs/index.mdhomepage card grid copy to align with the new reasons-to-choose framing. - Records the docs/README refresh in
CHANGELOG.md.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| README.md | Replaces the prior feature-inventory “Why” section with a 5-point reasons-to-choose pitch. |
| docs/index.md | Updates the homepage card grid to mirror the new positioning and ordering. |
| CHANGELOG.md | Adds an Unreleased entry describing the README + homepage refresh. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Three CoPilot findings on PR #114: 1. docs/index.md card 5 used "sub-graphs"; the canonical spelling across both code and docs is "subgraphs" (no hyphen). Normalized. 2. docs/index.md card 4 and README.md card 4 both claimed .compile() rejects "undeclared subgraph fields". The actual error (MappingReferencesUndeclaredField) fires for both side='parent' AND side='subgraph' across the fan_out.{items_field, target_field, collect_field, inputs, extra_outputs} checks; the previous wording was too narrow. Reworded to "mappings to undeclared state fields" so both surfaces match each other and the actual error shape. 3. CHANGELOG bullet framed the change as "around 5 reasons-to-choose" then enumerated 6 homepage cards. Reworded the bullet to acknowledge both counts (5 in README; 5 + retained async-first card on the homepage = 6).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fourth of five docs-polish items. Realigns README + docs homepage around 5 reasons-to-choose, ordered for an engineer or architect evaluating OA against alternatives.
README swaps the 10-bullet "Why OpenArmature" feature inventory for 5 differentiating reasons:
OTelObserverfor OTLP-compatible backends (Honeycomb, HyperDX, Phoenix, Datadog APM, Tempo, etc.). SeparateLangfuseObserverfor the Langfuse destination, MIT-licensed and decoupled through a Protocol so the swap cost is one file. No coupling to a framework-vendor-owned closed-source product..compile()rejects six categories of structural error beforeinvoke()is reachable.Docs homepage (
docs/index.md) card grid swaps the six feature-inventory cards for six reason-to-choose cards mirroring the README order:Card 5 captures parallelism specifically because the combination (distinct fan-out + parallel-branches primitives, bounded concurrency, per-instance error policy, attribution-correct observability when nested) IS differentiated against LangGraph's Send-based primitive that conflates the two concepts. Spec/conformance stays in the "Open specification" section at the bottom of the homepage.
Existing card icons retained.
Test plan
mkdocs serveand confirm the homepage card grid renders correctly with the new copyOut of scope