Device First Constellation

[sarthakagrawal927]

Spec-driven change: device-first-constellation

Proposal

Device-first constellation

Why

Keeping people in mind is not a spreadsheet job. The owner wants a private
iPhone surface where the people they add are visible as floating bubbles —
closer relationships larger — and each person has a dated log of the things
that actually happened.

What

• Add, edit, and remove people with name, circle, closeness, hue, optional
  birthday, how you met, and standing notes.
• A constellation home: drifting lanterns sized by closeness.
• A searchable list fallback and a frozen layout when Reduce Motion is on.
• Per-person chronological logs with kind, date, and body.
• One local JSON document. No account. No network.

Out

• Contact import, iCloud, notifications, photos, messaging, a web client,
  scoring closeness from activity.

How

SwiftUI app + KithCore document/store, XcodeGen project, XCTest for the
document and the main add-person / add-log path.

---

Design

Design

Kith is a single-document iPhone app.

flowchart LR
  Constellation --> Person
  Person --> Log
  Store[(kith-v1.json)]
  Constellation --> Store
  Person --> Store
  Log --> Store

Loading

• KithDocument owns people and entries. Mutations are methods on the
  document so they can be tested without SwiftUI.
• KithStore is an actor that reads and writes Application Support with
  complete file protection.
• AppModel is the @MainActor owner. --ui-demo and --fresh-demo
  replace the on-device file so tests never touch real notes.
• Bubble size is a pure function of closeness. The field is a small
  repulsion / wander simulation; reduced motion freezes it.

No backend, no CloudKit, no HealthKit.

---

Specs

people-and-logs/spec.md

People and logs

Requirements

Requirement: People are explicit

A person SHALL have a name, a circle, a closeness from 1 to 5, a hue, and
MAY have a birthday, how-we-met text, and standing notes. Closeness SHALL
NOT be inferred from recency or log volume.

Scenario: Closeness is set by the person

• WHEN a person is saved with closeness 4
• THEN their constellation lantern uses the diameter for closeness 4

Requirement: Logs belong to one person

An entry SHALL have a person, a kind, a happened-on date, and a body. A
person page SHALL list that person's entries newest first.

Scenario: A hangout is recorded

• WHEN a hangout entry is added for Maya on a given date
• THEN Maya's page shows that hangout and last contact becomes that date

Requirement: Data stays on the device

The document SHALL load and save from the app container. Launch arguments
--ui-demo and --fresh-demo SHALL NOT read or write the real document.

Scenario: Empty launch

• WHEN the app launches with --fresh-demo
• THEN the constellation is empty and invites adding someone

---

Spec-driven tracking issue. All design content lives here; no local openspec/ docs.

[sarthakagrawal927]

Completed: the device-first constellation, explicit closeness, people profiles, dated logs, searchable fallback, reduced-motion layout, and local JSON store are on main.