From db21ec94d0f92ca466bd59b46ddf6b3bf559bd84 Mon Sep 17 00:00:00 2001
From: Abdullah Sultan <abdullahmsultan1@gmail.com>
Date: Thu, 6 Aug 2026 16:33:22 -0500
Subject: [PATCH] dfdf

---
 BRIEF.md  | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  98 ++++++++++++++++++++++------------------
 2 files changed, 187 insertions(+), 43 deletions(-)
 create mode 100644 BRIEF.md

diff --git a/BRIEF.md b/BRIEF.md
new file mode 100644
index 0000000..d82c050
--- /dev/null
+++ b/BRIEF.md
@@ -0,0 +1,132 @@
+# Workstream A — README marketing restructure
+
+Repo: crosscode (pnpm monorepo). You are a copy/structure pass on ONE file. No code changes.
+
+## Files (the only files you may read or edit)
+
+- `README.md` — the only file you edit.
+- You may read (do not edit): `apps/docs-site/index.html` (for the accurate "Works with"
+  agent list, which is a `<ul class="chips">` around line 203), `docs/privacy.md`,
+  `PLAN.md`. Nothing else. Do not run repo-wide greps.
+
+## Goal
+
+Make the first screen of the README sell the product, without changing a single factual
+claim. Everything already in the README is accurate — this is reordering and tightening,
+not new claims.
+
+## Required changes to README.md
+
+1. **Top of file, in this order:**
+   - Logo + `Crosscode` h1 (keep as-is).
+   - Badge row. Keep the existing npm version, CI, stars, MIT, and Node 24 badges, and
+     ADD a shields.io weekly-downloads badge for the real package:
+     `https://img.shields.io/npm/dw/crosscode-cli?style=flat&color=08C&label=downloads`
+     linked to `https://www.npmjs.com/package/crosscode-cli`. Match the existing
+     `style=flat&color=08C` look. The MIT badge must link to `./LICENSE` (currently it is
+     an unlinked img — make it a link, keep the same shields.io URL).
+   - The one-line value prop as the headline sentence, in the spirit of:
+     "Real-time codebase sync between teammates and coding agents, so nobody overwrites
+     anyone else's work." Keep the existing follow-on sentences ("You edit a file, their
+     checkout updates within seconds..."). Do not overclaim beyond what the current text
+     says.
+   - **A demo GIF placeholder.** No GIF exists in this repo. Do NOT invent one, do not
+     reference a file that isn't there, and do not describe a recording as if it exists.
+     Insert an HTML comment placeholder, clearly marked, e.g.:
+     ```html
+     <!-- TODO(abdullah): record a ~10s screen capture of a sync landing in a second
+          checkout (edit on the left, file updating on the right), save it as
+          assets/demo.gif, and replace this comment with:
+          <p align="center"><img src="assets/demo.gif" alt="A file edit in one checkout appearing in another within seconds" width="720" /></p>
+     -->
+     ```
+     Nothing rendered should imply a GIF is present.
+   - The one-command install immediately under that placeholder — a fenced bash block with
+     exactly `npm install -g crosscode-cli` as the first line. It is fine that the fuller
+     Quickstart block later also contains it; the top one is the hook.
+   - The "Works with the agent you already run" section, moved up here (currently at
+     line ~197). Use the accurate list from the site's chips: Claude Code, Codex CLI,
+     OpenCode, Cursor, Gemini CLI, VS Code, Amp, Cline, Zed, Windsurf, + any MCP client.
+     Verify against `apps/docs-site/index.html` and match it exactly.
+
+2. **Keep the `> [!IMPORTANT]` disclosure block** (no end-to-end encryption, the service
+   can read your files, PLAN.md status) — but move it BELOW the first screen, i.e. after
+   the install + Works-with block, rather than deleting or softening it. Not one word of
+   it may be weakened. It must still be prominent (keep the `[!IMPORTANT]` callout
+   styling), just not the first thing above the fold.
+
+3. **Reorder the body** so it reads top-to-bottom as:
+   1. What it does — `How it works`, `Features`
+   2. How to install it — `Quickstart`
+   3. Why it's safe to trust — `What syncs, and what never does`, `The apply rule`
+      (which contains the rules-it-won't-break list), `Pricing`
+   4. Deeper detail for the curious — `What your agent sees`, `What Crosscode is not`,
+      `Developing`, `Community and support`, `License`, `Trademark`
+
+   Move whole sections. Do not rewrite section bodies except for minimal transition
+   fixes (e.g. a heading rename, or a sentence that now points backwards instead of
+   forwards). Every honest disclosure stays verbatim: the no-end-to-end-encryption
+   sentences, what the service stores, the free-no-paid-plans pricing status, and the
+   "What Crosscode is not" section.
+
+## Out of scope — do not touch
+
+- Any file other than `README.md`.
+- Anything about GitHub OAuth, sign-in, device codes, Stripe, or billing. The sign-in
+  paragraph in Quickstart stays exactly as written.
+- No new features, metrics, user counts, star counts, testimonials, or benchmark claims.
+  If a number is not already in the file, do not add it.
+- Do not delete the CI badge, the stars badge, or any docs link.
+- Do not commit, push, merge, rebase, or open a PR. Leave changes uncommitted in your
+  worktree.
+
+## Verify (run these yourself)
+
+```bash
+# 1. The install command is in the first 60 lines, and no fake GIF is referenced.
+head -60 README.md
+grep -n 'demo.gif' README.md          # expect: only inside the TODO comment
+ls assets/ | grep -i gif || echo "no gif present (expected)"
+
+# 2. Every disclosure survived, byte-for-byte on the key phrases:
+grep -c 'no end-to-end encryption' README.md        # expect 2 or more
+grep -n 'The hosted service is free' README.md
+grep -n 'What Crosscode is not' README.md
+grep -n 'docs/privacy.md' README.md
+
+# 3. No links were dropped. Compare the set of link targets before and after:
+git stash && grep -o '](\./[^)]*)' README.md | sort -u > /tmp/cc-links-before.txt
+git stash pop && grep -o '](\./[^)]*)' README.md | sort -u > /tmp/cc-links-after.txt
+comm -23 /tmp/cc-links-before.txt /tmp/cc-links-after.txt   # expect: EMPTY output
+
+# 4. Badge URLs resolve (npm downloads badge is real):
+curl -sS -o /dev/null -w '%{http_code}\n' 'https://img.shields.io/npm/dw/crosscode-cli'
+# expect 200
+```
+
+Expected result: install command visible in the first screen, comm output empty, all
+disclosure greps hit, no GIF file referenced outside the TODO comment.
+
+## Done means
+
+All four verify steps produce the expected output, and `git status` shows `README.md` as
+the only modified file.
+
+## Report back
+
+The verify command output, `git diff --stat`, and anything you could not do.
+
+## Ground rules (non-negotiable)
+
+Read only what this brief lists. If you need a file outside that list, stop and say so
+rather than exploring. Do not run repo-wide greps. Do not spawn subagents. Do not merge,
+rebase, commit, push, or touch any branch but your own. Leave your work uncommitted.
+
+This `BRIEF.md` file itself is untracked scaffolding — ignore it in your file-count check
+and do not commit or delete it.
+
+Any web/browser work uses Orca's browser (`orca tab create` / `goto` / `screenshot` /
+`eval`), never claude-in-chrome and never `browse`.
+
+Report at the end: your verify command output, `git diff --stat`, and anything you could
+not do or chose not to do.
diff --git a/README.md b/README.md
index c3b2611..df15f55 100644
--- a/README.md
+++ b/README.md
@@ -4,14 +4,16 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/crosscode-cli"><img src="https://img.shields.io/npm/v/crosscode-cli?style=flat&color=08C&label=npm" alt="crosscode-cli on npm" /></a>
+  <a href="https://www.npmjs.com/package/crosscode-cli"><img src="https://img.shields.io/npm/dw/crosscode-cli?style=flat&color=08C&label=downloads" alt="crosscode-cli weekly downloads" /></a>
   <a href="https://github.com/amsultan2010/crosscode/actions/workflows/ci.yml"><img src="https://github.com/amsultan2010/crosscode/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <a href="https://github.com/amsultan2010/crosscode"><img src="https://img.shields.io/github/stars/amsultan2010/crosscode?style=flat&label=%E2%98%85&color=08C" alt="GitHub stars" /></a>
-  <img src="https://img.shields.io/badge/license-MIT-08C?style=flat" alt="License: MIT" />
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-08C?style=flat" alt="License: MIT" /></a>
   <img src="https://img.shields.io/badge/node-24%2B-4493F8?style=flat" alt="Requires Node 24 or newer" />
 </p>
 
 <p align="center">
-  <strong>Real-time codebase sync between teammates.</strong><br/>
+  <strong>Real-time codebase sync between teammates and coding agents, so nobody overwrites
+  anyone else's work.</strong><br/>
   You edit a file, their checkout updates within seconds. They edit, yours does.
   Nobody presses anything and nobody watches anything.
 </p>
@@ -20,6 +22,32 @@
   <sub>Node 24 and a Git checkout. Nothing to deploy.</sub>
 </p>
 
+<!-- TODO(abdullah): record a ~10s screen capture of a sync landing in a second
+     checkout (edit on the left, file updating on the right), save it as
+     assets/demo.gif, and replace this comment with:
+     <p align="center"><img src="assets/demo.gif" alt="A file edit in one checkout appearing in another within seconds" width="720" /></p>
+-->
+
+```bash
+npm install -g crosscode-cli
+```
+
+## Works with the agent you already run
+
+<p>
+  <kbd>Claude Code</kbd> &nbsp;
+  <kbd>Codex CLI</kbd> &nbsp;
+  <kbd>OpenCode</kbd> &nbsp;
+  <kbd>Cursor</kbd> &nbsp;
+  <kbd>Gemini CLI</kbd> &nbsp;
+  <kbd>VS Code</kbd> &nbsp;
+  <kbd>Amp</kbd> &nbsp;
+  <kbd>Cline</kbd> &nbsp;
+  <kbd>Zed</kbd> &nbsp;
+  <kbd>Windsurf</kbd> &nbsp;
+  <kbd>+ any MCP client</kbd>
+</p>
+
 > [!IMPORTANT]
 > [`crosscode-cli`](https://www.npmjs.com/package/crosscode-cli) installs from npm, and the
 > sync engine underneath it (the shadow ref, the
@@ -194,38 +222,16 @@ Cursor, or any MCP-capable agent, and it runs the same commands and wires up the
 itself. Codex CLI's config is TOML and `start` does not write it, so Codex users add a
 three-line entry by hand. See [MCP client setup](./docs/mcp-clients.md).
 
-## Works with the agent you already run
-
-<p>
-  <kbd>Claude Code</kbd> &nbsp;
-  <kbd>Codex CLI</kbd> &nbsp;
-  <kbd>OpenCode</kbd> &nbsp;
-  <kbd>Cursor</kbd> &nbsp;
-  <kbd>Gemini CLI</kbd> &nbsp;
-  <kbd>VS Code</kbd> &nbsp;
-  <kbd>Amp</kbd> &nbsp;
-  <kbd>Cline</kbd> &nbsp;
-  <kbd>Zed</kbd> &nbsp;
-  <kbd>Windsurf</kbd> &nbsp;
-  <kbd>+ any MCP client</kbd>
-</p>
-
-## What your agent sees
-
-Four MCP tools, `status`, `conflicts`, `resolve`, and `pause`, plus one skill that says how
-to use them and, mostly, when to leave them alone.
+## What syncs, and what never does
 
-Every response from every tool carries any pending conflicts, whether the tool was asked for
-them or not. That is deliberate. An agent only looks at anything when it is invoked, so a
-conflict that arrives while it is idle would otherwise sit unseen. This way it trips over
-one the next time it does anything at all. Claude Code and Codex additionally get a hook
-that runs before a file edit, which moves that moment earlier still: a conflict on a file
-is known before the agent writes over it rather than after. The hook is a bonus on top of
-MCP, not a requirement, and every other client relies on the piggybacked conflicts alone.
+Tracked files only, plus a hard denylist. Your commits, branches, index, stash, and remotes
+are never touched, and nothing Crosscode does pushes to a remote. If you stop Crosscode or
+remove it, your repository is an ordinary Git repository, exactly as it was.
 
-The bar this is built to: **neither side's agent mentions Crosscode until a real conflict**,
-which the receiving agent then resolves without being asked. See
-[`skills/crosscode/SKILL.md`](./skills/crosscode/SKILL.md) for what the agent is told.
+Your files do pass through the hosted coordination service, and there is no end-to-end
+encryption, so we can read them. [docs/privacy.md](./docs/privacy.md) lists exactly what the
+service stores and for how long, and [docs/security.md](./docs/security.md) has the threat
+model.
 
 ## The apply rule
 
@@ -254,22 +260,28 @@ Rules that keep it invisible:
 
 More in [architecture](./docs/architecture.md) and [protocol](./docs/protocol.md).
 
-## What syncs, and what never does
-
-Tracked files only, plus a hard denylist. Your commits, branches, index, stash, and remotes
-are never touched, and nothing Crosscode does pushes to a remote. If you stop Crosscode or
-remove it, your repository is an ordinary Git repository, exactly as it was.
-
-Your files do pass through the hosted coordination service, and there is no end-to-end
-encryption, so we can read them. [docs/privacy.md](./docs/privacy.md) lists exactly what the
-service stores and for how long, and [docs/security.md](./docs/security.md) has the threat
-model.
-
 ## Pricing
 
 The hosted service is free. There are no paid plans, no seats, and no payment details
 collected. See [docs/terms.md](./docs/terms.md).
 
+## What your agent sees
+
+Four MCP tools, `status`, `conflicts`, `resolve`, and `pause`, plus one skill that says how
+to use them and, mostly, when to leave them alone.
+
+Every response from every tool carries any pending conflicts, whether the tool was asked for
+them or not. That is deliberate. An agent only looks at anything when it is invoked, so a
+conflict that arrives while it is idle would otherwise sit unseen. This way it trips over
+one the next time it does anything at all. Claude Code and Codex additionally get a hook
+that runs before a file edit, which moves that moment earlier still: a conflict on a file
+is known before the agent writes over it rather than after. The hook is a bonus on top of
+MCP, not a requirement, and every other client relies on the piggybacked conflicts alone.
+
+The bar this is built to: **neither side's agent mentions Crosscode until a real conflict**,
+which the receiving agent then resolves without being asked. See
+[`skills/crosscode/SKILL.md`](./skills/crosscode/SKILL.md) for what the agent is told.
+
 ## What Crosscode is not
 
 No accept-or-reject step on incoming work, no tasks, claims, or handoffs, no hidden snapshot