papiers 0.1.4 → 0.1.5

package/README.md

@@ -2,6 +2,9 @@
 
 Search and read your Papiers library from the terminal.
 
+The CLI is read-only: it can inspect your saved documents, highlights, notes,
+and conversations, but it cannot change your library.
+
 ## Install
 
 ```bash
@@ -10,17 +13,60 @@ npm install -g papiers
 
 Requires Node.js 22 or newer.
 
-## Sign in
+## First run
 
-In Papiers, open Settings -> API tokens, create a token, then sign in:
+1. In Papiers, open Settings -> API tokens and create a token.
+2. Sign in and check the connection:
 
 ```bash
 papiers auth login
+papiers auth status
+papiers doctor
 ```
 
 Paste the token when prompted. The CLI saves it locally so you do not need to
 paste it again.
 
+3. Explore your library with human-readable output:
+
+```bash
+# See what you saved recently.
+papiers list --kind document --limit 5 --pretty
+
+# Search across documents, passages, highlights, notes, and conversations.
+papiers search "retrieval augmented generation" --limit 5 --pretty
+
+# List notes, then read one using the nte_... ID from the result.
+papiers list --kind note --limit 5 --pretty
+papiers read nte_... --format markdown --pretty
+```
+
+Run `papiers <command> --help` for command-specific options or
+`papiers help --all` for the complete CLI reference.
+
+## Common workflows
+
+```bash
+# Recent highlights.
+papiers list --kind highlight --since 30d --limit 10 --pretty
+
+# Read the matching passages from a search through stdin.
+papiers search "retrieval" --kind passage --limit 5 --passage-ids \
+  | papiers read @- --format plain --pretty
+
+# Read document metadata without fetching its full content.
+papiers read doc_... --format metadata --pretty
+```
+
+Data commands emit stable JSON by default. Use `--pretty` for terminal reading;
+use `--json`, `--ids`, `--ids0`, and `--doc-ids` for scripts and pipelines.
+
+To forget the locally saved token:
+
+```bash
+papiers auth logout
+```
+
 ## Use with an AI agent
 
 This is what `papiers` is really for. Point a coding or research agent (Claude
@@ -33,9 +79,26 @@ The package ships a ready-to-use agent skill at
 encodes the loop — survey what you've been reading, search across passages +
 highlights + notes + conversations in one ranking, then read and cite your own
 sources.
-Hand that file to your agent (or drop it in its skills directory) and ask it to
-propose an idea, design an experiment, or review a draft. It will think with
-your library, not around it.
+
+After a global install, locate the packaged skill under the npm root:
+
+```bash
+PAPIERS_ROOT="$(npm root -g)/papiers"
+
+# Claude Code, project-local skill
+mkdir -p .claude/skills/papiers-research
+cp "$PAPIERS_ROOT/skills/papiers-research/SKILL.md" \
+  .claude/skills/papiers-research/SKILL.md
+
+# Codex, project-local skill
+mkdir -p .codex/skills/papiers-research
+cp "$PAPIERS_ROOT/skills/papiers-research/SKILL.md" \
+  .codex/skills/papiers-research/SKILL.md
+```
+
+For another agent, add the same file through its normal skill or project
+instructions mechanism. Then ask the agent to propose an idea, design an
+experiment, or review a draft. It will think with your library, not around it.
 
 ```bash
 # the agent only needs your token in its environment:
@@ -45,18 +108,28 @@ export PAPIERS_TOKEN=pap_live_...
 Every data command emits a stable JSON envelope (`--json` makes errors JSON
 too), so an agent can learn the whole tool from `papiers --help --all` alone.
 
-## Common Commands
+## Automation
 
 ```bash
-papiers list --kind document --limit 5
-papiers search "retrieval augmented generation" --limit 10
-papiers read doc_... --format markdown
-papiers doctor   # check your setup and connection
+# Keep the token in the process environment rather than passing it as an
+# argument. Do not commit it to source control.
+export PAPIERS_TOKEN=pap_live_...
+papiers search "mixture of experts" --limit 10 --json
 ```
 
-Use `--json` for stable machine-readable output. Use `--ids`, `--ids0`, and
-`--doc-ids` to pipe results between commands.
-
-## Automation
-
-For scripts and automation, set `PAPIERS_TOKEN` and pass `--json` for stable machine-readable output.
+`PAPIERS_TOKEN` takes precedence over a token saved by `papiers auth login`.
+Run `papiers doctor` to see which token source and API endpoint are active.
+
+## Troubleshooting
+
+- **`papiers: command not found`:** run `npm prefix -g` and make sure that
+  installation's binary directory is on `PATH`.
+- **Unsupported Node.js version:** run `node --version` and install Node.js 22
+  or newer.
+- **Authentication failed:** run `papiers auth status`. If necessary, run
+  `papiers auth logout`, create a fresh token in Papiers, and sign in again.
+- **Wrong token or endpoint:** run `papiers doctor`. Unset `PAPIERS_TOKEN` or
+  `PAPIERS_API_BASE_URL` if an automation environment is overriding your saved
+  login or the production endpoint.
+- **Connection or API error:** run `papiers doctor`, then retry the failing
+  command with `--json` to get a machine-readable error and request ID.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papiers",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Read-only CLI for your Papiers library.",
   "license": "UNLICENSED",
   "homepage": "https://papiers.ai",