caspian-utils 0.0.14 → 0.0.16

package/dist/docs/auth.md

@@ -1,6 +1,6 @@
 ---
 title: Authentication
-description: Manage session-backed authentication in Caspian with `casp.auth`, `AuthSettings`, the global `auth` object, centralized `auth_config.py`, page decorators, RPC protection, role-based routes, and optional Google or GitHub OAuth providers.
+description: Use this page when the task mentions `auth_config.py`, sign-in, signout, protected routes, `require_auth`, RBAC, auth decorators, or Google or GitHub OAuth in Caspian.
 related:
   title: Related docs
   description: Use the fetch-data guide when sign-in or signout happens through RPC, then use the state guide for transient auth-adjacent request state, validation to guard credentials, and routing or project structure to place auth files correctly.
@@ -113,7 +113,7 @@ Important behavior from the current implementation:
 - `default_token_validity` is parsed by the installed auth runtime with the format `^\d+(s|m|h|d)$`. Use values such as `30m`, `1h`, or `7d`.
 - `token_auto_refresh` only changes behavior when the request lifecycle calls `auth.refresh_session()`. In the installed `auth.py`, the flag alone does not refresh expiry by itself.
 - The framework `AuthSettings` dataclass defaults `is_all_routes_private=True`, but the project example above explicitly changes that to `False`.
-- In generated app-owned config like this workspace, `src/lib/auth/auth_config.py` starts with `is_all_routes_private=False`, so routes are public by default until the app chooses stricter route protection.
+- In generated app-owned starter config, `src/lib/auth/auth_config.py` starts with `is_all_routes_private=False`, so routes are public by default until the app chooses stricter route protection.
 - `public_routes`, `auth_routes`, `private_routes`, and `role_based_routes` are exact path matches in the installed `Auth` methods.
 - `private_routes` matters only when `is_all_routes_private=False`.
 - `role_based_routes` currently expects `PATH -> [ROLES]`, not role names keyed to paths the other way around.
@@ -124,7 +124,7 @@ Important behavior from the current implementation:
 
 Make this decision at app setup time in `src/lib/auth/auth_config.py`.
 
-- In the default app-owned starter pattern used in this workspace, routes start public because `is_all_routes_private=False` in `src/lib/auth/auth_config.py`.
+- In the default app-owned starter pattern, routes start public because `is_all_routes_private=False` in `src/lib/auth/auth_config.py`.
 - If the application has only a few public pages and most routes require auth, set `is_all_routes_private=True` and list the exceptions in `public_routes`.
 - If the application has many public pages and only a few protected areas, keep `is_all_routes_private=False` and list only the protected routes in `private_routes`.
 - In the current runtime, `auth_routes=["/signin", "/signup"]` stays public by default, and most apps do not need to change it unless the user explicitly asks for different auth routes.
@@ -756,14 +756,14 @@ Common placement patterns are:
 
 For browser-triggered auth forms, pair this page with `fetch-data.md`. For credential and form validation, pair it with `validation.md`.
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is deciding how to handle auth in Caspian, apply these rules first.
 
 - Treat `casp.auth` as the default authentication layer.
 - Centralize route visibility, redirects, and RBAC policy in `src/lib/auth/auth_config.py`.
 - Decide route mode early in `src/lib/auth/auth_config.py`: use `is_all_routes_private=True` when most routes should require auth, otherwise keep `is_all_routes_private=False` and list protected routes in `private_routes`.
-- In app-owned starter config like this workspace, treat `is_all_routes_private=False` as the default starting point, which means routes begin public until the app opts into stricter protection.
+- In app-owned starter config, treat `is_all_routes_private=False` as the default starting point, which means routes begin public until the app opts into stricter protection.
 - Treat `public_routes` as the public exception list for all-private apps. In the current defaults, `/` stays public and `auth_routes=["/signin", "/signup"]` stays public too.
 - Apply settings at startup in `main.py` with `configure_auth(build_auth_settings())`.
 - Register provider instances in `main.py` with `Auth.set_providers(...)` when Google or GitHub OAuth is enabled.

package/dist/docs/cache.md

@@ -1,6 +1,6 @@
 ---
 title: Cache
-description: Cache rendered Caspian route HTML with `casp.cache_handler`, `Cache`, and `CacheHandler`, using route-level TTLs, file-system storage, and explicit invalidation for public read-heavy pages.
+description: Use this page when the task mentions `Cache`, `CacheHandler`, page caching, route HTML reuse, TTLs, or invalidation in Caspian.
 related:
   title: Related docs
   description: Use the routing guide to place route-level cache declarations correctly, then pair cache with fetch-data when deciding what can be safely served from reused HTML.
@@ -242,7 +242,7 @@ Poor candidates are:
 - forms whose server-rendered HTML includes request-specific or sensitive state
 - pages that need sub-second freshness unless you have reliable invalidation hooks
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is deciding whether or how to cache a Caspian route, apply these rules first.
 

package/dist/docs/commands.md

@@ -1,6 +1,6 @@
 ---
 title: Commands
-description: Use the current Caspian CLI reference to choose the right scaffold, starter-kit, update, and Prisma regeneration workflow for the current workspace.
+description: Use this Caspian command reference for scaffolding, project updates, feature enablement, builds, and ORM regeneration. Use when the task mentions `create-caspian-app`, `casp update project`, `npm run dev`, `npm run build`, `prisma migrate`, or `ppy generate`.
 related:
   title: Related docs
   description: Start with installation for new apps, then use database, MCP, and structure docs when commands affect schema, server tooling, generated ORM files, or project layout.
@@ -8,18 +8,19 @@ related:
     - /docs/installation
     - /docs/database
     - /docs/mcp
+    - /docs/file-uploads
     - /docs/routing
     - /docs/project-structure
     - /docs/index
 ---
 
-This page documents the current Caspian command families used with this workspace and the surrounding docs toolchain.
+This page documents the main Caspian command families and the checks an AI agent should make before running them in a project.
 
 ## Overview
 
-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.
+Project creation, project updates, and Python ORM generation are commonly driven through `npx` workflows plus any project-local `package.json` scripts that a given project defines.
 
-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`.
+Do not assume a local binary, script, or generated file exists just because a doc mentions it. Confirm the actual `package.json`, repository tree, and `caspian.config.json` values in the project you are working on.
 
 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.
 
@@ -32,7 +33,7 @@ This updated reference includes the newer updater behavior and the current scaff
 - Windows-safe execution that resolves `npx.cmd` on Win32
 - scaffold behavior that reuses an existing `.venv` instead of recreating it every time
 
-Before running update commands, read `caspian.config.json` because it controls feature flags and `excludeFiles` overwrite protection. In the current workspace that config shows `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+Before running update commands, read `caspian.config.json` because it controls feature flags and any `excludeFiles` overwrite protection.
 
 Treat `caspian.config.json` as the single source of truth for optional feature enablement. Use feature-specific docs, files, or commands only after the matching flag is confirmed as enabled.
 
@@ -81,7 +82,9 @@ npm run dev
 
 Use when the user explicitly wants the local BrowserSync plus PostCSS development stack.
 
-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.
+Only use this when the current project's `package.json` actually defines `npm run dev`.
+
+Long-running local stack commands can regenerate framework-owned outputs such as built CSS, generated component maps, route maps, `__pycache__/`, and `.pyc` files. Treat project-specific generated outputs as artifacts when those workflows intentionally run.
 
 ### Build generated assets for deployment
 
@@ -91,6 +94,8 @@ npm run build
 
 Use when preparing deployment or when the user explicitly asks for a build.
 
+Only use this when the current project's `package.json` actually defines `npm run build`.
+
 Do not use `npm run build` as the default validation step for routine route, feature, or documentation edits.
 
 ### Regenerate ORM after schema changes
@@ -117,6 +122,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 any runtime upload directory that the project uses in the BrowserSync ignore list so uploads do not trigger reloads on every new blob.
 - Do not edit `__pycache__/` directories or `.pyc` files, and do not leave them in the final diff.
 
 ## 3. Supported Flags And Options
@@ -579,7 +585,7 @@ Result: parsing error because more than one version source was provided.
 
 ## 8. Prisma And Python ORM Regeneration
 
-The create and update commands above are not the whole maintenance story for this workspace. When `prisma/schema.prisma` changes, follow the ORM flow below so the TypeScript Prisma client, database state, and Python ORM layer stay aligned.
+The create and update commands above are not the whole maintenance story for a Prisma-enabled Caspian project. When `prisma/schema.prisma` changes, follow the ORM flow below so the TypeScript Prisma client, database state, and Python ORM layer stay aligned.
 
 ### Required order after schema changes
 
@@ -659,7 +665,7 @@ If you exclude a file, the updater preserves it, but you are responsible for mer
 4. Starter kits still support later overrides via explicit CLI flags.
 5. Frontend-oriented flags are only fully meaningful when `backendOnly` is false.
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is deciding which command flow to use, apply these rules first.
 

package/dist/docs/components.md

@@ -1,6 +1,6 @@
 ---
 title: Components
-description: Create reusable Caspian components as `@component` Python functions, import them into templates as `<MyComponent />`, and split interactive UI into same-name HTML templates when PulsePoint logic is involved.
+description: Use this page when the task mentions `@component`, reusable UI, component imports, same-name `.html` templates, or where shared components belong in a Caspian project.
 related:
   title: Related docs
   description: Use the structure guide for file placement, the routing guide for route templates, the PulsePoint guide for browser-side scripts, and the data guide for component-owned RPC flows.
@@ -16,7 +16,7 @@ Components in Caspian are Python functions decorated with `@component`.
 
 Import them into a template with an `@import` comment, then render them with JSX-style tags such as `<MyComponent />` or `<MyComponent>...</MyComponent>`.
 
-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.
+Component tooling scans Python files under the paths listed in `caspian.config.json`. When `componentScanDirs` includes `src/`, `src/components/` is the clean default location for reusable UI, even though any scanned path 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/`.
 

package/dist/docs/database.md

@@ -1,6 +1,6 @@
 ---
 title: Database
-description: Use Prisma in this workspace through `prisma/schema.prisma`, `prisma.config.ts`, migrations, seeding, and the generated client defined by the local schema.
+description: Use this page when the task mentions Prisma, `schema.prisma`, `prisma.config.ts`, migrations, `seed.ts`, Prisma Client, or `ppy generate` in a Caspian project.
 related:
   title: Related docs
   description: Use the project structure guide to place database files correctly, then use the fetch-data guide when Prisma calls need to power route rendering or RPC actions.
@@ -12,9 +12,9 @@ related:
     - /docs/index
 ---
 
-This page documents the Prisma workflow present in this workspace.
+This page documents the Prisma workflow for Caspian projects where `caspian.config.json` enables Prisma.
 
-This repo currently uses Prisma for schema management, migrations, and seed tooling on the Node side. The local `prisma/schema.prisma` uses `generator client { provider = "prisma-client-js" }`, `prisma.config.ts` seeds through `tsx prisma/seed.ts`, and this workspace already includes an app-owned Python database layer under `src/lib/prisma/`. If Python routes or RPC actions need database access, reuse that package instead of creating another helper.
+When a project enables Prisma, use `prisma/schema.prisma` for schema management, `prisma.config.ts` for Prisma config and seed wiring, and reuse an app-owned `src/lib/prisma/` package when the project includes one.
 
 Treat `caspian.config.json` as the single source of truth for whether Prisma is enabled in a workspace. If `prisma` is false and the user wants Prisma, ask first, then update `caspian.config.json` and run `npx casp update project` before assuming Prisma-managed files exist.
 
@@ -102,7 +102,7 @@ model Post {
 }
 ```
 
-After changing the schema, use this order in the current workspace:
+After changing the schema, use this order:
 
 1. Run `npx prisma migrate dev`.
 2. If seed data or the seed script needs the new schema, run `npx prisma generate` and then `npx prisma db seed`.
@@ -129,21 +129,21 @@ Default rule:
 - Use migrations for tracked application changes.
 - Use `db push` only when you intentionally want a faster, migration-free prototype loop.
 
-## Prisma Files In This Workspace
+## Prisma Files To Inspect
 
-The current repo ships Prisma files in these locations:
+In a Prisma-enabled Caspian project, inspect these locations:
 
 ### `prisma/schema.prisma`
 
-This file is the schema source of truth. It currently defines a `prisma-client-js` generator.
+This file is the schema source of truth. Confirm the actual datasource and generator configuration in the current project.
 
 ### `prisma.config.ts`
 
-This file configures the schema path, migrations path, and the seed entry point. In this workspace it runs seeds through `tsx prisma/seed.ts`.
+This file configures the schema path, migrations path, and the seed entry point. Confirm the actual seed command and import path in the current project.
 
 ### `prisma/seed.ts`
 
-This file is the current example of code that imports and uses the generated Prisma client.
+This file is the project-local example of code that imports and uses the generated Prisma client.
 
 ### `node_modules/@prisma/client/`
 
@@ -151,13 +151,13 @@ After `npx prisma generate`, Prisma writes the generated JavaScript client into
 
 ### `src/lib/prisma/`
 
-This workspace already includes an app-owned async Python database package that exports `prisma`, `PrismaClient`, generated models, and helper types.
+If the project includes an app-owned async Python database package here, it typically exports `prisma`, `PrismaClient`, generated models, and helper types.
 
 If Python route or RPC code needs database access, import from `src.lib.prisma` and keep that import path explicit in application code. Refresh generated classes with `npx ppy generate` instead of editing them manually.
 
 ## Python Route Usage
 
-This workspace already ships an app-owned Python Prisma-style layer under `src/lib/prisma/`. Treat it as async-first and reuse it from route and RPC code.
+If the project ships an app-owned Python Prisma-style layer under `src/lib/prisma/`, treat it as async-first and reuse it from route and RPC code.
 
 Example:
 
@@ -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
@@ -326,7 +338,7 @@ Use raw SQL sparingly. Prefer the generated Prisma API when the query can be exp
 - Validate incoming mutation data before calling `create`, `update`, or `delete` operations.
 - Prefer Prisma queries over raw SQL, and prefer raw SQL over undocumented custom query helpers.
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is working on a Caspian app with Prisma enabled, apply these rules first.
 
@@ -336,8 +348,9 @@ If an AI agent is working on a Caspian app with Prisma enabled, apply these rule
 - If the schema change requires seed data, run `npx prisma generate` and then `npx prisma db seed`.
 - Run `npx ppy generate` after schema changes to refresh the Python ORM classes.
 - 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.
+- Read `prisma.config.ts` and `prisma/seed.ts` when you need the current project'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

@@ -1,6 +1,6 @@
 ---
 title: Fetch Data
-description: Fetch first-render and interactive data in Caspian with async route functions, `@rpc()` actions, `pp.rpc()`, streaming, and uploads, with RPC as the default browser-to-server data path.
+description: Use this page when the task mentions `page()`, `layout()`, `@rpc()`, `pp.rpc()`, streaming, interactive fetches, uploads, or browser-triggered data loads in Caspian.
 related:
   title: Related docs
   description: Use the routing guide to place route logic correctly, then use the auth guide for protected actions, the MCP guide for AI-facing tools, the state guide for transient request-scoped mutation state, the cache guide for reusable first-render HTML, and the PulsePoint runtime guide for client-side `pp.rpc()` details.
@@ -9,6 +9,7 @@ related:
     - /docs/mcp
     - /docs/state
     - /docs/database
+    - /docs/file-uploads
     - /docs/cache
     - /docs/routing
     - /docs/pulsepoint
@@ -20,7 +21,7 @@ This page explains how data fetching works in Caspian. Use route functions for i
 
 Treat RPC as the default way for browser code to talk to Python in Caspian. Do not reach for ad hoc fetch calls to custom JSON endpoints, alternate transport layers, or older helper names unless the task explicitly requires that shape.
 
-MCP is a separate integration surface. Do not place app-owned FastMCP tools in route `index.py` files or treat `@rpc()` actions as a replacement for MCP tools. Use `mcp.md` and `src/lib/mcp/` only when `caspian.config.json` has `mcp: true`. In this workspace, `mcp: false`, so do not assume those files exist.
+MCP is a separate integration surface. Do not place app-owned FastMCP tools in route `index.py` files or treat `@rpc()` actions as a replacement for MCP tools. Use `mcp.md` and `src/lib/mcp/` only when `caspian.config.json` has `mcp: true`. If `mcp` is false, do not assume those files exist.
 
 ## Overview
 
@@ -73,7 +74,7 @@ Notes:
 - Put shared section-level props in `layout.py` when multiple child routes need the same synchronous payload. The current layout engine does not await `layout()`.
 - Keep reusable database or API clients under `src/lib/`; keep route-specific orchestration in `src/app/`.
 
-If the data source is Prisma, confirm `caspian.config.json` has `prisma: true`, then see `database.md` for the current workspace's schema, migration, and generation workflow. In this workspace, Prisma is enabled and the app-owned Python database layer lives under `src/lib/prisma/`.
+If the data source is Prisma, confirm `caspian.config.json` has `prisma: true`, then see `database.md` for the project's schema, migration, and generation workflow. If the project includes an app-owned Python database layer under `src/lib/prisma/`, reuse it instead of creating another helper.
 
 ## Interactive Data With RPC
 
@@ -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
 
@@ -244,7 +285,7 @@ A common pattern is:
 
 If the first-render HTML is expensive to produce and safe to share between visitors, add route-level caching with [cache.md](./cache.md) and invalidate affected URIs after successful mutations.
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is choosing how to load data in Caspian, apply these rules first.
 
@@ -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: Use this page when the task mentions file uploads, file managers, file pickers, upload progress, public storage paths, or BrowserSync-safe upload directories in Caspian.
+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 Caspian projects.
+
+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 a project-owned public directory such as `public/storage/...` 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/storage/**` or another app-owned public directory | Keep the public path predictable and derived from stored metadata. |
+| BrowserSync upload ignore | `settings/bs-config.ts` | Keep the active public upload directory 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 Retrieval 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

@@ -1,6 +1,6 @@
 ---
 title: Caspian Docs
-description: Caspian documentation with AI-aware routing to the right local docs before framework-specific code generation or project setup changes, with components, PulsePoint, RPC, and Validate as the default app stack.
+description: Packaged Caspian documentation manifest for AI task routing, feature discovery, and file placement. Use this page when deciding which Caspian doc to read first or which feature guide applies.
 related:
   title: Next Steps
   description: Start with installation, review the CLI commands, then use the structure and component guides to place Caspian files correctly.
@@ -8,15 +8,18 @@ related:
     - /docs/installation
     - /docs/commands
     - /docs/mcp
+    - /docs/file-uploads
     - /docs/project-structure
     - /docs/components
 ---
 
-This directory contains the local Caspian documentation set for quick reference and AI-aware routing.
+This directory contains the packaged Caspian documentation set for AI-aware feature discovery, task routing, and file-placement guidance.
 
-Before making feature, tooling, or file-placement decisions in a Caspian workspace, read `./caspian.config.json` almost immediately. That file is the project feature gate and tells you which capabilities are enabled, such as Prisma, MCP, TypeScript, Tailwind, backend-only mode, and component scan directories.
+Treat these docs as reusable Caspian feature guidance. Treat `./caspian.config.json` as the single source of truth for which optional features are enabled in the project being analyzed.
 
-Treat `caspian.config.json` as the single source of truth for optional feature enablement. Use feature-specific docs only after the matching flag is confirmed as enabled. If a feature is disabled and the user wants it, ask whether they want to enable it first, then follow the update workflow in `commands.md`.
+The docs can mention optional features even when those features are disabled in a project. Their job is to explain how a feature works, when a doc applies, and which files to inspect next once the feature is confirmed as relevant.
+
+Before making feature, tooling, or file-placement decisions in a Caspian project, read `./caspian.config.json` almost immediately. That file tells you which optional capabilities are enabled, such as Prisma, MCP, TypeScript, Tailwind, backend-only mode, and component scan directories.
 
 ## Default Stack
 
@@ -28,11 +31,7 @@ When generating or editing a Caspian app, treat these as the default choices unl
 
 ## Docs Location
 
-The local AI-aware docs for this workspace live here:
-
-- `node_modules/caspian-utils/dist/docs/`
-
-The packaged Caspian docs distributed by the current toolchain also live here:
+The packaged Caspian docs referenced by this index live here:
 
 - `node_modules/caspian-utils/dist/docs/`
 
@@ -40,12 +39,13 @@ The packaged Caspian docs distributed by the current toolchain also live here:
 
 - `installation.md` - First-time setup flow for creating a new Caspian application
 - `commands.md` - Main Caspian CLI workflows for project creation, generation, updates, and config-aware maintenance
-- `mcp.md` - MCP-specific layout, launch flow, and AI routing rules for workspaces where `caspian.config.json` enables MCP
-- `database.md` - Prisma schema, migration, seed, and client-generation workflow for workspaces where `caspian.config.json` enables Prisma, plus Python-side helper caveats
+- `mcp.md` - MCP-specific layout, launch flow, and AI routing rules for projects where `caspian.config.json` enables MCP
+- `database.md` - Prisma schema, migration, seed, and client-generation workflow for projects where `caspian.config.json` enables Prisma, plus Python-side helper caveats
 - `auth.md` - Session-backed authentication with `casp.auth`, centralized `auth_config.py`, public-vs-private route mode guidance, RPC-first signout guidance, RBAC, and OAuth provider helpers
 - `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
@@ -53,24 +53,19 @@ The packaged Caspian docs distributed by the current toolchain also live here:
 - `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 route files, reusable UI in `src/components/`, reusable non-UI code in `src/lib/`, and database files belong
 
-## AI Awareness Notes
+## AI Retrieval Notes
 
-If an AI tool needs Caspian project documentation, start with this directory and use this file as the manifest.
+If an AI tool needs Caspian documentation, start with this directory and use this file as the manifest.
 
 Preferred lookup order:
 
 1. Read `node_modules/caspian-utils/dist/docs/index.md` to discover available local docs.
-2. Read `./caspian.config.json` before making any feature assumption. Use it to confirm which project capabilities are enabled and which directories or tooling rules apply.
+2. Read `./caspian.config.json` before making any feature assumption. A doc existing in the package does not mean that feature is enabled in the current project.
 3. Treat `caspian.config.json` as the single source of truth for optional features. Use feature-specific docs only when the matching flag is enabled. If a feature is disabled and the user wants it, ask first, then update `caspian.config.json` and follow the update workflow in `commands.md`.
-4. Read `commands.md` before running any `package.json` script. In this workspace, npm scripts are opt-in operational commands, not default validation steps. Do not run them unless the user explicitly asks, the task genuinely requires that exact script, or deployment preparation needs `npm run build`.
-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. 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.
-9. 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" -->`.
-10. Prefer local docs before generating code, commands, or migration guidance.
-11. Check `node_modules/caspian-utils/dist/docs/` for packaged Caspian docs when local docs need more detail.
-12. Only fall back to upstream documentation when local and packaged markdown do not cover the topic.
+4. After the feature is confirmed, inspect the actual project files that decide behavior, such as `package.json`, `main.py`, `src/app/**`, `src/lib/**`, `settings/**`, `prisma/**`, and the installed `casp` runtime.
+5. Use `commands.md` for scaffold and update workflows, `project-structure.md` for placement decisions, and the feature docs such as `mcp.md`, `database.md`, `auth.md`, `fetch-data.md`, and `file-uploads.md` for task-specific guidance.
+6. Prefer packaged Caspian docs before upstream documentation when generating code, commands, or migration guidance.
+7. Keep `index.md` and cross-links aligned so AI can quickly discover the right doc.
 
 ## Maintenance
 

package/dist/docs/installation.md

@@ -1,12 +1,13 @@
 ---
 title: Installation
-description: Learn how to create a new Caspian application so AI agents use the first-time setup flow instead of assuming an existing project is already in place.
+description: Use this page when creating a new Caspian application, scaffolding a project, running first-time setup, or choosing optional features during install.
 related:
   title: Related docs
   description: Continue with the routing, structure, and MCP guides after scaffold so the new app follows Caspian conventions and keeps optional FastMCP files in the right place.
   links:
     - /docs/commands
     - /docs/mcp
+    - /docs/file-uploads
     - /docs/routing
     - /docs/project-structure
     - /docs/index
@@ -18,7 +19,7 @@ This page documents the first-time Caspian setup flow for new applications.
 
 Caspian provides a scaffold flow for new apps with a FastAPI backend and a PulsePoint-based reactive frontend workflow.
 
-In this workspace, the local `caspian-utils` package ships documentation only, so scaffold commands are resolved through external `npx` packages rather than project-local binaries.
+These packaged docs can exist inside an already-created Caspian project, but scaffold commands themselves are typically resolved through external `npx` packages rather than from this docs directory.
 
 ## Default App Stack
 
@@ -60,7 +61,7 @@ After scaffold, read `caspian.config.json` and treat it as the single source of
 
 If a feature is disabled and the user wants it later, ask whether they want to enable it first, then update `caspian.config.json` and run `npx casp update project` so framework-managed files align with the new feature set.
 
-If the project enables MCP, use `mcp.md` after scaffold to place the app-owned FastMCP server and config files correctly for the current workspace conventions.
+If the project enables MCP, use `mcp.md` after scaffold to place the app-owned FastMCP server and config files correctly for that project's conventions.
 
 ## Recommended VS Code Setup
 
@@ -84,7 +85,7 @@ cd my-app
 npm run dev
 ```
 
-In this workspace, `npm run dev` is backed by BrowserSync plus PostCSS watchers, not a Vite dev server.
+Confirm what `npm run dev` does in the generated project's `package.json`. Many Caspian projects use BrowserSync plus PostCSS watchers rather than a Vite dev server, but the actual script wins.
 
 For AI agents and other automated helpers, this is an opt-in local-stack command, not a default validation step. Do not run `package.json` scripts just because a route, feature, or doc changed.
 
@@ -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 a public upload directory, 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,11 +104,12 @@ 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.
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is reading this page, treat it as the source for new-project installation steps.
 

package/dist/docs/mcp.md

@@ -1,6 +1,6 @@
 ---
 title: MCP
-description: Check `caspian.config.json` first. When it enables MCP, this page becomes the relevant guide for reviewing, fixing, launching, and extending the workspace MCP feature.
+description: Check `caspian.config.json` first. Use this page when the task mentions MCP, FastMCP, `mcp_server.py`, `fastmcp.json`, tool servers, or enabling MCP in a Caspian project.
 related:
   title: Related docs
   description: Start with project structure for file placement, then use commands for feature enablement and local run flows, and index for documentation routing.
@@ -11,9 +11,9 @@ related:
     - /docs/index
 ---
 
-This page documents the Model Context Protocol workflow for Caspian workspaces.
+This page documents the Model Context Protocol workflow for Caspian projects.
 
-Treat `caspian.config.json` as the single source of truth for whether MCP is enabled. If `caspian.config.json` confirms `"mcp": true`, this page is relevant, the MCP-specific files in the workspace are the correct files to analyze, and the feature can be reviewed, fixed, launched, or extended here.
+Treat `caspian.config.json` as the single source of truth for whether MCP is enabled. If `caspian.config.json` confirms `"mcp": true`, this page is relevant, the MCP-specific files in the project are the correct files to analyze, and the feature can be reviewed, fixed, launched, or extended here.
 
 If `caspian.config.json` has `"mcp": false`, treat this page as reference material only. Do not assume `src/lib/mcp/**`, `settings/restart-mcp.ts`, or MCP-related npm scripts exist until the user chooses to enable MCP and the update workflow has run.
 
@@ -22,35 +22,35 @@ If `caspian.config.json` has `"mcp": false`, treat this page as reference materi
 1. Read `caspian.config.json` and confirm `mcp: true` before assuming MCP files or scripts should exist.
 2. If `mcp` is false and the user wants MCP, ask for confirmation first.
 3. After the user confirms, update `caspian.config.json` and run `npx casp update project` so framework-managed MCP files align with the new feature set.
-4. After the update, inspect the actual `package.json`, `src/lib/mcp/`, and any launcher files that the workspace now contains.
+4. After the update, inspect the actual `package.json`, `src/lib/mcp/`, and any launcher files that the project now contains.
 
-## MCP-Enabled Workspace Layout
+## MCP-Enabled Project Layout
 
 When `caspian.config.json` has `mcp: true`, these are the main MCP surfaces to inspect:
 
 - `src/lib/mcp/mcp_server.py` for the app-owned FastMCP server, tool definitions, instructions, and MCP-specific helper logic.
 - `src/lib/mcp/fastmcp.json` for the default FastMCP config, transport, host, port, path, and server entrypoint.
-- `settings/restart-mcp.ts` for workspace-specific launcher logic, discovery order, environment overrides, or log filtering when that file is present.
-- `package.json` for the actual MCP-related scripts that the current workspace defines.
+- `settings/restart-mcp.ts` for project-specific launcher logic, discovery order, environment overrides, or log filtering when that file is present.
+- `package.json` for the actual MCP-related scripts that the current project defines.
 
-If these files exist in the workspace, they are the right files to analyze when reviewing or fixing MCP behavior.
+If these files exist in the project, they are the right files to analyze when reviewing or fixing MCP behavior.
 
 ## What To Review
 
 When `mcp: true` and an MCP issue needs investigation, inspect the files in this order:
 
 1. `caspian.config.json` to confirm the feature is enabled.
-2. `package.json` to see which MCP scripts the workspace actually exposes.
+2. `package.json` to see which MCP scripts the project actually exposes.
 3. `src/lib/mcp/mcp_server.py` for tool implementation and server behavior.
 4. `src/lib/mcp/fastmcp.json` for config and entrypoint details.
-5. `settings/restart-mcp.ts` when the workspace includes it and launcher behavior is part of the issue.
+5. `settings/restart-mcp.ts` when the project includes it and launcher behavior is part of the issue.
 
 ## Running MCP
 
-Only when `caspian.config.json` has `mcp: true` and the relevant files or scripts exist:
+Only when `caspian.config.json` has `mcp: true` and the relevant files or scripts exist in the project:
 
-- Use the workspace-defined `npm run mcp` command when `package.json` provides it.
-- Use `npm run dev` only if the workspace wires MCP into the full local stack and the user explicitly wants that full stack running.
+- Use the project-defined `npm run mcp` command when `package.json` provides it.
+- Use `npm run dev` only if the project wires MCP into the full local stack and the user explicitly wants that full stack running.
 - Use direct FastMCP commands against `src/lib/mcp/fastmcp.json` when that config file exists, for example:
 
 ```powershell
@@ -58,18 +58,12 @@ Only when `caspian.config.json` has `mcp: true` and the relevant files or script
 .venv\Scripts\fastmcp.exe run src/lib/mcp/fastmcp.json --no-banner
 ```
 
-Because script names and launcher wiring can vary by workspace version, always confirm the actual scripts in `package.json` instead of assuming them from docs alone.
+Because script names and launcher wiring can vary by project, always confirm the actual scripts in `package.json` instead of assuming them from docs alone.
 
-## Current Workspace Status
-
-- `caspian.config.json` currently has `mcp: false`.
-- `package.json` does not currently define `npm run mcp`.
-- The current repo tree should not be treated as if `src/lib/mcp/**` is guaranteed to exist.
-
-## AI Routing Notes
+## AI Retrieval Notes
 
 1. Read `caspian.config.json` first.
 2. If `mcp` is false, do not infer MCP files, scripts, or launch flow from generic Caspian examples.
 3. If the user wants MCP while it is disabled, ask first, then update `caspian.config.json` and use `npx casp update project` before continuing.
-4. If `mcp` is true, this page becomes the relevant MCP guide and the MCP-specific files in the workspace become the correct analysis surface.
-5. Inspect the actual generated files and scripts in the workspace before editing or starting anything.
+4. If `mcp` is true, this page becomes the relevant MCP guide and the MCP-specific files in the project become the correct analysis surface.
+5. Inspect the actual generated files and scripts in the project before editing or starting anything.

package/dist/docs/metadata.md

@@ -1,6 +1,6 @@
 ---
 title: Metadata & SEO
-description: Define static and dynamic metadata in Caspian so titles, descriptions, and social cards inherit correctly from layouts to pages.
+description: Use this page when the task mentions metadata, SEO, page titles, descriptions, Open Graph, Twitter cards, or layout-to-page metadata inheritance in Caspian.
 related:
   title: Related docs
   description: Use the routing guide to place layout.py and index.py files correctly, then use the structure guide when deciding where metadata defaults belong.
@@ -185,7 +185,7 @@ Keep visual layout data and SEO metadata separate.
 - Put page-specific static metadata in `index.py`.
 - Put dynamic metadata inside `page()` after you have route params or fetched data.
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is deciding where to put SEO fields, apply these rules first.
 

package/dist/docs/project-structure.md

@@ -1,6 +1,6 @@
 ---
 title: Project Structure
-description: Understand the default Caspian project layout so AI agents place routes, reusable components, PulsePoint templates, RPC actions, validation helpers, auth code, MCP files, configuration, and database changes in the correct directories.
+description: Understand the default Caspian project layout so AI agents place routes, reusable components, `src/lib` helpers, auth code, MCP files, public assets, and database changes in the correct directories. Use when deciding where project files belong.
 related:
   title: Related docs
   description: Start with installation for new apps, then use the component guide for reusable UI, the auth guide for bootstrap and session wiring, the MCP guide for server layout, the routing guide to map URLs correctly, and the cache guide when route HTML should be reused safely.
@@ -12,11 +12,14 @@ related:
     - /docs/routing
     - /docs/cache
     - /docs/database
+    - /docs/file-uploads
     - /docs/index
 ---
 
 This page explains the default layout of a Caspian application, where Caspian core files live, and which paths AI agents should treat as project code versus framework internals.
 
+Treat it as a framework guide for Caspian projects. Use `caspian.config.json` and the actual repository tree to confirm which optional directories and files exist in the current project.
+
 ## Overview
 
 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.
@@ -40,6 +43,7 @@ Treat `caspian.config.json` as the single source of truth for optional feature e
 - `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.
@@ -54,6 +58,9 @@ my-app/
   prisma/
     schema.prisma
     seed.ts
+  settings/
+    bs-config.ts
+    build.ts
   public/
   src/
     app/
@@ -118,7 +125,7 @@ For component HTML files, follow the same one-parent rule as route HTML files: o
 
 Do not handwrite `pp-component="..."` or `type="text/pp"` in component source templates either. Write plain `<script>` inside the single root and let the render pipeline inject the runtime shape.
 
-This workspace's component tooling scans `src/` based on `caspian.config.json`, so `src/components/` is a conventionally clean location, not a hard-coded runtime requirement.
+The directories listed in `componentScanDirs` determine where component tooling scans. When that list includes `src/`, `src/components/` is a conventionally clean location, not a hard-coded runtime requirement.
 
 ### `src/lib/`
 
@@ -126,15 +133,17 @@ Use this folder for shared helpers, reusable validators, RPC-facing service wrap
 
 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/`.
 
-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/`.
+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/`.
+
+When a project 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/`.
 
-When MCP is enabled in the current workspace, this folder also contains the app-owned FastMCP server under `src/lib/mcp/`.
+When MCP is enabled for the project, this folder also contains the app-owned FastMCP server under `src/lib/mcp/`.
 
 ### Shared Database Helpers
 
 If your Python routes or RPC actions need reusable database access code, keep that helper layer under `src/lib/` and extend the existing `src/lib/prisma/` package.
 
-In this workspace, Prisma schema and seed files live under `prisma/`, while the Python-side adapter is application-owned code under `src/lib/prisma/`.
+In a Prisma-enabled Caspian project, schema and seed files typically live under `prisma/`, while the Python-side adapter lives in application-owned code under `src/lib/prisma/` when that layer exists.
 
 ### `src/lib/auth/`
 
@@ -151,7 +160,7 @@ When `caspian.config.json` has `mcp: true`:
 
 Keep MCP tool definitions here instead of placing them in route files, `main.py`, or framework internals.
 
-In the current workspace, `mcp: false`, so do not assume this folder exists until the feature is enabled and the update workflow has run.
+If `caspian.config.json` has `mcp: false`, do not assume this folder exists until the feature is enabled and the update workflow has run.
 
 ### `prisma/`
 
@@ -161,6 +170,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. Confirm the actual upload path in the project code and keep that directory aligned with any BrowserSync ignore rules.
+
+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`
@@ -184,7 +197,13 @@ The core feature configuration file for the application.
 
 AI agents should read this file before making almost any feature-level decision. Use it to confirm which capabilities are enabled, which code generation paths make sense, and which directories should be scanned for components or other project assets.
 
-In the current workspace, `caspian.config.json` shows `backendOnly: false`, `tailwindcss: true`, `mcp: false`, `prisma: true`, `typescript: false`, and `componentScanDirs: ["src"]`.
+Read the actual values in `caspian.config.json` instead of inferring feature state from this doc.
+
+### `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`
 
@@ -210,6 +229,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.
@@ -237,11 +258,11 @@ Notable internal files include:
 
 The packaged Caspian documentation location distributed with the current toolchain.
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is deciding where to make changes, use these rules first.
 
-- Read `caspian.config.json` almost immediately before making feature, tooling, or file-placement decisions. It tells you which Caspian features are enabled in the current workspace.
+- Read `caspian.config.json` almost immediately before making feature, tooling, or file-placement decisions. It tells you which Caspian features are enabled in the current project.
 - Treat `caspian.config.json` as the single source of truth for optional feature enablement. Use feature-specific docs and file paths only when the matching flag is enabled.
 - If an optional feature is disabled and the user wants it, ask first, then update `caspian.config.json` and use `npx casp update project` before assuming feature-managed files exist.
 - Treat `package.json` scripts as opt-in operations. Do not run `npm run dev` or `npm run build` unless the user explicitly asks, the task genuinely requires that exact script, or deployment prep needs `npm run build`.
@@ -249,6 +270,7 @@ If an AI agent is deciding where to make changes, use these rules first.
 - 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.
@@ -256,12 +278,13 @@ If an AI agent is deciding where to make changes, use these rules first.
 - 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.
 - Use `casp.cache_handler` when a route's first-render HTML should be reused safely across requests.
 - Use `casp.validate` at route and RPC boundaries, and move reusable validators into `src/lib/` when multiple routes share them.
-- Use `database.md` when the task involves Prisma schema changes, migrations, seed logic, or workspace-specific database helper conventions.
+- Use `database.md` when the task involves Prisma schema changes, migrations, seed logic, or project-specific database helper conventions.
 - Put authentication configuration in `src/lib/auth/auth_config.py`.
 - Put auth bootstrap, session middleware, and provider registration changes in `main.py`.
 - Put database models and seed logic in `prisma/`.

package/dist/docs/pulsepoint.md

@@ -1,6 +1,6 @@
 ---
 title: PulsePoint Runtime Guide
-description: Learn how AI agents should author PulsePoint against the shipped browser runtime in `public/js/pp-reactive-v2.js` and the Caspian render pipeline that injects runtime attributes automatically.
+description: Use this page when the task mentions PulsePoint, `pp.state`, `pp.effect`, `pp-ref`, `pp-for`, portals, SPA navigation, or `public/js/pp-reactive-v2.js`.
 related:
   title: Related docs
   description: Read the components, routing, data-fetching, and project-structure docs alongside the PulsePoint runtime contract.
@@ -14,19 +14,19 @@ related:
 
 ## Purpose
 
-This file documents the current PulsePoint contract for this workspace. Treat it as the AI-facing source of truth when generating or reviewing interactive Caspian UI.
+This file documents the PulsePoint contract for the shipped Caspian browser runtime. Treat it as the AI-facing source of truth when generating or reviewing interactive Caspian UI.
 
 If a task involves `pp.state`, `pp.effect`, `pp.layoutEffect`, `pp-ref`, `pp-spread`, `pp-for`, context, portals, SPA navigation, or component boundary behavior, read this page first and keep generated code aligned with the runtime implemented in this repo.
 
-Use `components.md` for authoring Python `@component` files and same-name HTML templates. Use this page for the browser-side PulsePoint contract, the authoring rules that feed it, and the React-style mental model used by the current runtime.
+Use `components.md` for authoring Python `@component` files and same-name HTML templates. Use this page for the browser-side PulsePoint contract, the authoring rules that feed it, and the React-style mental model used by the shipped runtime.
 
-PulsePoint is the default reactive frontend layer for Caspian. In this workspace it follows a React-like component pattern, but it is HTML-first rather than JSX-first.
+PulsePoint is the default reactive frontend layer for Caspian. In the current runtime it follows a React-like component pattern, but it is HTML-first rather than JSX-first.
 
 Do not assume React, Vue, Svelte, JSX, Alpine, HTMX, or older PulsePoint docs unless the task explicitly asks for a different frontend contract.
 
 ## Source Of Truth
 
-For the current workspace, follow this order when documenting or generating PulsePoint code:
+When documenting or generating PulsePoint code, follow this order:
 
 - `public/js/pp-reactive-v2.js` is the shipped browser runtime contract AI should follow.
 - `main.py` is the render-pipeline source of truth for how Caspian injects runtime attributes and rewrites scripts before the browser sees the HTML.
@@ -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

@@ -1,6 +1,6 @@
 ---
 title: Routing
-description: Understand Caspian's Next.js App Router-style file-based routing, including src/app conventions, index files, dynamic segments, route groups, nested layouts, and component-friendly route templates.
+description: Use this page when the task mentions `src/app`, `index.py`, `index.html`, `layout.py`, dynamic routes, route groups, nested layouts, or file-based routing in Caspian.
 related:
   title: Related docs
   description: Read the structure guide first, then use the components guide for reusable UI, the metadata guide for SEO fields, the cache guide for route-level HTML reuse, and the PulsePoint runtime guide for interactive route templates.
@@ -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).
@@ -304,7 +307,7 @@ src/
         index.py
 ```
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is choosing where to add or update route code, apply these rules first.
 

package/dist/docs/state.md

@@ -1,6 +1,6 @@
 ---
 title: State Management
-description: Manage transient Caspian server state with `casp.state_manager` and `StateManager`, using request-scoped ContextVar storage, shallow AttributeDict reads, listener callbacks, and session-backed JSON persistence.
+description: Use this page when the task mentions `StateManager`, `request.state.session`, request-scoped state, listeners, or session-backed JSON state in Caspian.
 related:
   title: Related docs
   description: Pair server request state with auth and RPC flows, then read the PulsePoint guide when the state really belongs in the browser instead of the request lifecycle.
@@ -64,7 +64,7 @@ Important implementation detail:
 
 In other words, cross-request persistence depends on the surrounding Caspian middleware keeping `request.state.session` available and in sync with session storage.
 
-In this workspace's current `main.py`, `SessionMiddleware` exposes `request.session`, but the middleware stack does not mirror that into `request.state.session`. Treat persistence as opt-in until you add that bridge explicitly.
+Inspect the current project's `main.py`: if `SessionMiddleware` exposes `request.session` but the middleware stack does not mirror that into `request.state.session`, treat persistence as opt-in until you add that bridge explicitly.
 
 ## Request Lifecycle
 
@@ -251,7 +251,7 @@ Poor candidates are:
 
 For browser-triggered writes and route actions, pair this page with [fetch-data.md](./fetch-data.md). For middleware and session-aware auth flows, pair it with [auth.md](./auth.md).
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is deciding how to use transient state in a Caspian app, apply these rules first.
 

package/dist/docs/validation.md

@@ -1,15 +1,15 @@
 ---
 title: Validation
-description: Validate and sanitize Caspian inputs with `casp.validate`, `Validate`, `Rule`, direct validators, rule-based checks, and file or date or ID validation before route or RPC logic persists data, with Validate as the default server-side validation layer.
+description: Use this page when the task mentions `Validate`, `Rule`, sanitization, form validation, credential checks, or guarding route and RPC inputs in Caspian.
 related:
-  title: Related docs
+    title: Related docs
     description: Use the auth guide for session and credential flows, the fetch-data guide when validation runs inside RPC actions, then use the structure guide to place reusable validators in the right layer.
-  links:
+    links:
         - /docs/auth
-    - /docs/fetch-data
-    - /docs/routing
-    - /docs/project-structure
-    - /docs/index
+        - /docs/fetch-data
+        - /docs/routing
+        - /docs/project-structure
+        - /docs/index
 ---
 
 This page explains the current installed Caspian validation API for direct field checks, rule-based validation, sanitization, and reusable input guards.
@@ -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.
@@ -276,7 +278,7 @@ def create_account(data: dict):
     return {"success": True}
 ```
 
-## AI Routing Notes
+## AI Retrieval Notes
 
 If an AI agent is deciding how to validate input in Caspian, apply these rules first.
 

package/package.json

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