@enactprotocol/cli 2.1.28 → 2.1.29

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AA8BH,eAAO,MAAM,OAAO,WAAW,CAAC;AAGhC,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AA+BH,eAAO,MAAM,OAAO,WAAW,CAAC;AAGhC,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -7,9 +7,9 @@
  */
 import { ensureGlobalSetup } from "@enactprotocol/shared";
 import { Command } from "commander";
-import { configureAuthCommand, configureCacheCommand, configureConfigCommand, configureEnvCommand, configureExecCommand, configureInfoCommand, configureInitCommand, configureInspectCommand, configureInstallCommand, configureLearnCommand, configureListCommand, configureMcpCommand, configurePublishCommand, configureReportCommand, configureRunCommand, configureSearchCommand, configureSetupCommand, configureSignCommand, configureTrustCommand, configureUnyankCommand, configureVisibilityCommand, configureYankCommand, } from "./commands";
+import { configureAuthCommand, configureCacheCommand, configureConfigCommand, configureEnvCommand, configureExecCommand, configureInfoCommand, configureInitCommand, configureInspectCommand, configureInstallCommand, configureLearnCommand, configureListCommand, configureMcpCommand, configurePublishCommand, configureReportCommand, configureRunCommand, configureSearchCommand, configureSetupCommand, configureSignCommand, configureTrustCommand, configureUnyankCommand, configureValidateCommand, configureVisibilityCommand, configureYankCommand, } from "./commands";
 import { error, formatError } from "./utils";
-export const version = "2.1.28";
+export const version = "2.1.29";
 // Main CLI entry point
 async function main() {
     // Ensure global setup is complete on first run
@@ -47,6 +47,8 @@ async function main() {
     configureVisibilityCommand(program);
     // MCP integration commands
     configureMcpCommand(program);
+    // Validation command
+    configureValidateCommand(program);
     // Global error handler - handle Commander's help/version exits gracefully
     program.exitOverride((err) => {
         // Commander throws errors for help, version, and other "exit" scenarios

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;AAKhC,uBAAuB;AACvB,KAAK,UAAU,IAAI;IACjB,+CAA+C;IAC/C,iBAAiB,EAAE,CAAC;IAEpB,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,OAAO,CAAC;SACb,WAAW,CAAC,6DAA6D,CAAC;SAC1E,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,2BAA2B,CAAC,CAAC;IAElE,yBAAyB;IACzB,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAEhC,8BAA8B;IAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/B,wCAAwC;IACxC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,uBAAuB,CAAC,OAAO,CAAC,CAAC;IAEjC,4BAA4B;IAC5B,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAEhC,wCAAwC;IACxC,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACpC,2BAA2B;IAC3B,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAE7B,0EAA0E;IAC1E,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,EAAE,EAAE;QAC3B,wEAAwE;QACxE,gEAAgE;QAChE,IACE,GAAG,CAAC,IAAI,KAAK,gBAAgB;YAC7B,GAAG,CAAC,IAAI,KAAK,yBAAyB;YACtC,GAAG,CAAC,IAAI,KAAK,mBAAmB;YAChC,GAAG,CAAC,IAAI,KAAK,kCAAkC;YAC/C,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EACnC,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,iEAAiE;QACjE,MAAM,MAAM,GAAG,GAA0C,CAAC;QAC1D,IAAI,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,IAAI,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACtF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;QACxB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACnB,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;QACxB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -14,6 +14,8 @@ export interface GlobalOptions {
     quiet?: boolean;
     /** Run without making changes (preview mode) */
     dryRun?: boolean;
+    /** Enable debug mode - show detailed parameter and environment information */
+    debug?: boolean;
 }
 /**
  * Context passed to command handlers

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qBAAqB;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gDAAgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,OAAO,EAAE,aAAa,CAAC;IACvB,wCAAwC;IACxC,IAAI,EAAE,OAAO,CAAC;IACd,0CAA0C;IAC1C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACxD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kEAAkE;IAClE,SAAS,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;;;CAOX,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAGhE,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qBAAqB;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gDAAgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,OAAO,EAAE,aAAa,CAAC;IACvB,wCAAwC;IACxC,IAAI,EAAE,OAAO,CAAC;IACd,0CAA0C;IAC1C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACxD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,cAAc,KACpB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,kEAAkE;IAClE,SAAS,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;;;CAOX,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAGhE,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AA+DH;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,CAAC;IACR,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IACX,gBAAgB,EAAE,CAAC;IACnB,SAAS,EAAE,GAAG,EAAE,sBAAsB;CAC9B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiEH;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,CAAC;IACR,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IACX,gBAAgB,EAAE,CAAC;IACnB,SAAS,EAAE,GAAG,EAAE,sBAAsB;CAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enactprotocol/cli",
-  "version": "2.1.28",
+  "version": "2.1.29",
   "description": "Command-line interface for Enact - the npm for AI tools",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,10 +34,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@enactprotocol/api": "2.1.28",
-    "@enactprotocol/execution": "2.1.28",
-    "@enactprotocol/secrets": "2.1.28",
-    "@enactprotocol/shared": "2.1.28",
+    "@enactprotocol/api": "2.1.29",
+    "@enactprotocol/execution": "2.1.29",
+    "@enactprotocol/secrets": "2.1.29",
+    "@enactprotocol/shared": "2.1.29",
     "commander": "^12.1.0",
     "picocolors": "^1.1.1"
   },

package/src/commands/index.ts

@@ -35,3 +35,6 @@ export { configureUnyankCommand } from "./unyank";
 export { configureVisibilityCommand } from "./visibility";
 // MCP integration commands
 export { configureMcpCommand } from "./mcp";
+
+// Validation command
+export { configureValidateCommand } from "./validate";

package/src/commands/init/templates/claude.ts

@@ -3,18 +3,24 @@
  */
 export const claudeTemplate = `# CLAUDE.md
 
-This project uses Enact tools — containerized, signed executables you can run via CLI.
+This project uses Enact tools — containerized, cryptographically-signed executables you can run via CLI.
 
 ## Quick Reference
-\`\`\`bash
-enact run <tool> --args '{"key": "value"}'   # Run a tool
-enact search "keyword"                        # Find tools
-enact learn author/tool                       # View tool documentation
-enact install author/tool                     # Install tool
-enact list                                    # List installed tools
-\`\`\`
+
+| Task | Command |
+|------|---------|
+| Run with JSON | \`enact run <tool> --args '{"key": "value"}'\` |
+| Run from file | \`enact run <tool> --input-file inputs.json\` |
+| Dry run | \`enact run <tool> --args '{}' --dry-run\` |
+| Debug params | \`enact run <tool> --args '{}' --debug\` |
+| Search tools | \`enact search "keyword"\` |
+| View docs | \`enact learn author/tool\` |
+| Install tool | \`enact install author/tool\` |
+| List installed | \`enact list\` |
+| Sign & publish | \`enact sign ./ && enact publish ./\` |
 
 ## Running Tools
+
 Tools take JSON input and return JSON output:
 \`\`\`bash
 # Run and capture output
@@ -24,47 +30,281 @@ result=$(enact run author/utils/formatter --args '{"code": "const x=1"}')
 enact run tool --args '{}' | jq '.data'
 \`\`\`
 
-## Creating Tools
-Create \`SKILL.md\` in a directory:
+## SKILL.md Structure
+
+Each tool is defined by a \`SKILL.md\` file (YAML frontmatter + Markdown docs):
+
 \`\`\`yaml
 ---
 name: namespace/category/tool
-description: Clear description for search
+description: What the tool does
 version: 1.0.0
-from: python:3.12-slim            # Docker image
-build: pip install requests       # Install dependencies (cached)
+enact: "2.0.0"
+
+from: python:3.12-slim            # Docker image (pin versions, not :latest)
+build: pip install requests       # Build steps (cached by Dagger)
 command: python /workspace/main.py \${input}
+timeout: 30s
+
 inputSchema:
   type: object
   properties:
-    input: { type: string, description: "The input to process" }
+    input:
+      type: string
+      description: "Input to process"
   required: [input]
+
+outputSchema:
+  type: object
+  properties:
+    result:
+      type: string
+
+env:
+  API_KEY:
+    description: "External API key"
+    secret: true                  # Set via: enact env set API_KEY --secret
 ---
 # Tool Name
-Usage documentation here.
+Documentation here.
+\`\`\`
+
+## Field Reference
+
+| Field | Description |
+|-------|-------------|
+| \`name\` | Hierarchical ID: \`org/category/tool\` |
+| \`description\` | What the tool does |
+| \`version\` | Semver version |
+| \`from\` | Docker image |
+| \`build\` | Build commands (string or array, cached) |
+| \`command\` | Shell command with \`\${param}\` substitution |
+| \`timeout\` | Max execution time (e.g., "30s", "5m") |
+| \`inputSchema\` | JSON Schema for inputs |
+| \`outputSchema\` | JSON Schema for outputs |
+| \`env\` | Environment variables and secrets |
+
+## Parameter Substitution
+
+Enact auto-quotes parameters. **Never manually quote:**
+
+\`\`\`yaml
+# WRONG - causes double-quoting
+command: python /workspace/main.py "\${input}"
+
+# RIGHT - Enact handles quoting
+command: python /workspace/main.py \${input}
+\`\`\`
+
+**Optional vs Required Parameters:**
+
+Parameters listed in the \`required\` array must be provided. All other properties are optional.
+
+\`\`\`yaml
+inputSchema:
+  type: object
+  properties:
+    url:                              # Required (in required array)
+      type: string
+    user_agent:                       # Optional (not in required array)
+      type: string
+      default: "Mozilla/5.0"          # Provide default for optional params
+    timeout:
+      type: number
+      default: 30
+  required: [url]                     # Only url is required
+\`\`\`
+
+**Best practices for optional parameters:**
+1. Always provide a \`default\` value in the schema when possible
+2. Optional params without defaults become empty strings in commands
+3. Use \`--debug\` to see how parameters are resolved: \`enact run ./ --debug\`
+
+Handle optional params in shell commands:
+\`\`\`yaml
+command: "curl \${url} -A '\${user_agent:-Mozilla/5.0}' --max-time \${timeout:-30}"
+\`\`\`
+
+Modifiers:
+- \`\${param}\` — auto-quoted (handles spaces, JSON, special chars)
+- \`\${param:raw}\` — raw, no quoting (use carefully)
+
+## Output
+
+Output valid JSON to stdout when \`outputSchema\` is defined:
+
+\`\`\`python
+import json, sys
+
+try:
+    result = do_work()
+    print(json.dumps({"status": "success", "result": result}))
+except Exception as e:
+    print(json.dumps({"status": "error", "message": str(e)}))
+    sys.exit(1)  # non-zero = error
+\`\`\`
+
+## Build Steps by Language
+
+**Python:**
+\`\`\`yaml
+from: python:3.12-slim
+build: pip install requests pandas
+\`\`\`
+
+**Node.js:**
+\`\`\`yaml
+from: node:20-alpine
+build:
+  - npm install
+  - npm run build
 \`\`\`
 
-Key points:
-- \`\${param}\` is auto-quoted — never add manual quotes
-- \`from:\` pin image versions (not \`:latest\`)
-- \`build:\` steps are cached by Dagger
-- Output JSON to stdout, errors to stderr
-- Non-zero exit = failure
+**Rust:**
+\`\`\`yaml
+from: rust:1.83-slim
+build: rustc /workspace/main.rs -o /workspace/tool
+command: /workspace/tool \${input}
+\`\`\`
+
+**Go:**
+\`\`\`yaml
+from: golang:1.22-alpine
+build: cd /workspace && go build -o tool main.go
+command: /workspace/tool \${input}
+\`\`\`
+
+**System packages:**
+\`\`\`yaml
+build: apt-get update && apt-get install -y libfoo-dev
+\`\`\`
+
+Build steps are cached — first run slow, subsequent runs instant.
+
+## Base Image Requirements
+
+Not all Docker images work as Enact base images. Requirements:
+
+**Must have:**
+- \`/bin/sh\` (POSIX shell) - Enact wraps commands with \`sh -c\`
+- Standard filesystem layout
 
-## Tool Development Workflow
+**Recommended base images:**
+| Language | Image | Notes |
+|----------|-------|-------|
+| Python | \`python:3.12-slim\` | Best balance of size/features |
+| Node.js | \`node:20-alpine\` | Smallest, may need build tools |
+| Ruby | \`ruby:3.2-slim\` | For Ruby tools |
+| Go | \`golang:1.22-alpine\` | Compile in build step |
+| Rust | \`rust:1.83-slim\` | Compile in build step |
+| General | \`alpine:3.18\` | Minimal, use apk for packages |
+| Debian | \`debian:bookworm-slim\` | More packages, larger |
+
+**Images that may NOT work:**
+- Distroless images (no shell)
+- Scratch images (no shell)
+- Some specialized images with custom entrypoints
+
+**Debugging image issues:**
 \`\`\`bash
-enact run ./ --args '{"input": "test"}'       # Test locally
-enact run ./ --args '{}' --dry-run            # Preview command
-enact sign ./ && enact publish ./             # Publish
+# Test if an image works with Enact
+enact exec . "echo test"  # Run simple command in tool's container
+enact run ./ --verbose    # See detailed container output
 \`\`\`
 
+## File Access
+
+Tools run in a container with \`/workspace\` as the working directory. All source files are copied there.
+
 ## Secrets
-Declare in SKILL.md, set via CLI:
+
+Declare in \`SKILL.md\`:
 \`\`\`yaml
 env:
-  API_KEY:    # Declared but not set
+  API_KEY:
+    description: "API key for service"
+    secret: true
 \`\`\`
+
+Set before running:
 \`\`\`bash
 enact env set API_KEY --secret --namespace author/tool
 \`\`\`
+
+Access in code:
+\`\`\`python
+import os
+api_key = os.environ.get('API_KEY')
+\`\`\`
+
+## LLM Instruction Tools
+
+Tools without a \`command\` field are interpreted by LLMs:
+
+\`\`\`yaml
+---
+name: myorg/ai/reviewer
+description: AI-powered code review
+inputSchema:
+  type: object
+  properties:
+    code: { type: string }
+  required: [code]
+outputSchema:
+  type: object
+  properties:
+    issues: { type: array }
+    score: { type: number }
+---
+# Code Reviewer
+
+You are a senior engineer. Review the code for bugs, style, and security.
+Return JSON: {"issues": [...], "score": 75}
+\`\`\`
+
+## Publishing Checklist
+
+- [ ] \`name\` follows \`namespace/category/tool\` pattern
+- [ ] \`version\` set (semver)
+- [ ] \`description\` is clear and searchable
+- [ ] \`inputSchema\` / \`outputSchema\` defined
+- [ ] \`from\` uses pinned image version
+- [ ] \`timeout\` set appropriately
+- [ ] Tool tested locally with \`enact run ./\`
+
+## Troubleshooting
+
+\`\`\`bash
+enact run ./ --args '{"x": "y"}' --verbose   # Verbose output
+enact run ./ --args '{}' --dry-run           # Preview command without running
+enact run ./ --args '{}' --debug             # Show parameter resolution details
+enact list                                   # List installed tools
+\`\`\`
+
+**Common issues:**
+
+| Issue | Solution |
+|-------|----------|
+| "Missing required parameter" | Check your \`required\` array in inputSchema |
+| Parameters not substituting | Use \`--debug\` to see what values are being passed |
+| Optional params failing | Add \`default\` values or handle empty strings |
+| Build step fails | Use \`--verbose\` to see build output |
+| Base image not working | Use recommended images (see Base Image Requirements) |
+| Command exit code 2 | Check if command exists in the container |
+
+**Debugging build failures:**
+\`\`\`bash
+enact run ./ --args '{}' --verbose   # See build output
+enact exec . "which python"          # Check if command exists
+enact exec . "ls /workspace"         # Check file mounts
+enact validate ./                    # Validate SKILL.md structure
+\`\`\`
+
+**Multi-step builds:** Use YAML array syntax for clearer error reporting:
+\`\`\`yaml
+build:
+  - apk add --no-cache ruby ruby-dev
+  - gem install bundler
+  - bundle install
+\`\`\`
 `;

package/src/commands/init/templates/tool-agents.ts

@@ -12,6 +12,7 @@ Enact tools are containerized, cryptographically-signed executables. Each tool i
 | Run with JSON | \`enact run ./ --args '{"key": "value"}'\` |
 | Run from file | \`enact run ./ --input-file inputs.json\` |
 | Dry run | \`enact run ./ --args '{}' --dry-run\` |
+| Debug params | \`enact run ./ --args '{}' --debug\` |
 | Sign & publish | \`enact sign ./ && enact publish ./\` |
 
 ## SKILL.md Structure
@@ -78,18 +79,33 @@ command: python /workspace/main.py "\${input}"
 command: python /workspace/main.py \${input}
 \`\`\`
 
-**Optional params:** Missing optional params become empty strings. Always provide defaults:
+**Optional vs Required Parameters:**
+
+Parameters listed in the \`required\` array must be provided. All other properties are optional.
+
 \`\`\`yaml
 inputSchema:
+  type: object
   properties:
-    greeting: 
+    url:                              # Required (in required array)
       type: string
-      default: "Hello"  # Recommended for optional params
+    user_agent:                       # Optional (not in required array)
+      type: string
+      default: "Mozilla/5.0"          # Provide default for optional params
+    timeout:
+      type: number
+      default: 30
+  required: [url]                     # Only url is required
 \`\`\`
 
-Or handle empty in shell:
+**Best practices for optional parameters:**
+1. Always provide a \`default\` value in the schema when possible
+2. Optional params without defaults become empty strings in commands
+3. Use \`--debug\` to see how parameters are resolved: \`enact run ./ --debug\`
+
+Handle optional params in shell commands:
 \`\`\`yaml
-command: "echo \${greeting:-Hello} \${name}"
+command: "curl \${url} -A '\${user_agent:-Mozilla/5.0}' --max-time \${timeout:-30}"
 \`\`\`
 
 Modifiers:
@@ -148,6 +164,37 @@ build: apt-get update && apt-get install -y libfoo-dev
 
 Build steps are cached — first run slow, subsequent runs instant.
 
+## Base Image Requirements
+
+Not all Docker images work as Enact base images. Requirements:
+
+**Must have:**
+- \`/bin/sh\` (POSIX shell) - Enact wraps commands with \`sh -c\`
+- Standard filesystem layout
+
+**Recommended base images:**
+| Language | Image | Notes |
+|----------|-------|-------|
+| Python | \`python:3.12-slim\` | Best balance of size/features |
+| Node.js | \`node:20-alpine\` | Smallest, may need build tools |
+| Ruby | \`ruby:3.2-slim\` | For Ruby tools |
+| Go | \`golang:1.22-alpine\` | Compile in build step |
+| Rust | \`rust:1.83-slim\` | Compile in build step |
+| General | \`alpine:3.18\` | Minimal, use apk for packages |
+| Debian | \`debian:bookworm-slim\` | More packages, larger |
+
+**Images that may NOT work:**
+- Distroless images (no shell)
+- Scratch images (no shell)
+- Some specialized images with custom entrypoints
+
+**Debugging image issues:**
+\`\`\`bash
+# Test if an image works with Enact
+enact exec . "echo test"  # Run simple command in tool's container
+enact run ./ --verbose    # See detailed container output
+\`\`\`
+
 ## File Access
 
 Tools run in a container with \`/workspace\` as the working directory. All source files are copied there.
@@ -212,7 +259,35 @@ Return JSON: {"issues": [...], "score": 75}
 
 \`\`\`bash
 enact run ./ --args '{"x": "y"}' --verbose   # Verbose output
-enact run ./ --args '{}' --dry-run             # Preview command
-enact list                                      # List installed tools
+enact run ./ --args '{}' --dry-run           # Preview command without running
+enact run ./ --args '{}' --debug             # Show parameter resolution details
+enact list                                   # List installed tools
+\`\`\`
+
+**Common issues:**
+
+| Issue | Solution |
+|-------|----------|
+| "Missing required parameter" | Check your \`required\` array in inputSchema |
+| Parameters not substituting | Use \`--debug\` to see what values are being passed |
+| Optional params failing | Add \`default\` values or handle empty strings |
+| Build step fails | Use \`--verbose\` to see build output |
+| Base image not working | Use recommended images (see Base Image Requirements) |
+| Command exit code 2 | Check if command exists in the container |
+
+**Debugging build failures:**
+\`\`\`bash
+enact run ./ --args '{}' --verbose   # See build output
+enact exec . "which python"          # Check if command exists
+enact exec . "ls /workspace"         # Check file mounts
+enact validate ./                    # Validate SKILL.md structure
+\`\`\`
+
+**Multi-step builds:** Use YAML array syntax for clearer error reporting:
+\`\`\`yaml
+build:
+  - apk add --no-cache ruby ruby-dev
+  - gem install bundler
+  - bundle install
 \`\`\`
 `;

package/src/commands/run/README.md

@@ -35,6 +35,7 @@ The `run` command executes a tool using the command defined in its manifest (`en
 | `--no-cache` | Disable container caching |
 | `--local` | Only resolve from local sources |
 | `--dry-run` | Show what would be executed without running |
+| `--debug` | Show detailed parameter and environment resolution |
 | `-v, --verbose` | Show detailed output including stderr and timing |
 | `--json` | Output result as JSON |
 
@@ -67,6 +68,9 @@ enact run alice/utils/greeter --args '{"name":"World"}' --json
 
 # Verbose mode for debugging
 enact run alice/utils/greeter --args '{"name":"World"}' --verbose
+
+# Debug parameter resolution
+enact run alice/utils/greeter --args '{"name":"World"}' --debug
 ```
 
 ### Multiple inputs
@@ -158,6 +162,19 @@ When using `--dry-run`, the command shows:
 - Environment variables (secrets masked as `***`)
 - The interpolated command
 
+## Debug Output
+
+When using `--debug`, the command shows detailed parameter resolution:
+
+- Schema properties with types and required/optional status
+- Raw inputs (exactly what was provided)
+- Inputs after defaults were applied
+- Final inputs after validation and type coercion
+- Environment variables (sensitive values masked)
+- The final interpolated command
+
+This is useful for troubleshooting parameter issues and understanding how optional parameters are handled.
+
 ## Exit Codes
 
 | Code | Description |