git:20261005.22be678 to git:20261015.5cc5fed

- <!-- brewcode-meta: version=6.4.0 content_version=6.0.0 generated_by=brewdoc:md-to-pdf -->

- Converts Markdown files to professional PDF using one of two rendering engines.

- Position 1 of `$ARGUMENTS` is a **free-form prompt** (RU/EN) — the file path, `--engine` flag, `styles`/`test`

- tokens and the quoted LLM-preprocessing prompt are all optional and may follow in any order. Nobody types keys:

- resolve mode + file FROM the prompt.

- 1. Strip `--engine <name>`. A literal mode token (`styles`, `config`, `test`, `help`) anywhere wins outright.

- 2. Else score modes by distinct whole-word keyword hits (table below). Highest unique score wins.

- 3. Empty arguments -> `help` (documented default). Read-only — asks nothing.

- 4. **Prose resolution (mandatory):** `$ARGUMENTS` may be a full sentence, not just tokens. Extract `md_file` from

- any path-shaped token or a filename explicitly named in prose (e.g. "convert my notes.md to pdf" ->

- `md_file = notes.md`, resolved against cwd). If the sentence implies CONVERT but no file is resolvable -> ONE

- `AskUserQuestion` for the file path. Never guess a file and never silently fall through to HELP.

- 5. Outcome-changing ambiguity (missing engine deps, no saved engine preference) -> ONE `AskUserQuestion`.

- Then print this block ONCE, before Step 1:

- Labels are literal; values follow the conversation language.

-

- Parse `$ARGUMENTS` to determine mode and components.

-

- | `md_file` | per mode | Path to `.md` file — literal token or extracted from prose (rule 4 above) |

- | `--engine` | No | `reportlab` or `weasyprint` (overrides saved config) |

- **Mode detection rules:**

-

- | TEST | `test` | test, sample, demo, bundled test file | тест, пример, демо | no (writes only to `/tmp/`) |

- Extract `--engine <name>` from anywhere in arguments if present. Remove it before further parsing.

-

- ## Step 1: Dependency Check

-

- Determine the target engine (from `--engine` flag, saved config, or default `reportlab`).

-

- **EXECUTE** using Bash tool:

- ```bash

- bash "${CLAUDE_SKILL_DIR}/scripts/check_deps.sh" check ENGINE_NAME 2>&1; echo "EXIT_CODE=$?"

- ```

- Replace `ENGINE_NAME` with the target engine.

- **If output contains `MISSING_PIP` or `MISSING_SYSTEM`:**

- Use `AskUserQuestion` presenting the engine comparison table:

- Options:

- - "Install ENGINE_NAME dependencies"

- - "Switch to OTHER_ENGINE" (if the other engine is available)

- - "Cancel"

-

- If user chooses install, **EXECUTE** using Bash tool:

- ```bash

- bash "${CLAUDE_SKILL_DIR}/scripts/check_deps.sh" install ENGINE_NAME 2>&1 && echo "---INSTALL_OK---" || echo "---INSTALL_FAILED---"

- ```

-

- > **STOP if INSTALL_FAILED** -- report error and exit.

-

- If user cancels -- STOP.

-

- ## Step 2: Engine Selection (first run only)

-

- Check for saved config in order:

- 1. Project: `.claude/md-to-pdf.config.json`

- 2. Global: `~/.claude/md-to-pdf.config.json`

-

- If `--engine` flag was provided -- use it (skip config lookup).

-

- If no saved preference and no `--engine` flag -- use `AskUserQuestion` with the engine comparison table from Step 1. Save the choice to project config `.claude/md-to-pdf.config.json`:

- The four provenance keys are mandatory on every write of this file and are RESOLVED, never hardcoded.

- **EXECUTE** using Bash tool (replace `ENGINE_VALUE` and `THEME_VALUE` with the chosen values):

- ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")}"

- PJ="${CLAUDE_SKILL_DIR}/../../.claude-plugin/plugin.json"

- PV=$(python3 -c "import json,sys;print(json.load(open(sys.argv[1])).get('version',''))" "$PJ" 2>/dev/null || true)

- [ -n "$PV" ] || { echo "❌ cannot read version from $PJ -- reinstall brewdoc"; exit 1; }

- SKILL_MD="${CLAUDE_SKILL_DIR}/SKILL.md"

- CV=$(python3 -c "

- import re,sys

- for line in open(sys.argv[1]):

- if 'brewcode-meta:' in line:

- m = re.search(r'content_version=(\d+\.\d+\.\d+)', line)

- print(m.group(1))

- " "$SKILL_MD" 2>/dev/null || true)

- [ -n "$CV" ] || { echo "❌ cannot read content_version from $SKILL_MD -- reinstall brewdoc"; exit 1; }

- mkdir -p "$ROOT/.claude"

- printf '{\n "engine": "ENGINE_VALUE",\n "pygments_theme": "THEME_VALUE",\n "version": "%s",\n "content_version": "%s",\n "generated_by": "brewdoc:md-to-pdf",\n "last_updated": "%s"\n}\n' "$PV" "$CV" "$(date +%F)" > "$ROOT/.claude/md-to-pdf.config.json" \

- && python3 -c "import json,sys;json.load(open(sys.argv[1]))" "$ROOT/.claude/md-to-pdf.config.json" \

- && echo "✅ config written (version $PV, content_version $CV)" || { echo "❌ config invalid JSON"; exit 1; }

- Print formatted usage:

- 1. Read the input MD file with Read tool. If not found -- STOP with error.

- 2. Determine output path: same directory, same name, `.pdf` extension.

- 3. Build the config path argument (if project or global config exists, add `--config CONFIG_PATH`).

- **EXECUTE** using Bash tool:

- Replace `INPUT_PATH`, `OUTPUT_PATH`, `ENGINE` with actual values. Add `--config CONFIG_PATH` if a style config JSON exists. Add `--pygments-theme THEME` for weasyprint if configured.

- 4. Parse structured output lines: `STATUS`, `OUTPUT`, `PAGES`, `SIZE`, `ENGINE`.

- 1. Read the input MD file with Read tool.

- 2. Apply LLM transformations per the `custom_prompt` instructions (delete sections, rewrite headings, restructure, etc.).

- 3. Write the transformed markdown, convert it and clean up in ONE Bash invocation. The temp name comes from

- `mktemp` -- never composed from the source name -- and cleanup is trapped and constrained to a `.tmp_*`

- basename, so a mis-substitution cannot name the source file.

- `OUTPUT_PATH` is the ORIGINAL name with a `.pdf` extension. Add `--config` / `--pygments-theme` exactly as in CONVERT mode.

-

- > Never write the transformed markdown with `Write`/`Edit` and never reuse a fixed `.tmp_<name>.md` path -- a

- > predictable name overwrites user files and collides with a concurrent conversion of the same source.

- > **STOP if CONVERT_FAILED** -- read error output, attempt fix, retry once. If still failing -- report error.

- 4. Parse the structured result lines, then proceed to Step 4 with `preprocessing: true`.

- Run interactive configuration via `AskUserQuestion` dialogs:

-

- **Question 1 -- Page size:**

- Options: `A4` (default), `Letter`, `Legal`

- **Question 2 -- Color scheme:**

- Options: `Default blue` (primary #1a3a5c), `Dark` (primary #2d3748), `Custom` (ask for hex values)

- **Question 3 -- Code theme (weasyprint only):**

- Options: `github` (default), `monokai`, `friendly`, `solarized-dark`, `solarized-light`

- **Question 4 -- Footer format:**

- Options: `Page {page} of {total}` (default), `{page}/{total}`, `Disabled`

- Build JSON config matching `styles/default.json` structure, overriding changed values, and Write it to a temp file (e.g. `/tmp/md-to-pdf-styles.json`). The merge below then lands it in `.claude/md-to-pdf.config.json` with the four mandatory provenance keys, carrying over any `engine` / `pygments_theme` the file already held -- this writer replaces the whole file, and dropping those would silently reset the saved engine choice.

- **EXECUTE** using Bash tool (replace `STYLE_JSON_PATH` with the temp file you wrote):

- ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")}"

- CFG="$ROOT/.claude/md-to-pdf.config.json"

- NEW="STYLE_JSON_PATH"

- PJ="${CLAUDE_SKILL_DIR}/../../.claude-plugin/plugin.json"

- SKILL_MD="${CLAUDE_SKILL_DIR}/SKILL.md"

- mkdir -p "$ROOT/.claude"

- CFG="$CFG" NEW="$NEW" PJ="$PJ" SKILL_MD="$SKILL_MD" TODAY="$(date +%F)" python3 - <<'PY'

- import json, os, re

- cfg_p, new_p = os.environ["CFG"], os.environ["NEW"]

- pv = json.load(open(os.environ["PJ"])).get("version")

- if not pv:

- raise SystemExit("no version in " + os.environ["PJ"])

- cv = None

- for line in open(os.environ["SKILL_MD"]):

- if "brewcode-meta:" in line:

- m = re.search(r"content_version=(\d+\.\d+\.\d+)", line)

- if m:

- cv = m.group(1)

- break

- if not cv:

- raise SystemExit("no content_version in " + os.environ["SKILL_MD"])

- old = json.load(open(cfg_p)) if os.path.exists(cfg_p) else {}

- data = json.load(open(new_p))

- for k in ("engine", "pygments_theme"):

- if k in old and k not in data:

- data[k] = old[k]

- data["version"] = pv

- data["content_version"] = cv

- data["generated_by"] = "brewdoc:md-to-pdf"

- data["last_updated"] = os.environ["TODAY"]

- with open(cfg_p, "w") as fh:

- json.dump(data, fh, indent=2)

- fh.write("\n")

- print("OK version=%s content_version=%s engine=%s" % (pv, cv, data.get("engine", "(unset)")))

- PY

- [ $? -eq 0 ] && echo "✅ styles saved" || { echo "❌ styles save FAILED"; exit 1; }

- rm -f "$NEW"

- > **STOP if ❌** -- fix before continuing.

-

- The four keys sit at the top level beside the style sections; `md_to_pdf.py`'s `load_config` deep-merges the file over `styles/default.json` and then reads only the sections it owns (`page`, `colors`, `typography`, `code`, `footer`), so extra top-level keys are inert.

-

- Report saved settings table and EXIT.

-

- ### TEST Mode

- 1. Use bundled test file at `${CLAUDE_SKILL_DIR}/test/test-all-elements.md` as INPUT_PATH.

- 2. Determine output path: `/tmp/md-to-pdf-test-ENGINE.pdf`

- 3. Run converter (same command as CONVERT mode, using test file as input, `/tmp/` output).

- 4. Proceed to Step 4.

- | Pages | from `PAGES=` in script output |

- | Size | from `SIZE=` in script output |