SharkFin v1.0.11

Teach a task once. Reuse the workflow. Inspect the result.

SharkFin runs workflows on your machine with reusable playbooks, transparent logs, and local run proofs. Start with the Founder Decision Brief: a model-backed workflow that writes a local markdown brief. A working model provider is needed for the live mission; Gmail, Telegram, Discord, and Calendar are optional. Model prompts go to the local or cloud provider you configure.

Why SharkFin

• Published npm package for fast customer setup
• Playbooks for repeatable local automations
• Forge Outcome Studio for typed workflow generation, simulation, artifact proof, run history, and repair
• Ghostwriter for local-first brand drafting and optional SharkBook publishing
• Multi-agent workflows for practical research, writing, and file-producing pipelines
• Cited local knowledge with opt-in automatic recall
• Restart-safe scheduled jobs with retries and authenticated webhook triggers
• Rich browser, Gmail, Calendar, Telegram, and Discord operations
• Transparency logs and dry-run support
• Optional NemoClaw compatibility controls, not NVIDIA OpenShell execution

The release focus is reusable workflows with inspectable results, rather than more tools. Describe a task to Forge, review and simulate the generated playbook, then run it and inspect its artifacts. Validation checks workflow structure and declared artifact requirements, not the factual correctness of model output.

Welcome Restoration In v1.0.11

This patch restores the branded shark wordmark and OpenClaw-inspired greeting for sharkfin start and sharkfin register. First-time setup again introduces Forge self-improvement, NemoClaw compatibility controls, multi-agent runs, and the responsibility notice. The displayed version comes from the release manifest.

Returning users keep configuration checks and run-history guidance; the TUI remains compact. Registration consent, optional integration defaults, and workflow execution are unchanged. NemoClaw remains a SharkFin-side compatibility layer, not NVIDIA OpenShell execution.

Upgrade with npm install -g [email protected], then check sharkfin --version. Existing registration and customer playbooks do not need to be reset to upgrade. The longer first-time introduction is shown only when registration has not been completed.

Quick Start

npm_config_prefix="$HOME/.local" npm install -g sharkfin
export PATH="$HOME/.local/bin:$PATH"
sharkfin register
sharkfin mission start --goal "Choose our highest-value priority this week" --simulate
sharkfin mission start --goal "Choose our highest-value priority this week"
sharkfin forge runs
sharkfin outcomes

During registration, configure your model and accept the default No for any optional integrations you want to skip. Simulation previews the plan without model calls or writing the decision brief; it still records a local run proof. The live mission prints the artifact path and run ID. Open the brief to review its recommendation, assumptions, and next steps; forge runs shows run history and outcomes summarizes local seven-day results.

If npm install -g sharkfin fails with an EACCES permission error on Linux because npm is trying to write to a system path like /usr/lib/node_modules, use the user-local prefix install above.

If you prefer the standard global npm path and your machine allows it:

npm install -g sharkfin
sharkfin register
sharkfin mission start --goal "Choose our highest-value priority this week" --simulate
sharkfin mission start --goal "Choose our highest-value priority this week"
sharkfin forge runs
sharkfin outcomes

If you already have a SharkFin source checkout, run these commands from that checkout. The public documentation repository is not a source distribution:

npm install
npm run build
npm link
sharkfin register
sharkfin mission start --goal "Choose our highest-value priority this week" --simulate
sharkfin mission start --goal "Choose our highest-value priority this week"
sharkfin forge runs
sharkfin outcomes

Setup Status And Optional Runtime

Registration saves setup; the presence of ~/.sharkfin/.registered alone does not prove model readiness. Use sharkfin capabilities and sharkfin doctor to inspect local configuration. A missing cloud API key or local endpoint needs attention. A configured cloud key or local model URL means configuration is present, not that the connection has been checked or a model response has succeeded. These diagnostics make no model calls.

Standalone mission start, forge runs, and outcomes do not require sharkfin start. After your first result, optionally run sharkfin start for the long-running headless chat and scheduling runtime, or sharkfin console for the interactive terminal dashboard. start is not a terminal chat prompt and does not detach itself; stop it with Ctrl+C.

Command Reference

sharkfin start
sharkfin console
sharkfin register
sharkfin doctor
sharkfin doctor --json
sharkfin capabilities
sharkfin capabilities --json
sharkfin logs

sharkfin agents launch <count> [--role <role>]
sharkfin agents list
sharkfin agents stop <id>
sharkfin agents status
sharkfin agents run <goal> [--agents <roles>]

sharkfin playbooks list
sharkfin playbooks simulate <name> [--set key=value]
sharkfin playbooks run <name> [--set key=value]
sharkfin playbooks lint
sharkfin playbooks lint --user
sharkfin playbooks lint --all
sharkfin playbooks quarantine-fallbacks --dry-run
sharkfin playbooks quarantine-fallbacks
sharkfin playbooks pack export <name> --out <file.sharkpack>
sharkfin playbooks pack verify <file.sharkpack>
sharkfin playbooks pack install <file.sharkpack> --yes [--trust-signer]

sharkfin forge suggest
sharkfin forge suggest --show-prompt
sharkfin forge inspect <name>
sharkfin forge test <name> [--set key=value]
sharkfin forge runs
sharkfin forge repair <failed-run-id> [--save]
sharkfin forge "<description>"
sharkfin forge "<description>" --simulate
sharkfin forge "<description>" --run --approve

sharkfin mission list
sharkfin mission start --goal "<decision>" [--context "<facts>"]
sharkfin outcomes
sharkfin outcomes --json

sharkfin ghostwriter start "<brand>"
sharkfin ghostwriter status [id]
sharkfin ghostwriter schedule <id> --run-at <iso>
sharkfin ghostwriter cycle <id> [--count <n>]
sharkfin ghostwriter manage <id> [--publish] [--sync-engagement]
sharkfin ghostwriter run-now <id>
sharkfin ghostwriter publish <id>
sharkfin ghostwriter reply <id> --post <postId>
sharkfin ghostwriter engagement <id>
sharkfin ghostwriter process-due
sharkfin ghostwriter stop <id>
sharkfin ghostwriter social status
sharkfin ghostwriter social enable --api-url <url> [--channel <name>] [--auto-publish]
sharkfin ghostwriter social disable

sharkfin telegram-auth
sharkfin discord-auth

sharkfin security enable nemoclaw
sharkfin security status
sharkfin security disable nemoclaw

sharkfin knowledge ingest <path> [--recursive]
sharkfin knowledge search "<query>"
sharkfin knowledge sources
sharkfin knowledge delete <source-id> --yes
sharkfin knowledge auto-recall enable
sharkfin knowledge auto-recall disable

sharkfin jobs schedule "<name>" --at <iso> --playbook <id>
sharkfin jobs schedule "<name>" --cron "<expression>" --timezone <iana> --playbook <id>
sharkfin jobs list
sharkfin jobs status <job-id>
sharkfin jobs run <job-id>
sharkfin jobs history <job-id>
sharkfin jobs cancel <job-id> --yes
sharkfin jobs webhook enable
sharkfin jobs webhook disable

Forge Outcome Studio In v1.0.10

Forge now acts as a productivity compiler instead of promoting unproven YAML. A generated workflow is linted, displayed as a reviewable execution plan, simulated before save, and refused if generation falls back to a placeholder. Live generated execution requires --run --approve.

The v1.0.10 workflow contract includes:

• typed runtime inputs supplied with repeatable --set key=value flags or --inputs JSON
• declared output artifacts with path, size, and required-content checks
• per-step timeout, bounded retry, safe conditions, and forward success/failure branches
• local proof records with run IDs, step attempts, redacted inputs, output paths, and artifact status
• forge inspect, forge test, forge runs, and forge repair for plan review and evidence-driven iteration
• failed input-validation proofs and timeout behavior that prevents a potentially active operation from being retried

Start with the Founder Decision Brief. It needs a working model provider, not Gmail, Telegram, Discord, Calendar, or a separate running agent. It coordinates analyst, writer, and reviewer roles and checks the declared requirements of the markdown artifact it writes:

sharkfin mission start --goal "Choose the best customer segment for the next 30 days" --simulate
sharkfin mission start --goal "Choose the best customer segment for the next 30 days" --context "Current traction, constraints, and options"
sharkfin forge runs
sharkfin outcomes

sharkfin outcomes calculates privacy-safe, local-only seven-day measures: successful live outcomes, first useful artifacts under five minutes, workflow reruns, and signed-pack referral installs observed on this machine. It does not send telemetry or provide global referral analytics.

Signed Playbook Packs

The first signed-pack workflow exports a playbook, its permission inventory, and an Ed25519 signature into a .sharkpack file. Verification detects post-signing changes. Installation requires explicit confirmation, and a new signer requires --trust-signer after the fingerprint has been checked through a trusted channel.

sharkfin playbooks pack export my-workflow --out my-workflow.sharkpack --referral teammate
sharkfin playbooks pack verify my-workflow.sharkpack
sharkfin playbooks pack install my-workflow.sharkpack --yes --trust-signer

This first release proves integrity and remembers local signer trust. It does not claim that a self-signed key proves a publisher's real-world identity. Packs containing literal secrets, invalid playbooks, or Forge fallback output are rejected.

Correctness And Security

v1.0.10 removes the general-purpose condition-expression dependency in favor of a small side-effect-free condition language, validates branch targets, runs legacy cron playbooks only when their five-field schedules match, and prevents duplicate runs within the same minute. Run proofs retain only declared inputs and redact sensitive values. Dependency and package release gates include a zero-advisory npm audit at release validation time.

Browser Teach Mode and MCP have reserved experimental configuration gates only. They have no execution path in v1.0.11 and are reported as unsupported, or degraded if manually enabled, by sharkfin capabilities.

Trust And Capability Hardening In v1.0.9

v1.0.9 focuses on secure execution, truthful capability reporting, and a reproducible release gate:

• one execution gateway applies approval policy, dry-run state, NemoClaw compatibility controls, parameter redaction, and transparency auditing to tool calls
• approval-required tools are denied for autonomous ReAct and subagent calls unless an explicit user decision or persisted background-job grant is present
• filesystem tools validate real paths, reject symbolic-link escapes, bound file sizes, and require approval for move and delete operations
• HTTP, web, browser, job webhook, and shell network paths share private-network and redirect validation with bounded response reads
• the default shell profile excludes interpreters and package execution; it is a restricted subprocess runner, not an operating-system sandbox
• sharkfin capabilities [--json] reports what is available, configured, degraded, or unsupported without making network calls
• sharkfin doctor --json provides stable machine-readable local health results
• npm packaging includes every bundled playbook and verifies the CLI entrypoint before release

Recommended release check:

sharkfin capabilities
sharkfin doctor
npm test
npm run verify:package

verify:package builds a real npm tarball, installs its production dependencies in a temporary directory, compares the installed files with the build, and checks the installed executable, first-run welcome and safe cancellation, all bundled playbooks, Forge and Starter Mission simulations, local outcome reporting, and the installed dependency audit. Its separate home and working directory keep your registration and .env out of the test. It makes no live model calls. The command prints the archive path, SHA-256 checksum, and verification report.

To retain the verified archive in the current directory, use npm run verify:package -- --output sharkfin-1.0.11.tgz. An existing archive is never overwritten, and this command does not publish to npm. For just the built welcome regression check, run npm run build followed by npm run test:welcome.

Reliability in v1.0.8

v1.0.8 adds customer-library diagnostics and protects playbooks across upgrades:

• sharkfin doctor checks configuration, model setup, writable directories, bundled and user playbooks, optional authentication, Ghostwriter state, cited knowledge integrity, durable-job state and webhook authentication, NemoClaw, and SharkBook configuration
• sharkfin playbooks lint --user validates generated and customer-authored playbooks, including invalid URLs, unknown tools, broken templates, duplicate ids, and Forge fallback artifacts
• sharkfin playbooks quarantine-fallbacks --dry-run previews recoverable cleanup; without --dry-run, fallback files move to ~/.sharkfin/quarantine/playbooks
• bundled playbook updates no longer overwrite customer-edited copies
• managed, untouched bundled copies can still receive safe release updates through hash tracking
• web.fetch now returns an actionable validation error for empty or invalid generated URLs and normalizes valid bare domains to HTTPS
• the release smoke test now requires an unrelated built-in playbook to succeed after Ghostwriter state and draft creation

Recommended release check:

sharkfin doctor
sharkfin playbooks lint --all
sharkfin playbooks quarantine-fallbacks --dry-run

Core Capability Expansion in v1.0.8

Cited Local Knowledge

SharkFin can ingest supported local files and directories, search them with local hybrid retrieval, and return source ids, excerpts, line ranges, and citation labels. Automatic recall is off by default because recalled excerpts may be sent to the configured LLM provider.

sharkfin knowledge ingest ./research --recursive --tags "market,customer"
sharkfin knowledge search "customer retention risks"
sharkfin knowledge auto-recall enable
sharkfin knowledge auto-recall status
sharkfin knowledge auto-recall disable

Durable Jobs

Durable jobs persist under ~/.sharkfin/jobs, survive process restarts, retain bounded run history, and support one-time, cron, and authenticated webhook triggers. Targets can run an existing playbook or POST to a public webhook, with retries and environment-backed secret headers.

sharkfin jobs schedule "Daily inbox brief" --cron "0 9 * * *" --timezone America/New_York --playbook morning-inbox
sharkfin jobs list
sharkfin jobs run <job-id>
sharkfin jobs history <job-id>
sharkfin jobs cancel <job-id> --yes

Inbound triggers are optional. Set a token of at least 16 characters in SHARKFIN_JOBS_WEBHOOK_TOKEN, run sharkfin jobs webhook enable, and restart sharkfin start. Keep the listener on loopback unless it is protected by TLS, network controls, and an authenticated reverse proxy.

Browser And Productivity Tools

The 71-tool registry includes isolated logical browser profiles and tabs; keyboard, select, hover, upload, download, wait, PDF, and screenshot operations; Gmail search and attachments; Calendar update, delete, and free-busy; and Telegram/Discord message read, search, reaction, and file delivery. Filesystem allowlists, approval requirements, response-size limits, and public-URL checks remain enforced.

The connector framework and new Slack, Microsoft Teams, WhatsApp, Google Drive, and OneDrive integrations are intentionally not included in this release. Telegram and Discord remain the active messaging adapters.

Forge in v1.0.8

Forge is the workflow-improvement and playbook-creation surface in SharkFin today. It suggests improvements based on recent action logs when you run sharkfin forge suggest, or periodically while the runtime is running with both forge.enabled and forge.proactiveSuggestions enabled. Suggestions do not automatically train a model or guarantee error-free workflows. Review generated plans, test them, and inspect the live results before reuse.

Included in v1.0.8:

• sharkfin forge suggest reviews recent action logs and proposes playbook or workflow improvements
• sharkfin forge suggest --show-prompt shows both the detected patterns and the exact prompt used to generate suggestions
• sharkfin forge "<description>" creates a playbook from plain English and validates it with a dry-run before saving
• sharkfin forge "<description>" --simulate makes that validation step explicit
• sharkfin forge "<description>" --run --approve validates, saves, and executes the reviewed generated playbook
• provider preflight and environment warnings before generation
• periodic log-based suggestions while the runtime is running with Forge and proactive suggestions enabled

Forge Workflow Examples

Review improvement ideas from recent usage:

sharkfin forge suggest
sharkfin forge suggest --show-prompt

Create and validate a playbook before saving:

sharkfin forge "Create a playbook that summarizes recruiter outreach into a local markdown brief"

Create, validate, save, and then execute:

sharkfin forge "Create a playbook that researches founder GTM ideas and writes a concise report" --run --approve

Suggested end-to-end loop:

sharkfin playbooks run morning-inbox
sharkfin playbooks run tiktok-trend-opportunity-brief
sharkfin forge suggest --show-prompt
sharkfin forge "Create a playbook that turns repeated inbox triage into a reusable daily summary flow" --simulate

Ghostwriter in v1.0.8

Ghostwriter in v1.0.8 is a local-first brand drafting and scheduling workflow with optional SharkBook publishing.

Included in v1.0.8:

• workspace-based brand setup with topics, audience, voice, cadence, and local state
• immediate local draft generation with deterministic fallback when the model is unavailable
• scheduled drafts and recurring content cycles
• ghostwriter manage brand loop for one workspace: fresh drafts, due work, optional publish, optional engagement sync
• markdown output that includes platform variants for: LinkedIn, X, and YouTube Community
• best-effort trend research that enriches draft prompts without blocking generation
• optional SharkBook publishing, reply publishing, and engagement sync over HTTP API

Not included in v1.0.8:

• direct LinkedIn, X, or YouTube publishing
• image generation
• autonomous multi-platform comment ingestion

Ghostwriter Workflow Examples

Create a workspace and generate a draft:

sharkfin ghostwriter start "FounderBrand" --topics "local ai, automation" --cadence daily
sharkfin ghostwriter run-now FounderBrand --brief "Draft a short founder update about practical AI workflows"
sharkfin ghostwriter status FounderBrand

Run a cycle or the full brand loop:

sharkfin ghostwriter cycle FounderBrand --count 3
sharkfin ghostwriter manage FounderBrand --count 2

Enable SharkBook and use the managed workflow:

sharkfin ghostwriter social enable --api-url http://localhost:3002 --channel general --auto-publish
sharkfin ghostwriter manage FounderBrand --count 2 --publish --sync-engagement

SharkBook Integration

SharkFin is currently configured to publish Ghostwriter output to SharkBook through the optional HTTP integration.

• enable it with ghostwriter social enable
• publish drafts with ghostwriter publish
• publish replies with ghostwriter reply
• refresh engagement with ghostwriter engagement

This integration is API-based. SharkFin does not need to run inside the sharkfin-social repo, but the SharkBook app must be running and reachable at the configured apiUrl.

Multi-Agent

SharkFin supports multi-agent orchestration for practical workflows such as research, writing, and file-producing runs.

Best fit in v1.0.8:

• concrete goals with one clear final deliverable
• research and writing handoffs
• workflows that save a final brief, draft, or report locally

Use a more explicit goal when possible. Multi-agent runs are strongest today when you tell SharkFin exactly what output to produce.

sharkfin agents launch 2 --role research
sharkfin agents list
sharkfin agents run "Research local AI workflow opportunities and write a founder brief to ~/.sharkfin/playbooks/founder-brief.md" --agents research,writer
sharkfin agents status

NemoClaw Security

SharkFin includes an optional NemoClaw compatibility layer for extra tool guardrails and audit metadata. This release does not execute tools through NVIDIA OpenShell; sharkfin capabilities reports true OpenShell execution as unsupported rather than silently overstating the integration.

sharkfin security enable nemoclaw
sharkfin security status
sharkfin security disable nemoclaw

Chat Adapter Auth

You can add Telegram or Discord after registration:

sharkfin telegram-auth
sharkfin discord-auth

Notes

• See playbookGuide.md for the current built-in playbooks
• See appREADME.md for deeper app details
• Local deployment is the supported runtime for v1.0.11

GitHub: https://github.com/sharkfinAI/sharkfinApp