Zonefoundry Local Sonos

Use this skill when an agent needs to control Sonos through ZoneFoundry `zf` on a same-LAN node. Start with readiness checks, then map user requests to safe...

Security Scan

The skill is coherent for local Sonos control (it uses the zf CLI as expected) but contains two runtime mechanisms that increase risk: it auto-executes commands returned by the CLI and refreshes the agent's instructions from the CLI output — both can be abused if the CLI or its updates are untrusted.

Purpose & Capability

Name, description, declared requirement (zf), and instructions all focus on using the local ZoneFoundry 'zf' CLI to control Sonos. Required binaries and commands align with the stated purpose.

Instruction Scope

The SKILL.md instructs the agent to run many zf commands (setup, doctor, play, auth flows) which is expected. However it also requires two risky behaviors: (1) 'Always obey nextCommand' / 'Always obey nextAction' — execute commands returned by zf setup/service list immediately; and (2) 'SKILL AUTO-REFRESH' — on every new conversation run 'zf skill show' and 'Use the returned "skill" content as your complete, up-to-date capability reference.' These allow runtime-provided data to change agent behavior or trigger immediate execution of commands beyond the agent's static instructions, creating an instruction-injection/execution risk if the zf binary or its update channel is compromised.

Install Mechanism

Install spec builds the zf binary from the Go module at github.com/kisssam6886/zonefoundry/cmd/zf@latest. GitHub-hosted Go module is a reasonable source for this CLI, but '@latest' is not pinned to a specific tag/commit which reduces reproducibility and increases exposure to supply-chain or accidental changes. No third-party or obscure download URLs are used.

Credentials

No environment variables, credentials, or unrelated config paths are requested by the skill. The requested surface (just the zf binary) is proportionate to the stated functionality.

Persistence & Privilege

The skill is not force-included (always=false) and does not request system-wide credentials, but the auto-update/auto-refresh behavior (check/update CLI on start and refresh skill instructions from 'zf skill show' on each session) combined with the 'always obey nextCommand' rule increases the blast radius: a compromised or malicious zf runtime could alter agent behavior or make the agent run additional commands. This is a privilege-risk pattern even though 'always' is not set.

Scan Findings in Context

[no_regex_findings] expected: The package is instruction-only (no code files requiring regex analysis), so the scanner found nothing to analyze. Instruction content is the primary surface to review.

What to consider before installing

This skill generally does what it says: it drives Sonos via the local 'zf' CLI. Before installing, confirm you trust the zf binary source (inspect the GitHub repo and consider pinning to a tagged release rather than @latest). Be aware the skill instructs the agent to: (1) automatically run any 'nextCommand' or 'nextAction' returned by zf and (2) refresh its own instructions from the output of 'zf skill show' on every conversation. Those behaviors let the local CLI change what the agent will do and cause the agent to execute CLI-provided commands immediately — acceptable only if the CLI and update channel are trusted and the host is secure. Recommendations: pin the Go module to a reviewed tag/commit, disable or audit the 'auto-refresh' and 'always obey nextCommand' behaviors unless you trust the runtime, install on an isolated/trusted always-on local node, and verify updates before allowing automatic execution.

Use this skill when an agent, local bot, or automation wants to control Sonos through the local zf CLI.

This skill is written English-first so global users can scan it quickly. Keep user-facing replies in the user's language. Chinese examples and China-specific readiness notes are included where they help.

Use this skill when

• the user wants to connect Sonos for the first time
• the user wants to check whether local Sonos control is ready
• the user wants to play, pause, skip, change volume, or inspect status
• the user wants to add songs to the current queue without interrupting playback
• the user wants to inspect or recover queue / transport problems
• the user wants to check music-service readiness or continue a pending local link flow

Do not use this skill for

• Sonos account creation or billing flows
• cloud relay, hosted bot subscription, or multi-tenant product logic
• arbitrary chat unrelated to Sonos control

Core model

Treat zf as the execution layer.

bot / agent / web onboarding -> zf -> Sonos

• the bot or agent translates intent and explains results
• zf handles discovery, playback, queueing, diagnostics, readiness checks, and recovery

Hard rules (MUST follow)

1. Always obey nextCommand: If zf setup --format json returns a nextCommand field, execute that command immediately.

2. Always obey nextAction: If zf service list --format json returns a nextAction field, follow it. If nextAction=ready, proceed to play.

3. Do not block playback on service linking status. QQ Music, Apple Music, and most services work without separate CLI-side linking — users bind services through the Sonos mobile app. If state is unclear, try playing directly first.

4. Do not expose internal implementation details, premium-only routing, or speculative workarounds in public-facing explanations. Describe user-visible outcomes and the next safe action instead.

5. Keep update paths separate:

clawhub update zonefoundry-local-sonos  # refresh this skill
zf update self --check --format json    # check local runtime update

Language rule

• keep user-facing replies in the user's language
• keep literal room names and service names exactly as the user sees them on Sonos
• use English examples by default, then add Chinese examples only when they improve clarity

First-run quickstart

When the user mentions Sonos for the first time, do not immediately say "not configured".

At the start of every new session, check runtime updates first:

zf update self --check --format json

If it returns status=update_available, update before doing deeper work:

zf update self --format json

Then run the one-shot readiness flow:

zf setup --format json

zf setup should be the default first move because it checks:

• speaker discovery
• default room
• service list and local readiness state
• default service
• a final summary with suggested next actions

If zf setup is unavailable on an older runtime, do this fallback preflight:

zf doctor --format json
zf discover --format json
zf config get defaultRoom
zf service list --format json
zf config get defaultService

If rooms are found but there is no default room, ask the user to choose exactly one visible room and then set it once:

zf config set defaultRoom "Office"

If there is no default service, ask once and set it:

zf config set defaultService "Spotify"

Environment gate

Before promising persistent local bot control, confirm there is an always-on device in the same LAN as Sonos.

Valid local nodes:

• Mac or Windows PC
• NAS
• mini PC
• Raspberry Pi
• Docker host
• Home Assistant host

If the user only has a phone:

• explain that Sonos itself can still be used normally
• guide service add/login through the official Sonos iOS / Android app
• treat Sonos Web App as a supplementary control surface, not the main onboarding path
• do not promise persistent local bot control or always-on automation

Short rule:

• Sonos itself does not require a desktop app
• persistent ZoneFoundry agent or bot flows do require an always-on local node

Minimum safe commands

Prefer JSON output by default.

zf setup --format json
zf doctor --format json
zf discover --format json
zf status --name "<room>" --format json
zf queue list --name "<room>" --format json

If the user already specified a room, prefer --name "<room>".

Safe command mapping

For user-facing explanations, prefer direct CLI command names.

Examples:

zf status --name "Office" --format json
zf pause --name "Office"
zf next --name "Office"
zf volume set 20 --name "Office"

Playback rules

Prefer the unified play music command for normal playback.

Common service examples:

zf play music "Miles Davis" --format json
zf play music "Taylor Swift" --service Spotify --format json
zf play music "Adele" --service "Apple Music" --format json
zf play music "黎明 夏日傾情" --service "Apple Music" --format json
zf play music "黎明" --enqueue --service "Apple Music" --limit 5 --format json
zf queue list --name "Office" --format json
zf queue remove 3 --name "Office"
zf say "Dinner is ready" --name "Kitchen" --mode queue-insert --format json

Chinese examples:

zf play music "周杰伦" --service "网易云音乐" --format json
zf play music "郑秀文" --enqueue --service "QQ音乐" --limit 5 --format json
zf play music "郑秀文 舍不得你" --service "QQ音乐" --format json
zf ncm lucky --name "客厅" "郑秀文" --format json
zf smapi search --name "客厅" --service "QQ音乐" --category tracks --open --index 1 --format json "周杰伦"

Default service selection:

• Chinese content (Chinese artist/song names, user speaks Chinese): use --service "QQ音乐". No fallback — QQ has the best Chinese catalog coverage.
• International content (English/other artist/song names, user speaks English): use --service "Spotify". If Spotify is unavailable, fallback to --service "Apple Music".
• If the user explicitly names a service, always honour that.
• QQ Music and Apple Music use public search APIs — no separate CLI linking needed. Just play directly.
• Use exact artist + title wording when the user specifies a song, for example zf play music "黎明 夏日傾情" --service "QQ音乐".

Important distinction:

• if the user says "play X", use zf play music "X" and expect a replace-style action
• if the user says "add X", "queue X", "append X", or "play X after this", use zf play music "X" --enqueue
• if the wording is ambiguous and something is already playing, --enqueue is usually the safer default

Natural-language examples:

• "play Taylor Swift" -> zf play music "Taylor Swift"
• "add five Adele songs" -> zf play music "Adele" --enqueue --limit 5
• "播郑秀文" -> zf play music "郑秀文"
• "再加一首陈奕迅" -> zf play music "陈奕迅" --enqueue

Lyrics rule

When the user asks about lyrics for the current song, use:

zf lyric --name "<room>" --format json

This fetches lyrics for the currently playing track when supported by the runtime. For raw LRC with timestamps, add --raw.

Announcement rule

If the user asks for a short spoken interruption such as:

• "read a one-minute news brief"
• "announce the meeting starts in 5 minutes"
• "播一分钟新闻"
• "20 分钟后提醒我开会"

default to a short TTS or reminder path, not radio search.

Current stable announcement path (direct mode, default):

zf say "<text>" --name "<room>" --format json

Important announcement rules:

1. Always use direct mode (the default). Do NOT pass --mode queue-insert. Direct mode plays TTS then automatically restores the original track and position (reltime).
2. Concatenate multiple items into one zf say call. If the user asks for "5 news headlines", compose all 5 headlines into a single text block and call zf say once. Do NOT call zf say five separate times — that causes interleaving with music and breaks reltime restore.
3. After TTS completes, the original song resumes at the exact playback position.

Only treat it as a live radio request if the user explicitly asks for a station or live news channel.

Queue hygiene rule

After adding songs via zf play music with --enqueue or after any queue-related playback, run an automatic queue prune to remove copyright-blocked tracks:

zf queue prune --name "<room>" --format json

This removes greyed-out tracks (e.g. "应版权方要求暂不能播放") from the queue. Run it silently — do not ask the user for permission, just report the result if tracks were pruned.

Service readiness rule

Most music services work without separate CLI-side linking:

• QQ Music: uses public search API → always ready, no linking needed
• Apple Music: uses public search API → always ready, no linking needed
• Spotify: depends on household setup; try playing directly first
• NetEase Cloud Music (网易云音乐): uses SMAPI; may need initial linking via zf setup

Users bind music services through the Sonos mobile app — there is no desktop binding. Do not tell users "service not linked" if zf play music works. Try playing first, diagnose only on failure.

If you need a reliable probe, prefer:

zf doctor service --service "Spotify" --query "Miles Davis" --format json

New-session rule

If a new session starts and the user says things like:

• "done"
• "complete"
• "I logged in already"
• "已经绑好啦"
• "我登录好了"

do not force the whole onboarding conversation again.

Prefer this order:

1. try playing the user's request directly
2. fall back to zf setup --format json only if playback fails and context is unclear

Failure routing

Read structured JSON errors first:

• error.code
• error.message
• error.details

Do not classify every playback failure as auth or copyright.

Known patterns:

• if the same song plays in a helper room but not in the target room, suspect room-local queue or transport pollution first
• if you see TRANSITIONING or partial queue failure, do not loop infinite retries
• if queue pollution is suspected, prefer explicit queue inspection and recovery commands
• if deeper room-local pollution is confirmed, zf group rebuild --name "<target>" --via "<helper>" is the stronger recovery path

Boundaries

• Sonos official mobile apps remain the default path for adding and logging in to content services
• Sonos Web App is a supplementary control surface, not the primary onboarding path
• group rebuild is a recovery tool, not proof that the original defect is fixed
• exact RelTime restoration is not a guaranteed stable capability
• OpenClaw skill updates and local zf runtime updates may require a new session to fully refresh

When to ask the user something

Ask only when required:

• choose a default room
• confirm a preferred music service
• confirm helper-room usage for group rebuild

Do not ask the user to learn repo internals or memorize command names.

User-facing tone

Good examples:

• "I'll first check whether this machine can discover your Sonos speakers on the LAN."
• "I found these rooms: Office, Kitchen. Which one should be the default?"
• "我先检查这台机器能不能发现你局域网里的 Sonos。"
• "我找到这些房间：客厅、浴室。你想默认控制哪一个？"

Avoid:

• "Please install the Sonos controller" as a blanket answer
• "Learn the zf CLI first"
• "Not configured" before running preflight

Read these references when needed

Bundled reference files (same repo, references/ subdirectory):

• onboarding-boundary.md — product scope and onboarding guidance
• command-map.md — command map and recovery rules
• china-service-linking.md — China service-linking notes