README trim + push exposition into docs/

smellslikeml · smellslikeml · commit a68da537a595 · 2026-07-02T12:26:21.000-07:00
Top-level README is now grep-friendly: hero paragraph + install +
concrete quickstart (init + three dispatch modes) + doc pointers +
command reference + development + links. Cut prose exposition.

New docs:
- docs/pipeline.md — discovery / implementation / validation
- docs/research-interests.md — three interest-creation flavors

Extended:
- docs/method-targeted-runs.md — team-scale patterns section
  (bulk-install, cross-fork paper coordination, retry-under-provider)
diff --git a/README.md b/README.md
@@ -1,8 +1,6 @@
 # Remyx AI CLI
 
-Automate paper-to-PR delivery for the teams building on top of your code. Install [Outrider](https://github.com/remyxai/outrider) on a GitHub repo, and Remyx handles the loop end-to-end: **discovers** newly-published arXiv methods matching your team's work, **implements** them as draft PRs wired into your existing call sites, and **validates** each draft against the paper's reference implementation before it lands.
-
-The CLI is your control surface for the whole loop.
+Install [Outrider](https://github.com/remyxai/outrider) on a repo, and Remyx handles the loop end-to-end: **discovers** newly-published arXiv methods matching your team's work, **implements** them as draft PRs, and **validates** each against the paper's reference before it lands.
 
 ## Install
 
@@ -13,113 +11,34 @@ export REMYXAI_API_KEY=<your-key>   # from engine.remyx.ai/account
 
 ## Quickstart
 
-**Install Outrider on your repo.** One command; Remyx handles the workflow, secrets, and first run server-side (no local git touched):
+Install Outrider on a repo — server-side, no local git touched:
 
 ```bash
 remyxai outrider init --repo your-org/your-repo --auto-interest
 ```
 
-`--auto-interest` extracts a Research Interest from your repo's commit history + README. It's what Outrider matches new arXiv papers against.
-
-**Three ways to trigger a run after init.** Each is a different level of specificity — pick by how much you want to override Remyx's own ranking:
+Trigger a run — three modes of specificity:
 
 ```bash
-# 1. Default: let Remyx pick the best implementable paper from your interest's
-#    ranked pool. Outrider's audit augments via agentic refine-queries;
-#    Claude Code selects the top match against your codebase's actual call sites.
+# 1. default — Remyx picks from the ranked pool; Outrider's audit augments via agentic search
 remyxai outrider trigger --repo your-org/your-repo
 
-# 2. --search-method: override the ranker with a free-text query.
-#    Remyx searches its catalog and Outrider implements the top hit.
-#    Use when you know the method family but not the specific paper.
+# 2. --search-method — override the pool with a free-text query, implement the top hit
 remyxai outrider trigger --repo your-org/your-repo \
   --search-method "riemannian preconditioning LoRA optimizer"
 
-# 3. --pin-arxiv: implement THIS specific paper. Bypasses ranking entirely.
-#    Use for reproducible re-runs, retries, or when you already know the arxiv id.
+# 3. --pin-arxiv — exact paper, bypasses selection entirely
 remyxai outrider trigger --repo your-org/your-repo --pin-arxiv 2402.02347v3
 ```
 
-## How the pipeline scales
-
-Systematizing paper adoption across a team is usually a coordination problem, not a technical one — someone spots the paper, someone else evaluates fit, someone else implements, someone else reviews. Remyx + Outrider collapses that chain into a single automated pipeline that your team gates rather than staffs.
-
-**Discovery.** Every day, Remyx ranks the latest arXiv against your Research Interests (extracted from your codebase, curated per-team, or written by hand). See what surfaced:
-
-```bash
-remyxai papers digest                             # grouped by interest
-remyxai papers list --interest "My Project" -n 5  # flat view, top 5
-```
-
-For an interest, Outrider runs an audit pass that agentically explores your codebase, refines the recommendation pool via targeted searches for under-represented themes, and picks the paper most directly implementable against real call sites. Nothing gets drafted against imagined structure.
-
-**Implementation.** Once a paper is selected, Outrider clones the target repo and invokes Claude Code with a scoped brief: implement the paper's core contribution as a draft PR, wired into an existing call site, honoring your repo's contribution conventions (extracted from recent merged PRs). If the paper can't be cleanly scaffolded — no natural integration point, or too large a scope for one PR — Outrider opens a design-discussion Issue instead. The routing decision is measurement-based, not aspirational.
-
-**Validation.** Before a PR lands as ready-for-review, three passes run automatically:
-
-- **Fidelity audit** — clones the paper's reference implementation and diffs the draft against it, flagging any invented algorithms, wrong schemas, or missing components the paper actually requires. This is what catches plausibility-optimized fabrications before they reach a human reviewer.
-- **Convention pass** — folds the PR body and code layout to your target repo's contribution conventions (PR-body scaffold, AI-disclosure, docstring style, test co-location patterns), extracted from recent merged PRs.
-- **Test gate** — runs lint + targeted tests on the touched files; drops the Draft state only if lint passes and tests execute cleanly.
-
-Each pass writes its findings to the run's Actions Summary — you inspect one panel to see the drafting, verification, and refinement decisions for every recommendation.
-
-## Team-scale patterns
-
-**Bulk-install across an org's repos.** Install Outrider once across every active repo, each with an auto-extracted interest:
-
-```bash
-remyxai outrider init --bulk-repos repos.tsv --mode review
-```
-
-`repos.tsv` is a two-column file (`owner/name<TAB>interest-uuid-or-empty`); rows with an empty interest column trigger `--auto-interest`. See [docs/install-paths.md](docs/install-paths.md) for the full bulk flow.
-
-**Coordinate a specific paper across multiple frameworks.** Same paper, different codebases, one dispatch loop:
-
-```bash
-for repo in your-org/framework-a your-org/framework-b your-org/framework-c; do
-  remyxai outrider trigger --repo "$repo" --pin-arxiv 2402.02347v3
-done
-```
-
-Fidelity's cross-fork consistency check catches drift: if the same paper's core algorithm ends up implemented three different ways across three drafts, that's a signal about the codebase, not the paper.
-
-**Route the model provider per dispatch.** Different backends for different cost/quality tradeoffs:
+## Documentation
 
-```bash
-remyxai outrider trigger --repo your-org/your-repo \
-  --pin-arxiv 2402.02347v3 --provider zai --model glm-5.2
-```
-
-See [`docs/method-targeted-runs.md`](docs/method-targeted-runs.md) for the full discover-then-trigger workflow (including `remyxai search query` to surface candidate methods before pinning).
-
-## Research Interests
-
-An interest is a natural-language description of what your team tracks. Three ways to create one:
-
-```bash
-# From free-form context (or a HuggingFace/GitHub URL, expanded server-side)
-remyxai interests create --name "LLM Efficiency" \
-  --context "Quantization, speculative decoding, KV cache compression"
-
-# From a GitHub repo — extracts themes, architecture, and commit history
-remyxai interests from-repo https://github.com/your-org/your-repo --wait
-
-# From a project's experiments (all, or a curated subset via -e/--include-experiment)
-remyxai interests from-project "Spatial VQA" --wait
-```
-
-Every create command kicks off a first recommendation pass automatically. Use `--wait` to block until picks are ready.
-
-## Credentials
-
-You set up two things once:
-
-1. **`REMYXAI_API_KEY`** in your shell (from [engine.remyx.ai/account](https://engine.remyx.ai/account)) — authorizes the CLI.
-2. **A model provider** connected on the [Integrations page](https://engine.remyx.ai/integrations) — Claude Code today, more providers coming soon. Outrider calls the model at runtime with this.
-
-During provisioning, the Remyx GitHub App creates the target repo's secrets for you (a scoped `REMYX_API_KEY` and the provider's key) — no manual `gh secret set` steps. If the App isn't installed on the target yet, the CLI surfaces the install link.
-
-For the no-App `setup-local` path (uses your own `gh`), see [docs/install-paths.md](docs/install-paths.md).
+| Topic | Doc |
+|---|---|
+| Pipeline: discovery → implementation → validation | [docs/pipeline.md](docs/pipeline.md) |
+| Method-targeted runs + team-scale patterns | [docs/method-targeted-runs.md](docs/method-targeted-runs.md) |
+| Research Interests: three ways to create one | [docs/research-interests.md](docs/research-interests.md) |
+| Install paths, credentials, bulk-install | [docs/install-paths.md](docs/install-paths.md) |
 
 ## Command reference
 
diff --git a/docs/method-targeted-runs.md b/docs/method-targeted-runs.md
@@ -163,3 +163,44 @@ remyxai outrider trigger \
 ```
 
 The CLI rejects values below 60 seconds at the command boundary. The action itself parses the input as an integer; non-integer values fail fast at the workflow's `INPUT_CLAUDE_TIMEOUT` parser.
+
+
+## Team-scale patterns
+
+### Bulk-install across an org's repos
+
+Install Outrider once across every active repo, each with an auto-extracted interest:
+
+```bash
+remyxai outrider init --bulk-repos repos.tsv --mode review
+```
+
+`repos.tsv` is a two-column file (`owner/name<TAB>interest-uuid-or-empty`); rows with an empty interest column trigger `--auto-interest`. See [install-paths.md](install-paths.md) for the full bulk flow.
+
+### Coordinate a specific paper across multiple frameworks
+
+Same paper, different codebases, one dispatch loop:
+
+```bash
+for repo in your-org/framework-a your-org/framework-b your-org/framework-c; do
+  remyxai outrider trigger --repo "$repo" --pin-arxiv 2402.02347v3
+done
+```
+
+Fidelity's cross-fork consistency check catches drift: if the same paper's core algorithm ends up implemented three different ways across three drafts, that's a signal about the codebase, not the paper.
+
+### Retry a run under a different provider
+
+If a run timed out under GLM (which tends to run 1.1–2.7× slower than Anthropic on the same paper), retry it under Anthropic:
+
+```bash
+# First attempt hit the wall-clock ceiling under GLM
+remyxai outrider trigger --repo owner/name --pin-arxiv 2402.02347v3 \
+  --provider zai --claude-timeout 1500
+
+# Retry under Anthropic at the default timeout
+remyxai outrider trigger --repo owner/name --pin-arxiv 2402.02347v3 \
+  --provider anthropic
+```
+
+`--pin-arxiv` guarantees reproducibility across retries — the second attempt implements the same paper the first one targeted, so the comparison isolates the provider/backend variable.
diff --git a/docs/pipeline.md b/docs/pipeline.md
@@ -0,0 +1,46 @@
+---
+type: reference
+description: How Remyx + Outrider automates the paper-adoption pipeline — discovery, implementation, validation.
+tags: [outrider, pipeline, discovery, implementation, validation]
+---
+
+# Pipeline: discovery → implementation → validation
+
+Systematizing paper adoption across a team is usually a coordination problem, not a technical one — someone spots the paper, someone else evaluates fit, someone else implements, someone else reviews. Remyx + Outrider collapses that chain into a single automated pipeline that your team gates rather than staffs.
+
+## Discovery
+
+Every day, Remyx ranks the latest arXiv against your Research Interests (extracted from your codebase, curated per-team, or written by hand):
+
+```bash
+remyxai papers digest                             # grouped by interest
+remyxai papers list --interest "My Project" -n 5  # flat view, top 5
+```
+
+When Outrider fires on a repo, it runs an **audit pass** that agentically explores the codebase, refines the recommendation pool via targeted searches for under-represented themes, and picks the paper most directly implementable against real call sites. Nothing gets drafted against imagined structure.
+
+## Implementation
+
+Once a paper is selected, Outrider clones the target repo and invokes Claude Code with a scoped brief: implement the paper's core contribution as a draft PR, wired into an existing call site, honoring your repo's contribution conventions (extracted from recent merged PRs).
+
+If the paper can't be cleanly scaffolded — no natural integration point, or too large a scope for one PR — Outrider opens a design-discussion Issue instead. The routing decision is **measurement-based**, not aspirational: the coding agent must find a real call site before drafting a PR.
+
+## Validation
+
+Before a PR lands as ready-for-review, three passes run automatically:
+
+- **Fidelity audit** — clones the paper's reference implementation and diffs the draft against it, flagging any invented algorithms, wrong schemas, or missing components the paper actually requires. This is what catches plausibility-optimized fabrications before they reach a human reviewer.
+- **Convention pass** — folds the PR body and code layout to your target repo's contribution conventions (PR-body scaffold, AI-disclosure, docstring style, test co-location patterns), extracted from recent merged PRs.
+- **Test gate** — runs lint + targeted tests on the touched files; drops the Draft state only if lint passes and tests execute cleanly.
+
+Each pass writes its findings to the run's Actions Summary — you inspect one panel to see the drafting, verification, and refinement decisions for every recommendation.
+
+## Where teams sit in the loop
+
+You gate rather than staff:
+
+- **Configure** — set up an interest that reflects what your team tracks (via `interests from-repo` for codebase-anchored, or `interests create` for hand-curated)
+- **Review** — Outrider files Draft PRs and design Issues; you review, request changes, or merge
+- **Steer** — dispatch ad-hoc runs on specific papers via `--pin-arxiv` or `--search-method` when you have a specific target in mind (see [method-targeted-runs.md](method-targeted-runs.md))
+
+The automation catches the discovery gap (papers you'd have missed) and the fabrication gap (implementations that look plausible but aren't). Your review time stays focused on architecture, scope, and merge-readiness.
diff --git a/docs/research-interests.md b/docs/research-interests.md
@@ -0,0 +1,72 @@
+---
+type: reference
+description: Three ways to create a Research Interest — free-form context, from a repo, or from a project.
+tags: [interests, cli, research-profile]
+---
+
+# Research Interests
+
+A Research Interest is a natural-language description of what your team tracks. The recommendation pipeline matches new arXiv papers (and other sources) to it. Every create command kicks off a first recommendation pass automatically — add `--wait` to block until picks are ready, or `--no-refresh` to skip.
+
+## From free-form context
+
+```bash
+remyxai interests create \
+  --name "LLM Efficiency" \
+  --context "Quantization, speculative decoding, KV cache compression"
+```
+
+`--context` also accepts a HuggingFace or GitHub URL, which the server expands into context.
+
+## From a GitHub repo
+
+`remyxai interests from-repo <github-url>` analyzes the repo, generates a profile of the project (themes, architecture, history), and uses it as the interest's context:
+
+```bash
+remyxai interests from-repo https://github.com/your-org/your-repo \
+  --name "My Project" --daily-count 3 --automate review --wait
+```
+
+- `--automate {none|review|auto}` — paper-PR automation on the repo:
+  - `none` (default) — just create the interest
+  - `review` — open a setup PR to review
+  - `auto` — set it up automatically
+
+For the full repo setup (bulk-install, credentials, secrets), see [install-paths.md](install-paths.md).
+
+## From a project
+
+`remyxai interests from-project <name-or-uuid>` builds the interest's context from a Remyx project's experiments:
+
+```bash
+# Track all experiments on the project
+remyxai interests from-project "Spatial VQA" --wait
+
+# Or curate a subset, and pin the context
+remyxai interests from-project <uuid> -e "baseline-run" -e "dpo-v2" --no-auto-update
+```
+
+- `-e/--include-experiment` — track a specific experiment (repeatable); omit to track all
+- `--no-auto-update` — pin the context instead of refreshing as new experiments land
+
+## Managing interests
+
+```bash
+remyxai interests list                       # show all your interests
+remyxai interests get <name-or-uuid>         # show one interest's details
+remyxai interests update <id> --context ...  # edit fields
+remyxai interests toggle <id>                # flip active/inactive
+remyxai interests delete <id>                # remove
+```
+
+An inactive interest is excluded from the daily digest until toggled back on. Deleting an interest also removes all its recommendations.
+
+## What the context body looks like
+
+Interests are prompt-anchor artifacts — the recommendation pipeline consumes the context as natural-language framing for the ranker. Good interest contexts:
+
+- Name specific method families ("Quantization, speculative decoding, KV cache compression"), not broad domains ("LLMs")
+- Include the codebase's shape when relevant ("This is a training library; algorithm-add papers implementing new optimizers are the primary target")
+- Explicitly scope out adjacent-but-off-domain areas ("Not interested in general-purpose agent frameworks; only LoRA / PEFT optimizer methods")
+
+`interests from-repo` produces a reasonable context automatically for most repos. Hand-editing via `interests update --context ...` afterward tightens the ranker's picks when the auto-extract is too broad or catches the wrong theme.
