cabloy 5.1.97 → 5.1.98

package/cabloy-docs/frontend/state-architecture-for-vue-developers.md

@@ -0,0 +1,218 @@
+# State Architecture for Vue Developers
+
+This guide is for Vue developers who already know common Vue state patterns and want the shortest docs-style explanation of how Zova/Cabloy organizes large-project state differently.
+
+It does **not** argue that Vue's usual tools are wrong.
+It explains why large projects often need a stronger architecture for state ownership, sharing boundaries, persistence, cache semantics, and SSR behavior.
+
+Use this page together with:
+
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison)
+- [IoC and Beans](/frontend/ioc-and-beans)
+- [Model Architecture](/frontend/model-architecture)
+- [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+
+## Why this page exists
+
+Many Vue teams do not struggle because they picked one obviously bad tool.
+
+They struggle because a large codebase gradually accumulates many valid state mechanisms at the same time:
+
+- component-local reactive state
+- composables
+- `provide/inject`
+- store layers
+- query cache
+- local persistence
+- SSR-specific state rules
+
+Each mechanism can solve a real local problem.
+
+The large-project difficulty usually appears later, when the team can no longer answer these questions cleanly:
+
+- who owns this state?
+- how far should it be shared?
+- which lifecycle rules apply to it?
+- who owns cache identity and invalidation?
+- is this only a value, or part of a larger resource boundary?
+
+That is the architectural problem this page addresses.
+
+## The shortest accurate summary
+
+If you only remember one paragraph, remember this one:
+
+> Large Vue projects rarely become hard because they need one more state tool. They usually become hard because ownership, sharing boundaries, persistence, cache semantics, and SSR behavior stop composing into one coherent system.
+
+Zova's answer is to push those concerns back under a more explicit architecture:
+
+- **Controller / Bean** makes ownership more explicit
+- **IoC scopes** make sharing boundaries more explicit
+- **Model** unifies several state families under one model-owned boundary
+- **Resource Owner** keeps query, schema, permissions, forms, and invalidation closer to one resource-level owner
+
+## Start with boundary questions, not only tool questions
+
+In many Vue projects, state discussions begin with questions like these:
+
+- should this go into a composable?
+- should this move to a store?
+- should we add a query layer?
+- should we persist this in localStorage?
+
+Those are reasonable questions.
+
+But in a large system, the more important questions usually come first:
+
+1. **Ownership** — which framework-managed object should own this state?
+2. **Sharing boundary** — is it local, parent/child shared, app-level, or system-level?
+3. **State family** — is it query-style remote state, in-memory state, local persistence, cookie-backed state, or async persisted state?
+4. **Lifecycle** — what should survive page disposal, refresh, route transitions, or SSR request boundaries?
+5. **Resource boundary** — does this state belong to a larger resource owner that also owns schema, permissions, forms, and invalidation?
+
+Zova tries to answer those questions structurally instead of leaving them spread across unrelated mechanisms.
+
+## 1. Ownership: make the state host explicit
+
+A common Vue mental model starts with local reactive primitives and composition logic inside `setup()`.
+
+Zova keeps Vue's reactive foundation, but changes the visible business-facing host. The most important state often lives on framework-managed Controller or Bean instances instead of starting life as scattered local variables.
+
+That changes the reading question from:
+
+- which composable or local variable holds this?
+
+into:
+
+- which Controller, Bean, or Model owns this?
+
+That is a better scaling question because ownership drift is often the first step toward cache drift, persistence drift, and SSR drift.
+
+For the broader authoring-model shift, read [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers) and [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison).
+
+## 2. Sharing: treat scope as a first-class architectural decision
+
+Large Vue codebases often express different sharing ranges through different mechanisms:
+
+- component-local state
+- parent-child props or `provide/inject`
+- app-level stores
+- long-lived globals or imported singletons
+
+Zova tries to keep more of those cases inside one bean-and-container architecture.
+
+A compact comparison is:
+
+| Sharing range      | Common Vue pattern                                      | Zova framing                                        |
+| ------------------ | ------------------------------------------------------- | --------------------------------------------------- |
+| component-internal | local state or component-local composables              | `ctx`-scoped bean ownership                         |
+| between-components | props/emits, parent-owned composables, `provide/inject` | hierarchical injection such as `host` or `skipSelf` |
+| app-global         | store or app-level provided state                       | `app`-scoped bean ownership                         |
+| system-level       | module singleton or long-lived imported state           | `sys`-scoped bean ownership                         |
+
+The key idea is simple:
+
+> Do not start by switching mechanisms. Start by choosing the sharing boundary.
+
+This distinction becomes especially important in SSR, where app/request state and system-level state should not be mixed casually.
+
+Read together with [IoC and Beans](/frontend/ioc-and-beans) and [System Startup Guide](/frontend/system-startup-guide).
+
+## 3. Model: unify multiple state families under one model boundary
+
+In many stacks, remote cache, in-memory shared state, local persistence, cookie state, and async persistent state are handled by separate tools or utilities.
+
+Zova Model tries to organize those families under one broader model-owned runtime.
+
+The current model layer exposes five main state families:
+
+- `data`
+- `mem`
+- `local`
+- `cookie`
+- `db`
+
+This means Model is not only a request wrapper and not only another store.
+
+Its architectural role is to give several important state categories a shared home for concerns such as:
+
+- cache identity
+- invalidation
+- restore behavior
+- persistence strategy
+- SSR-aware hydration behavior
+
+Read together with [Model Architecture](/frontend/model-architecture), [Model State Guide](/frontend/model-state-guide), and [Server Data](/frontend/server-data).
+
+## 4. Resource Owner: keep resource semantics together
+
+A large frontend resource usually needs more than a query call.
+
+The frontend often also needs:
+
+- schema
+- permissions
+- forms
+- list and item queries
+- create/update/delete mutations
+- invalidation rules
+
+If those concerns are split across pages, form helpers, store logic, and query callbacks, the resource boundary becomes hard to explain.
+
+Zova's resource-owner direction tries to keep more of that semantic bundle under one stable owner.
+
+A useful shorthand is:
+
+> the page consumes resource semantics, while the model owns query and resource semantics.
+
+That is why the Resource Owner pattern matters in large applications: it improves not only reuse, but also boundary stability.
+
+Read together with [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern) and [Using ModelResource in Your Module](/frontend/model-resource-usage-guide).
+
+## One comparison table
+
+| Dimension          | Common large-Vue drift                                            | Zova architectural answer                                       |
+| ------------------ | ----------------------------------------------------------------- | --------------------------------------------------------------- |
+| State host         | state starts locally, then moves outward case by case             | assign ownership first to Controller / Bean / Model             |
+| Sharing            | sharing range often changes the mechanism                         | sharing is framed through IoC scopes                            |
+| Persistence        | local, cookie, and async persistence drift into utilities         | persistence lives inside model-state families                   |
+| Cache identity     | keys and refresh rules drift across pages and callbacks           | model identity and model policy own more of the cache semantics |
+| SSR                | request-level and long-lived state can blur together              | `app` and `sys` make the distinction structural                 |
+| Resource semantics | schema, forms, permissions, and invalidation spread across layers | Resource Owner pulls them back under one owner                  |
+
+## When this architecture matters most
+
+This architecture is most valuable when the frontend is:
+
+- long-lived
+- maintained by multiple developers
+- SSR-aware
+- cache-heavy
+- persistence-heavy
+- resource-heavy
+
+For small or short-lived projects, a lighter scattered approach may still be good enough.
+
+The point is not that every Vue project must adopt the same architecture.
+The point is that as complexity rises, boundary control becomes more important than adding one more tool.
+
+## Recommended reading path
+
+If this page matches your question, continue in this order:
+
+1. [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+2. [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison)
+3. [IoC and Beans](/frontend/ioc-and-beans)
+4. [Model Architecture](/frontend/model-architecture)
+5. [Model State Guide](/frontend/model-state-guide)
+6. [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+7. [System Startup Guide](/frontend/system-startup-guide)
+
+## Final takeaway
+
+The most important practical idea is simple:
+
+> Large Vue projects usually do not need more state tools first. They need a state architecture that can keep ownership, scope, persistence, cache semantics, SSR behavior, and resource boundaries coherent as the system grows.
+
+That is the main reason to read Zova's frontend architecture through Controller / Bean ownership, IoC scopes, Model, and Resource Owner, instead of mapping every state problem back to one more isolated Vue mechanism.

package/cabloy-docs/frontend/system-startup-guide.md

@@ -167,6 +167,8 @@ The legacy system-start docs used route registration as the clearest example bou
 
 That distinction is especially important in SSR-capable systems, where app lifecycles can repeat while system-level route and config wiring should not.
 
+If your main question is how this `app` versus `sys` lifecycle split participates in the broader state architecture of a large Vue application, read [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers) together with [IoC and Beans](/frontend/ioc-and-beans).
+
 A practical reading sequence is:
 
 1. [Environment and Config Guide](/frontend/environment-config-guide)

package/cabloy-docs/frontend/zova-vs-vue3-comparison.md

@@ -12,6 +12,7 @@ The goal is to explain two things clearly:
 Use this page together with:
 
 - [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [State Architecture for Vue Developers](/frontend/state-architecture-for-vue-developers)
 - [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
 - [Zova Source Reading Map](/frontend/zova-source-reading-map)
 
@@ -40,16 +41,16 @@ The big difference is the **business-facing programming model**.
 
 ## Side-by-side comparison table
 
-| Dimension | Zova | Vue 3 default mental model |
-| --- | --- | --- |
-| Reactive host | controller or bean instance | local `ref` / `reactive` values inside `setup()` |
-| Derived state | `$computed()` often assigned to instance fields | `computed()` usually assigned to local variables |
-| Main wiring surface | `__init__` and bean lifecycle | `setup()` and composition hooks |
-| Route state access | page-controller surface such as `$route`, `$params`, `$query` | composables such as `useRoute()` |
-| Sharing model | IoC containers and bean scopes unify more sharing patterns | composables, props/emits, `provide/inject`, and store layers often coexist |
-| Render organization | controller-oriented; render can stay in controller or move to render beans | component-oriented; template/render/setup stay the obvious center |
-| Growth path | split into controller, render, style, service, model, or other beans | split into composables, child components, and store or helper layers |
-| Architectural emphasis | explicit object roles, scope ownership, and runtime-managed surfaces | flexible local composition with more developer-managed assembly |
+| Dimension              | Zova                                                                       | Vue 3 default mental model                                                 |
+| ---------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Reactive host          | controller or bean instance                                                | local `ref` / `reactive` values inside `setup()`                           |
+| Derived state          | `$computed()` often assigned to instance fields                            | `computed()` usually assigned to local variables                           |
+| Main wiring surface    | `__init__` and bean lifecycle                                              | `setup()` and composition hooks                                            |
+| Route state access     | page-controller surface such as `$route`, `$params`, `$query`              | composables such as `useRoute()`                                           |
+| Sharing model          | IoC containers and bean scopes unify more sharing patterns                 | composables, props/emits, `provide/inject`, and store layers often coexist |
+| Render organization    | controller-oriented; render can stay in controller or move to render beans | component-oriented; template/render/setup stay the obvious center          |
+| Growth path            | split into controller, render, style, service, model, or other beans       | split into composables, child components, and store or helper layers       |
+| Architectural emphasis | explicit object roles, scope ownership, and runtime-managed surfaces       | flexible local composition with more developer-managed assembly            |
 
 ## 1. Reactive host
 

package/cabloy-docs/fullstack/image-workflow.md

@@ -0,0 +1,403 @@
+# Fullstack Image Workflow
+
+This page explains the fullstack image workflow in Cabloy Basic with a practical, contract-chain path.
+
+In this page, **resolved relation field** means the DTO-side field such as `image` or `sceneImages` that carries `DtoImageView` data for frontend preview and display.
+
+It fills the gap between the layer-specific image guides:
+
+- [Backend Image Guide](/backend/image-guide)
+- [Frontend Image Guide](/frontend/image-guide)
+
+Use this page when the real question is not only backend image policy and not only frontend image rendering, but the bridge between the two.
+
+Use this page together with:
+
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- [Backend Image Guide](/backend/image-guide)
+- [Frontend Image Guide](/frontend/image-guide)
+- [Upload Guide](/backend/upload-guide)
+- [Serialization Guide](/backend/serialization-guide)
+- [Form Guide](/frontend/form-guide)
+- [Table Guide](/frontend/table-guide)
+
+> [!TIP]
+> **Image workflow docs path**
+>
+> - **[Fullstack Image Workflow](/fullstack/image-workflow)** — learn the cross-stack chain from backend image field contract and scene policy to frontend `basic-image` consumption
+> - **[Backend Image Guide](/backend/image-guide)** — learn image scenes, providers, serializer transforms, delivery policy, and backend lifecycle behavior
+> - **[Frontend Image Guide](/frontend/image-guide)** — learn `basic-image:formFieldImage`, `basic-image:image`, relation previews, and client-side image-field behavior
+>
+> Use this page when the question is about how one image field travels across the full stack rather than only one layer.
+
+## Why this page exists
+
+The repository now has a backend image guide and a frontend image guide.
+
+What contributors and AI workflows often still need is one continuous answer to this narrower question:
+
+> how does one image field travel from backend entity and DTO metadata to frontend form and table rendering?
+
+This page answers that question by treating image handling as one contract chain rather than as disconnected snippets.
+
+## The shortest correct mental model
+
+If you only remember one idea, remember this one:
+
+> backend code owns the image field contract, image scene policy, and DTO-side image view resolution, while frontend `basic-image` resources consume that resolved contract for upload, preview, and display.
+
+That means an image field usually has two connected surfaces:
+
+- a stored identity field such as `imageId` or `sceneImageIds`
+- a resolved relation field such as `image` or `sceneImages`
+
+The fullstack workflow works best when both surfaces are authored deliberately and kept aligned.
+
+## The fullstack chain in one view
+
+A practical image workflow usually looks like this:
+
+1. the backend entity stores image identity data such as `imageId` or `sceneImageIds`
+2. backend field metadata points to the frontend image resources with `ZovaRender.field(...)` and `ZovaRender.cell(...)`
+3. the backend image scene defines upload policy such as MIME type, size, and multiple-image rules
+4. the backend DTO resolves image IDs into `DtoImageView` or `DtoImageView[]` through `a-image:resolveView` or `a-image:resolveViews`
+5. the shared contract exposes both the stored ID field and the resolved relation field to frontend consumers
+6. frontend `basic-image:formFieldImage` binds the stored ID field while reusing the resolved relation field for preview cards and dialogs
+7. frontend `basic-image:image` uses the same resolved relation field to render thumbnails in list pages
+
+This is not only a forward chain and not only a reverse chain.
+
+Instead, it is one concrete business thread where backend contract truth, shared metadata, and frontend resource consumption cooperate.
+
+For the broader decision model, read [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
+## Specimen A: single image on Student
+
+The Student resource is the best single-image specimen because it shows the complete chain with the smallest number of moving parts.
+
+### Backend entity field
+
+The Student entity stores one image identity field and points to the built-in image resources:
+
+```typescript
+@Api.field(
+  v.title($locale('StudentImage')),
+  v.optional(),
+  ZovaRender.field('basic-image:formFieldImage', {
+    imageScene: 'training-student:studentImage',
+    relationName: 'image',
+    accept: ['image/png', 'image/jpeg', 'image/webp'],
+    maxSize: 2 * 1024 * 1024,
+    enableCrop: true,
+    cropAspectRatio: 1,
+    resize: {
+      width: 512,
+      height: 512,
+      fit: 'cover',
+      format: 'jpeg',
+      quality: 90,
+    },
+  }),
+  ZovaRender.cell('basic-image:image', { relationName: 'image' }),
+  v.tableIdentity(),
+)
+imageId?: TableIdentity;
+```
+
+This already defines two important truths:
+
+- the stored field is `imageId`
+- the frontend resource identities are `basic-image:formFieldImage` and `basic-image:image`
+
+### Backend image scene
+
+The Student image scene defines the upload policy:
+
+```typescript
+@ImageScene({
+  upload: {
+    maxSize: 2 * 1024 * 1024,
+    mimeTypes: ['image/png', 'image/jpeg', 'image/webp'],
+  },
+})
+export class ImageSceneStudentImage extends BeanBase {}
+```
+
+This means the backend owns the true upload policy even when the frontend also performs convenience validation.
+
+### DTO-side image resolution
+
+The Student DTO resolves the stored ID into a resolved relation field:
+
+```typescript
+@Api.field(
+  ZovaRender.visible(false),
+  v.optional(),
+  v.serializerTransform('a-image:resolveView', {
+    fieldName: 'imageId',
+    imageScene: 'training-student:studentImage',
+  }),
+  v.object(DtoImageView),
+)
+image?: DtoImageView;
+```
+
+This is the bridge that turns:
+
+- stored value: `imageId`
+- resolved preview data: `image?: DtoImageView`
+
+The same list-page branch is also visible in `DtoStudentSelectResItem`, where the row DTO resolves `image` for table usage.
+
+### Frontend consumption
+
+On the frontend side, the built-in resources consume that contract shape:
+
+- `basic-image:formFieldImage` binds the ID field and reuses the `image` resolved relation field for preview cards
+- `basic-image:image` uses the same resolved relation field to render thumbnails in tables
+
+This is the cleanest single-image chain in the repo.
+
+## Specimen B: multiple images on Record
+
+The Record resource shows the plural branch.
+
+### Backend entity field
+
+The Record entity stores an array of image IDs and points to the same built-in resources:
+
+```typescript
+@Api.field(
+  v.title($locale('ScenePhotos')),
+  v.optional(),
+  ZovaRender.field('basic-image:formFieldImage', {
+    imageScene: 'training-record:sceneImage',
+    multiple: true,
+    maxCount: 9,
+    relationName: 'sceneImages',
+    accept: ['image/png', 'image/jpeg', 'image/webp'],
+    maxSize: 2 * 1024 * 1024,
+    enableCrop: false,
+    resize: {
+      width: 1280,
+      height: 1280,
+      fit: 'contain',
+      format: 'jpeg',
+      quality: 90,
+    },
+  }),
+  ZovaRender.cell('basic-image:image', { relationName: 'sceneImages' }),
+  v.array(v.tableIdentity()),
+)
+sceneImageIds?: TableIdentity[];
+```
+
+### Backend image scene
+
+The matching scene enables multi-image upload policy:
+
+```typescript
+@ImageScene({
+  upload: {
+    maxSize: 2 * 1024 * 1024,
+    mimeTypes: ['image/png', 'image/jpeg', 'image/webp'],
+    multiple: true,
+  },
+})
+export class ImageSceneSceneImage extends BeanBase {}
+```
+
+### DTO-side image resolution
+
+The DTO resolves many IDs into many preview objects:
+
+```typescript
+@Api.field(
+  ZovaRender.visible(false),
+  v.optional(),
+  v.serializerTransform('a-image:resolveViews', {
+    fieldName: 'sceneImageIds',
+    imageScene: 'training-record:sceneImage',
+  }),
+  v.array(DtoImageView),
+)
+sceneImages?: DtoImageView[];
+```
+
+The same pattern also appears in `DtoRecordSelectResItem`, which makes the relation data available for list-page thumbnails.
+
+### Why this branch matters
+
+This branch proves that the same workflow scales from:
+
+- one ID -> one relation object
+- many IDs -> many relation objects
+
+without changing the overall contract-chain model.
+
+## Backend authoring responsibilities
+
+The backend owns the contract truth.
+
+For image workflows, that usually means:
+
+- the entity field defines the stored data shape
+- `ZovaRender.field(...)` chooses the form-side frontend resource identity
+- `ZovaRender.cell(...)` chooses the table-side frontend resource identity
+- the image scene bean defines upload policy
+- the DTO serializer transform resolves stored IDs into preview-ready image view objects
+
+A practical rule is:
+
+- when the business meaning of the image field changes, start by changing backend truth first
+
+For the backend-authoring details, read [Backend Image Guide](/backend/image-guide).
+
+## What crosses the contract boundary
+
+The most important thing that crosses the fullstack boundary is not only the raw image ID.
+
+What really crosses the boundary is the pairing of:
+
+- stored identity field
+- resolved preview field
+
+In the single-image branch, that pair is usually:
+
+- `imageId`
+- `image?: DtoImageView`
+
+In the multi-image branch, that pair is usually:
+
+- `sceneImageIds`
+- `sceneImages?: DtoImageView[]`
+
+This is why the DTO serializer step matters so much.
+
+It turns backend-owned identity data into frontend-friendly preview data without changing the persistence model.
+
+## Frontend consumption responsibilities
+
+The frontend does not redefine the image field contract.
+
+Instead, it consumes the contract through the built-in image resources.
+
+### `basic-image:formFieldImage`
+
+The form-side resource is responsible for:
+
+- selecting files
+- performing frontend validation
+- optionally cropping and resizing in the browser
+- requesting an upload token
+- uploading multipart data
+- binding the stored image ID field
+- synchronizing the resolved relation field for immediate UI refresh
+
+### `basic-image:image`
+
+The table-side resource is responsible for:
+
+- resolving relation-backed preview data first
+- falling back to URL-style values when needed
+- rendering thumbnails
+- opening the shared preview dialog
+
+### Why `relationName` matters
+
+The built-in frontend image resources work best when the resolved relation field is named predictably.
+
+Common pairings are:
+
+- `imageId` -> `image`
+- `sceneImageIds` -> `sceneImages`
+
+When your field names are nonstandard, set `relationName` explicitly so backend DTO resolution and frontend preview lookup stay aligned.
+
+For the frontend runtime details, read [Frontend Image Guide](/frontend/image-guide).
+
+## Single-image vs multi-image differences
+
+The contract chain stays the same, but three details change.
+
+### 1. Stored value shape
+
+- single image: scalar ID such as `imageId`
+- multiple images: ID array such as `sceneImageIds`
+
+### 2. DTO serializer transform
+
+- single image: `a-image:resolveView`
+- multiple images: `a-image:resolveViews`
+
+### 3. Relation preview shape
+
+- single image: one `DtoImageView`
+- multiple images: `DtoImageView[]`
+
+That is the main branching point the fullstack doc should make explicit.
+
+## Where this page sits in the contract loop
+
+This workflow is easiest to understand when you keep the contract-loop vocabulary precise.
+
+- backend field metadata and DTO/image-scene changes belong to backend contract truth
+- image DTO resolution is part of the backend-authored handoff
+- frontend `basic-image` resources are consumers of that truth
+- frontend-specific render behavior is not a reason to duplicate the backend contract
+
+That is why this page sits between:
+
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+
+It is a bridge page for one concrete business thread rather than a general direction guide.
+
+## Verification workflow
+
+When writing or changing image workflow docs, verify in this order.
+
+1. confirm the entity field still points to:
+   - `basic-image:formFieldImage`
+   - `basic-image:image`
+2. confirm the image scene still matches the specimen field
+3. confirm the DTO still uses:
+   - `a-image:resolveView` for single-image fields
+   - `a-image:resolveViews` for multi-image fields
+4. confirm the list-row DTOs still expose the same resolved relation fields for table usage
+5. confirm the frontend image resources still consume the same relation-name pattern
+6. confirm the page stays bridge-focused rather than duplicating the backend or frontend guides
+7. run the docs build and confirm the page appears under `Fullstack / Architecture & Integration`
+
+## Read together with
+
+Use the surrounding docs based on which layer now needs deeper attention.
+
+### Backend policy and authoring details
+
+- [Backend Image Guide](/backend/image-guide)
+- [Upload Guide](/backend/upload-guide)
+- [Serialization Guide](/backend/serialization-guide)
+- [Controller Guide](/backend/controller-guide)
+
+### Frontend runtime and rendering details
+
+- [Frontend Image Guide](/frontend/image-guide)
+- [Form Guide](/frontend/form-guide)
+- [Table Guide](/frontend/table-guide)
+- [TableCell Authoring Cookbook](/frontend/table-cell-cookbook)
+
+### Broader fullstack bridge and contract-loop decisions
+
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+
+A good final question is:
+
+- am I debugging one layer, or am I debugging the handoff between layers?
+
+If the answer is the handoff, this page is the right place to start.

package/cabloy-docs/fullstack/introduction.md

@@ -46,6 +46,7 @@ Use this path when the task is about how backend and frontend stay aligned insid
 - [Vona + Zova Integration](/fullstack/vona-zova-integration)
 - [Contract Loop Playbook](/fullstack/contract-loop-playbook)
 - [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
+- [Fullstack Image Workflow](/fullstack/image-workflow)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 - [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.97",
+  "version": "5.1.98",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [