# Phase 32: Setup Sharing System - Context

**Gathered:** 2026-04-13
**Status:** Ready for planning

<domain>
## Phase Boundary

Setup owners can toggle visibility between private, link-shared, and public. Share links use secret tokens with configurable expiration and revocation. Schema includes full future-proofing for person-specific shares, write permissions, and collaborative editing — but only read-only link sharing is enforced in this phase.

</domain>

<decisions>
## Implementation Decisions

### Visibility Model
- **D-01:** Three visibility levels: `private` (owner only), `link` (accessible via share token, not discoverable), `public` (discoverable on feed/profiles)
- **D-02:** Replace `isPublic: boolean` column on `setups` table with `visibility: text` column (`private`/`link`/`public`). Column on table for query speed — discovery feed queries `WHERE visibility = 'public'`
- **D-03:** Setting visibility to `private` deactivates (does not delete) all share links. Switching back to `link` reactivates them
- **D-04:** Share links use secret tokens — the setup's numeric ID alone is not sufficient for link-shared access

### Share Links
- **D-05:** Multiple share links can coexist per setup, each independent with its own token, expiration, and revocation status
- **D-06:** Share URLs: `/s/{token}` (short URL for sharing) AND `/setups/:id?share={token}` (both work, short URL is primary for sharing)
- **D-07:** Default link expiration: 14 days. Options when creating: 7 days, 14 days, 30 days, infinite
- **D-08:** Each link can be individually revoked without affecting other links
- **D-09:** Only read-only link shares are functional in this phase. Write permission exists in schema but is not enforced

### Schema
- **D-10:** Full `shares` table created now: id, setupId, token, permission (read/write), expiresAt (nullable = infinite), userId (nullable — null = link share, set = person-specific share), createdAt, revokedAt (nullable)
- **D-11:** Person-specific shares (userId column) exist in schema but are not used in this phase
- **D-12:** Write permission column exists but write-access is not enforced — no mutation permission checks

### Share UX
- **D-13:** Share modal (Google Docs style) is the single UI for managing visibility AND share links
- **D-14:** Share icon button replaces the current globe public/private toggle on setup detail page. Icon reflects current visibility state via color/icon variation
- **D-15:** Modal contains: visibility picker (private/link/public), create share link with expiration picker, active share links list with copy/revoke actions
- **D-16:** Desktop and mobile use the same share icon button opening the same modal

### Public Setup Presentation
- **D-17:** Link-shared setup viewer UX: Claude's discretion — will pick based on existing setup detail page patterns (subtle shared context vs. identical to public view)
- **D-18:** No changes to discovery feed or profile page visuals in this phase
- **D-19:** Discovery feed query updated from `isPublic = true` to `visibility = 'public'` — same behavior, new column

### Claude's Discretion
- Viewer experience for link-shared setups (shared banner/badge vs. clean view) — pick what fits the existing design patterns

### Folded Todos
None — no relevant todos matched this phase's scope.

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

No external specs — requirements fully captured in decisions above.

### Existing Implementation
- `src/db/schema.ts` — Current `setups` table with `isPublic` boolean (line 118-127)
- `src/server/services/setup.service.ts` — Setup CRUD with `isPublic` handling
- `src/server/services/discovery.service.ts` — Discovery feed query using `isPublic = true`
- `src/server/services/profile.service.ts` — `getPublicSetupWithItems()` for public viewing
- `src/client/routes/setups/$setupId.tsx` — Setup detail page with current globe toggle (lines 177-203)
- `src/client/hooks/useSetups.ts` — `usePublicSetup` hook (line 67)
- `src/shared/schemas.ts` — Zod schemas with `isPublic` field (lines 88, 93)

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- Setup detail page (`setups/$setupId.tsx`): Has desktop + mobile button patterns for the share button replacement
- `useSetups` hooks: Mutation patterns for `updateSetup` — extend for visibility changes
- `LucideIcon` component: Icons like `share-2`, `link`, `globe`, `lock` available for visibility states
- Modal patterns: Used elsewhere in the app (thread creation, item add) — reuse for share modal

### Established Patterns
- Service layer with DI (`db` as first param) for testability
- Zod validation on route handlers via `@hono/zod-validator`
- React Query mutations with cache invalidation
- Detail pages (not panels) for complex interactions

### Integration Points
- `src/db/schema.ts`: New `shares` table + modify `setups` table (isPublic → visibility)
- `src/server/routes/setups.ts`: New share link CRUD endpoints
- `src/server/routes/`: New `/s/:token` route for short share URLs
- `src/server/services/setup.service.ts`: Update queries from isPublic to visibility
- `src/server/services/discovery.service.ts`: Update feed query
- `src/server/services/profile.service.ts`: Update public setup query
- `src/client/routes/setups/$setupId.tsx`: Replace globe toggle with share button + modal
- `src/shared/schemas.ts`: New share schemas, update setup schemas

</code_context>

<specifics>
## Specific Ideas

- Share modal inspired by Google Docs share dialog — visibility picker at top, share links list below
- When visibility is set to `private`, share links become inactive but aren't deleted — switching back to `link` reactivates them
- Multiple shares coexist: e.g., one permanent read link + one 14-day read link simultaneously
- Future: person-specific shares should influence discovery algorithm (deferred)

</specifics>

<deferred>
## Deferred Ideas

- **Person-specific shares influencing discovery feed algorithm** — when direct shares exist between users, factor that into feed ranking. Belongs in a future personalization/social phase.
- **Write-access share enforcement** — collaborative editing requires conflict resolution, real-time sync, and mutation permission checks. Belongs in a dedicated collaborative editing phase.
- **Person-specific share UI** — inviting specific users by username/email to a setup. Needs user search/lookup. Future phase.

</deferred>

---

*Phase: 32-setup-sharing-system*
*Context gathered: 2026-04-13*