report-skills

name	report-skills
description	Shared setup and rules for the report-skills bundle (report-publisher, client-reporter, proposal-tracker, deck-publisher, report-designer). Loaded by the individual skills for the common ReportRoom MCP publish flow, account bootstrap, and safety gates. Not invoked directly — pick the specific skill for the job.

Report Skills — shared flow and rules

All five skills publish through the ReportRoom MCP server. This file holds what they share; each skill's SKILL.md holds only what differs.

The publish flow (every skill follows this)

1. Check access. Call account_status. If no account/API key exists, call create_account — it issues a key in-flow; never ask the user to leave the conversation to sign up. Note: publishing is blocked until the user clicks the email-verification link (create_account sends it), and unverified accounts serve from a preview/noindex domain — tell the user this upfront so the first publish isn't a surprise.
2. Fetch the design language. Call get_design_system and follow it exactly when authoring. The design system supplies the taste; you supply content and assembly. Do not improvise your own CSS framework.
3. Author a self-contained HTML document. Semantic HTML, responsive, dark-mode aware, no external dependencies beyond what the design system allows.
4. Lint before publish. Call lint_document and fix every issue it reports. Never skip this step.
5. Approval gate. Show the user: title, a one-paragraph summary of what the page contains, section list, and who it's for. Wait for explicit approval before calling publish on anything client-facing. For personal/internal shares the user may pre-approve ("just publish it"). Also tell them every published page carries a small "Published with ReportRoom" footer credit (see below) — clients and prospects will see it.
6. Publish. Call publish. Return the live URL prominently. Handle the two common failure modes instead of retrying blind:
   • cap_reached — the account is at its live-document limit (free = 10, pro = 100; Team/Business = unlimited). The error carries the live-doc list. Offer the user a choice: retire an old document to make room (publish with replace_slug: "<old-slug>" in the same call, or unpublish it first), or upgrade the plan. Never silently drop the new page.
   • Not verified / FORBIDDEN — publishing is blocked until email verification (see step 1). A FORBIDDEN also means a team viewer role can't publish (see workspaces below) — surface it, don't loop.
7. Close the loop. Tell the user view analytics are attached: they can ask any time "how is my report doing?" (→ get_analytics, which returns 7-day views by day plus a summary). For tracked deliverables, offer to check back. Do not promise per-viewer or per-section detail — current analytics are aggregate view counts.

Other tools you have

Beyond the core flow, the ReportRoom MCP exposes:

• list_documents — the account's live documents, most recent first. Use to keep recurring reports consistent, find a slug to update, or show what's using up the plan's slots.
• unpublish / republish — retire a live document (its URL returns 410 Gone, the plan slot frees up) or bring it back. Both idempotent. Use for expired proposals, superseded client reports, or freeing a slot at the cap.
• set_handle — rename the publishing subdomain (<handle>.reportroom.io/<slug>); existing docs move and old links redirect. This is the lightweight branding lever for everyone.
• attach_domain — attach a custom domain (Team/Business). Returns the DNS records the human must create at their registrar (a CNAME plus ownership/certificate TXT records) and streams progress as provisioning advances. Certificate issuance only completes after they add the records, so hand the records over and tell them to come back — don't wait on it. account_status and list_documents report the active custom domain once live. This is the real "branded page" lever for agencies.
• Team workspaces — account_status returns org_kind (personal/team) and the caller's role. In a team workspace, visibility: "team" on publish makes a document viewable only by signed-in org members (Team/Business plans); viewers cannot publish and will get a FORBIDDEN.

Data rooms (Business plan only)

When the user needs access control and per-person tracking — a fundraise, a diligence process, a gated proposal — a data room beats a published document. A room is a named, access-controlled bundle of documents at one URL, shared with identified viewers.

Gate: Business plan only (not Free/Pro/Team) and the caller must be the org owner or an admin. Anything else returns a clear error — relay it and offer the plain-document path instead of retrying. Limits: 10 live rooms per org, 200 viewers per room.

The flow, in order:

1. create_data_room — name it, pick access_mode (public | email (magic-link, the default) | passcode | allowlist), and optionally settings: nda_text, expires_at, allow_download, watermark. allow_download and watermark are accepted and stored but not yet enforced at serve time (Phase 2) — never tell the user a room is watermarked or download-locked. nda_text and expires_at are fully enforced.
2. add_documents_to_room — pass document_ids in display order. This replaces the whole set, so send the full ordered list every time. Documents stay first-class and standalone; adding one never unpublishes or moves it.
3. set_room_access — change access mode, rotate the passcode (string sets, null clears), or update NDA/expiry/download/watermark later.
4. grant_room_access — per viewer, by email. Returns a single-use invite link once and does not email it. Hand it to the user to send; it is never retrievable again (only a hash is stored), so if it's lost, re-grant to reissue. Never send it to the recipient yourself without the user's explicit go-ahead.
5. list_room_viewers — the roster with verification/NDA/revocation state. Never exposes invite tokens.
6. revoke_room_access — instantly ends that viewer's sessions.

get_room_analytics is different from get_analytics. It returns per-viewer, per-document opens, total events, and dwell — so you can say "the lead spent time on pricing and skipped the deck" and suggest a follow-up. Published documents outside a room remain aggregate view counts only. Don't mix the two up when telling the user what you can see.

Safety rules (all skills, non-negotiable)

• Published pages are public, search-indexable URLs. A normal published report/deck is world-readable and can be indexed by search engines — the slug is obfuscation, not protection. Before publishing, scan the content for secrets, API keys, internal hostnames, personal data of third parties, or anything marked confidential. If found, stop and ask. For genuinely internal material in a team workspace, visibility: "team" restricts viewing to signed-in org members (and serves noindex); for gating to named outside people, only a data room does that — a normal link cannot.
• Every page shows a "Published with ReportRoom" footer credit. It's discreet but always present on both reports and decks, on every plan. Disclose it before publishing anything client-facing so it isn't a surprise on the recipient's screen.
• Never fabricate data, metrics, or client results in a report. If a number is estimated, label it.
• Never publish without the approval gate for client-facing content, even if the user seems in a hurry.
• If lint_document or publish fails, show the actual error and fix the document — do not silently retry with degraded content.

Which skill for which job

The user wants	Use
Share research/analysis they just produced	report-publisher
A recurring, branded deliverable for a client	client-reporter
A proposal/offer where knowing "did they open it" matters	proposal-tracker
Slides, not a document	deck-publisher
An existing page made better-looking	report-designer