@smartsoft001-mobilems/claude-plugins 2.85.0 → 2.86.0

package/.claude-plugin/marketplace.json

@@ -7,12 +7,8 @@
   },
   "plugins": [
     {
-      "name": "flow",
-      "source": "./plugins/flow"
-    },
-    {
-      "name": "flow-legacy",
-      "source": "./plugins/flow-legacy"
+      "name": "mobilems",
+      "source": "./plugins/mobilems"
     }
   ]
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@smartsoft001-mobilems/claude-plugins",
-  "version": "2.85.0",
+  "version": "2.86.0",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "postinstall": "claude plugin update flow@mobilems --scope project || true"
+    "postinstall": "claude plugin update mobilems@mobilems --scope project || true"
   },
   "types": "./src/index.d.ts",
   "main": "./src/index.js",

package/plugins/mobilems/.claude-plugin/README.md

@@ -0,0 +1,30 @@
+# Mobilems Plugin for Claude Code
+
+MobileMS-specific skills for the MuzaCMS / MobileMS indexer API. This plugin is a thin complement to the generic `flow@smart-pro` workflow plugins — it provides skills that are tied to the MobileMS backend.
+
+## Contents
+
+| Type | Name | Purpose |
+|------|------|---------|
+| Skill | `mobilems-docs-reader` | Answer questions about the MuzaCMS / MobileMS indexer OpenAPI spec; fetches a fresh copy via the bundled refresh script |
+
+The skill ships with `scripts/refresh-mobilems-api-spec.sh`, which logs into `https://develop-indexer.mobilems.pl` using `MOBILEMS_LOGIN` / `MOBILEMS_PASSWORD` (read from env or `.env`) and writes the spec to `shared-assets/mobilems-api.json` inside the installed package. The script caches the fetched spec per Claude Code session (8h TTL).
+
+## Installation
+
+Enable in the consumer project's `.claude/settings.json`:
+
+```json
+{
+  "enabledPlugins": {
+    "mobilems@mobilems": true
+  },
+  "permissions": {
+    "allow": [
+      "Bash(bash ./node_modules/@smartsoft001-mobilems/claude-plugins/plugins/mobilems/scripts/refresh-mobilems-api-spec.sh:*)"
+    ]
+  }
+}
+```
+
+Generic workflow skills (`/commit`, `/impl`, `/plan`, `/push`, etc.) come from `flow@smart-pro` — see `@smartsoft001/pro-claude-plugins`. Maia API skills (`maia-files-upload`, `maia-files-delete`, `shared-maia-api`) are not MobilEMS-specific and live in `flow@smart-pro`.

package/plugins/mobilems/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "mobilems",
+  "description": "MobilEMS-specific Claude Code skills (MuzaCMS / MobileMS indexer API)",
+  "version": "2.86.0"
+}

package/plugins/mobilems/scripts/refresh-mobilems-api-spec.sh

@@ -0,0 +1,372 @@
+#!/usr/bin/env bash
+# Refresh the MuzaCMS / MobileMS indexer OpenAPI spec.
+#
+# Logs in to https://develop-indexer.mobilems.pl via Symfony form-login,
+# scrapes the Swagger 2.0 JSON from /docs/api, and writes it next to this
+# skill's owning package under shared-assets/mobilems-api.json.
+#
+# Required tools: bash, curl, jq.
+# Required env vars (read from shell or auto-loaded from $PWD/.env):
+#   MOBILEMS_LOGIN     — MuzaCMS username
+#   MOBILEMS_PASSWORD  — MuzaCMS password
+#
+# Cache: a sibling mobilems-api.meta.json stores { sessionId, fetchedAt }.
+# The script skips the network call when the same Claude Code session
+# (CLAUDE_CODE_SESSION_ID) already fetched the spec less than 8h ago.
+
+set -u
+
+BASE='https://develop-indexer.mobilems.pl'
+LOGIN_URL="${BASE}/admin/login"
+DOCS_URL="${BASE}/docs/api"
+
+QUIET=0
+for arg in "$@"; do
+  case "$arg" in
+    --quiet) QUIET=1 ;;
+  esac
+done
+if [[ "${CLAUDE_AGENT_INVOCATION:-0}" == "1" ]]; then
+  QUIET=1
+fi
+
+log() {
+  if [[ "$QUIET" -eq 0 ]]; then
+    printf '%s\n' "$*"
+  fi
+}
+
+err() {
+  printf '%s\n' "$*" >&2
+}
+
+die() {
+  err "$*"
+  exit 1
+}
+
+# --- dependency check --------------------------------------------------------
+
+check_deps() {
+  local missing=()
+  command -v curl >/dev/null 2>&1 || missing+=("curl")
+  command -v jq   >/dev/null 2>&1 || missing+=("jq")
+  if [[ ${#missing[@]} -gt 0 ]]; then
+    err "✗ Brak wymaganych narzędzi: ${missing[*]}"
+    err ""
+    err "Zainstaluj:"
+    err "  macOS:  brew install ${missing[*]}"
+    err "  Debian/Ubuntu:  sudo apt install ${missing[*]}"
+    exit 1
+  fi
+}
+
+# --- .env loader -------------------------------------------------------------
+# Minimal KEY=value parser. Ignores blank lines and #-comments, strips matching
+# surrounding quotes, and never overrides already-set env vars (parity with the
+# old refresh-mobilems-api-spec.js loader).
+
+load_dotenv() {
+  local env_path="${PWD}/.env"
+  [[ -f "$env_path" ]] || return 0
+  local line key value first last
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    # trim leading/trailing whitespace
+    line="${line#"${line%%[![:space:]]*}"}"
+    line="${line%"${line##*[![:space:]]}"}"
+    [[ -z "$line" ]] && continue
+    [[ "${line:0:1}" == "#" ]] && continue
+    [[ "$line" != *"="* ]] && continue
+    key="${line%%=*}"
+    value="${line#*=}"
+    # trim whitespace around key/value
+    key="${key#"${key%%[![:space:]]*}"}"
+    key="${key%"${key##*[![:space:]]}"}"
+    value="${value#"${value%%[![:space:]]*}"}"
+    value="${value%"${value##*[![:space:]]}"}"
+    [[ -z "$key" ]] && continue
+    # strip matching surrounding quotes (single or double)
+    first="${value:0:1}"
+    last="${value: -1}"
+    if [[ ${#value} -ge 2 ]] && { [[ "$first" == '"' && "$last" == '"' ]] || [[ "$first" == "'" && "$last" == "'" ]]; }; then
+      value="${value:1:${#value}-2}"
+    fi
+    # only set if not already in env
+    if [[ -z "${!key+x}" ]]; then
+      export "$key=$value"
+    fi
+  done < "$env_path"
+  log "→ loaded .env from $env_path"
+}
+
+# --- env-var validation (per Linear FRA-95 — Emil's request) ----------------
+# This runs as the very first step after .env loading. We MUST NOT attempt any
+# HTTP call until both credentials are present.
+
+validate_env_vars() {
+  if [[ -z "${MOBILEMS_LOGIN:-}" || -z "${MOBILEMS_PASSWORD:-}" ]]; then
+    err "✗ Brak wymaganych zmiennych środowiskowych dla MuzaCMS API:"
+    err "    MOBILEMS_LOGIN, MOBILEMS_PASSWORD"
+    err ""
+    err "Ustaw je w shellu:"
+    err "    export MOBILEMS_LOGIN=..."
+    err "    export MOBILEMS_PASSWORD=..."
+    err ""
+    err "Lub w pliku .env w katalogu głównym projektu:"
+    err "    MOBILEMS_LOGIN=..."
+    err "    MOBILEMS_PASSWORD=..."
+    err ""
+    err "Szczegóły: @smartsoft001-mobilems/claude-plugins README.md"
+    exit 1
+  fi
+}
+
+# --- output dir resolution ---------------------------------------------------
+# Mirrors resolveOutDir() in the old JS. Looks for shared-assets/ walking up
+# from this script's directory.
+
+resolve_out_dir() {
+  local script_dir
+  script_dir="$(cd "$(dirname "$0")" && pwd)"
+  # Installed layout (per-variant copy made by nx build):
+  #   <pkg-root>/plugins/<variant>/scripts/refresh-mobilems-api-spec.sh
+  #   <pkg-root>/shared-assets/mobilems-api.json
+  # Source layout:
+  #   packages/shared/claude-plugins/scripts/refresh-mobilems-api-spec.sh
+  #   packages/shared/claude-plugins/src/shared-assets/
+  local candidates=(
+    "$script_dir/../../../shared-assets"
+    "$script_dir/../shared-assets"
+    "$script_dir/../src/shared-assets"
+  )
+  local c
+  for c in "${candidates[@]}"; do
+    if [[ -d "$c" ]]; then
+      (cd "$c" && pwd)
+      return 0
+    fi
+  done
+  # No existing dir — pick the first candidate whose parent exists so we can
+  # mkdir into it.
+  for c in "${candidates[@]}"; do
+    if [[ -d "$(dirname "$c")" ]]; then
+      mkdir -p "$c"
+      (cd "$c" && pwd)
+      return 0
+    fi
+  done
+  # Last resort: create alongside the script.
+  mkdir -p "$script_dir/shared-assets"
+  (cd "$script_dir/shared-assets" && pwd)
+}
+
+# --- cache decision ----------------------------------------------------------
+# Mirrors cacheDecision() in the old JS.
+
+MAX_CACHE_AGE_S=$((8 * 60 * 60))
+
+iso_to_epoch() {
+  # macOS BSD date and GNU date diverge — try both forms.
+  local iso="$1"
+  if date -j -f "%Y-%m-%dT%H:%M:%SZ" "${iso%%.*}Z" "+%s" >/dev/null 2>&1; then
+    date -j -f "%Y-%m-%dT%H:%M:%SZ" "${iso%%.*}Z" "+%s"
+  elif date -d "$iso" "+%s" >/dev/null 2>&1; then
+    date -d "$iso" "+%s"
+  else
+    echo "0"
+  fi
+}
+
+cache_decision() {
+  # Echoes either "fetch:<reason>" or "skip:<age_seconds>".
+  local session_id="$1"
+  if [[ -z "$session_id" ]]; then
+    echo "fetch:manual/terminal invocation"
+    return
+  fi
+  if [[ ! -f "$SPEC_PATH" ]]; then
+    echo "fetch:spec file missing"
+    return
+  fi
+  if [[ ! -f "$META_PATH" ]]; then
+    echo "fetch:meta file missing"
+    return
+  fi
+  local meta_session meta_fetched_at meta_epoch now age
+  meta_session="$(jq -r '.sessionId // ""' "$META_PATH" 2>/dev/null)"
+  meta_fetched_at="$(jq -r '.fetchedAt // ""' "$META_PATH" 2>/dev/null)"
+  if [[ "$meta_session" != "$session_id" ]]; then
+    echo "fetch:new Claude Code session"
+    return
+  fi
+  if [[ -z "$meta_fetched_at" ]]; then
+    echo "fetch:meta missing fetchedAt"
+    return
+  fi
+  meta_epoch="$(iso_to_epoch "$meta_fetched_at")"
+  now="$(date +%s)"
+  age=$((now - meta_epoch))
+  if [[ "$meta_epoch" -le 0 || "$age" -gt "$MAX_CACHE_AGE_S" ]]; then
+    echo "fetch:cache older than 8 hours"
+    return
+  fi
+  echo "skip:$age"
+}
+
+# --- HTML extraction helpers -------------------------------------------------
+
+extract_csrf() {
+  # Mirrors extractCsrf() in the old JS.
+  local html="$1"
+  local token
+  token="$(printf '%s' "$html" | grep -oE 'name="_csrf_token"[[:space:]]+value="[^"]+"' | head -n 1 | sed -E 's/.*value="([^"]+)".*/\1/')"
+  if [[ -z "$token" ]]; then
+    die "✗ Could not find _csrf_token in login form HTML."
+  fi
+  printf '%s' "$token"
+}
+
+extract_swagger_data() {
+  # Mirrors extractSwaggerData() in the old JS.
+  # The <script id="swagger-data" type="application/json"> tag wraps a JSON blob.
+  local html="$1"
+  local json
+  # awk lets us span newlines safely, where sed's portability gets hairy.
+  json="$(printf '%s' "$html" | awk '
+    BEGIN { in_block = 0 }
+    {
+      line = $0
+      if (in_block == 0) {
+        idx = index(line, "<script id=\"swagger-data\" type=\"application/json\">")
+        if (idx > 0) {
+          in_block = 1
+          line = substr(line, idx + length("<script id=\"swagger-data\" type=\"application/json\">"))
+        } else {
+          next
+        }
+      }
+      end_idx = index(line, "</script>")
+      if (end_idx > 0) {
+        printf "%s", substr(line, 1, end_idx - 1)
+        exit
+      } else {
+        printf "%s\n", line
+      }
+    }
+  ')"
+  # trim leading/trailing whitespace
+  json="${json#"${json%%[![:space:]]*}"}"
+  json="${json%"${json##*[![:space:]]}"}"
+  if [[ -z "$json" ]]; then
+    die "✗ Could not find <script id=\"swagger-data\"> tag in /docs/api response. Login may have silently failed, or the docs page structure changed."
+  fi
+  printf '%s' "$json"
+}
+
+# --- main --------------------------------------------------------------------
+
+check_deps
+load_dotenv
+validate_env_vars
+
+OUT_DIR="$(resolve_out_dir)"
+SPEC_PATH="$OUT_DIR/mobilems-api.json"
+META_PATH="$OUT_DIR/mobilems-api.meta.json"
+
+SESSION_ID="${CLAUDE_CODE_SESSION_ID:-}"
+DECISION="$(cache_decision "$SESSION_ID")"
+
+if [[ "$DECISION" == skip:* ]]; then
+  age_s="${DECISION#skip:}"
+  age_min=$(( (age_s + 30) / 60 ))
+  fetched_at="$(jq -r '.fetchedAt // "unknown"' "$META_PATH" 2>/dev/null)"
+  log "✓ spec cached for this Claude Code session (refreshed ${age_min} min ago at ${fetched_at}), skipping fetch"
+  exit 0
+fi
+
+REASON="${DECISION#fetch:}"
+log "Refreshing MuzaCMS API spec from $BASE ($REASON)"
+
+JAR="$(mktemp -t mobilems-cookies.XXXXXX)"
+trap 'rm -f "$JAR"' EXIT
+
+log "→ GET /admin/login (CSRF + session)"
+LOGIN_HTML="$(curl --silent --show-error \
+  --cookie-jar "$JAR" \
+  "$LOGIN_URL")" || die "✗ Could not fetch $LOGIN_URL"
+
+CSRF="$(extract_csrf "$LOGIN_HTML")"
+
+log "→ POST /admin/login"
+# We need the HTTP status of the POST without following the redirect.
+LOGIN_POST_STATUS_BODY="$(curl --silent --show-error \
+  --output /dev/null \
+  --write-out '%{http_code} %{redirect_url}' \
+  --cookie-jar "$JAR" --cookie "$JAR" \
+  --data-urlencode "_username=${MOBILEMS_LOGIN}" \
+  --data-urlencode "_password=${MOBILEMS_PASSWORD}" \
+  --data-urlencode "_csrf_token=${CSRF}" \
+  --data-urlencode "_remember_me=on" \
+  -X POST \
+  "$LOGIN_URL")" || die "✗ POST $LOGIN_URL failed."
+
+LOGIN_STATUS="${LOGIN_POST_STATUS_BODY%% *}"
+LOGIN_REDIRECT="${LOGIN_POST_STATUS_BODY#* }"
+
+if [[ "$LOGIN_STATUS" != "302" ]]; then
+  die "✗ Login failed: expected 302 redirect, got HTTP ${LOGIN_STATUS}. Check MOBILEMS_LOGIN and MOBILEMS_PASSWORD."
+fi
+if [[ "$LOGIN_REDIRECT" == *"/admin/login"* ]]; then
+  die "✗ Login failed: server redirected back to /admin/login. Credentials were likely rejected."
+fi
+
+log "→ GET /docs/api"
+DOCS_STATUS_FILE="$(mktemp -t mobilems-docs-status.XXXXXX)"
+trap 'rm -f "$JAR" "$DOCS_STATUS_FILE"' EXIT
+
+DOCS_HTML="$(curl --silent --show-error \
+  --write-out '%{http_code}' \
+  --cookie-jar "$JAR" --cookie "$JAR" \
+  --output - \
+  "$DOCS_URL" 2>/dev/null | tee >(tail -c 3 > "$DOCS_STATUS_FILE"))"
+
+# Strip the trailing 3-char status code from the body
+DOCS_STATUS="$(cat "$DOCS_STATUS_FILE")"
+DOCS_HTML="${DOCS_HTML%$DOCS_STATUS}"
+
+if [[ "$DOCS_STATUS" != "200" ]]; then
+  die "✗ Docs page returned HTTP ${DOCS_STATUS}. Session may not be authenticated."
+fi
+if [[ "$DOCS_HTML" == *"login-card-body"* ]]; then
+  die "✗ Docs page returned the login form — session not authenticated."
+fi
+
+SPEC_JSON="$(extract_swagger_data "$DOCS_HTML")"
+
+# Validate + pretty-print through jq.
+if ! printf '%s' "$SPEC_JSON" | jq '.' > "${SPEC_PATH}.tmp"; then
+  rm -f "${SPEC_PATH}.tmp"
+  die "✗ Swagger JSON failed to parse."
+fi
+mv -f "${SPEC_PATH}.tmp" "$SPEC_PATH"
+
+SPEC_TITLE="$(jq -r '.spec.info.title // .info.title // "unknown"' "$SPEC_PATH")"
+SPEC_VERSION="$(jq -r '.spec.info.version // .info.version // "unknown"' "$SPEC_PATH")"
+
+# Preserve cached sessionId when running outside Claude Code (manual/terminal)
+# so a future in-session call still hits the cache. In-Claude-Code calls always
+# overwrite with the current session id.
+EFFECTIVE_SESSION_ID="$SESSION_ID"
+if [[ -z "$EFFECTIVE_SESSION_ID" && -f "$META_PATH" ]]; then
+  EFFECTIVE_SESSION_ID="$(jq -r '.sessionId // ""' "$META_PATH" 2>/dev/null)"
+fi
+ISO_NOW="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+jq -n \
+  --arg sid "$EFFECTIVE_SESSION_ID" \
+  --arg ts  "$ISO_NOW" \
+  '{sessionId: (if $sid == "" then null else $sid end), fetchedAt: $ts}' \
+  > "$META_PATH"
+
+BYTES="$(wc -c < "$SPEC_PATH" | tr -d ' ')"
+log "✓ Refreshed ${BYTES} bytes — ${SPEC_TITLE} ${SPEC_VERSION}"
+log "  $SPEC_PATH"

package/plugins/mobilems/skills/mobilems-docs-reader/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: mobilems-docs-reader
+description: Answer questions about the MuzaCMS / MobileMS indexer API by reading a freshly-fetched OpenAPI spec. Use whenever the user asks about endpoints, request/response shapes, status codes, auth, or behavior of the indexer API (host develop-indexer-api.mobilems.pl). Read-only — never fabricates endpoints.
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+You answer questions about the **MuzaCMS / MobileMS indexer API** strictly from the OpenAPI (Swagger 2.0) specification. You never invent endpoints, schemas, or status codes — if it is not in the spec, you say so plainly.
+
+The spec is **not bundled**. It is fetched from the live MuzaCMS instance by a refresh script that lives next to this skill, using credentials supplied via environment variables. The script caches the fetched spec per Claude Code session (with an 8-hour TTL safety net), so it may skip the actual network call and reuse a cached copy on follow-up invocations within the same session.
+
+## Step 1 — Run the refresh script (mandatory)
+
+On every invocation, run the refresh script via Bash. The script itself decides whether to actually fetch — it owns the cache. Your job is only to run it and react to the result. A successful run may be either:
+
+- A real fetch (`Refreshing MuzaCMS API spec from ... → GET /admin/login → POST /admin/login → GET /docs/api → ✓ Refreshed N bytes ...`), or
+- A cache hit (`✓ spec cached for this Claude Code session (refreshed N min ago at ...), skipping fetch`).
+
+Both are exit-code-0 successes. Treat them identically and proceed to Step 2. **Do not** attempt to bypass the cache, delete the cache file, or force a refetch — the cache is intentional and the script's decision is authoritative.
+
+### Invocation
+
+The refresh script is shipped under `plugins/mobilems/scripts/`. Invoke it through `bash` so the executable bit is irrelevant:
+
+```
+bash ./node_modules/@smartsoft001-mobilems/claude-plugins/plugins/mobilems/scripts/refresh-mobilems-api-spec.sh --quiet
+```
+
+Outcomes:
+
+- **Success (exit 0)** → jump to Step 2.
+- **Script-level error** (missing env vars, missing tooling, auth rejected, HTTP error, parse failure, etc.) → jump to the matching Fail mode below.
+- **Permission denied by Claude Code** → jump to "Fail mode — permission denied".
+
+The script reads two environment variables — `MOBILEMS_LOGIN` and `MOBILEMS_PASSWORD` — performs the Symfony CSRF + session login against `https://develop-indexer.mobilems.pl`, fetches `/docs/api`, and writes the spec to `shared-assets/mobilems-api.json` inside the installed package. It also auto-loads `.env` from the current working directory; no shell sourcing is needed.
+
+### Fail mode — permission denied by Claude Code
+
+If the Bash call is rejected by Claude Code's permission system, stop and tell the user verbatim:
+
+> The MuzaCMS spec could not be refreshed because Claude Code denied permission to run the refresh script. To allow it, add this entry to your project's `.claude/settings.json` (committed) or `.claude/settings.local.json` (per-dev, gitignored) under `permissions.allow`, then ask again:
+>
+> - `"Bash(bash ./node_modules/@smartsoft001-mobilems/claude-plugins/plugins/mobilems/scripts/refresh-mobilems-api-spec.sh:*)"`
+
+Do not attempt to answer the user's question from training knowledge. Do not invent alternative invocation patterns to try to bypass the denial.
+
+### Fail mode — missing env vars
+
+If the script exits non-zero with a message starting `✗ Brak wymaganych zmiennych środowiskowych` (or English equivalent listing `MOBILEMS_LOGIN` / `MOBILEMS_PASSWORD`), **stop immediately**. Relay the script's message verbatim to the user.
+
+Do not attempt to answer the user's question from training knowledge. Do not guess. Do not read any pre-existing `mobilems-api.json` that may be lying around in `node_modules/` — without a successful refresh you have no confirmation it is current.
+
+### Fail mode — missing tooling
+
+If the script exits with a message about missing `curl` or `jq`, relay it verbatim. The script tells the user exactly how to install the missing dependency (`brew install jq` / `apt install jq`).
+
+### Fail mode — other script failures
+
+If the script fails for any other reason (HTTP error, auth rejected, parse failure), report the exact error message from the script back to the user and stop. Do not answer the API question.
+
+## Step 2 — Locate the freshly-written spec
+
+Use `Glob` with this pattern:
+
+```
+**/claude-plugins/**/shared-assets/mobilems-api.json
+```
+
+The hit lives under `node_modules/@smartsoft001-mobilems/claude-plugins/shared-assets/` after a successful refresh. Exclude `dist/` and `tmp/` from the Glob, but **do** allow `node_modules/`.
+
+If the Glob returns nothing after the refresh script reported success, something is wrong with the install layout — tell the user and stop.
+
+## Step 3 — Answer from the spec
+
+The spec is **Swagger 2.0** with this wrapping shape:
+
+```
+{ "spec": { "swagger": "2.0", "paths": {...}, "definitions": {...} } }
+```
+
+Always traverse into `.spec` first.
+
+When the user asks about endpoints:
+
+1. **Locate the path** in `spec.paths`. Look for the exact path the user mentioned, including any path parameters (`{id}`).
+2. **Quote the HTTP method(s) and path verbatim.** Example: `GET /api/objects/{id}`.
+3. For request bodies and responses, cite the `$ref` target by name and (briefly) summarize its shape from `spec.definitions`.
+4. For status codes, list each documented response from `responses` with its `description`.
+5. For auth, check both the operation-level `security` and the global `spec.securityDefinitions`.
+
+If the user asks about a path that is **not in the spec**, say so explicitly:
+
+> The spec does not document a `DELETE /api/articles/{id}` endpoint. The articles paths in the spec are: `[list actual paths]`. If you've seen this endpoint elsewhere, it may exist in the running service without being documented — verify with a live request.
+
+## Known caveats — always surface when relevant
+
+- **Response schemas occasionally diverge from runtime.** Documented response shapes have, in practice, not always matched what the live API actually returns. When the user is about to implement against a response schema, add a brief reminder to verify with a real request before relying on the documented shape.
+- **Spec is regenerated server-side from PHP annotations.** Newly added endpoints in the live service may not appear until the next backend deployment, even with a fresh fetch.
+- **Auth flow nuance:** the spec describes the indexer API itself; the `/admin/login` flow used by the refresh script is separate and not documented in the spec.
+
+## Answering style
+
+- Be terse. The user wants a specific fact, not a tutorial on Swagger.
+- Always include exact path + method + relevant status codes when applicable.
+- When quoting definitions, use the schema name (e.g., `Object`, `Unauthorised`) as it appears in `spec.definitions`.
+- If multiple endpoints match a vague question, list them — don't pick one arbitrarily.
+
+## When NOT to use this skill
+
+- Non-MobileMS APIs (any other host).
+- Generic REST/OpenAPI guidance unrelated to the indexer.
+- Schema design decisions ("should I add X field?") — this skill only describes what exists.
+- Anything requiring a live network call to the API itself.

package/plugins/flow/.claude-plugin/README.md

@@ -1,91 +0,0 @@
-# Flow Plugin for Claude Code
-
-Development flow skills for Linear-driven development workflow.
-
-## Workflow Skills
-
-| Skill | Description |
-|-------|-------------|
-| `/commit` | Create conventional commit based on Linear task |
-| `/impl` | Implement plans from `plan.md` attachment on Linear issue; orchestration saved as `orchestration.md` attachment |
-| `/plan` | Create implementation plan, save as `plan.md` attachment on Linear issue, add `AI Plan` label |
-| `/push` | Push changes and update Linear status (keeps `plan.md` / `orchestration.md` attachments on the issue) |
-
-## Installation
-
-### 1. Enable plugin in project's `.claude/settings.json`:
-
-```json
-{
-  "enabledPlugins": {
-    "flow@mobilems": true
-  }
-}
-```
-
-### 2. Merge permissions from template
-
-Copy permissions from `settings.template.json` to your project's `.claude/settings.json`.
-
-**Quick merge script:**
-
-```bash
-# From project root
-node -e "
-const template = require('node_modules/@smartsoft001-mobilems/claude-plugins/plugins/flow/.claude-plugin/settings.template.json');
-const settings = require('.claude/settings.json');
-
-settings.permissions = settings.permissions || { allow: [], deny: [], ask: [] };
-settings.permissions.allow = [...new Set([...settings.permissions.allow, ...template.permissions.allow])];
-settings.permissions.ask = [...new Set([...settings.permissions.ask, ...template.permissions.ask])];
-
-require('fs').writeFileSync('.claude/settings.json', JSON.stringify(settings, null, 2));
-console.log('Permissions merged!');
-"
-```
-
-## Required MCP Servers
-
-Configure these in your `.mcp.json`:
-
-- `linear` - Linear API integration (MCP prefix `mcp__linear__`)
-- `playwright` - Browser automation for screenshots
-
-### Linear MCP tool dependencies
-
-`/plan`, `/impl`, and `/push` depend on the following `mcp__linear__*` tools (in addition to the standard comment/issue tools):
-
-- `create_attachment` (base64 upload), `get_attachment`, `delete_attachment` — for persisting `plan.md` / `orchestration.md` on issues (attachments are also returned by `get_issue`)
-- `list_issue_labels` — to find the workspace-level `AI Plan` label (the label is pre-configured organization-wide; `/plan` does not create it)
-
-Run `/mcp` after authenticating the Linear MCP server to see the exact loaded tool names. If a tool is exposed under a different name in your deployment, update `settings.template.json` and the `allowed-tools` lists in the three skills accordingly.
-
-## Permission Strategy
-
-### Automatic (allow)
-- Git read operations (status, diff, log, show)
-- Nx commands (test, lint, build)
-- Linear API (read/write issues, comments)
-- Playwright (screenshots)
-- Utility skills
-
-### Requires Confirmation (ask)
-- Workflow skills (/commit, /impl, /plan, /push)
-- `git commit` - creating commits
-- `git push` - pushing to remote
-- `gh pr create` - creating pull requests
-
-## Utility Skills
-
-| Skill | Description |
-|-------|-------------|
-| `maia-files-upload` | Upload files to Maia API |
-| `maia-files-delete` | Delete files from Maia API |
-| `browser-capture` | Capture screenshots with Playwright |
-| `linear-suggestion` | Create Linear issues for improvements |
-| `test-unit` | Run unit tests with coverage |
-| `a11y-audit` | Accessibility audit |
-
-## Agents
-
-See `agents/` directory for full list of specialized agents used by flow skills.