papiers 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papiers",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Read-only CLI for your Papiers library.",
   "license": "UNLICENSED",
   "homepage": "https://papiers.ai",
@@ -22,7 +22,8 @@
   "main": "dist/index.js",
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "skills"
   ],
   "engines": {
     "node": ">=22"

package/skills/papiers-research/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: papiers-research
+version: 1.2.0
+description: |
+  Ground proposals, experiment designs, reviews, and writing in the user's
+  Papiers library — their highlights, annotations, conversations, and
+  curated-but-unread saves — before generating. Use whenever output should
+  be shaped by what the user has read and thought, not generic knowledge:
+  proposing research ideas, designing experiments, advising on decisions,
+  or writing on topics the user studies.
+allowed-tools:
+  - Bash
+---
+
+# Thinking with the user's library
+
+The `papiers` CLI is the agent-readable memory of what the user has read and
+thought. It holds two kinds of signal, and you must treat them differently:
+
+- **Judgement** (read and marked): highlights, annotations, and past
+  conversations. These are the user's own words — stances, open questions,
+  connections. The strongest signal you have.
+- **Curation** (saved, possibly unread): library membership itself. The user
+  saves far more than they read, usually because someone they trust shared
+  it. A saved-but-unmarked document is an *endorsement the user has not had
+  bandwidth to evaluate* — your job is to complete that evaluation: read it
+  if relevant, then decide whether it should shape your output.
+
+All data commands emit stable JSON envelopes; pass `--json` so errors are
+JSON too (without it, errors print as plain text). Run `papiers --help --all`
+once for the full contract. `PAPIERS_TOKEN` must be configured.
+
+## The loop — run this BEFORE generating
+
+1. **Recent trajectory.** What is the user into right now?
+
+   ```bash
+   papiers list --kind highlight --since 30d --limit 20 --json
+   papiers list --kind document --limit 20 --json   # scan recent titles
+   ```
+
+2. **Facet sweep.** Decompose the task into 3–6 facets (for "improve MoE
+   router load balancing": expert routing, load balancing loss, expert
+   collapse, capacity factor…). One default search covers matching titles,
+   passages, highlights, equations, and conversations in a single fused
+   ranking:
+
+   ```bash
+   papiers search "<facet>" --limit 10 --json
+   papiers search "<facet>" --passage-ids | papiers read @- --format plain --json
+   ```
+
+   Keep structured attributes out of the free-text query. Search
+   `papiers search "diffusion" --filter venue.contains=neurips --json`, not
+   `"neurips diffusion"`; search `papiers search "dropout" --filter author.contains=hinton --json`
+   for an author surname or `author.contains=karpathy` for a handle.
+
+   Document results carry nested `evidence[]` for passage, highlight, and
+   equation hits. Use `--passage-ids`, `--highlight-ids`, or `--evidence-ids`
+   to project matching evidence flat for piping. `--doc-ids` pivots any
+   result page to deduped parent documents, skipping conversation hits.
+
+3. **Delegated reading.** Document hits you cannot tie to any judgement are
+   curated-but-unread candidates (`--filter engaged=false` lists the queue).
+   Read the most promising under a budget (default 3–8 documents per task).
+   Bare `read` returns content; cap it, and use `--format metadata` when you
+   only need citation fields:
+
+   ```bash
+   papiers read doc_<id> --max-chars-per-item 4000 --json
+   papiers search "<topic>" --doc-ids | papiers read @- --format metadata --json
+   papiers search "<subtopic>" --kind passage --document-id doc_<id> --json  # search within one document
+   ```
+
+4. **Judgement overlay.** For any document central to the task, pull the
+   user's marks on it, then read them:
+
+   ```bash
+   papiers list --kind highlight --document-id doc_<id> --json
+   papiers read hl_<id> --json   # quote + annotationText + quoteContext + dates
+   ```
+
+   Most highlights carry no annotation (quote-only); `annotationText` is
+   only present on reads, so read the highlights you intend to lean on.
+
+5. **Write the judgement brief.** Before generating anything, summarize what
+   you found: verbatim annotations with dates and IDs, stances, open
+   questions, and which curated-but-unread sources you read and why they
+   matter. If the sweep found nothing, say so — do not force citations.
+
+6. **Generate with attribution.** Every proposal states what shaped it:
+
+   > Shaped by your note (2026-04, `hl_d82f…`): "how did they survive until
+   > then? how much did they raise?"
+
+   - Surface the user's open questions as candidate experiments — annotations
+     are often questions the user left for later.
+   - If your proposal contradicts the user's recorded judgement, say so
+     explicitly instead of silently overriding it.
+
+## Rules
+
+- **Quote judgement verbatim.** Never paraphrase an annotation; its exact
+  wording is the signal.
+- **Dates are data.** Prefer recent judgement for "current interests"; when
+  an old note resonates with the task, resurface it with its age ("you noted
+  this two years ago"). `createdAt` is on every highlight; `--since` accepts
+  ISO timestamps or `30d`-style shorthand.
+- **Honor the quality signal.** `quality.signal: "empty"` or `"low"` means
+  the library has nothing — report that rather than citing weak matches.
+- **Cite IDs.** `hl_/cnv_/doc_/pas_` IDs are stable; include them so the
+  user can jump to sources.
+- **Budgets are policy, not protocol.** Default to ~10–20 queries and 3–8
+  document reads per task. The user may override any policy in this skill
+  (read more, weight recency differently, skip curation); the loop's shape
+  stays the same.