@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/paperclip/references/installation.md

@@ -1,341 +0,0 @@
-# Installing and authenticating Paperclip
-
-Paperclip is distributed by GXL (`https://paperclip.gxl.ai`). There are two ways to reach it: a local
-CLI, or a hosted MCP server. The CLI is the richer surface — the virtual filesystem, `grep`, `scan`,
-`sql`, repos, and the clipboard all live there — so prefer it unless you are on Windows or cannot
-install software.
-
-Commands here were exercised against **paperclip 0.7.14 and 0.7.15** on macOS (darwin 25.5.0). Per-client MCP
-configuration is transcribed from `https://paperclip.gxl.ai/install` and is not verified here.
-
-## 1. Install the CLI
-
-### One-line installer (recommended, macOS and Linux)
-
-```bash
-curl -fsSL https://paperclip.gxl.ai/install.sh | bash
-```
-
-This is the vendor's supported install path, and it executes a remotely-fetched script with the
-user's privileges — there is no published checksum or signature to verify it against. Get the user's
-go-ahead before running it, and read it first if they want that:
-
-```bash
-curl -fsSL https://paperclip.gxl.ai/install.sh | less
-```
-
-The same applies after install: the CLI self-updates opportunistically, so the code that runs can
-change between invocations. `paperclip --version` tells you what actually ran.
-
-This drops a self-contained CLI in `~/.paperclip/` and a launcher on your `PATH` (on macOS,
-`~/.local/bin/paperclip`). It bundles its own interpreter and dependencies under `~/.paperclip/lib/`,
-so it will not disturb any project virtualenv.
-
-If `paperclip` is not found afterwards, `~/.local/bin` is not on your `PATH`:
-
-```bash
-export PATH="$HOME/.local/bin:$PATH"      # add to ~/.zshrc or ~/.bashrc to persist
-```
-
-### Via uv
-
-Use this when you want the package inside an environment you control — for example to import the
-Python SDK alongside your own code.
-
-```bash
-uv pip install https://paperclip.gxl.ai/paperclip.whl
-paperclip setup        # = paperclip login + paperclip install
-```
-
-Two caveats. The wheel URL is unversioned, so it resolves to whatever is current — there is no pinned,
-hash-verified release to install instead, and `gxl-paperclip` is not published on PyPI. And the
-unrelated `paperclip` package **is** on PyPI: `uv pip install paperclip` installs the wrong software.
-Always install from the full URL.
-
-### Windows
-
-The native installer does not support Windows. Use Claude Desktop, claude.ai, or another MCP client
-pointed at the hosted server (below).
-
-## 2. Authenticate
-
-**Use an API key from the environment. Treat browser OAuth as the fallback.** A key is
-non-interactive, works headless and in CI, is independently revocable, and never blocks on a browser.
-
-### Resolution order
-
-Verified against `cli/app.py` and `client/client.py` in 0.7.14:
-
-| Priority | Source | Notes |
-|---|---|---|
-| 1 | `--api-key` flag | Works, but exposed in `ps` and shell history — avoid |
-| 2 | `PAPERCLIP_API_KEY` env var | **Preferred.** Click reads it via the flag's `envvar` binding |
-| 3 | `~/.paperclip/credentials.json` | Written by `paperclip login` |
-
-A key in the environment **short-circuits OAuth completely**: `_ensure_auth()` returns immediately, so
-no browser opens and a stored login is not consulted even when one exists. That also means an exported
-key silently overrides the account you logged in as — `paperclip config` will show
-`Auth: ✓ API key (env)` instead of your email.
-
-The Python SDK's `from_env()` uses a similar order with one extra step in front:
-`PAPERCLIP_BEARER_TOKEN` → `PAPERCLIP_API_KEY` → `~/.paperclip/credentials.json`.
-
-### API key from `.env` — the default path
-
-Create a key at `https://paperclip.gxl.ai/keys` (they look like `gxl_...`) and put it in the project's
-`.env`:
-
-```bash
-# .env  — add to .gitignore
-PAPERCLIP_API_KEY=gxl_...
-```
-
-**Paperclip has no dotenv support.** There is no `python-dotenv` dependency anywhere in the package;
-`config.py` reads `os.getenv("PAPERCLIP_API_KEY", "")` and nothing more. A `.env` sitting next to the
-command is invisible to it, so the file has to be exported into the environment first.
-
-Use this exact form, in the directory holding `.env`:
-
-```bash
-[ -f .env ] && { set -a; . ./.env; set +a; }; paperclip config
-```
-
-`set -a` marks subsequent assignments for export, `.` sources the file, `set +a` restores normal
-behavior.
-
-Two things about this form are not stylistic:
-
-**The `[ -f .env ]` guard is mandatory.** A bare `. ./.env` against a missing file is a *fatal* error
-in a POSIX shell — it terminates the shell, so everything after the `;` is silently discarded:
-
-```bash
-# WRONG — unguarded, run in a directory with no .env
-sh -c 'set -a; . ./.env 2>/dev/null; set +a; echo survived; paperclip config'
-#   (no output at all — "survived" never prints, paperclip never runs)
-```
-
-Guarded, it is safe in all four states, each verified: `.env` present, `.env` absent, key already
-ambient in the environment, and under both `sh` and `bash`.
-
-**Every invocation needs it.** Environment variables do not persist between separate shell
-invocations, which is exactly how an agent runs commands — one call per tool use. Export in one call
-and run `paperclip` in the next and the key is gone, and Paperclip does not complain: it silently
-falls back to stored OAuth, a *different identity*:
-
-```bash
-# WRONG — split across two tool calls
-# call 1
-set -a; . ./.env; set +a
-# call 2
-paperclip config      # → Auth: ✓ someone@example.com   ← the key never loaded
-```
-
-```bash
-# RIGHT — one self-contained call
-[ -f .env ] && { set -a; . ./.env; set +a; }; paperclip config   # → Auth: ✓ API key (env)
-```
-
-If the key is already exported — CI secrets, a shell profile, `direnv` — the guard is a harmless
-no-op and no prefix is needed.
-
-```bash
-export PAPERCLIP_API_KEY='gxl_...'   # ad hoc, current shell only
-```
-
-Values containing spaces must be quoted inside `.env` or the shell will try to run them; `gxl_` keys
-never contain spaces, so this only matters for other variables sharing the file.
-
-Over HTTP the key travels as an `X-API-Key` header. Never echo it, never commit `.env`, and never
-include it in a file you `paperclip upload`.
-
-### The `--api-key` flag
-
-```bash
-paperclip --api-key "$PAPERCLIP_API_KEY" search -s pmc "query" -n 5
-```
-
-Same mechanism, worse hygiene: the argument shows up in `ps` output and shell history. Use it only to
-run two identities in one shell where exporting would collide.
-
-### Fallback: browser OAuth — a human must run this
-
-`paperclip login` opens a browser and waits. An agent cannot complete it; ask the user to run it and
-report back. With no TTY it exits cleanly rather than hanging:
-
-```text
-[error] Not authenticated. Run: paperclip login
-       Or use --api-key flag or PAPERCLIP_API_KEY env var
-```
-
-For interactive use on a machine with a browser and no key available:
-
-```bash
-paperclip login       # opens a browser
-paperclip logout      # sign out, remove stored credentials
-```
-
-Credentials land in `~/.paperclip/credentials.json`. Sign-in is also triggered automatically on first
-use — which is exactly the blocking behavior an API key avoids, so set the key before the first call
-in any non-interactive context.
-
-## 3. Verify
-
-```bash
-paperclip config
-```
-
-With a key exported, a healthy install prints:
-
-```text
-  Paperclip
-  Server:  https://paperclip.gxl.ai
-           (default)
-  Auth:    ✓ API key (env)
-  Config:  /Users/you/.paperclip
-  Health:  ✓ server reachable
-  Sources: PubMed Central, bioRxiv, medRxiv, arXiv
-```
-
-Under OAuth the `Auth` line shows your email address instead.
-
-**`Auth: ✓` means a key is present, not that it is valid.** A junk key produces the identical line,
-and `Health: ✓ server reachable` is an unauthenticated probe. Only a real query proves the credential:
-
-```bash
-paperclip search -s pmc "CRISPR base editing" -n 3
-```
-
-You should get numbered results ending in a `[s_xxxxxxxx]` result id. An invalid key instead prints
-`[error] Authentication failed (API key invalid).` and exits **1**, which is what to check in a script.
-
-## 4. Install the agent skill files (optional)
-
-`paperclip install` writes Paperclip's own skill files into a project so an agent picks them up
-without being told.
-
-**It is interactive** — two prompts, agent and path. Run bare from a tool call it either hangs on a
-TTY or aborts without writing anything:
-
-```text
-  Select (e.g. 1,2 or all) [1]: Aborted!
-```
-
-Answer both prompts on stdin. `1` = Claude Code, `2` = Cursor, `3` = Codex; the empty second line
-accepts the `--dir` default:
-
-```bash
-printf '1\n\n' | paperclip install --dir /path/to/project
-# → writes /path/to/project/.claude/skills/paperclip/SKILL.md
-```
-
-Interactively:
-
-```bash
-paperclip install                 # prompts for client: Claude Code or Codex
-paperclip install --dir ~/work/my-project
-```
-
-Installed skills are tracked in `~/.paperclip/installed_skills.json`. This is independent of the
-CLI itself — the CLI works fine without it.
-
-## 5. MCP server (no local install)
-
-Universal endpoint:
-
-```text
-https://paperclip.gxl.ai/mcp
-```
-
-### Claude Code
-
-```bash
-claude mcp add --transport http paperclip https://paperclip.gxl.ai/mcp
-```
-
-### Codex
-
-```bash
-codex mcp add paperclip --url https://paperclip.gxl.ai/mcp
-codex mcp login paperclip
-```
-
-Codex Desktop: Settings → MCP servers → Custom MCP, with an `X-API-Key` header holding your key.
-
-### Cursor — `~/.cursor/mcp.json`
-
-```json
-{
-  "mcpServers": {
-    "paperclip": {
-      "url": "https://paperclip.gxl.ai/mcp",
-      "type": "http"
-    }
-  }
-}
-```
-
-Reload the window afterwards.
-
-### Claude Desktop and claude.ai
-
-Customize → Connectors → add a custom connector named "Paperclip" with the MCP URL above. Requires a
-Pro, Max, Team, or Enterprise plan.
-
-### Windsurf, Antigravity, ChatGPT
-
-Same URL, configured as a custom MCP server or connector; the first two need the `X-API-Key` header
-added by hand in their config file.
-
-**MCP caveat:** the MCP surface is a single `paperclip` tool, not the full CLI. Its own instructions
-tell you to run `paperclip skill` first to load the command reference.
-
-## 6. Maintenance
-
-```bash
-paperclip update      # upgrade the CLI and refresh installed agent skills
-paperclip uninstall   # remove Paperclip from this machine
-```
-
-The CLI also self-updates opportunistically. A command may print
-`[paperclip] Updated 0.7.14 → v0.7.15` before its output — harmless, but it means a long-running
-script can change versions mid-run. Pin behavior by running `paperclip update` up front if that
-matters.
-
-## 7. Configuration
-
-```bash
-paperclip config                              # diagnostics (default)
-paperclip config --show                       # current configuration
-paperclip config --url http://localhost:8002  # point at a different server
-paperclip config --sources pmc --sources fda  # persistent default source filter
-paperclip config --sources-list
-paperclip config --sources-clear
-```
-
-A persistent source filter narrows *every* subsequent command. If searches come back suspiciously
-empty, check `paperclip config --sources-list` before debugging anything else.
-
-Config lives in `~/.paperclip/`:
-
-```text
-~/.paperclip/
-├── credentials.json      OAuth tokens
-├── feature_flags.json
-├── installed_skills.json
-├── repos/                local repo state
-├── cache/
-└── lib/                  bundled interpreter + gxl_paperclip package
-```
-
-## Troubleshooting
-
-| Symptom | Cause and fix |
-|---|---|
-| `command not found: paperclip` | `~/.local/bin` missing from `PATH` — export it, or re-source your shell rc |
-| `Error: search requires a source flag (-s)` | Expected. Every search names a source: `-s pmc` |
-| `Auth: ✗` in `paperclip config` | Run `paperclip login`, or export `PAPERCLIP_API_KEY` |
-| Searches return nothing across sources | A stale source filter — `paperclip config --sources-clear` |
-| Corpus `grep` finds nothing for a rare term | Default scan is time-bounded; retry with `--exhaustive` |
-| `head` on `meta.json` prints nothing | `head`/`tail` handle `.lines` files; use `cat` for JSON |
-| Version changed mid-session | Opportunistic self-update; re-run `paperclip --version` |
-| MCP client cannot authenticate | Add the `X-API-Key` header with a key from `/keys` |

package/skills/paperclip/references/map-reduce.md

@@ -1,252 +0,0 @@
-# map, reduce, results, and figure analysis
-
-`map` runs an LLM reader over each document in a result set, in parallel. `reduce` synthesizes those
-per-document answers into one output. Together they are how you answer a question that spans papers
-without reading each one yourself.
-
-Flags below come from `paperclip map --help` and `paperclip reduce --help` at 0.7.14–0.7.15. The
-`quick-reader` map and the `table` reduce strategy were executed live against a three-paper result
-set; the other workers and the resume/cancel paths are transcribed from `--help` and not exercised.
-
-Examples omit the auth prefix. Every real invocation needs it:
-`[ -f .env ] && { set -a; . ./.env; set +a; }; paperclip <command>`.
-
-Two verified defects to know before you start — details in their sections below:
-
-1. **`--strategy table` returns prose, not a table**, with or without `--columns`.
-2. **`reduce` output embeds truncated document ids.** They do not resolve, so a citation URL built
-   from them is broken.
-
-## The pipeline
-
-```bash
-paperclip search -s pmc "lipid nanoparticle mRNA delivery" -n 10    # → s_abc123
-paperclip filter --from s_abc123 "in vivo delivery with quantified efficiency"
-paperclip map    --from s_abc123 "What delivery vector, target cell type, and transfection efficiency were reported?"
-paperclip reduce --from m_def456 --strategy table "Compare vector, cell type, and efficiency"
-```
-
-Result ids: `s_*` from `search`/`filter`/`grep`, `m_*` from `map`, `r_*` for the artifact `reduce`
-emits (`Artifact ID: r_36626b45`). `reduce` defaults to the most recent map if `--from` is omitted,
-but pass it explicitly — it is cheap insurance against picking up an unrelated run.
-
-A completed map prints a progress bar, a per-paper preview **truncated to roughly one line each**, and
-a `Full results: /.gxl/map_<id>.txt` pointer:
-
-```text
-  [######..............]  1/3 papers  run m_4b4632df  [2s]
-Map complete: 3/3 tasks succeeded in 3571ms
-Results ID: m_4b4632df
-Full results: /.gxl/map_m_4b4632df.txt
-
-  [success] Piperazine-derived lipid nanoparticles deliver mRNA to immune cells in  (PMC9376583)
-    Based on the paper, here are the details ... * **Delivery Vector:** Piperazine-derived lipi
-```
-
-**That `/.gxl/` path cannot be read** — `cat` on it returns "No such file" even though `ls /.gxl/`
-lists it. To see the untruncated per-paper answers, use `results`:
-
-```bash
-paperclip results m_4b4632df                       # full output, with real document ids
-paperclip results m_4b4632df --save map.csv        # or export it
-```
-
-## `map`
-
-```text
-map --from RESULTS_ID [OPTIONS] "query"
-
-  --from ID              Result id from a previous search (required)
-  --worker NAME          quick-reader (default) | eligibility-screen | exhaustive-extraction
-  --output_schema JSON   Structured output schema
-  --claim-schema JSON    JSON Schema each exhaustive claim must satisfy
-  --repo NAME            Shared repo receiving validated exhaustive claims
-  --resume MAP_ID        Continue pending work; never reruns successful papers
-  --retry-failed         With --resume, also retry failed papers
-  --cancel MAP_ID        Durably request cancellation; pending work will not start
-  -n, --limit N          Limit number of papers processed
-  --offset N             Skip the first N papers
-  -j, --max-concurrent N Concurrent extraction subagents (default 100, server hard cap 256)
-```
-
-### Workers
-
-| Worker | Use for |
-|---|---|
-| `quick-reader` (default) | Ordinary extraction and per-paper Q&A |
-| `eligibility-screen` | Single-turn structured screening of a full paper against inclusion criteria — the screening step of a systematic review |
-| `exhaustive-extraction` | Multi-turn Claude tool worker that inspects methods, results, tables, figures, and supplements. Slow and thorough; for quantitative extraction |
-
-### Writing the map query
-
-This is where map runs succeed or fail.
-
-- **Enumerate every field you want.** The worker returns what you asked for and nothing else.
-- **Name the section** when you know it: "From the Methods section, extract the cell line, passage
-  number, and transfection reagent."
-- **Ask for the absent case explicitly:** "If the paper does not report a sample size, say
-  'not reported'." Otherwise you cannot distinguish a gap from a miss.
-- Bad: `"Summarize this paper."`
-- Good: `"What delivery vector was used, what cell type was targeted, and what transfection efficiency was reported? State 'not reported' for any field the paper omits."`
-
-### Sizing
-
-Keep `quick-reader` runs to **3–10 papers** for interactive work — one LLM call per paper. For larger
-runs, prefer a single `map` with a higher `-j` over several overlapping map requests; the server caps
-concurrency at 256 and per-user limits may be lower.
-
-After a map completes, answer from its output. Do not follow up by re-reading each paper individually
-— that discards the work you just paid for.
-
-### Structured output
-
-```bash
-paperclip map --worker eligibility-screen \
-  --output_schema '{"decision":"yes|no|uncertain","reason":"string"}' \
-  --from s_abc123 "Apply the protocol eligibility criteria"
-```
-
-```bash
-paperclip map --worker exhaustive-extraction \
-  --repo review \
-  --claim-schema '{"type":"object","required":["type"],"properties":{"type":{"type":"string"}}}' \
-  --from s_yes "Extract all requested claims"
-```
-
-`--repo` plus `--claim-schema` routes validated claims straight into a repo — the machinery behind the
-`paperclip-meta-analysis` workflow. Only reach for it when the user asked for a verified corpus.
-
-### Long runs
-
-```bash
-paperclip map --resume m_abc123                  # continue; successful papers are not redone
-paperclip map --resume m_abc123 --retry-failed   # also retry failures
-paperclip map --cancel m_abc123                  # stop pending work
-```
-
-Resume is durable, so a large extraction that hits a timeout is recoverable — resume it rather than
-restarting.
-
-## `reduce`
-
-```text
-reduce --from MAP_ID [OPTIONS] "question"
-
-  --from ID           Map result id (m_*); defaults to the most recent map
-  --strategy STR      summarize (default) | table | themes | consensus | bullet_points | extract
-  --columns COL,...   Comma-separated columns for the table strategy
-```
-
-| Strategy | Produces |
-|---|---|
-| `summarize` | Integrated narrative across papers |
-| `table` | **Returns prose, not a table** — see below |
-| `themes` | Recurring topics and groupings |
-| `consensus` | Where papers agree and disagree — the right choice for contested findings |
-| `bullet_points` | Condensed list |
-| `extract` | Just the extracted values, minimal prose |
-
-### `--strategy table` does not produce a table
-
-Verified on both 0.7.14 and 0.7.15, with and without `--columns`: the output is multi-paragraph prose
-either way. If you need a comparison table, take `paperclip results m_<id>` and build it yourself.
-
-```bash
-paperclip reduce --from m_def456 --strategy table \
-  --columns "paper,vector,cell type,efficiency,n" \
-  "Compare delivery approaches"
-
-paperclip reduce --from m_def456 --strategy consensus \
-  "Do these studies agree on whether LNP delivery reaches hematopoietic stem cells in vivo?"
-```
-
-`reduce` synthesizes what `map` returned; it does not re-read the papers. If a field is missing from
-the reduce output, it was missing from the map — fix the map query and rerun.
-
-### Reduce embeds citation markers with broken ids
-
-Reduce prose carries inline pins like:
-
-```text
-... cholesterol, DMG-PEG2000, and DOPE or DSPC {{"document_id": "PMC12388", "line": 5}}
-```
-
-**Those document ids are truncated to eight characters and do not resolve.** The paper above is
-`PMC12388858`; `PMC12388` returns `cat: PMC paper not found`. Same for `PMC93765` (really
-`PMC9376583`) and `PMC11843` (really `PMC11843327`). A citation URL built from a reduce marker is a
-dead link.
-
-Use the marker only as a hint about *where* to look. Take real ids from `search`, `results`, or
-`meta.json`, then open the cited line and confirm it before citing:
-
-```bash
-paperclip results m_4b4632df                                  # real ids
-paperclip head -50 /papers/PMC12388858/content.lines
-```
-
-**Reduce output is not citable on its own.** Before quoting a number in your answer, open the paper it
-came from and read the line, then cite that line. Map and reduce are LLM summarizers, and the citation
-contract requires text you have actually seen.
-
-## `results`
-
-```bash
-paperclip results --list                      # recent ids with the command that made each one
-paperclip results s_4a2b61f6                  # view a saved result set
-paperclip results s_4a2b61f6 --save out.csv   # export to CSV
-paperclip results m_def456 --save map.txt     # export to TXT
-```
-
-`--list` output looks like:
-
-```text
-Recent results (20):
-
-  s_3b1a8db3  search -s papers 'somatic hypermutation' -n 2   2026-07-28 01:00
-  s_a5590fe3  grep -l SLC30A8 /papers/                        2026-07-28 00:58
-```
-
-Useful when you lost an id, or want to compare a fresh search against an earlier one.
-
-## `ask-image`
-
-```text
-ask-image PATH "question"
-ask-image --list                 # figures in the current directory (requires cd into a paper)
-
-  --fn describe       Describe the figure
-  --fn extract-data   Extract data from the figure
-```
-
-**Always `ls` first.** Figure filenames come from the publisher, not a `fig1.jpg` convention, and a
-guessed name fails with `Error: Image not found`.
-
-```bash
-paperclip ls /papers/PMC10945750/figures/
-# pnas.2307796121fig01.gif  pnas.2307796121fig01.jpg
-
-paperclip ask-image /papers/PMC10945750/figures/pnas.2307796121fig01.jpg \
-  "What is on each axis, which conditions are compared, and what is the reported effect size?"
-paperclip ask-image /papers/PMC10945750/figures/pnas.2307796121fig01.jpg --fn extract-data
-```
-
-`--list` is documented as an alternative, but it requires a `cd` into the paper directory and `cd`
-does not persist between invocations — use `ls` instead.
-
-Vision extraction from a plot is an estimate. If a number matters, find it in the text or the
-supplements and cite that instead:
-
-```bash
-paperclip ls /papers/PMC10945750/supplements/
-paperclip head -40 /papers/PMC10945750/supplements/<file>
-```
-
-## Cost and failure notes
-
-- One LLM call per paper for `quick-reader`; `exhaustive-extraction` is multi-turn and much heavier.
-- `filter` before `map` when your search returned more than ~10 results — it is cheaper to discard
-  irrelevant papers first.
-- `map` on a `grep` result id works: grep returns `s_*` ids like search does.
-- If papers fail mid-run, `--resume --retry-failed` rather than starting over.
-- An empty per-paper answer usually means the query named a field the paper does not report, not that
-  the reader failed. Ask for an explicit "not reported" to tell the two apart.