Home A - Z
Page Index
Properties 
category: reference
tags: [meta, design, prd, schema]
last_updated: 2026-03-12
confidence: high

Original PRD Note Schema

This page is part of the original single-tenant PRD, split across five wiki pages: Design/Research_Wiki | Design/Rest Api | Design/Semantic_Search | Design/Mcp Server | Design/Note_Schema

Note Schema

All wiki pages should use YAML frontmatter. This is a convention, not enforced by the system, but the Chroma plugin extracts metadata from it for filtering.

---
category: actor | variable | trend | proposition | event | reference | index
tags: [tag1, tag2]
last_updated: 2026-03-09
confidence: high | medium | low | speculative
---

Field definitions

  • category: What kind of note this is. Maps to the analytical framework:
    • actor — a state, organization, leader, or entity (e.g., "Iran", "Trump", "IRGC")
    • variable — a tracked parameter or measurable quantity (e.g., "WTI Oil Price", "Interceptor Stockpiles")
    • trend — an ongoing dynamic or trajectory (e.g., "Desalination Targeting Ratchet")
    • proposition — a testable analytical claim with observable indicators (e.g., "Iran is rationing ballistic missiles")
    • event — a specific dated occurrence (e.g., "Israel Strikes Tehran Oil Depots")
    • reference — an external source, report, or dataset (e.g., "USDA Prospective Plantings Report")
    • index — a hub or overview page that links to related notes
  • tags: Freeform tags for filtering. Examples: military, economic, food-security, p1-third-clock, p2-interceptor-race, p3-infrastructure, p4-economic-transmission
  • last_updated: Date of last substantive update (ISO 8601 date, e.g., 2026-03-09).
  • confidence: Epistemic status of the note's core claims.

Related notes are expressed only as [[WikiLinks]] in the body text, NOT in frontmatter. There is no related frontmatter field. The link graph is derived entirely by parsing WikiLinks in page content. This avoids the divergence problem where a frontmatter list and inline links get out of sync.

Page organization

Pages are organized in subdirectories by category:

Actors/
  Iran.md
  Trump.md
  China.md
  Russia.md
  Gulf States.md
Variables/
  WTI Oil Price.md
  Interceptor Stockpiles.md
  US Gas Prices.md
  Iranian Civilian Casualties.md
Trends/
  Desalination Targeting Ratchet.md
  Iran Attrition Strategy.md
  Economic Double Wave.md
Propositions/
  Iran Rationing Ballistic Missiles.md
  Fertilizer Supply Chain Disruption.md
Events/
  2026-03-01 US Strikes Begin.md
  2026-03-07 Israel Strikes Tehran Oil Depots.md
References/
  USDA Prospective Plantings.md
  FAO Food Price Index.md

Cross-referencing

Use Otterwiki's native [[WikiLink]] syntax. Examples:

The [[Actors/IranIran]] [[Trends/Iran Attrition Strategyattrition strategy]] 
involves a multi-phase approach: cheap drones to drain 
[[Variables/Interceptor Stockpilesinterceptor stockpiles]], followed by 
ballistic missiles against high-value targets.

Page size guidance

Notes should be 250–800 words (roughly 400–1200 tokens). This is a soft target, not a hard limit. The rationale is context window efficiency: the AI assistant pulls multiple notes per session. If individual notes are 3,000+ words, pulling five of them consumes most of the context window. Short, atomic notes let the AI pull 10–20 relevant notes and still have room for conversation, analysis, and system prompts.

If a note grows beyond ~1000 words, it should probably be split into multiple notes linked together. For example, a long "Iran" actor note should be decomposed into "Iran — Military Doctrine", "Iran — Political Leadership", "Iran — Nuclear Program", etc., with an "Iran" index page linking them.

That said, longer notes are not a system-level problem. The Chroma plugin chunks pages for embedding (see Component 2), so semantic search quality is unaffected by page length. The guidance is about keeping individual notes focused and context-window-friendly, not a technical constraint.

Complete example page

Here is what Trends/Iran Attrition Strategy.md looks like on disk:

---
category: trend
tags: [military, p2-interceptor-race, p3-infrastructure]
last_updated: 2026-03-08
confidence: high
---

# Iran Attrition Strategy

Iran is executing a multi-phase attrition campaign designed to degrade 
Gulf state and US defensive capacity before committing high-value 
ballistic missile assets.

## Phase structure

**Phase 1 — Drone saturation.** Cheap Shahed-series drones launched in 
large salvos to force expenditure of expensive interceptor missiles. 
The cost asymmetry is extreme: a $20,000 drone forces the use of a 
$1–3M interceptor. See [[Variables/Interceptor Stockpiles]].

**Phase 2 — Radar blinding.** Anti-radiation missiles and electronic 
warfare to degrade air defense radar networks, creating gaps in 
defensive coverage.

**Phase 3 — Ballistic strikes on high-value targets.** Once interceptor 
stockpiles are depleted and radar coverage is degraded, Iran commits 
ballistic missiles against infrastructure targets. The 86% drop in 
ballistic missile launch rates in the first week reflects deliberate 
rationing, not destroyed capability. See 
[[Propositions/Iran Rationing Ballistic Missiles]].

## Evidence

- Ballistic missile launch rate dropped ~86% after initial salvos 
  (Days 1–3 vs Days 4–9), while drone launch rates remained constant 
  or increased.
- [[Actors/IranIRGC]] messaging emphasizes "patience" and 
  "strategic depth."
- Historical precedent: Iran used similar phased approach in late 
  stages of Iran-Iraq War.

## Implications

This strategy means the most dangerous phase of the conflict for 
Gulf infrastructure is still ahead, not behind. The current period 
of relatively low ballistic missile activity is the preparation 
phase, not the resolution. See [[Trends/Desalination Targeting Ratchet]] 
for emerging target categories.

Master Index Convention

Purpose

The master index solves the "you don't know what you don't know" problem. At session start, the AI assistant reads one page and gets a complete map of the wiki's contents. This replaces the current protocol of reading all project PDFs.

Structure

Index/Master.md is a single page listing every note in the wiki, organized by category, with a one-line description per note. It is maintained by both the human and the AI. When either party creates a new note, they should add it to the master index.

Example

---
category: index
tags: [meta]
last_updated: 2026-03-09
confidence: high
---

# Master Index

## Actors
- [[Actors/Iran]] — military doctrine, IRGC command, attrition strategy, nuclear posture
- [[Actors/Trump]] — surrender framing, "no time limits" rhetoric, Third Clock dynamics
- [[Actors/China]] — hedging calculus, summit positioning, semiconductor leverage
- [[Actors/Russia]] — targeting intelligence provision, diplomatic posture
- [[Actors/Gulf States]] — defensive capacity, desalination vulnerability, alliance strain

## Variables (P1–P4)
- [[Variables/Third Clock]] — P1: Trump tolerance timeline ⚠️ STALLED as of Day 9
- [[Variables/Interceptor Stockpiles]] — P2: Gulf-wide Patriot/THAAD depletion tracking
- [[Variables/Iran Strike Intent]] — P3: ballistic/drone ratio, targeting pattern evolution
- [[Variables/WTI Oil Price]] — P4: $90.90 as of Day 9, record weekly gain
- [[Variables/US Gas Prices]] — P4: $3.45 as of Day 9
- [[Variables/Iranian Civilian Casualties]] — 1,200+ as of Day 9

## Trends
- [[Trends/Iran Attrition Strategy]] — multi-phase: drones → radar blinding → ballistic strikes
- [[Trends/Desalination Targeting Ratchet]] — confirmed both sides, precedent difficult to walk back
- [[Trends/Economic Double Wave]] — immediate oil shock + delayed harvest-time food prices (Q3–Q4)

## Propositions
- [[Propositions/Iran Rationing Ballistic Missiles]] — 86% launch rate drop = rationing, not destruction
- [[Propositions/Fertilizer Supply Chain Disruption]] — no strategic reserve, spring window biologically fixed

## Events (recent)
- [[Events/2026-03-07 Israel Strikes Tehran Oil Depots]] — first Israeli strike on Tehran
- [[Events/2026-03-08 New Iranian Supreme Leader Selected]] — unnamed successor
- [[Events/2026-03-08 Russia Providing Targeting Intelligence]] — confirmed

## References
- [[References/USDA Prospective Plantings]] — March 31 report, anchors food security monitoring
- [[References/FAO Food Price Index]] — April 3 update

Size budget

At ~15 words per entry, 200 notes ≈ 3,000 words ≈ 4,500 tokens. This fits comfortably in a single tool call. The master index only needs to be fragmented into sub-indexes if the wiki exceeds ~500 pages.

Orphan detection

The find_orphaned_notes MCP tool compares the full page list against pages referenced in all category: index pages. Pages that exist but aren't linked from any index are "orphans." This is used during periodic gardening sessions (see below), not at every session start.

Session start protocol

When beginning a research session, the AI assistant should:

  1. read_note("Index/Master") — load the full map
  2. list_notes(updated_since=<last_session_date>) — see what changed since last check-in
  3. Based on the day's research question, read_note the 5–15 most relevant pages
  4. Proceed with web search for new developments, as per existing protocol

Gardening sessions

Periodically (likely automated), a dedicated session focuses solely on wiki maintenance:

  • find_orphaned_notes() — add orphans to the appropriate index or flag for review
  • Review notes with stale last_updated dates
  • Check for broken WikiLinks (Otterwiki also has built-in housekeeping for this)
  • Update confidence levels on propositions based on accumulated evidence
  • Identify notes that have grown too long and should be split
  • Ensure tag consistency (catch typos like p2-interceptor_race vs p2-interceptor-race)
  • Update the master index

The gardening protocol will be refined once the system is running and we understand the actual maintenance patterns.

Open Questions

  1. Plugin blueprint support — This is the critical unknown. Phase 1 resolves it. Read otterwiki/plugins.py and docs/plugin_examples/ before writing any code.
  2. Chroma embedding model — all-MiniLM-L6-v2 is the pragmatic default (runs locally, no API key). The chunking strategy sizes chunks to fit within the model's input window, so the exact max sequence length matters for tuning target_tokens in the chunker. Verify the actual limit at implementation time and adjust accordingly. Could upgrade to a larger model later if retrieval quality is poor.
  3. Frontmatter parsing — Otterwiki has a community-contributed YAML frontmatter renderer plugin (noted in v2.10 changelog). Investigate whether it already handles frontmatter parsing that can be reused. If not, use PyYAML to parse the --- delimited block at the top of page content.
  4. Concurrent edit safety — The API should check the page revision before saving and return 409 on conflict. Otterwiki's web editor already handles this with a draft system. For the initial implementation, last-write-wins is acceptable — add optimistic locking later if it causes problems in practice.
  5. WikiLink direction — Otterwiki's syntax docs show [[Text to display|WikiPage]] (target is second). Verify this against the actual rendering code before implementing the parser, since getting this backwards would silently corrupt the link graph.