Skip to content

docs(readme): Quick Start above the fold; add Glossary; pack repo link#15

Merged
anthroos merged 1 commit intomainfrom
docs/readme-quickstart-first
May 2, 2026
Merged

docs(readme): Quick Start above the fold; add Glossary; pack repo link#15
anthroos merged 1 commit intomainfrom
docs/readme-quickstart-first

Conversation

@anthroos
Copy link
Copy Markdown
Owner

@anthroos anthroos commented May 2, 2026

Why

UX audit findings on the engine README:

  1. Quick Start was section 4 of 15 — buried under "The Question", "What It Is Not", and "The Methodological Core". A new visitor had to read three philosophy sections before seeing git clone.
  2. Four overlapping terms used without definition — `trajectory`, `pack`, `skill`, `openexp-use`. Readers conflate them; the README never lays them out.
  3. No bridge from Quick Start to a working demo — after `./setup.sh` finishes, a fresh visitor doesn't know what to do next. The seed pack lives in its own repo now (after refactor: split packs out of engine repo (one repo per pack) #14) but the README didn't point to it.

What

  • Reorder: Quick Start moved directly after the hero. Order is now hero → Quick Start (with pointer to seed pack) → The Question → Glossary → What It Is Not → Methodology → How It Works → ...
  • Add Glossary section — four terms, one line each. Resolves the trajectory / pack / skill / openexp-use confusion.
  • Quick Start pointer to the seed pack — `exp-inbound-acquisition-with-free-pilot`. After setup.sh, fresh visitors have a concrete next step: install a real pack, try retrieval.

Diff

`README.md | 41 ++++++++++++++++++++++++++++--------------` — 27 insertions, 14 deletions, net +13.

Existing TOC anchors (`#quick-start`, `#how-it-works`, `#publishing-an-experience`) still resolve.

Test plan

  • Confirm Quick Start renders before the philosophy sections
  • Confirm seed-pack link in Quick Start opens `anthroos/exp-inbound-acquisition-with-free-pilot`
  • Confirm Glossary anchors are accessible via section heading

Earlier order was: hero → Question → What It Is Not → Methodological
Core → Quick Start. A new visitor had to scroll past three sections
of context before seeing how to install. Reorders to: hero → Quick
Start → Question → Glossary → What It Is Not → Methodology. Action
first, context for those who stay.

Adds a Glossary section because the docs use four terms for related
things (trajectory / pack / skill / openexp-use) and readers conflate
them. Three-line definition each.

Adds a pointer from Quick Start to the seed pack repo
(anthroos/exp-inbound-acquisition-with-free-pilot) so a fresh visitor
who finishes setup.sh has a clear next step: install a real pack and
try retrieval.
@anthroos anthroos merged commit e2f93e5 into main May 2, 2026
@anthroos anthroos deleted the docs/readme-quickstart-first branch May 2, 2026 04:40
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