Skip to content

docs: reposition README + tighten CONCEPTS for the audience#46

Merged
phall1 merged 3 commits into
mainfrom
docs-tighten
Jun 3, 2026
Merged

docs: reposition README + tighten CONCEPTS for the audience#46
phall1 merged 3 commits into
mainfrom
docs-tighten

Conversation

@phall1
Copy link
Copy Markdown
Owner

@phall1 phall1 commented Jun 3, 2026

What

Two tightening commits (already on the branch) plus a README reposition aimed at the actual audience: senior engineers, AI-slop-saturated, deciding in 60 seconds.

README rewrite

  • Thesis-first hook. Leads with the knife — the same VT parser runs on both ends, so modern protocols survive a remote attach tmux would smear; and the addressable unit is the terminal, not the session — instead of the implementation ("a libghostty-backed control plane").
  • Agent/headless surface above the fold. send-keys / run / wait / watch + phux-mcp ship and are tested. The old README buried them under three tiers of "roadmapped." They're the story for this audience.
  • Honest status. Replaced roadmap-as-features (the docs(adr-0018): revise state-sync implementation gate — RenderState is the cache primitive #1 vaporware tell) with a blunt split: stable / shipped-but-API-moving / not-yet. Federation correctly scoped to "addressing in the wire, routing not yet."
  • Crates table updated for phux-client-core (compiler-enforced ratatui boundary) and phux-mcp.
  • Demo placeholder left as an HTML comment — a ~10s cast of kitty graphics surviving detach/reattach is the highest-leverage missing asset.

CONCEPTS tighten (pre-existing branch commits)

  • Killed the Philosophy preamble, the Hashimoto quote, the "When to use phux" section; reframed "unit of work" as "Terminals, not panes"; tightened the comparison table.

Notes

  • just docs-check green (75 files, 0 violations).
  • Rebased clean on current main (was 29 behind; README/CONCEPTS untouched upstream).
  • No demo asset committed yet — placeholder comment marks where it goes.

🤖 Generated with Claude Code

phall1 and others added 3 commits June 3, 2026 01:54
…phux' section, reframe 'unit of work' to 'Terminals, not panes'
Lead with the knife (same VT parser both ends; the terminal, not the
session, is the addressable unit) instead of the implementation. Surface
the headless/agent CLI + phux-mcp above the fold — it ships, the old
README buried it as "roadmapped". Replace the roadmap-as-features Status
section with an honest stable / shipped-but-moving / not-yet split.
Update Crates table for phux-client-core + phux-mcp.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@phall1 phall1 merged commit 18320c3 into main Jun 3, 2026
5 of 6 checks passed
@phall1 phall1 deleted the docs-tighten branch June 3, 2026 06:22
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