docs: rewrite README for humans and coding agents (COR-13588) - #11
Open
Bradenream wants to merge 3 commits into
Open
docs: rewrite README for humans and coding agents (COR-13588)#11Bradenream wants to merge 3 commits into
Bradenream wants to merge 3 commits into
Conversation
- Positioning header: what vf is and the surface it covers, replacing the internal 'Realtime API' framing; license badge tracks the Apache-2.0 decision - Remove the pre-publish 'not ready for production' banner - npm install (npx @voiceflow/cli) as the recommended install path - Add an agent-executable quickstart: zero to a talking agent in four commands, runnable end to end with only VF_TOKEN set, plus the traps that break scripts (draft vs published, TOON default in agent mode, --jq quoting, whoami being offline, vf docs for in-band lookup) All edits are in hand-owned README space (outside Speakeasy's marker pairs), so they persist across regenerations.
There was a problem hiding this comment.
Pull request overview
Updates the repository’s README to better explain what vf is, how to install it (including npm), and how to get from zero to a working conversation flow via a scriptable quickstart.
Changes:
- Repositions the README header/intro and updates the license badge to Apache-2.0.
- Adds npm-based installation instructions (
npx @voiceflow/cli,npm install -g). - Adds an “agent-executable” quickstart section plus scripting gotchas.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Restore the '# vf' H1: retitling it broke the generated table of contents' first anchor (#vf), which the TOC block still points at. The descriptive positioning moves to the line below, where it reads better anyway. - Match PR #4's license-badge href exactly (opensource.org/license/..., the canonical 200; /licenses/ 301-redirects) so the two PRs cannot disagree about the final text. - Drop '(recommended)' from the npm install heading — it is not a superlative worth making while the package is not yet published; the section is honest about what it does either way.
Bradenream
changed the title
…ency Copilot review, both real gaps for the audience this README targets: - 'npx @voiceflow/cli' prompts 'Ok to proceed?' when a TTY is present and the package is not already cached, which stalls exactly the unattended agent run the quickstart exists to serve. Use 'npx -y'. - The quickstart claimed it needed nothing but an access token while its commands pipe through jq to capture IDs. Name the dependency.
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.
Part of COR-13588 — shipping the vf CLI as an agent-era distribution channel.
What
vfis and the surface it covers, replacing the internal 'Realtime API' framing; license badge tracks the Apache-2.0 decision (chore: add Apache-2.0 LICENSE (COR-13588) #4)npx @voiceflow/cli) as the recommended install path (feat: publish the CLI to npm as @voiceflow/cli (COR-13588) #8)VF_TOKENset — the sequence the repo's own e2e suite exercises — plus the traps that break scripts (draft vs published, fresh projects'mainalias, TOON default in agent mode,--jqquoting,whoamibeing offline,vf docsfor in-band lookup)All edits are in hand-owned README space (outside Speakeasy's marker pairs), so they persist across regenerations. Base branch: #7.
Sequencing
Suggest merging last in the wave, after #4 (LICENSE — the badge), #8 (npm — the install path), and #10 (
vf docs— referenced in the quickstart notes), so the README only documents shipped behavior. A live unattended-agent validation run of the quickstart is queued (needs a vfp_ token) before this merges.