onboard

synology-mgmt: onboard

Establish the persistent connection profile for a Synology NAS. The same plugin install can serve multiple NAS environments — only the values in config.json are environment-specific. No host details should ever be hard-coded into other skills in this plugin.

Workspace resolution

Resolve the plugin's data directory as $CLAUDE_USER_DATA/synology-mgmt/ if CLAUDE_USER_DATA is set; otherwise $XDG_DATA_HOME/claude-plugins/synology-mgmt/ if XDG_DATA_HOME is set; otherwise ~/.local/share/claude-plugins/synology-mgmt/. Create the directory if it doesn't exist. See the canonical convention in the claude-rudder:plugin-data-storage skill.

Shell form:

PLUGIN_DATA_DIR="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/synology-mgmt"
mkdir -p "$PLUGIN_DATA_DIR"

The config file is $PLUGIN_DATA_DIR/config.json.

When to use

• User says "set up synology", "onboard nas", "configure synology plugin".
• Any other synology-mgmt skill finds no config.json at the resolved path — offer to run onboarding first.
• The user changes NAS, IPs, or SSH credentials.

Prerequisites

• SSH service enabled in DSM: Control Panel → Terminal & SNMP → Enable SSH service.
• The user has an admin or administrators-group account that can SSH in.

Procedure

1. Load existing config from $PLUGIN_DATA_DIR/config.json if present. Show the current values back. Offer Update vs Replace vs Cancel.

2. Interview the user. Ask each question; default sensibly when the user just hits enter:

   Field	Prompt	Notes
   host	"What's the LAN address of your NAS?"	No default — the user must answer. Accept hostname or IP.
   ssh_user	"SSH username?"	Default: admin. Synology blocks root SSH by default.
   ssh_port	"SSH port?"	Default: 22. Some users move it.
   ssh_key_path	"Path to the SSH private key (or leave blank for default agent)?"	Optional. Expand ~.
   dsm_web_url	"DSM web URL (with port)?"	Default: http://<host>:5000 (HTTPS DSM is usually on :5001).
   volume_root	"Primary volume mount point on the NAS?"	Default: /volume1.
   model	"NAS model (e.g. DS923+, DS1522+)?"	Optional but useful for context.
   dsm_version	"DSM version (e.g. 7.2)?"	Optional.
   dsm_user_ref	"Where is the DSM admin password stored, if you want skills to use the DSM API? (1Password ref / env var name / blank)"	Reference only.
   notes	"Any free-text notes about this NAS?"	Optional (e.g. RAID layout, attached UPS).

3. Test connectivity (best-effort, don't block on failure):

   ssh -o ConnectTimeout=5 -o BatchMode=yes -p "$SSH_PORT" "$SSH_USER@$HOST" \
     'uname -a; cat /etc/synoinfo.conf 2>/dev/null | grep -E "^(unique|upnpmodelname)" | head -3'
   

   If the command fails, surface the error to the user but still write the config — they may want to fix SSH separately.

4. Write $PLUGIN_DATA_DIR/config.json with this schema (pretty-printed, 2-space indent):

   {
     "schema_version": 1,
     "host": "192.168.1.50",
     "ssh_user": "admin",
     "ssh_port": 22,
     "ssh_key_path": null,
     "dsm_web_url": "http://192.168.1.50:5000",
     "volume_root": "/volume1",
     "model": null,
     "dsm_version": null,
     "dsm_user_ref": null,
     "notes": null,
     "updated_at": "<ISO-8601 timestamp>"
   }
   

5. Summarise: print every field and its final value. Show the path to config.json. List the sibling skills the user can now invoke (synology-operations).

Re-running

If config.json already exists, never silently overwrite. Always confirm. If the user picks Replace, back up the existing file with .bak suffix first.

Hard rules

• Never store DSM passwords in config.json. Only store a reference (1Password item path, env var name, file path). The seed skill resolves the reference at runtime.
• Never hard-code IPs, hostnames, or usernames into other skills. Every operational skill must read from config.json.
• Default values are suggestions, not assumptions. Synology defaults (admin, :5000, /volume1) are common but not universal — confirm with the user.