Skip to content

docs(readme): refresh as a landing page#596

Merged
tlongwell-block merged 7 commits into
mainfrom
readme-refresh
May 17, 2026
Merged

docs(readme): refresh as a landing page#596
tlongwell-block merged 7 commits into
mainfrom
readme-refresh

Conversation

@tlongwell-block
Copy link
Copy Markdown
Collaborator

@tlongwell-block tlongwell-block commented May 15, 2026

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

  • Vision-first hero: Sprout 🌱 headline, top-of-page nav, hero media slot (placeholder until a demo clip is captured).
  • "What is this, really?" opens on the human↔agent shared-rooms thesis, then names what agents can actually do once they're inside: open repos, send patches, review code, run workflows, edit canvases, orchestrate other agents, drop into voice huddles, create channels, and pull in whoever needs to see it. Same affordances as a human teammate, same audit trail, a different keypair.
  • "What Sprout is trying to make normal" — five concrete bullets (ask the project a question, triage a bug, branch-as-room, unified search, agents running the workspace).
  • "The weirdly powerful thing" — names the categories Sprout absorbs (chat, forges, bots, CI dashboards, release tools, search indexes) rather than the brands, so it reads as thesis rather than category fight.
  • Three little stories — incident memory, branch as room (now with an agent running first-pass review and the merge decision landing in the same room as the evidence), a release that writes itself.
  • Status table split into Works today / Being wired up / Strong opinions, pending code — Plausible-style honesty.
  • Two-phase quick start (Once / Every day) with a single hermit-activated path and an agent pointer to sprout-cli — JSON in, JSON out, designed for LLM tool calls.
  • Architecture diagram (lightly updated) and a <details>-wrapped crate map covering the current workspace including sprout-cli, sprout-acp, sprout-agent, sprout-dev-mcp, sprout-persona, sprout-pair-relay, sprout-pairing-cli, git-sign-nostr, and git-credential-nostr.
  • "What it is not" — three lines (not blockchain, not an AI replacement plan, not finished). Closer states the ambition explicitly: "the beginning of a workspace that can grow past the tabs it replaces."

Honesty pass

  • Git events (NIP-34: patches, repo announcements, status) are in the ✅ column — they ship today. Git hosting backend is the only git item still 🚧.
  • Mobile clients (Flutter, iOS + Android) are in the 🚧 column — the app exists, the relay wiring is in progress.
  • sprout-cli is the headline agent surface; sprout-mcp is kept in the crate map as legacy/optional.
  • No mention of 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.
  • Workflow approval gates: "infra exists, glue still drying" rather than a vague 🚧.

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.

@tlongwell-block tlongwell-block force-pushed the readme-refresh branch 2 times, most recently from 60fd95b to 9e7743a Compare May 16, 2026 23:05
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>
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>
@tlongwell-block tlongwell-block merged commit edcef51 into main May 17, 2026
15 checks passed
@tlongwell-block tlongwell-block deleted the readme-refresh branch May 17, 2026 00:04
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