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.
- Use a concise title and a descriptive introduction.
- Keep one idea in each section and label it clearly.
- Retain numbers, units, dates and the links that support them.
- Review the mobile layout before sharing the page.
| Stage | Input | Result |
|---|---|---|
| Import | Selected source files | Structured content |
| Review | Extracted text and tables | Checked reading order |
| Design | ImageFirm template | Consistent presentation |
| Preview | Desktop and mobile views | Readable layouts |
| Export | Reviewed publication | Standalone HTML |
No matching rows.
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.
| Meaning | English display | Turkish display |
|---|---|---|
| Amount | 1,234.56 | 1.234,56 |
| Percentage | 12.5% | %12,5 |
| Date | 14 November 2026 | 14 Kasım 2026 |
No matching rows.
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.
<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
- macOS 26.0 (Tahoe) or later — required for FoundationModels in later slices; current Slice (a) code runs on macOS 14+ but the bundle declares 26.0 as the floor.
- Apple Silicon (M-series).
- Command-line tools: xcode-select --install.
- Node 20+ for the Web bundle build.
- ≈ 10 GB free disk for the derivative cache + future model downloads.
Build and run
# 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
# 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
- Detects the 8 expected library folders on ~/Desktop/ — both Video Library and bare Video are accepted.
- Indexes every file read-only into ~/Library/Application Support/ImageFirm/catalog.sqlite.
- Extracts format-specific metadata: image dimensions + EXIF, video duration + codec + bitrate, audio duration + codec, PDF page count + word count from the first 50 pages.
- Maintains a virtual assets_fts FTS5 index (search lights up in Slice c).
- Shows Overview dashboard: 5 KPIs, library breakdown table, largest files, recent additions.
- Enforces the §2.1 safety rule: nothing inside ~/Desktop/<* Library>/ is ever written to.
Architecture
See docs/architecture-map.md for the layered diagram.
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
- Files in ~/Desktop/<* Library>/ are never modified by the app.
- All catalog and derivative writes go to ~/Library/Application Support/ImageFirm/ (mode 0700).
- Every write call goes through Sources/Safety/SafeFS.swift. A test (SafetyInvariantTests.test_invariant_singleWriteChokepoint) fails the build if any source file outside SafeFS.swift (or the future FinderTagWriter.swift) calls a raw FileManager write method.
- No outbound network in Slice (a). Drive lands in Slice (d).
- Refresh tokens (Slice d) will live in the macOS Keychain; nothing else on disk is a secret.
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:
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
| Path | Purpose |
|---|---|
| ~/Library/Application Support/ImageFirm/catalog.sqlite | Catalog 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.log | Hash-chained audit (Slice c+) |
| ~/Library/Application Support/ImageFirm/quarantine/ | Soft-deletes (Slice c) |
No matching rows.
Reset
rm -rf "$HOME/Library/Application Support/ImageFirm"
…and re-launch. The library files on Desktop are untouched.
Docs
- CLAUDE.md — codebase conventions
- CHANGELOG.md — per-module ledger and slice acceptance log
- docs/SESSION-HANDOFF.md — current state audit, open gaps, working agreement
- docs/ADR-001-stack-and-scope.md — locked stack decisions (some intent has since drifted from implementation; see CHANGELOG)
- docs/data-model.md — SQLite schema (sections marked [PLANNED] are intent, not implementation)
- docs/architecture-map.md — layered architecture
- docs/native-web-bridge.md — bridge contract
- docs/milestone-plan.md — slice scopes and acceptance criteria
- docs/library-inventory.md — empirical scale of the real corpus
- docs/trust-boundary.md — what crosses the network and when
- docs/open-questions.md — defaults needing sign-off per slice