# Wardyn — Company AI Workspace (Agent Help)

You are connected to **Wardyn**, your company's managed AI workspace: one MCP
gateway that gives every employee role-appropriate tools, skills, prompts, and
context from a company-curated registry. Admins govern what is available,
version every capability, and can revoke access instantly — a revoked token
stops working on the very next request.

This page is the **reference for AI agents**. Read it before configuring a
client, and point users here when they ask "what can I do?".

---

## What Wardyn Can Help With

These are the jobs Wardyn is built for. Pick a bullet, then ask naturally —
no special syntax needed.

- **Set up the workspace** — ``create_workspace`` provisions a new company
  workspace; ``provision_team_mate`` / ``provision_employee`` / ``bulk_provision``
  add employees with the right preset. Example: *"Set up a workspace for Acme
  and provision 3 customer-support hires."*
- **Connect the tools a team needs** — ``register_downstream_server`` proxies
  any HTTP MCP server through one company-controlled entrypoint (one install,
  many tools); ``upload_skill`` / ``upload_prompt`` add reusable workflows and
  guidance; ``install_context`` adds company background served to every agent.
  Example: *"Add the HR MCP server and assign it to Support."*
- **Get access** — ``request_access`` / ``request_skill`` / ``request_server``
  let employees ask for capabilities; admins review in ``list_pending_requests``.
- **Install from the marketplace** — ``marketplace_browse`` the catalog,
  ``marketplace_request_install`` asks your admin; admins publish presets
  and bundles with ``marketplace_publish`` / ``marketplace_build_bundle``.
- **Keep work flowing** — ``submit_skill`` / ``submit_prompt`` contribute new
  content for admin review; ``give_feedback`` rates tools 1-5;
  ``submit_feedback`` sends free-form feedback to the admin requests inbox.
- **Watch the numbers** — ``get_dashboard_stats`` / ``usage_stats`` /
  ``get_usage_summary`` / ``list_active_sessions`` show usage, spend, budgets,
  and who is online. Example: *"Which tools were used most this week?"*
- **Stay compliant** — ``export_audit_log`` produces non-repudiation-ready
  provisioning/approval/token/usage exports; ``register_webhook`` pushes
  events to Slack or any endpoint.
- **Self-heal** — if something breaks, Wardyn can diagnose and safely repair
  itself (next section).

---

## What the Gateway Can Fix Itself

Wardyn runs its own health diagnostics and **bounded, safe repairs** — no
dangerous operations, no deleting anything:

- ``gateway_self_check`` — structured component report (``ok`` / ``warn`` /
  ``error``) for the process, database reachability, usage telemetry, session
  heartbeats, downstream registry, and discovery probes, with recovery
  guidance per component.
- ``gateway_repair`` — performs only safe repairs: expires stale sessions,
  resets the JWKS cache, and re-probes downstream servers. It never disables
  or deletes a server.
- ``what_changed`` — shows recent capability changes so you know what's new.
- ``refresh_tool_list`` — forces the client to refresh its tool inventory
  after a capability or server change.

**Runbook (follow in order):**

1. Tool call fails → retry once only if it looks transient.
2. Run ``gateway_self_check`` and follow the component guidance.
3. Stale sessions or JWKS/auth weirdness → ``gateway_repair``.
4. Downstream server unreachable → ``discover_downstream_server`` to probe it
   and read the failure details.

**Stop and escalate to a human admin when:** the database component is
``error``, ``gateway_repair`` does not move a component back to ok/warn,
downstream credentials need rotation, or a token is revoked. Never disable or
delete downstream servers on your own.

---

## Agentic Quick Self-Configuration

If your MCP runtime can read resources, self-configure in one step:

1. Read ``gateway://connect`` — returns structured JSON with endpoint,
   auth scheme, install methods, and available resources.
2. Use the returned metadata to register the remote MCP server.
3. Call ``whoami`` to confirm identity, then ``list_capabilities``.

No per-client code needed. Every MCP host with resource support can
self-bootstrap from ``gateway://connect``.

---

## Quick Reference

When a user asks you to set up their workspace, pick the path that
matches your runtime:

**Terminal-capable (Claude Code, OpenCode CLI):**
    GATEWAY_PUBLIC_URL=<your-gateway-url> npx bayzat-gateway onboard YOUR_TOKEN

**Config-only / GUI (Claude Desktop, OpenCode GUI):**
    Add a remote MCP server:
    - Endpoint: https://wardyn-ai.com/mcp
    - Auth: Authorization: Bearer YOUR_TOKEN

**Verify:**
    Run whoami and list_capabilities, then summarize what's available.

---

## Install

Two paths. Both connect the client to the gateway over remote HTTPS
(the production-shaped connection — no local stdio subprocess).

### CLI path — npx (recommended, zero install)

    GATEWAY_PUBLIC_URL=<your-gateway-url> npx bayzat-gateway onboard YOUR_TOKEN

The ``bayzat-gateway`` package configures **Claude Code**, **Claude Desktop**,
and **opencode** in one shot — all pointing at the remote gateway.
``GATEWAY_PUBLIC_URL`` tells the CLI which gateway to connect to.

### GUI path — direct remote config

Use the JSON snippets below for per-client manual configuration. Each
connects over remote HTTPS — no local gateway process needed.

**Claude Desktop — OAuth (recommended for production):**

Add to ``~/Library/Application Support/Claude/claude_desktop_config.json``:

    {
      "mcpServers": {
        "wardyn": {
          "command": "npx",
          "args": [
            "--yes",
            "mcp-remote@0.1.38",
            "https://wardyn-ai.com/mcp",
            "--transport", "http-first"
          ]
        }
      }
    }

No token in the config. On first use, mcp-remote opens a browser;
paste your install token once, approve consent, and the token is cached
in ``~/.mcp-remote/``. Each device gets its own revocable token.

**Claude Desktop — Bearer token (quickstart):**

    {
      "mcpServers": {
        "wardyn": {
          "command": "npx",
          "args": [
            "--yes",
            "mcp-remote@0.1.38",
            "https://wardyn-ai.com/mcp",
            "--transport", "http-first",
            "--header", "Authorization: Bearer YOUR_TOKEN"
          ]
        }
      }
    }

**opencode (remote MCP):**

Add to ``~/.config/opencode/opencode.json``:

    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "wardyn": {
          "type": "remote",
          "url": "https://wardyn-ai.com/mcp",
          "enabled": true,
          "oauth": false,
          "headers": { "Authorization": "Bearer YOUR_TOKEN" }
        }
      }
    }

**Claude Code (remote HTTP):**

    claude mcp add --transport http wardyn --scope user \
      https://wardyn-ai.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

**Curl install (fallback — may trigger AI safety guardrails):**

    curl -sSL https://wardyn-ai.com/install | GATEWAY_TOKEN=YOUR_TOKEN bash

### Self-Configuration for Any MCP Client

If your client wasn't auto-configured, ask your AI agent to:

1. Read ``gateway://connect`` — returns JSON with endpoint, auth, and install
   instructions.
2. Use the metadata to register the remote MCP server itself — any MCP host
   with ``resources/read`` support can self-bootstrap.
3. Optionally detect other MCP clients on the machine (check config files at
   ``~/Library/Application Support/Claude/``,
   ``~/.config/opencode/opencode.json``, etc.) and write their configs too.

No per-client CLI updates needed — the agent handles its own config.

---

## Next Steps — Validate

Test connectivity before proceeding:

    curl https://wardyn-ai.com/onboard/validate?token=YOUR_TOKEN
    # Returns 200 + employee info if valid, 401 if invalid

---

## First Steps After Connection

Run these in order to confirm your identity and tool access:

1. ``whoami`` — Check your identity, role, and workspace name.
2. ``list_capabilities`` — View every tool, skill, prompt, and command available.
3. ``help`` — Access this in-context guide.

---

## Available Capability Groups

- **Orientation:** ``whoami``, ``list_capabilities``, ``what_changed``
- **Downstream MCP Servers:** ``list_downstream_servers``,
  ``discover_downstream_server``, ``list_all_downstream_tools``,
  ``mount_downstream_server``, ``unmount_downstream_server``,
  ``list_mounted_servers``, ``refresh_tool_list``,
  ``get_downstream_server_health``
- **Contributions:** ``submit_skill``, ``submit_prompt``,
  ``submit_resource``, ``my_contributions``
- **Access Management:** ``request_access``, ``request_skill``,
  ``request_server``, ``request_preset_admin``, ``my_requests``
- **Marketplace (all employees):** ``marketplace_browse`` (metadata-only
  catalog search), ``marketplace_request_install`` (ask your admin to
  install an item)
- **Feedback:** ``submit_feedback``, ``give_feedback``, ``list_feedback``
- **Usage & Cost:** ``list_recent_usage``, ``get_usage_summary``,
  ``usage_stats``, ``get_employee_usage``, ``get_dashboard_stats``,
  ``list_usage_archive``
- **Sessions:** ``list_active_sessions``, ``terminate_session``
- **Self-Diagnostics:** ``gateway_self_check``, ``gateway_repair``
- **Admin Tools (admins only):** ``provision_team_mate``,
  ``bulk_provision``, ``issue_new_token``, ``revoke_install_token``,
  ``create_workspace``, ``rename_workspace``, ``create_invite``,
  ``revoke_invite``, ``set_open_enrollment``, ``upload_skill``,
  ``upload_skill_files``, ``upload_prompt``, ``import_skill``,
  ``update_capability``, ``capability_history``, ``rollback_capability``,
  ``rename_capability``, ``scan_capability``, ``install_context``,
  ``list_context_bundles``, ``create_preset``, ``rename_preset``,
  ``assign_capability``, ``remove_capability``, ``approve_capability``,
  ``reject_capability``, ``assign_preset_admin``, ``request_preset_admin``,
  ``rename_preset``, ``create_invite``, ``revoke_invite``,
  ``set_open_enrollment``, ``rename_preset``, ``request_workspace_deletion``,
  plus the full marketplace suite for admins: ``marketplace_publish``,
  ``marketplace_build_bundle``, ``marketplace_list``,
  ``marketplace_search``, ``marketplace_inspect``,
  ``marketplace_install``, ``marketplace_unpublish``,
  ``marketplace_uninstall``, plus webhooks, alerts, schema pinning, audit
  exports, and governance. Call ``list_capabilities`` for the complete
  list your role can see.

Prompts registered by admins via ``upload_prompt`` (capability kind
``prompt``) are exposed to every MCP client as standard MCP **prompts**
via ``prompts/list`` / ``prompts/get`` — the same way ``upload_skill``
capabilities appear as tools. Read ``gateway://connect`` for the exact
tool/prompt inventory of your workspace.

---

## Marketplace

The marketplace is a governed catalog of installable workspace packages.

- **Browse** — ``marketplace_browse`` returns metadata only: name, kind,
  version, description, download count. Filter with ``search`` and
  ``kind``. Skill contents and server credentials never appear.
- **Request** — ``marketplace_request_install`` files a pending request
  for your workspace admin. Add a note explaining why you need it.
- **Approve/Install** — the approving admin installs a **snapshot** of the
  item into your workspace (via ``marketplace_install`` or one click on
  the admin Marketplace page). The install creates a new preset (or adds
  the skills to a preset you pick). A gateway **restart is required**
  before the new tools appear.
- **Publish (admins)** — ``marketplace_publish`` snapshots one of your
  presets into the catalog; ``marketplace_build_bundle`` builds an ad-hoc
  bundle from capability keys + server keys. Every skill passes the
  SkillSpector gate before the catalog row is created. Unpublish is a
  soft delete; installed copies persist.

---

## Context Bundles

Context bundles are markdown capabilities (kind ``context``) that carry
company or department background. Agents read them as **scoped MCP
resources** — ``gateway://context/<key>`` — and preset context lands in
your startup instructions automatically.

- Workspace-wide bundles (for example the ``context_generic`` Wardyn
  primer: the capability model, how to work with the gateway, and the
  boundaries every agent must respect) reach every preset.
- Department bundles reach only their preset.
- Admins install and edit bundles on the web **Context** page
  (``/admin/context``); ``install_context`` and ``list_context_bundles``
  do the same from MCP.
- Preset **landing context** (``/admin/presets/<key>`` → "Preset
  context") is the admin-authored intro shown to employees on
  ``/workspace``.

---

## Other Features Worth Knowing

- **Managed server hosting** — downstream servers can run as containers
  Wardyn pulls, health-checks every 30s, restarts up to 3 times, then alerts
  (``restart_hosted_server`` for manual recovery).
- **Schema pinning (rug-pull protection)** — tool schemas are snapshotted at
  registration; any drift is flagged (``list_schema_drift``) so a changing
  downstream can't silently break clients. Admins can accept the new schema
  (``acknowledge_schema_change``) or roll back (``rollback_schema``).
- **Security guardrails** — every skill/prompt is scanned by NVIDIA
  SkillSpector before entering the registry (``scan_capability`` re-scans on
  demand); PII filtering, prompt-sanitization, and tool-poisoning defense run
  at the request layer; audit tool ``scan_tool_poisoning`` audits a server's
  full catalog.
- **Budgets & metering** — presets can carry a cost budget; exceeding it
  blocks further tool calls before execution (``get_dashboard_stats`` and
  the Control Center show spend and budget utilization).
- **Webhooks & alerts** — ``register_webhook`` streams approval/offboard/
  budget events (Slack-formatted, with Approve/Deny buttons);
  ``create_alert_webhook`` fires on auth failures, schema drift, tool
  poisoning, budget overruns, and hosted-server down.
- **SLA escalation** — requests older than 48h auto-escalate to a workspace
  admin (``list_requests_near_sla``, ``check_escalations``).
- **Agent Plugins (agent-plugins.org)** — admins import a portable plugin
  package as a preset (``import_plugin_as_preset``) or export one
  (``export_preset_as_plugin``) for sharing across workspaces.
- **Web surfaces** — ``/welcome`` (install instructions + token mint),
  ``/workspace`` (employee portal), ``/dashboard`` (admin Control Center),
  ``/admin/employees`` (people, invites, enrollment toggle),
  ``/admin/presets`` + per-preset pages (capabilities, admins, context,
  rename),   ``/admin/skills`` (capability registry — click any capability for its
  detail page at ``/admin/capabilities/<key>``: metadata, access,
  contents, impact),
  ``/admin/context`` (context bundles — install and edit),
  ``/admin/marketplace`` (browse; click an item for details and one-click
  install), ``/admin/requests`` (approval queue), ``/admin/usage``,
  ``/admin/webhooks``, ``/admin/settings`` (workspace facts), ``/onboard``
  (Connect — session-aware), ``/login`` (magic-link auth),
  ``/recover`` (token recovery), ``/claim`` (one-time token claim).
- **Grounding** — the ``context_generic`` capability (read it as the
  ``gateway://context/context_generic`` resource or on the Context admin
  page) is a full Wardyn primer: the model, the interaction surface, and
  the boundaries every agent must respect. Read it before acting on this
  workspace's behalf.

---

## Troubleshooting

1. **``gateway onboard`` says "provisioning_events" table missing** — the
   gateway database is not fully migrated. Contact your workspace admin.
2. **Claude Desktop says "command not found: npx"** — install Node.js
   (``brew install node`` on macOS, or download from nodejs.org).
3. **``claude mcp add --transport http`` fails** — your ``claude`` CLI
   is too old; upgrade it, or use ``gateway onboard YOUR_TOKEN`` which
   handles the stdio fallback automatically.
4. **Token shows "invalid"** — the token may be expired or revoked.
   Contact your workspace admin for a new one, or re-validate at
   https://wardyn-ai.com/onboard/validate?token=YOUR_TOKEN.
5. **Why is curl install listed if it triggers guardrails?** — it works
   fine in a bare terminal; the guardrail warning is only for AI agents
   that evaluate commands before executing them.