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.
The English summary is being prepared. Showing the original description.
See how to installReview the instructions the agent will receive before you install.
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.
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
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.
The English summary is being prepared. Showing the original description.
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).
The English summary is being prepared. Showing the original description.
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 English summary is being prepared. Showing the original description.
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.
The English summary is being prepared. Showing the original description.
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 English summary is being prepared. Showing the original description.
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).
The English summary is being prepared. Showing the original description.