# Notion Cockpit

> Build an operations dashboard ("cockpit") page in Notion with hero, decision queue, KPI tiles, filtered section views, and a collapsed agent stream. Filters reference helper formulas on the source DBs.

- Skill: `chiragg-ds/notion-cockpit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add chiragg-ds/notion-cockpit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chiragg-ds/notion-cockpit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: chiragg-ds (https://skillmd.com/u/chiragg-ds)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chiragg-ds/notion-cockpit

---


# notion-cockpit

Render a structured Operations Dashboard onto an existing Notion page from a YAML layout spec. The cockpit pattern: every filter on the page resolves to a single-checkbox lookup against a helper formula on the source DB — making the dashboard fast for the user to wire up and self-documenting.

## Pattern

The cockpit has 4 stacked sections:

1. **Hero callout** — brand name + tagline
2. **Decision Queue** — N cards. Each = "things waiting for a decision right now" (filtered DB view).
3. **KPI tiles** — 4 columns, each a Count-all of a filtered view (helps the user see "how many X?")
4. **Active sections** — board / table / list views of currently-active rows
5. **Agent Stream** (optional) — collapsed toggle with a Weekly Status Log view

The Notion API **cannot create linked DB views**. Instead, the builder writes orange "WIRE HERE" callouts naming the DB, filter, sort, and group-by — which the user follows in the Notion UI (~10 minutes for a full cockpit).

## Prerequisites

- Helper formulas already added to source DBs (use `notion-helper-formulas` first)
- Target page ID where the cockpit should render

## Layout spec format

```yaml
brand_name: "Studio Nuvah"
tagline: "Decision queue, KPIs, and active project board."

decision_queue:
  - label: Approvals waiting
    db: Deliverables
    filter: "Needs Client Approval = checked"
    sort: "Feedback Due Date asc"

kpis:
  - icon: "🏗️"
    label: Active Projects
    db: Projects
    filter: "Is Active = checked"

sections:
  - heading: Active Projects
    db: Projects
    view: Board
    group_by: Project Stage
    filter: "Is Active = checked"
    sort: "Start Date asc"

agent_stream: true
```

## Steps

1. Confirm: helper formulas exist on referenced DBs (check `SCHEMA-REFERENCE.md`). If not, invoke `notion-helper-formulas` first.
2. Build / receive the layout spec.
3. Run:
   ```python
   from notion_os_toolkit import auth, client, cockpit_builder
   import yaml
   nc = client.NotionClient(auth.load_token())
   spec = yaml.safe_load(open("cockpit-spec.yaml"))
   cockpit_builder.render_cockpit(nc, "<page_id>", spec, wipe_existing=True)
   ```
4. Tell the user to follow the WIRE HERE callouts in Notion UI (estimate ~10 min for typical 9-view cockpit).

## Input/Output contract

**Input:** target page ID + layout spec dict
**Output:** rendered blocks on the page; count printed

## When NOT to use

- If the dashboard is for one specific person (role dashboard), tailor instead — cockpit is for the operational team.
- If the user wants automatic recomputation of KPI numbers — that's already what Notion's "Count all" calculation does on the linked view.