openuispec 0.1.6 → 0.1.8

package/cli/init.ts

@@ -170,6 +170,50 @@ OpenUISpec is a YAML-based format that describes your app's UI semantically —
 - \`draft\` — actively being specced. Tracked by drift.
 - \`ready\` — fully specified (default if omitted). Tracked by drift.
 
+## Learning OpenUISpec — local files and online reference
+
+All documentation is included in the installed package at \`node_modules/openuispec/\`:
+1. **Full specification:** \`node_modules/openuispec/spec/openuispec-v0.1.md\`
+2. **Example app:** \`node_modules/openuispec/examples/taskflow/\`
+3. **JSON Schemas:** \`node_modules/openuispec/schema/\`
+
+If the package is not in node_modules, fetch the full reference from:
+- \`https://openuispec.rsteam.uz/llms-full.txt\` — complete spec + all JSON schemas in one file
+- \`https://openuispec.rsteam.uz/llms.txt\` — concise summary with links
+
+## JSON Schemas (validation & file structure)
+
+**IMPORTANT:** Before creating or editing any spec file, read the corresponding JSON Schema to understand the valid structure. Schemas are located in the installed package:
+
+\`\`\`
+node_modules/openuispec/schema/
+├── openuispec.schema.json        ← root manifest (openuispec.yaml)
+├── screen.schema.json            ← screen files (screens/*.yaml)
+├── flow.schema.json              ← flow files (flows/*.yaml)
+├── platform.schema.json          ← platform overrides (platform/*.yaml)
+├── locale.schema.json            ← locale files (locales/*.json)
+├── custom-contract.schema.json   ← custom contracts (contracts/*.yaml)
+├── tokens/
+│   ├── color.schema.json         ← tokens/color.yaml
+│   ├── typography.schema.json    ← tokens/typography.yaml
+│   ├── spacing.schema.json       ← tokens/spacing.yaml
+│   ├── elevation.schema.json     ← tokens/elevation.yaml
+│   ├── motion.schema.json        ← tokens/motion.yaml
+│   ├── layout.schema.json        ← tokens/layout.yaml
+│   ├── themes.schema.json        ← tokens/themes.yaml
+│   └── icons.schema.json         ← tokens/icons.yaml
+└── defs/
+    ├── common.schema.json        ← shared types (icons, badges, etc.)
+    ├── action.schema.json        ← 13 action types (discriminated union)
+    ├── data-binding.schema.json  ← data sources, state, params
+    ├── adaptive.schema.json      ← adaptive override pattern
+    └── validation.schema.json    ← validation rule definitions
+\`\`\`
+
+**Workflow:** read the schema → create the YAML file → run \`openuispec validate\` to verify.
+
+**Example spec files:** \`node_modules/openuispec/examples/taskflow/\` — a complete app demonstrating all file types. Read these for real-world examples of screens, flows, tokens, and platform overrides.
+
 ## Spec format quick reference
 
 - **7 contract families:** nav_container, surface, action_trigger, input_field, data_display, collection, feedback
@@ -255,6 +299,29 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
 2. Run \`openuispec drift --snapshot --target <target>\` for each affected platform.
 3. Run \`openuispec drift\` to verify no untracked drift remains.
 
+## Learning OpenUISpec — local files and online reference
+All documentation is included in the installed package at \`node_modules/openuispec/\`:
+1. **Full specification:** \`node_modules/openuispec/spec/openuispec-v0.1.md\` — the complete spec (read this to understand the format)
+2. **Example app:** \`node_modules/openuispec/examples/taskflow/\` — a complete working app with all file types
+3. **JSON Schemas:** \`node_modules/openuispec/schema/\` — validation schemas that define the exact structure of every file type
+
+If the package is not in node_modules, fetch the full reference from:
+- \`https://openuispec.rsteam.uz/llms-full.txt\` — complete spec + all JSON schemas in one file
+- \`https://openuispec.rsteam.uz/llms.txt\` — concise summary with links
+
+## JSON Schemas — read before creating spec files
+Before creating or editing any spec file, read the corresponding JSON Schema to understand the valid structure:
+- \`node_modules/openuispec/schema/openuispec.schema.json\` — root manifest
+- \`node_modules/openuispec/schema/screen.schema.json\` — screens
+- \`node_modules/openuispec/schema/flow.schema.json\` — flows
+- \`node_modules/openuispec/schema/platform.schema.json\` — platform overrides
+- \`node_modules/openuispec/schema/locale.schema.json\` — locales
+- \`node_modules/openuispec/schema/custom-contract.schema.json\` — custom contracts
+- \`node_modules/openuispec/schema/tokens/*.schema.json\` — token files (color, typography, spacing, elevation, motion, layout, themes, icons)
+- \`node_modules/openuispec/schema/defs/*.schema.json\` — shared types (actions, data-binding, adaptive, validation, common)
+
+Workflow: read the spec → read the schema → read an example → create the YAML → run \`openuispec validate\`.
+
 ## Spec format reference
 - 7 contract families: nav_container, surface, action_trigger, input_field, data_display, collection, feedback
 - Custom contracts: prefixed with \`x_\` (e.g., \`x_media_player\`)

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "openuispec",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",
+  "homepage": "https://openuispec.rsteam.uz",
   "repository": {
     "type": "git",
     "url": "https://github.com/rsktash/openuispec.git"