Garage Construction Project

CLAUDE

11 min read

Pictures Folder - AI Assistant Guide

This document provides important context for AI assistants working with photo documentation in this folder.

Folder Organization (adopted 2026-04-22)

Photos live in year-month subfolders: pictures/YYYY-MM/. Two files stay at the root:

  • index.md — the dashboard / chronological gallery (date sections link into the subfolders)
  • CLAUDE.md — this guide

Every photo has a paired image (.jpg / .png / .JPG) and a .md description with the same base name. Both files live together in the same year-month subfolder.

Filename Convention (adopted 2026-04-22)

Photos and their paired .md descriptions follow the same scheme used in content/Email Imports/:

YYYY-MM-DD - Source - Description.ext

(See ../Email Imports/CLAUDE.md for the canonical description of this scheme — the only difference here is which values are used for the Source and Description fields.)

The three parts

PartRuleExample
YYYY-MM-DDThe photo’s local date (EDT/EST — already converted; the UTC timestamp embedded in a Pixel filename is not the filename date). Comes from the .md’s date: frontmatter.2025-10-30
SourceThe device or system that produced the image. One of: Pixel, DJI, Screenshot, Signal, ChatGPT.Pixel
DescriptionShort specific phrase — comes from the .md’s title: frontmatter with the leading date stripped. Use a time disambiguator in parentheses when multiple photos share the same date/source (replace : with - for filesystem safety, e.g., (2-12 PM) not (2:12 PM)).Foundation Forms (2-12 PM)

Full example

2025-10-30 - Pixel - Cement Truck Arrival (9-24 AM).jpg
2025-10-30 - Pixel - Cement Truck Arrival (9-24 AM).md

Both files live in pictures/2025-10/.

What the old PXL-style filenames used to look like

Before 2026-04-22 photos kept their camera-assigned names (PXL_YYYYMMDD_HHMMSSTTT.jpg, DJI_NNNN.JPG, Screenshot_YYYYMMDD_HHMMSS.png, signal-YYYY-MM-DD-HHMMSS_NNN.png, ChatGPT_*.png). Every file in the vault has since been renamed to the YYYY-MM-DD - Source - Description.ext scheme. If you find a legacy-named file, rename it per this scheme before committing.

Filesystem-safety in descriptions

  • : → - (colon is invalid on Windows; we need it for EDT/EST times like 9:24 AM, so substitute with hyphen)
  • / → or - (slash is a path separator — never include in a filename)
  • |, <, >, *, ?, " → drop or substitute
  • Spaces are fine, as are parentheses and hyphens.

Which subfolder does a file go in?

The year-month subfolder is taken from the first 7 chars of the new filename (YYYY-MM). So 2025-10-30 - Pixel - Cement Truck Arrival.jpg lands in pictures/2025-10/.

When you’re starting from a freshly-dropped camera-named file (still PXL_YYYYMMDD_*, DJI_NNNN.JPG, etc.), figure out the local date first (remember Pixel filenames are UTC — see the timezone section below), then build the new filename and move to pictures/YYYY-MM/.

Auto-file hook

.claude/hooks/auto-file-photos.sh (PostToolUse on Write) catches the common case: Claude writes a new description .md at pictures/ root using the new scheme (YYYY-MM-DD - Source - Description.md), and the hook moves both the .md and its paired image into pictures/YYYY-MM/ based on the date prefix in the filename.

The hook only fires on Write (new file creation) — editing an existing photo description does not trigger a move.

Hook output is echoed to stdout so the writing agent can update any cross-references to use the new path.

Legacy filenames: the hook historically matched camera-assigned PXL_YYYYMMDD_*.jpg names. Now that the vault has been migrated to the YYYY-MM-DD - Source - ... scheme, that legacy branch is obsolete for newly-filed photos, though the hook still matches both for belt-and-suspenders during the transition window.

Obsidian and Quartz both resolve [[BareFilename]] by searching the vault — so a reference like [[2026-04-22 - Pixel - First Shelly 1PM Mini Gen 4 Installed Behind Switch|photo]] continues to work regardless of which subfolder the file lives in. Explicit-path refs are fine too: [[pictures/2026-04/2026-04-22 - Pixel - First Shelly 1PM Mini Gen 4 Installed Behind Switch|photo]]. Prefer the explicit form in docs that reference photos across multiple months (Timeline, index pages), and the bare form inside photo-to-photo cross-links within the same subfolder.

Photo .md files reference other parts of the vault

Photo descriptions often link back to design docs, timeline, meetings, etc. Because photo files live one level deeper than the content root, relative paths must use ../../ to climb out of pictures/YYYY-MM/:

- [[../../10-Planning/Timeline|Timeline]]
- [[../../20-Design/Interior/Electrical Planning|Electrical Planning]]
- [[../../Email Imports/2025-11-18 - Letherer Truss - Delivery Email|Delivery Email]]

Not [[../... (that was correct when photos lived at pictures/ root; it’s wrong now).

Critical: Pixel Phone Timezone Issue

The Problem

Pixel phone filenames contain UTC timestamps, NOT local Eastern time.

The filename format of a freshly-dropped Pixel photo is: PXL_YYYYMMDD_HHMMSSTTT.jpg

  • Example: PXL_20251030_132458239.jpg
  • The timestamp 132458 means 13:24:58 UTC
  • This is NOT the local time when the photo was taken

The Solution

Always convert UTC to Eastern Time (EDT/EST) in documentation:

  • Eastern Daylight Time (EDT): UTC - 4 hours (March-November)
  • Eastern Standard Time (EST): UTC - 5 hours (November-March)

Conversion Examples

October 30, 2025 (EDT active):

PXL_20251030_132458239.jpg → 13:24 UTC → 9:24 AM EDT ✓
PXL_20251030_154535475.jpg → 15:45 UTC → 11:45 AM EDT ✓

October 20, 2025 (EDT active):

PXL_20251020_181223482.jpg → 18:12 UTC → 2:12 PM EDT ✓
PXL_20251020_224944298.jpg → 22:49 UTC → 6:49 PM EDT ✓

Why This Matters

Without timezone conversion, documentation shows impossible times:

  • Photos at “10:49 PM” that show bright daylight
  • Concrete truck “arriving at 1:24 PM” when it actually arrived at 9:24 AM
  • Work appearing to happen 4 hours later than it actually did

Standard Workflow: Adding New Photos

When the user drops a freshly-camera-named file (e.g., PXL_YYYYMMDD_HHMMSSTTT.jpg) into pictures/ and asks Claude to document it, the flow is:

  1. Read the .jpg to analyze content.

  2. Determine the photo’s local date (convert Pixel UTC → EDT/EST — see timezone section below).

  3. Pick a short description that captures what the photo shows. For same-date / same-source groups, include a time disambiguator in parentheses, substituting : with - (e.g., (9-24 AM)).

  4. Rename the image file to the new scheme using git mv (or plain mv if untracked):

    PXL_20251030_132458239.jpg
  -> 2025-10-30 - Pixel - Cement Truck Arrival (9-24 AM).jpg

  5. Write the markdown description file at pictures/ root with the same base name + .md using the Write tool. The auto-file-photos.sh hook fires on Write and moves both files into pictures/YYYY-MM/ based on the date prefix in the filename. Claude should use the post-move path (pictures/YYYY-MM/2025-10-30 - Pixel - ...) when adding cross-references elsewhere — the hook echoes the new path to stdout.

    Follow the structure of existing .md files (frontmatter, Photo Details, Description, Visible Elements, Related Notes). Photo .md files live at pictures/YYYY-MM/ — relative paths out of the file must use ../../ (see “Folder Organization” section above).

  6. Add the photo to the index page (pictures/index.md)

    • Group by date under the appropriate heading
    • Add a weather summary for the day under the date heading
    • Use chronological order within each date
    • Include corrected EDT/EST times (not UTC!)
    • Use bare [[YYYY-MM-DD - Source - Description|display text]] wiki-links — Obsidian and Quartz resolve them by base name across the vault.

  7. Update related documentation as needed

    • Add photo links to build progress documents if relevant
    • Update timeline entries if photos document new milestones
    • Prefer the explicit [[pictures/YYYY-MM/YYYY-MM-DD - Source - Description|display]] form in cross-project docs (Timeline, vendor records, design specs) where the subfolder helps a reader know when the photo is from.

This workflow should happen automatically without needing explicit instructions each time.

Weather Data Integration

When documenting photos from construction dates, automatically add weather information using the weather-mcp MCP tool. Weather context helps understand photo conditions and construction quality.

Adding Weather to Photo Documentation

  1. Fetch weather for photo date:

    • Use mcp__weather__get_historical_weather for dates within past 7 days
    • Location: Detroit, MI (42.3314°N, -83.0458°W)

  2. Add to Photo Details section:

    ## Photo Details
 
- **Date**: Month DD, YYYY
- **Time**: H:MM AM/PM EDT (or EST)
- **Weather**: [Conditions], [Temp]. [Context about visibility/conditions]
- **Phase**: Construction phase

  3. Example weather entries:

    • **Weather:** Clear skies, 59°F. Excellent visibility for photography.
    • **Weather:** Light drizzle, overcast, 48°F. Wet conditions visible in photo.
    • **Weather:** Partly cloudy, 52°F. Good lighting conditions.

Proactive Workflow

When user adds new construction photos or asks to document photos, automatically fetch and include weather data:

  1. Add weather to each individual photo’s markdown file
  2. Add weather summary to the date section in index.md

Index.md Weather Format:

## October 30, 2025 - Concrete Foundation Pour 🎉
 
**Weather:** Light drizzle during pour, overcast, 45-50°F. Challenging conditions.
 
**Major Milestone:** Complete concrete foundation pour...

Photo Documentation Workflow

When Adding New Photos

  1. Extract timestamp from filename (of the freshly-dropped camera file, before renaming):

    • Filename: PXL_20251030_132458239.jpg
    • UTC time: 13:24:58 (HH:MM:SS)

  2. Convert to Eastern Time:

    • Determine if EDT (UTC-4) or EST (UTC-5) based on date
    • EDT: Second Sunday in March through first Sunday in November
    • EST: First Sunday in November through second Sunday in March
    • Subtract hours: 13:24 UTC - 4 hours = 9:24 AM EDT

  3. Document in markdown frontmatter:

    date: 2025-10-30
time: 09:24

  4. Document in photo details:

    - **Time**: 9:24 AM EDT

Photo Markdown Template

When creating photo documentation, use this structure:

---
title: YYYY-MM-DD - Photo Description
type: photo-documentation
tags: [construction, relevant-tags]
date: YYYY-MM-DD
time: HH:MM
phase: foundation|framing|etc
status: in-progress|completed
---
 
# Photo Title
 
![Alt Text](filename.jpg)
 
## Photo Details
 
- **Date**: Month DD, YYYY
- **Time**: H:MM AM/PM EDT (or EST)
- **Phase**: Construction phase
- **Location**: 309 E. 7th St., Clare, MI
- **View**: Perspective description
 
## Description
 
Detailed description of what's visible in the photo...

File Naming Patterns

Pixel Phone Photos (as-received from phone)

  • Pattern: PXL_YYYYMMDD_HHMMSSTTT.jpg
  • Timestamp: UTC (not local time!)
  • Example: PXL_20251030_132458239.jpg
  • On ingest, renamed to the YYYY-MM-DD - Pixel - Description.jpg scheme above.

DJI Drone Photos (as-received from drone)

  • Pattern: DJI_####.JPG
  • Numbering: Sequential (e.g., DJI_0886.JPG, DJI_0887.JPG, …)
  • Timestamp: Check EXIF data or rely on file modification time
  • Note: Usually already in local time
  • On ingest, renamed to the YYYY-MM-DD - DJI - Description.JPG scheme above.

Photo Organization

Index Page Structure

Photos are organized chronologically by date on index.md:

## October 30, 2025 - Description
 
Brief overview of what happened this day.
 
- [[Photo1.md|Description (TIME)]]
- [[Photo2.md|Description (TIME)]]

Sorting

  • Photos within a day are sorted by time (earliest first)
  • The /pictures folder uses date-sort in reverse (newest first) via Quartz config

Common Pitfalls

❌ Don’t Do This

- **Time**: 1:24 PM  # This is UTC, not local time!
time: 13:24          # This is UTC, not local time!

✓ Do This

- **Time**: 9:24 AM EDT  # Converted from 13:24 UTC
time: 09:24              # 24-hour format, Eastern Time

Quick Reference Card

Filename UTCEDT ConversionEST Conversion
12:00 (noon)8:00 AM EDT7:00 AM EST
13:249:24 AM EDT8:24 AM EST
15:4511:45 AM EDT10:45 AM EST
18:122:12 PM EDT1:12 PM EST
22:496:49 PM EDT5:49 PM EST

Quick Checklist: New Photo Addition

When user adds new photos (e.g., “I dropped some new photos in the pictures folder”):

  • Read each new image file to analyze photo content
  • Extract UTC timestamp from Pixel phone filenames and convert to EDT/EST
  • Pick a short description; include (H-MM AM/PM) disambiguator if multiple photos share date/source
  • Rename the image from its camera-assigned name (PXL_YYYYMMDD_*, DJI_NNNN.JPG, etc.) to the YYYY-MM-DD - Source - Description.ext scheme using git mv (or plain mv if the file isn’t tracked yet)
  • Write the .md description at pictures/ root with the same base name — the auto-file hook moves both files into pictures/YYYY-MM/ based on the date prefix
    • YAML frontmatter with title: YYYY-MM-DD - Description, date: YYYY-MM-DD, time: HH:MM (local 24h), tags, phase, status
    • Photo Details section with converted local time
    • Description with “Visible Elements” subsections
    • Related Documents links (use ../../ to climb out of pictures/YYYY-MM/)
  • Confirm the auto-file hook moved the files into pictures/YYYY-MM/ (check stdout notice)
  • Add to index.md under appropriate date heading (bare [[YYYY-MM-DD - Source - Description|title]] links work)
  • Update related build docs if needed (Initial Build, Timeline, etc.) — prefer explicit [[pictures/YYYY-MM/YYYY-MM-DD - Source - Description|display]] links in cross-project docs
  • Commit with descriptive message

Example user prompt that triggers this workflow:

  • “I added some new photos to the pictures folder”
  • “Please document these new photos I just uploaded”
  • “Create descriptions for the latest pictures”
  • Initial Build - Links to photo documentation by phase
  • Timeline - Timeline references photo dates/times
  • Parent CLAUDE.md - Main project documentation guide

This file is ignored in Quartz builds but tracked in git for AI assistant reference.

Graph View