Notion team knowledge base

--- name: notion-docs description: Hierarchical Knowledge Base via Notion API. The "brain" of your organization : strategy, priorities, decisions, metrics. Use when reading/updating Active Context, strategy docs, or operational knowledge. Triggers on "active context", "brain", "knowledge base", "strategy doc". --- # 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:** BRAINPAGEID in your env file (see Credentials below) ### Section Routing Table When creating new pages, route them to the right section: | Signal | Section | Naming | Icon | |--------|---------|--------|------| | Company direction, positioning, "why" | Strategy | Descriptive title | Pick a meaningful emoji | | Day-to-day execution, billing, playbooks | Operations | Descriptive title | Pick a meaningful emoji | | Feature specs, platform standards | Product | Descriptive title | Pick a meaningful emoji | | External research, market/legal analysis | Research | Research: [Topic] prefix | Pick a meaningful emoji | | Superseded content | Archive | Keep original name | Keep original icon | **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 `bash python3 <skill-dir>/notion-docs/notion-api.py <command> [args] ` ### Commands `bash # 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:** `bash # 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: `bash # 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: `bash # 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): `bash # 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 - BRAINPAGEID : Root page ID (parent of all knowledge base pages). Also accepts KHBRAINPAGE_ID for backward compatibility. ## Metadata Fields | Field | Values | |-------|--------| | **Domain** | Free text : use what fits your organization (e.g., Strategy, Product, Research, Operations) | | **Status** | Current, Draft, Archived | | **Updated** | ISO date (auto-set on update) | | **Summary** | 1-2 sentence description : this IS the semantic map | ## Typical Session Workflow ### Startup `bash # 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 `bash # Read any page : find_page searches all sections automatically python3 <script> read "Billing & Invoicing" python3 <script> search "pricing" ` ### Session Close `bash 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 | Operation | Doc size | Approx time | When to use | |-----------|----------|-------------|-------------| | update | Small (20-30 blocks) | ~10-15s | Small docs with NO comments | | update | Large (100+ blocks) | ~45-60s | Only when rewriting the whole doc AND no comments | | patch | Any section (5-15 blocks) | ~5-15s | **Preferred** : preserves comments, faster | | move | Any page | ~3-30s | Copy-and-archive. Time scales with block count | **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