From 258dfa07d7543ef9edf142b7c1db231b49583a3f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 7 Jan 2026 19:27:15 +0000
Subject: [PATCH] Improve documentation clarity based on code review feedback

Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com>
---
 schemas/package-schemas/index_schema.json |  2 +-
 scripts/generate-package.ts               |  3 ++-
 storybook/src/stories/Introduction.mdx    | 24 ++++++++++++-----------
 3 files changed, 16 insertions(+), 13 deletions(-)

diff --git a/schemas/package-schemas/index_schema.json b/schemas/package-schemas/index_schema.json
index 5d2713bf7..679d4049a 100644
--- a/schemas/package-schemas/index_schema.json
+++ b/schemas/package-schemas/index_schema.json
@@ -346,7 +346,7 @@
           "description": "Package structure template mapping paths to schemas",
           "additionalProperties": {
             "type": "string",
-            "description": "Schema name for this location"
+            "description": "Schema name for this location. Note: scripts/*.json must follow script_schema.json with full function implementations (body), not just metadata declarations."
           },
           "default": {
             "package.json": "metadata",
diff --git a/scripts/generate-package.ts b/scripts/generate-package.ts
index 1f67431d8..612b17f1b 100644
--- a/scripts/generate-package.ts
+++ b/scripts/generate-package.ts
@@ -411,7 +411,8 @@ function generate(config: PackageConfig): GeneratedFile[] {
   files.push({ path: 'seed/metadata.json', content: generateMetadata(config) })
   files.push({ path: 'seed/components.json', content: generateComponentsJson(config) })
   files.push({ path: 'seed/layout.json', content: generateLayoutJson(config) })
-  // Removed functions.json generation - stick to proper script schema files with implementations
+  // Note: functions.json removed - script_schema.json requires full implementations with function bodies,
+  // not just metadata declarations. Use properly named script files (e.g., automation.json, lifecycle.json)
   files.push({ path: 'seed/index.ts', content: generateIndexTs(config) })
 
   // Schema files
diff --git a/storybook/src/stories/Introduction.mdx b/storybook/src/stories/Introduction.mdx
index 0beee3d7a..39ab97339 100644
--- a/storybook/src/stories/Introduction.mdx
+++ b/storybook/src/stories/Introduction.mdx
@@ -37,25 +37,27 @@ Test packages with different user contexts:
 - **Admin (Nerd Mode)** - Level 4 with nerdMode enabled
 - **Supergod** - Level 6 user
 
-## How It Works
-
-1. **JSON script packages** in `/packages/*/seed/scripts/` define UI component trees
-2. **Mock data** mirrors the output structure produced by the JSON scripts
-3. **PackageRenderer** (still the runtime entry) converts the component tree to React components
-4. **Component Registry** maps package-defined type names to React implementations
+## How It Works
 
-## Package Structure
-
-Each JSON script package follows this structure:
+1. **JSON script packages** in `/packages/*/seed/scripts/` define UI component trees
+2. **Mock data** mirrors the output structure produced by the JSON scripts
+3. **PackageRenderer** (still the runtime entry) converts the component tree to React components
+4. **Component Registry** maps package-defined type names to React implementations
+
+## Package Structure
+
+Each JSON script package follows this structure:
 
 ```
 packages/
 └── {package_name}/
-    └── seed/
+    └── seed/
         ├── metadata.json      # Package info
         ├── components.json    # Component definitions
         └── scripts/
-            └── [script-name].json  # JSON script definitions (e.g., automation.json)
+            └── [script-name].json  # JSON script definitions following script_schema.json
+                                     # Must include full function implementations with bodies,
+                                     # not just metadata declarations (e.g., automation.json)
 ```
 
 ## JSON Script Output