@orangecollective/oc 0.1.1

package/README.md

@@ -0,0 +1,103 @@
+# `oc`
+
+The OC-IDE research agent in your terminal: the same `yc-research-agent`, the same
+models, the same `@`-mention context, and the same batch activity digest the web
+app greets you with.
+
+## Install
+
+Needs **Node 22 or newer** (Ink's floor — check with `node -v`).
+
+```bash
+npm i -g @orangecollective/oc
+oc login      # opens your browser to authorize this machine
+oc
+```
+
+Upgrade with the same command. `oc --version` prints what you have.
+
+You need an Orange Collective account that belongs to at least one team — `oc`
+exits with "Your account isn't on a team yet" otherwise. Run it in a real
+terminal: Ink needs a TTY, so it can't be piped.
+
+If the install fails with `EACCES`, your npm prefix is root-owned. Fix the
+prefix rather than reaching for sudo, which leaves root-owned files that break
+later installs:
+
+```bash
+npm config set prefix ~/.npm-global      # then add ~/.npm-global/bin to PATH
+```
+
+### From source
+
+For working on the CLI itself:
+
+```bash
+git clone git@github.com:davecyen/oc-ide.git
+cd oc-ide/cli
+npm run setup     # install + build + link `oc` to this checkout
+```
+
+## Use
+
+```bash
+oc login                              # authorize this machine in your browser
+oc                                    # greeting + digest, then chat
+oc logout
+
+oc --host http://localhost:3000 login # target a dev server (or set OC_HOST)
+```
+
+In the chat:
+
+| | |
+|---|---|
+| `@name` | attach a company, founder, batch or skill |
+| `/` | open the command list (tab to complete) |
+| `/model [name]` | switch model (no argument lists them) |
+| `/web` | toggle web search |
+| `/team [slug]` · `/batch [W26]` | change scope |
+| `/digest [-r]` | re-run the digest (`-r` regenerates it server-side) |
+| `/new` · `/clear` · `/quit` | |
+| `?` | shortcuts (on an empty prompt) |
+| `↑ ↓` | history, or move through a list |
+| `esc` | interrupt · close a list · drop context |
+| `ctrl-c` ×2 | exit |
+
+Config lives in `~/.oc/` — `credentials.json` (session) and `state.json` (model,
+team, batch, thread), both `0600`. Set `OC_CONFIG_DIR` to relocate them.
+
+## Development
+
+```bash
+npm run dev        # tsx, no build step
+npm run typecheck
+npm run build      # esbuild → dist/oc.js
+```
+
+Notes for anyone editing this:
+
+- **All key handling lives in one `useInput` in `src/ui/App.tsx`.** Editing and the
+  pickers are interleaved, and two competing handlers race on the same keypress.
+  Ctrl-C is handled there too, which is why `oc.tsx` renders with
+  `exitOnCtrlC: false`.
+- Colour comes from `src/ui/theme.ts` — one orange ramp, used for the wordmark
+  gradient and as the single accent. Don't introduce raw ANSI colour names.
+- `Logo.tsx` rows are exactly 43 columns each and drop to a two-row wordmark
+  under 45 columns.
+- Pass `onError` to `readUIMessageStream` — it defaults to swallowing upstream
+  errors, which makes a bad provider key look like a hung CLI.
+- Finished output goes into Ink's `<Static>`, which is what keeps terminal
+  scrollback and piping working. Only the in-flight turn re-renders.
+- Streaming re-renders are throttled (`FLUSH_INTERVAL_MS`) and the in-progress
+  answer renders as raw text; markdown is parsed once, when the turn completes. A
+  half-written code fence renders as garbage otherwise.
+- This package is **not** an npm workspace of the app, and the app's `tsconfig` /
+  eslint config exclude it. It carries its own React and Ink; hoisting those into
+  the app's `node_modules` would affect the Next build.
+- `build.mjs` resolves the app's `@/` alias so a small allowlist of **pure**
+  modules can be shared (the digest wire format). Never import anything that
+  touches `next/headers`, a Supabase server client, or React components.
+- Server-side pieces this depends on: `lib/supabase/request.ts` (bearer auth),
+  `app/api/cli/*`, `app/auth/cli/[port]/[code]/page.tsx`, `lib/cli-auth.ts`. See
+  the `oc` CLI section in the repo's `CLAUDE.md`.