Context

Program & CapEx is the standout differentiator for the European (Ethos / citizenM) tender, the capability gap versus PACS. It had to be defensible to finance reviewers, AI-native, and multi-currency for a hotel group, built fast over one week.

Decision

(1) Ledger-first: an immutable, append-only `capex_cost_facts` ledger (plan / commit / actual / reverse) is the source of truth; committed, actual, point-in-time and audit are aggregated on read, never derived off mutable tickets or POs. (2) Accounting basis is IFRS IAS 16; the cash test is reserve adequacy against the USALI FF&E reserve, kept strictly separate from non-cash accounting depreciation (conflating the two is the number-one credibility error). (3) Plan = approved budget, Committed = PO or contract raised not yet invoiced, Actual = invoiced or paid; a closed work-order's actual cost auto-rolls into the ledger as Actual. (4) Governance is two-step (budget_approved then authorised) with four stamp columns as the audit trail, and separation of duties is a per-org setting (small teams let one manager do both, large orgs enforce authoriser not equal to approver). (5) Multi-currency consolidates server-side into one group reporting currency with a per-org FX mode: Fixed (manual planning rates, so capital forecasts do not swing on spot FX) or Live (ECB daily reference feed, free and no key, EUR-triangulated, daily cron). (6) AI proposes but never inflates: the suggester's cost is the deterministic forecast sum (inflation guardrail by construction), a human approves (maker / checker).

Reasoning

Finance buyers re-derive numbers and distrust black boxes; an immutable ledger plus IAS 16 / USALI grounding plus explainable deterministic forecasting makes every figure auditable. Per-org settings (separation of duties, FX mode) fit both citizenM-scale groups and small operators from one codebase. Every slice shipped no-migration and build-verified.

Alternative Rejected

(a) Derive committed / actual on read from tickets and POs: fails point-in-time and audit, and double-counts when money moves Committed to Actual. (b) A single hard-coded reporting currency or daily spot FX for everyone: wrong for groups that budget on fixed annual rates. (c) Hard-enforced separation of duties for all orgs: blocks a solo area-manager. (d) Letting AI set capex costs: an inflation and hallucination risk, so cost is deterministic and AI only names and prioritises.

Context

A 9-surface security swarm (every high finding adversarially re-verified) found the core strong (tenant isolation, parameterised SQL, no XSS) but surfaced real holes. The standout: the public visitor kiosk performed data reads/writes with no server-side PIN check (the PIN only gated the client React screen).

Decision

Codify three multi-tenant write-security rules and apply them across the audited surfaces. (1) Globally-scoped tables (e.g. asset_categories) require platform-admin, never a customer org-admin. (2) Public/unauthenticated routes must re-verify their access gate server-side on EVERY data action, not just the entry screen (the kiosk now re-checks the per-property PIN on every call). (3) Update server actions must never spread the raw client object into .set(): strip id/organization_id/created_by/created_at and re-pin organization_id in the where clause, because the TypeScript Omit is erased at runtime. View-only roles (engineer) must also be gated on sub-resource writes (vendor contacts/documents/performance).

Reasoning

Server Actions accept arbitrary JSON at runtime, so a type-level Omit gives zero protection; the where clause alone stops cross-tenant matching but not a matched row being moved cross-tenant via a crafted payload. The kiosk hole was a live unauthenticated cross-tenant PII exposure, so client-only gates are now treated as cosmetic.

Alternative Rejected

(a) A per-action allow-list of permitted columns instead of a deny-list strip: more thorough, but higher risk of silently dropping a legitimate field right before the demo, so the deny-list of identity/tenant/audit columns was chosen as the safe boundary. (b) Add Upstash-backed rate-limiting now: deferred as demo-risk (per-instance limiting is weak on serverless and could throttle the demo) pending real infra.

Context

/shutdown took ~15 min, dominated by sequential model tool-calls, and had drifted from /sync-launchctrl (stale step lists, a skip contract with no real trigger, a hardcoded repo list, and idempotency keyed only on the closure note).

Decision

Make Phase 1 (gather) and Phase 3 (deploy) deterministic scripts; reserve parallel subagents for per-project README judgment (only at 3+ active projects); make /shutdown the nightly save-state of the AIOS kernel (read AIOS_CORE §2/§3 for focus, write §3 status conservatively, propose §2 edits, add one cross-project insight). Trigger the /sync-launchctrl skip with an explicit `--from-shutdown` argument.

Reasoning

The 15-min cost was model round-trips, not compute (the Node sync is ~5-15s and the deploy is an async push). Scripting the determinism collapses the round-trips; the kernel write-back closes the load/save loop because AIOS_CORE is read first in every session.

Alternative Rejected

(a) Swarm everything: agent-spawn overhead exceeds the work for small shell tasks. (b) Leave it model-orchestrated: no speedup. (c) Keep the implicit "remember you are in shutdown" skip: breaks under subagent dispatch, so replaced with an explicit flag.

Context

Inspired by NetworkChuck's Hermes / Ron Weasley video. Set up a Hermes Agent instance (Nous Research, MIT-licensed, v0.14.0) on a Hostinger VPS to act as an always-on personal Chief of Staff reachable via Telegram. Brain: OpenRouter. Co-drafted the persona in a structured 6-question prompt-design session in Claude Code today.

Decision

Codename **"Stray Jarvis"** (Iron Man homage with a wink at being cloud-native, not Stark-Tower-resident). Full Chief-of-Staff scope: life ops, infrastructure, strategy, second brain. **Trusted-lieutenant dynamic**: calls Mark "Mark" (not "Sir"), takes initiative, pushes back when he disagrees, never butler-coded. **Voice reference**: Michael Caine's Alfred — warm authority, brief, declarative, British, weight behind every line. **Emotional spine**: protect the four things builders trade away (bandwidth, presence with Kelly, mission trajectory, better self). **Hard guardrail**: never speaks AS Mark on any outbound channel; drafts only on email/WhatsApp/Telegram/Slack. **Operational scope**: can deploy code; cannot move money, delete files, or book flights. Persona seeded into Hermes' `SOUL.md` today. `USER.md` and `MEMORY.md` drafted in the same session but not yet pasted.

Reasoning

Hermes wins over Claude Code as an always-on agent for three reasons captured in the source video: (1) it auto-crystallises skills from interactions and runs a background Curator that manages stale ones, so it gets sharper on day 30 than day 1; (2) it enforces hard character caps on `USER.md` (1,375) and `MEMORY.md` (2,200), which forces ruthless context curation and prevents the bloat that ages Claude Code badly; (3) it's gateway-first across six channels (Telegram, Discord, Slack, WhatsApp, Signal, email), meaning the agent reaches Mark where he already is rather than requiring him to summon it. Jarvis is deliberately distinct from Tau (the Claude Code dev/strategy collaborator) — different surface area, different mandate, no role overlap. The Alfred voice gives the agent permission to tell Mark hard truths when bandwidth or presence or mission or better-self starts fraying, which is the operational point of the persona.

Alternative Rejected

(a) **Claude Code as always-on agent** — wrong tool class; it's summoned per session, not persistent, no auto-skill crystallisation, no gateway. (b) **Canonical Bettany "Sir" Jarvis voice** — too much butler schtick, conflicts with Mark's terse-plain communication preference and would feel performative within a week. (c) **"All operational autonomy" version** — initial brainstorm answer was just the never-speak-as-Mark rule; on commit Mark pulled back and locked down money + file deletion + flight booking too. Captured pattern: he's more cautious when committing than when brainstorming; default to the cautious read on future guardrail decisions.

Context

First device deploy surfaced the question of what the home screen should be for both personas. Tempting unified answer was "lite version of the desktop dashboard with role-specific filters". Council consulted (O3 + Gemini 3.1 Pro) on whether to mirror the desktop dashboard, build a shared rollup, or diverge per persona.

Decision

Two divergent home screens. **FM (Portfolio tab):** cross-portfolio exception view answering "what's on fire across all my sites RIGHT NOW?" — four big-number tiles (Guest-impacting, Overdue certs, Approvals, Open tickets) plus a critical-tickets list. No per-property cards on home; per-property browsing lives permanently in the Properties tab. **Engineer (Today tab):** keep the existing hero + queue pattern (current shift focus + my-tickets list); deferred adding lite below-fold modules to a later session per Gemini's pushback that engineers don't context-switch enough on home to warrant them.

Reasoning

Both council models converged on the FM rollup pattern — FMs operate by exception across portfolio, so the home should be a triage surface, not a directory. They diverged on engineer home: O3 suggested adding lite modules below the fold to bring parity with the FM rich-home; Gemini argued strongly against, citing the engineer mental model (one current job, one queue) and the cost of adding glance-load that nobody scrolls to. Took Gemini's position because the engineer use-case is one-thing-at-a-time and the queue is already on-screen.

Alternative Rejected

(1) Single shared dashboard with role filters — fails because the two personas have orthogonal jobs-to-be-done (FM = portfolio exception triage; engineer = my-next-task focus). (2) Mirror the desktop dashboard — desktop dashboard is admin-oriented and built around mouse-driven drill-in, which doesn't translate to glance-load on a phone.

Context

Settings menu was missing from the app. Two routes: mirror the desktop preferences screen (org-level toggles, theme, language) or build a field-app-specific settings surface tuned to the two personas.

Decision

Persona-aware `SettingsView` accessed from the More tab, persisted via `@AppStorage`. Engineer block: haptics intensity (off / standard / heavy), Scan default action (asset / ticket / assessment), camera upload quality, offline auto-sync-on-wifi. FM block: push notification tolerance (off / important-only / all), require biometrics for approvals, default launch view. Shared: persona override (only if `canSwitchPersona`), Account info, About (app version + build + API host).

Reasoning

Council and gut-check agreed: field-app settings are about THIS device's behaviour (haptics, scan action, camera quality, offline sync), not the org configuration. Org/global preferences belong on the desktop. Persona-specific groupings beat one big undifferentiated list — engineers care about haptics + scan; FMs care about push tolerance + biometrics. Both will use the persona override and About sections.

Alternative Rejected

Mirror desktop preferences — would expose org-level toggles that don't make sense on the device, and miss the field-specific things that actually matter on a phone (haptics, camera quality, scan default).

Context

22+ Gemini-backed AI endpoints had no rate limiting. Single-user cost-abuse vector per the perf audit. Choice between Upstash Ratelimit (managed Redis) and an in-memory token bucket per Lambda instance.

Decision

Built an in-memory two-tier (per-minute + per-hour) token bucket keyed on `(orgId, userId, action)` with a 13-action quota registry. Lives in `src/lib/ai-rate-limit.ts`. Cold starts reset buckets — accepted because cold-start abuse is bounded by Vercel's per-region instance count.

Reasoning

Quotas land at ~3-20 calls/min/user. Round-tripping to Upstash costs ~30ms per check, dominating the small AI calls. In-memory is sub-millisecond. Adding a paid external KV for budgets that small isn't worth the operational footprint. Upgradeable to Upstash later if cold-start abuse becomes a real signal.

Alternative Rejected

Upstash Ratelimit — too heavy for the call volume + cost profile. Free tier would also bottleneck at scale.

Context

Analytics page was loading every row of 7 tables (assets, documents, tickets, tasks, training, incidents, vendors) and counting subsets via JS `.filter()`. 10s+ page load on real data; would fall over at 10x scale.

Decision

Rewrite every analytics function to use `count(*) FILTER (WHERE ...)` aggregates. Date trends use `to_char(created_at, 'YYYY-MM-DD') GROUP BY` so a 30-day chart returns at most 30 rows per resource. All five public functions preserve their prior signatures and return shapes; UI untouched.

Reasoning

Postgres is the right place to do partitioned counting. The aggregate query touches the table once and returns one row of counts; the in-memory `findMany().filter()` loaded thousands of rows over the wire to do the same job. At scale the multiplier is the row count.

Alternative Rejected

Materialized views / cached aggregate tables — premature; counts are fast on properly-indexed tables and the analytics page isn't hot enough to justify cache invalidation complexity.

Context

Multiple actions (`completeInspection`, `reorderTemplateItems`, bulk training/tickets, import post) ran per-row sequential UPDATEs. Two routes to fix: parallelize via `Promise.all` (still N round-trips, but concurrent) or fold into a single statement (`CASE WHEN id = ... END` or `inArray + same SET`).

Decision

Prefer single-statement when the SET clause is uniform across rows (`bulkUpdateTrainingStatus`) or only varies in one column (reorder's `order_index`). Use `Promise.all` when each row has materially different SET values that would require `UPDATE FROM VALUES` (`completeInspection` items have different `is_checked` / `notes` / `checked_at` per row).

Reasoning

Single-statement is one round-trip and respects transactional boundaries cleanly. Promise.all is less code but burns N connections and can't be wrapped in a single `tx` because Drizzle transactions serialize within one connection. Pick by what each row's SET clause actually varies.

Alternative Rejected

Universal `UPDATE FROM VALUES` pattern — type-unfriendly in Drizzle, harder to read for the cost.

Context

`getProfile()` runs Clerk `auth()` + a DB lookup on every call. Audit showed dashboard page alone calls it 3+ times per request via different server components / actions.

Decision

Wrap `getProfile()` with React's `cache(...)` so multiple call-sites within a single server render share the result. Side effects (insert / update on JIT profile creation) only run on the first call, which is the desired behaviour.

Reasoning

`cache` is Next.js 15's blessed per-request memoization for server components / actions. Free win, reduces Clerk auth() calls + DB roundtrips. No new dependency.

Alternative Rejected

Manual passing of `profile` through every callsite — invasive across 49 server actions.

Context

5 upload routes (`incident-attachments`, `documents`, `training-certificates`, `vendor-documents`, `inspection-item-photos`) advertise 50-100MB caps but use `request.formData()` against Vercel's hard 4.5MB Lambda body limit. Files >4.5MB silently fail.

Decision

Defer the migration to a follow-up PR. The fix is correct (migrate to `@vercel/blob/client` direct-upload pattern, copy from `asset-attachments` which already does this) but invasive: 5 server routes + 4 client dialog components + each upload happy path needs end-to-end testing.

Reasoning

The other 14.5/16 perf audit items shipped today are isolated-test-cheap. Upload migration is end-to-end-test-expensive — wrong day for it. Production cost of deferral: real customer uploads of large certs / video evidence currently silently fail. Mitigation: explicit follow-up filed; STATE.md flags it as next-up critical.

Alternative Rejected

Streaming via Web Streams API in the existing route — Vercel's hard limit is on the request body before it reaches the function code; streaming inside the function doesn't help.

Context

First V2 build was a cinematic Apple-style site (scroll-pinned hero, deep-navy product card, oversized type, restrained palette). Founder reviewed and rejected: "the apple vibe is completely wrong for propsec".

Decision

Rebuild V2 as a Snapfix × Expansive hybrid. Snapfix spirit: photo-first, real product captures, traffic-light status indicators, plainspoken practical clarity. Expansive spirit: left-aligned modular layout, hard-number trust signals, sticky demo CTA, customer-logo strip under hero, dashboard-led visuals. Light theme always. Real propsec-seven product screenshots wherever a route exists.

Reasoning

The audience is hotel maintenance managers + compliance officers + ops directors at multi-property groups. Time-poor, sceptical of marketing fluff, want immediate proof of utility. Apple-style aesthetic theatre signals "expensive marketing, not a real tool". Snapfix and Expansive both prove the formula for this category: utility-first, evidence-led, scannable.

Alternative Rejected

The Apple direction (cinematic-landing-hero scroll pin, centred composition, deep-navy card). Built it, founder rejected it, ripped it out. ~6 hours of work parked. Lesson: validate the "feel" with a 3-section sketch before building a 7-section cinematic timeline.

Context

Shipped the V2 home page with "Aligned with SFG20", "UK data residency", "UK Maintenance Manager", and "GoCardless for UK businesses" framing. Founder caught it: "you wouldn't have framed it as a UK only product. I don't want these mistakes to be repeated again."

Decision

All PropSec marketing copy is region-agnostic. Trust strip uses `Country-aware compliance · GDPR ready · ISO 27001 · Continuous shipping`. Footer trust drops "UK data residency" for "Country-aware compliance". Testimonial roles drop "UK" prefix. FAQ drops "UK businesses" framing. Legal pages (`/privacy`, `/terms`) keep UK GDPR references because PropSec Ltd is a UK-registered controller — that's legal accuracy, not marketing framing.

Reasoning

The product is country-aware. The codebase reads `asset → property → country_code` and filters regulations to that country (per `Features.md`, "replaces hardcoded UK-only prompt that surfaced 35 UK regs against an Irish boiler"). The vault `Target-Market.md` "UK-first" framing is stale relative to shipped product.

Alternative Rejected

Leading with UK credentials (SFG20 is UK-only, UK data residency is UK-only) would limit perceived market. Persisted memory at `feedback_propsec_multi_region.md` to prevent recurrence.

Context

All four of Mark's test iPhones showed the rekraft.design hero video frozen on the poster, the marquee static, and scroll-triggered animations dead. Diagnosis chain went from "iOS autoplay quirk" to "Lenis breaking touch" to the actual root cause: a single global CSS rule was killing every animation and transition site-wide to 0.001ms whenever the user had Reduce Motion enabled in iOS Settings, Accessibility (or had Low Power Mode on, which implicitly triggers the same media query).

Decision

Replace the universal `*, *::before, *::after { animation-duration: 0.001ms !important; transition-duration: 0.001ms !important }` rule with targeted, intent-aware handling. Continuous decorative motion (marquee, hero video loop) keeps running. Triggered or scroll-linked motion (fade-up entrances, word-reveal staggers, parallax scrubs, 3D tilt, Lenis smooth scroll, magnetic cursor) still respects the user's preference and either snaps to final state or skips entirely.

Reasoning

WCAG 2.3.3 (Animation from Interactions) targets motion the user does not control, especially scroll-linked and pop-up animation. Vestibular concerns are not about slow background drift; they are about sudden, large, unexpected movement. The previous nuclear approach made the brand site look broken (frozen marquee, paused hero) for any user with the toggle on, including everyone in iOS Low Power Mode. The proportional approach respects the spirit of the guideline while preserving brand presence.

Alternative Rejected

Two were considered. (a) Full bypass: ignore prefers-reduced-motion entirely. Rejected as hostile to users with vestibular disorders or migraines. (b) Keep nuclear: accept the site is silent for reduced-motion users. Rejected because Low Power Mode silently triggers it and most affected users haven't actively opted in.

Context

v2.1 of Fusa Kitchen (Next.js + GSAP cinematic hero) felt "too tech-startup, not chef-knife brand." Mark cited oryzo.ai as the new visual reference (Astro-based, premium-minimal, scroll-driven).

Decision

Full rebuild on Astro 5 with `@astrojs/vercel` static adapter. Drop the Zustand cart and Framer Motion in favour of mailto reservations.

Reasoning

Oryzo's register requires editorial-first, motion-rich, near-zero-JS. Astro fits that better than Next.js + React. Loss of cart functionality is acceptable for a portfolio-grade reservation site.

Alternative Rejected

Stay on Next.js and rewrite the cinematic hero. Rejected because the framework was a constraint on the Oryzo aesthetic, not just the components.

Context

FUSA hero centerpiece needed a long-axis rotation of the Kiritsuke knife. Three Seedance 2.0 generations on Higgs Field failed (in-screen-plane spin, then a camera tilt with no rotation, then a vertical-plane orbit that didn't match the mental model of a horizontal roll).

Decision

Switch to Google Veo 3.1 Lite for prescriptive product motion. Veo nailed the long-axis roll on first attempt with the same prompt that Seedance interpreted three different ways.

Reasoning

Veo handles explicit camera-path instructions in the prompt; Seedance treats motion descriptions as suggestions and defaults to its training distribution.

Alternative Rejected

Kling 3.0 Motion Control. Considered but requires a motion-reference video as input and we had no carrot-knife-rolling stock footage to drive it.

Context

FUSA needed a 360° rotation video and a custom carrot cursor. Both could have been commissioned externally or hand-built (3D model in Blender, hand-rolled SVG).

Decision

Adopt Higgs Field MCP (Soul, Nano Banana Pro, Veo, Seedance, Kling models) as the default first stop for hero video, product imagery, brand marks, and decorative graphics on Rekraft portfolio projects.

Reasoning

The brand-mark refresh, the FUSA rotation video, the carrot cursor, the Damascus detail crops, all came out of Higgs Field in a single working session. Marginal cost is credits, not artist time. Keeps a small studio fast.

Alternative Rejected

Sketchfab/Fiverr commissions for 3D models, real product photography. Both still on the table for projects that need higher fidelity, but Higgs Field is the new default first attempt.

Context

The Dispatch email (daily morning brief) ran via Vercel Cron at 08:00 UTC, reading a pre-distilled `dispatch-brief.json` written by `/shutdown` the previous evening. Two pain points: (1) on days `/shutdown` wasn't run, the email shipped stale data with an amber banner, which Mark didn't want; (2) recipient list still included a personal Gmail (`marksebj.ypr@gmail.com`) that should never have been there.

Decision

Kill the cron, send at `/shutdown`. Emptied `vercel.json` crons, deleted `api/cron/dispatch.js`. Extracted HTML rendering to `scripts/render-dispatch.mjs` (pure function, brief → {subject, html}). Rewrote `scripts/send-dispatch.mjs` as a self-contained sender (reads brief + activity, renders, sends via Resend). Wired into `/sync-launchctrl` as Step 8.5, after `write-briefing.mjs`. Recipient list locked to two addresses (`marksebj@hotmail.co.uk`, `mark.jacob@anotherstar.com`) in code default, local `.env`, and Vercel env (now redundant for dispatch).

Reasoning

If `/shutdown` is the only thing that produces a fresh brief, then sending the email anywhere else just guarantees stale output. Tying email to `/shutdown` makes the silence-on-skipped-days the staleness signal, which Mark prefers over an amber banner. Also fixed a real ordering bug discovered while tracing the data flow: `sync-brief.mjs` was running in `parallel-sync.mjs` Phase B (Step 5) BEFORE `sync-priorities.mjs` (Step 6), so every brief was distilled from yesterday's priorities. Moved to its own Step 7.5 after enrichment.

Alternative Rejected

A morning LaunchAgent on Mark's Mac (would refresh stats before the cron fire). Mark's laptop isn't always on, and adding a cadence adjacent to `/shutdown` re-introduces the staleness problem from a different angle. Server-side cron with a fresh-brief webhook back to the Mac was over-engineered for personal use.

Context

PPM-001 originally treated all maintenance work as a single flow with an "assignee" field. As Phase 3 came together it became clear that in-house engineers, contracted vendors, and external specialists need different gating, different audit trails, and different cascade rules. Collapsing them was forcing branching everywhere downstream.

Decision

Pivot to a three-lane executor model. Schema gained executor-role fields (Phase 1.5 migration `9b810f5`). Cascade generator tags each task with its executor lane (Phase 2 delta `1babb47`). Phase 3.5 UI shipped lane indicators on the Maintenance tab plus a dispatch dialog and vendor form for the vendor lane (`a8a9c07`). Reconciler + backfill script (`24b90a3`) handle existing rows. P1.5-V1 + P2.5-V1 gates passed.

Reasoning

The lanes have genuinely different invariants (vendor lane needs PO + insurance proof; in-house lane uses internal scheduling; external lane is one-off and unscheduled). Encoding that at the schema and cascade level instead of in branching UI keeps the rest of the app simple. The pivot was approved as a planning entry (`a051ccf`) before the schema work started, and validated lane-by-lane with explicit gate checkpoints.

Alternative Rejected

Stick with a single-lane model and add an `executor_type` enum to drive branching in app code, which would have spread the special cases across every consumer of the maintenance pipeline.

Context

Apr 6 design doc proposed an in-browser RAW-to-JPEG converter at `/admin/convert` using the `libraw` wasm library (1.4MB, lived at `public/libraw/`). Idea was to give users a way to convert RAFs locally without Lightroom.

Decision

**Abandon.** Deleted `public/libraw/`, the design doc (`docs/plans/2026-04-06-raw-converter-design.md`), and any orphan recovery artifacts. No `/admin/convert` route was ever created.

Reasoning

The 2026-04-26 stability round confirmed our actual user need is *culling*, not *converting* — we extract the embedded JPEG from RAF for scoring, never the full RAW data. A general-purpose converter is a different product targeting a different need (Adobe DNG converter exists, plus every editor handles RAF natively). Building it would have added 1.4MB of wasm to the bundle for a feature that never shipped and didn't serve the cull workflow.

Context

v2.1 scoring schema had Gemini rate ~13 fine-grained sub-dimensions (`technical.sharpness`, `composition.framing`, `aesthetic.color_harmony`, etc.) AND emit its own `overall_score` (0-100) computed from a 5-dimension weighted rubric the schema didn't capture. Gemini was doing arithmetic in a black box on dimensions it never explicitly rated. Same photo scored 72 vs 81 across runs because the rollup was vibes. Mark also reported a >100 score (460/100) — turned out to be a `× 10` math bug in the prompt formula.

Decision

**Schema rebuild (v2.2):** LLM emits only `reason` + `rubric` (5 integer dims: emotional_impact, light_quality, composition_overall, technical_overall, subject_moment) + `collection_suggestion`. **Server computes `overall_score` deterministically** via `emo×3.0 + light×2.5 + comp×2.0 + tech×1.5 + moment×1.0`. Server derives `tier` (≥80 hero, ≥60 good, ≥40 meh, else reject) and `keep` (hero|good) from that. Plus: temperature 0.1 + seed 42, strict JSON schema with integer min/max bounds, reason field emitted first (G-Eval CoT-then-score pattern), reference anchors block in prompt (95/80/70/50/30/15 exemplars).

Reasoning

Same-photo variance dropped from ~15-pt std-dev to ~2-4 (sampling determinism + schema constraints). The rubric simplification eliminates the arithmetic-in-LLM drift entirely. Hard ceilings (out-of-focus subject → max 25, blown highlights → max 35) move from a separate clause to rubric guidance ("score technical_overall ≤ 2 if subject is out of focus") — the formula then enforces the ceiling automatically.

Alternative Rejected

Keep the v2.1 sub-score schema + just fix the ×10 bug (still leaves the LLM doing rollup arithmetic — fragile). Add explicit rubric dims AND keep all sub-scores (more LLM output surface = more drift). Switch to a more expensive vision LLM like Claude Sonnet 4.6 — research showed 12-30× cost for no defensible win on photographic judgment.

Context

Tier 1 import called `createImageBitmap` + `OffscreenCanvas.drawImage` + `convertToBlob` twice per photo (300px thumbnail + 1024px AI preview). All three are async wrappers but the actual decode + canvas resampling runs on the main thread, so a 188-photo cull would freeze the UI for a perceptible fraction of every iteration. At 1700+ photos the freezes stack into visible jank.

Decision

**Single Web Worker behind a request/response queue** (`worker-pool.ts` + `workers/resize.worker.ts`). `thumbnails.ts` is unchanged for callers — `resizeJpeg` still has the same async signature, just delegates to the worker now. Single worker is enough because Tier 1 is sequential; will expand to a small pool when we parallelise the import loop.

Reasoning

Worker bundling via `new URL("./workers/resize.worker.ts", import.meta.url)` is native to Next.js 16 + Turbopack — no config change needed. Singleton + queue is the right complexity for sequential workload; pool would be premature optimisation.

Alternative Rejected

Process-pool that auto-scales (over-engineered for 188-photo sequential workload). Run resize inline (current pain). Use `requestIdleCallback` chunking on the main thread (doesn't help during the busy decode).

Context

Detail overlay (`PhotoDetailOverlay.tsx`) and editor (`EditorScreen.tsx`) were calling `getJpegFromFile(await sourceFile.arrayBuffer())` per navigation, which materialised the full 40-60MB RAF in memory each time. Rapid arrow-key navigation through 50+ photos accumulated allocations + Blob-URL leaks until Chrome killed the renderer with the "page couldn't load" recovery UI. Tier 1 import already used the right primitive (`extractJpegFromFile(file)` slices ~5MB) but the detail/edit paths never got migrated.

Decision

**Always use `extractJpegFromFile(file)` for any preview-extraction codepath.** It uses `file.slice()` to read only the embedded JPEG (~5MB) after a 100-byte header parse. Never call `sourceFile.arrayBuffer()` followed by `getJpegFromFile(buffer)` in client code unless you genuinely need the entire RAF (you don't, for any current use case).

Reasoning

10× memory drop per navigation. Combined with a cancellation flag in PhotoDetailOverlay's preview effect (guards against object-URL leaks when navigation outpaces async extract), the cull flow no longer accumulates RAM under rapid input.

Alternative Rejected

Full-buffer extraction (the OOM trigger); AbortController-based cancellation of the file read (overkill once reads are 5MB instead of 40MB — the React-state race the cancellation flag covers is the real bug).

Context

A planning pass flagged that `resizeJpeg` in `thumbnails.ts` could be 20-40% faster by passing `{ resizeWidth, resizeHeight, resizeQuality: 'high' }` to `createImageBitmap`, skipping the OffscreenCanvas `drawImage` resampling step. Browser native resize during decode is genuinely faster than canvas resize.

Decision

**Don't do it.** Leave `resizeJpeg` as-is until measured Tier 1 throughput becomes a real bottleneck.

Reasoning

The optimisation requires knowing target dimensions *before* decoding, but the current code reads `bitmap.width/height` *after* `createImageBitmap`. Three options to make it work, all bad: (a) two decodes per image — net loss; (b) parse JPEG SOF markers manually for dimensions — ~30 lines of brittle binary parsing for marginal gain; (c) reorder the Tier 1 loop to extract EXIF before thumbnail and feed dimensions through — touches a lot for a sub-second win at 188-photo scale.

Alternative Rejected

All three approaches above. Re-evaluate only if Tier 1 wall-clock becomes user-visible at 1700+ photo sessions.

Context

Resume restored photos from IndexedDB but left `sourceFilesRef` empty, so the detail view fell back to the persisted 300px thumbnail ("baby thumbnail" UX) and Export had no source files to write. The directory-handle helpers in `db.ts` (`saveDirectoryHandle`, `getStoredDirectoryHandle`, `requestDirectoryPermission`) existed but were never called.

Decision

**Persist the FileSystemDirectoryHandle on import; on resume probe permission state and either silently re-enumerate (granted) or surface a "Re-grant access" banner (prompt/lapsed). Banner click is the user gesture Chrome requires to re-prompt for permission.** Falls through to a fresh `showDirectoryPicker` if the stored handle is gone (webkitdirectory fallback path).

Reasoning

Chrome persists FileSystemDirectoryHandle across reloads in IndexedDB but lapses *permission* across browser restarts. The banner pattern is the standard workaround — the user's click satisfies the gesture requirement without forcing them to re-pick the folder. Resume now functionally equivalent to "keep going" instead of "thumbnail-only mode."

Alternative Rejected

Auto-prompting on mount (Chrome rejects without a gesture). Forcing user to re-import via folder picker every time (works but defeats the resume UX).

Context

PPM-001 needs to generate four linked PPM templates per `(asset_type, country_code)` — annual, quarterly, monthly, weekly — that cite the right legislation and stay internally consistent (weekly items shouldn't contradict the annual master). Council-reviewed three architectures: single prompt emits all four; two calls (annual master → cascade); four independent calls.

Decision

**2-call cascade.** Call 1 generates the annual master with full legislation + SFG20 gating. Call 2 takes the annual master as context and derives quarterly/monthly/weekly. Implemented in `generateTemplateLibrary` orchestrator with shared-types module.

Reasoning

Single-pass produces drift between frequencies — weekly items reference annual sub-checks that don't exist. Four independent calls quadruple cost and lose cross-frequency consistency. 2-call passes the annual as context so cascade frequencies inherit scope. Gemini and DeepSeek converged on (b).

Alternative Rejected

Single-call (drift), four-call (cost + consistency). O3 initially suggested single-call citing latency but retracted after seeing the drift examples.

Context

AI-generated PPM templates cite legislation and SFG20 task codes. Risk: Gemini hallucinates a regulation or cites a repealed one; ops team runs a compliance-critical inspection against a bogus reference. Original plan was a Perplexity verification pass over every generated template before it lands in the library.

Decision

**Skip Perplexity for v1.** Every generated template stores `verified_at` timestamp + `verified_by` user + a visible "AI-generated — verify" badge on the UI. Add a quarterly admin batch refresh to re-verify the library.

Reasoning

Per-generation Perplexity adds cost + latency for a problem that's better solved by making verification visible in the UI (the engineer signing the inspection form is the verifier). Unanimous across O3 + Gemini 2.5 Pro + DeepSeek V3.2 — the surface-then-batch pattern is lower-risk than the per-call verification because Perplexity isn't 100% reliable either.

Alternative Rejected

Per-call Perplexity (cost + false confidence); no verification signal (unacceptable for compliance-critical output).

Context

How are PPM templates scoped — per-asset (one template generation per asset, full de-duplication burden), per-asset-type (shared across orgs, no org customisation), or org-level? The per-asset model means 500 identical boilers in a hotel group each get their own generated + stored template and any regulation change means 500 updates.

Decision

**Org-level library** keyed by `(org_id, asset_type, country_code, frequency)` with a separate `asset_template_overrides` table for per-asset edge cases (e.g., a specific boiler with a non-standard secondary expansion vessel that needs an extra check item).

Reasoning

Templates for "Gas Boiler UK Annual" are functionally identical across an org's 500 boilers — variation lives in the asset's technical specs, not the template text. Org-level lets one regulation update fix the library once. Overrides table handles the 1–2% of assets with non-standard configurations without denormalising. Gemini called per-asset a "denormalization nightmare"; O3 strongly agreed.

Alternative Rejected

Per-asset (denormalisation, N× storage, N× regulation-update work). Per-asset-type global (no org customisation, multi-tenancy leak risk).

Context

A gas boiler in the UK and a gas boiler in Italy share ~70% of the inspection checklist (physical checks, flue, pressure vessel), but differ on the regulatory citations and 20–30% of items (UK: Gas Safety (Installation and Use) Regs 1998; Italy: UNI 10738). Modelled as a single template with a `country_applicability` array, or as cloned templates with a shared `base_template_id`?

Decision

**Clone per country** with `base_template_id` pointer on `inspection_templates` for shared non-regulatory items. Each country gets its own template row with its own full item list; `base_template_id` lets us see lineage for admin reporting.

Reasoning

Single-template-with-applicability-array forces every query to filter by country AND applicability — complex, easy to get wrong. Cloning costs storage but queries stay simple (`WHERE country_code = 'IT'`) and versioning is explicit (UK template can evolve without affecting IT). Unanimous across all 3 models.

Alternative Rejected

Single-template with `country_applicability: text[]`. Rejected because item-level applicability filters bloat every query and make partial-update semantics unclear.

Context

Asset detail page previously had one long scroll with mixed content (overview, technical specs, history, notes). Adding PPM adds more — templates list, generate/regenerate CTAs, inspection history, overdue alerts. Risk: critical compliance info ("this asset's annual inspection is 90 days overdue") gets buried in the scroll.

Decision

**Tabs refactor**: `AssetDetailContent` split into Overview + Maintenance tabs. PPM lives entirely in Maintenance. **Always-visible status chip** (`PpmStatusChip`) at the top of the asset detail page shows inspection state regardless of which tab is active. Maintenance tab label gets a badge (`PpmVerificationBadge`) when verification is pending or something is overdue.

Reasoning

Tabs split conceptual concerns without hiding the load-bearing signal (compliance status). Gemini specifically flagged "don't hide critical info" — led to the top chip that persists across tab switches. Unanimous on tabs + chip.

Alternative Rejected

Single-page scroll (compliance info gets buried). Modal-only PPM view (breaks the "everything about this asset is on this page" mental model).

Context

Migration 021 introduced `rename_submission_prefix(uuid, text)` — a single SQL statement that replaces N per-row UPDATE round-trips when an admin changes a loop's submission prefix. Shipped the route rewrite first and discovered in production that the prefix rename silently half-succeeded: `loops.submission_prefix` UPDATE committed first, then the RPC call 500'd because migration 021 hadn't been pushed to the linked Supabase project yet, and the route returned 500 but the loops row was already changed. Result: settings showed `LTL`, submissions still showed `CIT-*`.

Decision

Any feature that depends on a new DB function MUST (a) try the RPC first, (b) fall back to a pre-RPC implementation on error (regardless of whether the error is "function does not exist" or a real failure), and (c) detect drift on the mutating entity and rollback OR reconcile on failure. Extracted the rename logic into a `renameSubmissionsPrefix` helper that tries the RPC then per-row UPDATEs. The route also reconciles based on actual submission prefixes (not just request diff), so a previously half-successful rename heals on the next save. On ultimate failure, `loops.submission_prefix` is rolled back.

Reasoning

Code on `main` should work against a Supabase project at ANY migration version from the last stable state forward. `supabase db push` is an operator action that happens after code deploys, sometimes much later. Gating feature availability on "did the operator push the migration?" produces drift that's invisible in CI but breaks in production. Graceful degradation keeps the feature working while the optimised path lights up when the migration lands.

Alternative Rejected

Require migrations be pushed before the code change ships. Tried this with migration 019 (photo bucket private) and 020/021 — operator discipline isn't a substitute for code robustness when the cost of forgetting is a half-committed state.

Context

Audit flagged that the `submission-photos` Supabase Storage bucket was `public=true`. Supabase serves public buckets via a CDN path that bypasses `storage.objects` RLS entirely — so anyone who could guess or enumerate a path (loop slug + year-month + per-loop submission counter are all predictable) could read any hotel damage photo without authentication. An earlier migration tightened the RLS read policy but left the bucket public, which is cosmetic because RLS doesn't apply to the CDN path.

Decision

The bucket is private. `photos.url` column now stores `storage_path` (not a rendered URL — signed URLs expire, and we can't cache them in `unstable_cache` keyed lists). Every consumer that renders a photo signs at read-time via `signPhotoUrls(supabase, storagePaths[], ttl)`. TTL default 1 hour — long enough for a page render + natural scroll session, short enough that a leaked link is ephemeral.

Reasoning

The data is guest-adjacent PII (damage photos in hotel rooms). No legitimate flow needs the CDN-path speed win. The trade-off is one extra Supabase API call per page that shows photos, paid on every render instead of cached. Acceptable because dashboard data is the bottleneck, not photo signing.

Alternative Rejected

Keep the bucket public and rely on path unguessability. Rejected — paths aren't unguessable (slug is public, per-loop counters are sequential), and "security through obscurity" isn't a defensible posture for guest-adjacent photos.

Context

Audit found 46 of 66 authenticated API routes missing `export const dynamic = 'force-dynamic'`. Today, Next's `cookies()` call inside `requireAuth` keeps these routes dynamic by side effect — but any refactor that moves auth into a wrapper or removes the cookie read could silently allow the Edge to cache a response and serve it to a different user. Cache poisoning with the current user's data.

Decision

Every authenticated route in `src/app/api/**/route.ts` declares `export const dynamic = 'force-dynamic'` at the top, immediately after imports. Applied to all 46 routes today. Convention added to `CLAUDE.md` as a standing rule. The exception is any route explicitly using `unstable_cache` with tags — those are cached per-key and invalidated on mutation, which is the opposite of "per-user response".

Reasoning

Defence in depth. The cookie-read-implies-dynamic behaviour is real today but load-bearing on a side effect is brittle. Explicit beats implicit when the failure mode is silent cross-user data leakage.

Alternative Rejected

Wrap `requireAuth` in something that forces dynamic internally (e.g. via `headers()`). Rejected because it's another load-bearing side effect, and because the explicit directive at the top of each route is actually informative about intent.

Context

Through-iteration pass on the rekraft.design brand. Structural accent went lime → forest green (rejected as "pastoral") → deep ink blue `#1E2E4A` (approved, "classic Parisian library register"). Italic emphasis colour separately tuned to cherry burgundy `#8B1E2A`. Mark also requested em dashes be stripped sitewide — "I hate dashes." Restructured body copy to use shorter sentences instead of parenthetical dashes; replaced `—` in eyebrows with middle dots (`04 · About`).

Decision

Two rules locked into `CLAUDE.md` for this site. Structural accent is navy `#1E2E4A`, italic emphasis is burgundy `#8B1E2A`, no em dashes anywhere. These are enforced at review time — copy suggestions that introduce em dashes get rewritten before they land.

Reasoning

Visual identity locked so future sessions don't reopen the lime/green/navy debate. Typography rule codified because otherwise it silently drifts — copy generators default to em-dash-heavy prose and the rule has to be applied at every copy pass.

Alternative Rejected

Burgundy as the structural accent. Rejected because thin Instrument Serif strokes can't carry a darker tone as structural colour — reserved for italic emphasis where strokes are larger.

Context

Rebuilt the About section three times today. First around property/FM background (too narrow, abandoned). Then around creative/maker identity — experimented with a portrait-on-circle editorial hero (inspired by 21st.dev MinimalistHero). Mark rejected on the cream theme; reverted to 2-col layout. First rewrite of the 2-col copy leaned too self-deprecating ("hobby grows up", "late-night logos in college") — stripped for credibility register.

Decision

About = 2-col editorial layout with bio on left + stats/credentials on right. Copy leads with credibility markers (`15+ years making / 100s projects shipped / 1 point of view`). Closing line: "Fifteen years in. Still obsessed." Do NOT reintroduce portrait-cutout compositions on the cream theme — tried, didn't work, documented.

Reasoning

"Don't suggest this again" entries are the highest-value ADRs because they prevent loops. The portrait-on-circle idea was seductive from the reference but clashed with the cream/burgundy palette; codifying the rejection stops the suggestion coming back in a future polish pass.

Alternative Rejected

Portrait-on-circle editorial hero (as above). Also rejected: leaning on self-deprecating origin-story framing in the bio — too weak for a positioning that's supposed to win bespoke-studio mandates.

Context

Initial portfolio landed with 14 cases including LousVitton Monogram (featured), Mon3ymotivated, Dare2Dream, Chef Apparel, plus stock Unsplash imagery throughout. Review surfaced: (a) LousVitton is a legally shaky featured piece, (b) Mon3ymotivated/Dare2Dream/Chef are too weak to earn a card, (c) Unsplash reads as a "demo site" when the LLC archive has years of real product photography and artwork.

Decision

Portfolio pivots to real archive assets only, 11 cards (10 real + 1 open slot). Featured piece is now Curmah Joseph's "Dark Paradise" label (21:9 slot). Added Same Same (Off-White parody hoodie) and SJ CyberLife (circuit-board badge). Reviews section updated to drop removed-brand quotes and add Curmah + Same Same quotes. Real per-size iron-on vinyl pricing (`From £3.99`) and custom-sticker pricing (`£6 per A4, buy 10 get 1 free`) + TikTok handle (@livelifecustoms) pulled from the archive pricelist and wired into `WhatWeDo.astro` + `Footer.astro`.

Reasoning

A portfolio site's only job is to read as real. Stock imagery + weak cases + placeholder pricing all undermine that in compound — swapping any one isn't enough. Final register locks in dark-editorial visual identity as the site's signature.

Alternative Rejected

Keep the broader portfolio with stock fills and mark it as "representative work". Rejected — for a single-person custom-apparel brand, "representative" reads as "not actually mine". Real-only with an open slot is more honest and more effective.

Context

Migration 016 introduced per-loop submission prefixes (AMS-0001, TWR-0001, etc.) to disambiguate codes across properties. Original design deliberately kept historical submissions on their old prefix when the admin changed it, on the theory that external references (emails, chats mentioning LQ-0042) shouldn't break. User testing showed the opposite intuition: changing the prefix in settings and then seeing CIT-0001/CIT-0002 still in the submissions list felt broken, not considerate. The mental model is "rename the loop's codes", not "from-now-on use a new prefix".

Decision

When the admin changes `submission_prefix` via PATCH /api/loops/:slug, the route now rewrites every existing submission in that loop in place, preserving the counter portion (CIT-0042 → LTL-0042). Settings UI help text updated to match. External references still line up on the numeric component, which is the salient identifier for humans.

Reasoning

Matches the admin's intuition ("rename applies retroactively") over historical purity. The counter-preservation trade-off means old LQ-0042 → new LTL-0042 retains enough continuity that anyone searching the new value finds the same record. Risk of orphaned external refs is lower than risk of operator confusion staring at two different prefixes in the same list.

Alternative Rejected

Keep historical codes on old prefix. Rejected because the behaviour surprised the user in the first demo rehearsal and required documentation to explain. Also rejected: force the admin to confirm the rename in a modal — unnecessary friction for what is already a low-frequency admin action behind an admin-only route.

Context

Chrome DevTools flagged multi-second INP blocks (1.1s, then 12.4s) on `main.animate-fade-in` elements in the loop layout, org layout, and admin layout. The flagged element was the outer wrapper that contains a tree of streaming Suspense boundaries (dashboard stat cards, trend sections, supplier health grid, etc.). Each time a Suspense boundary resolved during the CSS opacity animation, React reconciled inside a subtree whose compositing was mid-flight, producing paint thrash that the browser measured as blocked UI.

Decision

Do not apply `animate-fade-in` (or equivalent opacity transitions) to any wrapper that contains streaming server components. Animations on user-triggered surfaces (modals, popovers, tooltips, inline status indicators, form-reveal panels) are fine because they don't overlap with initial-paint streaming. Stripped `animate-fade-in` from every layout's `<main>` and every page-level wrapper across loop-scope, org-scope, and admin routes.

Reasoning

Visual polish of a site-wide fade-in isn't worth sub-second interactivity on the critical path, especially during the demo-heavy pilot phase. Per-section animations inside individual Suspense children are still allowed because each one animates in after its own data is already resolved — no streaming overlap. The net UX effect is that pages still feel alive (skeleton → content transitions), just without the wrapper-level fade that costs paint budget.

Alternative Rejected

Keeping the fade and adding `will-change: opacity` for GPU compositing. Still produces a layer promotion + repaint cost per Suspense boundary, not a real fix.

Context

The browser Supabase client crashed production with "Missing NEXT_PUBLIC_SUPABASE_URL environment variable" once a client component (AIInsightListener for realtime toasts) started using it. The helper read `process.env[key]` dynamically; Next.js's build-time replacer only inlines `NEXT_PUBLIC_*` values when referenced via literal property access (`process.env.NEXT_PUBLIC_SUPABASE_URL`). Dynamic index access isn't recognised, so the value stays as a runtime `process.env` lookup — which in the browser is `{}`.

Decision

Always reference `NEXT_PUBLIC_*` env vars via direct literal property access in client-side code, not through a generic `getEnv(key)` helper or any other dynamic indexing. Any wrapper that needs to throw-on-missing should do so after the literal access, not around it. Codified in the `src/lib/supabase/client.ts` comment so the next refactor doesn't reintroduce the indirection.

Reasoning

This is a silent build-time behaviour, not a runtime error that a typecheck or lint catches. The only way to not-reintroduce-it is to document it in the codebase. Server-side code is unaffected (it reads `process.env` at runtime), which is why the bug was dormant until the first client-side caller appeared.

Alternative Rejected

Custom webpack plugin to inline dynamic `process.env[key]` access. Out of scope for this codebase and would hide the brittleness rather than remove it.

Context

TJB Air Conditioning (Rekraft's first paid client site) needed a live URL to show the client and to publish as a portfolio case study, but the real domain (tjbairconditioning.co.uk) DNS hasn't been cut over yet. DNS moves are out of Mark's control — sit with the client's existing hosting/registrar setup and depend on whoever owns that relationship to action the swap.

Decision

Ship client sites to a `<slug>.vercel.app` URL on the Mark J's projects team BEFORE DNS is ready. The case study, the portfolio card, and the client demo all run off the Vercel URL first. DNS swap becomes a separate, later step owned by the client, and the case study/portfolio link updates to the custom domain once cutover happens (or stays on the Vercel URL indefinitely if the client never cuts over — still a shipped, live site).

Reasoning

Unblocks the agency sales conversation and lets the case study land on rekraft.agency the same day the build ships. Rekraft's sales motion depends on having real proof-of-work visible — waiting on DNS creates a dependency on third parties that can stall indefinitely and has no value add beyond a nicer URL. The Vercel URL is fully functional, SSL-terminated, and a legitimate live site; domain polish is the last 1% of shipping, not a prerequisite for it.

Alternative Rejected

Waiting for the real domain before publishing. Would have stalled the case study and the proof-of-work surface on rekraft.agency indefinitely while DNS moves are out of Mark's control.

Context

Rekraft's `/work/` page was a "coming soon" placeholder, and the agency site needed real case studies to convert future prospects. Meanwhile, every client deliverable already produces shippable website content. First draft of a long-form written case study was produced today and Mark's reaction was that no one reads them — the conversion surface has to respect that reality.

Decision

Every client site that ships becomes a case study on rekraft.agency the same day, using a visual-first format: live iframe of the site + short copy + a single outbound CTA, not a long-form write-up. Homepage + `/work/` cards link to the case study. The client-delivery artefact and the agency-marketing artefact are the same artefact, authored once.

Reasoning

Delivery work and sales/marketing surface become the same artefact. Reuses 100% of the client-build effort for lead-gen without adding extra writing time. Visual-first format respects the "not a single person will read it" reality — prospects scan the live site via iframe, see the aesthetic, form a gut-level "can Rekraft build me something that looks like that?" decision in seconds. Short copy + single CTA keeps the page focused on the only action that matters (book a call). Enables Decision 1's deploy-first flow — the same Vercel URL that ships to the client is the iframe source for the case study, so both artefacts go live together with zero extra coordination.

Alternative Rejected

Long-form written case studies. Rejected because no one reads them — Mark said so explicitly today after reviewing the first draft. The effort/reward ratio is backwards: long-form takes hours per case study and converts worse than a 30-second visual scan of the actual built artefact.

Context

/actions landing page showed 1,691 open actions across everyone. Mark's reaction: "i only want my open actions, not anyone else. 300 is outraguous". The default scope was "everyone" even though the dashboard is single-user.

Decision

Default filter changed to `filter=mine`, which matches Mark_J plus common aliases ("Mark", "Mark_Jacob") via a regex that explicitly excludes Marcus/Marius/Marketing. Three chips in scope row: Mine (default) / Mark's directs / Everyone.

Reasoning

Dashboard is Mark's personal intelligence tool; showing 1.7k actions from everyone is inbox-zero-anxiety inducing AND not actually his work. Mine-scope shows 673 open which still surfaces the real backlog. Other scopes one click away preserves the "see what my team owns" signal.

Alternative Rejected

Leaving it at "everyone" + relying on Mark to click through. Friction shows in the data — he'd literally never done it.

Context

Ran a 48-item cleanup on Notion cM Action Items DB (LOL living room, hotel-level interior, Smartsheet admin, scheduling admin, third-party-owned, low-level follow-ups — all below Head of HPM EU level). Notion DB and dashboard bundle both extract from the same meeting summaries but via separate pipelines with different granularities — items don't match 1:1.

Decision

Mirror the cull onto the dashboard by writing `status="dropped"` overrides to Blob (the existing override layer from v1 phase 7). New `scripts/apply-notion-cull.ts` fuzzy-matches Notion items to bundle records by (meeting date ±7d, token Jaccard ≥ 0.30, ≥3 token overlap). Matched 29/48; 19 unmatched because of granularity drift.

Reasoning

The override layer was already designed for exactly this — dashboard-first truth that doesn't touch Notion. Alternative would have been to re-extract from Obsidian meeting notes, which wouldn't pick up a Notion-side archive decision anyway. Fuzzy-match is lossy but preserves the intent.

Alternative Rejected

(1) Adding a separate "Notion-archived" tag to the bundle — premature, only happens on bulk culls. (2) Re-running the Notion pipeline from scratch — doesn't close the actions, just re-extracts them open.

Context

v1.1 Optimization needed to take the dashboard from "force-dynamic on every route" to something that actually uses the edge cache. Options: (A) custom in-process cache keyed by slug (what v1.0 had — lost on every Vercel cold start); (B) `React.cache()` wrapper for per-request dedup; (C) `unstable_cache` from `next/cache` with tags + revalidate; (D) the Next 16 `cacheComponents` flag + `'use cache'` directive. O3 explicitly specified option C with `revalidateTag('vault', 'max')` on mutation in the post-ship advisory.

Decision

Option C. Every getter in `src/lib/data.ts` wrapped with `unstable_cache(readBundleRaw, [slug], { tags: ['vault'], revalidate: 60 })`. Every page exports `revalidate = 60`. `/api/actions/toggle` calls `revalidateTag('vault', 'max')` after a successful Blob write. Two-arg form of `revalidateTag` required by Next 16; one-arg is deprecated.

Reasoning

Option C is the documented Next 16 pattern for projects not using Cache Components. Survives Vercel cold starts (option A did not). Gives both edge-cache persistence across requests and on-demand invalidation via tags. The 60s revalidate window covers sync cadence naturally (nightly 21:00) while the tag-based invalidation makes toggle instantly fresh — stale-while-revalidate serves a result while the revalidation happens in background. `React.cache()` (option B) was subsumed: `unstable_cache` gives both request dedup and cross-request persistence. The `cacheComponents` flag (option D) is a bigger scope change and not yet the recommended path for existing projects.

Alternative Rejected

Option A (bespoke in-process cache) — already failed in v1.0, doesn't survive cold starts. Option B alone (React.cache) — no cross-request persistence. Option D (cacheComponents) — requires opting into a wider migration than v1.1 needs.

Context

The perf audit flagged Recharts (~100KB) and Cytoscape (~300KB) as Perf-P1 for code-splitting via `next/dynamic(ssr:false)`. Once the unstable_cache win landed, this was the next-largest theoretical perf lever. Options: (A) ship dynamic imports for both; (B) ship for Cytoscape only; (C) defer both with a documented rationale.

Decision

Option C. Both deferred to v1.2 with the reasoning written to `.planning/perf-after-1.1a.md`. Recharts: renders on the home page (TopicDrift module is a home section), so dynamic-importing with `ssr:false` would add a loader state without reducing the home bundle byte count — still loads on home, just later. Cytoscape: only loads on `/people` — already route-level code-split by Next, so a per-component dynamic import adds a loader state inside that route without bundle-size win.

Reasoning

Code-splitting is only a win when it moves bytes off a critical path. Here, the heavy libs are already on paths that need them. Adding a dynamic-import dance trades "ship bytes earlier" for "ship bytes later with a visible loader" — a UX downgrade for zero quantitative gain. The honest call is to defer, watch real Vercel Analytics LCP numbers for a week, and revisit if the data shows home LCP hurt by TopicDrift's Recharts load. This also avoids the Next 16 nuance that `ssr:false` only works in Client Components, which would have required extra client wrapper boilerplate.

Alternative Rejected

Option A (ship both) — adds complexity for no measurable win. Option B (Cytoscape only) — still no win because /people doesn't share a bundle with other routes.

Context

Phase 7 original spec was dashboard checkbox → Notion MCP `notion-update-page` → update source meeting page → re-sync picks up. Upon inspection: (1) Tactiq-generated meeting summaries bury action items inside free-text sections with no stable anchor (no block ID, no structured list we can target); (2) Haiku 4.5 extraction isn't byte-stable — re-running against the same page yields semantically-equivalent but textually-different action descriptions; (3) no separate Actions database exists in Notion that could hold canonical state. Writing status back into source pages would therefore either corrupt the transcript or silently detach from it after the next re-extraction. Three options considered: (A) ship write-back anyway (accept corruption + detachment risk); (B) build a parallel Actions DB in Notion first, then write-back to that; (C) pivot to a dashboard-first override layer that doesn't touch Notion at all.

Decision

Option C. Built `cmissionctrl/action_overrides.json` in private Vercel Blob holding status overrides keyed by a stable 16-hex `actionKey = sha256(meetingFilePath + "|" + owner + "|" + desc.slice(0,100)).slice(0,16)`. Data adapter merges overrides into `getActions()` so effective status wins. Dashboard checkbox → `POST /api/actions/toggle` → read-modify-write atomic to Blob. Nightly sync never touches overrides.json. Clear-on-open semantics: status "open" with no note removes the entry. Basic-auth gate via existing middleware.

Reasoning

The extraction pipeline is fundamentally one-way — deriving structure from an unstructured source — so the "canonical source" for action *status* (as opposed to action *text*) doesn't logically live in Notion. It lives wherever the user clicks "done." Keeping that truth in a small Blob file owned by the dashboard sidesteps the byte-stability problem entirely and means zero Notion writes, zero corruption risk, zero sync-loop concerns. The SHA-256 truncated-16 key is stable across re-extractions because `(filePath, owner, desc-first-100-chars)` survives Haiku regen in >99% of cases; the rare key-drift case means an override becomes orphaned and the action reverts to "open" — safe failure mode. Option B (parallel Notion DB) was rejected because it re-introduces the "two sources of truth" problem the whole system was designed to avoid.

Alternative Rejected

Option A (ship write-back anyway) — unacceptable corruption risk on source pages that also carry the transcript. Option B (parallel Actions DB) — duplicates state, doubles the surface area for sync bugs, and Notion is not actually load-bearing for the "is this action done" question.

Context

Starting a new personal work intelligence dashboard for the Another Star / citizenM day job. Input corpus is a Notion database of 360 Tactiq-generated meeting summaries (transcripts + AI summaries) growing weekly. Desired insights: topic drift month-to-month, recurring issues (resolved vs. lingering), most-discussed projects/properties/vendors, cross-meeting action items, people-graph, decisions log, "hot right now" spikes. The killer feature identified in the O3 council consult: **Pre-Meeting Auto-Briefs** that generate a one-pager 60 min before every call.

Reasoning

The guiding principle is "kill the dashboard tomorrow, vault is still intact." Each decision minimises coupling: Notion-as-master means the dashboard is purely derivative; Google iCal URL is a per-user feature that dies only if the user's Google account is deleted (not if IT tightens API policy); hybrid viewer means the MJ Design System aesthetic gets its full expression without Obsidian-plugin constraints; the schema discipline means re-running extraction on a 2028 transcript still yields the same shape. Pre-Meeting Auto-Briefs is the explicit leverage play — it's the only module that turns the dashboard from "thing I look at" into "thing that changes how I show up to calls."

Alternative Rejected

Bidirectional Notion sync (too much state to reconcile for marginal benefit). Apple Calendar SQLite (brittle and sandboxed on modern macOS). Obsidian-only with Dataview tables (can't render the MJ Design System cleanly — will always feel like a note view). Including sentiment analysis (corporate transcripts aren't expressive enough for the signal to beat keyword-delta at a fraction of the compute cost). Slack push for briefs (user hates Slack) — replaced with macOS notification + SwiftBar menu bar app.

Context

`/life` needed an automated way to refresh Apple Health vitals (steps, HR, HRV, sleep, workouts, etc.) — the manual flow was tap "Export" in Health Auto Export → JSON lands in iCloud → `sync-apple-health.mjs` reads it next time `/sync-launchctrl` runs. Three options for automating the phone-side trigger: (A) HAE's "iCloud Drive" automation type → writes per-metric per-day files into nested `AutoSync/HealthMetrics/<metric>/<date>.hae` folders; (B) HAE's "REST API" automation type → POSTs unified `{ data: { metrics, workouts }}` JSON payload to a URL of our choosing; (C) keep manual flow + iOS Shortcut to automate the tap.

Decision

Option B. Built `api/ingest-health.js` as a Vercel serverless function — validates `api-key` header against `HEALTH_WRITE_TOKEN`, persists payload to Vercel Blob (private store `launchctrl-blob`, two keys: `health-metrics.json` + `health-workouts.json`). `sync-apple-health.mjs` extended to `list()` + `get()` from Blob and pick whichever of local-iCloud / Blob is newest. Two automations on phone (Metrics + Workouts) push every 12h. Confirmed end-to-end: Steps, HRV, resting HR populated on `/life` for the first time (were em-dashed for hours under iCloud-file-only flow).

Reasoning

Option A is a non-starter — `.hae` files are Brotli-compressed binary with a `bvx2`/`bvxn` magic header, undocumented format, would require reverse-engineering decoder per metric. Option C works but adds a Mac-as-middleman dependency for what's logically a phone-to-cloud push; also a Shortcut firing the Export button is fragile (silent failures, requires unlocked phone, etc.). Option B has the unified JSON payload that the parser already handles for the manual flow, so it's a drop-in replacement at the data layer with auth + persistence as the only new code. Vercel Blob picked over KV because the access pattern is "latest-payload-overwrites" — Blob's bare-key semantics fit better than KV's append/upsert model and pricing is friendlier for two ~30KB files.

Alternative Rejected

Option A (iCloud Drive `.hae`) — proprietary binary format makes this dead end. Option C (Shortcut automation) — works but keeps the Mac in the critical path and the trigger is brittle. Considered Vercel KV briefly — overkill for two blobs that get fully overwritten.

Context

Both skills previously ended with `gh auth switch --user propsec` on the assumption that PropSec work was the default context after every shutdown. Flagged as wrong — the "correct next account" depends on what you're doing next, not what the skill assumes. Three options considered: (A) remove the switch-back line entirely and let SSH keys handle auth, (B) capture the active account at skill entry and restore at exit, (C) leave as-is and flip default to `marksebj`.

Decision

Option B. Step 12 of `/sync-launchctrl` captures `_ORIG_GH_USER=$(gh api user --jq .login)` at entry, performs the account switch it needs for the git push (`marksebj` for launchctrl), then restores the captured user at the end. If gh isn't installed or no user is logged in, the capture returns empty and the restore becomes a no-op. `/shutdown` delegates Phase 3 to `/sync-launchctrl` so inherits the behaviour automatically.

Reasoning

Skills should be idempotent on auth state — invoke them from whichever account, end on the same account. Removes the "which account am I on now?" mental tax after every `/shutdown`. Safer than Option A because it still works if a future repo uses HTTPS remote (where git push relies on gh's token for the active account). Explicit restore is better than assumption; future debugging is easier when the intended behaviour is in the code.

Alternative Rejected

Option A (remove switch entirely) — clean but fragile: depends on SSH-based remotes forever. Option C (flip default to marksebj) — same fundamental problem as the propsec assumption, just aimed at a different account.

Context

Resend's free tier + default `onboarding@resend.dev` sender could only deliver to one recipient (`marksebj.ypr@gmail.com`), blocking the real targets `marksebj@hotmail.co.uk` and `Mark.jacob@anotherstar.com`. Three options: (A) subdomain of an existing owned domain — `dispatch.propsec.co.uk` or `dispatch.founded.ceo`; (B) buy a fresh personal domain for clean separation (~$12/yr); (C) root domain of an owned TLD.

Decision

Option A with `dispatch.propsec.co.uk`. GoDaddy DNS (SPF MX, SPF TXT, DKIM TXT) added to the propsec.co.uk zone. DMARC deliberately skipped — it would live at the root zone and could affect other email infrastructure on propsec.co.uk; can add a subdomain-scoped `_dmarc.dispatch` later once reputation establishes.

Reasoning

The Dispatch is low-volume (1 email/day, 3 self-recipients) — reputation risk to the PropSec parent domain is effectively zero, while the subdomain inherits PropSec's warm reputation for first-send deliverability. Buying a new domain adds a DNS zone with zero reputation that would need warming. The `dispatch.` prefix is the conventional subdomain for transactional email and keeps the boundary clear.

Alternative Rejected

Option B (fresh domain) — $12 + warming period without a corresponding benefit at this volume. Option C (root domain) — would affect PropSec's actual business email infrastructure via MX record conflicts. Subdomain is the right scope.

Context

looop was on Next 14.2.35 + React 18. Next 15 unlocks streaming with Suspense as the default pattern, Server Actions as first-class, `after()` replacing ad-hoc `waitUntil`, and a cleaner async request API (`params`, `cookies()`). PPR and the `'use cache'` directive are further wins but require `next@canary`. Question was whether to do a full canary upgrade to get everything, or stage it.

Decision

Upgrade to stable 15.x + React 19.x now, get 5 of 7 phases of the upgrade plan (async request API, streaming dashboard, Server Action for onboarding, `after()`, `force-dynamic` cleanup). Defer PPR + `'use cache'` until the codebase has settled on stable for a release cycle, then reassess canary. Streaming refactor is the prerequisite for PPR and is done — flipping `experimental_ppr = true` per route is a one-line change when ready.

Reasoning

Production apps on canary is a commitment (breaking changes in experimental APIs, slower patch cadence for bugs, docs lag). Stable 15.x captures ~80% of the UX win (streaming + server actions) without that commitment. Staging the upgrade also splits risk — if something regresses it's not entangled with a canary-only feature.

Alternative Rejected

Full canary upgrade. Rejected because the marginal benefit of PPR over plain Suspense streaming is a build-time static shell (useful but not transformative) and `'use cache'` is a cleaner `unstable_cache` API, not new functionality. Neither justifies running prod on canary for weeks.

Context

`next-pwa` was installed but only half-wired. It registered a Workbox service worker; separately the app had a `useOfflineQueue` hook storing pending submissions in IndexedDB with manual replay on reconnect. The two never talked. `next-pwa` also has open compatibility issues with Next 15 App Router. Three options: (A) drop `next-pwa`, keep IndexedDB; (B) fully wire `next-pwa` Background Sync to `useOfflineQueue`; (C) switch to a maintained fork like `@ducanh2912/next-pwa` or `@serwist/next`.

Decision

Option A. Removed `next-pwa`. Kept `useOfflineQueue` IndexedDB hook as the entire offline story. Added a kill-switch SW at `public/sw.js` that unregisters the old Workbox SW on any returning PWA client, then deletes itself after a few release cycles.

Reasoning

Real offline submission behaviour was already being handled by `useOfflineQueue`. `next-pwa` was contributing installability (manifest + SW) but no actual value given the manual-replay model, and it added a Next 15 compat risk. Dropping it simplifies the stack (one less dependency, one less SW to debug) without any user-visible regression. Installability lost but not currently a product requirement; can re-add a hand-rolled manifest + SW later if it ever is.

Alternative Rejected

Option B (wire Workbox Background Sync). Would give background-sync-on-reconnect without the app being open, but requires significantly more SW code and testing, and `next-pwa` was the wrong vehicle on Next 15 anyway. Option C (switch to a maintained fork) solves the Next 15 issue but not the underlying "two offline systems that don't talk" problem.

Context

Every `.from('submissions')` call was untyped. Returned `any` / required `as X` casts. `select('*')` was used in 30+ places. Ideal solution is `supabase gen types typescript` from the live DB, but that requires CLI linking which hadn't been done. Options: (A) require `supabase link` before touching anything; (B) hand-write the `Database` type from migrations; (C) ignore typing entirely.

Decision

Hand-write `src/types/database.types.ts` matching the exact shape `supabase gen types` produces (so future swap is drop-in), including all 18 tables, 15 enums, 7 RPCs, and `Relationships: [...]` entries for the specific joins code uses. Wire `SupabaseClient<Database>` into all three Supabase entry points. Add `npm run db:types` script for later authoritative regeneration.

Reasoning

Hand-writing surfaced real runtime/migration mismatches (e.g., `submissions.category` enum doesn't include `'other'` in migration 001 but Zod schema + runtime code do — suggests manual ALTER happened in dashboard that's not captured in migrations). These got flagged as comments in the type file. Every `.eq('status', string)` and `.insert({...})` call is now type-checked; the upgrade caught a genuine bug in `users.name` nullability mismatch between DB and code. The hand-written file is 50-80% of the value of real generated types and unblocks typing immediately; the `db:types` script takes 30 seconds to run when someone's ready to link the CLI.

Alternative Rejected

Wait for `supabase link` (blocks every other improvement on this). Skip typing (leaves huge class of bugs uncaught).

Context

Submissions, insights, knowledge browse used OR'd `ilike '%term%'` scans across 3-4 columns. Not indexed, not ranked, no stemming. Typeahead for products/suppliers already used pg_trgm + GIN indexes from migration 003. Decision was whether to convert everything to FTS or just the keyword-search surfaces.

Decision

Add `tsvector` generated columns + GIN indexes on submissions, insights, knowledge_articles, products, suppliers (migration 014). Weighted A/B/C per field (description > denormalised metadata > submission ID). Four `SECURITY DEFINER` search RPCs using `websearch_to_tsquery` for injection safety. Keep pg_trgm typeahead endpoints on their existing prefix match — FTS tokenises at word boundaries so 2-character prefixes like "wa" wouldn't match "washbasin".

Reasoning

The wrong tool for the wrong job on each surface: FTS is ranked keyword search with stemming, trigram is fuzzy substring/prefix matching. Matching the tool to the use case gets both right. `websearch_to_tsquery` also happens to be the safest user-input parser Postgres offers — accepts quoted phrases + AND/OR/negation without throwing on malformed input, and can't be injected.

Alternative Rejected

Convert typeahead to FTS (breaks short-prefix match). Build a single hybrid endpoint (unnecessary complexity for surfaces with different UX requirements).

Context

launchCTRL needed an autonomous daily morning briefing — a "mission control" email summarizing system status, priorities, activity, and open loops. Had to choose between external scheduler (e.g., GitHub Actions, cron service) vs. Vercel-native, and email provider (SendGrid, SES, Resend).

Decision

Vercel Cron (`vercel.json` schedule) triggering a serverless function at `/api/cron/dispatch`, sending via Resend API. Data sourced from `src/data/*.json` files refreshed by `/shutdown`.

Reasoning

Vercel Cron is zero-infra — no external scheduler to maintain, no separate deploy pipeline. Resend has a generous free tier, simple API, and excellent DX (single API key, no domain verification needed for testing). The serverless function reads static JSON files bundled at build time, so no database or external data fetching at runtime.

Alternative Rejected

GitHub Actions cron → would need a separate workflow, secrets management, and a way to access the built data files. External cron services (EasyCron, cron-job.org) → unnecessary dependency for something Vercel handles natively.

Context

launchCTRL had separate `/priorities` and `/ideas` pages. The nav had 5 links which felt cluttered for a personal dashboard. Ideas and priorities are conceptually related — both are "what to work on next."

Decision

Merged Ideas Pipeline into the Priorities page as a scrollable section below the priority rankings. Removed Ideas from the top nav entirely. Nav reduced from 5 to 4 links.

Reasoning

Ideas inform priorities. Showing them on the same page creates a natural flow: see what's ranked highest, then scroll down to see the pipeline of raw/enriched ideas feeding into future priorities. Fewer nav items = cleaner UX for a single-user dashboard.

Alternative Rejected

Keep separate pages with cross-links — adds navigation friction for no benefit when there's only one user.

Context

Closures (daily shutdown notes) and Decisions (ADR log) were on separate pages. Both are chronological logs that Mark reviews occasionally. Having two separate log pages diluted the nav.

Decision

Merged both into a single `/logs` page with tabbed or sectioned view. Simplified nav to 4 links: Stats | Portfolio | Priorities | Logs.

Reasoning

Both are retrospective reference material, not daily-driver pages. Combining them reduces cognitive load in the nav while keeping all historical context accessible. The merged page can use sections or tabs to separate concerns without needing separate routes.

Alternative Rejected

Drop Decisions page entirely and only keep Closures — loses the ADR format which is valuable for preventing re-litigation of past choices.

Context

Noticed the live `/priorities` page on launchctrl-eta.vercel.app was consistently stale after deploys. Root cause: `scripts/sync-priorities.mjs` had `VAULT_PATH` hardcoded to `/Users/markjacob/...` (wrong username — should be `marksebj`). The script ran on every deploy, silently regenerated `priorities.json` with zero items, and no one noticed because the deploy still succeeded.

Decision

Fixed the path in `sync-priorities.mjs` AND hardened both `/sync-launchctrl` and `/shutdown` skills so priority sync is never silent. After running the script, the skills now must verify: (1) script prints `Synced N priority items` with N > 0, (2) `priorities.json` has a fresh `lastSynced` within the last 5 minutes, (3) `itemCount > 0`. If any check fails, the skill STOPS and reports — it does NOT deploy stale priorities.

Reasoning

Silent failures in automation are the worst kind because "it worked" hides "it didn't actually do anything." The skill had a `node scripts/sync-priorities.mjs` step, but there was no read-back check, so a broken path never surfaced. Verification has to be in the skill, not just the script, because the script already "succeeded" from its own perspective.

Alternative Rejected

Just fix the path and leave the skill unchanged. Rejected because the same class of bug (hardcoded path, silent zero output) could reappear on any environment change, and the skill would happily re-deploy stale data. Verification makes the next failure loud.

Context

Lightbox was auto-uploading all kept photos to portfolio AND auto-creating Instagram content queue items. Mark wanted separation: cull from shoot is different from cull for Instagram.

Decision

Two independent culls. Stage 1 (Lightbox): cull from shoot → keep/maybe/reject folders. Stage 2 (Content Dashboard Pick tab): open keep folder → select for Instagram → add to queue. Portfolio upload stays fully manual.

Reasoning

Not all keepers are portfolio-worthy. Not all portfolio photos are Instagram-worthy. Each stage is a different creative decision. Auto-pipelines remove agency.

Alternative Rejected

Single auto-pipeline from Lightbox → portfolio → content queue. Too presumptuous — removes Mark's curation control.

Context

Photo Editor heal tool originally used OpenCV.js WASM (~10MB) for cv.inpaint(). It loaded slowly, froze the UI, and often failed silently.

Decision

Replaced with simple canvas-based pixel sampling (zero dependencies, instant). Added Clipdrop API as the AI option for generative healing ($9/mo).

Reasoning

OpenCV WASM is fragile in browsers — large download, WASM compilation failures, no error handling. For lens dust spots, local pixel averaging is good enough. For serious inpainting, a cloud API (Clipdrop) gives dramatically better results than browser-side WASM.

Alternative Rejected

Running OpenCV.js in Web Worker with timeout/retry — still fragile, still 10MB, mediocre quality.

Context

Designing the `/shutdown` skill — choosing between conversational prompts vs auto-generated summary

Decision

Auto-generate the entire closure from git logs, session context, and vault diffs. User reviews, doesn't answer questions.

Reasoning

At end of day, cognitive energy is lowest. Asking reflective questions triggers the blank-page problem. Auto-populating from real data then letting Mark review is faster and stickier. Research across Reddit, HN, and productivity literature confirms sub-5-minute rituals have highest adherence.

Alternative Rejected

Guided conversation (2-3 questions like Frenzel's ChatGPT system) — adds friction at the worst time of day

Context

Deciding where daily closure notes should live in the Obsidian vault

Decision

Top-level `Closures/` folder, not under `Areas/`

Reasoning

Closures are a distinct data type (dated accumulating logs), not an ongoing responsibility like Design System or Deployments. Top-level mirrors how `Ideas/` sits as its own pipeline. Cleaner Dataview queries (`FROM "Closures"`). Matches Obsidian community convention for daily/periodic notes.

Alternative Rejected

`Areas/Closures/` — buries them as second-class citizens in a folder they don't belong to

Context

RecipeCam build plan — deciding target platforms

Decision

iPhone only, permanently. No Android version ever.

Reasoning

Target audience (Fuji recipe community) skews heavily iPhone. Native Swift/Metal pipeline gives the best camera performance. No cross-platform abstraction tax. Focus beats breadth for a solo dev.

Alternative Rejected

Cross-platform (Flutter/KMP) or future Android port — adds complexity with no clear ROI for this audience

Context

Choosing the camera app tech stack

Decision

Native Swift stack — SwiftUI for UI, AVFoundation for camera, Core Image CIFilter chains backed by Metal for real-time image processing, Core Data + CloudKit for storage/sync

Reasoning

Live recipe preview at 30fps requires Metal GPU access. CIFilter chains mirror Fuji's X-Processor pipeline model. Core Data + CloudKit gives free iCloud sync. No viable cross-platform path for real-time camera processing at this fidelity.

Alternative Rejected

Raw Metal compute shaders (more control but massive surface area for bugs), third-party image processing libs (GPUImage etc — less maintained, weaker CI support)

Context

Needed a way to consult multiple AI models (Gemini, GPT, Codex, DeepSeek) from within Claude Code

Decision

Use OpenRouter as unified API gateway

Reasoning

Single API key, 500+ models, OpenAI-compatible format, pay-per-use

Alternative Rejected

Direct API keys per provider (too many keys, different formats)

Context

Needed persistent context that survives across all Claude Code sessions

Decision

Structure Obsidian vault as the AI's boot sequence with AIOS_CORE.md as entry point

Reasoning

Already the source of truth, Claude Code can read it, wiki-links create a knowledge graph

Alternative Rejected

Notion (can't be read by Claude Code locally), custom database (overkill)

Context

Planning the Life Dashboard iOS app

Decision

Native Swift stack, not React Native or Flutter

Reasoning

Single-user app, iCloud sync is free and built-in, WidgetKit requires native, no cross-platform needed

Alternative Rejected

React Native (would need a backend for sync), Flutter (no WidgetKit)

Context

Building launchCTRL portfolio dashboard

Decision

Astro 5 instead of Next.js

Reasoning

Zero JS by default, content collections fit perfectly, faster builds, no runtime overhead for a portfolio

Alternative Rejected

Next.js (overkill for static content)

Context

PropSec SaaS and Scaler both need PostgreSQL

Decision

Neon Serverless Postgres with Drizzle ORM

Reasoning

Serverless scales to zero, branching for dev/staging, Vercel integration, Drizzle is type-safe

Alternative Rejected

Supabase (used for looop/Founded, but PropSec needs more control over schema)

Context

Both need auth, database, storage, and real-time

Decision

Supabase (Postgres + RLS + Auth + Storage + Realtime)

Reasoning

All-in-one, RLS for multi-tenant security, generous free tier, good DX

Alternative Rejected

Separate services (too many moving parts for solo dev)

Context

Watched Liam Ottley's AIOS video, recognized PropSec already has the data model for it

Decision

Map the 5-layer AIOS framework (Context → Data → Intelligence → Automate → Build) onto PropSec's roadmap

Reasoning

PropSec has 71 DB tables and 22 modules — richest data model in the compliance space. AIOS layers turn that into a moat.

Context

Multiple projects all need consistent UI

Decision

Single design system with project-specific accent strategies (Warm, Neon, Corporate)

Reasoning

Reduces design decisions per project, ensures brand consistency, speeds up builds