howone 0.1.30 → 0.1.32

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

@@ -0,0 +1,329 @@
+# Schema Operations
+
+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
+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 handwrite `.howone/database/*`. Sync from a backend version after apply.
+
+## Normal Flow
+
+For generated app work, avoid fake dry-runs. Build one correct patch and apply it.
+
+```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.
+```
+
+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.
+
+## Patch Shape
+
+```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" }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+Critical shape rules:
+
+- `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
+
+Patch operations accepted by `backend-api-design`:
+
+```text
+create_entity
+update_entity
+delete_entity
+add_field
+update_field
+delete_field
+set_field_required
+unset_field_required
+```
+
+Inspect/version operations are top-level tool calls, not patch operations:
+
+```text
+get_current_schema
+list_entities
+get_entity
+list_schema_versions
+get_schema_version
+restore_schema_version
+diff_schema_versions
+```
+
+## Operation Payloads
+
+### create_entity
+
+Use when the entity does not exist.
+
+```json
+{
+  "type": "create_entity",
+  "entityName": "Article",
+  "payload": {
+    "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
+      }
+    }
+  }
+}
+```
+
+Rules:
+
+- 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 entity metadata and contract sections.
+
+```json
+{
+  "type": "update_entity",
+  "entityName": "Article",
+  "payload": {
+    "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"]
+    }
+  }
+}
+```
+
+Allowed sections include `description`, `visibility`, `isActive`, `access`, `indexes`,
+`relations`, `presentation`, `lifecycle`, and `performance`.
+
+### add_field
+
+```json
+{
+  "type": "add_field",
+  "entityName": "Todo",
+  "payload": {
+    "fieldName": "priority",
+    "field": {
+      "type": "string",
+      "enum": ["low", "medium", "high"],
+      "default": "medium"
+    },
+    "required": false
+  }
+}
+```
+
+Rules:
+
+- 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
+
+```json
+{
+  "type": "update_field",
+  "entityName": "Todo",
+  "payload": {
+    "fieldName": "priority",
+    "patch": {
+      "enum": ["low", "medium", "high", "urgent"]
+    }
+  }
+}
+```
+
+Usually safe: adding enum values, adding descriptions, adding validation hints.
+
+Risky: removing enum values, changing type, removing defaults, narrowing nullability, or making
+existing data invalid.
+
+### delete_field
+
+```json
+{
+  "type": "delete_field",
+  "entityName": "Todo",
+  "payload": {
+    "fieldName": "legacyTag",
+    "removeFromData": false
+  }
+}
+```
+
+Default `removeFromData` to `false`. `true` requires explicit user confirmation.
+
+### set_field_required / unset_field_required
+
+```json
+{
+  "type": "set_field_required",
+  "entityName": "Todo",
+  "payload": { "fieldName": "text" }
+}
+```
+
+Setting required on existing data is risky unless a default exists or old records are known valid.
+Unsetting required is usually safe.
+
+### delete_entity
+
+```json
+{
+  "type": "delete_entity",
+  "entityName": "Todo",
+  "payload": {
+    "mode": "soft",
+    "deleteData": false
+  }
+}
+```
+
+Rules:
+
+- Default to `mode: "soft"`.
+- `mode: "hard"` requires explicit user request.
+- `deleteData: true` requires explicit confirmation.
+
+## Risk Checklist
+
+Stop before apply and align with the user when the patch:
+
+- 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.
+
+Usually safe to apply directly:
+
+- 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.
+
+## Sync Handoff
+
+After apply, use the returned version hint:
+
+```json
+{
+  "next": {
+    "recommendedAction": "sync_schema_artifacts",
+    "versionId": "dbv_next"
+  }
+}
+```
+
+Then:
+
+1. Call `sync_schema_artifacts` with the version ID and app root.
+2. Read `.howone/database/manifest.json`.
+3. Leave backend track.
+4. If app code must call the entity, read SDK track files and update `src/lib/sdk.ts`.
+
+## Common Mistakes
+
+| Mistake | Correct behavior |
+|---|---|
+| `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. |

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.

package/templates/vite/.howone/skills/howone/02-entity-schema/04-query-contracts.md

@@ -0,0 +1,123 @@
+# Backend Query Contracts
+
+Use this reference while designing entity query behavior: filters, sorts, pagination, indexes, and
+public constraints. It is backend-only; SDK query syntax belongs in `04-app-sdk/12-query-dsl-and-responses.md`.
+
+## Query Surface
+
+Every list/detail experience should be traceable to fields declared in the entity schema:
+
+| Need | Contract field |
+|---|---|
+| Filter by status/category/slug | `access.public.allowedFilters` for public reads; schema field exists |
+| Sort by date/rank/title | `access.public.allowedSorts` for public reads; `performance.allowedSorts` for app reads |
+| Fast owner history | owner-scoped index such as `["status", "updatedDate"]` |
+| Public one-record page | `public.read = "scoped"`, `requiredScopes`, low `maxLimit` |
+| Search | explicit product support; do not use as a replacement for scopes |
+
+## Filter Fields
+
+Only expose fields that are safe and stable.
+
+Good public filters:
+
+```json
+{
+  "allowedFilters": ["slug", "status", "category", "active"]
+}
+```
+
+Avoid public filters for:
+
+- private prompt text;
+- owner/user identifiers unless they are intentional route scopes;
+- internal moderation fields;
+- payment, token, or provider metadata;
+- high-cardinality fields that have no index and will be queried frequently.
+
+## Sort Fields
+
+Prefer predictable date or rank fields:
+
+```json
+{
+  "allowedSorts": ["publishedAt", "updatedDate"],
+  "defaultLimit": 20,
+  "maxLimit": 100
+}
+```
+
+Rules:
+
+- Public sort fields must be explicitly listed.
+- Sort fields used by large lists should have supporting indexes.
+- Do not expose arbitrary revenue, score, or internal ranking fields publicly unless the product
+  explicitly needs them.
+- Keep public `maxLimit` bounded.
+
+## Index Planning
+
+Design indexes from actual access patterns:
+
+```json
+{
+  "indexes": [
+    { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" },
+    { "name": "owner_status_updated", "fields": ["status", "updatedDate"], "scope": "owner" },
+    { "name": "public_slug_unique", "fields": ["slug"], "unique": true },
+    { "name": "public_status_published", "fields": ["status", "publishedAt"], "scope": "global" }
+  ]
+}
+```
+
+Use owner-scoped indexes for private per-user histories. Use global indexes for anonymous public
+lists. Use unique indexes for slug/share IDs when routes depend on uniqueness.
+
+## System Fields
+
+Generated records usually expose system fields such as:
+
+| Concept | Typical field |
+|---|---|
+| record id | `id` |
+| created date | `createdDate` |
+| updated date | `updatedDate` |
+| owner | `createdById` |
+| schema version id | `schemaVersionId` |
+| schema version number | `schemaVersionNumber` |
+
+Do not design app behavior around raw storage-only names unless the manifest or SDK reference
+requires that shape.
+
+## Pagination Defaults
+
+Every list contract should define practical limits:
+
+```json
+{
+  "performance": {
+    "defaultLimit": 20,
+    "maxLimit": 100,
+    "allowedSorts": ["updatedDate", "createdDate"]
+  }
+}
+```
+
+Public scoped detail pages should usually use:
+
+```json
+{
+  "defaultLimit": 1,
+  "maxLimit": 1
+}
+```
+
+## Query Contract Checklist
+
+- Every planned filter field exists in `properties`.
+- Public filters and sorts are explicitly allowlisted.
+- Owner/private histories have owner-scoped indexes.
+- Public lists have global indexes for common filter/sort combinations.
+- Scoped public pages include required scope fields and low limits.
+- List pages have pagination limits before SDK/UI code starts.
+- Query implementation is written only after `.howone/database/manifest.json` is synced.