--- name: pp-cdc-pakistan description: "The only machine-readable view of Pakistani custody data — per-security CDS penetration and a twenty-year eligibility record, from a source no tool has ever automated. Trigger phrases: `how much of this symbol is in CDS`, `CDS eligibility history for`, `has this PSX symbol been reused`, `government stake in this Pakistani company`, `CDC statistics`, `use cdc-pakistan`, `run cdc-pakistan`." author: "qazmataz" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - cdc-pakistan-pp-cli install: - kind: go bins: [cdc-pakistan-pp-cli] module: github.com/mvanhorn/printing-press-library/library/payments/cdc-pakistan/cmd/cdc-pakistan-pp-cli --- # CDC Pakistan — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `cdc-pakistan-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 cdc-pakistan --cli-only ``` 2. Verify: `cdc-pakistan-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.6 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/payments/cdc-pakistan/cmd/cdc-pakistan-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. CDC publishes the sole per-security custody-penetration figures in the Pakistani market as split PDFs behind a bot challenge, with no API and no history endpoint. This CLI mints a browser clearance once, replays it over plain HTTP, and turns the downloads corpus into a queryable local store. `coverage map` proves what is mirrored, `identity ledger` stops symbol recycling from corrupting your return series, and `eligibility state` folds two decades of notices into a per-security lifecycle. ## When to Use This CLI Reach for this CLI when you need Pakistani custody-layer facts that exist nowhere else in machine-readable form: what share of a security's capital sits in the central depository, whether a symbol has been reused by a different issuer, or when a security entered or left CDS eligibility. It is also the right tool when you need to prove a local mirror is complete before running research on it. ## Anti-triggers Do not use this CLI for: - Do not use this CLI for holder-level or sub-account positions — CDC does not publish them, they require an individual investor's own login. - Do not use it for the nine-class investor taxonomy that NCCPL and MUFAP publish — CDC exposes only Individual versus Corporate, at aggregate level. - Do not use it for daily prices, volumes or index data — that is the PSX CLI's surface. - Do not use it to determine whether a security is tradable today — CDS eligibility is a custody status, not a trading suspension. - Do not ask it for a free-float time series — only one live vintage of the penetration report exists. ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Local state that compounds - **`coverage map`** — See exactly which document buckets are mirrored, which are genuinely absent at source, and which were never asked for. _Run this before trusting any other command's completeness; it is the only command that writes the document index._ ```bash cdc-pakistan-pp-cli coverage map --category notices --agent ``` - **`identity ledger`** — Reconstruct a security's symbol, name and ISIN history so you never splice two different issuers into one return series. _Reach for this before joining CDC data to any symbol-keyed price series; symbol recycling silently corrupts factor research._ ```bash cdc-pakistan-pp-cli identity ledger --symbol LOTCHEM --agent ``` - **`stats history`** — Track the sixteen CDS aggregate metrics forward from your first sync, with archived rows labelled as such. _Use to measure retail-participation growth; archived rows are non-contiguous and must never be read as a continuous series._ ```bash cdc-pakistan-pp-cli stats history --metric sub_accounts_individual --agent ``` ### Twenty years of regulatory events - **`eligibility state`** — Get a security's full CDS-eligibility history folded from twenty years of notices into a six-state lifecycle. _Use for CDS-eligibility history, but note CDS eligibility is not the same as PSX trading suspension and is not a tradability gate._ ```bash cdc-pakistan-pp-cli eligibility state --isin PK0069501016 --agent ``` ### Extraction you can trust - **`verify rows`** — Prove the PDF extraction is trustworthy by asserting the report's own percentage column against its own share and capital columns. _Run this before any analysis that depends on the penetration numbers; residual signatures tell you which column drifted._ ```bash cdc-pakistan-pp-cli verify rows --vintage 2025-11-30 --agent ``` - **`verify schema`** — Refuse to blend vintages whose column sets are incompatible, and refuse a month that is missing one of its parts. _Run this whenever a new vintage lands; it blocks silently-incompatible data instead of averaging it._ ```bash cdc-pakistan-pp-cli verify schema --vintage 2025-11-30 --agent ``` ### Cross-source joins - **`float triangulate`** — Put CDC custody penetration beside PSX free-float shares and NCCPL free-float percent, with each denominator named. _Use this to see where the three float definitions disagree; it deliberately never blends them into one number._ ```bash cdc-pakistan-pp-cli float triangulate --symbol OGDC --agent ``` - **`gop stake`** — Derive state-held capital per security from the difference between the including-GoP and excluding-GoP capital columns. _Use for a current cross-section of state ownership; there is only one vintage, so no time series exists._ ```bash cdc-pakistan-pp-cli gop stake --min-pct 25 --agent ``` ## Command Reference **assets** — Static PDF report files under /assets/uploads/YYYY/MM/. - `cdc-pakistan-pp-cli assets` — Fetch one report PDF. Also challenged by Cloudflare, so the same clearance cookie is required. **downloads** — CDC downloads corpus — 7,956 documents across 15 categories, 2007-2026. - `cdc-pakistan-pp-cli downloads` — List download items for one (category, year, page). **statistics** — CDS aggregate statistics — a 16-row HTML table, overwritten monthly. Current-state only. - `cdc-pakistan-pp-cli statistics` — Fetch the current CDS aggregate statistics table. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash cdc-pakistan-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. `--json` (and other machine formats) keep that exit-2 contract and write `{"matches":[]}` on stdout so agents can inspect the envelope without treating a miss as success. ## Recipes ### Prove the mirror before trusting it ```bash cdc-pakistan-pp-cli coverage map --agent --select buckets.category,buckets.year,buckets.state ``` Returns the tri-state coverage per bucket so you can tell a genuine source gap from an unasked question. ### Narrow a wide eligibility history for an agent ```bash cdc-pakistan-pp-cli eligibility state --isin PK0069501016 --agent --select events.effective_date,events.state,events.notice_url ``` The full event payload is large; selecting three dotted paths keeps an agent's context small while preserving the audit trail. ### Find state-owned concentration ```bash cdc-pakistan-pp-cli gop stake --min-pct 25 --agent --select rows.symbol,rows.gop_shares,rows.gop_pct ``` Lists securities where the Government of Pakistan holds at least a quarter of paid-up capital. ### Catch a symbol collision before a join ```bash cdc-pakistan-pp-cli identity resolve --symbol LOTCHEM --as-of 2019-06-30 --agent ``` Returns the identity in force on that date, or NOT_IN_VINTAGE rather than guessing. ### Audit an extraction end to end ```bash cdc-pakistan-pp-cli verify rows --vintage 2025-11-30 --agent --select findings.check_name,findings.severity,findings.isin ``` Surfaces only the failing checks and the ISINs they belong to. ## Auth Setup CDC sits behind a Cloudflare JS challenge on every path. The authoritative gesture is `auth clearance set`, which stores three things as one unit: the `cf_clearance` cookie, the **exact User-Agent that minted it** (the cookie is bound to that User-Agent and is useless without it), and the mint time. Clear the challenge once in a real browser, then pass the cookie and that browser's User-Agent: ```bash # The cookie is read from stdin so it never reaches your shell history. printf '%s' "$CF_CLEARANCE" | cdc-pakistan-pp-cli auth clearance set --user-agent "$UA" cdc-pakistan-pp-cli auth clearance status ``` `$UA` must be the exact User-Agent of the browser you cleared the challenge in. The clearance has a **measured hard lifetime of roughly thirty minutes from mint**, regardless of traffic — the cookie's own expiry field claims a year and is not to be trusted. The long-running commands (`coverage map`, `verify rows`, `stats history --snapshot`) check the remaining margin before starting and refuse early rather than dying midway through a fan-out; the thin single-request commands (`downloads`, `statistics`, `assets`) send the stored pair but do not pre-check the margin, so past the window they simply return a challenge error. `auth login --chrome` is the framework's generic cookie import. It populates the generated credential store and is enough for the thin fetchers, but it captures neither the minting User-Agent nor a mint time, so it cannot support the margin guard and does not satisfy the commands that read the clearance store. Prefer `auth clearance set`. Run `cdc-pakistan-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color`. Global format flags share one contract on promoted, novel, sync, and `--deliver` paths: - `--json` — one JSON document on stdout (sync progress events go to stderr) - `--compact` — keep identity/status/timestamp fields; does not change the document vs stream shape - `--csv` / `--plain` — tabular rows (collection envelopes unwrap to the row array) - `--quiet` — one identity value per row, no envelope - **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 cdc-pakistan-pp-cli downloads --agent ``` - **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 `CDC_PAKISTAN_HOME=` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `CDC_PAKISTAN_CONFIG_DIR`, `CDC_PAKISTAN_DATA_DIR`, `CDC_PAKISTAN_STATE_DIR`, `CDC_PAKISTAN_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `CDC_PAKISTAN_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 `cdc-pakistan-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": { "cdc-pakistan": { "command": "cdc-pakistan-pp-mcp", "env": { "CDC_PAKISTAN_HOME": "/srv/cdc-pakistan" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `CDC_PAKISTAN_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 `CDC_PAKISTAN_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 cdc-pakistan-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": ["", "cdc-pakistan-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 `cdc-pakistan-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 ` prints the candidate's full payload before materializing it - check that the printed payload matches the behavior you verified. `learnings reject ` tombstones the derivation signature so the same candidate does not resurface. The envelope carries only the few candidates worth acting on now; `cdc-pakistan-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