docs(web): reorganize into docs/ folder; extract STATE_MANAGEMENT.md (LUM-1751)#31359
Conversation
…(LUM-1751)
Move apps/web's three deep-dive docs into a docs/ subfolder matching the
repo's existing pattern (assistant/docs/, repo-root docs/). Extract the
state-management section out of CONVENTIONS.md into its own file so it
can grow without bloating the umbrella doc.
apps/web/
AGENTS.md ← stays at root (entry point)
README.md ← stays at root (dev setup, commands)
docs/
CONVENTIONS.md ← moved; state-mgmt section replaced with pointer
STATE_MANAGEMENT.md ← new; extracted from CONVENTIONS.md
STYLE_GUIDE.md ← moved
CAPACITOR.md ← moved
Also dedupes the Data fetching content: the React Query rationale
section was duplicated between CONVENTIONS.md "Data fetching" and the
state-management content (after extraction). Renames the CONVENTIONS.md
section to "API client codegen" to honestly reflect what's left
(HeyAPI codegen + generated client usage), with a pointer to
STATE_MANAGEMENT.md for the server-state-vs-client-state stuff.
Link updates:
- AGENTS.md: 4 doc references → docs/ paths; adds the "extract topical
docs past ~100 lines" heuristic so future contributors know when to
split.
- README.md: 3 references updated.
- Cross-doc references between CAPACITOR, STYLE_GUIDE updated.
- One in-code comment in use-conversation-list-init.ts updated.
Pure file moves via git mv so history follows.
https://claude.ai/code/session_013dBXRbLF218UhdLq7FEAvv
Two real findings from the docs audit on this PR:
1. CAPACITOR.md links to src/ files used ./src/ paths. After moving
into docs/, ./src/ resolves to docs/src/ (doesn't exist).
Fixed to ../src/ (5 occurrences).
2. STATE_MANAGEMENT.md "Selector patterns and useShallow" section led
with useShallow examples as if they were the recommended pattern.
Contradicts the rule documented elsewhere ("useShallow is not
introduced in new code"). Restructured: section now opens with a
pointer to atomic selectors as the recommended pattern, and the
useShallow examples are explicitly marked "Legacy: do not use in
new code" with migration guidance.
https://claude.ai/code/session_013dBXRbLF218UhdLq7FEAvv
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
There was a problem hiding this comment.
🟡 Broken relative links in CONVENTIONS.md after move to docs/ subdirectory
When CONVENTIONS.md was moved from apps/web/ to apps/web/docs/, several relative links were not adjusted for the new directory depth. All links that reference parent or sibling paths are now off by one level:
- Line 8:
../AGENTS.mdresolves toapps/web/AGENTS.mdbut link text saysapps/AGENTS.md(should be../../AGENTS.md) - Line 9:
../../AGENTS.mdresolves toapps/AGENTS.mdbut link text says rootAGENTS.md(should be../../../AGENTS.md) - Line 18:
./README.mdresolves to non-existentapps/web/docs/README.md(should be../README.md) - Line 472:
../../packages/design-library/README.mdresolves to non-existentapps/packages/design-library/README.md(should be../../../packages/design-library/README.md)
(Refers to lines 8-9)
Prompt for agents
CONVENTIONS.md was moved from apps/web/ to apps/web/docs/ but its relative links to parent directories were not updated. All relative paths that go up from the file are now off by one directory level.
Fix the following lines in apps/web/docs/CONVENTIONS.md:
- Line 8: Change (../AGENTS.md) to (../../AGENTS.md)
- Line 9: Change (../../AGENTS.md) to (../../../AGENTS.md)
- Line 18: Change (./README.md) to (../README.md)
- Line 472: Change (../../packages/design-library/README.md) to (../../../packages/design-library/README.md)
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
🟡 Broken relative links in CAPACITOR.md after move to docs/ subdirectory
When CAPACITOR.md was moved from apps/web/ to apps/web/docs/, many relative links to source files (./src/...) and parent directories (../../apps/ios/) were not adjusted. The ./src/ prefix now resolves to the non-existent apps/web/docs/src/ instead of apps/web/src/, and ../../apps/ios/ resolves to non-existent apps/apps/ios/.
All broken links
- Line 7:
(../../apps/ios/)→apps/apps/ios/(should be../../../apps/ios/) - Line 42:
(./src/runtime/native-auth.ts)→ non-existent (should be../src/runtime/native-auth.ts) - Line 42:
(../../apps/ios/App/App/NativeAuthPlugin.swift)→ non-existent (should be../../../apps/ios/App/App/NativeAuthPlugin.swift) - Line 44:
(./src/components/native-splash.tsx)→ non-existent (should be../src/components/native-splash.tsx) - Line 48:
(./src/runtime/native-auth.ts)→ non-existent (should be../src/runtime/native-auth.ts) - Line 67:
(./src/utils/pointer.ts)→ non-existent (should be../src/utils/pointer.ts) - Line 75:
(./src/runtime/native-deep-link.ts)→ non-existent (should be../src/runtime/native-deep-link.ts)
(Refers to line 7)
Prompt for agents
CAPACITOR.md was moved from apps/web/ to apps/web/docs/ but its relative links were not updated.
Replace all ./src/ prefixes with ../src/ (7 occurrences on lines 42, 44, 48, 67, 75).
Replace ../../apps/ with ../../../apps/ (lines 7, 42).
Specifically:
- Line 7: (../../apps/ios/) -> (../../../apps/ios/)
- Line 42: (./src/runtime/native-auth.ts) -> (../src/runtime/native-auth.ts)
- Line 42: (../../apps/ios/App/App/NativeAuthPlugin.swift) -> (../../../apps/ios/App/App/NativeAuthPlugin.swift)
- Line 44: (./src/components/native-splash.tsx) -> (../src/components/native-splash.tsx)
- Line 48: (./src/runtime/native-auth.ts) -> (../src/runtime/native-auth.ts)
- Line 67: (./src/utils/pointer.ts) -> (../src/utils/pointer.ts)
- Line 75: (./src/runtime/native-deep-link.ts) -> (../src/runtime/native-deep-link.ts)
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
🟡 Broken subordination links in STYLE_GUIDE.md after move to docs/ subdirectory
When STYLE_GUIDE.md was moved from apps/web/ to apps/web/docs/, the subordination links on lines 7–8 were not adjusted. ../AGENTS.md now resolves to apps/web/AGENTS.md (the web app's own AGENTS.md) but the link text says apps/AGENTS.md (the apps-level one). ../../AGENTS.md resolves to apps/AGENTS.md but the link text says root AGENTS.md. Both links point to the wrong hierarchy level.
(Refers to lines 7-8)
Was this helpful? React with 👍 or 👎 to provide feedback.
| - **[`docs/CONVENTIONS.md`](./docs/CONVENTIONS.md)** — Architecture, code organization, component patterns, framework strategy, data fetching, testing. | ||
| - **[`docs/STATE_MANAGEMENT.md`](./docs/STATE_MANAGEMENT.md)** — Zustand stores, atomic selectors, TanStack Query, the no-`useReducer` rule. | ||
| - **[`docs/STYLE_GUIDE.md`](./docs/STYLE_GUIDE.md)** — Naming, imports, TypeScript, component authoring, formatting. | ||
| - **[`docs/CAPACITOR.md`](./docs/CAPACITOR.md)** — Capacitor / iOS patterns: lazy plugin imports, native auth, deep links, autogrowing textareas, streaming watchdogs, OS permission UI, capability detection, keyboard-only affordances. Mandatory reading if any code path you're touching might run inside the iOS WKWebView shell. |
There was a problem hiding this comment.
🟡 CONTRIBUTING.md and apps/ios/README.md still reference old file paths
This PR moved CONVENTIONS.md, STYLE_GUIDE.md, and CAPACITOR.md from apps/web/ to apps/web/docs/, but two files outside apps/web/ that link to the old paths were not updated:
CONTRIBUTING.md:95links toapps/web/CONVENTIONS.mdandapps/web/STYLE_GUIDE.md— both now 404apps/ios/README.md:98links to../web/CAPACITOR.md— should be../web/docs/CAPACITOR.md
This violates the root AGENTS.md rule: "When introducing, removing, or significantly modifying a service/module/data flow, update AGENTS.md and impacted domain docs."
Prompt for agents
Two files outside apps/web/ reference the old pre-move paths and need updating:
1. CONTRIBUTING.md line 95: Change apps/web/CONVENTIONS.md to apps/web/docs/CONVENTIONS.md, and apps/web/STYLE_GUIDE.md to apps/web/docs/STYLE_GUIDE.md.
2. apps/ios/README.md line 98: Change ../web/CAPACITOR.md to ../web/docs/CAPACITOR.md.
Was this helpful? React with 👍 or 👎 to provide feedback.
| ## API client codegen | ||
|
|
||
| React Query handles **server state**. Zustand handles **client state** | ||
| (UI interactions, streaming state, conversation selections). They do not | ||
| overlap. | ||
|
|
||
| Why React Query over alternatives: | ||
| - [HeyAPI `@tanstack/react-query` plugin](https://heyapi.dev/openapi-ts/plugins/tanstack-query) | ||
| auto-generates type-safe query/mutation hooks from the OpenAPI spec. | ||
| No equivalent plugin exists for SWR (still in proposal stage) or other | ||
| libraries. | ||
| - First-class mutation support, optimistic updates, and DevTools. | ||
| - 12M+ weekly downloads (2026), most feature-complete option. | ||
|
|
||
| References: | ||
| - [React Query — Overview](https://tanstack.com/query/latest/docs/framework/react/overview) | ||
| - [React Query — Comparison](https://tanstack.com/query/latest/docs/framework/react/comparison) | ||
| Server state, React Query usage, and the Zustand-vs-Query boundary are | ||
| covered in [`STATE_MANAGEMENT.md`](./STATE_MANAGEMENT.md). This section | ||
| is about the **tooling** that produces the API client itself: OpenAPI | ||
| codegen, generated hooks, and when to bypass them. |
There was a problem hiding this comment.
🚩 "React Query for server state" section content dropped without equivalent in STATE_MANAGEMENT.md
The old apps/web/CONVENTIONS.md had a dedicated "React Query for server state" subsection (old lines 856–877) that explained why React Query was chosen over alternatives (HeyAPI plugin availability, mutation support, DevTools, ecosystem size) and linked to the React Query Overview and Comparison docs. This section was removed as part of the "Data fetching" → "API client codegen" rename (apps/web/docs/CONVENTIONS.md:482-487), and the new pointer at line 484 claims "Server state, React Query usage… are covered in STATE_MANAGEMENT.md." However, apps/web/docs/STATE_MANAGEMENT.md only has a "Data fetching: React Query vs direct SDK calls" section (lines 246–287) covering the Zustand-vs-Query boundary — not the standalone justification for React Query or the comparison references. This may be intentional editorial trimming, but it means the rationale for choosing React Query over SWR/other libraries is no longer documented anywhere.
Was this helpful? React with 👍 or 👎 to provide feedback.
| - **Client state** lives in Zustand stores with direct named actions and atomic selectors via `createSelectors`. | ||
| - **Server state** lives in TanStack Query. | ||
| - **`useReducer` is not used** for client state, even within a single hook. See [STATE_MANAGEMENT.md — useReducer is not used](./STATE_MANAGEMENT.md#usereducer-is-not-used-for-client-state). | ||
| - **`useShallow`** is not introduced in new code — atomic selectors avoid the need. |
There was a problem hiding this comment.
🚩 New useShallow policy statement may need alignment with STATE_MANAGEMENT.md
Line 248 of apps/web/docs/CONVENTIONS.md introduces a new policy: "useShallow is not introduced in new code — atomic selectors avoid the need." This is a new rule that did not exist in the old CONVENTIONS.md. Meanwhile, apps/web/docs/STATE_MANAGEMENT.md:139-167 retains the full "Selector patterns and useShallow" section with examples showing when to use useShallow (pattern #2: object/array slices). The two documents are coherent if read as "here's the legacy pattern (STATE_MANAGEMENT.md) but don't add new instances (CONVENTIONS.md)", but there's no explicit note in the STATE_MANAGEMENT.md section marking useShallow as legacy/discouraged. A reader of STATE_MANAGEMENT.md alone would reasonably conclude useShallow is the recommended approach for multi-field selectors.
Was this helpful? React with 👍 or 👎 to provide feedback.
PR #31359 moved apps/web/{CONVENTIONS,STYLE_GUIDE,CAPACITOR}.md into docs/ but missed several relative-path adjustments. Devin caught six of them; fixing all. External files (didn't catch in initial sweep): - CONTRIBUTING.md:95 — updated apps/web/CONVENTIONS.md and apps/web/STYLE_GUIDE.md links to apps/web/docs/*; added STATE_MANAGEMENT.md alongside - apps/ios/README.md:98 — updated ../web/CAPACITOR.md to ../web/docs/CAPACITOR.md Subordination links in moved docs (depth changed by one): - CONVENTIONS.md:8-9 — ../AGENTS.md and ../../AGENTS.md → one ../ deeper - STYLE_GUIDE.md:7-8 — same fix - (STATE_MANAGEMENT.md was already correct, written for docs/ depth) CONVENTIONS.md internal links: - :18 — ./README.md → ../README.md - :472 — ../../packages/... → ../../../packages/... CAPACITOR.md cross-app links: - :7 and :42 — ../../apps/ → ../../../apps/ (the ./src/ → ../src/ changes were already in 8bb3be4) STATE_MANAGEMENT.md content restoration (Devin ANALYSIS_0001): The dedupe in 73e8d56 dropped the "Why React Query (not SWR or others)" rationale. Restored as a subsection under Data fetching, with the HeyAPI-plugin-availability argument that's specific to our codegen pipeline. Verified every link target exists with a shell loop over the resolved paths. https://claude.ai/code/session_013dBXRbLF218UhdLq7FEAvv
![vex-assistant-bot[bot]](https://avatars.githubusercontent.com/in/3399303?s=60&v=4){kind=small}
There was a problem hiding this comment.
The reorganization rationale is solid — docs/ subfolder matches the existing repo pattern, STATE_MANAGEMENT.md extraction is clean, and the useShallow policy statement in CONVENTIONS.md (line 248: "not introduced in new code") is consistent with STATE_MANAGEMENT.md's framing of useShallow examples as legacy-recognition-only (not a contradiction, as Devin #6 suggests). The React Query content IS in STATE_MANAGEMENT.md's "Data fetching: React Query vs direct SDK calls" section, so Devin #5 is also a false positive.
Three broken links need fixing before this merges. The PR test plan explicitly asked for a link spot-check — these are the ones it missed.
🔴 Blocker 1 — CONTRIBUTING.md:95 — two stale paths
Verified at HEAD via GitHub API:
apps/web/CONVENTIONS.md ← 404 (moved to apps/web/docs/CONVENTIONS.md)
apps/web/STYLE_GUIDE.md ← 404 (moved to apps/web/docs/STYLE_GUIDE.md)
Fix:
apps/web/docs/CONVENTIONS.md
apps/web/docs/STYLE_GUIDE.md
🔴 Blocker 2 — apps/ios/README.md:98 — stale CAPACITOR.md path
Verified at HEAD:
[`apps/web/CAPACITOR.md`](../web/CAPACITOR.md) ← 404Fix:
[`apps/web/docs/CAPACITOR.md`](../web/docs/CAPACITOR.md)🔴 Blocker 3 — apps/web/docs/CAPACITOR.md lines 7 and 42 — ../../apps/ios/ resolves to apps/apps/ios/
From apps/web/docs/, ../../ goes up to apps/ — so ../../apps/ios/ hits the non-existent apps/apps/ios/. Line 123 (also apps/ios/README.md reference) was correctly fixed to ../../../apps/ios/README.md in the second commit, but lines 7 and 42 were missed:
| Line | Current (broken) | Fix |
|---|---|---|
| 7 | (../../apps/ios/) |
(../../ios/) or (../../../apps/ios/) |
| 42 | (../../apps/ios/App/App/NativeAuthPlugin.swift) |
(../../ios/App/App/NativeAuthPlugin.swift) |
Non-blocking notes:
- CONVENTIONS.md / STYLE_GUIDE.md subordination link text (Devin #1/#3): the
../AGENTS.mdand../../AGENTS.mdHREFs resolve correctly toapps/web/AGENTS.mdandapps/AGENTS.mdrespectively. The display text in each doc says the wrong level. The links work — just a text label polish item. useShallowalignment (Devin #6): not a contradiction. CONVENTIONS.md:248 says "not introduced in new code"; STATE_MANAGEMENT.md shows useShallow examples explicitly labeled as "legacy call sites — for recognition and migration." Both say the same thing.- React Query rationale (Devin #5): content is present in STATE_MANAGEMENT.md "Data fetching: React Query vs direct SDK calls." Restructured, not dropped.
This is a public repo with external contributors. Removed internal-only
references and reframed migration content so the docs make sense to
someone who has never worked on vellum-assistant-platform.
Specifically:
- AGENTS.md: dropped the "Migration status" section (faithful-copy /
convention-compliance guidance was for internal porters, not OSS
readers). Kept the scope clarification ("only the assistant web app
and auth/identity pages — no marketing or admin surfaces"), which IS
useful to external contributors.
- AGENTS.md: replaced "Routes must match the platform repo exactly
during migration" with a neutral statement about URL stability
(bookmarks/deep links rely on them).
- STATE_MANAGEMENT.md: removed Linear link (LUM-1748) — OSS readers
cannot open it. Replaced with "will be migrated in a future change."
- CONVENTIONS.md: replaced "The team chose" / "discuss with the team"
with neutral framings ("this app uses" / "open a GitHub issue to
discuss"). External contributors shouldn't feel they need to be on
some team to push back on a rule.
- CONVENTIONS.md: clarified the `vel up --vite` mention — explained
that `vel` is Vellum's internal CLI, and OSS contributors should
just use `bun run dev`.
- CAPACITOR.md: added a one-line callout at the top so browser-only
contributors know they can skip the entire doc.
- Tightened "Subordinate to" prose across all docs (read like internal
policy hierarchy). Now "See also" with the same links.
- Softened "Legacy: do not use" framing in STATE_MANAGEMENT.md.
"For migration reference" is more neutral.
No content removed that an OSS reader would need. All link targets
verified to resolve.
https://claude.ai/code/session_013dBXRbLF218UhdLq7FEAvv
…reorg # Conflicts: # apps/web/docs/CONVENTIONS.md
…reorg # Conflicts: # apps/web/src/domains/conversations/use-conversation-list-init.ts
There was a problem hiding this comment.
✦ APPROVE — supersedes my prior CHANGES_REQUESTED at 8bb3be40
My three blockers are all resolved at HEAD (525e2ba1):
✅ Blocker 1 resolved — CONTRIBUTING.md:95 now points to apps/web/docs/CONVENTIONS.md, apps/web/docs/STATE_MANAGEMENT.md, and apps/web/docs/STYLE_GUIDE.md. The commit also added the new STATE_MANAGEMENT.md reference, which is a nice bonus.
✅ Blocker 2 resolved — apps/ios/README.md:98 now reads [apps/web/docs/CAPACITOR.md](../web/docs/CAPACITOR.md).
✅ Blocker 3 resolved — CAPACITOR.md lines 5 and 42 now use ../../../apps/ios/ which correctly resolves from apps/web/docs/ to apps/ios/. Both the intro link and the NativeAuthPlugin.swift link are correct.
All four Devin BUG findings are false positives at HEAD:
- BUG_0001 (CONVENTIONS.md relative links):
../AGENTS.md→apps/web/AGENTS.md,../../AGENTS.md→apps/AGENTS.md,../../../AGENTS.md→ rootAGENTS.md,../README.md→apps/web/README.md. All correct. Devin misread the resolved paths. - BUG_0002 (CAPACITOR.md): Already fixed (Blocker 3 above).
- BUG_0003 (STYLE_GUIDE.md links): Same pattern as CONVENTIONS.md —
../AGENTS.mdresolves toapps/web/AGENTS.mdwhich matches the display textapps/web/AGENTS.md. No mismatch. - BUG_0004 (CONTRIBUTING.md + ios/README.md): Already fixed (Blockers 1 + 2 above).
Both Devin ANALYSIS findings are non-issues (same conclusion as my prior review):
- ANALYSIS_0001 ("React Query rationale dropped"):
STATE_MANAGEMENT.md:288has an explicit### Why React Query (not SWR or others)section with the rationale and links to React Query docs. Content is present, just reorganized. - ANALYSIS_0002 ("useShallow alignment"):
STATE_MANAGEMENT.md:146explicitly marks the useShallow section as### Legacy: \useShallow` patterns (for migration reference).CONVENTIONS.md:275` says "not introduced in new code." Fully aligned — both say the same thing from different angles.
Reorganization is well-executed. The docs/ subfolder follows existing repo convention (assistant/docs/, repo-root docs/). STATE_MANAGEMENT.md extraction is clean — Zustand + TanStack Query is a coherent standalone boundary. The "Data fetching" → "API client codegen" rename in CONVENTIONS.md is honest (what remains is tooling, not state semantics). The extraction heuristic added to AGENTS.md ("when a topic grows past ~100 lines and has a coherent boundary") is a good convention to codify. The decision not to add docs/README.md (avoiding a second index that drifts from AGENTS.md) is correct.
Two follow-ups from PR #31375 review feedback: - Rename the store export from `useConversationListStore` to `useConversationStore` so it matches the renamed `conversation-store.ts` file. The `-list-` qualifier in the symbol was the same platform-era residue we already shed from the filename. 12 consumer files updated via sed; pure mechanical rename. - Restore the `apps/web/CONVENTIONS.md` docstring reference in `conversation-queries.ts`. The earlier `apps/web/docs/STATE_MANAGEMENT.md` path is from PR #31359 which hasn't merged, so the link was dead on this branch.
…54) (#31375) * refactor(web): align conversations domain with CONVENTIONS.md (LUM-1754) Mechanical alignment of the conversation-list refactor (LUM-1731) with apps/web/docs/CONVENTIONS.md and STATE_MANAGEMENT.md. Pure structural moves and renames — no behavior changes. File renames (git mv preserves history): - conversations/conversation-list-store.{ts,test.ts} → conversations/conversation-store.{ts,test.ts} - conversations/conversation-list-queries.{ts,test.ts} → conversations/conversation-queries.{ts,test.ts} The `-list-` qualifier was platform-era residue from when the store held the sidebar list data; post-LUM-1731 the store owns active/editing/processing/attention/snapshots — all client state for the conversations domain, not "the list." Hook moves into the conversations domain (matches the CONVENTIONS.md `conversations/use-conversation-loader.ts` example — domain-level hooks live at the domain top, no hooks/ subdirectory): - chat/hooks/use-conversation-actions.{ts,test.ts} → conversations/use-conversation-actions.{ts,test.ts} - chat/hooks/use-conversation-group-actions.ts → conversations/use-conversation-group-actions.ts - chat/hooks/use-conversation-loader.ts → conversations/use-conversation-loader.ts - chat/hooks/use-attention-tracking.ts → conversations/use-attention-tracking.ts - chat/hooks/use-attention-tracking-graduation.test.ts → conversations/use-attention-tracking-graduation.test.ts Cache helpers in conversation-queries.ts drop the `*InCache` / `*FromCache` suffix — they ARE the conversation-domain data mutators per the server-state-in-Query convention; queryClient.setQueryData is implementation detail: - patchConversationInCache → patchConversation - markConversationSeenInCache → markConversationSeenLocal (kept asymmetric to avoid shadowing the markConversationSeen API call when both are imported into use-attention-tracking) - prependConversationInCache → prependConversation - removeConversationFromCache → removeConversation - resolveDraftKeyInCache → resolveDraftKey - findConversationInCache → findConversation - getConversationsFromCache → getConversations - appendGroupInCache → appendGroup - patchGroupInCache → patchGroup - replaceOptimisticGroupInCache → replaceOptimisticGroup - removeGroupFromCache → removeGroup - deleteGroupAndResetConversationsInCache → deleteGroupAndResetConversations Dead-code cleanup uncovered by the rename pass: - Inlined applyConversationPatch into patchConversation; deleted its duplicated test block from use-conversation-actions.test.ts (the conversation-queries.test.ts tests for patchConversation cover the same behavior at the cache-write layer). - Deleted the standalone patchGroup pure-helper export and its entire test file — duplicated by the now-renamed patchGroup cache helper, with no production consumers. Updates all import sites and inline doc references. Deferred: use-conversation-history.ts could move to a new domains/messages/ folder per the CONVENTIONS.md example, but creating that domain is a separate decision; tracked for later. * refactor(web): align store export name with file name + fix doc ref Two follow-ups from PR #31375 review feedback: - Rename the store export from `useConversationListStore` to `useConversationStore` so it matches the renamed `conversation-store.ts` file. The `-list-` qualifier in the symbol was the same platform-era residue we already shed from the filename. 12 consumer files updated via sed; pure mechanical rename. - Restore the `apps/web/CONVENTIONS.md` docstring reference in `conversation-queries.ts`. The earlier `apps/web/docs/STATE_MANAGEMENT.md` path is from PR #31359 which hasn't merged, so the link was dead on this branch. * docs(web): restore docs/STATE_MANAGEMENT.md docstring reference PR #31359 (the docs reorg that moved CONVENTIONS.md / STATE_MANAGEMENT.md under apps/web/docs/) is on main as 74d81c4. Restoring the correct path in conversation-queries.ts now that main is merged into this branch. --------- Co-authored-by: Claude <noreply@anthropic.com>
2 participants
Summary
Reorganizes
apps/web/'s deep-dive docs into adocs/subfolder matching the repo's existing pattern (assistant/docs/, repo-rootdocs/). Extracts state management into its own file so it can grow without bloating CONVENTIONS.md.Tracking: LUM-1751.
What moved
apps/web/was the outlier — every other documented package in the repo (assistant/,skills/meet-join/, repo root) already puts deep-dive docs underdocs/. This rounds it out.Why these stay in
apps/web/docs/(notapps/docs/)Every doc moved is web-stack-specific:
apps/AGENTS.mdalready exists for cross-app concerns. If we ever need cross-app convention docs, those'd go inapps/docs/.Why no
docs/README.mdExisting convention: neither
docs/(repo root) norassistant/docs/has one.apps/web/AGENTS.mdalready lists each file with a one-line description — that's the canonical index. Adocs/README.mdwould be a redundant second index that drifts out of sync.Dedupe: Data fetching ↔ state management
The extraction surfaced a duplication. The standalone "Data fetching" section in CONVENTIONS.md had three subsections:
Renamed the CONVENTIONS.md section to "API client codegen" to honestly reflect what's left (the tooling/codegen bits), with a pointer to STATE_MANAGEMENT.md for the server-state-vs-client-state semantics. Each doc now has one clear concern.
Convention codification
Added to
apps/web/AGENTS.md:Link updates
apps/web/AGENTS.md— 4 doc references →docs/paths; adds the extraction heuristicapps/web/README.md— 3 references updatedapps/ios/README.mdre-anchored (../../../instead of../../)use-conversation-list-init.tsupdatedTest plan
bunx tsc --noEmit— cleanbun run lint— clean (pre-existing unrelated warning)bun run test:ci— 85/85 test files passgit mvused for moves sogit log --followworks on the moved filesgrep -rn "CONVENTIONS\\.md\\|STYLE_GUIDE\\.md\\|CAPACITOR\\.md\\|STATE_MANAGEMENT\\.md"shows no stale./paths at the package root)Risk
Low. Pure structural reorganization plus one dedupe edit. No code changes, no behavior changes, no convention-rule changes.
https://claude.ai/code/session_013dBXRbLF218UhdLq7FEAvv
Generated by Claude Code