--- name: pp-extron description: "Every Extron spec sheet and user manual, browsable and searchable offline with revision tracking no other Extron tool has. Trigger phrases: `download the Extron manual for`, `get the spec sheet for that projector`, `find the latest Extron doc revision`, `check what Extron literature is new`, `pull the Extron docs for this rack`, `use extron`, `run extron`." author: "drummerms" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - extron-pp-cli install: - kind: go bins: [extron-pp-cli] module: github.com/mvanhorn/printing-press-library/library/devices/extron/cmd/extron-pp-cli --- # 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: ```bash 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: ```bash 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`._ ```bash 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._ ```bash 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._ ```bash 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._ ```bash 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._ ```bash 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._ ```bash 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._ ```bash 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: ```bash extron-pp-cli which "" ``` `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: ```bash # 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: ```bash extron-pp-cli catalog sync --letters A,Q --full --timeout 15m ``` ### What did Extron release this month ```bash 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 ```bash 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 ```bash 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 ```bash extron-pp-cli literature family dtp --json ``` All DTP-family docs across every letter of the index, in machine-readable form. ### Bid compliance check ```bash 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: ```bash 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: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": } ``` 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 ` for one invocation, or set `EXTRON_HOME=` 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: ```json { "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: ```bash extron-pp-cli recall "" --agent ``` The response envelope: ```json { "query": "...", "normalized": "", "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": ["", "extron-pp-cli learnings confirm 12"] } ], "playbook": { "query_family": "...", "playbook": { "steps": [ { "cmd": "", "purpose": "..." } ], "entity_slots": ["$ENTITY"], "expected_tool_calls": 3 }, "slots_resolved": { "$ENTITY": { "token": "", "canonical": "" } }, "notes": "" }, "notes": "" } ``` 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 ` only after the trial verified the behavior. Reject a wrong candidate with `learnings reject `. -> 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