Pp Extron

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/devices/extron/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

Extron — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the extron-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install extron --cli-only

2. Verify: extron-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.5 or newer). This installs into $GOPATH/bin (default $HOME/go/bin), so add that directory to $PATH instead:

go install github.com/mvanhorn/printing-press-library/library/devices/extron/cmd/extron-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

Extron publishes spec sheets and manuals at extron.com, but finding them means browser tabs, letter-scoped tables, and a WAF that blocks plain curl. extron-pp-cli syncs the whole literature catalog into a local database, then lets you list, search, download, and track revisions from the terminal — including what's new (literature recent), which downloaded docs went stale (literature updates), and which doc types a rack's models are missing (catalog completeness).

When to Use This CLI

Use extron-pp-cli whenever an agent or integrator needs Extron spec sheets, user manuals, design/product guides, Declarations of Conformity, or Revit BIM families for a project — browsing the official literature library, checking what changed, assembling doc sets for a rack, or verifying downloaded PDFs are current and complete.

Anti-triggers

Do not use this CLI for:

• Do not use this CLI to control or configure Extron AV devices (SIS/TCP, SSH, IP Link web interfaces) — this CLI covers literature only.
• Do not use this CLI for Extron firmware files or software downloads — the literature library does not include them.
• Do not use this CLI for non-Extron documentation or generic AV manuals.

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Local catalog that compounds

• catalog sync — Build the local Extron literature catalog, walking the alphabetical index the site only exposes a letter at a time. Bare catalog sync fetches the first index page per letter bucket — a fast baseline of roughly 1,200 documents, with large categories truncated at the page-1 ceiling. --full follows each category's pagination and is what produces the complete catalog (roughly 3,600 documents and up). A failed letter bucket is retried and skipped rather than aborting the crawl, so a 36-bucket --full walk survives a flaky bucket.

  Run this first — every local read depends on it, and it is not the same command as top-level sync.

  extron-pp-cli catalog sync --full --timeout 15m --max-duration 4h --json

• literature updates — See which downloaded spec sheets and manuals have a newer revision available upstream, so project shares never run stale docs.

  Use this before commissioning or re-quoting to catch docs superseded since the last sync.

  extron-pp-cli literature updates --dir ./docs --json

• catalog completeness — Per-model gap report across Brochure, Declaration of Conformity, Design Guide, Product Guide, Manual, and Revit BIM — see which doc types each model is missing.

  Use it before a bid submittal or commissioning checklist to catch missing compliance or reference docs.

  extron-pp-cli catalog completeness --bom ./rack.csv --json

• literature recent — Newest Extron literature across the whole library, ordered by date, filterable by category and age.

  Use it to track manual/firmware-doc releases without re-checking the website.

  extron-pp-cli literature recent --days 30 --category manual --json --select title,date,category,url

• literature family — Browse every document for a product family (DTP, MAV, IPL, DVS, ...) across all alphabetical letters at once.

  Use it to pull every doc for a family before writing control code or a design guide review.

  extron-pp-cli literature family dtp --json

• catalog verify — Compare local PDF sizes against the download ledger to flag truncated or mismatched downloads.

  Use it after a batch download or sync to confirm every PDF landed complete and current.

  extron-pp-cli catalog verify --dir ./docs --json

Project-driven assembly

• literature rack — Assemble the full official doc set for every model in a rack bill of materials — report or batch-download in one pass.

  Use it when a project's doc binder must match the exact gear list on the job.

  extron-pp-cli literature rack --bom ./rack.csv --download --dir ./docs

Command Reference

catalog sync — Build the local literature catalog (run this first)

• extron-pp-cli catalog sync — fetch the first index page per letter bucket (0-9, A-Z). A fast baseline of roughly 1,200 documents, not the complete catalog: any category with more than one page of results is truncated at the page-1 ceiling.
• extron-pp-cli catalog sync --full — also follow each category's pagination. This is what produces the complete catalog (roughly 3,600 documents and up). Slower; budget it with --max-duration.
• extron-pp-cli catalog sync --letters A,B,C — narrow to specific letter buckets
• extron-pp-cli catalog sync --full --max-duration 4h --retries 3 — long crawl with a bigger overall budget and more per-letter retries

Use bare catalog sync to get something searchable quickly; use --full before any answer that depends on the catalog being complete — a rack doc binder, a completeness report, or a bid compliance check. --max-pages caps pagination per category and truncates in the same way --full's absence does, so leave it unset for a genuinely complete crawl.

A letter bucket that fails is retried (--retries, default 2) and then skipped, so one bad bucket does not discard the rest of the crawl. Skipped buckets are listed in the summary's errors array and counted in letters_failed; the run exits non-zero only when every bucket failed, or when --strict is passed. The root --timeout bounds each letter bucket; --max-duration (default 30m) bounds the whole crawl.

Do not confuse catalog sync with the top-level sync. Top-level sync walks the generated literature endpoint resource and refreshes entity lookups — it does not build the catalog. Only catalog sync populates the store that search, catalog completeness, catalog verify, literature recent, and literature updates read.

literature — Extron literature library index (spec sheets, manuals, guides)

• extron-pp-cli literature — Fetch the alphabetical literature index for a letter
• extron-pp-cli literature list — List literature from the local catalog, filterable by category and letter
• extron-pp-cli literature get — Resolve a product or document name to its official Extron literature
• extron-pp-cli literature download — Download official spec sheets and manuals as PDFs
• extron-pp-cli literature recent — Newest literature across the whole library, ordered by date
• extron-pp-cli literature updates — See which downloaded docs have a newer revision upstream
• extron-pp-cli literature family — Every document for a product family (DTP, MAV, IPL, DVS, ...)
• extron-pp-cli literature rack — Assemble the full doc set for every model in a rack BOM

catalog — Local-catalog reporting

• extron-pp-cli catalog completeness — Per-model gap report across Brochure, Declaration of Conformity, Design Guide, Product Guide, Manual, and Revit BIM
• extron-pp-cli catalog verify — Compare local PDF sizes and revisions against the download ledger

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

extron-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query. Under --json/--agent, an unmatched query returns exit 0 with an empty matches array.

Recipes

First run: build the catalog

Everything local — search, literature list, catalog completeness, catalog verify — reads the catalog this builds, so run it before trusting any local result. There are two passes, and the difference matters:

# Fast baseline: first index page per letter bucket, ~1,200 docs.
# Large categories are truncated here — this is NOT the complete catalog.
extron-pp-cli catalog sync

# Complete catalog: follows every category's pagination, ~3,600 docs and up.
extron-pp-cli catalog sync --full --timeout 15m --max-duration 4h --json

Run the --full pass before any answer that depends on completeness — a rack doc binder, a completeness report, a bid compliance check. If you only ran the baseline, a document that exists at Extron can be missing from local search with no error to tell you.

--timeout bounds each letter bucket, --max-duration bounds the whole crawl. Failed buckets are retried and then skipped; check letters_failed and errors in the summary, then re-run just those buckets:

extron-pp-cli catalog sync --letters A,Q --full --timeout 15m

What did Extron release this month

extron-pp-cli literature recent --days 30 --json --select title,date,category,url

Agent-friendly list of the newest docs with a narrow --select so the payload stays small.

Stale-doc sweep before commissioning

extron-pp-cli literature updates --dir ./docs --download --dry-run

See which project PDFs are superseded and preview the re-download without touching disk.

Rack doc binder

extron-pp-cli literature rack --bom ./rack.csv --download --dir ./docs

Pull the full official doc set for every model on the job in one pass.

Family reference pull

extron-pp-cli literature family dtp --json

All DTP-family docs across every letter of the index, in machine-readable form.

Bid compliance check

extron-pp-cli catalog completeness --bom ./rack.csv --json

Which models are missing a Declaration of Conformity or manual before the submittal.

Auth Setup

No authentication required.

Run extron-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr

• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  extron-pp-cli literature --agent --select id,name,status

• Previewable — --dry-run shows the request without sending

• Offline-friendly — sync/search commands can use the local SQLite store when available

• Non-interactive — never prompts, every input is a flag

• Read-only — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests

Response envelope

Commands that read from the local store or the API wrap output in a provenance envelope:

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.

Paths and state

Agents should treat the CLI's path resolver as part of the runtime contract:

• Use --home <dir> for one invocation, or set EXTRON_HOME=<dir> to relocate all four path kinds under one root.

• Use per-kind env vars only when a specific kind must diverge: EXTRON_CONFIG_DIR, EXTRON_DATA_DIR, EXTRON_STATE_DIR, EXTRON_CACHE_DIR.

• Resolution order is per-kind env var, --home, EXTRON_HOME, XDG (XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME), then platform defaults.

• config contains settings like config.toml and profiles. data contains credentials.toml, data.db, cookies, and auth sidecars. state contains persisted queries, jobs, and teach.log. cache contains regenerable HTTP/cache files.

• Stored secrets live in credentials.toml under the data dir. Existing legacy config.toml secrets are read for compatibility and leave config.toml on the first auth write.

• Run extron-pp-cli doctor --fail-on warn to surface path and credential-location warnings. agent-context exposes a schema v4 paths block for agents that need the resolved dirs.

• For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags:

  {
    "mcpServers": {
      "extron": {
        "command": "extron-pp-mcp",
        "env": {
          "EXTRON_HOME": "/srv/extron"
        }
      }
    }
  }

Fleet precedence: an inherited per-kind env var overrides an explicit --home for that kind. Use EXTRON_HOME or per-kind vars as durable fleet levers, and use --home only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing EXTRON_HOME, or doctor will not find credentials left under the former root.

Automatic learning

This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a flag_alias candidate, and a teach on a query family without a playbook auto-synthesizes a playbook_candidate from the session's journal. Your job is judgment only: recall first, act on surfaced candidates, teach the final answer, playbook amend when you observe a correction. You never record failures by hand.

Step 1: recall before any discovery

Before list/search/drill commands on a new user question, run:

extron-pp-cli recall "<user's question>" --agent

The response envelope:

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "extron-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and learnings list and learnings candidates are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught.

Step 2: decision tree

Read candidates, playbook, notes, results[0], and warnings in that order:

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `extron-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a Results[] hit - use both: the Playbook tells you which choreography to run; the resource hits short-circuit specific steps. Default to skipping mismatches; pass --debug-mismatches only when investigating cold-start surprises.

Candidate judgment details: learnings confirm <id> prints the candidate's full payload before materializing it - check that the printed payload matches the behavior you verified. learnings reject <id> tombstones the derivation signature so the same candidate does not resurface. The envelope carries only the few candidates worth acting on now; extron-pp-cli learnings candidates lists the full open set.

Graceful degradation: if learnings confirm is an unknown command, you are driving an older binary - ignore the candidates guidance and follow the rest of the protocol.