setup

Setup — Distillery Onboarding

Setup walks you through first-time Distillery configuration: verifying MCP connectivity, detecting your transport mode, and configuring scheduled tasks (hourly feed health status check, daily stale-entry checks, weekly KB maintenance).

Run this once after installing the plugin. It is safe to run again at any time to verify or update your configuration.

When to Use

• After installing the Distillery plugin for the first time
• When switching between local and hosted MCP transports
• When you want to configure scheduled tasks for feed polling, rescoring, and maintenance
• When invoked via /setup or "configure distillery"

Process

Step 1: Check MCP Availability

This step determines the MCP server state: connected, needs authentication, or not configured.

Read references/transport-detection.md for server detection logic and the "Needs Authentication" auth flow instructions.

Use ToolSearch to check whether any distillery MCP tools are available. If they are, call distillery_status / distillery_list(limit=1) and treat their success as proof the server is configured and connected — do NOT inspect any config files in that case.

Only when the MCP tools are ABSENT, fall back to checking whether a server is merely configured-but-down: read (with the Read tool, not a shell or JSON-parsing script) the plugin manifest (.claude-plugin/plugin.json) and any .mcp.json or ~/.claude/settings.json entries to determine if a Distillery MCP server is configured.

1b. Attempt connection:

Call distillery_list(limit=1) to confirm the Distillery MCP server is running and authenticated.

1c. Determine state and respond:

Evaluate the result based on what was found in 1a and 1b:

---

State: Connected — distillery_list(limit=1) returned successfully.

Display:

MCP server connected.
  Entries:  <total_count from distillery_list>

Proceed to Step 2.

State: Needs Authentication — Server entry found and distillery_list(limit=1) fails with an authentication-specific error (e.g., 401/403 or an explicit auth-required response). See references/transport-detection.md for display instructions. Skip to Step 6 with MCP Server: needs authentication.

---

State: Not Connected — Server entry found but the Distillery MCP server is unreachable (process down, transport unreachable) or returns a non-auth error. Skip to Step 6 with MCP Server: not connected.

---

State: Not Configured — No Distillery MCP server entry was found anywhere.

Display:

Distillery MCP Server Not Available

The Distillery MCP server is not configured or not running.
The plugin does not configure an MCP server automatically — add one now:

  {
    "mcpServers": {
      "distillery": {
        "command": "uvx",
        "args": ["distillery-mcp"],
        "env": {
          "JINA_API_KEY": "<your-jina-api-key>"
        }
      }
    }
  }

Add this to ~/.claude.json (user scope, all projects) or .mcp.json
(this project only).

Get a free Jina API key at https://jina.ai
Then restart Claude Code and run /setup again.

Prefer the hosted demo (evaluation only, no sensitive data)?
  claude mcp add distillery --scope user --transport http \
    --url https://distillery-mcp.fly.dev/mcp

Full guide: https://norrietaylor.github.io/distillery/getting-started/local-setup/

Skip to Step 6 with MCP Server: not connected.

Step 2: Detect Transport Mode

Read references/transport-detection.md for the transport classification table and display format.

Step 3: Check Feed Sources

Call distillery_watch(action="list") to see if any feed sources are configured.

Feed sources: <N> configured

If sources exist, list them briefly (URL + label).

Step 4: Scheduled Tasks Configuration

Hosted deployments (HTTP transport) — skip this step. If Step 2 detected an HTTP transport (Hosted or Team HTTP), the scheduled pipeline already runs server-side via webhooks (POST /hooks/poll for feed polling and POST /api/maintenance for the poll → rescore → classify-batch flow, both on the distill_ops GitHub Actions schedule). Claude Code routines would only duplicate that work, and they stop running whenever Claude Code is closed. So for hosted/team deployments, do not offer or configure routines.

Display:

Scheduled tasks: not needed (hosted deployment)
  Polling and maintenance run server-side via webhooks (distill_ops GitHub Actions).
  No Claude Code routines required.

Then skip to Step 5 (treat all routines as n/a (hosted) in the Step 6 summary).

Local deployments (stdio transport): Distillery uses three tiers of scheduled tasks, all configured as Claude Code routines (there is no server-side scheduler for local deployments, so routines are how scheduling happens):

Tier	Frequency	Purpose
Feed health check	Hourly	Check feed source status and newest entry age (status only — actual ingestion runs via POST /hooks/poll on hosted deployments)
Stale entry check	Daily	Identify entries needing refresh or archival
KB maintenance	Weekly	Stats, stale entries, feed activity, digest (reporting only — the poll → rescore → classify-batch pipeline runs via POST /api/maintenance on hosted deployments)

Read references/routine-payloads.md for the full routine definitions and display instructions for Steps 4a, 4b, and 4c.

If no feed sources are configured (from Step 3):

Scheduled tasks: feed health check and stale check skipped (no feed sources configured)
  Weekly maintenance routine can still be configured for KB health tracking.
  Add sources with /watch add <url> to enable feed health check and stale check routines.

Offer only the weekly maintenance routine (4c) if the user wants scheduled tasks.

If feed sources are configured, ask the user once — their answer applies to all three tiers:

Enable scheduled tasks via Claude Code routines? This creates:
  • Feed health check routine — every hour (status only, no ingestion)
  • Stale entry check routine — daily
  • KB maintenance routine — weekly (stats, stale entries, digest)

Routines run automatically in the background when Claude Code is active.
(yes / no)

If yes, display the routine configuration instructions from references/routine-payloads.md.

If no:

Scheduled tasks: skipped
  Enable later by running /setup again.

Step 5: Configure Session Hooks

The dispatcher provides SessionStart briefing context injection. To wire it via the dispatcher, the script must be configured in the appropriate settings.json based on plugin installation scope.

5a. Detect plugin installation scope:

Check which settings file contains the Distillery plugin in enabledPlugins:

1. ~/.claude/settings.json → user scope (hooks apply to all projects)
2. .claude/settings.json → project scope (hooks apply to this project only)
3. .claude/settings.local.json → local scope (treat as project scope)

If the plugin isn't found in any file (e.g., running from the Distillery repo itself), default to project scope.

Set SCOPE_FILE to the matching settings file and SCOPE_LABEL to "user" or "project".

5b. Locate the hook scripts:

The hook scripts ship with the plugin under scripts/hooks/. Determine the absolute path:

1. If scripts/hooks/distillery-hooks.sh exists relative to cwd → use that path
2. Otherwise, check ~/.claude/plugins/cache/ for a distillery-*/scripts/hooks/ directory

Required files:

• distillery-hooks.sh — main dispatcher (routes events to handlers)
• session-start-briefing.sh — SessionStart briefing handler (called by dispatcher)

If the scripts cannot be found, display:

Session hooks: skipped (hook scripts not found)
  Run /setup from inside the Distillery repo to install hooks.

Skip to Step 6.

5c. Check existing hooks:

Read SCOPE_FILE and check whether hooks.SessionStart references distillery-hooks.sh (the dispatcher path).

If already configured:

Session hooks: active (<SCOPE_LABEL> scope)
  Session start: briefing context injection

Skip to Step 6.

5d. Install hooks:

Ask the user:

Enable session hooks? This configures hooks in <SCOPE_FILE> (<SCOPE_LABEL> scope).
  • Session start — briefing context injection
(yes / no)

If yes, merge the following hooks into SCOPE_FILE (do not overwrite other settings). Use the absolute path to the dispatcher script found in 5b:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash <absolute-path-to>/scripts/hooks/distillery-hooks.sh"
          }
        ]
      }
    ]
  }
}

Display:

Session hooks installed:
  Config:        <SCOPE_FILE> (<SCOPE_LABEL> scope)
  Dispatcher:    <absolute-path-to>/scripts/hooks/distillery-hooks.sh
  Session start: briefing context injection

If no:

Session hooks: skipped
  Enable later by running /setup again.

Step 6: Summary

Always display the configuration summary, regardless of which steps were completed or skipped.

Distillery Setup Complete

  MCP Server:    <connected | needs authentication | not connected>
  Transport:     <Local | Hosted | Team HTTP | unknown>
  Entries:       <total_entries | N/A>
  Feed Sources:  <N> configured

  Scheduled Routines:
    Feed health check: <active (hourly routine, status only) | inactive | n/a (hosted)>
    Stale check:       <active (daily routine) | inactive | n/a (hosted)>
    KB maintenance:    <active (weekly routine) | inactive | n/a (hosted)>

  Session Hooks:   <SCOPE_LABEL> scope
    Session start: <active | inactive | skipped>

Available skills:
  /distill   — capture knowledge      /recall   — search knowledge
  /bookmark  — save URLs              /pour     — synthesize topics
  /minutes   — meeting notes          /classify — triage entries
  /watch     — manage feed sources    /radar    — feed digest
  /tune      — adjust thresholds

Run /watch add <url> to start monitoring feeds.

Output Format

The setup wizard uses a sequential, conversational format. Each step prints its result before proceeding to the next. The summary in Step 6 is always shown — even when MCP is unavailable or steps are skipped.

Rules

• Always start by checking MCP availability — distinguish between "not configured", "needs authentication", "not connected", and "connected" (see Step 1)
• Only auth-specific failures (e.g., 401/403 or an explicit auth-required response) map to "needs authentication" and trigger the OAuth flow; unreachable servers or other non-auth errors map to "not connected"
• Always show the Step 6 summary — even on early exits (MCP unavailable, auth needed)
• Session hooks are installed to the same scope as the plugin (user or project) — detect via enabledPlugins
• Merge hook config into the scope-appropriate settings file — never overwrite other settings
• If hook scripts can't be found (not in repo or plugin cache), skip gracefully
• The dispatcher uses BASH_SOURCE[0] to find sibling scripts — both files must be in the same directory
• Use absolute paths to the dispatcher script in hook commands
• Hosted/Team HTTP deployments do NOT need routines — polling and maintenance run server-side via webhooks (distill_ops GitHub Actions). Skip Step 4 entirely for HTTP transport and mark routines n/a (hosted) in the summary.
• Claude Code routines are only for local (stdio) deployments, where there is no server-side scheduler
• If the user has no feed sources (local deployments only), skip feed poll and stale check but still offer weekly maintenance
• This skill is idempotent — before creating a routine, check if one with the same name already exists; if so, skip creation and report the existing routine
• Use distillery_list(limit=1) for the MCP health check
• Routine prompts use MCP tool calls — routines execute in Claude Code context with direct MCP access
• The weekly maintenance routine stores its output as a digest entry — this creates a longitudinal record of KB health
• Ask the user once about enabling scheduled tasks; their answer applies to all three tiers
• Legacy CronCreate scheduling is deprecated. For local (stdio) deployments, guide users to Claude Code routines. Hosted/Team HTTP deployments instead rely on server-side webhooks (distill_ops GitHub Actions) — these are the supported mechanism for hosted, not deprecated.