@elmundi/ship-cli 0.7.0

package/README.md

@@ -0,0 +1,60 @@
+# @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.
+
+Published under the npm org **[elmundi](https://www.npmjs.com/org/elmundi)**; the binary name remains **`ship`**.
+
+## Requirements
+
+- **Node.js 20+** (matches Ship CI and typical adopters).
+
+## 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:
+npx @elmundi/ship-cli help
+```
+
+From a full **Ship** monorepo clone you can still run `npm run ship -- …` from the repo root (workspace).
+
+## Adopt without cloning the whole monorepo
+
+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):
+
+   ```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
+   ```
+
+3. Optional: work from a **local** Ship checkout (or **`SHIP_REPO`**) to read manifests from disk without calling the API.
+
+4. In your **product** repository, wire agents to the methodology API:
+
+   ```bash
+   cd /path/to/your-product
+   npx @elmundi/ship-cli init --yes
+   ```
+
+   Use **`--dry-run`** first to preview; **`--yes`** skips prompts and writes files — see `ship init help`.
+
+## Which commands need what
+
+| 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. |
+
+## Publishing (maintainers)
+
+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…*).
+
+The root monorepo `package.json` stays **`private`: true**; only **`@elmundi/ship-cli`** is intended for the public registry.
+
+## Semver
+
+Package version lives in **`cli/package.json`**. Bump it for each npm release following [semver](https://semver.org/).

package/bin/ship.mjs

@@ -0,0 +1,62 @@
+#!/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 { printHelp } from "../lib/commands/help.mjs";
+import { initCommand } from "../lib/commands/init.mjs";
+
+const raw = process.argv.slice(2);
+const { _, ...g } = extractGlobalArgv(raw);
+const ctx = {
+  baseUrl: g.baseUrl,
+  json: g.json,
+  yes: g.yes,
+  force: g.force,
+  dryRun: g.dryRun,
+};
+
+const [cmd, ...rest] = _;
+
+try {
+  if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (cmd === "docs") {
+    await docsCommand(ctx, rest);
+    process.exit(0);
+  }
+
+  if (cmd === "patterns") {
+    await patternsCommand(ctx, rest);
+    process.exit(0);
+  }
+
+  if (cmd === "tools") {
+    await manifestCatalogCommand("tools", ctx, rest);
+    process.exit(0);
+  }
+
+  if (cmd === "workflows") {
+    await manifestCatalogCommand("workflows", ctx, rest);
+    process.exit(0);
+  }
+
+  if (cmd === "collections") {
+    await manifestCatalogCommand("collections", ctx, rest);
+    process.exit(0);
+  }
+
+  if (cmd === "init") {
+    await initCommand(ctx, rest);
+    process.exit(0);
+  }
+
+  console.error(`Unknown command: ${cmd}\nRun: ship help`);
+  process.exit(1);
+} catch (err) {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+}

package/lib/commands/docs.mjs

@@ -0,0 +1,114 @@
+import { apiPost } from "../http.mjs";
+
+/**
+ * @param {{ baseUrl: string; json: boolean }} ctx
+ * @param {string[]} args
+ */
+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;
+  }
+
+  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`);
+      }
+    }
+    return;
+  }
+
+  if (sub === "fetch") {
+    const p = rest.join(" ").trim();
+    if (!p) {
+      console.error("fetch: path required.");
+      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`);
+      console.log(data.content);
+    }
+    return;
+  }
+
+  if (sub === "feedback") {
+    const opts = parseFeedbackArgs(rest);
+    if (opts.title.length < 5 || opts.summary.length < 10) {
+      console.error("feedback: --title (min 5) and --summary (min 10) are required.");
+      process.exit(1);
+    }
+    const body = {
+      title: opts.title,
+      summary: opts.summary,
+      recommendations: opts.recommendations,
+      source_context: opts.sourceContext || null,
+    };
+    const data = await apiPost(ctx.baseUrl, "/feedback", body);
+    if (ctx.json) console.log(JSON.stringify(data, null, 2));
+    else {
+      console.log(`Created: ${data.issue_url} (#${data.issue_number})`);
+      if (data.redactions_applied) console.log(`Redactions applied: ${data.redactions_applied}`);
+    }
+    return;
+  }
+
+  console.error(`Unknown docs subcommand: ${sub}`);
+  process.exit(1);
+}
+
+/** @param {string[]} rest */
+function parseFeedbackArgs(rest) {
+  let title = "";
+  let summary = "";
+  /** @type {string[]} */
+  const recommendations = [];
+  let sourceContext = "";
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--title" && rest[i + 1]) {
+      title = rest[++i];
+      continue;
+    }
+    if (a === "--summary" && rest[i + 1]) {
+      summary = rest[++i];
+      continue;
+    }
+    if (a === "--recommendation" && rest[i + 1]) {
+      recommendations.push(rest[++i]);
+      continue;
+    }
+    if (a === "--source-context" && rest[i + 1]) {
+      sourceContext = rest[++i];
+      continue;
+    }
+  }
+  return { title, summary, recommendations, sourceContext };
+}

package/lib/commands/help.mjs

@@ -0,0 +1,59 @@
+export function printHelp() {
+  console.log(`Ship CLI — Ship methodology HTTP API (search, fetch, feedback, patterns, tools, workflows, collections) + init.
+
+USAGE
+  ship help
+  ship docs search <query> [--top-k N]
+  ship docs fetch <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 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
+
+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).
+
+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.
+
+For full request/response schemas see documentation/tools/backend-api.md in the Ship repo.
+`);
+}

package/lib/commands/init.mjs

@@ -0,0 +1,223 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { detectAgentTargets } from "../detect.mjs";
+import { MARKER, cursorRuleMdc, markdownSection, standaloneDoc } from "../templates.mjs";
+
+const END_MARKER = "<!-- ship-cli:end methodology-api -->";
+
+/**
+ * @param {{ baseUrl: string; yes: boolean; force: boolean; dryRun: boolean; json: boolean }} ctx
+ * @param {string[]} args
+ */
+export async function initCommand(ctx, args) {
+  if (!args.length || args[0] === "help" || args[0] === "-h" || args[0] === "--help") {
+    console.log(`Usage:
+  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).
+
+Flags:
+  --dry-run   Show the plan only (recommended before first use).
+  --yes       Non-interactive: apply immediately. In CI or scripts there is no prompt;
+              combine with --dry-run first if you are unsure. --force replaces existing
+              ship-cli blocks; without --force, existing injections are skipped.
+  --force     Replace existing injected blocks.
+  --only      cursor | agents-md | claude-md | codex | copilot
+  --cwd       Target repository root (default: current directory).
+
+If stdin is not a TTY and you omit --yes, init exits with an error unless you use --dry-run.`);
+    return;
+  }
+
+  let cwd = process.cwd();
+  /** @type {string[]} */
+  let only = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--cwd" && args[i + 1]) {
+      cwd = path.resolve(args[++i]);
+      continue;
+    }
+    if (a === "--only" && args[i + 1]) {
+      only.push(args[++i]);
+      continue;
+    }
+  }
+
+  let targets = detectAgentTargets(cwd);
+  if (only.includes("cursor") && !targets.some((t) => t.id === "cursor")) {
+    targets.push({
+      id: "cursor",
+      label: "Cursor (`.cursor/rules/` will be created if missing)",
+      paths: [path.join(cwd, ".cursor", "rules", "ship-methodology-api.mdc")],
+    });
+  }
+  if (only.length) {
+    const allowed = new Set(["cursor", "agents-md", "claude-md", "codex", "copilot"]);
+    for (const o of only) {
+      if (!allowed.has(o)) {
+        console.error(`init: unknown --only ${o}. Allowed: ${[...allowed].join(", ")}`);
+        process.exit(1);
+      }
+    }
+    targets = targets.filter((t) => only.includes(t.id));
+    if (!targets.length) {
+      console.error("init: no agent targets matched --only (markers missing in this repo).");
+      process.exit(1);
+    }
+  }
+
+  /** @type {{ id: string; label: string; action: string }[]} */
+  const plan = [];
+
+  if (targets.some((t) => t.id === "cursor")) {
+    const rulesDir = path.join(cwd, ".cursor", "rules");
+    const file = path.join(rulesDir, "ship-methodology-api.mdc");
+    plan.push({ id: "cursor", label: "Cursor rule", action: `write ${path.relative(cwd, file)}` });
+  }
+  for (const t of targets) {
+    if (t.id === "agents-md") {
+      plan.push({ id: "agents-md", label: t.label, action: `append section → ${t.paths[0]}` });
+    }
+    if (t.id === "claude-md") {
+      plan.push({ id: "claude-md", label: t.label, action: `append section → ${t.paths[0]}` });
+    }
+    if (t.id === "codex") {
+      plan.push({ id: "codex", label: t.label, action: `write ${path.relative(cwd, t.paths[0])}` });
+    }
+    if (t.id === "copilot") {
+      plan.push({ id: "copilot", label: t.label, action: `append section → ${t.paths[0]}` });
+    }
+  }
+
+  const standalonePath = path.join(cwd, "SHIP_AGENT_API.md");
+  if (!targets.length) {
+    plan.push({
+      id: "standalone",
+      label: "Standalone reference (no agent markers in repo)",
+      action: `write ${path.relative(cwd, standalonePath)}`,
+    });
+  }
+
+  if (ctx.json) {
+    console.log(JSON.stringify({ cwd, baseUrl: ctx.baseUrl, plan }, null, 2));
+    return;
+  }
+
+  console.log(`Repository: ${cwd}`);
+  console.log(`API base URL in injected docs: ${ctx.baseUrl}\n`);
+  console.log("Planned changes:");
+  for (const p of plan) console.log(`  - [${p.id}] ${p.action}`);
+  console.log("");
+
+  if (ctx.dryRun) {
+    console.log("(dry-run: no files written)");
+    return;
+  }
+
+  if (!ctx.yes) {
+    if (!input.isTTY || !output.isTTY) {
+      console.error("init: not a TTY; re-run with --yes or use --dry-run to preview.");
+      process.exit(1);
+    }
+    const rl = readline.createInterface({ input, output });
+    const ans = (await rl.question("Apply these changes? [y/N] ")).trim().toLowerCase();
+    rl.close();
+    if (ans !== "y" && ans !== "yes") {
+      console.log("Aborted.");
+      return;
+    }
+  }
+
+  for (const t of targets) {
+    if (t.id === "cursor") {
+      await writeCursorRule(cwd, ctx);
+    }
+    if (t.id === "agents-md") {
+      await appendOrWrite(t.paths[0], markdownSection(ctx.baseUrl), ctx);
+    }
+    if (t.id === "claude-md") {
+      await appendOrWrite(t.paths[0], markdownSection(ctx.baseUrl), ctx);
+    }
+    if (t.id === "codex") {
+      await writeNew(t.paths[0], standaloneDoc(ctx.baseUrl), ctx);
+    }
+    if (t.id === "copilot") {
+      await appendOrWrite(t.paths[0], markdownSection(ctx.baseUrl), ctx);
+    }
+  }
+
+  if (!targets.length) {
+    await writeNew(standalonePath, standaloneDoc(ctx.baseUrl), ctx);
+  }
+
+  console.log("Done.");
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ force: boolean; dryRun: boolean }} ctx
+ */
+async function writeCursorRule(cwd, ctx) {
+  const rulesDir = path.join(cwd, ".cursor", "rules");
+  const file = path.join(rulesDir, "ship-methodology-api.mdc");
+  const body = cursorRuleMdc(ctx.baseUrl);
+  if (fs.existsSync(file) && fs.readFileSync(file, "utf8").includes(MARKER) && !ctx.force) {
+    console.log(`skip (exists): ${file}`);
+    return;
+  }
+  if (ctx.dryRun) return;
+  fs.mkdirSync(rulesDir, { recursive: true });
+  fs.writeFileSync(file, body, "utf8");
+  console.log(`wrote ${file}`);
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} section
+ * @param {{ force: boolean; dryRun: boolean }} ctx
+ */
+async function appendOrWrite(filePath, section, ctx) {
+  if (ctx.dryRun) return;
+  let prev = "";
+  if (fs.existsSync(filePath)) prev = fs.readFileSync(filePath, "utf8");
+  if (prev.includes(MARKER) && !ctx.force) {
+    console.log(`skip (already injected): ${filePath}`);
+    return;
+  }
+  if (prev.includes(MARKER) && ctx.force) {
+    prev = stripInjectedBlock(prev);
+  }
+  const block = `${section}\n${END_MARKER}\n`;
+  const next = prev.replace(/\s+$/, "") + (prev ? "\n" : "") + block;
+  fs.writeFileSync(filePath, next, "utf8");
+  console.log(`updated ${filePath}`);
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} body
+ * @param {{ force: boolean; dryRun: boolean }} ctx
+ */
+async function writeNew(filePath, body, ctx) {
+  if (ctx.dryRun) return;
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, "utf8").includes(MARKER) && !ctx.force) {
+    console.log(`skip (exists): ${filePath}`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, body, "utf8");
+  console.log(`wrote ${filePath}`);
+}
+
+/** @param {string} prev */
+function stripInjectedBlock(prev) {
+  const start = prev.indexOf(MARKER);
+  if (start === -1) return prev;
+  const end = prev.indexOf(END_MARKER, start);
+  if (end === -1) return prev.slice(0, start).replace(/\n{3,}$/, "\n\n");
+  return (prev.slice(0, start) + prev.slice(end + END_MARKER.length)).replace(/\n{3,}/g, "\n\n");
+}

package/lib/commands/manifest-catalog.mjs

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import path from "node:path";
+import { apiGet } from "../http.mjs";
+import { resolveShipRepoRootForCatalog } from "../find-ship-root.mjs";
+
+/** @type {Record<string, { manifestRel: string; arrayKey: string; name: string }>} */
+const CATALOGS = {
+  tools: { manifestRel: "tools/manifest.json", arrayKey: "tools", name: "Tools" },
+  workflows: {
+    manifestRel: "workflows/manifest.json",
+    arrayKey: "workflows",
+    name: "Workflows",
+  },
+  collections: {
+    manifestRel: "collections/manifest.json",
+    arrayKey: "collections",
+    name: "Collections",
+  },
+};
+
+/**
+ * @param {"tools"|"workflows"|"collections"} kind
+ * @param {{ baseUrl: string; json: boolean }} ctx
+ * @param {string[]} args subcommand tail (e.g. `list` or `show`, `linear`)
+ */
+export async function manifestCatalogCommand(kind, ctx, args) {
+  const spec = CATALOGS[kind];
+  if (!spec) throw new Error(`Unknown catalog kind: ${kind}`);
+
+  const [sub, ...rest] = args;
+  if (!sub || sub === "help") {
+    console.log(`Usage:
+  ship ${kind} list
+  ship ${kind} show <id>
+
+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).
+
+Global flags: --base-url URL  --json`);
+    return;
+  }
+
+  const root = resolveShipRepoRootForCatalog();
+  if (root) {
+    await manifestFromDisk(kind, root, spec, ctx, sub, rest);
+  } else {
+    await manifestFromHosted(kind, spec, ctx, sub, rest);
+  }
+}
+
+/**
+ * @param {"tools"|"workflows"|"collections"} kind
+ * @param {typeof CATALOGS["tools"]} spec
+ * @param {{ baseUrl: string; json: boolean }} ctx
+ */
+async function manifestFromHosted(kind, spec, ctx, sub, rest) {
+  const base = ctx.baseUrl;
+  if (sub === "list") {
+    const data = await apiGet(base, `/${kind}`);
+    if (ctx.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      const entries = /** @type {Array<{ id: string; title: string; path: string; tags?: string[] }>} */ (
+        data[spec.arrayKey] || []
+      );
+      console.log(`${data.description || spec.name}\n`);
+      for (const p of entries) {
+        console.log(`- ${p.id}`);
+        console.log(`  ${p.title}`);
+        console.log(`  path: ${p.path}  tags: ${(p.tags || []).join(", ")}\n`);
+      }
+    }
+    return;
+  }
+  if (sub === "show") {
+    const id = rest[0];
+    if (!id) {
+      console.error("show: id required.");
+      process.exit(1);
+    }
+    const data = await apiGet(base, `/${kind}/${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;
+  }
+  console.error(`Unknown ${kind} subcommand: ${sub}`);
+  process.exit(1);
+}
+
+/**
+ * @param {"tools"|"workflows"|"collections"} kind
+ * @param {string} root
+ * @param {typeof CATALOGS["tools"]} spec
+ * @param {{ json: boolean }} ctx
+ */
+async function manifestFromDisk(kind, root, spec, ctx, sub, rest) {
+  const manifestPath = path.join(root, spec.manifestRel);
+  const raw = fs.readFileSync(manifestPath, "utf8");
+  /** @type {Record<string, unknown>} */
+  const data = JSON.parse(raw);
+  const entries = /** @type {Array<{ id: string; title: string; summary?: string; path: string; tags?: string[] }>} */ (
+    data[spec.arrayKey] || []
+  );
+
+  if (sub === "list") {
+    if (ctx.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      console.log(`${data.description || spec.name}\n`);
+      for (const p of entries) {
+        console.log(`- ${p.id}`);
+        console.log(`  ${p.title}`);
+        console.log(`  path: ${p.path}  tags: ${(p.tags || []).join(", ")}\n`);
+      }
+    }
+    return;
+  }
+
+  if (sub === "show") {
+    const id = rest[0];
+    if (!id) {
+      console.error("show: id required.");
+      process.exit(1);
+    }
+    const entry = entries.find((e) => e.id === id);
+    if (!entry) {
+      console.error(`Unknown id: ${id}`);
+      process.exit(1);
+    }
+    const abs = path.resolve(root, entry.path);
+    const rootNorm = root.endsWith(path.sep) ? root.slice(0, -1) : root;
+    const absNorm = abs.endsWith(path.sep) ? abs.slice(0, -1) : abs;
+    if (absNorm !== rootNorm && !abs.startsWith(root + path.sep)) {
+      console.error("Manifest path escapes repository root.");
+      process.exit(1);
+    }
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+      console.error(`Missing file: ${entry.path}`);
+      process.exit(1);
+    }
+    const content = fs.readFileSync(abs, "utf8");
+    if (ctx.json) {
+      console.log(JSON.stringify({ ...entry, content }, null, 2));
+    } else {
+      console.log(`# ${entry.title} (${entry.id})\n`);
+      console.log(content);
+    }
+    return;
+  }
+
+  console.error(`Unknown ${kind} subcommand: ${sub}`);
+  process.exit(1);
+}

package/lib/commands/patterns.mjs

@@ -0,0 +1,170 @@
+import fs from "node:fs";
+import path from "node:path";
+import { apiGet } from "../http.mjs";
+import { resolveShipRepoRootForCatalog } from "../find-ship-root.mjs";
+
+const MANIFEST_REL = "patterns/manifest.json";
+
+/**
+ * @param {Record<string, unknown>} data
+ */
+function parseManifest(data) {
+  const patterns = /** @type {unknown} */ (data.patterns);
+  if (!Array.isArray(patterns)) {
+    throw new Error(`${MANIFEST_REL} must contain a "patterns" array.`);
+  }
+  return {
+    version: data.version ?? 1,
+    description: typeof data.description === "string" ? data.description : "",
+    patterns: /** @type {Array<Record<string, unknown>>} */ (patterns),
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} p
+ */
+function slimEntry(p) {
+  return {
+    id: p.id,
+    title: p.title,
+    summary: p.summary,
+    path: p.path,
+    tags: Array.isArray(p.tags) ? p.tags : [],
+    group: p.group,
+  };
+}
+
+/**
+ * @param {string} root
+ * @param {{ json: boolean }} ctx
+ * @param {string} sub
+ * @param {string[]} rest
+ */
+async function patternsFromDisk(root, ctx, sub, rest) {
+  const manifestPath = path.join(root, MANIFEST_REL);
+  const raw = fs.readFileSync(manifestPath, "utf8");
+  /** @type {Record<string, unknown>} */
+  const manifest = JSON.parse(raw);
+  const { version, description, patterns } = parseManifest(manifest);
+  const entries = patterns.filter((p) => p && typeof p === "object" && typeof p.id === "string");
+
+  if (sub === "list") {
+    const slim = entries.map((p) => slimEntry(p));
+    const out = { version, description, patterns: slim };
+    if (ctx.json) console.log(JSON.stringify(out, null, 2));
+    else {
+      console.log(`${description || "Patterns"}\n`);
+      for (const p of slim) {
+        console.log(`- ${p.id}`);
+        console.log(`  ${p.title}`);
+        const tags = (p.tags || []).join(", ");
+        console.log(`  path: ${p.path}  tags: ${tags}\n`);
+      }
+    }
+    return;
+  }
+
+  if (sub === "show") {
+    const id = rest[0];
+    if (!id) {
+      console.error("show: pattern id required.");
+      process.exit(1);
+    }
+    const entry = entries.find((e) => e.id === id);
+    if (!entry) {
+      console.error(`Unknown id: ${id}`);
+      process.exit(1);
+    }
+    const rel = entry.path;
+    if (typeof rel !== "string" || !rel.trim()) {
+      console.error("Pattern entry has no path.");
+      process.exit(1);
+    }
+    const abs = path.resolve(root, rel);
+    const rootNorm = root.endsWith(path.sep) ? root.slice(0, -1) : root;
+    const absNorm = abs.endsWith(path.sep) ? abs.slice(0, -1) : abs;
+    if (absNorm !== rootNorm && !abs.startsWith(root + path.sep)) {
+      console.error("Manifest path escapes repository root.");
+      process.exit(1);
+    }
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+      console.error(`Missing file: ${rel}`);
+      process.exit(1);
+    }
+    const content = fs.readFileSync(abs, "utf8");
+    const full = { ...slimEntry(entry), content };
+    if (ctx.json) console.log(JSON.stringify(full, null, 2));
+    else {
+      console.log(`# ${entry.title} (${entry.id})\n`);
+      console.log(content);
+    }
+    return;
+  }
+
+  console.error(`Unknown patterns subcommand: ${sub}`);
+  process.exit(1);
+}
+
+/**
+ * @param {{ baseUrl: string; json: boolean }} ctx
+ * @param {string} sub
+ * @param {string[]} rest
+ */
+async function patternsFromHosted(ctx, sub, rest) {
+  const base = ctx.baseUrl;
+  if (sub === "list") {
+    const data = await apiGet(base, "/patterns");
+    if (ctx.json) console.log(JSON.stringify(data, null, 2));
+    else {
+      console.log(`${data.description || "Patterns"}\n`);
+      for (const p of data.patterns || []) {
+        console.log(`- ${p.id}`);
+        console.log(`  ${p.title}`);
+        console.log(`  path: ${p.path}  tags: ${(p.tags || []).join(", ")}\n`);
+      }
+    }
+    return;
+  }
+  if (sub === "show") {
+    const id = rest[0];
+    if (!id) {
+      console.error("show: pattern id required.");
+      process.exit(1);
+    }
+    const data = await apiGet(base, `/patterns/${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;
+  }
+  console.error(`Unknown patterns subcommand: ${sub}`);
+  process.exit(1);
+}
+
+/**
+ * @param {{ baseUrl: string; json: boolean }} ctx
+ * @param {string[]} args
+ */
+export async function patternsCommand(ctx, args) {
+  const [sub, ...rest] = args;
+  if (!sub || sub === "help") {
+    console.log(`Usage:
+  ship patterns list
+  ship patterns show <pattern-id>
+
+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).
+
+Global flags: --base-url URL  --json`);
+    return;
+  }
+
+  const root = resolveShipRepoRootForCatalog();
+  if (root) {
+    await patternsFromDisk(root, ctx, sub, rest);
+  } else {
+    await patternsFromHosted(ctx, sub, rest);
+  }
+}

package/lib/config.mjs

@@ -0,0 +1,50 @@
+/**
+ * Pull known global flags out of argv; remainder is the subcommand tail.
+ * @param {string[]} argv
+ */
+export function extractGlobalArgv(argv) {
+  const out = {
+    _: /** @type {string[]} */ ([]),
+    baseUrl: (process.env.SHIP_API_BASE || "http://127.0.0.1:8100").replace(/\/$/, ""),
+    json: false,
+    yes: false,
+    force: false,
+    dryRun: false,
+  };
+  const copy = [...argv];
+  while (copy.length) {
+    const a = copy[0];
+    if (a === "--json") {
+      out.json = true;
+      copy.shift();
+      continue;
+    }
+    if (a === "--yes" || a === "-y") {
+      out.yes = true;
+      copy.shift();
+      continue;
+    }
+    if (a === "--force") {
+      out.force = true;
+      copy.shift();
+      continue;
+    }
+    if (a === "--dry-run") {
+      out.dryRun = true;
+      copy.shift();
+      continue;
+    }
+    if (a === "--base-url" && copy[1]) {
+      copy.shift();
+      out.baseUrl = String(copy.shift()).replace(/\/$/, "");
+      continue;
+    }
+    if (a.startsWith("--base-url=")) {
+      out.baseUrl = a.slice("--base-url=".length).replace(/\/$/, "");
+      copy.shift();
+      continue;
+    }
+    out._.push(copy.shift());
+  }
+  return out;
+}

package/lib/detect.mjs

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {string} cwd
+ * @returns {{ id: string; label: string; paths: string[] }[]}
+ */
+export function detectAgentTargets(cwd) {
+  /** @type {{ id: string; label: string; paths: string[] }[]} */
+  const targets = [];
+
+  const cursorDir = path.join(cwd, ".cursor");
+  const cursorRules = path.join(cursorDir, "rules");
+  if (fs.existsSync(cursorDir)) {
+    targets.push({
+      id: "cursor",
+      label: "Cursor (`.cursor/` present)",
+      paths: [path.join(cursorRules, "ship-methodology-api.mdc")],
+    });
+  }
+
+  const agents = path.join(cwd, "AGENTS.md");
+  if (fs.existsSync(agents)) {
+    targets.push({
+      id: "agents-md",
+      label: "OpenAI Codex / generic `AGENTS.md`",
+      paths: [agents],
+    });
+  }
+
+  const claude = path.join(cwd, "CLAUDE.md");
+  if (fs.existsSync(claude)) {
+    targets.push({
+      id: "claude-md",
+      label: "Claude Code `CLAUDE.md`",
+      paths: [claude],
+    });
+  }
+
+  const codexDir = path.join(cwd, ".codex");
+  if (fs.existsSync(codexDir)) {
+    targets.push({
+      id: "codex",
+      label: "Codex config dir (`.codex/`)",
+      paths: [path.join(codexDir, "SHIP_API.md")],
+    });
+  }
+
+  const copilot = path.join(cwd, ".github", "copilot-instructions.md");
+  if (fs.existsSync(copilot)) {
+    targets.push({
+      id: "copilot",
+      label: "GitHub Copilot instructions",
+      paths: [copilot],
+    });
+  }
+
+  return targets;
+}

package/lib/find-ship-root.mjs

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const MARKERS = [
+  "workflows/manifest.json",
+  "tools/manifest.json",
+  "collections/manifest.json",
+  "patterns/manifest.json",
+];
+
+function markersOk(dir) {
+  return MARKERS.every((m) => fs.existsSync(path.join(dir, m)));
+}
+
+/**
+ * Walk parents from cwd for a directory containing all Ship manifest markers.
+ * @returns {string | null}
+ */
+export function tryFindShipRepoRootFromWalk() {
+  let dir = path.resolve(process.cwd());
+  for (;;) {
+    if (markersOk(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Root of the Ship monorepo (manifests at repo root).
+ * Set `SHIP_REPO` to an absolute path when not running from inside the tree.
+ */
+export function findShipRepoRoot() {
+  const env = process.env.SHIP_REPO?.trim();
+  if (env) {
+    const r = path.resolve(env);
+    if (!markersOk(r)) {
+      throw new Error(
+        `SHIP_REPO=${r} is not the Ship monorepo (expected tools/, workflows/, collections/, patterns/ manifests at repo root).`,
+      );
+    }
+    return r;
+  }
+  const walked = tryFindShipRepoRootFromWalk();
+  if (walked) return walked;
+  throw new Error(
+    "Ship repo root not found: run from inside the ship clone, or set SHIP_REPO to the repository root.",
+  );
+}
+
+/**
+ * When `SHIP_REPO` is unset, returns repo root only if cwd is inside the tree; otherwise `null` (use hosted catalog).
+ * When `SHIP_REPO` is set, validates and returns that path or throws.
+ * @returns {string | null}
+ */
+export function resolveShipRepoRootForCatalog() {
+  const env = process.env.SHIP_REPO?.trim();
+  if (env) {
+    const r = path.resolve(env);
+    if (!markersOk(r)) {
+      throw new Error(
+        `SHIP_REPO=${r} is not the Ship monorepo (expected tools/, workflows/, collections/, patterns/ manifests at repo root).`,
+      );
+    }
+    return r;
+  }
+  return tryFindShipRepoRootFromWalk();
+}

package/lib/http.mjs

@@ -0,0 +1,46 @@
+/**
+ * @param {string} baseUrl
+ * @param {string} path
+ * @param {Record<string, unknown>} body
+ */
+export async function apiPost(baseUrl, path, body) {
+  const url = `${baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = text;
+  }
+  if (!res.ok) {
+    const msg = typeof data === "string" ? data : JSON.stringify(data);
+    throw new Error(`HTTP ${res.status} ${res.statusText} for POST ${url}\n${msg}`);
+  }
+  return data;
+}
+
+/**
+ * @param {string} baseUrl
+ * @param {string} path
+ */
+export async function apiGet(baseUrl, path) {
+  const url = `${baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+  const res = await fetch(url, { headers: { Accept: "application/json" } });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = text;
+  }
+  if (!res.ok) {
+    const msg = typeof data === "string" ? data : JSON.stringify(data);
+    throw new Error(`HTTP ${res.status} ${res.statusText} for GET ${url}\n${msg}`);
+  }
+  return data;
+}

package/lib/templates.mjs

@@ -0,0 +1,113 @@
+const MARKER = "<!-- ship-cli: methodology-api -->";
+
+/**
+ * @param {string} baseUrl
+ */
+export function cursorRuleMdc(baseUrl) {
+  return `---
+name: ship-methodology-api
+description: Call the Ship methodology HTTP API (semantic search, fetch full docs, retro feedback, pattern index) from the agent.
+---
+
+${MARKER}
+
+# Ship methodology API (local)
+
+Base URL (override with \`SHIP_API_BASE\` for agents, or \`--base-url\` for CLI): \`${baseUrl}\`
+
+## When to use
+
+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).
+
+## Examples (CLI from Ship repo)
+
+\`\`\`bash
+npm run ship -- docs 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
+\`\`\`
+
+Equivalent curl (when not using the CLI):
+
+\`\`\`bash
+curl -sS -X POST "${baseUrl}/search" -H "Content-Type: application/json" \\
+  -d '{"query":"release gates and qa split","top_k":8}'
+curl -sS -X POST "${baseUrl}/fetch" -H "Content-Type: application/json" \\
+  -d '{"path":"documentation/adoption/delivery-quality-and-release-process.md"}'
+curl -sS "${baseUrl}/patterns"
+\`\`\`
+
+## Agent workflow
+
+Prefer **search → fetch one path → quote** in your reply. Never paste secrets into \`/feedback\`; the server redacts common token shapes.
+
+Run the API locally: \`uvicorn backend.app.main:app --reload --host 127.0.0.1 --port 8100\` (see \`documentation/tools/backend-api.md\` in the Ship repo).
+`;
+}
+
+/**
+ * @param {string} baseUrl
+ */
+export function markdownSection(baseUrl) {
+  return `
+
+---
+
+${MARKER}
+
+## Ship methodology API
+
+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}\`
+
+Use search first, then fetch the best path. Keep tokens out of feedback bodies.
+`;
+}
+
+/**
+ * @param {string} baseUrl
+ */
+export function standaloneDoc(baseUrl) {
+  return `# Ship methodology API — agent reference
+
+${MARKER}
+
+Generated by \`ship init\`. Base URL: \`${baseUrl}\`
+
+See the Ship repo \`documentation/tools/backend-api.md\` for full contract.
+
+## Endpoints
+
+| Method | Path | Body / notes |
+|--------|------|----------------|
+| 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>\` |
+
+## 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
+\`\`\`
+
+## curl (direct HTTP)
+
+\`\`\`bash
+export SHIP=${baseUrl}
+curl -sS -X POST "$SHIP/search" -H "Content-Type: application/json" -d '{"query":"intake labels","top_k":5}'
+\`\`\`
+`;
+}
+
+export { MARKER };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@elmundi/ship-cli",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Ship CLI — docs API (search/fetch/feedback), on-disk patterns & catalogs, and agent init",
+  "license": "Apache-2.0",
+  "author": "Denys Kuzin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ElMundiUA/ship.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/ElMundiUA/ship/issues"
+  },
+  "homepage": "https://github.com/ElMundiUA/ship/tree/main/cli#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ship",
+    "cli",
+    "agents",
+    "methodology"
+  ],
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ship": "./bin/ship.mjs"
+  }
+}