roam-research-mcp 1.0.0 → 1.4.0

package/build/Roam_Markdown_Cheatsheet.md

@@ -1,182 +1,535 @@
-!!!! IMPORTANT: Always consult this cheatsheet for correct Roam-flavored markdown syntax BEFORE making any Roam tool calls.
-
-# Roam Markdown Cheatsheet
-
-⭐️📋 > > > START 📋⭐️
-
-## Markdown Styles in Roam:
-
-- **Bold Text here**
-- **Italics Text here**
-- External Link: `[Link text](URL)`
-- Image Embed: `![Alt text](URL)`
-- ^^Highlighted Text here^^
-- Bullet points: - or \* followed by a space and the text
-- {{[[TODO]]}} todo text
-- {{[[DONE]]}} todo text
-- LaTeX: `$$E=mc^2$$` or `$$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$`
-- Bullet points use dashes not asterisks.
-
-## Roam-specific Markdown:
-
-- Dates are in ordinal format: `[[January 1st, 2025]]`
-- Block references: `((block-id))` This inserts a reference to the content of a specific block.
-- Page references: `[[Page name]]` This creates a link to another page within your Roam graph.
-- Link to blocks: `[Link Text](<((block-id))>)` This will link to the block.
-- Embed block in a block: `{{[[embed]]: ((block-id))}}`
-- To-do items: `{{[[TODO]]}} todo text` or `{{[[DONE]]}} todo text`
-- Syntax highlighting for fenced code blocks (add language next to backticks before fenced code block - all in one block) - Example:
-  ```javascript
-      const foo(bar) => {
-          return bar;
-      }
-  ```
-- Tags:
-  - one-word: `#word`
-  - multiple words: `#[[two or more words]]`
-  - hyphenated words: `#self-esteem`
-
-## Roam Tables
-
-Roam tables are created by nesting blocks under a `{{[[table]]}}` parent block. The key to correct table rendering is to ensure proper indentation levels for headers and data cells. Each subsequent header or data cell within a row must be nested one level deeper than the previous one.
-
-- The `{{[[table]]}}` block acts as the container for the entire table.
-- The first header block should be at level 2 (one level deeper than `{{[[table]]}}`).
-- Subsequent header blocks must increase their level by one.
-- Each row starts at level 2.
-- The first data cell in a row is at level 3 (one level deeper than the row block).
-- Subsequent data cells within the same row must increase their level by one.
-
-Example of a 4x4 table structure:
+# Roam Markdown Cheatsheet — Generic Foundation v2.0.0
+
+> ⚠️ **MODEL DIRECTIVE**: Always consult this cheatsheet BEFORE making any Roam tool calls. Syntax errors in Roam are unforgiving.
+
+---
+
+## Quick Reference: Core Syntax
+
+### Text Formatting
+| Style | Syntax | Example |
+|-------|--------|---------|
+| Bold | `**text**` | **bold text** |
+| Italic | `__text__` | __italic text__ |
+| Highlight | `^^text^^` | ^^highlighted^^ |
+| Strikethrough | `~~text~~` | ~~struck~~ |
+| Inline code | `` `code` `` | `code` |
+| LaTeX | `$$E=mc^2$$` | rendered math |
+
+### Links & References
+| Type | Syntax | Notes |
+|------|--------|-------|
+| Page reference | `[[Page Name]]` | Creates/links to page |
+| Block reference | `((block-uid))` | Embeds block content inline |
+| Block embed | `{{[[embed]]: ((block-uid))}}` | Full block embed with children |
+| External link | `[text](URL)` | Standard markdown |
+| Aliased page ref | `[display text]([[Actual Page]])` | Shows custom text, links to page |
+| Aliased block ref | `[display text](<((block-uid))>)` | Links to specific block |
+| Image embed | `![alt text](URL)` | Inline image |
+
+### Tags & Hashtags
+| Type | Syntax | When to Use |
+|------|--------|-------------|
+| Single word | `#tag` | Simple categorization |
+| Multi-word | `#[[multiple words]]` | Phrases, compound concepts |
+| Hyphenated | `#self-esteem` | Naturally hyphenated terms |
+
+⚠️ **CRITICAL**: Never concatenate multi-word tags. `#knowledgemanagement` ≠ `#[[knowledge management]]`
+
+### Dates
+- **Always use ordinal format**: `[[January 1st, 2025]]`, `[[December 23rd, 2024]]`
+- Ordinals: 1st, 2nd, 3rd, 4th–20th, 21st, 22nd, 23rd, 24th–30th, 31st
+
+### Task Management
+| Status | Syntax |
+|--------|--------|
+| Todo | `{{[[TODO]]}} task description` |
+| Done | `{{[[DONE]]}} task description` |
+
+### Attributes (Properties)
+```
+Type:: Book
+Author:: [[Person Name]]
+Rating:: 4/5
+Source:: https://example.com
+```
+
+**Purpose**: Attributes create structured metadata that is **queryable across your entire graph**. The attribute name becomes a page reference, so only use `::` when the attribute is a reusable property that applies to multiple pages or concepts.
+
+**When to USE attributes:**
+| Attribute | Why It's Good |
+|-----------|---------------|
+| `Type:: Book` | Reusable across all media you consume |
+| `Author:: [[Person]]` | Links to author page, queryable |
+| `Status:: In Progress` | Standard project states, queryable |
+| `Source:: URL` | Consistent sourcing across notes |
+| `Date:: [[January 1st, 2025]]` | Enables date-based queries |
+
+**When NOT to use attributes:**
+| ❌ Wrong | ✅ Use Instead | Why |
+|----------|----------------|-----|
+| `Step 1:: Do this thing` | `**Step 1:** Do this thing` | Step numbers are page-specific, not queryable concepts |
+| `Note:: Some observation` | Just write the text, or use `#note` | One-off labels don't need attribute syntax |
+| `Summary:: The main point` | `**Summary:** The main point` | Section headers are formatting, not metadata |
+| `Definition:: Some text` | `Term:: Definition` | Only use for actual definitions you want to query |
+| `Implementation Tier 3 (Societal Restructuring):: Some text` | `** Implementation Tier 3 (Societal Restructuring)**: Some text` | Label is specific to current concept |
+
+⚠️ **The Test**: Ask yourself: "Will I ever query for all blocks with this attribute across my graph?" If no, use **bold formatting** (`**Label:**`) instead of `::` syntax.
+
+NOTE: Never combine bold markdown formatting with `::`. Roam formats attributes in bold by default. ✅ `<attribute>::` ❌ `**<attribute>**::`
+
+---
+
+## Block Structures
+
+### Bullet Points
+- Use `-` (dash) followed by space
+- Nested bullets: indent with tab or spaces
+```
+- Parent item
+    - Child item
+        - Grandchild item
+```
+
+### Code Blocks
+````
+```javascript
+const example = () => {
+    return "syntax highlighted";
+}
+```
+````
+
+### Queries
+```
+{{[[query]]: {and: [[tag1]] [[tag2]]}}}
+{{[[query]]: {or: [[optionA]] [[optionB]]}}}
+{{[[query]]: {not: [[exclude-this]]}}}
+{{[[query]]: {between: [[January 1st, 2025]] [[January 31st, 2025]]}}}
+```
+
+### Calculator
+```
+{{[[calc]]: 2 + 2}}
+{{[[calc]]: 100 * 0.15}}
+```
+
+---
+
+## Complex Structures
+
+### Tables
+Tables use nested indentation. Each column header/cell nests ONE LEVEL DEEPER than previous.
 
 ```
 {{[[table]]}}
     - Header 1
         - Header 2
             - Header 3
-                - Header 4
-    - Row 1
-        - Data 1.1
-            - Data 1.2
-                - Data 1.3
-                    - Data 1.4
-    - Row 2
-        - Data 2.1
-            - Data 2.2
-                - Data 2.3
-                    - Data 2.4
-    - Row 3
-        - Data 3.1
-            - Data 3.2
-                - Data 3.3
-                    - Data 3.4
-    - Row 4
-        - Data 4.1
-            - Data 4.2
-                - Data 4.3
-                    - Data 4.4
-```
-
-## Roam Mermaid
-
-This markdown structure represents a Roam Research Mermaid diagram. It begins with a `{{[[mermaid]]}}` block, which serves as the primary container for the diagram definition. Nested underneath this block, using bullet points, is the actual Mermaid syntax. Each bullet point corresponds to a line of the Mermaid graph definition, allowing Roam to render a visual diagram based on the provided code. For example, `graph TD` specifies a top-down directed graph, and subsequent bullet points define nodes and their connections.
-
-```
-- {{[[mermaid]]}}
+    - Row 1 Label
+        - Cell 1.1
+            - Cell 1.2
+                - Cell 1.3
+    - Row 2 Label
+        - Cell 2.1
+            - Cell 2.2
+                - Cell 2.3
+```
+
+**Rules:**
+- `{{[[table]]}}` is level 1
+- First header/row-label at level 2
+- Each subsequent column nests +1 level deeper
+- Keep tables ≤5 columns for readability
+
+### Kanban Boards
+```
+{{[[kanban]]}}
+    - Column 1 Title
+        - Card 1 content
+        - Card 2 content
+    - Column 2 Title
+        - Card 3 content
+```
+
+### Mermaid Diagrams
+```
+{{[[mermaid]]}}
     - graph TD
-        - A[Start] --> B{Decision Point}
-        - B -->|Yes| C[Process A]
-        - B -->|No| D[Process B]
-        - C --> E[Merge Results]
-        - D --> E
-        - E --> F[End]
-```
-
-## Roam Kanban Boards
-
-The provided markdown structure represents a Roam Research Kanban board. It starts with a `{{[[kanban]]}}` block, under which nested bullet points define the Kanban cards. Each top-level bullet point directly under `{{[[kanban]]}}` serves as a card title, and any further nested bullet points under a card title act as details or sub-items for that specific card.
-
-```
-- {{[[kanban]]}}
-    - card title 1
-        - bullet point 1.1
-        - bullet point 1.2
-    - card title 2
-        - bullet point 2.1
-        - bullet point 2.2
-```
-
----
-
-## Roam Hiccup
-
-This markdown structure allows embedding custom HTML or other content using Hiccup syntax. The `:hiccup` keyword is followed by a Clojure-like vector defining the HTML elements and their attributes in one block. This provides a powerful way to inject dynamic or custom components into your Roam graph. Example: `:hiccup [:iframe {:width "600" :height "400" :src "https://www.example.com"}]`
-
-## Specific notes and preferences concerning my Roam Research graph
-### When creating new pages
-
-- After creating a new page, ensure you add a new block on the daily page that references it if one doesn't already exist: `Created page: [[…]]`
-
-### What To Tag
-
-- Always think in terms of Future Me: How will I find this gem of information in this block in the future? What about this core idea might I be looking for? Aim for high relevance and helpfulness.
-- My notes in Roam are interconnected via wrapped terms/expressions [[…]] and hashtags (#…). The general salience guidelines are as follows:
-
-  - What greater domain would this core idea be best categorization?
-  - If block is parent of children blocks, can a word/phrase in the parent be wrapped in brackets.
-    - If not, could a hashtag be appended to the block? (This is like a "please see more"-on-this-subject categorization).
-  - Wrap any proper names—no titles—(Dr. [[Werner Erhard]]), organizations, abbreviations e.g. `[NASA]([[National Aeronautics and Space Administration (NASA)]])`
-  - Any synonyms or multi-worded phrases of already established categories/pages, e.g. `[frameworks for making quality decisions]([[decision-making frameworks]])`
-
-#### Advanced tagging methodology combining [[zettelkasten]] principles with serendipity engineering for maximum intellectual discovery potential. #[[knowledge management]] #[[tagging methodology]]
-
-- # Core Philosophy
-  - Tag for **intellectual collision** and **future conversation**, not just categorization. Every tag should maximize the potential for unexpected discoveries and cross-domain insights.
-  - Traditional academic categorization creates silos; serendipity-engineered tagging creates **conceptual magnets** that attract surprising connections.
-- ## Zettelkasten-Informed Principles
-  - **Atomic Thought Units**: Each tagged concept should function as a standalone intellectual object capable of connecting to ANY other domain
-  - **Conversation-Driven Linking**: Tag by the intellectual dialogues and debates a concept could inform, not just its subject matter
-  - **Temporal Intellectual Journey**: Tag for different phases of understanding - beginner discoveries, expert refinements, teaching moments
-  - **Intellectual Genealogy**: Create concept lineages that trace how ideas evolve and connect across domains
-- ## Serendipity Engineering Techniques
-  - **Conceptual Collision Matrix**: Force unlikely intellectual meetings by tagging across disparate domains
-    - Example: #[[parenting techniques]] + [[cognitive engineering]] = developing children's meta-cognitive awareness
-    - Example: #[[cooking methods]] + [[cultural rotation]] = how different cultures balance flavors → balancing competing AI instructions
-  - **Anti-Obvious Tagging**: Deliberately tag against natural categorization to maximize surprise
-    - Tag by **structural similarities** rather than surface content: #[[has feedback loops]], #[[requires calibration]], #[[exhibits emergence]]
-    - Connect concepts through **metaphorical bridges**: meditation techniques + bias detection (both about noticing the unnoticed)
-  - **Question Cascade Strategy**: Tag by what questions a concept could answer across unexpected domains
-    - Instead of "this is about X," ask "what problems could this solve that I haven't thought of yet?"
-    - Examples: #[[how do experts prevent tunnel vision?]], #[[what creates cognitive flexibility?]], #[[how do systems self-correct?]]
-  - **Future Collision Potential**: Tag with temporal discovery triggers
-    - [[will be relevant in 5 years]], #[[connects to unborn projects]], #[[solves problems I don't know I have yet]]
-- ## Practical Implementation
-  - **The Serendipity Test**: Before tagging, ask "Could this concept surprise me by connecting to something completely unrelated?"
-  - **Cross-Domain Bridge Tags**: Use structural rather than content-based categorization
-    - [[flow dynamics]] - connects fluid mechanics, music, conversation, AI prompt sequences
-    - [[calibration processes]] - bridges instrument tuning, relationships, AI parameters, personal habits
-    - [[perspective switching]] - connects photography, negotiation, cultural analysis, prompt engineering
-  - **Problem-Solution Pairing**: Tag by the problems solved rather than methods used
-    - [[breaking cognitive constraints]], #[[expanding solution spaces]], #[[preventing expert blindness]]
-  - **Intellectual State Triggers**: Tag for when you'd actually search based on mental/emotional context
-    - [[feeling stuck in patterns]], #[[needing fresh perspective]], #[[frustrated with conventional approaches]]
-- ## Tag Maintenance Strategy
-  - **Regular Collision Audits**: Periodically review tags to identify missed connection opportunities
-  - **Surprise Discovery Log**: Track when unexpected tag connections lead to insights, then engineer more of those patterns
-  - **Question Evolution**: Update question-based tags as your intellectual interests and problems evolve
-  - **Cross-Reference Integration**: Ensure new tagging approach complements existing page reference `[[…]]` and hashtag `#[[…]]` conventions
-
-### How to Tag (nuances)
-
-- Consider that when linking a parent block, all children blocks will also accompany future search results. Linking a childblock will only link the child block, not siblings.
-- The convention for tags is lower case unless proper nouns. When tagging might affect the capitalization within a sentence, use aliases. e.g. `[Cognitive biases]([[cognitive biases]]) of the person are listed…"
-- Can longer phrases and expressions be aliased to existing notes? `How one can leverage [[cognitive dissonance]] to [hypnotically influence others using language]([[hypnotic language techniques]])`
-- Reformat quotes in this format structure: `<quote> —[[<Quoted Person>]] #quote <hashtags>` with 2-3 additional relevant hashtag links
-- Anything that needs follow-up, further research, preface with `{{[[TODO]]}}`
-  - Scheduled review: Tag future dates in ordinal format so that it can come up for review when relevant, e.g. `[[For review]]: [[August 12th, 2026]]` Optionally, prepend with label ("Deadline", "For review", "Approved", "Pending", "Deferred", "Postponed until"). Place on parent block if relevant (if children blocks are related).
-
-### Constraints
-
-- Don't overtag.
-
-⭐️📋 END (Cheat Sheet LOADED) < < < 📋⭐️
+        - A[Start] --> B{Decision}
+        - B -->|Yes| C[Action]
+        - B -->|No| D[Alternative]
+```
+
+### Hiccup (Custom HTML)
+`:hiccup [:iframe {:width "600" :height "400" :src "https://example.com"}]`
+
+`:hiccup [:div {:style {:color "red"}} "Custom styled content"]`
+
+---
+
+## Anti-Patterns — DON'T DO THIS
+
+| ❌ Wrong | ✅ Correct | Why |
+|----------|-----------|-----|
+| `Step 1:: Do this` | `**Step 1:** Do this` | `::` creates queryable attributes; use bold for page-specific labels |
+| `#multiplewords` | `#[[multiple words]]` | Concatenated tags create dead references |
+| `[[january 1, 2025]]` | `[[January 1st, 2025]]` | Must use ordinal format with proper capitalization |
+| `[text](((block-uid)))` | `[text](<((block-uid))>)` | Block ref links need angle bracket wrapper |
+| `{{embed: ((uid))}}` | `{{[[embed]]: ((uid))}}` | Embed requires double brackets around keyword |
+| Deeply nested tables (6+ cols) | Max 4-5 columns | Becomes unreadable/unmanageable |
+| `- *bullet` | `- bullet` | Use dash, not asterisk for bullets |
+| `[[TODO]] task` | `{{[[TODO]]}} task` | TODO needs double curly braces |
+
+---
+
+## Tool Selection Decision Tree
+
+```
+CREATING CONTENT IN ROAM:
+
+┌─ Is this a NEW standalone page with structure?
+│   └─ YES → roam_create_page (with content array)
+│
+├─ Adding content to EXISTING page/block?
+│   ├─ Simple outline structure → roam_create_outline
+│   │   (provide page_title_uid and/or block_text_uid)
+│   │
+│   └─ Complex/nested markdown → roam_import_markdown
+│       (for deeply nested content, tables, etc.)
+│
+├─ Need to CREATE, UPDATE, MOVE, or DELETE individual blocks?
+│   └─ roam_process_batch_actions
+│       (fine-grained control, temporary UIDs for parent refs)
+│
+├─ Adding a memory/note to remember?
+│   └─ roam_remember (auto-tags with MEMORIES_TAG)
+│
+├─ Adding TODO items to today?
+│   └─ roam_add_todo (creates individual TODO blocks)
+│
+└─ SEARCHING/READING:
+    ├─ Find by tag → roam_search_for_tag
+    ├─ Find by text → roam_search_by_text  
+    ├─ Find by date range → roam_search_by_date
+    ├─ Find by status → roam_search_by_status
+    ├─ Get page content → roam_fetch_page_by_title
+    ├─ Get block + children → roam_fetch_block_with_children
+    ├─ Recall memories → roam_recall
+    └─ Complex queries → roam_datomic_query
+```
+
+---
+
+## API Efficiency Guidelines (Rate Limit Avoidance)
+
+The Roam API has rate limits. Follow these guidelines to minimize API calls:
+
+### Tool Efficiency Ranking (Best to Worst)
+1. **`roam_process_batch_actions`** - Single API call for multiple operations (MOST EFFICIENT)
+2. **`roam_create_page`** - Batches content with page creation
+3. **`roam_create_outline` / `roam_import_markdown`** - Include verification queries (use for smaller operations)
+4. **Multiple sequential tool calls** - Each call = multiple API requests (AVOID)
+
+### Best Practices for Intensive Operations
+
+#### When Updating/Revising a Page:
+1. Fetch the page content ONCE at the start
+2. Plan ALL changes needed (creates, updates, deletes)
+3. Execute ALL changes in a SINGLE `roam_process_batch_actions` call
+4. Do NOT fetch-modify-fetch-modify in a loop
+
+#### When Creating Large Content:
+- For 10+ blocks: Use `roam_process_batch_actions` with nested structure
+- For simple outlines (<10 blocks): `roam_create_outline` is fine
+
+#### UID Caching:
+- Save UIDs from previous operations - don't re-query for them
+- Use `page_uid` instead of `page_title` when available (avoids lookup query)
+- Use `block_uid` instead of `block_text_uid` when you have it
+
+#### UID Placeholders for Nested Blocks:
+When using `roam_process_batch_actions` to create nested blocks, use **placeholder tokens** instead of generating UIDs yourself. The server generates proper random UIDs and returns a mapping.
+
+**Syntax:** `{{uid:name}}` where `name` is any identifier you choose.
+
+**Example:**
+```json
+[
+  { "action": "create-block", "uid": "{{uid:parent}}", "string": "Parent Block", "location": { "parent-uid": "pageUid123", "order": 0 } },
+  { "action": "create-block", "string": "Child Block", "location": { "parent-uid": "{{uid:parent}}", "order": 0 } }
+]
+```
+
+**Response includes UID mapping:**
+```json
+{
+  "success": true,
+  "uid_map": {
+    "parent": "Xk7mN2pQ9"
+  }
+}
+```
+
+**Why placeholders?** LLMs are not reliable random generators. The server uses cryptographically secure randomness to generate proper 9-character Roam UIDs.
+
+### Example: Efficient Page Revision
+
+**Instead of:**
+```
+1. roam_fetch_page_by_title → get content
+2. roam_create_outline → add section 1
+3. roam_create_outline → add section 2
+4. roam_import_markdown → add more content
+```
+
+**Do this:**
+```
+1. roam_fetch_page_by_title → get page UID and content
+2. roam_process_batch_actions → ALL creates/updates in one call
+```
+
+---
+
+## Structural Defaults
+
+When unsure how to structure output:
+
+1. **Hierarchy depth**: Prefer 2-4 levels; rarely exceed 5
+2. **Block length**: Keep blocks atomic — one idea per block
+3. **Page refs vs hashtags**: 
+   - `[[Page]]` for concepts you'll expand into full pages
+   - `#tag` for categorization/filtering
+4. **When to embed vs reference**:
+   - `((uid))` — inline reference (shows content)
+   - `{{[[embed]]: ((uid))}}` — full block with children
+   - `[text](<((uid))>)` — clickable link only
+
+---
+## Visual Separation — Hierarchy First, Separators Never
+
+Empty blocks and decorative dividers create clutter. Roam's outliner structure provides all the visual separation you need.
+
+| ❌ Avoid | ✅ Instead |
+|----------|-----------|
+| Blank blocks | Let hierarchy create space — child blocks are visually indented |
+| `---` dividers | Use a **heading block** to signal section breaks |
+| Decorative lines `───` | Nest content under a parent block as a structural container |
+
+**Principle**: If you feel the urge to add visual breathing room, you probably need *better structure*, not more blocks. Promote a block to a heading, or reorganize into parent/child relationships.
+
+**The test**: If you'd delete it during cleanup, don't create it.
+
+---
+
+## Output Format Conventions
+
+### Quotes
+```
+<quote text> —[[Author Name]] #quote #[[relevant topic]]
+```
+
+### Definitions
+```
+Term:: Definition text #definition #[[domain]]
+```
+
+### Questions for Future
+```
+{{[[TODO]]}} Research: <question> #[[open questions]]
+```
+
+---
+
+*End of Generic Foundation — Personalization section follows during user setup.*
+# Roam Preferences — Personalization Layer
+
+> This section contains YOUR specific conventions, tagging philosophy, and graph-specific rules. Customize to match your workflow.
+
+---
+
+## Graph-Level Behaviors
+
+### On Creating New Pages
+<!-- CUSTOMIZE: What should happen when a new page is created? -->
+- After creating a new page, add a reference block on today's daily page: `Created page: [[New Page Name]]`
+- <!-- Add any naming conventions, required metadata, etc. -->
+
+### On Adding Content
+<!-- CUSTOMIZE: Any rules about where/how content gets added? -->
+- Default location for quick captures: Daily page
+- Long-form content: Create dedicated page, link from daily page
+- <!-- Your preferences here -->
+
+---
+
+## Tagging Philosophy
+
+### Core Principle
+> Tag for **intellectual collision** and **future discovery**, not just categorization. Every tag should maximize potential for unexpected connections.
+
+### The Serendipity Test
+Before tagging, ask: *"Could this concept surprise me by connecting to something completely unrelated?"*
+
+### What To Tag — Decision Framework
+
+```
+ASK YOURSELF:
+┌─ How will Future Me find this?
+│   └─ Tag by retrieval context, not just content
+│
+├─ What domain does this belong to?
+│   └─ Use broad category tags: #[[knowledge management]], #[[decision-making]]
+│
+├─ Is this a proper noun?
+│   └─ YES → Wrap name (no titles): [[Werner Erhard]], [[NASA]]
+│   └─ For abbreviations: [NASA]([[National Aeronautics and Space Administration (NASA)]])
+│
+├─ Could this alias to existing page?
+│   └─ YES → [displayed phrase]([[existing page name]])
+│   └─ Example: [frameworks for decisions]([[decision-making frameworks]])
+│
+└─ Parent block with children?
+    └─ Tag parent when category applies to all children
+    └─ Tag individual children for specific categorization
+```
+
+### Tag Type Selection
+
+| Use This | When |
+|----------|------|
+| `[[Page Reference]]` | Concept deserves its own page, will be expanded |
+| `#[[hashtag]]` | Categorization, filtering, won't be a standalone page |
+| `#single-word` | Simple, unambiguous category |
+| Attribute `Type::` | Structured metadata for queries |
+
+### Structural Tagging (Beyond Content)
+
+Tag by **patterns and mechanisms**, not just subjects:
+
+| Structural Tag | Connects |
+|----------------|----------|
+| `#[[has feedback loops]]` | Systems, habits, markets, conversations |
+| `#[[requires calibration]]` | Instruments, relationships, AI prompts |
+| `#[[exhibits emergence]]` | Complexity, culture, creativity |
+| `#[[perspective switching]]` | Photography, negotiation, analysis |
+| `#[[flow dynamics]]` | Fluids, music, conversation, sequences |
+
+### Problem-Oriented Tagging
+
+Tag by problems solved, not methods used:
+
+- `#[[breaking cognitive constraints]]`
+- `#[[expanding solution spaces]]`
+- `#[[preventing expert blindness]]`
+
+### Temporal & State-Based Tags
+
+| Tag Type | Examples |
+|----------|----------|
+| Future relevance | `#[[will be relevant in 5 years]]`, `#[[connects to unborn projects]]` |
+| Mental state triggers | `#[[feeling stuck in patterns]]`, `#[[needing fresh perspective]]` |
+| Review scheduling | `[[For review]]: [[August 12th, 2026]]` |
+
+---
+
+## Formatting Conventions
+
+### Quotes
+```
+<quote text> —[[Author Name]] #quote #[[topic1]] #[[topic2]]
+```
+Always include 2-3 relevant hashtags after quotes.
+
+### TODOs and Follow-ups
+```
+{{[[TODO]]}} <action needed>
+{{[[TODO]]}} #researchThis : <topic to investigate> 
+```
+
+### Scheduled Reviews
+```
+[[For review]]: [[Date in ordinal format]]
+```
+Optional labels: "Deadline", "Approved", "Pending", "Deferred", "Postponed until"
+
+### Aliasing for Case Sensitivity
+When a tag would awkwardly affect sentence capitalization:
+```
+[Cognitive biases]([[cognitive biases]]) affect decision-making...
+```
+
+### Definitions (OVERRIDE)
+```
+#def [[<term>]] : <definition>
+```
+
+---
+
+## Constraints & Guardrails
+
+### DON'T
+- **Overtag** — Quality over quantity; each tag should earn its place
+- **Tag obvious/redundant** — If parent block is tagged, children inherit context
+- **Use inconsistent capitalization** — Tags are lowercase unless proper nouns
+- **Create orphan tags** — Check if existing page/tag serves the purpose
+- **Bold Attributes** - ❌ `**Attribute**::`, ✅ `Attribute::` (Roam auto-formats)
+
+### DO
+- **Think retrieval-first** — How will you search for this later?
+- **Cross-pollinate domains** — Force unlikely intellectual meetings
+- **Update aging tags** — As interests evolve, so should tag vocabulary
+- **Track surprise discoveries** — When unexpected connections yield insights, engineer more of those patterns
+
+---
+
+## Custom Rules
+
+<!-- 
+CUSTOMIZE THIS SECTION with your specific conventions:
+- Naming patterns for certain page types
+- Required attributes for books/articles/people
+- Project-specific tagging schemes
+- Integration rules with other tools
+- etc.
+-->
+
+### Example Custom Rules (modify as needed):
+
+**Books:**
+```
+[[Book: Title by Author]]
+Type:: Book
+Author:: [[Author Name]]
+Status:: Reading | Completed | Abandoned
+Rating:: X/5
+```
+
+**People:**
+```
+[[Person Name]]
+Type:: Person
+Context:: How I know them
+```
+
+**Projects:**
+```
+[[Project: Name]]
+Status:: Active | Paused | Completed
+Start:: [[Date]]
+```
+
+---
+
+## Integration Notes
+
+<!-- CUSTOMIZE: Any rules about how Roam integrates with your other tools/systems -->
+
+- Daily pages serve as: <!-- inbox / journal / task list / etc. -->
+- Weekly reviews occur on: <!-- day of week -->
+- Content flows from: <!-- capture tools, read-later apps, etc. -->
+- Content flows to: <!-- publishing, archives, etc. -->
+
+---
+
+*End of Personalization Layer*