Use when modifying anything under features/files/, app/(core)/files/, app/(public)/share/, or any caller that uploads, downloads, lists, moves, renames, shares, or previews user files.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
설치 방법 보기설치하기 전에 에이전트에게 전달되는 지시 내용을 확인할 수 있습니다.
This skill enforces the architecture established in features/files/FEATURE.md. Read it first. This skill is the checklist version.
cloud_get_user_file_tree. No REST calls for reads unless the endpoint returns bytes.cloudFiles Redux slice. No local useState for file data. No new Redux slices for files — extend the existing one.fileId. Never cache by file_path — paths move with renames.requestId on every mutation.Drawer not Dialog; push-nav not tabs; dvh not vh; pb-safe on fixed bottoms; 16px inputs.FieldFlags<K> not Set<K> in Redux state (JSON-serializability).app/(core)/files/ routes follow app/(core)/_read_first_route_rules/RULES.md. SSR-first, zero layout shift; 'use cache' is NOT available (cacheComponents off — see CLAUDE.md).Read, in this order:
/Users/armanisadeghi/code/common-docs/systems/files/file-service/WIRE_CONTRACT.md — the backend contract (routes, shapes, quotas, TUS, share tokens).For route work under app/(core)/files/, additionally run these skills before writing code:
.claude/skills/nextjs-ssr-architecture/SKILL.md.claude/skills/ssr-zero-layout-shift/SKILL.md.claude/skills/ios-mobile-first/SKILL.md (for any mobile branch)import { useAppDispatch } from '@/lib/redux/hooks';
import { uploadFiles } from '@/features/files/redux/thunks';
const dispatch = useAppDispatch();
await dispatch(
uploadFiles({ files: [file], parentFolderId, visibility: 'private' })
).unwrap();
<img> / <video>import { useMediaResolution } from "@ai-matrx/media/core";
// Prefer <InlineMediaRef ref={{ file_id }} /> from @ai-matrx/media/react.
const src = useMediaResolution(fileId).resolution?.src ?? null;
return <img src={src ?? undefined} />;
import { openFilePicker } from '@/features/files/components/pickers/FilePicker';
const [file] = await openFilePicker({ multi: false });
import { useFolderContents } from '@/features/files/hooks/useFolderContents';
const { files, folders, loading } = useFolderContents(folderId);
import { useSharing } from '@/features/files/hooks/useSharing';
const { createShareLink } = useSharing();
const link = await createShareLink(fileId, {
permission_level: 'read',
expires_at: '2026-12-31T23:59:59Z',
max_uses: 50,
});
// link.share_token → https://app.aidream.com/share/${link.share_token}
cloudFiles.CloudFile, CloudFolder, etc. Import from features/files/index.ts.window.alert / confirm / prompt. Use components/ui/alert-dialog.Dialog on mobile. Branch via useIsMobile() to Drawer.h-screen / vh under app/(core)/files/ — use dvh, --header-height, pb-safe.Set in Redux state. Use FieldFlags<K> from @ai-matrx/agents/field-flags.components/core/FileTree/internal/*. Consume from the barrel.requestId. The realtime middleware will not be able to dedup, and you will see visual flicker.| Symptom | Likely cause |
|---|---|
| Optimistic update flickers/reverts after a second | Missing requestId on the REST write. Realtime echo is overwriting state. |
| Uploads succeed but don't appear in tree | Realtime middleware not attached. Check <CloudFilesRealtimeProvider> is mounted under the user-scoped layout. |
| Signed URL returns 403 | Expired. Use useFileSrc (the handler's expiry-wheel auto-refreshes). Never cache raw signed URLs across mounts. |
| Tree shows stale state after reconnect | reconcileTree() dispatch missing from the realtime middleware's SUBSCRIBED-after-error handler. |
Type error on CloudFile.metadata | You're using an inline type somewhere. Delete it and import from types.ts. |
| 413 on upload | File >tier cap (or >100MB free). For >100MB uploads, use the TUS endpoint at /files/upload/tus (transport is chosen in upload/cloudUpload.ts). |
After any non-trivial change:
/Users/armanisadeghi/code/common-docs/systems/files/file-service/HANDOFF.md.Treat docs as weight-equal to code. Stale docs cascade across every future agent touching this system.
아직 리뷰가 없습니다. 사용해 본 소감을 남겨 주세요.
로그인 없이 쓸 수 있습니다. 사용 후기, 질문, 작동하지 않은 환경 등을 편하게 남겨 주세요.
아직 댓글이 없습니다. 첫 댓글을 남겨 보세요.
Admin debug system wiring for the floating AdminIndicator's live debug data and Copy Full Context. Use when adding debug visibility to a route or feature, wiring useDebugContext or the debug panel, capturing console errors, or enabling the copy-context workflow for a page.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
Compact two-icon Copy / Copy-for-AI controls (components/agent-copy). Use when adding copy buttons to a row, card, list, or record; merging duplicate Copy/JSON/AI controls; continuing the copy rollout; or writing a Copy-for-AI payload. NOT for markdown content actions (use rich-document-actions).
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
Disclosing a surface's existing fixed AI jobs in the shell's top Agents menu. Use when a page, panel, overlay, or window already runs a mandate behind a button, assist, automatic action, or mode; when the agent-disclosure guard names a file; or during a surface check.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
The watch-fix-rerun method for making an existing platform agent or automated process efficient and correct: baseline its ledger, run one unit yourself, fix the class behind every wasted call, rerun, record. Use when asked to improve, optimize, watch, or 'make efficient' an agent, a sandbox session, a sync job, or any recurring automated process.
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
Redux state for agent execution and firing agent shortcuts. Use when editing features/agents/redux/, building agent UI, creating a conversation, touching assembleRequest or NDJSON stream state, wiring agent-state selectors, adding a per-conversation capability, or triggering a shortcut from a button, menu, or code (useShortcutTrigger, launchAgentExecution).
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.
The provision for a call site: the exhaustive menu of values that place in the code can realistically produce. Use before creating or fixing a mandate or agent that reasons about more than its own input, when deciding whether an agent can answer at all with what it is sent, or when its output 'looks right' but nobody checked it could be. NOT for building the agent (use create-agent).
한국어 요약은 준비 중입니다. 원문 설명을 표시하고 있습니다.