redraft-local 1.1.1 → 1.2.0

package/README.md

@@ -20,6 +20,8 @@ ReDraft turns any Git repository into a review workspace for markdown documents.
 
 **Remote and local are the same UI.** Use [redraft-docs.dev](https://redraft-docs.dev) to review any GitHub repo in the browser, or run `npx redraft-local` to serve your local checkout. Local mode lets you edit with your own tools — your editor, your scripts, your AI agents — and see changes reflected live. ReDraft ships with [built-in skills](.agents/skills/redraft-review/) for walking comment threads, drafting replies, and revising documents, so agents work alongside human reviewers out of the box.
 
+**Documentation stays next to the code.** Docs live as plain `.md` files in the same repo as the code they describe — no wiki, no external platform, no sync to maintain. When code changes, the docs are right there to update in the same PR. ReDraft adds a review layer on top without moving anything out of your repository.
+
 ---
 
 ## Get started
@@ -28,21 +30,32 @@ ReDraft turns any Git repository into a review workspace for markdown documents.
 
 Visit [redraft-docs.dev](https://redraft-docs.dev), enter a fine-grained GitHub PAT (`Contents: Read/Write` + `Metadata: Read`), point it at any repo, and start reviewing. Nothing to install.
 
+> [!NOTE]
+> ReDraft currently uses a fine-grained PAT for GitHub access. Real GitHub OAuth is coming soon.
+
 ### Local (advanced)
 
 For power users and AI agents who want to work with local tools:
 
 ```bash
-npx redraft-local --open
+npx redraft-local
 ```
 
-Launches a local server and opens the browser automatically. Every `.md` file in your working directory is ready for review — no signup, no PAT, no config. Edit files in your own editor or with AI agents and see changes live in the browser.
+Launches a local server and opens the browser. Every `.md` file in your working directory is ready for review — no signup, no PAT, no config. Edit files in your own editor or with AI agents and see changes live in the browser.
 
 ---
 
 ## How it works
 
-ReDraft stores nothing outside your repository. Documents are plain `.md` files on any branch — pick the branch you want to review from the branch selector. Comment threads live as structured JSON on a dedicated sidecar branch (`redraft` by default) under `.redraft/comments/`. The sidecar branch never touches your working tree — no merge conflicts, no noise in diffs.
+ReDraft stores nothing outside your repository. Documents are plain `.md` files on any branch — pick the branch you want to review from the branch selector. Comment threads live as structured JSON on a dedicated sidecar branch (`redraft` by default) under `.redraft/comments/`. The sidecar branch never touches your working tree — no merge conflicts, no noise in diffs. In local mode the branch is created automatically when you first comment; for remote mode, create it once:
+
+```bash
+# one-time setup — create an empty orphan branch for comment storage
+bash scripts/create-sidecar-branch.sh   # or: npx redraft-local init (#41)
+git push origin redraft
+```
+
+See [`scripts/create-sidecar-branch.sh`](scripts/create-sidecar-branch.sh) for details.
 
 ```
 your-repo/
@@ -51,7 +64,7 @@ your-repo/
 │   ├── rfcs/rfc-001.md
 │   └── docs/architecture.md
 │
-└── redraft (sidecar branch — created automatically)
+└── redraft (sidecar branch)
     └── .redraft/comments/<document-branch>/
         ├── proposals/api-design.comments.json
         └── rfcs/rfc-001.comments.json
@@ -106,7 +119,7 @@ npx redraft-local serve [directory] [options]
 
   --port <number>           Port to listen on (default: 4200)
   --host <string>           Bind address (default: 127.0.0.1)
-  --open                    Open the browser automatically
+  --no-open                 Skip opening the browser on startup
   --sidecar-branch <string> Git branch for comments (default: redraft)
   --no-ui                   API-only mode, skip serving the frontend
 ```

package/dist-server/cli.mjs

@@ -1268,7 +1268,7 @@ async function runServe(directory = ".", options = {}) {
     runningServer.hub.broadcast(event);
   });
   console.log(`ReDraft local server listening at ${runningServer.url}`);
-  if (options.open) {
+  if (options.open !== false) {
     triggerBrowserOpen(runningServer.url);
   }
   const shutdown = async (exitCode = 0) => {
@@ -1288,7 +1288,7 @@ function registerServeOptions(command) {
     "--port <number>",
     "Port to listen on (default: 4200)",
     (value) => Number(value)
-  ).option("--open", "Open the ReDraft UI in the default browser", false).option("--no-ui", "Skip serving the static frontend", false).option("--host <string>", "Bind address (default: 127.0.0.1)", "127.0.0.1").option(
+  ).option("--no-open", "Skip opening the browser on startup").option("--no-ui", "Skip serving the static frontend", false).option("--host <string>", "Bind address (default: 127.0.0.1)", "127.0.0.1").option(
     "--sidecar-branch <string>",
     "Git branch for sidecar comment files (default: redraft)",
     "redraft"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redraft-local",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Local-first proposal review tool — serve and review Markdown proposals from any directory",
   "repository": {
     "type": "git",