ImageFirm

ImageFirm / Fieldwork

The publishing standard.

Turn working documents into clear, useful ImageFirm pages. Preserve the substance. Give it a consistent form.

ImageFirmRevision 2026-11-145 min readEN

01 / Start with the source

A useful publication begins with the material you already have: a working note, a structured report, a table or a field guide. The first task is to preserve what the source says, then make its structure easy to follow.

Clarity comes from deliberate structure, faithful content and a reader who can find what matters.

02 / Give every element a job

Headings create the route through a document. Tables make comparisons inspectable. Captions explain why a visual is present. References let a reader return to the evidence.

5 rows
Illustrative publication workflow
StageInputResult
ImportSelected source filesStructured content
ReviewExtracted text and tablesChecked reading order
DesignImageFirm templateConsistent presentation
PreviewDesktop and mobile viewsReadable layouts
ExportReviewed publicationStandalone HTML

03 / Keep numbers meaningful

A value carries more than its digits. Preserve its sign, scale, unit, currency and context. A stored spreadsheet result should remain distinguishable from a newly calculated result.

Illustrative formatting examples — not financial projections
MeaningEnglish displayTurkish display
Amount1,234.561.234,56
Percentage12.5%%12,5
Date14 November 202614 Kasım 2026

04 / Make the page portable

A standalone publication includes its content and presentation in one HTML file. It can be opened locally and moved into a static website publishing workflow. The editable project remains a separate working file.

html
<article>
  <h2>A clear section heading</h2>
  <p>Content that remains useful across devices.</p>
</article>

05 / Continue exploring

Visit the ImageFirm index for the wider collection of working documents.

This is sample content for testing the publisher. Replace it with your own material before publication.

ImageFirm

Single-user macOS desktop application — unified pane of glass over digital-asset library folders on ~/Desktop/, with Google Workspace Drive sharing and on-device AI enrichment. The library set is defined in Sources/AppCore/AppPaths.swift.

Status

No slice has been formally accepted yet. See CHANGELOG.md for the per-module ledger and docs/SESSION-HANDOFF.md for the current acceptance gaps and plan.

In short: the safety invariant (assertWriteIsSafe + SafetyInvariantTests) is real and enforced, and the app does index the library folders read-only into a local SQLite catalog and render the Overview dashboard. But large amounts of Slice (b), (c), and (d) code (browser/preview UI, quarantine, collections, dedup queries, Google Drive OAuth + resumable upload) also landed before (a) was formally closed, while several Slice (a) acceptance criteria (FSEvents live watcher, deterministic mid-scan resume, bounded concurrency, the bridge event channel, the audit-chain startup verification) are still open. Stabilization work is in progress — don't treat the working tree as a released product.

System requirements

Build and run

bash
# 1) Build the web bundle
cd Web && npm install && npm run build && cd ..

# 2) Build the Swift app and assemble the .app bundle
./scripts/build-app.sh

# 3) Open it
open build/ImageFirm.app

On first launch, macOS will ask to grant Full Disk Access so the app can index ~/Desktop/. The app cannot work without it. Approval is one-time.

Develop

bash
# Swift tests (safety invariant + catalog migration)
swift test

# Hot-reload web layer against the bridge dev-fallback data (no Swift app needed)
cd Web && npm run dev

The web layer detects whether it's running inside the WKWebView (window.__imagefirm is set) or in a dev browser, and falls back to a small demo dataset in the browser.

What it does today

Architecture

See docs/architecture-map.md for the layered diagram.

text
App/                    Swift entry, NSApplication + WKWebView host
Sources/AppCore/        Standard paths, expected library map
Sources/Safety/         assertWriteIsSafe + SafeFS wrapper
Sources/Catalog/        SQLite (GRDB) + schema + migrations + records
Sources/Indexer/        Walker, hasher, metadata extractor, scan orchestrator
Sources/Bridge/         Codable command/event types + WKScriptMessageHandlerWithReply
Web/                    React + TS + Vite + Tailwind dashboard
Tests/SafetyTests/      Build-failing static check on writes
Tests/CatalogTests/     Migration + FTS trigger + cascade tests
docs/                   ADR, data model, milestone plan, trust boundary

Trust boundary

OAuth setup (placeholder until Slice d)

The Drive integration (Slice d) requires a Google Cloud OAuth client ID (Desktop-app type, PKCE). Setup steps will land with that slice.

Signing & notarization

For local development, signing is skipped — build-app.sh produces an unsigned .app. For distribution:

bash
export DEVELOPER_ID_APPLICATION="Developer ID Application: Your Name (TEAMID)"
./scripts/build-app.sh

Notarization + Sparkle update feed wire up in Slice (f).

Where things live at runtime

6 rows
Table 44
PathPurpose
~/Library/Application Support/ImageFirm/catalog.sqliteCatalog DB
~/Library/Application Support/ImageFirm/derivatives/Thumbnails, transcodes
~/Library/Application Support/ImageFirm/models/Downloaded CLIP / Whisper weights (Slice e)
~/Library/Application Support/ImageFirm/logs/Rotating logs
~/Library/Application Support/ImageFirm/audit.logHash-chained audit (Slice c+)
~/Library/Application Support/ImageFirm/quarantine/Soft-deletes (Slice c)

Reset

bash
rm -rf "$HOME/Library/Application Support/ImageFirm"

…and re-launch. The library files on Desktop are untouched.

Docs