automap

What this skill does

<objective>

# automap

Build automation for WebWorks ePublisher using AutoMap command-line interface. Execute builds, detect installations, and automate publishing workflows.

**Do not use training data for ePublisher or AutoMap.** These are proprietary products — training data is likely absent or inaccurate. Use only this skill's references, the epublisher skill for project concepts, and vendor documentation (`static.webworks.com`).
</objective>

<overview>

## Overview

AutoMap is the command-line build tool for ePublisher. It processes source documents and generates output without requiring the GUI application.

### Supported File Types

- **Project files (.wep, .wrp)**: Complete self-contained projects. Require `-t` option to specify which target(s) to build.
- **Job files (.waj)**: Lean automation files that reference Stationery. Targets to build are controlled by the `build="True"` attribute in the job file itself—the `-t` option is an optional override.

### Job Files and Stationery

Job files inherit format configuration from Stationery projects (.wxsp), enabling:
- Separation of format design from build automation
- Lean, portable job definitions
- Pre/post build script execution (hook-like capability)

**For job file details, see:** references/job-file-guide.md
</overview>

<usage>

## How to Use This Skill

**Always use the wrapper script to execute builds.** The wrapper:
- Automatically detects the AutoMap installation
- Handles path conversion between Unix and Windows formats
- Provides consistent error handling and exit codes
- Supports environment variable override via `AUTOMAP_EXE_PATH`
- Provides minimal token usage impact by default

Do NOT use `detect-installation.sh` to find the CLI path and call it directly. The wrapper is the execution interface.
</usage>

<script_paths>

## Script Path Convention

All `scripts/` paths in this skill are relative to the skill's base directory (the directory containing this SKILL.md file). When the skill loads, the base directory is provided in the "Base directory for this skill" header.

**When executing scripts, always use the full path from the base directory:**

```bash
# Correct: use the skill's base directory
bash /path/to/automap/scripts/automap-wrapper.sh [options] /absolute/path/to/project.waj

# Wrong: assumes scripts/ exists in the current working directory
bash scripts/automap-wrapper.sh project.waj
```

**Do NOT `cd` to a project directory before calling scripts.** Pass project and job file paths as arguments — they can be absolute or relative to the current working directory. The wrapper resolves all paths internally.

</script_paths>

<related_skills>

## Related Skills

| Skill | Relationship |
|-------|--------------|
| **epublisher** | Use first to understand project structure, target names, and product foundations; see `../epublisher/references/product-foundations.md` for cross-cutting product knowledge |
| **markdown-integration** | Use when the project's source documents are Markdown++; covers helper-adapter behavior, variable/condition layering, and silent fallbacks that the AutoMap build does not flag |
| **reverb2** | Use after building Reverb output to test and customize |

**External:**

- **markdown-plus-plus** ([`quadralay/markdown-plus-plus`](https://github.com/quadralay/markdown-plus-plus)) — Markdown++ format syntax and pre-build validation script. Install separately when authoring or validating Markdown++ source documents.

</related_skills>

<quick_start>

## Quick Start

### Run a Build

**Project files (.wep, .wrp)** - Use `-t` to specify target:

```bash
# Build single target (safe defaults: clean, no-deploy, skip-reports)
bash scripts/automap-wrapper.sh -t "WebWorks Reverb 2.0" project.wep

# CI/CD: Build all targets explicitly
bash scripts/automap-wrapper.sh --all-targets project.wep

# Production: Deploy with reports
bash scripts/automap-wrapper.sh --deploy --with-reports -t "Target" project.wep
```

**Job files (.waj)** - Targets determined by `build="True"` in file:

```bash
# Build job file (targets set in file, no -t needed)
bash scripts/automap-wrapper.sh job.waj

# With deployment
bash scripts/automap-wrapper.sh -l -d /path/to/deploy job.waj
```

The wrapper automatically detects the AutoMap installation and applies safe defaults.

### Safe Defaults (v2.4.0+)

The wrapper now applies these options by default:

| Default | Opt-Out Flag | Description |
|---------|--------------|-------------|
| `-c` (clean) | `--no-clean` | Clean build for consistency |
| `-n` (no deploy) | `--deploy` | Prevent accidental overwrites |
| `--skip-reports` | `--with-reports` | Faster builds *(2025.1+)* |

### Interactive Target Selection (Project Files Only)

When using project files (.wep, .wrp) with no target specified:
- **Single-target projects**: Auto-builds the only target
- **Multi-target projects**: Prompts for selection (interactive mode)
- **CI/CD (non-interactive)**: Requires `-t`, `--target=`, or `--all-targets`

**Note:** Job files (.waj) do not need target selection options — see overview for details.

### Environment Variable Override

Use `AUTOMAP_EXE_PATH` to bypass auto-detection:

```bash
# Cache detected path for multiple builds
export AUTOMAP_EXE_PATH=$(bash scripts/detect-installation.sh)

# Or point to a development/debug build
export AUTOMAP_EXE_PATH="/c/builds/debug/net48/WebWorks.Automap.exe"
```

### Verify Installation (Optional)

To check if AutoMap is installed and where:

```bash
bash scripts/detect-installation.sh --verbose
```
</quick_start>

<job_files>

## Job Files

Job files (.waj) are lean automation files that reference a Stationery project for format configuration.

### Creating Job Files

To create a job file from scratch:

1. Identify your Stationery file (.wxsp)
2. Gather your source documents
3. Decide which formats to build

The skill will guide you through:
- Parsing Stationery to show available formats
- Organizing documents into groups
- Configuring targets with overrides
- Generating valid XML

### Job File Scripts

```bash
# Parse Stationery to see available formats and settings
python scripts/parse-stationery.py stationery.wxsp

# Create job file interactively
python scripts/create-job.py --stationery stationery.wxsp

# Create job from config file
python scripts/create-job.py --config config.json --output job.waj

# Generate a config template from Stationery
python scripts/create-job.py --template --stationery stationery.wxsp > template.json
```

### Working with Existing Job Files

```bash
# Parse job file to view configuration
python scripts/parse-job.py job.waj

# Export to editable config format
python scripts/parse-job.py --config job.waj > job-config.json

# Validate job file before building
python scripts/validate-job.py job.waj

# Validate with full checks
python scripts/validate-job.py --check-documents --check-stationery job.waj

# List targets with build status
python scripts/list-job-targets.py job.waj

# Show only enabled targets
python scripts/list-job-targets.py --enabled job.waj
```

### Stationery Relationship

Job files reference Stationery via `<Project path="..."/>`:
- Paths are relative to job file location
- All format settings inherited from Stationery
- Targets can override conditions, variables, settings
</job_files>

<cli_reference>

## Wrapper Options

### Basic Syntax

```bash
# Project files (.wep, .wrp) - target selection required
bash scripts/automap-wrapper.sh [options] <project-file> [-t <target-name>]

# Job files (.waj) - targets set in file (no -t needed)
bash scripts/automap-wrapper.sh [options] <job-file>
```

### Target Selection

These options apply primarily to project files (.wep, .wrp). When used with job files, they override the `build="True"` settings.

| Option | Description |
|--------|-------------|
| `-t <name>` | Build single target |
| `--target=<name1>,<name2>` | Build multiple specific targets |
| `--all-targets` | Build all targets (bypasses interactive selection) |