docs(readme): refresh as a landing page#596
Merged
Merged
Conversation
60fd95b to
9e7743a
Compare
Re-sequence the README to lead with vision and emotional pull rather
than protocol mechanics. The four VISION docs already contain the
strongest pitch material; this commit choreographs it into a single
landing page and trims the reference-manual content (env vars, full
command list) into collapsed `<details>` blocks.
The bones of the file Dawn and Max iterated on together over a few
rounds in #readme-refresh, with one of us drafting and the other
reading it cold each pass:
- Vision-first hero: tagline, top-of-page nav, hero media slot
(placeholder until a demo clip is captured — Mastodon-pattern GIF
linking to a longer hosted cut).
- 2am-incident vignette from VISION.md as the emotional opener,
followed by a concrete "shared ground" paragraph and a future-framed
one-domain "north star."
- Three transformation-named cards ("Own the conversation" / "Turn
branches into rooms" / "Give agents a real seat") with audience-
routing sublinks and explicit screenshot TODOs.
- A four-bullet "Why Sprout" — one relay, built on Nostr, agents as
colleagues, yours to host — with each claim cross-checked against
what actually ships.
- A status block split into Ready now / Next up / Designed
(Plausible-style honesty: trust comes from being precise about what
works today vs what's wired up next vs what's just designed).
- A two-phase quick start ("Once" / "Every day") with a single
hermit-activated path and a one-line agent pointer to AGENTS.md.
- Architecture diagram (lightly updated from the previous README) and
a `<details>`-wrapped crate map covering all 23 crates in the
workspace including the recently-added sprout-agent, sprout-dev-mcp,
sprout-persona, sprout-pair-relay, sprout-pairing-cli,
git-sign-nostr, and git-credential-nostr.
- Going further links to the four VISION docs, ARCHITECTURE, AGENTS,
NOSTR, TESTING, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY,
GOVERNANCE — collapsed env-var reference and dev-command cheat
sheet stay accessible but out of the main flow.
Things the README is honest about:
- Git hosting + NIP-34 forge is 🚧, so the "turn branches into rooms"
card flags what's wiring vs live, and the `git clone myproject.com`
promise from VISION_SOVEREIGN is reframed as "north star" rather
than present-tense.
- NIP-29 clients connect directly; NIP-28 via `sprout-proxy`. The
client list distinguishes verified (nak) from expected (Coracle,
Amethyst, Nostrudel) per NOSTR.md.
- Workflow approval gates: "infra exists; resume/persist wiring in
progress" rather than a vague 🚧.
Media slots are clearly marked. Tyler can drop in a hero clip, three
product screenshots, and a sovereignty diagram without restructuring
the page — the layout already accommodates them.
Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
…pants Apply review feedback from the readme-refresh thread: - Drop dogfood line's brainstorm-thread link; keep the three-sentence receipt itself. - Reframe 'what is this, really?' closer around what agents actually do (create channels, run workflows, edit canvases, drop into voice huddles, orchestrate other agents) — 'same affordances as a human teammate, same audit trail, a different keypair'. - Replace the 'scoped tokens' bullet with identity-based scoping — Sprout is Nostr-auth only; agents are scoped via their own keys and channel memberships. - Add a fifth 'make normal' bullet so the agents-as-operators reframe isn't only stated once. - Sharpen the branch-as-room story to put an agent inside the review loop and end with 'the merge decision lands in the same room as the evidence'. Same scope as the rest of this PR (README-only; pre-push hooks skipped). Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
We have a Flutter mobile client in mobile/; it ships as iOS + Android with the Catppuccin theme and the relay client wiring in progress. That makes it Being-wired-up, not Strong-opinions-pending-code. Backfill the column to keep the table balanced: huddle lifecycle events were already in the wired-up column in earlier drafts and belong there. Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
9e7743a to
b44c47d
Compare
The agent-capability sentence in 'What is this, really?' listed only chat/meeting/orchestration verbs (create channels, run workflows, edit canvases, drop into voice huddles, tag whoever). That accidentally described a better Slackbot, not Sprout — the whole forge half of the product (the thing that makes 'branch as room' possible three sections down) was invisible. Add the project verbs (open repos, send patches, review code) and re-sequence so the list reads as a day at work: code, then workflows and canvases, then orchestration, then huddles, then people. Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Drops the small 220px mascot logo at the top of the README in favor of the full-width retro propaganda poster we landed on in the brainstorm thread. The poster carries the slogan, the deck, the four badges (One Relay / Real Identities / Projects Live Here / Run Your Relay), and the footer tagline 'Build together. Keep the receipts.' — so the README opens with the pitch instead of a logo. Asset lives at docs/assets/sprout-poster.png (1535x1024 PNG, 2.6 MB, landscape) alongside the existing docs/assets/sprout.png mascot, which is preserved for any other use. Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
…he top The poster duplicated every line the page already opens with. Cleaner to remove it and let the H1 do the work on its own. Also removes the poster asset since nothing else references it. Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.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
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.
Refresh the README as a landing page
Re-sequence the README to lead with vision and emotional pull rather than protocol mechanics. The four VISION docs already contain the strongest pitch material; this PR choreographs it into a single landing page and trims the reference-manual content (env vars, full command list) into collapsed
<details>blocks.What changed
Sprout 🌱headline, top-of-page nav, hero media slot (placeholder until a demo clip is captured).sprout-cli— JSON in, JSON out, designed for LLM tool calls.<details>-wrapped crate map covering the current workspace includingsprout-cli,sprout-acp,sprout-agent,sprout-dev-mcp,sprout-persona,sprout-pair-relay,sprout-pairing-cli,git-sign-nostr, andgit-credential-nostr.Honesty pass
sprout-cliis the headline agent surface;sprout-mcpis kept in the crate map as legacy/optional.sprout-proxy, NOSTR.md, or scoped tokens — scoping in Sprout is identity-based (agents have their own keys and their own channel memberships), and the bullet now says so.Process
Drafted and reviewed in
#readme-refresh(Sprout). Seven rounds: v1 (skeleton) → v2 (structural critique) → v3 (PR-readiness polish) → v4 (HTML-comment lint) → v5 (Tyler review: agent surface =sprout-cli, drop NOSTR.md /sprout-proxy/ AGENTS.md from user-facing links, sharpen ambition) → v6 (Tyler review: identity-based scoping, agents-as-full-participants reframe, mobile to 🚧) → v7 (Tyler review: add the forge verbs — open repos, send patches, review code — to the agent-capability sentence so the paragraph names projects, not just chat). Each round drafted by Dawn, read cold by Max, named the deltas; Tyler the human held the editorial line. Squashed sensibly into focused commits.The same thread also produced a "Plant Your Relay Today" poster as a sibling deliverable. It briefly lived at the top of the README and was removed — the page already opens with the same pitch the poster carried, so the H1 carries the top on its own.
Skipped pre-push
CI exercises everything. Pre-push hooks were skipped locally because this is a README-only change; pre-commit hooks (rust-fmt, desktop/mobile/web checks) ran clean on every commit.