# Phase 1 - Render DOCX

## Inputs

- One user-provided Markdown path: either `project-doc/project.md` or `commercial-offer/commercial-offer.md`.
- Bundled script: `scripts/render-docx.sh`.
- Bundled style templates under `skills/render-docx/templates/`.

## What to do

### Step 1: Validate the user request

Accept exactly one path. If the argument is empty, contains flags, or includes multiple files, stop and ask for one renderable Markdown path.

The only renderable paths are:

- `docs/discovery/<project-slug>/project-doc/project.md`
- `docs/discovery/<project-slug>/commercial-offer/commercial-offer.md`

If the path is any other Discovery artifact, STOP. Explain that requirements, HLA, planning, and PRD items remain Markdown source artifacts and are grouped into the Project Document for DOCX rendering.

### Step 2: Validate Markdown shape when applicable

If the input path is `docs/discovery/<project-slug>/project-doc/project.md`:

- It MUST start with frontmatter containing `source: machine-discovery:project-doc`, `project_slug:`, `status: draft`, `language: es` or `language: en`, and `processed_at:`.
- If `language: es`, it MUST contain `# Documento de proyecto -`.
- If `language: en`, it MUST contain `# Project Document -`.
- It MUST NOT contain raw `{{PLACEHOLDER}}` or `@@BLOCK@@` markers.

If the input path is `docs/discovery/<project-slug>/commercial-offer/commercial-offer.md`:

- It MUST start with frontmatter containing `source: machine-discovery:commercial-offer`, `project_slug:`, `status: draft`, `language: es` or `language: en`, and `processed_at:`.
- If `language: es`, it MUST contain `# Oferta Comercial F2 -`.
- If `language: en`, it MUST contain `# F2 Commercial Offer -`.
- It MUST NOT contain raw `{{PLACEHOLDER}}` or `@@BLOCK@@` markers.

Both renderable Markdown files MUST NOT contain raw `{{PLACEHOLDER}}` or `@@BLOCK@@` markers.

If any validation fails, STOP. Do not render. Tell the user to regenerate the Markdown with the matching machine-discovery command.

### Step 3: Run the renderer

Use the plugin script. Prefer `$CLAUDE_PLUGIN_ROOT` when the skill is installed:

```bash
bash "$CLAUDE_PLUGIN_ROOT/scripts/render-docx.sh" "<path.md>"
```

In a local checkout, call:

```bash
bash plugins/machine-discovery/scripts/render-docx.sh "<path.md>"
```

### Step 4: Verify the result

Confirm the generated `.docx` exists, is non-empty, and lives beside the Markdown with the same basename. If the script reports an error, pass that error back without inventing a workaround.

### Step 5: Hand to user

Report exactly:

```markdown
**DOCX rendered.**

Output: `<path-to-output.docx>`
```

## Anti-patterns

- Adding flags or optional arguments to the command.
- Overwriting an existing `.docx`.
- Rendering PDF or HTML.
- Editing the Markdown content before render.
- Running Pandoc without a bundled reference DOCX.