Skip to content

Build & Automation Guide

Reference for running scripts and managing the build pipeline.

Data Architecture

The data/ directory is the single source of truth for all structured data. Build.sh reads from it.

File Updated when Updated by
data/portfolio.json Jonathan reports new balances AI advisor (during session)
data/config.json Targets, policies, or income change AI advisor (during session)
data/expenses.json New CSVs added or patterns updated python3 scripts/categorise-expenses.py
data/expense-patterns.json New merchants identified AI advisor (during session)
data/history/YYYY-MM.json Monthly AI advisor (copies key values from portfolio.json)

What to Run and When

Trigger Action Command
New balances reported Update portfolio data Edit data/portfolio.json, add data/history/YYYY-MM.json
New expense CSVs added Regenerate expenses python3 scripts/categorise-expenses.py
Every session (at end) Build site, verify, commit & push ./build.sh && git add -A && git commit && git push
Strategy/number change Propagate — grep for stale values See Propagation Rule in agents.md
CSS or layout change Edit overrides/extra.css only, rebuild Edit CSS → ./build.sh

Pre-Commit Checklist (MANDATORY)

Do this EVERY time before git commit:

□ grep -rn "<any changed value>" .  — find ALL stale references
□ Fix every match (except snapshot chart data arrays showing current state)
□ ./build.sh — confirm clean build
□ Re-read the diff: git diff --stat && git diff
□ Only then: git add -A && git commit

This is not optional. If a number, percentage, policy, or platform changed during this session, grep for the old value. If you skip this step, you WILL leave inconsistencies.

Session Workflow (step-by-step)

1. ./auto-update.sh              # Pull spreadsheet, regenerate net-worth-history + Monte Carlo
2. Review outputs — check for data issues
3. Create/update notes/YYYY-MM/ files (snapshot, assessment, wife-summary)
4. Update current-plan.md and action-items.md
5. ./build.sh                    # Generates docs/, mkdocs.yml, injects portfolio value
6. Review build output for warnings (absolute links, broken anchors)
7. git add -A && git commit -m "YYYY-MM session: [summary]" && git push

What Each Script Does

auto-update.sh — Data pipeline:

  1. Downloads Google Sheets as XLSX (falls back to cached copy if download fails)
  2. Extracts Net Worth history → regenerates net-worth-history.md chart data
  3. Extracts latest figures → updates Monte Carlo starting value
  4. Requires: python3, openpyxl (pip3 install openpyxl)

build.sh — Site generator:

  1. Copies root .md files into docs/
  2. Extracts portfolio value from latest snapshot → injects into Monte Carlo + homepage
  3. Auto-discovers session folders → builds nav with prescribed ordering
  4. Generates mkdocs.yml with grouped nav (Strategy, Portfolio, Tools, Planning, Reference, Sessions)
  5. Generates homepage (docs/index.md) with live dashboard stats
  6. Adds cache-busting to CSS
  7. Runs mkdocs build → outputs to site/

Google Sheets Integration

  • URL: https://docs.google.com/spreadsheets/d/1b86kANqAC-ikfXC7_ydn0-X3zaeXROC4UIK2zdnZ_2c/export?format=xlsx
  • Access: Public (link-sharing enabled, no auth required)
  • Key tabs: Net Worth, Investments, Annual Overview, FIRE
  • Important: Always use the PREVIOUS month's row — the current month is in-progress/incomplete
  • Date column check: Verify which row corresponds to the correct month before extracting