@powerhousedao/ph-clint-cli 0.1.0-dev.8 → 0.1.0-dev.80

package/dist/framework.gen.d.ts

@@ -6,23 +6,63 @@ export declare const registry: import("@powerhousedao/ph-clint").InferRegistry<r
     readonly version: 1;
     readonly reducer: import("document-model").Reducer<import("@powerhousedao/ph-clint-app").PhClintProjectPHState>;
     readonly actions: {
-        enableRoutine: (input: import("@powerhousedao/ph-clint-app").EnableRoutineInput) => import("@powerhousedao/ph-clint-app").EnableRoutineAction;
-        disableRoutine: (input: import("@powerhousedao/ph-clint-app").DisableRoutineInput) => import("@powerhousedao/ph-clint-app").DisableRoutineAction;
+        setAgentModel: (input: import("@powerhousedao/ph-clint-app").SetAgentModelInput) => import("@powerhousedao/ph-clint-app").SetAgentModelAction;
+        addAgentProfileRef: (input: import("@powerhousedao/ph-clint-app").AddAgentProfileRefInput) => import("@powerhousedao/ph-clint-app").AddAgentProfileRefAction;
+        removeAgentProfileRef: (input: import("@powerhousedao/ph-clint-app").RemoveAgentProfileRefInput) => import("@powerhousedao/ph-clint-app").RemoveAgentProfileRefAction;
+        reorderAgentProfileRefs: (input: import("@powerhousedao/ph-clint-app").ReorderAgentProfileRefsInput) => import("@powerhousedao/ph-clint-app").ReorderAgentProfileRefsAction;
+        addAgentSkill: (input: import("@powerhousedao/ph-clint-app").AddAgentSkillInput) => import("@powerhousedao/ph-clint-app").AddAgentSkillAction;
+        removeAgentSkill: (input: import("@powerhousedao/ph-clint-app").RemoveAgentSkillInput) => import("@powerhousedao/ph-clint-app").RemoveAgentSkillAction;
+        addAgentToolPattern: (input: import("@powerhousedao/ph-clint-app").AddAgentToolPatternInput) => import("@powerhousedao/ph-clint-app").AddAgentToolPatternAction;
+        removeAgentToolPattern: (input: import("@powerhousedao/ph-clint-app").RemoveAgentToolPatternInput) => import("@powerhousedao/ph-clint-app").RemoveAgentToolPatternAction;
+        addSubAgent: (input: import("@powerhousedao/ph-clint-app").AddSubAgentInput) => import("@powerhousedao/ph-clint-app").AddSubAgentAction;
+        removeSubAgent: (input: import("@powerhousedao/ph-clint-app").RemoveSubAgentInput) => import("@powerhousedao/ph-clint-app").RemoveSubAgentAction;
+        setSubAgentName: (input: import("@powerhousedao/ph-clint-app").SetSubAgentNameInput) => import("@powerhousedao/ph-clint-app").SetSubAgentNameAction;
+        setSubAgentDescription: (input: import("@powerhousedao/ph-clint-app").SetSubAgentDescriptionInput) => import("@powerhousedao/ph-clint-app").SetSubAgentDescriptionAction;
+        setMainAgentName: (input: import("@powerhousedao/ph-clint-app").SetMainAgentNameInput) => import("@powerhousedao/ph-clint-app").SetMainAgentNameAction;
+        setMainAgentDescription: (input: import("@powerhousedao/ph-clint-app").SetMainAgentDescriptionInput) => import("@powerhousedao/ph-clint-app").SetMainAgentDescriptionAction;
+        clearMainAgentDescription: (input: import("@powerhousedao/ph-clint-app").ClearMainAgentDescriptionInput) => import("@powerhousedao/ph-clint-app").ClearMainAgentDescriptionAction;
+        setMainAgentImage: (input: import("@powerhousedao/ph-clint-app").SetMainAgentImageInput) => import("@powerhousedao/ph-clint-app").SetMainAgentImageAction;
+        clearMainAgentImage: (input: import("@powerhousedao/ph-clint-app").ClearMainAgentImageInput) => import("@powerhousedao/ph-clint-app").ClearMainAgentImageAction;
+        addProfile: (input: import("@powerhousedao/ph-clint-app").AddProfileInput) => import("@powerhousedao/ph-clint-app").AddProfileAction;
+        updateProfile: (input: import("@powerhousedao/ph-clint-app").UpdateProfileInput) => import("@powerhousedao/ph-clint-app").UpdateProfileAction;
+        removeProfile: (input: import("@powerhousedao/ph-clint-app").RemoveProfileInput) => import("@powerhousedao/ph-clint-app").RemoveProfileAction;
+        reorderProfiles: (input: import("@powerhousedao/ph-clint-app").ReorderProfilesInput) => import("@powerhousedao/ph-clint-app").ReorderProfilesAction;
+        addModel: (input: import("@powerhousedao/ph-clint-app").AddModelInput) => import("@powerhousedao/ph-clint-app").AddModelAction;
+        removeModel: (input: import("@powerhousedao/ph-clint-app").RemoveModelInput) => import("@powerhousedao/ph-clint-app").RemoveModelAction;
         enableMastra: (input: import("@powerhousedao/ph-clint-app").EnableMastraInput) => import("@powerhousedao/ph-clint-app").EnableMastraAction;
         disableMastra: (input: import("@powerhousedao/ph-clint-app").DisableMastraInput) => import("@powerhousedao/ph-clint-app").DisableMastraAction;
-        enablePowerhouse: (input: import("@powerhousedao/ph-clint-app").EnablePowerhouseInput) => import("@powerhousedao/ph-clint-app").EnablePowerhouseAction;
-        setPowerhouseSwitchboard: (input: import("@powerhousedao/ph-clint-app").SetPowerhouseSwitchboardInput) => import("@powerhousedao/ph-clint-app").SetPowerhouseSwitchboardAction;
-        setPowerhouseConnect: (input: import("@powerhousedao/ph-clint-app").SetPowerhouseConnectInput) => import("@powerhousedao/ph-clint-app").SetPowerhouseConnectAction;
-        setPackageName: (input: import("@powerhousedao/ph-clint-app").SetPackageNameInput) => import("@powerhousedao/ph-clint-app").SetPackageNameAction;
-        clearBin: (input: import("@powerhousedao/ph-clint-app").ClearBinInput) => import("@powerhousedao/ph-clint-app").ClearBinAction;
-        setBin: (input: import("@powerhousedao/ph-clint-app").SetBinInput) => import("@powerhousedao/ph-clint-app").SetBinAction;
+        setEnableChat: (input: import("@powerhousedao/ph-clint-app").SetEnableChatInput) => import("@powerhousedao/ph-clint-app").SetEnableChatAction;
+        addSupportedResource: (input: import("@powerhousedao/ph-clint-app").AddSupportedResourceInput) => import("@powerhousedao/ph-clint-app").AddSupportedResourceAction;
+        removeSupportedResource: (input: import("@powerhousedao/ph-clint-app").RemoveSupportedResourceInput) => import("@powerhousedao/ph-clint-app").RemoveSupportedResourceAction;
+        setProxyEnabled: (input: import("@powerhousedao/ph-clint-app").SetProxyEnabledInput) => import("@powerhousedao/ph-clint-app").SetProxyEnabledAction;
+        setObservabilityEnabled: (input: import("@powerhousedao/ph-clint-app").SetObservabilityEnabledInput) => import("@powerhousedao/ph-clint-app").SetObservabilityEnabledAction;
+        importSpec: (input: import("@powerhousedao/ph-clint-app").ImportSpecInput) => import("@powerhousedao/ph-clint-app").ImportSpecAction;
+        bumpVersion: (input: import("@powerhousedao/ph-clint-app").BumpVersionInput) => import("@powerhousedao/ph-clint-app").BumpVersionAction;
+        publishDev: (input: import("@powerhousedao/ph-clint-app").PublishDevInput) => import("@powerhousedao/ph-clint-app").PublishDevAction;
+        publishStaging: (input: import("@powerhousedao/ph-clint-app").PublishStagingInput) => import("@powerhousedao/ph-clint-app").PublishStagingAction;
+        publishProduction: (input: import("@powerhousedao/ph-clint-app").PublishProductionInput) => import("@powerhousedao/ph-clint-app").PublishProductionAction;
+        setPublishStatus: (input: import("@powerhousedao/ph-clint-app").SetPublishStatusInput) => import("@powerhousedao/ph-clint-app").SetPublishStatusAction;
+        addExternalSkill: (input: import("@powerhousedao/ph-clint-app").AddExternalSkillInput) => import("@powerhousedao/ph-clint-app").AddExternalSkillAction;
+        removeExternalSkill: (input: import("@powerhousedao/ph-clint-app").RemoveExternalSkillInput) => import("@powerhousedao/ph-clint-app").RemoveExternalSkillAction;
+        setExternalSkillName: (input: import("@powerhousedao/ph-clint-app").SetExternalSkillNameInput) => import("@powerhousedao/ph-clint-app").SetExternalSkillNameAction;
+        setExternalSkillGithubUrl: (input: import("@powerhousedao/ph-clint-app").SetExternalSkillGithubUrlInput) => import("@powerhousedao/ph-clint-app").SetExternalSkillGithubUrlAction;
+        addPowerhousePackage: (input: import("@powerhousedao/ph-clint-app").AddPowerhousePackageInput) => import("@powerhousedao/ph-clint-app").AddPowerhousePackageAction;
+        removePowerhousePackage: (input: import("@powerhousedao/ph-clint-app").RemovePowerhousePackageInput) => import("@powerhousedao/ph-clint-app").RemovePowerhousePackageAction;
+        addPackageDocumentType: (input: import("@powerhousedao/ph-clint-app").AddPackageDocumentTypeInput) => import("@powerhousedao/ph-clint-app").AddPackageDocumentTypeAction;
+        removePackageDocumentType: (input: import("@powerhousedao/ph-clint-app").RemovePackageDocumentTypeInput) => import("@powerhousedao/ph-clint-app").RemovePackageDocumentTypeAction;
+        setPackageVersion: (input: import("@powerhousedao/ph-clint-app").SetPackageVersionInput) => import("@powerhousedao/ph-clint-app").SetPackageVersionAction;
+        enableRoutine: (input: import("@powerhousedao/ph-clint-app").EnableRoutineInput) => import("@powerhousedao/ph-clint-app").EnableRoutineAction;
+        disableRoutine: (input: import("@powerhousedao/ph-clint-app").DisableRoutineInput) => import("@powerhousedao/ph-clint-app").DisableRoutineAction;
+        setPowerhouseLevel: (input: import("@powerhousedao/ph-clint-app").SetPowerhouseLevelInput) => import("@powerhousedao/ph-clint-app").SetPowerhouseLevelAction;
         setDescription: (input: import("@powerhousedao/ph-clint-app").SetDescriptionInput) => import("@powerhousedao/ph-clint-app").SetDescriptionAction;
         setVersion: (input: import("@powerhousedao/ph-clint-app").SetVersionInput) => import("@powerhousedao/ph-clint-app").SetVersionAction;
-        clearScope: (input: import("@powerhousedao/ph-clint-app").ClearScopeInput) => import("@powerhousedao/ph-clint-app").ClearScopeAction;
-        setScope: (input: import("@powerhousedao/ph-clint-app").SetScopeInput) => import("@powerhousedao/ph-clint-app").SetScopeAction;
+        setPackageIdentifier: (input: import("@powerhousedao/ph-clint-app").SetPackageIdentifierInput) => import("@powerhousedao/ph-clint-app").SetPackageIdentifierAction;
         setName: (name: string | {
             name: string;
         }) => import("document-model").SetNameAction;
+        setPreferredEditor: (input: string | null | {
+            preferredEditor: string | null;
+        }) => import("document-model").SetPreferredEditorAction;
         undo: (count?: number, scope?: string) => import("document-model").UndoAction;
         redo: (count?: number, scope?: string) => import("document-model").RedoAction;
         prune: (start?: number, end?: number, scope?: string) => import("document-model").SchemaPruneAction;

package/dist/framework.js

@@ -23,12 +23,8 @@ export const configSchema = z.object({
         .describe('Port reserved for the impl project (Service B) `pnpm dev`'),
     phVersion: z
         .string()
-        .default('6.0.0-dev.170')
+        .default('latest')
         .describe('Pinned Powerhouse version used when emitting a new impl project'),
-    projectDocumentId: z
-        .string()
-        .optional()
-        .describe('ID of the powerhouse/ph-clint-project document that drives codegen (set on first regen; edit to switch projects)'),
 });
 export const secretsSchema = z.object({
     apiKey: z.string().optional().describe('Anthropic API key'),

package/{prompts/agent-profiles/AgentBase.md → dist/gen/agent-profiles/PhClintDevAgent.md}

@@ -1,6 +1,6 @@
 # Agent Base System Prompt
 
-You are {{agentName}}, an agent available through the {{cliName}} CLI.
+You are PhClintDevAgent, an agent available through the  CLI.
 
 ## Capabilities
 

package/dist/gen/skills/cli-setup/.cli-docs.md

@@ -0,0 +1,135 @@
+## API Reference: CLI Setup
+
+### `defineCli<TSchema, TSecrets>(options): Cli`
+
+Factory function that creates a CLI from a declarative options object. Two generic type parameters:
+
+- `TSchema extends z.ZodType` — config schema type (defaults to `Record<string, unknown>`)
+- `TSecrets extends z.ZodType` — secrets schema type (defaults to `Record<string, unknown>`)
+
+### `CliOptions<TSchema, TSecrets>` Interface
+
+```typescript
+interface CliOptions<TSchema, TSecrets> {
+  name: string;                          // CLI name (kebab-case, used for config files and env var prefix)
+  version: string;                       // Semantic version (shown in --version)
+  root?: string;                         // Absolute path to package root (resolves sibling packages)
+  description: Resolvable<string, Config>; // Static string or function of ({ config, workdir })
+  commands: Command<any, any, any>[];    // Array of command definitions
+  configSchema?: TSchema;                // Zod schema for user-facing config
+  secretsSchema?: TSecrets;              // Zod schema for sensitive config (API keys, tokens)
+  interactive?: InteractiveConfig<Config>; // REPL configuration
+  triggers?: Trigger<any, any, any>[];   // Routine loop triggers
+  routine?: RoutineConfig;               // Routine loop timing & project scanner
+  services?: ServiceDefinition<Config>[]; // Background service definitions
+  events?: Record<string, (data: any, log: Logger) => void>; // Event handlers
+  workdir?: string;                      // Implementation-level workdir override (hides --workdir flag)
+  configDefaults?: Record<string, unknown>; // Layer 5 config defaults
+  prompts?: PromptsConfig;               // Agent skills & profiles
+}
+```
+
+### `InteractiveConfig<TConfig>` Interface
+
+```typescript
+interface InteractiveConfig<TConfig> {
+  welcome: Resolvable<string, TConfig>;  // Welcome message (static or dynamic)
+  outputWindow?: number;                 // Trailing output lines in REPL (default: 6)
+}
+```
+
+### `Resolvable<T, TConfig>` Type
+
+```typescript
+type Resolvable<T, TConfig> = T | ((ctx: { workdir: string; config: TConfig }) => T);
+```
+
+Allows static values OR dynamic computation based on resolved workdir and config.
+
+### `Cli` Object Interface
+
+Methods available on the object returned by `defineCli()`:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `run` | `(argv: string[], options?: RunOptions) => Promise<void>` | Main entry point — parse args, dispatch command or start REPL |
+| `bootstrap` | `(opts?: BootstrapOptions) => Promise<BootstrapResult>` | Initialize runtime without dispatch — for programmatic access |
+| `execute` | `(commandId, args, context?) => Promise<unknown>` | Execute a command directly (programmatic use) |
+| `parseArgs` | `(commandId, argv) => Record<string, unknown>` | Parse CLI argv for a specific command |
+| `getCommand` | `(id: string) => Command \| undefined` | Look up a registered command |
+| `listCommands` | `() => Command[]` | List all registered commands |
+| `generateHelp` | `() => string` | Generate CLI help text |
+| `generateCommandHelp` | `(commandId: string) => string` | Generate help for a specific command |
+| `generateCompletion` | `(shell: string) => string` | Generate shell completion script (bash/zsh/fish) |
+| `configEnvVars` | `() => ConfigEnvVar[]` | List config env var mappings |
+| `getMetadata` | `() => CliMetadata` | JSON-serializable CLI metadata |
+| `configureAgent` | `(loader: AgentLoader<any>) => void` | Set the agent factory (lazy-loaded) |
+| `configureReactor` | `(config: ReactorConfiguration) => void` | Set the reactor configuration (lazy-loaded) |
+
+Properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | CLI name |
+| `version` | `string` | CLI version |
+| `description` | `string` | CLI description |
+| `hasAgent` | `boolean` | True when `configureAgent()` has been called |
+| `hasReactor` | `boolean` | True when `configureReactor()` has been called |
+
+### `RunOptions` Interface
+
+```typescript
+interface RunOptions {
+  exit?: (code: number) => void;         // Override process.exit (for testing)
+  stdout?: (message: string) => void;    // Capture stdout
+  stderr?: (message: string) => void;    // Capture stderr
+  interactiveInput?: AsyncIterable<string>; // Headless REPL input (for testing)
+  resume?: string;                       // Resume agent conversation by thread ID
+  workdir?: string;                      // Override workdir (for testing)
+  configFile?: string;                   // --config flag value
+  logLevel?: LogLevel;                   // Override log verbosity (default: 'info')
+}
+```
+
+### `BootstrapOptions` & `BootstrapResult`
+
+```typescript
+interface BootstrapOptions {
+  workdir?: string;        // Explicit workdir (skips flag/cwd logic)
+  configFile?: string;     // Config file override
+  logLevel?: LogLevel;     // Log level (default: 'info')
+  stdout?: (text: string) => void;
+  stderr?: (text: string) => void;
+}
+
+interface BootstrapResult {
+  workdir: string;
+  config: Record<string, unknown>;
+  context: CommandContext;
+  getAgent(): Promise<AgentProvider | undefined>;
+  get mastraAgent(): Promise<unknown | undefined>;
+}
+```
+
+### Built-in Commands (Auto-Injected)
+
+| Command ID | Condition | Purpose |
+|-----------|-----------|---------|
+| `cli-docs` | Always | Show CLI help (also usable as agent tool) |
+| `config` | When `configSchema` provided | View/modify configuration settings |
+| `{service-id}-start` | Per service definition | Start a background service |
+| `{service-id}-stop` | Per service definition | Stop a running service |
+| `{service-id}-restart` | Per service definition | Restart a service |
+| `{service-id}-ps` | Per service definition | Show service status |
+| `{service-id}-logs` | Per service definition | Tail service logs |
+| `{service-id}-manage` | Per service definition | Interactive management (REPL only) |
+| `{service-id}-ls` | Per service + projectScanner | List discovered projects |
+
+### `readPackageInfo(importMetaUrl)`
+
+Utility to read name and version from the nearest `package.json`:
+
+```typescript
+import { readPackageInfo } from '@powerhousedao/ph-clint';
+const { name, version } = readPackageInfo(import.meta.url);
+```

package/dist/gen/skills/cli-setup/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: cli-setup
+description: "Set up a new CLI with defineCli, config schemas, entrypoint, and interactive mode"
+metadata:
+  author: Powerhouse
+  version: "1.0.0"
+---
+
+=== BEGIN SKILL BRIEFING ===
+
+IMPORTANT: Don't take any action yet. You will be guided through your tasks after the briefing(s). Just process and confirm your understanding.
+
+# CLI Setup - Skill Preamble
+
+With this skill, you can scaffold or extend a `defineCli()` configuration — the composition root that wires commands, config, services, triggers, and integrations into a single CLI runtime. A single `defineCli()` call produces a CLI that works in command mode (`mycli cmd --arg val`), interactive REPL mode (`/cmd --arg val`), and as an MCP server — all from the same code.
+
+## Core Principles
+
+### defineCli Is Declarative
+
+You describe _what_ the CLI has — the framework wires it up. The order of options doesn't matter, but understanding what triggers what does:
+
+- `configSchema` present → auto-injects a `config` command for viewing/modifying settings
+- `secretsSchema` present → fields merge into configSchema internally, but are censored in output
+- `services` present → auto-injects per-service management commands (`{id}-start`, `{id}-stop`, etc.)
+- `interactive` present → enables the `-i` flag for REPL mode
+- `triggers` present → enables routine loop
+- `cli-docs` command is always auto-injected (CLI help for the agent)
+
+### Resolvable Values
+
+`description` and `interactive.welcome` accept either a static string or a function `({ config, workdir }) => string`. Use functions when the message depends on runtime state — e.g., showing "demo mode" vs "LLM mode" based on whether an API key is configured.
+
+### The Cli Object
+
+`defineCli()` returns a `Cli` object — the public API with methods for running, testing, introspection, and metadata. The standard entry point is `cli.run(process.argv)`. For programmatic access (e.g., codegen scripts), use `cli.bootstrap()` which resolves workdir, config, and context without entering the dispatch loop.
+
+### Two Interaction Modes
+
+1. **Command mode** (headless): Execute one subcommand, then exit. Triggered by `mycli cmd --flag val`.
+2. **Interactive REPL mode**: Persistent session with `/command` syntax and bare text for the default subcommand (typically the agent). Triggered by `mycli -i` or when keep-alive features are active (routine loop, API server).
+
+### 6-Layer Config Resolution
+
+Config values are resolved in this priority order (highest wins):
+1. `--config <file>` flag
+2. Environment variables: `{CLI_NAME}_{UPPER_SNAKE_FIELD}`
+3. Local config: `{workdir}/.ph/{cliName}.config.local.json`
+4. User config: `~/.ph/{cliName}.config.user.json`
+5. Implementation defaults: `configDefaults` in CliOptions
+6. Zod schema `.default()` values
+
+### Config vs Secrets
+
+- `configSchema` — user-facing settings (model name, ports, feature flags). Shown in `config` command output.
+- `secretsSchema` — sensitive values (API keys, tokens). Merged into configSchema internally but censored as `***` in output unless `--revealSecrets` is used.
+
+Put API keys and tokens in `secretsSchema`, not `configSchema`.
+
+### configDefaults vs Schema Defaults
+
+- `.default(value)` in the Zod schema → layer 6, the fallback when nothing else is configured
+- `configDefaults` in CliOptions → layer 5, implementation-level overrides that sit above schema defaults but below user/local config
+
+Use schema `.default()` for universal sensible defaults. Use `configDefaults` for implementation-specific overrides that differ from the general-purpose default.
+
+### Entry Point Convention
+
+The CLI entry point is a TypeScript file with a Node.js shebang:
+
+```typescript
+#!/usr/bin/env node
+import { defineCli } from '@powerhousedao/ph-clint';
+// ... imports ...
+const cli = defineCli({ /* options */ });
+cli.run(process.argv);
+```
+
+The `package.json` needs a `"bin"` field pointing to the compiled output and `"type": "module"` for ESM.
+
+## Common Pitfalls
+
+- **Forgetting `version`** — Commander needs it for the `--version` flag; omitting it breaks help output
+- **Putting secrets in `configSchema`** — they show up in `config` command output and metadata, exposing sensitive values
+- **Not setting `interactive.welcome`** — REPL starts with no context, confusing the user
+- **Using `configDefaults` for universal defaults** — use `.default()` in the schema instead; `configDefaults` is for implementation-level overrides only
+- **Calling `configureAgent()` inside `defineCli()`** — it's a method on the returned `Cli` object, called after definition
+- **Forgetting `"type": "module"` in package.json** — ESM imports fail at runtime
+- **Not exporting the `cli` object** — other files (e.g., `mastra/index.ts`) may need it for `cli.bootstrap()`
+
+## When to Use `createTypes()`
+
+For projects with a config schema, use the typed factory to get automatic config typing in all commands:
+
+```typescript
+import { createTypes } from '@powerhousedao/ph-clint';
+const { defineCommand, defineTrigger } = createTypes({ configSchema });
+// context.config is now fully typed in every command
+```
+
+## Codegen-Managed Projects
+
+In ph-clint-cli projects, `clint-project-init` generates the initial scaffold including `cli.ts` with `@clint:begin`/`@clint:end` marker regions. The codegen system:
+
+- **Generates `cli.ts`** with marker regions for imports, commands, services, triggers, prompts, events, interactive, reactor, and mastra
+- **Generates `framework.gen.ts`** (codegen-owned) with the document registry — regenerated when the spec's `documentTypes` change
+- **Emits `framework.ts`** once (user-owned) with `configSchema`, `secretsSchema`, and `createTypes()` — never overwritten after creation
+
+**The agent never hand-edits marker regions in `cli.ts`.** To add or change CLI features:
+
+1. Update `project-spec.json` to declare the new structure
+2. Run `clint-project-regen` to regenerate the marker regions
+3. Run `clint-project-build` to verify
+
+User-owned code outside markers (`configSchema`, `secretsSchema`, `CLI_NAME`) is preserved across regens. User-owned files (`framework.ts`, `src/commands/*.ts`, `src/services/*.ts`, `src/triggers/*.ts`) are never overwritten.
+
+=== END OF SKILL BRIEFING ===
+
+## Specific tasks
+
+* **Assess Cli Needs** [references/00.assess-cli-needs.md](references/00.assess-cli-needs.md)
+* **Define Config Schema** [references/01.define-config-schema.md](references/01.define-config-schema.md)
+* **Wire Cli** [references/02.wire-cli.md](references/02.wire-cli.md)
+* **Add Entrypoint** [references/03.add-entrypoint.md](references/03.add-entrypoint.md)
+* **Expected Outcome** [references/expected-outcome.md](references/expected-outcome.md)

package/dist/gen/skills/cli-setup/references/00.assess-cli-needs.md

@@ -0,0 +1,53 @@
+# Phase 0: Assess CLI Needs
+
+Before writing any code, determine which features the CLI requires.
+
+## Steps
+
+### 1. Name the CLI
+
+Choose a kebab-case name. This name is used for:
+- Config file paths: `{workdir}/.ph/{name}.config.local.json`
+- Environment variable prefix: `{NAME}_*` (UPPER_SNAKE_CASE)
+- Package `"bin"` field and executable name
+
+### 2. Determine version sourcing
+
+Choose one:
+- **Hardcoded**: `version: '1.0.0'`
+- **From package.json**: `const { version } = readPackageInfo(import.meta.url)`
+
+### 3. Feature checklist
+
+For each feature, determine if the CLI needs it:
+
+- [ ] **Custom config?** → needs `configSchema` (Zod object)
+- [ ] **Sensitive config (API keys, tokens)?** → needs `secretsSchema` (Zod object)
+- [ ] **Interactive REPL?** → needs `interactive` with `welcome` message
+- [ ] **Background services?** → needs `services` array of `defineService()` definitions
+- [ ] **Automated triggers?** → needs `triggers` array + `routine` config
+- [ ] **AI agent?** → needs `cli.configureAgent(loader)` after `defineCli()`
+- [ ] **Skill templates?** → needs `prompts` config with `artifacts`, `agents`, `skills`
+- [ ] **Powerhouse documents?** → needs `cli.configureReactor(config)` after `defineCli()`
+- [ ] **Service lifecycle events?** → needs `events` handlers
+- [ ] **Implementation-level workdir override?** → needs `workdir` option (hides `--workdir` flag)
+
+### 4. List commands to register
+
+Enumerate all commands that will be passed to the `commands` array. These should already be defined using `defineCommand()` (see the `command-definition` skill). Note which ones need agent-compatible `{ text, data }` returns.
+
+### 5. Detect codegen vs manual project
+
+For existing projects, check if `cli.ts` already has `@clint:begin` marker regions:
+- **Codegen-managed**: Markers present — update `project-spec.json` and run `clint-project-regen`. Never hand-edit marker regions.
+- **Manual**: No markers — edit `defineCli()` directly as a regular TypeScript file.
+
+For new projects, prefer using `clint-project-init` to generate the scaffold with markers.
+
+### 6. Determine config field names
+
+For each config/secret field, verify the auto-generated env var name is sensible:
+- Field `apiKey` on CLI `mycli` → env var `MYCLI_API_KEY`
+- Field `connectPort` on CLI `vetra` → env var `VETRA_CONNECT_PORT`
+
+If a name would be confusing, consider renaming the field.

package/dist/gen/skills/cli-setup/references/01.define-config-schema.md

@@ -0,0 +1,78 @@
+# Phase 1: Define Config and Secrets Schemas
+
+Design and wire the configuration layer. Skip this phase if the CLI needs no configuration.
+
+## Steps
+
+### 1. Define configSchema
+
+Create a Zod object schema for user-facing settings:
+
+```typescript
+import { z } from 'zod';
+
+export const configSchema = z.object({
+  model: z.string().default('anthropic/claude-sonnet-4-5').describe('LLM model to use'),
+  port: z.number().default(4001).describe('Server port'),
+  verbose: z.boolean().default(false).describe('Enable verbose output'),
+});
+```
+
+Rules:
+- Every field MUST have `.describe('...')` — it appears in `config` command output, `--help`, and env var listings
+- Use `.default(value)` for fields with sensible defaults
+- Use `.optional()` only for truly optional fields with no default
+- Prefer specific types: `z.enum([...])` for constrained choices, `z.number()` for ports
+
+### 2. Define secretsSchema
+
+Create a separate Zod object schema for sensitive values:
+
+```typescript
+export const secretsSchema = z.object({
+  apiKey: z.string().optional().describe('LLM API key'),
+  dbToken: z.string().optional().describe('Database access token'),
+});
+```
+
+Rules:
+- Secrets are almost always `.optional()` — the CLI should work without them (possibly in a degraded mode)
+- These fields are merged into configSchema internally but censored in output
+- They follow the same env var naming: `{CLI_NAME}_{FIELD}`
+
+### 3. Set configDefaults (if needed)
+
+Use `configDefaults` in `defineCli()` for implementation-specific overrides that differ from the schema defaults:
+
+```typescript
+defineCli({
+  configSchema,
+  configDefaults: {
+    port: 8080, // This implementation uses 8080, not the schema default of 4001
+  },
+});
+```
+
+This is layer 5 — above schema `.default()` but below user/local config files.
+
+### 4. Use createTypes for typed commands
+
+If you have a configSchema, create a typed factory so all commands get typed `context.config`:
+
+```typescript
+// framework.ts
+import { createTypes } from '@powerhousedao/ph-clint';
+import { configSchema, secretsSchema } from './config.js';
+
+export const { defineCommand, defineTrigger } = createTypes({ configSchema, secretsSchema });
+export { configSchema, secretsSchema };
+```
+
+Then import `defineCommand` from `./framework.js` instead of `ph-clint` in all command files.
+
+### 5. Verify env var names
+
+Run through each field and check the auto-generated env var name:
+- `{CLI_NAME}` is the CLI name uppercased with hyphens replaced by underscores
+- Field keys are converted to UPPER_SNAKE_CASE
+- Example: CLI `my-app`, field `connectPort` → `MY_APP_CONNECT_PORT`

package/dist/gen/skills/cli-setup/references/02.wire-cli.md

@@ -0,0 +1,141 @@
+# Phase 2: Wire the defineCli Call
+
+Compose the `defineCli()` call with all the options determined in Phase 0.
+
+## Steps
+
+### 1. Assemble the core options
+
+```typescript
+import { defineCli } from '@powerhousedao/ph-clint';
+import { configSchema, secretsSchema } from './config.js';
+import { myCommand, otherCommand } from './commands/index.js';
+
+export const cli = defineCli({
+  name: 'my-app',
+  version: '1.0.0',
+  description: 'My application CLI',
+  commands: [myCommand, otherCommand],
+  configSchema,
+  secretsSchema,
+});
+```
+
+Always export the `cli` object — other files may need it (e.g., `mastra/index.ts` for `cli.bootstrap()`).
+
+### 2. Configure interactive mode
+
+Add an `interactive` block if the CLI supports REPL mode:
+
+```typescript
+interactive: {
+  welcome: 'My App CLI — type /help for commands',
+},
+```
+
+For dynamic welcome messages that depend on config:
+
+```typescript
+interactive: {
+  welcome: ({ config, workdir }) => {
+    const mode = config.apiKey ? config.model : 'demo mode';
+    return `My App (${mode})\nWorkdir: ${workdir}`;
+  },
+},
+```
+
+### 3. Add services (if needed)
+
+```typescript
+import { myService } from './services/my-service.js';
+
+defineCli({
+  // ...
+  services: [myService],
+});
+```
+
+This auto-injects `my-service-start`, `my-service-stop`, `my-service-restart`, `my-service-ps`, `my-service-logs`, and `my-service-manage` commands.
+
+### 4. Add event handlers (if needed)
+
+Wire lifecycle events for services or custom events:
+
+```typescript
+events: {
+  'service:ready': (event, log) => {
+    log.info(`${event.name} is ready`);
+  },
+  'service:failed': (event, log) => {
+    log.error(`${event.name} failed: ${event.error}`);
+  },
+  'service:stopped': (event, log) => {
+    log.info(`${event.name} stopped`);
+  },
+},
+```
+
+Available service events: `service:pattern-matched`, `service:ready`, `service:failed`, `service:restarting`, `service:stopped`. Each receives `(event, log)` where `log` is a structured Logger.
+
+### 5. Add prompts config (if skills are needed)
+
+```typescript
+import path from 'node:path';
+
+prompts: {
+  artifacts: [path.join(CLI_ROOT, 'gen', 'skills')],
+  agents: {
+    'my-agent': {
+      name: 'MyAgent',
+      sections: ['AgentBase.md', 'MySpecialization.md'],
+      skills: ['skill-one', 'skill-two'],
+    },
+  },
+  skills: {
+    'skill-one': {
+      description: 'Description of skill one',
+      inputSchema: z.object({
+        mode: z.enum(['expert', 'discovery']).default('expert').describe('Interaction mode'),
+      }),
+      instructionTemplate: 'Use your {{skillId}} skill in {{mode}} mode for: {{prompt}}',
+    },
+  },
+},
+```
+
+### 6. Call configureAgent / configureReactor (if needed)
+
+These are called AFTER `defineCli()` — they are methods on the returned `Cli` object:
+
+```typescript
+export const cli = defineCli({ /* ... */ });
+
+// Agent integration (Mastra)
+cli.configureAgent(createAgent);
+
+// Reactor integration (Powerhouse)
+cli.configureReactor({
+  registry: [/* document models */],
+  // ...
+});
+```
+
+Both are lazy-loaded — the actual agent/reactor is only created when first accessed.
+
+### 7. Codegen projects: use spec + regen
+
+In codegen-managed projects, do NOT manually edit `cli.ts` marker regions. Instead:
+
+1. Update `project-spec.json` with the new features (commands, services, triggers, integrations)
+2. Run `clint-project-regen` to regenerate marker regions
+3. Edit user-owned files directly: `framework.ts` for config/secrets schemas, `src/commands/*.ts` for commands, etc.
+
+Core options outside markers (`name`, `version`, `description`, `configSchema`, `secretsSchema`) are in the user-editable zone — edit those directly in `cli.ts`.
+
+### 8. Verify built-in commands
+
+After wiring, confirm these commands will be auto-injected:
+- `cli-docs` — always present
+- `config` — present if `configSchema` was provided
+- Service commands — present for each entry in `services`
+- Skill commands — present for each entry in `prompts.skills`