# Home Tab Design Spec — Manage App Personal Dashboard

> Design spec for adding a "Home" tab to the manage app that serves as Sam's personal hub for tasks, quick links, and notes. No code changes here — Sam reviews the spec, build happens in a future session.

## Project context

- Kind: personal-project (design / architectural)
- ID: home-tab-design-spec-2026-05
- Created: 2026-05-11
- Primary actor: Sam Foran
- Status: spec draft — ready for review
- Build trigger: review + approval; estimated post-Pittsburgh trip

---

## 1. Goal and motivation

Sam uses the `/manage` app constantly on phone. He wants a single always-available place inside that app for personal tasks, links to substrate research projects, and freeform notes — eliminating the friction of downloading HTML files, editing markdown, or routing through chat sessions every time he wants to capture a thought or check a list.

The Home tab is Sam's dashboard hub. It's interactive (add/check/delete tasks, click links, type notes). It's not a research deliverable — it's a working surface.

**Why this is worth building:**
- Sam already opens `/manage` multiple times per day. Adding a personal hub there is zero net friction.
- Markdown files and downloaded HTML don't update in real time and aren't reachable from his phone without effort.
- The "ask Claude / wait for output / download / save" loop is too slow for capture-as-you-go tasks.
- Owning the data in the manage app's existing localStorage + Firebase sync model means it's reachable from any device Sam logs into.

---

## 2. Tab placement and naming

**Recommendation: first tab, named "Home", default landing on app open.**

- Currently the nav order is: Dashboard, Estimator, Customers, Work, Invoices, Quotes, Expenses, Reports, Knowledge.
- "Dashboard" is the current default landing — it shows business stats (paid/owed/outstanding). Sam looks at this less often than he'd look at his personal hub.
- Sliding "Home" in as the first tab and making it the default landing matches the "always-available personal surface" intent.
- Alternative names considered: "Hub", "My Stuff", "Personal". "Home" wins on familiarity (universal app convention) and signals that this is Sam's own surface, not a business view.

**DECISION NEEDED**: should Home be admin-only, or visible to all roles (customer portal, household)? Recommendation: **admin-only**. The Home tab is Sam's personal surface; customer/household roles continue to see their existing portal views with no Home tab in nav.

---

## 3. Phase 1 sections (minimal MVP)

Three sections, each independent, each rendering as a card on the page.

### 3a. Today's Tasks

Interactive checkbox list. Sam can:
- **Add** a task — single text input + Add button. Adding focuses the input again for rapid entry.
- **Check** to complete — tap checkbox; completed tasks visually de-emphasize (strikethrough, fade).
- **Edit** — tap the task title to inline-edit. Save on blur or enter.
- **Delete** — small × button per task; soft delete (moves to archive view, recoverable for ~30 days).
- **Optional notes** — expandable below task title, for "I want to remember WHY".
- **Optional due date** — tap to add a date picker; tasks with past-due dates render with red accent.
- **Optional category tag** — free-text small label (e.g., "biz", "home", "tax"); colored chip rendering.

Task fields:
```
{ id, title, notes, dueDate, category, completed, created, updated, archived }
```

Default view: open (uncompleted) tasks first, then completed today, then "show archive" link.

**The friction point is adding tasks.** Add input should be the most prominent UI element — large, single-line, persistent at top of the section. Adding should be one tap to focus, type, hit return.

### 3b. Quick Links

Visual cards linking to:
- Substrate projects (e.g., metal-3dp landscape overview, SW paint walk-in sheet, pirates-phillies print guide)
- Frequently-used external URLs (substrate root, GitHub, Cloudflare dashboard, samesolutionsllc.com, /manage Billing)
- Anything else Sam wants on a tap

Card fields:
```
{ id, title, url, description, icon, color, order }
```

UI:
- Grid on desktop (3-4 columns), stack on mobile (1 column).
- Each card: icon/color tag at top, title, optional 1-line description, URL preview small at bottom.
- Tap card → opens URL in new tab.
- Edit mode (gear icon top-right of section): drag to reorder, edit, delete, add new.

Initial seeded entries (suggested):
- Substrate root: https://samesolutions-equipment-service.pages.dev/
- Metal 3DP landscape: https://samesolutions-equipment-service.pages.dev/personal/metal-3dp-business-exploration-2026/landscape-overview
- SW paint walk-in: https://samesolutions-equipment-service.pages.dev/personal/sw-bulk-paint-order-2026-05/walkin-sheet-v2
- Pirates print guide: https://samesolutions-equipment-service.pages.dev/personal/pirates-phillies-3d-print-2026-05/print-guide
- Manage Billing: /manage#billing (in-app link)
- Manage Knowledge Base: /manage#models (in-app link)

### 3c. Free Notes

Single freeform text area. "Things to remember."

- Textarea, full-width, auto-grow with content.
- Saves on blur (no explicit save button).
- No formatting — just plain text. (Markdown rendering is Phase 2.)
- Single shared note, not multiple notes. (Multiple notes is Phase 2.)

This is the "I need to remember to ask Jon about the gate" surface. Tasks are too structured for half-formed thoughts; Free Notes catches them.

---

## 4. Data model proposal

### Where data lives

Extend the existing `data` object in localStorage with a `personalHub` key.

### Schema

```js
data.personalHub = {
  tasks: [
    {
      id: 'task-<timestamp>-<short-random>',
      title: 'string',
      notes: 'string',        // optional, default ''
      dueDate: 'YYYY-MM-DD',  // optional, default null
      category: 'string',     // optional, default ''
      completed: false,       // boolean
      created: 'ISO-string',
      updated: 'ISO-string',
      archived: false         // soft-delete flag
    }
  ],
  quickLinks: [
    {
      id: 'link-<timestamp>-<short-random>',
      title: 'string',
      url: 'string',
      description: 'string',  // optional, default ''
      icon: 'string',         // emoji or icon class, default ''
      color: 'string',        // hex, default '' (uses brand gold)
      order: 0                // sort index
    }
  ],
  notes: ''                   // freeform string, default ''
};
```

### Migration

New DATA_VERSION 18 migration adds `personalHub` key with empty defaults:

```js
if (fromVersion < 18) {
  if (!data.personalHub) {
    data.personalHub = {
      tasks: [],
      quickLinks: [],  // optionally seeded with default links — see Section 3b
      notes: ''
    };
  }
}
```

Idempotent. No data loss for existing installs.

### Firebase sync

- **tasks and quickLinks**: sync to Firebase (so Sam can edit on phone and see on desktop).
- **notes**: also sync, treated like a single shared document. Last-write-wins on conflict (timestamp comparison).
- Sync follows existing Firebase patterns in the manage app; no new architecture needed.

**DECISION NEEDED**: Phase 1 — localStorage only, or include Firebase sync immediately? Recommendation: **localStorage only in Phase 1**. Sam's primary usage is one device at a time anyway. Firebase sync is Phase 2 once core UX is validated. Saves 1-2 hours of build time and one source of complexity in v1.

---

## 5. UI design considerations

### Mobile-first

Sam uses phone primarily. Design the mobile layout first; desktop is a "responsive enhancement" not the canonical view.

- Tab bar at bottom or top (matches existing manage app pattern — top, horizontal scrolling).
- Each section card stacks vertically.
- Add-task input fixed at top of Today's Tasks section for thumb reach.
- Tap targets ≥44px tall (iOS Human Interface Guidelines).

### Brand colors

- Black `#101820`, gold `#FFB612`, white, brand grays.
- Use existing CSS custom properties (`var(--black)`, `var(--gold)`, etc.).
- Use existing utility classes from `manage/utilities.css` (`.card-neutral`, `.row-between`, `.flex-grow`, `.mb-2`, etc.) — no new CSS for primitives.

### Patterns

- **Card layout**: each section is a `.card-neutral` or similar.
- **Add task button**: prominent, brand gold, big tap target. Recommend `class="btn btn-primary w-full"` or similar.
- **Checkbox pattern**: tap-to-complete (not swipe). Swipe is harder to discover on web; tap-checkbox is universally understood.
- **Completed task visual**: strikethrough title, opacity 0.5, sort below open tasks.
- **Past-due task visual**: red left border (`.card-danger` or a 4px red border-left).
- **Quick Link card**: hover/tap state with subtle lift; gold left border on hover.

### Friction points to optimize

The single highest-friction point is **adding a new task**. Make it:
1. Visible at all times (don't require a modal).
2. One tap to focus (autofocus on tab load? Maybe too aggressive — discuss).
3. Submit on Enter; refocus the input for rapid sequential entry.
4. No required fields beyond title.

If adding takes more than 3 seconds for the median case, the feature failed.

---

## 6. Phase 2 future considerations (not built in Phase 1)

- **Auto-population of Quick Links from substrate folder structure** — index/personal-project/*.md entries → automatic Quick Links cards. Removes manual link curation.
- **Research chat status integration** — show "Active chats" or "Last handoff" timestamp per substrate project. Requires substrate metadata Sam doesn't currently maintain.
- **Calendar / upcoming deadlines integration** — pull from substrate HARD DEADLINES or PLANNER.md, render due-soon highlights in Today's Tasks.
- **Claude Code-writable task API** — Firebase admin SDK or similar so AI chats can add tasks for Sam ("research chat finished metal 3DP demand analysis, log a task to read it"). This is the most powerful integration; it's also the most complex (auth, rate limits, idempotency).
- **Notifications / reminders** — browser push or email when due dates approach. Out of scope for v1.
- **Multiple notes / notebooks** — beyond single shared freeform note.
- **Markdown rendering in notes** — render `**bold**` `*italic*` etc.
- **Search across tasks and notes** — useful at 50+ tasks; premature at 5.
- **Export / archive view** — see all completed/archived tasks; bulk delete; export to JSON.

---

## 7. Risks and decisions to make

### DECISION NEEDED — localStorage vs Firebase in Phase 1

Recommendation: **localStorage only in Phase 1**. Add Firebase sync in Phase 2. Rationale above.

### DECISION NEEDED — task deletion: soft or hard

Recommendation: **soft delete with 30-day automatic purge**. Move to `archived: true` on delete; archive view accessible from Tasks section gear menu. Automatic purge runs at app load if `created < now - 30 days && archived`. This prevents accidental data loss while keeping the store from bloating.

### DECISION NEEDED — sync conflict resolution

If Phase 2 adds Firebase sync: last-write-wins per record, with timestamp comparison. Tasks edited on phone + desktop within the same minute might lose one edit. Mitigation: server-side merge on conflict is Phase 3+ work; for Phase 2 LWW is acceptable for a single-user tool.

### DECISION NEEDED — Quick Links: hand-curated or auto-discovered

Recommendation: **hand-curated in Phase 1**. Sam adds the 5-10 links he cares about. Auto-discovery from substrate index/ is Phase 2 — it requires a substrate fetch endpoint or a manifest convention that doesn't exist yet.

### Risk — feature creep

The temptation to add features ("what if it had a calendar?", "what if Claude could post to it?") will be strong. Phase 1 builds *tasks + links + notes* only. Anything else gets a Phase 2 note and waits.

### Risk — the data leak

The Home tab is admin-only by recommendation, but a misconfigured role check would expose Sam's personal tasks to customer portal users. The role check needs to be in the nav-render code AND in the page-render code (defense in depth) — not just one place. This is a normal pattern in the existing manage app codebase; just call it out.

---

## 8. Estimated build effort

| Phase | Scope | Effort |
|---|---|---|
| **Phase 1 MVP** | Tasks (CRUD + soft delete + archive) + Quick Links (CRUD + reorder) + Free Notes; localStorage only; brand styling using existing utilities; DATA_VERSION 18 migration; admin-only access guard | **4-6 hours** of focused Claude Code work |
| **Phase 2** | Firebase sync (tasks, quickLinks, notes); markdown rendering in notes; expanded due-date UX; bulk operations | **2-3 hours** |
| **Phase 3** | Claude Code-writable task API; auto-discovery from substrate; calendar/deadline integration; notifications | **Longer-term**, design-dependent |

Phase 1 estimate assumes:
- No new CSS primitives (uses utilities.css).
- No new auth surface (existing admin role guard suffices).
- No Firebase touches.
- Standard `migrateData()` extension.
- ~400-600 lines of new code in manage/index.html (page template, render functions, event handlers, migration block).

Total file growth: manage/index.html from ~28,600 lines to ~29,200 lines. Negligible.

---

## Active artifacts

- This file (intake.md) — the spec itself
- [Index entry](../../index/personal-project/home-tab-design-spec-2026-05.md)

## Status updates

- 2026-05-11: design spec drafted, committed to substrate, awaiting Sam's review. Build deferred until post-Pittsburgh trip (after 2026-05-16).

---

## Open decisions summary (for Sam's review)

1. Home as first tab + default landing? (recommend yes)
2. Admin-only or visible to all roles? (recommend admin-only)
3. Phase 1 localStorage only, or Firebase sync immediately? (recommend localStorage only)
4. Soft delete with 30-day purge, or hard delete? (recommend soft + purge)
5. Hand-curated Quick Links in Phase 1, or attempt auto-discovery? (recommend hand-curated)
6. Should the initial seeded Quick Links list match Section 3b's suggestion?

These can be answered in one round of feedback. Build session can start after that.