howone 0.1.31 → 0.1.32

package/templates/vite/.howone/skills/howone/02-entity-schema/02-schema-operations.md

@@ -1,108 +1,108 @@
 # Schema Operations
 
-Use this reference when applying backend entity schema changes through HowOne runtime tools or
-`client.schema.*`. It answers: **how do I safely change the schema and keep app code in sync?**
-
-For schema design decisions, read `01-schema-design.md` first.
+Use this reference when calling `backend-api-design` to change HowOne backend entity contracts.
+This is a backend design reference, not an app SDK guide.
 
 ## Source Of Truth
 
 ```text
-agent proposal                 = draft
-backend preview/apply result   = validated contract
-synced .howone/database files  = local copy of backend version
-src/lib/sdk.ts                 = generated app binding from synced manifest
-frontend code                  = consumer of generated bindings
+current backend schema          = inspect result
+backend-api-design apply result = validated contract version
+sync_schema_artifacts output    = local .howone/database manifest
+src/lib/sdk.ts                  = later SDK binding, handled by SDK track
 ```
 
-Do not hand-write `.howone/database/*`. Sync artifacts from a concrete backend version.
-
-## Preferred Patch Flow
-
-Use patch flow for most feature-level changes:
+Do not handwrite `.howone/database/*`. Sync from a backend version after apply.
 
-1. Inspect current `schema.getState()` and current entity definitions.
-2. Design a full patch containing all related operations.
-3. Preview the patch.
-4. Review risk, diff, and current version.
-5. Apply the exact same patch with `expectedVersionId`.
-6. Sync schema artifacts from `next.versionId`.
-7. Read `.howone/database/manifest.json`.
-8. Regenerate/update `src/lib/sdk.ts` bindings.
-9. Update frontend calls according to `access`.
-10. Run typecheck/build/tests.
+## Normal Flow
 
-Do not preview one patch and apply a different operation set.
+For generated app work, avoid fake dry-runs. Build one correct patch and apply it.
 
-## SDK Schema Client
+```text
+1. backend-api-design { type: "get_current_schema" }
+2. Design one complete patch.operations[] for the feature.
+3. backend-api-design { type: "apply_schema_patch", expectedVersionId, reason, patch }
+4. sync_schema_artifacts with the returned versionId/currentVersionId.
+5. Read .howone/database/manifest.json.
+6. Stop backend design; SDK/UI work is a separate track.
+```
 
-```ts
-const state = await client.schema.getState()
-const definitions = await client.schema.listDefinitions()
-const todo = await client.schema.getDefinition('Todo')
+There is no schema dry-run step. If a change is destructive, narrowing, or broadens public access,
+stop and align with the user before applying the final patch.
 
-const preview = await client.schema.previewPatch(patch, {
-  expectedVersionId: state.currentVersionId,
-  reason: 'Add priority field to Todo',
-})
+## Patch Shape
 
-if (preview.risk?.level === 'dangerous') {
-  // stop and ask for confirmation
+```json
+{
+  "type": "apply_schema_patch",
+  "expectedVersionId": "current-version-id-from-inspect",
+  "reason": "Add personal todo storage",
+  "patch": {
+    "operations": [
+      {
+        "type": "create_entity",
+        "entityName": "Todo",
+        "payload": {
+          "description": "Personal task item.",
+          "visibility": "private",
+          "type": "object",
+          "properties": {
+            "text": { "type": "string", "description": "Task text." },
+            "completed": { "type": "boolean", "default": false }
+          },
+          "required": ["text"],
+          "access": {
+            "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
+            "public": { "read": "none", "create": "none", "update": "none" }
+          },
+          "indexes": [
+            {
+              "name": "completed_updated",
+              "scope": "owner",
+              "fields": ["completed", "updatedDate"],
+              "order": { "updatedDate": "desc" }
+            }
+          ]
+        }
+      }
+    ]
+  }
 }
-
-const applied = await client.schema.applyPatch(patch, {
-  expectedVersionId: state.currentVersionId,
-  reason: 'Add priority field to Todo',
-})
 ```
 
-Available schema methods:
+Critical shape rules:
 
-| Method | Use |
-|---|---|
-| `listDefinitions()` | Get current entity definitions. |
-| `getDefinition(entityName)` | Inspect one entity. |
-| `upsertDefinitions(definition | definition[])` | Direct definition upsert; prefer patch for agent changes. |
-| `operate(operation)` | Single operation endpoint. |
-| `previewPatch(patch, options)` | Risk/diff preview without applying. |
-| `applyPatch(patch, options)` | Apply versioned patch. |
-| `getState()` | Current schema version pointer. |
-| `listVersions()` | Version history. |
-| `getVersion(versionId)` | Inspect version manifest. |
-| `restore(versionId, reason?)` | Restore definitions by creating a new restore version. |
+- `create_entity.payload.properties` is the field map. Do not use `payload.definition`.
+- `create_entity.payload.required` is the required field array. Do not use `requiredFields`.
+- `update_entity.payload` is the patch itself. Do not wrap it in `payload.patch`.
+- Entity and field names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`.
+- Backend-generated version IDs never go inside operation payloads.
 
 ## Operation Types
 
-```ts
-type EntitySchemaOperationType =
-  | 'list_entities'
-  | 'get_entity'
-  | 'create_entity'
-  | 'update_entity'
-  | 'delete_entity'
-  | 'add_field'
-  | 'update_field'
-  | 'delete_field'
-  | 'set_field_required'
-  | 'unset_field_required'
-```
-
-Operation shape:
+Patch operations accepted by `backend-api-design`:
 
-```ts
-type EntitySchemaOperation = {
-  type: EntitySchemaOperationType
-  entityName?: string
-  payload?: Record<string, unknown>
-}
+```text
+create_entity
+update_entity
+delete_entity
+add_field
+update_field
+delete_field
+set_field_required
+unset_field_required
 ```
 
-Patch shape:
+Inspect/version operations are top-level tool calls, not patch operations:
 
-```ts
-type EntitySchemaPatch = {
-  operations: EntitySchemaOperation[]
-}
+```text
+get_current_schema
+list_entities
+get_entity
+list_schema_versions
+get_schema_version
+restore_schema_version
+diff_schema_versions
 ```
 
 ## Operation Payloads
@@ -114,20 +114,28 @@ Use when the entity does not exist.
 ```json
 {
   "type": "create_entity",
-  "entityName": "Todo",
+  "entityName": "Article",
   "payload": {
-    "definition": {
-      "name": "Todo",
-      "type": "object",
-      "visibility": "private",
-      "properties": {
-        "text": { "type": "string" },
-        "completed": { "type": "boolean", "default": false }
-      },
-      "required": ["text"],
-      "access": {
-        "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
-        "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
+    "description": "Published article.",
+    "visibility": "public",
+    "type": "object",
+    "properties": {
+      "title": { "type": "string" },
+      "slug": { "type": "string" },
+      "status": { "type": "string", "enum": ["draft", "published"], "default": "draft" },
+      "publishedAt": { "type": ["date", "null"], "default": null }
+    },
+    "required": ["title", "slug"],
+    "access": {
+      "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
+      "public": {
+        "read": "list",
+        "create": "none",
+        "update": "none",
+        "allowedFilters": ["slug", "status"],
+        "allowedSorts": ["publishedAt", "updatedDate"],
+        "defaultLimit": 20,
+        "maxLimit": 100
       }
     }
   }
@@ -136,53 +144,44 @@ Use when the entity does not exist.
 
 Rules:
 
-- `payload.definition.properties` is required.
-- `required` must reference existing fields.
-- Include explicit `access`, even if `visibility` seems obvious.
+- Include explicit `access.authenticated` and `access.public`.
+- Required fields must exist in `properties`.
+- Required fields with `default` or `autoGenerate` may be omitted by create callers.
+- Do not include system fields such as `id`, `created_date`, `updated_date`, or owner IDs.
 
 ### update_entity
 
-Use for metadata and contract sections, not individual field changes.
+Use for entity metadata and contract sections.
 
 ```json
 {
   "type": "update_entity",
   "entityName": "Article",
   "payload": {
-    "patch": {
-      "access": {
-        "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
-        "public": {
-          "read": "list",
-          "create": "none",
-          "update": "none",
-          "delete": "none",
-          "allowedFilters": ["status", "slug"],
-          "allowedSorts": ["publishedAt"],
-          "defaultLimit": 20,
-          "maxLimit": 100
-        }
-      },
-      "performance": {
-        "defaultLimit": 20,
-        "maxLimit": 100,
-        "allowedSorts": ["publishedAt", "updatedDate"]
+    "description": "Published article with scoped public lookup.",
+    "access": {
+      "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
+      "public": {
+        "read": "scoped",
+        "create": "none",
+        "update": "none",
+        "requiredScopes": ["slug"],
+        "allowedFilters": ["slug", "status"],
+        "allowedSorts": ["publishedAt"],
+        "defaultLimit": 1,
+        "maxLimit": 10
       }
+    },
+    "presentation": {
+      "titleField": "title",
+      "listFields": ["title", "status", "publishedAt"]
     }
   }
 }
 ```
 
-Use this for:
-
-- `description`
-- `visibility`
-- `access`
-- `indexes`
-- `relations`
-- `presentation`
-- `lifecycle`
-- `performance`
+Allowed sections include `description`, `visibility`, `isActive`, `access`, `indexes`,
+`relations`, `presentation`, `lifecycle`, and `performance`.
 
 ### add_field
 
@@ -204,9 +203,9 @@ Use this for:
 
 Rules:
 
-- If adding a required field to an existing entity, prefer a default.
-- If no default exists and records already exist, treat as risky and ask for migration policy.
-- Add indexes only when new query paths need them.
+- Add optional fields or fields with defaults for existing entities.
+- If an added field must be required and has no default, align with the user first.
+- Add indexes only for actual query paths.
 
 ### update_field
 
@@ -223,13 +222,10 @@ Rules:
 }
 ```
 
-Risk levels:
+Usually safe: adding enum values, adding descriptions, adding validation hints.
 
-- Adding enum values: usually safe.
-- Removing enum values: risky if existing records use them.
-- Changing type: high risk.
-- Making nullable field required: high risk.
-- Removing default: risky for create flows.
+Risky: removing enum values, changing type, removing defaults, narrowing nullability, or making
+existing data invalid.
 
 ### delete_field
 
@@ -244,11 +240,7 @@ Risk levels:
 }
 ```
 
-Rules:
-
-- Default `removeFromData` to `false`.
-- Only use `removeFromData: true` after explicit confirmation.
-- Removing from schema does not necessarily remove historical data.
+Default `removeFromData` to `false`. `true` requires explicit user confirmation.
 
 ### set_field_required / unset_field_required
 
@@ -260,11 +252,8 @@ Rules:
 }
 ```
 
-Rules:
-
-- Required fields must exist in `properties`.
-- Setting required on an existing field is risky unless a default exists or old records are acceptable.
-- Unsetting required is generally safe but may change frontend validation expectations.
+Setting required on existing data is risky unless a default exists or old records are known valid.
+Unsetting required is usually safe.
 
 ### delete_entity
 
@@ -273,7 +262,7 @@ Rules:
   "type": "delete_entity",
   "entityName": "Todo",
   "payload": {
-    "hard": false,
+    "mode": "soft",
     "deleteData": false
   }
 }
@@ -281,52 +270,35 @@ Rules:
 
 Rules:
 
-- Default to soft delete.
-- Hard delete requires explicit user request.
-- `deleteData: true` requires explicit confirmation because it destroys records.
+- Default to `mode: "soft"`.
+- `mode: "hard"` requires explicit user request.
+- `deleteData: true` requires explicit confirmation.
 
 ## Risk Checklist
 
-Stop and ask before applying when:
-
-- deleting an entity;
-- deleting a field used by UI or workflow output;
-- removing historical data;
-- changing field type;
-- making a field required without default;
-- broadening public access;
-- enabling public write;
-- reducing public guardrails such as removing required scopes or raising max limits;
-- changing owner/public scope semantics.
-
-Usually safe:
-
-- adding optional field;
-- adding field with default;
-- adding enum value;
-- adding index for existing query path;
-- adding presentation metadata;
-- adding stricter public filter/sort limits.
+Stop before apply and align with the user when the patch:
 
-## Version Semantics
+- deletes entity definitions;
+- deletes fields used by app UI or AI outputs;
+- removes data from historical records;
+- changes field types;
+- makes fields required without defaults;
+- broadens public read;
+- enables public create/update;
+- removes public scopes/filter/sort limits.
 
-Schema versions manage definitions, not business records.
+Usually safe to apply directly:
 
-Restore behavior:
+- create a new entity with explicit private/public access;
+- add optional fields;
+- add fields with defaults;
+- add enum values;
+- add indexes for known query paths;
+- add presentation/performance metadata.
 
-```text
-restore(versionId)
-  -> creates a new current schema version from old manifest
-  -> future create/update uses restored definitions
-  -> old entitydatashares records are not rolled back
-```
-
-Data records may still carry old fields after schema changes. Do not assume restore deletes or
-rewrites data.
+## Sync Handoff
 
-## Manifest Sync Handoff
-
-After apply, the result should include a version hint:
+After apply, use the returned version hint:
 
 ```json
 {
@@ -337,62 +309,21 @@ After apply, the result should include a version hint:
 }
 ```
 
-Agent handoff sequence:
+Then:
 
-1. Sync artifacts for `versionId`.
+1. Call `sync_schema_artifacts` with the version ID and app root.
 2. Read `.howone/database/manifest.json`.
-3. Update `src/lib/sdk.ts` generated entity bindings.
-4. Update frontend CRUD/query code.
-5. Validate build.
-
-Never update frontend entity types from the draft patch alone when a synced manifest exists.
+3. Leave backend track.
+4. If app code must call the entity, read SDK track files and update `src/lib/sdk.ts`.
 
-## Common Agent Mistakes
+## Common Mistakes
 
 | Mistake | Correct behavior |
 |---|---|
-| Hand-writing `.howone/database/manifest.json` | Sync from backend version. |
-| Applying one operation after previewing a different patch | Apply the exact previewed patch. |
-| Adding required field without default | Treat as risk; ask migration/default policy. |
-| Public read list without `allowedFilters` / `allowedSorts` | Add public guardrails. |
-| Using `visibility: "public"` as permission model | Write explicit `access.public`. |
+| `payload.definition` for create | Put `properties`, `required`, `access`, etc. directly under `payload`. |
+| `payload.patch` for update | Put changed contract sections directly under `payload`. |
+| `fields[]` or `requiredFields` | Use `properties` object map and `required` array. |
+| Handwriting `.howone/database/manifest.json` | Use `sync_schema_artifacts`. |
+| Updating SDK bindings from draft patch | Read synced manifest first. |
+| Using public visibility as permission model | Write explicit `access.public`. |
 | Deleting data because schema changed | Schema changes do not imply data deletion. |
-| Updating `src/lib/sdk.ts` before manifest sync | Wait for synced manifest. |
-
-## Minimal Safe Patch Template
-
-```ts
-const state = await client.schema.getState()
-
-const patch = {
-  operations: [
-    {
-      type: 'add_field',
-      entityName: 'Todo',
-      payload: {
-        fieldName: 'priority',
-        field: {
-          type: 'string',
-          enum: ['low', 'medium', 'high'],
-          default: 'medium',
-        },
-        required: false,
-      },
-    },
-  ],
-}
-
-const preview = await client.schema.previewPatch(patch, {
-  expectedVersionId: state.currentVersionId,
-  reason: 'Add todo priority',
-})
-
-if (preview.risk?.level === 'dangerous') {
-  throw new Error('User confirmation required before applying schema patch')
-}
-
-const applied = await client.schema.applyPatch(patch, {
-  expectedVersionId: state.currentVersionId,
-  reason: 'Add todo priority',
-})
-```

package/templates/vite/.howone/skills/howone/02-entity-schema/03-access-models.md

@@ -0,0 +1,151 @@
+# Backend Access Models
+
+Use this reference while designing entity `access` contracts with `backend-api-design`.
+It is backend-only: do not write SDK calls from this file.
+
+Access answers four questions:
+
+1. Who can read records?
+2. Who can create records?
+3. Who can update/delete records?
+4. Which anonymous public operations are safe?
+
+## Authenticated Access
+
+Authenticated access is for logged-in users. Values are `own`, `all`, or `none`.
+
+Private per-user records:
+
+```json
+{
+  "access": {
+    "authenticated": {
+      "read": "own",
+      "create": "own",
+      "update": "own",
+      "delete": "own"
+    },
+    "public": {
+      "read": "none",
+      "create": "none",
+      "update": "none",
+      "delete": "none"
+    }
+  }
+}
+```
+
+Shared authenticated records:
+
+```json
+{
+  "access": {
+    "authenticated": {
+      "read": "all",
+      "create": "all",
+      "update": "all",
+      "delete": "all"
+    },
+    "public": {
+      "read": "none",
+      "create": "none",
+      "update": "none",
+      "delete": "none"
+    }
+  }
+}
+```
+
+Use `all` conservatively. If the product implies team roles, moderation, or ownership transitions
+that the dynamic schema cannot express yet, keep the schema narrow and leave role logic to a future
+platform capability or app-owned guard.
+
+## Public Read
+
+Public read is for anonymous access. Values are `none`, `list`, or `scoped`.
+
+Use `list` only when broad anonymous browsing is intended:
+
+```json
+{
+  "access": {
+    "authenticated": {
+      "read": "all",
+      "create": "all",
+      "update": "all",
+      "delete": "all"
+    },
+    "public": {
+      "read": "list",
+      "create": "none",
+      "update": "none",
+      "delete": "none",
+      "allowedFilters": ["status", "category", "slug"],
+      "allowedSorts": ["publishedAt", "updatedDate"],
+      "defaultLimit": 20,
+      "maxLimit": 100
+    }
+  }
+}
+```
+
+Use `scoped` when a public page should expose only records that match route-bound scope fields:
+
+```json
+{
+  "access": {
+    "public": {
+      "read": "scoped",
+      "requiredScopes": ["shareId"],
+      "allowedFilters": ["shareId", "active"],
+      "allowedSorts": ["updatedDate"],
+      "defaultLimit": 1,
+      "maxLimit": 1
+    }
+  }
+}
+```
+
+Public rules:
+
+- Public filters must be listed in `allowedFilters`.
+- Public sorts must be listed in `allowedSorts`.
+- Scoped reads must include every `requiredScopes` field.
+- Public records must not contain private prompts, tokens, internal review states, or owner-only data.
+- Public list entities need indexes covering common filters and sorts.
+
+## Public Create
+
+Public create is only for anonymous submissions such as waitlists, contact forms, feedback, and
+public RSVP flows.
+
+```json
+{
+  "access": {
+    "public": {
+      "read": "none",
+      "create": "scoped",
+      "update": "none",
+      "delete": "none",
+      "requiredScopes": ["created_by_user_id"],
+      "allowedFilters": [],
+      "allowedSorts": [],
+      "defaultLimit": 1,
+      "maxLimit": 1
+    }
+  }
+}
+```
+
+Do not enable public create for user libraries, generated histories, admin content, or entities that
+store sensitive workflow output. Add app-owned anti-abuse controls when anonymous submission is open.
+
+## Access Design Checklist
+
+- The entity has the narrowest access model that supports the product.
+- Private history uses authenticated `own`.
+- Shared admin/internal data uses authenticated `all` only when acceptable.
+- Public list data exposes only safe fields.
+- Public scoped pages use stable scope fields and low `maxLimit`.
+- Public create has a clear ownership/scope story and no anonymous read by default.
+- Access decisions are synced before SDK/UI implementation starts.