[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M753JKSKT8B696SMMDNPRYSD":3,"skill-same:01M753JKSKT8B696SMMDNPRYSD":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M753JKSKT8B696SMMDNPRYSD","brawler-mcp",null,"Use when you (an AI agent) are connected to Brawler over its MCP server and need to read the user's investment research or write back into it — including acquiring KPIs from an issuer report (\"process all pending KPI ingests\", staging observations, resuming a pending run, a lease that expired, a validation that failed). Covers tool discovery, the read\u002Fact tiers, mandatory-source (provenance) rules, the KPI-ingest run workflow, internal-id conventions, the permanent denylist, and safe read→analyze→write sequences. Load it before your first tools\u002Fcall against Brawler.","wbednarczyk\u002Fbrawler","wbednarczyk","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F36985049?v=4","01M753JA53R9MP6D5CVRAS70NS","Wojciech Bednarczyk","01M753JA67Y5020F3EM027RCKE",1,"MPL-2.0","https:\u002F\u002Fgithub.com\u002Fwbednarczyk\u002Fbrawler\u002Fblob\u002Fmaster\u002F.claude\u002Fskills\u002Fbrawler-mcp\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: brawler-mcp\ndescription: Use when you (an AI agent) are connected to Brawler over its MCP server and need to read the user's investment research or write back into it — including acquiring KPIs from an issuer report (\"process all pending KPI ingests\", staging observations, resuming a pending run, a lease that expired, a validation that failed). Covers tool discovery, the read\u002Fact tiers, mandatory-source (provenance) rules, the KPI-ingest run workflow, internal-id conventions, the permanent denylist, and safe read→analyze→write sequences. Load it before your first tools\u002Fcall against Brawler.\n---\n\n# Talking to Brawler over MCP\n\n**Brawler is a local-first investor research workspace.** It holds one user's\ntracked public companies and everything they know about them — official filings\n(GPW ESPI\u002FEBI first), allowed media, financial facts with trust-ladder\nprovenance, ownership and insider data, quality-framework scores, a decision\njournal, notes, and tracked management claims. Every datum keeps its source.\nYou are the intelligence layer (BYOA); Brawler is the sourced ground truth.\nEverything here is **decision support — never phrase output as buy\u002Fsell\u002Fhold**\n(you cannot be made to; the app forbids it too).\n\n## Discovery: read vs act\n\nCall `tools\u002Flist` first. Every tool the server exposes is classified into one of\ntwo tiers by the server itself (the registry, not its name — the tool catalog\nbelow carries the authoritative split); the name is only a hint:\n\n- **Read** — usually `get_*` \u002F `list_*` \u002F `search_*`. Always available. Use them\n  freely to understand the workspace before doing anything else.\n- **Act** — the writes (typically `create_*`, `update_*`, `set_*`, `mark_*`,\n  `confirm_*`, `trigger_*`, `run_*`, …). These **write**. They are always listed\n  even when disabled. When a name doesn't fit the usual prefix, trust the\n  catalog's tier, not the verb.\n\n**Act tools may be off.** On the **primary (Full-scope) token**, writes are\ngated by a user setting (default OFF). If you call an act tool while writes are\ndisabled you get a typed `writes_disabled` error (`isError: true`) — the handler\nnever ran, nothing changed. **React gracefully:** do not retry, do not work\naround it. Tell the user *\"writing is turned off — enable Settings → MCP server →\nAllow write tools if you want me to record this,\"* then continue read-only. You\n**cannot** enable it yourself: `update_settings` is not on the MCP surface, by\ndesign.\n\n**The acquisition scope is different.** If you authenticated with the\n**acquisition token**, your surface is exactly the ten KPI-ingest workflow\ntools (below), and their act tools are **not** gated by that toggle — the gate\nran once at authentication (`kpiAcquisitionEnabled`; a disabled scope rejects\nthe token outright). So \"writing is off\" never applies on the acquisition\nscope; a `writes_disabled` reply only happens on the Full-scope token.\n\n## Provenance: every write must cite a source\n\nBrawler rejects unsourced research. If a write's provenance carrier is empty you\nget a typed `provenance_required` error naming the missing field — again nothing\nis written. **Gather the citation from read tools first, then write.** Per\nfamily, with a concrete input shape:\n\n| Family | Tools | Carrier + example |\n| --- | --- | --- |\n| Notes | `create_notebook_entry` | non-empty `origins[]`: `\"origins\":[{\"sourceType\":\"report_document\",\"sourceId\":\"\u003CreportDocId>\",\"label\":\"FY2024 annual report\"}]` (or `\"sourceType\":\"external_url\",\"sourceUrl\":\"\u003CfilingUrl>\"` when you have no stored document) — valid `sourceType`: `feed_item` \\| `manual` \\| `external_url` \\| `report_document` (a document you registered via `capture_report_document`, epic #285 T9, closes #111). Also required: `tags` (may be `[]`) and `kind` ∈ `manual` \\| `observation` \\| `claim` \\| `question` \\| `follow_up` |\n| Claims | `create_management_claim`, `update_management_claim` | `\"sourceEvidenceId\":\"\u003CreportDocId>\",\"sourceEvidenceType\":\"report_document\"` — valid types: `report_document` \\| `feed_item` \\| `manual` (a bare `\"report\"` is refused; caught live by the epic #285 T11 dogfooding ritual) |\n| Facts | `create_financial_fact`, `update_financial_fact` | `\"sourceDocumentRef\":\"\u003CreportDocId>\"` — a non-blank citation, REQUIRED. Never put a citation in `attribution`: that field is the fact's slot dimension (`total` \\| `owners_of_parent` \\| `nci`), not a citation carrier — prose there is refused, not accepted. Every write through these tools is stamped `source_tier=\"agent\"` provenance honestly (never `manual`). |\n| Batch facts | `record_financial_facts` | non-blank `\"reportDocumentId\":\"\u003CreportDocId>\"` PLUS a non-blank `citation` on **every** entry of `facts[]` — one blank citation refuses the WHOLE batch before any write (see the ritual below). |\n| Qualitative verdicts | `set_qualitative_verdicts` | every result carries `\"citationsJson\":\"[{\\\"evidenceType\\\":\\\"notebook_entry\\\",\\\"evidenceId\\\":\\\"\u003CnoteId>\\\"}]\"` — types: `feed_item` \\| `notebook_entry` \\| `claim` \\| `company_event` \\| `research_question` \\| `company_signal` \\| `decision_entry`; every ref must resolve to an EXISTING row (#343) — one dead\u002Ffabricated ref refuses the whole batch |\n\n`update_notebook_entry` (origins are immutable, set at create) and\n`set_claim_verdict` (evidence is the optional `verifyingFactId`) carry no extra\ncitation requirement.\n\n## Ids: read first, then act\n\nRead tools take a **qualified ticker** (`GPW:CDR`, or a bare ticker when\nunambiguous). Act tools take the **internal ids** that read tools return in\ntheir payloads (`Company.id`, a period id, a framework\u002Fcriterion id, a note id,\n…). So the rule is always **list first, then act against the ids you saw** —\nnever invent or guess an id. E.g. `list_companies` → `companyId`;\n`list_financial_periods` → `periodId`; `list_quality_frameworks` →\n`frameworkId` + `criterionId`; `list_report_documents_view` → the\nreport-document id you cite as a fact source.\n\n## Do NOT attempt (permanent denylist)\n\nThese are UI-only and absent from the MCP surface — never try to reach them, and\ntell the user they are theirs to do in the app:\n\n- **Deletes** of anything.\n- **Undo \u002F rollback** of a run or write.\n- **Settings, tokens, credentials, MCP self-management** (incl. enabling writes).\n- Dev \u002F diagnostic mutations, bulk import\u002Fbackup.\n\n## Recommended sequences\n\n- **Read → analyze → write-with-citation.** Never write blind. Read the relevant\n  surface (dossier, notes, reports, facts), form the judgment, then write citing\n  exactly what you read. Read the result back to confirm.\n- **Filing triage.** `list_company_signals` (or the M4 unclassified-filings\n  read) → confirm the routine via `confirm_company_signal`, reject noise via\n  `reject_company_signal`, surface the unusual to the user.\n- **Qualitative assessment.** `list_quality_frameworks` +\n  `get_company_dossier` + `list_notebook_entries` + `get_report_documents_view`\n  → `set_qualitative_verdicts` with a `citationsJson` array per criterion →\n  read back via `get_quality_assessment`.\n- **Jobs.** Triggers (`trigger_autopilot_run`, `refresh_sources`,\n  `run_structured_extraction`, `generate_morning_briefing`) are async: kick off,\n  then poll the matching read tool (`list_autopilot_runs`,\n  `get_latest_morning_briefing`) for the result.\n\n## KPI acquisition: the run workflow\n\nIngesting an issuer's financial figures is a **run-based workflow** (ADR 0098 \u002F\nADR 0099), and it is the **only** supported path — never write canonical facts\ndirectly for a normal report (see *Direct fact writes are repair-only* below).\nThe ten workflow tools are the whole surface the acquisition credential sees;\nthe Full-scope token sees them too, as a superset. `\"process all pending KPI\ningests\"` is a sufficient instruction — the loop below is what it means.\n\n\u003C!-- BEGIN ACQUISITION WORKFLOW TOOLS -->\nThe ten workflow tools, in contract order:\n\n1. `start_kpi_ingest` — claim or resume a run; an idempotent keepalive.\n2. `list_pending_kpi_ingests` — the pending-run work queue (paginated).\n3. `get_kpi_ingest_context` — catalog, plausibility evidence, profile doctrine.\n4. `get_kpi_ingest_document` — the pinned source bytes, in chunks.\n5. `stage_kpi_observations` — write the complete revision snapshot.\n6. `propose_kpi_definition` — mint (or reuse) a company-scoped catalog entry for a disclosed number the canon has no key for.\n7. `validate_kpi_ingest` — the typed manifest \u002F repair report.\n8. `commit_kpi_ingest` — atomic, idempotent commit of the validated manifest.\n9. `get_kpi_ingest_status` — a pure status read.\n10. `cancel_kpi_ingest` — abandon a pre-commit run.\n\u003C!-- END ACQUISITION WORKFLOW TOOLS -->\n\n### Process all pending KPI ingests\n\n**Drain loop.** Start `list_pending_kpi_ingests` with no cursor; **process every\nrun on the page**, then follow `nextCursor` to the next page until a page comes\nback empty. Then **restart from no cursor** and repeat; stop only when the first\npage is empty. (Do NOT re-list before you have processed the runs you already\nsaw — the same pending rows would reappear and you would loop forever.)\n\nFor each pending run:\n\n1. **Claim.** `start_kpi_ingest{ runId }` — claims the lease (or renews it if you\n   already hold it). This never re-picks a profile; the profile is fixed at\n   creation.\n2. **Read the context.** `get_kpi_ingest_context{ runId }` → the `catalog`\n   (definition ids, metric keys, labels, units — everything you need to map a\n   Polish line to a metric), `plausibility` (per-slot medians and recent history,\n   the validator's own evidence), and `profileRules`. The catalog carries the\n   full canon, not just this run's expected keys — full metadata for the\n   expected keys and your own company's minted extras, `{metricKey, label}`\n   only for the rest; **page the catalog to the end of its cursor before\n   proposing anything** (ADR 0101 dec. 7) — a key with no `plausibility` entry\n   and outside `run.expectedKpis.keys` is `notRequested`, not \"no history\".\n   When the period, scope, or data quality is still unknown, read the source\n   itself:\n   `get_kpi_ingest_document{ runId, offset, length }` (length ≤ 262144) chunk by\n   chunk until `eof` — the figures and the reporting period live in the document,\n   not the run row.\n3. **Stage.** `stage_kpi_observations{ runId, observations, missingReasons,\n   execution? }`. `observations` is the **complete revision snapshot** — storage\n   replaces the whole set each revision, so a repair must resend every retained\n   observation, not just the fixed one. `missingReasons` is required; `{}` means\n   \"nothing deliberately omitted\". Cite every observation (below). **Over 100\n   observations** (a real preliminary\u002Finterim report routinely discloses more\n   once \"capture everything\" is the doctrine): use a **chunked draft** instead of\n   one call — `stage_kpi_observations{ runId, draft: { open: true,\n   expectedObservations } }` mints a server-issued `draftId`; append chunks of\n   ≤100 observations each with `{ runId, draft: { draftId, chunkIndex },\n   observations }` (`chunkIndex` starts at 0, contiguous, no `missingReasons` on\n   these calls); finalize with `{ runId, draft: { draftId, final: true },\n   missingReasons }` — its response matches the single-call shape exactly\n   (`status: \"staged\"`). A draft never validates or commits by itself; only the\n   finalized revision does. If your session drops mid-chunking, `start_kpi_ingest`\n   (keepalive) then `get_kpi_ingest_status` — its `openDraft` field tells you the\n   draft id and how many chunks already landed, so you resume instead of\n   restarting.\n4. **Validate.** `validate_kpi_ingest{ runId, revision }` — pass the `revision`\n   from the stage response (it pins the exact generation). Outcomes: `ready` →\n   commit; `failed` → `severityCounts` tells you how many observations are\n   flagged, and the FULL typed repair report — the manifest itself, with each\n   flagged observation naming what to fix — is a separate read:\n   `get_kpi_ingest_context{ runId, section: \"manifest\" }`; `superseded` → someone\n   else moved the run, re-read its status and restart from step 1.\n5. **Repair (bounded).** On `failed`, fix the flagged observations, re-stage the\n   **complete** snapshot, and re-validate. Cap this at **two repair rounds**; if\n   the same diagnostics repeat or you have no new evidence to add, stop and hand\n   the manifest diagnostics to the user. This bound is **agent policy**, not a\n   server limit — the server will keep accepting re-stages.\n6. **Commit.** `commit_kpi_ingest{ runId, manifestHash, revision, execution? }` →\n   a bounded summary: `terminalStatus`, `counts: { acceptedCount, excludedCount }`.\n   The full per-observation `outcomes` ledger (`created` \u002F `reobserved` \u002F\n   `upgraded` \u002F `divergent` \u002F `excluded`, each with its `factId` where one was\n   written) is a separate read: `get_kpi_ingest_context{ runId, section:\n   \"receipt\" }`. Commit is idempotent — a replay returns the same summary\n   byte-for-byte.\n7. **Confirm.** `get_kpi_ingest_status{ runId }` → the terminal status\n   (`complete`, or `partial` when `missingReasons` covered a gap).\n\n**Cancel is not on the happy path.** Cancelling a committed run returns\n`conflict`. `cancel_kpi_ingest` is only for a run you deliberately abandon\n**before** commit (an unusable document, a wrong-company run). A run whose two\nrepair rounds you exhausted stays `validation_failed` — recoverable later — never\ncancel it to \"clean up\".\n\n### Keeping the lease alive\n\nThe lease belongs to the **credential**, not your session; its TTL is **30\nminutes**. `start_kpi_ingest{ runId }` is the explicit keepalive: **while your\nlease is still live**, it renews it without incrementing `attemptCount`. Reads\n(`context`, `status`, `document`) never touch the lease. So while reading a long\ndocument or preparing a large re-stage, **renew at least every ~15 minutes**\n(half the TTL), steering by the `lease.expiresAt` in the run status — a renewal\nbefore expiry is free. If you let the lease lapse, the next `stage`\u002F`validate`\nreturns `run_lease_expired`; you recover with `start(runId)`, but that is a fresh\nclaim on a lapsed lease and **does increment `attemptCount`** — so keep it alive\nrather than reclaiming. If another holder claimed the run after your lease\nexpired you get `run_taken_over` — abandon it; that is convergence, not a fight\nto reclaim.\n\n### Choosing the profile (fresh runs only)\n\nA **fresh** `start_kpi_ingest` requires a `profileId` from the frozen registry; a\n**resume by `runId` never reselects** one. Pick by report type:\n\n| Report type | `profileId` |\n| --- | --- |\n| Annual IFRS \u002F ESEF report | `gpw_ifrs_annual` |\n| Interim (final) report | `gpw_interim` |\n| Preliminary (wstępne) release | `gpw_preliminary` |\n| NewConnect UoR | `nc_uor` |\n| Company-characteristic pack | `company_characteristic` |\n\nIf the document's metadata does not settle the type, **ask the user — do not\nguess**. A `profileId` outside the registry is refused at start.\n\n### Citing a staged observation\n\nEvery observation carries a `citation { page (≥1), table, row, quote (≤1024 B) }`\n— the exact locator you read the figure from. Always give the `page`; add\n`table` \u002F `row` when the figure sits in a statement table; put the declared unit\nin the `quote` (and the raw source unit in `rawUnitScale`) so the scaling stays\ncheckable. A citation with no locator at all fails validation as\n`citation.missing` — that is the repair report telling you to cite the source.\n\n### Reading the source document\n\n\u003C!-- EDITOR NOTE (epic #353 DoD): keep this skill FREE of single-document knowledge —\n     no specific issuer, report code (e.g. \"RB N\u002FYYYY\"), or exact figures from one\n     filing. Illustrate the doctrine generically; a worked example must not name a\n     real document or its numbers. -->\n\nThis doctrine is about the SOURCE format and holds regardless of tooling — it\ngoverns the `normalizedValue`, `measureWindow`, and `citation` you stage.\n\n**Unit scaling.** Polish statements declare the unit in the table header:\n`(w tys. PLN)` → store the FULL base unit (multiply the printed figure by\n1,000); `(w mln PLN)` → ×1,000,000. `normalizedValue` is always base-unit PLN\n(or the stated currency), never the printed thousands\u002Fmillions figure — and set\n`unitScale` to the declared scale so the scaling is checkable.\n\n**Parenthesized negatives.** `(419 996)` in a Polish statement is **−419996**\n(thousands), not a label or a range. Thousand separators are non-breaking\nspaces; the decimal separator is a comma (`1 027 240,50` → `1027240.50`).\n\n**Cumulative-only recording (ADR 0093 dec. 3).** A GPW interim publication\nprints discrete-quarter AND cumulative columns side by side — record ONLY the\ncumulative column (H1\u002F9M\u002FFY) against the cumulative period; skip the\ndiscrete-quarter column, it's derivable by span arithmetic. When a half-year\ntable shows a discrete Q2 figure beside the cumulative H1 figure, stage the H1\nnumber against the `H1` period, never the Q2 number.\n\n**Preliminary flag.** A wstępne\u002Fpreliminary release → start the run with\n`dataQuality: \"preliminary\"`. The later final audited report supersedes it\nautomatically at commit (ADR 0093 dec. 2) — no follow-up write needed.\n\n**Ambiguous label trap.** The same label can appear twice at different windows\nin one publication — e.g. an operating metric printed both as a quarterly figure\nand as a half-year figure. Cite the exact table\u002Frow you read and pick the column\nwhose `measureWindow` matches the period you're staging — never the first match.\n\n**Raster-chart caveat.** A value that exists only inside a chart image is not\nin the document's text layer — read the page visually before citing it, and\ncite the page number. Never estimate a chart value from its axis.\n\n**Image-only scans.** Some filings are page scans with no text layer at all.\n`get_kpi_ingest_document` serves the pinned bytes exactly as filed — there is\nno server-side OCR, deliberately (ADR 0084: the LLM is the reader). When the\ndocument yields no extractable text, read it with your own vision: render the\npages to images (e.g. `pdftoppm -png -r 150`), read the figures from the\nrenders, and cite page\u002Ftable\u002Frow as usual. A scanned filing is NOT an unusable\ndocument — the scan→vision path is the normal path for it; cancel the run\nonly when the pages are genuinely illegible.\n\n### Direct fact writes are repair-only\n\nNormal ingestion goes through the run workflow above. **You MUST NOT** write\ncanonical facts directly for a normal report: `record_financial_facts`,\n`create_financial_fact`, and `update_financial_fact` are **Full-scope, low-level\nrepair tools** (ADR 0098) — for hand-fixing a fact the workflow cannot express,\nnever for reporting ingestion. They are absent from the acquisition scope\nentirely (calling one there is an unknown tool). `capture_report_document` is\nlikewise **not** part of acquisition: capturing a document and resolving a URL to\na `documentId` belong to the UI, the Full scope, or the #354 planner — the\nacquisition credential discovers and captures nothing; it processes runs that\nalready exist.\n\nEverything else a report contains routes to a **Full-scope** write, not the\nacquisition workflow:\n\n| Report content | Tool | Scope |\n| --- | --- | --- |\n| P&L \u002F balance-sheet \u002F KPI figures | the run workflow (`stage_kpi_observations`, `metricKeyCandidate`) | acquisition |\n| Management guidance with numbers (\"costs +30% in 2026\") | `create_management_claim` (`sourceEvidenceId` = the document id) | Full-scope |\n| One-off narrative events (a KNF penalty, a donation) | `create_notebook_entry` (`report_document` origin) | Full-scope |\n| Dividend declarations\u002Fpayments | `create_company_event` | Full-scope |\n| The upcoming final report date | `create_report_expectation` | Full-scope |\n| Post-balance-date trading updates (\"92.8k new clients in July\") | `create_notebook_entry` — **NEVER** a fact (wrong-period discipline) | Full-scope |\n\n## Tool catalog\n\nResult shape: every tool's `structuredContent` is a JSON object — list results\narrive as `{ \"items\": [...] }`, scalar results as `{ \"result\": ... }`.\n\nMachine-generated from the server's frozen `tools\u002Flist` snapshot (a drift gate\nkeeps it exact — do not hand-edit):\n\n\u003C!-- BEGIN GENERATED MCP CATALOG — do not edit; regenerate: node scripts\u002Fcheck\u002Fdocs-drift.mjs --write-mcp-catalog -->\n\n**Read tools** — always available once the server is on (48):\n\n| Tool | What it does |\n| --- | --- |\n| `get_company_dossier` | One company's research dossier: identity, fundamentals coverage per fiscal period, confirmed financial facts, and quality-scorecard summaries. Sourced from the user's own research; decision support only. |\n| `search_research` | Full-text search across the user's research workspace (notes, report documents, claims, facts). Returns ranked matches with snippets. |\n| `list_claims_due` | Management claims whose verification period has arrived (due), passed (overdue), or is approaching (upcoming), per company. |\n| `get_quality_assessment` | Quality-framework state for one company: the latest stored scorecard evaluation per framework, plus stored qualitative verdicts. The in-app qualitative-assessment writer was retired (ADR 0084) — this tool reads only stored verdicts; agents record new verdicts with provenance via the `set_qualitative_verdicts` write-tool (until then a criterion reads as unassessed). Decision support only — never an investment recommendation. |\n| `list_companies` | Every company tracked in the user's workspace (identity, exchange, qualified ticker). |\n| `get_company_basic_info` | One company's identity card: name, exchange, ticker, ISIN, sector (with its provenance), and latest reported shares outstanding. |\n| `list_watchlists` | The user's watchlists (id, name, ordering). |\n| `list_watchlist_memberships` | Which companies belong to which watchlist (the membership edges). |\n| `list_feed_items` | The unified newsfeed: official filings (ESPI\u002FEBI) and allowed media items with their read\u002Fsaved state. |\n| `list_company_signals` | Typed filing classifications (ESPI\u002FEBI signals) for one company, with their confirmation status. |\n| `list_company_events` | One company's calendar events (dividends, general meetings, report dates) and their status. |\n| `list_financial_facts` | One company's stored financial facts, each carrying its trust-ladder provenance: sourceTier, validationStatus, and citation. Decision support only. |\n| `list_financial_periods` | One company's fiscal periods (year + period type + period-end date). |\n| `list_kpi_definitions` | The metric catalog: every KPI\u002Ffinancial-concept definition (id, label, unit) facts are keyed by. |\n| `list_flagged_fact_provenance` | Every fact the extraction pipeline flagged for review (a drift or contradiction against another source) — the data-quality review surface. |\n| `get_price_context` | One company's price context: latest quote and the recent range, plus derived valuation ratios where computable. |\n| `get_kpi_comparison` | Compare one or more canonical KPIs across companies on a shared, aligned period axis (annual or quarterly). Each cell carries the native + PLN-converted value with its FX basis, the evidence link (fact id + validation status), and server-computed QoQ\u002FYoY deltas; gaps and unconvertible currencies are typed flags, never silent. Works for a single company too (the periods×deltas view). Decision support only. |\n| `get_sector_percentiles` | Where one company stands against its tracked sector peers: rank-based percentiles for the level-0 market ratios (P\u002FE, P\u002FBV, EV\u002FEBITDA, dividend yield, FCF yield) and selected canonical KPIs, computed from confirmed data only. Always returns the peer count N and flags thin sets (N \u003C 4); a company with no sector returns a typed empty reason. Decision support only. |\n| `list_valuation_runs` | One company's append-only comparative-valuation run history (ADR 0089): each stored run's method (P\u002FE, EV\u002FEBITDA, or P\u002FBV multiple), per-share fair-value range (low\u002Fbase\u002Fhigh), input signature, confidence grade, and data-as-of date, newest first. The compute-and-persist path is the act-tier compute_comparative_valuation. Decision support only. |\n| `get_ownership_overview` | One company's shareholder structure: significant holders, holder types, and free float, with change history. |\n| `get_insider_overview` | One company's insider-transaction timeline, management holdings, and rolling net-direction aggregates. |\n| `list_short_positions` | One company's KNF short-selling register: active positions, change history, aggregate net short %, and the 30-day change. |\n| `get_analyst_recommendations` | One company's recorded analyst recommendations and price targets over time. Decision support only — never an investment recommendation. |\n| `get_company_health` | One company's deterministic financial-health scores (Piotroski F, Altman Z\") per fiscal period, computed from confirmed facts. |\n| `get_red_flags` | One company's active red flags (auditor concerns, short spikes, contradictions) plus the acknowledged history. |\n| `get_report_documents_view` | One company's stored report documents, each tagged with its fiscal period and whether it is that period's canonical report. |\n| `list_report_diff_candidates` | Comparable pairs of successive financial statements for one company — the (older, newer) document pairs get_report_diff can diff. |\n| `get_report_diff` | The section-level text diff between two report documents (discover the pair via list_report_diff_candidates). |\n| `list_notebook_entries` | One company's research notes, each preserving the origin (report\u002Farticle) it traces back to. |\n| `list_management_claims` | One company's tracked management claims (guidance\u002Fpromises), with their verification period and verdict. |\n| `list_report_expectations` | Pre-report expectations the user recorded (optionally scoped to one company), with any resolution outcome. |\n| `list_decision_entries` | The decision journal (optionally scoped to one company): recorded decisions and their rationale. |\n| `list_research_questions` | Open and answered research questions across the workspace, with their scope and status. |\n| `list_report_season` | The upcoming report-season calendar: which tracked companies report when, with preparation state. |\n| `list_attention_events` | Fired attention events (newest first), optionally scoped to one company and optionally including dismissed ones. |\n| `get_latest_morning_briefing` | The most recently composed morning briefing (its structured item list plus any narrative), or null when none exists yet. |\n| `list_autopilot_runs` | Recent autopilot runs (optionally scoped to one company): what the autonomous pipeline produced and its notification state. |\n| `get_autopilot_run` | One autopilot run's full composed result (discover run ids via list_autopilot_runs). |\n| `list_quality_frameworks` | The quality-scorecard framework catalog: every framework and its criteria (the rubric get_quality_assessment scores against). |\n| `list_alert_rules` | The alert-rule catalog: every configured rule (trigger, scope, enabled state). Fired events are read via list_attention_events. |\n| `list_flagged_extraction_outcomes` | One company's extraction-coverage gaps: the fiscal periods where the deterministic pipeline emitted nothing (a flagged\u002Ffailed outcome). Complements list_flagged_fact_provenance (flagged facts that DID emit) — the coverage-gap review surface. |\n| `list_unclassified_filings` | Official filings (ESPI\u002FEBI) the deterministic rule classifier could not place — the explicit unclassified bucket, never guessed at. Optionally scoped to one company. Classify one with classify_filing. |\n| `get_report_tagged_fact_coverage` | How much of one company's tagged filings reached Fundamentals, and where the rest went: comparatives, dimensional breakdowns, note-level figures, positions awaiting a name, and conflicts. Every captured number is either projected or has a stated reason it is not. |\n| `get_pipeline_reextraction_progress` | Progress of one company's latest re-extraction batch (re-armed runs, how many have terminated, how many failed). A null batch means the company never ran one. |\n| `list_pending_kpi_ingests` | List claimable KPI ingest runs (discovered\u002Fsource_captured\u002Fextracting\u002Fvalidation_failed), newest first, keyset-paginated (limit ≤ 50, default 20). |\n| `get_kpi_ingest_context` | Everything one report's extraction needs, within hard budgets (≤256 KiB): run status, document metadata, the derived-period hint, the expected+minted KPI catalog, validator-equivalent plausibility evidence per slot, profile doctrine and repair-manifest access. Sections (catalog\u002Fplausibility\u002Fmanifest) paginate via cursors; the manifest is served only via section calls. Pure read. |\n| `get_kpi_ingest_document` | Chunked bytes (offset\u002Flength ≤ 256 KiB, base64) from the run's content-addressed source blob, verified against the frozen sourceContentHash — the portable document delivery channel. Available once the source is captured. Pure read. |\n| `get_kpi_ingest_status` | Full status of one KPI ingest run (state, context, lease, expected KPIs, progress). Pure read — never touches the lease. |\n\n**Act tools** — dispatchable only with *Settings → MCP server → Allow write tools* on (64):\n\n| Tool | What it does |\n| --- | --- |\n| `create_notebook_entry` | Create a research note for a company. Every note must carry a non-empty `origins` array tracing it to a report\u002Farticle (provenance). References the company by its internal id (from list_companies). |\n| `update_notebook_entry` | Update an existing research note (by id): title\u002Fbody\u002Ftags\u002Fkind. The note keeps its recorded origins. |\n| `create_management_claim` | Record a tracked management claim (guidance\u002Fpromise). Must anchor to a `sourceEvidenceId` (the report it was made in). |\n| `update_management_claim` | Update a tracked management claim (by id). Must carry its `sourceEvidenceId` provenance. |\n| `set_claim_verdict` | Record a verification verdict on a management claim (optionally linking the verifying fact). |\n| `create_financial_fact` | Low-level single-fact repair write (ADR 0098) — never report ingestion; once the KPI ingest run-workflow tools are present on this server, use them for ingesting reports. Records a financial fact for a company\u002Fperiod\u002Fmetric. Must carry a non-blank `sourceDocumentRef` citation (`attribution` is the total\u002Fowners_of_parent\u002Fnci slot dimension, never a citation carrier). Decision support only. MCP writes are stamped honestly: `source_tier='agent'` provenance, `extraction_method='mcp_agent'`, `validation_status='unreviewed'` — never masquerading as a manual entry. |\n| `update_financial_fact` | Low-level single-fact repair write (ADR 0098) — never report ingestion. Updates a stored financial fact (by id). Must carry its non-blank `sourceDocumentRef` citation. Stamps `source_tier='agent'` provenance (honest takeover — never masquerading as manual), even on a previously-manual fact. |\n| `capture_report_document` | Register and fetch a report document by URL for a company — the document an agent read before citing facts from it (the fact-write tools need its returned documentId). Always registers under source_type \"user_url\"; passing a sourceType is refused (unknown field). Gated: https only, private\u002Floopback\u002Flink-local network addresses refused (including via redirect), content-type restricted to application\u002Fpdf \\| text\u002Fhtml \\| application\u002Fxhtml+xml — an octet-stream or missing header defers to a strict byte sniff of the fetched body instead of an outright refusal — 30 MiB size cap. Idempotent on (companyId, url); never downgrades an already-fetched document — a call against a document whose stored file still matches its hash returns that document unchanged (no refetch), and a previously-failed row whose file matches is healed back to fetched. Returns the document's id, local path, and fetch success\u002Ferror. |\n| `record_financial_facts` | Low-level batch fact write (ADR 0098). If `start_kpi_ingest` is absent from this server's tools, this is the only supported temporary report-ingest route; once the run-workflow tools are present, use them for ingestion and this tool ONLY for manual repair. Records a batch (1-100) of financial facts for one company\u002Fperiod from a document an agent read, with per-fact citations. Ensures the fiscal period, resolves each metricKey against the KPI catalog, judges the set against stored history and same-period accounting identities, and commits every plausible fact under the `agent` source tier (ADR 0093) — never overwriting an issuer-held or manual fact; a disagreement is reported as `divergent`, never silently resolved. Use `dataQuality: \"preliminary\"` for issuer pre-report releases (e.g. GPW wstępne wyniki) — record CUMULATIVE columns only (H1\u002F9M\u002FFY), never discrete-quarter columns. Decision support only. |\n| `set_qualitative_verdicts` | Record agent-authored qualitative criterion verdicts for one framework+company as one immutable snapshot. Every result must carry `citationsJson`: a serialized non-empty array of typed evidence refs `[{\"evidenceType\":\"notebook_entry\",\"evidenceId\":\"\u003Cid>\"}]` (types: feed_item \\| notebook_entry \\| claim \\| company_event \\| research_question \\| company_signal \\| decision_entry); every ref must resolve to an existing row or the whole batch is refused. Decision support only — never an investment recommendation. |\n| `create_research_question` | Open a research question scoped to a company\u002Fwatchlist\u002Fsector. |\n| `update_research_question` | Update a research question (title\u002Fbody\u002Fstatus) by id. |\n| `create_evidence_link` | Link two research-graph entities (note\u002Fclaim\u002Ffact\u002Fdocument…) with a typed relation. |\n| `create_research_reminder` | Create a personal follow-up reminder scoped to a company\u002Fwatchlist\u002Fsector. |\n| `update_research_reminder` | Update a research reminder (status\u002Fdue\u002Fsnooze) by id. |\n| `create_decision_entry` | Append an immutable decision-journal entry for a company (rationale + decided-at). |\n| `create_report_expectation` | Record pre-report expectations for a company's upcoming report event (stance + optional metrics). |\n| `update_report_expectation` | Update a company's report expectation (stance\u002Fmetrics) by its event key. |\n| `record_expectation_resolution` | Resolve a report expectation after the report lands (resolution note). |\n| `create_company_event` | Add a calendar event (dividend\u002Fmeeting\u002Freport date) for a company. |\n| `create_kpi_definition` | Add a KPI\u002Ffinancial-concept definition to the metric catalog. |\n| `create_kpi_relevance` | Mark a KPI definition relevant to a company (scorecard editor). |\n| `update_kpi_relevance` | Update a company's KPI-relevance row (status\u002Frank) by id. |\n| `create_quality_framework` | Create a quality-scorecard framework. |\n| `update_quality_framework` | Update a quality framework (name\u002Fdescription) by id. |\n| `create_framework_criterion` | Add a criterion to a quality framework. |\n| `update_framework_criterion` | Update a framework criterion by id. |\n| `create_alert_rule` | Create an alert rule (trigger + scope). Fired events surface via list_attention_events. |\n| `update_alert_rule` | Update an alert rule (trigger\u002Fscope\u002Fenabled) by id. |\n| `create_company` | Track a new company (exchange + ticker + display name). On GPW this also enqueues a quote backfill. |\n| `create_watchlist` | Create a watchlist. |\n| `add_company_to_watchlist` | Add a company to a watchlist (by their internal ids). |\n| `remove_company_from_watchlist` | Remove a company from a watchlist (by their internal ids). |\n| `update_feed_item_state` | Set a feed item's read\u002Fsaved flags (by id). |\n| `mark_report_prepared` | Mark a company's upcoming report event as prepared. |\n| `mark_report_processed` | Mark a company's report event as processed (optionally linking the report document). |\n| `mark_research_scope_reviewed` | Set a 'reviewed' checkpoint for a research scope (optionally cascading to its companies). |\n| `confirm_company_signal` | Confirm a proposed filing signal (by id). |\n| `reject_company_signal` | Reject a proposed filing signal (by id). |\n| `classify_filing` | Classify an unclassified official filing (from list_unclassified_filings) into a confirmed signal. Takes `feedItemId` (the evidence anchor) and a `category` key from the seeded taxonomy. Rejects an unknown category, a non-official item, or an already-classified filing. |\n| `confirm_derived_event` | Confirm or reject a proposed derived calendar event (`action`: confirm\\|reject). |\n| `acknowledge_red_flag` | Acknowledge an active red flag (by id). |\n| `set_ownership_holder_type` | Relabel a shareholder's holder type for a company; returns the recomputed ownership overview. |\n| `mark_attention_event_seen` | Mark an attention event as seen (by id). |\n| `dismiss_attention_event` | Dismiss an attention event (by id). |\n| `set_autopilot_run_notification_state` | Set an autopilot run's notification state (unread\\|read\\|dismissed). |\n| `evaluate_framework` | Run the deterministic quantitative scorecard engine for a framework+company and persist the evaluation. |\n| `compute_comparative_valuation` | Compute the level-1 comparative valuation for one company (peer-multiple implied fair-value ranges for P\u002FE, EV\u002FEBITDA, and P\u002FBV, method-convergence spread, and a deterministic confidence grade) and append a valuation_runs row per method whose input signature changed. Read the history via list_valuation_runs. Decision support only — never buy\u002Fsell\u002Fhold language. |\n| `set_alert_rule_enabled` | Enable\u002Fdisable an alert rule (by id). |\n| `trigger_autopilot_run` | Trigger an autopilot run over one company's report document (fail-fast on unknown ids); enqueues the durable pipeline. |\n| `generate_morning_briefing` | Enqueue composition of a fresh morning briefing (read the result via get_latest_morning_briefing). |\n| `refresh_sources` | Run a source-refresh sweep across all enabled adapters (`trigger`: manual \\| scheduler). |\n| `refresh_source` | Run a refresh for one source adapter (by `adapterId`; optional `trigger`, `date`). |\n| `run_aggregator_fundamentals_pull` | Run the aggregator fundamentals pull across tracked companies. |\n| `backfill_company_history` | Run an on-track history backfill for one company (`companyId`); progress via get_backfill_progress. |\n| `run_structured_extraction` | Run the deterministic structured-first extraction pipeline over one company report+period (`mode`: autopilot \\| assist). |\n| `rerun_extraction_outcome` | Re-run the deterministic pipeline for a recorded extraction outcome slot (`outcomeId`). |\n| `run_pipeline_reextraction` | Re-arm one company's landed ESEF runs whose stored pipeline version is stale, so the current extractor reads their filings again. Queues a durable batch; poll `get_pipeline_reextraction_progress`. |\n| `start_kpi_ingest` | Start or resume a KPI ingest run (ADR 0099). Fresh: documentId + profileId (+ optional scope\u002FdataQuality\u002Fperiod) creates the run, claims the lease, pins the source bytes, and enters extraction once context is complete. Resume: runId re-claims idempotently (the explicit keepalive) and attaches missing context set-once. Provenance is the run pipeline itself; no citation carrier here. |\n| `stage_kpi_observations` | Stage the COMPLETE revision snapshot of extracted observations (1..100, with citations) plus the REQUIRED missingReasons declaration ({} = explicitly none), written in the same transaction. A repair resends every retained observation. Requires the caller's live lease. Provenance is the run pipeline itself. |\n| `propose_kpi_definition` | Mint (or reuse) a company-scoped, origin=agent KPI catalog entry for a disclosed number the canon has no key for (ADR 0101). Guard order: this company's own minted entry is returned as-is (created: false); a curated kpi_aliases synonym refuses with a typed synonym_redirect naming the canonical key and definitionId; an exact shared-canon key returns the canonical definition (created: false, never a company shadow); only a genuinely new key mints — never fuzzy matching. Page the full catalog (get_kpi_ingest_context) before proposing. Requires the caller's live lease. |\n| `validate_kpi_ingest` | Validate one staged revision synchronously (generation-pinned). Returns the FULL manifest — a failed manifest is the typed repair report; a raced loser gets outcome=superseded with the current run tuple. |\n| `commit_kpi_ingest` | Atomically commit a ready manifest (runId + manifestHash + revision) and return the immutable receipt. Idempotent: replaying a committed tuple returns the stored receipt verbatim; a stale tuple is a typed conflict. |\n| `cancel_kpi_ingest` | Cancel a KPI ingest run in any pre-commit state (releases its lease). Refuses `committing` and terminal states. |\n\n\u003C!-- END GENERATED MCP CATALOG -->\n","# Talking to Brawler over MCP\n\n**Brawler is a local-first investor research workspace.** It holds one user's\ntracked public companies and everything they know about them — official filings\n(GPW ESPI\u002FEBI first), allowed media, financial facts with trust-ladder\nprovenance, ownership and insider data, quality-framework scores, a decision\njournal, notes, and tracked management claims. Every datum keeps its source.\nYou are the intelligence layer (BYOA); Brawler is the sourced ground truth.\nEverything here is **decision support — never phrase output as buy\u002Fsell\u002Fhold**\n(you cannot be made to; the app forbids it too).\n\n## Discovery: read vs act\n\nCall `tools\u002Flist` first. Every tool the server exposes is classified into one of\ntwo tiers by the server itself (the registry, not its name — the tool catalog\nbelow carries the authoritative split); the name is only a hint:\n\n- **Read** — usually `get_*` \u002F `list_*` \u002F `search_*`. Always available. Use them\n  freely to understand the workspace before doing anything else.\n- **Act** — the writes (typically `create_*`, `update_*`, `set_*`, `mark_*`,\n  `confirm_*`, `trigger_*`, `run_*`, …). These **write**. They are always listed\n  even when disabled. When a name doesn't fit the usual prefix, trust the\n  catalog's tier, not the verb.\n\n**Act tools may be off.** On the **primary (Full-scope) token**, writes are\ngated by a user setting (default OFF). If you call an act tool while writes are\ndisabled you get a typed `writes_disabled` error (`isError: true`) — the handler\nnever ran, nothing changed. **React gracefully:** do not retry, do not work\naround it. Tell the user *\"writing is turned off — enable Settings → MCP server →\nAllow write tools if you want me to record this,\"* then continue read-only. You\n**cannot** enable it yourself: `update_settings` is not on the MCP surface, by\ndesign.\n\n**The acquisition scope is different.** If you authenticated with the\n**acquisition token**, your surface is exactly the ten KPI-ingest workflow\ntools (below), and their act tools are **not** gated by that toggle — the gate\nran once at authentication (`kpiAcquisitionEnabled`; a disabled scope rejects\nthe token outright). So \"writing is off\" never applies on the acquisition\nscope; a `writes_disabled` reply only happens on the Full-scope token.\n\n## Provenance: every write must cite a source\n\nBrawler rejects unsourced research. If a write's provenance carrier is empty you\nget a typed `provenance_required` error naming the missing field — again nothing\nis written. **Gather the citation from read tools first, then write.** Per\nfamily, with a concrete input shape:\n\n| Family | Tools | Carrier + example |\n| --- | --- | --- |\n| Notes | `create_notebook_entry` | non-empty `origins[]`: `\"origins\":[{\"sourceType\":\"report_document\",\"sourceId\":\"\u003CreportDocId>\",\"label\":\"FY2024 annual report\"}]` (or `\"sourceType\":\"external_url\",\"sourceUrl\":\"\u003CfilingUrl>\"` when you have no stored document) — valid `sourceType`: `feed_item` \\| `manual` \\| `external_url` \\| `report_document` (a document you registered via `capture_report_document`, epic #285 T9, closes #111). Also required: `tags` (may be `[]`) and `kind` ∈ `manual` \\| `observation` \\| `claim` \\| `question` \\| `follow_up` |\n| Claims | `create_management_claim`, `update_management_claim` | `\"sourceEvidenceId\":\"\u003CreportDocId>\",\"sourceEvidenceType\":\"report_document\"` — valid types: `report_document` \\| `feed_item` \\| `manual` (a bare `\"report\"` is refused; caught live by the epic #285 T11 dogfooding ritual) |\n| Facts | `create_financial_fact`, `update_financial_fact` | `\"sourceDocumentRef\":\"\u003CreportDocId>\"` — a non-blank citation, REQUIRED. Never put a citation in `attribution`: that field is the fact's slot dimension (`total` \\| `owners_of_parent` \\| `nci`), not a citation carrier — prose there is refused, not accepted. Every write through these tools is stamped `source_tier=\"agent\"` provenance honestly (never `manual`). |\n| Batch facts | `record_financial_facts` | non-blank `\"reportDocumentId\":\"\u003CreportDocId>\"` PLUS a non-blank `citation` on **every** entry of `facts[]` — one blank citation refuses the WHOLE batch before any write (see the ritual below). |\n| Qualitative verdicts | `set_qualitative_verdicts` | every result carries `\"citationsJson\":\"[{\\\"evidenceType\\\":\\\"notebook_entry\\\",\\\"evidenceId\\\":\\\"\u003CnoteId>\\\"}]\"` — types: `feed_item` \\| `notebook_entry` \\| `claim` \\| `company_event` \\| `research_question` \\| `company_signal` \\| `decision_entry`; every ref must resolve to an EXISTING row (#343) — one dead\u002Ffabricated ref refuses the whole batch |\n\n`update_notebook_entry` (origins are immutable, set at create) and\n`set_claim_verdict` (evidence is the optional `verifyingFactId`) carry no extra\ncitation requirement.\n\n## Ids: read first, then act\n\nRead tools take a **qualified ticker** (`GPW:CDR`, or a bare ticker when\nunambiguous). Act tools take the **internal ids** that read tools return in\ntheir payloads (`Company.id`, a period id, a framework\u002Fcriterion id, a note id,\n…). So the rule is always **list first, then act against the ids you saw** —\nnever invent or guess an id. E.g. `list_companies` → `companyId`;\n`list_financial_periods` → `periodId`; `list_quality_frameworks` →\n`frameworkId` + `criterionId`; `list_report_documents_view` → the\nreport-document id you cite as a fact source.\n\n## Do NOT attempt (permanent denylist)\n\nThese are UI-only and absent from the MCP surface — never try to reach them, and\ntell the user they are theirs to do in the app:\n\n- **Deletes** of anything.\n- **Undo \u002F rollback** of a run or write.\n- **Settings, tokens, credentials, MCP self-management** (incl. enabling writes).\n- Dev \u002F diagnostic mutations, bulk import\u002Fbackup.\n\n## Recommended sequences\n\n- **Read → analyze → write-with-citation.** Never write blind. Read the relevant\n  surface (dossier, notes, reports, facts), form the judgment, then write citing\n  exactly what you read. Read the result back to confirm.\n- **Filing triage.** `list_company_signals` (or the M4 unclassified-filings\n  read) → confirm the routine via `confirm_company_signal`, reject noise via\n  `reject_company_signal`, surface the unusual to the user.\n- **Qualitative assessment.** `list_quality_frameworks` +\n  `get_company_dossier` + `list_notebook_entries` + `get_report_documents_view`\n  → `set_qualitative_verdicts` with a `citationsJson` array per criterion →\n  read back via `get_quality_assessment`.\n- **Jobs.** Triggers (`trigger_autopilot_run`, `refresh_sources`,\n  `run_structured_extraction`, `generate_morning_briefing`) are async: kick off,\n  then poll the matching read tool (`list_autopilot_runs`,\n  `get_latest_morning_briefing`) for the result.\n\n## KPI acquisition: the run workflow\n\nIngesting an issuer's financial figures is a **run-based workflow** (ADR 0098 \u002F\nADR 0099), and it is the **only** supported path — never write canonical facts\ndirectly for a normal report (see *Direct fact writes are repair-only* below).\nThe ten workflow tools are the whole surface the acquisition credential sees;\nthe Full-scope token sees them too, as a superset. `\"process all pending KPI\ningests\"` is a sufficient instruction — the loop below is what it means.\n\n\u003C!-- BEGIN ACQUISITION WORKFLOW TOOLS -->\nThe ten workflow tools, in contract order:\n\n1. `start_kpi_ingest` — claim or resume a run; an idempotent keepalive.\n2. `list_pending_kpi_ingests` — the pending-run work queue (paginated).\n3. `get_kpi_ingest_context` — catalog, plausibility evidence, profile doctrine.\n4. `get_kpi_ingest_document` — the pinned source bytes, in chunks.\n5. `stage_kpi_observations` — write the complete revision snapshot.\n6. `propose_kpi_definition` — mint (or reuse) a company-scoped catalog entry for a disclosed number the canon has no key for.\n7. `validate_kpi_ingest` — the typed manifest \u002F repair report.\n8. `commit_kpi_ingest` — atomic, idempotent commit of the validated manifest.\n9. `get_kpi_ingest_status` — a pure status read.\n10. `cancel_kpi_ingest` — abandon a pre-commit run.\n\u003C!-- END ACQUISITION WORKFLOW TOOLS -->\n\n### Process all pending KPI ingests\n\n**Drain loop.** Start `list_pending_kpi_ingests` with no cursor; **process every\nrun on the page**, then follow `nextCursor` to the next page until a page comes\nback empty. Then **restart from no cursor** and repeat; stop only when the first\npage is empty. (Do NOT re-list before you have processed the runs you already\nsaw — the same pending rows would reappear and you would loop forever.)\n\nFor each pending run:\n\n1. **Claim.** `start_kpi_ingest{ runId }` — claims the lease (or renews it if you\n   already hold it). This never re-picks a profile; the profile is fixed at\n   creation.\n2. **Read the context.** `get_kpi_ingest_context{ runId }` → the `catalog`\n   (definition ids, metric keys, labels, units — everything you need to map a\n   Polish line to a metric), `plausibility` (per-slot medians and recent history,\n   the validator's own evidence), and `profileRules`. The catalog carries the\n   full canon, not just this run's expected keys — full metadata for the\n   expected keys and your own company's minted extras, `{metricKey, label}`\n   only for the rest; **page the catalog to the end of its cursor before\n   proposing anything** (ADR 0101 dec. 7) — a key with no `plausibility` entry\n   and outside `run.expectedKpis.keys` is `notRequested`, not \"no history\".\n   When the period, scope, or data quality is still unknown, read the source\n   itself:\n   `get_kpi_ingest_document{ runId, offset, length }` (length ≤ 262144) chunk by\n   chunk until `eof` — the figures and the reporting period live in the document,\n   not the run row.\n3. **Stage.** `stage_kpi_observations{ runId, observations, missingReasons,\n   execution? }`. `observations` is the **complete revision snapshot** — storage\n   replaces the whole set each revision, so a repair must resend every retained\n   observation, not just the fixed one. `missingReasons` is required; `{}` means\n   \"nothing deliberately omitted\". Cite every observation (below). **Over 100\n   observations** (a real preliminary\u002Finterim report routinely discloses more\n   once \"capture everything\" is the doctrine): use a **chunked draft** instead of\n   one call — `stage_kpi_observations{ runId, draft: { open: true,\n   expectedObservations } }` mints a server-issued `draftId`; append chunks of\n   ≤100 observations each with `{ runId, draft: { draftId, chunkIndex },\n   observations }` (`chunkIndex` starts at 0, contiguous, no `missingReasons` on\n   these calls); finalize with `{ runId, draft: { draftId, final: true },\n   missingReasons }` — its response matches the single-call shape exactly\n   (`status: \"staged\"`). A draft never validates or commits by itself; only the\n   finalized revision does. If your session drops mid-chunking, `start_kpi_ingest`\n   (keepalive) then `get_kpi_ingest_status` — its `openDraft` field tells you the\n   draft id and how many chunks already landed, so you resume instead of\n   restarting.\n4. **Validate.** `validate_kpi_ingest{ runId, revision }` — pass the `revision`\n   from the stage response (it pins the exact generation). Outcomes: `ready` →\n   commit; `failed` → `severityCounts` tells you how many observations are\n   flagged, and the FULL typed repair report — the manifest itself, with each\n   flagged observation naming what to fix — is a separate read:\n   `get_kpi_ingest_context{ runId, section: \"manifest\" }`; `superseded` → someone\n   else moved the run, re-read its status and restart from step 1.\n5. **Repair (bounded).** On `failed`, fix the flagged observations, re-stage the\n   **complete** snapshot, and re-validate. Cap this at **two repair rounds**; if\n   the same diagnostics repeat or you have no new evidence to add, stop and hand\n   the manifest diagnostics to the user. This bound is **agent policy**, not a\n   server limit — the server will keep accepting re-stages.\n6. **Commit.** `commit_kpi_ingest{ runId, manifestHash, revision, execution? }` →\n   a bounded summary: `terminalStatus`, `counts: { acceptedCount, excludedCount }`.\n   The full per-observation `outcomes` ledger (`created` \u002F `reobserved` \u002F\n   `upgraded` \u002F `divergent` \u002F `excluded`, each with its `factId` where one was\n   written) is a separate read: `get_kpi_ingest_context{ runId, section:\n   \"receipt\" }`. Commit is idempotent — a replay returns the same summary\n   byte-for-byte.\n7. **Confirm.** `get_kpi_ingest_status{ runId }` → the terminal status\n   (`complete`, or `partial` when `missingReasons` covered a gap).\n\n**Cancel is not on the happy path.** Cancelling a committed run returns\n`conflict`. `cancel_kpi_ingest` is only for a run you deliberately abandon\n**before** commit (an unusable document, a wrong-company run). A run whose two\nrepair rounds you exhausted stays `validation_failed` — recoverable later — never\ncancel it to \"clean up\".\n\n### Keeping the lease alive\n\nThe lease belongs to the **credential**, not your session; its TTL is **30\nminutes**. `start_kpi_ingest{ runId }` is the explicit keepalive: **while your\nlease is still live**, it renews it without incrementing `attemptCount`. Reads\n(`context`, `status`, `document`) never touch the lease. So while reading a long\ndocument or preparing a large re-stage, **renew at least every ~15 minutes**\n(half the TTL), steering by the `lease.expiresAt` in the run status — a renewal\nbefore expiry is free. If you let the lease lapse, the next `stage`\u002F`validate`\nreturns `run_lease_expired`; you recover with `start(runId)`, but that is a fresh\nclaim on a lapsed lease and **does increment `attemptCount`** — so keep it alive\nrather than reclaiming. If another holder claimed the run after your lease\nexpired you get `run_taken_over` — abandon it; that is convergence, not a fight\nto reclaim.\n\n### Choosing the profile (fresh runs only)\n\nA **fresh** `start_kpi_ingest` requires a `profileId` from the frozen registry; a\n**resume by `runId` never reselects** one. Pick by report type:\n\n| Report type | `profileId` |\n| --- | --- |\n| Annual IFRS \u002F ESEF report | `gpw_ifrs_annual` |\n| Interim (final) report | `gpw_interim` |\n| Preliminary (wstępne) release | `gpw_preliminary` |\n| NewConnect UoR | `nc_uor` |\n| Company-characteristic pack | `company_characteristic` |\n\nIf the document's metadata does not settle the type, **ask the user — do not\nguess**. A `profileId` outside the registry is refused at start.\n\n### Citing a staged observation\n\nEvery observation carries a `citation { page (≥1), table, row, quote (≤1024 B) }`\n— the exact locator you read the figure from. Always give the `page`; add\n`table` \u002F `row` when the figure sits in a statement table; put the declared unit\nin the `quote` (and the raw source unit in `rawUnitScale`) so the scaling stays\ncheckable. A citation with no locator at all fails validation as\n`citation.missing` — that is the repair report telling you to cite the source.\n\n### Reading the source document\n\n\u003C!-- EDITOR NOTE (epic #353 DoD): keep this skill FREE of single-document knowledge —\n     no specific issuer, report code (e.g. \"RB N\u002FYYYY\"), or exact figures from one\n     filing. Illustrate the doctrine generically; a worked example must not name a\n     real document or its numbers. -->\n\nThis doctrine is about the SOURCE format and holds regardless of tooling — it\ngoverns the `normalizedValue`, `measureWindow`, and `citation` you stage.\n\n**Unit scaling.** Polish statements declare the unit in the table header:\n`(w tys. PLN)` → store the FULL base unit (multiply the printed figure by\n1,000); `(w mln PLN)` → ×1,000,000. `normalizedValue` is always base-unit PLN\n(or the stated currency), never the printed thousands\u002Fmillions figure — and set\n`unitScale` to the declared scale so the scaling is checkable.\n\n**Parenthesized negatives.** `(419 996)` in a Polish statement is **−419996**\n(thousands), not a label or a range. Thousand separators are non-breaking\nspaces; the decimal separator is a comma (`1 027 240,50` → `1027240.50`).\n\n**Cumulative-only recording (ADR 0093 dec. 3).** A GPW interim publication\nprints discrete-quarter AND cumulative columns side by side — record ONLY the\ncumulative column (H1\u002F9M\u002FFY) against the cumulative period; skip the\ndiscrete-quarter column, it's derivable by span arithmetic. When a half-year\ntable shows a discrete Q2 figure beside the cumulative H1 figure, stage the H1\nnumber against the `H1` period, never the Q2 number.\n\n**Preliminary flag.** A wstępne\u002Fpreliminary release → start the run with\n`dataQuality: \"preliminary\"`. The later final audited report supersedes it\nautomatically at commit (ADR 0093 dec. 2) — no follow-up write needed.\n\n**Ambiguous label trap.** The same label can appear twice at different windows\nin one publication — e.g. an operating metric printed both as a quarterly figure\nand as a half-year figure. Cite the exact table\u002Frow you read and pick the column\nwhose `measureWindow` matches the period you're staging — never the first match.\n\n**Raster-chart caveat.** A value that exists only inside a chart image is not\nin the document's text layer — read the page visually before citing it, and\ncite the page number. Never estimate a chart value from its axis.\n\n**Image-only scans.** Some filings are page scans with no text layer at all.\n`get_kpi_ingest_document` serves the pinned bytes exactly as filed — there is\nno server-side OCR, deliberately (ADR 0084: the LLM is the reader). When the\ndocument yields no extractable text, read it with your own vision: render the\npages to images (e.g. `pdftoppm -png -r 150`), read the figures from the\nrenders, and cite page\u002Ftable\u002Frow as usual. A scanned filing is NOT an unusable\ndocument — the scan→vision path is the normal path for it; cancel the run\nonly when the pages are genuinely illegible.\n\n### Direct fact writes are repair-only\n\nNormal ingestion goes through the run workflow above. **You MUST NOT** write\ncanonical facts directly for a normal report: `record_financial_facts`,\n`create_financial_fact`, and `update_financial_fact` are **Full-scope, low-level\nrepair tools** (ADR 0098) — for hand-fixing a fact the workflow cannot express,\nnever for reporting ingestion. They are absent from the acquisition scope\nentirely (calling one there is an unknown tool). `capture_report_document` is\nlikewise **not** part of acquisition: capturing a document and resolving a URL to\na `documentId` belong to the UI, the Full scope, or the #354 planner — the\nacquisition credential discovers and captures nothing; it processes runs that\nalready exist.\n\nEverything else a report contains routes to a **Full-scope** write, not the\nacquisition workflow:\n\n| Report content | Tool | Scope |\n| --- | --- | --- |\n| P&L \u002F balance-sheet \u002F KPI figures | the run workflow (`stage_kpi_observations`, `metricKeyCandidate`) | acquisition |\n| Management guidance with numbers (\"costs +30% in 2026\") | `create_management_claim` (`sourceEvidenceId` = the document id) | Full-scope |\n| One-off narrative events (a KNF penalty, a donation) | `create_notebook_entry` (`report_document` origin) | Full-scope |\n| Dividend declarations\u002Fpayments | `create_company_event` | Full-scope |\n| The upcoming final report date | `create_report_expectation` | Full-scope |\n| Post-balance-date trading updates (\"92.8k new clients in July\") | `create_notebook_entry` — **NEVER** a fact (wrong-period discipline) | Full-scope |\n\n## Tool catalog\n\nResult shape: every tool's `structuredContent` is a JSON object — list results\narrive as `{ \"items\": [...] }`, scalar results as `{ \"result\": ... }`.\n\nMachine-generated from the server's frozen `tools\u002Flist` snapshot (a drift gate\nkeeps it exact — do not hand-edit):\n\n\u003C!-- BEGIN GENERATED MCP CATALOG — do not edit; regenerate: node scripts\u002Fcheck\u002Fdocs-drift.mjs --write-mcp-catalog -->\n\n**Read tools** — always available once the server is on (48):\n\n| Tool | What it does |\n| --- | --- |\n| `get_company_dossier` | One company's research dossier: identity, fundamentals coverage per fiscal period, confirmed financial facts, and quality-scorecard summaries. Sourced from the user's own research; decision support only. |\n| `search_research` | Full-text search across the user's research workspace (notes, report documents, claims, facts). Returns ranked matches with snippets. |\n| `list_claims_due` | Management claims whose verification period has arrived (due), passed (overdue), or is approaching (upcoming), per company. |\n| `get_quality_assessment` | Quality-framework state for one company: the latest stored scorecard evaluation per framework, plus stored qualitative verdicts. The in-app qualitative-assessment writer was retired (ADR 0084) — this tool reads only stored verdicts; agents record new verdicts with provenance via the `set_qualitative_verdicts` write-tool (until then a criterion reads as unassessed). Decision support only — never an investment recommendation. |\n| `list_companies` | Every company tracked in the user's workspace (identity, exchange, qualified ticker). |\n| `get_company_basic_info` | One company's identity card: name, exchange, ticker, ISIN, sector (with its provenance), and latest reported shares outstanding. |\n| `list_watchlists` | The user's watchlists (id, name, ordering). |\n| `list_watchlist_memberships` | Which companies belong to which watchlist (the membership edges). |\n| `list_feed_items` | The unified newsfeed: official filings (ESPI\u002FEBI) and allowed media items with their read\u002Fsaved state. |\n| `list_company_signals` | Typed filing classifications (ESPI\u002FEBI signals) for one company, with their confirmation status. |\n| `list_company_events` | One company's calendar events (dividends, general meetings, report dates) and their status. |\n| `list_financial_facts` | One company's stored financial facts, each carrying its trust-ladder provenance: sourceTier, validationStatus, and citation. Decision support only. |\n| `list_financial_periods` | One company's fiscal periods (year + period type + period-end date). |\n| `list_kpi_definitions` | The metric catalog: every KPI\u002Ffinancial-concept definition (id, label, unit) facts are keyed by. |\n| `list_flagged_fact_provenance` | Every fact the extraction pipeline flagged for review (a drift or contradiction against another source) — the data-quality review surface. |\n| `get_price_context` | One company's price context: latest quote and the recent range, plus derived valuation ratios where computable. |\n| `get_kpi_comparison` | Compare one or more canonical KPIs across companies on a shared, aligned period axis (annual or quarterly). Each cell carries the native + PLN-converted value with its FX basis, the evidence link (fact id + validation status), and server-computed QoQ\u002FYoY deltas; gaps and unconvertible currencies are typed flags, never silent. Works for a single company too (the periods×deltas view). Decision support only. |\n| `get_sector_percentiles` | Where one company stands against its tracked sector peers: rank-based percentiles for the level-0 market ratios (P\u002FE, P\u002FBV, EV\u002FEBITDA, dividend yield, FCF yield) and selected canonical KPIs, computed from confirmed data only. Always returns the peer count N and flags thin sets (N \u003C 4); a company with no sector returns a typed empty reason. Decision support only. |\n| `list_valuation_runs` | One company's append-only comparative-valuation run history (ADR 0089): each stored run's method (P\u002FE, EV\u002FEBITDA, or P\u002FBV multiple), per-share fair-value range (low\u002Fbase\u002Fhigh), input signature, confidence grade, and data-as-of date, newest first. The compute-and-persist path is the act-tier compute_comparative_valuation. Decision support only. |\n| `get_ownership_overview` | One company's shareholder structure: significant holders, holder types, and free float, with change history. |\n| `get_insider_overview` | One company's insider-transaction timeline, management holdings, and rolling net-direction aggregates. |\n| `list_short_positions` | One company's KNF short-selling register: active positions, change history, aggregate net short %, and the 30-day change. |\n| `get_analyst_recommendations` | One company's recorded analyst recommendations and price targets over time. Decision support only — never an investment recommendation. |\n| `get_company_health` | One company's deterministic financial-health scores (Piotroski F, Altman Z\") per fiscal period, computed from confirmed facts. |\n| `get_red_flags` | One company's active red flags (auditor concerns, short spikes, contradictions) plus the acknowledged history. |\n| `get_report_documents_view` | One company's stored report documents, each tagged with its fiscal period and whether it is that period's canonical report. |\n| `list_report_diff_candidates` | Comparable pairs of successive financial statements for one company — the (older, newer) document pairs get_report_diff can diff. |\n| `get_report_diff` | The section-level text diff between two report documents (discover the pair via list_report_diff_candidates). |\n| `list_notebook_entries` | One company's research notes, each preserving the origin (report\u002Farticle) it traces back to. |\n| `list_management_claims` | One company's tracked management claims (guidance\u002Fpromises), with their verification period and verdict. |\n| `list_report_expectations` | Pre-report expectations the user recorded (optionally scoped to one company), with any resolution outcome. |\n| `list_decision_entries` | The decision journal (optionally scoped to one company): recorded decisions and their rationale. |\n| `list_research_questions` | Open and answered research questions across the workspace, with their scope and status. |\n| `list_report_season` | The upcoming report-season calendar: which tracked companies report when, with preparation state. |\n| `list_attention_events` | Fired attention events (newest first), optionally scoped to one company and optionally including dismissed ones. |\n| `get_latest_morning_briefing` | The most recently composed morning briefing (its structured item list plus any narrative), or null when none exists yet. |\n| `list_autopilot_runs` | Recent autopilot runs (optionally scoped to one company): what the autonomous pipeline produced and its notification state. |\n| `get_autopilot_run` | One autopilot run's full composed result (discover run ids via list_autopilot_runs). |\n| `list_quality_frameworks` | The quality-scorecard framework catalog: every framework and its criteria (the rubric get_quality_assessment scores against). |\n| `list_alert_rules` | The alert-rule catalog: every configured rule (trigger, scope, enabled state). Fired events are read via list_attention_events. |\n| `list_flagged_extraction_outcomes` | One company's extraction-coverage gaps: the fiscal periods where the deterministic pipeline emitted nothing (a flagged\u002Ffailed outcome). Complements list_flagged_fact_provenance (flagged facts that DID emit) — the coverage-gap review surface. |\n| `list_unclassified_filings` | Official filings (ESPI\u002FEBI) the deterministic rule classifier could not place — the explicit unclassified bucket, never guessed at. Optionally scoped to one company. Classify one with classify_filing. |\n| `get_report_tagged_fact_coverage` | How much of one company's tagged filings reached Fundamentals, and where the rest went: comparatives, dimensional breakdowns, note-level figures, positions awaiting a name, and conflicts. Every captured number is either projected or has a stated reason it is not. |\n| `get_pipeline_reextraction_progress` | Progress of one company's latest re-extraction batch (re-armed runs, how many have terminated, how many failed). A null batch means the company never ran one. |\n| `list_pending_kpi_ingests` | List claimable KPI ingest runs (discovered\u002Fsource_captured\u002Fextracting\u002Fvalidation_failed), newest first, keyset-paginated (limit ≤ 50, default 20). |\n| `get_kpi_ingest_context` | Everything one report's extraction needs, within hard budgets (≤256 KiB): run status, document metadata, the derived-period hint, the expected+minted KPI catalog, validator-equivalent plausibility evidence per slot, profile doctrine and repair-manifest access. Sections (catalog\u002Fplausibility\u002Fmanifest) paginate via cursors; the manifest is served only via section calls. Pure read. |\n| `get_kpi_ingest_document` | Chunked bytes (offset\u002Flength ≤ 256 KiB, base64) from the run's content-addressed source blob, verified against the frozen sourceContentHash — the portable document delivery channel. Available once the source is captured. Pure read. |\n| `get_kpi_ingest_status` | Full status of one KPI ingest run (state, context, lease, expected KPIs, progress). Pure read — never touches the lease. |\n\n**Act tools** — dispatchable only with *Settings → MCP server → Allow write tools* on (64):\n\n| Tool | What it does |\n| --- | --- |\n| `create_notebook_entry` | Create a research note for a company. Every note must carry a non-empty `origins` array tracing it to a report\u002Farticle (provenance). References the company by its internal id (from list_companies). |\n| `update_notebook_entry` | Update an existing research note (by id): title\u002Fbody\u002Ftags\u002Fkind. The note keeps its recorded origins. |\n| `create_management_claim` | Record a tracked management claim (guidance\u002Fpromise). Must anchor to a `sourceEvidenceId` (the report it was made in). |\n| `update_management_claim` | Update a tracked management claim (by id). Must carry its `sourceEvidenceId` provenance. |\n| `set_claim_verdict` | Record a verification verdict on a management claim (optionally linking the verifying fact). |\n| `create_financial_fact` | Low-level single-fact repair write (ADR 0098) — never report ingestion; once the KPI ingest run-workflow tools are present on this server, use them for ingesting reports. Records a financial fact for a company\u002Fperiod\u002Fmetric. Must carry a non-blank `sourceDocumentRef` citation (`attribution` is the total\u002Fowners_of_parent\u002Fnci slot dimension, never a citation carrier). Decision support only. MCP writes are stamped honestly: `source_tier='agent'` provenance, `extraction_method='mcp_agent'`, `validation_status='unreviewed'` — never masquerading as a manual entry. |\n| `update_financial_fact` | Low-level single-fact repair write (ADR 0098) — never report ingestion. Updates a stored financial fact (by id). Must carry its non-blank `sourceDocumentRef` citation. Stamps `source_tier='agent'` provenance (honest takeover — never masquerading as manual), even on a previously-manual fact. |\n| `capture_report_document` | Register and fetch a report document by URL for a company — the document an agent read before citing facts from it (the fact-write tools need its returned documentId). Always registers under source_type \"user_url\"; passing a sourceType is refused (unknown field). Gated: https only, private\u002Floopback\u002Flink-local network addresses refused (including via redirect), content-type restricted to application\u002Fpdf \\| text\u002Fhtml \\| application\u002Fxhtml+xml — an octet-stream or missing header defers to a strict byte sniff of the fetched body instead of an outright refusal — 30 MiB size cap. Idempotent on (companyId, url); never downgrades an already-fetched document — a call against a document whose stored file still matches its hash returns that document unchanged (no refetch), and a previously-failed row whose file matches is healed back to fetched. Returns the document's id, local path, and fetch success\u002Ferror. |\n| `record_financial_facts` | Low-level batch fact write (ADR 0098). If `start_kpi_ingest` is absent from this server's tools, this is the only supported temporary report-ingest route; once the run-workflow tools are present, use them for ingestion and this tool ONLY for manual repair. Records a batch (1-100) of financial facts for one company\u002Fperiod from a document an agent read, with per-fact citations. Ensures the fiscal period, resolves each metricKey against the KPI catalog, judges the set against stored history and same-period accounting identities, and commits every plausible fact under the `agent` source tier (ADR 0093) — never overwriting an issuer-held or manual fact; a disagreement is reported as `divergent`, never silently resolved. Use `dataQuality: \"preliminary\"` for issuer pre-report releases (e.g. GPW wstępne wyniki) — record CUMULATIVE columns only (H1\u002F9M\u002FFY), never discrete-quarter columns. Decision support only. |\n| `set_qualitative_verdicts` | Record agent-authored qualitative criterion verdicts for one framework+company as one immutable snapshot. Every result must carry `citationsJson`: a serialized non-empty array of typed evidence refs `[{\"evidenceType\":\"notebook_entry\",\"evidenceId\":\"\u003Cid>\"}]` (types: feed_item \\| notebook_entry \\| claim \\| company_event \\| research_question \\| company_signal \\| decision_entry); every ref must resolve to an existing row or the whole batch is refused. Decision support only — never an investment recommendation. |\n| `create_research_question` | Open a research question scoped to a company\u002Fwatchlist\u002Fsector. |\n| `update_research_question` | Update a research question (title\u002Fbody\u002Fstatus) by id. |\n| `create_evidence_link` | Link two research-graph entities (note\u002Fclaim\u002Ffact\u002Fdocument…) with a typed relation. |\n| `create_research_reminder` | Create a personal follow-up reminder scoped to a company\u002Fwatchlist\u002Fsector. |\n| `update_research_reminder` | Update a research reminder (status\u002Fdue\u002Fsnooze) by id. |\n| `create_decision_entry` | Append an immutable decision-journal entry for a company (rationale + decided-at). |\n| `create_report_expectation` | Record pre-report expectations for a company's upcoming report event (stance + optional metrics). |\n| `update_report_expectation` | Update a company's report expectation (stance\u002Fmetrics) by its event key. |\n| `record_expectation_resolution` | Resolve a report expectation after the report lands (resolution note). |\n| `create_company_event` | Add a calendar event (dividend\u002Fmeeting\u002Freport date) for a company. |\n| `create_kpi_definition` | Add a KPI\u002Ffinancial-concept definition to the metric catalog. |\n| `create_kpi_relevance` | Mark a KPI definition relevant to a company (scorecard editor). |\n| `update_kpi_relevance` | Update a company's KPI-relevance row (status\u002Frank) by id. |\n| `create_quality_framework` | Create a quality-scorecard framework. |\n| `update_quality_framework` | Update a quality framework (name\u002Fdescription) by id. |\n| `create_framework_criterion` | Add a criterion to a quality framework. |\n| `update_framework_criterion` | Update a framework criterion by id. |\n| `create_alert_rule` | Create an alert rule (trigger + scope). Fired events surface via list_attention_events. |\n| `update_alert_rule` | Update an alert rule (trigger\u002Fscope\u002Fenabled) by id. |\n| `create_company` | Track a new company (exchange + ticker + display name). On GPW this also enqueues a quote backfill. |\n| `create_watchlist` | Create a watchlist. |\n| `add_company_to_watchlist` | Add a company to a watchlist (by their internal ids). |\n| `remove_company_from_watchlist` | Remove a company from a watchlist (by their internal ids). |\n| `update_feed_item_state` | Set a feed item's read\u002Fsaved flags (by id). |\n| `mark_report_prepared` | Mark a company's upcoming report event as prepared. |\n| `mark_report_processed` | Mark a company's report event as processed (optionally linking the report document). |\n| `mark_research_scope_reviewed` | Set a 'reviewed' checkpoint for a research scope (optionally cascading to its companies). |\n| `confirm_company_signal` | Confirm a proposed filing signal (by id). |\n| `reject_company_signal` | Reject a proposed filing signal (by id). |\n| `classify_filing` | Classify an unclassified official filing (from list_unclassified_filings) into a confirmed signal. Takes `feedItemId` (the evidence anchor) and a `category` key from the seeded taxonomy. Rejects an unknown category, a non-official item, or an already-classified filing. |\n| `confirm_derived_event` | Confirm or reject a proposed derived calendar event (`action`: confirm\\|reject). |\n| `acknowledge_red_flag` | Acknowledge an active red flag (by id). |\n| `set_ownership_holder_type` | Relabel a shareholder's holder type for a company; returns the recomputed ownership overview. |\n| `mark_attention_event_seen` | Mark an attention event as seen (by id). |\n| `dismiss_attention_event` | Dismiss an attention event (by id). |\n| `set_autopilot_run_notification_state` | Set an autopilot run's notification state (unread\\|read\\|dismissed). |\n| `evaluate_framework` | Run the deterministic quantitative scorecard engine for a framework+company and persist the evaluation. |\n| `compute_comparative_valuation` | Compute the level-1 comparative valuation for one company (peer-multiple implied fair-value ranges for P\u002FE, EV\u002FEBITDA, and P\u002FBV, method-convergence spread, and a deterministic confidence grade) and append a valuation_runs row per method whose input signature changed. Read the history via list_valuation_runs. Decision support only — never buy\u002Fsell\u002Fhold language. |\n| `set_alert_rule_enabled` | Enable\u002Fdisable an alert rule (by id). |\n| `trigger_autopilot_run` | Trigger an autopilot run over one company's report document (fail-fast on unknown ids); enqueues the durable pipeline. |\n| `generate_morning_briefing` | Enqueue composition of a fresh morning briefing (read the result via get_latest_morning_briefing). |\n| `refresh_sources` | Run a source-refresh sweep across all enabled adapters (`trigger`: manual \\| scheduler). |\n| `refresh_source` | Run a refresh for one source adapter (by `adapterId`; optional `trigger`, `date`). |\n| `run_aggregator_fundamentals_pull` | Run the aggregator fundamentals pull across tracked companies. |\n| `backfill_company_history` | Run an on-track history backfill for one company (`companyId`); progress via get_backfill_progress. |\n| `run_structured_extraction` | Run the deterministic structured-first extraction pipeline over one company report+period (`mode`: autopilot \\| assist). |\n| `rerun_extraction_outcome` | Re-run the deterministic pipeline for a recorded extraction outcome slot (`outcomeId`). |\n| `run_pipeline_reextraction` | Re-arm one company's landed ESEF runs whose stored pipeline version is stale, so the current extractor reads their filings again. Queues a durable batch; poll `get_pipeline_reextraction_progress`. |\n| `start_kpi_ingest` | Start or resume a KPI ingest run (ADR 0099). Fresh: documentId + profileId (+ optional scope\u002FdataQuality\u002Fperiod) creates the run, claims the lease, pins the source bytes, and enters extraction once context is complete. Resume: runId re-claims idempotently (the explicit keepalive) and attaches missing context set-once. Provenance is the run pipeline itself; no citation carrier here. |\n| `stage_kpi_observations` | Stage the COMPLETE revision snapshot of extracted observations (1..100, with citations) plus the REQUIRED missingReasons declaration ({} = explicitly none), written in the same transaction. A repair resends every retained observation. Requires the caller's live lease. Provenance is the run pipeline itself. |\n| `propose_kpi_definition` | Mint (or reuse) a company-scoped, origin=agent KPI catalog entry for a disclosed number the canon has no key for (ADR 0101). Guard order: this company's own minted entry is returned as-is (created: false); a curated kpi_aliases synonym refuses with a typed synonym_redirect naming the canonical key and definitionId; an exact shared-canon key returns the canonical definition (created: false, never a company shadow); only a genuinely new key mints — never fuzzy matching. Page the full catalog (get_kpi_ingest_context) before proposing. Requires the caller's live lease. |\n| `validate_kpi_ingest` | Validate one staged revision synchronously (generation-pinned). Returns the FULL manifest — a failed manifest is the typed repair report; a raced loser gets outcome=superseded with the current run tuple. |\n| `commit_kpi_ingest` | Atomically commit a ready manifest (runId + manifestHash + revision) and return the immutable receipt. Idempotent: replaying a committed tuple returns the stored receipt verbatim; a stale tuple is a typed conflict. |\n| `cancel_kpi_ingest` | Cancel a KPI ingest run in any pre-commit state (releases its lease). Refuses `committing` and terminal states. |\n\n\u003C!-- END GENERATED MCP CATALOG -->\n",{"name":5,"description":7},"master","59d8936cc078fab7337ebe282e6155627d3ab47a",".claude\u002Fskills\u002Fbrawler-mcp",0,"https:\u002F\u002Fgithub.com\u002Fwbednarczyk\u002Fbrawler","https:\u002F\u002Fgithub.com\u002Fwbednarczyk","2026-11-01 08:56:22",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add wbednarczyk\u002Fbrawler --skill brawler-mcp",{"tool":37,"command":38},"bunx","bunx skills add wbednarczyk\u002Fbrawler --skill brawler-mcp",{"tool":40,"command":41},"pnpm","pnpm dlx skills add wbednarczyk\u002Fbrawler --skill brawler-mcp","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fwbednarczyk\u002Fbrawler\u002Fblob\u002Fmaster\u002F.claude\u002Fskills\u002Fbrawler-mcp\u002FSKILL.md",true,[],[46,53,60,67,74,81],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":50,"categories":51,"keywords":52,"publishedAt":19},"01M753K8XP1MXGASEJEC1595HH","ship-pr","Use when a change is implemented and needs to land as a PR — branching, evidence, commits, PR creation, CI watching, or when CI jobs fail and you must decide rerun-vs-fix. Also use when a \"green\" claim is about to be made.","https:\u002F\u002Fgithub.com\u002Fwbednarczyk\u002Fbrawler\u002Fblob\u002Fmaster\u002F.claude\u002Fskills\u002Fship-pr\u002FSKILL.md",[],[],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M753K3KKKY24G2YJAEB6FMK2","repoctx","Use repoctx for fast, indexed code navigation in this repo. Beats grep\u002Ffind\u002Fcat on structural questions about symbols, definitions, the call graph (who-calls \u002F callees \u002F callgraph), and surrounding source.","https:\u002F\u002Fgithub.com\u002Fwbednarczyk\u002Fbrawler\u002Fblob\u002Fmaster\u002F.claude\u002Fskills\u002Frepoctx\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M753K09Y1KY1AZ7CQ5EW2MF4","packaging","Build and smoke-test Brawler release artifacts — portable Windows .exe from Linux\u002FWSL via cargo-xwin, Linux .deb\u002F.rpm\u002FAppImage, native Windows fallback. Use for packaging, cross-build verification, or Windows hands-on testing paths.","https:\u002F\u002Fgithub.com\u002Fwbednarczyk\u002Fbrawler\u002Fblob\u002Fmaster\u002F.claude\u002Fskills\u002Fpackaging\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M753JWMZ4XEPRW4K6HYJ2ATB","investing-domain","Domain lens for designing\u002Fbuilding Brawler — how an equity investor actually reads companies (fundamental analysis, quality assessment, GPW specifics). Load when designing UI hierarchies, panels, journeys, or analytics for company data.","https:\u002F\u002Fgithub.com\u002Fwbednarczyk\u002Fbrawler\u002Fblob\u002Fmaster\u002F.claude\u002Fskills\u002Finvesting-domain\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M753JSV4X5AXGYDASYZJVP77","guardrail-harvest","Convert a flagged defect's class into a durable guardrail — a precise automated gate or a documented rule + checklist line — in the same change. Use whenever the user, a review, or a failing gate flags a defect.","https:\u002F\u002Fgithub.com\u002Fwbednarczyk\u002Fbrawler\u002Fblob\u002Fmaster\u002F.claude\u002Fskills\u002Fguardrail-harvest\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M753JF37R868TS9QD6JBJHT6","brawler-design","Use before ANY Brawler UI work — writing\u002Fchanging JSX, drawing a mockup, styleguide or visual-language work, choosing colors\u002Ftypography\u002Flabels, designing a panel or empty state. Binds the generic design skills to Brawler's normative design language (ADR 0104) and authoring contract.","https:\u002F\u002Fgithub.com\u002Fwbednarczyk\u002Fbrawler\u002Fblob\u002Fmaster\u002F.claude\u002Fskills\u002Fbrawler-design\u002FSKILL.md",[],[]]