neodrop-cli 1.1.0

package/lib/api.mjs

@@ -0,0 +1,104 @@
+// tRPC 11 HTTP 调用最小封装（适配 backend 配置的 superjson transformer）。
+//
+// URL 形态：
+//   - query:    GET  /trpc/<proc>?input=<urlencoded {json:<input>}>
+//   - mutation: POST /trpc/<proc>  body = {json:<input>}
+//
+// 响应形态（superjson）：
+//   - 成功：{ result: { data: { json: <T>, meta?: {...} } } }
+//   - 失败：{ error: { json: { message, code, data: {...} } } }
+//
+// 入参 / 出参的 superjson `meta` 字段用于 Date 等非 JSON 类型还原，CLI 用不上
+// （凭证 expiresAt 直接用 ISO 字符串），这里只取 `json` 字段。
+//
+// 零运行时依赖：用 Node 原生 fetch（Node 18+），不引第三方 HTTP 库。
+
+export class ApiError extends Error {
+  // tRPC 业务错误（HTTP >= 400 或 body.error 非空）。
+  // code 来自 tRPC 的错误码（'UNAUTHORIZED' / 'NOT_FOUND' / 'BAD_REQUEST' 等），
+  // CLI 上层可据此分流（如 401 提示重 login）。
+  constructor(message, code = "", httpStatus = 0) {
+    super(code ? `[${code}] ${message}` : message);
+    this.name = "ApiError";
+    this.code = code;
+    this.httpStatus = httpStatus;
+  }
+}
+
+function buildUrl(apiOrigin, proc, inputValue) {
+  const base = `${apiOrigin.replace(/\/+$/, "")}/trpc/${proc}`;
+  if (inputValue === undefined) return base;
+  // superjson 入参 wrapper：{ json: <value> }
+  const qs = new URLSearchParams({ input: JSON.stringify({ json: inputValue }) });
+  return `${base}?${qs.toString()}`;
+}
+
+// Cloudflare WAF 看到默认 UA 会按 bot 拒（HTTP 403 + error code 1010）。给一个
+// 老实的客户端身份——告诉 CF/origin「这是 neodrop-cli」，便于排查与白名单。
+// 改 UA 不是为了伪装，是为了通过基础的 client fingerprint check。
+const USER_AGENT = "neodrop-cli/1.0 (+https://github.com/NeoDropAI/neodrop-skills)";
+
+async function doRequest({ method, url, token, body }) {
+  const headers = {
+    "content-type": "application/json",
+    "user-agent": USER_AGENT,
+    accept: "application/json",
+  };
+  if (token) headers.authorization = `Bearer ${token}`;
+
+  // 一次 transparent retry——线上 Cloudflare/upstream 偶发 TLS-layer 抖动
+  // （"EOF occurred in violation of protocol" 等）。mutation 也加 retry：tRPC
+  // mutation 在网络抖动 + 业务层未提交时是幂等可重的（最多多签发一个 PAT/订阅，
+  // 可接受代价）。注意 fetch 对 4xx/5xx 不抛错——那由 handleResponse 处理，
+  // 这里只 retry 真正的网络层异常。
+  let lastErr;
+  for (let i = 0; i < 2; i++) {
+    try {
+      return await fetch(url, { method, headers, body, signal: AbortSignal.timeout(30000) });
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  // Node fetch 把真正的原因藏在 err.cause（如 ECONNREFUSED / ENOTFOUND /
+  // self-signed certificate）；err.message 通常只是笼统的 "fetch failed"。
+  const cause = lastErr?.cause;
+  const detail = cause?.code || cause?.message || lastErr?.message || String(lastErr);
+  throw new Error(`连接失败：${detail}`);
+}
+
+async function handleResponse(res) {
+  const text = await res.text();
+  let body = null;
+  if (text) {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      throw new Error(`非 JSON 响应（HTTP ${res.status}）：${text.slice(0, 200)}`);
+    }
+  }
+
+  if (res.status >= 400 || (body && body.error)) {
+    const err = (body && body.error) || {};
+    const errJson = err.json || {};
+    const msg = errJson.message || err.message || `HTTP ${res.status}`;
+    const code = (errJson.data && errJson.data.code) || err.code || "";
+    throw new ApiError(msg, code, res.status);
+  }
+
+  // superjson 响应剥层
+  return body.result.data.json;
+}
+
+export async function trpcQuery(opts, proc, inputValue) {
+  const url = buildUrl(opts.apiOrigin, proc, inputValue);
+  const res = await doRequest({ method: "GET", url, token: opts.token });
+  return handleResponse(res);
+}
+
+export async function trpcMutation(opts, proc, inputValue) {
+  const url = buildUrl(opts.apiOrigin, proc); // mutation 不走 query input
+  // mutation 永远发 JSON body：input 为 undefined 时发 {"json": null}
+  const body = JSON.stringify({ json: inputValue === undefined ? null : inputValue });
+  const res = await doRequest({ method: "POST", url, token: opts.token, body });
+  return handleResponse(res);
+}

package/lib/credentials.mjs

@@ -0,0 +1,58 @@
+// 本地凭证（~/.neodrop/credentials.json，chmod 0600）。
+//
+// 只支持单一 active token——切换 server / 换号都走 logout → login。
+//
+// 凭证 schema：
+//   webOrigin  string  产品域（neodrop.ai；本地 dev 4001）
+//   apiOrigin  string  API 域（api.neodrop.ai；本地 dev 3001）—— 与 web 拆开是因为部署不同域
+//   token      string  PAT 明文，仅本机；权限 0600
+//   tokenId    string  用于 logout / 远程撤销
+//   name       string  在 /settings/cli-tokens 上展示的客户端名
+//   expiresAt  string  ISO 8601，默认 90 天
+//   createdAt  string  ISO 8601
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const FILE_DIR = join(homedir(), ".neodrop");
+const FILE_PATH = join(FILE_DIR, "credentials.json");
+
+export function credentialsPath() {
+  return FILE_PATH;
+}
+
+export function readCredentials() {
+  if (!existsSync(FILE_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync(FILE_PATH, "utf-8"));
+  } catch (err) {
+    throw new Error(`无法解析 ${FILE_PATH}：${err.message}`);
+  }
+}
+
+// 原子写：写临时文件 → chmod 0600 → rename。chmod 在 rename 之前完成，确保最终
+// 文件出现的瞬间权限就是 0600，不存在其他进程能读到 world-readable 的窗口。
+export function writeCredentials(creds) {
+  mkdirSync(FILE_DIR, { recursive: true });
+  const tmp = `${FILE_PATH}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(creds, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, FILE_PATH);
+}
+
+export function clearCredentials() {
+  try {
+    unlinkSync(FILE_PATH);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+}
+
+export function requireCredentials() {
+  const creds = readCredentials();
+  if (creds === null) {
+    throw new Error("未登录。先运行：npx neodrop-cli login");
+  }
+  return creds;
+}

package/lib/install-skill.mjs

@@ -0,0 +1,42 @@
+// 把 SKILL.md + references/ 拷进 agent 的 skill 目录，让 `npx neodrop-cli` 一条命令
+// 既装好 CLI 又装好 skill 描述。
+//
+// npm/npx 只分发「可执行文件」；而 Claude Code 等 agent 的 skill 是 SKILL.md +
+// references/ 这组文件落进 agent 的 skill 目录后才会被路由。两条分发渠道本来是
+// 分开的，这个命令把它们合并成一步。
+//
+// 默认目标 ~/.claude/skills/neodrop-cli/（Claude Code 约定）；--dest 可改到别的
+// agent 的 skill 目录。目录名固定 neodrop-cli，与 SKILL.md frontmatter 的 name 一致。
+
+import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function defaultSkillDest() {
+  return join(homedir(), ".claude", "skills", "neodrop-cli");
+}
+
+export function installSkill({ dest } = {}) {
+  // 包根目录 = 本文件所在 lib/ 的上一层（bin/ 与 lib/ 与 SKILL.md 同级）
+  const here = dirname(fileURLToPath(import.meta.url)); // .../lib
+  const pkgRoot = dirname(here);
+  const target = dest || defaultSkillDest();
+
+  const skillSrc = join(pkgRoot, "SKILL.md");
+  if (!existsSync(skillSrc)) {
+    throw new Error(`找不到 SKILL.md（期望在 ${skillSrc}）；npm 包可能未按 files 白名单打进 SKILL.md`);
+  }
+
+  mkdirSync(target, { recursive: true });
+  cpSync(skillSrc, join(target, "SKILL.md"));
+
+  const refSrc = join(pkgRoot, "references");
+  const copied = ["SKILL.md"];
+  if (existsSync(refSrc)) {
+    cpSync(refSrc, join(target, "references"), { recursive: true });
+    copied.push("references/");
+  }
+
+  return { target, copied };
+}

package/lib/origins.mjs

@@ -0,0 +1,32 @@
+// Neodrop 部署的 web origin（产品域）与 api origin（backend 域）解耦。
+//
+// 线上：web = https://neodrop.ai，api = https://api.neodrop.ai
+// 本地 dev：web = http://localhost:4001，api = http://localhost:3001
+//
+// CLI 让用户显式传 --api；不传时按 web origin 启发式推断。self-host 用户默认
+// 假设 backend 反代到 web 同域 /trpc/*，需要时用 --api 覆盖。
+
+export function inferApiOrigin(webOrigin) {
+  let parsed;
+  try {
+    parsed = new URL(webOrigin);
+  } catch {
+    return webOrigin.replace(/\/+$/, "");
+  }
+  const host = (parsed.hostname || "").toLowerCase();
+  const port = parsed.port;
+  const scheme = parsed.protocol.replace(/:$/, "");
+
+  // 线上 neodrop.ai → api.neodrop.ai
+  if (host === "neodrop.ai") {
+    return `${scheme}://api.neodrop.ai`;
+  }
+
+  // 本地 dev：localhost:4001 / 127.0.0.1:4001 → 同 host 3001
+  if ((host === "localhost" || host === "127.0.0.1") && port === "4001") {
+    return `${scheme}://${host}:3001`;
+  }
+
+  // 其他（self-host 反代等）：默认与 web 同域，假设 /trpc/* 反代到 backend。
+  return webOrigin.replace(/\/+$/, "");
+}

package/lib/output.mjs

@@ -0,0 +1,19 @@
+// 统一输出：stdout = JSON（AI 直接 JSON.parse），stderr = 日志/提示。
+//
+// 默认单行 JSON；--pretty 切 2 空格缩进 JSON——两者都是合法 JSON，AI 不需要
+// flag 切换也能解析。
+
+let pretty = false;
+
+export function setPretty(value) {
+  pretty = Boolean(value);
+}
+
+export function emit(data) {
+  if (data === null || data === undefined) return;
+  process.stdout.write(`${JSON.stringify(data, null, pretty ? 2 : undefined)}\n`);
+}
+
+export function note(msg, end = "\n") {
+  process.stderr.write(msg + end);
+}

package/lib/web-urls.mjs

@@ -0,0 +1,30 @@
+// Neodrop 前端 URL 拼装：用户拿到 id 后能直接得到一条可点击的网页链接。
+//
+// 为什么放 skill 而不是后端 response：URL 路径（`/post/<id>` / `/channel/<id>` /
+// `/user/<id>`）是前端的渲染契约，不是数据契约——`grain.id` 是稳定的数据；前端
+// 明天可以把路由改成 `/post/<id>` 而无需后端发新版 API。把路由塞进 response 会让
+// backend 反向依赖前端渲染。这里给 CLI 内部用，作为 stderr 上的人类可读提示。
+//
+// 路径权威源 = `apps/web/src/app/[locale]/<route>/[id]/page.tsx`：
+//   post / grain  → `/post/<id>`
+//   channel       → `/channel/<id>`
+//   user          → `/user/<id>`
+//
+// 注意：CLI 不挂 locale 前缀（neodrop.ai 的 localePrefix='as-needed'，默认 locale
+// `en` 落到无前缀路径；其它 locale 由前端按用户偏好做客户端 redirect）。
+
+function strip(origin) {
+  return origin.replace(/\/+$/, "");
+}
+
+export function postUrl(webOrigin, postId) {
+  return `${strip(webOrigin)}/post/${postId}`;
+}
+
+export function channelUrl(webOrigin, channelId) {
+  return `${strip(webOrigin)}/channel/${channelId}`;
+}
+
+export function userUrl(webOrigin, userId) {
+  return `${strip(webOrigin)}/user/${userId}`;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "neodrop-cli",
+  "version": "1.1.0",
+  "description": "Neodrop (neodrop.ai) CLI — let your AI agent (Claude Code / Cursor / Codex) browse channels, read posts, manage subscriptions and create channels as you. stdout is always valid JSON. npx neodrop-cli login and go.",
+  "type": "module",
+  "bin": {
+    "neodrop": "bin/neodrop.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "SKILL.md",
+    "references/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "neodrop",
+    "cli",
+    "ai-agent",
+    "claude-code",
+    "skill",
+    "trpc"
+  ],
+  "homepage": "https://github.com/NeoDropAI/neodrop-skills/tree/main/skills/neodrop-cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NeoDropAI/neodrop-skills.git",
+    "directory": "skills/neodrop-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/NeoDropAI/neodrop-skills/issues"
+  },
+  "license": "MIT"
+}

package/references/auth.md

@@ -0,0 +1,84 @@
+# Login & credentials (auth)
+
+## The only login flow: session polling
+
+```bash
+npx neodrop-cli login
+```
+
+No flags, no mode branches. The CLI does this:
+
+1. Calls the backend `cliToken.startSession` to create a one-time session (256-bit random sessionId, valid 10 minutes), and receives a **private claim secret `pollSecret` handed only to this CLI process** (never in the URL).
+2. Prints a `https://neodrop.ai/cli-auth?session=<sid>` verification URL to stderr (the URL carries only the sessionId, no pollSecret).
+3. Polls `cliToken.pollSession` roughly every 2 s with `{sessionId, pollSecret}`, waiting for approval.
+4. The user opens the URL in any browser → signs in → lands on the consent page → sees the CLI's self-reported `clientName` → **ticks "this is the CLI I just started"** → approves.
+5. The CLI receives the PAT → writes it to `~/.neodrop/credentials.json` (`chmod 0600`).
+
+Properties:
+
+- **No auto-launched browser** — it only prints the URL; the user copies it (same machine / phone / another device).
+- **No local HTTP server / callback** — the CLI polls the backend one-way; the browser never connects back to the CLI machine.
+- **No token in a URL or browser history** — the plaintext token only ever travels over the CLI ↔ backend HTTPS API call.
+- **Claiming requires the pollSecret** — polling must return the private `pollSecret` from `startSession` (the backend stores only its hash); the URL carries only the sessionId, so even a leaked/forwarded/screenshotted URL can't claim the token.
+- **Single claim** — the moment the CLI's first poll receives the token, the backend wipes the `plaintextToken` field.
+- **Session expires in 10 minutes** — if it lapses, rerun `login`.
+
+## Credential file
+
+```jsonc
+~/.neodrop/credentials.json
+{
+  "webOrigin": "https://neodrop.ai",
+  "apiOrigin": "https://api.neodrop.ai",
+  "token": "grain_pat_…",          // plaintext PAT, local only; mode 0600
+  "tokenId": "tok_…",              // used for logout / remote revoke
+  "name": "Claude Code @ macbook",  // client name shown on /settings/cli-tokens
+  "expiresAt": "2026-09-01T…Z",    // 90 days by default
+  "createdAt": "2026-06-04T…Z"
+}
+```
+
+## Across machines: scp the credential file
+
+Cloud sandboxes / CI / remote agents / any machine with no browser but SSH access: log in once locally, then scp it over:
+
+```bash
+# Local machine (has a browser, already logged in):
+scp ~/.neodrop/credentials.json agent-box:~/.neodrop/credentials.json
+ssh agent-box 'chmod 600 ~/.neodrop/credentials.json && npx neodrop-cli whoami'
+```
+
+The credential file *is* the credential — the CLI has no dedicated `import` command because `cp` is enough. **A moved PAT equals your login identity**, so transfer it over SSH / an encrypted channel. A headless machine can `npx neodrop-cli logout` to revoke the token when done, then get a fresh one next time.
+
+## Security model
+
+| Risk | Defense |
+|---|---|
+| Someone sends you a malicious cli-auth URL to trick you into approving | The consent page forces the "this is the CLI I just started" checkbox + displays `clientName` for you to recognize |
+| A leaked session-id URL is replayed to claim the token | The browser-visible sessionId is separated from the CLI-private `pollSecret` — claiming requires the pollSecret (the backend verifies its hash), which the URL never contains; plus single-claim + 10-minute expiry |
+| A PAT recursively issuing new PATs | `approveSession` rejects requests whose `ctx.sessionId.startsWith('pat:')`, letting only browser sessions through |
+| A PAT file sitting in plaintext locally | Written with `chmod 0600`, per the `~/.aws/credentials` convention |
+| `startSession` being spammed | Backend IP-level rate limit (10 / min) |
+| Cross-user privilege escalation | Each procedure's own `where: { userId: ctx.userId }` guard |
+
+The consent page **untrustedly** shows the CLI's self-reported `clientName` (any script can pass `--name "Claude Code"` to spoof it) — which is exactly why the confirmation checkbox is mandatory. **The user must personally confirm** the clientName matches the command they just ran.
+
+## Self-hosting
+
+```bash
+# Option A — environment variable
+NEODROP_SERVER=https://your-neodrop.example.com npx neodrop-cli login
+
+# Option B — login flag
+npx neodrop-cli login --server https://your-neodrop.example.com
+```
+
+The API origin is inferred from the web origin heuristically (`neodrop.ai` → `api.neodrop.ai`; `localhost:4001` → `localhost:3001`; otherwise same as the web origin). If your API host differs, pass `--api <url>` or set `NEODROP_API`.
+
+## Revoke & rotate
+
+- Local logout: `npx neodrop-cli logout` (remote revoke + clears the local credential).
+- Web revoke: [neodrop.ai/settings/cli-tokens](https://neodrop.ai/settings/cli-tokens).
+- See which PATs you've issued: `npx neodrop-cli tokens list`.
+- Revoke a PAT elsewhere: `npx neodrop-cli tokens revoke <id>`.
+- PATs last 90 days by default; just `login` again when one expires.

package/references/commands.md

@@ -0,0 +1,74 @@
+# neodrop-cli command reference
+
+> Invocation convention: use `npx neodrop-cli <command>` (see [SKILL.md → How to invoke](../SKILL.md#how-to-invoke)).
+> Equivalent explicit package + bin form: `npx -p neodrop-cli neodrop <command>`.
+> Examples below are written as `neodrop <command>`.
+
+## identity
+
+```bash
+neodrop me                    # current user info (user.getMe)
+neodrop whoami                # me + token metadata (credential + expiry)
+neodrop tokens list           # every PAT you've issued
+neodrop tokens revoke <id>    # revoke a PAT; if it's this machine's token, the local credential is cleared too
+```
+
+## channels
+
+### View / search
+
+```bash
+neodrop channels list --mine                       # channels you own
+neodrop channels list --locale en --limit 20       # public channels, paginated
+neodrop channels get <channelId>                   # single channel detail (incl. requirement.public)
+neodrop channels categories                        # all categories
+neodrop channels by-category tech --sort latest --limit 20
+
+neodrop channels search "AI weekly" --locale en --limit 10
+```
+
+### Write
+
+```bash
+neodrop channels create --name "AI industry tracker" --description "..." --locale en
+neodrop channels create --json '{"name":"X","locale":"en","type":"PRIVATE"}'
+neodrop channels subscribe <channelId>
+neodrop channels unsubscribe <channelId>
+```
+
+**Default locale**: `channels list` defaults to `en`, matching the product's default public pool. `channels search` and `channels by-category` omit locale when `--locale` is not provided and let the backend decide. Pass `--locale en` (etc.) explicitly to query the public pool across locales.
+
+## posts
+
+> The content unit is called a **post** on Neodrop. The old command name `grains` is kept as a backward-compatible alias, but new code should use `posts`.
+
+```bash
+neodrop posts list --limit 10                     # public feed
+neodrop posts list --subscribed --limit 10        # your subscriptions (= neodrop feed --limit 10)
+neodrop posts list --channel <channelId> --limit 10
+neodrop posts get <postId>
+neodrop posts search "Apple Intelligence" --limit 10
+
+neodrop feed --limit 10                            # alias for posts list --subscribed
+```
+
+## api
+
+For tRPC procedures with no sugar command, fall back to `api`:
+
+```bash
+neodrop api channel.update --json '{"id":"<chId>","name":"New name"}' --mutation
+neodrop api user.getLinkedAccounts                 # any query
+echo '{...}' | neodrop api channel.create --stdin --mutation
+```
+
+- **Defaults to a GET query** — a mutation (write) MUST add `--mutation` explicitly, or the backend routes it as a query and rejects it.
+- Pass complex input with `--json '...'` inline, or `--stdin` to read from standard input (great for heredocs / pipelines).
+- To find a procedure's full name, check the main repo's `packages/backend/src/api/trpc/routers.ts`, or probe with `curl /api/trpc/<router>.<procedure>?input=...` against a dev backend.
+
+## Global
+
+```bash
+neodrop --pretty <cmd>          # indented JSON for humans (still valid JSON)
+neodrop <cmd> --help            # subcommand arguments
+```

package/references/troubleshooting.md

@@ -0,0 +1,37 @@
+# Troubleshooting
+
+When the CLI errors, **first read the error code in brackets on stderr**, then match it below.
+
+## Auth / login
+
+| Symptom | Meaning | Fix |
+|---|---|---|
+| `not logged in` | `~/.neodrop/credentials.json` wasn't found | Tell the user to run `npx neodrop-cli login` |
+| Consent page says "invalid authorization request / missing valid session parameter" | The opened URL has no valid `?session=cas_...`. **Most often the CLI is outdated** — old versions used a callback mode and print `/cli-auth?callback=&state=&name=`, which the new session-polling consent page rejects; otherwise the `?session=` tail was dropped when copying | Check the URL shape: ① `?callback=&state=` (or those keys all empty) → the CLI is stale (npx hit a cached old version); force the latest with `npx neodrop-cli@latest login`, the new link looks like `?session=cas_...`; ② already `?session=` but partial → rerun `login` and copy the whole line. Links are valid 10 minutes; reissue if expired |
+| `[UNAUTHORIZED]` | PAT is invalid (expired / revoked / user logged out) | Ask the user to `login` again; for headless environments see [auth.md](auth.md) |
+| `[FORBIDDEN]` | The PAT lacks permission for this procedure (e.g. an admin procedure) | Don't re-login — a PAT is always a regular-user identity; switch commands or have a real admin do it |
+
+## Network / domains
+
+| Symptom | Fix |
+|---|---|
+| `connection failed: ECONNREFUSED` | Backend isn't up / wrong port. Local dev: re-login with `NEODROP_SERVER=http://localhost:4001 npx neodrop-cli login` |
+| `connection failed: ENOTFOUND` / `EAI_AGAIN` | DNS failure; check whether `apiOrigin` is wrong (see `whoami` output) |
+| `connection failed: self-signed certificate` / `unable to verify ... certificate` | A self-hosted instance uses a self-signed cert; unsupported today — use LetsEncrypt or a reverse proxy with a valid cert |
+| `connection failed: HeadersTimeoutError` / hangs ~30 s then errors | Network flakiness / unresponsive backend (the CLI times out a single request at 30 s and already retried once); try again later |
+
+## Backend business errors
+
+| Symptom | Meaning | Fix |
+|---|---|---|
+| `[NOT_FOUND]` | id / slug doesn't exist | List with `channels list` / `posts list` first to verify the id |
+| `[BAD_REQUEST]` | Input schema is wrong (most common with `--json`) | Read the stderr detail; cross-check `neodrop <cmd> --help`; for complex input, get it working with a sugar command first, then drop to `--json` |
+| `[INTERNAL_SERVER_ERROR]` | The backend crashed | Retry once; if it persists, open an issue with the full stderr |
+
+## Environment
+
+| Symptom | Fix |
+|---|---|
+| `npx: command not found` / unsupported syntax / `fetch is not defined` | Node is missing or too old; install Node 18+ (`node --version` to check) |
+| `npx` stuck downloading / running a stale version | npx caches packages; force the latest with `npx neodrop-cli@latest <cmd>`, or install globally with `npm i -g neodrop-cli` |
+| stdout looks empty / isn't JSON | The command actually failed — read stderr; the CLI only writes JSON to stdout on success |

package/references/url-routing.md

@@ -0,0 +1,24 @@
+# Neodrop URL → CLI command mapping
+
+When the user pastes a Neodrop link and wants details, extract the id from the path and call the matching command below.
+
+| URL pattern | id meaning | Call |
+|---|---|---|
+| `neodrop.ai/post/<id>` | post id | `posts get <id>` |
+| `neodrop.ai/feed/<id>` | legacy post id | `posts get <id>` |
+| `neodrop.ai/channel/<id>` | channelId | `channels get <id>` |
+| `neodrop.ai/user/<id>` | userId | No dedicated sugar command — use `api user.getById --json '{"id":"<id>"}'` |
+| `neodrop.ai/discover` | public discover page | `channels list --locale <l>` / `channels by-category <slug>`, per the user's context |
+| `neodrop.ai/search?q=...` | site-wide search | `channels search "<q>"` + `posts search "<q>"` combined |
+
+## Reverse: how to give the user a link back
+
+**Don't hand-craft from memory** — `posts get` / `channels get` / `me` already print a `🔗 <canonical-url>` line to stderr; quote that line directly.
+
+Don't assemble `/grain/<id>` or legacy `/feed/<id>` (both migrate to `/post/<id>`) or guess other paths. If a command didn't print a canonical URL, derive it from the table above:
+
+- channelId → `https://neodrop.ai/channel/<id>`
+- postId → `https://neodrop.ai/post/<id>`
+- userId → `https://neodrop.ai/user/<id>`
+
+For a self-hosted instance, read the `webOrigin` from the credential (shown in `neodrop whoami` output).