Notion Docs

Brain — Notion Knowledge Base

Overview

The Knowledge Base is the "brain" of your organization — the semantic layer where strategy, priorities, metrics, and decisions live. The code repo is the "limbs" (execution). Docs in the codebase are "muscle memory" (how the limbs work).

Source of truth for: Active Context, strategy docs, billing, positioning, pricing model, platform strategy.

NOT for: Code docs (live in repo), legal docs (GDrive), spreadsheets, team artifacts.

Architecture

Hierarchical pages under a Brain root page. Five sections act as typed containers:

Brain (root page)
  Active Context          <- cross-cutting dashboard, stays at root
  Konban                  <- database, managed by konban skill
  Strategy/               <- why we build, how we position
  Operations/             <- how the business runs day-to-day
  Product/                <- what we build, platform specs
  Research/               <- external knowledge, read-mostly
  Archive/                <- superseded content (hidden from default index)

Pages are found by title regardless of which section they're in. find_page() searches Brain root and all sections automatically.

Metadata callout format (top of each page):

Domain: Strategy | Status: Current | Updated: 2026-02-21
Summary: One-liner description

Page ID: BRAIN_PAGE_ID in your env file (see Credentials below)

Section Routing Table

When creating new pages, route them to the right section:

Always set an icon when creating pages: --icon "🔬" on create, or meta "Title" --icon "🔬" after the fact. Pick an emoji that reflects the page's content, not its section.

Cross-cutting dashboards (Active Context) stay at root — they don't belong to one section.

Helper Script

python3 <skill-dir>/notion-docs/notion-api.py <command> [args]

Commands

# Hierarchical semantic map (THE starting point)
python3 <script> index
python3 <script> index --all    # include Archive section

# Read full page as markdown (works regardless of section)
python3 <script> read "Active Context"
python3 <script> read "Billing & Invoicing"  # finds it under Operations/
python3 <script> read "Title" --raw  # skip metadata header

# Create new page under a section (always include --icon)
python3 <script> create "New Doc" \
  --parent "Research" --icon "🔬" --domain Research --summary "One-liner" <<'NOTIONEOF'
# Content here
NOTIONEOF

# Create at Brain root (no --parent)
python3 <script> create "Cross-Cutting Doc" \
  --icon "🎯" --domain Strategy --summary "..." <<'NOTIONEOF'
# Content here
NOTIONEOF

# Move page between sections (copy-and-archive — non-destructive)
python3 <script> move "Page Title" --to "Operations"
python3 <script> move "Page Title" --to "root"  # back to Brain root

# Update page content — FULL REWRITE
# ABORTS if page has open comments. Use --force to override.
python3 <script> update "Title" <<'NOTIONEOF'
...full updated markdown here...
NOTIONEOF

# Patch a SINGLE SECTION (fast — only touches that section's blocks)
python3 <script> patch "Title" \
  --section "Section Heading" <<'NOTIONEOF'
## Section Heading
- Updated content
NOTIONEOF

# Update metadata only (domain, summary, status, name, icon)
python3 <script> meta "Title" --summary "Updated summary"
python3 <script> meta "Old Name" --name "New Name"
python3 <script> meta "Title" --icon "🔬"

# Search (includes pages in all sections)
python3 <script> search "pricing"

# Comments
python3 <script> comments "Title"
python3 <script> comment "Title" "Reply text" -d <discussion_id>
python3 <script> comment "Title" "New comment"

# Archive (sets status to Archived in metadata)
python3 <script> archive "Old Doc"

Common Mistakes (from real sessions)

Run index before guessing page titles:

# WRONG: read "Pricing Strategy"   (guessing — page might be named differently)
# RIGHT: first run index, then use the exact title shown
python3 <script> index
python3 <script> read "SaaS Pricing Model"

Run read --raw before using patch to see actual section headings:

# WRONG: patch "Active Context" --section "Current Sprint"  (guessing section name)
# RIGHT: read first, then patch with the exact heading
python3 <script> read "Active Context" --raw
python3 <script> patch "Active Context" \
  --section "Current Focus" <<'NOTIONEOF'
## Current Focus
- Updated content
NOTIONEOF

No --content flag on create or update. Use stdin (heredoc) or --file:

# WRONG: create "Doc" --content "Some text"
# WRONG: update "Doc" --content "New text"
# RIGHT (stdin):
python3 <script> create "Doc" --parent "Research" --icon "🔬" <<'NOTIONEOF'
Content here
NOTIONEOF
# RIGHT (file):
python3 <script> update "Doc" --file /tmp/doc.md

Move Command Details

move uses copy-and-archive because the Notion API doesn't support reparenting pages. It:

1. Creates a new page under the target section
2. Copies all blocks from the old page
3. Archives (soft-deletes) the old page

Content is preserved. Comments on the old page are lost (they stay on the archived original). Page ID changes — but all lookups are by title, so this is transparent.

Comment-Driven Editing Workflow

Team members can comment on Notion docs to give feedback. Claude reads, addresses, and replies.

Preferred: Pull-Edit-Push with patch (lean on tokens):

# 1. Pull doc + comments
python3 <script> read "Doc Title" --raw > /tmp/working-copy.md
python3 <script> comments "Doc Title"

# 2. Edit locally with the Edit tool — repeat as needed (~10 tokens each)

# 3. Push back SECTION BY SECTION + reply to comments
python3 <script> patch "Doc Title" \
  --section "Section Name" --file /tmp/section-extract.md

# 4. Reply to addressed comments
python3 <script> comment "Doc Title" \
  "Addressed: updated X per feedback" -d <discussion_id>

Notion API limitation: Cannot resolve comments programmatically. Reply with what was changed; the user resolves manually in Notion.

Credentials

Stored at ~/.claude/secrets/notion.env (auto-loaded by helper):

• NOTION_TOKEN — Internal integration token
• BRAIN_PAGE_ID — Root page ID (parent of all knowledge base pages). Also accepts KH_BRAIN_PAGE_ID for backward compatibility.

Metadata Fields

Typical Session Workflow

Startup

# Step 1: Load hierarchical semantic map
python3 <script> index

# Step 2: Load Active Context (cross-cutting priorities dashboard)
python3 <script> read "Active Context"

During Session

# Read any page — find_page searches all sections automatically
python3 <script> read "Billing & Invoicing"
python3 <script> search "pricing"

Session Close

python3 <script> update "Active Context" <<'NOTIONEOF'
...full updated markdown...
NOTIONEOF

CRITICAL: update Destroys Comments

update does delete-all + rewrite. This NUKES all inline Notion comments on the page.

Decision tree:

1. Page has open comments? -> Use patch (one section at a time)
2. Page has no comments + changing 1-2 sections? -> Use patch
3. Page has no comments + rewriting most of the doc? -> update is fine

Performance Notes

Section matching: --section matches the exact heading text (e.g., "Recent Notes", not "## Recent Notes").

Content Format

Pages store content as Notion blocks, converted from/to markdown. Supported:

• Headings (H1-H3), paragraphs, bullet/numbered lists
• Bold, italic, strikethrough, code, links
• Code blocks, blockquotes, horizontal rules, tables