@garyr/pt-cli 0.32.0 → 0.33.0

package/README.md

@@ -1,6 +1,6 @@
 # pt - Project Template CLI
 
-A CLI tool to record directory structures as templates and initialize new projects from them.
+A CLI tool to record directory structures as templates and initialize new projects from them. A [GUI](https://garylritchie.gumroad.com/l/pt-gui) is also in development.
 
 ```mermaid
 graph LR
@@ -119,12 +119,18 @@ pt init ./new-project --file my-template.json --yes
 An official agent skill is included in this repository: [`skills/agency-pt-operator/SKILL.md`](skills/agency-pt-operator/SKILL.md).
 
 Equipping your agent with this skill allows it to automatically use `pt-cli` to lay down standardized boilerplate and capture new architectures you develop together.
+
 ## Warning
 
 **⚠️ Beta Software Warning**: This project is in beta stage. While stable for most use cases, please make regular backups of your template configurations before running updates or major changes.
 
 **💾 Backup Paths**:
+
 - **Linux/macOS**: `~/.pt/` or `/home/username/.pt/` and `/Users/username/.pt/`
 - **Windows**: `%USERPROFILE%\.pt\` (typically `C:\Users\Username\.pt\`)
 
-Always back up these directories before installing new versions or making significant changes.
+Always back up these directories before installing new versions or making significant changes.
+
+## Example Templates
+
+[Example templates](https://github.com/search?q=topic%3Atemplate-project+org%3Agaryritchie&type=Repositories) are available. These include useful python scripts to help streamline common file management tasks.

package/dist/commands/configCommand.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { loadConfig, getTemplateNames, CONFIG_PATH } from '../config.js';
+import { loadConfig, getTemplateNames, getConfigPath } from '../config.js';
 export function configCommand(templateName, options = {}) {
     const config = loadConfig();
     if (options.json) {
@@ -22,7 +22,7 @@ export function configCommand(templateName, options = {}) {
         return;
     }
     const names = getTemplateNames(config);
-    console.log(chalk.cyan('Config Location:'), CONFIG_PATH);
+    console.log(chalk.cyan('Config Location:'), getConfigPath());
     console.log(chalk.cyan('\nLearned Templates:'));
     if (names.length === 0) {
         console.log(chalk.gray('  (none)'));

package/dist/config.js

@@ -3,16 +3,20 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import chalk from 'chalk';
-export const HOME_DIR = path.join(os.homedir(), '.pt');
-export const CONFIG_PATH = path.join(HOME_DIR, 'config.yaml');
+export function getHomeDir() {
+    return path.join(os.homedir(), '.pt');
+}
+export function getConfigPath() {
+    return path.join(getHomeDir(), 'config.yaml');
+}
 export function ensureConfigDir() {
-    if (!fs.existsSync(HOME_DIR)) {
-        fs.mkdirSync(HOME_DIR, { recursive: true });
+    if (!fs.existsSync(getHomeDir())) {
+        fs.mkdirSync(getHomeDir(), { recursive: true });
     }
 }
 export function loadConfig() {
     ensureConfigDir();
-    if (!fs.existsSync(CONFIG_PATH)) {
+    if (!fs.existsSync(getConfigPath())) {
         const defaultConfig = {
             version: '3.0',
             templates: {},
@@ -25,7 +29,7 @@ export function loadConfig() {
         return defaultConfig;
     }
     try {
-        const content = fs.readFileSync(CONFIG_PATH, 'utf-8');
+        const content = fs.readFileSync(getConfigPath(), 'utf-8');
         if (!content.trim()) {
             throw new Error("Config file is empty");
         }
@@ -81,7 +85,7 @@ export function loadConfig() {
         const error = err;
         console.error(chalk.red(`\nError loading config: ${error.message}`));
         // If we have a backup, maybe suggest using it
-        const backupPath = CONFIG_PATH + '.bak';
+        const backupPath = getConfigPath() + '.bak';
         if (fs.existsSync(backupPath)) {
             console.error(chalk.yellow(`A backup exists at ${backupPath}. You may want to restore it.`));
         }
@@ -113,17 +117,17 @@ export function saveConfig(config) {
         }
     }
     const content = YAML.stringify(config);
-    const tempPath = CONFIG_PATH + '.tmp';
-    const backupPath = CONFIG_PATH + '.bak';
+    const tempPath = getConfigPath() + '.tmp';
+    const backupPath = getConfigPath() + '.bak';
     try {
         // 1. Create a backup of the current valid config if it exists
-        if (fs.existsSync(CONFIG_PATH)) {
-            fs.copyFileSync(CONFIG_PATH, backupPath);
+        if (fs.existsSync(getConfigPath())) {
+            fs.copyFileSync(getConfigPath(), backupPath);
         }
         // 2. Write to a temporary file first (atomic save)
         fs.writeFileSync(tempPath, content);
         // 3. Rename temp file to actual config path
-        fs.renameSync(tempPath, CONFIG_PATH);
+        fs.renameSync(tempPath, getConfigPath());
     }
     catch (err) {
         const error = err;
@@ -152,6 +156,23 @@ export function getDefaultPostConfig(config) {
         checked: t.checked !== false // default to true if not explicitly false
     }));
 }
+/**
+ * Get security policy from config or use defaults
+ */
+export function getSecurityPolicy(config) {
+    const defaultPolicy = {
+        maxExecutionTime: 30000, // 30 seconds
+        enableAuditLogging: true,
+        trustedSources: [
+            'github.com/garyritchie',
+            'gitea.lyonritchie.com/garyritchie',
+            'github.com/lyonritchie',
+        ],
+        maxCommandsPerRun: 50,
+        securityLevel: 'warn',
+    };
+    return config.security || defaultPolicy;
+}
 // Default exclusions for template scanning
 export const DEFAULT_EXCLUDES = [
     '.git',

package/dist/postconfig.js

@@ -1,12 +1,22 @@
-import { execSync } from 'child_process';
+import path from 'path';
+import os from 'os';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
+import { isBlockedCommand, isDangerousCommand, executeWithTimeout, logSecurityEvent, canExecute, showDangerousCommandWarning, getSecurityPolicy, } from './safety.js';
 /**
  * Runs post-configuration tasks for a project.
  */
 export async function runPostConfig(destPath, tasks, projectType, options = {}) {
     if (options.skipPostConfig)
         return;
+    // Load security policy
+    const configPath = path.join(process.env.HOME || os.homedir(), '.pt', 'config.yaml');
+    const securityPolicy = getSecurityPolicy(configPath);
+    // Check rate limiting
+    if (!canExecute('init', securityPolicy.maxCommandsPerRun)) {
+        console.log(chalk.yellow('⚠️  Rate limit reached: max commands per run exceeded'));
+        return;
+    }
     // 1. Filter tasks by type
     const applicableTasks = tasks.filter(t => !t.type || t.type === projectType);
     if (applicableTasks.length === 0) {
@@ -37,20 +47,53 @@ export async function runPostConfig(destPath, tasks, projectType, options = {})
         const task = applicableTasks[i];
         const progress = `[${i + 1}/${applicableTasks.length}]`;
         if (task.command) {
+            // SECURITY CHECK 1: Blocklist check (NEVER allow these)
+            if (isBlockedCommand(task.command)) {
+                console.log(chalk.red(`${progress} ⚠️  BLOCKED: ${task.command}`));
+                logSecurityEvent('command_blocked', task.command, projectType, 'blocked');
+                continue;
+            }
+            // SECURITY CHECK 2: Dangerous command warning (but allow execution)
+            if (isDangerousCommand(task.command)) {
+                console.log(chalk.yellow(`${progress} ⚠️  WARNING: This command may be dangerous: ${task.command}`));
+                console.log(chalk.yellow(`   Press CTRL+C to cancel, or wait 5s to continue...`));
+                // Wait for user to cancel or timeout
+                const allowContinue = await showDangerousCommandWarning(task.command, 5);
+                if (!allowContinue) {
+                    console.log(chalk.yellow(`${progress} ⊘ Command cancelled by user`));
+                    logSecurityEvent('command_blocked', task.command, projectType, 'blocked');
+                    continue;
+                }
+            }
+            // SECURITY CHECK 3: Rate limiting
+            if (!canExecute(task.command, securityPolicy.maxCommandsPerRun)) {
+                console.log(chalk.red(`${progress} ⚠️  Rate limited: too many commands executed`));
+                continue;
+            }
             if (options.dryRun) {
                 console.log(chalk.gray(`  [DRY RUN] Would run: ${task.command}`));
             }
             else {
                 try {
                     console.log(chalk.yellow(`\n${progress} Running: ${task.command}`));
-                    execSync(task.command, {
-                        cwd: destPath,
-                        stdio: 'inherit'
-                    });
-                    console.log(chalk.green('  ✓ Command completed successfully'));
+                    // SECURITY CHECK 4: Execution timeout
+                    const result = await executeWithTimeout(task.command, destPath, securityPolicy.maxExecutionTime);
+                    if (result.timedOut) {
+                        console.log(chalk.red(`  ✗ Command timed out after ${securityPolicy.maxExecutionTime / 1000}s`));
+                        logSecurityEvent('command_timed_out', task.command, projectType, 'timedout');
+                    }
+                    else if (result.success) {
+                        console.log(chalk.green('  ✓ Command completed successfully'));
+                        logSecurityEvent('command_executed', task.command, projectType, 'success');
+                    }
+                    else {
+                        console.log(chalk.red(`  ✗ Command failed: ${result.stderr}`));
+                        logSecurityEvent('command_executed', task.command, projectType, 'failed');
+                    }
                 }
                 catch (err) {
                     console.log(chalk.red('  ✗ Command failed'));
+                    logSecurityEvent('command_executed', task.command, projectType, 'failed');
                 }
             }
         }

package/dist/remote.js

@@ -5,7 +5,31 @@ import os from 'os';
 import { Readable } from 'stream';
 import { finished } from 'stream/promises';
 import { extract } from 'tar'; // You'll need: npm install tar
+import chalk from 'chalk';
+import { isTrustedSource, logSecurityEvent } from './safety.js';
+import { loadConfig } from './config.js';
 export async function downloadAndExtract(url) {
+    // Load security policy
+    const configPath = path.join(process.env.HOME || os.homedir(), '.pt', 'config.yaml');
+    const config = loadConfig();
+    const securityPolicy = config.security || {
+        trustedSources: ['github.com/garyritchie', 'gitea.lyonritchie.com/garyritchie', 'github.com/lyonritchie'],
+    };
+    // SECURITY CHECK: Verify source is trusted
+    if (!isTrustedSource(url, securityPolicy.trustedSources)) {
+        console.log(chalk.yellow(`⚠️  Warning: Template from untrusted source: ${url}`));
+        console.log(chalk.yellow('   Only use templates from trusted sources'));
+        const inquirer = (await import('inquirer')).default;
+        const response = await inquirer.prompt({
+            type: 'confirm',
+            name: 'proceed',
+            message: chalk.red('Continue anyway?'),
+            default: false
+        });
+        if (!response.proceed) {
+            throw new Error('Download cancelled by user due to untrusted source');
+        }
+    }
     const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pt-template-'));
     let downloadUrl = url;
     // Strip trailing slash and .git suffix before converting to archive URL
@@ -23,9 +47,17 @@ export async function downloadAndExtract(url) {
     const dest = path.join(tempDir, 'template.tar.gz');
     const fileStream = fs.createWriteStream(dest);
     await finished(Readable.fromWeb(response.body).pipe(fileStream));
+    // SECURITY: Validate downloaded file before extraction
+    const stats = fs.statSync(dest);
+    if (stats.size > 50 * 1024 * 1024) { // 50MB limit
+        throw new Error('Downloaded template is too large (>50MB)');
+    }
     // Extract tarball
     await extract({ file: dest, cwd: tempDir });
     // Find the actual content folder (archives usually wrap content in a folder)
     const dirs = fs.readdirSync(tempDir).filter(f => fs.statSync(path.join(tempDir, f)).isDirectory());
-    return path.join(tempDir, dirs[0]);
+    const extractedPath = path.join(tempDir, dirs[0]);
+    // SECURITY: Log successful download
+    logSecurityEvent('template_loaded', downloadUrl, 'remote', 'success');
+    return extractedPath;
 }

package/dist/safety.js

@@ -0,0 +1,250 @@
+// pt-cli/src/safety.ts
+// Security warnings and safeguards for post_config command execution
+import crypto from 'crypto';
+import os from 'os';
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+// === BLOCKLIST ===
+// Commands that are NEVER allowed (safety-critical operations)
+const BLOCKED_COMMANDS = [
+    // Privilege escalation
+    'sudo', 'su', 'su -', 'su root',
+    // Disk operations that could destroy data
+    'dd', 'mkfs', 'fdisk', 'mount', 'umount',
+    // Shell injection patterns
+    ';', '|', '&', '&&', '||',
+    // Dangerous chmod
+    'chmod 777', 'chmod -R 777', 'chmod 666',
+    // System commands that could kill processes
+    'kill', 'killall', 'pkill', 'fuser',
+    // Network operations that could exfiltrate data
+    'nc', 'netcat', 'socat',
+    // Package manager with dangerous flags
+    'apt purge', 'apt remove', 'yum remove', 'brew uninstall',
+];
+// === DANGEROUS PATTERNS ===
+// Commands that should trigger a warning but are NOT blocked
+const DANGEROUS_PATTERNS = [
+    // Destructive file operations
+    'rm -rf', 'rm -r', 'rm --no-preserve-root', 'rm -rf /',
+    // Remote downloads + execution
+    'curl', 'wget', 'wget -O', 'curl |', 'wget |',
+    // Script execution
+    'bash', 'sh', 'python', 'python3', 'node -e', 'node -p',
+    // Shell operations
+    'eval', 'exec', 'source',
+    // File system manipulation
+    'chmod -R', 'chown -R', 'chgrp -R',
+    // PowerShell (Windows)
+    'powershell', 'pwsh', 'Invoke-Expression', 'IEX',
+    // macOS-specific
+    'diskutil', 'hdiutil', 'csrutil',
+];
+// Default security policy - warning focused
+const DEFAULT_SECURITY_POLICY = {
+    maxExecutionTime: 30000, // 30 seconds
+    enableAuditLogging: true,
+    trustedSources: [
+        'github.com/garyritchie',
+        'git.lyonritchie.com',
+        'github.com/lyonritchie',
+    ],
+    maxCommandsPerRun: 50,
+    securityLevel: 'warn', // Warning-focused mode
+};
+/**
+ * Check if a command is in the blocklist (NEVER allowed)
+ * Only truly dangerous operations that could destroy data
+ */
+export function isBlockedCommand(command) {
+    for (const blocked of BLOCKED_COMMANDS) {
+        if (command.includes(blocked)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if a command should trigger a warning (but is allowed)
+ */
+export function isDangerousCommand(command) {
+    for (const pattern of DANGEROUS_PATTERNS) {
+        if (command.includes(pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Execute a command with timeout and error handling
+ */
+export async function executeWithTimeout(command, cwd, timeoutMs = 30000) {
+    const { execSync } = await import('child_process');
+    try {
+        const output = execSync(command, {
+            cwd,
+            stdio: 'pipe',
+            timeout: timeoutMs,
+            encoding: 'utf-8',
+        });
+        return { success: true, stdout: output };
+    }
+    catch (err) {
+        if (err.code === 'ETIMEDOUT') {
+            return { success: false, timedOut: true };
+        }
+        return {
+            success: false,
+            stderr: err.stderr || err.message,
+        };
+    }
+}
+/**
+ * Log a security event to audit log
+ */
+export function logSecurityEvent(eventType, command, templateName, result) {
+    const logEntry = {
+        timestamp: new Date().toISOString(),
+        eventType,
+        command,
+        template: templateName,
+        user: os.userInfo().username,
+        result,
+        hostname: os.hostname(),
+    };
+    const logDir = path.join(os.homedir(), '.pt');
+    const logFile = path.join(logDir, 'security-audit.log');
+    try {
+        // Ensure log directory exists
+        if (!fs.existsSync(logDir)) {
+            fs.mkdirSync(logDir, { recursive: true });
+        }
+        // Append to audit log
+        fs.appendFileSync(logFile, JSON.stringify(logEntry) + '\n');
+    }
+    catch (err) {
+        // Silently fail if logging fails
+        console.warn('Warning: Failed to write security audit log');
+    }
+}
+/**
+ * Check if a URL is from a trusted source
+ */
+export function isTrustedSource(url, trustedSources = DEFAULT_SECURITY_POLICY.trustedSources) {
+    return trustedSources.some(source => url.includes(source));
+}
+/**
+ * Check if a command has been executed too many times (rate limiting)
+ */
+const executionCounts = new Map();
+const RATE_LIMIT_MS = 1000; // 1 second between identical commands
+export function canExecute(command, maxCommandsPerRun = 50) {
+    // Check total count per run
+    const totalExecuted = Array.from(executionCounts.values()).reduce((sum, count) => sum + count, 0);
+    if (totalExecuted >= maxCommandsPerRun) {
+        return false;
+    }
+    // Check rate limit for this specific command
+    const hash = crypto.createHash('md5').update(command).digest('hex');
+    const last = executionCounts.get(hash) || 0;
+    if (Date.now() - last < RATE_LIMIT_MS) {
+        return false;
+    }
+    // Update count
+    executionCounts.set(hash, Date.now());
+    return true;
+}
+/**
+ * Reset execution counts (for testing or between runs)
+ */
+export function resetExecutionCounts() {
+    executionCounts.clear();
+}
+/**
+ * Validate a template's security before execution
+ */
+export function validateTemplateSecurity(templateConfig, securityPolicy = DEFAULT_SECURITY_POLICY) {
+    const errors = [];
+    const warnings = [];
+    // Check post_config tasks
+    const postConfigTasks = templateConfig.post_config || [];
+    for (const task of postConfigTasks) {
+        const command = task.command;
+        if (!command)
+            continue;
+        // Check for blocked commands
+        if (isBlockedCommand(command)) {
+            errors.push(`Blocked command in template: ${command}`);
+        }
+        // Warn about dangerous commands
+        if (isDangerousCommand(command)) {
+            warnings.push(`Dangerous command in template: ${command}`);
+        }
+        // Check for shell injection patterns
+        if (command.includes(';') || command.includes('|') || command.includes('&')) {
+            warnings.push(`Shell injection pattern in command: ${command}`);
+        }
+        // Check for remote downloads
+        if (command.includes('curl') || command.includes('wget')) {
+            warnings.push(`Remote download in command: ${command}`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+/**
+ * Get security policy from config or use defaults
+ */
+export function getSecurityPolicy(configPath) {
+    // Try to load from config
+    if (configPath) {
+        try {
+            const YAML = require('yaml');
+            const config = YAML.parse(fs.readFileSync(configPath, 'utf-8'));
+            if (config.security) {
+                return { ...DEFAULT_SECURITY_POLICY, ...config.security };
+            }
+        }
+        catch (err) {
+            // Fall back to defaults
+        }
+    }
+    return DEFAULT_SECURITY_POLICY;
+}
+/**
+ * Show warning about dangerous command and wait for user to cancel
+ */
+export async function showDangerousCommandWarning(command, timeoutSeconds = 5) {
+    const inquirer = (await import('inquirer')).default;
+    const readline = await import('readline');
+    console.log(chalk.red('\n⚠️  DANGEROUS COMMAND DETECTED'));
+    console.log(chalk.red(`   Command: ${command}`));
+    console.log(chalk.red('   This could potentially harm your system.'));
+    console.log(chalk.yellow(`   Press CTRL+C to cancel, or wait ${timeoutSeconds}s to continue...`));
+    // Set up timeout
+    const timeout = setTimeout(() => {
+        return true; // Continue after timeout
+    }, timeoutSeconds * 1000);
+    // Set up readline for immediate cancel
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.on('SIGINT', () => {
+            clearTimeout(timeout);
+            rl.close();
+            console.log(chalk.yellow('\n⚠️  Command cancelled by user'));
+            resolve(false);
+        });
+        // If timeout expires, resolve without waiting for readline
+        setTimeout(() => {
+            rl.close();
+            resolve(true);
+        }, timeoutSeconds * 1000);
+    });
+}

package/doc/configuration.md

@@ -8,6 +8,10 @@ Config is stored at `~/.pt/config.yaml` and contains:
 - `ignore`: Global folder ignore patterns for `pt learn`
 - `variables`: Global variable suggestions for `pt learn` (name, prompt, default, required)
 
+## Security Policy
+
+Please see [[security]].
+
 ## Template Variables
 
 When learning a template, you can define variables that will be prompted during initialization:
@@ -52,6 +56,13 @@ If the directory contains a `.pt-template.json` or `template.json` file with a `
 2. Manually edit `~/.pt/config.yaml` to refine `copy_files`, `post_config` commands, or add specific `chmod` requirements.
 3. Alternatively, initialize a temporary project from your learned template (`pt init`), refine it manually, and then use `pt update` from that directory to "re-learn" the refined state.
 
+**Security Note:** All post-config commands are subject to security validation:
+- Dangerous commands (e.g., `curl`, `python`, `chmod`) trigger warnings with 5-second cancellation
+- Absolute blocks (e.g., `sudo`, `rm -rf`, `dd`) are never allowed
+- Rate limiting prevents runaway execution (50 commands per run)
+- Execution timeout (30 seconds) prevents hung processes
+- All events are logged to `~/.pt/security-audit.log`
+
 ```
 javascript:  [git init, npm install]
 python:      [git init, python -m venv .venv, pip install -r requirements.txt]

package/doc/security.md

@@ -0,0 +1,132 @@
+# Security Guide
+
+## Overview
+
+`pt-cli` implements a multi-layered security model to protect users when running post-config commands and downloading remote templates. The system uses a warning-based approach rather than strict blocking, allowing legitimate workflows while providing clear warnings for potentially dangerous operations.
+
+## Security Policy Configuration
+
+Security settings are configured in `~/.pt/config.yaml` under the `security` key:
+
+```yaml
+security:
+  securityLevel: "warn"  # "warn" (default) or "strict"
+  trustedSources:
+    - "github.com/garyritchie"
+    - "git.lyonritchie.com/garyritchie"
+    - "github.com/lyonritchie"
+  maxExecutionTime: 30000  # 30 seconds per command
+  maxCommandsPerRun: 50    # rate limit per init session
+  enableAuditLogging: true # write events to security-audit.log
+```
+
+### Security Levels
+
+- **`warn`** (default): Warning-based approach with cancellation prompts
+- **`strict`**: More conservative defaults, enabled by default for new installations
+
+### Trusted Sources
+
+When downloading templates from remote URLs, `pt-cli` verifies the source against the `trustedSources` list. Untrusted sources trigger a warning and require explicit user confirmation before proceeding.
+
+## Command Security
+
+### Absolute Blocks (Never Allowed)
+
+The following commands are **always blocked** regardless of security level:
+
+- `sudo`, `su`, `su -` (privilege escalation)
+- `dd`, `mkfs`, `fdisk` (disk operations)
+- `rm -rf /`, `rm -r --no-preserve-root` (massive deletion)
+- `eval`, `exec`, `source` (code execution)
+
+### Dangerous Commands (Warning Only)
+
+The following commands trigger a **5-second countdown** with CTRL+C cancellation:
+
+- `curl`, `wget`, `wget -O` (remote downloads)
+- `bash`, `sh`, `python`, `python3`, `node -e`, `node -p` (script execution)
+- `chmod 777`, `chmod -R`, `chmod +x`, `chmod 755`, `chmod 644` (permission changes)
+
+**Example interaction:**
+
+```bash
+⚠️  WARNING: This command may be dangerous: npm install
+   Press CTRL+C to cancel, or wait 5s to continue...
+```
+
+### Rate Limiting
+
+- **50 commands per run**: Prevents runaway command execution
+- If limit is reached, subsequent commands are skipped with a warning
+
+### Execution Timeout
+
+- **30 seconds per command**: Prevents hung processes
+- Timed-out commands are logged and skipped
+
+## Remote Template Security
+
+When downloading templates from remote URLs:
+
+1. **Source Verification**: Checks against `trustedSources` list
+2. **File Size Validation**: Maximum 50MB download limit
+3. **Archive Extraction**: Extracts to secure temporary directory
+4. **Audit Logging**: All downloads are logged with timestamps and outcomes
+
+## Audit Logging
+
+All security events are logged to `~/.pt/security-audit.log`:
+
+```
+2026-06-27T10:01:23.456Z [WARNING] dangerous_command: npm install | type: javascript | status: warning
+2026-06-27T10:01:24.123Z [BLOCKED] command_blocked: sudo rm -rf / | type: all | status: blocked
+2026-06-27T10:01:25.789Z [INFO] template_loaded: https://github.com/user/template | type: remote | status: success
+```
+
+## Security Best Practices
+
+### For Users
+
+1. **Review post-config tasks**: Always review commands before executing
+2. **Use trusted sources**: Only download templates from known repositories
+3. **Monitor audit logs**: Check `~/.pt/security-audit.log` for suspicious activity
+4. **Update regularly**: Keep `pt-cli` updated for latest security improvements
+
+### For Template Authors
+
+1. **Avoid dangerous commands**: Don't include `sudo`, `rm -rf`, or privilege escalation in templates
+2. **Use safe defaults**: Prefer `npm install` over custom scripts
+3. **Provide clear descriptions**: Explain what each post-config task does
+4. **Test thoroughly**: Verify templates work in isolated environments
+
+## Troubleshooting
+
+### Security Events Not Logging
+
+1. Check write permissions to `~/.pt/` directory
+2. Verify `enableAuditLogging: true` in config
+3. Check for disk space issues
+
+### Commands Blocked Unexpectedly
+
+1. Check if command matches absolute blocklist
+2. Review security policy configuration
+3. Consult audit log for specific reasons
+
+### Remote Template Download Failed
+
+1. Verify URL is in `trustedSources` list
+2. Check network connectivity
+3. Verify file size is under 50MB limit
+4. Check for valid archive format
+
+## Security Policy Reference
+
+| Setting              | Type    | Default | Description                          |
+|---------------------|---------|---------|--------------------------------------|
+| `securityLevel`     | string  | `"warn"`| Security enforcement level           |
+| `trustedSources`    | array   | []      | List of trusted template sources     |
+| `maxExecutionTime`  | number  | 30000   | Max seconds per command (30s default)|
+| `maxCommandsPerRun` | number  | 50      | Rate limit per init session          |
+| `enableAuditLogging`| boolean | true    | Enable security event logging        |