docs: full reposition — peer thesis, deadpan voice, truth-up the status#47
Merged
Conversation
Reframe the user-facing docs around the real thesis: a human's TUI and an agent's API are peer consumers of the same terminal, by design. Lead with the payoff, not the mechanism (libghostty moves to an aside); undersell on purpose; hold competitor shots until there's proof. - README: new hook, demo placeholder front-and-center, headless/agent surface above the fold, honest stable/moving/not-yet split. - docs/INSTALL.md (new): honest install ergonomics — brew + source, no cargo-install (binary unpublished), platform matrix. - CONCEPTS: peer thesis in the TL;DR; fix stale "agent SDK planned" to reflect the shipped CLI + phux-mcp surface vs the still-future crate. - vision: lighter framing; same agent-surface truth-up. - docs/README.md: real front door (read-order + pick-a-lane) over a bare index; add INSTALL/agents/mcp/web. - QUICKSTART: correct the stale "only phux + phux server ship" — the headless verbs and MCP adapter are real now. just docs-check green (76 files, 0 violations). All links verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Docs PR opened: phall1/mintlify-docs#6 Updated the phux Mintlify quickstart and introduction to document the shipped headless CLI verbs, phux-mcp adapter, and Homebrew install. |
The demo is the highest-leverage missing asset; give it a turnkey recipe instead of a bare TODO. docs/demo.md is the two-beat storyboard (content survives reattach; same thing driven headless), the reproducible payload, recording tools, and where the GIF lands. README placeholder now points at it. Also drop the imprecise "same six verbs" line (MCP tools and the CLI block don't line up one-to-one). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ax until it exists The CI dead-link checker resolves relative links inside comments and code fences too, so the placeholder image markdown pointed at a file that won't exist until the GIF is recorded. Reference the path as prose instead. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.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.
What
The "full send" pass on the user-facing docs. Reframes everything around the real thesis — a human's TUI and an agent's API are peer consumers of the same terminal, by design — in a deliberately deadpan, under-sold voice. Leads with the payoff, demotes the mechanism, holds competitor shots until there's proof.
Also a truth-up: several docs claimed the agent surface was "planned." It ships (headless CLI verbs +
phux-mcp). Fixed everywhere it was stale.Files
cargo install(the binary isn't published), platform-support matrix.phux+phux servership"; the headless verbs and MCP adapter are real now, with runnable examples.Checks
just docs-checkgreen (76 files, 0 violations).phux-mcpis a real[[bin]],phux ls --json/phux runexit-code passthrough confirmed incrates/phux/src/main.rs.Still open (not in this PR)
🤖 Generated with Claude Code