@garyr/pt-cli 0.25.0

package/doc/configuration.md

@@ -0,0 +1,333 @@
+# Configuration
+
+Config is stored at `~/.pt/config.yaml` and contains:
+
+- `version`: Config version
+- `templates`: Dictionary of learned templates with folder structure, `templateRoot`, `copy_files`, `post_copy`, and `post_config`
+- `default_post_config`: Array of default post-config tasks to suggest when learning a template
+- `ignore`: Global folder ignore patterns for `pt learn`
+- `variables`: Global variable suggestions for `pt learn` (name, prompt, default, required)
+
+## Template Variables
+
+When learning a template, you can define variables that will be prompted during initialization:
+
+```bash
+# Learn with variables
+pt learn /path/to/project
+# When prompted: Define template variables? (y/n)
+# Enter variables as comma-separated names: client_name,project_name
+```
+
+**Automatic Detection:**
+Instead of manual definition, `pt learn` and `pt update` automatically scan for placeholders like `{{ variable_name }}` in text files (root and 1st-level subdirectories). If found, they are automatically added to the `variables` list. This is the recommended way to manage variables for most templates.
+
+These variables are then used during `copy_files` operations to replace `{{variable_name}}` placeholders in copied files.
+
+## Post-Config Tasks
+
+Post-config tasks are optional commands that run after a project is initialized. They can be defined in a template or auto-detected from the source directory.
+
+**Auto-detection** (`pt learn`):
+
+When learning a template, `pt` scans the source directory for common patterns and suggests post-config tasks:
+
+| Pattern                        | Auto-detected task                | Type filter |
+| ------------------------------ | --------------------------------- | ----------- |
+| `.git/`                        | `git init`                        | all         |
+| `package.json`                 | `npm install`                     | javascript  |
+| `requirements.txt`             | `pip install -r requirements.txt` | python      |
+| `setup.py` or `pyproject.toml` | `pip install -e .`                | python      |
+| `Makefile`                     | `make init`                       | all         |
+
+Additionally, if `pt learn` finds a `post_config.sh` or `post_config.bat` file at the root of the directory, it will parse the scripts and automatically load the tasks into the `post_config` array.
+
+### The 80% Philosophy
+
+`pt` is designed to get you **80% of the way there** automatically. For complex templates, you are encouraged to:
+
+1. Use `pt learn` to capture the basic structure and key boilerplate.
+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.
+
+```
+javascript:  [git init, npm install]
+python:      [git init, python -m venv .venv, pip install -r requirements.txt]
+godot:       [git init, git lfs install]
+blender:     [git init, git lfs install]
+documentation: [git init]
+default:     [git init]
+```
+
+**Manual definition** in `config.yaml`:
+
+```yaml
+templates:
+  my_template:
+    name: My Project
+    type: javascript
+    post_config:
+      - command: "git init"
+        description: "Initialize git repository"
+      - command: "npm install"
+        description: "Install npm dependencies"
+        type: "javascript"
+      - command: "git lfs install"
+        description: "Install git-lfs hooks"
+        always_prompt: true
+      - script: "bin/setup.sh"
+        description: "Run custom setup script"
+```
+
+Each task supports:
+
+| Field            | Description                                                                      |
+| ---------------- | -------------------------------------------------------------------------------- |
+| `command`        | Shell command to run (auto-selected shell: `cmd /c` on Windows, `sh -c` on Unix) |
+| `description`    | Shown to user during prompt                                                      |
+| `type`           | Filter by project type (e.g., `javascript`)                                      |
+| `always_prompt`  | If `true`, ask per-task even if user says "yes"                                  |
+| `script`         | Path to script relative to template root                                         |
+| `cross_platform` | If `true`, use platform-safe runner                                              |
+
+**Interaction flow** during `pt init`:
+
+1. Folder structure created
+2. If template has `post_config`:
+   - Filter tasks by project type
+   - Show list: `[1/3] git init` ...
+   - Prompt: `Run post-config tasks? (y/N)`
+   - If yes: run each task, show ✓/✗ per task
+3. If no `post_config`, suggest baked-in defaults:
+   - Prompt: `No post-config defined. Use suggested tasks?`
+4. If `--skip-post-config` flag: skip entirely
+
+**Error handling**:
+
+- Missing template files: warn and skip
+- Command not found: catch error, log `✗`, continue to next task
+- Git already initialized: caught silently
+- Permission errors: caught and logged
+- If all tasks fail: warn but don't block project creation
+
+## Default Post-Config
+
+Default post-config tasks are defined at the top level of `~/.pt/config.yaml` under `default_post_config`. They serve as suggestions when creating or updating templates via `pt learn`. 
+
+Unlike previous versions, default tasks are **not** automatically applied during `pt init`. Instead, you select which ones to include when learning a template, and those selections are baked into the template's `post_config` list. This eliminates the need to repeat boilerplate setup (e.g. `git init`) across templates while keeping each template fully self-contained.
+
+### Configuration
+
+```yaml
+default_post_config:
+  - command: "git init"
+    description: "Initialize git repository"
+  - command: "git add -A && git commit -m 'Initial commit'"
+    description: "Initial git commit"
+    checked: false  # default on, but user must manually check
+  - command: "git lfs install"
+    description: "Install git-lfs hooks"
+    type: "godot"  # only applies to godot projects
+```
+
+### Fields
+
+Each default task supports the same fields as template post-config:
+
+| Field         | Description                                                                      |
+| ------------- | -------------------------------------------------------------------------------- |
+| `command`     | Shell command to run                                                             |
+| `description` | Shown to user during interactive selection                                       |
+| `checked`     | Default checkbox state (`true` by default); set `false` to require manual opt-in |
+| `type`        | Filter by project type (e.g. `"javascript"`); if set, task only applies when template type matches |
+
+### Behavior
+
+- **`pt learn --yes`**: all applicable default tasks are added automatically to the new template's `post_config`.
+- **Interactive mode (`pt learn`)**: applicable default tasks are shown in a checkbox group. Default tasks default to checked; `checked: false` overrides this.
+
+### Viewing
+
+Default tasks cannot be added via `pt add` or `pt learn` — they must be edited directly in `~/.pt/config.yaml` or viewed with `pt config`.
+
+## Global Variables
+
+Global variables are defined at the root of `~/.pt/config.yaml`. They serve as **suggestions** when creating or updating templates via `pt learn`.
+
+Unlike default post-config tasks, global variables are also **not** automatically applied during `pt init`. Instead, they are "stamped" into individual templates during the learning process. This allows you to maintain a consistent set of metadata (like `author`, `license`, or `version`) across all your project types without forcing those values onto old templates or external configurations.
+
+### Configuration
+
+```yaml
+variables:
+  - name: "author"
+    prompt: "Who is the author?"
+    default: "Gary Ritchie"
+  - name: "license"
+    prompt: "Choose a license:"
+    default: "MIT"
+    required: true
+```
+
+### Behavior
+
+1. **`pt learn`**: When scanning a project to create a new template, `pt` will:
+   - Detect variables from text files using `{{ name }}` syntax.
+   - Inject the **Global Variables** as additional suggestions.
+   - Prompt for each variable definition unless `--yes` is used.
+
+2. **`pt init`**: Project initialization uses only the variables explicitly saved in the chosen template. This ensures that templates are self-contained and portable.
+
+3. **`pt variables`**: Use this command to manage your global variables:
+   - `pt variables`: List current global variables.
+   - `pt variables --set KEY=VAL`: Set/update a global variable's default value.
+   - `pt variables --delete KEY`: Remove a global variable.
+   - `pt variables --set --json '...'`: Bulk update via JSON.
+
+## Copy Files
+
+Copy additional files from the template source directory with optional variable substitution and chmod:
+
+```yaml
+templates:
+  my_template:
+    name: My Project
+    type: javascript
+    copy_files:
+      - src: "templates/config.template"
+        dest: "config.json"
+        substitute_variables: true
+      - src: "scripts/setup.sh"
+        dest: "bin/setup.sh"
+        chmod: "0755"
+```
+
+Each entry supports:
+
+| Field                  | Description                                                       |
+| ---------------------- | ----------------------------------------------------------------- |
+| `src`                  | Path relative to template root (source directory from `pt learn`) |
+| `dest`                 | Path relative to project root                                     |
+| `substitute_variables` | If `true`, replace `{{variable_name}}` placeholders               |
+| `chmod`                | Octal permission string (e.g., `"0755"`) — skipped on Windows     |
+
+**How it works**:
+
+1. Read file from `templateRoot/src`
+2. If `substitute_variables`: replace `{{var}}` patterns with user-provided values
+3. Write to `projectRoot/dest` (creates intermediate directories)
+4. Apply `chmod` on Unix systems
+
+**Edge cases**:
+
+- Missing source file: warn and skip
+- Template root not set: skip silently (learn stores this)
+- Permission errors: caught and logged
+
+### Example: Variable Substitution
+
+A plausible scenario for customizing a new project's `package.json` and `README.md`:
+
+**1. Define in `config.yaml`**:
+```yaml
+templates:
+  node_web_app:
+    description: "A standard Node.js web application"
+    variables:
+      - name: "project_name"
+        prompt: "What is the project name?"
+        default: "my-app"
+      - name: "author_name"
+        prompt: "Who is the author?"
+        required: true
+    copy_files:
+      - src: "templates/package.json.tmpl"
+        dest: "package.json"
+        substitute_variables: true
+```
+
+**2. Template source (`templates/package.json.tmpl`)**:
+```json
+{
+  "name": "{{project_name}}",
+  "author": "{{author_name}}",
+  "version": "1.0.0"
+}
+```
+
+**3. Resulting project file**:
+If the user enters `my-service` and `Jane Doe`, the file `package.json` will be created with:
+```json
+{
+  "name": "my-service",
+  "author": "Jane Doe",
+  "version": "1.0.0"
+}
+```
+
+## Post-Copy
+
+Auto-detect executable scripts during `pt learn` and copy them to the new project:
+
+**Auto-detection** (`pt learn`):
+
+When learning a template, `pt` scans the source directory root for executable files:
+
+| Pattern                | Description                                         |
+| ---------------------- | --------------------------------------------------- |
+| `*.sh`                 | Shell scripts                                       |
+| `*.py`                 | Python scripts                                      |
+| `*.bat` / `*.cmd`      | Batch files                                         |
+| `Makefile`             | Makefiles                                           |
+| `*.mk`                 | Makefile includes                                   |
+| (no ext, has exec bit) | Any executable file (checks execute permission bit) |
+
+The detected files are presented to the user for confirmation:
+
+```
+Auto-detected executable files:
+  - bin/deploy.sh (shell script)
+  - scripts/lint.py (Python script)
+  - Makefile (makefile)
+
+Add to post_copy? (y/N):
+```
+
+**Manual definition** in `config.yaml`:
+
+```yaml
+templates:
+  my_template:
+    name: My Project
+    post_copy:
+      - src: "bin/deploy.sh"
+        dest: "bin/deploy.sh"
+      - src: "scripts/lint.py"
+        dest: "scripts/lint.py"
+```
+
+Each entry supports:
+
+| Field  | Description                                                       |
+| ------ | ----------------------------------------------------------------- |
+| `src`  | Path relative to template root (source directory from `pt learn`) |
+| `dest` | Path relative to project root (defaults to `src` if omitted)      |
+
+**How it works**:
+
+1. During `pt init`, copies each `post_copy` file from `templateRoot/src` to `projectRoot/dest`
+2. Auto-applies `0755` chmod for `.sh`, `.py`, `.bash`, `.bat` files
+3. Missing files: warn and skip, don't block project creation
+
+**vs copy_files**: `post_copy` is a simplified variant specifically for executables/scripts, auto-detected by `pt learn`. `copy_files` is for arbitrary template files with variable substitution support.
+
+## Order of Operations
+
+During `pt init`:
+
+1. **Create folder structure** — folders and `.info.md` inside directories
+2. **Copy `copy_files`** — with optional variable substitution and chmod
+3. **Copy `post_copy`** — executable scripts (auto-detected or manual)
+4. **Generate sharing metadata** — root `.info.md` and `post_config.sh`/`post_config.bat` are created so the result can be easily shared as a template
+5. **Merge post-config tasks** — evaluate the template's `post_config` tasks; filter by project type
+6. **Execute post-config tasks** — shell commands (interactive prompt, `--yes` for all, or `--skip-post-config` to omit)

package/doc/exclusions.md

@@ -0,0 +1,35 @@
+# Exclusions
+
+The following are excluded by default when learning templates:
+
+- `.git`, `node_modules`, `dist`, `build`
+- `.DS_Store`, `.pytest_cache`, `__pycache__`
+- `.vscode`, `.idea`
+- Various editor/IDE files (`.bak`, `.swp`, etc.)
+- Compiled files (`.pyc`, `.so`, `.dll`, etc.)
+- `.gitkeep.md`, `.info.md`, `.vale.ini`, `.gitattributes`
+
+## Ignore Patterns
+
+Use the top-level `ignore` key in `~/.pt/config.yaml` or the `--ignore` flag to exclude folders:
+
+```yaml
+ignore:
+  - DAILIES/*
+  - PARKING_LOT/*
+  - REFERENCE/*
+```
+
+Patterns use wildcards for clarity:
+
+| Pattern      | Effect                                                                       |
+| ------------ | ---------------------------------------------------------------------------- |
+| `DAILIES/*`  | Ignore all contents of DAILIES (DAILIES itself is kept as a template folder) |
+| `DAILIES/**` | Same as `DAILIES/*` (deep match)                                             |
+| `NODE`       | Ignore this specific folder only (no wildcard = exact match)                 |
+
+The CLI flag `--ignore=DAILIES/*,PARKING_LOT/*` merges with the config patterns (one-shot, not persistent).
+
+## Custom exclusions
+
+Additional patterns can be added to `DEFAULT_EXCLUDES` in `src/config.ts`.

package/doc/usage.md

@@ -0,0 +1,119 @@
+# Usage Guide
+
+## Learn a template
+
+```bash
+# Learn a new template (auto-detects post-config tasks)
+pt learn /path/to/PROJECT
+
+# Update an existing template (use current directory if no path given)
+pt update <template_name>
+pt update <template_name> /path/to/PROJECT
+
+# Ignore specific folders during learning
+pt learn /path/to/PROJECT --ignore=DAILIES/*,PARKING_LOT/*,REFERENCE/*
+
+# Ignore a folder name at any depth
+pt learn /path/to/PROJECT --ignore=**/.godot/
+
+# Non-interactive mode (useful for AI agents)
+pt learn /path/to/PROJECT --name my_template --desc "My new template" --yes
+```
+
+### Automatic Variable Detection
+
+During `pt learn` or `pt update`, the tool automatically scans text files at the root and in the first-level subdirectories for variable placeholders using the `{{ variable_name }}` syntax. 
+
+- **Detection Range:** Root files and 1st-level subfolder files (e.g., `README.md`, `.makerc`, `DOC/closedown.md`).
+- **Registration:** Any detected variables are automatically added to the template's configuration with default prompts (e.g., `Enter variable_name:`).
+- **Global Suggestions:** Your global variables (defined in `~/.pt/config.yaml`) are automatically injected as additional suggestions during the learn process.
+- **Updating:** You can add new placeholders to a project folder and run `pt update <template_name>` to automatically register them in your existing template.
+
+## Initialize a project
+
+```bash
+# Initialize from a template (auto-suggests post-config tasks)
+pt init <template_name> /path/to/new/PROJECT
+
+# Skip post-config tasks
+pt init <template_name> /path/to/new/PROJECT --skip-post-config
+
+# Dry run (preview actions without execution)
+pt init <template_name> /path/to/new/PROJECT --dry-run
+
+# Non-interactive mode with variables (useful for an API or AI agents)
+pt init <template_name> /path/to/new/PROJECT --yes --vars project_name=foo,author=bar
+```
+
+## Remove a template
+
+```bash
+# Remove a learned template (asks for confirmation)
+pt remove <template_name>
+
+# Short alias
+pt rm <template_name>
+```
+
+## Show config and templates
+
+```bash
+pt config
+```
+
+Shows all templates, their `post_config` tasks (if any), source paths, global post-config tasks, ignore patterns, global variables, and an example post-config block.
+
+## Manage Global Variables
+
+Global variables serve as boilerplate suggestions during the `pt learn` process.
+
+```bash
+# List global variables
+pt variables
+
+# Set/Update global variables (comma-separated pairs)
+pt variables --set AUTHOR="Gary Ritchie",LICENSE="MIT"
+
+# Delete a global variable
+pt variables --delete LICENSE
+```
+
+For more details on how these are used, see the [Configuration Guide](configuration.md).
+
+## Template Sharing & JSON
+
+### File-based Sharing
+
+You can share your templates with others simply by sharing a directory (or a ZIP of it). When someone else runs `pt learn` on it, `pt` will automatically detect the following files at the root:
+
+- `.info.md`: Used to automatically set the template's name (from the first `# Heading`) and description.
+- `post_config.sh` or `post_config.bat`: Parsed to automatically populate the `post_config` actions in the user's `config.yaml`.
+
+These files are also automatically generated at the root of a new project whenever you run `pt init`, making it trivial to initialize a project, zip it up, and share it with teammates as a fully-featured template!
+
+### JSON Export & Import
+
+For a more portable, text-based approach, you can export and import templates as JSON strings or files.
+
+#### Exporting a Template to JSON
+To export an existing template from your configuration as JSON:
+```bash
+pt config <template_name> --json > my_template.json
+```
+
+#### Importing a Template from JSON
+To add a template from a JSON file:
+```bash
+pt add <template_name> --file my_template.json
+```
+
+Or from a JSON string:
+```bash
+pt add <template_name> '{"description":"My Template","files":{...}}'
+```
+
+#### Exporting Full Config
+To see your entire configuration (including all templates) in JSON format:
+```bash
+pt config --json
+```

package/doc/variable_substitution_example.md

@@ -0,0 +1,78 @@
+# Variable Substitution Example
+
+This example demonstrates how to define variables in your template and use them to customize files during project initialization.
+
+## 1. Define Variables in `config.yaml`
+
+In your `~/.pt/config.yaml`, add a `variables` section to your template and set `substitute_variables: true` in the `copy_files` entries.
+
+```yaml
+templates:
+  node_web_app:
+    description: "A standard Node.js web application"
+    variables:
+      - name: "project_name"
+        prompt: "What is the project name?"
+        default: "my-app"
+      - name: "author_name"
+        prompt: "Who is the author?"
+        required: true
+    copy_files:
+      - src: "templates/package.json.tmpl"
+        dest: "package.json"
+        substitute_variables: true
+      - src: "templates/README.md.tmpl"
+        dest: "README.md"
+        substitute_variables: true
+```
+
+> [!TIP]
+> **New in v0.16.0:** You no longer need to manually define the `variables` section. During `pt learn` or `pt update`, the tool will automatically detect `{{ variable_name }}` placeholders in your files and add them to the configuration for you.
+
+## 2. Create Template Files
+
+Create the source files in your template directory using `{{variable_name}}` placeholders.
+
+**`templates/package.json.tmpl`**:
+```json
+{
+  "name": "{{project_name}}",
+  "version": "1.0.0",
+  "description": "Project created by pt-cli",
+  "author": "{{author_name}}",
+  "license": "MIT"
+}
+```
+
+**`templates/README.md.tmpl`**:
+```markdown
+# {{project_name}}
+
+Created by {{author_name}} using the Node Web App template.
+
+## Getting Started
+
+1. npm install
+2. npm run dev
+```
+
+## 3. Usage
+
+When you run `pt init node_web_app my-new-project`, the CLI will prompt you:
+
+```text
+? What is the project name? (my-app) my-awesome-service
+? Who is the author? Gary Ritchie
+```
+
+The resulting `package.json` in `my-new-project/` will be:
+
+```json
+{
+  "name": "my-awesome-service",
+  "version": "1.0.0",
+  "description": "Project created by pt-cli",
+  "author": "Gary Ritchie",
+  "license": "MIT"
+}
+```

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@garyr/pt-cli",
+  "version": "0.25.0",
+  "description": "Project Template CLI - Learn structures and initialize projects",
+  "main": "dist/index.js",
+  "bin": {
+    "pt": "./dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "tsx src/index.ts",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build",
+    "build:linux": "bun build ./src/index.ts --compile --target=bun-linux-x64   --outfile ../BUILD/pt-cli/pt-linux",
+    "build:macos": "bun build ./src/index.ts --compile --target=bun-darwin-x64  --outfile ../BUILD/pt-cli/pt-macos",
+    "build:windows": "bun build ./src/index.ts --compile --target=bun-windows-x64 --outfile ../BUILD/pt-cli/pt-win.exe",
+    "build:all": "npm run build:linux && npm run build:macos && npm run build:windows"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "inquirer": "^12.3.0",
+    "yaml": "^2.6.1",
+    "chalk": "^5.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0",
+    "@types/inquirer": "^9.0.7",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0"
+  }
+}

package/skills/agency-pt-operator/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: agency-pt-operator
+description: Specialist in using pt-cli to scaffold project templates, capture boilerplate, and maintain standardized directory structures. Includes knowledge of default_post_config, global variables, and automatic variable detection.
+---
+
+# `pt-cli` Operator Skill
+
+As an agent equipped with this skill, you have the ability to rapidly scaffold, manage, and learn project templates using the `pt-cli` tool. You must use this capability whenever you are asked to start a new project or establish a complex boilerplate structure.
+
+## Core Directives
+
+1. **Discovery First:**
+   Before creating a project structure manually, always check if a template exists.
+   - Run `pt config` to view available templates, their post-config tasks, and default post-config tasks.
+
+2. **Scaffolding (`pt init`):**
+   When a matching template exists, initialize it using the non-interactive flags.
+   - **Command:** `pt init <template_name> <destination_path> --yes`
+   - If the template requires variables, pass them: `pt init <template_name> <destination_path> --yes --vars key1=value1,key2=value2`
+   - *Never* run `pt init` without `--yes`, as interactive prompts will block you.
+   - Note any errors from auto-executed post-config tasks (like `npm install` failing) and correct them if necessary.
+   - Note any errors from auto-executed post-config tasks (like `npm install` failing) and correct them if necessary.
+
+3. **Capturing Knowledge (`pt learn`):**
+   If you spend time establishing a new, complex directory structure or configuration (e.g., a specific flavor of an Express backend with testing hooks), save it!
+   - **Command:** `pt learn <source_path> --name <template_name> --desc "<Description>" --yes`
+   - Explain to the user that you've captured this template for future use.
+   - **Automatic Variable Detection:** `pt learn` and `pt update` automatically scan text files (at root and one level deep) for `{{ variable_name }}` placeholders. You can add these to files (e.g., `README.md`, `.makerc`) and run `pt update <template> . --yes` to have them registered as template variables without manual configuration.
+
+4. **Template Maintenance (`pt rm`):**
+   If a template is obsolete or requested for deletion, use `pt rm`.
+   - **Command:** `pt rm <template_name> --yes`
+
+## Default Post-Config
+
+Default post-config tasks are stored in `~/.pt/config.yaml` under `default_post_config`. They are used as suggestions during `pt learn` to apply to the newly created template. Each task supports:
+
+- `command` — shell command to run
+- `description` — shown to user
+- `checked` — default checkbox state (defaults to `true` if omitted)
+- `type` — filter by project type (e.g., `"javascript"`); if set, the task only applies when that template's name matches the type filter
+
+Tasks with `checked: false` stay unchecked by default in interactive mode. In `pt learn --yes` mode, **all applicable** default tasks are included.
+
+Use `pt config` to view currently configured default tasks. To add default tasks, edit `~/.pt/config.yaml` directly or use `pt add` for template management (config is YAML-only at this time).
+
+## Global Variables
+
+Global variables are defined in `~/.pt/config.yaml` under `variables`. They act as **suggestions** during the `pt learn` or `pt update` process.
+
+- **Purpose:** They ensure that common metadata fields (like `author`, `license`, `project_version`) are consistently offered for inclusion in every new template you create.
+- **Inheritance:** When you `learn` a new project structure, these global variables are automatically merged with any detected variables (`{{ var }}`) and offered as part of the new template's variable list.
+- **Localization:** Once a template is saved, its variables are "stamped" in. Subsequent changes to global variables in the config will **not** retroactively affect old templates, ensuring stability and portability.
+- **Management:** Use `pt variables --set key=value` to update your global defaults. For bulk updates, use `pt variables --set --json '...'`.
+
+## Workflow Optimization
+
+`pt-cli` provides an "80% of the way there" solution. Your workflow for new projects should be:
+1. Identify the closest matching template (`pt config`).
+2. Scaffold it non-interactively (`pt init ... --yes`).
+3. Make the specific manual code/configuration changes requested by the user on top of that scaffolded base.