caspian-utils 0.0.13 → 0.0.15

package/dist/docs/commands.md

@@ -8,6 +8,7 @@ related:
     - /docs/installation
     - /docs/database
     - /docs/mcp
+    - /docs/file-uploads
     - /docs/routing
     - /docs/project-structure
     - /docs/index
@@ -19,7 +20,7 @@ This page documents the current Caspian command families used with this workspac
 
 The current workspace includes a local `prisma` binary, but it does not include local `create-caspian-app`, `casp`, or `ppy` binaries under `node_modules/.bin`. Treat project creation, project update, and Python ORM generation as external `npx` workflows rather than project-local executables.
 
-The current workspace `package.json` defines `projectName`, `tailwind`, `tailwind:build`, `browserSync`, `browserSync:build`, `dev`, and `build`. It does not currently define `npm run mcp` because `caspian.config.json` has `mcp: false`.
+The current workspace `package.json` defines `projectName`, `tailwind`, `tailwind:build`, `mcp`, `browserSync`, `browserSync:build`, `dev`, and `build`.
 
 Examples below use `npx create-caspian-app` for readability. If you want to force the latest published scaffold package explicitly, you can use `npx create-caspian-app@latest` instead.
 
@@ -83,6 +84,8 @@ Use when the user explicitly wants the local BrowserSync plus PostCSS developmen
 
 In this workspace, `npm run dev` is a long-running command that can regenerate framework-owned outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files.
 
+Because runtime uploads write to `public/assets/file-manager/`, `settings/bs-config.ts` keeps that directory in `PUBLIC_IGNORE_DIRS` so uploads do not trigger BrowserSync reloads.
+
 ### Build generated assets for deployment
 
 ```bash
@@ -117,6 +120,7 @@ Use when `prisma/schema.prisma` changes and you need migrations, seed flow, and
 - Use `npm run build` only for deployment prep or an explicit build request.
 - Treat `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files as generated outputs when a script intentionally runs.
 - Analyze `settings/component-map.json` and `settings/files-list.json` when needed, but do not hand-edit them. `settings/component-map.ts` and `settings/files-list.ts` regenerate them during the intentional dev and build flows.
+- Keep runtime upload directories such as `public/assets/file-manager` in `settings/bs-config.ts` `PUBLIC_IGNORE_DIRS` so BrowserSync does not reload on every uploaded blob.
 - Do not edit `__pycache__/` directories or `.pyc` files, and do not leave them in the final diff.
 
 ## 3. Supported Flags And Options

package/dist/docs/components.md

@@ -18,12 +18,14 @@ Import them into a template with an `@import` comment, then render them with JSX
 
 For the current workspace, component tooling scans Python files under the paths listed in `caspian.config.json`. Right now that means `src/`, so `src/components/` is the clean default location for reusable UI, even though any scanned path under `src/` can work.
 
+As the app grows, treat `src/components/` as the default home for reusable application UI. Keep route-owned markup in `src/app/`, and keep non-UI helpers or services in `src/lib/`.
+
 ## Mental Model
 
 - Use a Python component when you want a reusable server-rendered UI building block.
 - Return an HTML string directly for small presentational components.
 - Use `render_html(...)` with a same-name `.html` file when the component has more markup, PulsePoint behavior, or clearer separation between Python logic and UI.
-- Keep page-level workflows in `src/app/`, and move reusable UI into components.
+- Keep page-level workflows in `src/app/`, move reusable UI into `src/components/`, and keep helpers, services, validators, and adapters in `src/lib/`.
 
 ## Basic Component
 

package/dist/docs/database.md

@@ -273,6 +273,18 @@ async def create_user(email: str, name: str | None = None):
 
 Use validation before writes, especially for form payloads and public RPC actions. See `validation.md` for the recommended boundary checks.
 
+## Upload Metadata Pattern
+
+When a Caspian file manager needs durable metadata, keep the blob and the metadata in separate layers.
+
+- Write the uploaded blob to disk or object storage.
+- Persist the durable metadata in Prisma.
+- Store fields such as owner relation, original name, stored name, asset path, MIME type, collection, kind, size, and uploaded timestamp in the Prisma model.
+- Remove both the stored blob and the Prisma row during delete flows.
+- Do not use JSON manifests as the primary metadata store when Prisma is enabled.
+
+See [file-uploads.md](./file-uploads.md) for the route-local RPC plus public asset storage pattern.
+
 ## Advanced Features
 
 ### Aggregations
@@ -338,6 +350,7 @@ If an AI agent is working on a Caspian app with Prisma enabled, apply these rule
 - Never hand-edit generated Prisma or Python ORM classes.
 - Read `prisma.config.ts` and `prisma/seed.ts` when you need the current workspace's Prisma tooling examples.
 - Reuse the existing `src/lib/prisma/` package when the Python app needs database access.
+- For file managers and uploads, persist metadata in Prisma and keep blob storage separate. See [file-uploads.md](./file-uploads.md).
 - Put reusable database helpers in `src/lib/`; keep route and RPC orchestration in `src/app/`.
 - Use `async def page()` for first-render reads. Keep `layout()` synchronous in the current runtime, and use `@rpc()` plus `pp.rpc()` for browser-triggered reads and writes.
 - Check `fetch-data.md` for route versus RPC guidance and `validation.md` before writing public mutations.

package/dist/docs/fetch-data.md

@@ -9,6 +9,7 @@ related:
     - /docs/mcp
     - /docs/state
     - /docs/database
+    - /docs/file-uploads
     - /docs/cache
     - /docs/routing
     - /docs/pulsepoint
@@ -174,28 +175,68 @@ Use streaming when the user should see partial progress instead of waiting for a
 
 ## File Uploads
 
-RPC actions can accept FastAPI upload types.
+RPC actions can accept FastAPI upload types, but the preferred Caspian pattern is route-local upload actions in `src/app/**/index.py`, shared persistence helpers in `src/lib/`, and reactive client updates through `pp.rpc()`.
 
-Example:
+Example route-local upload action:
 
 ```python
 from fastapi import File, UploadFile
 from casp.rpc import rpc
-import shutil
 
-@rpc()
-def upload_file(file: UploadFile = File(...)):
-    with open(f"uploads/{file.filename}", "wb") as buffer:
-        shutil.copyfileobj(file.file, buffer)
+from src.lib.dashboard.file_manager import (
+    build_file_manager_payload,
+    save_file_manager_upload,
+)
+
+@rpc(require_auth=True)
+async def upload_file(file: UploadFile = File(...), collection: str = "auto"):
+    user_id = current_user_id()
+    content = await file.read()
+
+    uploaded = await save_file_manager_upload(
+        user_id,
+        file_name=file.filename or "file",
+        content=content,
+        mime_type=file.content_type,
+        desired_group=collection,
+    )
 
     return {
-        "status": "success",
-        "filename": file.filename,
-        "size": file.size,
+        "success": True,
+        "uploaded": uploaded,
+        "data": await build_file_manager_payload(user_id),
+    }
+```
+
+Client example:
+
+```html
+<script>
+  async function uploadSelectedFiles(fileList, collection = "auto") {
+    for (const file of Array.from(fileList ?? [])) {
+      const response = await pp.rpc("upload_file", { file, collection }, {
+        onUploadProgress: (progress) => {
+          console.log(progress.percentage ?? 0);
+        },
+      });
+
+      if (response?.data) {
+        setFileManagerData(response.data);
+      }
     }
+  }
+</script>
 ```
 
-On the client, call `pp.rpc()` and pass `onUploadProgress` when the UI needs progress updates.
+Use this pattern for real file managers:
+
+- Keep upload and delete actions in the owning route `index.py`, not in `main.py`.
+- Use `page()` to render the initial manager payload.
+- Store durable metadata in Prisma and store the browser-accessible blob separately under `public/assets/file-manager/`.
+- Use `pp.state(...)` plus `pp-for` for the list UI instead of manual `innerHTML` writes.
+- Add `public/assets/file-manager` to `PUBLIC_IGNORE_DIRS` in `settings/bs-config.ts` so runtime uploads do not trigger BrowserSync reloads during `npm run dev`.
+
+Read [file-uploads.md](./file-uploads.md) for the complete file-manager pattern.
 
 ## Auth, Roles, And Limits
 
@@ -255,6 +296,7 @@ If an AI agent is choosing how to load data in Caspian, apply these rules first.
 - Use `@rpc()` for backend functions that should be callable from the browser.
 - Use `pp.rpc()` for client-side calls; do not prefer older `pp.fetchFunction()` wording.
 - Prefer route-render data plus RPC over inventing parallel REST endpoints for normal Caspian page interactions.
+- Read [file-uploads.md](./file-uploads.md) when the task involves file pickers, upload progress, media libraries, or file-manager UI.
 - Use [cache.md](./cache.md) when a route's initial HTML should be reused across requests and invalidated after writes.
 - Use [state.md](./state.md) when an RPC mutation needs transient request-scoped success or error state outside the direct response payload.
 - Use `onStream` for streamed responses and `onUploadProgress` for upload-aware client calls.

package/dist/docs/file-uploads.md

@@ -0,0 +1,171 @@
+---
+title: File Uploads And File Managers
+description: Build Caspian file upload and file manager flows with route-local `@rpc()` actions, `pp.rpc()`, Prisma metadata, public asset storage, and BrowserSync-safe upload directories.
+related:
+  title: Related docs
+  description: Use fetch-data for the route versus RPC split, PulsePoint for client runtime behavior, database for Prisma persistence, project structure for file placement, validation for upload guards, and commands for local watcher behavior.
+  links:
+    - /docs/fetch-data
+    - /docs/pulsepoint
+    - /docs/database
+    - /docs/project-structure
+    - /docs/validation
+    - /docs/commands
+    - /docs/index
+---
+
+This page documents the recommended file upload and file manager pattern for this workspace and similar Caspian applications.
+
+Treat uploads as normal route behavior. Keep the owning browser UI in the route template, keep upload and delete `@rpc()` actions in the owning route `index.py`, and move reusable storage or persistence helpers into `src/lib/`.
+
+## Default Pattern
+
+- Keep first-render file manager data in `page()` so the initial HTML already contains the current asset list and storage summary.
+- Keep upload and delete actions in the route's `index.py`; do not move ordinary upload flows into `main.py`.
+- Keep reusable file-manager helpers in `src/lib/`.
+- Store uploaded blobs under `public/assets/file-manager/...` when the files should be browser-accessible.
+- Store durable metadata in Prisma, not in JSON manifests or ad hoc metadata files.
+- Use `pp.state(...)` plus `pp-for` to render and update the file list from returned server payloads.
+- Use `onUploadProgress` only for progress UI; let the RPC return refreshed manager data for the authoritative post-upload state.
+
+## Recommended Placement
+
+| Concern | Preferred location | Notes |
+| --- | --- | --- |
+| File picker UI, tabs, filters, progress state | `src/app/**/index.html` | Use PulsePoint state and template rendering. |
+| Upload and delete `@rpc()` actions | `src/app/**/index.py` | Keep these route-local so they stay close to the owning page. |
+| Shared storage, normalization, and persistence helpers | `src/lib/**` | Reuse helpers across routes without pushing route behavior into app bootstrap. |
+| Upload metadata model | `prisma/schema.prisma` | Persist owner, file name, MIME type, path, size, collection, and timestamps in Prisma. |
+| Browser-accessible uploaded blobs | `public/assets/file-manager/**` | Keep the public path predictable and derived from stored metadata. |
+| BrowserSync upload ignore | `settings/bs-config.ts` | Keep `public/assets/file-manager` in `PUBLIC_IGNORE_DIRS`. |
+
+## Route Flow
+
+The normal Caspian file-manager flow is:
+
+1. `page()` calls a shared helper such as `build_file_manager_payload(...)` and renders the first payload into the route template.
+2. The route template hydrates that payload into `pp.state(...)`.
+3. The file input calls `pp.rpc(...)` with a `File` object and optional `onUploadProgress` callback.
+4. The route-local `@rpc()` action validates auth, file presence, size, and routing-specific inputs.
+5. A shared helper writes the blob, creates or updates the Prisma row, and returns a serialized asset payload.
+6. The RPC action returns refreshed manager data.
+7. PulsePoint replaces the route state and `pp-for` rerenders the list.
+
+## Example Route-Local RPC
+
+```python
+from fastapi import File, UploadFile
+from casp.rpc import rpc
+
+from src.lib.dashboard.file_manager import (
+    build_file_manager_payload,
+    save_file_manager_upload,
+)
+
+@rpc(require_auth=True)
+async def upload_asset(file: UploadFile = File(...), collection: str = "auto"):
+    user_id = current_user_id()
+    content = await file.read()
+
+    uploaded = await save_file_manager_upload(
+        user_id,
+        file_name=file.filename or "file",
+        content=content,
+        mime_type=file.content_type,
+        desired_group=collection,
+    )
+
+    return {
+        "success": True,
+        "uploaded": uploaded,
+        "data": await build_file_manager_payload(user_id),
+    }
+```
+
+Keep route-specific auth checks, input validation, and final response shape here. Keep file naming, directory choice, and Prisma persistence in the shared helper.
+
+## Client Pattern
+
+```html
+<section class="files-page">
+  <input type="file" multiple onchange="{uploadSelectedFiles(event.target.files)}" />
+
+  <template pp-for="asset in assets">
+    <article key="{asset.id}">
+      <a href="{asset.url}">{asset.name}</a>
+    </article>
+  </template>
+
+  <script>
+    const [fileManagerData, setFileManagerData] = pp.state(initialFileManagerData);
+    const assets = fileManagerData.assets ?? [];
+
+    async function uploadSelectedFiles(fileList) {
+      for (const file of Array.from(fileList ?? [])) {
+        const response = await pp.rpc("upload_asset", { file }, {
+          onUploadProgress: (progress) => {
+            console.log(progress.percentage ?? 0);
+          },
+        });
+
+        if (response?.data) {
+          setFileManagerData(response.data);
+        }
+      }
+    }
+  </script>
+</section>
+```
+
+Prefer this state-driven shape over manual `innerHTML` list painting. In Caspian pages, manual DOM writes are easy to lose when PulsePoint rerenders the owner template.
+
+## Persistence Rules
+
+When Prisma is enabled, the durable record of an uploaded file should live in the database.
+
+- Write the blob to disk or object storage.
+- Write the metadata to Prisma.
+- Derive public URLs from the stored path.
+- On delete, remove both the stored file and its Prisma row.
+- Treat old JSON manifests only as migration input, not as the primary store.
+
+Typical metadata fields include:
+
+- owner or user relation
+- original file name
+- stored file name
+- asset path
+- MIME type
+- collection or grouping key
+- kind or preview type
+- size in bytes
+- uploaded timestamp
+
+## BrowserSync And Uploaded Public Files
+
+If runtime uploads write into `public/assets/file-manager/`, BrowserSync should ignore that directory during local development. Otherwise every upload can trigger a full browser reload.
+
+Use a workspace-relative ignore entry in `settings/bs-config.ts`:
+
+```ts
+const PUBLIC_IGNORE_DIRS = ["public/assets/file-manager"];
+```
+
+Match those entries against workspace-relative paths so nested uploads such as `public/assets/file-manager/user-1/media/example.png` are ignored too.
+
+## What To Avoid
+
+- Do not add ordinary upload routes or file-manager glue to `main.py`.
+- Do not use JSON files under `storage/` as the active metadata store when Prisma is enabled.
+- Do not treat `onUploadProgress` callbacks as the source of truth for the final asset list.
+- Do not manually repaint the file list with `innerHTML` when PulsePoint state can own the list.
+- Do not leave uploaded public directories out of BrowserSync ignore rules.
+
+## AI Routing Notes
+
+- Read this page first when the task mentions uploads, file pickers, file managers, media libraries, or upload progress UI.
+- Use `fetch-data.md` for the route-render versus RPC split.
+- Use `database.md` when Prisma models or relations must change for upload metadata.
+- Use `validation.md` for MIME, extension, and other boundary checks, then keep explicit size and auth checks in the owning RPC action.
+- Use `project-structure.md` for placement rules, especially `src/app/` versus `src/lib/` and `public/assets/file-manager/`.
+- Use `commands.md` and `settings/bs-config.ts` when uploads should not trigger BrowserSync reloads during `npm run dev`.

package/dist/docs/index.md

@@ -8,6 +8,7 @@ related:
     - /docs/installation
     - /docs/commands
     - /docs/mcp
+    - /docs/file-uploads
     - /docs/project-structure
     - /docs/components
 ---
@@ -46,12 +47,13 @@ The packaged Caspian docs distributed by the current toolchain also live here:
 - `components.md` - Create reusable Python components, template-backed UI, JSX-style imports, and the single-parent root rule for component HTML files
 - `pulsepoint.md` - Default reactive frontend runtime contract for component scripts, state, effects, directives, and client-side behaviors
 - `fetch-data.md` - Initial server-side data loading and browser-triggered RPC flows with `pp.rpc()`, streaming, uploads, and auth-aware actions
+- `file-uploads.md` - Route-local file uploads and file-manager flows with `@rpc()`, `pp.rpc()`, Prisma metadata, public asset storage, and BrowserSync ignore rules
 - `state.md` - Request-scoped server state with `StateManager`, session-backed JSON persistence, and listener callbacks for transient flows
 - `cache.md` - Route-level HTML caching with `Cache`, `CacheHandler`, TTL behavior, file-system storage, and invalidation patterns
 - `validation.md` - Input validation and sanitization with `Validate`, `Rule`, direct field checks, and multi-rule workflows for routes and RPC actions
 - `metadata.md` - Static and dynamic metadata, SEO inheritance, and Open Graph or Twitter card tags
 - `routing.md` - Next.js App Router-style file-based routing with `src/app`, dynamic segments, route groups, nested layouts, and single-root route templates
-- `project-structure.md` - Default Caspian layout and where routes, templates, shared code, and database files belong
+- `project-structure.md` - Default Caspian layout and where route files, reusable UI in `src/components/`, reusable non-UI code in `src/lib/`, and database files belong
 
 ## AI Awareness Notes
 
@@ -66,10 +68,12 @@ Preferred lookup order:
 5. Treat generated outputs such as `public/css/styles.css`, `settings/component-map.json`, `settings/files-list.json`, `__pycache__/`, and `.pyc` files as framework-managed artifacts when the local stack is intentionally running. They are not authored source files and should not be kept in the final diff unless the task explicitly requires them.
 6. Analyze `settings/component-map.json` and `settings/files-list.json` when you need the current generated view of components or routes, but do not hand-edit them. The framework regenerates them through `settings/component-map.ts` and `settings/files-list.ts` when the dev or build pipeline intentionally runs.
 7. Read `database.md` only when `caspian.config.json` enables Prisma, read `mcp.md` only when `caspian.config.json` enables MCP, and use `auth.md`, `components.md`, `pulsepoint.md`, `fetch-data.md`, `state.md`, `cache.md`, and `validation.md` as the next routing docs for those non-flagged concerns.
-8. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically, and treat `<!-- @import ... -->` comments as file-level directives that belong above the authored root element instead of inside `<div>`, `<section>`, or `<html>`. When several component tags come from one Python file, import them from that exact file path, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`.
-9. Prefer local docs before generating code, commands, or migration guidance.
-10. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
-11. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.
+8. Read `file-uploads.md` when the task mentions uploads, file pickers, file managers, media libraries, upload progress, or BrowserSync-safe public upload directories.
+9. As the app grows, standardize on `src/app/` for route-owned files, `src/components/` for reusable rendered UI, and `src/lib/` for reusable non-UI support code such as services, validators, adapters, and shared helpers.
+10. For authored component, route, and layout HTML files, generate exactly one top-level lowercase HTML element. Think React-style single parent wrapper: keep any owned PulsePoint logic in a plain `<script>` inside that root, do not handwrite `pp-component="..."` or `type="text/pp"` because Caspian injects those runtime attributes automatically, and treat `<!-- @import ... -->` comments as file-level directives that belong above the authored root element instead of inside `<div>`, `<section>`, or `<html>`. When several component tags come from one Python file, import them from that exact file path, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`.
+11. Prefer local docs before generating code, commands, or migration guidance.
+12. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
+13. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.
 
 ## Maintenance
 

package/dist/docs/installation.md

@@ -7,6 +7,7 @@ related:
   links:
     - /docs/commands
     - /docs/mcp
+    - /docs/file-uploads
     - /docs/routing
     - /docs/project-structure
     - /docs/index
@@ -92,6 +93,8 @@ If `npm run dev` is intentionally running, let that stack own generated outputs
 
 Inspect `settings/component-map.json` and `settings/files-list.json` when you need the generated component or route inventory, but do not hand-edit them. The framework refreshes them from `settings/component-map.ts` and `settings/files-list.ts`.
 
+If runtime uploads write into `public/assets/file-manager/`, keep that directory in `settings/bs-config.ts` `PUBLIC_IGNORE_DIRS` so BrowserSync does not reload on every uploaded file.
+
 ## After Setup
 
 Once the project is scaffolded:
@@ -101,6 +104,7 @@ Once the project is scaffolded:
 - Read `auth.md` before choosing public-vs-private route mode, wiring session config, sign-in or signout flows, route guards, or OAuth providers.
 - Read `pulsepoint.md` before generating interactive frontend behavior.
 - Read `fetch-data.md` before adding browser-triggered reads, writes, uploads, or streams.
+- Read `file-uploads.md` before building file pickers, media libraries, or Prisma-backed file-manager flows.
 - Read `validation.md` before handling forms, auth input, or RPC payloads.
 - Read `routing.md` to learn how `src/app` folders map to URLs.
 - Read `project-structure.md` to place route code, shared libraries, config, and database files in the correct directories.

package/dist/docs/project-structure.md

@@ -12,6 +12,7 @@ related:
     - /docs/routing
     - /docs/cache
     - /docs/database
+    - /docs/file-uploads
     - /docs/index
 ---
 
@@ -21,6 +22,8 @@ This page explains the default layout of a Caspian application, where Caspian co
 
 Caspian uses a lean project layout that keeps application code in `src`, database files in `prisma`, static assets in `public`, configuration in `caspian.config.json`, and framework internals in the installed package.
 
+As an app grows, keep reusable rendered UI in `src/components/`, keep reusable non-UI support code in `src/lib/`, and keep route-owned files in `src/app/`. That split keeps page composition separate from shared component and service code.
+
 In that layout, the default stack is Python components for reusable UI, PulsePoint in templates for reactive browser behavior, RPC for browser-triggered server calls, and `casp.validate` for input validation at route and action boundaries.
 
 For public pages that can safely reuse rendered HTML, Caspian also supports route-level page caching through `casp.cache_handler`.
@@ -31,12 +34,14 @@ Treat `caspian.config.json` as the single source of truth for optional feature e
 
 ## Top-Level Areas
 
-- `src/` contains routes, page templates, styles, and shared libraries.
-- `src/components/` contains reusable Python components and optional same-name HTML templates.
+- `src/` contains routes, page templates, styles, reusable components, and shared libraries.
+- `src/components/` contains reusable application UI components and optional same-name HTML templates.
+- `src/lib/` contains reusable non-UI code such as helpers, services, validators, adapters, and shared support modules.
 - `src/lib/auth/auth_config.py` contains auth-specific configuration for the app.
 - `src/lib/mcp/` contains the app-owned FastMCP server and nested FastMCP config when MCP is enabled.
 - `prisma/` contains the Prisma schema and seed scripts.
 - `public/` contains static assets served directly.
+- `settings/` contains BrowserSync, build, restart, and generated-project helper files.
 - `main.py` is the application entry point.
 - `caspian.config.json` is the core feature configuration file.
 - `.venv/Lib/site-packages/casp/` contains the installed Caspian framework core.
@@ -51,6 +56,9 @@ my-app/
   prisma/
     schema.prisma
     seed.ts
+  settings/
+    bs-config.ts
+    build.ts
   public/
   src/
     app/
@@ -105,6 +113,8 @@ See `routing.md` for the full App Router-style rules for dynamic segments, route
 
 Use this folder for reusable UI components that should be imported into route templates or other component templates.
 
+As the app grows, default to `src/components/` for application-level UI that will be shared across routes or features. Keep page-only markup close to the route in `src/app/`, but move shared cards, forms, shells, navigation, and other reusable visual building blocks into `src/components/`.
+
 The common Caspian pattern is a Python file such as `Button.py` with `@component`, optionally paired with a same-name HTML file such as `Button.html` when the component has richer markup or PulsePoint behavior.
 
 One Python file can also export multiple related `@component` functions. When that happens, import those tags from that exact file path in HTML, for example `<!-- @import { Breadcrumb, BreadcrumbItem, BreadcrumbList } from "../components/Breadcrumb.py" -->`, instead of assuming each tag has its own sibling `.py` file.
@@ -117,7 +127,11 @@ This workspace's component tooling scans `src/` based on `caspian.config.json`,
 
 ### `src/lib/`
 
-Use this folder for shared helpers, reusable validators, RPC-facing service wrappers, reusable UI utilities, and app-level support code.
+Use this folder for shared helpers, reusable validators, RPC-facing service wrappers, data-access helpers, formatting utilities, and other app-level support code that is not itself a reusable rendered component.
+
+If the code is primarily rendered UI that will be imported as a component tag, prefer `src/components/`. If the code is a helper, service, adapter, validator, or other non-visual support module, prefer `src/lib/`.
+
+For file upload and manager flows, keep route-owned `@rpc()` actions in `src/app/**/index.py` and keep shared storage, naming, filesystem, and Prisma-backed persistence helpers in `src/lib/`.
 
 This workspace already includes an app-owned Python database layer under `src/lib/prisma/`. Reuse that package for Python-side data access and keep any additional shared database helpers in `src/lib/`.
 
@@ -154,6 +168,10 @@ This folder contains your database model definitions in `schema.prisma` and any
 
 Store static assets here, including images, fonts, and generated frontend assets that should be served directly.
 
+Runtime-uploaded public blobs can also live here. In this workspace, file-manager uploads are stored under `public/assets/file-manager/`.
+
+If the local BrowserSync stack is running, keep that upload directory in `settings/bs-config.ts` `PUBLIC_IGNORE_DIRS` so new uploads do not force a full browser reload.
+
 ## Key Files
 
 ### `main.py`
@@ -179,6 +197,12 @@ AI agents should read this file before making almost any feature-level decision.
 
 In the current workspace, `caspian.config.json` shows `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
 
+### `settings/bs-config.ts`
+
+The BrowserSync watcher configuration for the local stack lives here.
+
+When runtime uploads write into `public/assets/file-manager/`, keep `public/assets/file-manager` in `PUBLIC_IGNORE_DIRS` and match it against workspace-relative paths so nested uploaded files do not trigger reloads.
+
 ### `src/lib/auth/auth_config.py`
 
 The project auth configuration file. Use this path when changing authentication behavior.
@@ -203,6 +227,8 @@ If this layout imports reusable components, place each `<!-- @import ... -->` co
 
 The backend logic for the route. This is where route behavior can load first-render data, expose `@rpc()` actions, and import framework features such as auth helpers, `casp.validate`, and route-level `Cache(...)` declarations.
 
+When a route owns a file manager or upload UI, keep the owning upload and delete `@rpc()` actions in that route's `index.py` and move reusable filesystem or Prisma helpers into `src/lib/`. Do not move ordinary upload behavior into `main.py`.
+
 ### `src/app/index.html`
 
 The route template. It supports standard HTML, `<!-- @import ... -->` component imports, and PulsePoint directives, and it should be the default place for reactive frontend behavior in Caspian.
@@ -241,12 +267,16 @@ If an AI agent is deciding where to make changes, use these rules first.
 - Treat `__pycache__/` directories, `.pyc` files, `public/css/styles.css`, `settings/component-map.json`, and `settings/files-list.json` as generated artifacts when the local stack is intentionally running. They are not authored source files.
 - Inspect `settings/component-map.json` and `settings/files-list.json` when you need the generated component or route inventory, but do not hand-edit them. The workspace regenerates them from `settings/component-map.ts` and `settings/files-list.ts`.
 - Put route templates and route-specific backend logic in `src/app/`.
+- As the app grows, keep route-owned code in `src/app/`, reusable rendered UI in `src/components/`, and reusable non-UI support code in `src/lib/`.
+- Read [file-uploads.md](./file-uploads.md) when the task involves upload widgets, media libraries, or file-manager flows.
 - Check [routing.md](./routing.md) when you need URL segment rules, layout nesting behavior, or dynamic route conventions.
 - Put reusable component files in `src/components/` and check [components.md](./components.md) for `@component`, `render_html(__file__)`, import comments, and single-root template rules.
+- When deciding between `src/components/` and `src/lib/`, use `src/components/` for anything rendered as reusable UI and `src/lib/` for helpers, services, validators, adapters, and shared business logic.
 - Use [mcp.md](./mcp.md) only when `caspian.config.json` enables MCP and the task involves FastMCP tool definitions, nested config discovery, or local MCP commands.
 - Keep `<!-- @import ... -->` comments above the single authored root element in route, layout, and component HTML files.
 - For route and component HTML files, always emit one top-level lowercase HTML element. Good: one wrapper containing the content and a plain `<script>` when needed. Bad: a wrapper element followed by a sibling top-level `<script>`, or handwritten `pp-component="..."` and `type="text/pp"` attributes in source.
 - Put shared helpers and reusable libraries in `src/lib/`.
+- Use `settings/bs-config.ts` when uploaded public assets should not trigger BrowserSync reloads during the local stack.
 - Put app-owned FastMCP code in `src/lib/mcp/` only when `caspian.config.json` enables MCP.
 - Use PulsePoint conventions in route templates for reactive frontend behavior.
 - Use `@rpc()` in route/backend code and `pp.rpc()` in client code for browser-triggered data flows.

package/dist/docs/pulsepoint.md

@@ -376,6 +376,7 @@ RPC notes:
 - Passing `true` as the third argument means `abortPrevious: true`.
 - The options object supports `abortPrevious`, `onStream`, `onStreamError`, `onStreamComplete`, `onUploadProgress`, and `onUploadComplete`.
 - File uploads switch to the XHR path when upload progress callbacks are needed.
+- For file managers, use upload callbacks for progress UI but replace the asset list from returned RPC state with `pp.state(...)` and `pp-for` instead of manual DOM repainting. See [file-uploads.md](./file-uploads.md).
 - Streamed `text/event-stream` responses are supported when a stream handler is provided.
 - Redirect headers are honored through `pp.redirect()`.
 
@@ -419,6 +420,7 @@ Use these rules when generating or editing PulsePoint runtime code:
 - Use native `on*` attributes, not framework-specific event syntax.
 - Use refs and portals only through the implemented `pp` APIs.
 - Use `pp.rpc()` for the bundled runtime API instead of older `pp.fetchFunction()` wording.
+- For upload managers, keep the authoritative asset list in `pp.state(...)` and route uploads through `pp.rpc()` with `onUploadProgress` as needed.
 - Avoid generating internal runtime attributes.
 - Avoid scriptless nested components when the child template contains its own bindings.
 - Prefer authored-template examples over runtime-inspected HTML examples unless the doc is specifically explaining runtime internals.

package/dist/docs/routing.md

@@ -8,6 +8,7 @@ related:
     - /docs/project-structure
     - /docs/components
     - /docs/cache
+    - /docs/file-uploads
     - /docs/metadata
     - /docs/pulsepoint
     - /docs/index
@@ -169,6 +170,8 @@ async def page():
 
 Use this pattern when the route needs to fetch data, compute metadata, or do other non-blocking server work before rendering.
 
+When a route owns a file manager or upload UI, keep the owning upload and delete `@rpc()` actions in that same `index.py` and move reusable filesystem or Prisma helpers into `src/lib/`. Do not move ordinary upload behavior into `main.py`. See [file-uploads.md](./file-uploads.md).
+
 For static and dynamic metadata rules, inheritance order, and social card fields, see [metadata.md](./metadata.md).
 
 If the rendered HTML for that route is public and safe to reuse, declare route-level caching in the same file with `Cache(...)`. See [cache.md](./cache.md).

package/dist/docs/validation.md

@@ -203,6 +203,8 @@ The installed file includes upload-oriented helpers and rules.
 
 Use these rules for RPC uploads and form submissions that accept files.
 
+Combine them with explicit auth, size, and storage-boundary checks in the owning RPC action before writing files to disk or Prisma. See [file-uploads.md](./file-uploads.md) for the recommended file-manager pattern.
+
 ## Sanitization
 
 Validation in Caspian is more than rule checking. The installed implementation also sanitizes or normalizes several values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caspian-utils",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Caspian tooling",
   "main": "index.js",
   "scripts": {