From bbb2812248c96aa1521556bb5e43cc1dee2cc85d Mon Sep 17 00:00:00 2001 From: Abel Date: Sat, 10 Oct 2026 14:04:44 +0100 Subject: [PATCH] Simplify onboarding and finish npm publication documentation --- README.md | 40 ++++++++++------ docs/CLIENTS.md | 2 +- docs/PACKAGING.md | 2 +- docs/START_HERE.md | 73 +++++++++++++++++++++++++++++ docs/VERIFICATION.md | 4 +- docs/assets/organizing-workflow.svg | 37 ++++++++++----- 6 files changed, 127 insertions(+), 31 deletions(-) create mode 100644 docs/START_HERE.md diff --git a/README.md b/README.md index 6774bc1..393d37e 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ [![CI](https://github.com/KingPsychopath/raindrop-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/KingPsychopath/raindrop-cli/actions/workflows/ci.yml) [![Release](https://github.com/KingPsychopath/raindrop-cli/actions/workflows/release.yml/badge.svg)](https://github.com/KingPsychopath/raindrop-cli/actions/workflows/release.yml) [![Version](https://img.shields.io/github/v/release/KingPsychopath/raindrop-cli)](https://github.com/KingPsychopath/raindrop-cli/releases/latest) -[![npm](https://img.shields.io/npm/v/@machineyearn/raindrop-cli)](https://www.npmjs.com/package/@machineyearn/raindrop-cli) +[![npm](https://img.shields.io/npm/v/%40machineyearn%2Fraindrop-cli?label=npm)](https://www.npmjs.com/package/@machineyearn/raindrop-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -[![Go Report Card](https://goreportcard.com/badge/github.com/KingPsychopath/raindrop-cli)](https://goreportcard.com/report/github.com/KingPsychopath/raindrop-cli) +[![Go version](https://img.shields.io/github/go-mod/go-version/KingPsychopath/raindrop-cli)](go.mod) Turn a growing [Raindrop.io](https://raindrop.io) library into something easier to use. Search saved links, inspect collections, find cleanup opportunities and review suggestions before making changes. Use it from your terminal or let your favorite agent do the reading and planning. @@ -20,35 +20,45 @@ Turn a growing [Raindrop.io](https://raindrop.io) library into something easier ## Get started -v0.2.0 is available through Homebrew and [native downloads](https://github.com/KingPsychopath/raindrop-cli/releases/tag/v0.2.0). Its npm tarballs are built and verified; registry publication awaits the owner's required npm 2FA setup. Use Homebrew or native binaries meanwhile. [Publishing status and commands](docs/PACKAGING.md#npm-packages). - -Install: +### 1. Install ```sh brew install KingPsychopath/tap/rdrop -# After npm registry publication: Node 22+, optional dependencies enabled: +# Or Node 22+, with optional dependencies enabled: npm install --global @machineyearn/raindrop-cli@0.2.0 rdrop version ``` -Prefer no global npm install? Use `npx --yes @machineyearn/raindrop-cli@0.2.0 COMMAND`. [Native downloads and checksums](https://github.com/KingPsychopath/raindrop-cli/releases/latest) are available for macOS, Linux and Windows on Intel/AMD and ARM. You can also build with `make install`; [packaging details](docs/PACKAGING.md). +Prefer no global install? Use `npx --yes @machineyearn/raindrop-cli@0.2.0 COMMAND`. [Native downloads](https://github.com/KingPsychopath/raindrop-cli/releases/latest) cover macOS, Linux and Windows on Intel/AMD and ARM. [Builds and checksums](docs/PACKAGING.md). + +### 2. Connect Raindrop -Create a token in your [Raindrop integration settings](https://app.raindrop.io/settings/integrations). Put this line in `~/.config/rdrop/env`, with directory permissions `700` and file permissions `600`: +Create a token in your [Raindrop integration settings](https://app.raindrop.io/settings/integrations). Add it to the private file `~/.config/rdrop/env`: ```text RAINDROP_TOKEN=your_token_here ``` -Then try: +Give the directory permissions `700` and the file `600`, then run `rdrop doctor`. Keep the token out of chat and Git. [Setup and troubleshooting](docs/START_HERE.md). -```sh -rdrop doctor -rdrop collections --tree -rdrop search 'type:article #go' --json -rdrop cleanup report --json +### 3. Ask your agent + +Copy this into Codex, Claude or your preferred coding agent. It can help with setup too: + +```text +Set up https://github.com/KingPsychopath/raindrop-cli so you can help +manage my Raindrop library. Use its plugin/MCP when available, otherwise +use the CLI. Check installation and authentication; have me add the token +privately. Use the existing model and configured services first. + +Start with a cleanup report and a small sample. Use my existing tags and +collections. Choose useful tools for search, content, classification and +planning; connect extra model providers, Executor or ACP only if needed. +Show the exact proposed changes and a dry-run. Preserve my tags and notes, +flag uncertain suggestions, and apply only the exact plan I approve. ``` -Environment variables take precedence. Custom token/config paths and redacted diagnostics are documented in [configuration](docs/COMMANDS.md#config). Keep tokens in private configuration, outside chat and Git. +[Connect an agent](docs/CLIENTS.md), or start in your shell with `rdrop collections --tree`, `rdrop search 'type:article #go' --json` and `rdrop cleanup report --json`. ## Choose your workflow diff --git a/docs/CLIENTS.md b/docs/CLIENTS.md index f413d28..381e1c1 100644 --- a/docs/CLIENTS.md +++ b/docs/CLIENTS.md @@ -1,6 +1,6 @@ # Connect your agent -Use the native `rdrop` executable or the pinned npm launcher from a local MCP client. The server starts read-only, reads the normal private CLI configuration, and keeps stdout reserved for MCP messages. v0.2.0 npm publication is currently waiting for the owner's required 2FA setup; use native stdio configuration below until the [publishing status](PACKAGING.md#npm-packages) confirms registry availability. +Use the native `rdrop` executable or the pinned npm launcher from a local MCP client. The server starts read-only, reads the normal private CLI configuration, and keeps stdout reserved for MCP messages. New here? Follow [three-step setup and the copyable agent prompt](START_HERE.md) first. ## Codex and Claude plugins diff --git a/docs/PACKAGING.md b/docs/PACKAGING.md index 95dfb57..f075722 100644 --- a/docs/PACKAGING.md +++ b/docs/PACKAGING.md @@ -18,7 +18,7 @@ The [Homebrew formula](../packaging/homebrew/rdrop.rb) and `KingPsychopath/tap` ## npm packages -v0.2.0 status (2026-10-10): all seven release tarballs are attached to the [GitHub release](https://github.com/KingPsychopath/raindrop-cli/releases/tag/v0.2.0), their checksums and packed installation passed, but npm rejected registry publication until the owner enables 2FA or supplies an eligible granular publishing token. No npm package was published. Homebrew and native archives are available now. +v0.2.0 is published as [@machineyearn/raindrop-cli](https://www.npmjs.com/package/@machineyearn/raindrop-cli) and six native platform packages. Every registry version's SHA-512 matches its exact [GitHub release](https://github.com/KingPsychopath/raindrop-cli/releases/tag/v0.2.0) tarball. Fresh registry installation passed version and read-only MCP catalog checks on macOS arm64; Homebrew and native archives are also available. ```sh node --test packaging/npm/launcher.test.cjs diff --git a/docs/START_HERE.md b/docs/START_HERE.md new file mode 100644 index 0000000..e0637ed --- /dev/null +++ b/docs/START_HERE.md @@ -0,0 +1,73 @@ +# Start here + +Install `rdrop`, connect your Raindrop account, then use your shell or agent. An existing Codex/Claude agent already supplies the model: you do not need another AI account, Laya, Executor or ACP to get started. + +## 1. Install + +Choose one: + +```sh +brew install KingPsychopath/tap/rdrop +# Or Node 22+, with optional dependencies enabled: +npm install --global @machineyearn/raindrop-cli@0.2.0 +rdrop version +``` + +Without a global npm install, replace `rdrop` in the commands below with `npx --yes @machineyearn/raindrop-cli@0.2.0`. [Native downloads, source builds and checksums](PACKAGING.md). + +## 2. Connect Raindrop + +Create a token in [Raindrop's integration settings](https://app.raindrop.io/settings/integrations). On macOS/Linux, prepare a private configuration file: + +```sh +mkdir -p "$HOME/.config/rdrop" +chmod 700 "$HOME/.config/rdrop" +touch "$HOME/.config/rdrop/env" +chmod 600 "$HOME/.config/rdrop/env" +``` + +Open that file in your text editor and add `RAINDROP_TOKEN=your_token_here`, replacing the placeholder privately. On Windows, the default file is `%USERPROFILE%\.config\rdrop\env`; keep it accessible only to your account. Then: + +```sh +rdrop doctor +rdrop cleanup report --json +``` + +The doctor checks configuration and account access without printing the token. The report reads your library; it does not change bookmarks. Environment variables override configuration files. If you use `XDG_CONFIG_HOME` or another location, run `rdrop config paths` to see the paths this installation reads. [Configuration reference](COMMANDS.md#config). + +## 3. Use your agent or shell + +Copy the [setup and organizing prompt from the README](../README.md#3-ask-your-agent) into your agent. It tells the agent to check setup, use existing tools, start with a report and small sample, then show exact changes before applying an approved plan. + +For Codex or Claude, install the [shared plugin](CLIENTS.md#codex-and-claude-plugins). Other local clients can use the [stdio MCP configuration](CLIENTS.md#direct-stdio-configuration). The default MCP server reads and plans. Installing the plugin does not enable writes. + +Or start directly: + +```sh +rdrop collections --tree +rdrop search 'type:article' --json +rdrop cleanup report --json +``` + +Your existing tag names and collection paths are the starting vocabulary. Review a bounded sample before extending organization to the rest of the library. [Reviewed planning and recovery](ORGANIZING.md). + +## Add capabilities when you need them + +| Need | Use | +| --- | --- | +| Raindrop's semantic search, extracted content or AI audits | Add `--official` to `mcp serve` or `agent`; [upstream plan limits apply](OFFICIAL_MCP.md) | +| Run a tool-capable model without an external agent | [`rdrop agent`](MODELS.md#direct-tool-calling-loop) with a hosted or local model | +| Fixed categories with visible uncertainty | [`classify`](MODELS.md#typed-decision-providers) with configured Jev, Laya or Clef | +| Local model inference | [Qwen/Laya setup and verification](VERIFICATION.md#start-the-actual-local-models) | +| Portable tools in Executor | [Executor setup](INTEGRATIONS.md#executor) | +| Give this MCP server to an existing ACP agent | [ACP configuration](INTEGRATIONS.md#acp) | + +These are optional routes. Keep the first setup small, then choose a provider or host for a concrete job. + +## If setup fails + +- **Command not found:** restart the terminal, check the npm/Homebrew bin directory is on PATH, or use `npx`. GUI agents may need an absolute executable path. +- **Missing token or HTTP 401:** inspect `rdrop config paths` and `rdrop config show`, then replace the token in the private file. Do not paste it into chat. +- **Missing npm platform package:** reinstall with `npm install --global --include=optional @machineyearn/raindrop-cli@0.2.0`, or use a native archive. +- **No agent tools:** reload/start a new client session and check its MCP connection. Browser-only clients require a hosted HTTP service; this local server uses stdio. +- **Official/model provider unavailable:** check that provider's configuration and account limits. The shell CLI and normal REST reads do not depend on that provider. diff --git a/docs/VERIFICATION.md b/docs/VERIFICATION.md index c9f4940..73698f2 100644 --- a/docs/VERIFICATION.md +++ b/docs/VERIFICATION.md @@ -4,7 +4,7 @@ The 2026-10-10 check used macOS arm64, Python 3.12.13, Ollama 0.40.2, `qwen3:4b` ## Released executables -The v0.2.0 release is tagged at `c4c997e748655bfa9b615b3d3eb17ea9952cff40`. All 14 native/npm/plugin artifacts were downloaded and checked against the release's `checksums.txt`. The exact release npm tarballs installed offline, reported the release commit, and completed a real MCP stdio handshake with 26 read-only tools. The downloaded native executable also passed the complete three-step Qwen/Laya loop, dry-run and one fixture update described below. This checks package bootstrap and transport independently of model prose. The source archive has its own Homebrew checksum. The tap's source build and formula tests passed in CI and on the tested macOS arm64 host; the installed version is `0.2.0`. +The v0.2.0 release is tagged at `c4c997e748655bfa9b615b3d3eb17ea9952cff40`. All 14 native/npm/plugin artifacts were downloaded and checked against the release's `checksums.txt`. All seven published npm versions have registry SHA-512 integrity matching the exact release tarballs. A fresh registry installation reported the release commit and 26 read-only tools. The exact tarballs also installed offline and completed a real MCP stdio handshake. The downloaded native executable also passed the complete three-step Qwen/Laya loop, dry-run and one fixture update described below. This checks package bootstrap and transport independently of model prose. The source archive has its own Homebrew checksum. The tap's source build and formula tests passed in CI and on the tested macOS arm64 host; the installed version is `0.2.0`. To repeat with the released macOS arm64 executable instead of a development build: @@ -27,7 +27,7 @@ python3 scripts/verify-models.py \ brew test KingPsychopath/tap/rdrop ``` -Choose the matching native archive on other platforms. npm uses exact release tarballs and verifies each packaged executable before running it; registry publication additionally requires npm account 2FA or an eligible granular publishing token. [Distribution and publishing commands](PACKAGING.md). +Choose the matching native archive on other platforms. npm uses exact release tarballs and verifies each packaged executable before running it. The documented `npx --yes @machineyearn/raindrop-cli@0.2.0 version` command passed after registry publication. Publishing requires npm account 2FA or an eligible granular publishing token. [Distribution and publishing commands](PACKAGING.md). ## Start the actual local models diff --git a/docs/assets/organizing-workflow.svg b/docs/assets/organizing-workflow.svg index d26ff21..07dea96 100644 --- a/docs/assets/organizing-workflow.svg +++ b/docs/assets/organizing-workflow.svg @@ -1,14 +1,27 @@ - - Your links, your rules, a reviewed library - Find saved links, review suggested tags and collections, then apply the exact changes while preserving existing tags. - - - A library that still feels like yours. - - 01 / FIND02 / REVIEW03 / ORGANIZE - See what you savedMake the choices yoursApply what you approved - Search links and collections.Find gaps in your library.Use existing tags and folders.Keep uncertain ideas visible.Check the exact changes first.Keep existing tags and notes. - Shell or your favorite agentLocal models or hosted AIA plan you can inspect - + + Inspect, suggest, review and apply + An example reviewed plan adds a reference tag and moves a Go HTTP reference bookmark to Reference, preserving its personal tag and notes. Review the exact changes and dry-run before applying. + + + + + + + + rdrop - Review before you apply + + 01 Inspect02 Suggest03 Review & apply + + Go HTTP reference + tag: personal + folder: Unsorted + add: reference + move: Reference + keep: personal + Review 1 bookmark + Dry-run the exact plan + Apply when approved + Your tags and notes stay. Uncertain suggestions stay visible. +