howone 0.1.23 → 0.1.26

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

@@ -1,96 +0,0 @@
-# Schema Operations
-
-Use this reference when applying backend entity schema changes through HowOne runtime tools.
-
-## Source Of Truth
-
-```text
-agent proposal != source of truth
-validated backend manifest = source of truth
-synced .howone/database files = local copy of a backend version
-src/lib/sdk.ts = app binding generated from synced manifest
-```
-
-Do not hand-write `.howone/database` files. Sync them from a concrete backend schema version.
-
-## Preferred Patch Flow
-
-For feature-level schema work:
-
-1. Inspect current schema definitions or schema state.
-2. Design one complete patch containing all related operations.
-3. Preview the patch.
-4. Apply the exact same operations if risk is acceptable.
-5. Sync schema artifacts using the returned `next.versionId`.
-6. Read `.howone/database/manifest.json`.
-7. Update `src/lib/sdk.ts` from the manifest.
-8. Update frontend calls according to access.
-9. Validate.
-
-Do not preview a patch and then apply a different set of single operations.
-
-## Operation Types
-
-Supported schema operations:
-
-| Type | Purpose |
-|---|---|
-| `list_entities` | List current entity definitions. |
-| `get_entity` | Read one entity definition before modifying it. |
-| `create_entity` | Create a new entity contract. |
-| `update_entity` | Update entity metadata such as description, visibility, access, indexes, relations, presentation, lifecycle, performance. |
-| `delete_entity` | Soft or hard delete an entity definition. |
-| `add_field` | Add a new field. |
-| `update_field` | Patch an existing field definition. |
-| `delete_field` | Remove a field from schema, optionally from historical data. |
-| `set_field_required` | Add a field to top-level `required`. |
-| `unset_field_required` | Remove a field from top-level `required`. |
-
-## Payload Rules
-
-- `entityName` is required for every operation except `list_entities`.
-- `payload.properties` is required for `create_entity`.
-- `payload.required` must only contain fields that exist in `properties`.
-- `add_field` should use `{ fieldName, field, required }`.
-- `update_field` should use `{ fieldName, patch, required? }`.
-- `delete_field` should use `{ fieldName, removeFromData: false }` by default.
-- `required` belongs to the entity top level, not inside individual field definitions.
-
-## Risk Guardrails
-
-- Default entity deletion to soft delete.
-- Use hard delete only when the user explicitly asks.
-- Use `deleteData: true` only when the user explicitly asks to delete all records too.
-- Use `removeFromData: true` only after explicit confirmation.
-- Adding a required field to an existing entity should include a default when possible.
-- Changing a field type is high risk; inspect current schema and confirm intent before applying.
-- Schema restore creates a new restore version; it does not roll business data back.
-
-## Version Rules
-
-Schema versions manage entity definitions only. They do not roll back `entitydatashares`.
-
-After apply, use the returned version context:
-
-```json
-{
-  "next": {
-    "recommendedAction": "sync_schema_artifacts",
-    "versionId": "dbv_next"
-  }
-}
-```
-
-The synced manifest must be read before updating SDK bindings.
-
-## Narrow Edit Flow
-
-Single operations are acceptable for small explicit edits, such as "add priority to Todo":
-
-1. `get_entity`
-2. Check whether field already exists.
-3. Preview/apply one `add_field` patch or use the schema operation fallback.
-4. Sync artifacts.
-5. Update SDK/UI.
-
-For broader features, batch operations into one patch.

package/templates/vite/.howone/skills/howone-sdk/02-database/03-data-access-patterns.md

@@ -1,172 +0,0 @@
-# Data Access Patterns
-
-Use this reference to connect backend `access` design to frontend SDK calls.
-
-## Private Per-User Data
-
-Use for todos, notes, journals, saved generations, personal files, dashboards, and user-owned
-settings.
-
-Schema posture:
-
-```json
-{
-  "visibility": "private",
-  "access": {
-    "authenticated": {
-      "read": "own",
-      "create": "own",
-      "update": "own",
-      "delete": "own"
-    },
-    "public": {
-      "read": "none",
-      "create": "none",
-      "update": "none",
-      "delete": "none"
-    }
-  }
-}
-```
-
-Frontend calls:
-
-```ts
-const result = await howone.entities.Todo.query.mine({
-  page: { number: 1, size: 50 },
-  orderBy: { updatedDate: 'desc' },
-})
-```
-
-Rules:
-
-- Use `query.mine(...)` for list pages.
-- Use authenticated `create/update/delete`.
-- Do not pass owner fields such as `ownerId`, `created_by_id`, `createdById`,
-  `created_by_user_id`, or `puid`.
-
-## Authenticated Shared Data
-
-Use when logged-in users in the app should see shared records.
-
-Schema posture:
-
-```json
-{
-  "visibility": "private",
-  "access": {
-    "authenticated": {
-      "read": "all",
-      "create": "all",
-      "update": "all",
-      "delete": "all"
-    },
-    "public": {
-      "read": "none",
-      "create": "none",
-      "update": "none",
-      "delete": "none"
-    }
-  }
-}
-```
-
-Frontend calls:
-
-```ts
-const result = await howone.entities.Project.query({
-  page: { number: 1, size: 20 },
-  orderBy: { updatedDate: 'desc' },
-})
-```
-
-Use `query(...)`, not `query.mine(...)`.
-
-## Public Read-Only Content
-
-Use for public articles, templates, catalogs, profiles, or landing-page content.
-
-Schema posture:
-
-```json
-{
-  "visibility": "public",
-  "access": {
-    "authenticated": {
-      "read": "all",
-      "create": "all",
-      "update": "all",
-      "delete": "all"
-    },
-    "public": {
-      "read": "list",
-      "create": "none",
-      "update": "none",
-      "delete": "none",
-      "allowedFilters": ["slug", "status", "category"],
-      "allowedSorts": ["publishedAt", "updatedDate"],
-      "defaultLimit": 20,
-      "maxLimit": 100
-    }
-  }
-}
-```
-
-Frontend calls:
-
-```ts
-const result = await howone.public.entities.Article.query({
-  where: { status: 'published' },
-  page: { number: 1, size: 20 },
-  orderBy: { publishedAt: 'desc' },
-})
-```
-
-Public query types should expose only allowed filters and allowed sorts.
-
-## Public Scoped Share Pages
-
-Use for public URLs that expose one owner-scoped record, such as QR pages or profile pages.
-
-Schema posture:
-
-```json
-{
-  "visibility": "public",
-  "access": {
-    "authenticated": {
-      "read": "own",
-      "create": "own",
-      "update": "own",
-      "delete": "own"
-    },
-    "public": {
-      "read": "scoped",
-      "create": "none",
-      "update": "none",
-      "delete": "none",
-      "requiredScopes": ["ownerId", "slug"],
-      "allowedFilters": ["slug", "active"],
-      "allowedSorts": ["updatedDate"],
-      "defaultLimit": 1,
-      "maxLimit": 10
-    }
-  }
-}
-```
-
-Frontend calls:
-
-```ts
-const result = await howone.public.entities.QrProfile.queryScoped({
-  where: { ownerId, slug, active: true },
-  page: { number: 1, size: 1 },
-})
-```
-
-Rules:
-
-- Pass every `requiredScopes` field.
-- Do not use current user's `puid` as public owner scope unless schema explicitly stores that
-  value as the public scope.
-- Public scoped reads must stay inside `howone.public.entities.*`.