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

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:

   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.