pal-e-docs

Convention: Block-First Knowledge Access

convention-block-first-access Convention

active convention
Project

Purpose

Block-first is the default pattern for how agents interact with pal-e-docs. Start narrow, widen if needed. Never read a full note when a section will do.

The Pattern

  • Navigate: get_note_toc(slug) — see what sections exist (~50 tokens)
  • Read: get_section(slug, anchor_id) — fetch the section you need (~200 tokens)
  • Write: update_block(slug, anchor_id, content) — edit one section without touching the rest
This replaces the old pattern of get_note() → read entire HTML blob → update_note(content=full_html). That pattern costs ~2,360 tokens per plan read. Block-first costs ~250 tokens for the same information.

When to Use What

I need to... Use Not Why
See what's in a note <code>get_note_toc(slug)</code> <code>get_note(slug)</code> TOC is ~50 tokens vs ~2,360 for a plan
Read one section <code>get_section(slug, anchor)</code> <code>get_note(slug)</code> Section is ~200 tokens vs full note
Read a small note (&lt;1K chars) <code>get_note(slug)</code> TOC + section Overhead of two calls not worth it for small notes
Update one section <code>update_block(slug, anchor, content)</code> <code>update_note(content=...)</code> Surgical edit, no full rewrite needed
Rewrite most of a note <code>update_note(content=...)</code> Multiple update_block calls Full rewrite is simpler when changing &gt;50% of content
Create a new note <code>create_note()</code> — Blocks auto-generated from HTML (7e-1)
See all blocks (debugging) <code>list_blocks(slug)</code> — Full block dump, rarely needed in normal workflow

The Rule

Start narrow, widen if needed.
  • TOC first — see the structure
  • Section if relevant — read what you need
  • Full note only if you need most of it
This pattern scales. 10 plans, 50 plans, 500 notes — startup cost stays flat because you only load what the task requires.

Session Startup

The session hook injects plan TOCs at startup. Betty Sue sees the structure of every active plan without reading any of them in full. When the user's first message arrives, Betty Sue reads the relevant sections.
Before (eager loading): ~11,640 tokens for 6 full plan reads
After (block-first): ~1,032 tokens for 6 TOCs + targeted section reads as needed
Board sync at startup: In addition to plan TOC injection, Betty Sue calls sync_board(board_slug) on active project boards at session start. This ensures board state reflects the latest phase statuses without reading full board item lists eagerly. Board sync is a write operation (reconciles the board) rather than a read, so it complements the block-first read pattern rather than replacing it.

Who This Applies To

Agent How block-first changes their workflow
<strong>Betty Sue</strong> Session startup uses TOCs. Plan/phase reads use <code>get_section()</code>. Doc updates use <code>update_block()</code> for surgical edits.
<strong>Dottie</strong> Content audits navigate by TOC. Doc updates use block-level writes. Full note reads only for small notes or full rewrites.
<strong>Dev / QA</strong> No change — they don't access pal-e-docs.

Exceptions

  • Small notes (<1K chars): get_note() is fine. Block overhead not justified.
  • Full rewrites: update_note(content=...) is correct when replacing most of a note's content.
  • Personality notes: Agent personality definitions need full text to work. These are injected in full at session start.
  • New note creation: create_note() accepts HTML and auto-generates blocks (7e-1).

Technical Foundation

This convention relies on the Phase 7 block infrastructure:
  • 7a: blocks + compiled_pages tables
  • 7b: HTML↔blocks parser and compiler
  • 7c: Backfill — all notes decomposed to blocks
  • 7d: Block API — 6 endpoints (toc, list, get_section, update, create, delete)
  • Phase 8: SDK (38 methods) + MCP (32 tools) wrapping block API
  • 7e-1: Source-of-truth cutover — note writes auto-generate blocks
  • 7e-2: Compiled page endpoint
  • decision-7e3-block-first-access — the decision record behind this convention
  • phase-postgres-7e-compiled-pages — the phase that implemented it
  • benchmark-phase7-block-baseline — before/after token measurements
  • agent-workflow — the operating model this convention extends