@enactprotocol/cli 2.1.24 → 2.1.29

package/dist/commands/index.d.ts

@@ -24,4 +24,6 @@ export { configureInspectCommand } from "./inspect";
 export { configureYankCommand } from "./yank";
 export { configureUnyankCommand } from "./unyank";
 export { configureVisibilityCommand } from "./visibility";
+export { configureMcpCommand } from "./mcp";
+export { configureValidateCommand } from "./validate";
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGlD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAGhD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAGpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGlD,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGlD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAGhD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAGpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGlD,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAG5C,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC"}

package/dist/commands/index.js

@@ -28,4 +28,8 @@ export { configureYankCommand } from "./yank";
 export { configureUnyankCommand } from "./unyank";
 // Private tools (Phase - visibility management)
 export { configureVisibilityCommand } from "./visibility";
+// MCP integration commands
+export { configureMcpCommand } from "./mcp";
+// Validation command
+export { configureValidateCommand } from "./validate";
 //# sourceMappingURL=index.js.map

package/dist/commands/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAElD,8BAA8B;AAC9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAEhD,wCAAwC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEpD,4BAA4B;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAElD,gDAAgD;AAChD,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAElD,8BAA8B;AAC9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAEhD,wCAAwC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AAEpD,4BAA4B;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAElD,gDAAgD;AAChD,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,2BAA2B;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAE5C,qBAAqB;AACrB,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC"}

package/dist/commands/init/templates/claude.d.ts

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

package/dist/commands/init/templates/claude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/templates/claude.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,cAAc,20DAkE1B,CAAC"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/templates/claude.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,cAAc,8pQAkT1B,CAAC"}

package/dist/commands/init/templates/claude.js

@@ -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,48 +30,282 @@ 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)
-command: python /work/main.py \${input}
+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}
 \`\`\`
 
-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
+**Optional vs Required Parameters:**
 
-## Tool Development Workflow
+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
+\`\`\`
+
+**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
+
+**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
+\`\`\`
 `;
 //# sourceMappingURL=claude.js.map

package/dist/commands/init/templates/claude.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../../../src/commands/init/templates/claude.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkE7B,CAAC"}
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../../../src/commands/init/templates/claude.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkT7B,CAAC"}

package/dist/commands/init/templates/tool-agents.d.ts

@@ -1,5 +1,5 @@
 /**
  * AGENTS.md template for tool development
  */
-export declare const toolAgentsTemplate = "# Enact Tool Development Guide\n\nEnact tools are containerized, cryptographically-signed executables. Each tool is defined by a `SKILL.md` file (YAML frontmatter + Markdown docs).\n\n## Quick Reference\n\n| Task | Command |\n|------|---------|\n| Run with JSON | `enact run ./ --args '{\"key\": \"value\"}'` |\n| Run from file | `enact run ./ --input-file inputs.json` |\n| Dry run | `enact run ./ --args '{}' --dry-run` |\n| Sign & publish | `enact sign ./ && enact publish ./` |\n\n## SKILL.md Structure\n\n```yaml\n---\nname: {{TOOL_NAME}}\ndescription: What the tool does\nversion: 1.0.0\nenact: \"2.0.0\"\n\nfrom: python:3.12-slim            # Docker image (pin versions, not :latest)\nbuild: pip install requests       # Build steps (cached by Dagger)\ncommand: python /work/main.py ${input}\ntimeout: 30s\n\ninputSchema:\n  type: object\n  properties:\n    input:\n      type: string\n      description: \"Input to process\"\n  required: [input]\n\noutputSchema:\n  type: object\n  properties:\n    result:\n      type: string\n\nenv:\n  API_KEY:\n    description: \"External API key\"\n    secret: true                  # Set via: enact env set API_KEY --secret\n---\n# Tool Name\nDocumentation here.\n```\n\n## Field Reference\n\n| Field | Description |\n|-------|-------------|\n| `name` | Hierarchical ID: `org/category/tool` |\n| `description` | What the tool does |\n| `version` | Semver version |\n| `from` | Docker image |\n| `build` | Build commands (string or array, cached) |\n| `command` | Shell command with `${param}` substitution |\n| `timeout` | Max execution time (e.g., \"30s\", \"5m\") |\n| `inputSchema` | JSON Schema for inputs |\n| `outputSchema` | JSON Schema for outputs |\n| `env` | Environment variables and secrets |\n\n## Parameter Substitution\n\nEnact auto-quotes parameters. **Never manually quote:**\n\n```yaml\n# WRONG - causes double-quoting\ncommand: python /work/main.py \"${input}\"\n\n# RIGHT - Enact handles quoting\ncommand: python /work/main.py ${input}\n```\n\n**Optional params:** Missing optional params become empty strings. Always provide defaults:\n```yaml\ninputSchema:\n  properties:\n    greeting: \n      type: string\n      default: \"Hello\"  # Recommended for optional params\n```\n\nOr handle empty in shell:\n```yaml\ncommand: \"echo ${greeting:-Hello} ${name}\"\n```\n\nModifiers:\n- `${param}` \u2014 auto-quoted (handles spaces, JSON, special chars)\n- `${param:raw}` \u2014 raw, no quoting (use carefully)\n\n## Output\n\nOutput valid JSON to stdout when `outputSchema` is defined:\n\n```python\nimport json, sys\n\ntry:\n    result = do_work()\n    print(json.dumps({\"status\": \"success\", \"result\": result}))\nexcept Exception as e:\n    print(json.dumps({\"status\": \"error\", \"message\": str(e)}))\n    sys.exit(1)  # non-zero = error\n```\n\n## Build Steps by Language\n\n**Python:**\n```yaml\nfrom: python:3.12-slim\nbuild: pip install requests pandas\n```\n\n**Node.js:**\n```yaml\nfrom: node:20-alpine\nbuild:\n  - npm install\n  - npm run build\n```\n\n**Rust:**\n```yaml\nfrom: rust:1.83-slim\nbuild: rustc /work/main.rs -o /work/tool\ncommand: /work/tool ${input}\n```\n\n**Go:**\n```yaml\nfrom: golang:1.22-alpine\nbuild: cd /work && go build -o tool main.go\ncommand: /work/tool ${input}\n```\n\n**System packages:**\n```yaml\nbuild: apt-get update && apt-get install -y libfoo-dev\n```\n\nBuild steps are cached \u2014 first run slow, subsequent runs instant.\n\n## File Access\n\nTools run in a container with `/work` as the working directory. All source files are copied there.\n\n## Secrets\n\nDeclare in `SKILL.md`:\n```yaml\nenv:\n  API_KEY:\n    description: \"API key for service\"\n    secret: true\n```\n\nSet before running:\n```bash\nenact env set API_KEY --secret --namespace {{TOOL_NAME}}\n```\n\nAccess in code:\n```python\nimport os\napi_key = os.environ.get('API_KEY')\n```\n\n## LLM Instruction Tools\n\nTools without a `command` field are interpreted by LLMs:\n\n```yaml\n---\nname: myorg/ai/reviewer\ndescription: AI-powered code review\ninputSchema:\n  type: object\n  properties:\n    code: { type: string }\n  required: [code]\noutputSchema:\n  type: object\n  properties:\n    issues: { type: array }\n    score: { type: number }\n---\n# Code Reviewer\n\nYou are a senior engineer. Review the code for bugs, style, and security.\nReturn JSON: {\"issues\": [...], \"score\": 75}\n```\n\n## Publishing Checklist\n\n- [ ] `name` follows `namespace/category/tool` pattern\n- [ ] `version` set (semver)\n- [ ] `description` is clear and searchable\n- [ ] `inputSchema` / `outputSchema` defined\n- [ ] `from` uses pinned image version\n- [ ] `timeout` set appropriately\n- [ ] Tool tested locally with `enact run ./`\n\n## Troubleshooting\n\n```bash\nenact run ./ --args '{\"x\": \"y\"}' --verbose   # Verbose output\nenact run ./ --args '{}' --dry-run             # Preview command\nenact list                                      # List installed tools\n```\n";
+export declare const toolAgentsTemplate = "# Enact Tool Development Guide\n\nEnact tools are containerized, cryptographically-signed executables. Each tool is defined by a `SKILL.md` file (YAML frontmatter + Markdown docs).\n\n## Quick Reference\n\n| Task | Command |\n|------|---------|\n| Run with JSON | `enact run ./ --args '{\"key\": \"value\"}'` |\n| Run from file | `enact run ./ --input-file inputs.json` |\n| Dry run | `enact run ./ --args '{}' --dry-run` |\n| Debug params | `enact run ./ --args '{}' --debug` |\n| Sign & publish | `enact sign ./ && enact publish ./` |\n\n## SKILL.md Structure\n\n```yaml\n---\nname: {{TOOL_NAME}}\ndescription: What the tool does\nversion: 1.0.0\nenact: \"2.0.0\"\n\nfrom: python:3.12-slim            # Docker image (pin versions, not :latest)\nbuild: pip install requests       # Build steps (cached by Dagger)\ncommand: python /workspace/main.py ${input}\ntimeout: 30s\n\ninputSchema:\n  type: object\n  properties:\n    input:\n      type: string\n      description: \"Input to process\"\n  required: [input]\n\noutputSchema:\n  type: object\n  properties:\n    result:\n      type: string\n\nenv:\n  API_KEY:\n    description: \"External API key\"\n    secret: true                  # Set via: enact env set API_KEY --secret\n---\n# Tool Name\nDocumentation here.\n```\n\n## Field Reference\n\n| Field | Description |\n|-------|-------------|\n| `name` | Hierarchical ID: `org/category/tool` |\n| `description` | What the tool does |\n| `version` | Semver version |\n| `from` | Docker image |\n| `build` | Build commands (string or array, cached) |\n| `command` | Shell command with `${param}` substitution |\n| `timeout` | Max execution time (e.g., \"30s\", \"5m\") |\n| `inputSchema` | JSON Schema for inputs |\n| `outputSchema` | JSON Schema for outputs |\n| `env` | Environment variables and secrets |\n\n## Parameter Substitution\n\nEnact auto-quotes parameters. **Never manually quote:**\n\n```yaml\n# WRONG - causes double-quoting\ncommand: python /workspace/main.py \"${input}\"\n\n# RIGHT - Enact handles quoting\ncommand: python /workspace/main.py ${input}\n```\n\n**Optional vs Required Parameters:**\n\nParameters listed in the `required` array must be provided. All other properties are optional.\n\n```yaml\ninputSchema:\n  type: object\n  properties:\n    url:                              # Required (in required array)\n      type: string\n    user_agent:                       # Optional (not in required array)\n      type: string\n      default: \"Mozilla/5.0\"          # Provide default for optional params\n    timeout:\n      type: number\n      default: 30\n  required: [url]                     # Only url is required\n```\n\n**Best practices for optional parameters:**\n1. Always provide a `default` value in the schema when possible\n2. Optional params without defaults become empty strings in commands\n3. Use `--debug` to see how parameters are resolved: `enact run ./ --debug`\n\nHandle optional params in shell commands:\n```yaml\ncommand: \"curl ${url} -A '${user_agent:-Mozilla/5.0}' --max-time ${timeout:-30}\"\n```\n\nModifiers:\n- `${param}` \u2014 auto-quoted (handles spaces, JSON, special chars)\n- `${param:raw}` \u2014 raw, no quoting (use carefully)\n\n## Output\n\nOutput valid JSON to stdout when `outputSchema` is defined:\n\n```python\nimport json, sys\n\ntry:\n    result = do_work()\n    print(json.dumps({\"status\": \"success\", \"result\": result}))\nexcept Exception as e:\n    print(json.dumps({\"status\": \"error\", \"message\": str(e)}))\n    sys.exit(1)  # non-zero = error\n```\n\n## Build Steps by Language\n\n**Python:**\n```yaml\nfrom: python:3.12-slim\nbuild: pip install requests pandas\n```\n\n**Node.js:**\n```yaml\nfrom: node:20-alpine\nbuild:\n  - npm install\n  - npm run build\n```\n\n**Rust:**\n```yaml\nfrom: rust:1.83-slim\nbuild: rustc /workspace/main.rs -o /workspace/tool\ncommand: /workspace/tool ${input}\n```\n\n**Go:**\n```yaml\nfrom: golang:1.22-alpine\nbuild: cd /workspace && go build -o tool main.go\ncommand: /workspace/tool ${input}\n```\n\n**System packages:**\n```yaml\nbuild: apt-get update && apt-get install -y libfoo-dev\n```\n\nBuild steps are cached \u2014 first run slow, subsequent runs instant.\n\n## Base Image Requirements\n\nNot all Docker images work as Enact base images. Requirements:\n\n**Must have:**\n- `/bin/sh` (POSIX shell) - Enact wraps commands with `sh -c`\n- Standard filesystem layout\n\n**Recommended base images:**\n| Language | Image | Notes |\n|----------|-------|-------|\n| Python | `python:3.12-slim` | Best balance of size/features |\n| Node.js | `node:20-alpine` | Smallest, may need build tools |\n| Ruby | `ruby:3.2-slim` | For Ruby tools |\n| Go | `golang:1.22-alpine` | Compile in build step |\n| Rust | `rust:1.83-slim` | Compile in build step |\n| General | `alpine:3.18` | Minimal, use apk for packages |\n| Debian | `debian:bookworm-slim` | More packages, larger |\n\n**Images that may NOT work:**\n- Distroless images (no shell)\n- Scratch images (no shell)\n- Some specialized images with custom entrypoints\n\n**Debugging image issues:**\n```bash\n# Test if an image works with Enact\nenact exec . \"echo test\"  # Run simple command in tool's container\nenact run ./ --verbose    # See detailed container output\n```\n\n## File Access\n\nTools run in a container with `/workspace` as the working directory. All source files are copied there.\n\n## Secrets\n\nDeclare in `SKILL.md`:\n```yaml\nenv:\n  API_KEY:\n    description: \"API key for service\"\n    secret: true\n```\n\nSet before running:\n```bash\nenact env set API_KEY --secret --namespace {{TOOL_NAME}}\n```\n\nAccess in code:\n```python\nimport os\napi_key = os.environ.get('API_KEY')\n```\n\n## LLM Instruction Tools\n\nTools without a `command` field are interpreted by LLMs:\n\n```yaml\n---\nname: myorg/ai/reviewer\ndescription: AI-powered code review\ninputSchema:\n  type: object\n  properties:\n    code: { type: string }\n  required: [code]\noutputSchema:\n  type: object\n  properties:\n    issues: { type: array }\n    score: { type: number }\n---\n# Code Reviewer\n\nYou are a senior engineer. Review the code for bugs, style, and security.\nReturn JSON: {\"issues\": [...], \"score\": 75}\n```\n\n## Publishing Checklist\n\n- [ ] `name` follows `namespace/category/tool` pattern\n- [ ] `version` set (semver)\n- [ ] `description` is clear and searchable\n- [ ] `inputSchema` / `outputSchema` defined\n- [ ] `from` uses pinned image version\n- [ ] `timeout` set appropriately\n- [ ] Tool tested locally with `enact run ./`\n\n## Troubleshooting\n\n```bash\nenact run ./ --args '{\"x\": \"y\"}' --verbose   # Verbose output\nenact run ./ --args '{}' --dry-run           # Preview command without running\nenact run ./ --args '{}' --debug             # Show parameter resolution details\nenact list                                   # List installed tools\n```\n\n**Common issues:**\n\n| Issue | Solution |\n|-------|----------|\n| \"Missing required parameter\" | Check your `required` array in inputSchema |\n| Parameters not substituting | Use `--debug` to see what values are being passed |\n| Optional params failing | Add `default` values or handle empty strings |\n| Build step fails | Use `--verbose` to see build output |\n| Base image not working | Use recommended images (see Base Image Requirements) |\n| Command exit code 2 | Check if command exists in the container |\n\n**Debugging build failures:**\n```bash\nenact run ./ --args '{}' --verbose   # See build output\nenact exec . \"which python\"          # Check if command exists\nenact exec . \"ls /workspace\"         # Check file mounts\nenact validate ./                    # Validate SKILL.md structure\n```\n\n**Multi-step builds:** Use YAML array syntax for clearer error reporting:\n```yaml\nbuild:\n  - apk add --no-cache ruby ruby-dev\n  - gem install bundler\n  - bundle install\n```\n";
 //# sourceMappingURL=tool-agents.d.ts.map

package/dist/commands/init/templates/tool-agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-agents.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/templates/tool-agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,kBAAkB,22JAsN9B,CAAC"}
+{"version":3,"file":"tool-agents.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/templates/tool-agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,kBAAkB,wsPAiS9B,CAAC"}

package/dist/commands/init/templates/tool-agents.js

@@ -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
@@ -25,7 +26,7 @@ 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 /work/main.py \${input}
+command: python /workspace/main.py \${input}
 timeout: 30s
 
 inputSchema:
@@ -72,24 +73,39 @@ Enact auto-quotes parameters. **Never manually quote:**
 
 \`\`\`yaml
 # WRONG - causes double-quoting
-command: python /work/main.py "\${input}"
+command: python /workspace/main.py "\${input}"
 
 # RIGHT - Enact handles quoting
-command: python /work/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:
@@ -130,15 +146,15 @@ build:
 **Rust:**
 \`\`\`yaml
 from: rust:1.83-slim
-build: rustc /work/main.rs -o /work/tool
-command: /work/tool \${input}
+build: rustc /workspace/main.rs -o /workspace/tool
+command: /workspace/tool \${input}
 \`\`\`
 
 **Go:**
 \`\`\`yaml
 from: golang:1.22-alpine
-build: cd /work && go build -o tool main.go
-command: /work/tool \${input}
+build: cd /workspace && go build -o tool main.go
+command: /workspace/tool \${input}
 \`\`\`
 
 **System packages:**
@@ -148,9 +164,40 @@ 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 \`/work\` as the working directory. All source files are copied there.
+Tools run in a container with \`/workspace\` as the working directory. All source files are copied there.
 
 ## Secrets
 
@@ -212,8 +259,36 @@ 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
 \`\`\`
 `;
 //# sourceMappingURL=tool-agents.js.map

package/dist/commands/init/templates/tool-agents.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-agents.js","sourceRoot":"","sources":["../../../../src/commands/init/templates/tool-agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsNjC,CAAC"}
+{"version":3,"file":"tool-agents.js","sourceRoot":"","sources":["../../../../src/commands/init/templates/tool-agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiSjC,CAAC"}

package/dist/commands/install/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/install/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA4BH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAonBzC;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyB9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/install/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA6BH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8nBzC;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyB9D"}