{
  "markdown": "# Recoup Catalog Deals\n\nAgent plugin for music catalog acquisition, seller preparation, financing\nunderwriting, royalty normalization, rights checks, and valuation\nanalysis. Built by [Recoup](https://recoupable.com).\n\nThe plugin turns a messy seller data room into a source-cited deal\npackage: normalized royalty data, rights exceptions, valuation\nworkpapers, an **agent-authored HTML dashboard**, and buyer/seller/lender\nmemos. The whole thing is driven by a single command —\n`/recoup-catalog-deal`.\n\n## Install\n\n### Claude Code (CLI)\n\n```bash\nclaude plugin install https://github.com/recoupable/recoup-catalogs-plugin\n```\n\nThen **restart your Claude Code session** so `hooks/hooks.json` loads.\n\n### Claude Cowork\n\n1. Open the plugin marketplace (puzzle-piece icon in the sidebar).\n2. Click **Add custom plugin** and paste:\n   `https://github.com/recoupable/recoup-catalogs-plugin`\n3. Approve the requested tool permissions (`Read`, `Write`, `Bash` —\n   needed to run the validator scripts).\n4. **Restart the Cowork session** so the PreToolUse and Stop hooks\n   load.\n5. Confirm install: type `/plugin` and check that\n   `recoup-catalogs-plugin` is listed.\n\n### Cursor\n\n1. Cursor → Settings → Plugins → **Add custom plugin**.\n2. Paste the GitHub URL above.\n3. Restart Cursor so `.cursor-plugin/plugin.json` loads commands,\n   skills, and agents.\n\n### Optional dependencies\n\nCore scripts run on the Python standard library alone. PDF and XLSX\nextraction need two extra packages:\n\n```bash\npip3 install -r requirements.txt   # pdfplumber, openpyxl\n```\n\nYou can skip this if your data room is CSV/TSV only.\n\n## Getting started\n\nAfter installing, open a new chat in Claude and try:\n\n> **Let's analyze a catalog with /recoup-catalog-deal**\n\nClaude will ask what kind of deal this is (buy-side, seller-prep, or\nfinancing) and what to call it. Drag your seller's files into the\nchat — royalty statements, contracts, metadata exports, even messy\nones. Claude runs the full workflow end-to-end: scaffolds the\nworkspace, normalizes the royalties, flags rights issues, builds an\ninteractive dashboard, and drafts an IC memo.\n\nWhen it finishes, open:\n\n```text\ndeals/{deal-id}/DASHBOARD.html\n```\n\nThe dashboard is **authored by the agent** for your specific\ncatalog — layout, charts, and narrative shaped by the deal's story.\nA concentration-driven catalog reads differently than a recoupment-\ncliff catalog. Agents in May 2026 build remarkable dashboards when\ngiven good direction; the `skills/recoup-catalog-dashboard/SKILL.md`\nfile is that direction.\n\nWhen you're ready to share the deal with a buyer, IC, or lender:\n\n```text\n/recoup-catalog-report\n```\n\nThat exports a single PDF you can attach to an email.\n\n### No catalog handy? Try the demo\n\nTo see what the plugin produces before pointing it at a real deal — or\nto show a teammate — run `/recoup-catalog-demo`. It runs the full\nworkflow against a bundled synthetic catalog.\n\n## Commands\n\n| Command | When to use it |\n| ------- | -------------- |\n| `/recoup-catalog-deal` | **Default.** End-to-end run from kickoff to dashboard and IC memo, no stops between phases. |\n| `/recoup-catalog-demo` | Optional: runs the full workflow on a bundled synthetic catalog. Useful for showing a teammate what the plugin produces. |\n| `/recoup-catalog-kickoff` | Power-user: scaffold the workspace and stop. |\n| `/recoup-catalog-ingest` | Power-user: re-normalize after dropping new files into `source/`. Auto-recovers when seller headers don't match a provider profile. |\n| `/recoup-catalog-analyze` | Power-user: refresh analysis workpapers (NPS/NLS bridge, valuation summary). |\n| `/recoup-catalog-dashboard` | Power-user: refresh `DASHBOARD.html` after editing workpapers, findings, or recommendations. |\n| `/recoup-catalog-qc` | Power-user: re-run QC after editing findings or memos. |\n| `/recoup-catalog-package` | Power-user: refine the IC memo / financing pack / seller cleanup report. |\n| `/recoup-catalog-report` | Export the validated dashboard + memo as a single shareable PDF you can email (`deals/{deal-id}/REPORT.pdf`). |\n\nIf you're new to the plugin, ignore the power-user commands and start\nwith `/recoup-catalog-deal`. Try `/recoup-catalog-demo` only if\nyou want to see the output before pointing it at a real deal.\n\n> **v0.3.0 spec migration:** The 9 slash commands above were migrated from `commands/*.md` files to `skills/<command-name>/SKILL.md` files per Anthropic's newer skills-not-commands convention (the official `claude-plugins-official` example-plugin declares the `commands/*.md` layout legacy). Both layouts exist in this release for back-compat; the legacy command files will be removed in a future release. Three of the new skill folders (`recoup-catalog-dashboard`, `recoup-catalog-ingest`, `recoup-catalog-report`) share names with existing model-invoked skills and were resolved by augmenting those existing skills rather than creating parallel files.\n\n## Skills\n\nLoaded automatically by description-matching when the agent recognizes\nthe task:\n\n| Skill | What it does |\n| ----- | ------------ |\n| `recoup-deal-kickoff` | Scaffolds a deal workspace and produces the first missing-file list. |\n| `recoup-catalog-ingest` | Normalizes data rooms, royalty statements, metadata, and rights files into auditable hand-off artifacts. |\n| `recoup-catalog-analysis` | Analyzes normalized cash flows and projects value. |\n| `recoup-catalog-dashboard` | Authors the customer-facing HTML dashboard. The agent picks layout, charts, narrative, and depth — guided by a strong skill spec and a post-hoc validator. |\n| `recoup-catalog-report` | Packages the validated dashboard + memo + workpapers as a single shareable PDF (`deals/{deal-id}/REPORT.pdf`). Agent picks the conversion path (headless Chrome, Playwright, WeasyPrint, or ReportLab). |\n| `recoup-rights-review` | Reviews ownership support, chain of title, splits, restrictions, transferability. |\n| `recoup-royalty-audit` | Audits statements, normalized ledgers, PRO/MLC issues, gross-to-net support. |\n| `recoup-seller-prep` | Creates cleanup worklists that reduce avoidable valuation discounts before going to market. |\n| `recoup-financing-underwrite` | Builds lender-ready collateral and cash-flow review. |\n| `recoup-ic-memo-package` | Assembles IC memos, seller cleanup reports, financing packs, and final outputs. |\n| `recoup-post-close-admin` | Turns deal-review data into transfer, registration, and income-monitoring worklists. |\n\n## What you get when `/recoup-catalog-deal` finishes\n\n```text\ndeals/{deal-id}/\n├── DASHBOARD.html              ← open this first (agent-authored)\n├── REPORT.pdf                  ← optional shareable export (run /recoup-catalog-report)\n├── source/                     ← raw seller files (immutable)\n├── normalized/\n│   ├── royalty-ledger.csv\n│   ├── canonical-catalog.csv\n│   └── rights-map.csv\n├── workpapers/\n│   ├── file-manifest.json\n│   ├── ingest-coverage.json\n│   ├── concentration-analysis.json\n│   ├── valuation-summary.json\n│   ├── nps-bridge.json\n│   ├── nls-bridge.json\n│   ├── recommendations.json\n│   └── readiness-check.md       ← internal-only QC view\n├── findings/\n│   ├── findings.json\n│   ├── missing-files.md\n│   └── manual-review-queue.md\n├── memos/\n│   └── ic-memo.md\n├── assumptions.yaml\n└── evidence-ledger.json\n```\n\n`DASHBOARD.html` is the customer-facing artifact. Everything else is\nprovenance, evidence, and internal QC. `source/` is treated as\nimmutable evidence — writes into it are denied by the PreToolUse hook\nso the agent cannot accidentally mutate the data room.\n\n## How the agent stays honest\n\nThe trust model has two complementary layers:\n\n### Deterministic source files\n\nRoyalty ledgers, valuation summaries, NPS/NLS bridges, concentration\nanalyses, findings, and the evidence ledger are all structured JSON\nor CSV. They go through validators\n(`scripts/run-deal-checks.py`) that confirm shape, evidence\nreferences, cross-artifact consistency, and findings-to-evidence\ntraceability. These are the source of truth.\n\n### Post-hoc dashboard verification\n\nThe dashboard itself is built by the agent — full creative freedom on\nlayout, chart types (Chart.js, D3, Plotly), tabs, scenario sliders,\nnarrative structure, depth. After the agent writes\n`DASHBOARD.html`, `scripts/validate-dashboard.py` runs and enforces:\n\n1. File exists, parses as HTML, between 5 KB and 5 MB.\n2. Required structural markers present (status, KPIs, findings,\n   recommendations, evidence trail).\n3. External `<script src>` tags only from a CDN allowlist\n   (`cdn.jsdelivr.net`, `cdnjs.cloudflare.com`, `unpkg.com`).\n4. No `<iframe>`, `<object>`, `<embed>`, `eval(`, `Function(`,\n   `document.write(`.\n5. Every `$`-claim in the rendered text either matches a workpaper\n   value within 5%, or carries a `data-evidence`, `data-source`, or\n   `data-derived` attribute (or any ancestor does). Unverified\n   numerical claims fail the validator.\n\n### Two hooks defined in `hooks/hooks.json`\n\n- **PreToolUse `protect-source-files.sh`** — denies any\n  `Write`/`Edit`/`MultiEdit` whose path matches `*/deals/*/source/*`.\n\n- **Stop hook (prompt-based, two gates)**.\n  - Gate A (completion claims) — when the agent claims a package is\n    \"ready\", the hook verifies that `run-deal-checks.py` ran\n    cleanly, the readiness check isn't `blocked`, `assumptions.yaml`\n    and `evidence-ledger.json` exist, findings aren't silently\n    dropped, and memo claims trace to evidence.\n  - Gate B (mid-workflow progress) — when the user launched\n    `/recoup-catalog-deal` or `/recoup-catalog-demo`, the hook blocks the\n    agent from stopping until `DASHBOARD.html` exists **and**\n    `validate-dashboard.py` returned `status: ok`. This is what\n    prevents the agent from quitting after Phase 2 with \"want me to\n    continue?\"\n\nRestart your session after editing `hooks/hooks.json`.\n\n## Development\n\nKeep each skill focused and self-contained. Use `references/` for\ndetailed domain material so each `SKILL.md` stays easy to scan. Use\n`scripts/` for deterministic checks and the dashboard validator —\n**not** for rendering customer-facing HTML. The dashboard is the\nagent's deliverable; presentation is its job.\n\nCurrent scripts include validators, the dashboard validator,\nnormalization, auto-column-mapping recovery, and concentration / NPS-NLS\nbridge calculators. The auto column mapper\n(`scripts/auto-column-map.py`) is the recovery path when a seller's\nCSV uses non-canonical headers — the agent runs it automatically when\nnormalization returns `status: \"partial\"`.\n\nGolden fixtures live under `fixtures/golden/` (per-provider canonical\ninput/expected output pairs). The synthetic demo catalog lives under\n`fixtures/demo-data-room/` — that's what `/recoup-catalog-demo` copies in.\n\nRun all tests before release:\n\n```bash\npython3 scripts/test-normalize-royalty-statement.py\npython3 scripts/test-golden-fixtures.py\npython3 scripts/test-validate-deal-workspace.py\npython3 scripts/test-validate-findings-evidence.py\npython3 scripts/test-validate-workspace-consistency.py\npython3 scripts/test-build-manual-review-queue.py\npython3 scripts/test-calculate-concentration.py\npython3 scripts/test-dataroom-hygiene-scan.py\npython3 scripts/test-deal-readiness.py\npython3 scripts/test-helpers.py\npython3 scripts/test-validate-dashboard.py\npython3 scripts/test-auto-column-map.py\n```\n\nOperate a real deal workspace with:\n\n```bash\npython3 scripts/run-deal-checks.py deals/{deal-id}\npython3 scripts/build-deal-readiness.py deals/{deal-id}      # internal readiness\npython3 scripts/validate-dashboard.py deals/{deal-id}        # check agent's DASHBOARD.html\n```\n\n## Structure\n\n```text\nrecoup-catalogs-plugin/\n├── .claude-plugin/plugin.json\n├── .codex-plugin/plugin.json\n├── .cursor-plugin/plugin.json\n├── agents/                     # Specialist sub-agents (QC, rights, royalty, valuation, metadata)\n├── commands/                   # Slash commands — start with /recoup-catalog-deal\n├── evals/                      # Behavioral eval scenarios\n├── fixtures/\n│   ├── demo-data-room/         # Synthetic catalog used by /recoup-catalog-demo\n│   └── golden/                 # Per-provider canonical input/output pairs\n├── hooks/                      # PreToolUse + Stop guardrails\n├── references/                 # Domain knowledge (workflow, red flags, normalization, tooling)\n├── scripts/                    # Deterministic Python — validators only, no renderers\n├── skills/                     # Loaded by description-matching at runtime\n│   └── recoup-catalog-dashboard/      # The agent's guide to authoring DASHBOARD.html\n├── templates/deal-workspace/   # Workspace scaffolding (assumptions, findings, evidence, memos)\n└── README.md\n```\n\n## About\n\n[Recoup](https://recoupable.com) builds AI-powered infrastructure for\nmusic operators. **Recoup Catalog Deals** is one product in the broader\n**Recoup Catalog Intelligence** product line.\n\n- Plugin: `recoup-catalogs-plugin`\n- Repository: <https://github.com/recoupable/recoup-catalogs-plugin>\n- Support: <support@recoupable.com>\n",
  "bytes": 13000,
  "sha": "a34ee5ab835dcc405aea4aa4fb8c16310d122154b138e3ce00ba4d12cb095af9",
  "repo_slug": "recoupable/music-catalog-diligence",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_recoupable_music_catalog_diligence_music_ca3843fe/readme"
}