@elmundi/ship-cli 0.7.0 → 0.8.1

package/README.md

@@ -1,60 +1,91 @@
 # @elmundi/ship-cli
 
-Command-line entry to the Ship methodology: **one HTTP API** (FastAPI) for **search, fetch, feedback, patterns, tools, workflows, collections** — or read catalogs from disk inside a Ship clone / `SHIP_REPO` — plus **`ship init`** to inject API usage into agent configs.
+**Ship** in your repository: agents get a standing policy to call the **methodology HTTP API** (semantic search, full doc fetch, catalog bodies, retro feedback) via the **`ship`** CLI and the URLs/snippets `ship init` writes.
 
-Published under the npm org **[elmundi](https://www.npmjs.com/org/elmundi)**; the binary name remains **`ship`**.
+Published as **`@elmundi/ship-cli`** under the [elmundi](https://www.npmjs.com/org/elmundi) org; the binary name is **`ship`**.
 
 ## Requirements
 
-- **Node.js 20+** (matches Ship CI and typical adopters).
+- **Node.js 20+**
 
 ## Install
 
-After the package is [published to npm](https://www.npmjs.com/package/@elmundi/ship-cli):
-
 ```bash
 npm install -g @elmundi/ship-cli
-# or, without a global install:
+# or one-off:
 npx @elmundi/ship-cli help
 ```
 
-From a full **Ship** monorepo clone you can still run `npm run ship -- …` from the repo root (workspace).
+## Bring Ship into your project (main path)
 
-## Adopt without cloning the whole monorepo
+You **do not** need the Ship monorepo cloned for day-to-day use. Work in **your product repo** and wire agents to the same methodology API the CLI uses.
 
-1. Install the CLI (`npm i -g @elmundi/ship-cli` or use `npx @elmundi/ship-cli`).
-2. From **any** directory, point **`SHIP_API_BASE`** at the **deployed methodology API** and list patterns or catalogs (same server as search):
+### 1. Pick the API URL
 
-   ```bash
-   SHIP_API_BASE=https://your-ship-api.example.com npx @elmundi/ship-cli patterns list
-   SHIP_API_BASE=https://your-ship-api.example.com npx @elmundi/ship-cli tools list
-   ```
+- **`SHIP_API_BASE`** — env var the CLI and injected snippets use (no trailing slash).
+- Or pass **`--base-url`** on each command.
+- Default matches other Ship tooling (public methodology host unless you override for local FastAPI).
 
-3. Optional: work from a **local** Ship checkout (or **`SHIP_REPO`**) to read manifests from disk without calling the API.
+### 2. Preview what `ship init` will change
 
-4. In your **product** repository, wire agents to the methodology API:
+From the **root of the repo** you want agents to use:
 
-   ```bash
-   cd /path/to/your-product
-   npx @elmundi/ship-cli init --yes
-   ```
+```bash
+cd /path/to/your-product
+npx @elmundi/ship-cli init --dry-run
+```
 
-   Use **`--dry-run`** first to preview; **`--yes`** skips prompts and writes files — see `ship init help`.
+`ship init` **detects what is already in the tree** and only plans injections for those stacks:
 
-## Which commands need what
+| If the repo has… | `ship init` can add… |
+|------------------|----------------------|
+| `.cursor/` | Cursor rule **`.cursor/rules/ship-methodology-api.mdc`** |
+| **`AGENTS.md`** | Appended section (Codex-style / generic agents file) |
+| **`CLAUDE.md`** | Appended section |
+| **`.codex/`** | **`SHIP_API.md`** under `.codex/` |
+| **`.github/copilot-instructions.md`** | Appended section |
 
-| Command | Needs |
-|--------|--------|
-| `ship patterns …`, `ship tools …`, `ship workflows …`, `ship collections …` | Same **`SHIP_API_BASE`** as docs when not on disk. **Local:** cwd inside Ship or **`SHIP_REPO`**. |
-| `ship docs search|fetch|feedback` | **`SHIP_API_BASE`** (default `http://127.0.0.1:8100`) or `--base-url`. |
-| `ship init` | Target repo cwd; **`SHIP_API_BASE` / `--base-url`** is the API URL written into snippets. |
+If **none** of the above exist, init offers a **standalone** **`SHIP_AGENT_API.md`** in the repo root so humans can copy the contract into whatever system you use later.
 
-## Publishing (maintainers)
+Use **`--only cursor|agents-md|claude-md|codex|copilot`** to limit targets; **`--cwd <dir>`** to point at another root.
 
-Releases are published via GitHub Actions (**Publish @elmundi/ship-cli to npm**): `npm publish -w @elmundi/ship-cli` from the monorepo root (not `npm publish --prefix cli`, which would try to publish the private root package). Configure the **`NPM_TOKEN`** repository secret. On npmjs.com use either a **Granular Access Token** with **Publish** on **`@elmundi/ship-cli`** (or the **elmundi** org) and **“Bypass two-factor authentication”** enabled for automation, or a classic **Automation** token — classic **Publish** tokens often cannot publish from CI when 2FA is on (`E403` *Two-factor authentication or granular access token with bypass 2fa…*).
+### 3. Apply with confirmation (recommended)
 
-The root monorepo `package.json` stays **`private`: true**; only **`@elmundi/ship-cli`** is intended for the public registry.
+Interactive run prints the plan and asks **Apply these changes? [y/N]**:
 
-## Semver
+```bash
+npx @elmundi/ship-cli init
+```
+
+After you confirm **`y`**, it writes/updates the files above. Injected content tells agents to **use the Ship methodology API** (and the **`ship`** CLI from a dev shell): **search → fetch** workflow, **`ship docs fetch`** for documentation paths, **`ship pattern|tool|workflow|collection`** for catalog entries, and **`ship docs feedback`** for safe retro notes — so methodology and **tools/workflows** discovery stay consistent with the server.
+
+### 4. Non-interactive (CI or scripts)
+
+Only after you are happy with **`--dry-run`**:
+
+```bash
+npx @elmundi/ship-cli init --yes
+```
+
+**`--force`** replaces blocks that were already injected (same marker). Without **`--force`**, existing injections are skipped.
+
+## Commands (quick reference)
+
+| Command | Role |
+|--------|------|
+| **`ship init`** | Inject agent-facing rules / sections with your **`SHIP_API_BASE`** (or **`--base-url`**). |
+| **`ship search …`** | Vector search over methodology corpus (`POST /search`). |
+| **`ship docs fetch …`**, **`ship docs feedback …`** | Documentation file fetch and retro feedback (`POST /fetch` with `path`, `POST /feedback`). |
+| **`ship pattern|tool|workflow|collection`** **`list` \| `show` \| `fetch` \| `search`** | Catalogs; hosted mode uses the same API (including **`fetch`** via `POST /fetch` with `kind` + `id`). Plural aliases (`patterns`, `tools`, …) work. |
+
+**Maintainers / full Ship checkout:** if the current directory (or **`SHIP_REPO`**) is inside the Ship monorepo, **`list` / `show` / `fetch`** for catalogs can read manifests from **disk** instead of HTTP. **`ship search`** always uses HTTP.
+
+Run **`ship help`** for full usage.
+
+## Versioning (until the CLI stabilizes)
+
+Releases **bump the patch (third) number only** (e.g. `0.8.0` → `0.8.1`) while the command surface and docs are still settling. Minor/major bumps resume once things are stable.
+
+## Publishing (maintainers)
 
-Package version lives in **`cli/package.json`**. Bump it for each npm release following [semver](https://semver.org/).
+GitHub Action **Publish @elmundi/ship-cli to npm** (tag **`cli-v<version>`** must match **`cli/package.json`**, or use **workflow_dispatch**). Repository secret **`NPM_TOKEN`** required. Publish from monorepo root: **`npm publish -w @elmundi/ship-cli`**, not `npm publish --prefix cli` (root package is private).

package/bin/ship.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { extractGlobalArgv } from "../lib/config.mjs";
 import { docsCommand } from "../lib/commands/docs.mjs";
-import { patternsCommand } from "../lib/commands/patterns.mjs";
-import { manifestCatalogCommand } from "../lib/commands/manifest-catalog.mjs";
+import { searchCommand } from "../lib/commands/search.mjs";
+import { patternCommand } from "../lib/commands/patterns.mjs";
+import { resourceManifestCommand } from "../lib/commands/manifest-catalog.mjs";
 import { printHelp } from "../lib/commands/help.mjs";
 import { initCommand } from "../lib/commands/init.mjs";
 
@@ -24,28 +25,33 @@ try {
     process.exit(0);
   }
 
+  if (cmd === "search") {
+    await searchCommand(ctx, rest);
+    process.exit(0);
+  }
+
   if (cmd === "docs") {
     await docsCommand(ctx, rest);
     process.exit(0);
   }
 
-  if (cmd === "patterns") {
-    await patternsCommand(ctx, rest);
+  if (cmd === "pattern" || cmd === "patterns") {
+    await patternCommand(ctx, rest);
     process.exit(0);
   }
 
-  if (cmd === "tools") {
-    await manifestCatalogCommand("tools", ctx, rest);
+  if (cmd === "tool" || cmd === "tools") {
+    await resourceManifestCommand("tool", ctx, rest);
     process.exit(0);
   }
 
-  if (cmd === "workflows") {
-    await manifestCatalogCommand("workflows", ctx, rest);
+  if (cmd === "workflow" || cmd === "workflows") {
+    await resourceManifestCommand("workflow", ctx, rest);
     process.exit(0);
   }
 
-  if (cmd === "collections") {
-    await manifestCatalogCommand("collections", ctx, rest);
+  if (cmd === "collection" || cmd === "collections") {
+    await resourceManifestCommand("collection", ctx, rest);
     process.exit(0);
   }
 

package/lib/commands/docs.mjs

@@ -1,6 +1,7 @@
 import { apiPost } from "../http.mjs";
 
 /**
+ * Documentation files only: fetch markdown by repo path, retro feedback.
  * @param {{ baseUrl: string; json: boolean }} ctx
  * @param {string[]} args
  */
@@ -8,52 +9,27 @@ export async function docsCommand(ctx, args) {
   const [sub, ...rest] = args;
   if (!sub || sub === "help") {
     console.log(`Usage:
-  ship docs search <query> [--top-k 8]
   ship docs fetch <repo-relative-path>
   ship docs feedback --title "..." --summary "..." [--recommendation "line"]... [--source-context "..."]
 
-Global flags: --base-url URL  --json`);
-    return;
-  }
+Vector search:  ship search <query>
+Catalog bodies:  ship pattern|tool|workflow|collection fetch <id>
 
-  if (sub === "search") {
-    const qParts = [];
-    let topK = 8;
-    for (let i = 0; i < rest.length; i++) {
-      const a = rest[i];
-      if (a === "--top-k" && rest[i + 1]) {
-        topK = Number(rest[++i]);
-        continue;
-      }
-      qParts.push(a);
-    }
-    const query = qParts.join(" ").trim();
-    if (query.length < 3) {
-      console.error("search: query must be at least 3 characters.");
-      process.exit(1);
-    }
-    const data = await apiPost(ctx.baseUrl, "/search", { query, top_k: topK });
-    if (ctx.json) console.log(JSON.stringify(data, null, 2));
-    else {
-      console.log(`Query: ${data.query}\n`);
-      for (const r of data.results || []) {
-        console.log(`- ${r.path}  (chunk ${r.chunk_index}, distance ${r.distance ?? "n/a"})`);
-        console.log(`  ${r.snippet}\n`);
-      }
-    }
+Global flags: --base-url URL  --json`);
     return;
   }
 
   if (sub === "fetch") {
     const p = rest.join(" ").trim();
     if (!p) {
-      console.error("fetch: path required.");
+      console.error("fetch: repo-relative path required (markdown/text under the Ship tree).");
       process.exit(1);
     }
     const data = await apiPost(ctx.baseUrl, "/fetch", { path: p });
     if (ctx.json) console.log(JSON.stringify(data, null, 2));
     else {
-      console.log(`# ${data.path}\n`);
+      const title = data.path ?? data.id ?? "document";
+      console.log(`# ${title}\n`);
       console.log(data.content);
     }
     return;

package/lib/commands/help.mjs

@@ -1,59 +1,39 @@
 export function printHelp() {
-  console.log(`Ship CLI — Ship methodology HTTP API (search, fetch, feedback, patterns, tools, workflows, collections) + init.
+  console.log(`Ship CLI — methodology on ship.elmundi.com (or SHIP_API_BASE) + init.
 
-USAGE
+ONE FLOW
+  1) ship search <query>     — vector search (POST /search) over docs + prompts + README
+  2) ship docs fetch <path>  — full markdown file by repo-relative path (POST /fetch { path })
+     ship pattern|tool|workflow|collection fetch <id> — catalog entry body (POST /fetch { kind, id })
+  3) ship docs feedback …   — improvement / retro note (POST /feedback)
+
+COMMANDS
   ship help
-  ship docs search <query> [--top-k N]
-  ship docs fetch <path>
+  ship search <query> [--top-k N]
+
+  ship docs fetch <repo-relative-path>
   ship docs feedback --title "..." --summary "..." [--recommendation "…"]... [--source-context "…"]
-  ship patterns list
-  ship patterns show <pattern-id>
-  ship tools list | ship tools show <id>
-  ship workflows list | ship workflows show <id>
-  ship collections list | ship collections show <id>
+
+  ship pattern list | ship pattern show <id> | ship pattern fetch <id> | ship pattern search <query> [--top-k N]
+  ship tool … | ship workflow … | ship collection …   (same subcommands; plural aliases: patterns, tools, …)
+
   ship init [--yes] [--force] [--dry-run] [--only <id>] [--cwd <dir>]
 
 GLOBAL FLAGS
-  --base-url URL   API root for ALL HTTP commands (default: SHIP_API_BASE or http://127.0.0.1:8100)
-  --json           Machine-readable JSON to stdout
+  --base-url URL   Methodology API (default: SHIP_API_BASE or https://ship.elmundi.com/api/methodology)
+  --json           Machine-readable JSON
 
-CATALOG COMMANDS (patterns, tools, workflows, collections)
-  If cwd or SHIP_REPO points at a Ship clone: read manifests from disk.
-  Otherwise: same base URL as docs — GET /patterns, /tools, /workflows, /collections (and /{id} for show).
+LOCAL TREE
+  pattern / tool / workflow / collection list|show|fetch read manifests from disk when cwd or SHIP_REPO
+  is inside the Ship monorepo (search always uses HTTP).
 
 INIT FLAGS
-  --yes            Skip confirmation prompts (non-interactive; writes files — review plan with --dry-run first)
-  --force          Overwrite / replace existing ship-cli blocks
-  --dry-run        Print actions only
-  --only <id>      Limit to one target: cursor | agents-md | claude-md | codex | copilot
-  --cwd <dir>      Repository root (default: current directory)
-
-BACKEND
-  Start from Ship repo:  uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8100
-  Env on server: OPENAI_API_KEY (/search), GITHUB_TOKEN (/feedback)
-
-────────────────────────────────────────────────────────
-Embedding in an agent (Cursor, Codex, Claude Code, etc.)
-────────────────────────────────────────────────────────
-
-1. Run the Ship backend locally (or deploy it) and set SHIP_API_BASE in the agent environment
-   if the URL is not the default http://127.0.0.1:8100 .
-
-2. Teach the agent this loop (or mirror it with curl):
-   - POST /search with the user question → pick 1–3 paths from results (CLI: ship docs search)
-   - POST /fetch for each chosen path → ground answers in those files (CLI: ship docs fetch)
-   - Optionally list/show patterns (CLI: ship patterns list | ship patterns show <id> — GET /patterns on the same API, or disk in a Ship clone / SHIP_REPO)
-   - POST /feedback only for retro-style notes (no secrets in free text) (CLI: ship docs feedback)
-
-3. Run  ship init  in the TARGET repository (your product repo, not necessarily Ship).
-   It detects .cursor/, AGENTS.md, CLAUDE.md, .codex/, or Copilot instructions and, after
-   your confirmation, drops a focused rule or appends a markdown section the agent can read.
-
-4. List patterns/tools/workflows/collections via the same API (or from disk in a clone / SHIP_REPO):  ship patterns list ,  ship tools list ,  etc.
-
-5. From CI or headless agents, call the same HTTP API with curl or fetch; use  ship … --json
-   for stable parsing.
+  --yes       Non-interactive apply (use --dry-run first)
+  --force     Replace existing injected blocks
+  --dry-run   Preview only
+  --only      cursor | agents-md | claude-md | codex | copilot
+  --cwd       Target repo root
 
-For full request/response schemas see documentation/tools/backend-api.md in the Ship repo.
+For HTTP schemas see documentation/tools/backend-api.md in the Ship repo.
 `);
 }

package/lib/commands/init.mjs

@@ -17,7 +17,7 @@ export async function initCommand(ctx, args) {
   ship init [--yes] [--force] [--dry-run] [--only <id>] [--cwd <dir>]
 
 Writes Cursor rules and/or markdown sections that point agents at the Ship methodology API
-(base URL from SHIP_API_BASE or --base-url, default http://127.0.0.1:8100).
+(base URL from SHIP_API_BASE or --base-url; same default as other commands, e.g. ship.elmundi.com).
 
 Flags:
   --dry-run   Show the plan only (recommended before first use).

package/lib/commands/manifest-catalog.mjs

@@ -1,62 +1,80 @@
 import fs from "node:fs";
 import path from "node:path";
-import { apiGet } from "../http.mjs";
+import { apiGet, apiPost } from "../http.mjs";
 import { resolveShipRepoRootForCatalog } from "../find-ship-root.mjs";
+import { searchCommand } from "./search.mjs";
 
-/** @type {Record<string, { manifestRel: string; arrayKey: string; name: string }>} */
-const CATALOGS = {
-  tools: { manifestRel: "tools/manifest.json", arrayKey: "tools", name: "Tools" },
-  workflows: {
+/** @type {Record<string, { manifestRel: string; arrayKey: string; name: string; apiPath: string; fetchKind: string }>} */
+const RESOURCES = {
+  tool: {
+    manifestRel: "tools/manifest.json",
+    arrayKey: "tools",
+    name: "Tools",
+    apiPath: "tools",
+    fetchKind: "tool",
+  },
+  workflow: {
     manifestRel: "workflows/manifest.json",
     arrayKey: "workflows",
     name: "Workflows",
+    apiPath: "workflows",
+    fetchKind: "workflow",
   },
-  collections: {
+  collection: {
     manifestRel: "collections/manifest.json",
     arrayKey: "collections",
     name: "Collections",
+    apiPath: "collections",
+    fetchKind: "collection",
   },
 };
 
 /**
- * @param {"tools"|"workflows"|"collections"} kind
+ * @param {"tool"|"workflow"|"collection"} resource
  * @param {{ baseUrl: string; json: boolean }} ctx
- * @param {string[]} args subcommand tail (e.g. `list` or `show`, `linear`)
+ * @param {string[]} args
  */
-export async function manifestCatalogCommand(kind, ctx, args) {
-  const spec = CATALOGS[kind];
-  if (!spec) throw new Error(`Unknown catalog kind: ${kind}`);
+export async function resourceManifestCommand(resource, ctx, args) {
+  const spec = RESOURCES[resource];
+  if (!spec) throw new Error(`Unknown resource: ${resource}`);
 
   const [sub, ...rest] = args;
   if (!sub || sub === "help") {
     console.log(`Usage:
-  ship ${kind} list
-  ship ${kind} show <id>
+  ship ${resource} list
+  ship ${resource} show <id>
+  ship ${resource} fetch <id>
+  ship ${resource} search <query> [--top-k N]
 
 With a local Ship tree (cwd or SHIP_REPO): reads ${spec.manifestRel} on disk.
-Otherwise: methodology HTTP API — GET /${kind} and GET /${kind}/<id> (SHIP_API_BASE / --base-url).
+Otherwise: methodology API (GET /${spec.apiPath}, POST /fetch for fetch, POST /search for search).
+
+Plural alias: ship ${spec.apiPath} …
 
 Global flags: --base-url URL  --json`);
     return;
   }
 
+  if (sub === "search") {
+    await searchCommand(ctx, rest);
+    return;
+  }
+
   const root = resolveShipRepoRootForCatalog();
   if (root) {
-    await manifestFromDisk(kind, root, spec, ctx, sub, rest);
+    await manifestFromDisk(resource, root, spec, ctx, sub, rest);
   } else {
-    await manifestFromHosted(kind, spec, ctx, sub, rest);
+    await manifestFromHosted(resource, spec, ctx, sub, rest);
   }
 }
 
 /**
- * @param {"tools"|"workflows"|"collections"} kind
- * @param {typeof CATALOGS["tools"]} spec
- * @param {{ baseUrl: string; json: boolean }} ctx
+ * @param {"tool"|"workflow"|"collection"} resource
  */
-async function manifestFromHosted(kind, spec, ctx, sub, rest) {
+async function manifestFromHosted(resource, spec, ctx, sub, rest) {
   const base = ctx.baseUrl;
   if (sub === "list") {
-    const data = await apiGet(base, `/${kind}`);
+    const data = await apiGet(base, `/${spec.apiPath}`);
     if (ctx.json) {
       console.log(JSON.stringify(data, null, 2));
     } else {
@@ -78,7 +96,22 @@ async function manifestFromHosted(kind, spec, ctx, sub, rest) {
       console.error("show: id required.");
       process.exit(1);
     }
-    const data = await apiGet(base, `/${kind}/${encodeURIComponent(id)}`);
+    const data = await apiGet(base, `/${spec.apiPath}/${encodeURIComponent(id)}`);
+    if (ctx.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      console.log(`# ${data.title} (${data.id})\n`);
+      console.log(data.content);
+    }
+    return;
+  }
+  if (sub === "fetch") {
+    const id = rest[0];
+    if (!id) {
+      console.error("fetch: id required.");
+      process.exit(1);
+    }
+    const data = await apiPost(base, "/fetch", { kind: spec.fetchKind, id });
     if (ctx.json) {
       console.log(JSON.stringify(data, null, 2));
     } else {
@@ -87,17 +120,14 @@ async function manifestFromHosted(kind, spec, ctx, sub, rest) {
     }
     return;
   }
-  console.error(`Unknown ${kind} subcommand: ${sub}`);
+  console.error(`Unknown ${resource} subcommand: ${sub}`);
   process.exit(1);
 }
 
 /**
- * @param {"tools"|"workflows"|"collections"} kind
- * @param {string} root
- * @param {typeof CATALOGS["tools"]} spec
- * @param {{ json: boolean }} ctx
+ * @param {"tool"|"workflow"|"collection"} resource
  */
-async function manifestFromDisk(kind, root, spec, ctx, sub, rest) {
+async function manifestFromDisk(resource, root, spec, ctx, sub, rest) {
   const manifestPath = path.join(root, spec.manifestRel);
   const raw = fs.readFileSync(manifestPath, "utf8");
   /** @type {Record<string, unknown>} */
@@ -120,10 +150,10 @@ async function manifestFromDisk(kind, root, spec, ctx, sub, rest) {
     return;
   }
 
-  if (sub === "show") {
+  if (sub === "show" || sub === "fetch") {
     const id = rest[0];
     if (!id) {
-      console.error("show: id required.");
+      console.error(`${sub}: id required.`);
       process.exit(1);
     }
     const entry = entries.find((e) => e.id === id);
@@ -152,6 +182,6 @@ async function manifestFromDisk(kind, root, spec, ctx, sub, rest) {
     return;
   }
 
-  console.error(`Unknown ${kind} subcommand: ${sub}`);
+  console.error(`Unknown ${resource} subcommand: ${sub}`);
   process.exit(1);
 }

package/lib/commands/patterns.mjs

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
-import { apiGet } from "../http.mjs";
+import { apiGet, apiPost } from "../http.mjs";
 import { resolveShipRepoRootForCatalog } from "../find-ship-root.mjs";
+import { searchCommand } from "./search.mjs";
 
 const MANIFEST_REL = "patterns/manifest.json";
 
@@ -36,7 +37,7 @@ function slimEntry(p) {
 
 /**
  * @param {string} root
- * @param {{ json: boolean }} ctx
+ * @param {{ baseUrl: string; json: boolean }} ctx
  * @param {string} sub
  * @param {string[]} rest
  */
@@ -64,10 +65,10 @@ async function patternsFromDisk(root, ctx, sub, rest) {
     return;
   }
 
-  if (sub === "show") {
+  if (sub === "show" || sub === "fetch") {
     const id = rest[0];
     if (!id) {
-      console.error("show: pattern id required.");
+      console.error(`${sub}: pattern id required.`);
       process.exit(1);
     }
     const entry = entries.find((e) => e.id === id);
@@ -101,7 +102,7 @@ async function patternsFromDisk(root, ctx, sub, rest) {
     return;
   }
 
-  console.error(`Unknown patterns subcommand: ${sub}`);
+  console.error(`Unknown pattern subcommand: ${sub}`);
   process.exit(1);
 }
 
@@ -139,7 +140,21 @@ async function patternsFromHosted(ctx, sub, rest) {
     }
     return;
   }
-  console.error(`Unknown patterns subcommand: ${sub}`);
+  if (sub === "fetch") {
+    const id = rest[0];
+    if (!id) {
+      console.error("fetch: pattern id required.");
+      process.exit(1);
+    }
+    const data = await apiPost(base, "/fetch", { kind: "pattern", id });
+    if (ctx.json) console.log(JSON.stringify(data, null, 2));
+    else {
+      console.log(`# ${data.title} (${data.id})\n`);
+      console.log(data.content);
+    }
+    return;
+  }
+  console.error(`Unknown pattern subcommand: ${sub}`);
   process.exit(1);
 }
 
@@ -147,20 +162,29 @@ async function patternsFromHosted(ctx, sub, rest) {
  * @param {{ baseUrl: string; json: boolean }} ctx
  * @param {string[]} args
  */
-export async function patternsCommand(ctx, args) {
+export async function patternCommand(ctx, args) {
   const [sub, ...rest] = args;
   if (!sub || sub === "help") {
     console.log(`Usage:
-  ship patterns list
-  ship patterns show <pattern-id>
+  ship pattern list
+  ship pattern show <id>
+  ship pattern fetch <id>
+  ship pattern search <query> [--top-k N]
 
-With a local Ship tree (cwd or SHIP_REPO): reads patterns/manifest.json on disk.
-Otherwise: same HTTP API as methodology — GET /patterns and GET /patterns/{id} (SHIP_API_BASE / --base-url).
+With a local Ship tree (cwd or SHIP_REPO): list/show/fetch read patterns/manifest.json on disk.
+Otherwise: methodology API (GET /patterns, POST /fetch for fetch, POST /search for search).
+
+Plural alias: ship patterns …
 
 Global flags: --base-url URL  --json`);
     return;
   }
 
+  if (sub === "search") {
+    await searchCommand(ctx, rest);
+    return;
+  }
+
   const root = resolveShipRepoRootForCatalog();
   if (root) {
     await patternsFromDisk(root, ctx, sub, rest);

package/lib/commands/search.mjs

@@ -0,0 +1,43 @@
+import { apiPost } from "../http.mjs";
+
+/**
+ * Vector search over methodology corpus (documentation, prompts, README).
+ * @param {{ baseUrl: string; json: boolean }} ctx
+ * @param {string[]} args query tokens (same line as `ship search …`)
+ */
+export async function searchCommand(ctx, args) {
+  if (!args.length || args[0] === "help" || args[0] === "-h" || args[0] === "--help") {
+    console.log(`Usage:
+  ship search <query> [--top-k 8]
+
+POST /search on the methodology API (same SHIP_API_BASE as ship pattern/tool/…).
+
+Global flags: --base-url URL  --json`);
+    return;
+  }
+
+  const qParts = [];
+  let topK = 8;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--top-k" && args[i + 1]) {
+      topK = Number(args[++i]);
+      continue;
+    }
+    qParts.push(a);
+  }
+  const query = qParts.join(" ").trim();
+  if (query.length < 3) {
+    console.error("search: query must be at least 3 characters.");
+    process.exit(1);
+  }
+  const data = await apiPost(ctx.baseUrl, "/search", { query, top_k: topK });
+  if (ctx.json) console.log(JSON.stringify(data, null, 2));
+  else {
+    console.log(`Query: ${data.query}\n`);
+    for (const r of data.results || []) {
+      console.log(`- ${r.path}  (chunk ${r.chunk_index}, distance ${r.distance ?? "n/a"})`);
+      console.log(`  ${r.snippet}\n`);
+    }
+  }
+}

package/lib/config.mjs

@@ -5,7 +5,9 @@
 export function extractGlobalArgv(argv) {
   const out = {
     _: /** @type {string[]} */ ([]),
-    baseUrl: (process.env.SHIP_API_BASE || "http://127.0.0.1:8100").replace(/\/$/, ""),
+    baseUrl: (
+      process.env.SHIP_API_BASE || "https://ship.elmundi.com/api/methodology"
+    ).replace(/\/$/, ""),
     json: false,
     yes: false,
     force: false,

package/lib/templates.mjs

@@ -20,14 +20,14 @@ Base URL (override with \`SHIP_API_BASE\` for agents, or \`--base-url\` for CLI)
 1. **Discover** — \`POST /search\` with a natural-language query over Ship docs + prompts.
 2. **Read** — \`POST /fetch\` with a repo-relative \`path\` from search hits (markdown/text only).
 3. **Retro** — \`POST /feedback\` to open a sanitized GitHub issue (needs \`GITHUB_TOKEN\` on the server).
-4. **Patterns** — run \`ship patterns list\` / \`ship patterns show <id>\` (\`GET /patterns\` on the same base URL as search; or disk when cwd/\`SHIP_REPO\` is the Ship tree).
+4. **Catalog** — \`ship pattern|tool|workflow|collection list\` / \`show <id>\` / \`fetch <id>\` (\`GET /…\` on the same base URL as search, or \`POST /fetch\` with \`{ kind, id }\` when hosted; or disk when cwd/\`SHIP_REPO\` is the Ship tree).
 
 ## Examples (CLI from Ship repo)
 
 \`\`\`bash
-npm run ship -- docs search "release gates and qa split" --top-k 8
+npm run ship -- search "release gates and qa split" --top-k 8
 npm run ship -- docs fetch documentation/adoption/delivery-quality-and-release-process.md
-npm run ship -- patterns list
+npm run ship -- pattern list
 \`\`\`
 
 Equivalent curl (when not using the CLI):
@@ -65,7 +65,7 @@ Base URL: \`${baseUrl}\` (env \`SHIP_API_BASE\`).
 - **Search** \`POST /search\` JSON \`{ "query": string, "top_k"?: number }\`
 - **Fetch** \`POST /fetch\` JSON \`{ "path": "documentation/...md" }\`
 - **Feedback** \`POST /feedback\` JSON \`{ "title", "summary", "recommendations"?: string[], "source_context"?: string }\`
-- **Patterns** — \`ship patterns list\` / \`ship patterns show <id>\` (same \`SHIP_API_BASE\` as search, or local tree): \`GET /patterns\`, \`GET /patterns/{id}\`
+- **Catalog** — \`ship pattern|tool|workflow|collection list\` / \`show <id>\` / \`fetch <id>\` (same \`SHIP_API_BASE\` as search, or local tree): \`GET /patterns\`, \`GET /patterns/{id}\`, or \`POST /fetch\` with \`{ "kind": "pattern", "id": "…" }\`
 
 Use search first, then fetch the best path. Keep tokens out of feedback bodies.
 `;
@@ -90,15 +90,16 @@ See the Ship repo \`documentation/tools/backend-api.md\` for full contract.
 | POST | /search | \`{ "query": "...", "top_k": 8 }\` |
 | POST | /fetch | \`{ "path": "documentation/foo.md" }\` |
 | POST | /feedback | \`{ "title", "summary", "recommendations": [], "source_context" }\` |
-| GET | /patterns | list manifest — **CLI:** \`ship patterns list\` (HTTP or disk in clone) |
-| GET | /patterns/{id} | metadata + markdown \`content\` — **CLI:** \`ship patterns show <id>\` |
+| GET | /patterns | list manifest — **CLI:** \`ship pattern list\` (HTTP or disk in clone) |
+| GET | /patterns/{id} | metadata + markdown \`content\` — **CLI:** \`ship pattern show <id>\` |
+| POST | /fetch | catalog body — **CLI:** \`ship pattern fetch <id>\` with \`{ "kind": "pattern", "id" }\` |
 
 ## CLI (from Ship monorepo)
 
 \`\`\`bash
-npm run ship -- patterns list
-npm run ship -- patterns show catalog-a1-intake
-npm run ship -- docs search "intake labels" --top-k 5
+npm run ship -- pattern list
+npm run ship -- pattern show catalog-a1-intake
+npm run ship -- search "intake labels" --top-k 5
 \`\`\`
 
 ## curl (direct HTTP)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@elmundi/ship-cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "type": "module",
-  "description": "Ship CLI — docs API (search/fetch/feedback), on-disk patterns & catalogs, and agent init",
+  "description": "Ship CLI — methodology search, docs fetch/feedback, catalog commands (pattern/tool/workflow/collection), and agent init",
   "license": "Apache-2.0",
   "author": "Denys Kuzin",
   "repository": {