CHANGE: Changed the default compile output folder defaults and updated documentation

Author: PredictabilityAtScale

README.md

@@ -187,7 +187,7 @@ Direct adapter rendering also accepts `environment` and `tier` selectors. This i
 ```typescript
 import type { ResolvedPromptAsset } from 'promptopskit';
 import { openaiAdapter } from 'promptopskit/openai';
-import compiledPrompt from './dist/prompts/summarizePullRequest.mjs';
+import compiledPrompt from './.generated-prompts/esm/summarizePullRequest.mjs';
 
 const prompt = compiledPrompt as ResolvedPromptAsset;
 
@@ -217,7 +217,7 @@ const request = await openaiAdapter.renderPrompt(
   {
     path: 'summarizePullRequest',
     sourceDir: path.join(process.cwd(), 'prompts'),
-    compiledDir: path.join(process.cwd(), 'output-json'),
+    compiledDir: path.join(process.cwd(), '.generated-prompts', 'json'),
   },
   {
     environment: 'dev',
@@ -386,7 +386,7 @@ promptopskit skill
 promptopskit validate <dir> [--strict]
 
 # Compile .md → JSON/ESM artifacts
-promptopskit compile <src> <out> [--dry-run] [--format json|esm] [--no-clean]
+promptopskit compile [src] [out] [--dry-run] [--format json|esm] [--no-clean]
 
 # Render a prompt preview (auto-loads .test.yaml sidecar)
 promptopskit render <file> [--env <name>] [--tier <name>] [--vars <file>] [--json]

SKILL.md

@@ -258,7 +258,7 @@ import { createPromptOpsKit } from 'promptopskit';
 
 const kit = createPromptOpsKit({
   sourceDir: './prompts',
-  compiledDir: './dist/prompts',
+  compiledDir: './.generated-prompts/json',
   warnings: {
     contextSize: process.env.NODE_ENV === 'production' ? 'off' : 'console-and-result',
   },
@@ -289,7 +289,7 @@ const request = await openaiAdapter.renderPrompt(
   {
     path: 'support/reply',
     sourceDir: path.join(process.cwd(), 'prompts'),
-    compiledDir: path.join(process.cwd(), 'dist/prompts'),
+    compiledDir: path.join(process.cwd(), '.generated-prompts', 'json'),
   },
   {
     environment: 'production',
@@ -311,7 +311,7 @@ const request = await openaiAdapter.renderPrompt(
 ```typescript
 import type { ResolvedPromptAsset } from 'promptopskit';
 import { openaiAdapter } from 'promptopskit/openai';
-import compiledPrompt from './dist/prompts/support/reply.mjs';
+import compiledPrompt from './.generated-prompts/esm/support/reply.mjs';
 
 const prompt = compiledPrompt as ResolvedPromptAsset;
 
@@ -344,13 +344,13 @@ Prompts should usually be validated and compiled as part of the normal build pip
 {
   "scripts": {
     "validate:prompts": "promptopskit validate ./prompts --strict",
-    "build:prompts": "promptopskit compile ./prompts ./dist/prompts --format json",
+    "build:prompts": "promptopskit compile",
     "build": "npm run validate:prompts && npm run build:prompts && tsup"
   }
 }
 ```
 
-Use `--format json` for server-side Node usage where prompts are loaded from disk. Use `--format esm` when prompts need to be imported into a bundle.
+`promptopskit compile` defaults to JSON output in `./.generated-prompts/json`, which matches runtime `compiledDir` loading. Use `promptopskit compile --format esm` when prompts need to be imported into a bundle; those artifacts default to `./.generated-prompts/esm`.
 
 ### Build strategy by environment
 
@@ -362,7 +362,7 @@ Use `--format json` for server-side Node usage where prompts are loaded from dis
 
 - Add `validate:prompts` before `build:prompts` so schema or variable mistakes fail fast
 - Treat compiled artifacts as build outputs, not the source of truth
-- Keep prompt source in `./prompts` and compiled output in a generated directory such as `./dist/prompts` or `./src/generated/prompts`
+- Keep prompt source in `./prompts`; use `./.generated-prompts/json` as the default server output and `./.generated-prompts/esm` for imported client artifacts unless a project-specific build layout needs something else
 - If using `createPromptOpsKit` in `auto` mode, point both `sourceDir` and `compiledDir` at those directories so local development can fall back to source when artifacts are stale or missing
 
 ### Typical server-side setup
@@ -372,7 +372,7 @@ import { createPromptOpsKit } from 'promptopskit';
 
 export const prompts = createPromptOpsKit({
   sourceDir: './prompts',
-  compiledDir: './dist/prompts',
+  compiledDir: './.generated-prompts/json',
   mode: 'auto',
 });
 ```
@@ -432,7 +432,7 @@ Hello {{ name }}
 |---------|-------------|
 | `promptopskit init [dir]` | Scaffold a prompts directory with starter files (including `defaults.md`) |
 | `promptopskit validate <dir>` | Validate all prompt files in a directory |
-| `promptopskit compile <src> <out>` | Compile `.md` prompts to JSON or ESM artifacts |
+| `promptopskit compile [src] [out]` | Compile `.md` prompts to JSON or ESM artifacts |
 | `promptopskit render <file>` | Render a prompt preview |
 | `promptopskit inspect <file>` | Print the normalized prompt asset |
 

docs/api-reference.md

@@ -9,7 +9,7 @@ import { createPromptOpsKit } from 'promptopskit';
 
 const kit = createPromptOpsKit({
   sourceDir: './prompts',
-  compiledDir: './dist/prompts',
+  compiledDir: './.generated-prompts/json',
   mode: 'auto',
   cache: true,
   warnings: {

docs/cli.md

@@ -65,19 +65,23 @@ Output per file:
 Compile `.md` prompt files to JSON or ESM artifacts.
 
 ```bash
-promptopskit compile <src> <out> [--dry-run] [--format json|esm] [--no-clean]
+promptopskit compile [src] [out] [--dry-run] [--format json|esm] [--no-clean]
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `<src>` | — | Source directory (required) |
-| `<out>` | — | Output directory (required) |
+| `<src>` | `./prompts` | Source directory |
+| `<out>` | `./.generated-prompts/json` | Output directory |
+| `--source`, `-s` | — | Explicit source directory override |
+| `--output`, `-o` | — | Explicit output directory override |
 | `--format` | `json` | Output format: `json` or `esm` |
 | `--dry-run` | — | Show what would be compiled without writing |
 | `--no-clean` | — | Don't clear the output directory before compiling |
 
 Includes are resolved during compilation so compiled artifacts are self-sufficient. The output directory is cleared by default before compiling (unless `--no-clean` is set).
 
+If you omit `<out>`, the CLI chooses `./.generated-prompts/json` for `json` and `./.generated-prompts/esm` for `esm`.
+
 `defaults.md` files are treated as configuration inputs and are not compiled as standalone prompts.
 
 JSON format produces `.json` files:

docs/getting-started.md

@@ -119,15 +119,15 @@ This checks all `.md` files for schema errors, unknown front matter keys (with "
 ## Compile for production
 
 ```bash
-npx promptopskit compile ./prompts ./dist/prompts
+npx promptopskit compile
 ```
 
 Pre-compiles `.md` files to JSON (or ESM) artifacts so deployments skip parsing entirely. Add to your build scripts:
 
 ```json
 {
   "scripts": {
-    "build:prompts": "promptopskit compile ./prompts ./dist/prompts"
+    "build:prompts": "promptopskit compile"
   }
 }
 ```

docs/providers.md

@@ -68,7 +68,7 @@ const request = await openaiAdapter.renderPrompt(
   {
     path: 'summarizePullRequest',
     sourceDir: path.join(process.cwd(), 'prompts'),
-    compiledDir: path.join(process.cwd(), 'output-json'),
+    compiledDir: path.join(process.cwd(), '.generated-prompts', 'json'),
   },
   {
     environment: 'dev',
@@ -86,7 +86,7 @@ The top-level `promptopskit` runtime is Node-oriented. It supports prompt loadin
 
 For browser or client-side code:
 
-- Precompile prompts to ESM with `promptopskit compile ./prompts ./dist/prompts --format esm` and import the generated artifact, or inline a small `ResolvedPromptAsset`.
+- Precompile prompts to ESM with `promptopskit compile --format esm` and import the generated artifact from `./.generated-prompts/esm`, or inline a small `ResolvedPromptAsset`.
 - Pass `environment` and `tier` directly to `adapter.validate()` and `adapter.render()` when you need overrides on the client side.
 - Avoid `renderPrompt()` in browser-only code because resolving prompt files from disk is Node-oriented.
 - Keep provider credentials on the server. In production, use the rendered request body with a server endpoint, server action, or edge function that owns the API key.

src/cli/commands/compile.ts

@@ -4,11 +4,13 @@ import { loadPromptFile } from '../../parser/index.js';
 import { resolveIncludes } from '../../composition/index.js';
 
 const HELP = `
-promptopskit compile <sourceDir> <outputDir> [options]
+promptopskit compile [sourceDir] [outputDir] [options]
 
-Compile .md prompt files to JSON artifacts.
+Compile .md prompt files to JSON or ESM artifacts.
 
 Options:
+  --source, -s   Source directory (default: ./prompts)
+  --output, -o   Output directory (default: ./.generated-prompts/<format>)
   --no-clean     Don't clear the output directory before compiling
   --dry-run      Show what would be compiled without writing files
   --format       Output format: json (default) or esm
@@ -21,16 +23,7 @@ export async function compile(args: string[]): Promise<void> {
     return;
   }
 
-  const positional = args.filter((a) => !a.startsWith('--'));
-  const sourceDir = positional[0];
-  const outputDir = positional[1];
-
-  if (!sourceDir || !outputDir) {
-    console.error('Error: Please provide source and output directories.');
-    console.error('Usage: promptopskit compile <sourceDir> <outputDir>');
-    process.exit(1);
-  }
-
+  const positional = getPositionalArgs(args, new Set(['--format', '--source', '--output', '-s', '-o']));
   const dryRun = args.includes('--dry-run');
   const noClean = args.includes('--no-clean');
   const format = getFlag(args, '--format') ?? 'json';
@@ -40,6 +33,9 @@ export async function compile(args: string[]): Promise<void> {
     process.exit(1);
   }
 
+  const sourceDir = getFlag(args, '--source', '-s') ?? positional[0] ?? './prompts';
+  const outputDir = getFlag(args, '--output', '-o') ?? positional[1] ?? defaultOutputDirForFormat(format);
+
   // Collect prompt files
   const files = await collectPromptFiles(sourceDir);
 
@@ -103,10 +99,36 @@ export async function compile(args: string[]): Promise<void> {
   }
 }
 
-function getFlag(args: string[], flag: string): string | undefined {
-  const idx = args.indexOf(flag);
-  if (idx >= 0 && idx + 1 < args.length) {
-    return args[idx + 1];
+function defaultOutputDirForFormat(format: 'json' | 'esm'): string {
+  return format === 'esm' ? './.generated-prompts/esm' : './.generated-prompts/json';
+}
+
+function getPositionalArgs(args: string[], flagsWithValues: Set<string>): string[] {
+  const positional: string[] = [];
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (flagsWithValues.has(arg)) {
+      index++;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      continue;
+    }
+
+    positional.push(arg);
+  }
+
+  return positional;
+}
+
+function getFlag(args: string[], ...flags: string[]): string | undefined {
+  for (const flag of flags) {
+    const idx = args.indexOf(flag);
+    if (idx >= 0 && idx + 1 < args.length) {
+      return args[idx + 1];
+    }
   }
   return undefined;
 }

src/cli/commands/init.ts

@@ -7,6 +7,9 @@ promptopskit init [dir]
 
 Scaffold a prompts directory with starter files.
 
+Arguments:
+  dir            Target directory (default: ./prompts)
+
 Options:
   --help, -h     Show this help
 `.trim();
@@ -180,7 +183,7 @@ export async function init(args: string[]): Promise<void> {
       if (!pkg.scripts?.['build:prompts']) {
         console.log();
         console.log(`Tip: Add to your package.json scripts:`);
-        console.log(`  "build:prompts": "promptopskit compile ${dir} ./dist/prompts"`);
+        console.log(`  "build:prompts": "promptopskit compile ${dir}"`);
       }
     } catch {
       // Ignore parse errors

src/cli/index.ts

@@ -14,7 +14,7 @@ Usage:
 Commands:
   init [dir]                           Scaffold a prompts directory with starter files
   validate <dir>                       Validate prompt files
-  compile <src> <out> [options]        Compile .md prompts to JSON/ESM artifacts
+  compile [src] [out] [options]        Compile .md prompts to JSON/ESM artifacts
   render <file> [options]              Render a prompt preview
   inspect <file>                       Print normalized prompt asset
   skill [options]                      Deploy AI agent instructions into your project

tests/composition.test.ts

@@ -355,4 +355,85 @@ Hello.
     const compiled = JSON.parse(await readFile(join(outDir, 'simple.json'), 'utf-8'));
     expect(compiled.sections.prompt_template).toBe('Hello.');
   });
+
+  it('defaults to ./prompts and ./.generated-prompts/json', async () => {
+    const cwd = process.cwd();
+    const srcDir = join(tmpDir, 'prompts');
+    const outDir = join(tmpDir, '.generated-prompts', 'json');
+    await mkdir(srcDir, { recursive: true });
+
+    await writeFile(join(srcDir, 'defaulted.md'), `---
+id: defaulted
+schema_version: 1
+---
+
+# Prompt template
+
+Hello.
+`);
+
+    process.chdir(tmpDir);
+
+    try {
+      const { compile } = await import('../src/cli/commands/compile.js');
+      await compile([]);
+    } finally {
+      process.chdir(cwd);
+    }
+
+    const compiled = JSON.parse(await readFile(join(outDir, 'defaulted.json'), 'utf-8'));
+    expect(compiled.id).toBe('defaulted');
+  });
+
+  it('defaults ESM output to ./.generated-prompts/esm', async () => {
+    const cwd = process.cwd();
+    const srcDir = join(tmpDir, 'prompts');
+    const outDir = join(tmpDir, '.generated-prompts', 'esm');
+    await mkdir(srcDir, { recursive: true });
+
+    await writeFile(join(srcDir, 'esm-default.md'), `---
+id: esm-default
+schema_version: 1
+---
+
+# Prompt template
+
+Hello.
+`);
+
+    process.chdir(tmpDir);
+
+    try {
+      const { compile } = await import('../src/cli/commands/compile.js');
+      await compile(['--format', 'esm']);
+    } finally {
+      process.chdir(cwd);
+    }
+
+    const compiled = await readFile(join(outDir, 'esm-default.mjs'), 'utf-8');
+    expect(compiled).toContain('export default');
+    expect(compiled).toContain('"id": "esm-default"');
+  });
+
+  it('accepts -s and -o aliases for source and output', async () => {
+    const srcDir = join(tmpDir, 'source-prompts');
+    const outDir = join(tmpDir, 'custom-output');
+    await mkdir(srcDir, { recursive: true });
+
+    await writeFile(join(srcDir, 'aliased.md'), `---
+id: aliased
+schema_version: 1
+---
+
+# Prompt template
+
+Hello.
+`);
+
+    const { compile } = await import('../src/cli/commands/compile.js');
+    await compile(['-s', srcDir, '-o', outDir]);
+
+    const compiled = JSON.parse(await readFile(join(outDir, 'aliased.json'), 'utf-8'));
+    expect(compiled.id).toBe('aliased');
+  });
 });