@mmmbuto/nexuscrew 0.8.32 → 0.8.34

package/skills/fill-forms/scripts/prepare_signature.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Prepare an explicitly authorised local signature image for PDF overlay."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import tempfile
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Remove paper background, crop and export a signature as transparent PNG. "
+            "Use only with the signer's explicit authorisation."
+        )
+    )
+    parser.add_argument("src", type=Path)
+    parser.add_argument("out", type=Path)
+    parser.add_argument("--dark", type=int, default=90)
+    parser.add_argument("--light", type=int, default=185)
+    parser.add_argument("--margin", type=int, default=12)
+    parser.add_argument(
+        "--min-alpha",
+        type=int,
+        default=60,
+        help="discard low-opacity background pixels; 0 disables",
+    )
+    parser.add_argument(
+        "--max-width",
+        type=int,
+        default=0,
+        help="downsize to this pixel width; 0 preserves the cropped width",
+    )
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="replace an existing output file, never the source",
+    )
+    return parser.parse_args()
+
+
+def load_dependencies():
+    try:
+        import numpy
+        from PIL import Image
+    except ImportError as exc:
+        raise SystemExit(
+            "Missing dependency: numpy and Pillow are required. With user "
+            "consent, install the packages listed in requirements.txt."
+        ) from exc
+    return numpy, Image
+
+
+def validate_args(args: argparse.Namespace) -> tuple[Path, Path]:
+    source = args.src.resolve()
+    output_unresolved = args.out.expanduser()
+    if output_unresolved.is_symlink():
+        raise SystemExit("Output must not be a symbolic link.")
+    output = output_unresolved.resolve()
+
+    if not source.is_file():
+        raise SystemExit(f"Input image not found or not a regular file: {source}")
+    if source == output:
+        raise SystemExit("Source and output must be different files.")
+    if output.exists() and not args.overwrite:
+        raise SystemExit("Output already exists. Use --overwrite for an intentional revision.")
+    if output.suffix.lower() != ".png":
+        raise SystemExit("Output must use the .png extension.")
+    if not 0 <= args.dark < args.light <= 255:
+        raise SystemExit("Require 0 <= --dark < --light <= 255.")
+    if args.margin < 0 or args.margin > 1000:
+        raise SystemExit("--margin must be between 0 and 1000 pixels.")
+    if not 0 <= args.min_alpha <= 255:
+        raise SystemExit("--min-alpha must be between 0 and 255.")
+    if args.max_width < 0 or args.max_width > 20_000:
+        raise SystemExit("--max-width must be between 0 and 20000 pixels.")
+    return source, output
+
+
+def flatten_to_greyscale(Image, source):
+    if source.mode in ("RGBA", "LA") or (
+        source.mode == "P" and "transparency" in source.info
+    ):
+        rgba = source.convert("RGBA")
+        flattened = Image.new("RGB", rgba.size, (255, 255, 255))
+        flattened.paste(rgba, mask=rgba.getchannel("A"))
+        return flattened.convert("L")
+    return source.convert("L")
+
+
+def main() -> None:
+    args = parse_args()
+    source_path, output_path = validate_args(args)
+    np, Image = load_dependencies()
+
+    try:
+        with Image.open(source_path) as source:
+            source.load()
+            grey = np.asarray(flatten_to_greyscale(Image, source), dtype=np.float32)
+    except Exception as exc:
+        raise SystemExit(f"Could not read input image: {exc}") from exc
+
+    dark = float(args.dark)
+    light = float(args.light)
+    alpha = np.clip((light - grey) / (light - dark), 0.0, 1.0)
+
+    ink = alpha > 0.35
+    height, width = ink.shape
+    column_ink = ink.sum(axis=0)
+    row_ink = ink.sum(axis=1)
+    minimum_column = max(3, int(0.004 * height))
+    minimum_row = max(3, int(0.004 * width))
+    columns = np.where(column_ink >= minimum_column)[0]
+    rows = np.where(row_ink >= minimum_row)[0]
+    if columns.size == 0 or rows.size == 0:
+        raise SystemExit(
+            "No consistent ink stroke detected. Adjust --dark/--light and inspect the source."
+        )
+
+    margin = args.margin
+    x0 = max(0, int(columns[0]) - margin)
+    x1 = min(width, int(columns[-1]) + 1 + margin)
+    y0 = max(0, int(rows[0]) - margin)
+    y1 = min(height, int(rows[-1]) + 1 + margin)
+
+    cropped_alpha = (alpha[y0:y1, x0:x1] * 255).astype(np.uint8)
+    if args.min_alpha:
+        cropped_alpha[cropped_alpha < args.min_alpha] = 0
+
+    crop_height, crop_width = cropped_alpha.shape
+    pixels = np.zeros((crop_height, crop_width, 4), dtype=np.uint8)
+    pixels[..., 3] = cropped_alpha
+    prepared = Image.fromarray(pixels, "RGBA")
+
+    if args.max_width and crop_width > args.max_width:
+        new_height = max(1, round(crop_height * args.max_width / crop_width))
+        prepared = prepared.resize(
+            (args.max_width, new_height),
+            Image.Resampling.LANCZOS,
+        )
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = tempfile.NamedTemporaryFile(
+        prefix=f".{output_path.name}.",
+        suffix=".tmp",
+        dir=output_path.parent,
+        delete=False,
+    )
+    temporary = Path(handle.name)
+    handle.close()
+    try:
+        prepared.save(temporary, format="PNG")
+        os.replace(temporary, output_path)
+        os.chmod(output_path, 0o600)
+    except Exception:
+        temporary.unlink(missing_ok=True)
+        raise
+    print(
+        f"Saved: {output_path} | crop {prepared.width}x{prepared.height}px "
+        f"from {width}x{height}px"
+    )
+    print(
+        "Verify the PNG on a pure white background. Keep it private and use it "
+        "only for the specifically authorised document."
+    )
+
+
+if __name__ == "__main__":
+    main()

package/skills/mail-assistant/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: mail-assistant
+description: Use for mailbox discovery, email search and reading, priority triage, attachment review, folder organisation, reply drafting, explicit sending, or recurring mail checks through an available Gmail or IMAP/SMTP MCP connector. Select the user-facing language from the request and the draft language from the thread, while preserving read-before-write discipline and explicit confirmation for consequential mail actions.
+---
+
+# Mail Assistant
+
+Use the mail tools already exposed by the current client. Discover folders,
+sender identities and supported operations live; never assume provider-specific
+folder names or account configuration.
+
+## Select languages
+
+Choose the language for digests, questions and explanations in this order:
+
+1. the user's explicit language preference;
+2. the language of the current request;
+3. a reliable client or system locale;
+4. English.
+
+Write a reply draft in the language of the email thread unless the user asks
+for another language. Preserve names, quoted text and required legal or
+technical terms; do not translate them merely to match the interface language.
+
+## Choose tools
+
+1. Prefer an exposed Gmail connector for Gmail-hosted workflows.
+2. Otherwise use an exposed IMAP/SMTP mail MCP such as `mcp-email-rs`.
+3. Search narrowly before listing large folders, and fetch complete message
+   bodies only when needed for classification, attachments or drafting.
+4. If no mail tool is available, explain the missing capability. When this
+   skill is packaged with NexusCrew, the optional companion is documented in
+   `../../MCP_COMPANIONS.md`. Do not install or configure it without consent.
+
+## Apply the safety boundary
+
+- Reading and searching are allowed when the user asks to inspect mail.
+- Treat moves, flags, drafts, folder changes and calendar/reminder creation as
+  explicit mutations; perform only the mutation the user requested.
+- Treat deletion and sending as consequential external actions. Confirm the
+  exact targets and intended content immediately before acting unless the
+  user's current request already gives unambiguous final authorization.
+- Prefer recoverable archive or Trash moves over permanent deletion.
+- Re-fetch message identifiers after moves; IMAP UIDs are folder-scoped and
+  can change.
+- Never expose credentials, authentication links or sensitive message content
+  in logs, push notifications, TTS or unrelated summaries.
+- Never infer an authorised sender identity. Use identities returned by the
+  connector or explicitly supplied by the user.
+
+## Triage and draft
+
+1. Fetch the smallest useful set of messages.
+2. Classify each item as urgent/action required, reply soon, waiting, or
+   informational, using the user's own priorities when available.
+3. Read attachments only when necessary and identify their type before
+   downloading.
+4. Present a compact digest with evidence from the messages and a proposed
+   next action.
+5. Draft only when requested. Preserve the user's tone, distinguish facts from
+   assumptions and leave unresolved details visible.
+6. Before sending, show or re-confirm recipients, subject, body and attachments.
+7. Report only actions that the tool actually completed.
+
+## Recurring checks
+
+Create recurring monitoring only when explicitly requested. Use the
+client-native scheduler or loop mechanism instead of manual polling, avoid
+duplicate jobs, respect quiet hours, and remain silent on unchanged ticks when
+the host workflow supports silent monitoring. A recurring authorization does
+not automatically authorize sending or permanent deletion.

package/skills/mail-assistant/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Mail Assistant"
+  short_description: "Safely triage and draft email in context"
+  default_prompt: "Use mail-assistant to review my new mail and prepare a concise action digest."

package/skills/memory/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: memory
+description: Use when reading or writing persistent AI-agent state through a Memory MCP server, including category discovery, versioned reads and writes, merge patches, optimistic concurrency, bounded append-only journals, search, context loading and history. Keep durable state separate from bounded logs and choose the user-facing language from the request.
+---
+
+# Memory
+
+Use the exposed Memory MCP tools rather than reading or editing the server's
+database, cache or state files directly.
+
+## Select response language
+
+Choose the language for explanations and summaries in this order:
+
+1. the user's explicit language preference;
+2. the language of the current request;
+3. a reliable client or system locale;
+4. English.
+
+Keep category names, tool names, JSON fields, paths and quoted source text
+unchanged unless the user explicitly asks to translate them.
+
+## Understand the model
+
+- A category is a named JSON document. `memory_read` takes a `category`, not a
+  nested key.
+- Reads may be broadly available while writes are scoped by the server's
+  device or actor ACL.
+- Every write is versioned; inspect `memory_history` when provenance matters.
+- Treat recalled state as a snapshot. Verify live files, flags and services
+  before acting on drift-prone facts.
+
+## Warm up narrowly
+
+1. Call `memory_list` to discover available categories.
+2. Read only relevant categories with `memory_read`, or load a bounded set with
+   `memory_context`.
+3. Use `memory_search` when the category is unknown.
+
+Do not load every category by default.
+
+## Write safely
+
+`memory_write {category, content}` replaces the category by default.
+
+- Set `merge:true` for a top-level patch: supplied keys are inserted or
+  overwritten, JSON `null` deletes a key, and untouched keys remain.
+- Pass `expected_hash` from the prior read/list result for read-modify-write
+  workflows so concurrent updates fail instead of being overwritten.
+- Never write another device's namespace unless the server ACL and the user's
+  request explicitly authorize it.
+
+## Separate state from journals
+
+Use `memory_append` for a bounded append-only log category. The server stamps
+entries and prunes them according to retention.
+
+- Do not simulate a journal by adding ever-growing dated keys to a normal
+  memory category.
+- Do not use `memory_write` on a log category.
+- Do not use `memory_append` on a normal memory category.
+
+A useful convention is:
+
+- `<name>_state`: lean declarative state, updated with `memory_write`;
+- `<name>_log`: bounded event journal, updated with `memory_append`.
+
+Facts that must never be pruned belong in normal durable state or an external
+document store, not in a bounded log.
+
+## Search and inspect
+
+- Use `memory_search` for BM25 full-text retrieval across categories.
+- Use `memory_search_semantic` only when the server exposes and supports it.
+- Use `memory_history` to inspect versions before restoring or explaining a
+  change.
+- Report writes only after the tool confirms them.
+
+If no Memory MCP tool is available and this skill is packaged with NexusCrew,
+the optional companion is documented in `../../MCP_COMPANIONS.md`. Explain the
+missing capability and ask before installing or configuring anything.

package/skills/memory/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Memory"
+  short_description: "Use persistent agent memory safely"
+  default_prompt: "Use memory to inspect and update the durable state relevant to this task."

package/skills/nexuscrew-agent/SKILL.md

@@ -36,6 +36,26 @@ Apply these rules:
 
 The MCP server is the stdio command `nexuscrew mcp` and must be registered in the host AI client. If the `nc_*` tools are not exposed, report that the bridge is not configured in that session and use the fallback flows below where applicable.
 
+## Optional capability companions
+
+NexusCrew does not make unrelated MCP servers hidden dependencies. When the
+user requests durable structured memory, document retrieval, bounded worker
+delegation or mailbox access:
+
+1. Discover the tools already exposed by the current AI client.
+2. Use an available tool that covers the request.
+3. If the capability is absent, consult the packaged
+   `../../mcp-companions.json` catalog and mention the matching optional
+   companion once.
+4. Explain the capability it adds and link its public repository.
+5. Ask before installing software, changing MCP configuration, starting a
+   service or requesting credentials.
+
+Never recommend a companion during unrelated work, repeatedly advertise it, or
+claim it is required by NexusCrew. The catalog is discovery metadata only; it
+does not authorize installation or external actions. See
+`../../MCP_COMPANIONS.md` for the human-readable guide.
+
 ## File exchange (inbox / outbox)
 
 Per session, NexusCrew watches `<root>/<session>/{inbox,outbox}` (root = `$NEXUSCREW_FILES_ROOT`, default `~/NexusFiles`):

package/skills/vl-msa/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: vl-msa
+description: Use when indexing or retrieving documents, notes, research or past conversations through a VL-MSA long-term-memory MCP server, including collections, batch indexing, BM25 or hybrid search, full-document grounding, remember/forget and bounded multi-hop interleaving. Enforce locate-then-ground retrieval and choose the user-facing language from the request.
+---
+
+# VL MSA
+
+Use VL-MSA for durable searchable source material. Collections persist across
+sessions; BM25 works without embeddings, while hybrid reranking is optional.
+
+## Select response language
+
+Choose the language for explanations and answers in this order:
+
+1. the user's explicit language preference;
+2. the language of the current request;
+3. a reliable client or system locale;
+4. English.
+
+Keep collection IDs, document IDs, tool names, metadata fields and quoted
+source text unchanged unless the user explicitly asks to translate them.
+
+## Locate, then ground
+
+Retrieval has two required steps:
+
+1. Call `msa_search {collection, query, k}` to locate relevant chunks.
+2. Call `msa_fetch_doc` for the selected hit before using it as evidence.
+
+Search chunks are locators, not complete sources. Do not answer a
+context-dependent question from truncated snippets alone.
+
+## Index material
+
+- Use `msa_index` for one document or note.
+- Use `msa_index_batch` for bulk ingest.
+- Group related material into a stable named collection.
+- Inspect `msa_list_collections`, `msa_stats` or `msa_manifest` before assuming
+  a collection exists or is populated.
+
+Index only material the user is authorized to store. Preserve provenance and
+do not place credentials or unrelated personal data in collection metadata.
+
+## Manage standalone memories
+
+- Use `msa_remember` for a standalone agent memory. Its deduplication and
+  low-signal gate may decline a write.
+- Use `msa_forget` for an explicitly requested removal.
+
+Do not claim a memory was stored or removed until the tool confirms the
+outcome.
+
+## Handle multi-hop questions
+
+Use `msa_interleave_round` for one bounded route, deduplicate and read step.
+Repeat only as needed, carrying forward the grounded facts from the prior
+round. Avoid a single unbounded search.
+
+## Choose ranking
+
+- Use BM25 by default.
+- Pass `dense_alpha` only when the server is built and configured for hybrid
+  retrieval.
+- Do not describe lexical-only results as semantic retrieval.
+
+If no VL-MSA tool is available and this skill is packaged with NexusCrew, the
+optional companion is documented in `../../MCP_COMPANIONS.md`. Explain the
+missing capability and ask before installing or configuring anything.

package/skills/vl-msa/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "VL MSA"
+  short_description: "Index and ground long-term knowledge"
+  default_prompt: "Use vl-msa to find and ground the relevant source documents for this question."