docs: fix README inaccuracies#67
Merged
Merged
Conversation
Several issues found while auditing every code/CLI example for
correctness against tip-of-main:
1. SDK quickstart was fictional — referenced non-existent
symbols (agent.Card, agent.Card.System, llm.Register,
model.UserText, Message.Text, runner.New() with no args).
Replaced with pointers to real, compilable examples in
sdk/agent/run_test.go, tests/quality/vessel/, and
examples/voice-pipeline/setup.go. The library path needs a
graph DAG + node.Factory + LLM resolver — too much for an
inline 20-line snippet without misleading readers.
2. CLI subcommand was wrong: vesseld uses `run`, not `start`.
Fixed in both README.md and examples/vesseld-multi-vessel/
README.md.
3. Voice example used voice.Config{...} which doesn't exist;
the real signature is positional (NewPipeline(stt, tts,
eng, ag, opts...)). Replaced with the real wiring shape.
4. HTTP curl examples used /tmp/vesseld.sock as the unix
socket path, but examples/vesseld-multi-vessel/daemon.yaml
declares /tmp/vesseld-multi-vessel.sock. Captured the path
in a SOCK shell var so the discrepancy is visible.
5. Architecture diagram had sdk/ in the middle and sdkx/ at
the bottom — but sdkx imports sdk, vessel imports sdk,
voice imports sdk; sdk is the foundation. Redrawn with
sdk at the bottom and sdkx/vessel/voice as siblings on
top of it. vesseld composes vessel + sdkx (single arrow
captures the actual dep direction).
6. Recall feature claim "Pluggable persistence (in-memory,
SQLite, Postgres + pgvector)" overstated the in-tree
coverage — the in-tree backend is in-memory only; SQLite
is used for the recall job queue, not the index. Reworded
to "Pluggable retrieval.Index backend; in-tree
implementation is in-memory."
7. "Combined via Reciprocal Rank Fusion" overstated the
algorithm — the merger uses entity-boost + TTL filtering,
not RRF. Reworded.
Co-authored-by: Cursor <cursoragent@cursor.com>
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
1 participant
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
Audit-driven fixes to `README.md` (and the matching `examples/vesseld-multi-vessel/README.md`). Every code snippet, CLI invocation, and HTTP example was verified against tip-of-main. Seven issues found, listed in commit message; highlights:
Test plan
Made with Cursor