@armanckeser/downstream 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armanc Keser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# Downstream
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Code review that reads a change the way it runs.
+
+Ask your coding agent to review a pull request, or to explain part of the codebase, and Downstream opens next to it: the change laid out from its entry points, each call one click deeper, the agent's reasons pinned to the lines they're about, and a margin where you talk it through with the agent while it listens. When you agree, the review you arrived at goes to the pull request: your verdict, your words, inline comments the author can apply in one click.
+
+![A review in Downstream: the agent's walkthrough lands live, a type hover, following a call, a question answered in the margin, the flow map](docs/demo.gif)
+
+## Home: what needs you
+
+`downstream home` opens a page with every pull request that needs you, for one GitHub account at a time, each with one next action: *Merge*, *Review*, *Re-review*, *Address 3 threads*, *Fix checks*, *Resolve conflicts*. One is **Now**. Pins come next in your order, then the rest ranked by what unblocks most. Pull requests waiting on someone else fold away.
+
+- **Accounts.** Every account `gh auth status` knows, one at a time (`1`, `2`). Inboxes never merge.
+- **Stacks.** A stack (`gh stack`) shows up as one row. Only the bottom layer can merge, so the row's action is the lowest layer that can move.
+- **Press a pull request** and Claude Code starts on it inside Downstream (through the Agent SDK, with your Claude Code settings). A review opens as soon as the agent writes it; other moves happen in a session page where you talk to the agent. Reading runs without asking; anything that writes asks you in the browser, and sending the review is always yours. **Move to terminal** stops it here and copies `claude --resume <id>`.
+
+Keys: `j`/`k` move, `↵` start, `n` Now, `p` pin, `r` refresh. In a review, one button is always the next thing to do (answer the agent, the next walkthrough step, send), and `↵` presses it.
+
+## Why
+
+A diff is a list of files, top to bottom, alphabetically. Nobody understands code that way. You find where control comes in, follow what it calls, and stop wherever something looks odd to ask why it's like that. The diff never tells you the entry point, never shows who calls the function you're reading, and never says why the author chose this interface over the obvious other one. That lives in the author's head, or now in the agent's context, and it's gone when the PR merges.
+
+Downstream gives the change that shape:
+
+- **Doors.** The entry points into the change: the route, the command, the component a page renders. Nothing else in the change calls them, so you start there.
+- **Trail.** Open a door and its code appears scoped to just that symbol, numbered like the real file. Click a call and the callee opens below it; the frame above folds to the one line that made the call. You read down the stack the way the code runs.
+- **Margin.** The agent writes `why` notes where a careful reader would stop, `decision` notes with the alternatives that lost, and findings with a severity and a failure scenario. You select lines and ask. It answers in the margin while you keep reading.
+- **Map.** The whole change as a system, left to right from its doors: what's new, what's changed, which calls are new, and which existing code reaches in.
+- **Send.** Findings are numbered (*fix 2 and 5*) and carry the problem, the smallest fix and what happens if you ship anyway. Each thread decides whether it reaches the author and in what words; the conversation stays private. Send review shows the exact review GitHub will get and posts it only when you confirm.
+
+Hover anything in the code for its real TypeScript type and docs. Hover a symbol on the map or in a note for its purpose, callers, calls and open findings.
+
+| | |
+|---|---|
+| ![The overview: the agent's summary, the doors into the change, findings and choices](docs/overview.png) | ![The trail: a step of the walkthrough, a symbol's code with pinned findings and a live type hover](docs/trail.png) |
+| ![A question in the margin, answered by the agent](docs/conversation.png) | ![The flow map, laid out from the change's entry points](docs/map.png) |
+
+![Send review: the verdict, the words for the author, and each inline comment exactly as GitHub will get it](docs/send.png)
+
+## How it works with an agent
+
+Downstream is a [Claude Code skill](SKILL.md). The agent drives a small CLI; you use the browser. Both go through the same actions on the same review, so either side can do anything the other can.
+
+```bash
+downstream open --pr 42          # analyze the change, open the browser
+downstream show                  # the agent reads the map: doors, symbols, edges
+downstream code pickNow          # and the code, numbered, with +/- marks and callers
+downstream apply plan.json       # it writes the walkthrough: summary, steps, why, decisions, findings
+downstream wait                  # then listens; returns when you ask, reply, resolve or finish
+downstream reply 2 "…"           # and answers in the margin
+downstream go openFirst          # or moves your view to what it's talking about
+downstream outgoing 2 "…"        # words a finding for the author (or --exclude keeps it private)
+downstream draft                 # the review exactly as it would be sent; you press Send
+```
+
+`downstream open --teach src/sync` does the same for existing code: no diff, a tour of how one request moves through that part of the system.
+
+The analyzer does the mechanical part. It diffs the change against the merge base, finds every function, method, class, type, component and route that changed (JSDoc included), and resolves calls, renders and type uses through the TypeScript compiler. It finds unchanged callers, and works out which calls are new in the change and which disappeared. The agent does the part only a reader can: what each piece is for, the order to read it in, why it's shaped this way, and what's wrong with it.
+
+## Built on agent-first primitives
+
+Downstream follows the [agent-first-apps](https://github.com/armanckeser/agent-first-apps) contract, adapted to a tool that starts in a second inside any repository:
+
+- **One source of truth.** A SQLite database per repository (`.downstream/review.db`, kept out of git), and one for the home page (`~/.downstream/home.db`: Now, pins, which repository and agent session belong to which pull request). The agent can query it read-only with `downstream sql`, and that connection cannot write.
+- **One action surface.** Every change is an action defined once in `server/actions.ts` with a schema: `note.add`, `note.reply`, `steps.set`, `symbol.annotate`, `navigate`, …. The browser, the CLI and plain HTTP all call it. `downstream actions` lists them.
+- **Live sync.** Every action emits an event. The browser follows them over server-sent events and updates as the agent writes.
+- **Shared application state.** The browser reports what you're looking at (the view, the trail of open frames, your selected lines), so when you ask about "this" the agent already knows what this is (`downstream screen`). The agent can move your view with `navigate`.
+- **Presence.** While `downstream wait` is blocked on you, the UI shows the agent as listening.
+
+Postgres and Electric would be the agent-first default. A review is short-lived, local and per repository, though, so an embedded database and SSE keep the same guarantees with nothing to start.
+
+## Install
+
+Run the home page straight from npm, from any directory:
+
+```bash
+npx @armanckeser/downstream home
+```
+
+To let Claude Code drive reviews, install it as a skill instead:
+
+```bash
+git clone https://github.com/armanckeser/downstream ~/.claude/skills/downstream
+cd ~/.claude/skills/downstream && npm install && npm run build
+```
+
+Then start the home page from any directory; it doesn't need to be inside a repository:
+
+```bash
+node ~/.claude/skills/downstream/bin/downstream.mjs home
+```
+
+One server runs per machine (`~/.downstream/`). Press a pull request and Downstream finds your clone of that repository under `~/projects`, `~/code`, `~/src`, `~/dev` or `~` (set `DOWNSTREAM_REPO_ROOTS` to search elsewhere), and makes a partial clone in `~/.downstream/repos/` when you don't have one.
+
+Or ask Claude Code to review something: *"help me review this branch"*, *"review PR 42 with me"*, *"teach me how the sync engine works"*. The first `open` in a repository takes a few seconds while TypeScript loads the project; after that the hovers are instant.
+
+Requires Node 22.18 or newer and git. `--pr` uses the GitHub CLI.
+
+**Languages.** TypeScript and JavaScript go through the compiler: symbols, call resolution, callers, real types on hover. Python is read from indentation and imports: functions, classes and methods with decorators and docstrings, FastAPI/Flask routes as doors, calls through imports and `self`, callers across the repo, signatures and docstrings on hover. Tests in either are marked as tests. Other languages arrive as one symbol per changed file; the agent splits them into real functions and draws the edges (`addSymbols`, `edges` in `apply`).
+
+## Development
+
+```bash
+npm install
+npm run build          # the web UI, served by the local server
+npm test               # analyzer tests against throwaway git repos
+npm run typecheck
+DOWNSTREAM_API=http://127.0.0.1:4317 npm run dev:web   # UI with hot reload against a running review
+npm pack               # what npm would publish: the UI and dist/ (the CLI and server compiled to JS)
+```
+
+A clone runs the TypeScript sources with Node's type stripping. A published copy lives under `node_modules`, where Node won't strip types, so `npm pack` and `npm publish` compile `cli/`, `server/` and `domain/` into `dist/` first (`server/install.ts` picks which one runs).
+
+| Path | What lives there |
+|---|---|
+| `SKILL.md` | The agent's instructions: the loop, what a good walkthrough contains, how to talk in the margin |
+| `domain/model.ts` | The review model, shared by server, CLI and browser |
+| `server/analyze/` | Git sides, TypeScript declarations, the flow graph |
+| `server/actions.ts` | Every action, defined once |
+| `server/publish.ts` | The review as the PR author sees it, and sending it |
+| `server/analyze/py.ts` | Python declarations, imports and calls |
+| `server/main.ts` | HTTP, SSE, `wait`; one server for every repository (`/r/<repo>/api`) |
+| `domain/inbox.ts` | The next action for each pull request, stacks, Now and pins |
+| `domain/next-move.ts` | The one next thing to do inside a review |
+| `domain/approval.ts` | Which agent tool calls run without asking |
+| `server/github.ts`, `server/gh.ts` | The inbox from GitHub search, per account |
+| `server/agent-host.ts`, `server/home.ts` | Agent sessions started from the home page; the home API |
+| `cli/downstream.ts` | The agent's CLI |
+| `web/src/` | The review surface (React, Tailwind, [Pierre diffs](https://diffs.com) and [trees](https://www.npmjs.com/package/@pierre/trees), dagre) |
+| `scripts/demo.mjs` | Records the demo above against a real repository |
+
+## License
+
+[MIT](LICENSE)

package/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: downstream
+description: Open a shared, live review surface for a code change or an area of code, walk the user through it, discuss it with them there, and (for pull requests) send the review you arrive at together. Use when the user asks to review a PR, branch or diff ("help me review this", "review PR 42", "walk me through this change"), or to explain how existing code works ("teach me how auth works", "give me a tour of src/sync"). TypeScript, JavaScript and Python are analyzed; other languages are mapped by hand.
+---
+
+# Downstream
+
+Downstream turns a change into something a person can read the way the code runs: start at an entry point ("a door"), follow each call downstream, and see why each piece is the way it is. You (the agent) map the change, write the walkthrough, and review it; the user reads it in a browser and talks to you in the margin; together you arrive at a review, and when the user says so, it goes to the pull request. You both read and write the same review through the same actions, and you hear the user through `downstream wait`.
+
+Run the CLI as `node "${CLAUDE_SKILL_DIR}/bin/downstream.mjs" <command>`. Below it is written `downstream <command>`. Run review commands from inside the repository being reviewed; `home`, `url` and `stop` work from anywhere. The first run installs dependencies and builds the UI (about a minute).
+
+## The loop
+
+1. **Open** the review.
+   ```bash
+   downstream open --pr 42              # someone's pull request (uses gh; no checkout needed)
+   downstream open                      # working tree (incl. uncommitted) vs main
+   downstream open --base main --head feature-x
+   downstream open --teach src/sync     # explain existing code instead of a diff
+   ```
+   It prints the URL and opens the browser. Tell the user the URL in one line, then keep working; the UI fills in live as you write. When Downstream started you (see *Running inside Downstream*), the user is already watching and the browser moves to the review by itself.
+
+2. **Understand** before you judge. `downstream show` prints the map: doors, every symbol with its status, flow edges (`*` = new in this change, `x` = removed), tests, threads. `downstream code <symbol>` prints a symbol's code with real line numbers and `+`/`-` marks, plus who calls it and what it calls. Then read past the map: the PR description, the callers of every changed function, the tests, where data comes in, what is stored, what goes out. A change can break code it doesn't touch: when a signature, return value or behavior changes, check every caller. Find the expected load (README, deploy config) and judge scale against it.
+
+3. **Write** the walkthrough and your review in one batch: a JSON file and `downstream apply plan.json` (shape below). You can apply again; steps are replaced as a whole, notes are added, `updates` edit existing threads.
+
+4. **Converse.** Run `downstream wait`. It blocks until the user replies, asks, flags, edits, resolves or ends the session, then prints what happened with the exact command to answer (and their selected code, when they asked about a selection). While it blocks, the UI shows you as *listening*. Answer, then `wait` again.
+
+5. **Arrive at the review.** When the conversation settles, draft what the author will read (see *Sending the review*). The user checks it in **Send review** and sends it, or tells you to.
+
+## What to look for
+
+Review like the senior developer who gets paged when it breaks. In order: correct, safe, holds under the expected load, tested, fast, lean.
+
+- **bug**: wrong result, crash, missed edge case (empty, zero, last item, rounding, time zones), a caller broken by the change, a fix in one caller while the shared function stays broken.
+- **risk**: security (injection, secrets, unchecked user input), data loss (swallowed errors, writes in the wrong order, no transaction), migrations that change what existing rows mean.
+- **scale**: fine for one user, wrong for many: check-then-write races, a query per item, unbounded growth, per-process state that must be shared.
+- **test**: risky new logic (a branch, a parser, money, security, data writes, a bug fix) with no test that fails when it breaks. One good test, not coverage.
+- **speed**: big slowdowns are findings; small wins are nice-to-haves.
+- **lean**: code that shouldn't exist (dead, speculative, an abstraction with one implementation), a helper the repo already has (name the path), a dependency for a few lines, near-copies that must change together.
+
+Every finding needs a concrete case: *this input or situation leads to this wrong result*. No case, no finding. Re-read the lines before you report: confirm the caller exists, the value can really be empty, the code really is unused. Propose the smallest fix that works; prefer fixes that delete code. No style taste, no "consider", no vague worries. Three real findings beat ten weak ones.
+
+## What a good walkthrough contains
+
+Write for a reader who has not seen the code: short sentences, everyday words, explain a term the first time. Name things; never say "it" when you can say `openFirst`. Wrap symbol names in backticks: in the UI they become links that show the code on hover and open it on click.
+
+- **summary** (3 to 8 sentences or a short list): what this change does, in behavior, then where the risk is. Not a file list.
+- **symbols**: a one-line purpose (`summary`) for every changed symbol and any unchanged one that matters to the flow ("what is this for?"). Fix `entry` flags: a door is where control enters the change (a route, a job, a CLI command, an exported function called from unchanged code, a component a page renders). Unmark what the analyzer guessed wrong.
+- **steps** (usually 3 to 8): the order to read the change, door first, then downstream along real calls. Each step anchors to a symbol (`symbolId`) and usually `lines`; its `body` says what happens at this point in the flow and why it's built this way. Point at the line that matters; don't repeat the code.
+- **notes**, each anchored to a symbol and, when about specific lines, `lines` (new-side numbers; `side: "old"` for removed code). Every note gets a number (`#1`, `#2`, …) the user can refer to; commands accept `3` or `#3` wherever they take a thread.
+  - `finding`: `severity` is `blocker` (shown as **must fix**: bug, security, data loss, breaks at the expected load), `concern` (**should fix**: risky code without a test, real slowness, duplication, code that shouldn't exist) or `nit` (**nice to have**). Set `category` (bug, risk, scale, test, speed, lean). `title` names the problem; `body` is the problem with its concrete case; `fix` is the smallest fix; `impact` says what happens if we ship it anyway; `suggestion` (`{lines, code}`) when the fix is concrete. A suggestion whose lines match the note's lines becomes a GitHub suggestion the author can apply in one click.
+  - `decision`: an abstraction or interface choice, with the `alternatives` that lost and their tradeoffs. For every new type, function boundary, dependency or data shape ask: why this shape and not the obvious other one? Is this the right layer? Anchor it to the shape's symbol; the overview shows each shape with its decision.
+  - `why`: the reason behind anything that would make a careful reader stop.
+  - `question`: you need the author's (or user's) intent to judge something.
+- **edges**: relationships the analyzer can't see (events, queues, HTTP between services, dynamic dispatch, DI wiring), with a `label`. `removeEdges` for noise.
+- **addSymbols**: for other languages (they arrive as one `module` symbol per file) add the real functions with `file`, `name`, `lines`, `status`, then connect them with `edges`. In TS/JS/Python you can pass just `line` and the declaration around it is found.
+
+Set `"status": "ready"` when the walkthrough is complete.
+
+### plan.json
+
+```json
+{
+  "summary": "Price tracking stops being something you switch on…\n\nThe risk is in the migration: …",
+  "status": "ready",
+  "symbols": [
+    { "id": "backend/app/features/price_tracking/service.py#apply_price_observation", "summary": "Records a fetched price; now also turns tracking on." },
+    { "id": "backend/app/features/wishlist_item/models.py#WishlistItem", "entry": false }
+  ],
+  "steps": [
+    { "title": "Tracking turns on when a check succeeds", "symbolId": "backend/app/features/price_tracking/service.py#apply_price_observation",
+      "lines": { "start": 267, "end": 271 }, "body": "A price we could read proves the page is trackable, so…" }
+  ],
+  "notes": [
+    { "kind": "finding", "severity": "blocker", "category": "risk", "symbolId": "backend/app/alembic/versions/f1a2_add_flag.py#upgrade",
+      "lines": { "start": 19, "end": 27 }, "title": "Everyone who turned tracking off is opted back in",
+      "body": "The new column defaults to false for every existing row, so an item whose owner switched tracking off…",
+      "fix": "Backfill in upgrade(): items that had a verified price and are off without a pause were turned off by their owner.",
+      "impact": "Owners who opted out start getting price notifications again the day this deploys.",
+      "suggestion": { "lines": { "start": 19, "end": 27 }, "code": "    op.add_column(…)\n    op.execute(\"UPDATE …\")" } },
+    { "kind": "decision", "symbolId": "backend/app/background/price_check.py#check_tracked_prices", "title": "Group by store instead of a global rate limiter",
+      "body": "…", "alternatives": [ { "option": "One global queue with a smaller delay", "tradeoff": "Every site sees faster requests." } ] },
+    { "kind": "question", "symbolId": "backend/app/background/price_check.py#check_tracked_prices", "title": "Is one scheduler process the expected deployment?", "body": "…" }
+  ],
+  "updates": [ { "noteId": "2", "outgoing": { "include": true, "body": "…" } } ],
+  "outgoingBody": "…",
+  "edges": [ { "from": "src/server/jobs.ts#enqueue", "to": "src/worker/run.ts#handle", "kind": "calls", "label": "via the jobs queue" } ]
+}
+```
+
+Two full examples from real reviews live in `examples/` (`kumbara-equity-grants.json` for TypeScript, `wishlist-auto-tracking.json` for Python).
+
+## Talking in the margin
+
+| The user… | You run |
+|---|---|
+| asks a question (`wait` shows `The user asked [n_x]…` with their selected code) | `downstream reply n_x "…"` |
+| replies in a thread | `downstream reply 3 "…"`, or `downstream resolve 3 "why"` when it's settled |
+| pushes back on a finding or decision | answer honestly. If they're right, say so and `resolve` or `dismiss` it with the reason; if the finding changes, `downstream do note.update '{"noteId":"3","body":"…"}'` |
+| says "this", "here" | `downstream screen` shows their view, open frames and selected lines |
+| says "fix 2 and 5" (their own code) | edit the code, `downstream reanalyze`, then `downstream resolve 2 "Fixed: …"` |
+| edits a thread's outgoing wording | `wait` reports it; leave their wording alone unless asked |
+| gives a verdict, sends, or ends the session | acknowledge in chat |
+
+- `downstream go <symbol> [--lines a-b]`, `go step 3`, `go thread 3`, `go map` moves the user's view. Use it when your answer is "look at this".
+- `downstream note <kind> <symbol> --title "…" [--body] [--severity] [--category] [--fix] [--impact] [--lines a-b]` adds one thread without a full apply.
+- `downstream ask "…" --symbol s` asks the user something.
+- `downstream sql "select * from v_notes where status = 'open'"` reads anything (read-only connection; views `v_symbols`, `v_edges`, `v_notes`, `v_replies`).
+- `downstream actions` lists every action with its input schema; `downstream do <action> '<json>'` calls one. The browser uses the same actions, so anything the user can do, you can do.
+
+Replies are markdown, shown in your voice in the margin. Keep them short: the claim, the evidence (a line, a caller), what you'd do.
+
+## Sending the review
+
+The conversation in the margin is between you and the user and never leaves. What the PR author reads is a separate, explicit draft:
+
+- **Which threads go out.** The user answers that per thread in the margin: **Send to author** (settles it, and it goes out) or **Don't send** for findings, **Got it** (private) or **Send to author too** for your explanations. That choice is `outgoing.include`; never override it. Threads the user hasn't answered: open findings go out, everything else stays private. You change it only when asked: `downstream outgoing 3 "…"` (send, in these words) or `downstream outgoing 4 --exclude`.
+- **The words.** Without outgoing wording, a finding goes out as written (severity, title, problem, fix, suggestion, impact). Reword when the conversation changed the finding, or when it should read as a question to the author. Write to the author, not to the user: no references to your conversation, and no `#3` thread numbers (on GitHub those link to issues and pull requests); name the problem instead.
+- **The body.** `outgoingBody` (via `apply` or `downstream do review.update '{"outgoingBody":"…"}'`): what the change does in a sentence or two, what must change before merging, and anything you could not check. Plain and kind.
+- **The verdict.** `downstream verdict changes|approve|comment "…"`. GitHub doesn't allow approving or requesting changes on your own pull request; use comment there.
+- `downstream draft` prints exactly what would be sent: the event, the body, each inline comment, and the comments that fall outside the diff (GitHub only takes inline comments on changed lines and their context, so those go into the body).
+
+Sending is public and permanent. **Never run `downstream send` on your own initiative.** The user sends from the Send review panel, or tells you to in chat ("send it"); then run `downstream draft`, show them the verdict and the number of comments in one line, and send only after they confirm. Only pull request reviews (`open --pr`) can be sent; for anything else the panel copies the review as markdown. If the PR changed since you opened it, `send` refuses: tell the user, and offer to re-open it (`open --pr <n>`) or, only if they say so, `send --force`.
+
+## Languages
+
+- **TypeScript / JavaScript**: the compiler resolves calls, renders, type uses and callers; hover shows real types and docs. Inner functions of large containers (Effect service layers, app builders) are lifted into their own symbols, and a service's `return { createGrant }` is followed back to the function.
+- **Python**: declarations come from indentation (decorators and docstrings included); FastAPI/Flask/Celery-style decorators mark routes and jobs as doors. Calls are resolved through each file's imports, `self.`/`cls.`, fresh instances (`Service().create()`), and unique method names; callers are found across the repo; hover shows the signature and docstring. There is no type checker: when a call goes through an injected object the analyzer can't see, add the edge yourself.
+- **Tests** are marked as tests: never doors, shown on a frame as *tested by*, hidden on the map unless toggled.
+
+## Teaching mode
+
+`downstream open --teach <paths…>` maps existing code instead of a diff: every declaration is a symbol, edges are the calls between them, doors are exported functions and routes nothing else in the set calls. The job is the same minus findings unless asked: what this part of the system is for, purposes for the important symbols, a walkthrough that follows one real request or operation end to end, and `why`/`decision` notes on the shapes a newcomer would question. Large maps open scoped to your walkthrough.
+
+## Running inside Downstream
+
+The user can start you from Downstream's home page (`downstream home`) by pressing a pull request. Then `DOWNSTREAM_HOSTED=1` is set and:
+
+- The user reads your output and answers your permission requests in the browser, not a terminal. Talk to them in the margin, and keep `downstream wait` running between turns; a message they write while you're idle also wakes you.
+- Reading never asks: file tools, searches, and read-only shell (`git log/show/diff`, `gh pr view`, `rg`, loops over those) run straight away. Anything that writes asks, and so does an expanded argument (`$f`, `$(…)`) to `git`, `gh` or the CLI, so prefer literal arguments. `downstream send` always asks.
+- For work other than a review (failing checks, feedback to address, conflicts), make changes in a git worktree and say what you'll change before you change it.
+- The user can move the session to their terminal (`claude --resume`); nothing changes for you.
+
+## Housekeeping
+
+- One server per machine (`~/.downstream/`, or `$DOWNSTREAM_HOME`); each repository's reviews live in `<repo>/.downstream/` (SQLite), added to `.git/info/exclude`. `downstream status`, `downstream url`, `downstream stop`, `downstream home`. An updated skill restarts the server and rebuilds the UI on the next `open`.
+- `downstream reanalyze` re-reads the code after edits and keeps summaries, threads and the walkthrough.
+- Reopening (`downstream open`) starts a fresh review and makes it current; old ones stay in the database.
+- If `open` fails, `~/.downstream/server.log` has the server's output.

package/bin/downstream.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Runs the CLI from the package's own directory so it works from any repository.
+// A clone runs the TypeScript sources with Node's built-in type stripping. A
+// published copy (npx, npm install) sits under node_modules, where Node refuses
+// to strip types, so it runs the JavaScript compiled into dist/ at publish time.
+import { spawnSync, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const skillDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const published = skillDir.split(path.sep).includes("node_modules");
+const entry = published ? path.join(skillDir, "dist", "cli", "downstream.js") : path.join(skillDir, "cli", "downstream.ts");
+if (!published && !existsSync(path.join(skillDir, "node_modules", "typescript"))) {
+  console.error("downstream: installing dependencies (first run)…");
+  execFileSync("npm", ["install", "--no-audit", "--no-fund"], { cwd: skillDir, stdio: "inherit", shell: process.platform === "win32" });
+}
+const res = spawnSync(process.execPath, ["--no-warnings=ExperimentalWarning", entry, ...process.argv.slice(2)], { stdio: "inherit" });
+process.exit(res.status ?? 1);