Current OS

Features

• Understory Labs portal added — ⬡ header button (all modes) opens a centered overlay with 3×2 section tiles: Intel, Wiki, Infra, Log, Projects, Home; each opens understorylabs.co in a new tab
• Meal Plan and Shopping collapsed to FABs — removed from the left gravity column, reducing it to three cards (Brief, Tasks/Radar)
• Shed FAB (⌂) added to the bottom-right cluster — opens ProjectsOverlay directly; overlay header renamed PROJECTS → SHED to disambiguate from the Understory Labs /projects link in the portal
• Tasks card gains Radar as a second tab — standalone Radar/Projects gravity card removed; tab state persists to localStorage("tasksTab")
• FAB cluster order finalized: Shed | Shopping | Meal Plan | Recipes | Projects (intake) | Notes

Infrastructure

• Vercel ETIMEDOUT on push-triggered deploy — vercel deploy --prod as manual fallback recovered without re-pushing

Lessons

• "Projects" becomes a naming collision once it appears in two navigational contexts (dashboard overlay and ecosystem portal) — renaming to Shed resolves the ambiguity and makes each thing's purpose immediately clear
• Secondary features that are pure click-targets to overlays are FAB candidates, not gravity card candidates — the gravity column is for content-first widgets, not action launchers
• Tab-merging two single-purpose cards (Tasks + Radar) reduces cognitive load without losing access; the right test is whether both views share the same audience and use moment

Features

• backlog and duplicate project statuses — backlog defers a project without archiving, duplicate closes with a visible label and no data loss
• Both groups collapse by default in the status list — generic expandedGroups Set replaces the previous completedExpanded boolean; any status added in the future collapses automatically if listed in COLLAPSED_BY_DEFAULT
• Multi-image support — project_images table stores photos and schematics per project; Photos section in the detail view with + tile upload and per-image × delete
• First uploaded photo auto-sets image_url card thumbnail; deleting the thumbnail rolls forward to the next photo or clears it

Bug Fixes

• Archive silent failure — archiveProject() had no error check; a failed DB write removed the project from local state but it reappeared on refresh; now reverts optimistic update and surfaces the error
• Negative estimated_hours display — type="number" input accepted negative entry; fixed with min="0" on input and Math.abs() in all display and group sum paths
• Broken image thumbnail — no onError on project card <img>; invalid storage URLs showed the broken image icon; now hides silently via inline style.display = "none"

Infrastructure

• Migration 010 — project_images table (photo/schematic type column, storage_path, RLS mirroring projects access model); projects.status CHECK constraint expanded to include backlog and duplicate
• Migrations 011, 012 — schematic image type and additional column additions applied

Lessons

• Supabase optimistic updates without { error } check create ghost state — UI shows success, failed write reverts on next load; always destructure error from mutations and revert local state on failure
• type="number" inputs accept negative values regardless of semantic context — add min="0" and normalize display with Math.abs() for any field where negative is invalid

TODO

• PI-5 Bug 1 — saveProject() in ProjectIntakeOverlay.tsx never inserts project_resources; steps, materials, and tools save correctly; resources don't
• PI-5 Bug 2 — research service may not be surfacing PDFs (results come back as search/video type); hit Taproot API directly to diagnose before writing code
• n8n timezone check — CT 102 likely running UTC; verify cron schedule alignment with local time (date on CT 102)

Features

• KM-6 intelligence layer complete — meal plan context flows into daily brief (tonight's dinner, defrost reminders)
• Dietary flag warnings in meal plan recipe picker — flagged recipes show ⚠ with hover tooltip listing flags; dietary_flags fetched on all recipe loads including quick-add path
• Preference learning — completeShopping() writes preferred_store back to recipe_ingredients for every checked item that has a source ingredient row; store routing improves automatically after each trip
• AI suggestion upgrade — meal-suggest.ts now labels each recipe fresh or recent (2-week cutoff), includes avg_cost, derives season from weekStart, adds variety/budget/seasonal constraints to prompt

Bug Fixes

• Removed unused CSSProperties import from ShopMode.tsx — Vercel strict build rejected it; local tsc --noEmit did not catch it
• Fixed RecipeSummary type mismatch on quick-add path — dietary_flags and avg_cost missing from select caused build failure on Vercel

Infrastructure

• Migration 009 — price_alerts table; written by n8n price monitor and sale surfacer; indexed for unseen alerts per user
• api/meal-suggest.ts auto-draft sub-action — n8n calls action: "auto-draft" with userId + weekStart; server fetches recipes, runs Claude, upserts meal_plan, clears and rewrites entries and cook events; secured by X-Automation-Secret header
• 4 n8n workflows imported and activated on CT 102: weekly plan drafter (Thu 8pm), price monitor (daily 2am), sale surfacer (Sun 6pm), pantry nudger (daily 8am)
• SUPABASE_URL added to Vercel dashboard — auto-draft sub-action requires it separate from VITE_SUPABASE_URL
• N8N_BLOCK_ENV_ACCESS_IN_NODE=false added to n8n docker-compose — required for $env access in Code nodes
• AUTOMATION_SECRET shared between Vercel and n8n — n8n docker-compose env var, Vercel dashboard env var, Vaultwarden entry

Lessons

• Vercel's strict TypeScript build catches errors local tsc --noEmit misses — always treat a passing local check as necessary but not sufficient
• The 12-function Vercel hobby limit is a real architectural constraint — sub-actions on existing functions (auto-draft in meal-suggest, costco-lookup in shopping-generate) are the right pattern; adding files is not
• n8n Variables is a paid feature; Docker environment variables with N8N_BLOCK_ENV_ACCESS_IN_NODE=false is the self-hosted equivalent — same $env.VAR syntax in Code nodes
• Heredocs reliably fail in LXC consoles and sometimes in PowerShell — scp a locally-written file instead of trying to write multiline content via paste

TODO

• Bud RecipeHandler — recipe email ingestion via n8n Gmail trigger; build in bud project session
• n8n timezone check — container runs UTC; verify Thu 8pm schedule aligns with local time (date on CT 102)
• Kroger production API approval — currently on Certification sandbox; apply when ready for real prices

Features

• Kitchen Module brainstormed and planned — 7-step plan covers recipe management, AI meal planning, batch cooking, pantry tracking, store-routed shopping lists (Kroger + Costco + Amazon), mobile /shop route, cost-per-recipe historicals, and n8n automation
• Recipe URL import — two-pass extraction: Schema.org JSON-LD first (zero AI cost on major recipe sites), Claude Haiku fallback for sites without structured data
• Conversational recipe intake — multi-turn Sonnet conversation builds a full recipe from natural description; auto-drafts when readyToDraft is true, manual trigger available after 2+ rounds
• Dietary flag scanning — soy derivatives and pea protein watchlists enforced at both import paths; soy-containing ingredients flagged inline during conversational flow
• RecipesOverlay — full overlay with list, detail, URL import, conversation, review/edit, and manual entry phases
• Recipe access wired into both shells — ⊛ FAB at bottom-right in DashboardShell, Recipes button under KITCHEN section in MobileShell More tab
• Kroger developer account registered — Certification environment, Products + Cart API products; Production approval is a separate step

Infrastructure

• Migration 003 — recipes and recipe_ingredients tables with RLS; soft delete (deleted_at); dietary_flags and tags as TEXT[]; source_type constrained to manual | url-import | conversational | email
• ISO 8601 duration parser — PT1H30M → 90; handles hours-only and minutes-only variants
• Schema.org extractor handles @graph arrays, root arrays, and direct Recipe objects — covers all major recipe site structural variants
• Markdown fence stripping on all Claude API responses — both handlers strip ```json wrappers before JSON.parse

Lessons

• Schema.org JSON-LD is reliable and free on major recipe sites — Haiku fallback is the exception, not the rule
• Dietary awareness needs two enforcement layers: prompt-level (inline warning during conversation) and data-level (scanner on all ingredients at save time) — one layer alone can be bypassed
• Store routing follows each platform's natural access point — Kroger has a developer API, Costco has a web interface, Amazon has direct search URLs; forcing a uniform integration pattern onto all three would be the wrong abstraction
• scrollIntoView() on nested scroll containers scrolls all ancestors — fixed by targeting containerRef.current.scrollTop directly on the specific chat div

TODO

• Apply supabase/migrations/003_kitchen_module.sql in Supabase SQL Editor before testing
• Test URL import with 3–5 real recipe URLs; test conversational flow with 2–3 meals
• KM-2: Meal Planning — meal_plans, meal_plan_entries, cook_events schema + MealPlanOverlay weekly grid

Features

• CLAUDE.md reduced from 546 to 115 lines — detailed specs extracted into five focused docs under docs/
• docs/architecture.md — full subsystem specs: gravity layout, items table, triage, capture, mobile, PWA, AI intake engine, context engine, home projects, AI API, infra principle, and component file map
• docs/phases.md — all phase completion tables (MVP through PI-6) and plan/vision document links consolidated in one place
• docs/widgets.md — per-widget behavioral specs: Calendar, Week, NowPlaying, Queue, Lyrics, Affirmations, DailyBrief, Lists
• docs/effects.md — breathing glow rAF loop, title line glow, header spark, ambient canvas, WidgetCard two-div structure
• docs/aesthetic.md — palettes, 3-tier font system, card/button specs, mode treatments, Cybernetic Nature direction
• CLAUDE.md now uses a manifest-style reference table with "read before..." triggers — lean index loads each session, detail files read on demand

Infrastructure

• Peer reference updated — ClaudeVault decommissioned; brother replaced full FastAPI + PostgreSQL + Redis app with declarative YAML manifest approach (same pattern as agent.yaml in everything-claude-code)
• Global CLAUDE.md: background agent Write restriction documented in Known Environment Patterns

Lessons

• Monolithic CLAUDE.md loads into every session regardless of what's being touched — modular docs eliminate noise; a background task on animations shouldn't carry 200 lines of phase history
• The manifest pattern (declarative index + "read before..." triggers) is the right abstraction — same principle as agent.yaml in ECC: discovery surface without runtime overhead
• Background agents spawned with run_in_background: true can't Write new files — permission is restricted; all new-file creation goes in the main session thread
• everything-claude-code evaluated and declined — 183 skills, most for stacks not in use, overlaps heavily with custom setup; valuable as a pattern reference, not an install target

Features

• PI-5 complete — draft generation now injects ingested manual chunks into the intake prompt as a ## Manufacturer Instructions block; steps from the manufacturer's sequence are labeled (from manual), AI additions labeled (AI-supplemented)
• api/_lib/taproot.ts established as the shared Taproot client — getChunks(projectId) fetches all cached chunks with 8s timeout, returns [] on failure so Taproot downtime never blocks draft generation
• Generate Plan button is now disabled while any resource is ingesting — "wait for ✓ before generating" message appears below the button so the user can't race ahead of the chunk pipeline
• Owned materials now display $0 in the price field instead of a strikethrough estimate — original price is preserved in state and restored if ownership is unchecked
• Validation product references updated throughout both PI plan files — Ring doorbell replaced with Aqara Video Doorbell G4, "pergola kit" replaced with Mirador 10x13 Louvered Pergola

Bug Fixes

• Skip disclaimer only fired on one of two skip paths — researchDecision === 'skipped' (Skip before research runs) and resourceApproval === 'skipped' (Skip after resources are found) are separate state variables; both must be checked
• Vercel build failed with TS2835 on the _lib/taproot import — moduleResolution: nodenext in Vercel's API tsconfig requires explicit .js extension on relative imports even when the source file is .ts
• api/ingest.ts was complete from a prior session but uncommitted — included in the PI-5 commit

Infrastructure

• api/_lib/taproot.ts — new shared helper file; Vercel treats _lib/ as private (no route exposure)
• ingestProjectKey threaded from ProjectIntakeOverlay into api/project-intake.ts request body — the temp UUID minted at resource-approval time is now the lookup key for chunk retrieval
• Chunk injection capped at 30 chunks with a truncation note to prevent prompt bloat on large manuals

Lessons

• Vercel's API tsconfig uses nodenext module resolution, which requires .js on relative imports — tsc --noEmit locally won't surface this; it only fails in the Vercel build pipeline
• Two separate state variables controlling the same logical outcome (resource skip) is a footgun — a future refactor should unify them into a single resourceDecision enum
• Disabling the action button during async pre-work is strictly better than a post-hoc warning — the user can't accidentally proceed, and the system state is always coherent when the button re-enables

TODO

• Validate PI-5 checkpoint against Aqara Video Doorbell G4 and Tuff Shed — steps should carry (from manual) labels and reference actual manual content
• PI-6: Build Companion API (api/project-companion.ts) + UI (Companion tab in ProjectsOverlay, FAB on mobile)

Features

• Bud vision brief complete — inbox intelligence system powered by n8n on Taproot with six handler types: purchase, coupon, delivery, appointment, reference, triage
• Cross-agent orchestration scoped — Bud feeds Current OS (tasks, radar, triage), Shed (project materials), Research API (product intelligence), Google Calendar, and a financial dashboard
• Name locked: Bud — dormant potential waiting to open, "nip it in the bud" for early problem detection, BUD inside BUDGET, buddy personality
• Standalone project — own repo, own LXC on Taproot, financial dashboard linked from Current OS under a broader domain TBD

Bug Fixes

• ISSUE-011: WeekWidget "This Week" card now auto-focuses when Work toggle activates — GravityWatcher gained a workVisible transition watcher that calls focusCard("week") on the false → true edge

Lessons

• Brainstorms should surface established self-hostable tools (n8n, Node-RED) before custom-build options — n8n was the obvious fit for email orchestration but had to be raised by the user
• Naming requires the design brief as input — two rounds failed before consulting the redwood forest ecosystem aesthetic
• Humble name for sophisticated tech (Shed, Bark, Bud) is the Understory Labs signature — the contrast IS the brand

TODO

• /plan on Bud — purchase handler first, end-to-end through n8n
• Cross-agent protocol design — how Bud, Shed, and Research API communicate
• Confirm ISSUE-011 fix after testing

Features

• Product detection lands in intake engine — product_assembly_detected inference fires when AI identifies a specific kit or product, readyToResearch flag signals the UI to offer research before drafting
• Research service deployed on Taproot — research.rootstack.dev live, returns ManualsLib results + YouTube search URL + DuckDuckGo fallback for any product query
• Resource approval UI complete — "Resources Found" section in observations panel with type badges, checkboxes, Add your own URL input, and three explicit degradation paths when Taproot is unreachable
• Ingest pipeline written — /ingest endpoint downloads PDFs and HTML, extracts text, chunks by step-pattern → headings → 500-token windows, stores to ZFS cache under a temp project key
• Per-resource ingest status in intake overlay — loading / done (chunk count) / image-only-warning / error badges fire immediately on resource approval, non-blocking

Bug Fixes

• Research fetch moved out of useEffect — cleanup function was aborting the in-flight request the moment researchStatus changed from idle to loading, causing an immediate AbortError
• @vercel/node import removed from api/research.ts — Vercel infers the runtime; explicit import broke the build
• Type assertion added for manual resource entry — TypeScript couldn't narrow the type field on user-pasted URLs

Infrastructure

• api/research.ts — Vercel proxy with 10s timeout, forwards to TAPROOT_RESEARCH_URL with x-api-key auth; RESEARCH_API_KEY never exposed to the browser
• api/ingest.ts — second Vercel proxy, 25s timeout for PDF downloads
• project_resources.source column added — distinguishes ai-discovered from manual resources; feeds the future manual library
• src/cache.js, src/ingest.js, src/retrieve.js written in ~/Projects/homelab/services/research/ — BM25-lite keyword retrieval, ZFS-backed chunk storage
• PI-4 not yet deployed — ZFS bind-mount into docker-host (requires CT stop) and service rebuild are the next physical steps

Lessons

• Chunking strategy order matters — trying numbered steps first (assembly manuals are full of them) before generic heading detection before token windows produces far better chunks than the reverse
• ingestProjectKey needs to be a temp UUID minted at resource-approval time, not the Supabase project ID — the project doesn't exist yet when ingestion kicks off; PI-5 will wire the linkage
• Explicit degradation beats silent fallback — presenting four named choices when Taproot is unreachable is only slightly more code and completely changes the user's ability to recover

TODO

• Deploy PI-4: ZFS dataset on Proxmox host → bind-mount into CT 100 → rebuild research service → push Vercel changes
• Validate PI-4 checkpoint: ingest a real Ring doorbell PDF, confirm /retrieve returns relevant sections
• PI-5: inject approved chunks into api/project-intake.ts draft prompt using ingestProjectKey

Bug Fixes

• Compressed project intake photos client-side (max 1200px, JPEG 85%) before base64 encoding — full-res phone photos exceeded Vercel's 4.5MB serverless body limit, returning HTTP 413.

Infrastructure

• Linked .vercel project config locally — pre-push deploy hook now works for life-automation on this machine.

TODO

• api/project-intake.ts lines 426–444: pre-existing TypeScript errors — property access on unknown type from JSON parse. Not blocking (build deploys), but should be fixed.

Features

• Gravity layout system complete — cards size themselves by focus state, dashboard adapts to any height without manual resizing
• GravityContext: three card states (focused / resting / collapsed), max 2 focused per column, oldest-first demotion, 60s auto-focus cooldown, localStorage persistence
• GravityCard render-prop pattern: widgets receive variant: 'focused' | 'resting' and render purpose-built compact views at rest — not shrunken full views
• GravityColumn: narrow prop collapses dual-column layout to a single scrollable column below 900px
• NowPlaying pinned at top of right column — always visible, no title bar, no collapse
• Mode system simplified: "online" | "offline" + workVisible boolean replaces the three-mode system
• Work toggle: header pill swaps accent to teal without changing the environment — data-mode="online-work" inherits pine-forest base, overrides accent only
• GravityWatcher: auto-focus signals wire morning→brief, music starts→lyrics, item captured→tasks

Bug Fixes

• LyricsGravityCard and QueueGravityCard never called registerCard — focusCard("lyrics") was a silent no-op, persistence and focus limits broken for both

Infrastructure

• DashboardShell reduced from ~1094 lines to ~400 — all grid infrastructure (MODE_LAYOUTS, getRows, GridResizeOverlay, expandedCards, rowOverrides) removed
• /gravity-test route added for layout testing without auth

Lessons

• Wrappers around non-GravityCard components need explicit registerCard in a useEffect — skipping it is a silent failure with no error, just no behavior
• Keeping the environment (pine-forest base) while swapping only the accent makes the work toggle feel like a lens over personal space, not a separate room
• GravityProvider must sit outside key={mode} — state reset on mode switch is the wrong default for a layout system

Features

• /start skill now surfaces the full unworked feature backlog at session open — deferred candidates, wishlist items, and open design questions pulled from memory and design-notes
• Backlog section grouped into "Ready to plan" and "Wishlist" with a pointer to /scope for details

Bug Fixes

• Online mode on weekdays no longer reports 8am–5pm as personal free time — reserveWorkBlock parameter added to computeDayContext in the context engine
• DailyBriefWidget, RadarWidget, and the AI context string all respect the work block — eligible items, day weight, and suggestions now reflect morning/evening availability only
• RadarWidget now mode-aware via useMode() — eligibility recomputes on mode switch
• ISSUE-008 closed — all three sub-items resolved across two sessions

Lessons

• The context engine grid (8am–6pm) only sees 1 hour of personal free time after a 9-hour work block — the heuristic naturally suppresses discretionary items on weekdays, which is the right behavior
• A default parameter (reserveWorkBlock = false) kept the change backward-compatible without touching every existing call site

Bug Fixes

• ISSUE-006 confirmed resolved — committed items not surfacing in TaskListWidget was caused by RLS infinite recursion on the projects SELECT policy, fixed in a prior session
• ISSUE-007 confirmed resolved — work tasks disappearing after mode switch was the same root cause: fetchTasks joins items → projects(title), triggering the same recursion; optimistic insert appeared to succeed but every re-query returned null, making persistence look broken
• ISSUE-008 (sub-problems 1 + 3) — DailyBriefWidget lacked mode awareness entirely; weekday tasks query had no mode filter, leaking work tasks into the Online brief
• Brief cache key was current-os-facts-{date} — shared across modes; switching Online → Work reused cached Online facts; key is now current-os-facts-{mode}-{date}
• "Work availability" label in the AI context string renamed to "Available time" — was mode-biased in Online brief context

Infrastructure

• DailyBriefWidget now uses useMode() — tasks query always filters by mode, AI context hint is mode + weekend aware across four combinations
• ISSUE-009 resolved — four "Project member reads X" SELECT policies in live DB updated via Supabase SQL Editor to use is_project_collaborator() instead of inline subquery; migration file synced to match

Lessons

• A single circular RLS policy (projects → project_collaborators → projects) silently killed every query that joined to projects — the join itself was the trigger, not the query result; two distinct-looking bugs shared one root cause
• Mode awareness needs to be explicit at every data boundary — a missing useMode() import left the brief entirely uninformed about which context it was writing for
• DDL statements in Supabase (DROP POLICY / CREATE POLICY) return "no rows" on success — expected behavior, not an error

TODO

• ISSUE-008 sub-problem 2 remains: planning overlay work block reservation (8am–5pm M–F in Online mode) — requires reserveWorkBlock flag in computeDayContext so freeHours reflects evening/morning personal time on weekdays

Bug Fixes

• Half-screen scroll restored — overflow-hidden on <main> was clipping the stage at ~540px; replaced with overflow-y-auto and added minHeight: 640px to the grid wrapper so fr rows have a usable definite height
• Stale closure in TaskListWidget items-changed handler fixed — handler was capturing a stale loadTasks reference; useRef + useCallback pattern ensures the latest version is always called
• RLS infinite recursion (42P17) resolved — projects SELECT policy queried project_collaborators, whose policy queried projects, creating a deadlock loop on any query joining projects (e.g., items → projects(title))
• Fix: is_project_collaborator() SECURITY DEFINER function queries project_collaborators directly, bypassing its RLS and breaking the cycle; projects SELECT policy updated to use it

Infrastructure

• Diagnostic logging added to commitToToday and TaskListWidget committed items SELECT to surface silent failures during investigation
• supabase/schema.sql synced to match live RLS fix — is_project_collaborator() function and updated project table policies now reflected in source of truth
• Committed items moved above regular tasks in render order — visible without scrolling

Lessons

• RLS policies that reference each other's tables form recursion cycles invisible until a cross-table query hits them — SECURITY DEFINER functions break the loop by querying at the function owner's privilege level, not the caller's
• Silent count=0 failures are harder to diagnose than errors — adding a read-back SELECT after an update immediately surfaces whether the write landed

TODO

• Confirm ISSUE-006 fully resolved — RLS fix is applied, but committed items behavior not yet user-verified in live session
• ISSUE-007: work tasks disappear after mode round-trip
• ISSUE-008: work/personal data leaking between modes in daily brief + planning overlay

Features

• Shed (Home Projects) feature complete — AI-powered home project tracker inside Current OS
• Project intake form with scope, phase, materials, and priority fields
• Projects overlay renders active projects with status and last-updated indicators
• AI scheduling integration — projects surface in prioritization context

Bug Fixes

• Project intake overlay z-index conflict with calendar resolved
• Phase label display corrected for multi-phase projects

Lessons

• Keeping features namespaced (Shed, not just "projects") helps maintain mental boundaries in a large app
• AI-aware data models pay off immediately — fields added for AI context during intake proved useful in first scheduling run

Features

• Intelligence Foundation phase complete — AI scheduling layer operational
• Event correction pipeline: Claude reviews raw calendar events and normalizes titles, durations, and categories
• Lifecycle tracking: events now carry state (raw, normalized, scheduled, completed)
• Normalization runs on ingest — events are clean before they hit the scheduling engine

Infrastructure

• Supabase schema extended with lifecycle_state and normalized_at columns
• Correction pipeline runs as a server action triggered by calendar sync
• Idempotent design — re-running normalization on already-normalized events is safe

Lessons

• Treating AI output as a suggestion layer (not a replacement for original data) made corrections reversible
• lifecycle_state as an enum column gave clearer audit trails than boolean flags
• The hardest part of AI pipeline design is deciding what "done" looks like for a given event — encoding that as a state machine helped